xdrs-core 0.32.0 → 0.34.2

package/lib/lint.js

@@ -18,7 +18,6 @@ const ALLOWED_SUBJECTS = {
 
 const TYPE_NAMES = new Set(Object.keys(TYPE_TO_ID));
 const RESERVED_SCOPES = new Set(['_core', '_local']);
-const SCOPE_TYPE_NAMES = new Set(['core', 'reference', 'platform', 'domain', '_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 scopes listed last override the ones listed first';
@@ -28,7 +27,7 @@ const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_D
 
 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 SCOPE_INDEX_ALLOWED_FRONTMATTER_KEYS = new Set(['scope-type', 'name', 'description', 'apply-to', 'valid-from', 'license', 'metadata', 'follows']);
+const SCOPE_INDEX_ALLOWED_FRONTMATTER_KEYS = new Set(['scope-type', 'name', 'description', 'apply-to', 'valid-from', 'license', 'metadata', 'follows', 'related-scopes']);
 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;
@@ -100,6 +99,42 @@ function lintWorkspace(targetPath, options = {}) {
   const rootEntries = safeReadDir(xdrsRoot, errors, 'read XDRS root directory');
   const scopeEntries = rootEntries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'));
 
+  // Pass 1: collect all core-type scopes by reading index.md directly (bypasses external-skip)
+  const coreScopes = [];
+  for (const scopeEntry of scopeEntries) {
+    const scopeIndexPath = path.join(xdrsRoot, scopeEntry.name, 'index.md');
+    if (!existsFile(scopeIndexPath)) continue;
+    const content = fs.readFileSync(scopeIndexPath, 'utf8');
+    const scopeTypeMatch = content.match(/^scope-type:\s*(.+)$/m);
+    if (scopeTypeMatch && scopeTypeMatch[1].trim() === 'core') {
+      coreScopes.push(path.join(xdrsRoot, scopeEntry.name));
+    }
+  }
+
+  // Pass 2: collect known scope-type names from NNN-{scope-type}-scope-type.md files in core scopes
+  const knownScopeTypes = new Map(); // scopeTypeName -> filePath
+  for (const coreScopePath of coreScopes) {
+    for (const typeName of Object.keys(TYPE_TO_ID)) {
+      const principlesDir = path.join(coreScopePath, typeName, 'principles');
+      if (!existsDirectory(principlesDir)) continue;
+      let principlesEntries;
+      try { principlesEntries = fs.readdirSync(principlesDir, { withFileTypes: true }); } catch { continue; }
+      for (const entry of principlesEntries) {
+        if (!entry.isFile()) continue;
+        const m = entry.name.match(NUMBERED_FILE_RE);
+        if (!m) continue;
+        const shortTitle = m[2];
+        if (!shortTitle.endsWith('-scope-type')) continue;
+        const rawTypeName = shortTitle.slice(0, -'-scope-type'.length);
+        // Special-case: 'local' maps to '_local' (underscore not allowed in NUMBERED_FILE_RE)
+        const scopeTypeName = rawTypeName === 'local' ? '_local' : rawTypeName;
+        if (!knownScopeTypes.has(scopeTypeName)) {
+          knownScopeTypes.set(scopeTypeName, path.join(principlesDir, entry.name));
+        }
+      }
+    }
+  }
+
   for (const entry of rootEntries) {
     if (entry.isFile() && entry.name !== 'index.md') {
       errors.push(`Unexpected file at .xdrs root: ${entry.name}`);
@@ -107,7 +142,7 @@ function lintWorkspace(targetPath, options = {}) {
   }
 
   for (const scopeEntry of scopeEntries) {
-    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes, ignoreExternal, effectiveExternalScopes);
+    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes, ignoreExternal, effectiveExternalScopes, knownScopeTypes);
   }
 
   const rootIndexPath = path.join(xdrsRoot, 'index.md');
@@ -183,7 +218,23 @@ function lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope,
   }
 }
 
-function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot) {
+/**
+ * Parse a scope-type policy file for a NN-parent-scope-type rule and return the parent type name.
+ * Returns null if no parent is declared or the file cannot be read.
+ */
+function extractParentScopeType(policyFilePath) {
+  let content;
+  try { content = fs.readFileSync(policyFilePath, 'utf8'); } catch { return null; }
+  // Find a rule heading like "#### NN-parent-scope-type"
+  const headingMatch = content.match(/^#{4}\s+\d+-parent-scope-type\s*$/m);
+  if (!headingMatch) return null;
+  // Extract text after the heading until the next heading or end of file
+  const afterHeading = content.slice(content.indexOf(headingMatch[0]) + headingMatch[0].length);
+  const bodyMatch = afterHeading.match(/`([a-z0-9-]+)`/);
+  return bodyMatch ? bodyMatch[1] : null;
+}
+
+function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes = new Map()) {
   const content = fs.readFileSync(scopeIndexPath, 'utf8');
   const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
   if (!fmMatch) {
@@ -205,10 +256,28 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot)
     errors.push(`Scope index frontmatter must include a scope-type field: ${toDisplayPath(scopeIndexPath)}`);
     return;
   }
-  if (!SCOPE_TYPE_NAMES.has(scopeType)) {
-    errors.push(`Scope index scope-type must be one of [${[...SCOPE_TYPE_NAMES].join(', ')}]: ${toDisplayPath(scopeIndexPath)}`);
+  if (!knownScopeTypes.has(scopeType) && scopeType !== '_local') {
+    errors.push(`Scope index scope-type "${scopeType}" has no corresponding ${scopeType}-scope-type policy in the principles subject of any core-type scope: ${toDisplayPath(scopeIndexPath)}`);
     return;
   }
+  // Validate inheritance chain: ensure all ancestors exist in knownScopeTypes
+  if (scopeType !== '_local') {
+    const visited = new Set([scopeType]);
+    let currentType = scopeType;
+    while (currentType) {
+      const policyPath = knownScopeTypes.get(currentType);
+      if (!policyPath) break;
+      const parentType = extractParentScopeType(policyPath);
+      if (!parentType) break;
+      if (visited.has(parentType)) break; // cycle detected
+      if (!knownScopeTypes.has(parentType)) {
+        errors.push(`Scope type "${currentType}" declares parent "${parentType}" but no ${parentType}-scope-type policy exists in any core-type scope: ${toDisplayPath(scopeIndexPath)}`);
+        break;
+      }
+      visited.add(parentType);
+      currentType = parentType;
+    }
+  }
   if (scopeName === '_core' && scopeType !== 'core') {
     errors.push(`Scope "_core" must have scope-type "core": ${toDisplayPath(scopeIndexPath)}`);
   }
@@ -236,8 +305,8 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot)
 
   if (!fm.description) {
     errors.push(`Scope index frontmatter must include a non-empty description field: ${toDisplayPath(scopeIndexPath)}`);
-  } else if (fm.descriptionText && fm.descriptionText.length > 1024) {
-    errors.push(`Scope index frontmatter description must be 1024 characters or fewer: ${toDisplayPath(scopeIndexPath)}`);
+  } else if (fm.descriptionText && countWords(fm.descriptionText) > 40) {
+    errors.push(`Scope index frontmatter description must be 40 words or fewer: ${toDisplayPath(scopeIndexPath)}`);
   }
 
   if (!fm.appliedTo) {
@@ -246,8 +315,8 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot)
     const words = countWords(fm.appliedTo);
     if (words === 0) {
       errors.push(`Scope index frontmatter apply-to must not be empty: ${toDisplayPath(scopeIndexPath)}`);
-    } else if (words >= 40) {
-      errors.push(`Scope index frontmatter apply-to must be under 40 words: ${toDisplayPath(scopeIndexPath)}`);
+    } else if (words > 30) {
+      errors.push(`Scope index frontmatter apply-to must be 30 words or fewer: ${toDisplayPath(scopeIndexPath)}`);
     }
   }
 
@@ -298,16 +367,74 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot)
         }
         return items;
       })();
