RepoGenome

Capture the architectural DNA of a codebase and track how it changes over time.

RepoGenome scans your source code and produces a genome.json — a structured snapshot of your architecture, patterns, concepts, and dependency flows. Run it again later and get a precise drift score showing exactly what changed and which directories caused it.

Install

npm install -g repogenome
# or run without installing:
npx repogenome init

Requires: Node.js ≥ 18

Quick Start

# 1. Create a baseline genome in your project root
npx repogenome init

# 2. Commit the baseline
git add .repogenome/genome.json
git commit -m "chore: add repogenome baseline"

# 3. Later — check if your architecture drifted
npx repogenome audit

# 4. Find which directories are responsible for the drift
npx repogenome blame

# 5. Compare two branches (requires git)
npx repogenome compare main feature/my-branch

Commands

For full flags, options, and examples for each command see docs/commands.md.

| Command | Description | |---------|-------------| | init | Scan repo and create architectural baseline | | audit | Compare current state against baseline, report drift | | blame | Attribute drift to specific directories and files | | compare | Diff two git refs against each other |

CI Integration

Block merges that exceed your drift threshold:

# .github/workflows/genome-check.yml
name: Genome Check
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx repogenome audit --threshold 25

Exit code 1 when drift exceeds the threshold — CI step fails automatically.

What Gets Detected

| Dimension | What it measures | Weight | |-----------|-----------------|--------| | Architecture | Layered vs modular vs flat structure change | 20% | | Patterns | Repository, Service, Controller, Factory, etc. | 25% | | Naming | Dominant casing, common prefixes/suffixes | 15% | | Concepts | Domain vocabulary drift | 15% | | Dependencies | DB access patterns, cross-layer imports | 15% | | Violations | Controller→Repository direct calls, circular imports | 10% |

Risk levels: 🟢 Low (<10%) · 🟡 Medium (10–30%) · 🔴 High (>30%)

Output Files

| File | Description | |------|-------------| | .repogenome/genome.json | Baseline — commit this | | .repogenome/history/<ts>.json | Snapshot per audit run — add to .gitignore | | repogenome-report.html | Self-contained HTML report (--format html) |

Supported Languages

TypeScript · JavaScript · Python · Go · Java · Kotlin

Documentation

| Doc | Description | |-----|-------------| | docs/commands.md | Full command reference with all flags and examples | | docs/security.md | Security policy and vulnerability reporting | | CONTRIBUTING.md | Development setup, project structure, PR guide | | CHANGELOG.md | Release history |

License

MIT © Muhammad Usman