@opengsd/gsd-core 1.7.0 → 1.9.0

package/scripts/check-glossary-refs.cjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Verifies the machine-checkable claims in CONTEXT.md against the shipped
+ * tree, so the glossary cannot silently re-rot the way the ADR index did
+ * before scripts/gen-adr-index.cjs (#2340).
+ *
+ * Unlike gen-adr-index.cjs this gate has NO `--write` — CONTEXT.md's prose is
+ * hand-authored, not a derived artifact this tool can regenerate. It only
+ * verifies.
+ *
+ * Two checks:
+ *
+ *   A. File references resolve. Every backticked token in CONTEXT.md that
+ *      looks like a file path — and whose path is inside a TRACKED_PREFIXES
+ *      directory (or is one of the two named exact files) — must exist on
+ *      disk. Everything else (generated bin/lib/*.cjs, `.planning/` runtime
+ *      artifacts, `~/`- or `/`-rooted paths, bare filenames, example data
+ *      shapes like `capability.json`) is deliberately ignored: asserting
+ *      those would false-fail a clean checkout, which is the exact trap this
+ *      gate exists to avoid falling into itself.
+ *
+ *   B. `allRuntimes` enum parity. CONTEXT.md documents the runtime enum's
+ *      count and member list in prose (e.g. "Runtime enum: `allRuntimes` (17
+ *      values: claude, ...)"). This is compared against the real
+ *      `allRuntimes` array literal in bin/install.js — both the count and the
+ *      member set — so adding/removing a runtime without updating the prose
+ *      is caught.
+ *
+ * Usage:
+ *   node scripts/check-glossary-refs.cjs           # print findings to stdout
+ *   node scripts/check-glossary-refs.cjs --check    # exit 1 on any finding
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const CONTEXT_PATH = path.join(ROOT, 'CONTEXT.md');
+const INSTALL_JS_PATH = path.join(ROOT, 'bin', 'install.js');
+
+/**
+ * Directory prefixes this gate can verify against the shipped tree. A token
+ * outside these — most importantly `gsd-core/bin/lib/**`, which is generated
+ * and gitignored — is not a claim this gate can check, so it is skipped
+ * rather than asserted.
+ */
+const TRACKED_PREFIXES = [
+  'src/',
+  'tests/',
+  'scripts/',
+  'docs/',
+  'gsd-core/references/',
+  'gsd-core/workflows/',
+  'gsd-core/templates/',
+  'gsd-core/contexts/',
+  '.github/',
+  'eslint-rules/',
+];
+
+/** The only bare (no-prefix-match) tokens this gate checks by exact name. */
+const TRACKED_EXACT = new Set(['bin/install.js', 'package.json']);
+
+/**
+ * Paths CONTEXT.md documents whose ABSENCE is the healthy steady state (#2778).
+ *
+ * `TRACKED_PREFIXES` skips claims this gate *cannot* check. This is the narrower
+ * third case: a claim it must not check, because "does not exist" is the correct
+ * state rather than drift.
+ *
+ * `tests/emitted-drift-ack.json` is the acknowledgment file from ADR-2719 §3. Its
+ * whole design property is that it appears in the changed-files list ONLY when
+ * something rippled unexpectedly — "touching it IS the alarm". A permanently
+ * committed copy would signal nothing, which is exactly why the ADR rejected
+ * shipping an empty stub. So the file is absent on a healthy `next` and present
+ * only inside a PR that needs it, and asserting either way is wrong.
+ *
+ * Until #2778 this passed only by accident: CONTEXT.md's `RULESET.` entries are
+ * themselves backtick-wrapped and contain backticks, so the sequential pairing in
+ * `extractTrackedRefs` happened to leave this token outside a code span. Any edit
+ * that shifted the parity — such as #2778's own — exposed it. A gate that passes
+ * by luck is not passing; naming the exemption makes the intent explicit and
+ * survives the next edit.
+ */
+const INTENTIONALLY_ABSENT = new Set(['tests/emitted-drift-ack.json']);
+
+/**
+ * Shape a backticked token must have to even be considered a path candidate:
+ * one or more `/`-separated segments of word/dot/dash characters, with an
+ * optional trailing `:<line>` suffix. Anything else inside backticks (CLI
+ * invocations with spaces, function signatures with parens/commas, bare
+ * identifiers, env vars) is prose, not a path reference.
+ */
+const PATH_TOKEN_RE = /^[\w.-]+(?:\/[\w.-]+)*(?::\d+)?$/;
+
+/** Whether `token` (line-suffix already stripped) is one this gate checks. */
+function isTracked(token) {
+  if (INTENTIONALLY_ABSENT.has(token)) return false;
+  return TRACKED_EXACT.has(token) || TRACKED_PREFIXES.some((prefix) => token.startsWith(prefix));
+}
+
+/**
+ * True if joining `token` to ROOT stays inside ROOT. `PATH_TOKEN_RE` admits `.`
+ * inside a segment, so a token like `src/../../../etc/passwd` matches and (via
+ * the `src/` prefix) reads as "tracked" — `path.join(ROOT, token)` would then
+ * normalize to an out-of-tree absolute path and `fs.existsSync` would probe it,
+ * turning a doc lint into a filesystem-existence oracle on the CI host. A
+ * CONTEXT.md reference is always a plain in-repo path, so a `..` escape is never
+ * legitimate: confine to ROOT and drop anything that climbs out.
+ */
+function isWithinRoot(token) {
+  const resolved = path.resolve(ROOT, token);
+  return resolved === ROOT || resolved.startsWith(ROOT + path.sep);
+}
+
+/**
+ * Every distinct, trackable file-path token referenced in `text`, with any
+ * trailing `:<line>` suffix stripped.
+ */
+function extractTrackedRefs(text) {
+  const tokens = new Set();
+  const re = /`([^`]+)`/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const raw = m[1];
+    if (!PATH_TOKEN_RE.test(raw)) continue;
+    const token = raw.replace(/:\d+$/, '');
+    if (!isTracked(token)) continue;
+    if (!isWithinRoot(token)) continue;
+    tokens.add(token);
+  }
+  return tokens;
+}
+
+/** Check A: every tracked reference must resolve on disk. */
+function checkFileRefs(contextText) {
+  const tokens = [...extractTrackedRefs(contextText)].sort();
+  const findings = [];
+  for (const token of tokens) {
+    if (!fs.existsSync(path.join(ROOT, token))) {
+      findings.push(`CONTEXT.md references \`${token}\` which does not exist in the repo.`);
+    }
+  }
+  return { findings, checked: tokens.length };
+}
+
+/** The glossary's own claim: `Runtime enum: `allRuntimes` (N values: a, b, c)`. */
+const ALLRUNTIMES_CLAIM_RE = /Runtime enum:\s*`allRuntimes`\s*\((\d+)\s*values:\s*([^)]*)\)/;
+
+function parseClaimedRuntimes(contextText) {
+  const m = contextText.match(ALLRUNTIMES_CLAIM_RE);
+  if (!m) return null;
+  return {
+    count: Number(m[1]),
+    members: m[2]
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean),
+  };
+}
+
+/** The real `allRuntimes = [...]` array literal in bin/install.js. */
+const ALLRUNTIMES_ARRAY_RE = /allRuntimes\s*=\s*\[([^\]]*)\]/;
+
+function parseRealRuntimes(installJsText) {
+  const m = installJsText.match(ALLRUNTIMES_ARRAY_RE);
+  if (!m) return null;
+  return [...m[1].matchAll(/'([^']+)'/g)].map((mm) => mm[1]);
+}
+
+/** Check B: CONTEXT.md's prose count + member set must match bin/install.js. */
+function checkAllRuntimesParity(contextText, installJsText) {
+  const claimed = parseClaimedRuntimes(contextText);
+  if (!claimed) {
+    return [
+      'CONTEXT.md is missing the `allRuntimes` enum-count sentence ' +
+        '("Runtime enum: `allRuntimes` (N values: ...)") that this gate checks against bin/install.js.',
+    ];
+  }
+
+  const real = parseRealRuntimes(installJsText);
+  if (!real) {
+    return ['bin/install.js does not contain a parseable `allRuntimes = [...]` array literal.'];
+  }
+
+  const findings = [];
+  if (claimed.count !== real.length) {
+    findings.push(
+      `CONTEXT.md's allRuntimes enum-count sentence claims ${claimed.count} values but bin/install.js's ` +
+        `allRuntimes array has ${real.length}.`,
+    );
+  }
+
+  const claimedSet = new Set(claimed.members);
+  const realSet = new Set(real);
+  const missingFromProse = real.filter((r) => !claimedSet.has(r)).sort();
+  const noLongerReal = claimed.members.filter((c) => !realSet.has(c)).sort();
+  if (missingFromProse.length > 0 || noLongerReal.length > 0) {
+    const parts = [];
+    if (missingFromProse.length > 0) parts.push(`missing from CONTEXT.md's list: ${missingFromProse.join(', ')}`);
+    if (noLongerReal.length > 0) parts.push(`no longer in bin/install.js's allRuntimes: ${noLongerReal.join(', ')}`);
+    findings.push(`CONTEXT.md's allRuntimes member list has drifted from bin/install.js (${parts.join('; ')}).`);
+  }
+
+  return findings;
+}
+
+function main() {
+  const [, , flag] = process.argv;
+
+  const contextText = fs.readFileSync(CONTEXT_PATH, 'utf8');
+  const installJsText = fs.readFileSync(INSTALL_JS_PATH, 'utf8');
+
+  const fileRefs = checkFileRefs(contextText);
+  const runtimeFindings = checkAllRuntimesParity(contextText, installJsText);
+  const findings = [...fileRefs.findings, ...runtimeFindings];
+
+  if (flag === '--check') {
+    if (findings.length > 0) {
+      process.stderr.write(`CONTEXT.md glossary has ${findings.length} drift finding(s).\n\n`);
+      for (const f of findings) process.stderr.write(`  ✗ ${f}\n`);
+      process.stderr.write('\n');
+      throw new ExitError(1);
+    }
+    process.stdout.write(
+      `CONTEXT.md glossary references are current (${fileRefs.checked} refs checked, allRuntimes parity ok).\n`,
+    );
+    return;
+  }
+
+  if (findings.length === 0) {
+    process.stdout.write(
+      `CONTEXT.md glossary references are current (${fileRefs.checked} refs checked, allRuntimes parity ok).\n`,
+    );
+  } else {
+    process.stdout.write(`CONTEXT.md glossary has ${findings.length} drift finding(s):\n\n`);
+    for (const f of findings) process.stdout.write(`  ✗ ${f}\n`);
+  }
+}
+
+runMain(main);

