@popoverai/dotrequirements 0.22.0 → 0.24.0

package/dist/codebase-to-spec/fan-out.js

@@ -0,0 +1,215 @@
+/**
+ * Specifier fan-out orchestrator.
+ *
+ * For each area in the outline, extract a slice, spawn a specifier worker,
+ * and write the resulting partial to the cache. Workers run in parallel up
+ * to a bounded concurrency limit. On per-area failure (no partial written,
+ * empty partial), the worker is retried once; on second failure, the area
+ * is recorded as failed for surfacing to the user.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1.2: bounded concurrent execution
+ * - CTS-SPEC-5: failed/empty specifier output is detected and retried
+ * - CTS-OBSERVE-2.0: failure details are logged with area name + cause
+ * - CTS-RESUME-1.2: existing non-empty partial means the specifier is skipped
+ */
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { extractSlice } from "./slice.js";
+import { runSpecifier } from "./specifier.js";
+export const DEFAULT_FAN_OUT_CONCURRENCY = 8;
+/**
+ * Convert an area name to a stable filesystem-safe identifier.
+ * E.g., "Reading & Editing Files" → "reading-editing-files"
+ */
+export function sanitizeAreaName(name) {
+    return (name
+        .replace(/[^A-Za-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase() || "area");
+}
+/**
+ * Run a bounded-concurrency loop over items. Workers pull items off a shared
+ * counter; at most `limit` workers run at a time.
+ */
+async function withLimit(items, limit, fn) {
+    let next = 0;
+    async function worker() {
+        while (true) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            await fn(items[i], i);
+        }
+    }
+    const workerCount = Math.min(Math.max(1, limit), items.length);
+    const workers = Array.from({ length: workerCount }, () => worker());
+    await Promise.all(workers);
+}
+function partialIsUsable(path) {
+    if (!existsSync(path))
+        return false;
+    try {
+        return statSync(path).size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run the fan-out: extract slices, invoke specifiers, retry on failure.
+ */
+export async function runFanOut(options) {
+    const { outline, fullPackPath, partialPathFor, slicePathFor, validateCommand, styleCheckCommand, addDirs, concurrency = DEFAULT_FAN_OUT_CONCURRENCY, runner, model, progress, } = options;
+    if (!existsSync(fullPackPath)) {
+        throw new Error(`Missing full pack at ${fullPackPath}`);
+    }
+    // Sanitization is lossy ("Read & Write" and "read/write" both become
+    // "read-write"). If two areas collide, they'd share a partial file path and
+    // silently overwrite each other downstream. Catch this up front.
+    const sanitizedNames = new Map();
+    for (const area of outline.areas) {
+        const key = sanitizeAreaName(area.name);
+        const bucket = sanitizedNames.get(key) ?? [];
+        bucket.push(area.name);
+        sanitizedNames.set(key, bucket);
+    }
+    const collisions = [...sanitizedNames.entries()].filter(([, names]) => names.length > 1);
+    if (collisions.length > 0) {
+        const detail = collisions
+            .map(([key, names]) => `  "${key}" ← ${names.map((n) => `"${n}"`).join(", ")}`)
+            .join("\n");
+        throw new Error(`Outline contains area names that collide after sanitization. Rename them so each produces a unique partial file path:\n${detail}`);
+    }
+    const outcomes = outline.areas.map((area) => ({
+        area,
+        status: "failed",
+        attempts: 0,
+        partialPath: partialPathFor(sanitizeAreaName(area.name)),
+    }));
+    // Ensure partials directory exists for each area.
+    for (const outcome of outcomes) {
+        mkdirSync(dirname(outcome.partialPath), { recursive: true });
+    }
+    await withLimit(outcomes, concurrency, async (outcome) => {
+        const sanitized = sanitizeAreaName(outcome.area.name);
+        const slicePath = slicePathFor(sanitized);
+        // CTS-RESUME-1.2: skip if a non-empty partial exists from a prior run.
+        if (partialIsUsable(outcome.partialPath)) {
+            outcome.status = "skipped-resume";
+            outcome.attempts = 0;
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `(resume) skipping ${outcome.area.name} — partial exists`,
+            });
+            return;
+        }
+        // Extract this area's slice from the full pack.
+        if (outcome.area.files.length === 0) {
+            // No files assigned — write a stub partial so compose has something.
+            writeFileSync(outcome.partialPath, "_(no files assigned to this area)_\n", "utf-8");
+            outcome.status = "failed";
+            outcome.attempts = 0;
+            outcome.failureCause = "no files assigned in outline";
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `!! ${outcome.area.name} has no files; marking as failed`,
+            });
+            return;
+        }
+        let sliceMatched = 0;
+        try {
+            const sliceResult = extractSlice(fullPackPath, slicePath, outcome.area.files);
+            sliceMatched = sliceResult.matched;
+        }
+        catch (err) {
+            outcome.failureCause = `slice extraction failed: ${err instanceof Error ? err.message : String(err)}`;
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `!! ${outcome.failureCause}`,
+            });
+            return;
+        }
+        if (sliceMatched === 0) {
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `(warning) slice for ${outcome.area.name} matched 0 files; specifier will need to fall back to full-pack reads`,
+            });
+        }
+        // Attempt 1
+        progress?.emit({
+            stage: "specify",
+            step: outcome.area.prefix,
+            message: `Running specifier for ${outcome.area.name} (attempt 1/2)`,
+        });
+        outcome.attempts = 1;
+        const r1 = await runSpecifier({
+            outline,
+            area: outcome.area,
+            slicePath,
+            fullPackPath,
+            partialPath: outcome.partialPath,
+            validateCommand,
+            styleCheckCommand,
+            addDirs,
+            runner,
+            model,
+        });
+        if (r1.wrotePartial) {
+            outcome.status = "completed";
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `${outcome.area.name} done (${r1.partialBytes} bytes)`,
+            });
+            return;
+        }
+        // Attempt 2 (retry once on no/empty partial)
+        progress?.emit({
+            stage: "specify",
+            step: outcome.area.prefix,
+            message: `!! ${outcome.area.name} produced no partial; retrying (attempt 2/2)`,
+        });
+        outcome.attempts = 2;
+        const r2 = await runSpecifier({
+            outline,
+            area: outcome.area,
+            slicePath,
+            fullPackPath,
+            partialPath: outcome.partialPath,
+            validateCommand,
+            styleCheckCommand,
+            addDirs,
+            runner,
+            model,
+        });
+        if (r2.wrotePartial) {
+            outcome.status = "completed";
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `${outcome.area.name} done on retry (${r2.partialBytes} bytes)`,
+            });
+            return;
+        }
+        // Two failures — record and continue. CTS-SPEC-5 says other areas still proceed.
+        outcome.status = "failed";
+        outcome.failureCause =
+            r2.exitCode !== 0
+                ? `specifier exited with code ${r2.exitCode}: ${r2.stderr.slice(0, 200)}`
+                : "specifier wrote no partial (or empty partial) on both attempts";
+        writeFileSync(outcome.partialPath, `_(missing partial — specifier failed after retry: ${outcome.failureCause})_\n`, "utf-8");
+        progress?.emit({
+            stage: "specify",
+            step: outcome.area.prefix,
+            message: `!! ${outcome.area.name} failed: ${outcome.failureCause}`,
+        });
+    });
+    const allSucceeded = outcomes.every((o) => o.status === "completed" || o.status === "skipped-resume");
+    return { outcomes, allSucceeded };
+}
+//# sourceMappingURL=fan-out.js.map

