mandrel 2.56.0 → 2.57.0

package/.agents/scripts/lib/orchestration/plan-persist/persist-helpers.js

@@ -3,224 +3,187 @@
  *
  * Exports:
  *   - `resolveBaseBranchRef(config)` — the one place the persist gates learn
- *     which ref to probe.
- *   - `validateTickets(tickets, config)` — runs the cross-link, model-capacity,
- *     freshness, and task-body validators in one pass. Capacity settings are
- *     explicit inputs so the validator and decomposer share one live delivery
- *     envelope instead of silently falling back to framework defaults.
- *   - `makeDefaultFanOutCounter({ baseBranchRef, cwd, git })` — production
- *     fan-out probe used by the conflict policy.
+ *     which branch name the operator configured.
+ *
+ * The ref the probes read is resolved per checkout (`resolveProbeRef`): the
+ * local branch when it exists, else its `origin/` tracking ref (a PR
+ * checkout on CI has no local `main`), else nothing — a shallow checkout
+ * with no base at all skips the probes instead of reading every path as
+ * absent.
+ *   - `validateTickets(tickets, config, opts)` — repairs the mechanical
+ *     `changes[]` formalities against the base branch, then runs the
+ *     cross-link, freshness, and task-body validators in one pass.
+ *
+ * Story #5312 deleted the fan-out probe that lived here: the delete
+ * blast-radius count never refused a real plan, and the `git grep` it paid
+ * for on every persist bought a warning nobody acted on.
  *
  * @module lib/orchestration/plan-persist/persist-helpers
  */
 
-import posix from 'node:path/posix';
 import { gitSpawn } from '../../git-utils.js';
 import { validateTaskBodies } from '../task-body-validator.js';
 import { validateAndNormalizeTickets } from '../ticket-validator.js';
-import { resolveConflictPolicy } from '../ticket-validator-conflicts.js';
-import { normalizeVerifyTiers } from '../verify-tier-repair.js';
+import { repairChangeEntries } from './changes-repair.js';
 
 /**
- * Extensions an import specifier may elide. Probed longest-path-first when
- * resolving an extensionless specifier back onto a concrete repo path.
+ * Resolve the ref the persist gates probe against.
+ *
+ * The canonical resolved config carries the base branch at
+ * `project.baseBranch` (`lib/config-resolver.js` defaults it to `main`).
+ * This helper used to read `config.baseBranch` — a key the resolver never
+ * produces — so every freshness / file-assumption probe silently targeted
+ * the literal `main` regardless of configuration. Benign in a repo whose
+ * base branch *is* `main`; wrong for any consumer that configured something
+ * else (Story #4541).
+ *
+ * The flat `config.baseBranch` fallback is retained for the legacy
+ * `settings`-bag callers that pass `{ baseBranch, paths, planning }`.
+ *
+ * @param {object} [config] Resolved config, or a legacy settings bag.
+ * @returns {string}
  */
-const RESOLVABLE_EXTENSIONS = ['', '.js', '.mjs', '.cjs', '.jsx', '.json'];
-
-/** Every quoted string on a candidate line — the specifier lives in one. */
-const QUOTED_RE = /['"]([^'"\n]+)['"]/g;
-
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+export function resolveBaseBranchRef(config) {
+  return config?.project?.baseBranch ?? config?.baseBranch ?? 'main';
 }
 
 /**
- * The specifier tails an importer of `path` could plausibly write as the
- * final segment of its quoted specifier: the basename, the basename minus
- * its extension, and — for a directory-index module — the directory name
- * (`./foo` resolving to `foo/index.js`).
- *
- * This is a *candidate* net only. It is deliberately generous because the
- * resolution pass below re-checks every hit against the real path; a tail
- * that over-matches costs one extra resolve, a tail that under-matches
- * loses a genuine importer.
+ * Does `ref` name a commit in the repo at `cwd`?
+ *
+ * @param {string} ref
+ * @param {string} cwd
+ * @returns {boolean}
  */
