@titan-design/code-graph 0.1.0 → 0.2.0

package/README.md

@@ -5,8 +5,8 @@ symbols, external packages, and the import / re-export / reference edges between
 index-time source metrics, in one SQLite file built from `@titan-design/store-sqlite` kit
 tables and refreshed incrementally.
 
-Tier 2 of the titan-platform DAG. Depends on `store-sqlite`, `ts-morph`, and the tree-sitter
-WASM grammars. Extracted from codewatch's `@codewatch/graph` (TP-9), split along the seam the
+Tier 2 of the titan-platform DAG. Depends on `store-sqlite`, `code-parser` (tree-sitter WASM
+parsing and the file filter), `ts-morph`, `web-tree-sitter` for node types, and `embed` plus `retrieval` for similar-symbol search. Extracted from codewatch's `@codewatch/graph` (TP-9), split along the seam the
 audit identified: that package did the job of both a store and a code graph.
 
 ```ts
@@ -23,7 +23,8 @@ listEdges(store, snapshotId); // imports / re-exports, references on request
 
 ## What was extracted, and what was not
 
-In: the parser (tree-sitter WASM for TypeScript, TSX and Python), the walk, the ts-morph
+In: the parser (tree-sitter WASM for TypeScript, TSX and Python, since moved to
+`@titan-design/code-parser` and still re-exported here), the walk, the ts-morph
 extractor and its symbol layer, role classification, generated-file detection, id aliasing
 across git renames, the three-tier incremental reuse, and the metrics computed at index time
 (degree, utilization, loc, cyclomatic, cognitive, nesting, class count, lcom4, per-symbol
@@ -31,16 +32,19 @@ complexity). `lcom.ts` came along despite being an analysis: `source-metrics.ts`
 directly and lcom4 is a pure function of a file's bytes, so it belongs with the metrics that
 carry forward under reuse.
 
+Ported later (TP-123, TP-124), strictly as codewatch had them: the rules engine
+(`check*.ts`, now `src/check/`) and the snapshot diff plus check diff (`diff.ts`,
+`check-diff.ts`, now `src/diff/`). See [Checks and diffs](#checks-and-diffs).
+Ported with TP-127 and TP-128: dead code, growth risk, PageRank, relevance, and symbol
+coupling, now `src/analysis/`. See [Graph analyses](#graph-analyses).
+Ported with TP-133: the test linker and the Istanbul coverage overlay, also in `src/analysis/`,
+and test-coverage ownership. See [Test linking and coverage](#test-linking-and-coverage).
+
 Deferred, all of it still in codewatch, all of it a follow-up on this package rather than a
 change to it:
 
-- The rules engine (`check*.ts`) that turns a snapshot into pass/fail against a config.
-- Git-history mining: churn, ownership, change coupling, symbol coupling, test coverage
-  linking. `buildIndexerMetrics` used to fold these into the same pass; here it computes only
-  what a file's own bytes and the assembled graph determine.
-- Graph analyses over a finished snapshot: communities, pagerank, partition quality,
-  relevance, conventions, coverage overlay, dead code, growth risk, patterns, prune,
-  test-linker, diff, reuse-delta reporting, embeddings.
+- Graph analyses over a finished snapshot: communities, partition quality, conventions,
+  patterns, prune, reuse-delta reporting.
 
 Python support is new here rather than ported. codewatch walked TypeScript only; the parser
 already had the grammar. The Python extractor is deliberately narrower than the ts-morph one:
@@ -49,16 +53,24 @@ same tree-sitter declaration walk that feeds complexity.
 
 ## The id scheme
 
-Preserved exactly from codewatch, because this repo's own `dag:check` consumes it through
-codewatch's CLI:
+File, module and external ids are preserved exactly from codewatch, because this repo's own
+`dag:check` consumes them through codewatch's CLI. Symbol ids diverge from codewatch since
+index version 0.14.0:
 
 - A **file** id is its path relative to the git toplevel, in posix form:
   `packages/registry/src/index.ts`. Ids root at the git toplevel even when you walk a
   subtree, so importers across subtrees share one id space.
 - A **module** id is the file id minus its extension: `packages/registry/src/index`. Its
   parent is the directory above it.
-- A **symbol** id hangs under its declaring file as `<fileId>#<name>`. `#` is legal in
-  neither a posix path nor a JS identifier, so the first one is the split.
+- A **symbol** id hangs under its declaring file as `<fileId>#<qualifiedName>`, split on the
+  first `#`. A top-level declaration's qualified name is its own name
+  (`src/a.ts#createThing`). A member or nested declaration is prefixed by its enclosing named
+  scopes, joined with `.`: `src/a.ts#Job.run`, `src/a.ts#outer.helper`, and
+  `src/a.ts#handlers.onClick` for a method of `const handlers = {…}`. Anonymous scopes, such
+  as a callback argument or an unbound class expression, add no segment, so ids do not depend
+  on declaration order. One scope binds a name once: a getter/setter pair, a Python property's
+  accessors, and overloads each share one node. Index versions before 0.14.0 keyed members by
+  bare name, so same-named methods in one file collapsed into one node (TP-182).
 - An **external** id is `npm:<package>` (scope-aware) or the `node:` builtin verbatim.
 
 `NodeKind`, `EdgeKind`, and the `role` vocabulary are unchanged. So is the property the DAG
