xdrs-core 0.33.0 → 0.35.0

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';
@@ -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,35 @@ 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 (scopeType.startsWith('_') && scopeType !== '_local') {
+    errors.push(`Scope type "${scopeType}" uses a reserved "_" prefix; only "_local" is a valid underscore-prefixed scope type: ${toDisplayPath(scopeIndexPath)}`);
     return;
   }
+  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)) {
+        errors.push(`Scope type "${currentType}" declares parent "${parentType}" which creates a cycle in the scope-type inheritance chain: ${toDisplayPath(scopeIndexPath)}`);
+        break;
+      }
+      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 +312,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 +322,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)}`);
     }
   }
 
@@ -257,12 +333,14 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot)
     errors.push(`Scope index frontmatter valid-from must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(scopeIndexPath)}`);
   }
 
+  let followsEntries = [];
   const followsLineMatch = block.match(/^follows:[ \t]*(.*)/m);
   if (followsLineMatch !== null) {
     const followsValue = followsLineMatch[1].trim();
     const scopeNamePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+    const commaSeparatedPattern = /^[a-zA-Z_][a-zA-Z0-9_-]*(\s*,\s*[a-zA-Z_][a-zA-Z0-9_-]*)+$/;
     if (followsValue) {
-      if (!scopeNamePattern.test(followsValue)) {
+      if (!scopeNamePattern.test(followsValue) && !commaSeparatedPattern.test(followsValue)) {
         errors.push(`Scope index frontmatter follows must be a core scope name or list of core scope names: ${toDisplayPath(scopeIndexPath)}`);
       }
     } else {
@@ -288,19 +366,46 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot)
       }
     }
     if (xdrsRoot) {
-      const entries = followsValue ? [followsValue] : (() => {
-        const items = [];
-        const followsStart = block.indexOf(followsLineMatch[0]) + followsLineMatch[0].length;
-        for (const line of block.slice(followsStart).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;
-      })();
+      const entries = followsValue
+        ? (commaSeparatedPattern.test(followsValue)
+            ? followsValue.split(',').map((s) => s.trim())
+            : [followsValue])
+        : (() => {
+          const items = [];
+          const followsStart = block.indexOf(followsLineMatch[0]) + followsLineMatch[0].length;
+          for (const line of block.slice(followsStart).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;
+        })();
+      followsEntries = entries;
+      const seenFollows = new Set();
       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)}`);
+        if (seenFollows.has(entry)) {
+          errors.push(`Scope index frontmatter follows has duplicate entry "${entry}": ${toDisplayPath(scopeIndexPath)}`);
+        }
+        seenFollows.add(entry);
+        if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(entry)) {
+          if (entry === scopeName) {
+            errors.push(`Scope index frontmatter follows must not reference the scope itself: ${toDisplayPath(scopeIndexPath)}`);
+            continue;
+          }
+          if (entry === '_core') {
+            errors.push(`Scope index frontmatter follows must not reference "_core" as it is always applied implicitly: ${toDisplayPath(scopeIndexPath)}`);
+            continue;
+          }
+          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)}`);
+            }
+          }
         }
       }
     }
@@ -347,16 +452,31 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot)
         }
         return items;
       })();
+      const seenRelated = new Set();
       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 related-scopes references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)}`);
+        if (seenRelated.has(entry)) {
+          errors.push(`Scope index frontmatter related-scopes has duplicate entry "${entry}": ${toDisplayPath(scopeIndexPath)}`);
+        }
+        seenRelated.add(entry);
+        if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(entry)) {
+          if (entry === scopeName) {
+            errors.push(`Scope index frontmatter related-scopes must not reference the scope itself: ${toDisplayPath(scopeIndexPath)}`);
+            continue;
+          }
+          if (followsEntries.includes(entry)) {
+            errors.push(`Scope index frontmatter related-scopes must not repeat scope "${entry}" already declared in follows: ${toDisplayPath(scopeIndexPath)}`);
+            continue;
+          }
+          if (!existsFile(path.join(xdrsRoot, entry, 'index.md'))) {
+            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)) {
@@ -396,7 +516,35 @@ 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);
+  }
+  lintScopeLocalStandards(xdrsRoot, scopeName, errors);
+}
+
+function lintScopeLocalStandards(xdrsRoot, scopeName, errors) {
+  const scopePath = path.join(xdrsRoot, scopeName);
+  const corePolicySuffix = `${scopeName}-core`;
+  const foundPolicies = [];
+  for (const typeName of Object.keys(TYPE_TO_ID)) {
+    const principlesDir = path.join(scopePath, 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;
+      if (!NUMBERED_FILE_RE.test(entry.name)) continue;
+      const filePath = path.join(principlesDir, entry.name);
+      let content;
+      try { content = fs.readFileSync(filePath, 'utf8'); } catch { continue; }
+      const fm = extractFrontmatter(content);
+      if (fm.name && (fm.name === corePolicySuffix || fm.name.endsWith(`-${corePolicySuffix}`))) {
+        foundPolicies.push(filePath);
+      }
+    }
+  }
+  if (foundPolicies.length > 1) {
+    const paths = foundPolicies.map((p) => toDisplayPath(p)).join(', ');
+    errors.push(`Scope "${scopeName}" has more than one scope-local standards policy (name ending with "${corePolicySuffix}"): ${paths}`);
   }
 }