session-orchestrator 3.22.0 → 3.24.0

package/scripts/lib/validate/check-validator-registration.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * check-validator-registration.mjs — every `scripts/lib/validate/check-*.mjs`
+ * must be referenced by basename from at least one of the three surfaces
+ * that actually RUN a validator (`scripts/validate-plugin.mjs`,
+ * `.husky/pre-commit`, `.gitlab-ci.yml`), or declare itself deliberately
+ * standalone. #1184.
+ *
+ * THE CLASS. A checker with real detection logic and zero callers is built
+ * work nobody ever runs — this repo's own `check-unwired-features.mjs`
+ * census exists for a sibling shape of the same problem (config keys nobody
+ * reads); this checker is that same discipline applied to the checkers
+ * directory itself. `scripts/validate-plugin.mjs` is the canonical local
+ * runner (`runCheck('check-foo.mjs')`); `.husky/pre-commit` and
+ * `.gitlab-ci.yml` are the two OTHER surfaces some checkers wire into
+ * directly instead of (or in addition to) the orchestrator —
+ * `check-owner-leakage.mjs`, `check-test-fixture-shapes.mjs` and
+ * `check-test-value-bans.mjs` all do this (verified live at HEAD 2ccea0f2).
+ *
+ * OPT-OUT. A checker that is deliberately CLI-only (invoked by a human or a
+ * different tool, never by these three surfaces) declares itself with a
+ * header-comment marker: `// registration: standalone <reason>`. The marker
+ * makes the checker report PASS as "standalone", not merely silence a
+ * warning — the same shape of inline self-declared exemption
+ * `check-untracked-test-deps.mjs`'s `IGNORE_MARKER` and
+ * `check-dead-bridge.mjs`'s `:ignore` marker already use in this directory.
+ *
+ * ORACLE. A plain substring match of the checker's own basename (e.g.
+ * `"check-foo.mjs"`) against the COMMENT-STRIPPED text of the three surface
+ * files — the same granularity `runCheck('check-foo.mjs')` calls and
+ * `.husky`/CI script lines already use to name a checker. MEASURED (HEAD
+ * 2ccea0f2, all 33 live `check-*.mjs` basenames): zero basenames are a
+ * substring of another, so this match cannot cross-attribute one checker's
+ * registration to a different one.
+ *
+ * COMMENT-STRIPPING (HIGH, qa review, #1184 FX-C). A basename referenced
+ * ONLY inside a `//`/`#` line comment or a `/* *\/` block comment is NOT a
+ * real registration — the surface text is stripped of comments (quote-aware,
+ * so a `#`/`//` INSIDE a string — a URL fragment, a shell parameter
+ * expansion `${VAR#pattern}` — is never mistaken for a comment start) before
+ * matching. MEASURED before this fix: a fixture whose only reference to
+ * `check-ghost.mjs` sat in `// runCheck('check-ghost.mjs'); // DISABLED`
+ * reported `registered: true` (exit 0) — commenting a checker OUT silently
+ * kept it PASSing. `scripts/validate-plugin.mjs` uses `//`+`/* *\/` (js);
+ * `.husky/pre-commit` and `.gitlab-ci.yml` use `#` (sh/yaml) — see
+ * {@link commentStyleForSurface}. The checker's OWN
+ * `// registration: standalone` header marker is read from the CHECKER file
+ * directly (never from a surface text) and is unaffected by this stripping.
+ *
+ * NAMED CEILING (BV-004): a checker referenced only in prose (a `.md` doc, a
+ * skill body) and nowhere in the three RUN surfaces above still reports
+ * UNREGISTERED — being documented is not being run. REVISIT if a fourth run
+ * surface (a new CI job file, a different git hook) is ever added: extend
+ * `RUN_SURFACES`, do not special-case it here. The comment stripper's own
+ * quote-tracking is a single flat state — an escaped quote (`\"`) inside a
+ * double-quoted string is not honoured, and a template-literal's `${...}`
+ * interpolation is not walked separately. Both failure directions lean
+ * toward treating MORE text as "inside a string" than a real parser would,
+ * which can only make the stripper MISS a comment (false "still
+ * registered"), never manufacture a false UNREGISTERED — the direction this
+ * checker's own false-positive history (the paragraph above) already
+ * measured as the live hazard.
+ *
+ * Usage: check-validator-registration.mjs <repo-root>
+ * Output: `  PASS: …` / `  FAIL: …` lines (two leading spaces), then
+ * `Results: N passed, M failed`. Exit 0 = every checker registered or
+ * standalone, 1 = at least one unregistered checker, 2 = tool error.
+ *
+ * Import-safety: importing this module MUST NOT execute anything — the
+ * isMain guard at the bottom is the only side-effecting path.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { listRepoFiles } from './repo-files.mjs';
+
+/** Marker line inside a checker's own header — declares deliberate CLI-only status. */
+export const STANDALONE_MARKER = /^\s*\/\/\s*registration:\s*standalone\b(?:\s+(.*))?$/m;
+
+/** The three surfaces that actually RUN a validator (not merely mention it). */
+const RUN_SURFACES = Object.freeze([
+  path.join('scripts', 'validate-plugin.mjs'),
+  path.join('.husky', 'pre-commit'),
+  path.join('.gitlab-ci.yml'),
+]);
+
+const VALIDATE_DIR_REL = path.join('scripts', 'lib', 'validate');
+
+/**
+ * Comment style for a RUN_SURFACES path, keyed on extension rather than
+ * position — avoids a silent index-drift if `RUN_SURFACES` is ever
+ * reordered. `.mjs` gets JS-shaped comments (`//`, `/* *\/`, quotes
+ * `'`/`"`/`` ` ``); everything else (`.husky/pre-commit` has no extension,
+ * `.gitlab-ci.yml`) gets shell/YAML-shaped comments (`#` only, quotes
+ * `'`/`"`).
+ *
+ * @param {string} rel repo-relative surface path
+ * @returns {{lineComment: string, blockComment: boolean, quoteChars: string[]}}
+ */
+function commentStyleForSurface(rel) {
+  return rel.endsWith('.mjs')
+    ? { lineComment: '//', blockComment: true, quoteChars: ['"', "'", '`'] }
+    : { lineComment: '#', blockComment: false, quoteChars: ['"', "'"] };
+}
+
+/**
+ * Strip comments from `text` so a checker basename mentioned only inside a
+ * comment is never read as a real registration. Quote-aware: walks `'`/`"`
+ * (and, for the js style, `` ` ``) spans without inspecting their contents,
+ * so a comment marker INSIDE a string (a URL fragment `#frag`, a shell
+ * parameter expansion `${VAR#pattern}`) is left untouched rather than
+ * truncating the line early. See the header NAMED CEILING for what this
+ * quote-tracking deliberately does not attempt.
+ *
+ * @param {string} text
+ * @param {{lineComment: string, blockComment: boolean, quoteChars: string[]}} style
+ * @returns {string}
+ */
+export function stripComments(text, { lineComment, blockComment, quoteChars }) {
+  let out = '';
+  let i = 0;
+  let inQuote = null;
+  while (i < text.length) {
+    const ch = text[i];
+    if (inQuote) {
+      out += ch;
+      if (ch === '\\' && i + 1 < text.length) {
+        out += text[i + 1];
+        i += 2;
+        continue;
+      }
+      if (ch === inQuote) inQuote = null;
+      i += 1;
+      continue;
+    }
+    if (quoteChars.includes(ch)) {
+      inQuote = ch;
+      out += ch;
+      i += 1;
+      continue;
+    }
+    if (blockComment && ch === '/' && text[i + 1] === '*') {
+      const end = text.indexOf('*/', i + 2);
+      i = end === -1 ? text.length : end + 2;
+      continue;
+    }
+    if (text.startsWith(lineComment, i)) {
+      const nl = text.indexOf('\n', i);
+      i = nl === -1 ? text.length : nl; // keep the newline itself, drop the comment text
+      continue;
+    }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+/**
+ * @typedef {{basename: string, registered: boolean, standalone: boolean, surfaces: string[]}} RegistrationResult
+ */
+
+/**
+ * @param {string} repoRoot
+ * @returns {RegistrationResult[]} sorted by basename
+ */
+export function scanValidatorRegistration(repoRoot) {
+  const checkerFiles = listRepoFiles(repoRoot, { dirs: [VALIDATE_DIR_REL], exts: ['mjs'] }).filter(
+    (f) => /^check-.*\.mjs$/.test(path.basename(f)),
+  );
+
+  // Comment-stripped before matching (HIGH, #1184 FX-C): a basename
+  // referenced only inside a `//`/`#`/`/* *\/` comment is NOT a real
+  // registration — see the header's COMMENT-STRIPPING paragraph.
+  const surfaceTexts = RUN_SURFACES.map((rel) => {
+    const abs = path.join(repoRoot, rel);
+    try {
+      const raw = existsSync(abs) ? readFileSync(abs, 'utf8') : '';
+      return stripComments(raw, commentStyleForSurface(rel));
+    } catch {
+      return '';
+    }
+  });
+
+  /** @type {RegistrationResult[]} */
+  const results = [];
+  for (const abs of checkerFiles) {
+    const basename = path.basename(abs);
+    let source = '';
+    try {
+      source = readFileSync(abs, 'utf8');
+    } catch {
+      /* unreadable — no marker can be found, no surface reference can save it either */
+    }
+    const standalone = STANDALONE_MARKER.test(source);
+    const surfaces = RUN_SURFACES.filter((_, i) => surfaceTexts[i].includes(basename));
+    results.push({ basename, registered: surfaces.length > 0, standalone, surfaces });
+  }
+  return results.sort((a, b) => a.basename.localeCompare(b.basename));
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the check against a repo root, printing the validate-plugin line
+ * vocabulary.
+ *
+ * @param {string} repoRoot
+ * @returns {number} 0 = every checker registered or standalone, 1 = finding(s), 2 = tool error
+ */
+export function runCheckValidatorRegistration(repoRoot) {
+  console.log('--- Check: validator registration (check-*.mjs must be wired or standalone) ---');
+
+  const results = scanValidatorRegistration(repoRoot);
+  let pass = 0;
+  let fail = 0;
+
+  for (const r of results) {
+    if (r.standalone) {
+      console.log(`  PASS: ${r.basename} — declared standalone (registration: standalone)`);
+      pass += 1;
+    } else if (r.registered) {
+      console.log(`  PASS: ${r.basename} — referenced in ${r.surfaces.join(', ')}`);
+      pass += 1;
+    } else {
+      console.log(
+        `  FAIL: ${r.basename} — referenced by NEITHER scripts/validate-plugin.mjs, .husky/pre-commit, NOR .gitlab-ci.yml, and carries no "registration: standalone" marker`,
+      );
+      fail += 1;
+    }
+  }
+
+  console.log('');
+  console.log(`Results: ${pass} passed, ${fail} failed`);
+  return fail > 0 ? 1 : 0;
+}
+
+const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+if (isMain) {
+  const root = process.argv[2];
+  if (!root) {
+    console.error('Usage: check-validator-registration.mjs <repo-root>');
+    process.exit(2);
+  }
+  process.exit(runCheckValidatorRegistration(path.resolve(root)));
+}

package/scripts/lib/validate/check-vcs-repo-flag.mjs

@@ -194,6 +194,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { SHELL_LANGS, forEachLine } from './markdown-fences.mjs';
 
 /** Directories whose content is scanned. Root-level `*.md` is added separately. */
 const SCAN_DIRS = Object.freeze([
@@ -224,9 +225,6 @@ const DOC_EXTENSIONS = Object.freeze(['.md']);
 /** Code extensions (comment + string-literal rules apply). */
 const CODE_EXTENSIONS = Object.freeze(['.mjs', '.js', '.cjs']);
 
-/** Fence languages whose body is shell. Anything else is prose. */
-const SHELL_LANGS = Object.freeze(new Set(['bash', 'sh', 'shell', 'console', 'zsh']));
-
 /**
  * Real top-level subcommands, harvested from `gh --help` / `glab --help`
  * (gh 2.86.0 / glab 1.91.0, 2026-08-14). Filter 4: a token that is not in this
@@ -576,33 +574,13 @@ export function scanMarkdown(relative, body, tally) {
   const findings = [];
   /** @type {{line: number, text: string}[]} */
   const shellLines = [];
-  /** @type {{marker: string, length: number, shell: boolean} | null} */
-  let fence = null;
 
-  const lines = body.split('\n');
-  for (let index = 0; index < lines.length; index += 1) {
-    const raw = lines[index];
-    const fenceMatch = raw.match(/^\s*(`{3,}|~{3,})\s*([A-Za-z0-9_+-]*)/);
-    if (fenceMatch) {
-      const marker = fenceMatch[1][0];
-      const length = fenceMatch[1].length;
-      const lang = fenceMatch[2].toLowerCase();
-      if (fence === null) {
-        fence = { marker, length, shell: SHELL_LANGS.has(lang) };
-        continue;
-      }
-      // A closing fence uses the same char, is at least as long, and has no info string.
-      if (marker === fence.marker && length >= fence.length && lang === '') {
-        fence = null;
-        continue;
-      }
-      // Otherwise it is fence content (a nested fence inside a wider one).
-    }
-    if (fence === null || !fence.shell) continue;
+  forEachLine(body, (raw, { lineNumber, inFence, lang }) => {
+    if (!inFence || !SHELL_LANGS.has(lang)) return;
     const stripped = raw.replace(/^\s*[$❯>]\s+/, '');
-    if (/^\s*#/.test(stripped)) continue;
-    shellLines.push({ line: index + 1, text: stripped });
-  }
+    if (/^\s*#/.test(stripped)) return;
+    shellLines.push({ line: lineNumber, text: stripped });
+  });
 
   for (const entry of joinContinuations(shellLines)) {
     for (const hit of extractBareInvocations(entry.text, tally)) {

package/scripts/lib/validate/markdown-fences.mjs

@@ -0,0 +1,196 @@
+/**
+ * markdown-fences.mjs — the ONE fenced-code-block tracker shared by every
+ * Markdown-scanning validator/extractor in this repo (#1181).
+ *
+ * ## Why one module
+ *
+ * The same regex pair + open/close comparison had drifted into four separate
+ * copies — `check-doc-cli-commands.mjs`, `check-skill-script-paths.mjs`,
+ * `check-vcs-repo-flag.mjs` and `auq/parse.mjs` — each tracking fence depth
+ * and language independently. A drifted copy is a silent one: nothing fails
+ * when copy #3 diverges from copy #1, because each copy only has to agree
+ * with itself.
+ *
+ * ## The rule this module encodes
+ *
+ * A fence opens on a line beginning with 3+ backticks or 3+ tildes, carrying
+ * an optional info string (most commonly a language tag). It closes on a
+ * line whose marker CHARACTER matches, whose LENGTH is at least the
+ * opener's, and whose info string is empty — CommonMark reserves the info
+ * string for the OPENING fence only, so a fence-shaped line that still
+ * carries one is fence CONTENT (most often a nested fence one level in), not
+ * a closer.
+ *
+ * ## The one real divergence between the four original copies, preserved as a parameter
+ *
+ * Three of the four copies anchor the fence-line regex only at the START of
+ * the line — trailing text after the info string is simply not captured,
+ * never rejected. `auq/parse.mjs`'s copy anchors at BOTH ends: a line
+ * carrying anything past the info string besides trailing whitespace is not
+ * recognised as a fence line at all. This is `{ wholeLine: true }` below —
+ * a real behavioural difference, not stylistic, so it stays a caller-chosen
+ * option rather than being silently resolved one way. Every other
+ * consumer-specific behaviour (the shell-language predicate, blockquote
+ * stripping, unbalanced-fence reporting) likewise stays at the call site —
+ * this module owns only the fence-line grammar itself.
+ */
+
+/** Fence languages whose body is shell. Both `check-doc-cli-commands.mjs` and
+ * `check-vcs-repo-flag.mjs` filtered on this identical literal set before
+ * extraction; centralised here rather than kept as two copies of the same
+ * five strings. */
+export const SHELL_LANGS = Object.freeze(new Set(['bash', 'sh', 'shell', 'console', 'zsh']));
+
+/** Start-anchored: matches CommonMark, tolerates trailing info-string text. */
+const FENCE_LINE_START_RE = /^\s*(`{3,}|~{3,})\s*([A-Za-z0-9_+-]*)/;
+
+/** Whole-line-anchored: nothing but whitespace may follow the info string. */
+const FENCE_LINE_WHOLE_RE = /^[ \t]*(`{3,}|~{3,})[ \t]*([^\s`~]*)[ \t]*$/u;
+
+/**
+ * Match a candidate fence-marker line.
+ *
+ * @param {string} line
+ * @param {{ wholeLine?: boolean }} [options] `wholeLine: true` requires the
+ *   ENTIRE line (after the marker) to be nothing but the info string plus
+ *   trailing whitespace — the stricter reading `auq/parse.mjs` needs.
+ *   Default `false` only anchors the START of the line, matching
+ *   CommonMark and the three `check-*.mjs` validators.
+ * @returns {{ marker: string, length: number, info: string } | null}
+ */
+export function matchFenceLine(line, { wholeLine = false } = {}) {
+  const match = (wholeLine ? FENCE_LINE_WHOLE_RE : FENCE_LINE_START_RE).exec(line);
+  if (!match) return null;
+  return { marker: match[1][0], length: match[1].length, info: match[2] ?? '' };
+}
+
+/**
+ * Does `candidate` close the fence opened by `open`? Same marker character,
+ * at least as long, and carrying no info string of its own.
+ *
+ * @param {{ marker: string, length: number }} open
+ * @param {{ marker: string, length: number, info: string }} candidate
+ * @returns {boolean}
+ */
+export function closesFence(open, candidate) {
+  return candidate.marker === open.marker && candidate.length >= open.length && candidate.info === '';
+}
+
+/**
+ * Normalise a fence's info string into a comparable language tag. Every
+ * caller that classified a fence by language did `.toLowerCase()` (never
+ * `.trim()`, since the capturing regex cannot include leading/trailing
+ * whitespace in the first place) before comparing against a language set —
+ * this makes that normalisation a single, explicit step instead of an
+ * implicit property of the extraction regex.
+ *
+ * @param {string} info
+ * @returns {string}
+ */
+export function normalizeLang(info) {
+  return String(info ?? '').trim().toLowerCase();
+}
+
+/**
+ * Strip a leading blockquote `>` chain so a quoted fence (`> \`\`\``) is
+ * still recognised as a fence line. Only `check-skill-script-paths.mjs`
+ * needs this — a fence inside a blockquote is still a fence there, but the
+ * other callers never scan quoted content.
+ *
+ * @param {string} line
+ * @returns {string}
+ */
+export function stripBlockquote(line) {
+  return line.replace(/^(?:\s*>)+\s?/, '');
+}
+
+/**
+ * Walk `text` line by line, tracking fence state, and call `onLine` for
+ * every CONTENT line. Fence-marker lines themselves (the opener and the
+ * closer) are consumed by the tracker and never handed to the callback —
+ * all four original copies treated marker lines as structural, never as
+ * scannable content. A fence-shaped line that neither opens nor validly
+ * closes (a nested fence one level in) IS still content and reaches the
+ * callback, exactly as in the original copies.
+ *
+ * @param {string} text
+ * @param {(line: string, state: { lineNumber: number, inFence: boolean, lang: string | null }) => void} onLine
+ * @param {{ wholeLine?: boolean, stripBlockquotes?: boolean }} [options]
+ * @returns {{ unbalancedFenceLine: number | null }} the 1-based line of a
+ *   fence that opened and never closed by EOF, or `null` if every fence
+ *   this walk saw was balanced.
+ */
+export function forEachLine(text, onLine, options = {}) {
+  const { wholeLine = false, stripBlockquotes = false } = options;
+  const lines = text.split('\n');
+  /** @type {{ marker: string, length: number, openLine: number } | null} */
+  let fence = null;
+  let lang = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index];
+    const probe = stripBlockquotes ? stripBlockquote(raw) : raw;
+    const candidate = matchFenceLine(probe, { wholeLine });
+    if (candidate) {
+      if (fence === null) {
+        fence = { marker: candidate.marker, length: candidate.length, openLine: index + 1 };
+        lang = normalizeLang(candidate.info);
+        continue;
+      }
+      if (closesFence(fence, candidate)) {
+        fence = null;
+        lang = null;
+        continue;
+      }
+      // Otherwise it is fence content (a nested fence inside a wider one) — falls through.
+    }
+    onLine(raw, { lineNumber: index + 1, inFence: fence !== null, lang });
+  }
+
+  return { unbalancedFenceLine: fence ? fence.openLine : null };
+}
+
+/**
+ * Extract fence BLOCKS (an open/close pair plus its body) rather than a
+ * per-line walk — the shape `auq/parse.mjs` needs, since it iterates fences
+ * as units, not lines.
+ *
+ * An unbalanced fence (opens, never closes) contributes NO block, mirroring
+ * the original `fencesOf()` contract: it silently drops the dangling opener
+ * rather than reporting it. Unlike `check-skill-script-paths.mjs`, whose
+ * unterminated fence is a doc DEFECT worth its own finding, `auq/parse.mjs`
+ * scans AskUserQuestion blocks in production code and prose, where an
+ * unterminated fence was never treated as a reportable condition in its own
+ * right — only as "no block found here".
+ *
+ * @param {string} text
+ * @param {{ wholeLine?: boolean }} [options]
+ * @returns {Array<{ openLine: number, closeLine: number, lang: string, bodyLines: string[], bodyStartLine: number }>}
+ */
+export function scanFenceBlocks(text, options = {}) {
+  const { wholeLine = false } = options;
+  const lines = text.split('\n');
+  /** @type {Array<{ openLine: number, closeLine: number, lang: string, bodyLines: string[], bodyStartLine: number }>} */
+  const blocks = [];
+  /** @type {{ marker: string, length: number, info: string, startIdx: number } | null} */
+  let open = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const candidate = matchFenceLine(lines[index], { wholeLine });
+    if (!candidate) continue;
+    if (open === null) {
+      open = { ...candidate, startIdx: index };
+      continue;
+    }
+    if (!closesFence(open, candidate)) continue; // fence content (nested), not a close
+    blocks.push({
+      openLine: open.startIdx + 1,
+      closeLine: index + 1,
+      lang: open.info,
+      bodyLines: lines.slice(open.startIdx + 1, index),
+      bodyStartLine: open.startIdx + 2,
+    });
+    open = null;
+  }
+  return blocks;
+}