mandrel 1.57.0

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

@@ -0,0 +1,123 @@
+/**
+ * format-autofix-shared.js — Story #3332 (Epic #3316): single-source the
+ * git/formatter plumbing shared by the two format-autofix forks.
+ *
+ * `format-autofix.js` (whole-tree heal) and `format-autofix-scoped.js`
+ * (Epic→Story changed-file heal) historically each carried their own copy
+ * of the porcelain-status parse, the formatter-command resolution, and the
+ * stage→commit→rev-parse sequence. The three forked helpers are
+ * byte-for-byte equivalent apart from cosmetics, so a fix to (say) the
+ * porcelain-line slice had to land twice. This module is the single home
+ * for all three; the two forks now differ only in file-scope, commit
+ * subject, and log level.
+ *
+ * Every helper takes an injected `git` runner (`(args, opts) => string`) so
+ * unit tests pin behaviour without spawning git.
+ */
+
+import { resolveFormatWriteCommand } from '../../close-validation.js';
+
+/**
+ * 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.
+ *
+ * @param {string} cwd
+ * @param {(args: string[], opts: object) => string} git
+ * @returns {string[]}
+ */
+export function listDirtyPaths(cwd, git) {
+  const out = git(['status', '--porcelain'], {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return out
+    .split('\n')
+    .filter((line) => line.length >= 4)
+    .map((line) => line.slice(3));
+}
+
+/**
+ * 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`.
+ *
+ * The whole-tree fork runs the command verbatim (keeping the trailing `.`
+ * so biome formats the entire tree). The scoped fork appends an explicit
+ * changed-file set, so it passes `dropTrailingDot: true` to strip the `.`
+ * before its file list.
+ *
+ * @param {{
+ *   commands?: object,
+ *   dropTrailingDot?: boolean,
+ * }} [opts]
+ * @returns {{ writeCmdString: string, writeCmd: string, writeArgs: string[] }}
+ */
+export function resolveFormatterCmd({
+  commands,
+  dropTrailingDot = false,
+} = {}) {
+  // `resolveFormatWriteCommand` reads `config.project.commands`; wrap the
+  // caller-supplied `commands` map into that canonical shape.
+  const writeCmdString = resolveFormatWriteCommand({ project: { commands } });
+  const parts = writeCmdString.split(/\s+/).filter(Boolean);
+  if (dropTrailingDot && 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`).
+ *
+ * @param {string} cwd
+ * @param {(args: string[], opts: object) => string} git
+ * @returns {string|null}
+ */
+export function currentBranch(cwd, git) {
+  try {
+    const out = git(['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const branch = (out ?? '').toString().trim();
+    if (!branch || branch === 'HEAD') return null;
+    return branch;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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).
+ *
+ * @param {{
+ *   cwd: string,
+ *   git: (args: string[], opts: object) => string,
+ *   subject: string,
+ * }} opts
+ * @returns {string} short HEAD SHA of the new commit
+ */
+export function commitDirtyPaths({ cwd, git, subject }) {
+  git(['add', '-u'], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+  git(['commit', '-m', subject], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return git(['rev-parse', '--short', 'HEAD'], {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+}

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

@@ -0,0 +1,216 @@
+/**
+ * format-autofix.js — self-healing biome-format step for story-close.
+ *
+ * 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.
+ *
+ * This module runs `npx biome format --write .` *before* the pre-merge
+ * gate chain. If it rewrites files, we stage and commit them on the
+ * Story branch with a `style:` subject so the merge into `epic/<id>`
+ * carries the fix forward atomically. The subsequent `biome format`
+ * check gate then passes deterministically.
+ *
+ * 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).
+ *
+ * Dependencies are injected so unit tests pin behaviour without
+ * spawning git or biome.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+import { getQuality } from '../../config-resolver.js';
+import { Logger as DefaultLogger } from '../../Logger.js';
+import {
+  commitDirtyPaths,
+  listDirtyPaths,
+  resolveFormatterCmd,
+} from './format-autofix-shared.js';
+
+const TAG = '[format-autofix]';
+
+/**
+ * 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 `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 now 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.
+ *
+ * @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 fork keeps the trailing `.` (formats the entire 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. Resolve
+  // through `getQuality` so consumers can tune via
+  // `delivery.quality.formatAutofix.timeoutMs`; an explicit caller-supplied
+  // positive integer wins over both the config and the framework default.
+  // 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 };
+}
+
+/**
+ * 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;
+}