xdrs-core 0.18.0 → 0.20.0

package/lib/lint.js

@@ -22,7 +22,7 @@ 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 SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches', 'plans']);
-const RESOURCE_DIR_NAME = 'assets';
+const RESOURCE_DIR_NAME = '.assets';
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp']);
 
 function runLintCli(args) {
@@ -34,7 +34,7 @@ function runLintCli(args) {
   const all = args.includes('--all');
   const pathArgs = args.filter((a) => !a.startsWith('--'));
   const targetPath = pathArgs[0] || '.';
-  const result = lintWorkspace(targetPath, { ignoreReadOnly: !all });
+  const result = lintWorkspace(targetPath, { ignoreExternal: !all });
 
   if (result.errors.length === 0) {
     console.log(`Lint passed for ${toDisplayPath(result.xdrsRoot)}`);
@@ -53,12 +53,12 @@ function printHelp() {
   console.log('Usage: xdrs-core lint [options] [path]\n');
   console.log('Lint the XDR tree rooted at [path]/.xdrs or at [path] when [path] already points to .xdrs.');
   console.log('\nOptions:');
-  console.log('  --all    Check all files, including read-only files from other scopes (default: skip read-only files)');
+  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 lintWorkspace(targetPath, options = {}) {
-  const { ignoreReadOnly = true } = options;
+  const { ignoreExternal = true } = options;
   const resolvedTarget = path.resolve(targetPath);
   const xdrsRoot = path.basename(resolvedTarget) === '.xdrs'
     ? resolvedTarget
@@ -70,6 +70,10 @@ function lintWorkspace(targetPath, options = {}) {
     return { xdrsRoot, errors };
   }
 
+  const repoRoot = path.dirname(xdrsRoot);
+  const filedistPaths = loadFiledist(repoRoot);
+  const externalScopes = getExternalScopes(filedistPaths, xdrsRoot);
+
   const actualTypeIndexes = [];
   const rootEntries = safeReadDir(xdrsRoot, errors, 'read XDR root directory');
   const scopeEntries = rootEntries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'));
@@ -81,7 +85,7 @@ function lintWorkspace(targetPath, options = {}) {
   }
 
   for (const scopeEntry of scopeEntries) {
-    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes, ignoreReadOnly);
+    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes, ignoreExternal, externalScopes);
   }
 
   const rootIndexPath = path.join(xdrsRoot, 'index.md');
@@ -109,8 +113,8 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors) {
     }
   }
 
-  const linkedTypeIndexes = links.filter((linkPath) => isCanonicalTypeIndex(linkPath, xdrsRoot));
-  const linkedSet = new Set(linkedTypeIndexes.map(normalizePath));
+  const linkedScopeIndexes = links.filter((linkPath) => isScopeIndex(linkPath, xdrsRoot));
+  const linkedSet = new Set(linkedScopeIndexes.map(normalizePath));
   const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
 
   for (const linkPath of links) {
@@ -119,21 +123,46 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors) {
     }
   }
 
+  // Collect non-_local scopes that have type indexes and check their scope index is linked
+  const scopesWithTypeIndexes = new Set();
   for (const indexPath of actualTypeIndexes) {
     const scopeName = path.basename(path.dirname(path.dirname(indexPath)));
-    if (scopeName === '_local') {
-      continue;
+    if (scopeName !== '_local') {
+      scopesWithTypeIndexes.add(scopeName);
+    }
+  }
+
+  for (const scopeName of scopesWithTypeIndexes) {
+    const scopeIndexPath = normalizePath(path.join(xdrsRoot, scopeName, 'index.md'));
+    if (!linkedSet.has(scopeIndexPath)) {
+      errors.push(`Root index is missing scope index link: ${toDisplayPath(path.join(xdrsRoot, scopeName, 'index.md'))}`);
+    }
+  }
+}
+
+function lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope, errors) {
+  const content = fs.readFileSync(scopeIndexPath, 'utf8');
+  const repoRoot = path.dirname(xdrsRoot);
+  const links = parseLocalLinks(content, path.dirname(scopeIndexPath), repoRoot);
+  const linkedSet = new Set(links.map(normalizePath));
+
+  for (const linkPath of links) {
+    if (!fs.existsSync(linkPath)) {
+      errors.push(`Broken link in scope index: ${displayPath(scopeIndexPath, linkPath)}`);
     }
-    if (!linkedSet.has(normalizePath(indexPath))) {
-      errors.push(`Root index is missing canonical index link: ${toDisplayPath(indexPath)}`);
+  }
+
+  for (const typeIndexPath of typeIndexesInScope) {
+    if (!linkedSet.has(normalizePath(typeIndexPath))) {
+      errors.push(`Scope index ${toDisplayPath(scopeIndexPath)} is missing link to type index: ${toDisplayPath(typeIndexPath)}`);
     }
   }
 }
 
-function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, ignoreReadOnly) {
+function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, ignoreExternal, externalScopes) {
   const scopePath = path.join(xdrsRoot, scopeName);
 
-  if (ignoreReadOnly && isReadOnly(scopePath)) {
+  if (ignoreExternal && externalScopes.has(scopeName)) {
     return;
   }
 
@@ -141,6 +170,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, igno
     errors.push(`Invalid scope name: ${toDisplayPath(scopePath)}`);
   }
 
+  const typeIndexesInScope = [];
   const entries = safeReadDir(scopePath, errors, `read scope directory ${scopeName}`);
   for (const entry of entries) {
     const entryPath = path.join(scopePath, entry.name);
@@ -149,15 +179,30 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, igno
         errors.push(`Unexpected directory under scope ${scopeName}: ${toDisplayPath(entryPath)}`);
         continue;
       }
-      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, actualTypeIndexes, ignoreReadOnly);
+      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, actualTypeIndexes);
+      const typeIndexPath = path.join(entryPath, 'index.md');
+      if (existsFile(typeIndexPath)) {
+        typeIndexesInScope.push(typeIndexPath);
+      }
+      continue;
+    }
+
+    if (entry.name === 'index.md') {
       continue;
     }
 
     errors.push(`Unexpected file under scope ${scopeName}: ${toDisplayPath(entryPath)}`);
   }
