github/semantic: Parsing, analyzing, and comparing source code across many languages


semantic is a Haskell library and command line tool for parsing, analyzing, and comparing source code.


Run semantic --help for complete list of up-to-date options.


Usage: semantic parse ([--sexpression] | [--json] | [--json-graph] | [--symbols]
                      | [--dot] | [--show] | [--quiet]) [FILES...]
  Generate parse trees for path(s)

Available options:
  --sexpression            Output s-expression parse trees (default)
  --json                   Output JSON parse trees
  --json-graph             Output JSON adjacency list
  --symbols                Output JSON symbol list
  --dot                    Output DOT graph parse trees
  --show                   Output using the Show instance (debug only, format
                           subject to change without notice)
  --quiet                  Don't produce output, but show timing stats


Usage: semantic diff ([--sexpression] | [--json] | [--json-graph] | [--toc] |
                     [--dot] | [--show]) [FILE_A] [FILE_B]
  Compute changes between paths

Available options:
  --sexpression            Output s-expression diff tree (default)
  --json                   Output JSON diff trees
  --json-graph             Output JSON diff trees
  --toc                    Output JSON table of contents diff summary
  --dot                    Output the diff as a DOT graph
  --show                   Output using the Show instance (debug only, format
                           subject to change without notice)


Usage: semantic graph ([--imports] | [--calls]) [--packages] ([--dot] | [--json]
                      | [--show]) ([--root DIR] [--exclude-dir DIR]
                      DIR:LANGUAGE | FILE | --language ARG (FILES... | --stdin))
  Compute a graph for a directory or from a top-level entry point module

Available options:
  --imports                Compute an import graph (default)
  --calls                  Compute a call graph
  --packages               Include a vertex for the package, with edges from it
                           to each module
  --dot                    Output in DOT graph format (default)
  --json                   Output JSON graph
  --show                   Output using the Show instance (debug only, format
                           subject to change without notice)
  --root DIR               Root directory of project. Optional, defaults to
                           entry file/directory.
  --exclude-dir DIR        Exclude a directory (e.g. vendor)
  --language ARG           The language for the analysis.
  --stdin                  Read a list of newline-separated paths to analyze
                           from stdin.

Language support

Priority Language Parse Assign Diff ToC Symbols Import graph Call graph Control flow graph
1 Ruby 🚧
2 JavaScript 🚧
3 TypeScript 🚧
4 Python 🚧
5 Go 🚧
Java 🔶
Haskell 🔶
Markdown 🔶 N/A N/A N/A  
  • — Supported
  • 🔶 — Partial support
  • 🚧 — Under development


We use cabal's Nix-style local builds for development. To get started quickly:

git clone [email protected]:github/semantic.git
cd semantic
git submodule sync --recursive && git submodule update --init --recursive --force
cabal new-build
cabal new-test

semantic requires GHC 8.6.4. We recommend using ghcup to sandbox GHC versions. Our version bounds are based on Stackage LTS versions. The current LTS version is 13.13; stack build should also work if you prefer.

Technology and architecture

Architecturally, semantic:

  1. Reads blobs.
  2. Generates parse trees for those blobs with tree-sitter (an incremental parsing system for programmings tools).
  3. Assigns those trees into a generalized representation of syntax.
  4. Performs analysis, computes diffs, or just returns parse trees.
  5. Renders output in one of many supported formats.

Semantic leverages a number of interesting algorithms and techniques:


Contributions are welcome! Please see our contribution
and our code of conduct for
details on how to participate in our community.


Semantic is licensed under the MIT license.


Source link