mandrel 2.31.0 → 2.33.0

package/.agents/scripts/lib/findings/route-finding.js

@@ -35,11 +35,11 @@ import { fingerprintSeverity } from './severity.js';
 const SEP = '␟'; // unit separator — keeps fingerprint fields unambiguous
 const MARKER = 'audit-fingerprints:';
 const SEMANTIC_MARKER = 'audit-semantic-keys:';
-const SHA1_RE = /^[0-9a-f]{40}$/;
+export const SHA1_RE = /^[0-9a-f]{40}$/;
 // A semantic key round-trips through a comma-joined footer, so it must not
 // carry a comma or a `>` (which would truncate the HTML comment). Both are
 // stripped when the key is built, so this guard is defence-in-depth.
-const SEMANTIC_KEY_RE = /^[^,>]+$/;
+export const SEMANTIC_KEY_RE = /^[^,>]+$/;
 
 /**
  * Normalise a single scalar identity field to a stable string.
@@ -343,12 +343,59 @@ function decisionForIssue(issue) {
   return state === 'closed' ? 'regression-of-closed' : 'update-existing';
 }
 
+/**
+ * Resolve the pool that **attributes** a finding, out of everything that
+ * confirmed it (Story #5045).
+ *
+ * Confirmation admits two different strengths of claim, and collapsing them
+ * was the source of two wrong routes:
+ *
+ * - An issue carrying the finding's exact **fingerprint** owns it. That is
+ *   identity: this issue tracks *this* finding.
+ * - An issue matching only on the location-based **semantic key** is merely
+ *   adjacent: it tracks *a* finding at the same `area␟primaryFile`.
+ *
+ * Owners win outright when any exist. Location-only matches are not discarded
+ * — they are the whole point of the semantic key and remain the pool when
+ * nothing carries the fingerprint (a reworded finding at an unchanged
+ * location). The pool is sorted by issue number so a genuine tie resolves to
+ * the earliest-filed issue rather than to whatever order the search port
+ * happened to return.
+ *
+ * @param {Array<{ number: number, state: string, body?: string }>} confirmed
+ * @param {string} sha
+ * @returns {Array<{ number: number, state: string }>}
+ */
+function attributedPool(confirmed, sha) {
+  const owns = (issue) => issueCarriesFingerprint(issue, sha);
+  const owners = confirmed.filter(owns);
+  const pool = owners.length > 0 ? owners : confirmed.filter((i) => !owns(i));
+  return [...pool].sort((a, b) => (a?.number ?? 0) - (b?.number ?? 0));
+}
+
 /**
  * Decide the final route from a confirmed-match pool (issues that both
- * surfaced in the candidate/search pass AND carry the finding's fingerprint
- * in their footer). Shared by both the semantic-first and fingerprint-only
- * code paths so the decision enum is identical regardless of how candidates
- * were gathered.
+ * surfaced in the candidate/search pass AND carry a confirming footer).
+ * Shared by both the semantic-first and fingerprint-only code paths so the
+ * decision enum is identical regardless of how candidates were gathered.
+ *
+ * **Attribution decides, not array order (Story #5045).** The pool used to be
+ * read flat, which produced two wrong answers whenever more than one issue
+ * confirmed:
+ *
+ *   1. Two open matches routed `duplicate` pinned to `open[0]` — whichever
+ *    issue the search port happened to return first. With per-Story
+ *    provenance that pick is answerable rather than arbitrary: the issue
+ *    carrying the finding's own fingerprint owns it, and a sibling matching
+ *    only by location does not.
+ *   2. Any open match at all masked a closed one, so a finding whose
+ *    fingerprint is owned by a **closed** Story routed `update-existing`
+ *    against an open neighbour — a genuine regression filed as a
+ *    business-as-usual update. Attribution restores it: state is read off the
+ *    owning issue, not off whatever else shares its location.
+ *
+ * {@link attributedPool} owns that selection; the decision below reads only
+ * the pool it returns.
  *
  * @param {Array<{ number: number, state: string }>} confirmed
  * @param {string} sha
@@ -359,7 +406,8 @@ function decideFromConfirmed(confirmed, sha) {
     return { decision: 'new', matchedIssue: null, fingerprint: sha };
   }
 
-  const open = confirmed.filter((h) => normaliseField(h.state) === 'open');
+  const attributed = attributedPool(confirmed, sha);
+  const open = attributed.filter((h) => normaliseField(h.state) === 'open');
   if (open.length > 1) {
     return { decision: 'duplicate', matchedIssue: open[0], fingerprint: sha };
   }
@@ -371,7 +419,7 @@ function decideFromConfirmed(confirmed, sha) {
     };
   }
 
-  const closed = confirmed[0];
+  const closed = attributed[0];
   return {
     decision: decisionForIssue(closed),
     matchedIssue: closed,
@@ -484,4 +532,5 @@ export const __testing = {
   decideFromConfirmed,
   issueCarriesSemanticKey,
   parseSemanticKeyFooter,
+  attributedPool,
 };

package/.agents/scripts/lib/fs-walk.js

@@ -0,0 +1,52 @@
+/**
+ * fs-walk.js — the one recursive file walker the lint scripts share.
+ *
+ * `check-lifecycle-lint.js` and `lint-label-vocabulary.js` each carried a
+ * private copy of this generator, differing only in the extension they
+ * matched — the second one's comment said so outright ("mirrors the walker
+ * shape in check-lifecycle-lint.js"). Story #5024 extracted it: shrinking
+ * check-lifecycle-lint.js pushed its duplication percentage up on an unchanged
+ * clone count, which is the ratchet correctly pointing at boilerplate that
+ * should not have been copied twice.
+ *
+ * A missing directory yields nothing rather than throwing. That is
+ * load-bearing, not lenient: the lint surfaces are directories a deletion can
+ * legitimately remove (Story #5024 deleted `lifecycle/listeners/`), and a scan
+ * of an absent path is vacuously clean, not an error. Every other `readdir`
+ * failure — a permission error, a file where a directory was expected —
+ * propagates, so a genuinely broken scan cannot read as clean.
+ */
+
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Walk a directory tree synchronously, yielding absolute paths of every file
+ * whose name ends with `extension`.
+ *
+ * @param {string} dir Absolute directory to walk.
+ * @param {string} extension Extension to match, leading dot included (`.js`).
+ * @param {{ readDir?: typeof readdirSync }} [ports] Injectable for tests.
+ * @returns {Generator<string, void, void>}
+ */
+export function* walkFilesByExtension(
+  dir,
+  extension,
+  { readDir = readdirSync } = {},
+) {
+  let entries;
+  try {
+    entries = readDir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  for (const entry of entries) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkFilesByExtension(p, extension, { readDir });
+    } else if (entry.isFile() && entry.name.endsWith(extension)) {
+      yield p;
+    }
+  }
+}

