auditor-lambda 0.6.12 → 0.8.0

package/dist/orchestrator/reviewPackets.js

@@ -1,76 +1,13 @@
 import { createHash } from "node:crypto";
-import { estimateTokensFromBytes, isRecord } from "@audit-tools/shared";
 import { LENS_ORDER, priorityRank, sortLenses } from "./auditTaskUtils.js";
-import { UnionFind } from "./unionFind.js";
-import { normalizeGraphPath, isPackageManifestPath, isTypescriptProjectConfigPath, isGoModuleManifestPath, isCargoManifestPath, isMavenPomPath, } from "../extractors/graphPathUtils.js";
+import { normalizeGraphPath } from "../extractors/graphPathUtils.js";
+import { DEFAULT_MAX_TASKS_PER_PACKET, DEFAULT_TARGET_PACKET_TOKENS, ESTIMATED_TOKENS_PER_LINE, ESTIMATED_PACKET_PROMPT_TOKENS, sizeIndexFromManifest, fileGroupContentTokens, taskContentTokens, estimateTaskGroupTokens, } from "./reviewPacketSizing.js";
+import { HIGH_FAN_DEGREE_THRESHOLD, collectGraphEdges, buildGraphDegreeIndex, isPacketExpansionEdge, buildFileToGroupKeys, isConcreteGraphEdge, unionFindFromGroups, roundQuality, buildPlanningGraphEdges, buildPacketGraphContext, } from "./reviewPacketGraph.js";
 // Re-exported for scope.ts, which imports the canonical path normalizer here.
 export { normalizeGraphPath };
