Code Evolution Lab← Back to site

Command-line interface for Code Evolution Lab, published on npm as code-evolution-lab.

The CLI runs the static analysis engine locally: it detects issues and writes reports. It does not generate or evolve candidate fixes — that is part of web and API scans. See Rule Reference for the 35 rules it runs.

Install

# Run without installing
npx code-evolution-lab analyze

# Or install globally
npm install -g code-evolution-lab

Commands

analyze [path]

Analyze a project for performance anti-patterns. Defaults to the current directory.

code-evolution-lab analyze
code-evolution-lab analyze ./src
code-evolution-lab analyze --severity high --category loop
Option Default Description
-s, --severity <level> low Minimum severity to report: critical, high, medium, low
-c, --category <cat> all Filter to a single rule category
-o, --output <dir> .codeevolution Where report files are written
--json off Print the report as JSON
--no-files off Skip writing report files

Unless --no-files is passed, three files are written to the output directory: a JSON report, a Markdown report, and a score file.

scan

Scan the current project and save a snapshot to .codeevolution/baseline.json. Use it to record a reference point before making changes.

code-evolution-lab scan
code-evolution-lab scan --output .codeevolution
Option Default Description
-o, --output <dir> .codeevolution Where the baseline is written

compare

Re-scan the project and compare it against the saved snapshot. Exits non-zero if the current score is lower than the baseline, which makes it usable as a CI guard rail.

code-evolution-lab compare
Option Default Description
-o, --output <dir> .codeevolution Where to read the baseline from

replay [study]

Replay benchmarks for reproducibility validation. Rules carry a reference to the study they were derived from, and replay re-runs those benchmarks on your own machine so you can check the published numbers hold there.

Coverage is partial — not every study has a replay implemented yet. Run replay with no argument to see what is available.

code-evolution-lab replay
code-evolution-lab replay --quick
Option Description
--quick Reduced trial count for a faster check

Exit codes

Code Meaning
0 Completed; no critical issues
1 analyze found at least one critical issue, or compare found a score regression

Note that analyze exits non-zero only on critical severity. High-severity findings alone will not fail a build. To gate on something stricter, use compare against a baseline instead.

Configuration

The CLI has no config file. .codeevolutionrc.json is read by the backend engine only, so options are passed on the command line each run.

Directories are skipped by default and this is not configurable: node_modules, .git, dist, build, coverage, .next, .nuxt, __pycache__. Files are analysed if they end in .js, .ts, .jsx, .tsx, or .mjs, plus schema.prisma for the index rules.

Categories

--category accepts a rule category, which is the segment before the slash in a rule ID — loop/sequential-await is in the loop category:

n1, loop, memory, payload, index, caching, resource, blocking-io, dom, bundle, redos

Next steps