Skip to content

README.md

Latest commit

 

History

History
160 lines (112 loc) · 5.23 KB

README.md

File metadata and controls

160 lines (112 loc) · 5.23 KB
Raw

Codefang

Codefang Logo

CI License: Apache 2.0

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).

What it does

  • UAST parsing — uast turns 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 (and yaml, ndjson, timeseries, bin, text, compact, plot). The machine formats are a stable contract, pinned by CLI-level end-to-end tests (see Testing below).

Why

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.

Install / build

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 install

make 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 version
uast version

Usage

uast and codefang are separate tools (see ADR-0002).

Parse a source file into a UAST:

uast parse main.rs

Run a static analyzer over a checkout (UAST is built internally per file):

codefang run --analyzers static/complexity --format json --head /path/to/repo

Run a history analyzer by walking Git history (use --limit to cap commits):

codefang run --analyzers history/burndown --format json --limit 50 /path/to/repo

List every analyzer ID:

codefang run --list-analyzers

Analyzer IDs are static/<name> and history/<name>; -a accepts globs (static/*, history/*, *).

Testing

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 item

The 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.

Documentation

Contributing

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).

Security

Report vulnerabilities privately through GitHub's "Report a vulnerability" button on the Security tab. See the Security policy.

License

Codefang is released under the Apache-2.0 license.