-const DEFAULT_MAX_TASKS_PER_PACKET = 0;
-const DEFAULT_TARGET_PACKET_LINES = 8000;
-export const ESTIMATED_TOKENS_PER_LINE = 4;
-export const ESTIMATED_PACKET_PROMPT_TOKENS = 900;
-// Default per-packet content-token budget. Kept equal to the legacy
-// line-target × per-line estimate so byte-derived sizing lands on the same
-// thresholds as the old line-based sizing when the line fallback is in effect.
-const DEFAULT_TARGET_PACKET_TOKENS = DEFAULT_TARGET_PACKET_LINES * ESTIMATED_TOKENS_PER_LINE;
-/**
- * Build a path → size_bytes index from a repo manifest. Byte counts are
- * recorded during intake, so this never reads files. Review packet token
- * estimates are derived from these bytes (Phase 2) instead of counted lines.
- */
-export function sizeIndexFromManifest(repoManifest) {
-    if (!repoManifest)
-        return {};
-    return Object.fromEntries(repoManifest.files.map((file) => [file.path, file.size_bytes]));
-}
-/**
- * Estimated content tokens for a single file. Prefers a byte-based estimate
- * from `sizeIndex` (sourced from the repo manifest); falls back to the legacy
- * line-based estimate when no positive byte count is available (e.g. manually
- * built tasks in tests, or paths absent from the manifest).
- */
-function pathContentTokens(owner, path, sizeIndex, lineIndex) {
-    const bytes = sizeIndex?.[path];
-    if (typeof bytes === "number" && bytes > 0) {
-        return estimateTokensFromBytes(bytes);
-    }
-    const lines = owner?.file_line_counts?.[path] ?? lineIndex?.[path] ?? 0;
-    return lines * ESTIMATED_TOKENS_PER_LINE;
-}
-/** Estimated content tokens for one task across all of its files. */
-function taskContentTokens(task, sizeIndex, lineIndex) {
-    return task.file_paths.reduce((sum, path) => sum + pathContentTokens(task, path, sizeIndex, lineIndex), 0);
-}
-/**
- * Estimated content tokens across a set of file paths, resolving an owning task
- * per path so the line fallback can read its `file_line_counts`. Shared files
- * are counted once.
- */
-function fileGroupContentTokens(filePaths, tasks, sizeIndex, lineIndex) {
-    let total = 0;
-    for (const path of filePaths) {
-        const owner = tasks.find((task) => task.file_paths.includes(path));
-        total += pathContentTokens(owner, path, sizeIndex, lineIndex);
-    }
-    return total;
-}
-export function estimateTaskGroupTokens(tasks, sizeIndex, lineIndex) {
-    let contentTokens = 0;
-    for (const task of tasks) {
-        contentTokens += taskContentTokens(task, sizeIndex, lineIndex);
-    }
-    return ESTIMATED_PACKET_PROMPT_TOKENS + contentTokens;
-}
-const PACKET_EXPANSION_MIN_CONFIDENCE = 0.65;
-/**
- * Fan-in / fan-out degree above which a node is treated as a hub. Exported so
- * the Phase 3 delta-scope expansion skips the same hubs that packet planning
- * skips, preventing scope blow-up through highly-connected modules.
- */
-export const HIGH_FAN_DEGREE_THRESHOLD = 12;
-const HIGH_FAN_EXPANSION_CONFIDENCE = 0.99;
-const MAX_PACKET_KEY_EDGES = 8;
-const MAX_PACKET_BOUNDARY_FILES = 12;
+// Sizing / token-budget arithmetic moved to reviewPacketSizing.ts; re-exported
+// here for the modules that import it from reviewPackets.
+export { ESTIMATED_TOKENS_PER_LINE, ESTIMATED_PACKET_PROMPT_TOKENS, sizeIndexFromManifest, estimateTaskGroupTokens, };
 const MAX_WEAK_PACKET_SAMPLES = 12;
 const MAX_WEAK_PACKET_SAMPLE_FILES = 8;
 const WEAK_PACKET_GAP_ORDER = [
@@ -78,36 +15,6 @@ const WEAK_PACKET_GAP_ORDER = [
     "unexplained_files",
     "partial_cohesion",
 ];
-const MAX_ENTRYPOINT_FLOW_BRIDGE_HOPS = 3;
-const MAX_ENTRYPOINT_FLOW_BRANCHES = 8;
-const SUBSYSTEM_CLUSTER_CONFIDENCE = 0.7;
-const PACKAGE_OWNERSHIP_CLUSTER_CONFIDENCE = 0.68;
-const MODULE_OWNERSHIP_CLUSTER_CONFIDENCE = 0.66;
-const ANALYZER_OWNERSHIP_EDGE_KIND = "analyzer-ownership-root-link";
-const MAX_SUBSYSTEM_CLUSTER_GROUPS = 4;
-const MAX_SUBSYSTEM_CLUSTER_TASKS = 8;
-const MAX_SUBSYSTEM_CLUSTER_FILES = 8;
-const MODULE_OWNERSHIP_EDGE_KINDS = new Set([
-    "typescript-project-reference-link",
-    "go-workspace-module-link",
-    "cargo-workspace-member-link",
-    "maven-module-link",
-    ANALYZER_OWNERSHIP_EDGE_KIND,
-]);
-const BROAD_ANALYZER_OWNERSHIP_ROOTS = new Set([
-    "src",
-    "lib",
-    "app",
-    "apps",
-    "packages",
-    "services",
-    "crates",
-    "modules",
-    "test",
-    "tests",
-    "spec",
-    "specs",
-]);
 function normalizePriority(priority) {
     return priority ?? "low";
 }
@@ -135,647 +42,6 @@ function buildTaskGroups(tasks) {
     }
     return groups;
 }
