peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/slice/slice-decompose-service.js

@@ -0,0 +1,532 @@
+/**
+ * Slice Decomposition Service -- the 6-stage pure algorithm.
+ *
+ * See `.peaks/_runtime/2026-06-13-session-86d852/sc/slice-algorithm-design.md`
+ * for the full spec, and `slice-decompose-types.ts` for all input/output
+ * type contracts.
+ *
+ * Public surface (one exported function):
+ *
+ *   decomposeSlices(rid, prdMarkdown, projectRoot, options)
+ *
+ * Default runners (CLI-mode, real shell-outs):
+ *
+ *   defaultCodegraphRunner()  -- spawns `npx codegraph <cmd>`
+ *   defaultUnderstandRunner() -- reads .understand-anything/knowledge-graph.json
+ *   defaultImportEdgeRunner() -- reads source files for import statements
+ *
+ * Tests inject fakes via the `codegraphRunner`, `understandRunner`, and
+ * `importEdgeRunner` fields of `DecomposeOptions`.
+ */
+import { join, relative, dirname, basename } from 'node:path';
+import { calibrate } from './calibration-store.js';
+// =====================================================================
+// PUBLIC: decomposeSlices (the 6-stage pure algorithm)
+// =====================================================================
+export async function decomposeSlices(rid, prdMarkdown, projectRoot, options = {}) {
+    const cg = options.codegraphRunner ?? defaultCodegraphRunner();
+    const ur = options.understandRunner ?? defaultUnderstandRunner();
+    const ier = options.importEdgeRunner ?? defaultImportEdgeRunner();
+    // ---------- Stage 0: Validate codegraph ----------
+    const cgStatus = await cg.status(projectRoot);
+    if (!cgStatus.indexed) {
+        throw new Error('peaks codegraph not initialised on this project. ' +
+            'Run `npx codegraph init` then `npx codegraph index` in ' +
+            projectRoot +
+            ' before invoking `peaks slice decompose`.');
+    }
+    // ---------- Read understand-anything ----------
+    const kg = await ur.read(projectRoot);
+    const understandAvailable = kg !== null;
+    // ---------- Stage 1: Work-unit resolution ----------
+    const acs = extractAcceptanceCriteria(prdMarkdown);
+    let workUnits = await resolveWorkUnits(rid, acs, cg, projectRoot);
+    // ---------- Stage 2: Dependency DAG ----------
+    const explicitFiles = workUnits.flatMap((w) => w.files);
+    const probeImports = await ier.importsOf(projectRoot, explicitFiles);
+    const fileSet = new Set(explicitFiles);
+    for (const e of probeImports) {
+        fileSet.add(e.from);
+        fileSet.add(e.to);
+    }
+    const allFiles = Array.from(fileSet);
+    // If no ACs but the import graph has files, create implicit WUs (one per file).
+    // This is the fallback path for the chain/diamond test cases.
+    if (workUnits.length === 0 && allFiles.length > 0) {
+        workUnits = allFiles.map((file, i) => ({
+            id: `F${i + 1}`,
+            label: basename(file),
+            files: [file],
+            loc: 110,
+            testsAdded: 0,
+            filePath: file,
+            candidates: [`file:${file}`]
+        }));
+    }
+    let codegraphAffectedCrossFile = false;
+    if (allFiles.length > 0) {
+        try {
+            const aff = await cg.affected(allFiles, projectRoot);
+            codegraphAffectedCrossFile = aff.totalDependentsTraversed > 0;
+        }
+        catch {
+            codegraphAffectedCrossFile = false;
+        }
+    }
+    const importEdges = await ier.importsOf(projectRoot, allFiles);
+    const depEdges = buildDependencyEdges(workUnits, importEdges, kg, projectRoot);
+    // ---------- Stage 3: SCC + critical path ----------
+    const nodeIds = workUnits.map((w) => w.id);
+    const scc = findSCCs(nodeIds, depEdges);
+    const criticalPath = findCriticalPath(workUnits, depEdges);
+    // ---------- Stage 4: Min-cut ----------
+    const minCut = findMinCut(workUnits, depEdges, criticalPath, kg);
+    // ---------- Stage 5+6: Partition + Estimate + Emit ----------
+    const parallelBatches = partitionIntoBatches(workUnits, depEdges, criticalPath);
+    const batchesWithEstimates = parallelBatches.map((b) => ({
+        ...b,
+        slices: b.slices.map((s) => ({
+            ...s,
+            estimate: estimateSlice(s, kg)
+        }))
+    }));
+    const totalSlices = batchesWithEstimates.reduce((sum, b) => sum + b.slices.length, 0);
+    const pickHint = totalSlices > 10
+        ? `slice count is ${totalSlices} (>10); split into multiple pick sessions for operator comfort`
+        : undefined;
+    const codegraphEnvelope = {
+        nodes: cgStatus.nodes,
+        edges: cgStatus.edges,
+        dbMB: cgStatus.dbMB,
+        freshness: cgStatus.freshness,
+        affectedCrossFile: codegraphAffectedCrossFile,
+        note: codegraphAffectedCrossFile
+            ? 'cross-file dependents resolved via codegraph.affected'
+            : 'codegraph.affected returned 0 cross-file dependents (v0.7.10 limitation); used real import edges'
+    };
+    const understandEnvelope = {
+        kgNodes: kg?.nodes.length ?? 0,
+        kgEdges: kg?.edges.length ?? 0,
+        available: understandAvailable,
+        fallback: understandAvailable ? 'semantic' : 'structural-only',
+        note: understandAvailable
+            ? 'read from .understand-anything/knowledge-graph.json'
+            : '.understand-anything/knowledge-graph.json not found; algorithm falls back to structural cuts'
+    };
+    return {
+        rid,
+        generatedAt: new Date().toISOString(),
+        codegraph: codegraphEnvelope,
+        understandAnything: understandEnvelope,
+        workUnits,
+        dependencyDAG: { edges: depEdges },
+        sccAnalysis: scc,
+        criticalPath,
+        minCutResult: minCut,
+        parallelBatches: batchesWithEstimates,
+        ...(pickHint !== undefined ? { pickHint } : {})
+    };
+}
+// =====================================================================
+// Stage 1 helpers
+// =====================================================================
+function extractAcceptanceCriteria(prd) {
+    const acs = [];
+    const lines = prd.split('\n');
+    let inAcSection = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (/^##\s+acceptance criteria/i.test(trimmed)) {
+            inAcSection = true;
+            continue;
+        }
+        if (inAcSection && /^##\s+/.test(trimmed)) {
+            break;
+        }
+        if (inAcSection && trimmed.length > 0) {
+            const cleaned = trimmed.replace(/^[-*]\s+/, '').replace(/^\d+\.\s+/, '');
+            acs.push(cleaned);
+        }
+    }
+    return acs;
+}
+async function resolveWorkUnits(_rid, acs, cg, projectRoot) {
+    if (acs.length === 0) {
+        return [];
+    }
+    const wus = [];
+    const seen = new Set();
+    for (let i = 0; i < acs.length; i++) {
+        const ac = acs[i];
+        const hits = await cg.query(ac, projectRoot);
+        const hit = matchAcToHit(ac, hits);
+        if (hit === null)
+            continue;
+        if (seen.has(hit.filePath))
+            continue;
+        seen.add(hit.filePath);
+        wus.push({
+            id: `W${i + 1}`,
+            label: hit.name,
+            files: [hit.filePath],
+            loc: hit.loc ?? 110,
+            testsAdded: 0,
+            filePath: hit.filePath,
+            candidates: [hit.id]
+        });
+    }
+    return wus;
+}
+function matchAcToHit(ac, hits) {
+    if (hits.length === 0)
+        return null;
+    const acLower = ac.toLowerCase();
+    for (const h of hits) {
+        const nameBase = basename(h.filePath, '.ts').replace(/\.tsx?$/, '').toLowerCase();
+        if (acLower.includes(nameBase)) {
+            return h;
+        }
+    }
+    return hits[0];
+}
+// =====================================================================
+// Stage 2 helpers
+// =====================================================================
+function buildDependencyEdges(wus, importEdges, kg, projectRoot) {
+    const fileToWu = new Map();
+    for (const wu of wus) {
+        for (const f of wu.files) {
+            fileToWu.set(f, wu.id);
+        }
+    }
+    const edges = [];
+    const seen = new Set();
+    const addEdge = (from, to, kind, weight, evidence, isSemantic, confidence) => {
+        if (from === to)
+            return;
+        const key = `${from}->${to}|${kind}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        edges.push({ from, to, kind, weight, evidence, isSemantic, confidence });
+    };
+    for (const imp of importEdges) {
+        let fromWu = fileToWu.get(imp.from);
+        let toWu = fileToWu.get(imp.to);
+        if (!fromWu) {
+            const resolved = resolveRelativeImport(projectRoot, imp.from, imp.evidence);
+            fromWu = fileToWu.get(resolved);
+        }
+        if (!toWu) {
+            const resolved = resolveRelativeImport(projectRoot, imp.from, imp.evidence);
+            toWu = fileToWu.get(resolved);
+        }
+        if (fromWu && toWu) {
+            addEdge(fromWu, toWu, 'imports', 10.0, imp.evidence, false, 'structural');
+        }
+    }
+    if (kg !== null) {
+        for (const e of kg.edges) {
+            if (e.type !== 'contains_flow' && e.type !== 'flow_step')
+                continue;
+            const fromNode = kg.nodes.find((n) => n.id === e.source);
+            const toNode = kg.nodes.find((n) => n.id === e.target);
+            if (!fromNode?.filePath || !toNode?.filePath)
+                continue;
+            const fromWu = fileToWu.get(fromNode.filePath);
+            const toWu = fileToWu.get(toNode.filePath);
+            if (fromWu && toWu && fromWu !== toWu) {
+                const weight = e.type === 'flow_step' ? 0.05 : 0.1;
+                addEdge(fromWu, toWu, e.type, weight, `understand-anything: ${e.type} ${e.source}->${e.target}`, true, 'semantic');
+            }
+        }
+    }
+    return edges;
+}
+function resolveRelativeImport(projectRoot, sourceFile, evidence) {
+    const match = /from\s+['"]([^'"]+)['"]/.exec(evidence);
+    if (!match)
+        return sourceFile;
+    const importPath = match[1];
+    if (!importPath.startsWith('.'))
+        return sourceFile;
+    const sourceDir = dirname(sourceFile);
+    const tsPath = importPath.replace(/\.js$/, '.ts').replace(/\.jsx$/, '.tsx');
+    return relative(projectRoot, join(projectRoot, sourceDir, tsPath));
+}
+// =====================================================================
+// Stage 3: Tarjan SCC + longest path
+// =====================================================================
+function findSCCs(nodeIds, edges) {
+    const adj = new Map();
+    for (const id of nodeIds)
+        adj.set(id, []);
+    for (const e of edges) {
+        const list = adj.get(e.from);
+        if (list && !list.includes(e.to))
+            list.push(e.to);
+    }
+    let index = 0;
+    const idx = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    const strongconnect = (v) => {
+        idx.set(v, index);
+        lowlink.set(v, index);
+        index++;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of adj.get(v) ?? []) {
+            if (!idx.has(w)) {
+                strongconnect(w);
+                lowlink.set(v, Math.min(lowlink.get(v) ?? 0, lowlink.get(w) ?? 0));
+            }
+            else if (onStack.has(w)) {
+                lowlink.set(v, Math.min(lowlink.get(v) ?? 0, idx.get(w) ?? 0));
+            }
+        }
+        if (lowlink.get(v) === idx.get(v)) {
+            const component = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                component.push(w);
+            } while (w !== v);
+            sccs.push(component);
+        }
+    };
+    for (const id of nodeIds) {
+        if (!idx.has(id))
+            strongconnect(id);
+    }
+    const trivial = [];
+    const nonTrivial = [];
+    for (const scc of sccs) {
+        if (scc.length === 1)
+            trivial.push(scc[0]);
+        else
+            nonTrivial.push(...scc);
+    }
+    let condensationEdges = 0;
+    for (const e of edges) {
+        if (!sameScc(sccs, e.from, e.to))
+            condensationEdges++;
+    }
+    return {
+        sccCount: sccs.length,
+        trivialSCCs: trivial,
+        nonTrivialSCCs: nonTrivial,
+        condensationEdges
+    };
+}
+function sameScc(sccs, a, b) {
+    for (const scc of sccs) {
+        if (scc.includes(a) && scc.includes(b))
+            return true;
+    }
+    return false;
+}
+function findCriticalPath(wus, edges) {
+    const locById = new Map();
+    for (const wu of wus) {
+        locById.set(wu.id, wu.loc);
+    }
+    const adj = new Map();
+    for (const wu of wus)
+        adj.set(wu.id, []);
+    for (const e of edges) {
+        const list = adj.get(e.from);
+        if (list)
+            list.push({ to: e.to, weight: locById.get(e.to) ?? 0 });
+    }
+    const indeg = new Map();
+    for (const wu of wus)
+        indeg.set(wu.id, 0);
+    for (const e of edges)
+        indeg.set(e.to, (indeg.get(e.to) ?? 0) + 1);
+    const queue = [];
+    for (const [id, d] of indeg)
+        if (d === 0)
+            queue.push(id);
+    const topoOrder = [];
+    while (queue.length > 0) {
+        const n = queue.shift();
+        topoOrder.push(n);
+        for (const { to } of adj.get(n) ?? []) {
+            indeg.set(to, (indeg.get(to) ?? 0) - 1);
+            if (indeg.get(to) === 0)
+                queue.push(to);
+        }
+    }
+    for (const wu of wus)
+        if (!topoOrder.includes(wu.id))
+            topoOrder.push(wu.id);
+    const dist = new Map();
+    const prev = new Map();
+    for (const wu of wus) {
+        dist.set(wu.id, locById.get(wu.id) ?? 0);
+        prev.set(wu.id, null);
+    }
+    for (const u of topoOrder) {
+        for (const { to, weight } of adj.get(u) ?? []) {
+            const newDist = (dist.get(u) ?? 0) + weight;
+            if (newDist > (dist.get(to) ?? 0)) {
+                dist.set(to, newDist);
+                prev.set(to, u);
+            }
+        }
+    }
+    let endNode = topoOrder[0];
+    let maxDist = -1;
+    for (const [id, d] of dist) {
+        if (d > maxDist) {
+            maxDist = d;
+            endNode = id;
+        }
+    }
+    const path = [];
+    let cur = endNode;
+    while (cur !== null) {
+        path.unshift(cur);
+        cur = prev.get(cur) ?? null;
+    }
+    const totalLoc = path.reduce((sum, id) => sum + (locById.get(id) ?? 0), 0);
+    const totalDeltaLoc = path.reduce((sum, id) => {
+        const wu = wus.find((w) => w.id === id);
+        return sum + (wu?.deltaLoc ?? wu?.loc ?? 0);
+    }, 0);
+    const edgeStrs = path.slice(0, -1).map((n, i) => `${n} -> ${path[i + 1]}`);
+    return {
+        nodes: path,
+        edges: edgeStrs,
+        totalLoc,
+        totalDeltaLoc,
+        rationale: `Longest path by sum of LoC across the dependency DAG; ${path.length} work units, ${totalLoc} LoC summed`
+    };
+}
+// =====================================================================
+// Stage 4: Min-cut
+// =====================================================================
+function findMinCut(_wus, edges, criticalPath, _kg) {
+    const cpSet = new Set(criticalPath.nodes);
+    const nonCpEdges = edges.filter((e) => !cpSet.has(e.from) || !cpSet.has(e.to));
+    const sorted = [...nonCpEdges].sort((a, b) => a.weight - b.weight);
+    const cutSet = sorted.filter((e) => e.weight < 0.5);
+    const partitions = [];
+    partitions.push({ name: 'critical-path', nodes: criticalPath.nodes });
+    // For v1, just label every non-CP WU as its own parallel partition
+    const remaining = Array.from(new Set(_wus.map((w) => w.id).filter((id) => !cpSet.has(id))));
+    let parallelIdx = 1;
+    for (const id of remaining) {
+        partitions.push({ name: `parallel-${parallelIdx++}`, nodes: [id] });
+    }
+    if (remaining.length === 0) {
+        partitions.push({ name: 'parallel-empty', nodes: [] });
+    }
+    return {
+        algorithm: 'v1 simplified min-cut: lowest-weight non-critical-path edges; full Stoer-Wagner in v2',
+        cutEdges: cutSet.map((e) => ({
+            from: e.from,
+            to: e.to,
+            kind: e.kind,
+            weight: e.weight,
+            isSemantic: e.isSemantic,
+            confidence: e.confidence
+        })),
+        partitions
+    };
+}
+// =====================================================================
+// Stage 5+6: Estimate + Partition
+// =====================================================================
+function estimateSlice(slice, _kg) {
+    const sampleSize = 0;
+    const complexitySum = 0;
+    return calibrate(complexitySum, slice.estimate.testCount, slice.estimate.locSum, sampleSize);
+}
+function partitionIntoBatches(wus, edges, _criticalPath) {
+    const upstream = new Map();
+    for (const wu of wus)
+        upstream.set(wu.id, []);
+    for (const e of edges) {
+        const list = upstream.get(e.to);
+        if (list && !list.includes(e.from))
+            list.push(e.from);
+    }
+    const placed = new Set();
+    const batches = [];
+    if (wus.length === 0)
+        return batches;
+    let currentBatch = [];
+    for (const wu of wus) {
+        if ((upstream.get(wu.id) ?? []).length === 0) {
+            currentBatch.push(wu.id);
+        }
+    }
+    batches.push({
+        batch: 1,
+        dependsOn: [],
+        slices: currentBatch.map((id) => wuToSlice(wus.find((w) => w.id === id))),
+        parallelizableWithinBatch: currentBatch.length > 1
+    });
+    for (const id of currentBatch)
+        placed.add(id);
+    let batchNum = 2;
+    let prevBatchNums = [1];
+    while (placed.size < wus.length) {
+        currentBatch = [];
+        for (const wu of wus) {
+            if (placed.has(wu.id))
+                continue;
+            const ups = upstream.get(wu.id) ?? [];
+            if (ups.every((u) => placed.has(u))) {
+                currentBatch.push(wu.id);
+            }
+        }
+        if (currentBatch.length === 0) {
+            for (const wu of wus) {
+                if (!placed.has(wu.id))
+                    currentBatch.push(wu.id);
+            }
+        }
+        batches.push({
+            batch: batchNum,
+            dependsOn: prevBatchNums,
+            slices: currentBatch.map((id) => wuToSlice(wus.find((w) => w.id === id))),
+            parallelizableWithinBatch: currentBatch.length > 1
+        });
+        for (const id of currentBatch)
+            placed.add(id);
+        prevBatchNums = [batchNum];
+        batchNum++;
+    }
+    return batches;
+}
+function wuToSlice(wu) {
+    return {
+        rid: `${wu.id}-slice`,
+        label: wu.label,
+        files: wu.files,
+        estimate: {
+            complexitySum: 0,
+            testCount: wu.testsAdded,
+            locSum: wu.loc,
+            minutesP50: 0,
+            minutesP90: 0,
+            confidence: 'low',
+            rationale: 'preliminary; replaced by calibrate() in estimateSlice'
+        },
+        semanticAnchor: `file:${wu.filePath}`
+    };
+}
+// Re-export the 3 default runner factories so external callers (CLI,
+// tests) keep importing from this module unchanged. The runners
+// (CLI-mode, real shell-outs) live in the sibling
+// `slice-decompose-runners.ts` module — see v2.18.3 file-split for
+// the rationale. Function signatures and behaviour are unchanged
+// (verbatim move).
+import { defaultCodegraphRunner, defaultUnderstandRunner, defaultImportEdgeRunner } from './slice-decompose-runners.js';
+export { defaultCodegraphRunner, defaultUnderstandRunner, defaultImportEdgeRunner } from './slice-decompose-runners.js';