code-ranker

Structural-analysis tool for Rust, Python, JavaScript and TypeScript codebases. Built AI-agent-friendly first — finds where a project has structural problems and hands an actionable shortlist to a human or an AI agent for the actual refactor.

👉 Map your codebase's worst structural problems in 30 seconds — jump to the Rust quick start and run it on your repo now.

Status: pre-alpha. APIs and output shapes may change without notice.

Rust quick start

cargo install code-ranker  # install the CLI
code-ranker report .       # make html report in .code-ranker/ folder

report . needs no flags: it writes a self-contained HTML report (plus a JSON snapshot) into .code-ranker/. Open the latest …-<commit>.html to explore the dependency graph, per-file metrics, and the AI prompt generator. Everything below is detail.

Offline & private

code-ranker always runs entirely on your machine. It makes no network calls, sends no telemetry or analytics, and never uploads your code or analysis results anywhere. Generated HTML reports are self-contained — no CDN, no external requests, no tracking.

AI agents friendly

Hand your codebase to an AI agent and let it fix the worst spot. code-ranker is built to feed work straight to an AI coding agent (Claude Code, Cursor, …). Attach the short playbook docs/ai-skill.md to your agent's context — it teaches the agent which two metrics matter (dependency cycles ADP, coupling HK) and the exact fix loop (scorecard → snapshot → fix → re-check → before/after report).

Then just ask, e.g.:

• "Read https://raw.githubusercontent.com/ffedoroff/code-ranker/main/docs/ai-skill.md. Find the worst dependency cycle in this project and propose a refactor that breaks it — show me the plan before changing code."
• "Read https://raw.githubusercontent.com/ffedoroff/code-ranker/main/docs/ai-skill.md. Find the most complex / highest-HK file and analyze how to split it; explain what the split buys for me (lower coupling, smaller blast radius). Take a before report, apply the split, take an after report, and show me the HTML diff."

The agent drives the CLI itself — ai-skill.md already spells out the commands and the loop, so no glue is needed.

What it finds

• Files that grew too complex and should be split. Per-file cyclomatic / cognitive / Halstead / MI metrics; flags files above your threshold.
• Strong coupling between files. Computes fan-in / fan-out / HK on the file dependency graph; surfaces the files that everything depends on (or that depend on everything). Third-party libraries are tracked separately as depth-1 external nodes (fan_out_external), so they never inflate your internal-coupling numbers.
• Cyclic dependencies. Detects SCCs in the file graph — including the silent ones the compiler does not catch.
• Files that are just too big. Raw LOC, public surface size per file.

The tool does not refactor for you. It produces a structured, machine-readable list of problem spots and an offline HTML report a human or an LLM can act on.

CI integration

Runs as a linter. Configure thresholds in code-ranker.toml; the CLI exits non-zero when the codebase breaches them — so a PR that introduces a new cycle, a file above your cognitive budget, or a file above your LOC limit fails the build.

code-ranker check . \
  --threshold file.cognitive=25 --threshold file.loc=800

The linter is the check command — exits non-zero on any cycle or threshold violation, e.g. a PR that introduces a new file-level cycle or a file above your LOC limit (mutual and chain cycle checks are on by default). See docs/CLI.md for all flags.

Add it to your pipeline today — one code-ranker check step stops new cycles and bloat from ever landing.

Full CLI

Written in Rust — fast, memory-safe, single static-ish binary with no runtime dependencies (no Python, no Node, no JVM, no shared libs to install). One file on PATH, done.

Two commands: check (linter — exits non-zero on violations; with --baseline, a relative regression gate) and report (snapshot JSON + offline HTML; with --baseline, a baseline↔current diff). Both accept a directory or an existing .json/.html snapshot as input — analyze once, then run cheap passes over the snapshot. No daemon, no language server, no plugin host required at runtime. Full reference: docs/CLI.md.

HTML report with dynamic diagrams

code-ranker report writes a single self-contained HTML file with:

• An interactive file dependency graph; third-party libraries appear as depth-1 external nodes in a distinct amber colour with dashed edges.
• Dagre-laid-out graph with pan/zoom and live filtering.
• Sortable table per metric; click a node to open its neighbourhood.
• "Prompt generator" panel that copies a ready-to-paste prompt (one for each principle: ADP, SRP, OCP, LSP, ISP, DIP, DRY, KISS, LoD, MISU, CoI, YAGNI; plus Reduce Complexity, Split Components) — feed the prompt + the selected nodes to your AI agent.

No network, no analytics, no telemetry. Open in any browser, share as a file.

Live demo — code-ranker run on its own repo: interactive HTML report · JSON snapshot (regenerated on every push to main).

Install

Pick any channel — all ship the same code-ranker binary (Linux, macOS, Windows). Full guide with exact commands: docs/installation.md.

• Shell / PowerShell installer — prebuilt binary on PATH (universal)
• Cargo — cargo install code-ranker · crates.io
• npm — npm install -g code-ranker · npm
• pip / uv / pipx — pip install code-ranker · PyPI
• Docker — Docker Hub · GHCR

Quick start

# lint a project — non-zero exit on violations (CI linter)
code-ranker check ./path/to/project

# analyze and write a snapshot JSON + offline HTML report
code-ranker report
# → .code-ranker/{ts}-{git-hash-3}.json + .code-ranker/{ts}-{git-hash-3}.html
#   (override paths via --output.<fmt>.path or [output.<fmt>] in code-ranker.toml)

# before / after refactor comparison: an HTML diff against a baseline snapshot
code-ranker report . --baseline .code-ranker/before.json

Built-in plugins: rust (cargo + syn), python, javascript (also handles TypeScript) — all compiled into the single binary, nothing to install.

Documentation

• Installation — every install channel with exact commands
• CLI — commands, flags, and examples
• Rule reference — rule ids grouped by concern (CYC/CPX/CPL/SIZ), per-file thresholds (file), what each flags, and how to fix it
• Config — code-ranker.toml schema
• AI agent skill — a short playbook to attach to an AI agent's context (the ADP/HK fix loop)
• PRD — product requirements
• DESIGN — technical design
• Why structure matters — the empirical evidence (studies, books, statistics) behind the signals code-ranker measures
• Principles corpus — Rust / Python / TypeScript principle catalogues used by the prompt generator

Try it now

cargo install code-ranker && code-ranker report . && open .code-ranker/

One command on any Rust project — you'll have an interactive structural map and an AI-ready shortlist in seconds. ⭐ the repo if it helps.

License

Apache-2.0.