Metrolith

Evidence, not scores.

Metrolith helps repository maintainers and researchers understand their code and evaluate rules they choose, with measurements they can inspect.

Languages: Java, JavaScript/TypeScript, Python and Go.

It records versioned evidence for code lines, source files, classes/structs, methods/functions and complexity. Maintenance analyses are optional.

Prerequisites

Requires CPython 3.13. Release verification is currently performed with 3.13.9 on x86-64 Windows and Ubuntu.

Git must be on PATH. The current source-acquisition workflow requires it even for directory snapshots. Your source directory does not need to be a Git repository.

Install

Install from a source checkout or a local wheel using the instructions below.

Start in the downloaded or cloned source root (containing pyproject.toml). Use CPython 3.13 and an unused sibling environment directory; stop if either prerequisite check fails. The commands below install Metrolith and its dependencies, including native tree-sitter parsers, and make metrolith available in the current shell. Installation can download dependencies.

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 --require-hashes -r requirements/install-tooling.lock
& ../metrolith-user/Scripts/python.exe -m pip install .
$env:PATH = "$((Resolve-Path '../metrolith-user/Scripts').Path);$env:PATH"

Ubuntu shell:

python3.13 --version
git --version
python3.13 -m venv ../metrolith-user
../metrolith-user/bin/python -m pip install --require-hashes -r requirements/install-tooling.lock
../metrolith-user/bin/python -m pip install .
source ../metrolith-user/bin/activate

PowerShell's PATH change is session-only; no execution-policy change is needed. See Usage for local-wheel installation and troubleshooting.

Check the installed environment:

metrolith doctor --format text

Analyze your project

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

metrolith analyze .

A Run directory holds the results and evidence for an analysis; the command prints its path. By default, Runs are written under metrolith-output/runs/ in the invocation workspace (METROLITH_HOME or the current directory). Analysis leaves analyzed source files unchanged; it writes generated outputs and cache/workspace state. See source and output locations for overrides.

Inspect the results

Open the printed Run directory's summary.md for the summary and measurement states.

Replace RUN below with that printed directory. Keep the quotes around the path.

Validation checks recorded evidence; it does not rerun analysis or establish repository authenticity. The HTML report is a derived view. The Run also contains JSON/CSV evidence, per-subject fact sheets and per-language details in language_metrics.csv.

Optional: verify your installation

From an empty working directory, this command runs the packaged example without network access. Git must remain available.

metrolith example run --local

Recorded output from the bundled synthetic example:

Subject key      example:network-free
Source           directory snapshot (non-Git)
Overall status   complete
Lines of Code       22 (complete)
Source Files        2 (complete)
Classes/Structs     0 (complete)
Methods/Functions   4 (complete)

Zero classes is a measured result, not missing data. This example illustrates the output; it is not a benchmark. Use its newly printed Run path with the inspection commands above.

Evidence and limits

Source state. Directory snapshots, Git working snapshots, tracked-only snapshots and exact Git revisions have different source identities. Each Run records its source identity; a working snapshot is not proof of committed bytes.

Measurement status. Complete, partial, unavailable, not requested and measured zero are different outcomes. A successful analysis can contain partial measurements; inspect the recorded statuses rather than relying on the exit code alone.

Your rules. A policy is a set of measurement rules you provide. metrolith check evaluates it; Metrolith does not supply universal quality thresholds or infer architecture labels. metrolith dossier combines accepted evidence into a report. A local PASS does not establish organizational approval. See Policy and trust requirements for these workflows.

See Reproducibility for source identity, output comparisons and environment limitations. The separately implemented hosted website is not installed by this package.

Documentation and development

• Usage: source modes, policies, Ratchet, safe exports and the full command/version reference.
• Examples: local samples and optional repository examples.
• Development: pinned build, test and artifact-validation environments, using requirements/release-verification.lock and tools/release_verify.py for deliberate full release verification.
• Release checklist: maintainer publication checks.

Technical references: metrics, complexity and artifact contracts.

The package is metrolith. The deprecated archlens and arch-bench commands, archlens_json import, legacy configuration keys and format identifiers remain for compatibility.

License, citation and contact

Apache-2.0 · Software citation

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

Source · Issues