@therocketcode/gsd-core 1.4.0

package/scripts/lint-skill-deps.cjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * lint-skill-deps.cjs
+ *
+ * Two checks:
+ *
+ * a) Frontmatter to body consistency:
+ *    For each commands/gsd/*.md, parse requires: and walk the body for
+ *    references to other GSD skills (pattern: /gsd:<stem> or gsd:<stem>).
+ *    Fail if a skill body references a skill not listed in requires:.
+ *
+ * b) Profile closure satisfaction:
+ *    Load PROFILES from install-profiles.cjs. For each non-full profile,
+ *    compute closure(profile.base) using the manifest. If any skill in
+ *    the closure references a skill NOT in the closure, fail.
+ *
+ * Usage:
+ *   node scripts/lint-skill-deps.cjs               # scans commands/gsd/
+ *   node scripts/lint-skill-deps.cjs --dir <path>  # scan a custom dir (testing)
+ *
+ * Exits 0 if all pass; exits 1 if any violation.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const PROFILES_MODULE = path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'install-profiles.cjs');
+const { PROFILES, loadSkillsManifest, resolveProfile } = require(PROFILES_MODULE);
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+let commandsDir = path.join(__dirname, '..', 'commands', 'gsd');
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--dir' && args[i + 1]) {
+    commandsDir = args[i + 1];
+    i++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Reference extraction from skill body
+// ---------------------------------------------------------------------------
+
+function extractBodyReferences(body) {
+  const refs = new Set();
+  const re = /(?:\/?)gsd:([a-z0-9_-]+)/g;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    refs.add(m[1]);
+  }
+  return refs;
+}
+
+function extractBody(content) {
+  const fmEnd = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/m);
+  if (!fmEnd) return content;
+  return content.slice(fmEnd[0].length);
+}
+
+// ---------------------------------------------------------------------------
+// Check a: frontmatter to body consistency
+// ---------------------------------------------------------------------------
+
+function checkFrontmatterBodyConsistency(manifest, allStems) {
+  const violations = [];
+
+  for (const [stem, declared] of manifest) {
+    if (stem.startsWith('_calls_agents_')) continue;
+    const filePath = path.join(commandsDir, stem + '.md');
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+    const body = extractBody(content);
+    const referenced = extractBodyReferences(body);
+    const declaredSet = new Set(declared);
+    for (const ref of referenced) {
+      if (ref === stem) continue;
+      if (!allStems.has(ref)) {
+        violations.push({
+          stem,
+          filePath,
+          undeclared: ref,
+          message: 'body references unknown skill gsd:' + ref,
+        });
+        continue;
+      }
+      if (!declaredSet.has(ref)) {
+        violations.push({
+          stem,
+          filePath,
+          undeclared: ref,
+          message: 'body references gsd:' + ref + ' but requires: does not list it',
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+// ---------------------------------------------------------------------------
+// Check b: profile closure satisfaction
+// ---------------------------------------------------------------------------
+
+function checkProfileClosure(manifest) {
+  const violations = [];
+
+  for (const profileName of Object.keys(PROFILES)) {
+    const base = PROFILES[profileName];
+    if (base === '*') continue;
+    const resolved = resolveProfile({ modes: [profileName], manifest });
+    if (resolved.skills === '*') continue;
+
+    const closure = resolved.skills;
+    for (const stem of closure) {
+      const deps = manifest.get(stem) || [];
+      for (const dep of deps) {
+        if (!closure.has(dep)) {
+          violations.push({
+            profile: profileName,
+            stem,
+            missingDep: dep,
+            message: 'profile "' + profileName + '" includes "' + stem + '" which requires "' + dep + '", but "' + dep + '" is not in the closure',
+          });
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const manifest = loadSkillsManifest(commandsDir);
+  const allStems = new Set(
+    [...manifest.keys()].filter((k) => !k.startsWith('_calls_agents_'))
+  );
+
+  const consistencyViolations = checkFrontmatterBodyConsistency(manifest, allStems);
+  const closureViolations = checkProfileClosure(manifest);
+
+  const totalViolations = consistencyViolations.length + closureViolations.length;
+
+  if (totalViolations === 0) {
+    const checked = manifest.size;
+    process.stdout.write('ok lint-skill-deps: ' + checked + ' skill(s) checked, 0 violations\n');
+    return 0;
+  }
+
+  process.stderr.write('\nERROR lint-skill-deps: ' + totalViolations + ' violation(s) found\n\n');
+
+  if (consistencyViolations.length > 0) {
+    process.stderr.write('Frontmatter to body consistency violations (' + consistencyViolations.length + '):\n\n');
+    for (const v of consistencyViolations) {
+      process.stderr.write('  ' + v.filePath + '\n');
+      process.stderr.write('    ' + v.message + '\n\n');
+    }
+    process.stderr.write('Fix: add missing deps to requires: in the skill frontmatter.\n\n');
+  }
+
+  if (closureViolations.length > 0) {
+    process.stderr.write('Profile closure violations (' + closureViolations.length + '):\n\n');
+    for (const v of closureViolations) {
+      process.stderr.write('  ' + v.message + '\n');
+    }
+    process.stderr.write('\nFix: add the missing skills to the profile base set in install-profiles.cjs.\n\n');
+  }
+
+  return 1;
+}
+
+runMain(main);

package/scripts/lint-test-file-count.allowlist.json

@@ -0,0 +1,135 @@
+{
+  "_doc": "Baseline of modules currently exceeding the 2-test-file limit. Each entry locks in TODAY's exact test filenames as the allowlisted set (identity ratchet). Adding a NEW test file to a capped module fails (novel). Removing one requires pruning this list (stale, ratchet-down). When a cluster drops to ≤ 2, remove its entry entirely. New entries require justification in PR description.",
+  "modules": {
+    "audit": {
+      "files": [
+        "audit-fix-command.test.cjs",
+        "bug-2659-audit-open-crash.test.cjs",
+        "bug-2836-audit-open-summary-uat-drift.test.cjs",
+        "bug-2911-audit-open-output-shape.test.cjs"
+      ],
+      "issue": "192"
+    },
+    "config": {
+      "files": [
+        "bug-2943-config-get-context-window-default.test.cjs",
+        "bug-321-config-defaults-clone-strategy.test.cjs",
+        "bug-3227-config-set-model-overrides.test.cjs",
+        "bug-442-config-dir-equals-in-path.test.cjs",
+        "config-field-docs.test.cjs",
+        "config-get-default.test.cjs",
+        "config-schema.property.test.cjs",
+        "config.test.cjs"
+      ],
+      "issue": "TBD"
+    },
+    "graphify": {
+      "files": [
+        "bug-622-graphify-optional-graph-html.test.cjs",
+        "graphify-auto-update.test.cjs",
+        "graphify-query.test.cjs",
+        "graphify-visualization.test.cjs",
+        "graphify.test.cjs"
+      ],
+      "issue": "622"
+    },
+    "intel": {
+      "files": [
+        "bug-2351-intel-kilo-layout.test.cjs",
+        "bug-3290-intel-updater-layout-block.test.cjs",
+        "intel.test.cjs"
+      ],
+      "issue": "TBD"
+    },
+    "milestone": {
+      "files": [
+        "bug-730-milestone-phase-details-scope.test.cjs",
+        "milestone-archive.test.cjs",
+        "milestone-helper.test.cjs",
+        "milestone-prefixed-convention.test.cjs",
+        "milestone-summary.test.cjs",
+        "milestone.test.cjs"
+      ],
+      "issue": "TBD"
+    },
+    "phase": {
+      "files": [
+        "bug-214-phase-researcher-write-truncation-contract.test.cjs",
+        "phase-dependency-levels.test.cjs",
+        "phase.test.cjs"
+      ],
+      "issue": "597"
+    },
+    "roadmap": {
+      "files": [
+        "bug-2661-roadmap-sync-parallel.test.cjs",
+        "bug-3128-roadmap-plan-count-slug-layout.test.cjs",
+        "bug-3599-roadmap-get-phase-project-code-prefix.test.cjs",
+        "enh-2447-roadmap-wave-deps.test.cjs",
+        "roadmap-mode-field.test.cjs",
+        "roadmap-phase-fallback.test.cjs",
+        "roadmap.test.cjs"
+      ],
+      "issue": "TBD"
+    },
+    "runtime-artifact-layout": {
+      "files": [
+        "runtime-artifact-layout-install-profiles.test.cjs",
+        "runtime-artifact-layout-surface.test.cjs",
+        "runtime-artifact-layout.test.cjs"
+      ],
+      "issue": "TBD"
+    },
+    "security": {
+      "files": [
+        "security-prompt-injection.test.cjs",
+        "security-scan.test.cjs",
+        "security.test.cjs"
+      ],
+      "issue": "TBD"
+    },
+    "state": {
+      "files": [
+        "bug-21-state-md-template-frontmatter.test.cjs",
+        "bug-2630-state-frontmatter-milestone-switch.test.cjs",
+        "bug-3127-state-begin-phase-idempotent.test.cjs",
+        "bug-3242-state-update-progress-trample.test.cjs",
+        "bug-3286-state-write-routing.test.cjs",
+        "bug-3454-state-dollar-backreference-growth.test.cjs",
+        "bug-397-state-preserve-executor-authored.test.cjs",
+        "state-acquirestatelock-non-eexist.test.cjs",
+        "state-prune.test.cjs",
+        "state.test.cjs"
+      ],
+      "issue": "180"
+    },
+    "verify": {
+      "files": [
+        "bug-2969-verify-reapply-patches.test.cjs",
+        "bug-2994-verify-reapply-patches-installed-path.test.cjs",
+        "bug-3381-verify-work-workstream.test.cjs",
+        "bug-3657-verify-reapply-patches-pristine-drift.test.cjs",
+        "verify-health.test.cjs",
+        "verify-mvp-uat.test.cjs",
+        "verify-npm-publish.test.cjs",
+        "verify-test-quality.test.cjs",
+        "verify-work-auto-transition.test.cjs",
+        "verify.test.cjs"
+      ],
+      "issue": "3767"
+    },
+    "install": {
+      "files": [
+        "bug-410-install-defaults-test-mode-guard.test.cjs",
+        "enh-776-install-gemini-hook-events.test.cjs",
+        "install-minimal-hooks.test.cjs",
+        "install-path-detection.test.cjs",
+        "install-regressions.test.cjs",
+        "install-runtime-artifacts.test.cjs",
+        "install-update-marker.test.cjs",
+        "install.test.cjs"
+      ],
+      "issue": "TBD"
+    }
+  }
+}

package/scripts/lint-test-file-count.cjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * lint-test-file-count.cjs — max 2 test files per production module.
+ *
+ * Scans sdk/src/query/, sdk/src/, gsd-core/bin/lib/, bin/ for production
+ * modules, then counts matching test files in tests/ and sdk/src (recursive). Cap is 2
+ * (primary + one integration). Over-limit clusters must be in the allowlist with the
+ * EXACT set of test filenames grandfathered (identity ratchet via allowlist-ratchet.cjs).
+ * Adding a new test file to a capped module is a novel offender; removing one requires
+ * pruning the allowlist entry (stale). --json emits structured output.
+ *
+ * Verdicts: OK_UNDER_LIMIT | OK_IN_ALLOWLIST | FAIL_EXCEEDS_LIMIT |
+ *           FAIL_NOVEL_FILES | FAIL_STALE_ALLOWLIST
+ */
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { assertWithinAllowlist } = require('./lib/allowlist-ratchet.cjs');
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.join(__dirname, '..');
+const PROD_DIRS = [
+  path.join(ROOT, 'sdk', 'src', 'query'),
+  path.join(ROOT, 'sdk', 'src'),
+  path.join(ROOT, 'gsd-core', 'bin', 'lib'),
+  path.join(ROOT, 'bin'),
+];
+const TEST_DIRS = [
+  path.join(ROOT, 'tests'),
+  path.join(ROOT, 'sdk', 'src'),
+];
+const ALLOWLIST_PATH = path.join(__dirname, 'lint-test-file-count.allowlist.json');
+const MAX_FILES = 2;
+
+const Verdict = Object.freeze({
+  OK_UNDER_LIMIT:       'OK_UNDER_LIMIT',
+  OK_IN_ALLOWLIST:      'OK_IN_ALLOWLIST',
+  FAIL_EXCEEDS_LIMIT:   'FAIL_EXCEEDS_LIMIT',
+  FAIL_NOVEL_FILES:     'FAIL_NOVEL_FILES',
+  FAIL_STALE_ALLOWLIST: 'FAIL_STALE_ALLOWLIST',
+});
+
+function isTestFile(name) {
+  return name.endsWith('.test.ts') || name.endsWith('.test.cjs');
+}
+
+function listFiles(dir, pred) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter(e => e.isFile() && pred(e.name))
+      .map(e => path.join(dir, e.name));
+  } catch (_) { return []; }
+}
+
+function findTestFilesRecursive(dir) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch (_) { return out; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...findTestFilesRecursive(full));
+    else if (isTestFile(e.name)) out.push(full);
+  }
+  return out;
+}
+
+function prodPrefix(filename) {
+  return filename.replace(/\.(cjs|ts|js)$/, '');
+}
+
+// Strip .test.{cjs,ts} and .integration.test.ts, then strip issue stamps.
+function testEffectivePrefix(testName) {
+  const bare = testName
+    .replace(/\.integration\.test\.(ts|cjs)$/, '')
+    .replace(/\.test\.(ts|cjs)$/, '');
+  const m = bare.match(/^(?:feat|bug|enh|fix)-\d+(?:-\d+)*-(.+)$/);
+  return m ? m[1] : bare;
+}
+
+function collectProdPrefixes() {
+  const map = new Map();
+  for (const dir of PROD_DIRS) {
+    for (const f of listFiles(dir, n =>
+      !isTestFile(n) &&
+      !/\.(generated|md|json)(\.|$)/.test(n) &&
+      /\.(ts|cjs|js)$/.test(n)
+    )) {
+      const prefix = prodPrefix(path.basename(f));
+      if (!map.has(prefix)) map.set(prefix, f);
+    }
+  }
+  return map;
+}
+
+function collectAllTestFiles() {
+  const seen = new Set();
+  const all = [];
+  for (const dir of TEST_DIRS) {
+    for (const f of findTestFilesRecursive(dir)) {
+      if (!seen.has(f)) { seen.add(f); all.push(f); }
+    }
+  }
+  return all;
+}
+
+function buildTestMap(prodPrefixes, allTestFiles) {
+  const map = new Map([...prodPrefixes.keys()].map(p => [p, []]));
+  for (const tf of allTestFiles) {
+    const ep = testEffectivePrefix(path.basename(tf));
+    for (const prefix of prodPrefixes.keys()) {
+      if (ep === prefix || ep.startsWith(prefix + '-')) {
+        map.get(prefix).push(tf);
+        break;
+      }
+    }
+  }
+  return map;
+}
+
+function loadAllowlist() {
+  try { return JSON.parse(fs.readFileSync(ALLOWLIST_PATH, 'utf-8')).modules || {}; }
+  catch (_) { return {}; }
+}
+
+/**
+ * Evaluate one module's test files against the allowlist.
+ *
+ * For modules under the default cap (≤ MAX_FILES): simple count check.
+ * For modules with an allowlist entry: identity check via assertWithinAllowlist.
+ *   - count now ≤ MAX_FILES → FAIL_STALE_ALLOWLIST (all known files are stale; prune entry)
+ *   - novel files (in current but not in known) → FAIL_NOVEL_FILES
+ *   - stale files (in known but not in current) → FAIL_STALE_ALLOWLIST
+ *   - exact match → OK_IN_ALLOWLIST
+ * For modules over the cap with no allowlist entry: FAIL_EXCEEDS_LIMIT.
+ *
+ * Returns { verdict, prefix, count, knownFiles, novel, stale, files }
+ */
+function evaluateLint({ prefix, testFiles, allowlist }) {
+  const count = testFiles.length;
+  const entry = allowlist[prefix];
+  const currentNames = testFiles.map(f => path.basename(f));
+
+  if (entry !== undefined) {
+    const knownFiles = Array.isArray(entry.files) ? entry.files : [];
+    // If the module is now at or under the default cap, the entire allowlist entry is
+    // stale and must be removed — this is a ratchet-DOWN failure, not a hint.
+    // All known files are stale (the whole entry can go).
+    if (count <= MAX_FILES) {
+      return {
+        verdict: Verdict.FAIL_STALE_ALLOWLIST,
+        prefix, count,
+        knownFiles,
+        novel: [],
+        stale: knownFiles.slice().sort(),
+        files: testFiles,
+      };
+    }
+    // Identity check via assertWithinAllowlist
+    const messages = [];
+    const { novel, stale } = assertWithinAllowlist({
+      label: prefix,
+      current: currentNames,
+      known: knownFiles,
+      fail: (msg) => messages.push(msg),
+      pruneHint: 'scripts/lint-test-file-count.allowlist.json',
+    });
+
+    if (novel.length > 0) {
+      return { verdict: Verdict.FAIL_NOVEL_FILES,     prefix, count, knownFiles, novel, stale, files: testFiles };
+    }
+    if (stale.length > 0) {
+      return { verdict: Verdict.FAIL_STALE_ALLOWLIST, prefix, count, knownFiles, novel, stale, files: testFiles };
+    }
+    return { verdict: Verdict.OK_IN_ALLOWLIST,        prefix, count, knownFiles, novel: [], stale: [], files: testFiles };
+  }
+
+  if (count <= MAX_FILES) {
+    return { verdict: Verdict.OK_UNDER_LIMIT,    prefix, count, knownFiles: null, novel: [], stale: [], files: testFiles };
+  }
+  return   { verdict: Verdict.FAIL_EXCEEDS_LIMIT, prefix, count, knownFiles: null, novel: [], stale: [], files: testFiles };
+}
+
+function run() {
+  const jsonMode = process.argv.includes('--json');
+  const prodPrefixes = collectProdPrefixes();
+  const allTestFiles = collectAllTestFiles();
+  const testMap      = buildTestMap(prodPrefixes, allTestFiles);
+  const allowlist    = loadAllowlist();
+
+  const results = [];
+  for (const [prefix, files] of testMap) {
+    if (files.length === 0) continue;
+    results.push(evaluateLint({ prefix, testFiles: files, allowlist }));
+  }
+
+  const failures = results.filter(r =>
+    r.verdict === Verdict.FAIL_EXCEEDS_LIMIT ||
+    r.verdict === Verdict.FAIL_NOVEL_FILES ||
+    r.verdict === Verdict.FAIL_STALE_ALLOWLIST);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: failures.length === 0, results, failures, hints: [] }, null, 2));
+    return failures.length > 0 ? 1 : 0;
+  }
+
+  if (failures.length === 0) {
+    const inAllowlist = results.filter(r => r.verdict === Verdict.OK_IN_ALLOWLIST).length;
+    console.log(`ok lint-test-file-count: ${results.length} module(s) checked, 0 failures` +
+      (inAllowlist > 0 ? `, ${inAllowlist} allowlisted` : ''));
+    return 0;
+  }
+
+  process.stderr.write(`\nERROR lint-test-file-count: ${failures.length} module(s) exceed the test-file limit\n\n`);
+  for (const f of failures) {
+    if (f.verdict === Verdict.FAIL_EXCEEDS_LIMIT) {
+      process.stderr.write(`  ${f.prefix}: ${f.count} files (limit ${MAX_FILES}) — not in allowlist\n`);
+      for (const tf of f.files) process.stderr.write(`    ${path.relative(ROOT, tf)}\n`);
+    } else if (f.verdict === Verdict.FAIL_NOVEL_FILES) {
+      process.stderr.write(`  ${f.prefix}: ${f.novel.length} NEW test file(s) not in allowlist\n`);
+      for (const n of f.novel) process.stderr.write(`    + ${n}\n`);
+    } else if (f.verdict === Verdict.FAIL_STALE_ALLOWLIST) {
+      if (f.count <= MAX_FILES) {
+        const staleList = f.stale.join(', ');
+        process.stderr.write(`  "${f.prefix}": now at ${f.count} file(s) (≤ ${MAX_FILES}) — remove its entry from the allowlist (stale: ${staleList})\n`);
+      } else {
+        process.stderr.write(`  ${f.prefix}: ${f.stale.length} allowlisted file(s) no longer present — prune allowlist\n`);
+        for (const s of f.stale) process.stderr.write(`    - ${s}\n`);
+      }
+    }
+  }
+  process.stderr.write('\nFix: consolidate test files per module (one primary + one integration).\n');
+  process.stderr.write('Or update scripts/lint-test-file-count.allowlist.json with PR justification.\n\n');
+  return 1;
+}
+
+module.exports = {
+  Verdict, evaluateLint, testEffectivePrefix, prodPrefix,
+  _collectProdPrefixes: collectProdPrefixes,
+  _collectAllTestFiles: collectAllTestFiles,
+  _buildTestMap: buildTestMap,
+  _loadAllowlist: loadAllowlist,
+};
+
+if (require.main === module) runMain(run);