audit-tools 0.32.16 → 0.32.18

package/dist/audit/decompose/sources.js

@@ -0,0 +1,168 @@
+// Structure-layer source adapter (Phase B): turns the audit graph substrate into
+// the independently-sourced views the overlay-and-delta operator consumes. PURE —
+// the async extraction (comment/doc reads, git co-change) happens in the executor;
+// this module only shapes already-gathered signals into partitions.
+//
+// Behavior-exhibited sources (call/import, git co-change, data/state) each become
+// a WEIGHTED GRAPH clustered across the resolution ladder → a multi-resolution
+// partition family (feeds both agreed-across-source and stable-across-scale).
+// Intent-declared sources (directory depths, docs, comments) each become one or
+// more PARTITIONS over the same file universe (feed agreed-across-source only).
+import { resolutionSweep } from "audit-tools/shared";
+import { allGraphEdges } from "../extractors/graphSignals.js";
+import { GIT_CO_CHANGE_CATEGORY } from "../extractors/gitHistory.js";
+import { deriveDataStateCoupling, } from "../extractors/dataStateCoupling.js";
+function toPosix(path) {
+    return path.replace(/\\/g, "/");
+}
+/** Aggregate undirected edges over the universe into a WeightedGraph. */
+function weightedGraph(universe, edges) {
+    const inScope = new Set(universe);
+    const byPair = new Map();
+    for (const edge of edges) {
+        const a = toPosix(edge.a);
+        const b = toPosix(edge.b);
+        if (a === b || !inScope.has(a) || !inScope.has(b))
+            continue;
+        if (!(edge.weight > 0))
+            continue;
+        const lo = a.localeCompare(b) <= 0 ? a : b;
+        const hi = a.localeCompare(b) <= 0 ? b : a;
+        const key = `${lo} ${hi}`;
+        byPair.set(key, (byPair.get(key) ?? 0) + edge.weight);
+    }
+    const aggregated = [];
+    for (const [key, weight] of byPair) {
+        const idx = key.indexOf(" ");
+        aggregated.push({ a: key.slice(0, idx), b: key.slice(idx + 1), weight });
+    }
+    return { nodes: universe, edges: aggregated };
+}
+/** Directed graph edges → undirected coupling edges (weight = confidence or 1). */
+function edgesFromGraph(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const edge of raw) {
+        if (!edge ||
+            typeof edge.from !== "string" ||
+            typeof edge.to !== "string") {
+            continue;
+        }
+        const weight = typeof edge.confidence === "number" && edge.confidence > 0
+            ? edge.confidence
+            : 1;
+        out.push({ a: edge.from, b: edge.to, weight });
+    }
+    return out;
+}
+/** Build a single partition from disjoint member groups; ungrouped → singleton. */
+function partitionFromGroups(universe, groups) {
+    const partition = new Map();
+    for (const node of universe)
+        partition.set(node, node);
+    for (const group of groups) {
+        const rep = [...group].sort((a, b) => a.localeCompare(b))[0];
+        if (!rep)
+            continue;
+        for (const member of group) {
+            const m = toPosix(member);
+            if (partition.has(m))
+                partition.set(m, rep);
+        }
+    }
+    return partition;
+}
+/** Directory-prefix partition at a given depth (community = first `depth` segs). */
+function directoryPartition(universe, depth) {
+    const partition = new Map();
+    for (const node of universe) {
+        const segs = node.split("/");
+        // A file with fewer than depth+1 segments has no dir at this depth → itself.
+        const community = segs.length > depth ? segs.slice(0, depth).join("/") : node;
+        partition.set(node, community);
+    }
+    return partition;
+}
+const DEFAULT_DIRECTORY_DEPTHS = [1, 2, 3];
+/**
+ * Build the structure-layer decomposition sources. Behavior sources with no edges
+ * and intent sources with no non-trivial grouping are omitted so an empty source
+ * never dilutes the agreement mean.
+ */
+export function buildStructureSources(input) {
+    const universe = [...new Set(input.universe.map(toPosix))].sort((a, b) => a.localeCompare(b));
+    const sources = [];
+    // --- Behavior-exhibited sources ---
+    const callImport = weightedGraph(universe, allGraphEdges(input.graphBundle).map((e) => ({
+        a: e.from,
+        b: e.to,
+        weight: typeof e.confidence === "number" && e.confidence > 0 ? e.confidence : 1,
+    })));
+    if (callImport.edges.length > 0) {
+        sources.push({
+            id: "call_import",
+            family: "behavior",
+            partitions: resolutionSweep(callImport, input.resolutions),
+        });
+    }
+    const coChangeRaw = input.graphBundle.graphs[GIT_CO_CHANGE_CATEGORY];
+    const coChange = weightedGraph(universe, edgesFromGraph(coChangeRaw));
+    if (coChange.edges.length > 0) {
+        sources.push({
+            id: "co_change",
+            family: "behavior",
+            partitions: resolutionSweep(coChange, input.resolutions),
+        });
+    }
+    const dataState = weightedGraph(universe, deriveDataStateCoupling(input.graphBundle));
+    if (dataState.edges.length > 0) {
+        sources.push({
+            id: "data_state",
+            family: "behavior",
+            partitions: resolutionSweep(dataState, input.resolutions),
+        });
+    }
+    // --- Intent-declared sources ---
+    const depths = input.directoryDepths ?? DEFAULT_DIRECTORY_DEPTHS;
+    const directoryPartitions = depths.map((d) => directoryPartition(universe, d));
+    // Include the directory source only when at least one depth actually groups
+    // files (a flat repo with all files at the root yields only singletons).
+    const directoryGroups = directoryPartitions.some((p) => hasNonTrivialGroup(p));
+    if (directoryGroups) {
+        sources.push({
+            id: "directory",
+            family: "intent",
+            partitions: directoryPartitions,
+        });
+    }
+    if (input.docGroups.length > 0) {
+        sources.push({
+            id: "docs",
+            family: "intent",
+            partitions: [partitionFromGroups(universe, input.docGroups)],
+        });
+    }
+    const commentGraph = weightedGraph(universe, input.commentEdges);
+    if (commentGraph.edges.length > 0) {
+        // Comment cross-references are a coupling graph; cluster it at the ladder so a
+        // comment web forms boundaries the same way behavior graphs do.
+        sources.push({
+            id: "comments",
+            family: "intent",
+            partitions: resolutionSweep(commentGraph, input.resolutions),
+        });
+    }
+    return sources;
+}
+function hasNonTrivialGroup(partition) {
+    const counts = new Map();
+    for (const comm of partition.values()) {
+        counts.set(comm, (counts.get(comm) ?? 0) + 1);
+    }
+    for (const count of counts.values())
+        if (count >= 2)
+            return true;
+    return false;
+}
+//# sourceMappingURL=sources.js.map

