@opengsd/gsd-core 1.7.0-rc.6 → 1.8.0

package/scripts/check-glossary-refs.cjs

@@ -0,0 +1,220 @@
+#!/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']);
+
+/**
+ * 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) {
+  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

@@ -145,6 +145,37 @@ const RULES = [
       'tests/golden-install-parity.test.cjs', // any src/installer change can alter emitted install artifacts → re-verify golden install parity (drift guard)
     ],
   },
+  {
+    name: 'shipped install content (golden-parity drift guard, #2267)',
+    // 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.
+    // 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
+    //     package layout' rule (path.startsWith('gsd-core/bin/')) — so matching it
+    //     here would be pure noise; and
+    // (2) enumerating only the installer-shipped content subtrees preserves the
+    //     bug-408 unit-fallback contract: a gsd-core/ path that is NOT shipped
+    //     verbatim (the bug-408 test uses gsd-core/src/some-util.js) must still
+    //     fall back to ['unit'] when no rule matches.
+    // Listed: the four gsd-core content subtrees the installer ships verbatim
+    // (contexts, references, templates, workflows) + bin/shared/*.json data files.
+    // Verify against Object.keys(golden fixture) grouped by gsd-core/<subdir>.
+    match: path =>
+      ['hooks/', 'commands/', 'agents/', 'skills/', 'gsd-core/workflows/', 'gsd-core/templates/', 'gsd-core/references/', 'gsd-core/contexts/', 'scripts/changeset/', 'scripts/lib/'].some(p => path.startsWith(p)) ||
+      (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',
+    ],
+  },
   {
     name: 'hooks',
     match: path => path.startsWith('hooks/'),
@@ -364,8 +395,15 @@ function classify(files) {
   for (const file of files) {
     // Determine if this file is product/pipeline code.
     // docs/ and root-level .md files are intentionally excluded.
+    // 'skills/' is shipped agent-skill content installed into every runtime by
+    // the installer (see the 'shipped install content' RULES entry below) — it
+    // must be product code, or a skills/-only change silently gets
+    // code_changed=false and skips the ENTIRE CI matrix, not merely golden-parity
+    // (found while verifying the #2267 golden-parity rule against skills/**: the
+    // rule fired in `reasons` but classify()'s codeChanged gate zeroed out every
+    // targeted test because 'skills/' was absent from this list).
     if (
-      ['bin/', 'src/', 'gsd-core/', 'agents/', 'commands/', 'hooks/', 'tests/', 'scripts/', 'eslint-rules/'].some(p => file.startsWith(p)) ||
+      ['bin/', 'src/', 'gsd-core/', 'agents/', 'commands/', 'hooks/', 'skills/', 'tests/', 'scripts/', 'eslint-rules/'].some(p => file.startsWith(p)) ||
       file === 'package.json' || file === 'package-lock.json' ||
       (file.startsWith('tsconfig') && file.endsWith('.json')) ||
       file.startsWith('.github/rulesets/')