proteum 2.5.12 → 2.5.13

package/cli/commands/docs.ts

@@ -8,6 +8,7 @@ import { renderStep, renderSuccess, renderTitle, renderWarning } from '../presen
 
 const { collectDocAnchors } = require('../../docAnchors.js') as {
     collectDocAnchors: (sourceText: string) => {
+        adr: string[];
         docs: string[];
         fix: string[];
         entries: { line: number; tag: string; value: string }[];
@@ -20,7 +21,7 @@ const { collectDocAnchors } = require('../../docAnchors.js') as {
 
 type TDocsCheckFinding = {
     detail: string;
-    kind: 'unresolved-anchor' | 'unanchored-fix-note' | 'orphan-feature-pack';
+    kind: 'unresolved-anchor' | 'ambiguous-anchor' | 'unanchored-fix-note' | 'orphan-feature-pack';
     subject: string;
 };
 
@@ -96,6 +97,39 @@ const resolveAnchorValue = (value: string, fromDirectory: string, root: string)
     return roots.some((candidate) => fs.existsSync(path.resolve(candidate, value)));
 };
 
+/**
+ * Resolve an `@adr` reference to the decision records whose filename starts with
+ * it. Returns every match, because two records sharing an identifier makes the
+ * reference ambiguous rather than merely valid.
+ */
+const resolveAdrReference = (value: string, fromDirectory: string, root: string) => {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) return [];
+
+    const directories: string[] = [];
+    let current = fromDirectory;
+    while (current) {
+        const candidate = path.join(current, 'docs', 'decisions');
+        if (fs.existsSync(candidate)) directories.push(candidate);
+        const parent = path.dirname(current);
+        if (parent === current) break;
+        current = parent;
+    }
+
+    const rootCandidate = path.join(root, 'docs', 'decisions');
+    if (fs.existsSync(rootCandidate) && !directories.includes(rootCandidate)) directories.push(rootCandidate);
+
+    // A project with no decisions corpus never fails this check.
+    if (directories.length === 0) return null;
+
+    return directories.flatMap((directory) =>
+        fs
+            .readdirSync(directory)
+            .filter((entry) => entry.toLowerCase().startsWith(normalized))
+            .map((entry) => path.relative(root, path.join(directory, entry))),
+    );
+};
+
 const listFeaturePacks = (root: string) => {
     const featuresDir = path.join(root, 'docs', 'features');
     if (!fs.existsSync(featuresDir)) return [];
@@ -143,6 +177,24 @@ export const buildDocsCheckReport = (root: string): TDocsCheckReport => {
                 findings.push({ detail: `@fix ${value}`, kind: 'unresolved-anchor', subject: relative });
             }
         });
+
+        anchors.adr.forEach((value) => {
+            const matches = resolveAdrReference(value, path.dirname(filepath), root);
+            if (matches === null) return;
+
+            if (matches.length === 0) {
+                findings.push({ detail: `@adr ${value}`, kind: 'unresolved-anchor', subject: relative });
+                return;
+            }
+
+            if (matches.length > 1) {
+                findings.push({
+                    detail: `@adr ${value} matches ${matches.length} records: ${matches.join(', ')}`,
+                    kind: 'ambiguous-anchor',
+                    subject: relative,
+                });
+            }
+        });
     });
 
     listFixNotesRequiringAnchor(root).forEach((note) => {
@@ -202,6 +254,7 @@ export const run = async (): Promise<void> => {
                 { label: 'files anchored', value: String(report.anchoredFiles) },
             ]),
             renderFindings(report.findings, 'unresolved-anchor', 'Unresolved anchors'),
+            renderFindings(report.findings, 'ambiguous-anchor', 'Ambiguous anchors'),
             renderFindings(report.findings, 'unanchored-fix-note', 'Fix notes with no code anchor'),
             renderFindings(report.findings, 'orphan-feature-pack', 'Feature packs with no inbound anchor'),
         ].join('\n\n'),

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.12",
+	"version": "2.5.13",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/tests/docs-check.test.cjs

@@ -83,6 +83,45 @@ test('docs check resolves anchors aimed at the repo corpus when run from an app
     assert.equal(report.anchoredFiles, 1);
 });
 
+test('docs check resolves an adr anchor against the decisions corpus', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/decisions/ADR-0004-page-query-contracts.md', '# ADR-0004\n');
+    writeFile(root, 'apps/product/server/controllers/search.ts', '/**\n * @adr ADR-0004\n */\nexport default {};\n');
+
+    assert.equal(kinds(buildDocsCheckReport(root), 'unresolved-anchor').length, 0);
+});
+
+test('docs check reports an adr anchor matching no decision record', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/decisions/ADR-0004-page-query-contracts.md', '# ADR-0004\n');
+    writeFile(root, 'apps/product/server/controllers/search.ts', '/**\n * @adr ADR-9999\n */\nexport default {};\n');
+
+    const unresolved = kinds(buildDocsCheckReport(root), 'unresolved-anchor');
+
+    assert.equal(unresolved.length, 1);
+    assert.equal(unresolved[0].detail, '@adr ADR-9999');
+});
+
+test('docs check reports an adr identifier shared by two decision records', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/decisions/ADR-0010-catalog-provenance.md', '# ADR-0010\n');
+    writeFile(root, 'docs/decisions/ADR-0010-visual-system.md', '# ADR-0010\n');
+    writeFile(root, 'apps/product/server/controllers/search.ts', '/**\n * @adr ADR-0010\n */\nexport default {};\n');
+
+    const ambiguous = kinds(buildDocsCheckReport(root), 'ambiguous-anchor');
+
+    assert.equal(ambiguous.length, 1);
+    assert.equal(/matches 2 records/.test(ambiguous[0].detail), true);
+});
+
+test('docs check stays silent about adr anchors when a project has no decisions corpus', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(root, 'apps/product/server/controllers/search.ts', '/**\n * @adr ADR-0004\n */\nexport default {};\n');
+
+    assert.equal(kinds(buildDocsCheckReport(root), 'unresolved-anchor').length, 0);
+});
+
 test('docs check reports a fix note whose invariant no code anchors', () => {
     const root = createRoot();
     writeFile(root, 'docs/fixes/2026-06-14-watchdog.md', '# Fix\n\n## Agent warning\n\nDo not remove the guards.\n');