xdrs-core 0.15.2 → 0.15.4

package/README.md

@@ -153,7 +153,7 @@ Multiple scope packages can be combined in the same workspace by listing them as
 The published package exposes the `xdrs-core` CLI.
 
 - Bootstrap or extract managed XDR files with the existing `filedist`-backed commands such as `npx -y xdrs-core extract` and `npx -y xdrs-core check`.
-- Lint an XDR tree with `npx -y xdrs-core lint .`.
+- Lint an XDR tree with `npx -y xdrs-core lint .`. By default, read-only files distributed from external scopes are skipped; use `--all` to include them.
 
 The `lint` command reads `./.xdrs/**` from the given workspace path and checks common consistency rules, including:
 
@@ -167,6 +167,7 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - canonical index presence and link consistency
 - root index coverage for all discovered canonical indexes
 - XDR metadata section placement and `Valid` / `Applied to` field format
+- local markdown links between XDR documents, skills, articles, researches, and plans (excluding fenced code blocks)
 - local image and `assets/` links resolving inside the sibling `assets/` folder for each document
 
 Examples:

package/lib/lint.js

@@ -148,7 +148,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, igno
         errors.push(`Unexpected directory under scope ${scopeName}: ${toDisplayPath(entryPath)}`);
         continue;
       }
-      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, actualTypeIndexes);
+      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, actualTypeIndexes, ignoreReadOnly);
       continue;
     }
 
@@ -156,7 +156,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, igno
   }
 }
 
-function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeIndexes) {
+function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeIndexes, ignoreReadOnly) {
   const typePath = path.join(xdrsRoot, scopeName, typeName);
   const indexPath = path.join(typePath, 'index.md');
   const xdrNumbers = new Map();
@@ -164,7 +164,7 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeInde
 
   if (!existsFile(indexPath)) {
     errors.push(`Missing canonical index: ${toDisplayPath(indexPath)}`);
-  } else {
+  } else if (!shouldSkipReadOnlyPath(indexPath, ignoreReadOnly)) {
     actualTypeIndexes.push(indexPath);
   }
 
@@ -183,15 +183,15 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeInde
       continue;
     }
 
-    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrNumbers, errors));
+    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrNumbers, errors, ignoreReadOnly));
   }
 
-  if (existsFile(indexPath)) {
+  if (existsFile(indexPath) && !shouldSkipReadOnlyPath(indexPath, ignoreReadOnly)) {
     lintTypeIndex(indexPath, xdrsRoot, artifacts, errors);
   }
 }
 
-function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNumbers, errors) {
+function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNumbers, errors, ignoreReadOnly) {
   const subjectPath = path.join(xdrsRoot, scopeName, typeName, subjectName);
   const artifacts = [];
   const entries = safeReadDir(subjectPath, errors, `read subject directory ${scopeName}/${typeName}/${subjectName}`);
@@ -204,19 +204,19 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
         continue;
       }
       if (entry.name === 'skills') {
-        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
         continue;
       }
       if (entry.name === 'articles') {
-        artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
         continue;
       }
       if (entry.name === 'researches') {
-        artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
         continue;
       }
       if (entry.name === 'plans') {
-        artifacts.push(...lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        artifacts.push(...lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
         continue;
       }
 
@@ -229,6 +229,10 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
       continue;
     }
 
+    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
+      continue;
+    }
+
     artifacts.push(entryPath);
     lintXdrFile(xdrsRoot, scopeName, typeName, entryPath, xdrNumbers, errors);
   }
@@ -244,7 +248,6 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
   }
 
   const number = match[1];
-  const shortTitle = match[2];
   const previous = xdrNumbers.get(number);
   if (previous) {
     errors.push(`Duplicate XDR number ${number} in ${scopeName}/${typeName}: ${toDisplayPath(previous)} and ${toDisplayPath(filePath)}`);
@@ -263,9 +266,35 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
     errors.push(`XDR title must start with "${expectedHeader}": ${toDisplayPath(filePath)}`);
   }
 
-  const expectedName = `${scopeName}-${TYPE_TO_ID[typeName]}-${number}-${shortTitle}`;
+  const expectedName = extractExpectedXdrNameFromHeading(firstLine)
+    || `${scopeName}-${TYPE_TO_ID[typeName]}-${number}-${match[2]}`;
   lintXdrFrontmatter(content, expectedName, filePath, errors);
