Metrolith

Evidence, not scores.

Metrolith is a local-first, multi-language static-analysis CLI. It produces versioned code metrics and offline reports so you can investigate a source tree, inspect complex functions, and compare changes between revisions. Optional duplication and history analyses provide additional evidence; you choose which analyses and rules to run.

Inspect what was measured, what was excluded, and where results are partial or unavailable before deciding what to change.

Languages: Python, Java, JavaScript/TypeScript and Go. Parsing and measurement coverage are language-specific.

Try online · Explore a recorded demo · Install from PyPI · Read the guide

Three questions to start with

• What is in this source tree? Inspect languages, files, code size, classes/structs and methods/functions alongside inclusion reasons and explicit measurement coverage.
• Where should I look more closely? Read callable complexity, then request lexical or structural duplication evidence separately. Their populations can overlap; their group counts are not a combined defect total.
• What changed between revisions? Use revision Diff or existing-Run comparisons, and Changed Code for explicit base/head revisions. Evaluate a Policy of rules you select; measurements do not infer architecture quality.

For how these pieces fit together, see Architecture.

Quickstart from PyPI

Install in a fresh virtual environment, check the environment, then run a tiny bundled example. CPython 3.13 is required (>=3.13,<3.14); 3.13.9 is the verified patch on Windows and Ubuntu. Git must be on PATH, including for local directory snapshots. Your analyzed directory need not be a Git repository.

Start in an empty working directory outside your project's source. Use an unused metrolith-user environment directory. Installation can download dependencies; the bundled local example is network-free afterward.

PowerShell — python must resolve to CPython 3.13:

python --version
git --version
python -m venv "metrolith-user"
& "./metrolith-user/Scripts/python.exe" -m pip install "metrolith==4.0.0"
$env:PATH = "$((Resolve-Path './metrolith-user/Scripts').Path);$env:PATH"
metrolith doctor --format text
metrolith example run --local

Ubuntu / POSIX shell:

python3.13 --version
git --version
python3.13 -m venv "metrolith-user"
"./metrolith-user/bin/python" -m pip install "metrolith==4.0.0"
. "./metrolith-user/bin/activate"
metrolith doctor --format text
metrolith example run --local

Stop if a prerequisite check or installation fails. PowerShell changes PATH only for this session; no execution-policy change is needed.

With published Metrolith 4.0.0, the bundled example measures 22 code lines, 2 source files, 0 classes/structs and 4 methods/functions, with complete core metrics. Zero classes is a measured result. The Run path printed by example run --local belongs to this example; open its summary.md to inspect these values.

Next, in the same configured shell, change to your project's source directory and run:

metrolith analyze . --workspace "../metrolith-results"

Choose an output workspace outside the analyzed source. This command prints a new Run directory for your project under WORKSPACE/metrolith-output/runs/. metrolith analyze . also works; its default workspace is METROLITH_HOME or the current directory. Analysis reads source and writes outputs/cache state in the workspace. See source modes and locations.

Read your first Run

Open summary.md in the Run directory for the source you want to inspect. Each invocation prints its own path; use your project's path when reading your project.

Replace RUN below with the printed directory, keeping quotes:

metrolith report "RUN"
metrolith explain "RUN"
metrolith validate "RUN"

report writes the derived offline view at RUN/report.html; open it in a browser. explain describes recorded scope and availability. validate checks required artifacts and cross-file consistency; it does not rerun analysis or prove source authenticity. Keep the Run's JSON/CSV evidence and fact sheets with the report.

Completion does not mean every measurement is complete. Read partial, unavailable, not requested, and not applicable separately from measured zero. Optional analyses are not all executed by analyze.

Evidence and boundaries

Directory snapshots, working snapshots and exact Git revisions record different source identities. A working snapshot is not proof of committed bytes. A Policy contains your rules; a Ratchet compares selected measurements with a retained baseline and chosen tolerances. Neither supplies universal quality thresholds. Local PASS does not establish protected organizational approval.

pip install metrolith installs the CLI and offline reporting. The hosted Story/Explorer is a separate companion to the CLI's offline HTML report. Local source processing and the website's server-side repository processing have different privacy and feasibility boundaries; see the website guide.

Choose your next path

• Using Metrolith: Documentation map, Usage and full command reference, Examples.
• Understanding evidence: Architecture, recorded walkthrough, reproducibility.
• Contributing: Development preserves the hash-locked source setup. Build & smoke checks Ubuntu packaging and a tiny installed example; it is not full engine qualification.
• Maintaining releases: Publication record and procedure. Deliberate full qualification uses tools/release_verify.py and requirements/release-verification.lock.

The deprecated archlens/arch-bench commands and frozen ArchLens format identifiers remain compatibility contracts.

License, citation and contact

Apache-2.0 · Software citation · Issues

Maintainer: Ali Sajedifar — its.alisajedifar@gmail.com.