audit-tools 0.32.17 → 0.32.18

package/dist/audit/decompose/buildStructureDecomposition.d.ts

@@ -0,0 +1,14 @@
+import type { FileDisposition, GraphBundle } from "audit-tools/shared";
+import type { RepoManifest } from "../types.js";
+import type { StructureDecomposition } from "../types/structureDecomposition.js";
+export interface BuildStructureDecompositionParams {
+    /** Repo root (absolute); when absent, comment/doc extraction is skipped. */
+    root?: string;
+    repoManifest: RepoManifest;
+    disposition: FileDisposition;
+    graphBundle: GraphBundle;
+    /** Injectable file reader (tests supply a map-backed reader). */
+    readFileText?: (absPath: string) => Promise<string | undefined>;
+}
+export declare function buildStructureDecomposition(params: BuildStructureDecompositionParams): Promise<StructureDecomposition>;
+//# sourceMappingURL=buildStructureDecomposition.d.ts.map

package/dist/audit/decompose/buildStructureDecomposition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildStructureDecomposition.d.ts","sourceRoot":"","sources":["../../../src/audit/decompose/buildStructureDecomposition.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EAEZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAgBjF,MAAM,WAAW,iCAAiC;IAChD,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,EAAE,eAAe,CAAC;IAC7B,WAAW,EAAE,WAAW,CAAC;IACzB,iEAAiE;IACjE,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACjE;AAmBD,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,iCAAiC,GACxC,OAAO,CAAC,sBAAsB,CAAC,CA+EjC"}

package/dist/audit/decompose/buildStructureDecomposition.js

@@ -0,0 +1,107 @@
+// Top-level Phase B orchestration: gather the structure-layer sources (behavior
+// graphs + the two new intent extractors), run the overlay-and-delta operator,
+// emit the non-co-localization findings, and assemble the
+// structure_decomposition.json artifact. The single async entry point the
+// executor calls; the pure pieces it composes are individually tested.
+import { clustersFromPartitions, decompose } from "audit-tools/shared";
+import { deriveCommentDecomposition, deriveDocGroups, } from "../extractors/commentDecomposition.js";
+import { buildStructureSources } from "./sources.js";
+import { detectNonColocalization } from "./findings.js";
+const DOC_EXTENSION = /\.(md|markdown|adoc|rst|txt)$/i;
+/** Threshold at which an intent source's partitions collapse into boundary groups. */
+const INTENT_BOUNDARY_FRACTION = 0.5;
+function toPosix(path) {
+    return path.replace(/\\/g, "/");
+}
+/** Convert a partition into its non-trivial member groups (size ≥ 2). */
+function partitionGroups(partition) {
+    const byComm = new Map();
+    for (const [node, comm] of partition) {
+        const list = byComm.get(comm);
+        if (list)
+            list.push(node);
+        else
+            byComm.set(comm, [node]);
+    }
+    const groups = [];
+    for (const members of byComm.values()) {
+        if (members.length >= 2) {
+            groups.push([...members].sort((a, b) => a.localeCompare(b)));
+        }
+    }
+    return groups;
+}
+export async function buildStructureDecomposition(params) {
+    // In-scope code universe = disposition-included files; doc files (prose intent)
+    // are the doc_only status plus markdown/asciidoc/rst by extension.
+    const universe = [];
+    const docFiles = [];
+    for (const item of params.disposition.files) {
+        const path = toPosix(item.path);
+        if (item.status === "included")
+            universe.push(path);
+        if (item.status === "doc_only" || DOC_EXTENSION.test(path)) {
+            if (item.status !== "excluded" && item.status !== "binary") {
+                docFiles.push(path);
+            }
+        }
+    }
+    const sortedUniverse = [...new Set(universe)].sort((a, b) => a.localeCompare(b));
+    const sortedDocs = [...new Set(docFiles)].sort((a, b) => a.localeCompare(b));
+    // Async intent extraction (skipped without a root — degrades to empty).
+    const commentResult = params.root
+        ? await deriveCommentDecomposition({
+            root: params.root,
+            files: sortedUniverse,
+            readFileText: params.readFileText,
+        })
+        : { edges: [], scannedFiles: 0 };
+    const docGroups = params.root
+        ? await deriveDocGroups({
+            root: params.root,
+            docFiles: sortedDocs,
+            codeFiles: sortedUniverse,
+            readFileText: params.readFileText,
+        })
+        : [];
+    const sources = buildStructureSources({
+        universe: sortedUniverse,
+        graphBundle: params.graphBundle,
+        commentEdges: commentResult.edges,
+        docGroups,
+    });
+    const result = decompose(sources, "structure");
+    // Finding inputs: pooled behavior partitions, all intent-declared boundaries,
+    // and the stated-purpose subset (docs + comments) for the smeared-purpose side.
+    const behaviorPartitions = sources
+        .filter((s) => s.family === "behavior")
+        .flatMap((s) => s.partitions);
+    const intentBoundaries = [];
+    const purposeGroups = [];
+    for (const source of sources) {
+        if (source.family !== "intent")
+            continue;
+        const groups = source.partitions.length === 1
+            ? partitionGroups(source.partitions[0])
+            : clustersFromPartitions(source.partitions, INTENT_BOUNDARY_FRACTION);
+        intentBoundaries.push(...groups);
+        if (source.id === "docs" || source.id === "comments") {
+            purposeGroups.push(...groups);
+        }
+    }
+    const findings = detectNonColocalization({
+        behaviorPartitions,
+        intentBoundaries,
+        purposeGroups,
+    });
+    return {
+        generated_at: new Date().toISOString(),
+        target: result.target,
+        node_universe_size: sortedUniverse.length,
+        source_ids: sources.map((s) => s.id),
+        consensus: result.consensus,
+        contested: result.contested,
+        findings,
+    };
+}
+//# sourceMappingURL=buildStructureDecomposition.js.map

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

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