-  lintDocumentResourceLinks(filePath, errors);
+  lintDocumentLinks(filePath, errors);
+}
+
+function extractExpectedXdrNameFromHeading(headingLine) {
+  const match = headingLine.match(/^#\s+([a-z0-9_]+-(?:adr|bdr|edr)-\d{3,}):\s+(.+?)\s*$/);
+  if (!match) {
+    return null;
+  }
+
+  const identifier = match[1];
+  const titleSlug = slugifyTitle(match[2]);
+  if (!titleSlug) {
+    return null;
+  }
+
+  return `${identifier}-${titleSlug}`;
+}
+
+function slugifyTitle(title) {
+  return title
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/--+/g, '-');
 }
 
 function lintXdrFrontmatter(content, expectedName, filePath, errors) {
@@ -297,7 +326,7 @@ function lintXdrFrontmatter(content, expectedName, filePath, errors) {
   }
 }
 
-function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors) {
+function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors, ignoreReadOnly) {
   const artifacts = [];
   const skillNumbers = new Map();
   const entries = safeReadDir(skillsPath, errors, `read skills directory ${scopeName}/${typeName}/${subjectName}/skills`);
@@ -328,13 +357,18 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
     }
 
     const skillFilePath = path.join(entryPath, 'SKILL.md');
-    artifacts.push(skillFilePath);
 
     if (!existsFile(skillFilePath)) {
       errors.push(`Missing SKILL.md in skill package: ${toDisplayPath(entryPath)}`);
       continue;
     }
 
+    if (shouldSkipReadOnlyPath(skillFilePath, ignoreReadOnly)) {
+      continue;
+    }
+
+    artifacts.push(skillFilePath);
+
     const skillContent = fs.readFileSync(skillFilePath, 'utf8');
     const skillFm = extractFrontmatter(skillContent);
     if (!skillFm.present) {
@@ -350,13 +384,13 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       }
     }
 
-    lintDocumentResourceLinks(skillFilePath, errors);
+    lintDocumentLinks(skillFilePath, errors);
   }
 
   return artifacts;
 }
 
-function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, articlesPath, errors) {
+function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, articlesPath, errors, ignoreReadOnly) {
   const artifacts = [];
   const articleNumbers = new Map();
   const entries = safeReadDir(articlesPath, errors, `read articles directory ${scopeName}/${typeName}/${subjectName}/articles`);
@@ -378,6 +412,10 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
       continue;
     }
 
+    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
+      continue;
+    }
+
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -399,13 +437,13 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
       errors.push(`Article title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
 
-    lintDocumentResourceLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, errors);
   }
 
   return artifacts;
 }
 
-function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, researchPath, errors) {
+function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, researchPath, errors, ignoreReadOnly) {
   const artifacts = [];
   const researchNumbers = new Map();
   const entries = safeReadDir(researchPath, errors, `read research directory ${scopeName}/${typeName}/${subjectName}/researches`);
@@ -427,6 +465,10 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
       continue;
     }
 
+    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
+      continue;
+    }
+
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -448,13 +490,13 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
       errors.push(`Research title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
 
-    lintDocumentResourceLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, errors);
   }
 
   return artifacts;
 }
 
-function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPath, errors) {
+function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPath, errors, ignoreReadOnly) {
   const artifacts = [];
   const planNumbers = new Map();
   const entries = safeReadDir(plansPath, errors, `read plans directory ${scopeName}/${typeName}/${subjectName}/plans`);
@@ -476,6 +518,10 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
       continue;
     }
 
+    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
+      continue;
+    }
+
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -498,7 +544,7 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
     }
 
     lintPlanExpectedEndDate(content, entryPath, errors);
-    lintDocumentResourceLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, errors);
   }
 
   return artifacts;
@@ -545,23 +591,32 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   }
 }
 
