driftmap

Architectural Drift Detection — track how your codebase's structure changes over time.

The Problem

Codebases don't rot overnight. Architecture erodes gradually — one shortcut at a time. A module that started clean accumulates dependencies. Boundaries blur. Coupling grows. By the time you notice, it's a rewrite.

driftmap detects this drift early by analyzing your codebase's structure over time, quantifying how coupling, complexity, and module boundaries change.

How It Works

1. Parse — Tree-sitter ASTs extract call graphs and dependency graphs from JS/TS/Python
2. Graph — Build structural representations: which functions call which, which modules import which
3. Compare — Weisfeiler-Leman graph kernel computes structural similarity between snapshots
4. Measure — Fan-in, fan-out, instability ratios, internal complexity per module
5. Score — coupling_delta × complexity_delta × change_frequency = drift_risk

Install

npm install -g @phoenixaihub/driftmap
# or
npx @phoenixaihub/driftmap analyze .

CLI Usage

Analyze current architecture

driftmap analyze ./src
driftmap analyze ./src --output json

Compare two commits

driftmap compare abc123 def456 --dir .

Generate drift report

driftmap report --dir . --since 30d
driftmap report --dir . --since 7d --output json

Programmatic API

import { analyze, compare, report } from '@phoenixaihub/driftmap';

// Current snapshot
const snapshot = analyze('./src');
console.log(snapshot.coupling.modules);

// Compare commits
const diff = await compare('.', 'main~10', 'main');
console.log(diff.drift.filter(d => d.risk === 'critical'));

// Drift report
const r = await report('.', '2026-03-01');
console.log(JSON.stringify(r, null, 2));

Output Format

{
  "period": { "from": "2026-03-01", "to": "2026-04-01" },
  "modulesAnalyzed": 47,
  "driftScore": 34,
  "hotspots": [
    {
      "module": "src/auth/",
      "coupling_before": 3,
      "coupling_after": 47,
      "coupling_increase": "15.7x",
      "complexity_delta": "+340%",
      "risk": "critical",
      "recommendation": "Module is becoming a god object. Consider extracting shared logic."
    }
  ],
  "graphDiff": {
    "nodes_added": 12,
    "nodes_removed": 3,
    "edges_added": 89,
    "edges_removed": 7
  }
}

Core Algorithms

Weisfeiler-Leman Graph Kernel

Hash-based graph isomorphism test. Iteratively refines node labels by incorporating neighbor information, producing histograms that capture structural patterns. Cosine similarity between histograms quantifies how different two graph snapshots are.

Coupling Metrics

• Fan-in: How many modules depend on X (afferent coupling)
• Fan-out: How many modules X depends on (efferent coupling)
• Instability: fan_out / (fan_in + fan_out) — 0 = maximally stable, 1 = maximally unstable

Drift Score

drift = |coupling_delta| × (1 + |complexity_delta|) × change_frequency

Risk levels: critical (>10), high (>5), medium (>2), low (≤2)

Supported Languages

• JavaScript (.js, .jsx, .mjs, .cjs)
• TypeScript (.ts, .tsx)
• Python (.py)

License

MIT