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.
• Circular dependency detection via --cycles (CI-friendly exit codes).
• 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.
• Persistent parse caching with automatic stale-entry pruning.
• JSON export for machine-readable output.
• Runtime indicator at command completion (seconds).
• 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

Check for circular dependencies (fails with exit code 1 if any are found):

repolens /path/to/repo --cycles

Use this mode in CI to fail builds when circular dependencies are introduced.

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
• --cycles detect circular dependencies and exit non-zero when cycles exist
• --health print architectural health metrics and exit
• -V, --version print CLI version
• -h, --help show help

Example Output

Outputs after I ran repolens on nest repository of nestjs (https://github.com/nestjs/nest.git`)

Summary mode (repolens)

Health mode (repolens --health)

Implementation Search (repolens --implements <name>)

Circular Dependency Check (repolens --cycles)

Found 1 circular dependencies.

a.ts -> b.ts -> c.ts -> a.ts

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 run test

Type check:

npm run lint

Caching Behavior

Repolens stores parsed-file metadata in .repolens-cache.json at the scanned repository root.

• Cache hit: same file path and unchanged mtime reuse prior parse output.
• Cache miss: changed mtime triggers re-parse.
• Stale cleanup: entries for files no longer in the scan set are pruned automatically.
• Repository isolation: each scanned repo has its own independent cache file.

Practical expectation: the first run on a large repository is slower, while repeated runs on unchanged files are significantly faster due to cache hits.

Exit Codes

• repolens --cycles: exits 0 when no cycles are found, exits 1 when cycles are detected.
• Other modes return normal CLI success/failure behavior.

CI Integration (GitHub Actions)

Use --cycles in pull-request checks to prevent new circular dependencies:

name: RepoLens Cycles Check

on:
  pull_request:
  push:
    branches: [main]

jobs:
  cycles:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - run: node dist/index.js . --cycles

This job fails automatically when the cycle check exits with code 1.

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.