package/dist/codebase-to-spec/interactive.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Interactive / non-interactive mode detection and overwrite prompting.
+ *
+ * Requirements covered:
+ * - CTS-CLI-4: CLI distinguishes interactive and non-interactive invocation modes
+ * - CTS-PRESENT-2: Overwrites in interactive mode prompt the Engineer
+ * - CTS-PRESENT-3: Overwrites in non-interactive mode require an explicit flag
+ */
+export type OverwriteChoice = "overwrite" | "skip" | "merge";
+export interface InteractiveMode {
+    /** True when running in interactive mode (TTY on stdin, or --interactive forced). */
+    isInteractive: boolean;
+    /** What the engineer chose for a given path (only used in interactive mode). */
+    prompt: (path: string) => Promise<OverwriteChoice | "cancel">;
+}
+/**
+ * Detect interactive mode. Defaults to TTY detection on stdin; can be forced
+ * by the caller via the `force` argument.
+ *
+ * @param force 'interactive' or 'non-interactive' to override TTY detection.
+ */
+export declare function detectMode(force?: "interactive" | "non-interactive"): {
+    isInteractive: boolean;
+};
+/**
+ * Prompt the engineer for an overwrite decision in interactive mode.
+ * Returns the chosen action, or `'cancel'` if the engineer dismissed the prompt.
+ */
+export declare function promptOverwriteChoice(path: string): Promise<OverwriteChoice | "cancel">;
+//# sourceMappingURL=interactive.d.ts.map

