@jterrazz/typescript 9.2.0 → 9.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/typescript",
-    "version": "9.2.0",
+    "version": "9.3.0",
     "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
     "repository": {
         "type": "git",

package/src/docs.js

@@ -48,8 +48,14 @@ const JOURNAL_WORDS = new Set([
 /** The closed status vocabulary of a decision record. */
 const STATUSES = new Set(['Proposed', 'Accepted', 'Deprecated']);
 
-/** The fourth status carries the record that replaced it. */
-const SUPERSEDED = /^Superseded by ADR-\d{3}$/;
+/**
+ * The fourth status carries the record that replaced it, as a link a reader
+ * can follow — a citation is a place a human can look, not just a number.
+ */
+const SUPERSEDED = /^Superseded by \[ADR-\d{3}\]\([^)]+\)$/;
+
+/** The same status named but not linked — the successor exists, the citation does not. */
+const BARE_SUPERSEDED = /^Superseded by ADR-\d{3}$/;
 
 /** What a chapter's file name must be: two digits, lowercase words, single hyphens. */
 const CHAPTER_NAME = /^\d{2}-[a-z\d]+(?:-[a-z\d]+)*\.md$/;
@@ -193,12 +199,17 @@ function auditChapters(report, { chapters, ships }) {
     }
 
     const numbers = chapters.map((chapter) => chapter.number).sort((a, b) => a - b);
-    const contiguous = numbers.every((number, index) => number === index + 1);
+    const hasOperating = numbers.includes(4);
+    // 04 is the one number the spine never requires (`docs-operating-missing`
+    // Asks for it on its own terms), so a run missing it is still contiguous —
+    // Every number from 05 on shifts down one slot to close the gap.
+    const expected = (index) => (!hasOperating && index + 1 >= 4 ? index + 2 : index + 1);
+    const contiguous = numbers.every((number, index) => number === expected(index));
     if (numbers.length > 0 && !contiguous) {
         report(
             'docs-chapter-numbering',
             'docs/',
-            `chapter numbers run ${numbers.map(padded).join(', ')}: they are contiguous from 01, one file per number`,
+            `chapter numbers run ${numbers.map(padded).join(', ')}: they are contiguous from 01, one file per number, except that 04 may be absent`,
         );
     }
 
@@ -284,11 +295,11 @@ function auditRecord(report, record, heads) {
 
     const status = head.map((line) => DECISION_STATUS.exec(line)?.groups?.status).find(Boolean);
     if (status === undefined || !(STATUSES.has(status) || SUPERSEDED.test(status))) {
-        report(
-            'docs-decision-status',
-            record.path,
-            `${record.path}: **Status:** is none of Proposed, Accepted, Superseded by ADR-NNN, Deprecated`,
-        );
+        const message =
+            status !== undefined && BARE_SUPERSEDED.test(status)
+                ? `${record.path}: **Status:** names a successor but no link — write Superseded by [ADR-NNN](file.md)`
+                : `${record.path}: **Status:** is none of Proposed, Accepted, Superseded by [ADR-NNN](file.md), Deprecated`;
+        report('docs-decision-status', record.path, message);
     }
 }
 
@@ -313,6 +324,16 @@ function auditDecisions(report, { files, heads }) {
         auditRecord(report, record, heads);
     }
 
+    const numbers = [...new Set(records.map((record) => record.name.slice(0, 3)))].sort();
+    const sequential = numbers.every((number, index) => Number.parseInt(number, 10) === index + 1);
+    if (numbers.length > 0 && !sequential) {
+        report(
+            'docs-decision-sequence',
+            'docs/decisions/',
+            `docs/decisions/ numbers run ${numbers.join(', ')}: they run from 001 with no gap — a decision that moved folders takes the next number where it lands`,
+        );
+    }
+
     const claimed = new Map();
     for (const record of records) {
         const number = record.name.slice(0, 3);

package/src/docs.test.ts

@@ -154,7 +154,7 @@ test('names chapter numbers that skip, and numbers claimed twice', () => {
 
     // Then - one sentence about the whole run
     expect(sentence(tree, 'docs-chapter-numbering')).toBe(
-        'chapter numbers run 01, 02, 03, 05, 05: they are contiguous from 01, one file per number',
+        'chapter numbers run 01, 02, 03, 05, 05: they are contiguous from 01, one file per number, except that 04 may be absent',
     );
 });
 
@@ -211,6 +211,40 @@ test('never asks for 04-operating.md from a repository that ships nothing', () =
     expect(rules(manual())).toEqual([]);
 });
 
+test('lets 05 follow 03 directly when the repository ships nothing', () => {
+    // Given - 01-03 then 05, no 04 chapter, nothing that would ask for one
+    const tree = manual({
+        files: [...manual().files, 'docs/05-building.md'],
+        links: { 'docs/README.md': [...manual().links['docs/README.md'], '05-building.md'] },
+    });
+
+    // Then - 04 is the one gap the numbering excuses
+    expect(rules(tree)).toEqual([]);
+});
+
+test('still asks for 04-operating.md from that same shape once it ships', () => {
+    // Given - the same 01-03 + 05 shape, but an image this time
+    const tree = manual({
+        files: [...manual().files, 'docs/05-building.md'],
+        links: { 'docs/README.md': [...manual().links['docs/README.md'], '05-building.md'] },
+        ships: { dockerfile: true, infrastructure: false, publishable: false },
+    });
+
+    // Then - the numbering stays clean; only the presence test speaks
+    expect(rules(tree)).toEqual(['docs-operating-missing']);
+});
+
+test('refuses a gap at 05 even though 04 may be absent', () => {
+    // Given - 01-03 then 06, skipping past the one number the spine excuses
+    const tree = manual({
+        files: [...manual().files, 'docs/06-quality-checks.md'],
+        links: { 'docs/README.md': [...manual().links['docs/README.md'], '06-quality-checks.md'] },
+    });
+
+    // Then - only 04 is excused; 05 still has to be there
+    expect(rules(tree)).toEqual(['docs-chapter-numbering']);
+});
+
 test('names a chapter that is a journal, not a subject', () => {
     // Given - a fourth chapter recording a design exploration
     const tree = manual({
@@ -332,12 +366,28 @@ test('names a decision outside the status vocabulary', () => {
 
     // Then - the four the vocabulary holds
     expect(sentence(tree, 'docs-decision-status')).toBe(
-        'docs/decisions/001-the-first-call.md: **Status:** is none of Proposed, Accepted, Superseded by ADR-NNN, Deprecated',
+        'docs/decisions/001-the-first-call.md: **Status:** is none of Proposed, Accepted, Superseded by [ADR-NNN](file.md), Deprecated',
     );
 });
 
-test('accepts a superseded status that names the record replacing it', () => {
-    // Given - the one status carrying an argument
+test('accepts a superseded status that links the record replacing it', () => {
+    // Given - the one status carrying an argument, written as a citation
+    const tree = withDecisions({
+        heads: {
+            'docs/decisions/001-the-first-call.md': [
+                '# ADR-001: The first call',
+                '',
+                '**Status:** Superseded by [ADR-014](014-the-later-call.md)',
+            ],
+        },
+    });
+
+    // Then - nothing to say
+    expect(rules(tree)).toEqual([]);
+});
+
+test('refuses a superseded status with no link naming the successor', () => {
+    // Given - the bare form: a successor is named, but not as a place to look
     const tree = withDecisions({
         heads: {
             'docs/decisions/001-the-first-call.md': [
@@ -348,10 +398,108 @@ test('accepts a superseded status that names the record replacing it', () => {
         },
     });
 
+    // Then - the missing link is the whole complaint
+    expect(sentence(tree, 'docs-decision-status')).toBe(
+        'docs/decisions/001-the-first-call.md: **Status:** names a successor but no link — write Superseded by [ADR-NNN](file.md)',
+    );
+});
+
+test('passes an empty decisions folder', () => {
+    // Given - the folder exists but holds no record yet
+    const tree = manual({ files: [...manual().files, 'docs/decisions/'] });
+
+    // Then - a folder with nothing to number has no sequence to break
+    expect(rules(tree)).toEqual(['docs-template-missing']);
+});
+
+test('passes a decisions folder holding only the template', () => {
+    // Given - the mold, and not a single record beside it
+    const tree = manual({
+        files: [...manual().files, 'docs/decisions/', 'docs/decisions/_template.md'],
+    });
+
     // Then - nothing to say
     expect(rules(tree)).toEqual([]);
 });
 
+test('refuses a decision sequence that skips a number', () => {
+    // Given - 001 and 003, with no record ever numbered 002
+    const tree = withDecisions({
+        files: [
+            ...manual().files,
+            'docs/decisions/',
+            'docs/decisions/001-the-first-call.md',
+            'docs/decisions/003-the-third-call.md',
+            'docs/decisions/_template.md',
+        ],
+        heads: {
+            'docs/decisions/001-the-first-call.md': [
+                '# ADR-001: The first call',
+                '',
+                '**Status:** Accepted',
+            ],
+            'docs/decisions/003-the-third-call.md': [
+                '# ADR-003: The third call',
+                '',
+                '**Status:** Accepted',
+            ],
+        },
+    });
+
+    // Then - the gap is named, from 001
+    expect(sentence(tree, 'docs-decision-sequence')).toBe(
+        'docs/decisions/ numbers run 001, 003: they run from 001 with no gap — a decision that moved folders takes the next number where it lands',
+    );
+});
+
+test('refuses a decision sequence that starts above 001', () => {
+    // Given - 006 and 008, with nothing numbered before them
+    const tree = withDecisions({
+        files: [
+            ...manual().files,
+            'docs/decisions/',
+            'docs/decisions/006-the-sixth-call.md',
+            'docs/decisions/008-the-eighth-call.md',
+            'docs/decisions/_template.md',
+        ],
+        heads: {
+            'docs/decisions/006-the-sixth-call.md': [
+                '# ADR-006: The sixth call',
+                '',
+                '**Status:** Accepted',
+            ],
+            'docs/decisions/008-the-eighth-call.md': [
+                '# ADR-008: The eighth call',
+                '',
+                '**Status:** Accepted',
+            ],
+        },
+    });
+
+    // Then - the same rule, from an offset start
+    expect(sentence(tree, 'docs-decision-sequence')).toBe(
+        'docs/decisions/ numbers run 006, 008: they run from 001 with no gap — a decision that moved folders takes the next number where it lands',
+    );
+});
+
+test('lets a duplicated number pass the sequence check on its own', () => {
+    // Given - two records claiming 001, and none other — the set is just {001}
+    const tree = withDecisions({
+        files: [...withDecisions().files, 'docs/decisions/001-the-same-call.md'],
+        heads: {
+            ...withDecisions().heads,
+            'docs/decisions/001-the-same-call.md': [
+                '# ADR-001: The same call',
+                '',
+                '**Status:** Proposed',
+            ],
+        },
+    });
+
+    // Then - docs-decision-number still refuses it; the sequence itself is not the gap
+    expect(rules(tree)).toEqual(['docs-decision-number']);
+});
+
 test('names a number two records claim', () => {
     // Given - two records numbered 001
     const tree = withDecisions({