package/dist/audit/decompose/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../../../src/audit/decompose/sources.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,kFAAkF;AAClF,mFAAmF;AACnF,oEAAoE;AACpE,EAAE;AACF,kFAAkF;AAClF,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,gFAAgF;AAOhF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACL,uBAAuB,GAExB,MAAM,oCAAoC,CAAC;AAE5C,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED,yEAAyE;AACzE,SAAS,aAAa,CACpB,QAAkB,EAClB,KAAqB;IAErB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QAC5D,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;YAAE,SAAS;QACjC,MAAM,EAAE,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3C,MAAM,EAAE,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,UAAU,GAAmB,EAAE,CAAC;IACtC,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAChD,CAAC;AAED,mFAAmF;AACnF,SAAS,cAAc,CACrB,GAAY;IAEZ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,IACE,CAAC,IAAI;YACL,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAC7B,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,EAC3B,CAAC;YACD,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GACV,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC;YACxD,CAAC,CAAC,IAAI,CAAC,UAAU;YACjB,CAAC,CAAC,CAAC,CAAC;QACR,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mFAAmF;AACnF,SAAS,mBAAmB,CAC1B,QAAkB,EAClB,MAAkB;IAElB,MAAM,SAAS,GAAc,IAAI,GAAG,EAAE,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,QAAQ;QAAE,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACvD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,KAAK,MAAM,MAAM,IAAI,KAAK,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC1B,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,oFAAoF;AACpF,SAAS,kBAAkB,CAAC,QAAkB,EAAE,KAAa;IAC3D,MAAM,SAAS,GAAc,IAAI,GAAG,EAAE,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7B,6EAA6E;QAC7E,MAAM,SAAS,GACb,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9D,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAeD,MAAM,wBAAwB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA4B;IAE5B,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACvE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CACnB,CAAC;IACF,MAAM,OAAO,GAA0B,EAAE,CAAC;IAE1C,qCAAqC;IACrC,MAAM,UAAU,GAAG,aAAa,CAC9B,QAAQ,EACR,aAAa,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC3C,CAAC,EAAE,CAAC,CAAC,IAAI;QACT,CAAC,EAAE,CAAC,CAAC,EAAE;QACP,MAAM,EAAE,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;KAChF,CAAC,CAAC,CACJ,CAAC;IACF,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC;YACX,EAAE,EAAE,aAAa;YACjB,MAAM,EAAE,UAAU;YAClB,UAAU,EAAE,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC;SAC3D,CAAC,CAAC;IACL,CAAC;IAED,MAAM,WAAW,GACf,KAAK,CAAC,WAAW,CAAC,MACnB,CAAC,sBAAsB,CAAC,CAAC;IAC1B,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC;IACtE,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC;YACX,EAAE,EAAE,WAAW;YACf,MAAM,EAAE,UAAU;YAClB,UAAU,EAAE,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC;SACzD,CAAC,CAAC;IACL,CAAC;IAED,MAAM,SAAS,GAAG,aAAa,CAC7B,QAAQ,EACR,uBAAuB,CAAC,KAAK,CAAC,WAAW,CAAC,CAC3C,CAAC;IACF,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC;YACX,EAAE,EAAE,YAAY;YAChB,MAAM,EAAE,UAAU;YAClB,UAAU,EAAE,eAAe,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC;SAC1D,CAAC,CAAC;IACL,CAAC;IAED,kCAAkC;IAClC,MAAM,MAAM,GAAG,KAAK,CAAC,eAAe,IAAI,wBAAwB,CAAC;IACjE,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/E,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,eAAe,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CACrD,kBAAkB,CAAC,CAAC,CAAC,CACtB,CAAC;IACF,IAAI,eAAe,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CAAC;YACX,EAAE,EAAE,WAAW;YACf,MAAM,EAAE,QAAQ;YAChB,UAAU,EAAE,mBAAmB;SAChC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC;YACX,EAAE,EAAE,MAAM;YACV,MAAM,EAAE,QAAQ;YAChB,UAAU,EAAE,CAAC,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED,MAAM,YAAY,GAAG,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IACjE,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,+EAA+E;QAC/E,gEAAgE;QAChE,OAAO,CAAC,IAAI,CAAC;YACX,EAAE,EAAE,UAAU;YACd,MAAM,EAAE,QAAQ;YAChB,UAAU,EAAE,eAAe,CAAC,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,kBAAkB,CAAC,SAAoB;IAC9C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,KAAK,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACjE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/audit/extractors/commentDecomposition.d.ts

