proteum 2.5.12 → 2.5.14

package/agents/project/CODING_STYLE.md

@@ -85,6 +85,8 @@ Write anchors in a leading block comment:
 
 - `@docs` points at the feature pack that owns the file. Required on every file that default-exports `definePageRoute`, `defineController`, `defineServerRoute`, or `defineServerRoutes`, and on every exported class extending a service base such as `Service` or `UsersManagementService`. Error routes are exempt: they render a status message and carry no feature-specific rule, so requiring a pack for one would manufacture documentation. Add an anchor to an error route only when it really does carry a rule.
 - Components are not covered automatically. A presentational primitive such as `Icon.tsx` or `Card.tsx` owns no feature, so a blanket rule would manufacture documentation for hundreds of files. Cover the component directories that do own a feature by listing them in `includeDocAnchors` when building the ESLint config, for example `['client/components/paywall/**']`.
+- Infrastructure is exempt the same way error routes are. A transport helper, a metrics router or a rate limiter owns no feature contract, so list those paths in `excludeDocAnchors` rather than pointing them at a pack that does not describe them. An excluded file may still declare anchors, and `valid-doc-anchor` keeps checking any it declares.
+- A feature pack that no code will ever point at, such as a retirement record or a document describing audiences rather than modules, opts out of the orphan report by carrying a `RETIRED` note or a `code-owned: false` line in its README. Without that, the pack is reported as orphaned forever and the backlog stops being actionable.
 - `@adr` and `@fix` point at the decision record and fix note that constrain the file. Add them where the decision or the bug actually lives, not on every file in the area.
 - `@rule` states the invariant inline, in full. It is the one anchor that carries content rather than a pointer, because the rule is what an agent needs at the moment of editing. A `@rule` that only says `todo` or repeats the linked title is a defect.
 - Anchors are not a substitute for the documents. Narrative, alternatives, benchmarks and acceptance stay under `docs/**`; the anchor carries the pointer and the single-sentence rule.

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,58 @@ 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 retiredPackPattern = /^\s*>?\s*RETIRED\b/im;
+const notCodeOwnedPattern = /^\s*>?\s*code-owned:\s*false\s*$/im;
+
+/**
+ * A pack opts out of the orphan report by saying so in its README, either with
+ * a `RETIRED` note or a `code-owned: false` line.
+ *
+ * Retirement records and intent documents describe decisions and audiences, not
+ * modules, so no source file will ever point at them. Reporting those forever
+ * trains a reader to ignore the whole list.
+ */
+const packOptsOutOfOrphanReport = (featuresDir: string, pack: string) => {
+    const readme = path.join(featuresDir, pack, 'README.md');
+    if (!fs.existsSync(readme)) return false;
+
+    const content = fs.readFileSync(readme, 'utf8');
+    return retiredPackPattern.test(content) || notCodeOwnedPattern.test(content);
+};
+
 const listFeaturePacks = (root: string) => {
     const featuresDir = path.join(root, 'docs', 'features');
     if (!fs.existsSync(featuresDir)) return [];
@@ -103,6 +156,7 @@ const listFeaturePacks = (root: string) => {
     return fs
         .readdirSync(featuresDir, { withFileTypes: true })
         .filter((entry) => entry.isDirectory())
+        .filter((entry) => !packOptsOutOfOrphanReport(featuresDir, entry.name))
         .map((entry) => entry.name);
 };
 
@@ -143,6 +197,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 +274,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/eslint.js

@@ -545,6 +545,7 @@ const createRequireDocAnchorRule = () => ({
                 type: 'object',
                 properties: {
                     definitions: { type: 'array', items: { type: 'string' } },
+                    exclude: { type: 'array', items: { type: 'string' } },
                     include: { type: 'array', items: { type: 'string' } },
                     requiredTags: { type: 'array', items: { enum: docAnchorTags } },
                     serviceBasePattern: { type: 'string' },
@@ -558,15 +559,22 @@ const createRequireDocAnchorRule = () => ({
         const definitions = options.definitions || defaultDocAnchorDefinitions;
         const requiredTags = options.requiredTags || ['docs'];
         const includes = options.include || [];
+        const excludes = options.exclude || [];
         const serviceBasePattern = new RegExp(options.serviceBasePattern || 'Service$');
         const filename = context.filename || context.getFilename?.() || '';
 
+        // Infrastructure carries no feature contract, so a project lists those
+        // paths here rather than anchoring them to a pack that does not exist.
+        // An excluded file may still declare anchors, and `valid-doc-anchor`
+        // keeps checking them.
+        const excluded = matchesIncludeGlob(filename, excludes);
+
         let reported = false;
 
         const reportMissing = (node, subject) => {
             // One report per file: a service class and an include glob can both
             // match, and repeating the same instruction adds no information.
-            if (reported) return;
+            if (reported || excluded) return;
 
             const anchors = collectFileDocAnchors(context);
             if (anchors.entries.length === 0) {
@@ -661,7 +669,12 @@ const createValidDocAnchorRule = () => ({
     },
 });
 
-const createProteumEslintConfig = ({ docAnchors = 'warn', includeDocAnchors = [], ignores = [] } = {}) => [
+const createProteumEslintConfig = ({
+    docAnchors = 'warn',
+    excludeDocAnchors = [],
+    includeDocAnchors = [],
+    ignores = [],
+} = {}) => [
     {
         ignores: [...defaultIgnores, ...ignores],
     },
@@ -706,7 +719,10 @@ const createProteumEslintConfig = ({ docAnchors = 'warn', includeDocAnchors = []
             // `includeDocAnchors` opts in extra paths, which is how a project
             // covers the feature-owning components without dragging in every
             // presentational primitive.
-            'proteum/require-doc-anchor': [docAnchors, { include: includeDocAnchors }],
+            'proteum/require-doc-anchor': [
+                docAnchors,
+                { exclude: excludeDocAnchors, include: includeDocAnchors },
+            ],
             // A stale anchor is always an error: it only fires on files that
             // already opted in, and a pointer to a deleted document is worse
             // than no pointer at all.

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.14",
 	"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');
@@ -121,6 +160,23 @@ test('docs check reports a feature pack that no code points at', () => {
     assert.deepEqual(orphans.map((finding) => finding.subject), ['docs/features/orphan']);
 });
 
+test('docs check lets a retired or non-code pack opt out of the orphan report', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(root, 'docs/features/pro-preview/README.md', '# Pro Preview\n\n> RETIRED 2026-07-07. Superseded.\n');
+    writeFile(root, 'docs/features/persona-journeys/README.md', '# Personas\n\ncode-owned: false\n');
+    writeFile(root, 'docs/features/still-orphaned/README.md', '# Orphan\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/search\n */\nexport default {};\n',
+    );
+
+    const orphans = kinds(buildDocsCheckReport(root), 'orphan-feature-pack');
+
+    assert.deepEqual(orphans.map((finding) => finding.subject), ['docs/features/still-orphaned']);
+});
+
 test('docs check ignores generated and vendored directories', () => {
     const root = createRoot();
     writeFile(root, 'docs/features/search/README.md', '# Search\n');

package/tests/eslint-rules.test.cjs

@@ -541,6 +541,50 @@ test('proteum lint accepts an included file once it carries an anchor', () => {
     assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
 });
 
+test('proteum lint exempts infrastructure paths listed in excludeDocAnchors', () => {
+    const { root } = createDocProject();
+    const options = { docAnchors: 'warn', excludeDocAnchors: ['server/services/Utils/**', 'server/routes/debug.ts'] };
+
+    const utilService = lint(
+        `export default class FetchService extends Service {}`,
+        path.join(root, 'server', 'services', 'Utils', 'Fetch', 'index.ts'),
+        options,
+    );
+    assert.equal(messagesFor(utilService, requireDocAnchorRuleId).length, 0);
+
+    const debugRoute = lint(
+        `export default defineServerRoutes(() => null);`,
+        path.join(root, 'server', 'routes', 'debug.ts'),
+        options,
+    );
+    assert.equal(messagesFor(debugRoute, requireDocAnchorRuleId).length, 0);
+
+    // A service outside the excluded paths is still required to anchor.
+    const covered = lint(
+        `export default class SearchService extends Service {}`,
+        path.join(root, 'server', 'services', 'Domains', 'search', 'index.ts'),
+        options,
+    );
+    assert.equal(messagesFor(covered, requireDocAnchorRuleId).length, 1);
+});
+
+test('proteum lint still validates anchors declared on an excluded file', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/deleted-feature
+             */
+            export default class FetchService extends Service {}
+        `,
+        path.join(root, 'server', 'services', 'Utils', 'Fetch', 'index.ts'),
+        { docAnchors: 'warn', excludeDocAnchors: ['server/services/Utils/**'] },
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+    assert.equal(messagesFor(messages, validDocAnchorRuleId).length, 1);
+});
+
 test('proteum lint does not require a doc anchor on error routes', () => {
     const { root } = createDocProject();
     const messages = lint(