@nathapp/nax 0.75.6 → 0.77.0

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

@@ -0,0 +1,136 @@
+/**
+ * Commit messages for the flow's `commit_<phase>` checkpoints.
+ *
+ * These commits are shipped history — they land on the feature branch and a
+ * human reviews them in the PR. Every one of them used to read
+ * `fix(<feature>): nax-finish <phase> fixes` with an empty body, so a reviewer
+ * looking at six such commits could not tell which one re-enabled a disabled
+ * market gate and which one renamed a variable. The reviewer already produced
+ * exactly the material needed to say so — severity, title, problem, fix — and
+ * it was being discarded at the one moment it could have been recorded.
+ *
+ * Subject lines follow the repo's conventional-commit rule and the 72-column
+ * git summary convention; the findings go in the body, one bullet each.
+ */
+import type { Finding, FinishPhase } from "./types";
+
+/** Git's conventional soft cap for a commit summary line. */
+const MAX_SUBJECT_LEN = 72;
+
+/** Worst-first, so the subject of a mixed batch reports the severity that matters. */
+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;
+
+interface MessageCtx {
+  outputs: Record<string, unknown>;
+}
+
+interface PhaseOutputs {
+  findings?: Finding[];
+  failing?: string[];
+  output?: string;
+}
+
+function outputsFor(ctx: MessageCtx, nodeId: string): PhaseOutputs {
+  return (ctx.outputs[nodeId] ?? {}) as PhaseOutputs;
+}
+
+function findingsFor(ctx: MessageCtx, phase: FinishPhase): Finding[] {
+  const raw = outputsFor(ctx, `review_${phase}`).findings;
+  return Array.isArray(raw) ? raw.filter((f): f is Finding => Boolean(f?.title)) : [];
+}
+
+function worstSeverity(findings: Finding[]): string {
+  const present = new Set(findings.map((f) => f.severity));
+  return SEVERITY_ORDER.find((s) => present.has(s)) ?? findings[0]?.severity ?? "LOW";
+}
+
+/**
+ * Lowercase a finding title's leading word for the subject line.
+ *
+ * Reviewers write titles as sentences ("Market gate skip branch is
+ * unreachable"); conventional-commit subjects read better in lower case. Only
+ * the first character is touched — an all-caps leading token is an acronym
+ * (`SSRF guard …`) and must survive intact.
+ */
+function subjectCase(title: string): string {
+  const [first = "", ...rest] = title.split(" ");
+  const isAcronym = first.length > 1 && first === first.toUpperCase();
+  return isAcronym
+    ? title
+    : `${first.charAt(0).toLowerCase()}${first.slice(1)}${rest.length ? ` ${rest.join(" ")}` : ""}`;
+}
+
+function truncate(s: string): string {
+  return s.length <= MAX_SUBJECT_LEN ? s : `${s.slice(0, MAX_SUBJECT_LEN - 3)}...`;
+}
+
+/** "lint and test", "lint, test and typecheck" — a readable list for the subject. */
+function humanList(items: string[]): string {
+  if (items.length <= 1) return items[0] ?? "";
+  return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+
+function reviewSubject(phase: FinishPhase, findings: Finding[]): string {
+  if (findings.length === 1) return subjectCase(findings[0].title);
+  return `address ${findings.length} ${phase} review findings (worst: ${worstSeverity(findings)})`;
+}
+
+function subjectFor(phase: FinishPhase, ctx: MessageCtx): string {
+  if (phase === "gate") {
+    const failing = outputsFor(ctx, "quality_gates").failing ?? [];
+    return failing.length > 0 ? `repair failing ${humanList(failing)} gates` : "repair failing quality gates";
+  }
+  if (phase === "acceptance") return "repair failing acceptance tests";
+  const findings = findingsFor(ctx, phase);
+  return findings.length > 0 ? reviewSubject(phase, findings) : `apply ${phase} review fixes`;
+}
+
+function bodyFor(phase: FinishPhase, ctx: MessageCtx): 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] : [])];
+  }
+  if (phase === "acceptance") {
+    const tail = (outputsFor(ctx, "acceptance").output ?? "")
+      .trim()
+      .split("\n")
+      .slice(-MAX_GATE_OUTPUT_LINES)
+      .join("\n");
+    return tail ? [tail] : [];
+  }
+  const findings = findingsFor(ctx, phase);
+  if (findings.length === 0) return [];
+  return [
+    findings
+      .map((f) =>
+        [`- [${f.severity}] ${f.title}`, f.problem ? `  ${f.problem}` : "", f.fix ? `  Fix: ${f.fix}` : ""]
+          .filter(Boolean)
+          .join("\n"),
+      )
+      .join("\n"),
+  ];
+}
+
+/** Human-readable phase label for the attribution trailer. */
+function phaseLabel(phase: FinishPhase): string {
+  return phase === "gate" ? "quality gate" : phase === "acceptance" ? "acceptance" : `${phase} review`;
+}
+
+/**
+ * Build the commit message for a `commit_<phase>` checkpoint.
+ *
+ * Never throws and never returns an empty subject: a missing or malformed
+ * reviewer output degrades to the phase label. A commit that cannot be
+ * 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 {
+  const subject = truncate(`fix(${feature}): ${subjectFor(phase, ctx)}`);
+  const body = bodyFor(phase, ctx);
+  return [subject, ...body, `nax-finish: ${phaseLabel(phase)} fixes`].join("\n\n");
+}

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

@@ -0,0 +1,107 @@
+/**
+ * Readers over an acpx `FlowNodeContext` — the flow graph's view of its own
+ * state.
+ *
+ * Split out of `nax-finish.flow.ts` (600-line source cap). These are all pure
+ * functions of `ctx.input` / `ctx.outputs` / `ctx.state.steps`; anything that
+ * shells out lives under `./steps/`.
+ *
+ * Two views of the same run, and the difference matters in a graph whose whole
+ * shape is loops:
+ *
+ * - `ctx.outputs` is a map keyed by node id, so it holds only each node's
+ *   **latest** output. A node re-entering a loop cannot see its own previous
+ *   round there.
+ * - `ctx.state.steps` is the ordered history and carries every step's `output`,
+ *   so an earlier round IS recoverable from it. A step is appended on its
+ *   *outcome*, so the currently-executing node is never in this list — which is
+ *   what lets `incrementalSince` find the *previous* review rather than itself.
+ */
+import type { AcceptanceGroup, Finding, FinishInput, FinishPhase, ReviewVerdict } from "./types";
+
+/** Minimal shapes so each reader takes only the part of the context it reads. */
+export interface StepsCtx {
+  state: { steps: { nodeId: string; output?: unknown }[] };
+}
+export interface OutputsCtx {
+  outputs: unknown;
+}
+
+export const inputOf = (ctx: { input: unknown }) => ctx.input as FinishInput;
+
+/** What `load_ctx` resolves once, for every downstream node to read. */
+export interface LoadCtxOutput {
+  base?: string;
+  specPath?: string;
+  groups?: AcceptanceGroup[];
+  /** `nax features resolve`'s acceptance status: "ok" | "disabled" | "no-prd". */
+  acceptanceStatus?: string;
+  /** Test-file regex sources from `nax features resolve`; empty = cannot classify. */
+  testFileRegex?: string[];
+  route?: string;
+}
+
+export function fixAttemptCount(ctx: StepsCtx, fixNodeId: string): number {
+  return (ctx.state.steps ?? []).filter((s) => s.nodeId === fixNodeId).length;
+}
+
+export function loadCtxOf(ctx: OutputsCtx): LoadCtxOutput {
+  return ((ctx.outputs as Record<string, LoadCtxOutput | undefined>).load_ctx ?? {}) as LoadCtxOutput;
+}
+/**
+ * The narrative node's parsed prose.
+ *
+ * Absent when the node was skipped by config, died, or produced only
+ * whitespace — `amend_body` treats all three identically, so there is one
+ * branch downstream rather than three.
+ */
+export function narrativeOf(ctx: OutputsCtx): string | undefined {
+  const out = (ctx.outputs as Record<string, unknown>).narrative;
+  return typeof out === "string" && out.trim().length > 0 ? out : undefined;
+}
+
+export function gateOutputs(ctx: OutputsCtx): { failing?: string[]; ran?: string[] } {
+  return ((ctx.outputs as Record<string, { failing?: string[]; ran?: string[] } | undefined>).quality_gates ?? {}) as {
+    failing?: string[];
+    ran?: string[];
+  };
+}
+
+/** The findings the `fix_<phase>` node was asked to resolve; empty for non-review phases. */
+export function findingsOf(ctx: OutputsCtx, phase: FinishPhase): Finding[] {
+  if (phase !== "spec" && phase !== "quality") return [];
+  return (ctx.outputs as Record<string, ReviewVerdict | undefined>)[`review_${phase}`]?.findings ?? [];
+}
+
+/**
+ * The ref a re-review should diff from, or null to review the whole branch.
+ *
+ * A reviewer node re-reads the spec in full and the entire `git diff
+ * base...HEAD` on every round. Reviews were 58% of the wall clock on
+ * rs-stock/pipeline-run-outcome (7 calls, 1306s of 2232s), and round 3 re-read
+ * everything rounds 1-2 had already cleared.
+ *
+ * The scoping ref is the `shaBefore` of the **first** `commit_*` step after this
+ * phase's last review — that commit's parent is, by construction, the tree the
+ * previous verdict passed on, since only `commit_*` nodes commit. Taking the
+ * first (not the last) is what makes the window complete when more than one
+ * commit landed in it, which happens when the acceptance loop commits between a
+ * spec fix and its re-review: `firstCommit.shaBefore..HEAD` spans both.
+ *
+ * Read from `ctx.state.steps[].output`, not `ctx.outputs` — the latter keeps
+ * only each node's newest output, which for two commit steps of the same node id
+ * would have discarded the earlier `shaBefore` and silently under-scoped the
+ * review.
+ *
+ * Returns null — a full review — when there is no prior review of this phase
+ * (round 1), no commit since it (nothing new to look at), or the commit step
+ * recorded no `shaBefore`.
+ */
+export function incrementalSince(ctx: OutputsCtx & StepsCtx, phase: "spec" | "quality"): string | null {
+  const steps = ctx.state.steps ?? [];
+  const lastReview = steps.map((s) => s.nodeId).lastIndexOf(`review_${phase}`);
+  if (lastReview < 0) return null;
+  const firstCommit = steps.slice(lastReview + 1).find((s) => s.nodeId.startsWith("commit_"));
+  if (!firstCommit) return null;
+  return (firstCommit.output as { shaBefore?: string | null } | undefined)?.shaBefore ?? null;
+}

