ai-maturity-scanner

Scan a code repository and generate its AI coding maturity report — a level from L0–L4 plus a 0–100 AMI score. Standalone Node.js CLI. No server, no database, no auth.

npx @merico-ai/maturity-scanner ./my-repo

It walks the repo's tracked files (via git ls-files), classifies each one into five maturity dimensions (file_type, agent_type, file_extension, project_scope, skill_level), aggregates them into 15 raw metrics, normalizes those into 3 weighted dimensions, and renders the result.

The classification rules, scoring caps, and level thresholds are maintained in this package and covered by focused unit and end-to-end tests.

Install

npm install -g @merico-ai/maturity-scanner
# or one-off:
npx @merico-ai/maturity-scanner ./my-repo

Installs the ai-maturity-scanner command. Requires Node 22+. Requires git on PATH.

Usage

# Default: scan CWD, write ./ai-maturity-report.png, print the generated path
ai-maturity-scanner

# Explicit path
ai-maturity-scanner ./my-repo

# Terminal report to stdout
ai-maturity-scanner --format terminal

# Markdown report to stdout
ai-maturity-scanner --format md

# JSON report for CI gates
ai-maturity-scanner --format json --out report.json

# PNG report at a custom path
ai-maturity-scanner --out report.png

# PNG report plus terminal scan results and metrics on stdout
ai-maturity-scanner --verbose

# Read and validate the hidden PNG fingerprint metadata
ai-maturity-scanner verify-image report.png

Flags

Flag	Values	Default	Purpose
[path]	directory path	.	Repository to scan
-f, --format	png | terminal | md | json	png	Output format
-o, --out	file path	./ai-maturity-report.png for png, stdout for text	Write report output
-V, --version	boolean	false	Print the current package version
--redacted	boolean	false	Hide the repository path in PNG output
--verbose	boolean	false	Also print terminal scan results and metrics when the primary output is written to a file

Subcommands

Command	Purpose
verify-image <file>	Recompute the image pixel hash and validate hidden PNG metadata

Exit codes

Code	Meaning
0	Success
1	Bad CLI args or runtime error
2	Target is not a git repository
3	git binary not found on PATH

Levels

The cascade checks from L4 down to L0; the first satisfied tier wins. L0 is reserved for repos with no AI instruction file at all.

Level	Criteria
L0	ai_instruction_files < 1 (no CLAUDE.md / AGENTS.md / GEMINI.md / .cursorrules / etc.)
L1	Default once L0 fails.
L2	ability_applied ≥ 8 AND advanced_skill ≥ 1
L3	ability_applied ≥ 15 AND advanced_skill ≥ 2 AND skill_engineering_rate ≥ 0.15 AND specs_files ≥ 10
L4	ability_applied ≥ 25 AND skill_engineering_rate ≥ 0.40 AND specs_files ≥ 20

Where:

• ability_applied = skill + skill_resource + agent + command + mcp, where mcp is the count of unique supported MCP server names
• advanced_skill = skills whose directory bundles scripts/ or script files
• skill_engineering_rate = advanced_skill / skill
• specs_files = Markdown files that aren't themselves ability fixtures

AMI (0–100)

Weighted average of three normalized dimensions:

Dimension	Weight	What it measures
Configuration depth	0.6	Skill / Agent / Command / MCP ability fixtures
Context richness	0.3	AI instruction files + spec docs
Integration breadth	0.1	Subproject-scoped instruction coverage

Example output (terminal)

  AI Maturity Report
  /Users/me/my-repo @ abc12345

  Level: L3    AMI: 67.5/100

  Configuration depth  ██████████████████░░░░░░  75.0
  Context richness     ███████████████░░░░░░░░░  60.0
  Integration breadth  ████████░░░░░░░░░░░░░░░░  40.0

  Skill class
  skill_count                         12  ████████░░░░░░░░░░░░░░░░  40.0
  ...

What gets detected

A non-exhaustive list of path patterns the classifier looks for:

• Instruction: CLAUDE.md, AGENTS.md, GEMINI.md, copilot-instructions.md, .cursorrules, .windsurfrules, .clinerules, rules/*.mdc, .rules
• Skill / skill_resource: skills/<name>/SKILL.md and anything else under skills/
• Command: commands/*.md, .codex/prompts/*.md
• Agent: agents/*.md, .agent/*.md
• Spec: specs/*.md
• Hook: .codex/hooks.json
• Config: .claude/settings.json, opencode.json, .codex/config.toml, .gemini/settings.json, .continue/config.json
• MCP: unique server names parsed from Claude Code .mcp.json / mcp.json and Codex .codex/config.toml

Plus the matching agent_type dimension (claude, codex, cursor, gemini, etc.) for files under each tool's directory.

Development

npm install
npm test            # vitest
npm run build       # tsup → dist/cli.js
npm run lint        # biome
npm run demo:image  # writes preview PNG reports under demo-output/

The repo is a single ESM TypeScript package. Source layout:

• src/rules/ — path classification (mirrored from rules.py)
• src/metrics/ — aggregation + scoring (mirrored from calculator.py)
• src/git/, src/scan/ — repo walking and line counting
• src/report/ — png / terminal / md / json renderers
• tests/ — golden fixture, unit, and end-to-end tests

Image rendering

The PNG report uses sharp to rasterize a deterministic 1080x1920 SVG template for mobile sharing. The QR slot is reserved for the future web quick start link and shows a placeholder until that URL is configured in the CLI. The PNG file includes a hidden AI-Maturity-Image-Hash metadata field derived from decoded image pixels, plus a report payload fingerprint. verify-image recomputes the pixel hash and compares it with the hidden value; issuer authenticity will still require a future signed web record.

nvm exec 22 npm run build
nvm exec 22 node dist/cli.js --out report.png

Each translated file cites the upstream Python source by commit SHA in a header comment.

License

MIT