Repolens

Repolens is a repository intelligence CLI that scans source trees and builds a dependency graph to surface architectural signals such as hubs, coupling, instability, and implementation relationships.

It is designed for fast, practical analysis in real-world codebases and currently supports JavaScript, TypeScript, Python, Java, and Markdown.

Why Repolens

• Identify critical files that many others depend on.
• Spot unstable files likely to create churn.
• Find concrete implementations of an interface or base class.
• Export graph data as JSON for custom dashboards and automation.
• Get a concise repository summary without heavyweight setup.

Features

• Multi-language scanning using tree-sitter parsing.
• Dependency graph construction and ranking.
• Architectural health report:
  • Top core dependencies by afferent coupling ($Ca$)
  • Top unstable files by instability ($I = \frac{Ce}{Ca + Ce}$)
• Interface implementation lookup via --implements.
• JSON export for machine-readable output.
• Verbose mode for parser and scan diagnostics.

Installation

Install globally from npm:

npm install -g @anirudw/repolens

Verify installation:

repolens --version

Quick Start

Run in the current directory:

repolens

Run against a specific repository path:

repolens /path/to/repo

Print architectural health metrics:

repolens /path/to/repo --health

Export analysis as JSON:

repolens /path/to/repo --format json --output repolens-graph.json

Find files implementing an interface/base class:

repolens /path/to/repo --implements ILogger

Command Reference

repolens [path] [options]

• [path] optional directory to scan (defaults to current working directory)

Options

• -v, --verbose enable verbose output
• -f, --format <format> output format: text or json (default: text)
• -o, --output <file> output file path for JSON export
• -i, --implements <interfaceName> list files implementing an interface/base class
• --health print architectural health metrics and exit
• -V, --version print CLI version
• -h, --help show help

Example Output

Summary mode (repolens)

Health mode (repolens --health)

Implementation Search (repolens --implements <name>)

Supported Languages

• JavaScript: .js, .jsx, .mjs, .cjs
• TypeScript: .ts, .tsx, .mts, .cts
• Python: .py
• Java: .java
• Markdown: .md, .markdown

Development

Clone and install dependencies:

npm install

Run in dev mode:

npm run dev -- /path/to/repo --health

Build distributable CLI:

npm run build

Run tests:

npm test -- --run

Type check:

npm run lint

Troubleshooting

• If a global install appears stale, reinstall the latest version:

npm uninstall -g @anirudw/repolens
npm install -g @anirudw/repolens@latest

• Use verbose mode to inspect parse warnings:

repolens /path/to/repo --verbose

• Use --health or --implements when you want focused output (they exit early by design and do not print summary mode).

License

MIT. See LICENSE.