@skill-graph/cli 0.5.6

package/scripts/backfill-schema-version.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/**
+ * backfill-schema-version.js — ensure every SKILL.md declares `schema_version`
+ *
+ * Walks a skill tree and reports any SKILL.md that is missing the
+ * `schema_version` key in its YAML frontmatter. Optionally writes the
+ * current version into missing files.
+ *
+ * This script exists because the v3 schema requires `schema_version`, but
+ * libraries that existed before v3 (or that drift over time) may have
+ * SKILL.md files missing the field. Audit reports need a deterministic
+ * way to measure the gap and a safe way to close it.
+ *
+ * Usage:
+ *   node scripts/backfill-schema-version.js                     # dry-run, default roots
+ *   node scripts/backfill-schema-version.js --write             # apply changes
+ *   node scripts/backfill-schema-version.js --root <dir>        # custom root
+ *   node scripts/backfill-schema-version.js --version 3         # override version value
+ *   node scripts/backfill-schema-version.js --report report.md  # write a markdown report
+ *
+ * Default roots (in order, first existing wins):
+ *   - ./skills
+ *   - ./Skill Graph/skills
+ *
+ * Multi-root workspaces should pass `--root <dir>` per project root, or use
+ * `.skill-graph/config.json` (consumed by `scripts/generate-manifest.js`).
+ *
+ * No external dependencies.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_ROOTS = [
+  'skills',
+  'Skill Graph/skills'
+];
+
+const DEFAULT_VERSION = 3;
+
+function parseArgs(argv) {
+  const args = {
+    write: false,
+    roots: [],
+    version: DEFAULT_VERSION,
+    report: null
+  };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--write') args.write = true;
+    else if (a === '--root') args.roots.push(path.resolve(argv[++i]));
+    else if (a === '--version') args.version = parseInt(argv[++i], 10);
+    else if (a === '--report') args.report = path.resolve(argv[++i]);
+    else if (a === '--help' || a === '-h') {
+      console.log('Usage: backfill-schema-version.js [--write] [--root <dir>]... [--version N] [--report <path>]');
+      process.exit(0);
+    } else {
+      console.error(`Unknown arg: ${a}`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+function resolveRoots(customRoots) {
+  if (customRoots.length) return customRoots;
+  const cwd = process.cwd();
+  const resolved = [];
+  for (const candidate of DEFAULT_ROOTS) {
+    const full = path.resolve(cwd, candidate);
+    if (fs.existsSync(full) && fs.statSync(full).isDirectory()) {
+      resolved.push(full);
+    }
+  }
+  return resolved;
+}
+
+function walkSkillFiles(root) {
+  const out = [];
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { continue; }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (ent.name === 'node_modules' || ent.name.startsWith('.git')) continue;
+        stack.push(full);
+      } else if (ent.isFile() && ent.name === 'SKILL.md') {
+        out.push(full);
+      }
+    }
+  }
+  return out.sort();
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---\n')) return { start: -1, end: -1, lines: [] };
+  const rest = content.slice(4);
+  const endIdx = rest.indexOf('\n---\n');
+  if (endIdx === -1) return { start: -1, end: -1, lines: [] };
+  const fm = rest.slice(0, endIdx);
+  return { start: 4, end: 4 + endIdx + 5, lines: fm.split('\n') };
+}
+
+function hasSchemaVersion(lines) {
+  return lines.some(l => /^schema_version\s*:/.test(l));
+}
+
+function insertSchemaVersion(content, version) {
+  if (!content.startsWith('---\n')) {
+    return `---\nschema_version: ${version}\n---\n\n${content}`;
+  }
+  // insert as first frontmatter line
+  return content.replace(/^---\n/, `---\nschema_version: ${version}\n`);
+}
+
+function formatReport(results, version) {
+  const missing = results.filter(r => !r.hasSchemaVersion);
+  const present = results.filter(r => r.hasSchemaVersion);
+  const lines = [
+    '# schema_version Backfill Report',
+    '',
+    `Generated: ${new Date().toISOString()}`,
+    `Target version: ${version}`,
+    '',
+    `## Summary`,
+    '',
+    `- Total SKILL.md files scanned: **${results.length}**`,
+    `- With \`schema_version\` already: **${present.length}**`,
+    `- Missing \`schema_version\`: **${missing.length}**`,
+    `- Coverage: **${results.length ? Math.round((present.length / results.length) * 100) : 0}%**`,
+    '',
+    `## Missing (would add \`schema_version: ${version}\`)`,
+    ''
+  ];
+  if (missing.length === 0) {
+    lines.push('_None — every SKILL.md declares schema_version._');
+  } else {
+    for (const r of missing) lines.push(`- ${r.path}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const roots = resolveRoots(args.roots);
+  if (roots.length === 0) {
+    console.error('No skill roots found. Pass --root <dir> or run from a directory containing one of:', DEFAULT_ROOTS.join(', '));
+    process.exit(2);
+  }
+
+  console.log(`[backfill] Mode: ${args.write ? 'WRITE' : 'DRY-RUN'}  Version: ${args.version}`);
+  console.log(`[backfill] Scanning roots:`);
+  for (const r of roots) console.log(`  - ${r}`);
+
+  const results = [];
+  for (const root of roots) {
+    const files = walkSkillFiles(root);
+    for (const file of files) {
+      const content = fs.readFileSync(file, 'utf8');
+      const fm = parseFrontmatter(content);
+      const has = fm.lines.length > 0 && hasSchemaVersion(fm.lines);
+      results.push({ path: path.relative(process.cwd(), file), hasSchemaVersion: has, absPath: file });
+
+      if (!has && args.write) {
+        const updated = insertSchemaVersion(content, args.version);
+        fs.writeFileSync(file, updated, 'utf8');
+      }
+    }
+  }
+
+  const missing = results.filter(r => !r.hasSchemaVersion);
+  const present = results.filter(r => r.hasSchemaVersion);
+
+  console.log(`[backfill] Scanned: ${results.length}  With schema_version: ${present.length}  Missing: ${missing.length}`);
+
+  if (missing.length) {
+    const display = missing.slice(0, 20);
+    console.log(`[backfill] ${args.write ? 'Updated' : 'Would update'} ${missing.length} files:`);
+    for (const r of display) console.log(`  - ${r.path}`);
+    if (missing.length > display.length) console.log(`  ... (${missing.length - display.length} more)`);
+  }
+
+  if (args.report) {
+    fs.writeFileSync(args.report, formatReport(results, args.version), 'utf8');
+    console.log(`[backfill] Wrote report to ${args.report}`);
+  }
+
+  if (!args.write && missing.length > 0) {
+    console.log(`[backfill] Dry-run only. Re-run with --write to apply.`);
+    process.exit(0); // dry-run is always success-exit
+  }
+}
+
+main();

package/scripts/build-field-reference.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * build-field-reference.js — Schema → field-reference.generated.md
+ *
+ * Reads schemas/skill.schema.json (the current canonical schema) and emits
+ * docs/field-reference.generated.md
+ * with one section per top-level field. The prose is taken from the schema's
+ * `description` attributes; cross-links to the full reference + glossary are
+ * inserted automatically.
+ *
+ * Purpose: provide a drift-free field reference that is guaranteed in sync
+ * with the schema. The hand-authored `docs/field-reference.md` stays as the
+ * canonical prose (richer examples, when-to-use guidance, lint notes). This
+ * generator produces a thinner companion doc for consumers that want a
+ * machine-guaranteed index of every field.
+ *
+ * Usage:
+ *   node scripts/build-field-reference.js                     # writes default path
+ *   node scripts/build-field-reference.js --output <path>     # custom path
+ *   node scripts/build-field-reference.js --check             # exit 1 if regeneration would differ
+ *
+ * No external dependencies.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const SCHEMA_PATH = path.join(ROOT, 'schemas', 'skill.schema.json');
+const DEFAULT_OUTPUT = path.join(ROOT, 'docs', 'field-reference.generated.md');
+
+function parseArgs(argv) {
+  const args = { output: DEFAULT_OUTPUT, check: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--output' || a === '-o') args.output = path.resolve(argv[++i]);
+    else if (a === '--check') args.check = true;
+    else if (a === '--help' || a === '-h') {
+      console.log('Usage: build-field-reference.js [--output <path>] [--check]');
+      process.exit(0);
+    } else {
+      console.error(`Unknown arg: ${a}`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+function loadSchema() {
+  const raw = fs.readFileSync(SCHEMA_PATH, 'utf8');
+  return JSON.parse(raw);
+}
+
+function renderObjectShape(prop, indent = 0) {
+  if (prop.type === 'object' && prop.properties) {
+    const pad = '  '.repeat(indent);
+    const sub = Object.entries(prop.properties).map(([k, v]) => {
+      const req = (prop.required || []).includes(k);
+      const marker = req ? '*required*' : '*optional*';
+      const desc = v.description ? ` — ${v.description.split('.')[0]}.` : '';
+      const enumHint = v.enum ? ` (${v.enum.map(e => `\`${e}\``).join(' | ')})` : '';
+      return `${pad}- \`${k}\` ${marker}${enumHint}${desc}`;
+    });
+    return sub.join('\n');
+  }
+  return '';
+}
+
+function typeLabel(prop) {
+  if (prop.enum) return prop.enum.map(v => `\`${v}\``).join(' | ');
+  if (prop.oneOf) return 'multiple — see schema';
+  if (prop.type === 'array') {
+    const itemType = prop.items ? (prop.items.type || (prop.items.oneOf ? 'string | object' : 'string')) : 'any';
+    return `array of ${itemType}`;
+  }
+  if (prop.type) return prop.type;
+  return 'any';
+}
+
+function renderField(name, prop, requiredSet) {
+  const isRequired = requiredSet.has(name);
+  const requiredLabel = isRequired ? ' *(required)*' : ' *(optional)*';
+  const typeStr = typeLabel(prop);
+  const desc = prop.description || '_No description in schema._';
+
+  const parts = [
+    `### \`${name}\`${requiredLabel}`,
+    '',
+    `**Type:** ${typeStr}`,
+    '',
+    desc.trim(),
+    ''
+  ];
+
+  if (prop.pattern) parts.push('', `**Pattern:** \`${prop.pattern}\``, '');
+  if (prop.format) parts.push('', `**Format:** ${prop.format}`, '');
+  if (prop.minLength !== undefined) parts.push('', `**Min length:** ${prop.minLength}`, '');
+  if (prop.maxLength !== undefined) parts.push('', `**Max length:** ${prop.maxLength}`, '');
+
+  if (prop.type === 'object' && prop.properties) {
+    parts.push('', '**Sub-fields:**', '', renderObjectShape(prop), '');
+  }
+
+  if (prop.items && prop.items.type === 'object' && prop.items.properties) {
+    parts.push('', '**Item shape (object form):**', '', renderObjectShape(prop.items), '');
+  }
+
+  parts.push('', `**Full reference:** [\`docs/field-reference.md#${name}\`](field-reference.md#${name})`, '');
+
+  return parts.join('\n').replace(/\n{3,}/g, '\n\n');
+}
+
+function render(schema) {
+  const requiredSet = new Set(schema.required || []);
+  const now = new Date().toISOString().slice(0, 10);
+  const lines = [
+    '# Skill Graph Field Reference (Generated)',
+    '',
+    `> **Generated from** \`schemas/skill.schema.json\` on ${now} by \`scripts/build-field-reference.js\`.`,
+    '> **Do not edit by hand.** The canonical prose reference is [\`docs/field-reference.md\`](field-reference.md).',
+    '> **Predicate glossary:** [\`docs/glossary.md\`](glossary.md).',
+    '> **JSON-LD @context:** [\`schemas/skill.context.jsonld\`](../schemas/skill.context.jsonld).',
+    '',
+    `Schema version: **${schema.properties.schema_version?.oneOf?.[0]?.const ?? 'unknown'}** · Field count: **${Object.keys(schema.properties).length}** · Required: **${requiredSet.size}**`,
+    '',
+    '---',
+    ''
+  ];
+
+  for (const [name, prop] of Object.entries(schema.properties)) {
+    lines.push(renderField(name, prop, requiredSet));
+    lines.push('---');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const schema = loadSchema();
+  const output = render(schema);
+
+  if (args.check) {
+    let existing = '';
+    try { existing = fs.readFileSync(args.output, 'utf8'); } catch {}
+    if (existing !== output) {
+      console.error(`[check] ${args.output} is out of date. Regenerate with: node scripts/build-field-reference.js`);
+      process.exit(1);
+    }
+    console.log(`[check] ${args.output} is up to date.`);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(args.output), { recursive: true });
+  fs.writeFileSync(args.output, output, 'utf8');
+  console.log(`Wrote ${args.output} (${output.length} bytes, ${Object.keys(schema.properties).length} fields)`);
+}
+
+main();