mandrel 2.54.0 → 2.56.0

package/.agents/scripts/lib/audit-to-stories/issue-index.js

@@ -0,0 +1,83 @@
+/**
+ * lib/audit-to-stories/issue-index.js — a local index of the audit Issues a
+ * sweep must dedupe against.
+ *
+ * Dedup used to answer every finding with a **search** round-trip: one
+ * `findIssuesByFingerprint(sha)` per finding, plus a meaning-first semantic
+ * search on top. GitHub's search endpoint is rate-limited an order of magnitude
+ * harder than the list endpoint, so a full-scope sweep — hundreds of findings —
+ * spent its whole budget re-discovering the same few dozen Issues, and then
+ * degraded the rest of the run to `create`, which is how a sweep opens
+ * duplicates of Issues it already filed.
+ *
+ * The Issues that can possibly match are exactly those carrying an `audit::*`
+ * label, and there are tens of them, not hundreds. Listing them **once per run**
+ * and indexing their provenance footers answers every exact-fingerprint lookup
+ * locally, for free. The search API is then spent only where it is the only
+ * thing that can help: a finding with no exact hit, whose fingerprint may have
+ * drifted under a rewording.
+ *
+ * Pure: the caller injects the list port and this module performs no I/O.
+ */
+
+import {
+  parseFingerprintFooter,
+  parseSemanticKeyFooter,
+} from '../findings/route-finding.js';
+
+/**
+ * Add `record` to the list `map` keys under `key`.
+ *
+ * @param {Map<string, object[]>} map
+ * @param {string} key
+ * @param {object} record
+ */
+function push(map, key, record) {
+  const bucket = map.get(key);
+  if (bucket) bucket.push(record);
+  else map.set(key, [record]);
+}
+
+/**
+ * Index issues by both provenance footers the audit filers stamp.
+ *
+ * An issue carrying neither footer is indexed under nothing — it can never
+ * confirm a match, exactly as it could not when it came back from a search.
+ *
+ * @param {Array<{ number: number, state: string, body?: string }>} issues
+ * @returns {{ byFingerprint: Map<string, object[]>, bySemanticKey: Map<string, object[]>, size: number }}
+ */
+export function buildIssueIndex(issues) {
+  const byFingerprint = new Map();
+  const bySemanticKey = new Map();
+  const records = (issues ?? []).filter(
+    (issue) => typeof issue?.number === 'number',
+  );
+  for (const issue of records) {
+    for (const sha of parseFingerprintFooter(issue.body)) {
+      push(byFingerprint, sha, issue);
+    }
+    for (const key of parseSemanticKeyFooter(issue.body)) {
+      push(bySemanticKey, key, issue);
+    }
+  }
+  return { byFingerprint, bySemanticKey, size: records.length };
+}
+
+/**
+ * The union of the two local lookups for one finding, fingerprint hits first.
+ *
+ * Order matters downstream: `routeFinding` keeps the first record contributed
+ * for an issue number, and the record retrieved by exact identity is the one
+ * that should survive into confirmation.
+ *
+ * @param {{ byFingerprint: Map, bySemanticKey: Map }} index
+ * @param {string} sha
+ * @param {string} semanticKey
+ * @returns {{ exact: object[], pool: object[] }}
+ */
+export function lookupLocally(index, sha, semanticKey) {
+  const exact = index.byFingerprint.get(sha) ?? [];
+  const byKey = semanticKey ? (index.bySemanticKey.get(semanticKey) ?? []) : [];
+  return { exact, pool: [...exact, ...byKey] };
+}

package/.agents/scripts/lib/audit-to-stories/issues-file.js

