mandrel 2.16.0 → 2.18.0

package/.agents/scripts/drain-pending-cleanup.js

@@ -39,8 +39,44 @@ const progress = Logger.createProgress('drain-pending-cleanup', {
   stderr: false,
 });
 
-async function main() {
+/**
+ * The drain core, extracted from the CLI shell so the whole decision table —
+ * empty manifest, dry-run report, drain + escalate reporting — is reachable
+ * without a real worktree ledger or a real process kill.
+ *
+ * Every seam on the optional final `deps` parameter defaults to the real
+ * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main` and
+ * every production caller are unchanged.
+ *
+ * @param {string[]} [argv]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   readManifestImpl?: typeof readManifest,
+ *   findHoldersInPathImpl?: typeof findHoldersInPath,
+ *   forceDrainImpl?: typeof forceDrainPendingCleanup,
+ *   gitImpl?: typeof gitUtils,
+ *   projectRoot?: string,
+ *   progressImpl?: (phase: string, message: string) => void,
+ *   logger?: { error: Function },
+ * }} [deps]
+ * @returns {Promise<{ drained: number[], remaining: number } | { remaining: number }>}
+ */
+export async function runDrainPendingCleanup(
+  argv = process.argv.slice(2),
+  deps = {},
+) {
+  const {
+    resolveConfigImpl = resolveConfig,
+    readManifestImpl = readManifest,
+    findHoldersInPathImpl = findHoldersInPath,
+    forceDrainImpl = forceDrainPendingCleanup,
+    gitImpl = gitUtils,
+    projectRoot = PROJECT_ROOT,
+    progressImpl = progress,
+    logger = Logger,
+  } = deps;
   const { values } = parseArgs({
+    args: argv,
     options: {
       escalate: { type: 'boolean', default: true },
       'dry-run': { type: 'boolean', default: false },
@@ -49,20 +85,23 @@ async function main() {
     strict: false,
   });
 
-  const config = resolveConfig();
+  const config = resolveConfigImpl();
   const wtConfig = config.delivery?.worktreeIsolation;
   const worktreeRoot = path.resolve(
-    PROJECT_ROOT,
+    projectRoot,
     values['worktree-root'] ?? wtConfig?.root ?? '.worktrees',
   );
 
-  const before = readManifest(worktreeRoot);
+  const before = readManifestImpl(worktreeRoot);
   if (before.length === 0) {
-    progress('SCAN', 'pending-cleanup manifest is empty — nothing to drain.');
-    return;
+    progressImpl(
+      'SCAN',
+      'pending-cleanup manifest is empty — nothing to drain.',
+    );
+    return { remaining: 0 };
   }
 
-  progress(
+  progressImpl(
     'SCAN',
     `pending-cleanup manifest has ${before.length} entry(ies): ${before
       .map((e) => `story-${e.storyId}(attempts=${e.attempts ?? 0})`)
@@ -71,8 +110,8 @@ async function main() {
 
   if (values['dry-run']) {
     for (const entry of before) {
-      const holders = findHoldersInPath(entry.path);
-      progress(
+      const holders = findHoldersInPathImpl(entry.path);
+      progressImpl(
         'DRY-RUN',
         `story-${entry.storyId} path=${entry.path} holders=${holders.length}` +
           (holders.length > 0
@@ -80,23 +119,23 @@ async function main() {
             : ''),
       );
     }
-    return;
+    return { remaining: before.length };
   }
 
-  const result = await forceDrainPendingCleanup({
-    repoRoot: PROJECT_ROOT,
+  const result = await forceDrainImpl({
+    repoRoot: projectRoot,
     worktreeRoot,
-    git: gitUtils,
+    git: gitImpl,
     escalate: values.escalate,
     logger: {
-      info: (m) => progress('DRAIN', m),
-      warn: (m) => progress('DRAIN', `⚠️ ${m}`),
-      error: (m) => Logger.error(`[drain-pending-cleanup] ${m}`),
+      info: (m) => progressImpl('DRAIN', m),
+      warn: (m) => progressImpl('DRAIN', `⚠️ ${m}`),
+      error: (m) => logger.error(`[drain-pending-cleanup] ${m}`),
     },
   });
 
   if (result.drained.length > 0) {
-    progress(
+    progressImpl(
       'DRAIN',
       `✅ drained ${result.drained.length} entry(ies): ${result.drained
         .map((id) => `story-${id}`)
@@ -107,10 +146,10 @@ async function main() {
     const summary = result.escalated
       .map((id) => `story-${id}=[${(result.killedPids[id] ?? []).join(',')}]`)
       .join(', ');
-    progress('ESCALATE', `terminated holders: ${summary}`);
+    progressImpl('ESCALATE', `terminated holders: ${summary}`);
   }
   if (result.noHolders && result.noHolders.length > 0) {
-    progress(
+    progressImpl(
       'ESCALATE',
       `⚠️ no user-mode holders for: ${result.noHolders
         .map((id) => `story-${id}`)
@@ -120,7 +159,7 @@ async function main() {
     );
   }
   if (result.persistent.length > 0) {
-    progress(
+    progressImpl(
       'PERSIST',
       `⚠️ persistent-lock remains on: ${result.persistent
         .map((id) => `story-${id}`)
@@ -128,7 +167,7 @@ async function main() {
     );
   }
   if (result.stillPending.length > 0) {
-    progress(
+    progressImpl(
       'STILL-PENDING',
       `⚠️ still-pending (below threshold): ${result.stillPending
         .map((id) => `story-${id}`)
@@ -136,12 +175,17 @@ async function main() {
     );
   }
 
-  const after = readManifest(worktreeRoot);
-  progress(
+  const after = readManifestImpl(worktreeRoot);
+  progressImpl(
     'DONE',
     `pending-cleanup manifest now has ${after.length} entry(ies). ` +
       `Drained=${result.drained.length}, escalated=${result.escalated.length}, persistent=${result.persistent.length}.`,
   );
+  return { drained: result.drained, remaining: after.length };
+}
+
+async function main() {
+  await runDrainPendingCleanup();
 }
 
 runAsCli(import.meta.url, main, {

package/.agents/scripts/generate-lens-checklists.js

@@ -83,16 +83,21 @@ export function planChecklists(lenses, workflowExists, readWorkflow) {
  *   content; `missing` lists lenses with no `audit-<lens>.md`; `strays` lists
  *   on-disk checklist basenames that map to no current lens.
  */
-export function buildExpected() {
-  const workflowPath = (lens) => path.join(WORKFLOWS_DIR, `audit-${lens}.md`);
+export function buildExpected({
+  fsImpl = fs,
+  lenses = AUDIT_LENSES,
+  workflowsDir = WORKFLOWS_DIR,
+  checklistsDir = CHECKLISTS_DIR,
+} = {}) {
+  const workflowPath = (lens) => path.join(workflowsDir, `audit-${lens}.md`);
   const { expected, missing } = planChecklists(
-    AUDIT_LENSES,
-    (lens) => fs.existsSync(workflowPath(lens)),
-    (lens) => fs.readFileSync(workflowPath(lens), 'utf8'),
+    lenses,
+    (lens) => fsImpl.existsSync(workflowPath(lens)),
+    (lens) => fsImpl.readFileSync(workflowPath(lens), 'utf8'),
   );
 
-  const onDisk = fs.existsSync(CHECKLISTS_DIR)
-    ? fs.readdirSync(CHECKLISTS_DIR).filter((name) => name.endsWith('.md'))
+  const onDisk = fsImpl.existsSync(checklistsDir)
+    ? fsImpl.readdirSync(checklistsDir).filter((name) => name.endsWith('.md'))
     : [];
   const strays = onDisk.filter((name) => !expected.has(name));
 
@@ -101,29 +106,69 @@ export function buildExpected() {
 
 /**
  * @param {string} basename — e.g. `security.md`
+ * @param {string} [checklistsDir]
+ * @param {string} [projectRoot]
  * @returns {string} repo-relative POSIX path for messages.
  */
-function relChecklist(basename) {
+function relChecklist(
+  basename,
+  checklistsDir = CHECKLISTS_DIR,
+  projectRoot = PROJECT_ROOT,
+) {
   return path
-    .relative(PROJECT_ROOT, path.join(CHECKLISTS_DIR, basename))
+    .relative(projectRoot, path.join(checklistsDir, basename))
     .split(path.sep)
     .join('/');
 }
 
 /**
- * @param {string[]} argv
+ * The generator core, extracted from the CLI shell so both modes — the
+ * `--check` drift gate and the write/prune pass — are reachable without
+ * touching the real `.agents/audit-checklists` tree.
+ *
+ * Every seam on the optional final `deps` parameter defaults to the real
+ * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main` and
+ * `npm run docs:check` are unchanged.
+ *
+ * @param {string[]} [argv]
+ * @param {{
+ *   fsImpl?: typeof fs,
+ *   lenses?: ReadonlyArray<string>,
+ *   workflowsDir?: string,
+ *   checklistsDir?: string,
+ *   projectRoot?: string,
+ *   logger?: { info: Function },
+ * }} [deps]
+ * @returns {Promise<{ wrote: number, pruned: number, checked?: boolean }>}
  */
-async function main(argv = process.argv.slice(2)) {
+export async function runGenerateLensChecklists(
+  argv = process.argv.slice(2),
+  deps = {},
+) {
+  const {
+    fsImpl = fs,
+    lenses = AUDIT_LENSES,
+    workflowsDir = WORKFLOWS_DIR,
+    checklistsDir = CHECKLISTS_DIR,
+    projectRoot = PROJECT_ROOT,
+    logger = Logger,
+  } = deps;
   const { values } = parseArgs({
     args: argv,
     options: { check: { type: 'boolean', default: false } },
     allowPositionals: false,
   });
 
-  const { expected, missing, strays } = buildExpected();
+  const { expected, missing, strays } = buildExpected({
+    fsImpl,
+    lenses,
+    workflowsDir,
+    checklistsDir,
+  });
+  const rel = (basename) => relChecklist(basename, checklistsDir, projectRoot);
 
   if (missing.length > 0) {
-    Logger.info(
+    logger.info(
       `generate-lens-checklists: no audit-<lens>.md for: ${missing.join(', ')} — no checklist emitted.`,
     );
   }
@@ -131,21 +176,21 @@ async function main(argv = process.argv.slice(2)) {
   if (values.check) {
     const drifted = [];
     for (const [basename, content] of expected) {
-      const target = path.join(CHECKLISTS_DIR, basename);
-      const original = fs.existsSync(target)
-        ? fs.readFileSync(target, 'utf8')
+      const target = path.join(checklistsDir, basename);
+      const original = fsImpl.existsSync(target)
+        ? fsImpl.readFileSync(target, 'utf8')
         : null;
-      if (original !== content) drifted.push(relChecklist(basename));
+      if (original !== content) drifted.push(rel(basename));
     }
     if (drifted.length === 0 && strays.length === 0) {
-      Logger.info(
+      logger.info(
         `generate-lens-checklists: ${expected.size} checklist(s) up to date.`,
       );
-      return;
+      return { wrote: 0, pruned: 0, checked: true };
     }
     const problems = [
       ...drifted.map((p) => `out of date: ${p}`),
-      ...strays.map((s) => `stray (no lens): ${relChecklist(s)}`),
+      ...strays.map((s) => `stray (no lens): ${rel(s)}`),
     ];
     throw new Error(
       `Lens checklists are out of sync:\n  ${problems.join('\n  ')}\n` +
@@ -153,26 +198,32 @@ async function main(argv = process.argv.slice(2)) {
     );
   }
 
-  fs.mkdirSync(CHECKLISTS_DIR, { recursive: true });
+  fsImpl.mkdirSync(checklistsDir, { recursive: true });
   let wrote = 0;
   for (const [basename, content] of expected) {
-    const target = path.join(CHECKLISTS_DIR, basename);
-    const original = fs.existsSync(target)
-      ? fs.readFileSync(target, 'utf8')
+    const target = path.join(checklistsDir, basename);
+    const original = fsImpl.existsSync(target)
+      ? fsImpl.readFileSync(target, 'utf8')
       : null;
     if (original === content) continue;
-    fs.writeFileSync(target, content, 'utf8');
+    fsImpl.writeFileSync(target, content, 'utf8');
     wrote += 1;
   }
   for (const stray of strays) {
-    fs.rmSync(path.join(CHECKLISTS_DIR, stray));
-    Logger.info(
-      `generate-lens-checklists: pruned stray ${relChecklist(stray)}`,
-    );
+    fsImpl.rmSync(path.join(checklistsDir, stray));
+    logger.info(`generate-lens-checklists: pruned stray ${rel(stray)}`);
   }
-  Logger.info(
+  logger.info(
     `generate-lens-checklists: wrote ${wrote} of ${expected.size} checklist(s) (${strays.length} pruned).`,
   );
+  return { wrote, pruned: strays.length };
+}
+
+/**
+ * @param {string[]} [argv]
+ */
+async function main(argv = process.argv.slice(2)) {
+  await runGenerateLensChecklists(argv);
 }
 
 export { CHECKLISTS_DIR, WORKFLOWS_DIR };

package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js

@@ -31,6 +31,9 @@ const HEADING_FINDING = /^###\s+(.+?)\s*$/;
 const HEADING_SECTION = /^##\s+(.+?)\s*$/;
 const PATH_HINT =
   /(?<![\w/])([A-Za-z0-9_./\\@-]+\.(?:js|ts|tsx|jsx|mjs|cjs|md|json|yaml|yml|css|scss|html|py|go|rs|java|kt|rb|sh|ps1|tf|env))(?![\w])/g;
+const FILE_EXT =
+  /\.(?:js|ts|tsx|jsx|mjs|cjs|md|json|yaml|yml|css|scss|html|py|go|rs|java|kt|rb|sh|ps1|tf|env)$/;
+const TITLE_ANCHOR = /^\s*`([^`]+)`/;
 
 function unwrapInlineCode(value) {
   if (typeof value !== 'string') return '';
@@ -81,17 +84,81 @@ function deriveDimension(fields, fallbackDimension) {
  * @param {Record<string, string>} fields
  * @returns {string[]}
  */
-function deriveLocationFiles(fields) {
+/**
+ * Normalise a raw path token to a repo-relative path, or `null` when the
+ * token is not a usable file reference.
+ *
+ * Three shapes historically leaked through and poisoned grouping downstream:
+ * an **absolute** path (which can never match a repo-relative group key), a
+ * **degenerate** token such as a bare `/`, and — most damagingly — a
+ * **root-level** file such as `AGENTS.md`, which the old slash-only guard
+ * discarded outright even when it was the finding's explicit `Location:`.
+ *
+ * `requireSeparator` is what keeps that third fix from over-reaching. In the
+ * **structured** fields — the title anchor and `Location:` — a bare
+ * `AGENTS.md` is unambiguously a file, so the separator is not required. In
+ * free **prose**, a bare `description.md` is far more likely to be a word than
+ * a path, so the separator stays mandatory there.
+ *
+ * @param {string} raw — the token as it appeared in the report.
+ * @param {string} [repoRoot] — absolute repo root; absolute tokens beneath it
+ *   are relativised. Omitted (the pure default) leaves absolutes to be dropped.
+ * @param {{ requireSeparator?: boolean }} [options]
+ * @returns {string|null}
+ */
+function normalisePathToken(raw, repoRoot, { requireSeparator = false } = {}) {
+  if (typeof raw !== 'string') return null;
+  const stripped = raw
+    .replace(/^[`'"([]+/, '')
+    .replace(/[`'")\].,;]+$/, '')
+    .trim();
+  // `Location:` anchors appear as `:line`, `:line:col`, and `:start-end`.
+  const cleaned = stripped.replace(/:\d+(?:-\d+)?(?::\d+)?$/, '');
+  if (!cleaned || cleaned === '.' || cleaned === '..') return null;
+
+  let out = cleaned;
+  if (typeof repoRoot === 'string' && repoRoot.length > 0) {
+    for (const sep of ['/', '\\']) {
+      const root = repoRoot.endsWith(sep) ? repoRoot : `${repoRoot}${sep}`;
+      if (out.startsWith(root)) {
+        out = out.slice(root.length);
+        break;
+      }
+    }
+  }
+  // A path that is still absolute lives outside the repo — it can never be a
+  // valid group key, so drop it rather than let it become one.
+  if (out.startsWith('/') || out.startsWith('\\') || /^[A-Za-z]:/.test(out)) {
+    return null;
+  }
+  const hasSeparator = out.includes('/') || out.includes('\\');
+  if (requireSeparator && !hasSeparator) return null;
+  if (!hasSeparator && !FILE_EXT.test(out)) return null;
+  return out;
+}
+
+/**
+ * The finding-block skeleton mandates that a title lead with the primary file
+ * the finding lives in (``### `path/to/file.ext` — title``). That anchor is
+ * the most reliable primary-file signal a block carries, so it seeds `files[]`
+ * ahead of `Location:` and prose scraping — `pickPrimaryFile` takes `files[0]`.
+ */
+function deriveTitleFile(title, repoRoot) {
+  const match = TITLE_ANCHOR.exec(typeof title === 'string' ? title : '');
+  if (!match) return [];
+  const normalised = normalisePathToken(match[1], repoRoot);
+  return normalised ? [normalised] : [];
+}
+
+function deriveLocationFiles(fields, repoRoot) {
   const raw = fields.location;
   if (typeof raw !== 'string' || raw.trim().length === 0) return [];
   const cleaned = raw.replace(/[`[\]]/g, ' ');
   const out = [];
   for (const token of cleaned.split(/[\s,]+/)) {
     if (!token) continue;
-    const withoutLine = token.replace(/:\d+(?::\d+)?$/, '');
-    if (withoutLine.includes('/') || withoutLine.includes('\\')) {
-      out.push(withoutLine);
-    }
+    const normalised = normalisePathToken(token, repoRoot);
+    if (normalised) out.push(normalised);
   }
   return out;
 }
@@ -113,14 +180,15 @@ function normaliseTitle(title) {
     .trim();
 }
 
-function extractFilePaths(text) {
+function extractFilePaths(text, repoRoot) {
   if (typeof text !== 'string') return [];
   const seen = new Set();
   for (const match of text.matchAll(PATH_HINT)) {
-    const candidate = match[1].replace(/^[`'"]+|[`'"]+$/g, '');
-    if (candidate.includes('/') || candidate.includes('\\')) {
-      seen.add(candidate);
-    }
+    // Prose: a bare `description.md` is more likely a word than a path.
+    const normalised = normalisePathToken(match[1], repoRoot, {
+      requireSeparator: true,
+    });
+    if (normalised) seen.add(normalised);
   }
   return [...seen];
 }
@@ -211,7 +279,7 @@ function parseBlockFields(bodyLines) {
  *   sourceReport: string,
  * }>}
  */
-export function parseAuditReport({ markdown, sourceReport }) {
+export function parseAuditReport({ markdown, sourceReport, repoRoot }) {
   if (typeof markdown !== 'string') {
     throw new Error('parseAuditReport: markdown must be a string');
   }
@@ -231,10 +299,11 @@ export function parseAuditReport({ markdown, sourceReport }) {
       fields['recommendation & rationale'] ?? fields.recommendation ?? '';
     const agentPrompt = fields['agent prompt'] ?? '';
     const fileSet = new Set([
-      ...deriveLocationFiles(fields),
-      ...extractFilePaths(currentState),
-      ...extractFilePaths(recommendation),
-      ...extractFilePaths(agentPrompt),
+      ...deriveTitleFile(block.title, repoRoot),
+      ...deriveLocationFiles(fields, repoRoot),
+      ...extractFilePaths(currentState, repoRoot),
+      ...extractFilePaths(recommendation, repoRoot),
+      ...extractFilePaths(agentPrompt, repoRoot),
     ]);
 
     return {
@@ -258,15 +327,17 @@ export function parseAuditReport({ markdown, sourceReport }) {
  * an audit can legitimately come back empty.
  *
  * @param {Array<{ markdown: string, sourceReport: string }>} reports
+ * @param {{ repoRoot?: string }} [options] — `repoRoot` relativises absolute
+ *   paths quoted in a report so they can match repo-relative group keys.
  * @returns {Array<ReturnType<typeof parseAuditReport>[number]>}
  */
-export function parseAuditReports(reports) {
+export function parseAuditReports(reports, { repoRoot } = {}) {
   if (!Array.isArray(reports)) {
     throw new Error('parseAuditReports: reports must be an array');
   }
   const out = [];
   for (const report of reports) {
-    out.push(...parseAuditReport(report));
+    out.push(...parseAuditReport({ ...report, repoRoot }));
   }
   return out;
 }