@opengsd/gsd-core 1.10.0 → 1.12.0

package/scripts/gen-inventory-manifest.cjs

@@ -117,6 +117,47 @@ function statOrNull(p) {
   }
 }
 
+/**
+ * Collect `<dir>/<subdir>/<file>` entries as `<subdir>/<file>` keys — ONE level of
+ * subdirectory beneath `dir` itself, where the subdirectory's NAME is the thing being
+ * collected (unlike `collectNested`, there is no fixed subdir name to look for; every
+ * child directory of `dir` is scanned). This is what makes `gsd-core/bin/lib/<subdir>/*.cjs`
+ * (e.g. `health-diagnostic-rules/`, `installer-migrations/`, `host-integration-adapters/`,
+ * `observability/`) visible to the `cli_modules` family, mirroring the shape
+ * `docs/INVENTORY.md`'s CLI Modules table already uses for these files.
+ *
+ * Same defensive `statOrNull`-based style as `collectNested`: a stat/readdir failure on
+ * one entry is swallowed rather than thrown, so one unreadable subdirectory cannot take
+ * down `--check` for the whole repo.
+ */
+function collectOneLevelSubdirs({ dir, filter }) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  let children;
+  try {
+    children = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  for (const child of children) {
+    const childStat = statOrNull(path.join(dir, child));
+    if (!childStat || !childStat.isDirectory()) continue;
+    const subdirPath = path.join(dir, child);
+    let files;
+    try {
+      files = fs.readdirSync(subdirPath);
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      const fileStat = statOrNull(path.join(subdirPath, file));
+      if (!fileStat || !fileStat.isFile() || !filter(file)) continue;
+      out.push([child, file].join('/'));
+    }
+  }
+  return out.sort();
+}
+
 function collectNested({ root, subdir, filter }) {
   if (!fs.existsSync(root)) return [];
   const out = [];
@@ -150,11 +191,16 @@ function collectNested({ root, subdir, filter }) {
 function buildManifest() {
   const manifest = { families: {} };
   for (const { name, dir, filter, toName } of FAMILIES) {
-    manifest.families[name] = fs
+    const flat = fs
       .readdirSync(dir)
       .filter((f) => fs.statSync(path.join(dir, f)).isFile() && filter(f))
-      .map(toName)
-      .sort();
+      .map(toName);
+    // `cli_modules` also ships subdirectory modules (`health-diagnostic-rules/`,
+    // `installer-migrations/`, `host-integration-adapters/`, `observability/`) invisible to
+    // the flat readdirSync above; merge them into the SAME sorted array, matching the single
+    // "CLI Modules" table shape docs/INVENTORY.md already uses (#3309).
+    const nested = name === 'cli_modules' ? collectOneLevelSubdirs({ dir, filter }) : [];
+    manifest.families[name] = [...flat, ...nested].sort();
   }
   for (const family of NESTED_FAMILIES) {
     manifest.families[family.name] = collectNested(family);
@@ -209,4 +255,4 @@ if (require.main === module) {
 // `DEFECT.GENERATIVE-FIX` divergence class: adding a family here while the test kept
 // its own list meant the test silently verified fewer families than shipped, and still
 // passed. The test now imports these, so the two surfaces cannot drift.
-module.exports = { FAMILIES, NESTED_FAMILIES, collectNested, buildManifest };
+module.exports = { FAMILIES, NESTED_FAMILIES, collectNested, collectOneLevelSubdirs, buildManifest };

package/scripts/gen-loop-host-contract.cjs

@@ -20,6 +20,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { escapeRegex: escapeRegExp } = require('../gsd-core/bin/lib/pattern.cjs');
+const { normalizeEol } = require('../gsd-core/bin/lib/text-lines.cjs');
 
 const ROOT = path.resolve(__dirname, '..');
 const WORKFLOWS_DIR = path.join(ROOT, 'gsd-core', 'workflows');
@@ -191,13 +193,6 @@ function parseLoopHostBlock(content, fileName) {
  * @param {string}   fileName    For error messages
  * @returns {string[]}           Array of error strings; empty = OK
  */
-/**
- * Escape a string for literal use in a RegExp.
- */
-function escapeRegExp(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 function crossCheckRoles(content, agentRoles, fileName) {
   const errors = [];
   for (const role of agentRoles) {
@@ -375,21 +370,6 @@ function serializeContract(contract) {
   return lines.join('\n');
 }
 
-// ─── --check diff helper ──────────────────────────────────────────────────────
-
-/**
- * Normalize line endings to LF for CRLF-agnostic comparison.
- * FIX 4: The serializer has no nondeterministic content (no timestamp), so
- * the generated-by-line stripping that was here has been removed — full content
- * comparison is now used so header drift is caught by --check.
- *
- * @param {string} content
- * @returns {string}
- */
-function normalizeLineEndings(content) {
-  return content.replace(/\r/g, '');
-}
-
 // ─── Main ─────────────────────────────────────────────────────────────────────
 
 function main() {
@@ -415,7 +395,7 @@ function main() {
 
     const committed = fs.readFileSync(CONTRACT_PATH, 'utf8');
     // FIX 4: Compare full content (no generated-by stripping) so header drift is caught.
-    if (normalizeLineEndings(committed) !== normalizeLineEndings(live)) {
+    if (normalizeEol(committed) !== normalizeEol(live)) {
       process.stderr.write(
         'gsd-core/bin/lib/loop-host-contract.cjs is stale. Run:\n' +
         '  node scripts/gen-loop-host-contract.cjs --write\n',
@@ -466,8 +446,11 @@ const HOST_LOOP_FILES = STEP_WORKFLOWS.map((w) => 'gsd-core/workflows/' + w.file
  * @param {string} text  Content of a workflow file (or any text).
  * @returns {Set<string>}
  */
+/** The call-site shape both scanners key on — one regex, two consumers (#3606). */
+const CALL_SITE_RE = /loop render-hooks\s+([a-z:]+)/g;
+
 function scanWiredPoints(text) {
-  const re = /loop render-hooks\s+([a-z:]+)/g;
+  const re = CALL_SITE_RE;
   const result = new Set();
   let m;
   while ((m = re.exec(text)) !== null) {
@@ -476,6 +459,132 @@ function scanWiredPoints(text) {
   return result;
 }
 
+// ─── Hook-kind coverage (#3606) ──────────────────────────────────────────────
+
+const HOOK_KINDS = ['contribution', 'step', 'gate'];
+
+/**
+ * The kinds one call site's dispatch text actually covers (#3606).
+ *
+ * A point having a `loop render-hooks <point>` call site proves the hooks are
+ * RENDERED, not that they are DISPATCHED — a consumer that iterates only
+ * `kind == "gate"` (or narrows `kind == "step"` to one `ref.skill`) silently
+ * drops every other registered kind. Coverage rules for the text following a
+ * call site, up to the next call site or the region cap, judged LINE by line:
+ *
+ * - A deferral line (one carrying an `@`-included path to the generic
+ *   contract, e.g. `@gsd-core/references/loop-hook-dispatch.md`) that names a
+ *   kind (`kind == "step"`) covers that kind; a deferral line with no kind
+ *   discriminator ("apply each entry") covers every kind. A bare §-citation
+ *   of the reference (validation guidance only, no `@`) covers nothing —
+ *   plan-phase cites the gate-validation section while dispatching only gates.
+ * - Otherwise a kind is covered when some LINE dispatches it unconditionally:
+ *   a `kind == "<kind>"` discriminator with NO same-line narrowing to one
+ *   hook (`ref.skill ==`, `ref.agent ==`, `ref.command ==`). A narrowed line
+ *   special-cases ONE hook and proves nothing about the kind generally — the
+ *   exact hand-rolled-consumer shape the reference warns about.
+ *
+ * Quote style and spacing vary across the corpus (`kind == "step"`,
+ * `kind === 'gate'`), so the matcher is tolerant of both quote characters and
+ * of `==`/`===`.
+ *
+ * Pure: same input, same output; CRLF-safe (line splitting tolerates \r).
+ *
+ * @param {string} region  Dispatch text following one call site.
+ * @returns {Set<string>}
+ */
+function coveredKindsInRegion(region) {
+  const covered = new Set();
+  // Same-SEGMENT narrowing to ONE hook voids credit: `ref.skill ==`, `capId ==`,
+  // and `into ==` each special-case a subset, not the kind generally
+  // (plan-phase's `kind == "contribution" and capId == "security"` is the
+  // hand-rolled shape; `into == "planner"` covers only planner-targeted
+  // contributions). Segments, not lines: execute-phase legitimately writes
+  // "dispatch `kind == "step"` hooks per … . `ref.skill == "code-review"`:" —
+  // the deferral is one sentence, the specialization the next; narrowing in a
+  // DIFFERENT segment must not void the deferral's credit.
+  const narrowingRe = /(?:ref\.(?:skill|agent|command)|capId|into)\s*={2,3}/;
+  // Negated mentions describe an absence, not a dispatch ("Branch 1 — no active
+  // step hooks (`activeHooks` has no entry with `kind == "step"`)" — ship.md).
+  const negationRe = /\b(?:no|without|absent|lacks?|missing)\b[^.|]*kind\s*={2,3}/;
+  const deferralRe = /@\S*loop-hook-dispatch\.md/;
+  for (const line of region.split(/\r?\n/)) {
+    // Sentence segments: a `.`/`;` followed by whitespace ends a segment. A
+    // period NOT followed by whitespace (the `.md` inside a deferral path,
+    // `ref.skill`) is not a boundary.
+    for (const segment of line.split(/(?<=[.;])\s+/)) {
+      const kindDiscriminators = [];
+      for (const kind of HOOK_KINDS) {
+        if (new RegExp(`kind\\s*={2,3}\\s*["']${kind}["']`).test(segment)) kindDiscriminators.push(kind);
+      }
+      if (kindDiscriminators.length === 0) {
+        // A deferral with no kind discriminator ("apply each entry per …")
+        // still covers every kind.
+        if (deferralRe.test(segment)) for (const kind of HOOK_KINDS) covered.add(kind);
+        continue;
+      }
+      if (negationRe.test(segment)) continue;
+      if (deferralRe.test(segment)) {
+        // Deferral naming kinds ("dispatch `kind == "step"` hooks per …").
+        if (!narrowingRe.test(segment)) for (const kind of kindDiscriminators) covered.add(kind);
+        continue;
+      }
+      if (!narrowingRe.test(segment)) for (const kind of kindDiscriminators) covered.add(kind);
+    }
+  }
+  return covered;
+}
+
+/**
+ * Scan every `loop render-hooks <point>` call site in `text` and accumulate,
+ * per point, the union of hook kinds its dispatch regions cover (#3606).
+ *
+ * @param {string} text  Content of a workflow file (or any text).
+ * @returns {Map<string, Set<string>>}  point → covered kinds.
+ */
+function scanWiredKinds(text) {
+  const result = new Map();
+  const siteRe = CALL_SITE_RE;
+  const sites = [];
+  let m;
+  while ((m = siteRe.exec(text)) !== null) sites.push({ point: m[1], start: m.index });
+  const REGION_CAP = 6000;
+  for (let i = 0; i < sites.length; i++) {
+    const regionEnd = i + 1 < sites.length ? sites[i + 1].start : Math.min(text.length, sites[i].start + REGION_CAP);
+    const region = text.slice(sites[i].start, regionEnd);
+    const covered = coveredKindsInRegion(region);
+    if (!result.has(sites[i].point)) result.set(sites[i].point, new Set());
+    for (const kind of covered) result.get(sites[i].point).add(kind);
+  }
+  return result;
+}
+
+/**
+ * Read every host-loop workflow file and return, per point, the union of hook
+ * kinds its call sites' dispatch text covers (#3606).
+ *
+ * @param {string} [repoRoot]  Path to the repository root. Defaults to ROOT.
+ * @returns {Map<string, Set<string>>}
+ */
+function getWiredKinds(repoRoot) {
+  const resolvedRoot = repoRoot !== undefined ? repoRoot : ROOT;
+  const result = new Map();
+  for (const relPath of HOST_LOOP_FILES) {
+    const absPath = path.join(resolvedRoot, relPath);
+    let content;
+    try {
+      content = fs.readFileSync(absPath, 'utf8');
+    } catch (err) {
+      throw new Error('getWiredKinds: cannot read host-loop file ' + absPath + ': ' + err.message);
+    }
+    for (const [point, kinds] of scanWiredKinds(content)) {
+      if (!result.has(point)) result.set(point, new Set());
+      for (const kind of kinds) result.get(point).add(kind);
+    }
+  }
+  return result;
+}
+
 /**
  * Read every host-loop workflow file and return the union of all wired loop points
  * (i.e. points that have a `loop render-hooks <point>` call site).
@@ -509,7 +618,7 @@ module.exports = {
   assertPointsCoverage,
   buildContract,
   serializeContract,
-  normalizeLineEndings,
+  normalizeLineEndings: normalizeEol,
   STEP_WORKFLOWS,
   HOST_LOOP_FILES,
   CANONICAL_POINTS,
@@ -517,6 +626,10 @@ module.exports = {
   ROLE_TO_AGENT,
   scanWiredPoints,
   getWiredLoopPoints,
+  coveredKindsInRegion,
+  scanWiredKinds,
+  getWiredKinds,
+  HOOK_KINDS,
 };
 
 // ─── CLI entry point ──────────────────────────────────────────────────────────

package/scripts/gen-registry.cjs

@@ -35,6 +35,7 @@ const path = require('node:path');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 const { renderMarkdown } = require('./registry-schema.cjs');
+const { normalizeEol } = require('../gsd-core/bin/lib/text-lines.cjs');
 
 const SOURCES = [
   { type: 'capability', jsonFile: 'capabilities.json', mdFile: 'capability-registry.md' },
@@ -42,18 +43,6 @@ const SOURCES = [
   { type: 'reviewer', jsonFile: 'reviewers.json', mdFile: 'reviewer-registry.md', optional: true },
 ];
 
-/**
- * The generator always writes LF; a Windows checkout (autocrlf) may present
- * committed files with CRLF. Normalize before comparing so `--check` only
- * fails on real content drift, not checkout-introduced line-ending noise.
- *
- * @param {string} content
- * @returns {string}
- */
-function normalizeLineEndings(content) {
-  return content.replace(/\r/g, '');
-}
-
 function getRegistriesDir() {
   return path.join(process.cwd(), 'docs', 'registries');
 }
@@ -126,7 +115,7 @@ function main() {
         continue;
       }
       const committed = fs.readFileSync(mdPath, 'utf8');
-      if (normalizeLineEndings(committed) !== normalizeLineEndings(rendered)) {
+      if (normalizeEol(committed) !== normalizeEol(rendered)) {
         process.stderr.write(`${mdFile} is stale. Run:\n  node scripts/gen-registry.cjs --write\n`);
         anyDrift = true;
       }
@@ -149,4 +138,4 @@ function main() {
 
 if (require.main === module) runMain(main);
 
-module.exports = { main, renderFor, SOURCES, normalizeLineEndings };
+module.exports = { main, renderFor, SOURCES, normalizeLineEndings: normalizeEol };

package/scripts/gen-scripts-cli-exit.cjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * gen-scripts-cli-exit.cjs — generates scripts/lib/cli-exit.cjs from a fresh
+ * compile of src/cli-exit.cts.
+ *
+ * ADR-3889 Phase 0 (#3904): scripts/lib/cli-exit.cjs used to be a hand-written
+ * fork of gsd-core/bin/lib/cli-exit.cjs (the compiled artifact of
+ * src/cli-exit.cts). The two drifted — only the .cts copy routed a
+ * non-ExitError throw through getJsonErrorMode() to emit a structured
+ * { ok:false, reason, message } envelope. This script makes scripts/lib/cli-exit.cjs
+ * a generated artifact of the SAME source, so the two surfaces cannot diverge
+ * again.
+ *
+ * scripts/ runs straight from the repo checkout and must work on an unbuilt
+ * clone (scripts/check-env.cjs requires this file before any build runs), so
+ * the generated file is compiled to a THROWAWAY outDir rather than read from
+ * gsd-core/bin/lib/ — reading the tracked build output would let a stale build
+ * produce a false green.
+ *
+ * Usage:
+ *   node scripts/gen-scripts-cli-exit.cjs            # same as --write
+ *   node scripts/gen-scripts-cli-exit.cjs --write     # write scripts/lib/cli-exit.cjs
+ *   node scripts/gen-scripts-cli-exit.cjs --check     # exit 1 if committed file is stale
+ */
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const OUTPUT_PATH = path.join(REPO_ROOT, 'scripts', 'lib', 'cli-exit.cjs');
+const COMPILE_TIMEOUT_MS = 60_000;
+
+/** Frozen reason codes so tests assert on structure, not prose. */
+const REASON = Object.freeze({
+  OK: 'ok_generated_sync',
+  DRIFTED: 'fail_generated_drifted',
+  BUILD_FAILED: 'fail_build_failed',
+  MISSING_EMIT: 'fail_missing_emit',
+  USAGE: 'fail_usage',
+});
+
+const USAGE_MESSAGE = [
+  'Usage: node scripts/gen-scripts-cli-exit.cjs [--write|--check]',
+  '  (no flag)  same as --write',
+  '  --write    write scripts/lib/cli-exit.cjs',
+  '  --check    exit 1 if the committed file is stale',
+].join('\n');
+
+const BANNER = [
+  '// GENERATED FILE — DO NOT EDIT BY HAND.',
+  '// Source of truth: src/cli-exit.cts. Regenerate with:',
+  '//   node scripts/gen-scripts-cli-exit.cjs --write',
+  '// Byte-compared by `npm run lint:generated-sync` (#3904, ADR-3889 Phase 0).',
+  '//',
+  '// Why this copy exists: scripts/ runs straight from the repo checkout and must',
+  '// work on an unbuilt clone — 64+ scripts require this file, including',
+  '// check-env.cjs, which runs before any build. gsd-core/bin/lib/cli-exit.cjs is',
+  '// gitignored tsc output and doubles as the build sentinel, so it cannot be',
+  '// required from here. Hence one source, two emitted locations.',
+  '',
+  '',
+].join('\n');
+
+/** Compile the whole project to a throwaway outDir so the work tree is untouched. */
+function compileToTemp() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-scripts-cli-exit-'));
+  try {
+    execFileSync(
+      process.execPath,
+      [
+        path.join(REPO_ROOT, 'node_modules', 'typescript', 'bin', 'tsc'),
+        '-p', path.join(REPO_ROOT, 'tsconfig.build.json'),
+        '--outDir', tmp,
+        // A throwaway outDir must not reuse the in-tree incremental state, or
+        // tsc skips emit for files it believes are already current.
+        '--incremental', 'false',
+        '--tsBuildInfoFile', 'null',
+      ],
+      { cwd: REPO_ROOT, encoding: 'utf8', stdio: 'pipe', timeout: COMPILE_TIMEOUT_MS },
+    );
+    return { ok: true, dir: tmp };
+  } catch (err) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    const detail = [err.stdout, err.stderr].filter(Boolean).join('\n').trim();
+    return { ok: false, detail };
+  }
+}
+
+/**
+ * Compile src/cli-exit.cts to a throwaway outDir and return the expected
+ * generated content (banner + compiled bytes), or a failure descriptor.
+ *
+ * @returns {{ ok: true, content: string } | { ok: false, reason: string, detail?: string }}
+ */
+function buildExpectedContent() {
+  const build = compileToTemp();
+  if (!build.ok) {
+    return { ok: false, reason: REASON.BUILD_FAILED, detail: build.detail };
+  }
+  try {
+    const emitted = path.join(build.dir, 'cli-exit.cjs');
+    if (!fs.existsSync(emitted)) {
+      return { ok: false, reason: REASON.MISSING_EMIT, detail: `no emit produced at ${emitted} from src/cli-exit.cts` };
+    }
+    const compiled = fs.readFileSync(emitted, 'utf8');
+    return { ok: true, content: BANNER + compiled };
+  } finally {
+    fs.rmSync(build.dir, { recursive: true, force: true });
+  }
+}
+
+function doWrite() {
+  const result = buildExpectedContent();
+  if (!result.ok) {
+    console.error(`FAIL gen-scripts-cli-exit: ${result.reason}`);
+    if (result.detail) console.error(result.detail);
+    return 1;
+  }
+  fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });
+  fs.writeFileSync(OUTPUT_PATH, result.content, 'utf8');
+  console.log(`ok gen-scripts-cli-exit: wrote ${path.relative(REPO_ROOT, OUTPUT_PATH)}`);
+  return 0;
+}
+
+function doCheck() {
+  const result = buildExpectedContent();
+  if (!result.ok) {
+    console.error(`FAIL gen-scripts-cli-exit: ${result.reason}`);
+    if (result.detail) console.error(result.detail);
+    return 1;
+  }
+
+  if (!fs.existsSync(OUTPUT_PATH)) {
+    console.error(`FAIL gen-scripts-cli-exit: ${REASON.MISSING_EMIT}`);
+    console.error(`  ${path.relative(REPO_ROOT, OUTPUT_PATH)} does not exist. Run:`);
+    console.error('  node scripts/gen-scripts-cli-exit.cjs --write');
+    return 1;
+  }
+
+  const committed = fs.readFileSync(OUTPUT_PATH, 'utf8');
+  if (committed !== result.content) {
+    console.error(`FAIL gen-scripts-cli-exit: ${REASON.DRIFTED}`);
+    console.error(
+      `  ${path.relative(REPO_ROOT, OUTPUT_PATH)} (${committed.length} bytes) != ` +
+      `compile of src/cli-exit.cts (${result.content.length} bytes)`,
+    );
+    console.error('');
+    console.error('Regenerate with:');
+    console.error('  node scripts/gen-scripts-cli-exit.cjs --write');
+    return 1;
+  }
+
+  console.log(`ok gen-scripts-cli-exit: ${path.relative(REPO_ROOT, OUTPUT_PATH)} matches src/cli-exit.cts`);
+  return 0;
+}
+
+function main() {
+  const flag = process.argv[2];
+  const extra = process.argv[3];
+
+  if (flag !== undefined && flag !== '--write' && flag !== '--check') {
+    console.error(`FAIL gen-scripts-cli-exit: ${REASON.USAGE}`);
+    console.error(`  unrecognized argument: ${flag}`);
+    console.error(USAGE_MESSAGE);
+    return 1;
+  }
+
+  if (extra !== undefined) {
+    console.error(`FAIL gen-scripts-cli-exit: ${REASON.USAGE}`);
+    console.error(`  unexpected extra argument: ${extra}`);
+    console.error(USAGE_MESSAGE);
+    return 1;
+  }
+
+  if (flag === '--check') return doCheck();
+  return doWrite();
+}
+
+if (require.main === module) process.exitCode = main();
+
+module.exports = { REASON, buildExpectedContent, OUTPUT_PATH, BANNER };