@opengsd/get-shit-done-redux 1.0.0

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);

package/scripts/lint-pr-check-project-dir.cjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+const DEFAULT_RELATIVE_FILES = [
+  '.github/workflows/test.yml',
+  '.github/workflows/pr-template-format.yml',
+  '.github/workflows/changeset-required.yml',
+  'scripts/lint-no-source-grep.cjs',
+  'scripts/lint-command-contract.cjs',
+  'scripts/lint-skill-deps.cjs',
+  'scripts/lint-descriptions.cjs',
+  'scripts/lint-shell-command-projection-drift.cjs',
+  'scripts/pr-template-policy.cjs',
+  'scripts/changeset/lint.cjs',
+];
+
+function defaultFiles(rootDir = ROOT) {
+  return DEFAULT_RELATIVE_FILES
+    .map((file) => path.join(rootDir, file))
+    .filter((file) => fs.existsSync(file));
+}
+
+function findForbiddenCwd(content, file = '<inline>') {
+  const findings = [];
+  const lines = content.split(/\r?\n/);
+
+  lines.forEach((line, index) => {
+    const pattern = /\bcwd\b/g;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      findings.push({
+        file,
+        line: index + 1,
+        column: match.index + 1,
+        source: line.trim(),
+      });
+    }
+  });
+
+  return findings;
+}
+
+function checkFiles(files, { rootDir = ROOT } = {}) {
+  const findings = [];
+  for (const file of files) {
+    const content = fs.readFileSync(file, 'utf8');
+    const rel = path.relative(rootDir, file);
+    findings.push(...findForbiddenCwd(content, rel));
+  }
+  return findings;
+}
+
+function formatFindings(findings) {
+  const lines = [
+    `ERROR lint-pr-check-project-dir: ${findings.length} forbidden cwd reference(s) found`,
+    '',
+    'PR checkers must use projectDir for project roots; cwd is forbidden in this layer.',
+    '',
+  ];
+
+  for (const finding of findings) {
+    lines.push(`  ${finding.file}:${finding.line}:${finding.column}`);
+    lines.push(`    ${finding.source}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const files = argv.length > 0 ? argv.map((file) => path.resolve(file)) : defaultFiles();
+  const findings = checkFiles(files);
+
+  if (findings.length === 0) {
+    console.log(`ok lint-pr-check-project-dir: ${files.length} PR check files checked`);
+    return 0;
+  }
+
+  process.stderr.write(formatFindings(findings));
+  return 1;
+}
+
+if (require.main === module) {
+  process.exit(main());
+}
+
+module.exports = {
+  DEFAULT_RELATIVE_FILES,
+  checkFiles,
+  defaultFiles,
+  findForbiddenCwd,
+  formatFindings,
+  main,
+};