AST Metrics for Node.js

AST Metrics is a static analyzer that tells you which parts of a codebase are risky to touch. This package installs it with npm, like any other dev tool: no compiler, no service. The analyzer is a single binary, downloaded once and cached.

You may not need this package. It exists for one thing: getting the analyzer through npm, so it lands in package-lock.json with the rest of your tooling and npx ast-metrics just works. If that is not what you are after, install the analyzer directly:

brew install ast-metrics/tap/ast-metrics    # macOS, Linux
curl -fsSL https://install.ast-metrics.dev | sh

And on pull requests, there is a ready-made action: ast-metrics/action-ast-metrics@v2.

Usage

Without installing anything:

npx ast-metrics analyze src

Or as a dev dependency, which pins the analyzer version in your lockfile:

npm install --save-dev ast-metrics
npx ast-metrics analyze src
npx ast-metrics analyze --report-html=./report src

Everything else: npx ast-metrics --help, or ast-metrics.dev.

What gets analyzed

TypeScript (.ts, .tsx), and, in the same run, Go, PHP, Python, Rust, Java and C#. Most codebases are not made of one language, and the metrics are comparable across all of them.

Plain JavaScript (.js, .jsx, .mjs) is not parsed yet. On a pure JavaScript project, the run reports zero files. Follow the analyzer repository for that one.

In CI

- run: npx ast-metrics analyze --ci src

--ci writes the HTML and Markdown reports and keeps the output plain. Reports for a quality gate: --report-sarif=<file> (read by GitHub code scanning and GitLab), --report-json=<file>, --report-openmetrics=<file>.

The binary is downloaded once per version and cached in $XDG_CACHE_HOME/ast-metrics, so caching that directory between builds removes the download entirely.

Configuration

All optional.

Variable	Effect
AST_METRICS_BINARY	Path to a binary to use as-is, nothing downloaded: air-gapped CI, distribution packages.
AST_METRICS_VERSION	Release tag to download, or latest. Defaults to the pinned version.
AST_METRICS_CACHE_DIR	Where binaries are cached. Defaults to $XDG_CACHE_HOME/ast-metrics.
AST_METRICS_SKIP_DOWNLOAD	Skips the download that npm install normally does upfront. The binary is then fetched on first use.
HTTP_PROXY, HTTPS_PROXY, NO_PROXY	Honoured for the download, including CONNECT tunnels.

The analyzer version is pinned by this package rather than resolved to latest, so a locked package-lock.json gives a reproducible analysis. The package version matches the analyzer version it installs: [email protected] runs AST Metrics 0.41.1. To upgrade, npm update ast-metrics.

Installing with --ignore-scripts is fine: the download simply happens on the first run instead of during the install.

Migrating from a JavaScript complexity tool?

There is no argument translation here, unlike the PHP bridge and its PhpMetrics compatibility layer. plato, complexity-report and the ESLint complexity rules have no shared command line to translate, so this package passes your arguments straight through to the analyzer. Start with npx ast-metrics analyze src, then npx ast-metrics init to write a configuration file.

Contributing

See CONTRIBUTING.md. Analyzer bugs go to ast-metrics/ast-metrics; this repository is the Node.js bridge.

License

MIT. See LICENSE.