@@ -0,0 +1,52 @@
+import type { CouplingEdge } from "./dataStateCoupling.js";
+/**
+ * Extract concatenated comment text from source, honoring the file's comment
+ * syntax and skipping string literals (single/double/backtick, backslash-escaped)
+ * so a comment marker inside a string is not misread. A single-pass char scanner:
+ * normal → string → line-comment → block-comment. Degrades gracefully (an
+ * unterminated block just consumes to EOF).
+ */
+export declare function extractCommentText(source: string, path: string): string;
+export interface CommentDecompositionResult {
+    /** Intent-declared coupling edges from comment cross-references (undirected). */
+    edges: CouplingEdge[];
+    /** Number of files whose source was read + scanned. */
+    scannedFiles: number;
+}
+export interface CommentDecompositionParams {
+    root: string;
+    /** In-scope repo-relative file paths. */
+    files: string[];
+    /**
+     * Injectable file reader (absolute path → text | undefined). Defaults to a
+     * size-capped node:fs read; tests supply a map-backed reader.
+     */
+    readFileText?: (absPath: string) => Promise<string | undefined>;
+    /** Skip files larger than this many bytes when reading (default 512 KiB). */
+    maxBytes?: number;
+}
+/**
+ * Derive intent-declared coupling edges from comment cross-references across the
+ * in-scope files. For each file, its comment text is scanned for the distinctive
+ * reference tokens of OTHER files; a match adds an undirected edge. Deterministic:
+ * files are processed in sorted order and edges are canonicalized + sorted.
+ */
+export declare function deriveCommentDecomposition(params: CommentDecompositionParams): Promise<CommentDecompositionResult>;
+export interface DocGroupsParams {
+    root: string;
+    /** Doc files (prose) to mine — README / ADRs / other markdown. */
+    docFiles: string[];
+    /** In-scope code files a doc may name (the grouping universe). */
+    codeFiles: string[];
+    readFileText?: (absPath: string) => Promise<string | undefined>;
+    maxBytes?: number;
+}
+/**
+ * Derive intent-declared groups from docs: each doc's ENTIRE text (docs are
+ * prose, not comment-embedded) is scanned for the reference tokens of in-scope
+ * code files; every code file a single doc names becomes one group (the doc
+ * declares a module). Returns disjoint member groups of size ≥ 2 (a doc naming
+ * one file declares no grouping), lexically sorted. Deterministic.
+ */
+export declare function deriveDocGroups(params: DocGroupsParams): Promise<string[][]>;
+//# sourceMappingURL=commentDecomposition.d.ts.map

