@opencodehub/ingestion 0.1.0

package/dist/pipeline/phases/accesses.js

@@ -0,0 +1,194 @@
+/**
+ * Accesses phase — emits ACCESSES edges from Function/Method/Constructor
+ * nodes to Property nodes, tagged `read` or `write`.
+ *
+ * Scope (v2): providers that opt in (TS, TSX, JS, Python) supply an
+ * {@link LanguageProvider.extractPropertyAccesses} hook; everyone else is a
+ * silent no-op. The hook receives per-file `definitions`, `captures`,
+ * `sourceText`, and `filePath` (mirroring the parse-phase hand-off) and
+ * returns {@link PropertyAccess} records keyed by the enclosing symbol's
+ * `NodeId`.
+ *
+ * Resolution: property names are FLAT. For every access we look up a matching
+ * `Property` node in order:
+ *   1. Same-file property with identical `name`. Matches by name only; a
+ *      future pass will tighten to (owner, name) pairs once TS classes
+ *      reliably surface field members.
+ *   2. Any other `Property` node with the same name (deterministically the
+ *      one with the smallest NodeId).
+ *   3. If neither hits, we synthesise a `Property:unresolved:<name>` stub
+ *      node. The stub serves as a stable anchor so a later re-run that
+ *      introduces the real field produces a CLEAN graph-hash delta instead
+ *      of orphaned accesses being silently dropped.
+ *
+ * Determinism:
+ *   - Files are iterated in sorted order.
+ *   - Providers sort their accesses before returning.
+ *   - The phase re-sorts by (fromId, toId, startLine) before calling
+ *     `graph.addEdge` so the final emit order is independent of provider
+ *     output order.
+ *   - A 50,000 edges-per-file cap guards against pathological generated
+ *     files; overage is dropped with a `warn` event.
+ */
+import { makeNodeId } from "@opencodehub/core-types";
+import { getProvider } from "../../providers/registry.js";
+import { CROSS_FILE_PHASE_NAME } from "./cross-file.js";
+import { PARSE_PHASE_NAME } from "./parse.js";
+export const ACCESSES_PHASE_NAME = "accesses";
+/** Cap on ACCESSES edges emitted per file; protects against generated code. */
+const MAX_ACCESSES_PER_FILE = 50_000;
+export const accessesPhase = {
+    name: ACCESSES_PHASE_NAME,
+    deps: [PARSE_PHASE_NAME, CROSS_FILE_PHASE_NAME],
+    async run(ctx, deps) {
+        const parse = deps.get(PARSE_PHASE_NAME);
+        if (parse === undefined) {
+            throw new Error("accesses: parse output missing from dependency map");
+        }
+        return runAccesses(ctx, parse);
+    },
+};
+function runAccesses(ctx, parse) {
+    // ---- Build a global Property index by bare name. ----------------------
+    // Per-file pre-filter + global fallback pools. Both are deterministic:
+    // NodeIds are sorted before being inserted into each bucket.
+    const propByFileAndName = new Map();
+    const propByName = new Map();
+    for (const n of ctx.graph.nodes()) {
+        if (n.kind !== "Property")
+            continue;
+        const bucket = propByName.get(n.name) ?? [];
+        bucket.push(n.id);
+        propByName.set(n.name, bucket);
+        let perFile = propByFileAndName.get(n.filePath ?? "");
+        if (perFile === undefined) {
+            perFile = new Map();
+            propByFileAndName.set(n.filePath ?? "", perFile);
+        }
+        // Most-recent-wins is fine: if two properties share a file+name the
+        // graph is already inconsistent, and the walker only observes one.
+        perFile.set(n.name, n.id);
+    }
+    for (const [name, list] of propByName) {
+        propByName.set(name, [...list].sort());
+    }
+    // ---- Per-file provider dispatch + edge emission. ----------------------
+    let edgeCount = 0;
+    let unresolvedCount = 0;
+    const truncatedFiles = [];
+    const syntheticIds = new Set();
+    const files = [...parse.definitionsByFile.keys()].sort();
+    for (const filePath of files) {
+        const language = languageForFile(filePath, parse);
+        if (language === undefined)
+            continue;
+        const provider = getProvider(language);
+        if (provider.extractPropertyAccesses === undefined)
+            continue;
+        const defs = parse.definitionsByFile.get(filePath) ?? [];
+        const sourceText = parse.sourceByFile.get(filePath);
+        if (sourceText === undefined || sourceText === "")
+            continue;
+        // `captures` is reserved for a future AST-driven path; the walker
+        // only consumes `definitions` + `sourceText` today.
+        const accesses = provider.extractPropertyAccesses({
+            filePath,
+            definitions: defs,
+            captures: [],
+            sourceText,
+        });
+        // Cap enforcement — emit a warning once and drop the tail. The
+        // providers already sort by (enclosingSymbolId, propertyName,
+        // startLine), so truncation is stable across runs.
+        let usableAccesses = accesses;
+        if (accesses.length > MAX_ACCESSES_PER_FILE) {
+            truncatedFiles.push(filePath);
+            usableAccesses = accesses.slice(0, MAX_ACCESSES_PER_FILE);
+            ctx.onProgress?.({
+                phase: ACCESSES_PHASE_NAME,
+                kind: "warn",
+                message: `accesses: ${filePath} produced ${accesses.length} accesses; capped at ${MAX_ACCESSES_PER_FILE}`,
+            });
+        }
+        const edges = [];
+        const perFile = propByFileAndName.get(filePath);
+        for (const acc of usableAccesses) {
+            let target = perFile?.get(acc.propertyName);
+            if (target === undefined) {
+                const global = propByName.get(acc.propertyName);
+                if (global !== undefined && global.length > 0)
+                    target = global[0];
+            }
+            if (target === undefined) {
+                // Synthesise the stub on first use so the graph stays minimal.
+                const stubId = makeNodeId("Property", "<unresolved>", acc.propertyName);
+                if (!syntheticIds.has(stubId)) {
+                    syntheticIds.add(stubId);
+                    unresolvedCount += 1;
+                    const node = {
+                        id: stubId,
+                        kind: "Property",
+                        name: acc.propertyName,
+                        filePath: "<unresolved>",
+                        startLine: 0,
+                        endLine: 0,
+                    };
+                    ctx.graph.addNode(node);
+                }
+                target = stubId;
+            }
+            edges.push({
+                from: acc.enclosingSymbolId,
+                to: target,
+                reason: acc.reason,
+                startLine: acc.startLine,
+            });
+        }
+        // Re-sort for emit determinism: (fromId, toId, startLine, reason).
+        edges.sort((a, b) => {
+            if (a.from !== b.from)
+                return a.from < b.from ? -1 : 1;
+            if (a.to !== b.to)
+                return a.to < b.to ? -1 : 1;
+            if (a.startLine !== b.startLine)
+                return a.startLine - b.startLine;
+            return a.reason < b.reason ? -1 : 1;
+        });
+        for (const e of edges) {
+            ctx.graph.addEdge({
+                from: e.from,
+                to: e.to,
+                type: "ACCESSES",
+                confidence: 0.8,
+                reason: e.reason,
+            });
+            edgeCount += 1;
+        }
+    }
+    return { edgeCount, truncatedFiles, unresolvedCount };
+}
+function languageForFile(filePath, _parse) {
+    const idx = filePath.lastIndexOf(".");
+    if (idx < 0)
+        return undefined;
+    const ext = filePath.slice(idx).toLowerCase();
+    switch (ext) {
+        case ".ts":
+        case ".mts":
+        case ".cts":
+            return "typescript";
+        case ".tsx":
+            return "tsx";
+        case ".js":
+        case ".mjs":
+        case ".cjs":
+        case ".jsx":
+            return "javascript";
+        case ".py":
+        case ".pyi":
+            return "python";
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=accesses.js.map

package/dist/pipeline/phases/accesses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accesses.js","sourceRoot":"","sources":["../../../src/pipeline/phases/accesses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAoB,MAAM,YAAY,CAAC;AAEhE,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAE9C,+EAA+E;AAC/E,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAWrC,MAAM,CAAC,MAAM,aAAa,GAAkC;IAC1D,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,CAAC,gBAAgB,EAAE,qBAAqB,CAAC;IAC/C,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAA4B,CAAC;QACpE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;CACF,CAAC;AAEF,SAAS,WAAW,CAAC,GAAoB,EAAE,KAAkB;IAC3D,0EAA0E;IAC1E,uEAAuE;IACvE,6DAA6D;IAC7D,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA+B,CAAC;IACjE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC/C,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU;YAAE,SAAS;QACpC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/B,IAAI,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;QACtD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;YACpC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;QACnD,CAAC;QACD,oEAAoE;QACpE,mEAAmE;QACnE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,UAAU,EAAE,CAAC;QACtC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,0EAA0E;IAC1E,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IAEvC,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAClD,IAAI,QAAQ,KAAK,SAAS;YAAE,SAAS;QACrC,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,QAAQ,CAAC,uBAAuB,KAAK,SAAS;YAAE,SAAS;QAE7D,MAAM,IAAI,GAAG,KAAK,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACzD,MAAM,UAAU,GAAG,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACpD,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,EAAE;YAAE,SAAS;QAC5D,kEAAkE;QAClE,oDAAoD;QACpD,MAAM,QAAQ,GAAG,QAAQ,CAAC,uBAAuB,CAAC;YAChD,QAAQ;YACR,WAAW,EAAE,IAAI;YACjB,QAAQ,EAAE,EAAE;YACZ,UAAU;SACX,CAAC,CAAC;QAEH,+DAA+D;QAC/D,8DAA8D;QAC9D,mDAAmD;QACnD,IAAI,cAAc,GAAyC,QAAQ,CAAC;QACpE,IAAI,QAAQ,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;YAC5C,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC9B,cAAc,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;YAC1D,GAAG,CAAC,UAAU,EAAE,CAAC;gBACf,KAAK,EAAE,mBAAmB;gBAC1B,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,aAAa,QAAQ,aAAa,QAAQ,CAAC,MAAM,wBAAwB,qBAAqB,EAAE;aAC1G,CAAC,CAAC;QACL,CAAC;QAUD,MAAM,KAAK,GAAe,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAChD,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;YACjC,IAAI,MAAM,GAAuB,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAChE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;gBAChD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;oBAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YACpE,CAAC;YACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,+DAA+D;gBAC/D,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;gBACxE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC9B,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBACzB,eAAe,IAAI,CAAC,CAAC;oBACrB,MAAM,IAAI,GAAc;wBACtB,EAAE,EAAE,MAAM;wBACV,IAAI,EAAE,UAAU;wBAChB,IAAI,EAAE,GAAG,CAAC,YAAY;wBACtB,QAAQ,EAAE,cAAc;wBACxB,SAAS,EAAE,CAAC;wBACZ,OAAO,EAAE,CAAC;qBACX,CAAC;oBACF,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC1B,CAAC;gBACD,MAAM,GAAG,MAAM,CAAC;YAClB,CAAC;YACD,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,GAAG,CAAC,iBAA2B;gBACrC,EAAE,EAAE,MAAM;gBACV,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,SAAS,EAAE,GAAG,CAAC,SAAS;aACzB,CAAC,CAAC;QACL,CAAC;QAED,mEAAmE;QACnE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAClB,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;gBAAE,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACvD,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE;gBAAE,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC/C,IAAI,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS;gBAAE,OAAO,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;YAClE,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QAEH,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC;gBAChB,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,IAAI,EAAE,UAAU;gBAChB,UAAU,EAAE,GAAG;gBACf,MAAM,EAAE,CAAC,CAAC,MAAM;aACjB,CAAC,CAAC;YACH,SAAS,IAAI,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AACxD,CAAC;AAED,SAAS,eAAe,CACtB,QAAgB,EAChB,MAAmB;IAEnB,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9C,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,KAAK,CAAC;QACX,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,YAAY,CAAC;QACtB,KAAK,MAAM;YACT,OAAO,KAAK,CAAC;QACf,KAAK,KAAK,CAAC;QACX,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,YAAY,CAAC;QACtB,KAAK,KAAK,CAAC;QACX,KAAK,MAAM;YACT,OAAO,QAAQ,CAAC;QAClB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/pipeline/phases/annotate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Annotate phase — terminal step that computes final graph statistics for
+ * the orchestrator. Does not touch storage; the CLI is responsible for
+ * persisting the resulting envelope.
+ *
+ * Outputs:
+ *   - `schemaVersion` (pinned by `@opencodehub/core-types`)
+ *   - `currentCommit` (captured by scan when not `skipGit`)
+ *   - counts per NodeKind + RelationType
+ *
+ * No staleness decision is made here because the previous-run metadata is
+ * owned by the storage package and threaded through at the CLI layer.
+ */
+import type { PipelinePhase } from "../types.js";
+export declare const ANNOTATE_PHASE_NAME = "annotate";
+export interface AnnotateStats {
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+    readonly byKind: Record<string, number>;
+    readonly byRelation: Record<string, number>;
+}
+export interface AnnotateOutput {
+    readonly schemaVersion: string;
+    readonly currentCommit?: string;
+    readonly stats: AnnotateStats;
+}
+export declare const annotatePhase: PipelinePhase<AnnotateOutput>;
+//# sourceMappingURL=annotate.d.ts.map

package/dist/pipeline/phases/annotate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotate.d.ts","sourceRoot":"","sources":["../../../src/pipeline/phases/annotate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAMlE,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B;AAED,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,cAAc,CAMvD,CAAC"}

package/dist/pipeline/phases/annotate.js

@@ -0,0 +1,60 @@
+/**
+ * Annotate phase — terminal step that computes final graph statistics for
+ * the orchestrator. Does not touch storage; the CLI is responsible for
+ * persisting the resulting envelope.
+ *
+ * Outputs:
+ *   - `schemaVersion` (pinned by `@opencodehub/core-types`)
+ *   - `currentCommit` (captured by scan when not `skipGit`)
+ *   - counts per NodeKind + RelationType
+ *
+ * No staleness decision is made here because the previous-run metadata is
+ * owned by the storage package and threaded through at the CLI layer.
+ */
+import { SCHEMA_VERSION } from "@opencodehub/core-types";
+import { COCHANGE_PHASE_NAME } from "./cochange.js";
+import { PROCESSES_PHASE_NAME } from "./processes.js";
+import { SCAN_PHASE_NAME } from "./scan.js";
+import { TEMPORAL_PHASE_NAME } from "./temporal.js";
+export const ANNOTATE_PHASE_NAME = "annotate";
+export const annotatePhase = {
+    name: ANNOTATE_PHASE_NAME,
+    deps: [PROCESSES_PHASE_NAME, TEMPORAL_PHASE_NAME, COCHANGE_PHASE_NAME],
+    async run(ctx) {
+        return runAnnotate(ctx);
+    },
+};
+function runAnnotate(ctx) {
+    const scan = ctx.phaseOutputs.get(SCAN_PHASE_NAME);
+    const byKind = {};
+    for (const n of ctx.graph.nodes()) {
+        byKind[n.kind] = (byKind[n.kind] ?? 0) + 1;
+    }
+    const byRelation = {};
+    for (const e of ctx.graph.edges()) {
+        byRelation[e.type] = (byRelation[e.type] ?? 0) + 1;
+    }
+    // Canonicalise key order for byte-identical JSON serialisation if the
+    // caller persists the output.
+    const byKindSorted = sortRecord(byKind);
+    const byRelationSorted = sortRecord(byRelation);
+    const stats = {
+        nodeCount: ctx.graph.nodeCount(),
+        edgeCount: ctx.graph.edgeCount(),
+        byKind: byKindSorted,
+        byRelation: byRelationSorted,
+    };
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ...(scan?.gitHead !== undefined ? { currentCommit: scan.gitHead } : {}),
+        stats,
+    };
+}
+function sortRecord(rec) {
+    const out = {};
+    for (const key of Object.keys(rec).sort()) {
+        out[key] = rec[key] ?? 0;
+    }
+    return out;
+}
+//# sourceMappingURL=annotate.js.map

package/dist/pipeline/phases/annotate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotate.js","sourceRoot":"","sources":["../../../src/pipeline/phases/annotate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAmB,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAe9C,MAAM,CAAC,MAAM,aAAa,GAAkC;IAC1D,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,CAAC,oBAAoB,EAAE,mBAAmB,EAAE,mBAAmB,CAAC;IACtE,KAAK,CAAC,GAAG,CAAC,GAAG;QACX,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;CACF,CAAC;AAEF,SAAS,WAAW,CAAC,GAAoB;IACvC,MAAM,IAAI,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,eAAe,CAA2B,CAAC;IAE7E,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,UAAU,GAA2B,EAAE,CAAC;IAC9C,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAClC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACrD,CAAC;IACD,sEAAsE;IACtE,8BAA8B;IAC9B,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,gBAAgB,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAEhD,MAAM,KAAK,GAAkB;QAC3B,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE;QAChC,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE;QAChC,MAAM,EAAE,YAAY;QACpB,UAAU,EAAE,gBAAgB;KAC7B,CAAC;IAEF,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,KAAK;KACN,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,GAA2B;IAC7C,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1C,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/pipeline/phases/cochange.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Cochange phase — emit file×file association-rule rows into the dedicated
+ * `cochanges` storage table.
+ *
+ * Co-change is fundamentally different from the deterministic edges that live
+ * in `relations`:
+ *   - statistical, not deterministic (no binary truth, no oracle confirms it);
+ *   - file-level, not symbol-level (stretching it to symbols inflated graph
+ *     cardinality by ~5x on real repos);
+ *   - rewrites on every commit, even docs-only commits, so it's a poor fit
+ *     for the graph-hash input.
+ *
+ * The phase consumes `TemporalOutput.commitFileLists`, computes per-file and
+ * per-pair co-commit counts, and emits one row per ordered `(source_file,
+ * target_file)` pair (with `source_file < target_file`) carrying the standard
+ * association-rule `lift` metric. Rows are returned on the phase output; the
+ * CLI persists them to DuckDB after bulkLoad — the phase NEVER touches
+ * `ctx.graph`.
+ */
+import type { CochangeRow } from "@opencodehub/storage";
+import type { PipelinePhase } from "../types.js";
+export declare const COCHANGE_PHASE_NAME: "cochange";
+/**
+ * Commits that touch more than this many files are treated as
+ * mass-rename / mechanical refactors and skipped for co-change emission.
+ * The cap is a heuristic — 50 balances catching real cross-file features
+ * against dropping sweeping rename commits. Exposed so tests can drive
+ * the boundary precisely.
+ */
+export declare const DEFAULT_MAX_FILES_PER_COMMIT = 50;
+export interface CochangeOptions {
+    /** Override the mass-rename threshold. Defaults to {@link DEFAULT_MAX_FILES_PER_COMMIT}. */
+    readonly cochangeMaxFilesPerCommit?: number;
+}
+export interface CochangeOutput {
+    readonly rows: readonly CochangeRow[];
+    readonly rowsEmitted: number;
+    readonly commitsSkipped: number;
+    readonly totalCommits: number;
+}
+export declare const cochangePhase: PipelinePhase<CochangeOutput>;
+//# sourceMappingURL=cochange.d.ts.map

package/dist/pipeline/phases/cochange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cochange.d.ts","sourceRoot":"","sources":["../../../src/pipeline/phases/cochange.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,eAAO,MAAM,mBAAmB,EAAG,UAAmB,CAAC;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAE/C,MAAM,WAAW,eAAe;IAC9B,4FAA4F;IAC5F,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,cAAc,CAoGvD,CAAC"}

package/dist/pipeline/phases/cochange.js.map

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

package/dist/pipeline/phases/communities.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Communities phase — cluster callable symbols with the Leiden algorithm.
+ *
+ * We build an undirected, weighted graph whose nodes are every `Function`,
+ * `Method`, `Class`, `Interface`, `Struct`, and `Trait` in the workspace.
+ * Edge weights:
+ *   - `CALLS`        → 1.0 (strongest intra-feature signal)
+ *   - `HAS_METHOD`   → 0.5 (co-location by ownership)
+ *
+ * Files, folders, routes, tools, modules, communities, and processes are
+ * intentionally excluded so the clustering reflects *behavioural* coupling
+ * rather than filesystem neighbourhoods.
+ *
+ * The Leiden call is parameterised with a fixed `randomSeed` so two runs on
+ * the same input graph produce identical community assignments. If the
+ * external Leiden integration produces zero communities (e.g. the graph was
+ * trivially empty or the library's shape changed), we fall back to a
+ * deterministic connected-components labeler and emit a warning.
+ *
+ * Community names are synthesised from the top-3 most-frequent identifier
+ * tokens across the community's members (splitting on camelCase, snake_case,
+ * and dots; filtering against a small English stop-word list). A fallback of
+ * `community-<id>` is used when no tokens survive.
+ */
+import type { PipelinePhase } from "../types.js";
+export declare const COMMUNITIES_PHASE_NAME = "communities";
+export interface CommunitiesOutput {
+    readonly communityCount: number;
+    readonly memberCount: number;
+    readonly unclusteredCount: number;
+    readonly usedFallback: boolean;
+}
+export declare const communitiesPhase: PipelinePhase<CommunitiesOutput>;
+//# sourceMappingURL=communities.d.ts.map

package/dist/pipeline/phases/communities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"communities.d.ts","sourceRoot":"","sources":["../../../src/pipeline/phases/communities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAMlE,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAiBD,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAAC,iBAAiB,CAM7D,CAAC"}