+
+  const scopeIndexPath = path.join(scopePath, 'index.md');
+  if (!existsFile(scopeIndexPath)) {
+    errors.push(`Missing required scope index: ${toDisplayPath(scopeIndexPath)}`);
+  } else {
+    lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope, errors);
+  }
 }
 
-function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeIndexes, ignoreReadOnly) {
+function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeIndexes) {
   const typePath = path.join(xdrsRoot, scopeName, typeName);
   const indexPath = path.join(typePath, 'index.md');
   const xdrNumbers = new Map();
@@ -165,7 +210,7 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeInde
 
   if (!existsFile(indexPath)) {
     errors.push(`Missing canonical index: ${toDisplayPath(indexPath)}`);
-  } else if (!shouldSkipReadOnlyPath(indexPath, ignoreReadOnly)) {
+  } else {
     actualTypeIndexes.push(indexPath);
   }
 
@@ -184,15 +229,15 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeInde
       continue;
     }
 
-    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrNumbers, errors, ignoreReadOnly));
+    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrNumbers, errors));
   }
 
-  if (existsFile(indexPath) && !shouldSkipReadOnlyPath(indexPath, ignoreReadOnly)) {
+  if (existsFile(indexPath)) {
     lintTypeIndex(indexPath, xdrsRoot, artifacts, errors);
   }
 }
 
-function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNumbers, errors, ignoreReadOnly) {
+function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNumbers, errors) {
   const subjectPath = path.join(xdrsRoot, scopeName, typeName, subjectName);
   const artifacts = [];
   const entries = safeReadDir(subjectPath, errors, `read subject directory ${scopeName}/${typeName}/${subjectName}`);
@@ -205,19 +250,19 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
         continue;
       }
       if (entry.name === 'skills') {
-        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
+        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
       }
       if (entry.name === 'articles') {
-        artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
+        artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
       }
       if (entry.name === 'researches') {
-        artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
+        artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
       }
       if (entry.name === 'plans') {
-        artifacts.push(...lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
+        artifacts.push(...lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
       }
 
@@ -230,14 +275,14 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
       continue;
     }
 
-    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
-      continue;
-    }
-
     artifacts.push(entryPath);
     lintXdrFile(xdrsRoot, scopeName, typeName, entryPath, xdrNumbers, errors);
   }
 
+  const subjectAssetsDir = path.join(subjectPath, RESOURCE_DIR_NAME);
+  const xdrDocsInSubject = artifacts.filter((p) => path.dirname(p) === subjectPath);
+  lintOrphanAssets(subjectAssetsDir, xdrDocsInSubject, xdrsRoot, errors);
+
   return artifacts;
 }
 
@@ -327,7 +372,7 @@ function lintXdrFrontmatter(content, expectedName, filePath, errors) {
   }
 }
 
-function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors, ignoreReadOnly) {
+function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors) {
   const artifacts = [];
   const skillNumbers = new Map();
   const entries = safeReadDir(skillsPath, errors, `read skills directory ${scopeName}/${typeName}/${subjectName}/skills`);
@@ -364,10 +409,6 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       continue;
     }
 
-    if (shouldSkipReadOnlyPath(skillFilePath, ignoreReadOnly)) {
-      continue;
-    }
-
     artifacts.push(skillFilePath);
 
     const skillContent = fs.readFileSync(skillFilePath, 'utf8');
@@ -386,12 +427,13 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
     }
 
     lintDocumentLinks(skillFilePath, xdrsRoot, scopeName, errors);
+    lintOrphanAssets(path.join(entryPath, RESOURCE_DIR_NAME), [skillFilePath], xdrsRoot, errors);
   }
 
   return artifacts;
 }
 