package/dist/audit/extractors/commentDecomposition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commentDecomposition.d.ts","sourceRoot":"","sources":["../../../src/audit/extractors/commentDecomposition.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAiD3D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoEvE;AA8CD,MAAM,WAAW,0BAA0B;IACzC,iFAAiF;IACjF,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAChE,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAiBD;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,0BAA0B,CAAC,CA0DrC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kEAAkE;IAClE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CA0CrB"}

package/dist/audit/extractors/commentDecomposition.js

@@ -0,0 +1,298 @@
+// Comment-decomposition extractor (Phase B intent-declared source; design of
+// record spec/conceptual-design-review-design.md §"Structure decomposition
+// sources" rule 2: "Comments are their own delta — comments are stated intent
+// embedded in code").
+//
+// Comments are stated intent embedded in the code. This extractor mines the
+// INTENT-DECLARED structure they assert: where a file's comments explicitly
+// cross-reference another in-scope file (by path), the author is declaring the
+// two related. Those cross-references become an intent-declared coupling source
+// that the overlay-and-delta operator compares against the behavior graphs — a
+// comment that claims a boundary the code does not honor surfaces as a
+// non-co-localization finding downstream.
+//
+// The "stripped vs unstripped" pair the design calls for falls out structurally:
+// the STRIPPED view (code without comments) is exactly the existing call/import
+// coupling graph; the UNSTRIPPED intent is this comment source. Phase C layers the
+// LLM comments-stripped semantic-cohesion pass on top; Phase B stays deterministic.
+//
+// Comment lexing is keyed by file EXTENSION — comment syntax is per-language
+// lexical fact, not an environment coupling (the language-neutral invariant is
+// about the graph/planning contract, not pretending `.py` doesn't use `#`).
+// Unknown extensions fall back to the C-family `//` + `/* */` so a stray `#`
+// (e.g. a JS private field) is never misread as a comment.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+const C_FAMILY = { line: ["//"], block: [["/*", "*/"]] };
+const HASH_ONLY = { line: ["#"], block: [] };
+const PY = {
+    line: ["#"],
+    block: [
+        ['"""', '"""'],
+        ["'''", "'''"],
+    ],
+};
+const MARKUP = { line: [], block: [["<!--", "-->"]] };
+const CSS = { line: [], block: [["/*", "*/"]] };
+const SQL_LIKE = { line: ["--"], block: [["/*", "*/"]] };
+/** Extension (with dot, lowercased) → comment syntax. Unknown → C_FAMILY. */
+const SYNTAX_BY_EXT = {
+    ".js": C_FAMILY, ".jsx": C_FAMILY, ".ts": C_FAMILY, ".tsx": C_FAMILY,
+    ".mjs": C_FAMILY, ".cjs": C_FAMILY, ".mts": C_FAMILY, ".cts": C_FAMILY,
+    ".java": C_FAMILY, ".c": C_FAMILY, ".h": C_FAMILY, ".cpp": C_FAMILY,
+    ".hpp": C_FAMILY, ".cc": C_FAMILY, ".cs": C_FAMILY, ".go": C_FAMILY,
+    ".rs": C_FAMILY, ".swift": C_FAMILY, ".kt": C_FAMILY, ".scala": C_FAMILY,
+    ".php": C_FAMILY, ".dart": C_FAMILY,
+    ".py": PY, ".pyi": PY,
+    ".rb": HASH_ONLY, ".sh": HASH_ONLY, ".bash": HASH_ONLY, ".zsh": HASH_ONLY,
+    ".yaml": HASH_ONLY, ".yml": HASH_ONLY, ".toml": HASH_ONLY, ".r": HASH_ONLY,
+    ".pl": HASH_ONLY, ".conf": HASH_ONLY, ".ini": HASH_ONLY, ".cfg": HASH_ONLY,
+    ".sql": SQL_LIKE, ".lua": SQL_LIKE, ".hs": SQL_LIKE, ".elm": SQL_LIKE,
+    ".html": MARKUP, ".htm": MARKUP, ".xml": MARKUP, ".vue": MARKUP,
+    ".svelte": MARKUP, ".md": MARKUP, ".markdown": MARKUP,
+    ".css": CSS, ".scss": CSS, ".less": CSS,
+};
+function extensionOf(path) {
+    const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+    const dot = path.lastIndexOf(".");
+    if (dot <= slash)
+        return "";
+    return path.slice(dot).toLowerCase();
+}
+function syntaxFor(path) {
+    return SYNTAX_BY_EXT[extensionOf(path)] ?? C_FAMILY;
+}
+/**
+ * Extract concatenated comment text from source, honoring the file's comment
+ * syntax and skipping string literals (single/double/backtick, backslash-escaped)
+ * so a comment marker inside a string is not misread. A single-pass char scanner:
+ * normal → string → line-comment → block-comment. Degrades gracefully (an
+ * unterminated block just consumes to EOF).
+ */
+export function extractCommentText(source, path) {
+    const syntax = syntaxFor(path);
+    const out = [];
+    const n = source.length;
+    let i = 0;
+    const startsWith = (marker) => source.startsWith(marker, i);
+    while (i < n) {
+        const ch = source[i];
+        // String literals — skip so markers inside them don't count.
+        if (ch === '"' || ch === "'" || ch === "`") {
+            // Python triple-quote docstrings are handled as block comments below; only
+            // treat as a string here when it is NOT an opening triple quote for PY.
+            const triple = ch + ch + ch;
+            const isTriple = startsWith(triple);
+            const treatAsBlock = syntax.block.some(([open]) => open === triple);
+            if (!(isTriple && treatAsBlock)) {
+                i += 1;
+                while (i < n) {
+                    if (source[i] === "\\") {
+                        i += 2;
+                        continue;
+                    }
+                    if (source[i] === ch) {
+                        i += 1;
+                        break;
+                    }
+                    i += 1;
+                }
+                continue;
+            }
+        }
+        // Block comments (incl. Python triple-quote docstrings).
+        let matchedBlock = false;
+        for (const [open, close] of syntax.block) {
+            if (startsWith(open)) {
+                const end = source.indexOf(close, i + open.length);
+                const stop = end === -1 ? n : end;
+                out.push(source.slice(i + open.length, stop));
+                i = end === -1 ? n : end + close.length;
+                matchedBlock = true;
+                break;
+            }
+        }
+        if (matchedBlock)
+            continue;
+        // Line comments.
+        let matchedLine = false;
+        for (const marker of syntax.line) {
+            if (startsWith(marker)) {
+                const nl = source.indexOf("\n", i);
+                const stop = nl === -1 ? n : nl;
+                out.push(source.slice(i + marker.length, stop));
+                i = stop;
+                matchedLine = true;
+                break;
+            }
+        }
+        if (matchedLine)
+            continue;
+        i += 1;
+    }
+    return out.join("\n");
+}
+/** Normalize a repo path to forward slashes for matching. */
+function toPosix(path) {
+    return path.replace(/\\/g, "/");
+}
+const GENERIC_STEMS = new Set([
+    "index",
+    "types",
+    "type",
+    "utils",
+    "util",
+    "helpers",
+    "helper",
+    "constants",
+    "main",
+    "mod",
+]);
+/**
+ * Distinctive reference tokens for a file — the strings a comment would plausibly
+ * use to name it. Path-like tokens (≥ 2 segments) are always distinctive; a bare
+ * basename qualifies only when it is long enough and not a generic stem, so
+ * `index`/`types` never spuriously couple files.
+ */
+function referenceTokens(posixPath) {
+    const tokens = new Set();
+    const noExt = posixPath.replace(/\.[^./]+$/, "");
+    tokens.add(posixPath);
+    tokens.add(noExt);
+    const segs = posixPath.split("/");
+    if (segs.length >= 2) {
+        tokens.add(segs.slice(-2).join("/"));
+        const lastTwoNoExt = segs.slice(-2).join("/").replace(/\.[^./]+$/, "");
+        tokens.add(lastTwoNoExt);
+    }
+    const base = segs[segs.length - 1] ?? posixPath;
+    const stem = base.replace(/\.[^./]+$/, "");
+    if (stem.length >= 5 && !GENERIC_STEMS.has(stem.toLowerCase())) {
+        tokens.add(base); // basename WITH extension only, to stay distinctive
+    }
+    // Keep only tokens with a path separator or a kept distinctive basename.
+    return [...tokens].filter((t) => t.includes("/") || t === base);
+}
+const DEFAULT_MAX_BYTES = 512 * 1024;
+async function defaultReadFileText(absPath, maxBytes) {
+    try {
+        const buf = await readFile(absPath);
+        if (buf.byteLength > maxBytes)
+            return undefined;
+        return buf.toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Derive intent-declared coupling edges from comment cross-references across the
+ * in-scope files. For each file, its comment text is scanned for the distinctive
+ * reference tokens of OTHER files; a match adds an undirected edge. Deterministic:
+ * files are processed in sorted order and edges are canonicalized + sorted.
+ */
+export async function deriveCommentDecomposition(params) {
+    const maxBytes = params.maxBytes ?? DEFAULT_MAX_BYTES;
+    const read = params.readFileText ?? ((abs) => defaultReadFileText(abs, maxBytes));
+    const files = [...new Set(params.files.map(toPosix))].sort((a, b) => a.localeCompare(b));
+    // token → owning file (longest/most-specific token wins on collision is
+    // unnecessary; a token maps to exactly one file by construction of paths).
+    const tokenOwner = new Map();
+    for (const file of files) {
+        for (const token of referenceTokens(file)) {
+            // A token shared by two files (possible for a bare basename) is ambiguous —
+            // drop it rather than couple arbitrarily.
+            if (tokenOwner.has(token))
+                tokenOwner.set(token, "\0ambiguous");
+            else
+                tokenOwner.set(token, file);
+        }
+    }
+    for (const [token, owner] of [...tokenOwner]) {
+        if (owner === "\0ambiguous")
+            tokenOwner.delete(token);
+    }
+    // Sort tokens longest-first so a specific path matches before a substring.
+    const tokens = [...tokenOwner.keys()].sort((a, b) => b.length - a.length || a.localeCompare(b));
+    const weightByPair = new Map();
+    let scannedFiles = 0;
+    for (const file of files) {
+        const text = await read(join(params.root, file));
+        if (text === undefined)
+            continue;
+        scannedFiles += 1;
+        const comments = extractCommentText(text, file);
+        if (comments.length === 0)
+            continue;
+        const posixComments = toPosix(comments);
+        const referenced = new Set();
+        for (const token of tokens) {
+            const owner = tokenOwner.get(token);
+            if (owner === file || referenced.has(owner))
+                continue;
+            if (posixComments.includes(token))
+                referenced.add(owner);
+        }
+        for (const other of referenced) {
+            const a = file.localeCompare(other) <= 0 ? file : other;
+            const b = file.localeCompare(other) <= 0 ? other : file;
+            const key = `${a} ${b}`;
+            weightByPair.set(key, (weightByPair.get(key) ?? 0) + 1);
+        }
+    }
+    const edges = [];
+    for (const [key, weight] of weightByPair) {
+        const idx = key.indexOf(" ");
+        edges.push({ a: key.slice(0, idx), b: key.slice(idx + 1), weight });
+    }
+    edges.sort((x, y) => x.a.localeCompare(y.a) || x.b.localeCompare(y.b));
+    return { edges, scannedFiles };
+}
+/**
+ * Derive intent-declared groups from docs: each doc's ENTIRE text (docs are
+ * prose, not comment-embedded) is scanned for the reference tokens of in-scope
+ * code files; every code file a single doc names becomes one group (the doc
+ * declares a module). Returns disjoint member groups of size ≥ 2 (a doc naming
+ * one file declares no grouping), lexically sorted. Deterministic.
+ */
+export async function deriveDocGroups(params) {
+    const maxBytes = params.maxBytes ?? DEFAULT_MAX_BYTES;
+    const read = params.readFileText ?? ((abs) => defaultReadFileText(abs, maxBytes));
+    const codeFiles = [...new Set(params.codeFiles.map(toPosix))].sort((a, b) => a.localeCompare(b));
+    const docFiles = [...new Set(params.docFiles.map(toPosix))].sort((a, b) => a.localeCompare(b));
+    const tokenOwner = new Map();
+    for (const file of codeFiles) {
+        for (const token of referenceTokens(file)) {
+            if (tokenOwner.has(token))
+                tokenOwner.set(token, "\0ambiguous");
+            else
+                tokenOwner.set(token, file);
+        }
+    }
+    for (const [token, owner] of [...tokenOwner]) {
+        if (owner === "\0ambiguous")
+            tokenOwner.delete(token);
+    }
+    const tokens = [...tokenOwner.keys()].sort((a, b) => b.length - a.length || a.localeCompare(b));
+    const groups = [];
+    for (const doc of docFiles) {
+        const text = await read(join(params.root, doc));
+        if (text === undefined)
+            continue;
+        const posixText = toPosix(text);
+        const named = new Set();
+        for (const token of tokens) {
+            const owner = tokenOwner.get(token);
+            if (named.has(owner))
+                continue;
+            if (posixText.includes(token))
+                named.add(owner);
+        }
+        if (named.size >= 2) {
+            groups.push([...named].sort((a, b) => a.localeCompare(b)));
+        }
+    }
+    groups.sort((a, b) => (a[0] ?? "").localeCompare(b[0] ?? ""));
+    return groups;
+}
+//# sourceMappingURL=commentDecomposition.js.map

package/dist/audit/extractors/commentDecomposition.js.map

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

package/dist/audit/extractors/dataStateCoupling.d.ts

@@ -0,0 +1,26 @@
+import type { GraphBundle } from "audit-tools/shared";
+/** An undirected weighted coupling edge (canonical `a < b`). */
+export interface CouplingEdge {
+    a: string;
+    b: string;
+    weight: number;
+}
+export interface DataStateCouplingOptions {
+    /**
+     * A target is "generic" (dropped) once its referrer count exceeds
+     * max(genericAbsolute, genericFraction × universe). Ubiquitous targets carry no
+     * grouping signal and would otherwise couple everything.
+     */
+    genericFraction?: number;
+    genericAbsolute?: number;
+    /** Minimum shared-target count for an edge to be emitted. */
+    minSharedTargets?: number;
+}
+/**
+ * Derive data/state coupling edges from a graph bundle's structural edges. Two
+ * source files sharing K non-generic targets get one undirected edge of weight K.
+ * Deterministic: edges are canonicalized (`a < b`) and sorted by (a, b). Degrades
+ * to `[]` for an edgeless / malformed bundle (never throws).
+ */
+export declare function deriveDataStateCoupling(graphBundle: GraphBundle, options?: DataStateCouplingOptions): CouplingEdge[];
+//# sourceMappingURL=dataStateCoupling.d.ts.map

package/dist/audit/extractors/dataStateCoupling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataStateCoupling.d.ts","sourceRoot":"","sources":["../../../src/audit/extractors/dataStateCoupling.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,WAAW,EACxB,OAAO,GAAE,wBAA6B,GACrC,YAAY,EAAE,CAgDhB"}

package/dist/audit/extractors/dataStateCoupling.js

@@ -0,0 +1,71 @@
+// Data/state coupling extractor (Phase B behavior-exhibited source; design of
+// record spec/conceptual-design-review-design.md §"Structure decomposition
+// sources"): "code touching the same artifact/state even with no direct call."
+//
+// Realized deterministically + language-neutrally as BIBLIOGRAPHIC COUPLING: two
+// files that reference the SAME targets are coupled through that shared state,
+// even when neither calls the other. This is distinct from the direct
+// call/import source (which is the edges themselves) — here the signal is shared
+// OUT-neighbors, computed purely from the existing structural edge set (no file
+// reads, no new IO).
+//
+// A target referenced by nearly everything (a ubiquitous util / logger) carries
+// no grouping signal — like a stop-word — so targets whose in-degree exceeds a
+// genericness cap are dropped before pairing. This also bounds the cost: a hub
+// with N referrers would otherwise contribute O(N²) pairs.
+import { allGraphEdges } from "./graphSignals.js";
+const DEFAULT_GENERIC_FRACTION = 0.25;
+const DEFAULT_GENERIC_ABSOLUTE = 12;
+const DEFAULT_MIN_SHARED_TARGETS = 2;
+/**
+ * Derive data/state coupling edges from a graph bundle's structural edges. Two
+ * source files sharing K non-generic targets get one undirected edge of weight K.
+ * Deterministic: edges are canonicalized (`a < b`) and sorted by (a, b). Degrades
+ * to `[]` for an edgeless / malformed bundle (never throws).
+ */
+export function deriveDataStateCoupling(graphBundle, options = {}) {
+    const genericFraction = options.genericFraction ?? DEFAULT_GENERIC_FRACTION;
+    const genericAbsolute = options.genericAbsolute ?? DEFAULT_GENERIC_ABSOLUTE;
+    const minSharedTargets = options.minSharedTargets ?? DEFAULT_MIN_SHARED_TARGETS;
+    const edges = allGraphEdges(graphBundle);
+    if (edges.length === 0)
+        return [];
+    // target → set of source files that reference it (self-references dropped).
+    const referrersByTarget = new Map();
+    const sources = new Set();
+    for (const edge of edges) {
+        if (edge.from === edge.to)
+            continue;
+        sources.add(edge.from);
+        let referrers = referrersByTarget.get(edge.to);
+        if (!referrers) {
+            referrers = new Set();
+            referrersByTarget.set(edge.to, referrers);
+        }
+        referrers.add(edge.from);
+    }
+    const genericThreshold = Math.max(genericAbsolute, Math.ceil(sources.size * genericFraction));
+    // Accumulate shared-target counts per source pair, over non-generic targets.
+    const sharedByPair = new Map();
+    for (const referrers of referrersByTarget.values()) {
+        if (referrers.size < 2 || referrers.size > genericThreshold)
+            continue;
+        const members = [...referrers].sort((a, b) => a.localeCompare(b));
+        for (let i = 0; i < members.length; i++) {
+            for (let j = i + 1; j < members.length; j++) {
+                const key = `${members[i]} ${members[j]}`;
+                sharedByPair.set(key, (sharedByPair.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const result = [];
+    for (const [key, weight] of sharedByPair) {
+        if (weight < minSharedTargets)
+            continue;
+        const idx = key.indexOf(" ");
+        result.push({ a: key.slice(0, idx), b: key.slice(idx + 1), weight });
+    }
+    result.sort((x, y) => x.a.localeCompare(y.a) || x.b.localeCompare(y.b));
+    return result;
+}
+//# sourceMappingURL=dataStateCoupling.js.map