The heavy lifter for your codebase — deep code analysis through structure and history.
Codefang understands your code as structure (an abstract syntax tree) and as
history (Git), not just as text. It ships two binaries: uast parses source
into a Universal Abstract Syntax Tree across 60+ languages, and codefang runs
static and history analyzers over that structure and over Git repositories.
For deep dives — architecture, per-analyzer references, the metric models — see
the documentation site (built from
site/ with MkDocs Material).
- UAST parsing —
uastturns source code into one normalized tree shape, so a single analyzer works across Go, Python, JavaScript, Rust, Java, C++ and more (Tree-sitter under the hood). - Static analysis — complexity, cohesion, comments, clones, composition, Halstead, and imports, computed from the UAST.
- History analysis — burndown, developers, couples, file-history, imports, quality, sentiment, shotness, typos, and anomaly, computed by walking Git history through libgit2.
- Stable machine output —
--format json(andyaml,ndjson,timeseries,bin,text,compact,plot). The machine formats are a stable contract, pinned by CLI-level end-to-end tests (see Testing below).
The original hercules mined Git history at scale but understood code only as
diffs. Codefang keeps the history mining and adds a structural layer (the UAST),
so one analyzer reasons about meaning across many languages. The project is now
a Rust workspace; the original Go implementation has been removed.
Codefang is a single Rust workspace rooted at the repository root. You need a
recent stable Rust toolchain and a C toolchain (a C/C++ compiler and CMake) —
the git2 crate builds a vendored copy of libgit2 from
third_party/libgit2, so no system libgit2 is required.
The quickest path — clone, then one make install that builds both binaries
and puts them on your PATH (~/.cargo/bin):
git clone --recurse-submodules https://github.com/Sumatoshi-tech/codefang.git
cd codefang
make installmake install also initializes the submodule, so if you cloned without
--recurse-submodules it still works. Run make help to see the other targets
(build, test, clean).
Prefer plain cargo, or just want the binaries in target/release/ without
touching PATH? Use make build (equivalently
cargo build --release -p codefang -p uast) and invoke them by full path.
Check the install:
codefang versionuast versionuast and codefang are separate tools (see ADR-0002).
Parse a source file into a UAST:
uast parse main.rsRun a static analyzer over a checkout (UAST is built internally per file):
codefang run --analyzers static/complexity --format json --head /path/to/repoRun a history analyzer by walking Git history (use --limit to cap commits):
codefang run --analyzers history/burndown --format json --limit 50 /path/to/repoList every analyzer ID:
codefang run --list-analyzersAnalyzer IDs are static/<name> and history/<name>; -a accepts globs
(static/*, history/*, *).
Three gates, all runnable locally and all required to be green:
make test # the workspace test suite (unit, integration, CLI-level e2e)
make lint # clippy across the workspace; every warning is an error
make deadcode # fails on any unreachable private itemThe analyzer crates carry unit tests for their metric math; bins/codefang/tests
drives the real binary over hermetic fixture repositories and source trees and
pins the machine-format bytes end to end.
The CLI examples in this README and in docs/ are themselves executed against
the built Rust binary by the doc-examples test crate
(cargo test -p doc-examples), so the commands shown here are runnable, not
illustrative.
- Architecture overview and the UAST system.
- Per-analyzer references under
site/analyzers/and the metric models undersite/explanation/. - Architecture Decision Records under
docs/adr/. - Per-crate Rust API docs:
cargo doc --open.
PRs are welcome. Read the Contributing guide for the build, the test gates, and commit conventions. Architecturally significant changes are recorded as ADRs (see ADR-0001).
Report vulnerabilities privately through GitHub's "Report a vulnerability" button on the Security tab. See the Security policy.
Codefang is released under the Apache-2.0 license.