-function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, articlesPath, errors, ignoreReadOnly) {
+function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, articlesPath, errors) {
   const artifacts = [];
   const articleNumbers = new Map();
   const entries = safeReadDir(articlesPath, errors, `read articles directory ${scopeName}/${typeName}/${subjectName}/articles`);
@@ -413,10 +455,6 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
       continue;
     }
 
-    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
-      continue;
-    }
-
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -441,10 +479,12 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
     lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
+  lintOrphanAssets(path.join(articlesPath, RESOURCE_DIR_NAME), artifacts, xdrsRoot, errors);
+
   return artifacts;
 }
 
-function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, researchPath, errors, ignoreReadOnly) {
+function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, researchPath, errors) {
   const artifacts = [];
   const researchNumbers = new Map();
   const entries = safeReadDir(researchPath, errors, `read research directory ${scopeName}/${typeName}/${subjectName}/researches`);
@@ -466,10 +506,6 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
       continue;
     }
 
-    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
-      continue;
-    }
-
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -494,10 +530,12 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
     lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
+  lintOrphanAssets(path.join(researchPath, RESOURCE_DIR_NAME), artifacts, xdrsRoot, errors);
+
   return artifacts;
 }
 
-function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPath, errors, ignoreReadOnly) {
+function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPath, errors) {
   const artifacts = [];
   const planNumbers = new Map();
   const entries = safeReadDir(plansPath, errors, `read plans directory ${scopeName}/${typeName}/${subjectName}/plans`);
@@ -519,10 +557,6 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
       continue;
     }
 
-    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
-      continue;
-    }
-
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -548,6 +582,8 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
     lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
+  lintOrphanAssets(path.join(plansPath, RESOURCE_DIR_NAME), artifacts, xdrsRoot, errors);
+
   return artifacts;
 }
 
@@ -599,6 +635,46 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   }
 }
 
+function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
+  if (!existsDirectory(assetsDir)) {
+    return;
+  }
+
+  const entries = safeReadDir(assetsDir, errors, `read assets directory ${toDisplayPath(assetsDir)}`);
+  if (entries.length === 0) {
+    return;
+  }
+
+  const assetFiles = entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => normalizePath(path.join(assetsDir, entry.name)));
+
+  if (assetFiles.length === 0) {
+    return;
+  }
+
+  const repoRoot = path.dirname(xdrsRoot);
+  const referencedAssets = new Set();
+
+  for (const docPath of documentPaths) {
+    if (!existsFile(docPath)) {
+      continue;
+    }
+    const content = fs.readFileSync(docPath, 'utf8');
+    const docDir = path.dirname(docPath);
+    const links = parseLocalLinks(content, docDir, repoRoot);
+    for (const linkPath of links) {
+      referencedAssets.add(normalizePath(linkPath));
+    }
+  }
+
+  for (const assetPath of assetFiles) {
+    if (!referencedAssets.has(assetPath)) {
+      errors.push(`Orphan asset file not referenced by any document: ${toDisplayPath(assetPath)}`);
+    }
+  }
+}
+
 function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors) {
   const lines = fs.readFileSync(documentPath, 'utf8').split(/\r?\n/);
   const ignoredLines = findIgnoredMarkdownLines(lines);
@@ -693,6 +769,11 @@ function isCanonicalTypeIndex(filePath, xdrsRoot) {
   return relative.length === 3 && TYPE_NAMES.has(relative[1]) && relative[2] === 'index.md';
 }
 
+function isScopeIndex(filePath, xdrsRoot) {
+  const relative = relativeFrom(xdrsRoot, filePath).split(path.sep);
+  return relative.length === 2 && relative[1] === 'index.md';
+}
+
 function shouldValidateResourceLink(rawTarget) {
   const normalizedTargetPath = normalizeLocalLinkTarget(rawTarget);
   if (!normalizedTargetPath) {
@@ -857,17 +938,38 @@ function existsFile(filePath) {
   }
 }
 
-function isReadOnly(filePath) {
-  try {
-    fs.accessSync(filePath, fs.constants.W_OK);
-    return false;
-  } catch {
-    return true;
+function loadFiledist(repoRoot) {
+  const filedistPath = path.join(repoRoot, '.filedist');
+  if (!existsFile(filedistPath)) {
+    return new Set();
   }
+  const content = fs.readFileSync(filedistPath, 'utf8');
+  const paths = new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const parts = trimmed.split('|');
+    if (parts.length >= 2) {
+      paths.add(normalizePath(path.join(repoRoot, parts[0])));
+    }
+  }
+  return paths;
 }
 
-function shouldSkipReadOnlyPath(filePath, ignoreReadOnly) {
-  return ignoreReadOnly && isReadOnly(filePath);
+function getExternalScopes(filedistPaths, xdrsRoot) {
+  const externalScopes = new Set();
+  for (const filePath of filedistPaths) {
+    const relative = path.relative(xdrsRoot, filePath);
+    if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+      const parts = relative.split(path.sep);
+      if (parts.length >= 1 && parts[0]) {
+        externalScopes.add(parts[0]);
+      }
+    }
+  }
+  return externalScopes;
 }
 
 function displayPath(indexPath, targetPath) {