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

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

@@ -1,246 +0,0 @@
-/**
- * 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/src/services/slice/granularity-decider.d.ts

@@ -1,37 +0,0 @@
-/**
- * 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/src/services/slice/granularity-decider.js

@@ -1,40 +0,0 @@
-/**
- * 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/src/services/slice/llm-arbitrator.d.ts

@@ -1,35 +0,0 @@
-/**
- * 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/src/services/slice/llm-arbitrator.js

@@ -1,63 +0,0 @@
-/**
- * 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/src/services/slice/multi-pass-orchestrator.d.ts

@@ -1,67 +0,0 @@
-/**
- * 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>;