proteum 2.5.13 → 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

@@ -130,6 +130,25 @@ const resolveAdrReference = (value: string, fromDirectory: string, root: string)
     );
 };
 
+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 [];
@@ -137,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);
 };
 

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.13",
+	"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

@@ -160,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(