@skill-graph/cli 0.5.7 → 0.5.8

package/scripts/build-status-doc.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * Generate `docs/status.generated.md` — a single-source-of-truth status
+ * snapshot that pulls live values from package.json, the schema, the
+ * generated manifest, and the deterministic check scripts.
+ *
+ * The intent is to make the project's trust surface auditable from one URL:
+ * a reader can see, without running any code, what the current package
+ * version, schema version, skill count, and check states are.
+ *
+ * Usage:
+ *   node scripts/build-status-doc.js               # write docs/status.generated.md
+ *   node scripts/build-status-doc.js --check       # print summary, exit non-zero on drift
+ *   node scripts/build-status-doc.js --stdout      # print to stdout, do not write file
+ *   node scripts/build-status-doc.js --no-checks   # skip check execution (just version + count)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const OUTPUT_PATH = path.join(REPO_ROOT, 'docs', 'status.generated.md');
+
+function readJson(relPath) {
+  return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, relPath), 'utf8'));
+}
+
+function runCheck(scriptRelPath, label) {
+  const t0 = Date.now();
+  const r = spawnSync('node', [scriptRelPath], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+    timeout: 60_000,
+  });
+  const duration_ms = Date.now() - t0;
+  if (r.error) {
+    return { label, status: 'ERROR', duration_ms, detail: r.error.message };
+  }
+  const tail = (r.stdout + r.stderr).trim().split('\n').slice(-1)[0] || '';
+  return {
+    label,
+    status: r.status === 0 ? 'PASS' : 'FAIL',
+    exit_code: r.status,
+    duration_ms,
+    detail: tail.slice(0, 200),
+  };
+}
+
+function readSchemaVersion() {
+  const schema = readJson('schemas/skill.schema.json');
+  const sv = schema?.properties?.schema_version;
+  if (typeof sv?.const === 'number') return sv.const;
+  if (Array.isArray(sv?.oneOf)) {
+    for (const b of sv.oneOf) if (typeof b.const === 'number') return b.const;
+  }
+  return 'unknown';
+}
+
+function readSkillCount() {
+  const manifestPath = path.join(REPO_ROOT, 'skills.manifest.json');
+  if (!fs.existsSync(manifestPath)) return null;
+  const m = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  return Array.isArray(m.skills) ? m.skills.length : null;
+}
+
+function readMirrorStatus() {
+  const adrPath = path.join(REPO_ROOT, 'docs', 'adr', '0009-sibling-repo-deprecation.md');
+  if (!fs.existsSync(adrPath)) return 'unknown';
+  return 'docs-only mirrors per ADR 0009 (2026-05-18)';
+}
+
+function renderMarkdown(state) {
+  const { pkg, schema_version, skill_count, checks, generated_at, mirror_status } = state;
+  const checkRow = c => {
+    const badge = c.status === 'PASS' ? '✅ PASS' : c.status === 'SKIP' ? '⏭️  SKIP' : '❌ ' + c.status;
+    const detail = c.detail ? c.detail.replace(/\|/g, '\\|') : '';
+    return `| ${c.label} | ${badge} | ${c.duration_ms ?? '—'} ms | ${detail} |`;
+  };
+
+  return `# Skill Graph — Generated Status
+
+> **Generated:** ${generated_at}
+> **Generator:** \`node scripts/build-status-doc.js\` (regenerate; never hand-edit)
+>
+> This file is the single-source-of-truth status snapshot for the project's
+> trust surface. Each value below is pulled from a deterministic origin:
+> \`package.json\`, \`schemas/skill.schema.json\`, the generated manifest, ADR
+> 0009, and the live exit code of each check script.
+
+## Identity
+
+| Field | Value | Source |
+|---|---|---|
+| Package name | \`${pkg.name}\` | \`package.json\` |
+| Package version | \`${pkg.version}\` | \`package.json\` |
+| Node engine | \`${pkg.engines?.node ?? '—'}\` | \`package.json\` |
+| Active schema version | \`${schema_version}\` | \`schemas/skill.schema.json\` |
+| Skill count (manifest) | \`${skill_count ?? '—'}\` | \`skills.manifest.json\` |
+| Mirror status | ${mirror_status} | \`docs/adr/0009-sibling-repo-deprecation.md\` |
+
+## Checks
+
+| Check | Status | Duration | Last line |
+|---|---|---|---|
+${checks.map(checkRow).join('\n')}
+
+## How to refresh
+
+\`\`\`bash
+node scripts/build-status-doc.js
+\`\`\`
+
+\`docs/status.generated.md\` is regenerated and overwritten each run. CI
+should commit the regenerated file alongside any code that affects the
+underlying values (package version bump, schema bump, new lint check,
+etc.).
+
+## What this replaces
+
+- Hand-maintained "Latest release" lines in README hero sections (drifted three minor versions in Phase 1).
+- Ad-hoc "skill count" claims scattered across docs (drifted from 137 → 141 → 145 in Phase 1 alone).
+- Manual "we run these checks" lists in CONTRIBUTING.
+
+The reader is now one URL away from the truth.
+`;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const opts = {
+    check: argv.includes('--check'),
+    stdout: argv.includes('--stdout'),
+    skipChecks: argv.includes('--no-checks'),
+  };
+
+  const pkg = readJson('package.json');
+  const schema_version = readSchemaVersion();
+  const skill_count = readSkillCount();
+  const mirror_status = readMirrorStatus();
+  const generated_at = new Date().toISOString();
+
+  const checks = opts.skipChecks ? [] : [
+    runCheck('scripts/check-markdown-links.js', 'check-markdown-links'),
+    runCheck('scripts/check-protocol-consistency.js', 'check-protocol-consistency'),
+    runCheck('scripts/check-doc-drift.js', 'check-doc-drift'),
+    runCheck('scripts/check-mirror-freeze.js', 'check-mirror-freeze'),
+  ];
+
+  const state = { pkg, schema_version, skill_count, mirror_status, generated_at, checks };
+  const markdown = renderMarkdown(state);
+
+  if (opts.stdout) {
+    process.stdout.write(markdown);
+    process.exit(0);
+  }
+
+  fs.writeFileSync(OUTPUT_PATH, markdown);
+
+  const failed = checks.filter(c => c.status !== 'PASS' && c.status !== 'SKIP');
+  if (opts.check && failed.length > 0) {
+    process.stderr.write(
+      `FAIL build-status-doc: ${failed.length} check(s) not passing — see docs/status.generated.md\n`
+    );
+    process.exit(1);
+  }
+
+  process.stdout.write(
+    `OK   wrote ${path.relative(REPO_ROOT, OUTPUT_PATH)} (${pkg.name}@${pkg.version}, schema v${schema_version}, ${skill_count ?? '?'} skills, ${checks.length} checks)\n`
+  );
+}
+
+module.exports = { readSchemaVersion, readSkillCount, renderMarkdown, runCheck };
+
+if (require.main === module) main();

