xdrs-core 0.37.2 → 0.38.0

package/lib/lint.test.js

@@ -116,7 +116,7 @@ test('skips broken links to missing scope directories when ignoring external sco
   const result = lintWorkspace(workspaceRoot);
 
   expect(result.errors.join('\n')).not.toContain('Broken local link in');
-  expect(result.errors.join('\n')).not.toContain('_core');
+  expect(result.errors.join('\n')).not.toContain('_core/adrs');
 });
 
 test('skips entire external scope when only some of its files are in filedist', () => {
@@ -1341,7 +1341,7 @@ test('reports invalid follows value in scope index frontmatter', () => {
   expect(result.errors.join('\n')).toContain('Scope index frontmatter follows must be a core scope name or list of core scope names');
 });
 
-test('reports follows scope that does not exist in workspace', () => {
+test('marks scope as read-only when follows references a -core scope not in workspace', () => {
   const workspaceRoot = createWorkspace('follows-missing-scope', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
     '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nfollows: nonexistent-core\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
@@ -1351,7 +1351,8 @@ test('reports follows scope that does not exist in workspace', () => {
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).toContain('follows references scope "nonexistent-core" which does not exist in the workspace');
+  expect(result.errors.join('\n')).not.toContain('follows references scope "nonexistent-core" which does not exist in the workspace');
+  expect(result.readOnlyScopes.has('myteam')).toBe(true);
 });
 
 test('accepts follows scope that exists in workspace', () => {
@@ -2550,4 +2551,268 @@ function planDocument(body) {
     'Expected end date: 2026-12-31',
     ''
   ].join('\n');
-}
+}
+
+// ─── Tests for Phase 1 new checks ────────────────────────────────────────────
+
+test('reports root index linking directly to a type index', () => {
+  const workspaceRoot = createWorkspace('root-index-type-link', {
+    '.xdrs/index.md': [
+      '# XDRS Index',
+      '',
+      '## Scope Indexes',
+      '',
+      'XDRS scopes listed last override the ones listed first',
+      '',
+      '[_local ADRs](_local/adrs/index.md)',
+      '',
+      '### _local (reserved)',
+      '',
+      'Read _local scope index at `_local/index.md` when it exists.',
+    ].join('\n'),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([]),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Root index must not link directly to type indexes');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-001]');
+});
+
+test('does not report root index linking to scope indexes', () => {
+  const workspaceRoot = createWorkspace('root-index-scope-link-ok', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([]),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Root index must not link directly to type indexes');
+});
+
+test('reports parent document missing link to its slide file', () => {
+  const workspaceRoot = createWorkspace('parent-missing-slide-link', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-guide](principles/articles/001-guide.md) - Guide'
+    ]),
+    '.xdrs/_local/adrs/principles/articles/001-guide.md': articleDocument('No link to slide here.'),
+    '.xdrs/_local/adrs/principles/articles/.assets/001-guide-slides.md': slideDocument('[Parent](../001-guide.md)'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Parent document must contain a link to its slide file');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-009]');
+});
+
+test('does not report parent document when it links to its slide file', () => {
+  const workspaceRoot = createWorkspace('parent-has-slide-link', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-guide](principles/articles/001-guide.md) - Guide'
+    ]),
+    '.xdrs/_local/adrs/principles/articles/001-guide.md': articleDocument('Body.\n\n[Slides](.assets/001-guide-slides.md)'),
+    '.xdrs/_local/adrs/principles/articles/.assets/001-guide-slides.md': slideDocument('[Parent](../001-guide.md)'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Parent document must contain a link to its slide file');
+});
+
+test('reports structured rule block with non-two-digit number', () => {
+  const workspaceRoot = createWorkspace('structured-rule-bad-number', {
+    '.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([
+      '### Details',
+      '',
+      '#### 1-my-rule',
+      '',
+      'This rule MUST be followed.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('structured rule number must be exactly two digits');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.02-rule-numbering-must-be-stable]');
+});
+
+test('reports structured rule block with non-kebab-case title', () => {
+  const workspaceRoot = createWorkspace('structured-rule-bad-title', {
+    '.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([
+      '### Details',
+      '',
+      '#### 01-My Rule Title',
+      '',
+      'This rule MUST be followed.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('structured rule title must be in kebab-case');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.01-always-use-numbered-rules-for-strong-or-referenceable-policies]');
+});
+
+test('reports structured rule block with duplicate rule number', () => {
+  const workspaceRoot = createWorkspace('structured-rule-dup-number', {
+    '.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([
+      '### Details',
+      '',
+      '#### 01-first-rule',
+      '',
+      'This rule MUST be followed.',
+      '',
+      '#### 01-second-rule',
+      '',
+      'This rule MUST also be followed.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Duplicate structured rule number "01"');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.02-rule-numbering-must-be-stable]');
+});
+
+test('reports structured rule block body missing normative language', () => {
+  const workspaceRoot = createWorkspace('structured-rule-no-normative', {
+    '.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([
+      '### Details',
+      '',
+      '#### 01-my-rule',
+      '',
+      'This is a rule without normative keywords.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('structured rule body must contain normative language');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.03-rule-body-must-use-normative-language]');
+});
+
+test('accepts valid structured rule blocks', () => {
+  const workspaceRoot = createWorkspace('structured-rule-valid', {
+    '.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([
+      '### Details',
+      '',
+      '#### 01-my-first-rule',
+      '',
+      'This rule MUST be followed.',
+      '',
+      '#### 02-my-second-rule',
+      '',
+      'Implementors SHOULD consider this.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('structured rule');
+});
+
+test('reports research section exceeding word limit', () => {
+  const body500words = Array(500).fill('word').join(' ');
+  const workspaceRoot = createWorkspace('research-section-over-limit', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-study](principles/researches/001-study.md) - Study'
+    ]),
+    '.xdrs/_local/adrs/principles/researches/001-study.md': researchDocument(
+      'Background text. Question: What is the answer?',
+      null
+    ).replace('Single paragraph abstract.', body500words),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Research ## Abstract section exceeds 200 words');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-006]');
+});
+
+test('accepts research sections within word limits', () => {
+  const workspaceRoot = createWorkspace('research-section-within-limit', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-study](principles/researches/001-study.md) - Study'
+    ]),
+    '.xdrs/_local/adrs/principles/researches/001-study.md': researchDocument(
+      'Background text.',
+      'Question: What is the answer?'
+    ),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('section exceeds');
+});
+
+test('reports policy frontmatter name ending with hyphen', () => {
+  const workspaceRoot = createWorkspace('policy-name-trailing-hyphen', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-my-](principles/001-my-.md) - My decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-my-.md': [
+      '---',
+      'name: _local-adr-policy-001-my-',
+      'description: Test policy',
+      'apply-to: All scopes',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# _local-adr-policy-001: My decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Body.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Decision.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Policy frontmatter name must not end with a hyphen');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-002]');
+});
+
+test('error messages include policy references', () => {
+  const workspaceRoot = createWorkspace('policy-ref-in-errors', {
+    '.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('[_core-adr-policy-');
+  expect(result.errors.every((e) => e.includes('[_core-adr-policy-'))).toBe(true);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.37.2",
+  "version": "0.38.0",
   "description": "A framework to structure, compile and distribute Architectural (ADR), Business (BDR), and Engineering (EDR) decision records contents so that AI agents and humans can reliably find and use them with hierarchical scopes and controlled rollout in the format of distributable versioned packages.",
   "repository": {
     "type": "git",