@nathapp/nax 0.77.3 → 0.79.0

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

@@ -0,0 +1,183 @@
+/**
+ * The two gate nodes — `acceptance` and `quality_gates`.
+ *
+ * Split out of `nax-finish.flow.ts`, which sits against the 600-line source
+ * cap. They belong together: both answer the same question ("did anything
+ * actually verify this tree?"), both enforce the same rule that **nothing ran
+ * is not a pass**, and both route on the shared `MAX_FIX_ATTEMPTS` cap.
+ *
+ * Keeping them out of the flow file also makes them callable in tests without
+ * reaching through `flow.nodes.*`.
+ */
+import { fixAttemptCount, inputOf, loadCtxOf } from "../flow-ctx";
+import { MAX_FIX_ATTEMPTS } from "../verdict";
+import { runAcceptanceGate } from "./acceptance";
+import { type QualityCommands, loadQualityCommands, runQualityGates } from "./quality";
+
+/** The slice of an acpx `FlowNodeContext` these nodes read. */
+export interface GateNodeCtx {
+  input: unknown;
+  outputs: unknown;
+  state: { steps: { nodeId: string }[] };
+}
+
+export interface AcceptanceNodeOutput {
+  route: string;
+  reason?: string;
+  output: string;
+}
+
+export interface QualityGatesNodeOutput {
+  route: string;
+  reason?: string;
+  ran: string[];
+  failing: string[];
+  output: string;
+}
+
+/** The repo's explicit opt-out, as reported by `nax features resolve`. */
+function acceptanceDisabled(ctx: GateNodeCtx): boolean {
+  return loadCtxOf(ctx).acceptanceStatus === "disabled";
+}
+
+/**
+ * Re-run the acceptance gate, routing on the shared fix-cap rules.
+ *
+ * "Nothing ran" is not a pass — the same rule `quality_gates` applies to an
+ * unconfigured repo. `nax features resolve` reports `groups: []` for `no-prd`,
+ * for `disabled`, **and** for an `ok` resolution whose PRD grouped to no
+ * package at all; it reports `exists: false` for a group whose test was
+ * expected at its canonical path but never generated. Treating any of those as
+ * green let the flow open a ready PR having verified nothing about the
+ * feature's own contract (#1398). Only `disabled` — the repo's explicit opt-out
+ * — skips cleanly.
+ */
+export async function acceptanceGateNode(ctx: GateNodeCtx): Promise<AcceptanceNodeOutput> {
+  const i = inputOf(ctx);
+  const { groups = [], acceptanceStatus } = loadCtxOf(ctx);
+  if (acceptanceStatus === "disabled") {
+    return { route: "proceed", output: "[acceptance] disabled in .nax/config.json — skipping" };
+  }
+  if (acceptanceStatus === "no-prd") {
+    return {
+      route: "escalate",
+      reason: `Acceptance targets could not be computed (status: no-prd) — nothing was verified for "${i.feature}".`,
+      output: "[acceptance] no prd.json resolved — acceptance targets unknown",
+    };
+  }
+
+  const r = await runAcceptanceGate(i.workdir, groups, { timeoutMs: i.timeouts?.acceptanceMs });
+  if (r.passed) {
+    // A real failure below routes to the fix loop, which is more actionable;
+    // the coverage hole is only reported once the runnable groups are green.
+    if (r.missing.length > 0) {
+      return {
+        route: "escalate",
+        reason: `Acceptance test never generated for: ${r.missing.join(", ")} — that package's contract is unverified.`,
+        output: r.output,
+      };
+    }
+    // Passed, nothing missing, and nothing ran: the resolver produced no group
+    // to run at all. `status: "ok"` does NOT imply a target exists — it means
+    // the PRD loaded — so this is the one remaining way an empty gate reports
+    // green. Escalating matches what `runQualityGates` does for a repo with no
+    // configured commands: an LLM fix node cannot invent the missing target.
+    if (r.ran === 0) {
+      return {
+        route: "escalate",
+        reason: `No acceptance test target resolved for "${i.feature}" (status: ${acceptanceStatus ?? "unknown"}) — nothing verified its contract.`,
+        output: r.output,
+      };
+    }
+    return { route: "proceed", output: r.output };
+  }
+  const attempts = fixAttemptCount(ctx, "fix_acceptance");
+  if (attempts >= MAX_FIX_ATTEMPTS) {
+    return {
+      route: "escalate",
+      reason: `Acceptance tests still failing after ${attempts} fix attempts.`,
+      output: r.output,
+    };
+  }
+  return { route: "fix", output: r.output };
+}
+
+/**
+ * Acceptance is gate zero here, not just at the `acceptance` node.
+ *
+ * Both fix loops that run after it — quality review and this gate — edit code,
+ * and the repo-root `test` command does not cover the feature's acceptance
+ * tests: they live under `<pkg>/.nax/features/<f>/` and usually need their own
+ * runner config. Re-running them here is what makes "nothing reaches open_pr
+ * without the feature's own contract passing against the tree as it will ship"
+ * true on every path (#1398).
+ *
+ * Unconditional apart from the repo's own opt-out, though the common green path
+ * re-runs a gate that already passed: acceptance is the cheapest gate in the
+ * pipeline, and a conditional skip derived from step history would be a check
+ * that can be *wrong* — a silent false green, the failure mode this exists to
+ * prevent. The `disabled` skip is not such a derivation: it is the same
+ * resolver field the `acceptance` node already honours, and the two nodes
+ * disagreeing about who owns the opt-out is its own bug.
+ *
+ * `missing` is deliberately ignored: groups are resolved once at load_ctx, so a
+ * coverage hole was already escalated by the acceptance node and cannot appear
+ * here.
+ */
+async function reverifyAcceptance(ctx: GateNodeCtx): Promise<QualityGatesNodeOutput | null> {
+  if (acceptanceDisabled(ctx)) return null;
+  const i = inputOf(ctx);
+  const acc = await runAcceptanceGate(i.workdir, loadCtxOf(ctx).groups ?? [], {
+    timeoutMs: i.timeouts?.acceptanceMs,
+  });
+  if (acc.passed) return null;
+  // Short-circuit: the repo gates are re-run next round anyway, and skipping
+  // them keeps this out of the "nothing configured" branch below, which would
+  // otherwise misreport configured-but-skipped commands as absent.
+  const attempts = fixAttemptCount(ctx, "fix_gate");
+  const failing = ["acceptance"];
+  if (attempts >= MAX_FIX_ATTEMPTS) {
+    return {
+      route: "escalate",
+      reason: `A later fix broke the feature's own contract: acceptance still failing after ${attempts} fix attempts.`,
+      ran: [],
+      failing,
+      output: acc.output,
+    };
+  }
+  return { route: "fix", ran: [], failing, output: acc.output };
+}
+
+export async function qualityGatesNode(ctx: GateNodeCtx): Promise<QualityGatesNodeOutput> {
+  const i = inputOf(ctx);
+
+  const accFailure = await reverifyAcceptance(ctx);
+  if (accFailure) return accFailure;
+
+  const cmds: QualityCommands = await loadQualityCommands(i.workdir);
+  const r = await runQualityGates(i.workdir, cmds, { timeoutMs: i.timeouts?.gateMs });
+  if (r.passed) return { route: "green", ran: r.ran, failing: r.failing, output: r.output };
+  // Nothing configured is not a pass — escalate immediately rather than open a
+  // "ready" PR having verified nothing. An LLM fix node cannot invent the
+  // repo's build/test commands.
+  if (r.ran.length === 0) {
+    return {
+      route: "escalate",
+      reason: "No quality.commands configured in .nax/config.json — nax-finish verified nothing.",
+      ran: r.ran,
+      failing: r.failing,
+      output: r.output,
+    };
+  }
+  const attempts = fixAttemptCount(ctx, "fix_gate");
+  if (attempts >= MAX_FIX_ATTEMPTS) {
+    return {
+      route: "escalate",
+      reason: `Quality gates still failing after ${attempts} fix attempts (${r.failing.join(", ")}).`,
+      ran: r.ran,
+      failing: r.failing,
+      output: r.output,
+    };
+  }
+  return { route: "fix", ran: r.ran, failing: r.failing, output: r.output };
+}

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

