xdrs-core 0.24.1 → 0.26.0

package/lib/lint.js

@@ -5,9 +5,9 @@ const fs = require('fs');
 const path = require('path');
 
 const TYPE_TO_ID = {
-  adrs: 'adr',
-  bdrs: 'bdr',
-  edrs: 'edr'
+  adrs: 'adr-policy',
+  bdrs: 'bdr-policy',
+  edrs: 'edr-policy'
 };
 
 const ALLOWED_SUBJECTS = {
@@ -20,18 +20,18 @@ const TYPE_NAMES = new Set(Object.keys(TYPE_TO_ID));
 const RESERVED_SCOPES = new Set(['_core', '_local']);
 const NUMBERED_FILE_RE = /^(\d{3,})-([a-z0-9-]+)\.md$/;
 const NUMBERED_DIR_RE = /^(\d{3,})-([a-z0-9-]+)$/;
-const REQUIRED_ROOT_INDEX_TEXT = 'XDRs in scopes listed last override the ones listed first';
+const REQUIRED_ROOT_INDEX_TEXT = 'XDRS scopes listed last override the ones listed first';
 const SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches', 'plans']);
 const RESOURCE_DIR_NAME = '.assets';
 const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_DIR_NAME]);
 
-const XDR_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'apply-to', 'valid-from', 'license', 'metadata']);
+const POLICY_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'apply-to', 'valid-from', 'license', 'metadata']);
 const SKILL_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'license', 'metadata', 'compatibility', 'allowed-tools']);
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp']);
 const SLIDE_FILE_RE = /^.+-slides(?:-[a-z0-9-]+)?\.md$/;
 const SLIDE_MAX_NAME_LENGTH = 64;
 const EMOJI_RE = /\p{Extended_Pictographic}/u;
-const XDR_MAX_WORDS = 2600;
+const POLICY_MAX_WORDS = 2600;
 const ARTICLE_MAX_WORDS = 5000;
 const RESEARCH_MAX_WORDS = 5000;
 const SKILL_MAX_WORDS = 6500;
@@ -62,14 +62,14 @@ function runLintCli(args) {
 
 function printHelp() {
   console.log('Usage: xdrs-core lint [options] [path]\n');
-  console.log('Lint the XDR tree rooted at [path] when [path] contains an index.md, or at [path]/.xdrs by default.');
+  console.log('Lint the XDRS tree rooted at [path] when [path] contains an index.md, or at [path]/.xdrs by default.');
   console.log('\nOptions:');
   console.log('  --all    Check all files, including files from external scopes distributed via .filedist (default: skip external scopes)');
   console.log('\nAll other commands continue to be delegated to the bundled filedist CLI.');
 }
 
 function resolveXdrsRoot(resolvedTarget) {
-  // If the path itself contains an index.md, treat it as the XDR root directly.
+  // If the path itself contains an index.md, treat it as the XDRS root directly.
   // This allows any folder name to serve as the root, not only ".xdrs".
   if (existsFile(path.join(resolvedTarget, 'index.md'))) {
     return resolvedTarget;
@@ -85,7 +85,7 @@ function lintWorkspace(targetPath, options = {}) {
   const errors = [];
 
   if (!existsDirectory(xdrsRoot)) {
-    errors.push(`Missing XDR root directory: ${toDisplayPath(xdrsRoot)}`);
+    errors.push(`Missing XDRS root directory: ${toDisplayPath(xdrsRoot)}`);
     return { xdrsRoot, errors };
   }
 
@@ -95,7 +95,7 @@ function lintWorkspace(targetPath, options = {}) {
   const effectiveExternalScopes = ignoreExternal ? externalScopes : new Set();
 
   const actualTypeIndexes = [];
-  const rootEntries = safeReadDir(xdrsRoot, errors, 'read XDR root directory');
+  const rootEntries = safeReadDir(xdrsRoot, errors, 'read XDRS root directory');
   const scopeEntries = rootEntries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'));
 
   for (const entry of rootEntries) {
@@ -227,7 +227,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, igno
 function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeIndexes, externalScopes = new Set()) {
   const typePath = path.join(xdrsRoot, scopeName, typeName);
   const indexPath = path.join(typePath, 'index.md');
-  const xdrNumbers = new Map();
+  const xdrsNumbers = new Map();
   const artifacts = [];
 
   if (!existsFile(indexPath)) {
@@ -251,7 +251,7 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeInde
       continue;
     }
 
-    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrNumbers, errors, externalScopes));
+    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrsNumbers, errors, externalScopes));
   }
 
   if (existsFile(indexPath)) {
@@ -259,7 +259,7 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeInde
   }
 }
 
