@opengsd/gsd-core 1.2.0-rc.1

package/scripts/changeset/serialize.cjs

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * Markdown serializer + parser for the changelog IR. The two are inverses
+ * over the well-formed subset; tests assert via round-trip (parse(serialize(ir)))
+ * rather than by inspecting serialized text — see CONTRIBUTING.md
+ * "Prohibited: Raw Text Matching on Test Outputs".
+ *
+ * Serialized form (Keep a Changelog):
+ *
+ *   ## [1.42.0] - 2026-05-01
+ *
+ *   ### Fixed
+ *
+ *   - body of the bullet (#NNNN)
+ *
+ *   <priorChangelog appended verbatim>
+ */
+
+function serializeChangelog(ir) {
+  const lines = [];
+  const { version, date } = ir.releaseHeader;
+  lines.push(`## [${version}] - ${date}`);
+  lines.push('');
+  for (const section of ir.sections) {
+    lines.push(`### ${section.type}`);
+    lines.push('');
+    for (const b of section.bullets) {
+      lines.push(`- ${b.body} (#${b.pr})`);
+    }
+    lines.push('');
+  }
+  let out = lines.join('\n');
+  if (ir.priorChangelog) {
+    out += '\n' + ir.priorChangelog;
+  }
+  return out;
+}
+
+/**
+ * Inverse parser: extracts the structured releases from a CHANGELOG.md
+ * text. Returns { releases: [{ version, date, sections: [{ type, bullets:
+ * [{ pr, body }] }] }] }. Tolerates the actual repo's CHANGELOG dialect.
+ *
+ * Multi-line bullets are supported: a bullet opens on a line starting with
+ * `- ` and continues on lines starting with two or more spaces (or a tab).
+ * The `(#NNNN)` PR trailer may appear on any continuation line.  Single-line
+ * bullets (entire entry on one `- ` line) are still handled as before.
+ *
+ * Fix for #3496: the previous implementation only matched single-line bullets
+ * whose `(#NNNN)` suffix was on the same line as the opening `- `.  Long
+ * bullets — which wrap onto indented continuation lines — returned 0 entries
+ * for their section even when the markdown was well-formed.
+ */
+function parseChangelog(text) {
+  const releases = [];
+  const lines = text.split(/\r?\n/);
+  let cur = null;
+  let curSection = null;
+  // Accumulates lines belonging to the current in-flight bullet (may span
+  // multiple lines).  Flushed when a new block-level element is encountered.
+  let bulletLines = null;
+
+  function flushBullet() {
+    if (bulletLines === null || !curSection) return;
+    const joined = bulletLines.join(' ').trim();
+    // Locate the (# pr) trailer anywhere in the joined text.  The trailer is
+    // expected to be at the very end, but we tolerate trailing whitespace.
+    const trailMatch = joined.match(/^(.*?)\s*\(#(\d+)\)\s*$/);
+    if (trailMatch) {
+      curSection.bullets.push({ body: trailMatch[1].trim(), pr: Number(trailMatch[2]) });
+    } else {
+      // Bullet has no PR trailer — preserve it with pr: null so callers
+      // (e.g. cmdExtract) do not silently drop authored content.
+      curSection.bullets.push({ body: joined, pr: null });
+    }
+    bulletLines = null;
+  }
+
+  for (const line of lines) {
+    // F3: match linked headers: ## [1.42.1](url) - 2026-05-15
+    //     The (?:\([^)]*\))? group skips an optional (url) after the closing ]
+    //     before looking for the optional date suffix.
+    // F6: strip a leading `v` from the captured version so `## [v1.0.0]`
+    //     parses as version "1.0.0" instead of "v1.0.0".
+    const releaseMatch = line.match(/^##\s+\[([^\]]+)\](?:\([^)]*\))?\s*(?:-\s*(\S+))?/);
+    if (releaseMatch) {
+      flushBullet();
+      const rawVersion = releaseMatch[1];
+      const version = rawVersion.replace(/^v/, '');
+      cur = { version, date: releaseMatch[2] || null, sections: [] };
+      curSection = null;
+      releases.push(cur);
+      continue;
+    }
+    if (!cur) continue;
+    const sectionMatch = line.match(/^###\s+(.+?)\s*$/);
+    if (sectionMatch) {
+      flushBullet();
+      curSection = { type: sectionMatch[1], bullets: [] };
+      cur.sections.push(curSection);
+      continue;
+    }
+    if (!curSection) continue;
+
+    // New bullet: line begins with `- ` (after optional leading spaces that
+    // would indicate a nested list — we only handle top-level bullets here).
+    if (/^-\s+/.test(line)) {
+      flushBullet();
+      bulletLines = [line.replace(/^-\s+/, '')];
+      continue;
+    }
+
+    // Continuation line: any indentation (F7: relaxed from /^[ \t]{2}/ so that
+    // 1-space-indented continuations also fold) BUT NOT a nested bullet marker
+    // (F4: `  - nested item` terminates the current bullet rather than folding).
+    if (bulletLines !== null && /^\s+/.test(line) && !/^\s+-\s/.test(line)) {
+      bulletLines.push(line.trim());
+      continue;
+    }
+
+    // Any other line (blank, heading, nested bullet, etc.) terminates a pending bullet.
+    flushBullet();
+  }
+  flushBullet();
+
+  return { releases };
+}
+
+module.exports = { serializeChangelog, parseChangelog };

package/scripts/check-alias-drift.cjs

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..');
+const aliasesPath = path.join(ROOT, 'get-shit-done', 'bin', 'lib', 'command-aliases.cjs');
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function ensureArray(value, name) {
+  if (!Array.isArray(value)) {
+    fail(`check:alias-drift: expected ${name} to be an array`);
+  }
+}
+
+function assertNoDuplicates(values, label) {
+  const seen = new Set();
+  for (const value of values) {
+    if (seen.has(value)) {
+      fail(`check:alias-drift: duplicate ${label} value "${value}"`);
+    }
+    seen.add(value);
+  }
+}
+
+if (!fs.existsSync(aliasesPath)) {
+  fail(`check:alias-drift: missing ${path.relative(ROOT, aliasesPath)}`);
+}
+
+const aliases = require(aliasesPath);
+
+const families = [
+  {
+    commandAliases: 'STATE_COMMAND_ALIASES',
+    subcommands: 'STATE_SUBCOMMANDS',
+    routerPath: path.join(ROOT, 'get-shit-done', 'bin', 'lib', 'state-command-router.cjs'),
+  },
+  {
+    commandAliases: 'VERIFY_COMMAND_ALIASES',
+    subcommands: 'VERIFY_SUBCOMMANDS',
+    routerPath: path.join(ROOT, 'get-shit-done', 'bin', 'lib', 'verify-command-router.cjs'),
+  },
+  {
+    commandAliases: 'INIT_COMMAND_ALIASES',
+    subcommands: 'INIT_SUBCOMMANDS',
+    routerPath: path.join(ROOT, 'get-shit-done', 'bin', 'lib', 'init-command-router.cjs'),
+  },
+  {
+    commandAliases: 'PHASE_COMMAND_ALIASES',
+    subcommands: 'PHASE_SUBCOMMANDS',
+    routerPath: path.join(ROOT, 'get-shit-done', 'bin', 'lib', 'phase-command-router.cjs'),
+  },
+  {
+    commandAliases: 'PHASES_COMMAND_ALIASES',
+    subcommands: 'PHASES_SUBCOMMANDS',
+    routerPath: path.join(ROOT, 'get-shit-done', 'bin', 'lib', 'phases-command-router.cjs'),
+  },
+  {
+    commandAliases: 'VALIDATE_COMMAND_ALIASES',
+    subcommands: 'VALIDATE_SUBCOMMANDS',
+    routerPath: path.join(ROOT, 'get-shit-done', 'bin', 'lib', 'validate-command-router.cjs'),
+  },
+  {
+    commandAliases: 'ROADMAP_COMMAND_ALIASES',
+    subcommands: 'ROADMAP_SUBCOMMANDS',
+    routerPath: path.join(ROOT, 'get-shit-done', 'bin', 'lib', 'roadmap-command-router.cjs'),
+  },
+];
+
+for (const family of families) {
+  const commandAliases = aliases[family.commandAliases];
+  const subcommands = aliases[family.subcommands];
+
+  ensureArray(commandAliases, family.commandAliases);
+  ensureArray(subcommands, family.subcommands);
+
+  const derivedSubcommands = commandAliases.map((entry) => entry && entry.subcommand);
+  assertNoDuplicates(derivedSubcommands, `${family.commandAliases}.subcommand`);
+
+  if (derivedSubcommands.length !== subcommands.length) {
+    fail(
+      `check:alias-drift: ${family.subcommands} length ${subcommands.length} does not match ` +
+      `${family.commandAliases} length ${derivedSubcommands.length}`,
+    );
+  }
+
+  for (let i = 0; i < derivedSubcommands.length; i++) {
+    if (derivedSubcommands[i] !== subcommands[i]) {
+      fail(
+        `check:alias-drift: ${family.subcommands}[${i}] = "${subcommands[i]}" ` +
+        `does not match ${family.commandAliases}[${i}].subcommand = "${derivedSubcommands[i]}"`,
+      );
+    }
+  }
+
+  const routerSource = fs.readFileSync(family.routerPath, 'utf8');
+  if (!routerSource.includes(family.subcommands)) {
+    fail(
+      `check:alias-drift: ${path.relative(ROOT, family.routerPath)} does not reference ${family.subcommands}`,
+    );
+  }
+}
+
+process.stdout.write('check:alias-drift ok\n');

package/scripts/check-env.cjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/check-env.cjs — Environment parity validator for contributors (issue #117).
+//
+// Node.js port of scripts/check-env.sh. Behaviorally identical output and
+// exit codes; shell-agnostic so it runs on Windows, macOS, and Linux.
+//
+// Checks that the developer's environment matches project requirements before
+// running tests or audits. Designed to catch mismatches early rather than
+// through cryptic test failures.
+//
+// Exit codes:
+//   0  All checks passed
+//   1  One or more checks failed
+//   2  Tool error (missing required tool, corrupt package.json, etc.)
+//
+// Usage:
+//   node scripts/check-env.cjs           # Human-readable report
+//   node scripts/check-env.cjs --json    # Structured JSON report
+//   node scripts/check-env.cjs --help    # This message
+//
+// Sources:
+//   npm engines:         https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines
+//   Reproducible builds: https://reproducible-builds.org/docs/source-tree/
+//   npm ci docs:         https://docs.npmjs.com/cli/v10/commands/npm-ci
+//   gsd-test-runner:     https://github.com/open-gsd/gsd-test-runner
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync, spawnSync } = require('child_process');
+
+// On Windows, npm ships as npm.cmd (a batch wrapper); spawnSync without
+// shell:true requires the exact filename including extension.
+const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+let jsonMode = false;
+
+for (const arg of process.argv.slice(2)) {
+  if (arg === '--json') {
+    jsonMode = true;
+  } else if (arg === '--help' || arg === '-h') {
+    process.stdout.write(
+      'scripts/check-env.cjs — Environment parity validator for contributors (issue #117).\n' +
+      '\n' +
+      'Checks that the developer\'s environment matches project requirements before\n' +
+      'running tests or audits. Designed to catch mismatches early rather than\n' +
+      'through cryptic test failures.\n' +
+      '\n' +
+      'Exit codes:\n' +
+      '  0  All checks passed\n' +
+      '  1  One or more checks failed\n' +
+      '  2  Tool error (missing required tool, corrupt package.json, etc.)\n' +
+      '\n' +
+      'Usage:\n' +
+      '  node scripts/check-env.cjs           # Human-readable report\n' +
+      '  node scripts/check-env.cjs --json    # Structured JSON report\n' +
+      '  node scripts/check-env.cjs --help    # This message\n'
+    );
+    process.exit(0);
+  } else {
+    process.stderr.write(`Unknown option: ${arg}\n`);
+    process.exit(2);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Locate the project root (directory containing package.json)
+// ---------------------------------------------------------------------------
+const PROJECT_ROOT = process.cwd();
+const PACKAGE_JSON = path.join(PROJECT_ROOT, 'package.json');
+
+if (!fs.existsSync(PACKAGE_JSON)) {
+  process.stderr.write(`ERROR: package.json not found in ${PROJECT_ROOT}\n`);
+  process.exit(2);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** @type {Array<{name: string, status: 'pass'|'fail'|'skip', message: string}>} */
+const checks = [];
+
+function addCheck(name, status, message) {
+  checks.push({ name, status, message });
+}
+
+/**
+ * Semver comparison: does `version` satisfy `constraint`?
+ * Constraint forms: >=X.Y.Z, >X.Y.Z, <=X.Y.Z, <X.Y.Z, =X.Y.Z, X.Y.Z
+ * Returns true if satisfied, false otherwise.
+ */
+function satisfiesConstraint(version, constraint) {
+  // Strip leading 'v' and pre-release/build suffixes
+  version = version.replace(/^v/, '').replace(/-.*$/, '').replace(/\+.*$/, '');
+
+  let op, reqVer;
+  const opMatch = constraint.match(/^(>=|>|<=|<|=)(.+)$/);
+  if (opMatch) {
+    op = opMatch[1];
+    reqVer = opMatch[2];
+  } else {
+    op = '=';
+    reqVer = constraint;
+  }
+  reqVer = reqVer.replace(/^v/, '').replace(/-.*$/, '').replace(/\+.*$/, '');
+
+  function parseTuple(v) {
+    const parts = (v + '.0.0').split('.');
+    return [
+      parseInt(parts[0], 10) || 0,
+      parseInt(parts[1], 10) || 0,
+      parseInt(parts[2], 10) || 0,
+    ];
+  }
+
+  const [vMaj, vMin, vPat] = parseTuple(version);
+  const [rMaj, rMin, rPat] = parseTuple(reqVer);
+
+  const vNum = vMaj * 1_000_000 + vMin * 1_000 + vPat;
+  const rNum = rMaj * 1_000_000 + rMin * 1_000 + rPat;
+
+  switch (op) {
+    case '>=': return vNum >= rNum;
+    case '>':  return vNum >  rNum;
+    case '<=': return vNum <= rNum;
+    case '<':  return vNum <  rNum;
+    case '=':  return vNum === rNum;
+    default:   return false;
+  }
+}
+
+/**
+ * Read a field from package.json using dot-notation (e.g. 'engines.node').
+ * Returns the string value or empty string if absent.
+ * Uses './package.json' so Node resolves relative to CWD on all platforms.
+ */
+function pkgField(fieldPath) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8'));
+    let val = pkg;
+    for (const key of fieldPath.split('.')) {
+      if (val == null || typeof val !== 'object') return '';
+      val = val[key];
+    }
+    return val != null ? String(val) : '';
+  } catch {
+    return '';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Check 1: Node version vs engines.node
+// ---------------------------------------------------------------------------
+const enginesNode = pkgField('engines.node');
+let currentNode = '';
+try {
+  currentNode = process.version.replace(/^v/, '');
+} catch { /* ignore */ }
+
+if (!currentNode) {
+  addCheck('node-version', 'fail', 'node binary not found on PATH');
+} else if (!enginesNode) {
+  addCheck('node-version', 'fail', 'engines.node missing from package.json — add it (see D2 in docs/contributing/bootstrap.md)');
+} else {
+  if (satisfiesConstraint(currentNode, enginesNode)) {
+    addCheck('node-version', 'pass', `Node ${currentNode} satisfies ${enginesNode}`);
+  } else {
+    addCheck('node-version', 'fail', `Node ${currentNode} does NOT satisfy engines.node ${enginesNode}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Check 2: npm version vs engines.npm (skip if field absent)
+// ---------------------------------------------------------------------------
+const enginesNpm = pkgField('engines.npm');
+let currentNpm = '';
+try {
+  const res = spawnSync(npmCmd, ['--version'], { encoding: 'utf8', timeout: 10_000, shell: process.platform === 'win32' });
+  if (res.status === 0 && res.stdout) {
+    currentNpm = res.stdout.trim();
+  }
+} catch { /* ignore */ }
+
+if (!enginesNpm) {
+  addCheck('npm-version', 'skip', 'engines.npm not set in package.json — skipping');
+} else if (!currentNpm) {
+  addCheck('npm-version', 'fail', 'npm binary not found on PATH');
+} else {
+  if (satisfiesConstraint(currentNpm, enginesNpm)) {
+    addCheck('npm-version', 'pass', `npm ${currentNpm} satisfies ${enginesNpm}`);
+  } else {
+    addCheck('npm-version', 'fail', `npm ${currentNpm} does NOT satisfy engines.npm ${enginesNpm}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Check 3: Lockfile presence
+// ---------------------------------------------------------------------------
+const LOCKFILE = path.join(PROJECT_ROOT, 'package-lock.json');
+if (fs.existsSync(LOCKFILE)) {
+  addCheck('lockfile-present', 'pass', 'package-lock.json exists');
+} else {
+  addCheck('lockfile-present', 'fail', "package-lock.json missing — run 'npm install' to generate it");
+}
+
+// ---------------------------------------------------------------------------
+// Check 4: Lockfile sync (npm ci --dry-run)
+// ---------------------------------------------------------------------------
+if (fs.existsSync(LOCKFILE)) {
+  try {
+    const res = spawnSync(npmCmd, ['ci', '--dry-run'], {
+      cwd: PROJECT_ROOT,
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+    });
+    if (res.status === 0) {
+      addCheck('lockfile-sync', 'pass', 'package-lock.json is in sync with package.json');
+    } else {
+      addCheck('lockfile-sync', 'fail', "package-lock.json is out of sync — run 'npm ci' to restore");
+    }
+  } catch {
+    addCheck('lockfile-sync', 'fail', "package-lock.json is out of sync — run 'npm ci' to restore");
+  }
+} else {
+  addCheck('lockfile-sync', 'skip', 'skipped — lockfile missing');
+}
+
+// ---------------------------------------------------------------------------
+// Check 5: Version manager pin vs active Node
+// Looks for .nvmrc, .node-version, or .tool-versions at project root.
+// ---------------------------------------------------------------------------
+const NVMRC = path.join(PROJECT_ROOT, '.nvmrc');
+const NODE_VERSION_FILE = path.join(PROJECT_ROOT, '.node-version');
+const TOOL_VERSIONS = path.join(PROJECT_ROOT, '.tool-versions');
+
+let pinnedMajor = '';
+let pinSource = '';
+
+if (fs.existsSync(NVMRC)) {
+  const content = fs.readFileSync(NVMRC, 'utf8').split('\n')[0].trim().replace(/^v/, '');
+  pinnedMajor = content.split('.')[0];
+  pinSource = '.nvmrc';
+} else if (fs.existsSync(NODE_VERSION_FILE)) {
+  const content = fs.readFileSync(NODE_VERSION_FILE, 'utf8').split('\n')[0].trim().replace(/^v/, '');
+  pinnedMajor = content.split('.')[0];
+  pinSource = '.node-version';
+} else if (fs.existsSync(TOOL_VERSIONS)) {
+  const lines = fs.readFileSync(TOOL_VERSIONS, 'utf8').split('\n');
+  const nodeLine = lines.find(l => /^nodejs\s+/.test(l));
+  if (nodeLine) {
+    const ver = nodeLine.split(/\s+/)[1] || '';
+    pinnedMajor = ver.replace(/^v/, '').split('.')[0];
+    pinSource = '.tool-versions';
+  }
+}
+
+if (!pinnedMajor) {
+  addCheck('version-manager-pin', 'skip', 'no .nvmrc, .node-version, or .tool-versions found — skipping');
+} else if (process.env.CI === 'true') {
+  addCheck('version-manager-pin', 'skip', 'CI=true — version-manager pin check skipped (matrix tests multiple Node majors)');
+} else {
+  const activeMajor = process.version.replace(/^v/, '').split('.')[0];
+  if (activeMajor === pinnedMajor) {
+    addCheck('version-manager-pin', 'pass', `Active Node major (${activeMajor}) matches ${pinSource} pin (${pinnedMajor})`);
+  } else {
+    addCheck('version-manager-pin', 'fail', `Active Node major (${activeMajor}) does NOT match ${pinSource} pin (${pinnedMajor}) — run 'nvm use' or equivalent`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Output
+// ---------------------------------------------------------------------------
+const overallPass = checks.every(c => c.status !== 'fail');
+
+if (jsonMode) {
+  // Structured JSON: {pass: bool, checks: [{name, status, message}]}
+  const out = {
+    pass: overallPass,
+    checks: checks.map(c => ({ name: c.name, status: c.status, message: c.message })),
+  };
+  process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+} else {
+  // Human-readable report
+  process.stdout.write('=== Environment Check ===\n');
+  for (const { name, status, message } of checks) {
+    const icon = status === 'pass' ? '[PASS]' : status === 'fail' ? '[FAIL]' : '[SKIP]';
+    const namePadded = name.padEnd(25);
+    process.stdout.write(`  ${icon}  ${namePadded}  ${message}\n`);
+  }
+  process.stdout.write('\n');
+  if (overallPass) {
+    process.stdout.write('Result: ALL CHECKS PASSED\n');
+  } else {
+    process.stdout.write('Result: ONE OR MORE CHECKS FAILED — see above\n');
+  }
+}
+
+process.exit(overallPass ? 0 : 1);