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

package/dist/services/slice/cross-pass-edge-merger.js

@@ -0,0 +1,246 @@
+/**
+ * CrossPassEdgeMerger — Phase 2 of slice-topology-multipass (W2 T7).
+ *
+ * Produces `CrossPassEdge`s that span two adjacent decomposition passes by
+ * combining fast structural detectors with the `LLMArbitrator` fallback.
+ *
+ * Pipeline (per adjacent pass pair `(upper, lower)`):
+ *   1. Build a `path → upperSliceId` index of every file owned by `upper`.
+ *   2. For each lower slice, for each file in that slice:
+ *        a. type-shares      — `import type { ... } from '...'` resolves to an upper file.
+ *        b. import-re-export — `export ... from '...'` resolves to an upper file.
+ *        c. fixture-shares    — file is a test file AND `from '...'` resolves to an upper file.
+ *      Each match emits one `CrossPassEdge` with `confidence: 'structural'` and
+ *      `arbitratedBy: null`.
+ *   3. If a lower slice emitted NO static edges AND `opts.llmRunner` is provided AND
+ *      `llmCalls.length < opts.maxLlmCalls`, invoke `arbitrate(...)` once. On a
+ *      successful `{"depends": true}` response, emit one edge with
+ *      `kind: 'llm-arbitrated'`, `confidence: 'llm'`, and `arbitratedBy: <callId>`.
+ *   4. The budget is `opts.maxLlmCalls ?? 2`; once exhausted the merger returns
+ *      what it has accumulated and never crashes.
+ *
+ * Pass 3 is reserved for future use; the type allows `passNumber: 3` but v1 input
+ * never contains it. Pairs are processed left-to-right so edges are deterministic.
+ */
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { arbitrate } from './llm-arbitrator.js';
+// ---------------------------------------------------------------------------
+// Static-detection regexes
+// ---------------------------------------------------------------------------
+/** `import type { Foo } from '../upper/...'` and `import type * as Foo from '...'` */
+const TYPE_IMPORT_RE = /import\s+type\s+(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+['"]([^'"]+)['"]/g;
+/** `export { Bar } from '...'` / `export * from '...'` / `export type { Bar } from '...'`. */
+const RE_EXPORT_RE = /\bexport\s+(?:type\s+)?(?:\*|\{[^}]*\})\s+from\s+['"]([^'"]+)['"]/g;
+/** Any `from '...'` — used only for the fixture-shares rule (test files). */
+const ANY_FROM_RE = /\bfrom\s+['"]([^'"]+)['"]/g;
+const RESOLVE_EXTENSIONS = [
+    '',
+    '.ts',
+    '.tsx',
+    '.js',
+    '/index.ts',
+    '/index.tsx',
+    '/index.js'
+];
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export async function merge(passes, opts) {
+    const edges = [];
+    const llmCalls = [];
+    const maxLlm = opts.maxLlmCalls ?? 2;
+    const cacheDir = opts.cacheDir ?? join(opts.projectRoot, '.peaks/cache/arbitrator');
+    mkdirSync(cacheDir, { recursive: true });
+    for (let i = 0; i < passes.length - 1; i++) {
+        const upper = passes[i];
+        const lower = passes[i + 1];
+        // Index every upper file → the slice that owns it.
+        const upperFileToSlice = new Map();
+        for (const slice of upper.slices) {
+            for (const file of slice.files) {
+                upperFileToSlice.set(file, slice.id);
+            }
+        }
+        for (const slice of lower.slices) {
+            const emittedBefore = edges.length;
+            for (const file of slice.files) {
+                detectStaticEdges(file, slice.id, upper.passNumber, lower.passNumber, upperFileToSlice, edges);
+            }
+            const hadStaticEdge = edges.length > emittedBefore;
+            // LLM fallback — only when this slice emitted nothing AND we still have budget.
+            if (!hadStaticEdge && opts.llmRunner && llmCalls.length < maxLlm) {
+                await runLlmFallback(upper, slice, upper.passNumber, lower.passNumber, cacheDir, maxLlm, opts.llmRunner, edges, llmCalls);
+            }
+        }
+    }
+    return { edges, llmCalls };
+}
+// ---------------------------------------------------------------------------
+// Static detectors — append matched edges to `edges` in-place.
+// ---------------------------------------------------------------------------
+function detectStaticEdges(file, lowerSliceId, fromPass, toPass, upperFileToSlice, edges) {
+    if (!existsSync(file)) {
+        return;
+    }
+    const content = readFileSync(file, 'utf8');
+    // 1. type-shares — `import type ... from '...'`
+    forEachMatch(TYPE_IMPORT_RE, content, (spec, evidence) => {
+        const resolved = resolveImport(file, spec);
+        const upperSliceId = upperFileToSlice.get(resolved);
+        if (upperSliceId !== undefined) {
+            edges.push(buildEdge({
+                fromPass,
+                toPass,
+                fromSliceId: upperSliceId,
+                toSliceId: lowerSliceId,
+                kind: 'type-shares',
+                confidence: 'structural',
+                evidence,
+                arbitratedBy: null,
+            }));
+        }
+    });
+    // 2. import-re-export — `export ... from '...'`
+    forEachMatch(RE_EXPORT_RE, content, (spec, evidence) => {
+        const resolved = resolveImport(file, spec);
+        const upperSliceId = upperFileToSlice.get(resolved);
+        if (upperSliceId !== undefined) {
+            edges.push(buildEdge({
+                fromPass,
+                toPass,
+                fromSliceId: upperSliceId,
+                toSliceId: lowerSliceId,
+                kind: 'import-re-export',
+                confidence: 'structural',
+                evidence,
+                arbitratedBy: null,
+            }));
+        }
+    });
+    // 3. fixture-shares — test file imports an upper module.
+    if (isTestFile(file)) {
+        forEachMatch(ANY_FROM_RE, content, (spec, evidence) => {
+            const resolved = resolveImport(file, spec);
+            const upperSliceId = upperFileToSlice.get(resolved);
+            if (upperSliceId !== undefined) {
+                edges.push(buildEdge({
+                    fromPass,
+                    toPass,
+                    fromSliceId: upperSliceId,
+                    toSliceId: lowerSliceId,
+                    kind: 'fixture-shares',
+                    confidence: 'structural',
+                    evidence,
+                    arbitratedBy: null,
+                }));
+            }
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// LLM fallback
+// ---------------------------------------------------------------------------
+async function runLlmFallback(upper, lowerSlice, fromPass, toPass, cacheDir, maxCallsPerInvocation, llmRunner, edges, llmCalls) {
+    const upperSliceId = upper.slices[0]?.id ?? '<unknown-upper>';
+    const prompt = `Does upper slice "${upperSliceId}" depend on lower slice "${lowerSlice.id}"? ` +
+        `Reply with JSON of the shape {"depends": boolean, "reason": string}.`;
+    const promptHash = createHash('sha256').update(prompt).digest('hex');
+    const result = await arbitrate(prompt, {
+        cacheDir,
+        maxCallsPerInvocation,
+        perCallTimeoutMs: 5000,
+        llmRunner,
+    });
+    const isFailurePath = result.callId === 'budget-exhausted' ||
+        result.callId === 'timeout' ||
+        result.callId === 'error';
+    const confidence = isFailurePath ? 'low' : 'medium';
+    llmCalls.push({
+        callId: result.callId,
+        promptHash,
+        input: prompt,
+        output: result.output ?? '',
+        confidence,
+        tokens: result.tokens
+    });
+    if (result.output === null) {
+        return;
+    }
+    const parsed = parseDependsReply(result.output);
+    if (parsed?.depends === true) {
+        edges.push(buildEdge({
+            fromPass,
+            toPass,
+            fromSliceId: upperSliceId,
+            toSliceId: lowerSlice.id,
+            kind: 'llm-arbitrated',
+            confidence: 'llm',
+            evidence: `llm:${result.callId}: ${parsed.reason}`,
+            arbitratedBy: result.callId,
+        }));
+    }
+}
+function buildEdge(fields) {
+    return {
+        fromPass: fields.fromPass,
+        toPass: fields.toPass,
+        fromSliceId: fields.fromSliceId,
+        toSliceId: fields.toSliceId,
+        kind: fields.kind,
+        confidence: fields.confidence,
+        evidence: fields.evidence,
+        arbitratedBy: fields.arbitratedBy,
+    };
+}
+function forEachMatch(re, content, cb) {
+    re.lastIndex = 0;
+    let match;
+    while ((match = re.exec(content)) !== null) {
+        const spec = match[1];
+        cb(spec, match[0]);
+    }
+}
+/**
+ * Resolve an import specifier relative to the importing file. Tries common
+ * TypeScript extensions and returns the first candidate that exists on disk;
+ * if none exist (e.g. the file is virtual / generated), falls back to the
+ * `.ts` form so the caller can still match against its own index.
+ */
+function resolveImport(fromFile, spec) {
+    const base = isAbsolute(spec)
+        ? spec
+        : resolve(dirname(fromFile), spec);
+    for (const ext of RESOLVE_EXTENSIONS) {
+        const candidate = base + ext;
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return base + '.ts';
+}
+function isTestFile(filePath) {
+    return (filePath.endsWith('.test.ts') ||
+        filePath.endsWith('.test.tsx') ||
+        filePath.endsWith('.test.js') ||
+        /(^|[\\/])__tests__[\\/]/.test(filePath) ||
+        /(^|[\\/])tests[\\/]/.test(filePath));
+}
+function parseDependsReply(raw) {
+    // Accept either a pure JSON object or a fenced ```json { ... } ``` block.
+    const fence = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const candidate = fence ? fence[1] : raw;
+    try {
+        const obj = JSON.parse(candidate);
+        if (typeof obj.depends !== 'boolean')
+            return null;
+        return {
+            depends: obj.depends,
+            reason: typeof obj.reason === 'string' ? obj.reason : '',
+        };
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}

package/dist/services/slice/granularity-decider.d.ts

@@ -0,0 +1,37 @@
+/**
+ * GranularityDecider — pure function used by MultiPassOrchestrator to
+ * decide whether a WorkUnit should be subdivided further.
+ *
+ * No LLM dependency. Output is one of three branches:
+ *   - { subdivide: true }          — clearly over threshold, split now
+ *   - { subdivide: 'tie-break' }   — within 20% of threshold, defer to LLMArbitrator
+ *   - { subdivide: false }         — under threshold, stop subdividing
+ *
+ * The "tie-break" branch exists because large files (>80% of threshold)
+ * sometimes read like one cohesive unit; the orchestrator calls
+ * LLMArbitrator (which has project context) for that call.
+ */
+import type { WorkUnit } from './slice-decompose-types.js';
+export interface GranularityThresholds {
+    readonly maxFiles: number;
+    readonly maxLoc: number;
+}
+export type DeciderResult = {
+    readonly subdivide: true;
+    readonly reason: string;
+} | {
+    readonly subdivide: false;
+    readonly reason: string;
+} | {
+    readonly subdivide: 'tie-break';
+    readonly reason: string;
+};
+export declare const DEFAULT_THRESHOLDS: GranularityThresholds;
+/**
+ * Decide whether `wu` should be subdivided.
+ *
+ * Boundary semantics: `>` (strict). At the exact threshold (loc === maxLoc,
+ * files.length === maxFiles) the result is `subdivide: false`. This matches
+ * the spec: "threshold is exclusive; we only subdivide what is OVER it."
+ */
+export declare function shouldSubdivide(wu: WorkUnit, thresholds?: GranularityThresholds): DeciderResult;

package/dist/services/slice/granularity-decider.js

@@ -0,0 +1,40 @@
+/**
+ * GranularityDecider — pure function used by MultiPassOrchestrator to
+ * decide whether a WorkUnit should be subdivided further.
+ *
+ * No LLM dependency. Output is one of three branches:
+ *   - { subdivide: true }          — clearly over threshold, split now
+ *   - { subdivide: 'tie-break' }   — within 20% of threshold, defer to LLMArbitrator
+ *   - { subdivide: false }         — under threshold, stop subdividing
+ *
+ * The "tie-break" branch exists because large files (>80% of threshold)
+ * sometimes read like one cohesive unit; the orchestrator calls
+ * LLMArbitrator (which has project context) for that call.
+ */
+export const DEFAULT_THRESHOLDS = { maxFiles: 3, maxLoc: 400 };
+/**
+ * Decide whether `wu` should be subdivided.
+ *
+ * Boundary semantics: `>` (strict). At the exact threshold (loc === maxLoc,
+ * files.length === maxFiles) the result is `subdivide: false`. This matches
+ * the spec: "threshold is exclusive; we only subdivide what is OVER it."
+ */
+export function shouldSubdivide(wu, thresholds = DEFAULT_THRESHOLDS) {
+    const locExceeded = wu.loc > thresholds.maxLoc;
+    const filesExceeded = wu.files.length > thresholds.maxFiles;
+    if (locExceeded || filesExceeded) {
+        return {
+            subdivide: true,
+            reason: `wu ${wu.id}: loc=${wu.loc} files=${wu.files.length} exceeds threshold`,
+        };
+    }
+    const locBorderline = wu.loc > thresholds.maxLoc * 0.8;
+    const filesBorderline = wu.files.length > thresholds.maxFiles * 0.8;
+    if (locBorderline || filesBorderline) {
+        return {
+            subdivide: 'tie-break',
+            reason: `wu ${wu.id}: within 20% of threshold, needs LLM judgment`,
+        };
+    }
+    return { subdivide: false, reason: `wu ${wu.id}: under threshold` };
+}

package/dist/services/slice/llm-arbitrator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * LLMArbitrator — the focused LLM 兜底 (fallback) path used by
+ * `CrossPassEdgeMerger` (W2 T7) when structural heuristics cannot
+ * decide whether a cross-pass edge is real.
+ *
+ * Contract:
+ *   - `arbitrate(prompt, opts)` is the only public entry point.
+ *   - Cache key is `sha256(prompt)`; cache file is `<cacheDir>/<hash>.json`.
+ *   - Cache hit short-circuits: llmRunner.call is NOT invoked.
+ *   - A module-level counter (`callsThisInvocation`) caps live LLM calls
+ *     per orchestrator invocation. When exhausted, the result is
+ *     `{ output: null, callId: 'budget-exhausted', tokens: null }`.
+ *   - Live calls are raced against `perCallTimeoutMs`; on timeout, return
+ *     `{ output: null, callId: 'timeout', tokens: null }`.
+ *   - On any other error, return `{ output: null, callId: 'error', tokens: null }`.
+ *   - `resetArbitratorBudget()` zeros the module counter so the orchestrator
+ *     can re-arm it for the next invocation.
+ */
+import type { LlmRunner } from '../audit/audit-goal-service.js';
+export interface ArbitratorOptions {
+    readonly cacheDir: string;
+    readonly maxCallsPerInvocation: number;
+    readonly perCallTimeoutMs: number;
+    readonly llmRunner: LlmRunner;
+}
+export interface ArbitrateResult {
+    readonly output: string | null;
+    readonly callId: string;
+    readonly tokens: {
+        input: number;
+        output: number;
+    } | null;
+}
+export declare function resetArbitratorBudget(): void;
+export declare function arbitrate(prompt: string, opts: ArbitratorOptions): Promise<ArbitrateResult>;

package/dist/services/slice/llm-arbitrator.js

@@ -0,0 +1,63 @@
+/**
+ * LLMArbitrator — the focused LLM 兜底 (fallback) path used by
+ * `CrossPassEdgeMerger` (W2 T7) when structural heuristics cannot
+ * decide whether a cross-pass edge is real.
+ *
+ * Contract:
+ *   - `arbitrate(prompt, opts)` is the only public entry point.
+ *   - Cache key is `sha256(prompt)`; cache file is `<cacheDir>/<hash>.json`.
+ *   - Cache hit short-circuits: llmRunner.call is NOT invoked.
+ *   - A module-level counter (`callsThisInvocation`) caps live LLM calls
+ *     per orchestrator invocation. When exhausted, the result is
+ *     `{ output: null, callId: 'budget-exhausted', tokens: null }`.
+ *   - Live calls are raced against `perCallTimeoutMs`; on timeout, return
+ *     `{ output: null, callId: 'timeout', tokens: null }`.
+ *   - On any other error, return `{ output: null, callId: 'error', tokens: null }`.
+ *   - `resetArbitratorBudget()` zeros the module counter so the orchestrator
+ *     can re-arm it for the next invocation.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const SYSTEM_PROMPT = 'You are a focused technical arbitrator.';
+let callsThisInvocation = 0;
+export function resetArbitratorBudget() {
+    callsThisInvocation = 0;
+}
+export async function arbitrate(prompt, opts) {
+    const promptHash = createHash('sha256').update(prompt).digest('hex');
+    const cacheFile = join(opts.cacheDir, `${promptHash}.json`);
+    if (existsSync(cacheFile)) {
+        const cached = JSON.parse(readFileSync(cacheFile, 'utf8'));
+        return {
+            output: cached.output,
+            callId: `cache:${promptHash.slice(0, 12)}`,
+            tokens: null
+        };
+    }
+    if (callsThisInvocation >= opts.maxCallsPerInvocation) {
+        return { output: null, callId: 'budget-exhausted', tokens: null };
+    }
+    try {
+        const result = await Promise.race([
+            opts.llmRunner.call(SYSTEM_PROMPT, prompt, { maxTokens: 1000 }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), opts.perCallTimeoutMs))
+        ]);
+        callsThisInvocation++;
+        mkdirSync(opts.cacheDir, { recursive: true });
+        writeFileSync(cacheFile, JSON.stringify({ output: result.output, cachedAt: new Date().toISOString() }));
+        return {
+            output: result.output,
+            callId: `live:${promptHash.slice(0, 12)}`,
+            tokens: result.tokens
+        };
+    }
+    catch (err) {
+        const message = err.message;
+        return {
+            output: null,
+            callId: message === 'timeout' ? 'timeout' : 'error',
+            tokens: null
+        };
+    }
+}

package/dist/services/slice/multi-pass-orchestrator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * MultiPassOrchestrator — Phase 2 of slice-topology-multipass (W2 T9).
+ *
+ * Top-level orchestrator that runs the existing 6-stage algorithm
+ * (`decomposeSlices`) at service-level and/or file-level granularity, then
+ * stitches the passes together with `merge` to produce a v2
+ * `DecompositionResultV2` with cross-pass edges.
+ *
+ * Granularity semantics:
+ *   - 'service': Pass 1 only. Each workUnit becomes a SliceV2 with
+ *                granularity='service' and parentSliceId=null.
+ *   - 'file':    Pass 2 only. `decomposeSlices` is called once on the full
+ *                scope (no parent subdivision). Each workUnit becomes a
+ *                SliceV2 with granularity='file' and parentSliceId=null.
+ *   - 'both':    Pass 1 + N Pass 2 (one per parent). Pass 2 runs for every
+ *                Pass 1 slice without decider filtering.
+ *   - 'auto':    Same as 'both' but Pass 2 only runs for parents where
+ *                `shouldSubdivide(wu).subdivide !== false` (both `true` and
+ *                `'tie-break'` qualify).
+ *
+ * Granularity-mapping approach (see pre-flight note in the task spec):
+ *   Approach 1 — pass-through with post-hoc filter. The 6-stage algorithm
+ *   (`decomposeSlices`) does NOT accept a `granularity` or `scopeFilter`
+ *   option, and the pre-flight note recommends NOT extending `DecomposeOptions`
+ *   (surgical change rule). We therefore:
+ *     1. Pass the full `opts` (including the orchestrator-only `granularity`
+ *        and `llmRunner` fields) through to `decomposeSlices`; the algorithm
+ *        ignores the extra fields.
+ *     2. Filter Pass 2 `result.workUnits` post-hoc so each Pass 2 result
+ *        only contains files inside the parent slice's file scope.
+ *
+ * Cross-pass edges are produced by `merge` whenever there are ≥2 passes.
+ * The merger handles both static detection (type-shares, fixture-shares,
+ * import-re-export — runs UNCONDITIONALLY) and the LLM fallback path (only
+ * when `opts.llmRunner` is provided). Without an llmRunner the orchestrator
+ * still gets statically-detected cross-pass edges; only `llmArbitrations`
+ * stays empty.
+ *
+ * @see ./slice-decompose-service.ts  — the 6-stage algorithm (reused as-is)
+ * @see ./granularity-decider.ts      — subdivide decision
+ * @see ./cross-pass-edge-merger.ts   — cross-pass edge detection
+ * @see ./llm-arbitrator.ts           — LLM fallback for cross-pass edges
+ * @see ./slice-topology-types.ts     — DecompositionResultV2, PassResult, etc.
+ */
+import type { LlmRunner } from '../audit/audit-goal-service.js';
+import type { DecomposeOptions } from './slice-decompose-types.js';
+import type { DecompositionResultV2 } from './slice-topology-types.js';
+export type Granularity = 'service' | 'file' | 'both' | 'auto';
+export interface MultiPassOptions extends DecomposeOptions {
+    /** Service-level vs file-level vs both. Defaults to `'both'`. */
+    readonly granularity?: Granularity;
+    /** Optional LLM runner; when present, cross-pass edges are computed via `merge`. */
+    readonly llmRunner?: LlmRunner;
+}
+/**
+ * Run the multi-pass decomposition algorithm and return a v2 result.
+ *
+ * 1. Reset the LLM arbitrator budget for this invocation.
+ * 2. Run Pass 1 (service-level) if granularity includes 'service'.
+ * 3. Run Pass 2 (file-level) — for every qualifying parent in 'both'/'auto',
+ *    or once on the full scope in 'file'-only mode.
+ * 4. Compute cross-pass edges via `merge` whenever there are ≥2 passes
+ *    (static detection runs unconditionally; LLM fallback only when an
+ *    llmRunner is supplied).
+ * 5. Return a `DecompositionResultV2` with `partial: false`.
+ */
+export declare function decompose(rid: string, prdMarkdown: string, projectRoot: string, opts?: MultiPassOptions): Promise<DecompositionResultV2>;