-function lintDocumentResourceLinks(documentPath, errors) {
-  const content = fs.readFileSync(documentPath, 'utf8');
+function lintDocumentLinks(documentPath, errors) {
+  const lines = fs.readFileSync(documentPath, 'utf8').split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
   const documentDir = path.dirname(documentPath);
   const resourceDir = path.join(documentDir, RESOURCE_DIR_NAME);
 
-  for (const link of parseLocalLinkTargets(content, documentDir)) {
-    if (!shouldValidateResourceLink(link.rawTarget)) {
+  for (let index = 0; index < lines.length; index += 1) {
+    if (ignoredLines[index]) {
       continue;
     }
 
-    if (!fs.existsSync(link.resolvedPath)) {
-      errors.push(`Broken asset link in ${toDisplayPath(documentPath)}: ${link.rawTarget}`);
-      continue;
-    }
+    for (const link of parseLocalLinkTargets(lines[index], documentDir)) {
+      const isResourceLink = shouldValidateResourceLink(link.rawTarget);
+
+      if (!fs.existsSync(link.resolvedPath)) {
+        if (isResourceLink) {
+          errors.push(`Broken asset link in ${toDisplayPath(documentPath)}: ${link.rawTarget}`);
+        } else {
+          errors.push(`Broken local link in ${toDisplayPath(documentPath)}:${index + 1}: ${link.rawTarget}`);
+        }
+        continue;
+      }
 
-    if (!isPathInside(resourceDir, link.resolvedPath)) {
-      errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget}`);
+      if (isResourceLink && !isPathInside(resourceDir, link.resolvedPath)) {
+        errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget}`);
+      }
     }
   }
 }
@@ -576,11 +631,11 @@ function parseLocalLinkTargets(markdown, baseDir) {
   let match = linkRe.exec(markdown);
   while (match) {
     const rawTarget = match[1].trim();
-    if (isLocalLink(rawTarget)) {
-      const targetWithoutAnchor = rawTarget.split('#')[0];
+    const normalizedTarget = normalizeLocalLinkTarget(rawTarget);
+    if (normalizedTarget) {
       links.push({
         rawTarget,
-        resolvedPath: path.resolve(baseDir, targetWithoutAnchor)
+        resolvedPath: path.resolve(baseDir, normalizedTarget)
       });
     }
     match = linkRe.exec(markdown);
@@ -588,6 +643,17 @@ function parseLocalLinkTargets(markdown, baseDir) {
   return links;
 }
 
+function normalizeLocalLinkTarget(target) {
+  if (!isLocalLink(target)) {
+    return null;
+  }
+
+  const bracketWrappedTarget = target.match(/^<(.+)>$/);
+  const cleanedTarget = bracketWrappedTarget ? bracketWrappedTarget[1] : target;
+
+  return cleanedTarget.split('#')[0].split('?')[0] || null;
+}
+
 function isLocalLink(target) {
   return target !== ''
     && !target.startsWith('#')
@@ -602,9 +668,13 @@ function isCanonicalTypeIndex(filePath, xdrsRoot) {
 }
 
 function shouldValidateResourceLink(rawTarget) {
-  const targetWithoutAnchor = rawTarget.split('#')[0];
-  const normalizedTarget = targetWithoutAnchor.replace(/\\/g, '/');
-  const extension = path.extname(targetWithoutAnchor).toLowerCase();
+  const normalizedTargetPath = normalizeLocalLinkTarget(rawTarget);
+  if (!normalizedTargetPath) {
+    return false;
+  }
+
+  const normalizedTarget = normalizedTargetPath.replace(/\\/g, '/');
+  const extension = path.extname(normalizedTargetPath).toLowerCase();
 
   return normalizedTarget === RESOURCE_DIR_NAME
     || normalizedTarget.startsWith(`${RESOURCE_DIR_NAME}/`)
@@ -638,12 +708,20 @@ function stripFrontmatter(content) {
 function findIgnoredMarkdownLines(lines) {
   const ignored = [];
   let inCodeFence = false;
+  let activeFence = null;
 
   for (let index = 0; index < lines.length; index += 1) {
     const trimmed = lines[index].trim();
-    if (/^```/.test(trimmed)) {
+    const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+    if (fenceMatch) {
       ignored[index] = true;
-      inCodeFence = !inCodeFence;
+      if (activeFence === fenceMatch[1][0]) {
+        activeFence = null;
+        inCodeFence = false;
+      } else if (activeFence === null) {
+        activeFence = fenceMatch[1][0];
+        inCodeFence = true;
+      }
       continue;
     }
 
@@ -762,6 +840,10 @@ function isReadOnly(filePath) {
   }
 }
 
+function shouldSkipReadOnlyPath(filePath, ignoreReadOnly) {
+  return ignoreReadOnly && isReadOnly(filePath);
+}
+
 function displayPath(indexPath, targetPath) {
   return `${toDisplayPath(indexPath)} -> ${toDisplayPath(targetPath)}`;
 }

package/lib/lint.test.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { lintWorkspace } = require('./lint');
+
+let tmpRoot;
+
+beforeAll(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'xdrs-core-lint-'));
+});
+
+afterAll(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+test('reports broken local document links in XDR files', () => {
+  const workspaceRoot = createWorkspace('broken-xdr-link', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument(`See [Missing](002-missing.md).`),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Broken local link in');
+  expect(result.errors.join('\n')).toContain('002-missing.md');
+});
+
+test('ignores local links inside fenced code blocks', () => {
+  const workspaceRoot = createWorkspace('ignore-code-fence', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument([
+      '```markdown',
+      '[Missing](002-missing.md)',
+      '```'
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Broken local link in');
+});
+
+test('reports broken local document links in skill files', () => {
+  const workspaceRoot = createWorkspace('broken-skill-link', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check local links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('See [Missing](missing.md).'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Broken local link in');
+  expect(result.errors.join('\n')).toContain('missing.md');
+});
+
+test('skips read-only files by default and checks them when ignoreReadOnly is false', () => {
+  const workspaceRoot = createWorkspace('readonly-default-skip', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('See [Missing](002-missing.md).'),
+  });
+  const filePath = path.join(workspaceRoot, '.xdrs/_local/adrs/principles/001-main.md');
+  fs.chmodSync(filePath, 0o444);
+
+  const defaultResult = lintWorkspace(workspaceRoot);
+  const allResult = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+
+  expect(defaultResult.errors.join('\n')).not.toContain('Broken local link in');
+  expect(allResult.errors.join('\n')).toContain('Broken local link in');
+});
+
+test('derives expected frontmatter name from the markdown heading title', () => {
+  const workspaceRoot = createWorkspace('heading-name-match', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [002-scope-guidelines](principles/002-xdr-scope-guidelines.md) - Scope guidelines'
+    ]),
+    '.xdrs/_local/adrs/principles/002-xdr-scope-guidelines.md': [
+      '---',
+      'name: _local-adr-002-xdr-scope-guidelines-for-agentme',
+      'description: Test XDR document',
+      '---',
+      '',
+      '# _local-adr-002: XDR scope guidelines for agentme',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Test body.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+
+  expect(result.errors.join('\n')).not.toContain('XDR frontmatter name must be');
+});
+
+function createWorkspace(name, files) {
+  const workspaceRoot = path.join(tmpRoot, name);
+  fs.mkdirSync(workspaceRoot, { recursive: true });
+
+  for (const [relativePath, content] of Object.entries(files)) {
+    const filePath = path.join(workspaceRoot, relativePath);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+  }
+
+  return workspaceRoot;
+}
+
+function rootIndex() {
+  return [
+    '# XDR Standards Index',
+    '',
+    '## Scope Indexes',
+    '',
+    'XDRs in scopes listed last override the ones listed first',
+    '',
+    '### _local (reserved)',
+    '',
+    'Project-local XDRs stay in the workspace tree only.',
+  ].join('\n');
+}
+
+function localAdrIndex(entries) {
+  return [
+    '# _local ADR Index',
+    '',
+    'Local ADRs for tests.',
+    '',
+    '## principles',
+    '',
+    ...entries,
+    ''
+  ].join('\n');
+}
+
+function xdrDocument(body) {
+  return [
+    '---',
+    'name: _local-adr-001-main',
+    'description: Test XDR document',
+    '---',
+    '',
+    '# _local-adr-001: Main decision',
+    '',
+    '## Context and Problem Statement',
+    '',
+    body,
+    ''
+  ].join('\n');
+}
+
+function skillDocument(body) {
+  return [
+    '---',
+    'name: 001-check-links',
+    'description: Test skill document',
+    '---',
+    '',
+    '# Test skill',
+    '',
+    body,
+    ''
+  ].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "description": "A standard way to organize Decision Records (XDRs) across scopes, subjects, and teams so that AI agents can reliably query and follow them.",
   "repository": {
     "type": "git",