package/scripts/ci-rebase-check.cjs

@@ -8,6 +8,22 @@
 //   GITHUB_BASE_REF — PR base branch name (set by GitHub Actions on pull_request events)
 //   GITHUB_REPOSITORY — owner/repo (set by GitHub Actions)
 //
+// Optional:
+//   CI_REBASE_BASE_SHA — pin the merge to one exact base commit (#2472).
+//
+// Why the pin matters. Every job of a run executes this step independently, at
+// whatever wall-clock moment it gets there — and Windows/macOS installs skew
+// that by minutes across a 12-job matrix. Merging the moving `origin/<branch>`
+// ref means that if the base advances mid-run, different jobs merge different
+// trees. That was survivable when jobs only had to agree on pass/fail, but the
+// sharded lane makes them agree on a PARTITION: each shard job computes the
+// whole split and keeps its own slice, so jobs working from different trees can
+// place a file in two shards or in none. Each job still looks internally
+// consistent, so nothing errors — a test silently never runs and CI stays
+// green. Pinning every job to `github.event.pull_request.base.sha`, which is
+// fixed for the life of the run, removes the divergence at its source rather
+// than detecting it after the fact.
+//
 // Exit 0 = merged cleanly (or merge was a no-op).
 // Exit 1 = merge conflict or fetch failure.
 