package/dist/codebase-to-spec/interactive.js

@@ -0,0 +1,48 @@
+/**
+ * Interactive / non-interactive mode detection and overwrite prompting.
+ *
+ * Requirements covered:
+ * - CTS-CLI-4: CLI distinguishes interactive and non-interactive invocation modes
+ * - CTS-PRESENT-2: Overwrites in interactive mode prompt the Engineer
+ * - CTS-PRESENT-3: Overwrites in non-interactive mode require an explicit flag
+ */
+import prompts from "prompts";
+/**
+ * Detect interactive mode. Defaults to TTY detection on stdin; can be forced
+ * by the caller via the `force` argument.
+ *
+ * @param force 'interactive' or 'non-interactive' to override TTY detection.
+ */
+export function detectMode(force) {
+    if (force === "interactive")
+        return { isInteractive: true };
+    if (force === "non-interactive")
+        return { isInteractive: false };
+    // TTY detection
+    return { isInteractive: !!process.stdin.isTTY };
+}
+/**
+ * Prompt the engineer for an overwrite decision in interactive mode.
+ * Returns the chosen action, or `'cancel'` if the engineer dismissed the prompt.
+ */
+export async function promptOverwriteChoice(path) {
+    const response = await prompts({
+        type: "select",
+        name: "choice",
+        message: `Overwrite ${path}?`,
+        choices: [
+            { title: "Overwrite (replace the existing file)", value: "overwrite" },
+            { title: "Skip (leave the existing file untouched)", value: "skip" },
+            {
+                title: "Merge (keep both — append new requirements to existing)",
+                value: "merge",
+            },
+        ],
+        initial: 0,
+    });
+    if (response.choice === undefined) {
+        return "cancel";
+    }
+    return response.choice;
+}
+//# sourceMappingURL=interactive.js.map