package/.agents/scripts/lib/git-branch-lifecycle.js

@@ -129,8 +129,8 @@ export function classifyBranchSeed({ localHas, remoteHas }) {
  *     throws (the v2 standalone path has no concurrent creator to race).
  *
  * The asymmetric surrounding wrappers (merged-sweep, fast-forward,
- * donor-prime, workspace-verify, phase-timer) are deliberately NOT folded
- * in — they stay in their respective callers.
+ * donor-prime, workspace-verify) are deliberately NOT folded in — they stay
+ * in their respective callers.
  *
  * Caller-specific log lines and error text are passed in as the `messages`
  * data bag so behaviour stays byte-identical to the pre-extraction switches.

package/.agents/scripts/lib/git-utils.js

@@ -28,6 +28,7 @@
  */
 
 import { execFileSync, spawnSync } from 'node:child_process';
+import { execFileCapture, spawnCapture } from './child-exec.js';
 
 /**
  * Result of a `gitSpawn` invocation. Field semantics match `child_process.spawnSync`
@@ -40,23 +41,6 @@ import { execFileSync, spawnSync } from 'node:child_process';
  * @property {string} stderr - Trimmed stderr.
  */
 
-/**
- * Explicit stdout ceiling for every git invocation in this module.
- *
- * Both child-process runners default `maxBuffer` to 1 MB, at which point the
- * child is killed and the call fails with `ENOBUFS` for a reason unrelated to
- * git. The push path is the sharp edge: `git push` relays the whole `pre-push`
- * hook output, which is unbounded by design — this repo's hook emits a full
- * `check-baselines` envelope, measured at 2,166,643 bytes, so every Story
- * close failed at `phase: push` once hooks became reachable inside worktrees.
- *
- * 64 MB is the bound Story #4914 already set on `baselines/git-base.js` for
- * the identical failure, matching `run-test-profile.js`,
- * `audit-baselines/trend.js` and `audit-baselines/weights.js`. This module was
- * missed by that sweep.
- */
-const MAX_BUFFER_BYTES = 64 * 1024 * 1024;
-
 let _execFileSync = execFileSync;
 let _spawnSync = spawnSync;
 
