proteum 2.5.10 → 2.5.11

package/eslint.js

@@ -1,8 +1,19 @@
+const fs = require('node:fs');
+const path = require('node:path');
 const tseslint = require('typescript-eslint');
 const reactPlugin = require('eslint-plugin-react');
 const reactHooksPlugin = require('eslint-plugin-react-hooks');
 const jsxA11yPlugin = require('eslint-plugin-jsx-a11y');
 
+const {
+    buildDocAnchorGroups,
+    docAnchorTags,
+    hasDocAnchorTag,
+    isPathDocAnchorTag,
+    minDocAnchorRuleLength,
+    parseDocAnchorComment,
+} = require('./docAnchors.js');
+
 const defaultIgnores = [
     '**/node_modules/**',
     '**/bin/**',
@@ -307,7 +318,250 @@ const createNoAppImportRule = () => ({
     },
 });
 
-const createProteumEslintConfig = ({ ignores = [] } = {}) => [
+// Error routes are deliberately absent: a `_messages/404` page renders a status
+// message and carries no feature-specific rule, so requiring a feature pack for
+// one would manufacture documentation to satisfy the linter. An error page that
+// does carry a real rule can still add an anchor, and `valid-doc-anchor` keeps
+// checking it.
+const defaultDocAnchorDefinitions = [
+    'defineController',
+    'definePageRoute',
+    'defineServerRoute',
+    'defineServerRoutes',
+];
+
+const docsRootCache = new Map();
+const directoryEntriesCache = new Map();
+
+const getSourceCode = (context) => context.sourceCode || context.getSourceCode?.();
+
+const getContextCwd = (context) => context.cwd || context.getCwd?.() || process.cwd();
+
+const pathExists = (candidate) => {
+    try {
+        return fs.existsSync(candidate);
+    } catch (_error) {
+        return false;
+    }
+};
+
+const readDirectoryEntries = (directory) => {
+    if (directoryEntriesCache.has(directory)) return directoryEntriesCache.get(directory);
+
+    let entries = [];
+    try {
+        entries = fs.readdirSync(directory);
+    } catch (_error) {
+        entries = [];
+    }
+
+    directoryEntriesCache.set(directory, entries);
+    return entries;
+};
+
+/**
+ * Collect every ancestor of a linted file that holds a `docs/` directory,
+ * nearest first.
+ *
+ * All of them are candidates, not just the nearest: a monorepo app commonly has
+ * its own `apps/<app>/docs/` alongside the repository-level corpus, and stopping
+ * at the first match would make every anchor aimed at the shared corpus fail to
+ * resolve.
+ */
+const findDocsRoots = (startDirectory) => {
+    if (docsRootCache.has(startDirectory)) return docsRootCache.get(startDirectory);
+
+    const resolved = [];
+    let current = startDirectory;
+    while (current) {
+        if (pathExists(path.join(current, 'docs'))) resolved.push(current);
+
+        const parent = path.dirname(current);
+        if (parent === current) break;
+        current = parent;
+    }
+
+    docsRootCache.set(startDirectory, resolved);
+    return resolved;
+};
+
+const resolveAnchorRoots = (context) => {
+    const filename = context.filename || context.getFilename?.() || '';
+    const fileDirectory = filename ? path.dirname(filename) : undefined;
+    const cwd = getContextCwd(context);
+    const roots = [];
+
+    const addRoot = (root) => {
+        if (root && !roots.includes(root)) roots.push(root);
+    };
+
+    if (fileDirectory) findDocsRoots(fileDirectory).forEach(addRoot);
+    addRoot(cwd);
+    addRoot(fileDirectory);
+
+    return roots;
+};
+
+const resolvePathAnchor = (value, roots) => {
+    if (path.isAbsolute(value)) return pathExists(value);
+
+    return roots.some((root) => pathExists(path.resolve(root, value)));
+};
+
+const resolveAdrAnchor = (value, roots) => {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) return false;
+
+    const decisionDirectories = roots
+        .map((root) => path.join(root, 'docs', 'decisions'))
+        .filter((directory) => pathExists(directory));
+
+    // Projects without a decisions corpus never fail this check, so the rule
+    // stays silent instead of inventing a convention the app has not adopted.
+    if (decisionDirectories.length === 0) return true;
+
+    return decisionDirectories.some((directory) =>
+        readDirectoryEntries(directory).some((entry) => entry.toLowerCase().startsWith(normalized)),
+    );
+};
+
+const collectFileDocAnchors = (context) => {
+    const sourceCode = getSourceCode(context);
+    if (!sourceCode) return buildDocAnchorGroups([]);
+
+    const entries = [];
+    sourceCode.getAllComments().forEach((comment) => {
+        if (comment.type !== 'Block') return;
+        entries.push(...parseDocAnchorComment(comment.value, comment.loc?.start?.line || 1));
+    });
+
+    return buildDocAnchorGroups(entries);
+};
+
+const unwrapExpression = (node) => {
+    let current = node;
+    while (
+        current &&
+        (current.type === 'TSAsExpression' ||
+            current.type === 'TSSatisfiesExpression' ||
+            current.type === 'TSNonNullExpression')
+    ) {
+        current = current.expression;
+    }
+
+    return current;
+};
+
+const getDefinitionCalleeName = (node, definitions) => {
+    const expression = unwrapExpression(node);
+    if (expression?.type !== 'CallExpression') return null;
+
+    const name = getCalleePropertyName(expression.callee);
+    return name && definitions.includes(name) ? name : null;
+};
+
+const createRequireDocAnchorRule = () => ({
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require Proteum definition files to anchor the documentation that governs them.',
+        },
+        messages: {
+            missingAnchor:
+                '`{{definition}}` files must carry a doc anchor. Add a leading block comment with `@docs <path to the feature pack>`, plus `@rule <one-line invariant>` when a fix or decision constrains this file.',
+            missingTag:
+                '`{{definition}}` files must carry a `@{{tag}}` doc anchor in a leading block comment.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    definitions: { type: 'array', items: { type: 'string' } },
+                    requiredTags: { type: 'array', items: { enum: docAnchorTags } },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    create(context) {
+        const options = context.options?.[0] || {};
+        const definitions = options.definitions || defaultDocAnchorDefinitions;
+        const requiredTags = options.requiredTags || ['docs'];
+
+        return {
+            ExportDefaultDeclaration(node) {
+                const definition = getDefinitionCalleeName(node.declaration, definitions);
+                if (!definition) return;
+
+                const anchors = collectFileDocAnchors(context);
+                if (anchors.entries.length === 0) {
+                    context.report({ node, messageId: 'missingAnchor', data: { definition } });
+                    return;
+                }
+
+                const missingTag = requiredTags.find((tag) => !hasDocAnchorTag(anchors, tag));
+                if (missingTag) {
+                    context.report({ node, messageId: 'missingTag', data: { definition, tag: missingTag } });
+                }
+            },
+        };
+    },
+});
+
+const createValidDocAnchorRule = () => ({
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require doc anchors to point at documentation that still exists.',
+        },
+        messages: {
+            unresolvedPath:
+                'Doc anchor `@{{tag}} {{value}}` does not resolve to a file or directory. Update the anchor to the current documentation path, or remove it.',
+            unresolvedAdr:
+                'Doc anchor `@adr {{value}}` matches no decision record under `docs/decisions`. Use the current ADR identifier.',
+            emptyRule:
+                'Doc anchor `@rule` must state the invariant in full so an agent editing this file can apply it without opening the linked document.',
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            'Program:exit'() {
+                const anchors = collectFileDocAnchors(context);
+                if (anchors.entries.length === 0) return;
+
+                const roots = resolveAnchorRoots(context);
+                anchors.entries.forEach((entry) => {
+                    const loc = { line: entry.line, column: 0 };
+
+                    if (entry.tag === 'rule') {
+                        if (entry.value.length < minDocAnchorRuleLength) {
+                            context.report({ loc, messageId: 'emptyRule' });
+                        }
+                        return;
+                    }
+
+                    if (isPathDocAnchorTag(entry.tag)) {
+                        if (!resolvePathAnchor(entry.value, roots)) {
+                            context.report({
+                                loc,
+                                messageId: 'unresolvedPath',
+                                data: { tag: entry.tag, value: entry.value },
+                            });
+                        }
+                        return;
+                    }
+
+                    if (entry.tag === 'adr' && !resolveAdrAnchor(entry.value, roots)) {
+                        context.report({ loc, messageId: 'unresolvedAdr', data: { value: entry.value } });
+                    }
+                });
+            },
+        };
+    },
+});
+
+const createProteumEslintConfig = ({ docAnchors = 'warn', ignores = [] } = {}) => [
     {
         ignores: [...defaultIgnores, ...ignores],
     },
@@ -334,6 +588,8 @@ const createProteumEslintConfig = ({ ignores = [] } = {}) => [
                 rules: {
                     'no-app-import': createNoAppImportRule(),
                     'no-swallowed-caught-error': createSwallowedErrorRule(),
+                    'require-doc-anchor': createRequireDocAnchorRule(),
+                    'valid-doc-anchor': createValidDocAnchorRule(),
                 },
             },
             react: reactPlugin,
@@ -344,6 +600,13 @@ const createProteumEslintConfig = ({ ignores = [] } = {}) => [
             '@typescript-eslint/no-explicit-any': 'error',
             'proteum/no-app-import': 'error',
             'proteum/no-swallowed-caught-error': 'error',
+            // Missing anchors warn by default so adopting apps see the backlog
+            // without a failing build; pass `docAnchors: 'error'` once backfilled.
+            'proteum/require-doc-anchor': docAnchors,
+            // 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.
+            'proteum/valid-doc-anchor': docAnchors === 'off' ? 'off' : 'error',
             'no-restricted-syntax': [
                 'error',
                 {

package/package.json

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

package/tests/doc-anchors.test.cjs

@@ -0,0 +1,115 @@
+const assert = require('node:assert/strict');
+
+const {
+    buildDocAnchorGroups,
+    collectDocAnchors,
+    hasDocAnchorTag,
+    isPathDocAnchorTag,
+    parseDocAnchorComment,
+} = require('../docAnchors.js');
+
+test('doc anchor parser reads every supported tag from a block comment', () => {
+    const groups = collectDocAnchors(`
+        /**
+         * @docs docs/features/search
+         * @adr  ADR-0004
+         * @fix  docs/fixes/2026-06-09-keyword-search-semantic-order.md
+         * @rule Composite ordering stays alias-aware.
+         */
+        export default definePageRoute({ path: '/browse' });
+    `);
+
+    assert.deepEqual(groups.docs, ['docs/features/search']);
+    assert.deepEqual(groups.adr, ['ADR-0004']);
+    assert.deepEqual(groups.fix, ['docs/fixes/2026-06-09-keyword-search-semantic-order.md']);
+    assert.deepEqual(groups.rules, ['Composite ordering stays alias-aware.']);
+});
+
+test('doc anchor parser joins multi-line rule invariants into one value', () => {
+    const groups = collectDocAnchors(`
+        /**
+         * @rule Composite ordering stays alias-aware.
+         *       Never rewrite ORDER BY with regex.
+         */
+    `);
+
+    assert.deepEqual(groups.rules, ['Composite ordering stays alias-aware. Never rewrite ORDER BY with regex.']);
+});
+
+test('doc anchor parser reports the line each anchor sits on', () => {
+    const groups = collectDocAnchors(['const a = 1;', '', '/**', ' * @docs docs/features/search', ' */'].join('\n'));
+
+    assert.equal(groups.entries.length, 1);
+    assert.equal(groups.entries[0].line, 4);
+});
+
+test('doc anchor parser ignores unrelated jsdoc tags', () => {
+    const groups = collectDocAnchors(`
+        /**
+         * @param input The request payload.
+         * @returns The parsed row.
+         */
+    `);
+
+    assert.equal(groups.entries.length, 0);
+});
+
+test('doc anchor parser stops a value at a blank comment line', () => {
+    const groups = collectDocAnchors(`
+        /**
+         * @rule Never rewrite ORDER BY with regex.
+         *
+         * Unrelated prose that must not join the invariant.
+         */
+    `);
+
+    assert.deepEqual(groups.rules, ['Never rewrite ORDER BY with regex.']);
+});
+
+test('doc anchor parser collects anchors from several comments and drops duplicates', () => {
+    const groups = collectDocAnchors(`
+        /** @docs docs/features/search */
+        const first = 1;
+        /** @docs docs/features/search */
+        /** @docs docs/features/billing */
+        const second = 2;
+    `);
+
+    assert.deepEqual(groups.docs, ['docs/features/search', 'docs/features/billing']);
+});
+
+test('doc anchor parser ignores tags with no value', () => {
+    const groups = collectDocAnchors(`
+        /**
+         * @docs
+         * @rule
+         */
+    `);
+
+    assert.equal(groups.entries.length, 0);
+});
+
+test('doc anchor parser caps how much source it scans', () => {
+    const padding = `${'// filler\n'.repeat(200)}`;
+    const source = `${padding}/** @docs docs/features/search */`;
+
+    assert.equal(collectDocAnchors(source, { maxLength: 50 }).entries.length, 0);
+    assert.equal(collectDocAnchors(source).docs.length, 1);
+});
+
+test('doc anchor parser tolerates empty and missing input', () => {
+    assert.equal(collectDocAnchors('').entries.length, 0);
+    assert.equal(collectDocAnchors(undefined).entries.length, 0);
+    assert.equal(parseDocAnchorComment(undefined).length, 0);
+});
+
+test('doc anchor helpers expose the tag contract', () => {
+    const groups = buildDocAnchorGroups(parseDocAnchorComment('* @docs docs/features/search', 1));
+
+    assert.equal(hasDocAnchorTag(groups, 'docs'), true);
+    assert.equal(hasDocAnchorTag(groups, 'rule'), false);
+    assert.equal(isPathDocAnchorTag('docs'), true);
+    assert.equal(isPathDocAnchorTag('fix'), true);
+    assert.equal(isPathDocAnchorTag('adr'), false);
+    assert.equal(isPathDocAnchorTag('rule'), false);
+});

package/tests/docs-check.test.cjs

@@ -0,0 +1,138 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+require('../cli/context.ts');
+
+const { buildDocsCheckReport } = require('../cli/commands/docs.ts');
+
+const createRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-docs-check-'));
+
+const writeFile = (root, filepath, content) => {
+    const full = path.join(root, filepath);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+};
+
+const kinds = (report, kind) => report.findings.filter((finding) => finding.kind === kind);
+
+test('docs check accepts anchors that resolve against the corpus', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/search\n */\nexport default {};\n',
+    );
+
+    const report = buildDocsCheckReport(root);
+
+    assert.equal(kinds(report, 'unresolved-anchor').length, 0);
+    assert.equal(kinds(report, 'orphan-feature-pack').length, 0);
+    assert.equal(report.anchoredFiles, 1);
+});
+
+test('docs check reports an anchor pointing at a deleted document', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/deleted\n */\nexport default {};\n',
+    );
+
+    const report = buildDocsCheckReport(root);
+    const unresolved = kinds(report, 'unresolved-anchor');
+
+    assert.equal(unresolved.length, 1);
+    assert.equal(unresolved[0].detail, '@docs docs/features/deleted');
+});
+
+test('docs check resolves anchors from an app that owns a nested docs directory', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(root, 'apps/product/docs/fixes/local.md', '# Local\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/search\n */\nexport default {};\n',
+    );
+
+    assert.equal(kinds(buildDocsCheckReport(root), 'unresolved-anchor').length, 0);
+});
+
+test('docs check resolves anchors aimed at the repo corpus when run from an app root', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/search\n */\nexport default {};\n',
+    );
+
+    // Running from the app root must not orphan an anchor that points at the
+    // repository-level corpus one directory up.
+    const report = buildDocsCheckReport(path.join(root, 'apps', 'product'));
+
+    assert.equal(kinds(report, 'unresolved-anchor').length, 0);
+    assert.equal(report.anchoredFiles, 1);
+});
+
+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');
+    writeFile(root, 'apps/daemon/src/rdap.ts', 'export default {};\n');
+
+    const unanchored = kinds(buildDocsCheckReport(root), 'unanchored-fix-note');
+
+    assert.equal(unanchored.length, 1);
+    assert.equal(unanchored[0].subject, 'docs/fixes/2026-06-14-watchdog.md');
+});
+
+test('docs check clears a fix note once code anchors it', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/fixes/2026-06-14-watchdog.md', '# Fix\n\n## Agent warning\n\nDo not remove the guards.\n');
+    writeFile(
+        root,
+        'apps/daemon/src/rdap.ts',
+        '/**\n * @fix  docs/fixes/2026-06-14-watchdog.md\n * @rule Do not remove the guards.\n */\nexport default {};\n',
+    );
+
+    assert.equal(kinds(buildDocsCheckReport(root), 'unanchored-fix-note').length, 0);
+});
+
+test('docs check reports a feature pack that no code points at', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(root, 'docs/features/orphan/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/orphan']);
+});
+
+test('docs check ignores generated and vendored directories', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(
+        root,
+        'node_modules/some-package/index.ts',
+        '/**\n * @docs docs/features/nope\n */\nexport default {};\n',
+    );
+    writeFile(root, 'apps/product/var/generated.ts', '/**\n * @docs docs/features/nope\n */\nexport default {};\n');
+
+    const report = buildDocsCheckReport(root);
+
+    assert.equal(kinds(report, 'unresolved-anchor').length, 0);
+    assert.equal(report.anchoredFiles, 0);
+});