-function specifierTails(path) {
-  const base = posix.basename(path);
-  const ext = posix.extname(base);
-  const stem = ext ? base.slice(0, -ext.length) : base;
-  const tails = new Set([base, stem]);
-  if (stem === 'index') {
-    const dir = posix.basename(posix.dirname(path));
-    if (dir && dir !== '.') tails.add(dir);
-  }
-  return [...tails].filter((t) => t.length > 0);
+function refResolves(ref, cwd) {
+  return (
+    gitSpawn(cwd, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`)
+      .status === 0
+  );
 }
 
 /**
- * ERE matching a line that carries an `import` / `export … from` /
- * `require(` / dynamic `import(` whose quoted specifier *ends* at one of
- * `tails`. The `(^|/)`-equivalent guard (`([^'"]*\/)?`) is what keeps
- * `notification.js` from matching `push-notification.js`.
+ * Resolve the configured base branch to a ref the footprint probes can read
+ * in this checkout, or `null` when none exists.
+ *
+ * A developer checkout carries a local `main`; a CI pull-request checkout
+ * (`actions/checkout` at the merge ref, detached) carries only
+ * `origin/main`; a shallow smoke checkout carries neither. Probing the
+ * bare branch name in the last two answers "absent" for every path, which
+ * turns each bare-path repair into a `creates` and every declared path into
+ * a stale reference. So: the local branch when it resolves, else its
+ * `origin/` tracking ref when that does, else `null` — the caller then
+ * skips the probes and says so, rather than reporting the tree as missing.
+ *
+ * @param {{ baseBranch: string, cwd?: string }} opts
+ * @returns {string|null}
  */
-function buildProbePattern(tails) {
-  const alt = tails.map(escapeRegExp).join('|');
-  return `(from|require|import)[[:space:]]*\\(?[[:space:]]*['"]([^'"]*/)?(${alt})['"]`;
+function resolveProbeRef({ baseBranch, cwd }) {
+  const repo = cwd ?? process.cwd();
+  const candidates = [baseBranch, `origin/${baseBranch}`];
+  return candidates.find((ref) => refResolves(ref, repo)) ?? null;
 }
 
 /**
- * Resolve a relative specifier written in `importerPath` back onto a repo
- * path and report whether it names `deletedPath`.
- *
- * **Known boundary:** only relative (`./`, `../`) specifiers resolve. A
- * consumer repo that imports its own modules through bare specifiers or a
- * path alias (`#lib/x`, `@app/x`, a `tsconfig` `paths` entry) would
- * under-count, because resolving those needs the resolver config this probe
- * deliberately does not read. Mandrel's own internal imports are all
- * relative. Under-counting is the *quiet* failure direction — it argues for
- * a deletion rather than against one — so if alias-importing consumers
- * appear, this is the place to teach the probe their resolver.
+ * Default git probe: returns true when `path` exists at `ref` in the cwd repo.
+ * `git cat-file -e <ref>:<path>` is the standard low-cost existence check —
+ * the same probe the validator's own gates run, so the repair pass and the
+ * gates cannot disagree about what is at base.
+ *
+ * @param {{ baseBranchRef: string, path: string, cwd?: string }} opts
+ * @returns {boolean}
  */
-function specifierResolvesTo(importerPath, specifier, deletedPath) {
-  if (!specifier.startsWith('./') && !specifier.startsWith('../')) return false;
-  const resolved = posix.normalize(
-    posix.join(posix.dirname(importerPath), specifier),
+function defaultGitRunner({ baseBranchRef, path, cwd }) {
+  const result = gitSpawn(
+    cwd ?? process.cwd(),
+    'cat-file',
+    '-e',
+    `${baseBranchRef}:${path}`,
   );
-  for (const ext of RESOLVABLE_EXTENSIONS) {
-    if (`${resolved}${ext}` === deletedPath) return true;
-    if (ext && `${resolved}/index${ext}` === deletedPath) return true;
-  }
-  return false;
+  return result.status === 0;
 }
 
 /**
- * Quote one argv entry so the reported probe is **runnable as emitted**.
- *
- * The probe is the operator's route to checking the number, so it has to
- * survive a paste into a shell. Unquoted, the ERE's `(`, `|`, `[[:space:]]`
- * and `?` are glob/grouping metacharacters: zsh fails the paste with
- * `no matches found` *and exits 0*, which reads as "zero importers" — the
- * gate's own audit trail would then argue for the deletion it is meant to
- * question (Story #4547).
+ * The `existsAtBase` predicate the `changes[]` repair pass probes with. With
+ * no base to read, a bare bullet is taken as the in-place edit it almost
+ * always is.
+ *
+ * @param {{ baseBranchRef: string|null, cwd?: string, gitRunner?: Function }} opts
+ * @returns {(path: string) => boolean}
  */
-function shellQuote(value) {
-  if (/^[A-Za-z0-9_./-]+$/.test(value)) return value;
-  return `'${value.replaceAll("'", "'\\''")}'`;
+function makeExistsAtBase({ baseBranchRef, cwd, gitRunner }) {
+  if (baseBranchRef === null) return () => true;
+  const runner = gitRunner ?? defaultGitRunner;
+  return (path) => Boolean(runner({ baseBranchRef, path, cwd }));
 }
 
 /**
- * Parse one `git grep -n` output line of the form `<ref>:<path>:<lineno>:<text>`.
+ * The one warning a checkout with no readable base leaves on the dry-run.
+ *
+ * @param {string} baseBranch
+ * @param {string|null} baseBranchRef
+ * @returns {string[]}
  */
-function parseGrepLine(line, baseBranchRef) {
-  const prefix = `${baseBranchRef}:`;
-  if (!line.startsWith(prefix)) return null;
-  const rest = line.slice(prefix.length);
-  const pathEnd = rest.indexOf(':');
-  if (pathEnd === -1) return null;
-  const path = rest.slice(0, pathEnd);
-  const afterPath = rest.slice(pathEnd + 1);
-  const lineEnd = afterPath.indexOf(':');
-  if (lineEnd === -1) return null;
-  return { path, text: afterPath.slice(lineEnd + 1) };
+function probeSkipWarnings(baseBranch, baseBranchRef) {
+  if (baseBranchRef !== null) return [];
+  return [
+    `base branch ${baseBranch} does not resolve in this checkout (tried ` +
+      `${baseBranch} and origin/${baseBranch}) — footprint probes skipped; ` +
+      'the plan summary reports its references as ambiguous, not stale.',
+  ];
 }
 
 /**
- * Default fan-out probe — resolves the *importers* of the deleted module at
- * `baseBranchRef`, and reports the referencing files alongside the exact
- * probe that produced them.
- *
- * Two-stage, because accuracy and cost pull in opposite directions:
- *
- *   1. `git grep -n -E` narrows the tree to lines whose quoted import /
- *      require specifier could name the module (final-segment match).
- *   2. Each candidate specifier is resolved against its own importer's
- *      directory and compared to the deleted path. Only a real resolution
- *      counts.
- *
- * The predecessor (Story #2962) grepped the basename stem as a bare word
- * across the whole tree, so a module named `notification` or `options`
- * reported dozens of call sites drawn from prose, schemas, and unrelated
- * modules — and the gate that fired on that number told the operator to
- * split a migration that did not exist. It also returned 0 without probing
- * for any stem under three characters, under-reporting in silence. Both are
- * gone: coupling is measured by resolution, not vocabulary (Story #4547).
- *
- * @returns {(arg: { path: string }) => { count: number, files: string[], probe: string }}
+ * Attach non-enumerable bookkeeping to the validated array.
+ *
+ * @param {object[]} validated
+ * @param {Record<string, unknown>} extras
  */
-export function makeDefaultFanOutCounter({ baseBranchRef, cwd, git } = {}) {
-  const spawn = git?.gitSpawn ?? gitSpawn;
-  return ({ path }) => {
-    const tails = specifierTails(path);
-    const pattern = buildProbePattern(tails);
-    const args = ['grep', '-n', '-E', '--full-name', pattern, baseBranchRef];
-    const probe = `git ${args.map(shellQuote).join(' ')}`;
-    const result = spawn(cwd ?? process.cwd(), ...args);
-    // git grep exits 1 on "no matches" — an empty result, not a failure.
-    if (result.status !== 0) return { count: 0, files: [], probe };
-    const files = new Set();
-    for (const line of result.stdout.split('\n')) {
-      if (line.trim().length === 0) continue;
-      const hit = parseGrepLine(line, baseBranchRef);
-      // The deleted module's own self-references are not call sites.
-      if (!hit || hit.path === path) continue;
-      for (const match of hit.text.matchAll(QUOTED_RE)) {
-        if (specifierResolvesTo(hit.path, match[1], path)) {
-          files.add(hit.path);
-          break;
-        }
-      }
-    }
-    const sorted = [...files].sort();
-    return { count: sorted.length, files: sorted, probe };
-  };
+function defineHidden(validated, extras) {
+  for (const [key, value] of Object.entries(extras)) {
+    Object.defineProperty(validated, key, {
+      value,
+      enumerable: false,
+      configurable: true,
+      writable: true,
+    });
+  }
 }
 
 /**
- * Resolve the ref the persist gates probe against.
- *
- * The canonical resolved config carries the base branch at
- * `project.baseBranch` (`lib/config-resolver.js` defaults it to `main`).
- * This helper used to read `config.baseBranch` — a key the resolver never
- * produces — so every freshness / file-assumption / fan-out probe silently
- * targeted the literal `main` regardless of configuration. Benign in a repo
- * whose base branch *is* `main`; wrong for any consumer that configured
- * something else (Story #4541).
+ * Repair the mechanical `changes[]` formalities, then validate.
  *
- * The flat `config.baseBranch` fallback is retained for the legacy
- * `settings`-bag callers that pass `{ baseBranch, paths, planning }`.
+ * Repair before judging (Story #5312, the shape Story #5005 set for the
+ * verify tier): a plain-string bullet or a trailing parenthetical is
+ * rewritten into `{ path, assumption }` by probing the base branch, and
+ * each rewrite is reported on the returned array's `repairs` so the dry-run
+ * can print it. An entry nothing path-shaped can be salvaged from survives
+ * untouched and still hard-errors in `validateTaskBodies`.
  *
- * @param {object} [config] Resolved config, or a legacy settings bag.
- * @returns {string}
+ * @param {object[]} tickets Mutated in place.
+ * @param {object} config Resolved config.
+ * @param {{ cwd?: string, gitRunner?: Function }} [opts]
+ * @returns {object[] & { findings: object[], errors: string[], warnings: string[], normalizations: object[], repairs: object[], probeRef: string|null }}
  */
-export function resolveBaseBranchRef(config) {
-  return config?.project?.baseBranch ?? config?.baseBranch ?? 'main';
-}
-
 export function validateTickets(tickets, config, opts = {}) {
-  const baseBranchRef = resolveBaseBranchRef(config);
-  const conflictPolicy = resolveConflictPolicy(config);
-  if (typeof opts.fanOutCounter === 'function') {
-    conflictPolicy.fanOutCounter = opts.fanOutCounter;
-  } else {
-    conflictPolicy.fanOutCounter = makeDefaultFanOutCounter({
+  const baseBranch = resolveBaseBranchRef(config);
+  const baseBranchRef = resolveProbeRef({ baseBranch, cwd: opts.cwd });
+  const repairs = repairChangeEntries(tickets, {
+    existsAtBase: makeExistsAtBase({
       baseBranchRef,
       cwd: opts.cwd,
-    });
-  }
+      gitRunner: opts.gitRunner,
+    }),
+  });
   const validated = validateAndNormalizeTickets(tickets, {
-    baseBranchRef,
-    conflictPolicy,
-    modelCapacity: opts.modelCapacity,
+    baseBranchRef: baseBranchRef ?? undefined,
+    gitRunner: opts.gitRunner,
     // Thread the repo cwd into the AC-freshness / file-assumption git
     // probes (#4474 PR7) — without it they silently ran against
     // process.cwd(), which is only the repo root by coincidence.
     cwd: opts.cwd,
   });
-  // Repair before judging (Story #5005): a `verify[]` entry whose tier the
-  // validator can already infer is auto-corrected rather than rejected, so a
-  // mechanically-fixable formality no longer costs a re-authoring round. An
-  // uninferable entry survives untouched and still hard-errors below.
-  normalizeVerifyTiers(validated);
+  validated.warnings.push(...probeSkipWarnings(baseBranch, baseBranchRef));
   validateTaskBodies(validated);
+  defineHidden(validated, { repairs, probeRef: baseBranchRef });
   return validated;
 }