@@ -129,26 +113,30 @@ export function __setGitRunners(exec, spawn) {
  * the interface returned by {@link createGitInterface} route through this —
  * they differ only in which `execFileSync` they hand it.
  *
+ * Buffer, shell and encoding policy belong to
+ * [`child-exec.js`](child-exec.js); this function contributes only the git
+ * specifics (argv prefix, cwd, scrubbed env).
+ *
  * @param {typeof execFileSync} exec
  * @param {string} cwd
  * @param {string[]} args
  * @returns {string} Trimmed stdout text.
  */
 function runGitSync(exec, cwd, args) {
-  return exec('git', args, {
-    cwd,
-    encoding: 'utf8',
-    stdio: ['pipe', 'pipe', 'pipe'],
-    shell: false,
-    env: cleanGitEnv(),
-    maxBuffer: MAX_BUFFER_BYTES,
-  }).trim();
+  return String(
+    execFileCapture('git', args, {
+      run: exec,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: cleanGitEnv(),
+    }),
+  ).trim();
 }
 
 /**
  * The **single** non-throwing git runner — the `spawnSync` counterpart of
  * {@link runGitSync}, normalising `status`/stdout/stderr into a
- * {@link GitResult}.
+ * {@link GitResult} via the shared exec surface.
  *
  * @param {typeof spawnSync} spawn
  * @param {string} cwd
@@ -156,19 +144,11 @@ function runGitSync(exec, cwd, args) {
  * @returns {GitResult}
  */
 function runGitSpawn(spawn, cwd, args) {
-  const result = spawn('git', args, {
+  return spawnCapture('git', args, {
+    run: spawn,
     cwd,
-    stdio: 'pipe',
-    encoding: 'utf-8',
-    shell: false,
     env: cleanGitEnv(),
-    maxBuffer: MAX_BUFFER_BYTES,
   });
-  return {
-    status: result.status ?? 1,
-    stdout: (result.stdout ?? '').trim(),
-    stderr: (result.stderr ?? '').trim(),
-  };
 }
 
 /**

package/.agents/scripts/lib/knip-config-resolver.js

@@ -0,0 +1,181 @@
+/**
+ * knip-config-resolver.js — resolve a repository's knip configuration the way
+ * knip itself would, and hand back its declared entry patterns.
+ *
+ * Split out of `knip-entry-sync.js` (Story #5039) because these are two
+ * concerns that change for different reasons: *what knip's config says* tracks
+ * knip's own releases, while *which CLIs something invokes* tracks this
+ * repository's callers. Keeping them in one file also pushed that module's
+ * maintainability index below its floor.
+ *
+ * Why not read the file ourselves: #5026 hardcoded
+ * `JSON.parse(<root>/knip.json)`, so all seven of knip's other config
+ * locations plus `package.json#knip` resolved to ENOENT and failed the gate
+ * closed. That made it unusable in exactly the repositories that adopt the
+ * shared `knip.base.json` — knip 6 has no root-level `extends`, so inheriting
+ * the base means spreading it inside a TypeScript module, which a static
+ * `knip.json` structurally cannot express.
+ *
+ * Going through `createOptions` also drops the assumption that `entry` is
+ * *statically declared*. A config may build the array programmatically, so
+ * even a purpose-built `knip.config.ts` parser would read the wrong thing;
+ * knip evaluates the module and returns the computed value.
+ */
+
+/**
+ * Load knip's own config resolver.
+ *
+ * Deliberately a dynamic import behind an injectable seam. `knip` is declared
+ * in `runtime-deps.json` as an **optional** dependency, mirroring `typescript`:
+ * the `.agents/` payload is materialized into consumers that may not run knip
+ * at all, so an unresolvable `knip` must degrade to the skip path rather than
+ * crash the gate at module load — and must never be preflight-blocked.
+ *
+ * @returns {Promise<{ createOptions?: Function }>}
+ */
+function importKnipSession() {
+  return import('knip/session');
+}
+
+/**
+ * Collect every declared entry pattern from a resolved knip configuration.
+ *
+ * Entries live in two places and #5026 read only the first. A pnpm-workspace
+ * config — the shape that made this gate unusable in `Beestera/swarm-os` —
+ * declares them per workspace, so a config with no top-level `entry` at all is
+ * still fully enumerated. A named workspace's patterns are workspace-relative
+ * and are joined to the workspace name; the root workspace (`.`) is already
+ * repo-relative. A leading `!` is knip's *negation* marker (as opposed to the
+ * trailing production marker) and stays at the front of the pattern rather
+ * than getting buried behind the workspace prefix.
+ *
+ * `sawEntryArray` separates "declared nothing under `.agents/scripts/`" — a
+ * legitimate result, reported as `missing` divergences — from "this config
+ * enumerates no entry points anywhere", which leaves the gate nothing to
+ * compare against.
+ *
+ * @param {object} parsedConfig knip's schema-parsed configuration
+ * @returns {{ patterns: string[], sawEntryArray: boolean }}
+ */
+function collectEntryPatterns(parsedConfig) {
+  const patterns = [];
+  let sawEntryArray = false;
+
+  const push = (value, prefix) => {
+    if (typeof value !== 'string') return;
+    if (!prefix) patterns.push(value);
+    else if (value.startsWith('!'))
+      patterns.push(`!${prefix}${value.slice(1)}`);
+    else patterns.push(`${prefix}${value}`);
+  };
+
+  const addAll = (entry, prefix) => {
+    if (!Array.isArray(entry)) return;
+    sawEntryArray = true;
+    for (const value of entry) push(value, prefix);
+  };
+
+  addAll(parsedConfig?.entry, '');
+
+  const workspaces = parsedConfig?.workspaces;
+  if (workspaces && typeof workspaces === 'object') {
+    for (const [name, workspace] of Object.entries(workspaces)) {
+      const trimmed = name.replace(/^\.\/+/, '').replace(/\/+$/, '');
+      const prefix = trimmed === '' || trimmed === '.' ? '' : `${trimmed}/`;
+      addAll(workspace?.entry, prefix);
+    }
+  }
+
+  return { patterns, sawEntryArray };
+}
+
+/**
+ * Resolve the entry patterns knip would see for `repoRoot`.
+ *
+ * Three outcomes, deliberately distinct — collapsing the first two is how a
+ * broken configuration would come to look like an absent one:
+ *
+ *   skipped — nothing to check (no config file, no `package.json#knip`, or no
+ *     resolvable `knip`). The gate exits 0. This is what makes it safe to wire
+ *     into every consumer, matching `qa.gherkinLint`'s opt-in posture.
+ *   error — a configuration exists but could not be resolved, or enumerates no
+ *     entry points at all. The gate exits 2.
+ *   resolved — `patterns` carries every declared entry, top-level and
+ *     per-workspace, with knip's trailing `!` production markers intact.
+ *
+ * @param {{ repoRoot: string, loadKnipSession?: () => Promise<object> }} opts
+ * @returns {Promise<{
+ *   patterns: string[],
+ *   configFilePath: string | null,
+ *   skipped: string | null,
+ *   error: string | null,
+ * }>}
+ */
+export async function resolveKnipEntryPatterns({
+  repoRoot,
+  loadKnipSession = importKnipSession,
+}) {
+  const nothing = { patterns: [], configFilePath: null };
+
+  let createOptions;
+  try {
+    ({ createOptions } = await loadKnipSession());
+  } catch (error) {
+    return {
+      ...nothing,
+      skipped: `the "knip" package is not resolvable from ${repoRoot} (${error.message})`,
+      error: null,
+    };
+  }
+  if (typeof createOptions !== 'function') {
+    return {
+      ...nothing,
+      skipped: null,
+      error:
+        'the installed "knip" does not export createOptions from "knip/session" — this gate needs knip 6 or newer',
+    };
+  }
+
+  let options;
+  try {
+    options = await createOptions({ cwd: repoRoot, args: {} });
+  } catch (error) {
+    return {
+      ...nothing,
+      skipped: null,
+      error: `cannot resolve the knip configuration: ${error.message}`,
+    };
+  }
+
+  const configFilePath = options?.configFilePath ?? null;
+  if (!configFilePath) {
+    return {
+      ...nothing,
+      skipped: `no knip configuration found under ${repoRoot} (no config file, no package.json#knip)`,
+      error: null,
+    };
+  }
+
+  const { patterns, sawEntryArray } = collectEntryPatterns(
+    options?.parsedConfig,
+  );
+  if (!sawEntryArray) {
+    return {
+      patterns: [],
+      configFilePath,
+      skipped: null,
+      error: `${configFilePath} declares no "entry" array, at the top level or in any workspace`,
+    };
+  }
+
+  return { patterns, configFilePath, skipped: null, error: null };
+}
+
+/**
+ * Test-only seam. Not API — `collectEntryPatterns` is exercised directly so the
+ * workspace-prefix and negation rules can be pinned without a fixture tree.
+ */
+export const __testing = Object.freeze({
+  collectEntryPatterns,
+  importKnipSession,
+});