-export function collectGraphEdges(graphBundle) {
-    if (!graphBundle?.graphs) {
-        return [];
-    }
-    const edges = [];
-    for (const key of ["imports", "calls", "references"]) {
-        const raw = graphBundle.graphs[key];
-        if (!Array.isArray(raw)) {
-            continue;
-        }
-        for (const item of raw) {
-            if (!isRecord(item)) {
-                continue;
-            }
-            if (typeof item.from !== "string" || typeof item.to !== "string") {
-                continue;
-            }
-            const edge = {
-                from: item.from,
-                to: item.to,
-                kind: typeof item.kind === "string" ? item.kind : undefined,
-            };
-            if (item.direction === "directed" || item.direction === "undirected") {
-                edge.direction = item.direction;
-            }
-            if (typeof item.confidence === "number" && Number.isFinite(item.confidence)) {
-                edge.confidence = Math.min(1, Math.max(0, item.confidence));
-            }
-            if (typeof item.reason === "string" && item.reason.trim().length > 0) {
-                edge.reason = item.reason.trim();
-            }
-            edges.push(edge);
-        }
-    }
-    return edges;
-}
-export function graphEdgeConfidence(edge) {
-    if (typeof edge.confidence === "number" && Number.isFinite(edge.confidence)) {
-        return Math.min(1, Math.max(0, edge.confidence));
-    }
-    if (edge.kind === "heuristic-container-edge") {
-        return 0.25;
-    }
-    if (edge.kind?.startsWith("heuristic-")) {
-        return 0.5;
-    }
-    return 0.8;
-}
-function isConcreteGraphEdge(edge) {
-    return edge.kind !== "heuristic-container-edge";
-}
-export function buildGraphDegreeIndex(edges) {
-    const fanIn = new Map();
-    const fanOut = new Map();
-    for (const edge of edges) {
-        if (!isConcreteGraphEdge(edge)) {
-            continue;
-        }
-        const from = normalizeGraphPath(edge.from);
-        const to = normalizeGraphPath(edge.to);
-        fanOut.set(from, (fanOut.get(from) ?? 0) + 1);
-        fanIn.set(to, (fanIn.get(to) ?? 0) + 1);
-    }
-    return { fanIn, fanOut };
-}
-function isPacketExpansionEdge(edge, degreeIndex) {
-    if (!isConcreteGraphEdge(edge)) {
-        return false;
-    }
-    const confidence = graphEdgeConfidence(edge);
-    if (confidence < PACKET_EXPANSION_MIN_CONFIDENCE) {
-        return false;
-    }
-    const fromFanOut = degreeIndex.fanOut.get(normalizeGraphPath(edge.from)) ?? 0;
-    const toFanIn = degreeIndex.fanIn.get(normalizeGraphPath(edge.to)) ?? 0;
-    const highFanEdge = fromFanOut > HIGH_FAN_DEGREE_THRESHOLD ||
-        toFanIn > HIGH_FAN_DEGREE_THRESHOLD;
-    return !highFanEdge || confidence >= HIGH_FAN_EXPANSION_CONFIDENCE;
-}
-function buildFileToGroupKeys(groups) {
-    const fileToGroupKeys = new Map();
-    for (const [key, tasks] of groups) {
-        for (const path of new Set(tasks.flatMap((task) => task.file_paths))) {
-            const normalized = normalizeGraphPath(path);
-            const existing = fileToGroupKeys.get(normalized) ?? new Set();
-            existing.add(key);
-            fileToGroupKeys.set(normalized, existing);
-        }
-    }
-    return fileToGroupKeys;
-}
-function collectEntrypointFlowRoots(graphEdges, graphBundle) {
-    const roots = new Set();
-    const routes = Array.isArray(graphBundle?.graphs.routes)
-        ? graphBundle.graphs.routes
-        : [];
-    for (const route of routes) {
-        if (isRecord(route) && typeof route.handler === "string") {
-            roots.add(normalizeGraphPath(route.handler));
-        }
-    }
-    for (const edge of graphEdges) {
-        if (edge.kind === "route-handler-link") {
-            roots.add(normalizeGraphPath(edge.from));
-            roots.add(normalizeGraphPath(edge.to));
-        }
-        else if (edge.kind === "package-entrypoint-link") {
-            roots.add(normalizeGraphPath(edge.to));
-        }
-    }
-    return roots;
-}
-function buildRepresentativePathIndex(groups, graphEdges, graphBundle) {
-    const representatives = new Map();
-    const addPath = (path) => {
-        const normalized = normalizeGraphPath(path);
-        if (!representatives.has(normalized)) {
-            representatives.set(normalized, path);
-        }
-    };
-    for (const tasks of groups.values()) {
-        for (const path of tasks.flatMap((task) => task.file_paths)) {
-            addPath(path);
-        }
-    }
-    for (const edge of graphEdges) {
-        addPath(edge.from);
-        addPath(edge.to);
-    }
-    const routes = Array.isArray(graphBundle?.graphs.routes)
-        ? graphBundle.graphs.routes
-        : [];
-    for (const route of routes) {
-        if (isRecord(route) && typeof route.handler === "string") {
-            addPath(route.handler);
-        }
-    }
-    return representatives;
-}
-function uniqueTaskFilePaths(tasks) {
-    return [...new Set(tasks.flatMap((task) => task.file_paths))].sort((a, b) => a.localeCompare(b));
-}
-function groupsOverlap(a, b) {
-    for (const key of a) {
-        if (b.has(key)) {
-            return true;
-        }
-    }
-    return false;
-}
-function unionFindFromGroups(groups, graphEdges) {
-    const uf = new UnionFind(groups.keys());
-    const fileToGroupKeys = buildFileToGroupKeys(groups);
-    const degreeIndex = buildGraphDegreeIndex(graphEdges);
-    for (const keys of fileToGroupKeys.values()) {
-        const [first, ...rest] = [...keys].sort((a, b) => a.localeCompare(b));
-        if (!first)
-            continue;
-        for (const key of rest) {
-            uf.union(first, key);
-        }
-    }
-    for (const edge of graphEdges) {
-        if (!isPacketExpansionEdge(edge, degreeIndex)) {
-            continue;
-        }
-        const fromGroups = fileToGroupKeys.get(normalizeGraphPath(edge.from));
-        const toGroups = fileToGroupKeys.get(normalizeGraphPath(edge.to));
-        if (!fromGroups || !toGroups) {
-            continue;
-        }
-        for (const fromKey of fromGroups) {
-            for (const toKey of toGroups) {
-                uf.union(fromKey, toKey);
-            }
-        }
-    }
-    return uf;
-}
-function buildGraphConnectedComponentIndex(groups, graphEdges) {
-    const uf = unionFindFromGroups(groups, graphEdges);
-    return new Map([...groups.keys()].map((key) => [key, uf.find(key)]));
-}
-function subsystemRootForPath(path) {
-    const segments = normalizeGraphPath(path).split("/").filter(Boolean);
-    const directories = segments.slice(0, -1);
-    if (directories.length < 2) {
-        return undefined;
-    }
-    const namespace = directories[0];
-    const depth = namespace === "apps" || namespace === "packages"
-        ? 4
-        : namespace === "src" ||
-            namespace === "lib" ||
-            namespace === "app" ||
-            namespace === "tests" ||
-            namespace === "test" ||
-            namespace === "spec"
-            ? 3
-            : 2;
-    if (directories.length < depth) {
-        return undefined;
-    }
-    return directories.slice(0, depth).join("/");
-}
-function subsystemRootForTasks(tasks) {
-    const rootsForFiles = uniqueTaskFilePaths(tasks).map(subsystemRootForPath);
-    if (rootsForFiles.some((root) => root === undefined)) {
-        return undefined;
-    }
-    const roots = new Set(rootsForFiles);
-    return roots.size === 1 ? [...roots][0] : undefined;
-}
-function buildBoundedClusterEdges(params) {
-    const groupToComponent = buildGraphConnectedComponentIndex(params.groups, params.graphEdges);
-    const clusters = new Map();
-    for (const [key, tasks] of params.groups) {
-        const root = params.rootForTasks(tasks);
-        if (!root) {
-            continue;
-        }
-        const filePaths = uniqueTaskFilePaths(tasks);
-        const cluster = clusters.get(root) ?? [];
-        cluster.push({
-            component: groupToComponent.get(key) ?? key,
-            tasks,
-            filePaths,
-            representativePath: filePaths[0] ?? root,
-        });
-        clusters.set(root, cluster);
-    }
-    const clusterEdges = [];
-    for (const [root, entries] of [...clusters.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
-        const components = new Map();
-        for (const entry of entries) {
-            const component = components.get(entry.component) ?? {
-                taskCount: 0,
-                filePaths: new Set(),
-                representativePath: entry.representativePath,
-            };
-            component.taskCount += entry.tasks.length;
-            for (const filePath of entry.filePaths) {
-                component.filePaths.add(filePath);
-            }
-            if (entry.representativePath.localeCompare(component.representativePath) < 0) {
-                component.representativePath = entry.representativePath;
-            }
-            components.set(entry.component, component);
-        }
-        const componentEntries = [...components.values()].sort((a, b) => a.representativePath.localeCompare(b.representativePath));
-        if (componentEntries.length < 2 ||
-            componentEntries.length > MAX_SUBSYSTEM_CLUSTER_GROUPS) {
-            continue;
-        }
-        const allFiles = new Set(componentEntries.flatMap((entry) => [...entry.filePaths]));
-        const totalTasks = componentEntries.reduce((sum, entry) => sum + entry.taskCount, 0);
-        const clusterTasks = entries.flatMap((entry) => entry.tasks);
-        const totalContentTokens = fileGroupContentTokens(allFiles, clusterTasks, params.sizeIndex, params.lineIndex);
-        if (allFiles.size > MAX_SUBSYSTEM_CLUSTER_FILES ||
-            totalTasks > MAX_SUBSYSTEM_CLUSTER_TASKS ||
-            totalContentTokens >
-                (params.targetPacketTokens ?? DEFAULT_TARGET_PACKET_TOKENS)) {
-            continue;
-        }
-        for (let index = 1; index < componentEntries.length; index++) {
-            const previous = componentEntries[index - 1];
-            const current = componentEntries[index];
-            clusterEdges.push({
-                from: previous.representativePath,
-                to: current.representativePath,
-                kind: params.edgeKind,
-                direction: "undirected",
-                confidence: params.edgeConfidence,
-                reason: params.reasonForCluster(root, allFiles.size),
-            });
-        }
-    }
-    return clusterEdges.sort(compareGraphEdges);
-}
-function buildSubsystemClusterEdges(groups, graphEdges, lineIndex, sizeIndex, targetPacketTokens = DEFAULT_TARGET_PACKET_TOKENS) {
-    return buildBoundedClusterEdges({
-        groups,
-        graphEdges,
-        rootForTasks: subsystemRootForTasks,
-        edgeKind: "subsystem-cluster-link",
-        edgeConfidence: SUBSYSTEM_CLUSTER_CONFIDENCE,
-        reasonForCluster: (root, fileCount) => `Bounded subsystem cluster '${root}' groups ${fileCount} file(s) without stronger graph evidence.`,
-        lineIndex,
-        sizeIndex,
-        targetPacketTokens,
-    });
-}
-function packageManifestRoot(path) {
-    const segments = normalizeGraphPath(path).split("/").filter(Boolean);
-    if (!isPackageManifestPath(path) || segments.length < 2) {
-        return undefined;
-    }
-    return segments.slice(0, -1).join("/");
-}
-function configFileRoot(path, predicate) {
-    const segments = normalizeGraphPath(path).split("/").filter(Boolean);
-    if (!predicate(path) || segments.length < 2) {
-        return undefined;
-    }
-    return segments.slice(0, -1).join("/");
-}
-function moduleConfigRoot(path) {
-    return (configFileRoot(path, isTypescriptProjectConfigPath) ??
-        configFileRoot(path, isGoModuleManifestPath) ??
-        configFileRoot(path, isCargoManifestPath) ??
-        configFileRoot(path, isMavenPomPath));
-}
-function analyzerOwnershipRoot(path) {
-    const root = normalizeGraphPath(path).replace(/\/+$/, "");
-    if (root.length === 0 ||
-        root === "." ||
-        root === ".." ||
-        root.startsWith("../") ||
-        root.startsWith("/")) {
-        return undefined;
-    }
-    const segments = root.split("/").filter(Boolean);
-    if (segments.length === 1 &&
-        BROAD_ANALYZER_OWNERSHIP_ROOTS.has(segments[0])) {
-        return undefined;
-    }
-    return root;
-}
-function collectPackageOwnershipRoots(groups, graphEdges) {
-    const roots = new Set();
-    const addRoot = (path) => {
-        const root = packageManifestRoot(path);
-        if (root) {
-            roots.add(root);
-        }
-    };
-    for (const tasks of groups.values()) {
-        for (const path of tasks.flatMap((task) => task.file_paths)) {
-            addRoot(path);
-        }
-    }
-    for (const edge of graphEdges) {
-        addRoot(edge.from);
-        addRoot(edge.to);
-    }
-    return roots;
-}
-function ownershipRootForPath(path, ownershipRoots) {
-    const normalized = normalizeGraphPath(path);
-    let bestMatch;
-    for (const root of ownershipRoots) {
-        if (normalized === `${root}/package.json` ||
-            normalized === `${root}/tsconfig.json` ||
-            normalized.startsWith(`${root}/`)) {
-            if (!bestMatch || root.length > bestMatch.length) {
-                bestMatch = root;
-            }
-        }
-    }
-    return bestMatch;
-}
-function packageOwnershipRootForTasks(tasks, packageRoots) {
-    if (packageRoots.size === 0) {
-        return undefined;
-    }
-    const rootsForFiles = uniqueTaskFilePaths(tasks).map((path) => ownershipRootForPath(path, packageRoots));
-    if (rootsForFiles.some((root) => root === undefined)) {
-        return undefined;
-    }
-    const roots = new Set(rootsForFiles);
-    return roots.size === 1 ? [...roots][0] : undefined;
-}
-function buildPackageOwnershipClusterEdges(groups, graphEdges, lineIndex, sizeIndex, targetPacketTokens = DEFAULT_TARGET_PACKET_TOKENS) {
-    const packageRoots = collectPackageOwnershipRoots(groups, graphEdges);
-    if (packageRoots.size === 0) {
-        return [];
-    }
-    return buildBoundedClusterEdges({
-        groups,
-        graphEdges,
-        rootForTasks: (tasks) => packageOwnershipRootForTasks(tasks, packageRoots),
-        edgeKind: "package-ownership-link",
-        edgeConfidence: PACKAGE_OWNERSHIP_CLUSTER_CONFIDENCE,
-        reasonForCluster: (root, fileCount) => `Package ownership root '${root}' groups ${fileCount} file(s) across bounded package subdirectories.`,
-        lineIndex,
-        sizeIndex,
-        targetPacketTokens,
-    });
-}
-function collectModuleOwnershipRoots(groups, graphEdges) {
-    const roots = new Map();
-    const addRoot = (path) => {
-        const root = moduleConfigRoot(path);
-        if (root) {
-            roots.set(root, roots.get(root) ?? "project configuration");
-        }
-    };
-    const addAnalyzerRoot = (path) => {
-        const root = analyzerOwnershipRoot(path);
-        if (root) {
-            roots.set(root, roots.get(root) ?? "analyzer ownership hint");
-        }
-    };
-    for (const tasks of groups.values()) {
-        for (const path of tasks.flatMap((task) => task.file_paths)) {
-            addRoot(path);
-        }
-    }
-    for (const edge of graphEdges) {
-        if (edge.kind === ANALYZER_OWNERSHIP_EDGE_KIND) {
-            addAnalyzerRoot(edge.from);
-            continue;
-        }
-        if (!MODULE_OWNERSHIP_EDGE_KINDS.has(edge.kind ?? "")) {
-            continue;
-        }
-        addRoot(edge.from);
-        addRoot(edge.to);
-    }
-    return roots;
-}
-function moduleOwnershipRootForTasks(tasks, moduleRoots) {
-    if (moduleRoots.size === 0) {
-        return undefined;
-    }
-    const rootsForFiles = uniqueTaskFilePaths(tasks).map((path) => ownershipRootForPath(path, moduleRoots));
-    if (rootsForFiles.some((root) => root === undefined)) {
-        return undefined;
-    }
-    const roots = new Set(rootsForFiles);
-    return roots.size === 1 ? [...roots][0] : undefined;
-}
-function buildModuleOwnershipClusterEdges(groups, graphEdges, lineIndex, sizeIndex, targetPacketTokens = DEFAULT_TARGET_PACKET_TOKENS) {
-    const moduleRoots = collectModuleOwnershipRoots(groups, graphEdges);
-    if (moduleRoots.size === 0) {
-        return [];
-    }
-    const moduleRootSet = new Set(moduleRoots.keys());
-    return buildBoundedClusterEdges({
-        groups,
-        graphEdges,
-        rootForTasks: (tasks) => moduleOwnershipRootForTasks(tasks, moduleRootSet),
-        edgeKind: "module-ownership-link",
-        edgeConfidence: MODULE_OWNERSHIP_CLUSTER_CONFIDENCE,
-        reasonForCluster: (root, fileCount) => {
-            const source = moduleRoots.get(root) ?? "project configuration";
-            return source === "analyzer ownership hint"
-                ? `Module ownership root '${root}' from analyzer ownership hint groups ${fileCount} file(s) across bounded subdirectories.`
-                : `Module ownership root '${root}' from project configuration groups ${fileCount} file(s) across bounded subdirectories.`;
-        },
-        lineIndex,
-        sizeIndex,
-        targetPacketTokens,
-    });
-}
-function buildEntrypointFlowBridgeEdges(groups, graphEdges, graphBundle) {
-    const roots = collectEntrypointFlowRoots(graphEdges, graphBundle);
-    if (roots.size === 0) {
-        return [];
-    }
-    const fileToGroupKeys = buildFileToGroupKeys(groups);
-    const degreeIndex = buildGraphDegreeIndex(graphEdges);
-    const representatives = buildRepresentativePathIndex(groups, graphEdges, graphBundle);
-    const adjacency = new Map();
-    for (const edge of graphEdges) {
-        if (edge.direction === "undirected" ||
-            !isPacketExpansionEdge(edge, degreeIndex)) {
-            continue;
-        }
-        const from = normalizeGraphPath(edge.from);
-        const edges = adjacency.get(from) ?? [];
-        edges.push(edge);
-        adjacency.set(from, edges);
-    }
-    for (const edges of adjacency.values()) {
-        edges.sort(compareGraphEdges);
-    }
-    const bridgeEdges = new Map();
-    const displayPath = (normalized) => representatives.get(normalized) ?? normalized;
-    for (const root of [...roots].sort((a, b) => a.localeCompare(b))) {
-        const rootGroups = fileToGroupKeys.get(root);
-        if (!rootGroups) {
-            continue;
-        }
-        const queue = [
-            { node: root, path: [root], edges: [] },
-        ];
-        const visited = new Set([root]);
-        while (queue.length > 0) {
-            const current = queue.shift();
-            if (!current || current.edges.length >= MAX_ENTRYPOINT_FLOW_BRIDGE_HOPS) {
-                continue;
-            }
-            const outgoing = adjacency.get(current.node) ?? [];
-            if (outgoing.length > MAX_ENTRYPOINT_FLOW_BRANCHES) {
-                continue;
-            }
-            for (const edge of outgoing) {
-                const target = normalizeGraphPath(edge.to);
-                if (current.path.includes(target)) {
-                    continue;
-                }
-                const nextEdges = [...current.edges, edge];
-                const nextPath = [...current.path, target];
-                const targetGroups = fileToGroupKeys.get(target);
-                if (targetGroups &&
-                    nextEdges.length > 1 &&
-                    !groupsOverlap(rootGroups, targetGroups)) {
-                    const from = displayPath(root);
-                    const to = displayPath(target);
-                    const intermediates = nextPath.slice(1, -1).map(displayPath);
-                    const confidence = Math.min(...nextEdges.map(graphEdgeConfidence));
-                    const bridgeEdge = {
-                        from,
-                        to,
-                        kind: "entrypoint-flow-link",
-                        direction: "directed",
-                        confidence,
-                        reason: intermediates.length > 0
-                            ? `Entrypoint flow from '${from}' reaches '${to}' via ${intermediates.join(" -> ")}.`
-                            : `Entrypoint flow from '${from}' reaches '${to}'.`,
-                    };
-                    bridgeEdges.set(`${from}\0${to}\0${bridgeEdge.kind}`, bridgeEdge);
-                }
-                if (!targetGroups &&
-                    nextEdges.length < MAX_ENTRYPOINT_FLOW_BRIDGE_HOPS &&
-                    !visited.has(target)) {
-                    visited.add(target);
-                    queue.push({
-                        node: target,
-                        path: nextPath,
-                        edges: nextEdges,
-                    });
-                }
-            }
-        }
-    }
-    return [...bridgeEdges.values()].sort(compareGraphEdges);
-}
-function buildPlanningGraphEdges(groups, graphEdges, graphBundle, lineIndex, sizeIndex, targetPacketTokens = DEFAULT_TARGET_PACKET_TOKENS) {
-    const bridgeEdges = buildEntrypointFlowBridgeEdges(groups, graphEdges, graphBundle);
-    const graphWithBridges = bridgeEdges.length > 0 ? [...graphEdges, ...bridgeEdges] : graphEdges;
-    const subsystemEdges = buildSubsystemClusterEdges(groups, graphWithBridges, lineIndex, sizeIndex, targetPacketTokens);
-    const graphWithSubsystems = subsystemEdges.length > 0
-        ? [...graphWithBridges, ...subsystemEdges]
-        : graphWithBridges;
-    const packageOwnershipEdges = buildPackageOwnershipClusterEdges(groups, graphWithSubsystems, lineIndex, sizeIndex, targetPacketTokens);
-    const graphWithPackageOwnership = packageOwnershipEdges.length > 0
-        ? [...graphWithSubsystems, ...packageOwnershipEdges]
-        : graphWithSubsystems;
-    const moduleOwnershipEdges = buildModuleOwnershipClusterEdges(groups, graphWithPackageOwnership, lineIndex, sizeIndex, targetPacketTokens);
-    return moduleOwnershipEdges.length > 0
-        ? [...graphWithPackageOwnership, ...moduleOwnershipEdges]
-        : graphWithPackageOwnership;
-}
-function compareGraphEdges(a, b) {
-    const confidenceDelta = graphEdgeConfidence(b) - graphEdgeConfidence(a);
-    if (confidenceDelta !== 0)
-        return confidenceDelta;
-    return (a.from.localeCompare(b.from) ||
-        a.to.localeCompare(b.to) ||
-        (a.kind ?? "").localeCompare(b.kind ?? ""));
-}
-function reviewPacketGraphEdge(edge) {
-    const result = {
-        from: edge.from,
-        to: edge.to,
-        confidence: graphEdgeConfidence(edge),
-    };
-    if (edge.kind)
-        result.kind = edge.kind;
-    if (edge.reason)
-        result.reason = edge.reason;
-    return result;
-}
-function roundQuality(value) {
-    return Math.round(value * 1000) / 1000;
-}
-function packetEntrypoints(filePaths, graphBundle) {
-    const fileSet = new Set(filePaths.map(normalizeGraphPath));
-    const routes = Array.isArray(graphBundle?.graphs.routes)
-        ? graphBundle.graphs.routes
-        : [];
-    return routes
-        .filter((route) => isRecord(route) &&
-        typeof route.handler === "string" &&
-        typeof route.path === "string" &&
-        fileSet.has(normalizeGraphPath(route.handler)))
-        .map((route) => {
-        const method = typeof route.method === "string" ? `${route.method} ` : "";
-        return `${method}${route.path} -> ${route.handler}`;
-    })
-        .sort((a, b) => a.localeCompare(b));
-}
-function buildPacketGraphContext(filePaths, graphEdges, graphBundle) {
-    const fileSet = new Set(filePaths.map(normalizeGraphPath));
-    const internalEdges = [];
-    const boundaryFiles = new Set();
-    let boundaryEdgeCount = 0;
-    for (const edge of graphEdges) {
-        if (!isConcreteGraphEdge(edge)) {
-            continue;
-        }
-        const fromInPacket = fileSet.has(normalizeGraphPath(edge.from));
-        const toInPacket = fileSet.has(normalizeGraphPath(edge.to));
-        if (fromInPacket && toInPacket) {
-            internalEdges.push(edge);
-        }
-        else if (fromInPacket !== toInPacket) {
-            boundaryEdgeCount += 1;
-            boundaryFiles.add(fromInPacket ? edge.to : edge.from);
-        }
-    }
-    const internallyConnectedFiles = new Set();
-    for (const edge of internalEdges) {
-        internallyConnectedFiles.add(normalizeGraphPath(edge.from));
-        internallyConnectedFiles.add(normalizeGraphPath(edge.to));
-    }
-    const unexplainedFileCount = filePaths.length <= 1
-        ? 0
-        : filePaths.filter((path) => !internallyConnectedFiles.has(normalizeGraphPath(path))).length;
-    const cohesionScore = filePaths.length <= 1
-        ? 1
-        : Math.min(1, internalEdges.length / (filePaths.length - 1));
-    return {
-        keyEdges: internalEdges
-            .sort(compareGraphEdges)
-            .slice(0, MAX_PACKET_KEY_EDGES)
-            .map(reviewPacketGraphEdge),
-        boundaryFiles: [...boundaryFiles]
-            .sort((a, b) => a.localeCompare(b))
-            .slice(0, MAX_PACKET_BOUNDARY_FILES),
-        entrypoints: packetEntrypoints(filePaths, graphBundle),
-        quality: {
-            cohesion_score: roundQuality(cohesionScore),
-            internal_edge_count: internalEdges.length,
-            boundary_edge_count: boundaryEdgeCount,
-            unexplained_file_count: unexplainedFileCount,
-        },
-    };
-}
 function sanitizeSegment(value) {
     const sanitized = value
         .replace(/[^a-zA-Z0-9_-]+/g, "-")