-function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNumbers, errors, externalScopes = new Set()) {
+function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrsNumbers, errors, externalScopes = new Set()) {
   const subjectPath = path.join(xdrsRoot, scopeName, typeName, subjectName);
   const artifacts = [];
   const entries = safeReadDir(subjectPath, errors, `read subject directory ${scopeName}/${typeName}/${subjectName}`);
@@ -293,22 +293,22 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
     }
 
     if (!NUMBERED_FILE_RE.test(entry.name)) {
-      errors.push(`Invalid XDR file name: ${toDisplayPath(entryPath)}`);
+      errors.push(`Invalid Policy file name: ${toDisplayPath(entryPath)}`);
       continue;
     }
 
     artifacts.push(entryPath);
-    lintXdrFile(xdrsRoot, scopeName, typeName, entryPath, xdrNumbers, errors, externalScopes);
+    lintXdrsElementFile(xdrsRoot, scopeName, typeName, entryPath, xdrsNumbers, errors, externalScopes);
   }
 
   const subjectAssetsDir = path.join(subjectPath, RESOURCE_DIR_NAME);
-  const xdrDocsInSubject = artifacts.filter((p) => path.dirname(p) === subjectPath);
-  lintOrphanAssets(subjectAssetsDir, xdrDocsInSubject, xdrsRoot, errors);
+  const xdrsDocsInSubject = artifacts.filter((p) => path.dirname(p) === subjectPath);
+  lintOrphanAssets(subjectAssetsDir, xdrsDocsInSubject, xdrsRoot, errors);
 
   return artifacts;
 }
 
