@blamejs/exceptd-skills 0.12.11 → 0.12.15

package/lib/lint-skills.js

@@ -43,6 +43,7 @@ const process = require('node:process');
 
 const REPO_ROOT = path.resolve(__dirname, '..');
 const MANIFEST_PATH = path.join(REPO_ROOT, 'manifest.json');
+const SKILLS_DIR = path.join(REPO_ROOT, 'skills');
 const DATA_DIR = path.join(REPO_ROOT, 'data');
 const ATLAS_PATH = path.join(DATA_DIR, 'atlas-ttps.json');
 const FRAMEWORK_GAPS_PATH = path.join(DATA_DIR, 'framework-control-gaps.json');
@@ -50,6 +51,7 @@ const RFC_REFS_PATH = path.join(DATA_DIR, 'rfc-references.json');
 const CWE_REFS_PATH = path.join(DATA_DIR, 'cwe-catalog.json');
 const D3FEND_REFS_PATH = path.join(DATA_DIR, 'd3fend-catalog.json');
 const DLP_REFS_PATH = path.join(DATA_DIR, 'dlp-controls.json');
+const ATTACK_REFS_PATH = path.join(DATA_DIR, 'attack-techniques.json');
 
 const REQUIRED_FRONTMATTER_FIELDS = [
   'name',
@@ -80,6 +82,18 @@ const REQUIRED_SECTIONS = [
   'Compliance Theater Check',
 ];
 
+// L3 — Defensive Countermeasure Mapping became a required section for skills
+// reviewed on or after this cutoff (documented in AGENTS.md). Pre-cutoff
+// skills remain exempt to preserve patch-class compatibility; v0.13.0 may
+// broaden the cutoff.
+const COUNTERMEASURE_SECTION = 'Defensive Countermeasure Mapping';
+const COUNTERMEASURE_CUTOFF = '2026-05-11';
+
+// L1 — Minimum number of words of body text between a section heading and the
+// next heading (or EOF) for the section to count as populated. Header-only
+// sections surface as WARNINGS in v0.12.12; v0.13.0 will tighten to failure.
+const MIN_SECTION_BODY_WORDS = 20;
+
 const PLACEHOLDER_PATTERNS = [
   /\bTODO\b/i,
   /\bTBD\b/i,
@@ -148,6 +162,12 @@ function readJson(p) {
 function parseFrontmatter(text) {
   const lines = text.split(/\r?\n/);
   const result = {};
+  // S4: track every top-level key we've already assigned. YAML's
+  // last-wins semantics would let a tampered skill set name twice
+  // ("name: real-skill\nname: evil-skill") and silently take the
+  // second value — a skill-identity spoofing primitive. Refuse
+  // duplicates outright; an honest skill never has them.
+  const seenKeys = new Set();
   let i = 0;
   while (i < lines.length) {
     const raw = lines[i];
@@ -166,6 +186,12 @@ function parseFrontmatter(text) {
     }
     const key = m[1];
     const rest = m[2];
+    if (seenKeys.has(key)) {
+      throw new Error(
+        `Duplicate frontmatter key "${key}" at line ${i + 1} — refusing last-wins semantics`,
+      );
+    }
+    seenKeys.add(key);
     if (rest === '' || rest === undefined) {
       const items = [];
       i++;
@@ -331,15 +357,69 @@ function validateFrontmatter(fm, skillName) {
   return errors;
 }
 
-function findMissingSections(body) {
-  const lower = body.toLowerCase();
+/* L1 — Heading-anchored section detection.
+ *
+ * Returns { missing, headerOnly }:
+ *   - missing[]    — sections with no `^## <Section Name>` heading anywhere
+ *                    in the body (case-insensitive). Hard failure.
+ *   - headerOnly[] — sections whose heading exists but whose body between
+ *                    that heading and the next heading is shorter than
+ *                    MIN_SECTION_BODY_WORDS words. Warning in v0.12.12;
+ *                    v0.13.0 will tighten. */
+function findMissingSections(body, requiredSections) {
+  const sections = requiredSections || REQUIRED_SECTIONS;
+  const lines = body.split(/\r?\n/);
+  // Index every heading line (any depth) so we know where each section ends.
+  const headings = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (m) {
+      headings.push({ line: i, depth: m[1].length, title: m[2].trim() });
+    }
+  }
+  // Heading match is case-insensitive and tolerates trailing context
+  // qualifiers (e.g. "## Threat Context (mid-2026)" or
+  // "## TTP Mapping (MITRE ATT&CK Enterprise, mid-2026)"). The required
+  // section name must appear as a leading token followed by end-of-string
+  // or a non-alphanumeric character (paren, dash, colon).
+  const findHeading = (title) => {
+    const t = title.toLowerCase();
+    return headings.find((h) => {
+      const lower = h.title.toLowerCase();
+      if (lower === t) return true;
+      if (lower.startsWith(t)) {
+        const next = lower[t.length];
+        if (next === undefined) return true;
+        if (!/[a-z0-9]/.test(next)) return true;
+      }
+      return false;
+    });
+  };
+
   const missing = [];
-  for (const section of REQUIRED_SECTIONS) {
-    if (!lower.includes(section.toLowerCase())) {
+  const headerOnly = [];
+  for (const section of sections) {
+    const h = findHeading(section);
+    if (!h) {
       missing.push(section);
+      continue;
+    }
+    // Find the next heading at the same or shallower depth, or EOF.
+    const idx = headings.indexOf(h);
+    let endLine = lines.length;
+    for (let j = idx + 1; j < headings.length; j++) {
+      if (headings[j].depth <= h.depth) {
+        endLine = headings[j].line;
+        break;
+      }
+    }
+    const bodyText = lines.slice(h.line + 1, endLine).join(' ').trim();
+    const wordCount = bodyText ? bodyText.split(/\s+/).length : 0;
+    if (wordCount < MIN_SECTION_BODY_WORDS) {
+      headerOnly.push({ section, wordCount });
     }
   }
-  return missing;
+  return { missing, headerOnly };
 }
 
 function findPlaceholders(text) {
@@ -358,17 +438,18 @@ function findPlaceholders(text) {
 
 function lintSkill(entry, ctx) {
   const skillErrors = [];
+  const skillWarnings = [];
   const skillPath = path.join(REPO_ROOT, entry.path);
 
   if (!fs.existsSync(skillPath)) {
-    return { name: entry.name, errors: [`skill file not found at ${entry.path}`] };
+    return { name: entry.name, errors: [`skill file not found at ${entry.path}`], warnings: [] };
   }
 
   const content = fs.readFileSync(skillPath, 'utf8');
   const { frontmatter: fmRaw, body } = extractFrontmatterBlock(content);
   if (fmRaw === null) {
     skillErrors.push('skill.md does not start with a `---` YAML frontmatter block');
-    return { name: entry.name, errors: skillErrors };
+    return { name: entry.name, errors: skillErrors, warnings: skillWarnings };
   }
 
   let fm;
@@ -376,7 +457,7 @@ function lintSkill(entry, ctx) {
     fm = parseFrontmatter(fmRaw);
   } catch (err) {
     skillErrors.push(`frontmatter parse error: ${err.message}`);
-    return { name: entry.name, errors: skillErrors };
+    return { name: entry.name, errors: skillErrors, warnings: skillWarnings };
   }
 
   skillErrors.push(...validateFrontmatter(fm, entry.name));
@@ -448,17 +529,62 @@ function lintSkill(entry, ctx) {
     }
   }
 
-  const missingSections = findMissingSections(body);
-  for (const s of missingSections) {
+  // L2 — attack_refs cross-catalog resolution. Surface as WARNINGS in
+  // v0.12.12 to preserve patch-class compatibility; v0.13.0 will flip to
+  // hard failures. If data/attack-techniques.json is missing entirely the
+  // ctx.attackKeys set is null — skip the check (the gate degrades to its
+  // pre-v0.12.12 behavior).
+  if (Array.isArray(fm.attack_refs) && ctx.attackKeys) {
+    for (const ref of fm.attack_refs) {
+      if (!ctx.attackKeys.has(ref)) {
+        skillWarnings.push(
+          `attack_refs: "${ref}" not present in data/attack-techniques.json (will hard-fail in v0.13.0)`,
+        );
+      }
+    }
+  }
+
+  // L3 — Defensive Countermeasure Mapping is required for skills reviewed
+  // on or after COUNTERMEASURE_CUTOFF. Pre-cutoff skills are exempt. The
+  // section's absence on a post-cutoff skill is a WARNING in v0.12.12 so
+  // existing skills can add the section gradually; v0.13.0 will flip to
+  // a hard failure.
+  const { missing, headerOnly } = findMissingSections(body, REQUIRED_SECTIONS);
+  for (const s of missing) {
     skillErrors.push(`body: missing required section "${s}"`);
   }
+  for (const ho of headerOnly) {
+    // L1 — Header-only sections are WARNINGS in v0.12.12; v0.13.0 will
+    // tighten to failure.
+    skillWarnings.push(
+      `body: section "${ho.section}" has only ${ho.wordCount} words of body text (need >= ${MIN_SECTION_BODY_WORDS}); will hard-fail in v0.13.0`,
+    );
+  }
+  if (
+    typeof fm.last_threat_review === 'string' &&
+    ISO_DATE_RE.test(fm.last_threat_review) &&
+    fm.last_threat_review >= COUNTERMEASURE_CUTOFF
+  ) {
+    const cmResult = findMissingSections(body, [COUNTERMEASURE_SECTION]);
+    if (cmResult.missing.length > 0) {
+      skillWarnings.push(
+        `body: missing required section "${COUNTERMEASURE_SECTION}" (required for skills with last_threat_review >= ${COUNTERMEASURE_CUTOFF}; will hard-fail in v0.13.0)`,
+      );
+    } else {
+      for (const ho of cmResult.headerOnly) {
+        skillWarnings.push(
+          `body: section "${ho.section}" has only ${ho.wordCount} words of body text (need >= ${MIN_SECTION_BODY_WORDS}); will hard-fail in v0.13.0`,
+        );
+      }
+    }
+  }
 
   const placeholders = findPlaceholders(content);
   for (const p of placeholders) {
     skillErrors.push(`placeholder language at line ${p.line} (pattern /${p.pattern}/): ${p.text}`);
   }
 
-  return { name: entry.name, errors: skillErrors };
+  return { name: entry.name, errors: skillErrors, warnings: skillWarnings };
 }
 
 function loadContext() {
@@ -475,6 +601,14 @@ function loadContext() {
     }
     return s;
   }
+  // L2 — attack-techniques.json may not exist in older trees. When absent,
+  // ctx.attackKeys is null and the L2 check is skipped.
+  let attackKeys = null;
+  if (fs.existsSync(ATTACK_REFS_PATH)) {
+    attackKeys = new Set();
+    const j = readJson(ATTACK_REFS_PATH);
+    for (const k of Object.keys(j)) if (!k.startsWith('_')) attackKeys.add(k);
+  }
   return {
     atlasKeys,
     frameworkKeys,
@@ -482,9 +616,45 @@ function loadContext() {
     cweKeys: loadKeys(CWE_REFS_PATH),
     d3fendKeys: loadKeys(D3FEND_REFS_PATH),
     dlpKeys: loadKeys(DLP_REFS_PATH),
+    attackKeys,
   };
 }
 
+/*
+ * S6 — orphan skill.md detector.
+ *
+ * Walk every subdirectory of skills/ and assert each skill.md file is
+ * referenced by exactly one manifest entry. Catches the v0.12.8
+ * stash-restore class: a directory left behind on disk that nobody
+ * signs because nobody listed it in the manifest, then the next
+ * `npm pack` ships an unsigned skill (or worse, conflicts with a
+ * future manifest entry of the same name).
+ *
+ * @param {Array<{path: string}>} manifestSkills
+ * @returns {string[]} list of orphan filesystem paths (relative)
+ */
+function findOrphanSkillFiles(manifestSkills) {
+  if (!fs.existsSync(SKILLS_DIR)) return [];
+  // F19 — manifest paths are stored as forward-slash strings by contract
+  // (lib/verify.js validateSkillPath() rejects backslashes). The previous
+  // path.sep split was a no-op on Linux and incorrect on Windows when
+  // mixed separators arrived through other ingest paths; the cleaner
+  // contract is to normalise the comparison key directly.
+  const referenced = new Set(
+    manifestSkills.map((s) => String(s.path).replace(/\\/g, '/')),
+  );
+  const orphans = [];
+  for (const entry of fs.readdirSync(SKILLS_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const candidate = path.join(SKILLS_DIR, entry.name, 'skill.md');
+    if (fs.existsSync(candidate)) {
+      const rel = `skills/${entry.name}/skill.md`;
+      if (!referenced.has(rel)) orphans.push(rel);
+    }
+  }
+  return orphans;
+}
+
 function main() {
   const opts = parseArgs(process.argv);
   const manifest = readJson(MANIFEST_PATH);
@@ -503,24 +673,50 @@ function main() {
   const results = skills.map((entry) => lintSkill(entry, ctx));
 
   let failed = 0;
+  let warned = 0;
   for (const r of results) {
-    if (r.errors.length === 0) {
+    const warns = r.warnings || [];
+    if (r.errors.length === 0 && warns.length === 0) {
       if (!opts.quiet) {
         console.log(`PASS  ${r.name}`);
       }
+    } else if (r.errors.length === 0) {
+      warned++;
+      if (!opts.quiet) console.log(`WARN  ${r.name}`);
+      for (const w of warns) console.log(`        - [warn] ${w}`);
     } else {
       failed++;
       console.log(`FAIL  ${r.name}`);
       for (const e of r.errors) {
         console.log(`        - ${e}`);
       }
+      for (const w of warns) {
+        console.log(`        - [warn] ${w}`);
+      }
+    }
+  }
+
+  // S6 — orphan check runs only on a full lint pass (no --skill filter).
+  // A targeted single-skill lint is for diagnosing one entry; running
+  // the orphan walk there would surface unrelated findings.
+  let orphans = [];
+  if (!opts.skill) {
+    orphans = findOrphanSkillFiles(manifest.skills);
+    for (const o of orphans) {
+      console.log(`FAIL  <orphan>`);
+      console.log(`        - skill.md exists on disk but not in manifest: ${o}`);
+      console.log(`          fix: re-run \`node lib/sign.js sign-all\` after adding it to manifest.json, OR delete the orphan directory`);
     }
   }
 
   const total = results.length;
-  const passed = total - failed;
-  console.log(`\n${passed}/${total} skills passed${failed ? `, ${failed} failed` : ''}.`);
-  process.exit(failed === 0 ? 0 : 1);
+  const passed = total - failed - warned;
+  const orphanSummary = orphans.length ? `, ${orphans.length} orphan skill.md file(s)` : '';
+  const warnSummary = warned ? `, ${warned} with warnings` : '';
+  console.log(
+    `\n${passed}/${total} skills passed${warnSummary}${failed ? `, ${failed} failed` : ''}${orphanSummary}.`,
+  );
+  process.exit(failed === 0 && orphans.length === 0 ? 0 : 1);
 }
 
 // Export the minimal frontmatter parser for downstream consumers
@@ -529,6 +725,12 @@ module.exports = {
   parseFrontmatter,
   extractFrontmatterBlock,
   unquote,
+  findOrphanSkillFiles,
+  findMissingSections,
+  REQUIRED_SECTIONS,
+  COUNTERMEASURE_SECTION,
+  COUNTERMEASURE_CUTOFF,
+  MIN_SECTION_BODY_WORDS,
 };
 
 if (require.main === module) {