@jterrazz/typescript 9.2.0 → 9.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/typescript",
-    "version": "9.2.0",
+    "version": "9.2.1",
     "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);
     }
 }
 

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,18 +366,18 @@ 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',
+                '**Status:** Superseded by [ADR-014](014-the-later-call.md)',
             ],
         },
     });
@@ -352,6 +386,24 @@ test('accepts a superseded status that names the record replacing it', () => {
     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': [
+                '# ADR-001: The first call',
+                '',
+                '**Status:** Superseded by ADR-014',
+            ],
+        },
+    });
+
+    // 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('names a number two records claim', () => {
     // Given - two records numbered 001
     const tree = withDecisions({