@@ -0,0 +1,121 @@
+/**
+ * lib/audit-to-stories/issues-file.js — the issue corpus dedup checks against,
+ * and the one normaliser every source of it goes through.
+ *
+ * Dedup needs exactly one thing from GitHub: the list of Issues carrying an
+ * `audit::*` label. Until Story #5301 the only way to get it was the provider,
+ * which spawns `gh`, so a host without a `gh` CLI — a Claude Code cloud
+ * sandbox, where `gh` is absent and direct API access is disabled but the
+ * GitHub MCP tools work fine — could not dedup at all. Every group classified
+ * `create` and a scheduled sweep re-filed findings it had already filed.
+ *
+ * `--issues-file <path>` breaks that coupling: the host fetches the list by
+ * whatever access path it has and hands over a JSON array. Nothing here knows
+ * how it was fetched, so MCP, REST, and a cached dump are all equally valid.
+ *
+ * A file that cannot be read as an issue array is a **hard error**, never a
+ * degrade. Falling back would mean "dedup did not run" on precisely the
+ * invocation whose whole purpose is that it does — and a create-only plan the
+ * operator reads as checked is how the duplicate-filing loop starts.
+ */
+
+import fs from 'node:fs';
+
+/**
+ * Flatten one raw issue onto the `{ number, state, title, body }` shape the
+ * dedupe module reads, collapsing every closed-ish state spelling (`CLOSED`,
+ * `state_reason: not_planned`, …) onto `'closed'`.
+ *
+ * Shared by both corpus sources — the provider's `searchIssues` hits and the
+ * `--issues-file` array — so a host can hand over a raw `list_issues` result
+ * verbatim without knowing which spelling this repo's dedup expects.
+ *
+ * @param {object} hit
+ * @returns {{ number: number, state: 'open'|'closed', title: string, body: string }}
+ */
+export function normaliseIssueHit(hit) {
+  return {
+    number: hit.number,
+    state: (hit.state ?? hit.state_reason ?? 'open')
+      .toString()
+      .toLowerCase()
+      .includes('closed')
+      ? 'closed'
+      : 'open',
+    title: hit.title ?? '',
+    body: hit.body ?? '',
+  };
+}
+
+/**
+ * Read and normalise a host-supplied issue corpus.
+ *
+ * `state` is read from either `state` or `state_reason`, so a closed-as-
+ * not-planned issue is recognised however the host's API spelled it. Only
+ * `number` and `body` are load-bearing: the number identifies the match and
+ * the body carries the provenance footers dedup confirms identity against.
+ *
+ * @param {string} filePath — path to a JSON array of issues.
+ * @param {{ readFileSyncImpl?: typeof fs.readFileSync }} [seams]
+ * @returns {Array<{ number: number, state: string, title: string, body: string }>}
+ * @throws {Error} when the file is missing, unreadable, not JSON, or not an array.
+ */
+export function loadIssuesFile(
+  filePath,
+  { readFileSyncImpl = fs.readFileSync } = {},
+) {
+  let raw;
+  try {
+    raw = readFileSyncImpl(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `--issues-file: cannot read "${filePath}" (${err.message}). Dedup needs ` +
+        'the issue corpus to check against; running without it would classify ' +
+        'every group "create" and re-file findings already tracked.',
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `--issues-file: "${filePath}" is not valid JSON (${err.message}). ` +
+        'Expected a JSON array of issues, e.g. the result of listing every ' +
+        'issue labelled audit::* with state "all".',
+    );
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(
+      `--issues-file: "${filePath}" holds ${describeShape(parsed)}, not a JSON ` +
+        'array of issues. Pass the issue list itself, not the envelope wrapping it.',
+    );
+  }
+  return parsed.filter(isIssueLike).map(normaliseIssueHit);
+}
+
+/**
+ * Whether one array entry can possibly identify an issue. An entry without a
+ * numeric `number` can never confirm a match — exactly as it could not when it
+ * came back from a search — so it is dropped rather than indexed under nothing.
+ *
+ * @param {unknown} entry
+ * @returns {boolean}
+ */
+function isIssueLike(entry) {
+  return (
+    Boolean(entry) &&
+    typeof entry === 'object' &&
+    typeof entry.number === 'number'
+  );
+}
+
+/**
+ * Name what a non-array payload actually was, so the error points at the fix.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeShape(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return `a JSON ${typeof value}`;
+}

package/.agents/scripts/lib/audit-to-stories/ledger-commit.js

@@ -12,8 +12,9 @@
  * This module closes that hole from both ends:
  *
  *   - {@link runLedgerCommit} (`--auto --ledger-commit`) commits the changed
- *     ledger onto a dated `chore/audit-ledger-<YYYY-MM-DD>` branch, pushes it,
- *     and opens a PR against `project.baseBranch` through the `gh` wrapper.
+ *     ledger onto a `chore/audit-ledger-<YYYY-MM-DD>-<shortsha>` branch cut
+ *     from `origin/<base>`, pushes it, and opens a PR against
+ *     `project.baseBranch` through the `gh` wrapper.
  *     Auto-merge is never requested: a ledger PR records machine-derived state
  *     a human should glance at, so landing it stays an operator decision.
  *   - {@link resolveLedgerSummary} answers the question the *unflagged* sweep
@@ -27,9 +28,10 @@
  * complexity budget does not absorb a git driver.
  */
 