-function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors, externalScopes = new Set()) {
+function lintXdrsElementFile(xdrsRoot, scopeName, typeName, filePath, xdrsNumbers, errors, externalScopes = new Set()) {
   const baseName = path.basename(filePath);
   const match = baseName.match(NUMBERED_FILE_RE);
   if (!match) {
@@ -316,35 +316,35 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
   }
 
   const number = match[1];
-  const previous = xdrNumbers.get(number);
+  const previous = xdrsNumbers.get(number);
   if (previous) {
-    errors.push(`Duplicate XDR number ${number} in ${scopeName}/${typeName}: ${toDisplayPath(previous)} and ${toDisplayPath(filePath)}`);
+    errors.push(`Duplicate Policy number ${number} in ${scopeName}/${typeName}: ${toDisplayPath(previous)} and ${toDisplayPath(filePath)}`);
   } else {
-    xdrNumbers.set(number, filePath);
+    xdrsNumbers.set(number, filePath);
   }
 
   if (baseName !== baseName.toLowerCase()) {
-    errors.push(`XDR file name must be lowercase: ${toDisplayPath(filePath)}`);
+    errors.push(`Policy file name must be lowercase: ${toDisplayPath(filePath)}`);
   }
 
   const content = fs.readFileSync(filePath, 'utf8');
   const expectedHeader = `# ${scopeName}-${TYPE_TO_ID[typeName]}-${number}:`;
   const firstLine = firstNonEmptyLine(stripFrontmatter(content));
   if (!firstLine.startsWith(expectedHeader)) {
-    errors.push(`XDR title must start with "${expectedHeader}": ${toDisplayPath(filePath)}`);
+    errors.push(`Policy title must start with "${expectedHeader}": ${toDisplayPath(filePath)}`);
   }
 
-  const expectedName = extractExpectedXdrNameFromHeading(firstLine)
+  const expectedName = extractExpectedXdrsNameFromHeading(firstLine)
     || `${scopeName}-${TYPE_TO_ID[typeName]}-${number}-${match[2]}`;
-  lintXdrFrontmatter(content, expectedName, filePath, errors);
-  lintRequiredSections(content, filePath, XDR_REQUIRED_SECTIONS, 'XDR', errors);
-  lintNoEmojis(content, filePath, 'XDR', errors);
-  lintWordCount(content, filePath, 'XDR', XDR_MAX_WORDS, errors);
+  lintXdrsElementFrontmatter(content, expectedName, filePath, errors);
+  lintRequiredSections(content, filePath, XDRS_REQUIRED_SECTIONS, 'Policy', errors);
+  lintNoEmojis(content, filePath, 'Policy', errors);
+  lintWordCount(content, filePath, 'Policy', POLICY_MAX_WORDS, errors);
   lintDocumentLinks(filePath, xdrsRoot, scopeName, errors, externalScopes);
 }
 
-function extractExpectedXdrNameFromHeading(headingLine) {
-  const match = headingLine.match(/^#\s+([a-z0-9_]+-(?:adr|bdr|edr)-\d{3,}):\s+(.+?)\s*$/);
+function extractExpectedXdrsNameFromHeading(headingLine) {
+  const match = headingLine.match(/^#\s+([a-z0-9_]+-(?:adr-policy|bdr-policy|edr-policy)-\d{3,}):\s+(.+?)\s*$/);
   if (!match) {
     return null;
   }
@@ -368,43 +368,43 @@ function slugifyTitle(title) {
     .replace(/--+/g, '-');
 }
 
-function lintXdrFrontmatter(content, expectedName, filePath, errors) {
+function lintXdrsElementFrontmatter(content, expectedName, filePath, errors) {
   const fm = extractFrontmatter(content);
   if (!fm.present) {
-    errors.push(`XDR must start with a YAML frontmatter block: ${toDisplayPath(filePath)}`);
+    errors.push(`Policy must start with a YAML frontmatter block: ${toDisplayPath(filePath)}`);
     return;
   }
   if (!fm.name) {
-    errors.push(`XDR frontmatter must include a non-empty name field: ${toDisplayPath(filePath)}`);
+    errors.push(`Policy frontmatter must include a non-empty name field: ${toDisplayPath(filePath)}`);
   } else {
     if (fm.name !== expectedName) {
-      errors.push(`XDR frontmatter name must be "${expectedName}": ${toDisplayPath(filePath)}`);
+      errors.push(`Policy frontmatter name must be "${expectedName}": ${toDisplayPath(filePath)}`);
     }
     if (fm.name.length > 64) {
-      errors.push(`XDR frontmatter name must be 64 characters or fewer: ${toDisplayPath(filePath)}`);
+      errors.push(`Policy frontmatter name must be 64 characters or fewer: ${toDisplayPath(filePath)}`);
     }
   }
   if (!fm.description) {
-    errors.push(`XDR frontmatter must include a non-empty description field: ${toDisplayPath(filePath)}`);
+    errors.push(`Policy frontmatter must include a non-empty description field: ${toDisplayPath(filePath)}`);
   } else if (fm.descriptionText && fm.descriptionText.length > 1024) {
-    errors.push(`XDR frontmatter description must be 1024 characters or fewer: ${toDisplayPath(filePath)}`);
+    errors.push(`Policy frontmatter description must be 1024 characters or fewer: ${toDisplayPath(filePath)}`);
   }
   if (fm.validFrom !== undefined) {
     if (!isIsoDate(fm.validFrom)) {
-      errors.push(`XDR frontmatter valid-from must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(filePath)}`);
+      errors.push(`Policy frontmatter valid-from must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(filePath)}`);
     }
   }
   if (fm.appliedTo !== undefined) {
     const words = countWords(fm.appliedTo);
     if (words === 0) {
-      errors.push(`XDR frontmatter apply-to must not be empty: ${toDisplayPath(filePath)}`);
+      errors.push(`Policy frontmatter apply-to must not be empty: ${toDisplayPath(filePath)}`);
     } else if (words >= 40) {
-      errors.push(`XDR frontmatter apply-to must be under 40 words: ${toDisplayPath(filePath)}`);
+      errors.push(`Policy frontmatter apply-to must be under 40 words: ${toDisplayPath(filePath)}`);
     }
   }
   for (const key of fm.topLevelKeys) {
-    if (!XDR_ALLOWED_FRONTMATTER_KEYS.has(key)) {
-      errors.push(`XDR frontmatter has unknown field "${key}": ${toDisplayPath(filePath)}`);
+    if (!POLICY_ALLOWED_FRONTMATTER_KEYS.has(key)) {
+      errors.push(`Policy frontmatter has unknown field "${key}": ${toDisplayPath(filePath)}`);
     }
   }
 }
@@ -472,8 +472,10 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       if (!skillFm.name) {
         errors.push(`SKILL.md frontmatter must include a non-empty name field: ${toDisplayPath(skillFilePath)}`);
       } else {
-        if (skillFm.name !== entry.name) {
-          errors.push(`Skill frontmatter name must match package directory "${entry.name}": ${toDisplayPath(skillFilePath)}`);
+        const typeId = TYPE_TO_ID[typeName].split('-')[0]; // 'adr', 'bdr', or 'edr'
+        const expectedSkillName = `${scopeName}-${typeId}-skill-${number}-${match[2]}`;
+        if (skillFm.name !== expectedSkillName) {
+          errors.push(`Skill frontmatter name must be "${expectedSkillName}": ${toDisplayPath(skillFilePath)}`);
         }
         if (skillFm.name.length > 64) {
           errors.push(`SKILL.md frontmatter name must be 64 characters or fewer: ${toDisplayPath(skillFilePath)}`);
@@ -537,7 +539,8 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
     }
 
     const content = fs.readFileSync(entryPath, 'utf8');
-    const expectedHeader = `# ${scopeName}-article-${number}:`;
+    const typeId = TYPE_TO_ID[typeName].split('-')[0]; // 'adr', 'bdr', or 'edr'
+    const expectedHeader = `# ${scopeName}-${typeId}-article-${number}:`;
     const firstLine = firstNonEmptyLine(content);
     if (!firstLine.startsWith(expectedHeader)) {
       errors.push(`Article title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
@@ -591,7 +594,8 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
     }
 
     const content = fs.readFileSync(entryPath, 'utf8');
-    const expectedHeader = `# ${scopeName}-research-${number}:`;
+    const typeId = TYPE_TO_ID[typeName].split('-')[0]; // 'adr', 'bdr', or 'edr'
+    const expectedHeader = `# ${scopeName}-${typeId}-research-${number}:`;
     const firstLine = firstNonEmptyLine(content);
     if (!firstLine.startsWith(expectedHeader)) {
       errors.push(`Research title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
@@ -646,7 +650,8 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
     }
 
     const content = fs.readFileSync(entryPath, 'utf8');
-    const expectedHeader = `# ${scopeName}-plan-${number}:`;
+    const typeId = TYPE_TO_ID[typeName].split('-')[0]; // 'adr', 'bdr', or 'edr'
+    const expectedHeader = `# ${scopeName}-${typeId}-plan-${number}:`;
     const firstLine = firstNonEmptyLine(content);
     if (!firstLine.startsWith(expectedHeader)) {
       errors.push(`Plan title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
@@ -709,7 +714,7 @@ function lintResearchIntroductionQuestion(content, filePath, errors) {
   }
 }
 
-const XDR_REQUIRED_SECTIONS = ['## Context and Problem Statement', '## Decision Outcome'];
+const XDRS_REQUIRED_SECTIONS = ['## Context and Problem Statement', '## Decision Outcome'];
 const ARTICLE_REQUIRED_SECTIONS = ['## Overview', '## Content', '## References'];
 const RESEARCH_REQUIRED_SECTIONS = ['## Abstract', '## Introduction', '## Methods', '## Results', '## Discussion', '## Conclusion', '## References'];
 const PLAN_REQUIRED_SECTIONS = ['## Executive Summary', '## Context and Problem Statement', '## Proposed Solution'];