@opengsd/gsd-core 1.2.0-rc.1

package/scripts/lint-descriptions.cjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * lint-descriptions.cjs
+ *
+ * Enforces the 100-char description budget for commands/gsd/*.md files.
+ *
+ * Usage:
+ *   node scripts/lint-descriptions.cjs [file.md ...]
+ *
+ * If no args are given, scans commands/gsd/ automatically.
+ * Exits 1 if any description exceeds 100 chars; exits 0 if all pass.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_LENGTH = 100;
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands', 'gsd');
+
+/**
+ * Parse the description field from frontmatter in a .md file.
+ * Returns null if no description is found.
+ */
+function parseDescription(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return null;
+  const fm = fmMatch[1];
+
+  const quoted = fm.match(/^description:\s+"((?:[^"\\]|\\.)*)"\s*$/m);
+  if (quoted) return quoted[1];
+
+  const plain = fm.match(/^description:\s+(.+)$/m);
+  if (plain) return plain[1].trim();
+
+  return null;
+}
+
+function getFiles() {
+  if (process.argv.length > 2) {
+    return process.argv.slice(2);
+  }
+  return fs.readdirSync(COMMANDS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => path.join(COMMANDS_DIR, f));
+}
+
+const files = getFiles();
+const violations = [];
+
+for (const filePath of files) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    process.stderr.write(`ERROR: Cannot read file: ${filePath}\n  ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const description = parseDescription(content);
+  if (description === null) continue;
+
+  if (description.length > MAX_LENGTH) {
+    violations.push({ filePath, length: description.length, description });
+  }
+}
+
+if (violations.length === 0) {
+  const checked = files.length;
+  process.stdout.write(`ok lint-descriptions: ${checked} file(s) checked, 0 violations\n`);
+  process.exit(0);
+}
+
+process.stderr.write(`\nERROR lint-descriptions: ${violations.length} violation(s) found\n\n`);
+for (const v of violations) {
+  const preview = v.description.length > 120 ? v.description.slice(0, 117) + '...' : v.description;
+  process.stderr.write(`  ${v.filePath}\n`);
+  process.stderr.write(`    Length : ${v.length} (max ${MAX_LENGTH})\n`);
+  process.stderr.write(`    Desc   : ${preview}\n\n`);
+}
+process.stderr.write(`Trim descriptions to <= ${MAX_LENGTH} chars. Flag docs belong in argument-hint:.\n\n`);
+process.exit(1);

package/scripts/lint-docs-required.cjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Docs-required lint (#3213).
+ *
+ * Mirrors scripts/changeset/lint.cjs. Pure verdict function
+ * evaluateLint({ changedFiles, fragments, labels, malformed }) returns
+ * { ok, reason, triggering } using the LINT_REASON enum. The CLI wrapper
+ * reads the PR diff (`git diff --name-only origin/${base}...HEAD`), parses
+ * each touched `.changeset/*.md` fragment, then calls evaluateLint.
+ *
+ * Tests assert on the structured verdict, never on free text.
+ */
+
+const { parseFragment, FRAGMENT_ERROR } = require('./changeset/parse.cjs');
+
+const LINT_REASON = Object.freeze({
+  OK_NO_TRIGGERING_FRAGMENTS: 'ok_no_triggering_fragments',
+  OK_DOCS_UPDATED: 'ok_docs_updated',
+  OK_OPT_OUT_LABEL: 'ok_opt_out_label',
+  OK_FRAGMENTS_EXEMPT: 'ok_fragments_exempt',
+  FAIL_DOCS_MISSING: 'fail_docs_missing',
+  FAIL_MALFORMED_FRAGMENT: 'fail_malformed_fragment',
+});
+
+const OPT_OUT_LABEL = 'no-docs';
+
+// Fragment types that require a docs update. `Fixed` and `Security` are
+// bug-class — they describe regressions or vulnerabilities, not new
+// behavior to document.
+const TRIGGERING_TYPES = new Set(['Added', 'Changed', 'Deprecated', 'Removed']);
+
+const DOCS_PREFIX = 'docs/';
+
+function isFragmentPath(file) {
+  return /^\.changeset\/[^/]+\.md$/.test(file) && !file.endsWith('/README.md');
+}
+
+function isDocsFile(file) {
+  return file.startsWith(DOCS_PREFIX);
+}
+
+// Per-fragment escape hatch: parse.cjs extracts `<!-- docs-exempt: <reason> -->`
+// from the body into `fragment.docsExempt` (a non-empty reason string when the
+// marker was present and well-formed; `null` otherwise). A non-empty audit
+// trail is required — the lint defends in depth here too: even if a caller
+// constructs a fragment with `docsExempt: ''`, that does not count as exempt.
+function isExemptFragment(fragment) {
+  return typeof fragment.docsExempt === 'string' && fragment.docsExempt.trim().length > 0;
+}
+
+/**
+ * Pure verdict — no fs, no git.
+ *
+ * Malformed fragments fail closed: a triggering fragment with bad frontmatter
+ * cannot silently bypass docs enforcement. The changeset-required lint only
+ * checks fragment _presence_, not _validity_, so docs lint takes responsibility
+ * for any fragment it tries to consume.
+ *
+ * @param {object} args
+ * @param {string[]} args.changedFiles  - file paths changed in the PR
+ * @param {Array<{ path: string, type: string, body: string, docsExempt: string|null }>} args.fragments
+ *   - parsed records for well-formed `.changeset/*.md` files in `changedFiles`
+ * @param {Array<{ path: string, reason: string }>} [args.malformed]
+ *   - records for `.changeset/*.md` files that failed `parseFragment`
+ * @param {string[]} args.labels        - PR labels
+ * @returns {{ ok: boolean, reason: string, triggering: string[], malformed?: Array<{path:string,reason:string}> }}
+ */
+function evaluateLint({ changedFiles, fragments, labels, malformed = [] }) {
+  if (malformed.length > 0) {
+    return {
+      ok: false,
+      reason: LINT_REASON.FAIL_MALFORMED_FRAGMENT,
+      triggering: [],
+      malformed,
+    };
+  }
+
+  const triggering = fragments.filter((f) => TRIGGERING_TYPES.has(f.type));
+  const triggeringPaths = triggering.map((f) => f.path);
+
+  if (triggering.length === 0) {
+    return { ok: true, reason: LINT_REASON.OK_NO_TRIGGERING_FRAGMENTS, triggering: [] };
+  }
+
+  // Per-fragment exempt path: every triggering fragment must carry the marker.
+  // Partial exemption fails closed — one un-marked Added fragment still requires docs.
+  if (triggering.every(isExemptFragment)) {
+    return { ok: true, reason: LINT_REASON.OK_FRAGMENTS_EXEMPT, triggering: triggeringPaths };
+  }
+
+  if (labels.includes(OPT_OUT_LABEL)) {
+    return { ok: true, reason: LINT_REASON.OK_OPT_OUT_LABEL, triggering: triggeringPaths };
+  }
+
+  if (changedFiles.some(isDocsFile)) {
+    return { ok: true, reason: LINT_REASON.OK_DOCS_UPDATED, triggering: triggeringPaths };
+  }
+
+  return { ok: false, reason: LINT_REASON.FAIL_DOCS_MISSING, triggering: triggeringPaths };
+}
+
+function readFragmentsFromDisk(changedFiles, rootDir) {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const fragments = [];
+  const malformed = [];
+  for (const rel of changedFiles) {
+    if (!isFragmentPath(rel)) continue;
+    const abs = path.join(rootDir, rel);
+    if (!fs.existsSync(abs)) continue; // fragment deleted in PR — skip
+    let src;
+    try {
+      src = fs.readFileSync(abs, 'utf8');
+    } catch (e) {
+      malformed.push({ path: rel, reason: 'read_error', detail: e.code || e.message });
+      continue;
+    }
+    const parsed = parseFragment(src);
+    if (!parsed.ok) {
+      malformed.push({ path: rel, reason: parsed.reason, detail: parsed.detail || null });
+      continue;
+    }
+    fragments.push({
+      path: rel,
+      type: parsed.fragment.type,
+      body: parsed.fragment.body,
+      docsExempt: parsed.fragment.docsExempt,
+    });
+  }
+  return { fragments, malformed };
+}
+
+function main() {
+  const fs = require('node:fs');
+  const cp = require('node:child_process');
+  const path = require('node:path');
+
+  const rootDir = path.join(__dirname, '..');
+
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  let labels = [];
+  if (eventPath && fs.existsSync(eventPath)) {
+    try {
+      const event = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
+      labels = (event.pull_request?.labels || []).map((l) => l.name);
+    } catch { /* fall through */ }
+  }
+
+  const base = process.env.GITHUB_BASE_REF || 'main';
+  let changedFiles = [];
+  try {
+    // execFileSync with argv — no shell, so a malicious GITHUB_BASE_REF
+    // cannot inject shell syntax. Git's own ref-name validator rejects
+    // any metacharacters it would otherwise interpret.
+    const out = cp.execFileSync(
+      'git',
+      ['diff', '--name-only', `origin/${base}...HEAD`],
+      { encoding: 'utf8', cwd: rootDir },
+    );
+    changedFiles = out.split('\n').filter(Boolean);
+  } catch (e) {
+    process.stderr.write(`could not compute diff: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  const { fragments, malformed } = readFragmentsFromDisk(changedFiles, rootDir);
+  const verdict = evaluateLint({ changedFiles, fragments, labels, malformed });
+
+  if (process.argv.includes('--json')) {
+    process.stdout.write(
+      JSON.stringify({ ...verdict, changedFiles, fragments, malformed, labels }, null, 2) + '\n',
+    );
+  } else if (verdict.ok) {
+    process.stdout.write(`ok docs-lint: ${verdict.reason}\n`);
+  } else if (verdict.reason === LINT_REASON.FAIL_MALFORMED_FRAGMENT) {
+    process.stderr.write(`\nERROR docs-lint: ${verdict.reason}\n`);
+    process.stderr.write(
+      `${malformed.length} changeset fragment(s) failed to parse — docs lint cannot consume them:\n`,
+    );
+    for (const m of malformed) {
+      process.stderr.write(`  ${m.path}  (reason: ${m.reason}${m.detail ? `, detail: ${m.detail}` : ''})\n`);
+    }
+    process.stderr.write(
+      `\nFix the fragment frontmatter (\`type:\` + \`pr:\`) before this PR can pass.\n`,
+    );
+  } else {
+    process.stderr.write(`\nERROR docs-lint: ${verdict.reason}\n`);
+    process.stderr.write(
+      `${verdict.triggering.length} changeset fragment(s) require documentation updates:\n`,
+    );
+    for (const f of fragments.filter((f) => TRIGGERING_TYPES.has(f.type))) {
+      process.stderr.write(`  ${f.path}  (type: ${f.type})\n`);
+    }
+    process.stderr.write(`\nNo files under docs/ were modified in this PR.\n\n`);
+    process.stderr.write(
+      `Update the relevant docs/ file(s), or add the \`${OPT_OUT_LABEL}\` label if this change\n`,
+    );
+    process.stderr.write(
+      `is genuinely internal-only (infrastructure, refactor, test-only). Per-fragment\n`,
+    );
+    process.stderr.write(
+      `exemption via \`<!-- docs-exempt: <reason> -->\` inside the fragment body also works.\n`,
+    );
+  }
+  process.exit(verdict.ok ? 0 : 1);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  evaluateLint,
+  readFragmentsFromDisk,
+  LINT_REASON,
+  OPT_OUT_LABEL,
+  TRIGGERING_TYPES,
+  FRAGMENT_ERROR,
+  isFragmentPath,
+  isDocsFile,
+  isExemptFragment,
+};

package/scripts/lint-no-source-grep-extras.cjs

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * Extended detector for the no-source-grep rule (#2982).
+ *
+ * The base lint (scripts/lint-no-source-grep.cjs) only catches the
+ * direct-chain form: readFileSync(...).includes(...). The much more common
+ * var-binding form escapes it:
+ *
+ *   const src = fs.readFileSync(p, 'utf8');
+ *   // ... 50 lines later ...
+ *   assert.ok(src.includes('foo'));   // ← still source-grep, lint missed it
+ *
+ * This module exposes pure detectors that scan source text and return
+ * structured violation records. The CLI wrapper (in the base lint) calls
+ * these for each test file.
+ *
+ * Tests assert on the typed VIOLATION enum codes, not on prose messages.
+ */
+
+const VIOLATION = Object.freeze({
+  VAR_FROM_READFILE_USED_IN_TEXT_MATCH: 'var_from_readfile_used_in_text_match',
+  WRAPPED_ASSERT_OK_MATCH: 'wrapped_assert_ok_match',
+});
+
+const TEXT_MATCH_METHODS = ['includes', 'startsWith', 'endsWith', 'match', 'search'];
+
+/**
+ * Single-pass scanner. Tracks variables bound from a readFileSync call,
+ * then flags any subsequent <var>.<method>( use where method is one of
+ * TEXT_MATCH_METHODS.
+ */
+function detectVarBindingViolations(src) {
+  // Pass 1: collect variables bound from readFileSync.
+  // Matches:   const|let|var <name> = [fs.]readFileSync(
+  const bindRe = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:[A-Za-z_$][\w$.]*\.)?readFileSync\s*\(/g;
+  const boundVars = new Set();
+  let m;
+  while ((m = bindRe.exec(src)) !== null) {
+    boundVars.add(m[1]);
+  }
+  if (boundVars.size === 0) return [];
+
+  // Pass 2: find <var>.<method>( on any bound var.
+  const findings = [];
+  // Build a regex alternation from the bound var names.
+  const alt = [...boundVars].map((v) => v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+  const useRe = new RegExp(
+    `\\b(${alt})\\s*\\.\\s*(${TEXT_MATCH_METHODS.join('|')})\\s*\\(`,
+    'g',
+  );
+  while ((m = useRe.exec(src)) !== null) {
+    findings.push({
+      kind: VIOLATION.VAR_FROM_READFILE_USED_IN_TEXT_MATCH,
+      variable: m[1],
+      method: m[2],
+    });
+  }
+  return findings;
+}
+
+/**
+ * Detects assert.ok(<expr>.match(/.../)) and assert.ok(<expr>.match(<expr>))
+ * which is the same anti-pattern as assert.match but escapes the simpler
+ * regex used by the base lint.
+ */
+function detectWrappedAssertOkMatch(src) {
+  const re = /assert\.ok\s*\(\s*[A-Za-z_$][\w$.]*\.match\s*\(/g;
+  const findings = [];
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    findings.push({ kind: VIOLATION.WRAPPED_ASSERT_OK_MATCH });
+  }
+  return findings;
+}
+
+function detectAll(src) {
+  return [...detectVarBindingViolations(src), ...detectWrappedAssertOkMatch(src)];
+}
+
+module.exports = { detectVarBindingViolations, detectWrappedAssertOkMatch, detectAll, VIOLATION };

package/scripts/lint-no-source-grep.cjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * lint-no-source-grep.cjs
+ *
+ * Enforces the "no source-grep tests" rule:
+ *   Tests must NOT read source-code .cjs files with readFileSync to assert string
+ *   presence. That pattern (source-grep theater) proves a literal exists in source,
+ *   not that the runtime behavior is correct.
+ *
+ * ALLOWED:
+ *   - require('../get-shit-done/bin/lib/foo.cjs')  -- runs the module, not text inspection
+ *   - readFileSync on .md / .json / .txt files     -- product-content or config output
+ *   - Files annotated: // allow-test-rule: <reason>
+ *
+ * DISALLOWED (without allow-test-rule):
+ *   - readFileSync where the path argument ends in a .cjs filename literal
+ *   - A path constant (e.g. CONFIG_PATH) assigned to a .cjs lib file, used in readFileSync
+ *
+ * Exit 0 = clean. Exit 1 = violations found (with diagnostics).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const TESTS_DIR = path.join(__dirname, '..', 'tests');
+const ALLOW_ANNOTATION = /\/\/\s*allow-test-rule:\s*\S/;
+
+// Matches constant definitions that hold a .cjs path in a SOURCE directory.
+// Requires a source-dir indicator ('bin', 'lib', 'get-shit-done') to avoid
+// flagging temp files like path.join(tmpDir, 'example.cjs').
+//   const CONFIG_PATH = path.join(__dirname, '..', 'get-shit-done', 'bin', 'lib', 'config-schema.cjs');
+const CJS_PATH_CONST_RE = /(?:const|let|var)\s+(\w+)\s*=\s*path\.join\s*\([^)]*(?:'bin'|"bin"|'lib'|"lib"|'get-shit-done'|"get-shit-done")[^)]*['"][^'"]*\.cjs['"]/gm;
+
+// Matches readFileSync with a named variable as first arg
+const READ_WITH_CONST_RE = /readFileSync\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,/gm;
+
+// Matches readFileSync with an inline path.join(.cjs) as first arg
+const READ_WITH_INLINE_CJS_RE = /readFileSync\s*\([^,)]*path\.join\s*\([^)]*(?:'bin'|"bin"|'lib'|"lib"|'get-shit-done'|"get-shit-done")[^)]*['"][^'"]*\.cjs['"]/;
+
+/**
+ * #2962-class violations: raw text matching against process output or file
+ * content. The rule from CONTRIBUTING.md "Prohibited: Raw Text Matching on
+ * Test Outputs": tests assert on typed structured fields, never on rendered
+ * text. Patterns below are the obvious anti-patterns; subtler hidden forms
+ * (e.g. wrapping the same logic in a parser function) are still forbidden
+ * by the prose rule but cannot be detected lexically without an AST.
+ */
+const RAW_MATCH_PATTERNS = [
+  {
+    re: /assert\.(?:match|doesNotMatch)\s*\(\s*[A-Za-z_$][A-Za-z0-9_$]*\.(?:stdout|stderr)\b/,
+    label: 'assert.match/doesNotMatch on .stdout/.stderr (emit --json from the SUT and assert on typed fields)',
+  },
+  {
+    re: /\.(?:stdout|stderr)\.(?:includes|startsWith|endsWith)\s*\(/,
+    label: '.stdout/.stderr substring match (emit --json and assert on typed fields)',
+  },
+  {
+    re: /readFileSync\s*\([^)]*\)\s*\.(?:includes|startsWith|endsWith)\s*\(/,
+    label: 'readFileSync(...).<includes|startsWith|endsWith> (expose an IR from production code; assert on its fields)',
+  },
+];
+
+function setFromMatches(content, re) {
+  const found = new Set();
+  let m;
+  const cloned = new RegExp(re.source, re.flags);
+  while ((m = cloned.exec(content)) !== null) found.add(m[1]);
+  return found;
+}
+
+function check(filepath) {
+  const content = fs.readFileSync(filepath, 'utf-8');
+  const rel = path.relative(path.join(__dirname, '..'), filepath);
+
+  if (ALLOW_ANNOTATION.test(content)) return null;
+
+  const violations = [];
+
+  // Pattern A: readFileSync(path.join(..., 'foo.cjs'), ...)
+  if (READ_WITH_INLINE_CJS_RE.test(content)) {
+    violations.push({
+      reason: 'readFileSync with inline .cjs path literal',
+      fix: 'Replace with runGsdTools() behavioral test, or add // allow-test-rule: <reason>',
+    });
+  }
+
+  // Pattern B: const FOO_PATH = path.join(..., 'foo.cjs')  +  readFileSync(FOO_PATH, ...)
+  const cjsConsts = setFromMatches(content, CJS_PATH_CONST_RE);
+  if (cjsConsts.size > 0) {
+    const readConsts = setFromMatches(content, READ_WITH_CONST_RE);
+    const overlap = [...cjsConsts].filter(c => readConsts.has(c));
+    if (overlap.length > 0) {
+      violations.push({
+        reason: `source .cjs path constant(s) used in readFileSync: ${overlap.join(', ')}`,
+        fix: 'Replace with runGsdTools() behavioral test, or add // allow-test-rule: <reason>',
+      });
+    }
+  }
+
+  // Patterns C..E: raw text matching against process output or file content.
+  // See CONTRIBUTING.md "Prohibited: Raw Text Matching on Test Outputs".
+  for (const { re, label } of RAW_MATCH_PATTERNS) {
+    if (re.test(content)) {
+      violations.push({
+        reason: label,
+        fix: 'Expose typed IR from production code; assert on structured fields. Or add // allow-test-rule: <reason>',
+      });
+    }
+  }
+
+  // Patterns F..G (#2982): var-binding readFileSync().<text-method>() and
+  // assert.ok(<expr>.match(...)). These escape the simpler patterns above
+  // because the bind and the use are on different lines or wrapped.
+  const extras = require('./lint-no-source-grep-extras.cjs');
+  const varBindFindings = extras.detectVarBindingViolations(content);
+  if (varBindFindings.length > 0) {
+    const samples = varBindFindings.slice(0, 3)
+      .map((f) => `${f.variable}.${f.method}()`)
+      .join(', ');
+    violations.push({
+      reason: `readFileSync-bound variable used in text-match method: ${samples}${varBindFindings.length > 3 ? `, …+${varBindFindings.length - 3} more` : ''}`,
+      fix: 'Expose typed IR; assert on structured fields. Or // allow-test-rule: <reason>',
+    });
+  }
+  const wrappedFindings = extras.detectWrappedAssertOkMatch(content);
+  if (wrappedFindings.length > 0) {
+    violations.push({
+      reason: `assert.ok(<expr>.match(...)) — escapes assert.match rule (${wrappedFindings.length} occurrence${wrappedFindings.length > 1 ? 's' : ''})`,
+      fix: 'Use assert.equal on a typed field, not regex match on text. Or // allow-test-rule: <reason>',
+    });
+  }
+
+  if (violations.length === 0) return null;
+  return { file: rel, violations };
+}
+
+function findTestFiles(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findTestFiles(full));
+    } else if (entry.name.endsWith('.test.cjs')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+const testFiles = findTestFiles(TESTS_DIR);
+
+const violations = testFiles.map(check).filter(Boolean);
+
+if (violations.length === 0) {
+  console.log(`ok lint-no-source-grep: ${testFiles.length} test files checked, 0 violations`);
+  process.exit(0);
+}
+
+const totalIssues = violations.reduce((n, v) => n + v.violations.length, 0);
+process.stderr.write(`\nERROR lint-no-source-grep: ${totalIssues} violation(s) across ${violations.length} file(s)\n\n`);
+for (const f of violations) {
+  process.stderr.write(`  ${f.file}\n`);
+  for (const v of f.violations) {
+    process.stderr.write(`    Problem : ${v.reason}\n`);
+    process.stderr.write(`    Fix     : ${v.fix}\n`);
+  }
+  process.stderr.write('\n');
+}
+process.stderr.write('See CONTRIBUTING.md "Prohibited: Source-Grep Tests" and\n');
+process.stderr.write('"Prohibited: Raw Text Matching on Test Outputs" for guidance.\n');
+process.stderr.write('Structural tests that legitimately read source files: add // allow-test-rule: <reason>\n\n');
+process.exit(1);