@@ -35,6 +51,28 @@ function runOrThrow(cmd, args, label) {
 const token = process.env.GITHUB_TOKEN || '';
 const baseBranch = process.env.GITHUB_BASE_REF || 'main';
 const repo = process.env.GITHUB_REPOSITORY || '';
+// Resolve what to fetch and what to merge, pinned together so they can never
+// disagree. Pure and exported so the pin contract is testable without spawning
+// git: env in, refs out.
+//
+// Only a full 40-hex sha is accepted. Anything else — empty on push/dispatch
+// events, or a malformed/injected value — falls back to the branch ref,
+// preserving the pre-#2472 behavior rather than handing an arbitrary string to
+// `git fetch` as a refspec.
+function resolveBaseRefs(env = process.env, fallbackBranch = 'main') {
+  const branch = env.GITHUB_BASE_REF || fallbackBranch;
+  const raw = env.CI_REBASE_BASE_SHA || '';
+  const sha = /^[0-9a-f]{40}$/.test(raw) ? raw : null;
+  return {
+    branch,
+    sha,
+    pinned: sha !== null,
+    fetchRef: sha || branch,
+    mergeRef: sha || `origin/${branch}`,
+  };
+}
+
+const { fetchRef, mergeRef } = resolveBaseRefs(process.env, 'main');
 
 function main() {
   // Configure git identity (needed for merge commit).
@@ -52,12 +90,12 @@ function main() {
 
   // Fetch base branch with retry.
   for (let attempt = 1; attempt <= 3; attempt++) {
-    const result = run('git', ['fetch', 'origin', baseBranch]);
+    const result = run('git', ['fetch', 'origin', fetchRef]);
     if (result) {
       break;
     }
     if (attempt === 3) {
-      throw new ExitError(1, `::error::git fetch origin ${baseBranch} failed after 3 attempts.`);
+      throw new ExitError(1, `::error::git fetch origin ${fetchRef} failed after 3 attempts.`);
     }
     // Wait before retry: attempt * 4 seconds.
     const waitMs = attempt * 4000;
@@ -67,7 +105,7 @@ function main() {
 
   // Attempt merge.
   try {
-    execFileSync('git', ['merge', '--no-edit', '--no-ff', `origin/${baseBranch}`], { stdio: 'inherit' });
+    execFileSync('git', ['merge', '--no-edit', '--no-ff', mergeRef], { stdio: 'inherit' });
   } catch (e) {
     process.stderr.write(
       `::error::This PR cannot cleanly merge origin/${baseBranch}. Rebase your branch onto current ${baseBranch} and push again.\n`
@@ -83,4 +121,10 @@ function main() {
   }
 }
 
-runMain(main);
+// Only run when invoked as the CI step. Guarded so a test can require this
+// module for resolveBaseRefs without firing git fetch/merge as a side effect.
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = { resolveBaseRefs };

package/scripts/ci-test-scope.cjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
+const path = require('path');
 const { execFileSync } = require('child_process');
 const { existsSync, readdirSync, appendFileSync } = require('fs');
 
@@ -105,9 +106,8 @@ const RULES = [
     fullMatrix: true,
     tests: [
       'tests/check-env.test.cjs',
-      'tests/npm-integrity-gate.test.cjs',
+      'tests/npm-integrity-gate.test.cjs', // #2758: absorbs the former tests/bug-3588-npm-audit-clean.test.cjs (folded into it by consolidation epic #1969 B6 #1975; the stale filename here was a silent coverage hole this rule never actually re-selected)
       'tests/package-manifest.test.cjs',
-      'tests/bug-3588-npm-audit-clean.test.cjs',
     ],
   },
   {
@@ -116,9 +116,9 @@ const RULES = [
     // still trigger the migrated module's tests (otherwise CI silently skips them).
     match: path => path.startsWith('src/') || path === 'tsconfig.build.json',
     tests: [
-      'tests/semver-compare.test.cjs',
-      'tests/bug-10-semver-policy-consolidation.test.cjs',
-      'tests/golden-install-parity.test.cjs', // any src/installer change can alter emitted install artifacts → re-verify golden install parity (drift guard)
+      'tests/semver-compare.test.cjs', // #2758: absorbs the former tests/bug-10-semver-policy-consolidation.test.cjs (folded into it by consolidation epic #1969 B3 #1972; the stale filename here was a silent coverage hole this rule never actually re-selected)
+      'tests/emitted-provenance.test.cjs', // any src/installer change can alter emitted install artifacts → re-verify provenance totality (#2724: golden-install-parity retired, this is the sole gate)
+      'tests/emitted-attribution.test.cjs',
     ],
   },
   {
@@ -142,19 +142,23 @@ const RULES = [
       // SCOPED_LANE_EXCLUDE guard below, which also drops it when it is itself a
       // changed test file.
       'tests/runtime-artifact-layout.test.cjs',
-      'tests/golden-install-parity.test.cjs', // any src/installer change can alter emitted install artifacts → re-verify golden install parity (drift guard)
+      'tests/emitted-provenance.test.cjs', // any src/installer change can alter emitted install artifacts → re-verify provenance totality (#2724: golden-install-parity retired, this is the sole gate)
+      'tests/emitted-attribution.test.cjs',
     ],
   },
   {
-    name: 'shipped install content (golden-parity drift guard, #2267)',
+    name: 'shipped install content (emitted-attribution drift guard, #2267/#2724)',
     // Every source file the installer EMITS into a runtime layout is captured by
-    // golden-install-parity + the install-tree snapshot. A source edit here that
-    // changes emitted output MUST re-verify the fixtures — otherwise stale golden
-    // fixtures merge silently (#2266: a hooks/gsd-statusline.js edit changed
-    // installed output but no rule selected golden-parity, so stale fixtures
-    // shipped to next undetected). Union semantics: this ADDS the parity guard on
-    // top of each path's existing content-specific tests. Targeted lane only (the
-    // golden test skips win32 by design), no fullMatrix.
+    // the emitted-attribution differential + the install-tree snapshot. A source
+    // edit here that changes emitted output MUST re-verify (#2266: a
+    // hooks/gsd-statusline.js edit changed installed output but no rule selected
+    // the drift guard, so a stale emitted state shipped to next undetected).
+    // Union semantics: this ADDS the drift guard on top of each path's existing
+    // content-specific tests. Targeted lane only (the real-tree test skips win32
+    // by design), no fullMatrix.
+    // #2724: golden-install-parity.test.cjs is retired (ADR-2719 Phase 4); the
+    // emitted differential (ADR-2719 Phase 2/3) is now the sole gate for a PR
+    // editing only shipped content, the archetypal emitted-ripple case.
     // NOTE: intentionally NOT a blanket 'gsd-core/' prefix, for two reasons:
     // (1) gsd-core/bin/** is tsc-compiled runtime output — EXCLUDED_PREFIXES-
     //     excluded from both manifests, and already covered by the 'installer and
@@ -172,8 +176,9 @@ const RULES = [
       (path.startsWith('gsd-core/bin/shared/') && path.endsWith('.json')) ||
       ['scripts/fix-slash-commands.cjs', 'scripts/gen-capability-registry.cjs', 'scripts/gen-loop-host-contract.cjs'].includes(path),
     tests: [
-      'tests/golden-install-parity.test.cjs',
       'tests/golden-install-tree.test.cjs',
+      'tests/emitted-provenance.test.cjs',
+      'tests/emitted-attribution.test.cjs',
     ],
   },
   {
@@ -236,7 +241,13 @@ const RULES = [
       'tests/workflow-size-budget.test.cjs',
       'tests/workflow-guard-registration.test.cjs',
       'tests/commands.test.cjs',
-      'tests/bug-3683-workflow-colon-namespace-leak.test.cjs',
+      // #2758: was 'tests/bug-3683-workflow-colon-namespace-leak.test.cjs', deleted by
+      // consolidation epic #1969 (B6 #1975) and folded into slash-command-namespace.test.cjs
+      // ("folded:bug-3683-workflow-colon-namespace-leak" describe block). The stale filename
+      // here was itself an instance of this issue's defect class — silently dropped by
+      // existingTests() below, so gsd-core/workflows/ changes stopped re-running this
+      // regression's coverage with nothing signaling it.
+      'tests/slash-command-namespace.test.cjs',
     ],
   },
   {
@@ -291,6 +302,41 @@ const RULES = [
   },
  ];
 
+/**
+ * Every RULES[].tests entry (deduped, across every rule) that does NOT exist on
+ * disk. #2758: a rule naming a test file that no longer exists is not merely
+ * inert — existingTests() below silently drops it out of targeted_tests, with
+ * nothing in the CI output signaling why. Phase 4 (#2724) deletes
+ * tests/golden-install-parity.test.cjs; without this check, any rule still
+ * naming it would stop selecting the guard entirely and CI would stay green
+ * throughout. Pure and independent of which rule / which file: it catches ANY
+ * phantom entry, not only the two names this issue is about.
+ * Paths resolve relative to the repo root (this file's parent directory), not
+ * the caller's cwd, so the check behaves identically whether invoked as the CLI
+ * (`node scripts/ci-test-scope.cjs ...`, cwd == repo root by convention) or
+ * required directly by a test.
+ */
+function missingRuleTestFiles(rules) {
+  const referenced = new Set();
+  for (const rule of rules) {
+    for (const f of rule.tests) referenced.add(f);
+  }
+  return [...referenced].filter(f => !existsSync(path.join(__dirname, '..', f))).sort();
+}
+
+// Fail loudly at module load, mirroring the PROTECTED_WORKFLOWS check above —
+// this fires on EVERY invocation of the CLI (including the real `changes` job
+// in .github/workflows/test.yml), not only when a test suite happens to run.
+{
+  const missing = missingRuleTestFiles(RULES);
+  if (missing.length > 0) {
+    throw new Error(
+      `ci-test-scope: RULES reference test file(s) that do not exist on disk ` +
+      `(silent coverage hole — see #2758):\n  ${missing.join('\n  ')}`,
+    );
+  }
+}
+
 function usage() {
   return [
     'Usage:',
@@ -523,4 +569,8 @@ function main() {
   }
 }
 
-runMain(main);
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = { RULES, missingRuleTestFiles };