@nathapp/nax 0.77.2 → 0.77.3

package/flows/nax-finish/commit-message.ts

@@ -23,10 +23,74 @@ const SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW"] as const;
 /** How much gate output to quote in the body before it stops being a commit message. */
 const MAX_GATE_OUTPUT_LINES = 20;
 
+/**
+ * Markers a test runner uses to introduce a failing case, worst-supported-first.
+ *
+ * A heuristic, deliberately: nax orchestrates polyglot repos, so this cannot be
+ * one runner's format. Each entry is the literal token that precedes the test's
+ * name — bun/jest `(fail)`, go `--- FAIL:`, pytest `FAILED`, and the tick-style
+ * reporters. Nothing downstream depends on a match; a miss just falls back to
+ * the output tail, which is what shipped before.
+ */
+const FAILURE_MARKERS = ["(fail)", "--- FAIL:", "FAILED ", "FAIL ", "✗ ", "× "];
+
+/** How many failing test names to name before the message stops being a commit message. */
+const MAX_NAMED_FAILURES = 10;
+
+/**
+ * Strip machine-local filesystem layout out of text bound for shipped history.
+ *
+ * Two passes, because the two cases differ: a path under the repo is meaningful
+ * once made relative, while a path outside it is noise no reader of the commit
+ * can act on. The home-directory pattern catches what remains — runner output
+ * routinely quotes absolute paths from outside the repo (caches, toolchains).
+ */
+function redactPaths(text: string, workdir?: string): string {
+  const withoutRepo = workdir ? text.split(`${workdir}/`).join("") : text;
+  return withoutRepo.replace(/(?:\/Users\/|\/home\/)[^/\s)]+\//g, "~/");
+}
+
+/**
+ * The names of the tests that actually failed, in output order.
+ *
+ * This is the whole point of the change: the body used to be the last 20 lines
+ * of runner stdout, and a suite whose *passing* tests write to stderr pushes the
+ * real failure out of that window — so the commit named a stack trace from a
+ * test that passed (#1506).
+ */
+function failingTestNames(output: string): string[] {
+  const names: string[] = [];
+  for (const line of output.split("\n")) {
+    const trimmed = line.trim();
+    const marker = FAILURE_MARKERS.find((m) => trimmed.startsWith(m));
+    if (!marker) continue;
+    // Drop bun's trailing `[0.12ms]` timing — it is noise in a commit message
+    // and makes otherwise-identical messages differ between runs.
+    const name = trimmed
+      .slice(marker.length)
+      .replace(/\s*\[[\d.]+m?s\]$/, "")
+      .trim();
+    if (name) names.push(name);
+  }
+  // Say so when the list is cut short. A bare list of ten reads as "ten tests
+  // failed", and a reader who acts on that count is acting on a truncation.
+  if (names.length > MAX_NAMED_FAILURES) {
+    const dropped = names.length - MAX_NAMED_FAILURES;
+    return [...names.slice(0, MAX_NAMED_FAILURES), `...and ${dropped} more failing test(s)`];
+  }
+  return names;
+}
+
 interface MessageCtx {
   outputs: Record<string, unknown>;
 }
 