@@ -1,6 +1,7 @@
 export * from "./context";
 export * from "./acceptance";
 export * from "./quality";
+export * from "./gates";
 export * from "./escalate";
 export * from "./forge";
 export * from "./git";

package/flows/nax-finish/types.ts

@@ -80,16 +80,17 @@ export type FinishRoundOutcome =
    */
   | "no-reviewer"
   /**
-   * A re-review was owed and deliberately skipped — today only a `gate` fix
-   * that touched test files exclusively (`gateCommitRoute` → `tests-only`).
+   * A re-review was owed and deliberately skipped.
    *
-   * Distinct from `no-reviewer`, which the same node writes when the fix *is*
-   * routed on to `review_quality`. Without the distinction both wrote
-   * `no-reviewer`, so the audit could not tell a gate fix that was re-reviewed
-   * from one whose re-review was skipped by policy — the #1507 failure mode
-   * surviving on the one path where the omission is intentional, and the path
-   * where a reader most needs to know. Recording it is also what makes "how
-   * often does this fire?" answerable before anyone decides to close the hole.
+   * **No longer emitted.** It described the `gate` → `tests-only` route, which
+   * skipped `review_quality` as a cost tradeoff; #1510 closed that hole, so
+   * every committed gate fix is now re-reviewed and nothing writes this.
+   *
+   * Retained because the audit trail is read, not just written: a project that
+   * ran an earlier nax can hold rounds carrying this outcome, and dropping it
+   * from the union would make those unrenderable. Do not reuse the name for a
+   * new meaning — a reader hitting it in an old artifact must still be told
+   * what it meant when it was written.
    */
   | "review-skipped";
 
