nightralph 0.0.53 → 0.0.54

package/dist/review.js

@@ -0,0 +1,662 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import {
+  NOTES_PATH,
+  formatDate,
+  collectNotes,
+  ensureNotesIgnored,
+  appendEntry
+} from "./learnings.js";
+import { runTestCmd } from "./testcmd.js";
+import { commitProgress } from "./progress.js";
+import { runWithRetries } from "./retry.js";
+import {
+  createNamedWorktree,
+  deleteBranch,
+  removeWorktree,
+  commitDirty,
+  hasNewCommits,
+  isDirty,
+  hasChangesOutside,
+  headCommit,
+  isAncestor,
+  mergeBase
+} from "./worktree.js";
+import { mergeBranch } from "./merge.js";
+import {
+  readDocsRule,
+  installRule,
+  testGateRule,
+  LINT_RULE,
+  integrityRule,
+  CONFINEMENT_RULES,
+  commitRule,
+  notesRule,
+  agentsMdRule
+} from "./rules.js";
+const FINDINGS_FILE = "findings.md";
+const FINDINGS_PATH = `${dirname(NOTES_PATH)}/${FINDINGS_FILE}`;
+const NO_FINDINGS = "No findings.";
+const REVIEW_EXCLUDE = ".scratch";
+const REVIEW_MARKER = "---- REVIEW INSTRUCTIONS ----";
+const FIX_MARKER = "---- REVIEW FINDINGS ----";
+function reviewExcludeFor(repoRoot, reviewPath) {
+  let dir = dirname(reviewPath);
+  while (dirname(dir) !== dir) {
+    if (basename(dir) === ".scratch") {
+      const rel = relative(repoRoot, dir);
+      if (rel && !rel.startsWith("..")) return rel;
+      break;
+    }
+    dir = dirname(dir);
+  }
+  return REVIEW_EXCLUDE;
+}
+__name(reviewExcludeFor, "reviewExcludeFor");
+function reviewDiffCommand(from, to, exclude = REVIEW_EXCLUDE) {
+  return `git diff ${from}..${to} -- . ':(exclude)${exclude}'`;
+}
+__name(reviewDiffCommand, "reviewDiffCommand");
+function renderReviewPrompt(opts) {
+  return [
+    "---- SPEC CONTEXT ----",
+    opts.specBody,
+    "",
+    REVIEW_MARKER,
+    "You are reviewing work that autonomous agents merged into this branch, one ticket at a time. Review the combined change as a whole.",
+    "",
+    "The change to review:",
+    "",
+    `    ${reviewDiffCommand(opts.from, opts.to, opts.exclude)}`,
+    "",
+    "Follow these rules:",
+    "- Read any AGENTS.md in or above the directories the change touches, plus CONTEXT.md and the relevant docs/adr/ entries if they exist. Treat their contracts and the spec above as the standard the code must meet.",
+    "- Look for correctness bugs, missing or weak tests, and code that breaks a documented contract. Ignore style preferences.",
+    "- You may run the tests or the type checker to confirm a suspicion.",
+    "- Do NOT edit, stage, or commit code. Anything you change here is discarded.",
+    ...CONFINEMENT_RULES,
+    "",
+    `Write your findings to \`${FINDINGS_PATH}\` (create the directory), most severe first, in exactly this form:`,
+    "",
+    "- [ ] <one-line summary of the finding>",
+    "    <file:line, and a concrete input or state that goes wrong>",
+    "",
+    "If you find nothing worth fixing, write the single line: " + NO_FINDINGS,
+    "Never git add or commit that file; the orchestrator collects it.",
+    ""
+  ].join("\n");
+}
+__name(renderReviewPrompt, "renderReviewPrompt");
+const FIX_FAILURE_TEXT = {
+  install: "dependency install failed",
+  exit: "the agent exited with an error",
+  "no-commits": "the agent made no commits",
+  tests: "the test command failed after the agent finished",
+  merge: "the fix branch did not merge cleanly"
+};
+function findingLines(findings) {
+  return findings.flatMap((f) => [
+    `- [ ] ${f.summary}`,
+    ...f.detail ? f.detail.split("\n").map((l) => `    ${l}`) : []
+  ]);
+}
+__name(findingLines, "findingLines");
+function previousBlock(previous) {
+  if (!previous) return [];
+  return [
+    "---- PREVIOUS FIX ATTEMPT ----",
+    `It failed: ${FIX_FAILURE_TEXT[previous.reason]}.`,
+    previous.notes ?? "It left no notes.",
+    ""
+  ];
+}
+__name(previousBlock, "previousBlock");
+function renderFixPrompt(opts) {
+  return [
+    "---- SPEC CONTEXT ----",
+    opts.specBody,
+    "",
+    FIX_MARKER,
+    ...findingLines(opts.findings),
+    "",
+    ...previousBlock(opts.previous),
+    "---- AGENT INSTRUCTIONS ----",
+    "You are an autonomous coding agent. Fix the review findings above using /tdd.",
+    "",
+    "Follow these rules:",
+    readDocsRule("findings"),
+    "- Fix ONLY the listed findings. Do not fix unrelated problems you notice.",
+    ...installRule(opts.installCmd),
+    "- Use /tdd for every finding: write a failing test that shows the problem, then write only enough code to make it pass, then refactor.",
+    testGateRule(opts.testCmd, "fix"),
+    LINT_RULE,
+    integrityRule("finding"),
+    ...CONFINEMENT_RULES,
+    commitRule("finding"),
+    notesRule("finding", "fix"),
+    "- After fixing each finding, print a line: [x] <finding summary> (matching the summary text exactly).",
+    "- If a finding is wrong or cannot be fixed honestly, leave it unchecked and explain why in your notes file.",
+    agentsMdRule("fix"),
+    ""
+  ].join("\n");
+}
+__name(renderFixPrompt, "renderFixPrompt");
+const SENTINEL_PREFIX = "<!-- nightralph:review";
+const SENTINEL_RE = /^<!-- nightralph:review (.*) -->$/;
+const SHA_RE = /^[0-9a-f]{4,64}$/;
+const FIX_HEADING = "### Fix";
+const FINDING_RE = /^ ?[-*+]\s+\[([ xX])\]\s+(.+)$/;
+const REVIEW_STATUSES = [
+  "clean",
+  "fixed",
+  "unresolved",
+  "review-failed"
+];
+function isReviewStatus(value) {
+  return REVIEW_STATUSES.includes(value);
+}
+__name(isReviewStatus, "isReviewStatus");
+function collapse(s) {
+  return s.replace(/\s+/g, " ").trim();
+}
+__name(collapse, "collapse");
+function normalize(s) {
+  return collapse(s).toLowerCase();
+}
+__name(normalize, "normalize");
+function sanitize(text) {
+  return text.replace(
+    new RegExp(SENTINEL_PREFIX, "g"),
+    "<!-- nightralph-review"
+  );
+}
+__name(sanitize, "sanitize");
+function splitLines(text) {
+  return text.split("\n").map((line) => {
+    return line.endsWith("\r") ? line.slice(0, -1) : line;
+  });
+}
+__name(splitLines, "splitLines");
+function parseFindings(text) {
+  const findings = [];
+  const details = [];
+  for (const line of splitLines(text)) {
+    const m = line.match(FINDING_RE);
+    if (m) {
+      findings.push({
+        summary: collapse(m[2]),
+        detail: "",
+        checked: m[1] !== " "
+      });
+      details.push([]);
+    } else if (findings.length > 0 && line.trim()) {
+      details[details.length - 1].push(line.trim());
+    }
+  }
+  if (findings.length > 0) {
+    return findings.map((f, i) => {
+      return { ...f, detail: details[i].join("\n") };
+    });
+  }
+  const clean = splitLines(text).some((line) => {
+    return normalize(line) === NO_FINDINGS.toLowerCase();
+  });
+  return clean ? [] : null;
+}
+__name(parseFindings, "parseFindings");
+function markFixed(findings, completedItems) {
+  const done = new Set(completedItems.map(normalize));
+  return findings.map((f) => {
+    return { ...f, checked: done.has(normalize(f.summary)) };
+  });
+}
+__name(markFixed, "markFixed");
+function headline(input) {
+  const n = input.findings.length;
+  const fixed = input.findings.filter((f) => f.checked).length;
+  switch (input.status) {
+    case "clean":
+      return "no findings";
+    case "fixed":
+      return `${fixed} of ${n} fixed`;
+    case "unresolved":
+      return `${n} finding${n === 1 ? "" : "s"}, fix failed`;
+    case "review-failed":
+      return "review failed";
+    default: {
+      const _exhaustive = input.status;
+      return _exhaustive;
+    }
+  }
+}
+__name(headline, "headline");
+function renderFindings(input) {
+  if (input.status === "review-failed") {
+    return ["The reviewer left no usable findings file."];
+  }
+  if (input.findings.length === 0) return [NO_FINDINGS];
+  return input.findings.flatMap((f) => {
+    const box = f.checked ? "[x]" : "[ ]";
+    const detail = f.detail ? f.detail.split("\n").map((l) => `    ${sanitize(l)}`) : [];
+    return [`- ${box} ${sanitize(collapse(f.summary))}`, ...detail];
+  });
+}
+__name(renderFindings, "renderFindings");
+function renderFix(fix) {
+  if (!fix) return [];
+  return [
+    "",
+    FIX_HEADING,
+    `- attempts: ${fix.attempts} of ${fix.maxAttempts}`,
+    ...fix.effort ? [`- effort: ${fix.effort}`] : [],
+    `- agent exit code: ${fix.exitCode ?? "none"}`,
+    `- result: ${sanitize(fix.result)}`,
+    "",
+    fix.notes ? sanitize(fix.notes) : "The fixer left no notes."
+  ];
+}
+__name(renderFix, "renderFix");
+function renderReviewEntry(input) {
+  return [
+    `${SENTINEL_PREFIX} from=${input.from} to=${input.to} status=${input.status} -->`,
+    `## ${formatDate(input.now)} -- review ${input.from.slice(0, 7)}..${input.to.slice(0, 7)} -- ${headline(input)}`,
+    ...renderFindings(input),
+    ...renderFix(input.fix),
+    "---",
+    ""
+  ].join("\n");
+}
+__name(renderReviewEntry, "renderReviewEntry");
+function parseEntry(sentinel, bodyLines) {
+  const attrs = {};
+  for (const part of sentinel.split(/\s+/).filter(Boolean)) {
+    const idx = part.indexOf("=");
+    if (idx > 0) attrs[part.slice(0, idx)] = part.slice(idx + 1);
+  }
+  const { from, to, status } = attrs;
+  if (!from || !SHA_RE.test(from)) return null;
+  if (!to || !SHA_RE.test(to)) return null;
+  if (!status || !isReviewStatus(status)) return null;
+  const lines = [...bodyLines];
+  while (lines.length > 0 && !lines[lines.length - 1].trim()) {
+    lines.pop();
+  }
+  if (lines[lines.length - 1] === "---") lines.pop();
+  const fixAt = lines.indexOf(FIX_HEADING);
+  const findingLines2 = fixAt === -1 ? lines : lines.slice(0, fixAt);
+  return {
+    from,
+    to,
+    status,
+    findings: parseFindings(findingLines2.join("\n")) ?? [],
+    body: lines.join("\n").trim()
+  };
+}
+__name(parseEntry, "parseEntry");
+function parseReviewEntries(text) {
+  const entries = [];
+  let sentinel = null;
+  let body = [];
+  const flush = /* @__PURE__ */ __name(() => {
+    if (sentinel === null) return;
+    const entry = parseEntry(sentinel, body);
+    if (entry) entries.push(entry);
+  }, "flush");
+  for (const line of splitLines(text)) {
+    const m = line.match(SENTINEL_RE);
+    if (m) {
+      flush();
+      sentinel = m[1];
+      body = [];
+    } else if (sentinel !== null) {
+      body.push(line);
+    }
+  }
+  flush();
+  return entries;
+}
+__name(parseReviewEntries, "parseReviewEntries");
+function selectReviewBase(entries, opts) {
+  const last = [...entries].reverse().find((e) => {
+    return e.status !== "review-failed";
+  });
+  if (last && opts.isAncestor(last.to)) return last.to;
+  return opts.forkPoint ?? opts.launchCommit;
+}
+__name(selectReviewBase, "selectReviewBase");
+function renderReviewSummary(outcome, reviewPath) {
+  const see = ` -- see ${reviewPath}`;
+  const plural = outcome.findings === 1 ? "" : "s";
+  switch (outcome.status) {
+    case "skipped":
+      return null;
+    case "clean":
+      return `Review: no findings${see}`;
+    case "fixed":
+      return `Review: ${outcome.findings} finding${plural}, ${outcome.fixed} fixed${see}`;
+    case "unresolved":
+      return `Review: ${outcome.findings} finding${plural}, fix failed${see}`;
+    case "review-failed":
+      return `Review: the reviewer failed${see}`;
+    default: {
+      const _exhaustive = outcome.status;
+      return _exhaustive;
+    }
+  }
+}
+__name(renderReviewSummary, "renderReviewSummary");
+function logPath(logsDir, stem, attempt, ext) {
+  const suffix = attempt > 1 ? `.attempt${attempt}` : "";
+  return join(logsDir, `${stem}${suffix}${ext}`);
+}
+__name(logPath, "logPath");
+async function runStep(opts, deps, cmd, cwd, path) {
+  const result = await runTestCmd({
+    cmd,
+    cwd,
+    timeout: opts.timeout,
+    registry: deps.registry
+  });
+  writeFileSync(path, result.output);
+  return result.exitCode === 0;
+}
+__name(runStep, "runStep");
+async function discardWorktree(opts, wt) {
+  try {
+    await removeWorktree(wt.worktreePath, { force: true });
+    await deleteBranch(opts.repoRoot, wt.branchName);
+  } catch (err) {
+    opts.log(
+      `  Failed to remove ${wt.worktreePath}: ` + (err instanceof Error ? err.message : String(err))
+    );
+  }
+}
+__name(discardWorktree, "discardWorktree");
+async function runReviewer(opts, deps, range) {
+  return runWithRetries({
+    maxAttempts: opts.retries + 1,
+    retryDelay: opts.retryDelay,
+    agentCmd: opts.agentCmd,
+    effort: opts.effort,
+    label: "review",
+    log: opts.log
+  }, async (attempt, effort) => {
+    const wt = await createNamedWorktree({
+      repoRoot: opts.repoRoot,
+      repoName: opts.repoName,
+      baseBranch: opts.baseBranch,
+      name: "review"
+    });
+    try {
+      if (opts.installCmd && !await runStep(
+        opts,
+        deps,
+        opts.installCmd,
+        wt.worktreePath,
+        logPath(opts.logsDir, "review", attempt, ".install.log")
+      )) {
+        opts.log("  review: install failed");
+        return { result: null, stop: false };
+      }
+      ensureNotesIgnored(wt.worktreePath);
+      await deps.spawnAgent({
+        prompt: renderReviewPrompt({
+          specBody: opts.specBody,
+          ...range,
+          exclude: reviewExcludeFor(
+            opts.repoRoot,
+            opts.reviewPath
+          )
+        }),
+        agentCmd: opts.agentCmd,
+        model: opts.model,
+        timeout: opts.timeout,
+        logPath: logPath(opts.logsDir, "review", attempt, ".log"),
+        cwd: wt.worktreePath,
+        label: "review",
+        maxTurns: opts.maxTurns,
+        effort,
+        onLine: opts.log
+      });
+      const text = collectNotes(wt.worktreePath, FINDINGS_FILE);
+      const findings = text === null ? null : parseFindings(text);
+      if (findings === null) {
+        opts.log("  review: no usable findings file");
+      }
+      return { result: findings, stop: findings !== null };
+    } finally {
+      await discardWorktree(opts, wt);
+    }
+  });
+}
+__name(runReviewer, "runReviewer");
+async function runFixer(opts, deps, findings) {
+  const unchecked = findings.map((f) => ({ ...f, checked: false }));
+  let previous;
+  return runWithRetries({
+    maxAttempts: opts.retries + 1,
+    retryDelay: opts.retryDelay,
+    agentCmd: opts.agentCmd,
+    effort: opts.effort,
+    label: "review fix",
+    log: opts.log
+  }, async (attempt, effort) => {
+    const fail = /* @__PURE__ */ __name((reason, exitCode, notes) => {
+      previous = { reason, notes };
+      opts.log(`  review fix: ${FIX_FAILURE_TEXT[reason]}`);
+      return {
+        result: {
+          merged: false,
+          findings: unchecked,
+          attempts: attempt,
+          effort,
+          exitCode,
+          result: FIX_FAILURE_TEXT[reason],
+          notes
+        },
+        stop: false
+      };
+    }, "fail");
+    const wt = await createNamedWorktree({
+      repoRoot: opts.repoRoot,
+      repoName: opts.repoName,
+      baseBranch: opts.baseBranch,
+      name: "review-fix"
+    });
+    try {
+      if (opts.installCmd && !await runStep(
+        opts,
+        deps,
+        opts.installCmd,
+        wt.worktreePath,
+        logPath(
+          opts.logsDir,
+          "review-fix",
+          attempt,
+          ".install.log"
+        )
+      )) {
+        return fail("install", null, null);
+      }
+      ensureNotesIgnored(wt.worktreePath);
+      const agent = await deps.spawnAgent({
+        prompt: renderFixPrompt({
+          specBody: opts.specBody,
+          findings,
+          testCmd: opts.testCmd,
+          installCmd: opts.installCmd,
+          previous
+        }),
+        agentCmd: opts.agentCmd,
+        model: opts.model,
+        timeout: opts.timeout,
+        logPath: logPath(
+          opts.logsDir,
+          "review-fix",
+          attempt,
+          ".log"
+        ),
+        cwd: wt.worktreePath,
+        label: "review-fix",
+        maxTurns: opts.maxTurns,
+        effort,
+        onLine: opts.log
+      });
+      const notes = collectNotes(wt.worktreePath);
+      if (!agent.timedOut && agent.exitCode !== 0) {
+        return fail("exit", agent.exitCode, notes);
+      }
+      if (isDirty(wt.worktreePath)) {
+        await commitDirty(
+          wt.worktreePath,
+          "nightralph: auto-commit review fix remaining changes"
+        );
+      }
+      if (!hasNewCommits(
+        opts.repoRoot,
+        opts.baseBranch,
+        wt.branchName
+      )) {
+        return fail("no-commits", agent.exitCode, notes);
+      }
+      if (opts.testCmd === "") {
+        opts.log("  review fix: no test gate");
+      } else if (!await runStep(
+        opts,
+        deps,
+        opts.testCmd,
+        wt.worktreePath,
+        logPath(
+          opts.logsDir,
+          "review-fix",
+          attempt,
+          ".test.log"
+        )
+      )) {
+        return fail("tests", agent.exitCode, notes);
+      }
+      const merged = await mergeBranch(
+        opts.repoRoot,
+        wt.branchName
+      );
+      if (!merged.success) {
+        return fail(
+          "merge",
+          agent.exitCode,
+          [notes, merged.stderr].filter(Boolean).join("\n\n") || null
+        );
+      }
+      opts.log("  review fix: merged");
+      return {
+        result: {
+          merged: true,
+          findings: markFixed(findings, agent.completedItems),
+          attempts: attempt,
+          effort,
+          exitCode: agent.exitCode,
+          result: "merged",
+          notes
+        },
+        stop: true
+      };
+    } finally {
+      await discardWorktree(opts, wt);
+    }
+  });
+}
+__name(runFixer, "runFixer");
+function readReviewEntries(path) {
+  if (!existsSync(path)) return [];
+  return parseReviewEntries(readFileSync(path, "utf8"));
+}
+__name(readReviewEntries, "readReviewEntries");
+async function runReviewPass(opts, deps) {
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  const to = headCommit(opts.repoRoot);
+  const forkPoint = opts.forkedFrom ? mergeBase(opts.repoRoot, opts.forkedFrom, to) : null;
+  const from = selectReviewBase(readReviewEntries(opts.reviewPath), {
+    isAncestor: /* @__PURE__ */ __name((sha) => isAncestor(opts.repoRoot, sha, to), "isAncestor"),
+    forkPoint,
+    launchCommit: opts.launchCommit
+  });
+  const exclude = reviewExcludeFor(opts.repoRoot, opts.reviewPath);
+  if (!hasChangesOutside(opts.repoRoot, from, to, exclude)) {
+    opts.log("\nReview: nothing new to review");
+    return { status: "skipped", findings: 0, fixed: 0 };
+  }
+  opts.log(`
+Reviewing ${from.slice(0, 7)}..${to.slice(0, 7)}`);
+  const findings = await runReviewer(opts, deps, { from, to });
+  let entry;
+  if (findings === null) {
+    entry = {
+      from,
+      to,
+      status: "review-failed",
+      now: now(),
+      findings: []
+    };
+  } else if (findings.length === 0) {
+    entry = { from, to, status: "clean", now: now(), findings: [] };
+  } else {
+    opts.log(
+      `Review: ${findings.length} finding${findings.length === 1 ? "" : "s"}`
+    );
+    const fix = await runFixer(opts, deps, findings);
+    entry = {
+      from,
+      // A merged fix counts as reviewed
+      to: fix.merged ? headCommit(opts.repoRoot) : to,
+      status: fix.merged ? "fixed" : "unresolved",
+      now: now(),
+      findings: fix.findings,
+      fix: {
+        attempts: fix.attempts,
+        maxAttempts: opts.retries + 1,
+        effort: fix.effort,
+        exitCode: fix.exitCode,
+        result: fix.result,
+        notes: fix.notes
+      }
+    };
+  }
+  appendEntry(opts.reviewPath, renderReviewEntry(entry));
+  await commitProgress(
+    opts.repoRoot,
+    opts.reviewPath,
+    "nightralph: record review"
+  );
+  return {
+    status: entry.status,
+    findings: entry.findings.length,
+    fixed: entry.findings.filter((f) => f.checked).length
+  };
+}
+__name(runReviewPass, "runReviewPass");
+export {
+  FINDINGS_FILE,
+  FINDINGS_PATH,
+  FIX_FAILURE_TEXT,
+  FIX_MARKER,
+  NO_FINDINGS,
+  REVIEW_EXCLUDE,
+  REVIEW_MARKER,
+  REVIEW_STATUSES,
+  markFixed,
+  parseFindings,
+  parseReviewEntries,
+  readReviewEntries,
+  renderFixPrompt,
+  renderReviewEntry,
+  renderReviewPrompt,
+  renderReviewSummary,
+  reviewDiffCommand,
+  reviewExcludeFor,
+  runFixer,
+  runReviewPass,
+  runReviewer,
+  selectReviewBase
+};
+//# sourceMappingURL=review.js.map