mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/orchestration/story-close/format-autofix.js

@@ -1,68 +1,23 @@
 /**
- * format-autofix.js — self-healing biome-format step for story-close.
+ * format-autofix.js — self-healing biome-format step for story-close, plus
+ * the git plumbing it shares with `baseline-upward-writeback.js`.
  *
- * Story #4017 collapsed the historical three-module split (a whole-tree
- * fork, a scoped changed-file fork, and a shared plumbing module) into
- * this single module. The two entry points differ only in file-scope,
- * commit subject, and log level; the git/formatter plumbing is shared
- * below.
- *
- * Background. The pre-merge `biome format` gate is check-only — it fails
- * the close when the working tree has any format drift. In practice
- * upstream waves frequently leave drift in files that lint-staged does
- * not glob (JSON/JSON5/YAML), so the *next* wave's close hits the gate,
- * fails, and forces an operator-driven `npx biome format --write` plus a
- * `style:` commit before the close can resume. That manual loop is
- * trivially automatable.
- *
- * Entry points:
- *
- *   - {@link runFormatAutofix} — whole-tree heal (`biome format --write .`)
- *     before the pre-merge gate chain, for resume/legacy callers that have
- *     no Epic→Story diff anchor. Bounded by a wall-clock timeout
- *     (Story #2165).
- *   - {@link runScopedFormatAutofix} — Story #2533: scopes the formatter to
- *     the changed-file set between the Epic branch and the Story branch and
- *     folds auto-fixed paths into a dedicated `fix(story-close):` commit,
- *     emitting `Logger.warn` naming the files. Carries the worktree-cwd fix
- *     and branch assert from Story #3907.
- *
- * Dependencies are injected so unit tests pin behaviour without spawning
- * git or biome.
+ * The pre-merge format gate is check-only, and drift in files lint-staged
+ * doesn't glob (JSON/YAML) would otherwise fail the next close; this step
+ * formats the changed files and commits the result instead.
  */
 
 import { execFileSync } from 'node:child_process';
 
 import { diffNameOnly } from '../../changed-files.js';
 import { resolveFormatWriteCommand } from '../../close-validation/commands.js';
-import { getQuality } from '../../config-resolver.js';
 import { Logger as DefaultLogger } from '../../Logger.js';
 
-const TAG = '[format-autofix]';
 const SCOPED_TAG = '[format-autofix-scoped]';
 
 /**
- * Story #2165 — exit code surfaced when the bounded `npx biome format
- * --write` spawn is killed by the timeout watchdog. Matches the GNU
- * `timeout(1)` convention so the close orchestrator can branch on "hang"
- * (124) vs. "formatter exited non-zero" (any other status) without
- * inspecting signal names. Mirrors `COVERAGE_TIMEOUT_EXIT_CODE` from
- * `coverage-capture.js` (Story #2142).
- */
-export const FORMAT_AUTOFIX_TIMEOUT_EXIT_CODE = 124;
-
-/**
- * Run `git status --porcelain` and return the list of changed paths.
- *
- * Porcelain lines are `XY <path>` — exactly two status chars, one space,
- * then the path. Leading whitespace inside the status pair is significant
- * (e.g. ` M file` for unstaged-modified) so we slice a fixed 3 chars off
- * the front rather than trimming.
- *
- * Exported since Story #5277: `baseline-upward-writeback.js` needs the same
- * "is this path already dirty?" test before it rewrites a baseline row, and a
- * second porcelain parser is exactly the near-duplicate the duplication gate
- * exists to refuse.
+ * Paths from `git status --porcelain`. Lines are `XY <path>` and the status
+ * pair's leading space is significant, so slice 3 chars rather than trim.
  *
  * @param {string} cwd
  * @param {(args: string[], opts: object) => string} git
@@ -81,38 +36,23 @@ export function listDirtyPaths(cwd, git) {
 }
 
 /**
- * Resolve the formatter write command from `project.commands.formatWrite`
- * (falling back to the historical `npx biome format --write .`) and split
- * it into an executable + argv pair ready for `execFileSync`.
+ * Split the configured format-write command into executable + argv, dropping
+ * a trailing whole-tree `.` so a file list can be appended.
  *
- * The whole-tree entry point runs the command verbatim (keeping the
- * trailing `.` so biome formats the entire tree). The scoped entry point
- * appends an explicit changed-file set, so it passes
- * `dropTrailingDot: true` to strip the `.` before its file list.
- *
- * @param {{
- *   commands?: object,
- *   dropTrailingDot?: boolean,
- * }} [opts]
+ * @param {{ commands?: object }} [opts]
  * @returns {{ writeCmdString: string, writeCmd: string, writeArgs: string[] }}
  */