@@ -71,7 +83,14 @@ ts-morph resolves back onto `src/`. That remap needs the target package built, w
 
 Every run writes a fingerprint per file: a content hash and a comment/whitespace-insensitive
 hash of its parse structure. The next run diffs against the most recent snapshot carrying the
-same `INDEX_VERSION` and sorts each file into one tier.
+same `INDEX_VERSION` and sorts each file into one tier. `INDEX_VERSION` is bumped whenever a
+metric can change for the same bytes, not only when the node or edge shape changes: 0.12.0
+marks `.tsx` files moving to the tsx grammar, which changed their complexity metrics and
+symbol spans; 0.13.0 marks the dead-code and growth-risk metrics joining the carry-forward set;
+0.14.0 marks symbol ids qualified by their enclosing scopes (TP-182). A snapshot from before
+0.14.0 is never reused, so re-index. The first 0.14.0 run after an older snapshot writes
+`requalify` id aliases from each bare-name id to its qualified successor, only where exactly one
+declaration in the file carries that name.
 
 | Tier | Trigger | Work skipped |
 |---|---|---|
@@ -88,6 +107,10 @@ always recomputed over the whole assembled graph, so a heavily-reused run and a
 
 `openCodeGraph` opens the database with the kit's pragmas and runs three migrations.
 
+It refuses a database stamped past `SCHEMA_VERSION` with `SchemaTooNewError`: a code graph
+database belongs to one build, so a higher version means a newer build already moved the
+schema and this one would query columns that are gone.
+
 Kit tables: `snapshot` (the snapshot registry), `node` (`entity_snap`, keyed
 `(snapshot_id, id)`), `blob_cache` (content-addressed, for the embedding and summary caches
 an analysis layer will want). Migration 2 adds four columns the kit shapes do not carry but