package/dist/codebase-to-spec/outline-review-loop.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Outline review loop: planner → reviewer → revise → reviewer → ... → approved.
+ *
+ * The reviewer runs in a SINGLE stateful claude session across turns (so it
+ * can compare prior outlines to the latest one). The planner is stateless —
+ * each invocation is fresh.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-2: stateful reviewer session
+ * - CTS-PLAN-3: approved → proceed
+ * - CTS-PLAN-4: approved-with-revisions → one revision pass, then proceed
+ * - CTS-PLAN-5: requires-another-review → revision loop
+ * - CTS-PLAN-6: max-turns + convergence nudge
+ */
+import { type ClaudeRunner } from "./claude.js";
+import type { ProgressEmitter } from "./progress.js";
+import { type Outline, type OutlineReview } from "./schemas.js";
+export declare const DEFAULT_OUTLINE_LOOP_MAX_TURNS = 3;
+export interface OutlineReviewLoopOptions {
+    overviewPath: string;
+    addDirs: string[];
+    maxTurns?: number;
+    runner?: ClaudeRunner;
+    model?: string;
+    progress?: ProgressEmitter;
+    /** Override session id (for tests and reproducibility). Otherwise random. */
+    sessionId?: string;
+}
+export interface OutlineReviewLoopResult {
+    /** The final outline after the loop converges (or hits max-turns). */
+    outline: Outline;
+    /** Per-turn outline snapshots (turn 1 is the initial, then each revision). */
+    outlinesByTurn: Outline[];
+    /** Per-turn reviewer results. */
+    reviewsByTurn: OutlineReview[];
+    /** The final reviewer verdict. */
+    finalVerdict: OutlineReview["verdict"];
+    /** Number of review turns used (= length of reviewsByTurn). */
+    turnsUsed: number;
+    /** True if the loop hit max-turns without converging. */
+    hitMaxTurns: boolean;
+}
+/**
+ * Run the outline review loop end-to-end.
+ *
+ * Returns the final outline (after applying mechanical revisions if the
+ * verdict was `approved-with-revisions`), the per-turn trace, and the final
+ * verdict.
+ */
+export declare function runOutlineReviewLoop(options: OutlineReviewLoopOptions): Promise<OutlineReviewLoopResult>;
+//# sourceMappingURL=outline-review-loop.d.ts.map

package/dist/codebase-to-spec/outline-review-loop.js

