proteum 2.5.10 → 2.5.12

package/tests/eslint-rules.test.cjs

@@ -1,17 +1,53 @@
 const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
 const { Linter } = require('eslint');
 
 const { createProteumEslintConfig } = require('../eslint.js');
 
-const lint = (code, filename = 'client/example.tsx') => {
+const lint = (code, filename = 'client/example.tsx', configOptions) => {
     const linter = new Linter({ configType: 'flat' });
-    return linter.verify(code, createProteumEslintConfig(), {
+    return linter.verify(code, createProteumEslintConfig(configOptions), {
         filename,
     });
 };
 
 const swallowedErrorRuleId = 'proteum/no-swallowed-caught-error';
 const noAppImportRuleId = 'proteum/no-app-import';
+const requireDocAnchorRuleId = 'proteum/require-doc-anchor';
+const validDocAnchorRuleId = 'proteum/valid-doc-anchor';
+
+const messagesFor = (messages, ruleId) => messages.filter((message) => message.ruleId === ruleId);
+
+// The fixture lives inside the repository `.temp` directory rather than the OS
+// temp directory: on macOS the latter sits under `/var/folders`, which the
+// shared `**/var/**` ignore would exclude from linting entirely.
+const docProjectParent = path.resolve(__dirname, '..', '.temp');
+const docProjectRoots = [];
+
+afterAll(() => {
+    docProjectRoots.forEach((root) => fs.rmSync(root, { force: true, recursive: true }));
+});
+
+/**
+ * Build a throwaway project whose documentation corpus really exists on disk,
+ * because the anchor rules resolve their paths against the filesystem.
+ */
+const createDocProject = () => {
+    fs.mkdirSync(docProjectParent, { recursive: true });
+    const root = fs.mkdtempSync(path.join(docProjectParent, 'proteum-doc-anchor-'));
+    docProjectRoots.push(root);
+
+    fs.mkdirSync(path.join(root, 'docs', 'features', 'search'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'docs', 'features', 'search', 'README.md'), '# Search\n');
+    fs.mkdirSync(path.join(root, 'docs', 'decisions'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'docs', 'decisions', 'ADR-0004-page-query-contracts.md'), '# ADR-0004\n');
+    fs.mkdirSync(path.join(root, 'docs', 'fixes'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'docs', 'fixes', '2026-06-09-keyword-order.md'), '# Fix\n');
+    fs.mkdirSync(path.join(root, 'client', 'pages'), { recursive: true });
+
+    return { pageFile: path.join(root, 'client', 'pages', 'browse.tsx'), root };
+};
 
 test('proteum lint rejects contextual @app imports', () => {
     const messages = lint(`
@@ -384,3 +420,283 @@ test('proteum lint allows direct reject promise catch handlers', () => {
 
     assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
 });
+
+test('proteum lint requires a doc anchor on definition files', () => {
+    const { pageFile } = createDocProject();
+    const messages = lint(`export default definePageRoute({ path: '/browse' });`, pageFile);
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 1);
+});
+
+test('proteum lint accepts a definition file that anchors its feature pack', () => {
+    const { pageFile } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/search
+             */
+            export default definePageRoute({ path: '/browse' });
+        `,
+        pageFile,
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+    assert.equal(messagesFor(messages, validDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint requires a doc anchor on every Proteum definition kind', () => {
+    const { pageFile } = createDocProject();
+
+    for (const definition of [
+        'defineController',
+        'definePageRoute',
+        'defineServerRoute',
+        'defineServerRoutes',
+    ]) {
+        const messages = lint(`export default ${definition}({ path: '/browse' });`, pageFile);
+        assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 1, definition);
+    }
+});
+
+test('proteum lint requires a doc anchor on exported service classes', () => {
+    const { root } = createDocProject();
+    const serviceFile = path.join(root, 'server', 'services', 'Domains', 'search', 'index.ts');
+
+    const missing = lint(
+        `export default class DomainsSearchService extends Service<Config, {}, Application, object> {}`,
+        serviceFile,
+    );
+    assert.equal(messagesFor(missing, requireDocAnchorRuleId).length, 1);
+
+    const anchored = lint(
+        `
+            /**
+             * @docs docs/features/search
+             */
+            export default class DomainsSearchService extends Service<Config, {}, Application, object> {}
+        `,
+        serviceFile,
+    );
+    assert.equal(messagesFor(anchored, requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint covers app-specific service base classes and named exports', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `export class AuthManagement extends UsersManagementService<TUser, AuthApplication, TJwtSession> {}`,
+        path.join(root, 'server', 'services', 'Users', 'Auth', 'index.ts'),
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 1);
+});
+
+test('proteum lint leaves non-service classes alone', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `export default class DomainCard extends React.Component {}`,
+        path.join(root, 'client', 'components', 'DomainCard.tsx'),
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint reports a service class only once per file', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `
+            export class FirstService extends Service {}
+            export default class SecondService extends Service {}
+        `,
+        path.join(root, 'server', 'services', 'Two', 'index.ts'),
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 1);
+});
+
+test('proteum lint opts extra files in through include globs', () => {
+    const { root } = createDocProject();
+    const paywallFile = path.join(root, 'client', 'components', 'paywall', 'PaywallModal', 'index.tsx');
+    const iconFile = path.join(root, 'client', 'components', 'Icon.tsx');
+    const source = `const Modal = () => null;\nexport default Modal;\n`;
+    const options = { docAnchors: 'warn', includeDocAnchors: ['client/components/paywall/**'] };
+
+    assert.equal(messagesFor(lint(source, paywallFile, options), requireDocAnchorRuleId).length, 1);
+    assert.equal(messagesFor(lint(source, iconFile, options), requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint accepts an included file once it carries an anchor', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/search
+             */
+            const Modal = () => null;
+            export default Modal;
+        `,
+        path.join(root, 'client', 'components', 'paywall', 'PaywallModal', 'index.tsx'),
+        { docAnchors: 'warn', includeDocAnchors: ['client/components/paywall/**'] },
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint does not require a doc anchor on error routes', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `export default defineErrorRoute({ code: 404 });`,
+        path.join(root, 'client', 'pages', '_messages', '404.tsx'),
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint ignores files that export no Proteum definition', () => {
+    const { pageFile } = createDocProject();
+    const messages = lint(`export default { path: '/browse' };`, pageFile);
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint reports a definition file whose anchors omit the feature pack', () => {
+    const { pageFile } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @rule Browse rows never expose raw score values.
+             */
+            export default definePageRoute({ path: '/browse' });
+        `,
+        pageFile,
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 1);
+});
+
+test('proteum lint resolves anchors against the repo corpus when the app has its own docs directory', () => {
+    const { root } = createDocProject();
+
+    // Mirrors the monorepo layout: apps/<app>/docs/ sits between the source file
+    // and the repository-level corpus that the anchor actually points at.
+    const appRoot = path.join(root, 'apps', 'website');
+    fs.mkdirSync(path.join(appRoot, 'docs', 'fixes'), { recursive: true });
+    fs.mkdirSync(path.join(appRoot, 'client', 'pages'), { recursive: true });
+
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/search
+             */
+            export default definePageRoute({ path: '/browse' });
+        `,
+        path.join(appRoot, 'client', 'pages', 'browse.tsx'),
+    );
+
+    assert.equal(messagesFor(messages, validDocAnchorRuleId).length, 0);
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint rejects a doc anchor pointing at a missing document', () => {
+    const { pageFile } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/deleted-feature
+             */
+            export default definePageRoute({ path: '/browse' });
+        `,
+        pageFile,
+    );
+
+    const reported = messagesFor(messages, validDocAnchorRuleId);
+    assert.equal(reported.length, 1);
+    assert.equal(/docs\/features\/deleted-feature/.test(reported[0].message), true);
+});
+
+test('proteum lint resolves fix and decision anchors against the documentation corpus', () => {
+    const { pageFile } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/search
+             * @adr  ADR-0004
+             * @fix  docs/fixes/2026-06-09-keyword-order.md
+             * @rule Composite ordering stays alias-aware.
+             */
+            export default definePageRoute({ path: '/browse' });
+        `,
+        pageFile,
+    );
+
+    assert.equal(messagesFor(messages, validDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint rejects a decision anchor that matches no decision record', () => {
+    const { pageFile } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/search
+             * @adr  ADR-9999
+             */
+            export default definePageRoute({ path: '/browse' });
+        `,
+        pageFile,
+    );
+
+    assert.equal(messagesFor(messages, validDocAnchorRuleId).length, 1);
+});
+
+test('proteum lint rejects a rule anchor that states no invariant', () => {
+    const { pageFile } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/search
+             * @rule todo
+             */
+            export default definePageRoute({ path: '/browse' });
+        `,
+        pageFile,
+    );
+
+    assert.equal(messagesFor(messages, validDocAnchorRuleId).length, 1);
+});
+
+test('proteum lint validates anchors on files that export no definition', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/deleted-feature
+             */
+            export const helper = () => null;
+        `,
+        path.join(root, 'server', 'services', 'search.ts'),
+    );
+
+    assert.equal(messagesFor(messages, validDocAnchorRuleId).length, 1);
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint escalates and disables doc anchor rules through config options', () => {
+    const { pageFile } = createDocProject();
+    const source = `
+        /**
+         * @docs docs/features/deleted-feature
+         */
+        export default definePageRoute({ path: '/browse' });
+    `;
+
+    const warned = lint(`export default definePageRoute({ path: '/browse' });`, pageFile);
+    assert.equal(messagesFor(warned, requireDocAnchorRuleId)[0].severity, 1);
+
+    const escalated = lint(`export default definePageRoute({ path: '/browse' });`, pageFile, {
+        docAnchors: 'error',
+    });
+    assert.equal(messagesFor(escalated, requireDocAnchorRuleId)[0].severity, 2);
+
+    const disabled = lint(source, pageFile, { docAnchors: 'off' });
+    assert.equal(messagesFor(disabled, requireDocAnchorRuleId).length, 0);
+    assert.equal(messagesFor(disabled, validDocAnchorRuleId).length, 0);
+});

package/tests/mcp.test.cjs

@@ -18,6 +18,7 @@ const {
     compactRouteCandidatesResponse,
     compactTraceResponse,
     compactWorkflowStartResponse,
+    readOwnerDocAnchors,
     resolveInstructionRouting,
 } = require('../common/dev/mcpPayloads.ts');
 const { createProteumMcpServer } = require('../common/dev/mcpServer.ts');
@@ -241,6 +242,114 @@ test('instruction routing promotes triggered full instruction files', () => {
     );
 });
 
+test('owner doc anchors resolve the documentation that governs a source file', () => {
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-doc-anchor-'));
+    const anchoredFile = path.join(appRoot, 'client/pages/browse.tsx');
+    const plainFile = path.join(appRoot, 'client/pages/plain.tsx');
+
+    writeFile(
+        anchoredFile,
+        [
+            '/**',
+            ' * @docs docs/features/search',
+            ' * @adr  ADR-0004',
+            ' * @fix  docs/fixes/2026-06-09-keyword-order.md',
+            ' * @rule Composite ordering stays alias-aware.',
+            ' */',
+            "export default definePageRoute({ path: '/browse' });",
+        ].join('\n'),
+    );
+    writeFile(plainFile, "export default definePageRoute({ path: '/plain' });\n");
+
+    const anchors = readOwnerDocAnchors(anchoredFile);
+
+    assert.deepEqual(anchors.docs, ['docs/features/search']);
+    assert.deepEqual(anchors.adr, ['ADR-0004']);
+    assert.deepEqual(anchors.fix, ['docs/fixes/2026-06-09-keyword-order.md']);
+    assert.deepEqual(anchors.rules, ['Composite ordering stays alias-aware.']);
+
+    assert.equal(readOwnerDocAnchors(plainFile), undefined);
+    assert.equal(readOwnerDocAnchors(path.join(appRoot, 'missing.tsx')), undefined);
+    assert.equal(readOwnerDocAnchors(undefined), undefined);
+});
+
+test('owner payloads carry the doc anchors declared by the owning file', () => {
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-owner-docs-'));
+    const pageFile = path.join(appRoot, 'client/pages/domains.tsx');
+
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# App Agents\n\n- root\n');
+    writeFile(
+        pageFile,
+        [
+            '/**',
+            ' * @docs docs/features/product-domain-listings',
+            ' * @rule Public rows never expose raw score values.',
+            ' */',
+            'export default function Domains() { return null; }',
+        ].join('\n'),
+    );
+
+    const manifest = {
+        version: 10,
+        app: {
+            root: appRoot,
+            coreRoot,
+            identityFilepath: path.join(appRoot, 'identity.config.ts'),
+            setupFilepath: path.join(appRoot, 'proteum.config.ts'),
+            identity: { name: 'Owner Docs App', identifier: 'OwnerDocsApp', description: '' },
+            setup: {},
+        },
+        conventions: { routeOptionKeys: [], reservedRouteOptionKeys: [] },
+        env: {
+            source: 'test',
+            loadedVariableKeys: [],
+            requiredVariables: [],
+            resolved: {
+                name: 'test',
+                profile: 'dev',
+                routerPort: 3105,
+                routerCurrentDomain: 'localhost',
+                routerInternalUrl: 'http://localhost:3105',
+            },
+        },
+        connectedProjects: [],
+        services: { app: [], routerPlugins: [] },
+        controllers: [],
+        commands: [],
+        routes: { client: [], server: [] },
+        layouts: [],
+        diagnostics: [],
+    };
+    const doctor = { summary: { errors: 0, warnings: 0, strictFailed: false }, diagnostics: [] };
+    const payload = compactWorkflowStartResponse({
+        contracts: doctor,
+        doctor,
+        manifest,
+        owner: {
+            matches: [
+                {
+                    details: [],
+                    kind: 'route',
+                    label: '/domains',
+                    matchedOn: ['path'],
+                    originHint: 'manifest',
+                    scopeLabel: 'local',
+                    score: 100,
+                    source: { filepath: pageFile, line: 1, column: 1 },
+                },
+            ],
+            normalizedQuery: '/domains',
+            query: '/domains',
+        },
+        route: '/domains',
+        runtime: { publicUrl: 'http://localhost:3105', mcpUrl: 'http://localhost:3105/__proteum/mcp' },
+        task: 'read-only runtime health pass',
+    });
+
+    assert.deepEqual(payload.data.owner.top.docs.docs, ['docs/features/product-domain-listings']);
+    assert.deepEqual(payload.data.owner.top.docs.rules, ['Public rows never expose raw score values.']);
+});
+
 test('workflow start payload combines compact runtime, instructions, owner, and duplicate guidance', () => {
     const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-workflow-app-'));
     const pageFile = path.join(appRoot, 'client/pages/domains.tsx');

package/tests/verify-changed.test.cjs

@@ -46,7 +46,10 @@ test('changed verification planner runs related tests for source files', () => {
         changedFiles: ['packages/auth/src/session.ts'],
     });
 
-    assert.deepEqual(planCommands(plan), ["npx vitest related 'packages/auth/src/session.ts'"]);
+    assert.deepEqual(planCommands(plan), [
+        "npx vitest related 'packages/auth/src/session.ts'",
+        'npx proteum docs check',
+    ]);
     assert.deepEqual(plan.selectedChecks[0].matchedFiles, ['packages/auth/src/session.ts']);
 });
 
@@ -115,7 +118,9 @@ test('changed verification planner skips tests for docs-only changes', () => {
         changedFiles: ['docs/testing.md'],
     });
 
-    assert.deepEqual(plan.selectedChecks, []);
+    // Test suites are skipped, but the doc-anchor check still runs: moving or
+    // renaming a document is precisely what leaves an anchor pointing nowhere.
+    assert.deepEqual(planIds(plan), ['builtin:doc-anchors']);
     assert.equal(plan.docsOnly, true);
     assert.deepEqual(plan.skippedChecks.map((check) => check.id), ['builtin:docs-only']);
 });
@@ -195,6 +200,49 @@ test('verify changed CLI JSON output keeps the planner and execution shape stabl
     assert.ok(Array.isArray(output.skippedChecks));
     assert.ok(Array.isArray(output.executions));
     assert.equal(typeof output.result.ok, 'boolean');
-    assert.equal(output.result.selectedChecks, 0);
+    // A docs-only change still skips the test suites, but it does run the
+    // doc-anchor check: renaming a document is exactly what orphans an anchor.
+    assert.equal(output.result.selectedChecks, 1);
+    assert.deepEqual(
+        output.selectedChecks.map((check) => check.id),
+        ['builtin:doc-anchors'],
+    );
     assert.equal(output.result.failedChecks, 0);
 });
+
+test('changed verification planner checks doc anchors when documentation moves', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+
+    const plan = buildChangedVerificationPlan({
+        cwd: root,
+        changedFiles: ['docs/features/search/README.md'],
+    });
+
+    assert.deepEqual(planIds(plan), ['builtin:doc-anchors']);
+    assert.deepEqual(planCommands(plan), ['npx proteum docs check']);
+});
+
+test('changed verification planner checks doc anchors when a source file changes', () => {
+    const root = createRoot();
+    writeFile(root, 'apps/product/server/controllers/Domains/search.ts', 'export default {};\n');
+
+    const plan = buildChangedVerificationPlan({
+        cwd: root,
+        changedFiles: ['apps/product/server/controllers/Domains/search.ts'],
+    });
+
+    assert.ok(planIds(plan).includes('builtin:doc-anchors'));
+});
+
+test('changed verification planner leaves doc anchors alone for unrelated changes', () => {
+    const root = createRoot();
+    writeFile(root, 'README.md', '# Root\n');
+
+    const plan = buildChangedVerificationPlan({
+        cwd: root,
+        changedFiles: ['README.md'],
+    });
+
+    assert.equal(planIds(plan).includes('builtin:doc-anchors'), false);
+});