@esbenwiberg/archmap 0.1.0

package/README.md

@@ -0,0 +1,361 @@
+# archmap
+
+Classify every file in a Node+TypeScript repo as `leaf | branch | hub` based on dependency topology. AI builder and reviewer agents shell out to the same binary and get the same answer — one shared artifact, opposite behaviours.
+
+## The model
+
+Classification is based on **afferent coupling (Ca)** — how many files import a given file.
+
+| Class    | Ca                         | Meaning for an agent                              |
+|----------|----------------------------|---------------------------------------------------|
+| `leaf`   | ≤ threshold.leaf (2)       | Nothing depends on it. Change freely.             |
+| `branch` | > leaf, ≤ junction (3–10)  | Moderate blast radius. Warn, soft-flag.           |
+| `hub`    | > threshold.junction (10)  | Many things depend on it. Mandatory human review. |
+
+Also computed: **instability** `I = Ce / (Ca + Ce)` (Robert Martin's metric). Reported for context; the primary classification signal is Ca.
+
+`.archmap.yaml` carries `overrides` that always win over computed class. This is where Ca can't see risk (security boundaries, published contracts, legacy code scheduled for deletion).
+
+## Install
+
+```bash
+npm install -g @esbenwiberg/archmap
+# or run locally:
+npx tsx bin/archmap.ts <command>
+```
+
+## Commands
+
+```bash
+archmap scan                      # rebuild topology → .archmap/topology.json
+archmap classify <file>           # leaf | branch | hub + Ca, instability, risk, reason
+archmap check <file>...           # exit 1 if ANY input is a hub (CI gate)
+archmap explain <file>            # list dependents + classification rationale
+archmap risk [--top N]            # rank files by combined topology + churn risk
+archmap export [--scope <file>]   # self-contained classified artifact (JSON); --scope narrows to a path list
+```
+
+All commands accept `--json` for machine-readable output (`export` is always JSON). All commands accept `--config <path>` to point at an alternate `.archmap.yaml`.
+
+**Config discovery.** When `--config` is omitted, `archmap` walks up from the
+current directory to the nearest `.archmap.yaml` and treats that directory as
+the project root (chdir'ing into it), so you can run any command from a
+subdirectory and still analyse the whole tree. `entry` paths in a discovered
+config resolve relative to the config file's directory. (With an explicit
+`--config`, paths resolve relative to your current directory.)
+
+### scan
+
+```bash
+archmap scan
+# Scanned 47 files → .archmap/topology.json
+```
+
+### classify
+
+```bash
+archmap classify src/auth/TokenValidator.ts --json
+# {
+#   "file": "src/auth/TokenValidator.ts",
+#   "class": "hub",
+#   "ca": 14,
+#   "tca": 63,
+#   "instability": 0.06,
+#   "risk": { "risk": 100, "structural": 8.41, "churn": 3.14, "tca": 63, "commits": 22 },
+#   "reason": "Ca=14 (14 direct, 63 transitive)",
+#   "overridden": false
+# }
+```
+
+### check
+
+Exit code `0` = no hubs in changeset. Exit code `1` = at least one hub touched.
+
+```bash
+archmap check $(git diff --name-only main)
+# load-bearing (hub) files detected:
+#   src/auth/TokenValidator.ts  Ca=14 (63 transitive)  risk=100/100
+# [exits 1]
+```
+
+### explain
+
+```bash
+archmap explain src/utils/format.ts
+# src/utils/format.ts
+#   class:     hub
+#   reason:    Ca=12 (12 dependents)
+#   ca:        12 (12 files depend on this)
+#   dependents:
+#     src/components/DatePicker.ts
+#     src/services/ReportService.ts
+#     ...
+```
+
+### risk
+
+`classify`/`explain`/`check` answer "how connected is this file?" — a pure
+topology question. `risk` answers "where is fragility concentrated *right
+now*?" by folding in **git churn** (how often a file has changed recently).
+A hub nobody touches is stable; a hub under constant churn is where incidents
+come from.
+
+```bash
+archmap risk --top 5
+# Top 5 riskiest files:
+#
+#   100/100  src/auth/TokenValidator.ts
+#          ca=14  tca=63  churn=22c/90d  structural=8.41
+#    91/100  src/utils/format.ts
+#          ca=12  tca=40  churn=9c/90d   structural=6.77
+#   ...
+```
+
+```bash
+archmap risk --top 1 --json
+# [
+#   {
+#     "file": "src/auth/TokenValidator.ts",
+#     "risk": 100,        # percentile rank across the repo (0–100)
+#     "structural": 8.41, # log1p(Ca) + 1.5·log1p(tCa)
+#     "churn": 3.14,      # log1p(commits in window)
+#     "tca": 63,          # transitive afferent coupling
+#     "commits": 22       # commits touching this file in the last 90 days
+#   }
+# ]
+```
+
+**Risk model.** Each file gets a raw score `0.6·structural + 0.4·churn`, then
+risk is the **percentile rank** of that raw score across the repo (0–100, ties
+share a rank, a lone file scores 50). Components:
+
+- **structural** = `log1p(Ca) + 1.5·log1p(tCa)` — direct *and* transitive
+  fan-in, log-damped so a 200-dependent file isn't 10× a 20-dependent one.
+  Transitive coupling (`tCa`) is weighted higher: indirect blast radius is
+  what makes a change scary.
+- **churn** = `log1p(commits in the last 90 days)` — recency-bounded edit
+  frequency from `git log`.
+
+Risk is **advisory context, not a gate** — `check` still keys off `class`
+alone. Use `risk` to prioritise review attention and refactoring, not to block
+merges. The same `risk` block is attached to every `classify` result, so a
+builder agent gets it for free on its pre-edit probe.
+
+### export
+
+The other commands answer one file at a time and need the source tree present
+to build the graph. `export` answers the whole repo **once** and bakes the
+verdicts into a single self-contained JSON — so a consumer with *no source
+tree* (a hosted review bot that only ever sees a diff) can classify changed
+files by pure lookup.
+
+```bash
+archmap export > archmap.json   # whole repo — every file (good for a global map)
+```
+
+**Scope it to a PR.** The graph still has to be built whole-repo (you can't know
+a file's `dependents` without seeing every importer), but the *output* doesn't
+have to be. `--scope` narrows the emitted `files` to a path list — typically the
+PR's changed files — while keeping each entry's full `dependents` blast radius:
+
+```bash
+git diff --name-only BASE HEAD | archmap export --scope -   # "-" = stdin; or a file
+# {
+#   "version": 1,
+#   "commit": "36d9aef…",                     # consumer verifies this == PR head SHA
+#   "generatedAt": "2026-05-29T19:37:36.047Z",
+#   "scope": {
+#     "requested": ["src/auth/TokenValidator.ts", "src/old.ts"],
+#     "missing":   ["src/old.ts"]              # requested but not in the graph — loud, not silent
+#   },
+#   "files": {                                 # only the in-scope (changed) files
+#     "src/auth/TokenValidator.ts": {
+#       "class": "hub", "ca": 14, "tca": 63,
+#       "instability": 0.06, "risk": 100,
+#       "overridden": false,
+#       "reason": "Ca=14 (14 direct, 63 transitive)",
+#       "dependents": ["src/api/login.ts", "…"]   // the off-diff blast radius
+#     }
+#   }
+# }
+```
+
+Scoping makes the artifact's size track the **diff**, not the repo (a one-line PR
+→ a few entries, not 10k), and archmap normalizes the incoming paths against its
+own graph keys — so a path that doesn't resolve lands in `scope.missing` rather
+than silently vanishing.
+
+**The artifact is derived data — never commit it.** Committing a generated file
+means churn on every PR and a guaranteed merge conflict between any two
+concurrent PRs. Instead, build it in CI (which has the tree) and ship it *out of
+band*, keyed by commit SHA.
+
+#### Consuming the artifact (diff-only review bot)
+
+The integration is: **CI builds and scopes the artifact, the bot just reacts.**
+
+**Race condition** — the `pull_request` webhook and the CI run fire at the same
+instant. Any consumer triggered by `pull_request` will arrive before the
+artifact exists and get a 404. Trigger downstream work on `workflow_run`
+instead:
+
+```yaml
+on:
+  workflow_run:
+    workflows: ["archmap"]
+    types: [completed]
+```
+
+That event fires only after the archmap job finishes — the artifact is
+guaranteed to be present. No polling, no retries, no sleep loops.
+
+**As a GitHub Actions workflow** — see
+[`.github/workflows/archmap-review.yml`](.github/workflows/archmap-review.yml)
+for a complete, copy-paste ready example. Key points:
+- `workflow_run` jobs run in the base-branch context and have write access to
+  `pull-requests` even for fork PRs (unlike `pull_request` jobs).
+- Download the artifact from the *triggering* run via `run-id:
+  ${{ github.event.workflow_run.id }}`.
+- `github.event.workflow_run.pull_requests` is empty for fork PRs; embed the PR
+  number inside the artifact or via a sidecar artifact if you need fork support.
+
+**As an external webhook bot** — subscribe to `workflow_run` events (not
+`pull_request`). Filter for `workflow_run.name === "archmap"` and
+`workflow_run.conclusion === "success"`, then fetch the artifact by
+`workflow_run.head_sha`:
+
+```js
+// webhook handler for workflow_run events
+if (payload.workflow_run.name !== "archmap") return;
+if (payload.workflow_run.conclusion !== "success") return;
+
+const sha = payload.workflow_run.head_sha;
+const art = await fetchArtifact(`archmap-${sha}`); // GH Actions API
+
+if (art.scope.missing.length)                  // paths CI couldn't resolve —
+  warn(`unresolved: ${art.scope.missing}`);    //   surface, don't swallow
+
+const hubs = Object.entries(art.files)
+  .filter(([, v]) => v.class === "hub");
+
+if (hubs.length) {
+  comment(
+    "⚠️ load-bearing files in this diff:\n" +
+    hubs.map(([p, h]) => `- \`${p}\` — ${h.dependents.length} dependents (risk ${h.risk}/100)`).join("\n")
+  );
+}
+```
+
+The `dependents` array is the payload the bot can't get from a diff: the
+files that import the changed one but aren't in the changeset.
+
+If you need the artifact to outlive Actions' retention or to be reachable
+outside GitHub, swap the upload step for a `PUT` to a blob store keyed by SHA
+(`…/<sha>/archmap.json`); the bot's fetch URL changes, nothing else does.
+
+## Configuration: `.archmap.yaml`
+
+Commit this file. It is the human source of truth.
+
+```yaml
+version: 1
+
+thresholds:
+  leaf: 2        # Ca <= 2  → leaf
+  junction: 10   # Ca > 10  → hub; between is branch
+
+# Overrides always win over computed class.
+overrides:
+  - path: "packages/formbuilder/src/schema/**"
+    classification: hub
+    reason: "Schema contract shipped to partners — external blast radius"
+  - path: "src/auth/TokenValidator.ts"
+    classification: hub
+    reason: "Security boundary, low internal fan-in but high risk"
+  - path: "src/legacy/**"
+    classification: leaf
+    reason: "Frozen, scheduled for deletion — don't gate"
+
+analyzers:
+  - lang: typescript
+    entry: "src/"
+```
+
+If `.archmap.yaml` is absent, defaults apply: thresholds 2/10, no overrides, entry `src/`.
+
+## Agent recipes
+
+### Builder agent — pre-edit probe
+
+```bash
+FILE="src/auth/TokenValidator.ts"
+RESULT=$(archmap classify "$FILE" --json)
+CLASS=$(echo "$RESULT" | jq -r '.class')
+
+if [ "$CLASS" = "hub" ]; then
+  echo "⚠ Hub file detected. Make smallest possible diff, preserve public interface."
+  echo "Note contract impact in PR description."
+else
+  echo "Leaf/branch — proceed freely."
+fi
+```
+
+Or as a preamble snippet for your agent:
+
+```
+Before editing any file, run: archmap classify <file> --json
+If class == "hub":
+  - Make the smallest possible diff
+  - Preserve the public interface exactly
+  - Note contract impact in the PR description
+If class == "leaf" or "branch": proceed normally
+```
+
+### Reviewer agent — PR gate
+
+```bash
+HUB_CHECK=$(archmap check $(git diff --name-only main) --json)
+HAS_HUBS=$(echo "$HUB_CHECK" | jq -r '.hasHubs')
+
+if [ "$HAS_HUBS" = "true" ]; then
+  echo "$HUB_CHECK" | jq -r '.hubs[] | "Hub: \(.file)  Ca=\(.ca)"'
+  gh pr edit --add-label "requires-human-review"
+fi
+```
+
+### Pre-commit hook
+
+Add to `.git/hooks/pre-commit` (or via husky/lint-staged):
+
+```bash
+#!/bin/sh
+archmap check $(git diff --cached --name-only)
+```
+
+## Caching
+
+`.archmap/` is a derived cache — **add it to `.gitignore`**:
+
+```
+.archmap/
+```
+
+`.archmap.yaml` is config — **commit it**.
+
+The cache key hashes only import/export structure (not function bodies), so editing a leaf function body doesn't invalidate the graph. `classify` and `check` are near-instant when structure is unchanged.
+
+**Churn cache.** Risk scoring also needs git history, which is independent of
+import structure. The churn map is cached separately, keyed on the current git
+`HEAD` and the window length — so a body edit doesn't bust it, but a new commit
+does. Repeated `classify`/`risk`/`check` calls at the same `HEAD` (e.g. a
+pre-commit run touching many files) reuse one `git log` instead of shelling out
+per file.
+
+## Deferred features (v2+)
+
+These are intentionally absent from v1:
+
+- **C#/Roslyn analyzer** — config schema allows `analyzers[].lang: csharp` but only `typescript` is implemented. Doing it properly needs an LSP/compiler to resolve dependency injection and generics, so it's a large task deferred until there's demand. Node+TypeScript is the focus.
+- **Dirty-subgraph partial rebuild** — full rescan on miss; the cache makes it rare
+- **Cycle / SCC handling** — `dependency-cruiser` can report cycles; classifying them is v2
+- **A review bot** — `archmap` stays just the CLI. `export` + the sample workflow give a consumer everything it needs (see [export](#export)), but the bot that fetches the artifact and comments on PRs lives downstream.

package/dist/bin/archmap.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=archmap.d.ts.map

package/dist/bin/archmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archmap.d.ts","sourceRoot":"","sources":["../../bin/archmap.ts"],"names":[],"mappings":""}

package/dist/bin/archmap.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { scanCommand } from "../src/commands/scan.js";
+import { classifyCommand } from "../src/commands/classify.js";
+import { checkCommand } from "../src/commands/check.js";
+import { explainCommand } from "../src/commands/explain.js";
+import { riskCommand } from "../src/commands/risk.js";
+import { exportCommand } from "../src/commands/export.js";
+const program = new Command();
+program
+    .name("archmap")
+    .description("Classify repo files as leaf | branch | hub by dependency topology")
+    .version("0.1.0")
+    .option("--config <path>", "Path to .archmap.yaml (default: .archmap.yaml)");
+program
+    .command("scan")
+    .description("Rebuild topology and write .archmap/topology.json")
+    .option("--entry <path>", "Entry path override (overrides config)")
+    .option("--json", "JSON output")
+    .action(async (opts) => {
+    const { resolveProject } = await import("../src/config.js");
+    const globalOpts = program.opts();
+    const { entry: cfgEntry } = resolveProject(globalOpts.config);
+    const entry = opts.entry ?? cfgEntry;
+    await scanCommand(entry, opts);
+});
+program
+    .command("classify <file>")
+    .description("Classify a single file (leaf | branch | hub)")
+    .option("--json", "JSON output")
+    .action(async (file, opts) => {
+    const globalOpts = program.opts();
+    await classifyCommand(file, { ...opts, config: globalOpts.config });
+});
+program
+    .command("check <files...>")
+    .description("Exit non-zero if any input file is a hub (CI/hook gate)")
+    .option("--json", "JSON output")
+    .action(async (files, opts) => {
+    const globalOpts = program.opts();
+    await checkCommand(files, { ...opts, config: globalOpts.config });
+});
+program
+    .command("explain <file>")
+    .description("List dependents and classification rationale")
+    .option("--json", "JSON output")
+    .action(async (file, opts) => {
+    const globalOpts = program.opts();
+    await explainCommand(file, { ...opts, config: globalOpts.config });
+});
+program
+    .command("risk")
+    .description("List riskiest files by combined topology + churn score")
+    .option("--top <n>", "Number of files to show (default: 10)")
+    .option("--json", "JSON output")
+    .action(async (opts) => {
+    const globalOpts = program.opts();
+    await riskCommand({ ...opts, config: globalOpts.config });
+});
+program
+    .command("export")
+    .description("Emit a self-contained classified topology artifact (JSON) for external consumers")
+    .option("--scope <file>", "Narrow output to a newline-delimited path list (\"-\" for stdin)")
+    .action(async (opts) => {
+    const globalOpts = program.opts();
+    await exportCommand({ ...opts, config: globalOpts.config });
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+});
+//# sourceMappingURL=archmap.js.map

package/dist/bin/archmap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archmap.js","sourceRoot":"","sources":["../../bin/archmap.ts"],"names":[],"mappings":"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"}

package/dist/src/cache.d.ts

@@ -0,0 +1,30 @@
+import type { Topology } from "./graph.js";
+import type { ChurnData } from "./churn.js";
+interface ChurnCache {
+    key: string;
+    entries: Array<[string, ChurnData]>;
+}
+interface CacheEntry {
+    hash: string;
+    topology: Topology;
+    churn?: ChurnCache;
+}
+export declare function readCache(): CacheEntry | null;
+/** Persist topology under a structure hash, preserving any cached churn. */
+export declare function writeCache(hash: string, topology: Topology): void;
+export declare function getFreshTopology(entry: string, buildFn: (entry: string) => Promise<Topology>): Promise<{
+    topology: Topology;
+    cacheHit: boolean;
+}>;
+/**
+ * Return the churn map, reusing the cached one when git HEAD and the window
+ * are unchanged. Churn is keyed on HEAD (not the structure hash) because it
+ * derives from commit history, not import structure — so editing a file body
+ * doesn't bust it, but a new commit does.
+ */
+export declare function getFreshChurn(windowDays: number, buildFn: (windowDays: number) => Map<string, ChurnData>): {
+    churn: Map<string, ChurnData>;
+    cacheHit: boolean;
+};
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/src/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;CACrC;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAkBD,wBAAgB,SAAS,IAAI,UAAU,GAAG,IAAI,CAM7C;AAOD,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAGjE;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,GAC5C,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CASpD;AAaD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GACtD;IAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAUtD"}

package/dist/src/cache.js

@@ -0,0 +1,78 @@
+import { createHash } from "crypto";
+import { execSync } from "child_process";
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { listTypeScriptFiles } from "./files.js";
+const CACHE_DIR = ".archmap";
+const CACHE_FILE = `${CACHE_DIR}/cache.json`;
+function computeStructureHash(entry) {
+    const files = listTypeScriptFiles(entry);
+    const hasher = createHash("sha256");
+    for (const file of files) {
+        hasher.update(file + "\n");
+        try {
+            const src = readFileSync(file, "utf8");
+            const imports = src.match(/^(import|export).*from\s+['"].*['"]/gm) ?? [];
+            hasher.update(imports.join("\n") + "\n");
+        }
+        catch {
+            // skip unreadable files
+        }
+    }
+    return hasher.digest("hex");
+}
+export function readCache() {
+    try {
+        return JSON.parse(readFileSync(CACHE_FILE, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeCacheEntry(entry) {
+    mkdirSync(CACHE_DIR, { recursive: true });
+    writeFileSync(CACHE_FILE, JSON.stringify(entry, null, 2));
+}
+/** Persist topology under a structure hash, preserving any cached churn. */
+export function writeCache(hash, topology) {
+    const existing = readCache();
+    writeCacheEntry({ hash, topology, churn: existing?.churn });
+}
+export async function getFreshTopology(entry, buildFn) {
+    const hash = computeStructureHash(entry);
+    const cached = readCache();
+    if (cached && cached.hash === hash) {
+        return { topology: cached.topology, cacheHit: true };
+    }
+    const topology = await buildFn(entry);
+    writeCache(hash, topology);
+    return { topology, cacheHit: false };
+}
+function gitHead() {
+    try {
+        return execSync("git rev-parse HEAD", {
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "nogit";
+    }
+}
+/**
+ * Return the churn map, reusing the cached one when git HEAD and the window
+ * are unchanged. Churn is keyed on HEAD (not the structure hash) because it
+ * derives from commit history, not import structure — so editing a file body
+ * doesn't bust it, but a new commit does.
+ */
+export function getFreshChurn(windowDays, buildFn) {
+    const key = `${gitHead()}:${windowDays}`;
+    const cached = readCache();
+    if (cached?.churn && cached.churn.key === key) {
+        return { churn: new Map(cached.churn.entries), cacheHit: true };
+    }
+    const churn = buildFn(windowDays);
+    const base = cached ?? { hash: "", topology: { files: {} } };
+    writeCacheEntry({ ...base, churn: { key, entries: [...churn] } });
+    return { churn, cacheHit: false };
+}
+//# sourceMappingURL=cache.js.map

package/dist/src/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/src/churn.d.ts

@@ -0,0 +1,6 @@
+export interface ChurnData {
+    commits: number;
+    windowDays: number;
+}
+export declare function buildChurnMap(windowDays?: number): Map<string, ChurnData>;
+//# sourceMappingURL=churn.d.ts.map

package/dist/src/churn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"churn.d.ts","sourceRoot":"","sources":["../../src/churn.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,aAAa,CAAC,UAAU,SAAK,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAkCrE"}

package/dist/src/churn.js

@@ -0,0 +1,32 @@
+import { execSync } from "child_process";
+export function buildChurnMap(windowDays = 90) {
+    const churn = new Map();
+    let raw;
+    try {
+        raw = execSync(`git log --name-only --pretty=format:"COMMIT" --after="${windowDays} days ago"`, { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] });
+    }
+    catch {
+        return churn;
+    }
+    let currentFile = false;
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "COMMIT") {
+            currentFile = true;
+            continue;
+        }
+        if (trimmed === "") {
+            currentFile = false;
+            continue;
+        }
+        if (currentFile && trimmed) {
+            const existing = churn.get(trimmed);
+            churn.set(trimmed, {
+                commits: (existing?.commits ?? 0) + 1,
+                windowDays,
+            });
+        }
+    }
+    return churn;
+}
+//# sourceMappingURL=churn.js.map

package/dist/src/churn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"churn.js","sourceRoot":"","sources":["../../src/churn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAOzC,MAAM,UAAU,aAAa,CAAC,UAAU,GAAG,EAAE;IAC3C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;IAE3C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,QAAQ,CACZ,yDAAyD,UAAU,YAAY,EAC/E,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CACxD,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;YACzB,WAAW,GAAG,IAAI,CAAC;YACnB,SAAS;QACX,CAAC;QACD,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;YACnB,WAAW,GAAG,KAAK,CAAC;YACpB,SAAS;QACX,CAAC;QACD,IAAI,WAAW,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACpC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE;gBACjB,OAAO,EAAE,CAAC,QAAQ,EAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC;gBACrC,UAAU;aACX,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/classify.d.ts

@@ -0,0 +1,16 @@
+import type { ArchmapConfig } from "./config.js";
+import type { Topology } from "./graph.js";
+import type { RiskScore } from "./risk.js";
+export type Klass = "leaf" | "branch" | "hub";
+export interface Classification {
+    file: string;
+    class: Klass;
+    ca: number;
+    tca: number;
+    instability: number;
+    risk: RiskScore | null;
+    reason: string;
+    overridden: boolean;
+}
+export declare function classifyFile(file: string, topology: Topology, config: ArchmapConfig, riskScores?: Map<string, RiskScore>): Classification;
+//# sourceMappingURL=classify.d.ts.map

package/dist/src/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/classify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE9C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,aAAa,EACrB,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GAClC,cAAc,CA8DhB"}