@skill-graph/cli 0.5.6

package/scripts/skill-overlap.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * Skill Graph overlap detector.
+ *
+ * Detects collisions across the three activation surfaces that a router
+ * consults to decide which skill claims an inbound request:
+ *
+ *   1. triggers — exact label match. A duplicate is a routing ambiguity
+ *      the router cannot resolve (no semantic fallback for identical
+ *      labels). Duplicates are hard errors.
+ *
+ *   2. keywords — semantic match. Some overlap is natural (e.g. both an
+ *      a11y skill and a testing-strategy skill might reference "keyboard").
+ *      Excessive overlap is a signal that activation will mis-fire;
+ *      emitted as warnings for author review.
+ *
+ *   3. paths — glob match. Two skills claiming the same file surface
+ *      will both activate when that surface is touched. Exact-string
+ *      glob duplicates are flagged as warnings; partial-overlap
+ *      (e.g. `src/**` vs `src/auth/**`) is out of scope for a
+ *      dependency-free implementation.
+ *
+ * Complementary to skill-lint.js, which validates per-skill correctness.
+ * This script validates cross-skill routing hygiene.
+ *
+ * Self-contained. Only uses Node built-ins — no external dependencies.
+ * Exit 0 on success (no errors), 1 on any trigger/keyword/path error.
+ * With --strict, warnings are promoted to errors.
+ *
+ * Usage:
+ *   node scripts/skill-overlap.js
+ *   node scripts/skill-overlap.js --include-template   # also scan skill-metadata-template.md
+ *   node scripts/skill-overlap.js --strict             # warnings become errors
+ *   node scripts/skill-overlap.js --json               # machine-readable output
+ *   node scripts/skill-overlap.js --no-color           # plain CI output
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatter } = require('./lib/parse-frontmatter');
+const { loadWorkspaceConfig, resolveSkillRoots, workspaceRoot } = require('./lib/roots');
+
+const REPO_ROOT = workspaceRoot();
+const TEMPLATE_PATH = path.join(REPO_ROOT, 'examples', 'skill-metadata-template.md');
+const WORKSPACE_CONFIG = loadWorkspaceConfig(REPO_ROOT, msg => process.stderr.write(`WARN ${msg}\n`));
+const SKILL_ROOTS = resolveSkillRoots(REPO_ROOT, WORKSPACE_CONFIG);
+
+// ANSI color helpers — matched to scripts/lint/format-code-frame.js palette.
+const C = {
+  red:    '\x1b[31m',
+  yellow: '\x1b[33m',
+  green:  '\x1b[32m',
+  dim:    '\x1b[2m',
+  bold:   '\x1b[1m',
+  reset:  '\x1b[0m',
+};
+function paint(s, color, enabled) {
+  return enabled ? color + s + C.reset : s;
+}
+
+// ---------------------------------------------------------------------------
+// Skill loading
+// ---------------------------------------------------------------------------
+
+function loadSkills(includeTemplate) {
+  const skills = [];
+  for (const root of SKILL_ROOTS) {
+    if (!fs.existsSync(root.absPath)) continue;
+    for (const name of fs.readdirSync(root.absPath).sort()) {
+      const skillMd = path.join(root.absPath, name, 'SKILL.md');
+      if (!fs.existsSync(skillMd)) continue;
+      const text = fs.readFileSync(skillMd, 'utf8');
+      const fm = parseFrontmatter(text);
+      if (fm && fm.name) skills.push({ file: skillMd, fm });
+    }
+  }
+  if (includeTemplate && fs.existsSync(TEMPLATE_PATH)) {
+    const text = fs.readFileSync(TEMPLATE_PATH, 'utf8');
+    const fm = parseFrontmatter(text);
+    if (fm && fm.name) skills.push({ file: TEMPLATE_PATH, fm });
+  }
+  return skills;
+}
+
+// ---------------------------------------------------------------------------
+// Overlap detection helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a map of value → [skill-name, ...] for a given frontmatter array field.
+ * Case-insensitive (activation surfaces are case-insensitive in practice).
+ * Returns only entries that appear in 2+ skills.
+ */
+function detectDuplicates(skills, field) {
+  const map = new Map();
+  for (const { fm } of skills) {
+    const list = Array.isArray(fm[field]) ? fm[field] : [];
+    for (const raw of list) {
+      if (typeof raw !== 'string') continue;
+      const key = raw.trim().toLowerCase();
+      if (!key) continue;
+      if (!map.has(key)) map.set(key, { value: raw, owners: [] });
+      // Avoid double-listing a skill that has the same value twice in its own array.
+      const entry = map.get(key);
+      if (!entry.owners.includes(fm.name)) entry.owners.push(fm.name);
+    }
+  }
+  const dups = [];
+  for (const [, entry] of map) {
+    if (entry.owners.length >= 2) dups.push(entry);
+  }
+  return dups.sort((a, b) => a.value.localeCompare(b.value));
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function formatDuplicateLine(kind, entry, useColor) {
+  const label = paint(kind, C.bold, useColor);
+  const value = paint(JSON.stringify(entry.value), C.yellow, useColor);
+  const owners = entry.owners.map(o => paint(o, C.dim, useColor)).join(', ');
+  return `  ${label} ${value}  —  in: ${owners}`;
+}
+
+function printReport({ triggerDups, keywordDups, pathDups, strict, useColor }) {
+  // Triggers — always error.
+  if (triggerDups.length === 0) {
+    console.log(paint('OK   ', C.green, useColor) + '[triggers]   no duplicate trigger labels');
+  } else {
+    console.error(paint('FAIL ', C.red, useColor) + `[triggers]   ${triggerDups.length} duplicate label(s)`);
+    for (const d of triggerDups) console.error(formatDuplicateLine('trigger', d, useColor));
+  }
+
+  // Keywords — warning (or error in --strict).
+  if (keywordDups.length === 0) {
+    console.log(paint('OK   ', C.green, useColor) + '[keywords]   no duplicate keyword entries');
+  } else {
+    const level = strict ? 'FAIL ' : 'WARN ';
+    const levelColor = strict ? C.red : C.yellow;
+    const stream = strict ? console.error : console.log;
+    stream.call(console, paint(level, levelColor, useColor) + `[keywords]   ${keywordDups.length} duplicate keyword(s)`);
+    for (const d of keywordDups) stream.call(console, formatDuplicateLine('keyword', d, useColor));
+  }
+
+  // Paths — warning (or error in --strict).
+  if (pathDups.length === 0) {
+    console.log(paint('OK   ', C.green, useColor) + '[paths]      no duplicate path globs');
+  } else {
+    const level = strict ? 'FAIL ' : 'WARN ';
+    const levelColor = strict ? C.red : C.yellow;
+    const stream = strict ? console.error : console.log;
+    stream.call(console, paint(level, levelColor, useColor) + `[paths]      ${pathDups.length} duplicate glob(s)`);
+    for (const d of pathDups) stream.call(console, formatDuplicateLine('path', d, useColor));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const argv = process.argv.slice(2);
+  const strict = argv.includes('--strict');
+  const includeTemplate = argv.includes('--include-template');
+  const jsonOut = argv.includes('--json');
+  const noColor = argv.includes('--no-color');
+  const useColor = !noColor && process.stdout.isTTY;
+
+  const skills = loadSkills(includeTemplate);
+  if (skills.length === 0) {
+    console.error('No skills found to analyze.');
+    process.exit(1);
+  }
+
+  const triggerDups = detectDuplicates(skills, 'triggers');
+  const keywordDups = detectDuplicates(skills, 'keywords');
+  const pathDups    = detectDuplicates(skills, 'paths');
+
+  const triggerErrors = triggerDups.length;
+  const warnCount     = keywordDups.length + pathDups.length;
+  const totalErrors   = triggerErrors + (strict ? warnCount : 0);
+
+  if (jsonOut) {
+    const payload = {
+      skills_scanned: skills.length,
+      triggers: triggerDups,
+      keywords: keywordDups,
+      paths:    pathDups,
+      summary:  {
+        errors:   triggerErrors,
+        warnings: strict ? 0 : warnCount,
+        strict,
+      },
+    };
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    process.exit(totalErrors > 0 ? 1 : 0);
+  }
+
+  printReport({ triggerDups, keywordDups, pathDups, strict, useColor });
+
+  const tail = strict && warnCount > 0
+    ? ` (--strict: ${warnCount} warning(s) promoted to errors)`
+    : warnCount > 0
+      ? `, ${warnCount} warning(s)`
+      : '';
+  console.log(`\n${skills.length} skill(s) analyzed, ${totalErrors} error(s)${tail}.`);
+  process.exit(totalErrors > 0 ? 1 : 0);
+}
+
+main();

package/scripts/verify-skill-md-export.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * Verify that Skill Graph skills export to plain SKILL.md frontmatter.
+ *
+ * This is intentionally stricter than "export script exits 0": it rebuilds the
+ * exported frontmatter in memory and validates the structural shape that broad
+ * SKILL.md-compatible runtimes expect at the top level.
+ *
+ * Usage:
+ *   node scripts/verify-skill-md-export.js
+ *   node scripts/verify-skill-md-export.js skills/documentation
+ *   node scripts/verify-skill-md-export.js --plain marketplace/skills
+ *   node scripts/verify-skill-md-export.js --json
+ *
+ * Self-contained. Only uses Node built-ins.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatter } = require('./lib/parse-frontmatter');
+const { workspaceRoot, loadWorkspaceConfig, resolveSkillRoots } = require('./lib/roots');
+const { buildExportedSkill } = require('./export-skill');
+
+const REPO_ROOT = workspaceRoot();
+const WORKSPACE_CONFIG = loadWorkspaceConfig(REPO_ROOT, msg => process.stderr.write(`WARN ${msg}\n`));
+const SKILL_ROOTS = resolveSkillRoots(REPO_ROOT, WORKSPACE_CONFIG);
+// Primary skill root — first configured root, or local skills/ as fallback.
+const DEFAULT_SKILLS_DIR = SKILL_ROOTS[0].absPath;
+const TOP_LEVEL_FIELDS = new Set(['name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools']);
+
+function repoRelative(filePath) {
+  return path.relative(REPO_ROOT, filePath).split(path.sep).join('/');
+}
+
+function collectSkillFiles(inputs) {
+  const files = [];
+  const roots = inputs.length > 0 ? inputs : [DEFAULT_SKILLS_DIR];
+
+  for (const input of roots) {
+    const abs = path.resolve(input);
+    if (!fs.existsSync(abs)) continue;
+    const stat = fs.statSync(abs);
+    if (stat.isFile() && path.basename(abs) === 'SKILL.md') {
+      files.push(abs);
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+
+    const direct = path.join(abs, 'SKILL.md');
+    if (fs.existsSync(direct)) {
+      files.push(direct);
+      continue;
+    }
+
+    for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const skillMd = path.join(abs, entry.name, 'SKILL.md');
+      if (fs.existsSync(skillMd)) files.push(skillMd);
+    }
+  }
+
+  return files.sort((a, b) => repoRelative(a).localeCompare(repoRelative(b)));
+}
+
+function validateName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    return ['name must be a non-empty string'];
+  }
+  if (/[/:]/.test(name)) {
+    return ['name must not contain "/" or ":" in exported SKILL.md frontmatter'];
+  }
+  return [];
+}
+
+function validateExportedFrontmatter(fm) {
+  const errors = [];
+
+  for (const key of Object.keys(fm)) {
+    if (!TOP_LEVEL_FIELDS.has(key)) {
+      errors.push(`unexpected top-level field "${key}"`);
+    }
+  }
+
+  errors.push(...validateName(fm.name));
+
+  if (typeof fm.description !== 'string' || fm.description.length === 0) {
+    errors.push('description must be a non-empty string');
+  }
+
+  if (fm.license !== undefined && typeof fm.license !== 'string') {
+    errors.push('license must be a string when present');
+  }
+
+  if (fm.compatibility !== undefined) {
+    if (typeof fm.compatibility !== 'string' || fm.compatibility.length === 0) {
+      errors.push('compatibility must be a non-empty string when present');
+    }
+  }
+
+  if (fm['allowed-tools'] !== undefined && typeof fm['allowed-tools'] !== 'string') {
+    errors.push('allowed-tools must be a space-separated string when present');
+  }
+
+  if (fm.metadata !== undefined) {
+    if (!fm.metadata || typeof fm.metadata !== 'object' || Array.isArray(fm.metadata)) {
+      errors.push('metadata must be a key-value object when present');
+    } else {
+      for (const [key, value] of Object.entries(fm.metadata)) {
+        if (key.length === 0) errors.push('metadata keys must be non-empty strings');
+        if (typeof value !== 'string') errors.push(`metadata.${key} must be a string`);
+      }
+    }
+  }
+
+  return { errors };
+}
+
+function verifySkillFile(skillMd, options = {}) {
+  const sourceText = fs.readFileSync(skillMd, 'utf8');
+  const sourceFm = parseFrontmatter(sourceText);
+  if (!sourceFm) {
+    return {
+      file: repoRelative(skillMd),
+      ok: false,
+      errors: ['source SKILL.md has no parseable frontmatter'],
+    };
+  }
+
+  if (options.plain) {
+    const validation = validateExportedFrontmatter(sourceFm);
+    return {
+      file: repoRelative(skillMd),
+      ok: validation.errors.length === 0,
+      errors: validation.errors,
+    };
+  }
+
+  const exportedText = buildExportedSkill(sourceText);
+  if (!exportedText) {
+    return {
+      file: repoRelative(skillMd),
+      ok: false,
+      errors: ['exported SKILL.md could not be built from source'],
+    };
+  }
+  const exportedFm = parseFrontmatter(exportedText);
+  const validation = exportedFm
+    ? validateExportedFrontmatter(exportedFm)
+    : { errors: ['exported SKILL.md has no parseable frontmatter'] };
+
+  return {
+    file: repoRelative(skillMd),
+    ok: validation.errors.length === 0,
+    errors: validation.errors,
+  };
+}
+
+function printText(results) {
+  for (const r of results) {
+    if (r.ok) continue;
+    process.stdout.write(`FAIL ${r.file}\n`);
+    for (const e of r.errors) process.stdout.write(`  - ${e}\n`);
+  }
+  const passing = results.filter(r => r.ok).length;
+  const failing = results.length - passing;
+  process.stdout.write(`${results.length} skill export(s): ${passing} PASS, ${failing} FAIL.\n`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const outputJson = args.includes('--json');
+  const quiet = args.includes('--quiet');
+  const plain = args.includes('--plain') || args.includes('--as-is');
+  const inputs = args.filter(a => !a.startsWith('--'));
+  const skillFiles = collectSkillFiles(inputs);
+
+  if (skillFiles.length === 0) {
+    process.stderr.write('ERROR no SKILL.md files found to verify.\n');
+    process.exit(1);
+  }
+
+  const results = skillFiles.map(skillFile => verifySkillFile(skillFile, { plain }));
+
+  if (outputJson) {
+    process.stdout.write(JSON.stringify({ results }, null, 2) + '\n');
+  } else if (!quiet) {
+    printText(results);
+  }
+
+  process.exit(results.some(r => !r.ok) ? 1 : 0);
+}
+
+module.exports = {
+  collectSkillFiles,
+  validateExportedFrontmatter,
+  verifySkillFile,
+};
+
+if (require.main === module) main();