@@ -106,6 +107,19 @@ export interface FinishRound {
   findings: Finding[];
   /** Gate commands that were red this round (gate phase). */
   failing?: string[];
+  /**
+   * The successor this round's commit routed to — `changed` / `tests-only` /
+   * `unchanged` for `gate`, `changed` / `unchanged` elsewhere.
+   *
+   * Recorded because `outcome` stopped carrying it. Until #1510 a tests-only
+   * gate fix was the only round writing `review-skipped`, so the outcome
+   * doubled as the classification; now every committed gate fix is reviewed
+   * and writes `no-reviewer`, which would leave "what did this fix touch?"
+   * unanswerable from the trail. That question is the input to deciding
+   * whether the re-review ever needs a cheaper, test-scoped form, so it has to
+   * survive the round it was computed in.
+   */
+  route?: string;
   /**
    * `HEAD` SHA after this round's commit (set only when `committed`); absent
    * on no-op rounds so a reader can distinguish "no commit" from "record lost".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.77.3",
+  "version": "0.79.0",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {
@@ -39,13 +39,22 @@
     "test:e2e": "timeout -k 5s 180s bun test test/e2e/ --timeout=60000",
     "test:coverage": "bun run scripts/check-coverage.ts",
     "test:coverage:report": "bun run scripts/check-coverage.ts --report",
-    "check-test-overlap": "bun run scripts/check-test-overlap.ts",
-    "check-dead-tests": "bun run scripts/check-dead-tests.ts",
-    "check:test-sizes": "bun run scripts/check-test-sizes.ts",
+    "report:test-overlap": "bun run scripts/report-test-overlap.ts",
+    "report:dead-tests": "bun run scripts/report-dead-tests.ts",
     "check:test-mocks": "bun scripts/check-inline-test-mocks.ts --strict",
     "check:process-cwd": "bash scripts/check-process-cwd.sh",
     "check:no-adapter-wrap": "bash scripts/check-no-adapter-wrap.sh",
     "check:dispatch-context": "bash scripts/check-dispatch-context.sh",
+    "check:naxconfig-cast": "bash scripts/check-no-silent-naxconfig-cast.sh",
+    "check:runtime-cleanup": "bash scripts/check-runtime-cleanup.sh",
+    "check:scripts": "bash scripts/check-scripts.sh",
+    "check:adapter-no-config-import": "bash scripts/check-adapter-no-config-import.sh",
+    "check:test-typecheck": "bun run scripts/check-test-typecheck.ts",
+    "check:test-typecheck:update": "bun run scripts/check-test-typecheck.ts --update-baseline",
+    "check:test-as-unknown-as": "bun run scripts/check-test-as-unknown-as.ts",
+    "check:test-as-unknown-as:update": "bun run scripts/check-test-as-unknown-as.ts --update-baseline",
+    "check:gate-reachability": "bun run scripts/check-gate-reachability.ts",
+    "check:all": "bun run lint && bun run check:test-mocks && bun run check:process-cwd && bun run check:no-adapter-wrap && bun run check:scripts && bun run check:dispatch-context && bun run check:naxconfig-cast && bun run check:runtime-cleanup && bun run check:adapter-no-config-import && bun run check:test-typecheck && bun run check:test-as-unknown-as && bun run check:gate-reachability",
     "prepublishOnly": "bun run build",
     "test:full": "FULL=1 NAX_PRECHECK=1 bun test test/ --timeout=60000"
   },