package/dist/audit/decompose/findings.d.ts

@@ -0,0 +1,23 @@
+import type { Finding } from "../types.js";
+import type { Partition } from "audit-tools/shared";
+export interface NonColocalizationInput {
+    /** Pooled behavior partitions (every resolution of every behavior source). */
+    behaviorPartitions: Partition[];
+    /** All intent-declared boundaries (directory + docs + comments groups). */
+    intentBoundaries: string[][];
+    /** Explicit stated-purpose groups (docs + comments only — not directory). */
+    purposeGroups: string[][];
+    agreementThreshold?: number;
+    overlapThreshold?: number;
+    /** Minimum behavior-cluster size to report a no-purpose finding. */
+    minClusterSize?: number;
+    /** Cap on findings emitted per kind (deterministic top-by-size). */
+    maxPerKind?: number;
+}
+/**
+ * Emit the two non-co-localization finding kinds. Deterministic: clusters/groups
+ * are processed largest-first (ties by first member), and ids are a stable
+ * instance-scoped SD-### sequence.
+ */
+export declare function detectNonColocalization(input: NonColocalizationInput): Finding[];
+//# sourceMappingURL=findings.d.ts.map

package/dist/audit/decompose/findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.d.ts","sourceRoot":"","sources":["../../../src/audit/decompose/findings.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AA8BpD,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,kBAAkB,EAAE,SAAS,EAAE,CAAC;IAChC,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,EAAE,EAAE,CAAC;IAC7B,6EAA6E;IAC7E,aAAa,EAAE,MAAM,EAAE,EAAE,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,EAAE,CA+EX"}

package/dist/audit/decompose/findings.js