@@ -0,0 +1,187 @@
+/**
+ * Outline review loop: planner → reviewer → revise → reviewer → ... → approved.
+ *
+ * The reviewer runs in a SINGLE stateful claude session across turns (so it
+ * can compare prior outlines to the latest one). The planner is stateless —
+ * each invocation is fresh.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-2: stateful reviewer session
+ * - CTS-PLAN-3: approved → proceed
+ * - CTS-PLAN-4: approved-with-revisions → one revision pass, then proceed
+ * - CTS-PLAN-5: requires-another-review → revision loop
+ * - CTS-PLAN-6: max-turns + convergence nudge
+ */
+import { randomUUID } from "node:crypto";
+import { runClaude } from "./claude.js";
+import { runInitialPlanner, runRevisingPlanner, } from "./planner.js";
+import { OUTLINE_REVIEWER_PROMPT } from "./prompts/outline-reviewer.js";
+import { OUTLINE_REVIEW_JSON_SCHEMA, parseOutlineReview, } from "./schemas.js";
+export const DEFAULT_OUTLINE_LOOP_MAX_TURNS = 3;
+function reviewerUserMessageInitial(overviewPath, outline) {
+    return [
+        `Initial outline review.`,
+        ``,
+        `The compressed packed codebase is at: ${overviewPath}`,
+        ``,
+        `## Outline`,
+        `\`\`\`json`,
+        JSON.stringify(outline, null, 2),
+        `\`\`\``,
+        ``,
+        `Read the codebase if you need to verify file paths or coverage gaps, then produce your critique JSON.`,
+    ].join("\n");
+}
+function reviewerUserMessageRevised(turn, overviewPath, outline, nudge) {
+    const parts = [
+        `Review turn ${turn}. The planner has revised the outline based on your prior feedback.`,
+        ``,
+    ];
+    if (nudge) {
+        parts.push(nudge, ``);
+    }
+    parts.push(`The codebase pack at ${overviewPath} is unchanged.`, ``, `## Revised outline`, `\`\`\`json`, JSON.stringify(outline, null, 2), `\`\`\``, ``, `Compare this outline to the prior one. Report on what was fixed, what is still open, and what (if anything) was introduced as a new issue. Then produce your critique JSON.`);
+    return parts.join("\n");
+}
+function convergenceNudge(turn, maxTurns) {
+    return `CONVERGENCE NUDGE: This is review turn ${turn} of ${maxTurns} maximum. Please prioritize convergence. Your job is still to only approve a genuinely-ready outline, but if it is close, lean toward \`approved-with-revisions\` over \`requires-another-review\`. Reserve \`requires-another-review\` for genuine structural problems that the planner has not addressed despite prior feedback.`;
+}
+async function callReviewer(args) {
+    const result = await args.runner({
+        systemPrompt: OUTLINE_REVIEWER_PROMPT,
+        userMessage: args.userMessage,
+        model: args.model,
+        tools: ["Read", "Grep"],
+        addDirs: args.addDirs,
+        jsonSchema: OUTLINE_REVIEW_JSON_SCHEMA,
+        session: {
+            kind: args.isFirstTurn ? "fresh" : "resume",
+            sessionId: args.sessionId,
+        },
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(`Outline reviewer failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
+    }
+    // On parse failure, retry the same turn once before failing.
+    // CTS-PLAN-2 requirement: "on validation failure the CLI logs the parse error
+    // and retries the same turn once before failing the loop"
+    try {
+        return parseOutlineReview(result.stdout);
+    }
+    catch (err) {
+        // Retry once
+        const retry = await args.runner({
+            systemPrompt: OUTLINE_REVIEWER_PROMPT,
+            userMessage: `${args.userMessage}\n\n(Your prior output failed schema validation: ${err instanceof Error ? err.message : String(err)}. Please try again, emitting JSON only.)`,
+            model: args.model,
+            tools: ["Read", "Grep"],
+            addDirs: args.addDirs,
+            jsonSchema: OUTLINE_REVIEW_JSON_SCHEMA,
+            session: { kind: "resume", sessionId: args.sessionId },
+        });
+        if (retry.exitCode !== 0) {
+            throw new Error(`Outline reviewer retry failed (exit ${retry.exitCode}): ${retry.stderr || retry.stdout}`);
+        }
+        return parseOutlineReview(retry.stdout);
+    }
+}
+/**
+ * Run the outline review loop end-to-end.
+ *
+ * Returns the final outline (after applying mechanical revisions if the
+ * verdict was `approved-with-revisions`), the per-turn trace, and the final
+ * verdict.
+ */
+export async function runOutlineReviewLoop(options) {
+    const { overviewPath, addDirs, maxTurns = DEFAULT_OUTLINE_LOOP_MAX_TURNS, runner = runClaude, model, progress, sessionId = randomUUID(), } = options;
+    const plannerCtx = { overviewPath, addDirs, runner, model };
+    // Turn 1 — initial planner + initial reviewer
+    progress?.emit({
+        stage: "plan",
+        step: "planner-initial",
+        message: "Generating initial outline",
+    });
+    const outline1 = await runInitialPlanner(plannerCtx);
+    const outlinesByTurn = [outline1];
+    const reviewsByTurn = [];
+    progress?.emit({
+        stage: "outline-review",
+        step: "turn-1",
+        message: `Reviewing initial outline (${outline1.areas.length} areas)`,
+    });
+    let currentOutline = outline1;
+    let review = await callReviewer({
+        runner,
+        sessionId,
+        isFirstTurn: true,
+        userMessage: reviewerUserMessageInitial(overviewPath, outline1),
+        addDirs,
+        model,
+    });
+    reviewsByTurn.push(review);
+    progress?.emit({
+        stage: "outline-review",
+        step: "turn-1",
+        message: `Verdict: ${review.verdict}`,
+        data: { verdict: review.verdict },
+    });
+    let turn = 1;
+    while (review.verdict === "requires-another-review" && turn < maxTurns) {
+        turn++;
+        progress?.emit({
+            stage: "plan",
+            step: `revise-turn-${turn}`,
+            message: "Revising outline based on critique",
+        });
+        currentOutline = await runRevisingPlanner(plannerCtx, currentOutline, review);
+        outlinesByTurn.push(currentOutline);
+        const nudge = turn >= maxTurns - 1 && turn !== maxTurns
+            ? convergenceNudge(turn, maxTurns)
+            : undefined;
+        progress?.emit({
+            stage: "outline-review",
+            step: `turn-${turn}`,
+            message: `Reviewing revised outline (turn ${turn}/${maxTurns})`,
+            data: { turn, maxTurns, nudge: !!nudge },
+        });
+        review = await callReviewer({
+            runner,
+            sessionId,
+            isFirstTurn: false,
+            userMessage: reviewerUserMessageRevised(turn, overviewPath, currentOutline, nudge),
+            addDirs,
+            model,
+        });
+        reviewsByTurn.push(review);
+        progress?.emit({
+            stage: "outline-review",
+            step: `turn-${turn}`,
+            message: `Verdict: ${review.verdict}`,
+            data: { verdict: review.verdict },
+        });
+    }
+    const hitMaxTurns = review.verdict === "requires-another-review" && turn >= maxTurns;
+    // If the verdict ended on approved-with-revisions, run the planner once
+    // more to apply the listed revisions. Same agent as the revise loop; the
+    // difference is that we proceed to fan-out instead of looping back to
+    // review.
+    if (review.verdict === "approved-with-revisions" &&
+        review.revisions.length > 0) {
+        progress?.emit({
+            stage: "plan",
+            step: "apply-revisions",
+            message: `Applying ${review.revisions.length} revision(s)`,
+        });
+        currentOutline = await runRevisingPlanner(plannerCtx, currentOutline, review);
+        outlinesByTurn.push(currentOutline);
+    }
+    return {
+        outline: currentOutline,
+        outlinesByTurn,
+        reviewsByTurn,
+        finalVerdict: review.verdict,
+        turnsUsed: turn,
+        hitMaxTurns,
+    };
+}
+//# sourceMappingURL=outline-review-loop.js.map

package/dist/codebase-to-spec/pack.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pack stage: produce compressed and uncompressed views of a codebase.
+ *
+ * Wraps Repomix's programmatic API to write:
+ * - `.dotrequirements-cache/overview.txt` — compressed (tree-sitter signatures)
+ * - `.dotrequirements-cache/source.txt` — uncompressed (full source for slices)
+ *
+ * Requirements covered:
+ * - CTS-PACK-1: Pack stage produces compressed and uncompressed views
+ * - CTS-PACK-2: Engineer can extend the ignore list per project
+ */
+import type { CachePaths } from "./cache.js";
+/**
+ * The curated default ignore list. These patterns are applied in addition to
+ * `.gitignore` and any project-level `.dotrequirements-ignore`.
+ *
+ * Sized to remove obvious non-behavioral noise: generated code, package
+ * manifests/lockfiles, vendored libraries, build artifacts, large binaries.
+ */
+export declare const DEFAULT_IGNORES: readonly string[];
+/**
+ * Read project-level ignore patterns from `.dotrequirements-ignore` (and
+ * `.dotreqignore` as a shorthand), if either exists. Returns an empty array if
+ * no file is present.
+ */
+export declare function readProjectIgnores(projectRoot: string): string[];
+export interface PackOptions {
+    projectRoot: string;
+    paths: CachePaths;
+    /** Optional scope path (subdir of projectRoot) to limit which files are packed. */
+    scope?: string;
+    /** Additional ignore patterns (beyond defaults and project-level). */
+    extraIgnores?: string[];
+}
+export interface PackResult {
+    overviewPath: string;
+    sourcePath: string;
+    /** Number of files included after ignores. */
+    fileCount: number;
+}
+/**
+ * Run Repomix twice over the same scope: once compressed, once uncompressed.
+ *
+ * We use Repomix's programmatic API rather than `npx repomix` so the CLI does
+ * not require a separate install and so we can control config precisely.
+ *
+ * NOTE: Repomix's TypeScript API is invoked via `runCli`. We invoke it as the
+ * library exposes it; the surface is small enough that this wraps cleanly.
+ */
+export declare function runPack(options: PackOptions): Promise<PackResult>;
+//# sourceMappingURL=pack.d.ts.map