+import { DEFAULT_LEDGER_PATH } from '../findings/audit-ledger.js';
 import { gh as defaultGh } from '../gh-exec.js';
 import { gitSync } from '../git-utils.js';
-import { DEFAULT_LEDGER_PATH } from './ledger.js';
+import { openLedgerPullRequest, probeGit } from './ledger-pr.js';
 
 /** Fallback base branch when config carries no `project.baseBranch`. */
 const DEFAULT_BASE_BRANCH = 'main';
@@ -64,43 +66,6 @@ async function resolveBaseBranch(explicit) {
   return DEFAULT_BASE_BRANCH;
 }
 
-/**
- * Run a read-only git probe that must never throw: a checkout with no commits
- * (or no repository at all) is a legitimate answer of "nothing to report",
- * not a crash. The write path below uses {@link runStep} instead, where a
- * failure IS fatal.
- * @param {(cwd: string, ...args: string[]) => string} git
- * @param {string} cwd
- * @param {string[]} args
- * @returns {string} trimmed stdout, or `''` when git failed.
- */
-function probeGit(git, cwd, args) {
-  try {
-    const out = git(cwd, ...args);
-    return typeof out === 'string' ? out.trim() : '';
-  } catch (_) {
-    return '';
-  }
-}
-
-/**
- * Wrap one write step so a git or `gh` failure surfaces as a fatal error that
- * names the step that broke. Accepts sync and async steps alike.
- * @param {string} name
- * @param {() => unknown} fn
- * @returns {Promise<unknown>}
- */
-async function runStep(name, fn) {
-  try {
-    return await fn();
-  } catch (error) {
-    throw new Error(
-      `--ledger-commit failed at step "${name}": ${error?.message ?? error}`,
-      { cause: error },
-    );
-  }
-}
-
 /**
  * Inspect whether the ledger changed and whether this checkout could persist
  * it at all. Module-local: the two exported entry points below are the whole
@@ -127,14 +92,10 @@ async function assessLedgerPersistence({
   git = gitSync,
 } = {}) {
   const base = await resolveBaseBranch(baseBranch);
-  const changed =
-    probeGit(git, cwd, ['status', '--porcelain', '--', ledgerPath]).length > 0;
-  const hasOrigin = probeGit(git, cwd, ['remote'])
-    .split('\n')
-    .map((line) => line.trim())
-    .includes('origin');
-  const headBranch = probeGit(git, cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
-  const onBaseBranch = headBranch === base;
+  const probe = (args) => probeGit(git, cwd, args);
+  const changed = ledgerIsDirty(probe, ledgerPath);
+  const hasOrigin = hasOriginRemote(probe);
+  const headBranch = headBranchOf(probe);
 
   return {
     ledgerPath,
@@ -142,11 +103,46 @@ async function assessLedgerPersistence({
     changed,
     hasOrigin,
     headBranch,
-    onBaseBranch,
-    unpersisted: changed && (!hasOrigin || !onBaseBranch),
+    onBaseBranch: headBranch === base,
+    unpersisted: changed && (!hasOrigin || headBranch !== base),
   };
 }
 
+/**
+ * Has the sweep actually written new memory? Scoped to the ledger pathspec, so
+ * unrelated dirt in the checkout is never mistaken for it.
+ * @param {(args: string[]) => string} probe
+ * @param {string} ledgerPath
+ * @returns {boolean}
+ */
+function ledgerIsDirty(probe, ledgerPath) {
+  return probe(['status', '--porcelain', '--', ledgerPath]).length > 0;
+}
+
+/**
+ * Is there an `origin` to push to at all? The ephemeral-clone shape that makes
+ * a sweep amnesiac usually has none.
+ * @param {(args: string[]) => string} probe
+ * @returns {boolean}
+ */
+function hasOriginRemote(probe) {
+  return probe(['remote'])
+    .split('\n')
+    .map((line) => line.trim())
+    .includes('origin');
+}
+
+/**
+ * The branch HEAD is on, or `''` when the checkout is detached or has no
+ * commits — both of which read as "not the base branch", which is the answer
+ * the callers need.
+ * @param {(args: string[]) => string} probe
+ * @returns {string}
+ */
+function headBranchOf(probe) {
+  return probe(['rev-parse', '--abbrev-ref', 'HEAD']);
+}
+
 /**
  * Warn that the reconciled ledger has nowhere to go. Names the file, because
  * "state will be lost" is unactionable without knowing which state.
@@ -196,34 +192,13 @@ export async function resolveLedgerSummary({
 }
 
 /**
- * Compose the ledger PR body. Kept separate so the step sequence below reads
- * as a sequence and not as a string-building exercise.
- * @param {string} ledgerPath
- * @param {string} date
- * @returns {string}
- */
-function pullRequestBody(ledgerPath, date) {
-  return [
-    `Reconciles the cross-run audit ledger (\`${ledgerPath}\`) written by the`,
-    `unattended \`audit-to-stories --auto\` sweep on ${date}.`,
-    '',
-    'Ledger-only change — no source, workflow or documentation file is touched.',
-    'Merging it is what gives the next sweep a memory: without it the ledger',
-    'dies with the checkout and every later run re-proposes findings this one',
-    'already filed, and re-surfaces findings a human already rejected.',
-    '',
-    'Auto-merge is deliberately not requested: the ledger records machine-derived',
-    'lifecycle state, and a human glance before it lands is the point.',
-  ].join('\n');
-}
-
-/**
- * Commit the changed ledger onto a dated branch and open a PR for it.
+ * Commit the changed ledger onto a unique branch cut from the remote base and
+ * open a PR for it.
  *
- * Skipped — returning `{ committed: false }` with a `reason` — when the ledger
- * did not change. Every git/`gh` failure is fatal and names its step; the
- * caller runs this *after* printing the run summary, so a broken remote never
- * costs the operator the sweep's findings.
+ * Assesses the checkout, then hands the whole write sequence to
+ * {@link openLedgerPullRequest}. Every git/`gh` failure is fatal and names its
+ * step; the caller runs this *after* printing the run summary, so a broken
+ * remote never costs the operator the sweep's findings.
  *
  * @param {object} [params]
  * @param {string} [params.ledgerPath]
@@ -233,7 +208,8 @@ function pullRequestBody(ledgerPath, date) {
  * @param {{ pr: { create: (flags: string[]) => Promise<unknown> } }} [params.gh]
  * @param {Date|string|number} [params.now]
  * @returns {Promise<{ committed: boolean, reason?: string, branch?: string,
- *   subject?: string, baseBranch?: string, ledgerPath: string }>}
+ *   subject?: string, baseBranch?: string, prUrl?: string|null,
+ *   resumed?: boolean, ledgerPath: string }>}
  */
 export async function runLedgerCommit({
   ledgerPath = DEFAULT_LEDGER_PATH,
@@ -249,42 +225,12 @@ export async function runLedgerCommit({
     cwd,
     git,
   });
-  if (!state.changed) {
-    return { committed: false, reason: 'ledger-unchanged', ledgerPath };
-  }
-
-  const date = isoDate(now);
-  const branch = `chore/audit-ledger-${date}`;
-  const subject = `chore(audit): reconcile audit ledger ${date}`;
-
-  await runStep('create-branch', () => git(cwd, 'checkout', '-b', branch));
-  await runStep('stage-ledger', () => git(cwd, 'add', '--', ledgerPath));
-  // The `-- <path>` pathspec is what keeps the commit ledger-only even when
-  // the sweep's checkout carries unrelated dirt.
-  await runStep('commit-ledger', () =>
-    git(cwd, 'commit', '-m', subject, '--', ledgerPath),
-  );
-  await runStep('push-branch', () =>
-    git(cwd, 'push', '--set-upstream', 'origin', branch),
-  );
-  await runStep('open-pull-request', () =>
-    gh.pr.create([
-      '--base',
-      state.baseBranch,
-      '--head',
-      branch,
-      '--title',
-      subject,
-      '--body',
-      pullRequestBody(ledgerPath, date),
-    ]),
-  );
-
-  return {
-    committed: true,
-    branch,
-    subject,
-    baseBranch: state.baseBranch,
+  return openLedgerPullRequest({
+    state,
     ledgerPath,
-  };
+    cwd,
+    git,
+    gh,
+    date: isoDate(now),
+  });
 }