@@ -0,0 +1,121 @@
+// The two non-co-localization findings (Phase B; design of record
+// spec/conceptual-design-review-design.md §"The two non-co-localizations are
+// first-class findings"). When structure-consensus (behavior) and the
+// intent-declared boundaries FAIL to coincide:
+//   - behavioral cluster with no coherent purpose → accidental complexity / dead
+//     subsystem (a coupling cluster no declared boundary owns).
+//   - a purpose with no behavioral cluster → a goal smeared across the codebase,
+//     never modularized (often the highest-value refactor).
+//
+// Deterministic LEADS, not verdicts (confidence: low): they mark where the
+// behavior graphs and the human-declared boundaries disagree, for the Phase C
+// charter pass to confirm against real charters. blast_radius is left unset
+// (Phase C populates goal-graph linkage).
+import { clustersFromPartitions } from "audit-tools/shared";
+/** Structural boundary-integrity findings carry the architecture lens. */
+const LENS = "architecture";
+function createIdGenerator() {
+    let n = 1;
+    return () => `SD-${String(n++).padStart(3, "0")}`;
+}
+/** |subset ∩ group| / |subset|. */
+function overlapFraction(subset, group) {
+    if (subset.length === 0)
+        return 0;
+    let hit = 0;
+    for (const m of subset)
+        if (group.has(m))
+            hit += 1;
+    return hit / subset.length;
+}
+/** Best fraction of `members` contained in any single group. */
+function bestContainment(members, groups) {
+    let best = 0;
+    for (const group of groups) {
+        const set = new Set(group);
+        const frac = overlapFraction(members, set);
+        if (frac > best)
+            best = frac;
+    }
+    return best;
+}
+const DEFAULT_AGREEMENT = 0.5;
+const DEFAULT_OVERLAP = 0.6;
+const DEFAULT_MIN_CLUSTER = 3;
+const DEFAULT_MAX_PER_KIND = 20;
+/**
+ * Emit the two non-co-localization finding kinds. Deterministic: clusters/groups
+ * are processed largest-first (ties by first member), and ids are a stable
+ * instance-scoped SD-### sequence.
+ */
+export function detectNonColocalization(input) {
+    const agreementThreshold = input.agreementThreshold ?? DEFAULT_AGREEMENT;
+    const overlapThreshold = input.overlapThreshold ?? DEFAULT_OVERLAP;
+    const minClusterSize = input.minClusterSize ?? DEFAULT_MIN_CLUSTER;
+    const maxPerKind = input.maxPerKind ?? DEFAULT_MAX_PER_KIND;
+    const nextId = createIdGenerator();
+    const bySizeThenFirst = (a, b) => b.length - a.length || (a[0] ?? "").localeCompare(b[0] ?? "");
+    const findings = [];
+    // One clustering pass shared by both detectors: the full set for the
+    // purpose-side containment check, the size-filtered set for the no-purpose one.
+    const allBehaviorClusters = clustersFromPartitions(input.behaviorPartitions, agreementThreshold);
+    // --- Behavioral cluster with no coherent purpose ---
+    const behaviorClusters = allBehaviorClusters
+        .filter((c) => c.length >= minClusterSize)
+        .sort(bySizeThenFirst);
+    for (const cluster of behaviorClusters.slice(0, maxPerKind)) {
+        const best = bestContainment(cluster, input.intentBoundaries);
+        if (best + 1e-12 >= overlapThreshold)
+            continue; // aligns to a declared boundary
+        findings.push({
+            id: nextId(),
+            title: `Behavioral cluster spans declared boundaries: ${cluster.length} files`,
+            category: "non_colocalization_behavioral",
+            severity: "low",
+            confidence: "low",
+            lens: LENS,
+            summary: `These ${cluster.length} files are tightly coupled by behavior (call/import, ` +
+                `co-change, and/or shared state) yet no single declared boundary ` +
+                `(directory, doc, or comment grouping) contains most of them ` +
+                `(best overlap ${(best * 100).toFixed(0)}%). A coupling cluster no ` +
+                `declared purpose owns is accidental complexity or a dead subsystem — a ` +
+                `lead for the conceptual charter pass to confirm.`,
+            affected_files: cluster.map((path) => ({ path })),
+            evidence: [
+                `Behavioral coupling consensus across ${input.behaviorPartitions.length} resolution levels.`,
+                `Best containment in any declared boundary: ${(best * 100).toFixed(0)}% (threshold ${(overlapThreshold * 100).toFixed(0)}%).`,
+            ],
+            systemic: true,
+        });
+    }
+    // --- A purpose with no behavioral cluster (smeared) ---
+    const purposeGroups = [...input.purposeGroups]
+        .filter((g) => g.length >= 2)
+        .sort(bySizeThenFirst);
+    for (const group of purposeGroups.slice(0, maxPerKind)) {
+        const best = bestContainment(group, allBehaviorClusters);
+        if (best + 1e-12 >= overlapThreshold)
+            continue; // the purpose IS a behavior cluster
+        findings.push({
+            id: nextId(),
+            title: `Declared purpose is behaviorally smeared: ${group.length} files`,
+            category: "non_colocalization_purpose",
+            severity: "low",
+            confidence: "low",
+            lens: LENS,
+            summary: `A doc/comment grouping declares these ${group.length} files a unit, but ` +
+                `they do not form a behavioral cluster — no single coupling cluster ` +
+                `contains most of them (best overlap ${(best * 100).toFixed(0)}%). A ` +
+                `purpose smeared across the codebase and never modularized is often the ` +
+                `highest-value refactor — a lead for the conceptual charter pass.`,
+            affected_files: group.map((path) => ({ path })),
+            evidence: [
+                `Declared as one unit by an intent-declared source (doc/comment).`,
+                `Best containment in any behavioral cluster: ${(best * 100).toFixed(0)}% (threshold ${(overlapThreshold * 100).toFixed(0)}%).`,
+            ],
+            systemic: true,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=findings.js.map

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

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

package/dist/audit/decompose/sources.d.ts

@@ -0,0 +1,21 @@
+import type { DecompositionSource, GraphBundle } from "audit-tools/shared";
+import { type CouplingEdge } from "../extractors/dataStateCoupling.js";
+export interface StructureSourcesInput {
+    /** In-scope files (posix, sorted, unique) — the shared node universe. */
+    universe: string[];
+    graphBundle: GraphBundle;
+    /** Comment cross-reference edges from deriveCommentDecomposition. */
+    commentEdges: CouplingEdge[];
+    /** Doc-declared groups from deriveDocGroups. */
+    docGroups: string[][];
+    resolutions?: readonly number[];
+    /** Directory depths for the intent directory family (default [1,2,3]). */
+    directoryDepths?: number[];
+}
+/**
+ * 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 declare function buildStructureSources(input: StructureSourcesInput): DecompositionSource[];
+//# sourceMappingURL=sources.d.ts.map

package/dist/audit/decompose/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../../src/audit/decompose/sources.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,mBAAmB,EACnB,WAAW,EAEZ,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,oCAAoC,CAAC;AAqF5C,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,qEAAqE;IACrE,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,gDAAgD;IAChD,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAID;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,qBAAqB,GAC3B,mBAAmB,EAAE,CAmFvB"}

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":"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"}

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"}