proteum 2.5.9 → 2.5.11

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,200 @@ 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 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/ui-singletons.test.cjs

@@ -0,0 +1,104 @@
+const assert = require('node:assert/strict');
+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');
+
+const {
+    isUiSingletonRequest,
+    resolveUiSingletonAliases,
+    resolveUiSingletonServerExternalRequest,
+} = require('../cli/compiler/common/uiSingletons.ts');
+
+test('UI singleton matcher includes React and Preact runtime packages', () => {
+    assert.equal(isUiSingletonRequest('preact'), true);
+    assert.equal(isUiSingletonRequest('preact/hooks'), true);
+    assert.equal(isUiSingletonRequest('preact-render-to-string'), true);
+    assert.equal(isUiSingletonRequest('react'), true);
+    assert.equal(isUiSingletonRequest('react-dom/client'), true);
+});
+
+test('UI singleton matcher does not match unrelated React-prefixed packages', () => {
+    assert.equal(isUiSingletonRequest('react-number-format'), false);
+    assert.equal(isUiSingletonRequest('reactive-stream'), false);
+    assert.equal(isUiSingletonRequest('@radix-ui/react-popover'), false);
+    assert.equal(isUiSingletonRequest(undefined), false);
+});
+
+test('UI singleton aliases resolve React imports to Preact runtime requests', () => {
+    const seenRequests = [];
+    const seenPackageRoots = [];
+    const aliases = resolveUiSingletonAliases({
+        resolvePackageRoot: (packageName) => {
+            seenPackageRoots.push(packageName);
+            return `/app/node_modules/${packageName}`;
+        },
+        resolveRequest: (request) => {
+            seenRequests.push(request);
+            return `/app/node_modules/${request}`;
+        },
+    });
+
+    assert.equal(aliases['preact'], '/app/node_modules/preact');
+    assert.equal(aliases['preact$'], '/app/node_modules/preact');
+    assert.equal(aliases['preact/hooks$'], '/app/node_modules/preact/hooks');
+    assert.equal(aliases['react$'], '/app/node_modules/preact/compat');
+    assert.equal(aliases['react-dom$'], '/app/node_modules/preact/compat');
+    assert.equal(aliases['react-dom/client$'], '/app/node_modules/preact/compat/client');
+    assert.equal(aliases['react/jsx-runtime$'], '/app/node_modules/preact/jsx-runtime');
+    assert.equal(aliases['preact-render-to-string'], '/app/node_modules/preact-render-to-string');
+    assert.equal(aliases['preact-render-to-string$'], '/app/node_modules/preact-render-to-string');
+    assert.deepEqual(seenPackageRoots, ['preact', 'preact-render-to-string']);
+    assert.equal(
+        Object.keys(aliases).indexOf('preact/jsx-dev-runtime$') < Object.keys(aliases).indexOf('preact'),
+        true,
+    );
+    assert.deepEqual(
+        seenRequests.filter((request) => request === 'preact-render-to-string'),
+        ['preact-render-to-string'],
+    );
+});
+
+test('UI singleton server externals resolve Preact and React compat requests from the app', () => {
+    const seenRequests = [];
+    const resolveRequest = (request) => {
+        seenRequests.push(request);
+        return `/app/node_modules/${request}`;
+    };
+
+    assert.equal(resolveUiSingletonServerExternalRequest('preact', resolveRequest), '/app/node_modules/preact');
+    assert.equal(
+        resolveUiSingletonServerExternalRequest('preact/hooks', resolveRequest),
+        '/app/node_modules/preact/hooks',
+    );
+    assert.equal(
+        resolveUiSingletonServerExternalRequest('react', resolveRequest),
+        '/app/node_modules/preact/compat',
+    );
+    assert.equal(
+        resolveUiSingletonServerExternalRequest('react/jsx-runtime', resolveRequest),
+        '/app/node_modules/preact/jsx-runtime',
+    );
+    assert.equal(
+        resolveUiSingletonServerExternalRequest('react-dom/client', resolveRequest),
+        '/app/node_modules/preact/compat/client',
+    );
+    assert.deepEqual(seenRequests, [
+        'preact',
+        'preact/hooks',
+        'preact/compat',
+        'preact/jsx-runtime',
+        'preact/compat/client',
+    ]);
+});
+
+test('UI singleton server externals keep the SSR renderer compiled', () => {
+    const resolveRequest = () => {
+        throw new Error('should not resolve');
+    };
+
+    assert.equal(resolveUiSingletonServerExternalRequest('preact-render-to-string', resolveRequest), undefined);
+});

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);
+});

package/agents/project/app-root/AGENTS.md

@@ -1,14 +0,0 @@
-# Proteum App-Root Addendum
-
-This file is the app-root-only addendum for a Proteum app that lives inside a larger monorepo.
-Keep the reusable Proteum contract in the nearest ancestor root `AGENTS.md`, and keep this file only for instructions that depend on the current directory being the Proteum app root.
-Role: keep only app-root workflow and local project-semantic rules here.
-Do not put here: reusable Proteum architecture contracts, shared verification rules, documentation-driven coding workflow, diagnostics workflow, optimization checklists, coding-style details, or area-specific rules already covered by broader `AGENTS.md` files or the root-level `DOCUMENTATION.md`, `diagnostics.md`, `optimizations.md`, and `CODING_STYLE.md`.
-
-## App-Root Triggers
-
-- If you are working in a newly created Proteum worktree, before following the rest of these instructions:
-  - Run `npx proteum worktree init --source <source-app-root>`.
-  - Read and acknowledge the applicable `AGENTS.md` files.
-  - Run the dev server with the task-safe elevated-permissions launch workflow from the reusable root `AGENTS.md`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link. If `proteum dev` reports blocked instruction paths, resolve them before continuing.
-- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, use root-level `DOCUMENTATION.md` to choose the smallest relevant `./docs/` pack before editing. If a dev server is already running, print the live dev server URL as a clickable Markdown link.