@@ -103,3 +126,174 @@ The symbol layer is hidden by default. `listNodes` drops `symbol` nodes and `lis
 `references` edges unless you ask for them, so a caller reasoning about module structure sees
 the graph it expects and does not have one import of thirty names read as thirty
 dependencies.
+
+## Checks and diffs
+
+The rules engine turns a snapshot into pass/fail against a `check.json`. Six rule types:
+`metric-max`, `metric-min`, `metric-product-max`, `forbid-import`, `layered-deps`, and
+`no-internal-only-barrels`. Severity defaults to `error`; only new errors fail a check.
+
+```ts
+import { checkSnapshot, loadCheckRules, openCodeGraph } from "@titan-design/code-graph";
+
+const store = openCodeGraph(".codewatch/graph.db");
+const rules = await loadCheckRules(".codewatch/check.json", { onWarn: console.warn });
+const { result } = checkSnapshot(store, { snapshot: "head", baseline: "main", rules });
+result.passed; // false only when a violation is an error and absent from the baseline
+```
+
+`snapshot` and `baseline` take a numeric snapshot id or a ref name; a ref resolves to its
+newest snapshot. `runChecks(store, { snapshotId, rules, baselineSnapshotId })` is the same
+engine on ids, and `validateRules(json)` validates an already-parsed rules object.
+
+The baseline is a ratchet. A violation whose key (rule id, node id, and destination id for
+edge rules) also fires on the baseline snapshot is marked `isCarryover` and counts as
+carryover, so existing debt does not block a change but new debt does. Deprecated metric and
+role spellings in a rules file (`lines`, `tests`) heal to their canonical names with a
+warning through `onWarn` instead of failing validation.
+
+`diffSnapshots(store, { fromSnapshotId, toSnapshotId })` reports added, removed and renamed
+nodes, added and removed edges, and metric deltas on nodes present in both. The
+to-snapshot's `id_alias` rows carry a renamed file across, so a move reads as a rename rather
+than a delete plus an add, and its edges do not churn. Metric and edge-kind spellings are
+canonicalised before comparing.
+
+`diffCheckResults(store, { fromSnapshotId, toSnapshotId, rules })` runs the rules on both
+snapshots and buckets each violation as new, resolved, or unchanged; unchanged metric
+violations are further split into worsened and improved by value.
+
+`scripts/dag-check-self.mjs` in the repo root runs this repo's DAG check on this engine
+instead of codewatch's CLI.
+
+## Similar symbols
+
+Ported from codewatch's `embeddings.ts` (TP-129). It answers "does something like this
+already exist?" before you write it. The embedder is injected; this package never builds
+one and never talks to a network on its own.
+
+```ts
+import { OllamaEmbedder } from "@titan-design/embed";
+import { findSimilarCapability, tryEmbedSnapshot } from "@titan-design/code-graph";
+
+const embedder = new OllamaEmbedder();
+const attempt = await tryEmbedSnapshot(store, snapshotId, embedder);
+// { ok: true, result: { symbols, embedded, withPurpose, newlyEmbedded, reused, model } }
+// or { ok: false, model, error } when the backend is down; the snapshot is unaffected
+const { candidates, coverage } = await findSimilarCapability(store, snapshotId, "parse a duration", embedder);
+```
+
+- **Corpus.** Exported symbols with a signature, minus test, fixture and generated files.
+  The embedded text is `signature -- purpose` (the docstring), never the body.
+- **Storage.** Vectors go in `blob_cache` under namespace `code-graph/symbol-embedding`,
+  keyed by `embedder.model` and the SHA-256 of the text. They are not snapshot-scoped, so
+  re-embedding unchanged text costs zero embed calls. `embedSnapshot` throws on a backend
+  failure; `tryEmbedSnapshot` reports it.
+- **Query.** `vectorRetriever` over a `BruteForceVectorIndex` from `retrieval`. The query is
+  embedded with role `query` and the symbol texts with role `document`; the embedder applies
+  the matching prefix (`search_query: ` / `search_document: ` for nomic models).
+- **Results are candidates, not verdicts.** Each has a cosine score, and `coverage` says how
+  many symbols were searchable and how many carry purpose text. There is deliberately no
+  co-location filter.
+- **Python symbols are not in the corpus yet.** The Python extractor records no signature or
+  docstring, so no Python symbol passes the corpus filter.
+- **Prefixes are part of the cache key.** `embedder.model` includes a hash of the embedder's
+  prefix table, so two prefix configurations never share a vector. codewatch used no prefix;
+  `new OllamaEmbedder({ prefixes: { document: "", query: "" } })` reproduces its rankings.
+
+## Graph analyses
+
+Dead-code and growth-risk metrics are computed at index time, like the source metrics, and
+carry forward for unchanged files. Both are sparse: a file gets a row only when a count is
+above zero.
+
+- Dead code, TypeScript only: `unreachable_statements` (after a `return`, `throw`, `break`
+  or `continue` in the same block), `unused_locals`, and `unused_params` (trailing run only).
+- Growth risk, TypeScript and Python: `loop_depth` (at 2 or more), `recursive_functions`,
+  and `search_in_loop` (`.includes`, `.find` and similar inside a loop). These are smells,
+  not complexity bounds. Recursion and search match TypeScript call nodes only, so Python
+  files get `loop_depth` alone, as in codewatch.
+
+PageRank, relevance, and symbol coupling run at query time over one snapshot:
+
+```ts
+import {
+  snapshotPageRank,
+  snapshotRelevance,
+  snapshotSymbolCoupling,
+} from "@titan-design/code-graph";
+
+snapshotPageRank(store, snapshotId); // global centrality over the file-level graph
+snapshotPageRank(store, snapshotId, { personalization: new Map([[fileId, 1]]) }); // seeded
+snapshotRelevance(store, snapshotId, [fileId]); // seeded over symmetrized edges
+snapshotSymbolCoupling(store, snapshotId); // symbol pairs co-imported by 2+ files
+```
+
+The pure `computePageRank`, `computeRelevance`, `computeSymbolConsumers`, and
+`computeSymbolCoupling` take node and edge arrays instead of a store.
+
+## Git history
+
+Ported in TP-126, strictly as codewatch had it: churn over rolling windows, first-seen dates,
+ownership and bus factor, and change coupling. The engine lives in `src/history/` and is
+published on its own subpath. Its API is path-based: repo-relative posix paths in, plain
+records out, no node ids or snapshots.
+
+```ts
+import { computeChangeCoupling, couplingFor, loadChurnEntries } from "@titan-design/code-graph/history";
+
+const entries = loadChurnEntries({ repoRoot: ".", windowDays: 90 }) ?? []; // null outside git
+const { pairs, skippedLargeCommits } = computeChangeCoupling(entries);
+couplingFor(pairs, "packages/code-graph/src/indexer.ts"); // partners by co-edit count
+```
+
+`indexPaths` writes history metrics on file nodes by default, through the
+`history-metrics.ts` adapter, with codewatch's names: `churn_{w}`, `churn_{w}_commits`,
+`churn_{w}_authors` and `recency_{w}` for each window, `file_age_days`, and `bus_factor_{w}`
+plus `top_author_share_{w}` for the primary window. Windows default to 30, 90 and 180 days
+plus `churnWindowDays` (the primary, default 30); `churnWindows` replaces the defaults and
+`lifetime: true` adds an all-history window with its own ownership. `computeChurn: false`
+turns all of it off. Outside git, or without a git binary, the index simply has no history
+metrics.
+
+Change coupling is not stored. It is computed on demand from `loadChurnEntries`, as
+codewatch's `graph coupled` command did.
+
+**The seam.** Nothing under `src/history/` imports the rest of code-graph; the rest may import
+it. The `code-graph-history-seam` rule in `.codewatch/check.json` fails `pnpm dag:check` on
+any such import. That keeps a later extraction into `@titan-design/git-history` a directory
+move plus an import-path change.
+
+**Behaviour kept from codewatch, gaps included.** A rename is followed only inside the commit
+that made it, so a file's churn before the rename stays on its old path and is dropped.
+First-seen dates come from a separate `--no-renames` pass, which makes a renamed file look
+younger. `--since` resolves against git's clock while window slicing uses `nowEpoch`. History
+metrics are recomputed on every index and never carried forward under reuse.
+
+## Test linking and coverage
+
+Ported in TP-133, strictly as codewatch had it. `linkTestsToSources` pairs each test file
+with non-test files in two passes. Pass 1 uses path conventions: it strips a `.test` or `.spec`
+infix and collapses a `__tests__/`, `test/` or `tests/` segment. Pass 2 gives a test that
+pass 1 left unpaired its strongest co-edited non-test partner, with at least 2 shared commits.
+
+`indexPaths` writes `linked_test_count` on each linked source, with or without git. With git
+history on it also writes `test_bus_factor_{w}` and `test_top_author_share_{w}` for the
+primary window. These summarize churn authorship across all tests linked to a source, so a
+file can be well spread in production code and a single-author silo in its tests. All three
+are recomputed on every index and never carried forward.
+
+`computeTestCoverageOwnership` lives in the `history-metrics.ts` adapter, not in
+`src/history/`. It needs test links, and the seam forbids history from importing them.
+
+```ts
+import { attributeCoverage } from "@titan-design/code-graph";
+
+// fileIdOf maps an absolute path to a file id, or null to skip; spans come from symbol nodes' attrs.
+const metrics = attributeCoverage(istanbulReport, fileIdOf, symbolSpansByFile);
+```
+
+`attributeCoverage` turns an Istanbul `coverage-final.json` into `coverage_pct` metrics: one
+per file (covered functions over total functions) and one per symbol, matched by line-range
+containment to the innermost symbol. Coverage depends on which tests ran, not on file bytes,
+so the index never writes or carries it. The caller stores it on the snapshot it measured,
+as codewatch's `graph coverage` command does.

package/dist/change-coupling-CyqHgRsm.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A churn window is either a rolling N-day window or `"lifetime"` = all of git
+ * history (no `--since` bound). Lifetime mode lets an unfamiliar repo be audited
+ * cold, where any recent rolling slice is thin relative to the repo's whole
+ * life, so a windowed view reads an established repo as nearly churn-free.
+ */
+type ChurnWindow = number | "lifetime";
+
+interface ChurnEntry {
+    commit: string;
+    /** Author identity: git author email (%ae), stable across name spelling drift. */
+    author: string;
+    /** Committer time (%ct), epoch seconds; lets one wide log be sliced per window. */
+    epoch: number;
+    /** Repo-relative posix path, rebased onto the caller's root. */
+    filePath: string;
+    added: number;
+    deleted: number;
+}
+interface LoadChurnOptions {
+    /** Directory paths are made relative to; entries outside it are dropped. */
+    repoRoot: string;
+    windowDays?: ChurnWindow;
+}
+/**
+ * Parse the last `windowDays` of git history into ChurnEntry[] rebased onto
+ * `repoRoot`. Returns null if git isn't available; [] if no commits matched.
+ * Used both for churn metrics and for change-coupling.
+ */
+declare function loadChurnEntries(options: LoadChurnOptions): ChurnEntry[] | null;
+declare function parseChurnLog(text: string): ChurnEntry[];
+declare function resolveRenamedPath(rawPath: string): string;
+/** Entries whose commit landed within the last `windowDays` of `nowEpoch`. */
+declare function entriesWithin(entries: readonly ChurnEntry[], windowDays: number, nowEpoch: number): ChurnEntry[];
+
+interface CoEditPair {
+    fileA: string;
+    fileB: string;
+    /** Commits in which both files changed. */
+    count: number;
+    /** Most recent commits (up to maxCommitsPerPair). */
+    commits: string[];
+}
+interface ComputeChangeCouplingOptions {
+    /** Skip pairs that co-occur in fewer than this many commits. Default 2. */
+    minCount?: number;
+    /** Truncate the commits sample per pair. Default 10. */
+    maxCommitsPerPair?: number;
+    /**
+     * Skip commits touching more than this many files (sweeping refactors, mass
+     * renames). Default 50: beyond that the O(n²) pair explosion is signal-poor.
+     */
+    largeCommitThreshold?: number;
+    /** Filter file paths to this set before pairing. */
+    knownPaths?: ReadonlySet<string>;
+}
+interface ChangeCouplingResult {
+    pairs: CoEditPair[];
+    /** Commits dropped by largeCommitThreshold, so callers can say when sweeps suppressed the signal. */
+    skippedLargeCommits: number;
+    /** Threshold that was applied (echoed for diagnostic messages). */
+    largeCommitThreshold: number;
+}
+interface CouplingPartner {
+    partner: string;
+    count: number;
+    commits: string[];
+}
+declare function computeChangeCoupling(entries: readonly ChurnEntry[], options?: ComputeChangeCouplingOptions): ChangeCouplingResult;
+/** Files most coupled to `seed`, by co-edit count desc then path; the seed itself is excluded. */
+declare function couplingFor(pairs: readonly CoEditPair[], seed: string): CouplingPartner[];
+
+export { type ChurnEntry as C, type LoadChurnOptions as L, type ChurnWindow as a, type ChangeCouplingResult as b, type CoEditPair as c, type ComputeChangeCouplingOptions as d, type CouplingPartner as e, computeChangeCoupling as f, couplingFor as g, entriesWithin as h, loadChurnEntries as l, parseChurnLog as p, resolveRenamedPath as r };

package/dist/chunk-PFI5XMUG.js

@@ -0,0 +1,332 @@
+// src/history/log.ts
+import { realpathSync } from "fs";
+import * as path from "path";
+
+// src/history/git.ts
+import { execFileSync } from "child_process";
+function discoveryEnv() {
+  const env = { ...process.env };
+  delete env.GIT_DIR;
+  delete env.GIT_INDEX_FILE;
+  delete env.GIT_WORK_TREE;
+  return env;
+}
+function runGit(cwd, args) {
+  try {
+    return execFileSync("git", [...args], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      env: discoveryEnv()
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function detectGitToplevel(cwd) {
+  return runGit(cwd, ["rev-parse", "--show-toplevel"]);
+}
+function runGitLarge(cwd, args, maxBuffer) {
+  try {
+    return execFileSync("git", [...args], {
+      cwd,
+      encoding: "utf-8",
+      maxBuffer,
+      stdio: ["ignore", "pipe", "ignore"],
+      env: discoveryEnv()
+    });
+  } catch {
+    return null;
+  }
+}
+
+// src/history/window.ts
+var DAY_SECONDS = 86400;
+function windowCutoff(windowDays, nowEpoch) {
+  return nowEpoch - windowDays * DAY_SECONDS;
+}
+
+// src/history/log.ts
+var DEFAULT_WINDOW_DAYS = 30;
+var COMMIT_HASH_RE = /^[0-9a-f]{7,40}$/;
+var NUMSTAT_FIRST_RE = /^(\d+|-)$/;
+function loadChurnEntries(options) {
+  const windowDays = options.windowDays ?? DEFAULT_WINDOW_DAYS;
+  const gitRoot = detectGitToplevel(options.repoRoot);
+  if (gitRoot === null) return null;
+  const log = runChurnLog(options.repoRoot, windowDays);
+  if (log === null) return null;
+  const canonicalRoot = canonicalize(options.repoRoot);
+  return parseChurnLog(log).flatMap((entry) => {
+    const rel = rebasePath(entry.filePath, gitRoot, canonicalRoot);
+    return rel === null ? [] : [{ ...entry, filePath: rel }];
+  });
+}
+function rebasePath(gitPath, gitRoot, rootDir) {
+  const rel = path.relative(rootDir, path.resolve(gitRoot, gitPath));
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join("/");
+}
+function canonicalize(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+function parseChurnLog(text) {
+  const out = [];
+  let header = null;
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trimEnd();
+    if (!line) continue;
+    const parts = line.split("	");
+    if (parts.length === 3 && header && NUMSTAT_FIRST_RE.test(parts[0]) && NUMSTAT_FIRST_RE.test(parts[1])) {
+      out.push({ ...header, ...parseNumstat(parts), filePath: resolveRenamedPath(parts[2]) });
+      continue;
+    }
+    if (parts.length >= 2 && COMMIT_HASH_RE.test(parts[0])) {
+      header = { commit: parts[0], author: parts[1], epoch: parts.length >= 3 ? Number(parts[2]) : 0 };
+    }
+  }
+  return out;
+}
+function parseNumstat(parts) {
+  return {
+    added: parts[0] === "-" ? 0 : Number(parts[0]),
+    deleted: parts[1] === "-" ? 0 : Number(parts[1])
+  };
+}
+function resolveRenamedPath(rawPath) {
+  const braceMatch = /^(.*)\{(.*) => (.*)\}(.*)$/.exec(rawPath);
+  if (braceMatch) {
+    const [, prefix, , newSeg, suffix] = braceMatch;
+    return `${prefix}${newSeg}${suffix}`.replace(/\/+/g, "/");
+  }
+  const arrow = rawPath.indexOf(" => ");
+  if (arrow >= 0) return rawPath.slice(arrow + 4);
+  return rawPath;
+}
+function entriesWithin(entries, windowDays, nowEpoch) {
+  const cutoff = windowCutoff(windowDays, nowEpoch);
+  return entries.filter((e) => e.epoch >= cutoff);
+}
+function runChurnLog(repoRoot, windowDays) {
+  const sinceArgs = windowDays === "lifetime" ? [] : [`--since=${windowDays}.days.ago`];
+  const format = "--pretty=format:%H%x09%ae%x09%ct";
+  return runGitLarge(repoRoot, ["log", ...sinceArgs, "--no-merges", "--numstat", "-M", format], 64 * 1024 * 1024);
+}
+
+// src/history/first-seen.ts
+function loadFileFirstSeen(options) {
+  const gitRoot = detectGitToplevel(options.repoRoot);
+  if (gitRoot === null) return null;
+  const log = runFirstSeenLog(options.repoRoot);
+  if (log === null) return null;
+  const canonicalRoot = canonicalize(options.repoRoot);
+  const firstSeen = /* @__PURE__ */ new Map();
+  for (const { epoch, gitPath } of parseFirstSeenLog(log)) {
+    const rel = rebasePath(resolveRenamedPath(gitPath), gitRoot, canonicalRoot);
+    if (rel === null) continue;
+    if (options.knownPaths && !options.knownPaths.has(rel)) continue;
+    if (!firstSeen.has(rel)) firstSeen.set(rel, epoch);
+  }
+  return firstSeen;
+}
+function parseFirstSeenLog(text) {
+  const out = [];
+  let epoch = 0;
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trimEnd();
+    if (!line) continue;
+    const parts = line.split("	");
+    if (parts.length === 2 && COMMIT_HASH_RE.test(parts[0])) {
+      epoch = Number(parts[1]);
+      continue;
+    }
+    if (epoch) out.push({ epoch, gitPath: line });
+  }
+  return out;
+}
+function runFirstSeenLog(repoRoot) {
+  const args = ["log", "--reverse", "--no-merges", "--no-renames", "--name-only", "--pretty=format:%H%x09%ct"];
+  return runGitLarge(repoRoot, args, 128 * 1024 * 1024);
+}
+
+// src/history/churn.ts
+function aggregateChurn(entries, knownPaths) {
+  const lines = /* @__PURE__ */ new Map();
+  const commits = /* @__PURE__ */ new Map();
+  const authors = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    if (knownPaths && !knownPaths.has(e.filePath)) continue;
+    lines.set(e.filePath, (lines.get(e.filePath) ?? 0) + e.added + e.deleted);
+    setAdd(commits, e.filePath, e.commit);
+    setAdd(authors, e.filePath, e.author);
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const [filePath, total] of lines) {
+    out.set(filePath, {
+      lines: total,
+      commits: commits.get(filePath).size,
+      authors: authors.get(filePath).size
+    });
+  }
+  return out;
+}
+function aggregateChurnWindows(entries, windowsDays, nowEpoch, knownPaths) {
+  const out = /* @__PURE__ */ new Map();
+  for (const windowDays of windowsDays) {
+    const within = windowDays === "lifetime" ? entries : entriesWithin(entries, windowDays, nowEpoch);
+    out.set(windowDays, aggregateChurn(within, knownPaths));
+  }
+  return out;
+}
+function setAdd(map, key, value) {
+  let set = map.get(key);
+  if (!set) {
+    set = /* @__PURE__ */ new Set();
+    map.set(key, set);
+  }
+  set.add(value);
+}
+
+// src/history/ownership.ts
+var DEFAULT_BUS_FACTOR_THRESHOLD = 0.5;
+function computeOwnership(entries, options = {}) {
+  const threshold = options.busFactorThreshold ?? DEFAULT_BUS_FACTOR_THRESHOLD;
+  const out = /* @__PURE__ */ new Map();
+  for (const [filePath, byAuthor] of authorLinesByPath(entries, options.knownPaths)) {
+    const summary = summarizeOwnership(byAuthor, threshold);
+    if (summary !== null) out.set(filePath, summary);
+  }
+  return out;
+}
+function authorLinesByPath(entries, known) {
+  const out = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    if (known && !known.has(e.filePath)) continue;
+    const lines = e.added + e.deleted;
+    if (lines === 0) continue;
+    let byAuthor = out.get(e.filePath);
+    if (!byAuthor) {
+      byAuthor = /* @__PURE__ */ new Map();
+      out.set(e.filePath, byAuthor);
+    }
+    byAuthor.set(e.author, (byAuthor.get(e.author) ?? 0) + lines);
+  }
+  return out;
+}
+function summarizeOwnership(byAuthor, threshold = DEFAULT_BUS_FACTOR_THRESHOLD) {
+  let total = 0;
+  for (const v of byAuthor.values()) total += v;
+  if (total === 0) return null;
+  const sorted = [...byAuthor.values()].sort((a, b) => b - a);
+  const topAuthorShare = sorted[0] / total;
+  const busFactor = minAuthorsToReach(sorted, total, threshold);
+  return { authors: sorted.length, topAuthorShare, busFactor };
+}
+function minAuthorsToReach(sortedDesc, total, threshold) {
+  let acc = 0;
+  for (let i = 0; i < sortedDesc.length; i++) {
+    acc += sortedDesc[i];
+    if (acc / total >= threshold) return i + 1;
+  }
+  return sortedDesc.length;
+}
+
+// src/history/change-coupling.ts
+var DEFAULT_MIN_COUNT = 2;
+var DEFAULT_MAX_COMMITS_PER_PAIR = 10;
+var DEFAULT_LARGE_COMMIT_THRESHOLD = 50;
+function computeChangeCoupling(entries, options = {}) {
+  const maxCommits = options.maxCommitsPerPair ?? DEFAULT_MAX_COMMITS_PER_PAIR;
+  const largeThreshold = options.largeCommitThreshold ?? DEFAULT_LARGE_COMMIT_THRESHOLD;
+  const pairs = /* @__PURE__ */ new Map();
+  let skippedLargeCommits = 0;
+  for (const [commit, files] of groupByCommit(entries, options.knownPaths)) {
+    if (files.length < 2) continue;
+    if (files.length > largeThreshold) {
+      skippedLargeCommits++;
+      continue;
+    }
+    accumulatePairs(commit, files, pairs, maxCommits);
+  }
+  return {
+    pairs: finalize(pairs, options.minCount ?? DEFAULT_MIN_COUNT),
+    skippedLargeCommits,
+    largeCommitThreshold: largeThreshold
+  };
+}
+function groupByCommit(entries, known) {
+  const out = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    if (known && !known.has(e.filePath)) continue;
+    let files = out.get(e.commit);
+    if (!files) {
+      files = [];
+      out.set(e.commit, files);
+    }
+    if (!files.includes(e.filePath)) files.push(e.filePath);
+  }
+  return out;
+}
+function accumulatePairs(commit, files, pairs, maxCommits) {
+  const sorted = [...files].sort();
+  for (let i = 0; i < sorted.length; i++) {
+    for (let j = i + 1; j < sorted.length; j++) {
+      const key = `${sorted[i]}	${sorted[j]}`;
+      let acc = pairs.get(key);
+      if (!acc) {
+        acc = { count: 0, commits: [] };
+        pairs.set(key, acc);
+      }
+      acc.count++;
+      if (acc.commits.length < maxCommits) acc.commits.push(commit);
+    }
+  }
+}
+function finalize(pairs, minCount) {
+  const out = [];
+  for (const [key, acc] of pairs) {
+    if (acc.count < minCount) continue;
+    const [a, b] = key.split("	");
+    out.push({ fileA: a, fileB: b, count: acc.count, commits: acc.commits });
+  }
+  return out.sort(comparePairs);
+}
+function comparePairs(a, b) {
+  if (b.count !== a.count) return b.count - a.count;
+  if (a.fileA !== b.fileA) return a.fileA < b.fileA ? -1 : 1;
+  return a.fileB < b.fileB ? -1 : a.fileB > b.fileB ? 1 : 0;
+}
+function couplingFor(pairs, seed) {
+  const out = [];
+  for (const p of pairs) {
+    if (p.fileA === seed) out.push({ partner: p.fileB, count: p.count, commits: p.commits });
+    else if (p.fileB === seed) out.push({ partner: p.fileA, count: p.count, commits: p.commits });
+  }
+  out.sort((a, b) => {
+    if (b.count !== a.count) return b.count - a.count;
+    return a.partner < b.partner ? -1 : a.partner > b.partner ? 1 : 0;
+  });
+  return out;
+}
+
+export {
+  runGit,
+  detectGitToplevel,
+  loadChurnEntries,
+  parseChurnLog,
+  resolveRenamedPath,
+  entriesWithin,
+  loadFileFirstSeen,
+  aggregateChurn,
+  aggregateChurnWindows,
+  computeOwnership,
+  authorLinesByPath,
+  summarizeOwnership,
+  computeChangeCoupling,
+  couplingFor
+};
+//# sourceMappingURL=chunk-PFI5XMUG.js.map