+      for (const entry of entries) {
+        if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(entry)) {
+          const followedIndexPath = path.join(xdrsRoot, entry, 'index.md');
+          if (!existsFile(followedIndexPath)) {
+            errors.push(`Scope index frontmatter follows references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)}`);
+          } else {
+            const followedContent = fs.readFileSync(followedIndexPath, 'utf8');
+            const followedTypeMatch = followedContent.match(/^scope-type:\s*(.+)$/m);
+            if (!followedTypeMatch || followedTypeMatch[1].trim() !== 'core') {
+              errors.push(`Scope index frontmatter follows references scope "${entry}" which is not a core-type scope: ${toDisplayPath(scopeIndexPath)}`);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const relatedScopesLineMatch = block.match(/^related-scopes:[ \t]*(.*)/m);
+  if (relatedScopesLineMatch !== null) {
+    const relatedScopesValue = relatedScopesLineMatch[1].trim();
+    const scopeNamePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+    if (relatedScopesValue) {
+      if (!scopeNamePattern.test(relatedScopesValue)) {
+        errors.push(`Scope index frontmatter related-scopes must be a scope name or list of scope names: ${toDisplayPath(scopeIndexPath)}`);
+      }
+    } else {
+      const relatedScopesStart = block.indexOf(relatedScopesLineMatch[0]) + relatedScopesLineMatch[0].length;
+      const listItems = [];
+      let hasInvalidEntry = false;
+      for (const line of block.slice(relatedScopesStart).split('\n')) {
+        const itemMatch = line.match(/^\s+-\s*(\S.*)?$/);
+        if (itemMatch) {
+          const item = (itemMatch[1] || '').trim();
+          if (!item || !scopeNamePattern.test(item)) {
+            errors.push(`Scope index frontmatter related-scopes entries must be non-empty scope names: ${toDisplayPath(scopeIndexPath)}`);
+            hasInvalidEntry = true;
+            break;
+          }
+          listItems.push(item);
+        } else if (line.trim() && !/^\s/.test(line)) {
+          break;
+        }
+      }
+      if (!hasInvalidEntry && listItems.length === 0) {
+        errors.push(`Scope index frontmatter related-scopes must be a scope name or list of scope names: ${toDisplayPath(scopeIndexPath)}`);
+      }
+    }
+    if (xdrsRoot) {
+      const entries = relatedScopesValue ? [relatedScopesValue] : (() => {
+        const items = [];
+        const relatedScopesStart = block.indexOf(relatedScopesLineMatch[0]) + relatedScopesLineMatch[0].length;
+        for (const line of block.slice(relatedScopesStart).split('\n')) {
+          const itemMatch = line.match(/^\s+-\s*(\S.*)?$/);
+          if (itemMatch && itemMatch[1]) items.push(itemMatch[1].trim());
+          else if (line.trim() && !/^\s/.test(line)) break;
+        }
+        return items;
+      })();
       for (const entry of entries) {
         if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(entry) && !existsFile(path.join(xdrsRoot, entry, 'index.md'))) {
-          errors.push(`Scope index frontmatter follows references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)}`);
+          errors.push(`Scope index frontmatter related-scopes references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)}`);
         }
       }
     }
   }
 }
 
-function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, ignoreExternal, externalScopes) {
+function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, ignoreExternal, externalScopes, knownScopeTypes = new Map()) {
   const scopePath = path.join(xdrsRoot, scopeName);
 
   if (ignoreExternal && externalScopes.has(scopeName)) {
@@ -347,7 +474,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, igno
     errors.push(`Missing required scope index: ${toDisplayPath(scopeIndexPath)}`);
   } else {
     lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope, errors, externalScopes);
-    lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot);
+    lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes);
   }
 }