+/** Options carrying what the message builder cannot read off `ctx.outputs`. */
+interface MessageOptions {
+  /** Absolute repo root, used to rewrite quoted paths as repo-relative. */
+  workdir?: string;
+}
+
 interface PhaseOutputs {
   findings?: Finding[];
   failing?: string[];
@@ -88,20 +152,30 @@ function subjectFor(phase: FinishPhase, ctx: MessageCtx): string {
   return findings.length > 0 ? reviewSubject(phase, findings) : `apply ${phase} review fixes`;
 }
 
-function bodyFor(phase: FinishPhase, ctx: MessageCtx): string[] {
+/**
+ * What to quote from a runner's output: the failing test names if they can be
+ * identified, otherwise the tail, as before.
+ *
+ * Never both. Naming the failures *and* pasting the tail reproduces the noise
+ * this replaces, and the tail is the weaker signal whenever the names exist.
+ */
+function runnerEvidence(output: string, opts: MessageOptions): string {
+  const clean = redactPaths(output, opts.workdir).trim();
+  const names = failingTestNames(clean);
+  if (names.length > 0) return ["Failed tests:", ...names.map((n) => `- ${n}`)].join("\n");
+  return clean.split("\n").slice(-MAX_GATE_OUTPUT_LINES).join("\n");
+}
+
+function bodyFor(phase: FinishPhase, ctx: MessageCtx, opts: MessageOptions): string[] {
   if (phase === "gate") {
     const gate = outputsFor(ctx, "quality_gates");
     const failing = gate.failing ?? [];
-    const tail = (gate.output ?? "").trim().split("\n").slice(-MAX_GATE_OUTPUT_LINES).join("\n");
-    return [...(failing.length > 0 ? [`Failing: ${failing.join(", ")}`] : []), ...(tail ? [tail] : [])];
+    const evidence = runnerEvidence(gate.output ?? "", opts);
+    return [...(failing.length > 0 ? [`Failing: ${failing.join(", ")}`] : []), ...(evidence ? [evidence] : [])];
   }
   if (phase === "acceptance") {
-    const tail = (outputsFor(ctx, "acceptance").output ?? "")
-      .trim()
-      .split("\n")
-      .slice(-MAX_GATE_OUTPUT_LINES)
-      .join("\n");
-    return tail ? [tail] : [];
+    const evidence = runnerEvidence(outputsFor(ctx, "acceptance").output ?? "", opts);
+    return evidence ? [evidence] : [];
   }
   const findings = findingsFor(ctx, phase);
   if (findings.length === 0) return [];
@@ -129,8 +203,13 @@ function phaseLabel(phase: FinishPhase): string {
  * described is still a commit that must happen — failing here would strand the
  * fix uncommitted and reintroduce the stale-diff bug (#1397).
  */
-export function buildFixCommitMessage(phase: FinishPhase, feature: string, ctx: MessageCtx): string {
+export function buildFixCommitMessage(
+  phase: FinishPhase,
+  feature: string,
+  ctx: MessageCtx,
+  opts: MessageOptions = {},
+): string {
   const subject = truncate(`fix(${feature}): ${subjectFor(phase, ctx)}`);
-  const body = bodyFor(phase, ctx);
+  const body = bodyFor(phase, ctx, opts);
   return [subject, ...body, `nax-finish: ${phaseLabel(phase)} fixes`].join("\n\n");
 }

package/flows/nax-finish/nax-finish.flow.ts

@@ -34,7 +34,8 @@
  * - `commit_gate` re-enters `review_quality` when its fix touched non-test code
  *   — the gate loop was previously the one editing loop whose output only ever
  *   faced mechanical checks. A test-only fix skips the re-review by explicit
- *   cost tradeoff; see `gateCommitRoute` for why that is a known hole.
+ *   cost tradeoff; see `gateCommitRoute` for why that is a known hole. The skip
+ *   records `review-skipped`, so it is visible in the audit.
  * - Every `commit_*` node appends its round to the finish-audit trail as it
  *   happens, rather than a terminal node reconstructing them from
  *   `ctx.state.steps`. Appending live is what makes the trail survive a flow
@@ -50,6 +51,7 @@ import {
   _contextDeps,
   amendPrBodyNode,
   appendRound,
+  buildCommitRound,
   buildEscalationComment,
   commitAndPush,
   commitFixes,
@@ -63,6 +65,7 @@ import {
   postEscalation,
   preflight,
   resolveFeature,
+  routeReviewAndRecord,
   runAcceptanceGate,
   runQualityGates,
   writeResult,
@@ -70,7 +73,7 @@ import {
 import type { Forge } from "./steps/forge";
 import { _prBodyDeps, buildFinishBody, buildFinishTitle } from "./steps/pr-body";
 import type { FinishInput, FinishPhase, FinishResult, ReviewVerdict } from "./types";
-import { MAX_FIX_ATTEMPTS, parseFixVerdict, parseReviewVerdict, repromptCount, routeReview } from "./verdict";
+import { MAX_FIX_ATTEMPTS, parseFixVerdict, parseReviewVerdict, repromptCount } from "./verdict";
 
 /**
  * Disabled only on an explicit "0". An unset variable means enabled, so a flow
@@ -153,7 +156,7 @@ async function acceptanceGateNode(ctx: {
  *   The defect that motivated the re-entry (rs-stock `b6fb66dd`) was itself
  *   test-only — 8 copy-pasted stubs across 3 test files — so this route would
  *   not have caught it. Widen it here if test-quality regressions start
- *   shipping.
+ *   shipping — the audit's `review-skipped` rounds are the evidence.
  * - `changed` — production code was touched, or the paths could not be
  *   classified at all. "Cannot classify" reviews rather than skips.
  */
@@ -202,30 +205,32 @@ function commitFixNode(phase: FinishPhase) {
       // PR opens, and a hook failure here would kill the flow mid-loop.
       const { committed, shaBefore, shaAfter } = await commitFixes(
         i.workdir,
-        buildFixCommitMessage(phase, i.feature, messageCtx),
+        buildFixCommitMessage(phase, i.feature, messageCtx, { workdir: i.workdir }),
         { skipHooks: true },
       );
-      await appendRound(i, {
-        ts: new Date().toISOString(),
-        phase,
-        attempt: fixAttemptCount(ctx, `fix_${phase}`),
-        committed,
-        findings: findingsOf(ctx, phase),
-        ...(phase === "gate" ? { failing: gateOutputs(ctx).failing ?? [] } : {}),
-        // Carry `shaAfter` onto committed rounds only: a no-op round has no
-        // commit, so no SHA to record — keeping the field absent (rather than
-        // null/undefined) lets the result-file reader distinguish "no commit"
-        // from "record lost".
-        ...(committed && shaAfter ? { sha: shaAfter } : {}),
-      });
-      // Only `commit_gate` routes on this; the other phases have unconditional
-      // edges and ignore it.
+      // Routed BEFORE the round is recorded: `buildCommitRound` needs the
+      // successor to tell an owed-but-skipped re-review from a phase that never
+      // had a reviewer. Only `commit_gate` routes on this; the other phases have
+      // unconditional edges and ignore it.
       const route =
         phase === "gate"
           ? await gateCommitRoute(i, committed, shaAfter, loadCtxOf(ctx).testFileRegex ?? [])
           : committed
             ? "changed"
             : "unchanged";
+      await appendRound(
+        i,
+        buildCommitRound({
+          phase,
+          attempt: fixAttemptCount(ctx, `fix_${phase}`),
+          committed,
+          route,
+          findings: findingsOf(ctx, phase),
+          failing: phase === "gate" ? (gateOutputs(ctx).failing ?? []) : undefined,
+          shaAfter,
+          now: new Date().toISOString(),
+        }),
+      );
       return { committed, route, shaBefore, shaAfter };
     },
   };
@@ -286,7 +291,7 @@ export default defineFlow({
     },
     route_spec: {
       nodeType: "compute",
-      run: (ctx) => routeReview(ctx, "spec"),
+      run: (ctx) => routeReviewAndRecord(ctx, "spec"),
     },
     fix_spec: {
       nodeType: "acp",
@@ -312,7 +317,7 @@ export default defineFlow({
     },
     route_quality: {
       nodeType: "compute",
-      run: (ctx) => routeReview(ctx, "quality"),
+      run: (ctx) => routeReviewAndRecord(ctx, "quality"),
     },
     fix_quality: {
       nodeType: "acp",

package/flows/nax-finish/pr-template-merge.ts

@@ -0,0 +1,253 @@
+/**
+ * Merge nax's generated PR/MR body into the repository's own PR template.
+ *
+ * ## Why this exists
+ *
+ * `gh pr create --body` / `glab mr create --description` suppress the repo's
+ * template, so a generated body has to account for it. The first attempt
+ * appended the template verbatim after the generated content, which shipped a
+ * *blank form* below a filled one: placeholder comments, a dangling `Closes #`,
+ * duplicated headings, and an unchecked "`bun test` passes" box sitting under a
+ * Verification section that already said the gates were green (nax#1504).
+ *
+ * A PR template is an input form, not decoration. So the template is treated as
+ * **shape** and nax's content as **fill**:
+ *
+ * - a template heading nax can fill  → keep the heading, replace its body
+ * - a template heading nax cannot    → drop it (`merge`) or empty it (`strict`)
+ * - nax content with no home         → append under nax's own heading
+ *
+ * The governing invariant is **never emit a field that was not filled**. That
+ * is the same rule `buildFinishBody` already followed for its own sections
+ * (nax#1477 forbids a bare heading with nothing under it); this module extends
+ * it to template-derived text. `strict` mode is the one deliberate exception,
+ * for repos whose CI asserts a set of headings exists.
+ *
+ * ## Why deterministic
+ *
+ * Placement is decided by a heading-alias table, not by a model. The facts in
+ * the body — gate results, story counts, diffstat, review rounds — stay a pure
+ * string join, which is what keeps a finish body greppable in PR history. A
+ * repo whose headings the table does not know loses nothing: its sections are
+ * dropped and nax's own headings are used instead, and `sectionMap` pins the
+ * mapping explicitly when a team wants its headings honoured.
+ *
+ * Lives under `flows/` (and is imported from `src/` via `@flows/*`, not
+ * re-implemented) because `flows/` is the more constrained runtime — acpx runs
+ * it in its own Node process where `Bun` and the `@/*` alias do not exist. Code
+ * that satisfies that constraint runs in both places; the reverse is not true.
+ */
+
+/** One nax-authored section of the body. */
+export interface BodySection {
+  /**
+   * Stable id matched against the alias table. Independent of `heading` so
+   * renaming nax's own heading does not silently break template matching.
+   */
+  key: string;
+  /**
+   * nax's H2 text, used when the section is appended rather than merged.
+   * Empty means headingless (the run footer) — such a section is rendered as
+   * bare text and is never matched to a template heading, so a stray alias
+   * cannot bury the footer under someone's `## Notes`.
+   */
+  heading: string;
+  /** Markdown body without its heading line. Callers omit empty sections. */
+  body: string;
+}
+
+/**
+ * - `merge`  — template headings nax cannot fill are dropped. Default.
+ * - `strict` — they are kept, empty, for repos with heading-checking CI.
+ * - `ignore` — the template is not consulted at all.
+ */
+export type TemplateMode = "merge" | "strict" | "ignore";
+
+export interface MergeOptions {
+  mode?: TemplateMode;
+  /**
+   * Normalised template heading → `BodySection.key`, layered over
+   * `DEFAULT_SECTION_ALIASES`. An empty value suppresses a default alias,
+   * which is how a repo says "do not put anything under this heading".
+   */
+  sectionMap?: Record<string, string>;
+}
+
+/**
+ * Normalised heading → section key.
+ *
+ * Deliberately partial. `why`, `notes`, `screenshots` and friends are absent
+ * because nax has nothing truthful to put under them — an alias that mapped
+ * them to some loosely-related section would reintroduce exactly the
+ * unfilled-field problem this module exists to remove.
+ */
+export const DEFAULT_SECTION_ALIASES: Record<string, string> = {
+  // → narrative
+  what: "narrative",
+  "what changed": "narrative",
+  "whats changed": "narrative",
+  summary: "narrative",
+  description: "narrative",
+  overview: "narrative",
+  changes: "narrative",
+  "what does this do": "narrative",
+  "what does this mr do and why": "narrative",
+  "what does this pr do": "narrative",
+  // → stories
+  how: "stories",
+  implementation: "stories",
+  "implementation details": "stories",
+  "changes made": "stories",
+  approach: "stories",
+  design: "stories",
+  // → verification
+  testing: "verification",
+  tests: "verification",
+  "test plan": "verification",
+  verification: "verification",
+  qa: "verification",
+  validation: "verification",
+  "how to test": "verification",
+  "how has this been tested": "verification",
+  "how to set up and validate locally": "verification",
+};
+
+const HEADING_RE = /^##[ \t]+(.+?)[ \t]*$/;
+const FRONTMATTER_RE = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+/** `Closes #`, `Fixes # (issue)` — an issue reference with no issue. */
+const DANGLING_ISSUE_RE = /^[ \t]*(?:closes?|fixe?s?|resolves?)[ \t]*:?[ \t]*#[ \t]*(?:\([^)]*\))?[ \t]*$/i;
+/** An unticked task-list item — an unfilled field wherever it appears. */
+const UNCHECKED_BOX_RE = /^[ \t]*[-*+][ \t]+\[[ \t]\]/;
+
+interface TemplateSection {
+  heading: string;
+  body: string;
+}
+
+interface ParsedTemplate {
+  frontmatter: string;
+  preamble: string;
+  sections: TemplateSection[];
+}
+
+/** Lowercase, drop punctuation, collapse whitespace — so `## Testing:` matches `testing`. */
+function normalizeHeading(heading: string): string {
+  return heading
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Strip placeholders from template-derived prose.
+ *
+ * Only ever applied to the preamble — the one template region that survives
+ * into the body. Text under a matched heading is replaced wholesale and text
+ * under an unmatched one is discarded, so a checklist or a stale `Closes #`
+ * *inside a section* never reaches this function, which is why there is no
+ * checkbox-versus-gate reconciliation anywhere in this module.
+ *
+ * The preamble is the exception, because a template may open with a
+ * contributor checklist before its first heading. An unticked box there is an
+ * unfilled field like any other, so it is dropped while the prose around it is
+ * kept.
+ */
+function cleanTemplateText(text: string): string {
+  return text
+    .replace(HTML_COMMENT_RE, "")
+    .split("\n")
+    .filter((line) => !DANGLING_ISSUE_RE.test(line) && !UNCHECKED_BOX_RE.test(line))
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .trim();
+}
+
+function parseTemplate(rawText: string): ParsedTemplate {
+  // Normalised up front so a CRLF template (anything authored on Windows, or
+  // fetched through a forge web editor) cannot leak a stray carriage return
+  // into a heading this module re-emits.
+  const text = rawText.replace(/\r\n/g, "\n");
+  const frontmatterMatch = FRONTMATTER_RE.exec(text);
+  const frontmatter = frontmatterMatch ? frontmatterMatch[0].trimEnd() : "";
+  const rest = frontmatterMatch ? text.slice(frontmatterMatch[0].length) : text;
+
+  const preambleLines: string[] = [];
+  const sections: TemplateSection[] = [];
+  let current: { heading: string; lines: string[] } | null = null;
+
+  for (const line of rest.split("\n")) {
+    const heading = HEADING_RE.exec(line);
+    if (heading) {
+      if (current) sections.push({ heading: current.heading, body: current.lines.join("\n") });
+      current = { heading: heading[1], lines: [] };
+      continue;
+    }
+    if (current) current.lines.push(line);
+    else preambleLines.push(line);
+  }
+  if (current) sections.push({ heading: current.heading, body: current.lines.join("\n") });
+
+  return { frontmatter, preamble: preambleLines.join("\n"), sections };
+}
+
+function renderSection(heading: string, body: string): string {
+  if (heading.length === 0) return body;
+  return body.length === 0 ? `## ${heading}` : `## ${heading}\n\n${body}`;
+}
+
+/** Nax-only body: every section under its own heading, in the order given. */
+function renderSections(sections: BodySection[]): string {
+  return sections
+    .filter((s) => s.body.trim().length > 0)
+    .map((s) => renderSection(s.heading, s.body.trim()))
+    .join("\n\n")
+    .trim();
+}
+
+export function mergeTemplate(
+  template: string | null | undefined,
+  sections: BodySection[],
+  opts: MergeOptions = {},
+): string {
+  const mode = opts.mode ?? "merge";
+  if (mode === "ignore" || !template || template.trim().length === 0) return renderSections(sections);
+
+  const parsed = parseTemplate(template);
+  // No H2 anywhere: the template is prose, or nests everything under H1/H3.
+  // There is no shape to merge into, and appending it unparsed is the defect
+  // this module removes — so fall back to the body nax would have written.
+  if (parsed.sections.length === 0) return renderSections(sections);
+
+  // Override keys go through the same normalisation as the template headings
+  // they are matched against, so a repo pins a heading by pasting it —
+  // `"What does this MR do and why?"` — not by hand-normalising it first.
+  const aliases = { ...DEFAULT_SECTION_ALIASES };
+  for (const [heading, key] of Object.entries(opts.sectionMap ?? {})) aliases[normalizeHeading(heading)] = key;
+  const fillable = sections.filter((s) => s.heading.length > 0 && s.body.trim().length > 0);
+  const consumed = new Set<string>();
+  const parts: string[] = [];
+
+  if (parsed.frontmatter.length > 0) parts.push(parsed.frontmatter);
+  const preamble = cleanTemplateText(parsed.preamble);
+  if (preamble.length > 0) parts.push(preamble);
+
+  for (const templateSection of parsed.sections) {
+    const key = aliases[normalizeHeading(templateSection.heading)];
+    const match = key ? fillable.find((s) => s.key === key && !consumed.has(s.key)) : undefined;
+    if (match) {
+      consumed.add(match.key);
+      parts.push(renderSection(templateSection.heading, match.body.trim()));
+    } else if (mode === "strict") {
+      parts.push(renderSection(templateSection.heading, ""));
+    }
+  }
+
+  for (const section of sections) {
+    if (consumed.has(section.key) || section.body.trim().length === 0) continue;
+    parts.push(renderSection(section.heading, section.body.trim()));
+  }
+
+  return parts.join("\n\n").trim();
+}

package/flows/nax-finish/steps/commit-round.ts

@@ -0,0 +1,64 @@
+/**
+ * Assembling the audit round a `commit_<phase>` node records.
+ *
+ * Split out of `nax-finish.flow.ts` for room — that file sits against the
+ * 600-line source cap — but the split earns its keep independently: the round's
+ * shape is a data decision with four conditional fields, and it is now unit
+ * testable without driving a flow node through a git mock.
+ *
+ * Pairs with `./review-round`, which records the rounds that produce no commit.
+ */
+import type { Finding, FinishPhase, FinishRound, FinishRoundOutcome } from "../types";
+
+/** Phases that own a reviewer node; every other phase's round has nobody behind it. */
+const REVIEWED_PHASES: FinishPhase[] = ["spec", "quality"];
+
+/**
+ * What produced this round, given the successor the commit routed to.
+ *
+ * The `route` argument is why this is computed after the commit rather than
+ * alongside it: `tests-only` is only known once the committed paths have been
+ * classified, and it is the difference between "no reviewer exists for this
+ * phase" and "a reviewer exists, was owed a look, and was skipped".
+ */
+export function commitRoundOutcome(phase: FinishPhase, route: string): FinishRoundOutcome {
+  if (REVIEWED_PHASES.includes(phase)) return "fixed";
+  // Only `gate` can skip an owed re-review; `acceptance` has no reviewer to
+  // skip, so its `tests-only`-shaped routes (it has none today) stay honest.
+  if (phase === "gate" && route === "tests-only") return "review-skipped";
+  return "no-reviewer";
+}
+
+export interface CommitRoundInput {
+  phase: FinishPhase;
+  attempt: number;
+  committed: boolean;
+  /** The successor this commit routed to — see `commitRoundOutcome`. */
+  route: string;
+  findings: Finding[];
+  /** Gate commands that were red this round; omitted for non-gate phases. */
+  failing?: string[];
+  /** Post-commit HEAD, when there was a commit. */
+  shaAfter?: string | null;
+  now: string;
+}
+
+/**
+ * Build the round record for a commit checkpoint.
+ *
+ * `sha` and `failing` are omitted rather than set to null/undefined: a reader of
+ * the JSONL distinguishes "no commit" from "record lost" by the key's absence,
+ * and that only works if absence is never used to mean anything else.
+ */
+export function buildCommitRound(i: CommitRoundInput): FinishRound {
+  return {
+    ts: i.now,
+    phase: i.phase,
+    attempt: i.attempt,
+    committed: i.committed,
+    outcome: commitRoundOutcome(i.phase, i.route),
+    findings: i.findings,
+    ...(i.failing ? { failing: i.failing } : {}),
+    ...(i.committed && i.shaAfter ? { sha: i.shaAfter } : {}),
+  };
+}

package/flows/nax-finish/steps/index.ts

@@ -6,4 +6,6 @@ export * from "./forge";
 export * from "./git";
 export * from "./pr";
 export * from "./pr-narrative";
+export * from "./commit-round";
 export * from "./result";
+export * from "./review-round";