package/flows/nax-finish/narrative.ts

@@ -0,0 +1,133 @@
+/**
+ * The PR body's "What changed" section — prompt, parse, and the chain that
+ * decides what text (if any) the section carries.
+ *
+ * Prompt building lives here rather than in `src/prompts/builders/` because
+ * `flows/` is loaded by acpx in its own Node process and imports nothing from
+ * `src/`. `review-prompts.ts` sits beside this file for the same reason.
+ *
+ * `resolveNarrative` is a standalone pure function, not flow wiring, because
+ * the acp node that produces the model text cannot be executed in tests. The
+ * degradation chain is the part that must never break, so it lives where a
+ * test can reach it.
+ */
+
+/** Longest narrative rendered into a PR body, in characters, including the ellipsis. */
+export const NARRATIVE_MAX_CHARS = 4000;
+
+const TRUNCATION_SUFFIX = "…";
+
+/** Headings a spec uses for its lead paragraph, in priority order. */
+const SUMMARY_HEADINGS = ["summary", "overview"] as const;
+
+/**
+ * Prompt for the narrative node.
+ *
+ * Two jobs: point the agent at the real diff (never the spec, which describes
+ * intent rather than what shipped), and forbid restating the sections the body
+ * already renders deterministically.
+ */
+/**
+ * `prompt` for the `narrative` flow node. Lives here rather than inline in
+ * `nax-finish.flow.ts` to keep that file under its 600-line cap — the node
+ * just needs `ctx.outputs.load_ctx.base`, which is all this wrapper reads.
+ */
+export function narrativePrompt(ctx: { outputs: unknown }): string {
+  const base = (ctx.outputs as { load_ctx?: { base?: string } }).load_ctx?.base ?? "origin/main";
+  return buildNarrativePrompt({ base });
+}
+
+export function buildNarrativePrompt(args: { base: string }): string {
+  return [
+    'Write the "What changed" section of a pull request body.',
+    "",
+    `Read the branch diff yourself: \`git diff ${args.base}...HEAD\`.`,
+    "Read whatever source files you need to understand it.",
+    "",
+    "The PR body ALREADY renders these deterministically, from run artifacts:",
+    "- a Stories table (story id, title, acceptance-criteria count)",
+    "- a Verification block (acceptance status, regression status, gates run, diffstat)",
+    "- a Review rounds block (every finding, with its severity)",
+    "- an Out of scope list",
+    "",
+    "Do NOT restate, summarise, or refer to any of them. Repeating them is how the",
+    "written and the generated halves of this body drift apart.",
+    "",
+    "Describe what the change actually does, in prose: the shape of the change, and",
+    "anything a reviewer would otherwise have to reconstruct from the diff by hand.",
+    `Hard limit: ${NARRATIVE_MAX_CHARS} characters.`,
+    "Do not write a heading — the heading is added for you.",
+    "Return the prose only. No JSON, no code fences, no preamble.",
+  ].join("\n");
+}
+
+/**
+ * `parse` for the narrative acp node.
+ *
+ * Never throws. A throw inside `parse` fails the node, and acpx has no error
+ * edge — see `verdict.ts`. Here that would mean the flow dying *after* the PR
+ * was already opened.
+ */
+export function parseNarrative(text: string): string {
+  return typeof text === "string" ? text.trim() : "";
+}
+
+function truncate(text: string): string {
+  if (text.length <= NARRATIVE_MAX_CHARS) return text;
+  return text.slice(0, NARRATIVE_MAX_CHARS - TRUNCATION_SUFFIX.length) + TRUNCATION_SUFFIX;
+}
+
+/**
+ * Pick the narrative text, best source first.
+ *
+ * The spec summary is the fallback rather than the primary source because a
+ * spec describes intent: when an implementation deviates and the deviation is
+ * accepted, a spec-derived narrative confidently describes code that does not
+ * exist.
+ *
+ * `undefined` means "render no section at all" — never an empty heading.
+ */
+export function resolveNarrative(agentText: string | undefined, specSummary: string | null): string | undefined {
+  const fromAgent = agentText?.trim();
+  if (fromAgent) return truncate(fromAgent);
+  const fromSpec = specSummary?.trim();
+  if (fromSpec) return truncate(fromSpec);
+  return undefined;
+}
+
+function sectionBody(lines: string[], heading: string): string | null {
+  const start = lines.findIndex((line) => line.trim().toLowerCase() === `## ${heading}`);
+  if (start === -1) return null;
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex((line) => line.startsWith("## "));
+  const body = (end === -1 ? rest : rest.slice(0, end)).join("\n").trim();
+  return body.length > 0 ? body : null;
+}
+
+/**
+ * First `## Summary` or `## Overview` block in the spec, or `null`.
+ *
+ * Both headings are accepted because both occur in this repository's real
+ * specs — five of six use `## Summary`, the older `plugin-001` uses
+ * `## Overview`. Fail-open on every read error: a missing or unreadable spec
+ * costs the section, never the PR.
+ */
+export async function readSpecSummary(
+  specPath: string | undefined,
+  readText: (path: string) => Promise<string | null>,
+): Promise<string | null> {
+  if (!specPath) return null;
+  let text: string | null;
+  try {
+    text = await readText(specPath);
+  } catch {
+    return null;
+  }
+  if (text === null) return null;
+  const lines = text.split(/\r?\n/);
+  for (const heading of SUMMARY_HEADINGS) {
+    const body = sectionBody(lines, heading);
+    if (body !== null) return body;
+  }
+  return null;
+}