package/scripts/check-doc-drift.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * Schema-version drift sentinel for documentation.
+ *
+ * Reads the active schema_version from schemas/skill.schema.json and scans
+ * active .md docs for stale references like `schema_version: 4`, `v4 today`,
+ * `equals \`5\``, and similar patterns that would teach old contracts.
+ *
+ * Allowlist:
+ *   - Files under any `_archived/` segment (historical snapshots)
+ *   - Files under `docs/migrations/` (intentionally cite multiple versions)
+ *   - Files matching `CHANGELOG.md` at any depth (release notes cite versions)
+ *   - Files under `examples/` (test fixtures and sample skills intentionally
+ *     test multiple schema versions and historical exports)
+ *   - Filenames containing `migration` or `compatibility` (cross-version docs)
+ *
+ * Each finding includes file:line and the offending fragment.
+ *
+ * Exit codes:
+ *   0  — no drift in active docs
+ *   1  — at least one drift hit in an active doc
+ *
+ * Flags:
+ *   --json          Emit findings as JSON
+ *   --quiet         Only print failure summary line
+ *   --include-warn  Report warning-class hits (e.g. raw `v4`, `v5` mentions)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { workspaceRoot } = require('./lib/roots');
+
+const REPO_ROOT = workspaceRoot();
+const SKILL_SCHEMA_PATH = path.join(REPO_ROOT, 'schemas', 'skill.schema.json');
+const IGNORED_DIRS = new Set(['.git', 'node_modules', '.artifacts', '.roundtable', 'marketplace']);
+
+function readActiveSchemaVersion() {
+  const schema = JSON.parse(fs.readFileSync(SKILL_SCHEMA_PATH, 'utf8'));
+  const sv = schema?.properties?.schema_version;
+  if (!sv) throw new Error(`Cannot resolve schema_version constraint in ${SKILL_SCHEMA_PATH}`);
+  // schema may be `{ const: N }` or `{ oneOf: [{ const: N }, { const: "N" }] }`
+  if (typeof sv.const === 'number') return sv.const;
+  if (Array.isArray(sv.oneOf)) {
+    for (const branch of sv.oneOf) {
+      if (typeof branch.const === 'number') return branch.const;
+    }
+  }
+  throw new Error(`Unsupported schema_version shape in ${SKILL_SCHEMA_PATH}`);
+}
+
+function isAllowlisted(absPath) {
+  const rel = path.relative(REPO_ROOT, absPath).split(path.sep);
+  if (rel.some(seg => seg === '_archived')) return true;
+  if (rel[0] === 'docs' && rel[1] === 'migrations') return true;
+  if (rel[0] === 'examples') return true;
+  if (path.basename(absPath) === 'CHANGELOG.md') return true;
+  const base = path.basename(absPath).toLowerCase();
+  if (base.includes('migration') || base.includes('compatibility')) return true;
+  return false;
+}
+
+function collectMarkdownFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') && IGNORED_DIRS.has(entry.name)) continue;
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!IGNORED_DIRS.has(entry.name)) collectMarkdownFiles(abs, out);
+      continue;
+    }
+    if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) out.push(abs);
+  }
+  return out;
+}
+
+function buildPatterns(activeVersion) {
+  // Patterns that name an explicit non-current version.
+  const errorPatterns = [];
+  for (let v = 1; v < activeVersion; v++) {
+    errorPatterns.push({
+      kind: 'schema_version',
+      regex: new RegExp(String.raw`\bschema_version:\s*"?${v}"?\b`),
+      version: v,
+    });
+    errorPatterns.push({
+      kind: 'schema_version-equals',
+      regex: new RegExp(String.raw`equals\s*\`${v}\``),
+      version: v,
+    });
+    errorPatterns.push({
+      kind: 'schema_version-tracks-latest',
+      regex: new RegExp(String.raw`tracks\s+latest\s*\(v${v}\s+today\)`, 'i'),
+      version: v,
+    });
+  }
+  // Loose patterns reported only with --include-warn.
+  const warnPatterns = [];
+  for (let v = 1; v < activeVersion; v++) {
+    warnPatterns.push({
+      kind: 'bare-version-token',
+      regex: new RegExp(String.raw`\bv${v}\b(?!\s*-?to-?)`),
+      version: v,
+    });
+  }
+  return { errorPatterns, warnPatterns };
+}
+
+// Heading-level allowlist: when inside a migration section (e.g. `## v4 -> v5`
+// or `### v5 → v6 (historical)`), lines are treated as migration context and
+// not reported. The section ends at the next heading at the same level or
+// shallower.
+function buildMigrationSectionMask(lines) {
+  const mask = new Array(lines.length).fill(false);
+  let inMigration = false;
+  let migrationDepth = 0;
+  const migrationHeadingRe = /^(#{2,6})\s+.*\bv\d+\s*(?:->|→|to)\s*v\d+\b/i;
+  const headingRe = /^(#{1,6})\s+/;
+
+  lines.forEach((line, idx) => {
+    const mh = line.match(migrationHeadingRe);
+    if (mh) {
+      inMigration = true;
+      migrationDepth = mh[1].length;
+      return;
+    }
+    if (inMigration) {
+      const hh = line.match(headingRe);
+      if (hh && hh[1].length <= migrationDepth) {
+        inMigration = false;
+      }
+    }
+    mask[idx] = inMigration;
+  });
+  return mask;
+}
+
+function scanFile(absPath, patterns) {
+  const text = fs.readFileSync(absPath, 'utf8');
+  const lines = text.split(/\r?\n/);
+  const migrationMask = buildMigrationSectionMask(lines);
+  const hits = [];
+  lines.forEach((line, idx) => {
+    if (migrationMask[idx]) return;
+    for (const p of patterns) {
+      if (p.regex.test(line)) {
+        hits.push({
+          file: path.relative(REPO_ROOT, absPath),
+          line: idx + 1,
+          kind: p.kind,
+          version: p.version,
+          snippet: line.trim().slice(0, 240),
+        });
+      }
+    }
+  });
+  return hits;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const opts = {
+    json: argv.includes('--json'),
+    quiet: argv.includes('--quiet'),
+    includeWarn: argv.includes('--include-warn'),
+  };
+
+  const activeVersion = readActiveSchemaVersion();
+  const { errorPatterns, warnPatterns } = buildPatterns(activeVersion);
+
+  const files = collectMarkdownFiles(REPO_ROOT)
+    .filter(f => !isAllowlisted(f))
+    .sort((a, b) => a.localeCompare(b));
+
+  const errorHits = [];
+  const warnHits = [];
+  for (const file of files) {
+    errorHits.push(...scanFile(file, errorPatterns));
+    if (opts.includeWarn) warnHits.push(...scanFile(file, warnPatterns));
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({
+      active_schema_version: activeVersion,
+      files_scanned: files.length,
+      errors: errorHits,
+      warnings: warnHits,
+    }, null, 2) + '\n');
+    process.exit(errorHits.length > 0 ? 1 : 0);
+  }
+
+  if (!opts.quiet) {
+    if (warnHits.length > 0) {
+      for (const h of warnHits) {
+        process.stderr.write(`WARN ${h.file}:${h.line} [${h.kind}] ${h.snippet}\n`);
+      }
+    }
+    for (const h of errorHits) {
+      process.stderr.write(`${h.file}:${h.line} [${h.kind} v${h.version}] ${h.snippet}\n`);
+    }
+  }
+
+  if (errorHits.length > 0) {
+    process.stderr.write(`FAIL doc drift: ${errorHits.length} stale schema-version reference(s) in active docs (active v${activeVersion}). Allowlisted: _archived/, docs/migrations/, CHANGELOG.md.\n`);
+    process.exit(1);
+  }
+
+  const warnNote = opts.includeWarn && warnHits.length > 0
+    ? ` (${warnHits.length} warning(s) reported)`
+    : '';
+  process.stdout.write(`OK   doc drift sentinel: ${files.length} active doc(s) scanned against schema v${activeVersion}${warnNote}\n`);
+}
+
+module.exports = {
+  buildMigrationSectionMask,
+  buildPatterns,
+  collectMarkdownFiles,
+  isAllowlisted,
+  readActiveSchemaVersion,
+  scanFile,
+};
+
+if (require.main === module) main();

package/scripts/check-markdown-links.js

@@ -6,6 +6,15 @@
  * that GitHub will resolve from Markdown files. Paths are checked with
  * case-sensitive segment matching even on Windows so links do not pass locally
  * and 404 after push.
+ *
+ * Severity model:
+ *   - Active docs (default): broken links are errors and fail the build.
+ *   - Archived docs (under any `_archived/` segment): broken links are warnings
+ *     and DO NOT fail the build. Archived docs are historical snapshots; the
+ *     project's link guarantees apply to the active surface only.
+ *
+ * Override with --strict-archived to treat archived broken links as errors
+ * (useful when migrating an archive batch or auditing snapshot integrity).
  */
 
 'use strict';
@@ -17,6 +26,14 @@ const { workspaceRoot } = require('./lib/roots');
 const REPO_ROOT = workspaceRoot();
 const IGNORED_DIRS = new Set(['.git', 'node_modules', '.artifacts', '.roundtable']);
 
+// Lenient policy: any markdown file beneath a `_archived/` segment is treated
+// as a historical snapshot. Broken links inside such files become warnings
+// rather than build-failing errors.
+function isArchivedPath(absPath) {
+  const rel = path.relative(REPO_ROOT, absPath).split(path.sep);
+  return rel.some(segment => segment === '_archived');
+}
+
 function repoRelative(filePath) {
   return path.relative(REPO_ROOT, filePath).split(path.sep).join('/');
 }
@@ -174,18 +191,27 @@ function checkFile(filePath) {
 }
 
 function main() {
+  const flagArgs = process.argv.slice(2).filter(a => a.startsWith('--'));
+  const strictArchived = flagArgs.includes('--strict-archived');
   const args = process.argv.slice(2).filter(a => !a.startsWith('--'));
   const files = args.length > 0
     ? args.map(a => path.resolve(a)).filter(p => fs.existsSync(p) && p.toLowerCase().endsWith('.md'))
     : collectMarkdownFiles(REPO_ROOT).sort((a, b) => repoRelative(a).localeCompare(repoRelative(b)));
 
   const failures = [];
+  const warnings = [];
   for (const file of files) {
-    for (const error of checkFile(file)) {
-      failures.push({ file, ...error });
+    const archived = !strictArchived && isArchivedPath(file);
+    for (const issue of checkFile(file)) {
+      (archived ? warnings : failures).push({ file, ...issue });
     }
   }
 
+  for (const warning of warnings) {
+    process.stderr.write(
+      `WARN ${repoRelative(warning.file)}:${warning.line}: ${warning.message} (${warning.target}) [archived snapshot]\n`
+    );
+  }
   for (const failure of failures) {
     process.stderr.write(
       `${repoRelative(failure.file)}:${failure.line}: ${failure.message} (${failure.target})\n`
@@ -193,11 +219,14 @@ function main() {
   }
 
   if (failures.length > 0) {
-    process.stderr.write(`FAIL markdown links: ${failures.length} broken local link(s)\n`);
+    process.stderr.write(`FAIL markdown links: ${failures.length} broken local link(s) in active docs (${warnings.length} in _archived/ ignored — use --strict-archived to elevate)\n`);
     process.exit(1);
   }
 
-  process.stdout.write(`OK   markdown links (${files.length} file(s))\n`);
+  const suffix = warnings.length > 0
+    ? ` — ${warnings.length} archived-doc warning(s) ignored (use --strict-archived to elevate)`
+    : '';
+  process.stdout.write(`OK   markdown links (${files.length} file(s))${suffix}\n`);
 }
 
 module.exports = {
@@ -205,6 +234,7 @@ module.exports = {
   collectMarkdownFiles,
   existsCaseSensitive,
   extractInlineLinks,
+  isArchivedPath,
   slugifyHeading,
 };