-function resolveFormatterCmd({ commands, dropTrailingDot = false } = {}) {
-  // `resolveFormatWriteCommand` reads `config.project.commands`; wrap the
-  // caller-supplied `commands` map into that canonical shape.
+function resolveFormatterCmd({ commands } = {}) {
   const writeCmdString = resolveFormatWriteCommand({ project: { commands } });
   const parts = writeCmdString.split(/\s+/).filter(Boolean);
-  if (dropTrailingDot && parts[parts.length - 1] === '.') parts.pop();
+  if (parts[parts.length - 1] === '.') parts.pop();
   const [writeCmd, ...writeArgs] = parts;
   return { writeCmdString, writeCmd, writeArgs };
 }
 
 /**
- * Resolve the branch currently checked out at `cwd` via
- * `git rev-parse --abbrev-ref HEAD`. Returns the trimmed branch name, or
- * `null` when the call fails or the tree is in a detached-HEAD state
- * (`HEAD`). Used as the commit-target guard before
- * {@link commitDirtyPaths} writes a scoped-autofix commit, so the commit
- * can never land on the wrong branch (e.g. the main checkout's `main`).
+ * Checked-out branch at `cwd`, or `null` on failure or detached HEAD. Guards
+ * commits against landing on the wrong branch.
  *
  * @param {string} cwd
  * @param {(args: string[], opts: object) => string} git
@@ -134,9 +74,7 @@ export function currentBranch(cwd, git) {
 }
 
 /**
- * Stage every modified path (`git add -u`), commit with the caller-supplied
- * `subject`, and return the short HEAD SHA. Hooks must run; we never pass
- * `--no-verify` (project policy: never skip git hooks).
+ * `git add -u` + commit with hooks enabled (never `--no-verify`).
  *
  * @param {{
  *   cwd: string,
@@ -159,195 +97,13 @@ export function commitDirtyPaths({ cwd, git, subject }) {
 }
 
 /**
- * Story #2165 — resolve the format-autofix spawn timeout. An explicit
- * caller-supplied positive integer wins over both
- * `delivery.quality.formatAutofix.timeoutMs` and the framework default
- * (60 s). Any resolver failure surfaces as `null`; the caller treats that
- * as "no timeout" and the spawn runs unbounded — same fail-open contract
- * coverage-capture uses.
- */
-function resolveFormatTimeoutMs({ timeoutMs, config }) {
-  if (
-    typeof timeoutMs === 'number' &&
-    Number.isInteger(timeoutMs) &&
-    timeoutMs > 0
-  ) {
-    return timeoutMs;
-  }
-  try {
-    const resolved = getQuality(config)?.formatAutofix?.timeoutMs;
-    if (
-      typeof resolved === 'number' &&
-      Number.isInteger(resolved) &&
-      resolved > 0
-    ) {
-      return resolved;
-    }
-  } catch {
-    // resolver failure → fall through to "no timeout"
-  }
-  return null;
-}
-
-/**
- * Run `npx biome format --write .` then, if anything changed, commit
- * the result on the Story branch with a `style:` subject. Returns a
- * structured envelope so callers can log a single line.
- *
- * Story #2165: the formatter spawn is bounded by a wall-clock timeout
- * (resolved from `delivery.quality.formatAutofix.timeoutMs`, default
- * 60 s). A SIGKILL fired at the budget boundary is translated to the
- * `timedOut: true` envelope below so the close orchestrator can flip the
- * Story to `agent::blocked` with a friction comment naming the spawn,
- * mirroring the coverage-capture pattern from Story #2142.
- *
- * The step is a no-op when:
- *   - biome rewrites nothing (clean tree),
- *   - the working tree is dirty for unrelated reasons (we refuse to
- *     opportunistically commit those — operator intent is unclear), or
- *   - `npx biome format --write` exits non-zero (we surface the error
- *     and let the existing format gate report it with the canonical
- *     hint).
- *
- * @param {{
- *   cwd: string,
- *   storyId: number|string,
- *   config?: object,
- *   timeoutMs?: number,
- *   logger?: object,
- *   spawnSync?: typeof execFileSync,
- *   gitSync?: (args: string[], opts: object) => string,
- * }} opts
- * @returns {{
- *   ran: boolean,
- *   committed: boolean,
- *   sha?: string,
- *   dirtyPathsBefore?: string[],
- *   timedOut?: boolean,
- *   timeoutMs?: number,
- *   exitCode?: number,
- *   writeCmdString?: string,
- * }}
- */
-export function runFormatAutofix({
-  cwd,
-  storyId,
-  config,
-  timeoutMs,
-  logger = DefaultLogger,
-  spawnSync = execFileSync,
-  gitSync,
-} = {}) {
-  if (!cwd) throw new Error('runFormatAutofix: cwd is required');
-
-  const git = gitSync ?? ((args, opts) => spawnSync('git', args, opts));
-  // Resolve the formatter command from `project.commands.formatWrite` so
-  // Prettier / dprint repos use their own formatter. Falls back to the
-  // historical `npx biome format --write .` for repos that haven't opted in.
-  // The whole-tree entry point keeps the trailing `.` (formats the tree).
-  const { writeCmdString, writeCmd, writeArgs } = resolveFormatterCmd({
-    commands: config?.project?.commands,
-  });
-
-  // Refuse to act when the tree is already dirty for unrelated reasons —
-  // we don't want to absorb stray edits into a `style:` commit.
-  const dirtyBefore = listDirtyPaths(cwd, git);
-  if (dirtyBefore.length) {
-    logger.info?.(
-      `${TAG} skipped — working tree dirty before autofix (${dirtyBefore.length} paths). ` +
-        'The format check gate will report any drift with the canonical hint.',
-    );
-    return { ran: false, committed: false, dirtyPathsBefore: dirtyBefore };
-  }
-
-  // Story #2165 — bounded wall-clock for the formatter spawn.
-  // execFileSync's contract: on a SIGKILL trip the thrown error carries
-  // `err.signal === 'SIGKILL'` and `err.status === null`, so we branch on
-  // that to surface the 124 envelope below — same shape coverage-capture
-  // returns to its caller (Story #2142).
-  const resolvedTimeoutMs = resolveFormatTimeoutMs({
-    timeoutMs,
-    config,
-  });
-  const spawnOpts = {
-    cwd,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf8',
-    killSignal: 'SIGKILL',
-  };
-  if (Number.isInteger(resolvedTimeoutMs) && resolvedTimeoutMs > 0) {
-    spawnOpts.timeout = resolvedTimeoutMs;
-  }
-  // Run the configured formatter in write mode. We tolerate a non-zero exit
-  // because the existing format gate downstream is the source of truth for
-  // "did formatting succeed" — our job is only to opportunistically heal
-  // drift that *would* have failed the gate.
-  let writeFailed = false;
-  try {
-    spawnSync(writeCmd, writeArgs, spawnOpts);
-  } catch (err) {
-    if (err?.signal === 'SIGKILL') {
-      logger.warn?.(
-        `${TAG} ⏱ \`${writeCmdString}\` exceeded ${resolvedTimeoutMs}ms — killed (SIGKILL). ` +
-          `Returning exit ${FORMAT_AUTOFIX_TIMEOUT_EXIT_CODE}; story-close will flip Story #${storyId} to agent::blocked.`,
-      );
-      return {
-        ran: true,
-        committed: false,
-        timedOut: true,
-        timeoutMs: resolvedTimeoutMs,
-        exitCode: FORMAT_AUTOFIX_TIMEOUT_EXIT_CODE,
-        writeCmdString,
-      };
-    }
-    writeFailed = true;
-    logger.warn?.(
-      `${TAG} \`${writeCmdString}\` exited non-zero (${err?.status ?? 'unknown'}); ` +
-        'falling through to the format check gate to report drift.',
-    );
-  }
-
-  const dirtyAfter = listDirtyPaths(cwd, git);
-  if (!dirtyAfter.length) {
-    logger.info?.(
-      writeFailed
-        ? `${TAG} no autofix changes produced (formatter write failed).`
-        : `${TAG} no format drift — tree clean after \`${writeCmdString}\`.`,
-    );
-    return { ran: true, committed: false };
-  }
-
-  // Stage every modified path and commit. Hooks must run; do not pass
-  // --no-verify (project policy: never skip git hooks).
-  const subject = `style: biome format autofix on story-close (story #${storyId})`;
-  const sha = commitDirtyPaths({ cwd, git, subject });
-
-  logger.info?.(
-    `${TAG} healed ${dirtyAfter.length} path(s) with \`${writeCmdString}\`; ` +
-      `committed as ${sha} on story branch.`,
-  );
-  return { ran: true, committed: true, sha };
-}
-
-/**
- * List the files changed between `baseBranch` and `storyBranch` using the
- * three-dot merge-base diff. Delegates parsing to `diffNameOnly` from
- * `changed-files.js` so the stdout → path-list conversion lives in one place.
- *
- * The `git` parameter uses the caller's local interface:
- * `(args: string[], opts: object) => string`. A bridge adapter wraps it into
- * the `gitSpawn(cwd, ...args)` shape that `diffNameOnly` expects.
- *
- * Exported since Story #5224: the sibling `baseline-upward-writeback.js` step
- * scopes to the same branch changed-file set, and a second copy of this
- * `(args, opts)` → `gitSpawn` bridge is exactly the kind of near-duplicate the
- * duplication gate exists to refuse.
+ * Files changed in `baseBranch...storyBranch`, bridging the local
+ * `(args, opts)` git interface to the `gitSpawn` shape `diffNameOnly` takes.
  *
  * @param {{ cwd: string, baseBranch: string, storyBranch: string, git: Function }} opts
  * @returns {string[]}
  */
 export function listChangedFiles({ cwd, baseBranch, storyBranch, git }) {
-  // Bridge the (args, opts) → string interface into gitSpawn(cwd, ...args).
   const gitSpawn = (_cwd, ...args) => {
     try {
       const stdout = git(args, {
@@ -372,37 +128,11 @@ export function listChangedFiles({ cwd, baseBranch, storyBranch, git }) {
 }
 
 /**
- * Story #2533 — run `biome format --write <changedFiles>` on the Epic→Story
- * diff. If any file is modified, stage and commit the changes on the Story
- * branch with a conventional `fix(story-close):` subject and emit a
- * `Logger.warn` naming the auto-fixed files. Returns a structured
- * envelope so callers can log a single line.
- *
- * Why scoped + warn-level. The Tech Spec (Epic #2527, Story 5) calls out
- * that format diffs introduced by Story commits should never surface to
- * Phase 3 close-validation. The whole-tree autofix already covers that,
- * but emits `info` so operators routinely miss it. This entry point emits
- * `Logger.warn` naming the auto-fixed files so the signal is visible in
- * the close transcript and downstream ledger.
- *
- * No-op envelopes:
- *   - `{ ran: false, reason: 'no-changed-files' }`        — empty diff.
- *   - `{ ran: false, reason: 'dirty-tree' }`              — refused to
- *     absorb pre-existing edits.
- *   - `{ ran: true, committed: false }`                   — formatter
- *     was clean.
- *
- * **Worktree scope (Story #3907).** All git + formatter operations run in
- * `worktreePath` (the Story worktree where `story-<id>` is checked out), not
- * `cwd` (the main checkout). The earlier implementation ran every step
- * against `cwd`, so the `git add -u` + `git commit` could land an unreviewed
- * `fix(story-close):` commit on whatever branch the main checkout happened to
- * have out — including `main`. Before committing, the worktree's checked-out
- * branch is asserted to equal `storyBranch`; a mismatch refuses to commit and
- * returns `{ ran: true, committed: false, reason: 'wrong-branch' }` so a
- * stale-state checkout can never absorb the autofix into the wrong history.
- * `worktreePath` defaults to `cwd` for the resume/legacy callers that have no
- * separate worktree.
+ * Format the branch's changed files and fold any drift into one
+ * `fix(story-close):` commit, logged at warn so it is visible in the close
+ * transcript. Everything runs in `worktreePath` (default `cwd`), and the
+ * commit is refused unless that tree is on `storyBranch` — otherwise a
+ * mis-wired cwd could commit onto `main`. Refuses to absorb a dirty tree.
  *
  * @param {{
  *   cwd: string,
@@ -440,18 +170,12 @@ export function runScopedFormatAutofix({
   if (!storyBranch)
     throw new Error('runScopedFormatAutofix: storyBranch is required');
 
-  // Story #3907 — the formatter writes + the commit must land in the Story
-  // worktree, never the main checkout. Fall back to `cwd` only for callers
-  // that do not run under worktree isolation.
   const workTree = worktreePath || cwd;
 
   const git = gitSync ?? ((args, opts) => spawnSync('git', args, opts));
 
-  // Resolve the formatter base command (e.g. `npx biome format --write`).
-  // We drop a trailing `.` so we can append the changed-file set explicitly.
   const { writeCmdString, writeCmd, writeArgs } = resolveFormatterCmd({
     commands: config?.project?.commands,
-    dropTrailingDot: true,
   });
 
   const changed = listChangedFiles({
@@ -475,9 +199,7 @@ export function runScopedFormatAutofix({
     return { ran: false, committed: false, reason: 'dirty-tree' };
   }
 
-  // Run the formatter against the changed-file set. We tolerate non-zero
-  // exit because the downstream check gate is the source of truth for
-  // "did formatting succeed".
+  // A non-zero exit is tolerated: the downstream check gate is authoritative.
   try {
     spawnSync(writeCmd, [...writeArgs, ...changed], {
       cwd: workTree,
@@ -498,11 +220,6 @@ export function runScopedFormatAutofix({
     return { ran: true, committed: false };
   }
 
-  // Story #3907 — assert the worktree is actually on `storyBranch` before we
-  // stage + commit. Without this guard a stale-state checkout (or a
-  // mis-wired `cwd`) could absorb the autofix onto the wrong branch (incl.
-  // `main`). A mismatch refuses to commit and leaves the format drift for the
-  // downstream check gate to surface.
   const onBranch = currentBranch(workTree, git);
   if (onBranch !== storyBranch) {
     logger.warn?.(
@@ -512,14 +229,9 @@ export function runScopedFormatAutofix({
     return { ran: true, committed: false, reason: 'wrong-branch' };
   }
 
-  // Stage every modified path and commit. Hooks must run; do not pass
-  // --no-verify (project policy: never skip git hooks).
   const subject = `fix(story-close): auto-apply biome format in scoped lint (story #${storyId})`;
   const sha = commitDirtyPaths({ cwd: workTree, git, subject });
 
-  // The warn-level emission is the Tech Spec contract — operators read
-  // this line in the close transcript to know auto-fix landed in the
-  // close commit, and downstream ledger inspectors filter on it.
   logger.warn?.(
     `${SCOPED_TAG} auto-applied biome format to ${dirtyAfter.length} path(s) on story #${storyId}: ${dirtyAfter.join(', ')}; committed as ${sha}.`,
   );