@platformos/platformos-mcp-supervisor 0.0.2 → 0.2.0

package/dist/adapter-input.spec.js

@@ -0,0 +1,275 @@
+import { APP_SOURCE_SUBTREES } from '@platformos/platformos-common';
+import { join, parse } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { bufferTooLarge, fileApplicability, MAX_BUFFER_BYTES, misplacedSource, notPlatformOSFile, toAbsoluteFilePath, } from './adapter-input.js';
+/**
+ * Without this gate `validate_code` lints ANY path, and because check-common's
+ * `toSourceCode` types an unrecognized extension as JSON, `/etc/passwd` came back as
+ * `ValidJSON` with `must_fix_before_write: true` while `/etc/shadow` containing `{}` came
+ * back `ok` — a false approval for a path outside the project.
+ *
+ * These pin the pure decision; the end-to-end consequence is pinned in
+ * `transport/validate-code.spec.ts`.
+ */
+const PROJECT = join('/srv', 'app');
+const applicable = (filePath) => fileApplicability(PROJECT, filePath);
+/**
+ * The two refusal messages, duplicated from the implementation on purpose: the prose is the
+ * entire payload of a declined call. Both must state that nothing was checked — an agent
+ * must never read a refusal as a pass.
+ */
+const outside = (filePath) => ({
+    applicable: false,
+    code: 'outside_project',
+    reason: `\`${filePath}\` resolves outside the project root (${PROJECT}), so there is no project ` +
+        `context to validate it against. This server validates only files inside the project it was ` +
+        `started for. Nothing was checked — treat this as "unknown", not as approval.`,
+});
+const unsupported = (relativePath) => ({
+    applicable: false,
+    code: 'unsupported_type',
+    reason: `\`${relativePath}\` is not a platformOS source file, so there is nothing to check. The ` +
+        `platform deploys app/, marketplace_builder/, modules/*/public/, modules/*/private/ only. ` +
+        `Nothing was checked — writing this file is your call, not a validated pass. Directory ` +
+        `structure: https://documentation.platformos.com/developer-guide/platformos-workflow/directory-structure`,
+});
+/**
+ * An ASSET is refused for a different reason and says so. It IS part of the app and IS
+ * deployed — there is simply no source in it to check — so the "not a platformOS source
+ * file, the platform deploys app/ only" message above would be false about it.
+ */
+const asset = (relativePath) => ({
+    applicable: false,
+    code: 'unsupported_type',
+    reason: `\`${relativePath}\` is an asset, not a source file the linter understands — it checks ` +
+        `Liquid, GraphQL and YAML — so no check ran against it. The file is still deployed and ` +
+        `served; there is simply nothing here to validate. Nothing was checked, which is not the ` +
+        `same as a pass.`,
+});
+describe('Unit: fileApplicability', () => {
+    describe('accepts every file type the linter would actually visit', () => {
+        it.each([
+            'app/views/pages/index.liquid',
+            'app/views/partials/card.liquid',
+            'app/views/layouts/application.liquid',
+            'app/lib/helper.liquid',
+            // A page that emits JSON is Liquid — classified by the `.liquid` extension, NOT by
+            // the `.json` in its name, which a naive extension check would misroute.
+            'app/views/pages/feed.json.liquid',
+            'app/graphql/things/search.graphql',
+            'app/translations/en.yml',
+            'app/schema/thing.yml',
+            'modules/mcp/public/views/partials/tool.liquid',
+        ])('%s', (filePath) => {
+            expect(applicable(filePath)).toEqual({ applicable: true });
+        });
+        it('accepts an absolute path inside the project', () => {
+            expect(applicable(join(PROJECT, 'app/views/pages/index.liquid'))).toEqual({
+                applicable: true,
+            });
+        });
+        it('accepts a path whose `..` segments normalize back inside the project', () => {
+            expect(applicable('app/views/pages/../partials/card.liquid')).toEqual({ applicable: true });
+        });
+    });
+    describe('declines paths outside the project root', () => {
+        // `''` is refused by the zod schema instead — see validate-code.spec.ts.
+        it.each([
+            ['an absolute system path', '/etc/passwd'],
+            ['a relative traversal', '../../../etc/passwd'],
+            ['a traversal onto a plausible-looking file', '../other/app/views/pages/x.liquid'],
+            ['an absolute path outside the root', '/tmp/scratch/app/views/pages/x.liquid'],
+            // A `startsWith` containment test would ACCEPT this, since
+            // '/srv/app-backup'.startsWith('/srv/app'); only a path-segment comparison rejects it.
+            ['a sibling root extending the project name', '/srv/app-backup/app/views/pages/x.liquid'],
+        ])('%s', (_label, filePath) => {
+            expect(applicable(filePath)).toEqual(outside(filePath));
+        });
+        it.each([
+            ['the project root itself', PROJECT],
+            ['the project root via a round trip', 'app/..'],
+        ])('%s is a directory, not a file under edit', (_label, filePath) => {
+            expect(applicable(filePath)).toEqual(outside(filePath));
+        });
+    });
+    describe('declines in-project files that are not platformOS sources', () => {
+        it.each([
+            ['markdown', 'README.md'],
+            ['plain text', 'app/notes.txt'],
+            // The extension whose fallback used to swallow everything else.
+            ['standalone json', 'app/pos-modules.json'],
+            ['ruby', 'script/deploy.rb'],
+            ['no extension at all', 'Makefile'],
+        ])('%s', (_label, filePath) => {
+            expect(applicable(filePath)).toEqual(unsupported(filePath));
+        });
+        /**
+         * REFUSED BY TYPE, not by extension, and this branch fixes a measured FALSE BLOCK: a
+         * bare `.liquid` has no response format, so `sourceCodeTypeOf` falls back to
+         * `html.liquid` and handed `app/assets/x.liquid` to the Liquid parser. Backwards
+         * besides, since `theme.css.liquid` — the asset form the platform DOES process — was
+         * exempt all along.
+         *
+         * The rule is `platformos-common`'s `isParsedFileType`, and this gate ASKS it rather
+         * than comparing to `PlatformOSFileType.Asset` itself, so it cannot drift from the
+         * lint's answer.
+         */
+        it.each([
+            ['an image', 'app/assets/logo.png'],
+            ['a stylesheet', 'app/assets/site.css'],
+            ['a css asset partial', 'app/assets/site.css.liquid'],
+            ['a js asset partial', 'app/assets/app.js.liquid'],
+            ['an asset manifest', 'app/assets/manifest.json'],
+            // THE CASE THAT WAS BLOCKING WRITES. A parser accepts it; the platform does not
+            // evaluate it. Sabotage check: revert the `Asset` branch in `fileApplicability` and
+            // only this row fails, because it is the only one a parser claims.
+            ['a bare liquid file the parser would accept', 'app/assets/x.liquid'],
+            ['a nested bare liquid file', 'app/assets/nested/deep/w.liquid'],
+            // Legacy spelling of the same directory, so the rule cannot be half-applied.
+            ['a marketplace_builder asset', 'marketplace_builder/assets/x.liquid'],
+        ])('refuses %s as an asset, never as a source', (_label, filePath) => {
+            expect(applicable(filePath)).toEqual(asset(filePath));
+        });
+        /**
+         * THE LINE THIS GATE DRAWS. It asks ONE question — "is this a type we parse at all?" —
+         * from the extension and nothing else, and deliberately not whether the path is
+         * somewhere the platform deploys, which `isSupportedSourceFile(uri, root)` would answer.
+         *
+         * Using that here would collapse two situations into one wrong answer.
+         * `scripts/helper.liquid` IS a platformOS source in the wrong place, and its author
+         * needs to hear "nothing will ever load this", not "this is not a platformOS file".
+         * check-node draws that distinction where classification happens, so the gate admits
+         * anything parseable and lets the lint say which it is.
+         *
+         * So being ADMITTED here means "worth asking about", not "will be linted".
+         */
+        it.each([
+            // Liquid outside every deployed subtree: admitted here, then reported as
+            // `misplaced_source` by the lint, which is the answer that helps.
+            ['unclassified liquid', 'scripts/helper.liquid'],
+            // A REAL platformOS source under master's classification: `PlatformOSFileType` has
+            // `InstanceConfig` (`app/config.yml`) and `UserSchema` (`app/user.yml`) as fixed-path
+            // singletons, and the file-type-coverage group pins that something examines them.
+            ['the app config singleton', 'app/config.yml'],
+            ['the user schema singleton', 'app/user.yml'],
+            // KNOWN WRONG ADVICE, admitted here on purpose rather than special-cased. A `.yml` at
+            // the project root is parseable, so the lint calls it `misplaced-source` — telling the
+            // author of this toolchain's OWN config file that it is "likely misplaced". It never
+            // blocks a write, and narrowing it belongs at the point of classification, in
+            // check-node. Asserted so the behaviour is recorded and the fix has a test to flip.
+            ['the check config itself', '.platformos-check.yml'],
+        ])('admits %s, leaving the verdict to the lint', (_label, filePath) => {
+            expect(applicable(filePath)).toEqual({ applicable: true });
+        });
+        it('reports the PROJECT-RELATIVE path even when given an absolute one', () => {
+            // Forward slashes, spelled literally rather than built with `join`: the reason string
+            // is agent-facing, and an agent that sent `app/notes.txt` must get that spelling back
+            // on every platform. Building the expectation with `join` made it agree with whatever
+            // the host does, so it passed on POSIX while asserting `app\notes.txt` on Windows.
+            //
+            // This cannot FAIL on POSIX if the separator handling regresses — check-common's
+            // `path.spec.ts` is what guards that, over Windows-shaped input on any host.
+            expect(applicable(join(PROJECT, 'app/notes.txt'))).toEqual(unsupported('app/notes.txt'));
+        });
+    });
+    it('checks containment BEFORE type, so an unsupported outside path cites the root', () => {
+        // Both rules reject `/etc/passwd`; the order determines which reason the agent
+        // gets, and "outside the project" is the more actionable of the two.
+        expect(applicable('/etc/passwd')).toEqual(outside('/etc/passwd'));
+    });
+});
+/**
+ * The size bound is the ONLY guard that acts before a pathological buffer reaches the
+ * parser, and it is sized against the FULL lint (~61 ms/KiB), not the parse alone.
+ *
+ * A deadline cannot substitute for it: the parse is synchronous, so the timer cannot even
+ * FIRE during one, and further out the parser stops completing at all — 2 MiB throws inside
+ * ohm's CST→AST recursion, 4 MiB produced a native V8 abort that no handler can catch.
+ */
+describe('Unit: bufferTooLarge', () => {
+    const bytes = (n) => 'a'.repeat(n);
+    it('accepts a buffer at exactly the limit', () => {
+        // Boundary is inclusive — an exactly-limit buffer is legal, so `<=` not `<`.
+        expect(bufferTooLarge(bytes(MAX_BUFFER_BYTES))).toBeUndefined();
+    });
+    it('refuses a buffer one byte over the limit', () => {
+        const declined = bufferTooLarge(bytes(MAX_BUFFER_BYTES + 1));
+        expect(declined?.code).toEqual('too_large');
+        expect(declined?.reason).toEqual('The buffer is 128 KiB, above the 128 KiB limit this server will validate, so it was ' +
+            'refused before parsing. Liquid validation costs about 75 ms per KiB and the parser stops ' +
+            'completing at all a few MiB out, so checking this would risk hanging the server rather ' +
+            'than answering. Nothing was checked — consider splitting the file, which is almost ' +
+            'certainly worth doing at this size regardless.');
+    });
+    it('accepts every realistic file size', () => {
+        // The largest real source file found across local projects is 76 KiB.
+        expect([
+            bufferTooLarge(''),
+            bufferTooLarge('{% render "card" %}'),
+            bufferTooLarge(bytes(76 * 1024)),
+            bufferTooLarge(bytes(120 * 1024)),
+        ]).toEqual([undefined, undefined, undefined, undefined]);
+    });
+    it('counts BYTES, not string length, so multi-byte content cannot slip past', () => {
+        // '€' is 3 bytes in UTF-8. A `content.length` check would see a third of the real cost
+        // and admit a buffer three times the intended size.
+        const justUnderByLength = '€'.repeat(Math.floor(MAX_BUFFER_BYTES / 3) + 1);
+        expect(justUnderByLength.length).toBeLessThan(MAX_BUFFER_BYTES);
+        expect(bufferTooLarge(justUnderByLength)?.code).toEqual('too_large');
+    });
+    it('reports the actual size in the reason, so the agent knows by how much', () => {
+        expect(bufferTooLarge(bytes(2 * 1024 * 1024))?.reason).toContain('The buffer is 2048 KiB');
+    });
+});
+describe('Unit: toAbsoluteFilePath', () => {
+    it('joins a relative path onto the project root', () => {
+        expect(toAbsoluteFilePath(PROJECT, 'app/views/pages/index.liquid')).toEqual(join(PROJECT, 'app/views/pages/index.liquid'));
+    });
+    it('returns an absolute path unchanged', () => {
+        expect(toAbsoluteFilePath(PROJECT, '/etc/passwd')).toEqual('/etc/passwd');
+    });
+    it('normalizes `..` segments when joining', () => {
+        // Expressed against the filesystem ROOT rather than a literal `/etc/passwd`, so it
+        // resolves with the host's own separator; hard-coding the POSIX spelling asserted the
+        // platform rather than the normalization this test is about.
+        const filesystemRoot = parse(PROJECT).root;
+        expect(toAbsoluteFilePath(PROJECT, '../../../etc/passwd')).toEqual(join(filesystemRoot, 'etc', 'passwd'));
+    });
+});
+/**
+ * `next_step` is prose the supervisor writes ABOUT ITS OWN ANSWER, which invariant #6
+ * permits. The line is thin here, because a refusal has to say something about where
+ * platformOS looks for files in order to be actionable at all.
+ *
+ * It stays on the right side of it by DERIVING that fact: the deployed subtrees come from
+ * `APP_SOURCE_SUBTREES`, and the rule itself is a documentation URL. A hand-written list
+ * would be a second source of truth for the directory layout.
+ */
+describe('Unit: refusal prose derives platform facts rather than restating them', () => {
+    const subtrees = APP_SOURCE_SUBTREES.map((subtree) => `${subtree}/`);
+    it.each([
+        ['misplacedSource', misplacedSource('scripts/build.liquid')],
+        ['notPlatformOSFile', notPlatformOSFile('README.md')],
+    ])('%s names every deployed subtree, from the shared table', (_name, declined) => {
+        expect(subtrees.filter((subtree) => !declined.reason.includes(subtree))).toEqual([]);
+    });
+    it('points at the documentation for the rule instead of explaining it here', () => {
+        // The pointer, not the prose: an agent that needs the whole directory layout is sent
+        // to the page that owns it.
+        expect(misplacedSource('scripts/build.liquid').reason).toContain('https://documentation.platformos.com/developer-guide/platformos-workflow/directory-structure');
+    });
+    /**
+     * The CONTROL: this must fail if the subtree list is ever hardcoded to today's value.
+     * Deriving the expectation from the same constant the code reads would pass either way,
+     * so the assertion is that the message tracks a subtree the shared table does NOT
+     * currently contain — impossible to satisfy with a literal string.
+     */
+    it('would track a new subtree without an edit here', () => {
+        // Every subtree in the message came from the table, and the message contains no
+        // directory that looks deployed but is absent from it.
+        const invented = 'definitely_not_a_subtree';
+        expect(misplacedSource('x.liquid').reason).not.toContain(invented);
+        expect(APP_SOURCE_SUBTREES).not.toContain(invented);
+    });
+});
+//# sourceMappingURL=adapter-input.spec.js.map

package/dist/bin/args.d.ts

@@ -6,17 +6,30 @@
  */
 export interface ParsedArgs {
     projectDir?: string;
+    /** `false` only when `--no-impact` was passed. Cross-file impact is ON by default. */
+    impact: boolean;
     help: boolean;
 }
 /**
- * Parse `--project <dir>` / `--project=<dir>` / `--help` / `-h` from a
+ * Parse `--project <dir>` / `--project=<dir>` / `--no-impact` / `--help` / `-h` from a
  * `process.argv.slice(2)`-style array. Unknown flags are tolerated so a
  * forward-compatible client can pass extras without breaking the bin.
  */
 export declare function parseArgs(argv: ReadonlyArray<string>): ParsedArgs;
+/**
+ * Whether cross-file impact runs, by precedence: `--no-impact` wins, then
+ * `POS_SUPERVISOR_NO_IMPACT` (any non-empty value other than `0`/`false`), then ON.
+ *
+ * A SERVER setting rather than a tool parameter, deliberately. The per-call knob would put
+ * the choice with the agent, and an agent that does not know it is editing a shared partial
+ * is exactly the one that would not ask for the check — this server exists for what the
+ * agent does not know. It also keeps the tool surface unchanged: `mode` was a real parameter
+ * here once and was retired, and `stdio-smoke.spec.ts` still asserts a stale one is ignored.
+ */
+export declare function resolveImpactEnabled(args: ParsedArgs, env: NodeJS.ProcessEnv): boolean;
 /**
  * Resolve the project directory by precedence:
  *   1. `--project` argument, 2. `POS_SUPERVISOR_PROJECT_DIR`, 3. cwd.
  */
 export declare function resolveProjectDir(args: ParsedArgs, env: NodeJS.ProcessEnv, cwd: string): string;
-export declare const HELP = "platformos-mcp-supervisor \u2014 MCP stdio server exposing validate_code\n\nUsage:\n  platformos-mcp-supervisor [--project <dir>]\n\nOptions:\n  --project <dir>   Project root to validate against\n                    (env: POS_SUPERVISOR_PROJECT_DIR; default: current directory)\n  -h, --help        Show this help\n";
+export declare const HELP = "platformos-mcp-supervisor \u2014 MCP stdio server exposing validate_code\n\nUsage:\n  platformos-mcp-supervisor [--project <dir>] [--no-impact]\n\nOptions:\n  --project <dir>   Project root to validate against\n                    (env: POS_SUPERVISOR_PROJECT_DIR; default: current directory)\n  --no-impact       Do not compute cross-file impact. Each result still reports\n                    every finding in the buffers you send; it simply stops\n                    reporting what your change breaks in files you are NOT\n                    editing. Costs ~240 ms per request on a 2,600-file project.\n                    (env: POS_SUPERVISOR_NO_IMPACT=1)\n  -h, --help        Show this help\n";

package/dist/bin/args.js

@@ -1,16 +1,20 @@
 /**
- * Parse `--project <dir>` / `--project=<dir>` / `--help` / `-h` from a
+ * Parse `--project <dir>` / `--project=<dir>` / `--no-impact` / `--help` / `-h` from a
  * `process.argv.slice(2)`-style array. Unknown flags are tolerated so a
  * forward-compatible client can pass extras without breaking the bin.
  */
 export function parseArgs(argv) {
     let projectDir;
+    let impact = true;
     let help = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '--help' || arg === '-h') {
             help = true;
         }
+        else if (arg === '--no-impact') {
+            impact = false;
+        }
         else if (arg === '--project') {
             projectDir = argv[i + 1];
             i++;
@@ -19,7 +23,26 @@ export function parseArgs(argv) {
             projectDir = arg.slice('--project='.length);
         }
     }
-    return { projectDir, help };
+    return { projectDir, impact, help };
+}
+/**
+ * Whether cross-file impact runs, by precedence: `--no-impact` wins, then
+ * `POS_SUPERVISOR_NO_IMPACT` (any non-empty value other than `0`/`false`), then ON.
+ *
+ * A SERVER setting rather than a tool parameter, deliberately. The per-call knob would put
+ * the choice with the agent, and an agent that does not know it is editing a shared partial
+ * is exactly the one that would not ask for the check — this server exists for what the
+ * agent does not know. It also keeps the tool surface unchanged: `mode` was a real parameter
+ * here once and was retired, and `stdio-smoke.spec.ts` still asserts a stale one is ignored.
+ */
+export function resolveImpactEnabled(args, env) {
+    if (!args.impact)
+        return false;
+    const disabled = env.POS_SUPERVISOR_NO_IMPACT;
+    if (disabled === undefined || disabled === '' || disabled === '0' || disabled === 'false') {
+        return true;
+    }
+    return false;
 }
 /**
  * Resolve the project directory by precedence:
@@ -31,11 +54,16 @@ export function resolveProjectDir(args, env, cwd) {
 export const HELP = `platformos-mcp-supervisor — MCP stdio server exposing validate_code
 
 Usage:
-  platformos-mcp-supervisor [--project <dir>]
+  platformos-mcp-supervisor [--project <dir>] [--no-impact]
 
 Options:
   --project <dir>   Project root to validate against
                     (env: POS_SUPERVISOR_PROJECT_DIR; default: current directory)
+  --no-impact       Do not compute cross-file impact. Each result still reports
+                    every finding in the buffers you send; it simply stops
+                    reporting what your change breaks in files you are NOT
+                    editing. Costs ~240 ms per request on a 2,600-file project.
+                    (env: POS_SUPERVISOR_NO_IMPACT=1)
   -h, --help        Show this help
 `;
 //# sourceMappingURL=args.js.map

package/dist/bin/args.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin/args.spec.js

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { parseArgs, resolveProjectDir } from './args.js';
+describe('Unit: parseArgs', () => {
+    it('parses --project <dir>', () => {
+        expect(parseArgs(['--project', '/p'])).toEqual({ projectDir: '/p', help: false });
+    });
+    it('parses --project=<dir>', () => {
+        expect(parseArgs(['--project=/p'])).toEqual({ projectDir: '/p', help: false });
+    });
+    it('parses --help and -h', () => {
+        expect(parseArgs(['--help'])).toEqual({ projectDir: undefined, help: true });
+        expect(parseArgs(['-h'])).toEqual({ projectDir: undefined, help: true });
+    });
+    it('tolerates unknown flags', () => {
+        expect(parseArgs(['--future', 'x', '--project', '/p'])).toEqual({
+            projectDir: '/p',
+            help: false,
+        });
+    });
+    it('returns no projectDir when none given', () => {
+        expect(parseArgs([])).toEqual({ projectDir: undefined, help: false });
+    });
+});
+describe('Unit: resolveProjectDir', () => {
+    it('prefers the --project argument over env and cwd', () => {
+        expect(resolveProjectDir({ projectDir: '/arg', help: false }, { POS_SUPERVISOR_PROJECT_DIR: '/env' }, '/cwd')).toEqual('/arg');
+    });
+    it('falls back to POS_SUPERVISOR_PROJECT_DIR when no argument', () => {
+        expect(resolveProjectDir({ help: false }, { POS_SUPERVISOR_PROJECT_DIR: '/env' }, '/cwd')).toEqual('/env');
+    });
+    it('falls back to cwd when neither argument nor env is set', () => {
+        expect(resolveProjectDir({ help: false }, {}, '/cwd')).toEqual('/cwd');
+    });
+});
+//# sourceMappingURL=args.spec.js.map

package/dist/bin/platformos-mcp-supervisor.js

@@ -20,7 +20,7 @@
  */
 import { createLogger } from '../logger.js';
 import { startServer } from '../transport/server.js';
-import { HELP, parseArgs, resolveProjectDir } from './args.js';
+import { HELP, parseArgs, resolveImpactEnabled, resolveProjectDir } from './args.js';
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.help) {
@@ -29,7 +29,11 @@ async function main() {
     }
     const log = createLogger('platformos-mcp-supervisor');
     const projectDir = resolveProjectDir(args, process.env, process.cwd());
-    await startServer({ projectDir, log });
+    await startServer({
+        projectDir,
+        log,
+        impactEnabled: resolveImpactEnabled(args, process.env),
+    });
 }
 main().catch((err) => {
     process.stderr.write(`fatal: ${err?.stack ?? String(err)}\n`);

package/dist/check-docs.d.ts

@@ -0,0 +1,21 @@
+/** The documentation a check publishes about itself. */
+export interface CheckDocs {
+    /** One-line description, from `meta.docs.description`. */
+    description: string;
+    /**
+     * The check's documentation page. Absent for the few checks whose meta publishes no
+     * `url` — absent rather than guessed, because a URL assembled from a code is a link
+     * that 404s, which is worse than no link.
+     */
+    url?: string;
+}
+/**
+ * The documentation for a check code, or `undefined` when nothing is registered under it.
+ *
+ * `undefined` is a real answer, not a gap to paper over: `CheckError` — check-common's code
+ * for "a check crashed on this file" — is reported on offenses and is not a registered
+ * check, so a consumer must handle a miss rather than assume every offense has a page.
+ */
+export declare function checkDocs(code: string): CheckDocs | undefined;
+/** Every registered check code. Exported for the tests that assert this map is complete. */
+export declare function registeredCheckCodes(): string[];

package/dist/check-docs.js

@@ -0,0 +1,38 @@
+/**
+ * What a check MEANS and where to read more — derived from check-common's registry.
+ *
+ * THE SUPERVISOR AUTHORS NO DOCUMENTATION (ARCHITECTURE.md §Invariants). It may describe
+ * itself — its result contract, how to read an answer — and nothing about the platform or
+ * about what a check is for; that prose lives in `meta.docs.description` and at
+ * `meta.docs.url`.
+ *
+ * So this module is a LOOKUP, not a table, built from `allChecks` at load time: a check
+ * renamed, removed or added upstream changes this map without anyone editing it.
+ */
+import { allChecks } from '@platformos/platformos-check-common';
+/**
+ * Keyed by `meta.code` ONLY, which is the exact string an offense carries
+ * (`check: check.meta.code` in check-common's `check()`).
+ *
+ * `meta.aliases` are deliberately NOT keys: an alias is a name a CONFIG may use, never
+ * something an offense carries, so mapping it would add entries nothing can look up.
+ */
+const BY_CODE = new Map(allChecks.map((check) => [
+    check.meta.code,
+    { description: check.meta.docs.description, url: check.meta.docs.url },
+]));
+/**
+ * The documentation for a check code, or `undefined` when nothing is registered under it.
+ *
+ * `undefined` is a real answer, not a gap to paper over: `CheckError` — check-common's code
+ * for "a check crashed on this file" — is reported on offenses and is not a registered
+ * check, so a consumer must handle a miss rather than assume every offense has a page.
+ */
+export function checkDocs(code) {
+    return BY_CODE.get(code);
+}
+/** Every registered check code. Exported for the tests that assert this map is complete. */
+export function registeredCheckCodes() {
+    return [...BY_CODE.keys()];
+}
+//# sourceMappingURL=check-docs.js.map

package/dist/check-docs.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/check-docs.spec.js

@@ -0,0 +1,87 @@
+/**
+ * The check-documentation lookup is DERIVED, and these assertions are written so a
+ * documentation release cannot fail them while OUR side falling behind does.
+ *
+ * Nothing here restates what a check's description SAYS, or which URL it has. That is
+ * settled in check-common and in the `platformos-documentation` repo, where the page
+ * lives; a test here that pinned the text would duplicate a gate it cannot see and rot on
+ * a release that is perfectly correct.
+ */
+import { allChecks } from '@platformos/platformos-check-common';
+import { describe, expect, it } from 'vitest';
+import { checkDocs, registeredCheckCodes } from './check-docs.js';
+describe('Unit: checkDocs', () => {
+    it('answers for every registered check, and for nothing else', () => {
+        // Derived on both sides: the registry is the input AND the expectation, so adding a
+        // check upstream cannot leave this map behind.
+        expect(registeredCheckCodes().sort()).toEqual(allChecks.map((check) => check.meta.code).sort());
+    });
+    it('returns each check its own description, taken from the registry rather than restated', () => {
+        const mismatched = allChecks
+            .map((check) => ({
+            code: check.meta.code,
+            expected: check.meta.docs.description,
+            actual: checkDocs(check.meta.code)?.description,
+        }))
+            .filter((entry) => entry.actual !== entry.expected);
+        expect(mismatched).toEqual([]);
+    });
+    it('returns the check its own documentation URL, and omits it when meta publishes none', () => {
+        const mismatched = allChecks
+            .map((check) => ({
+            code: check.meta.code,
+            expected: check.meta.docs.url,
+            actual: checkDocs(check.meta.code)?.url,
+        }))
+            .filter((entry) => entry.actual !== entry.expected);
+        expect(mismatched).toEqual([]);
+    });
+    /**
+     * A miss is a real answer. `CheckError` is check-common's code for "a check crashed on
+     * this file"; it reaches an agent as an ordinary offense and has no registry entry, so a
+     * consumer that assumed every code resolves would throw on exactly the paths that are
+     * already going wrong.
+     */
+    it('returns undefined for a code that is not a registered check', () => {
+        expect(checkDocs('CheckError')).toBeUndefined();
+        expect(checkDocs('NotACheckAtAll')).toBeUndefined();
+    });
+    /**
+     * EVERY check publishes a documentation URL — a requirement rather than a report, now
+     * that the server instructions tell an agent to follow `see_also` instead of restating
+     * platform rules. A check with no URL means an agent is stopped by a finding and given
+     * nowhere to read about it.
+     *
+     * A new check therefore fails here until it is documented: the page is part of shipping a
+     * check, not a follow-up.
+     */
+    it('every registered check publishes a documentation URL', () => {
+        const withoutUrl = allChecks
+            .filter((check) => !check.meta.docs.url)
+            .map((check) => check.meta.code)
+            .sort();
+        expect(withoutUrl, `these checks have no docs.url — add a page under ` +
+            `app/views/pages/developer-guide/platformos-check/checks/ in platformos-documentation, ` +
+            `plus its overview row and nav entry:\n${withoutUrl.join('\n')}`).toEqual([]);
+    });
+    /**
+     * The URL must be one the documentation site can serve, not merely a non-empty string.
+     *
+     * Asserted by SHAPE rather than by fetching — no network in a unit test — which still
+     * catches the realistic mistake: a URL pointing at the wrong section, or a check code
+     * pasted where a slug belongs.
+     *
+     * A check with NO url is skipped rather than dereferenced; that is the sibling test's
+     * subject, and a `TypeError` here would preempt it.
+     */
+    it('every documentation URL points into the checks section of the docs site', () => {
+        const BASE = 'https://documentation.platformos.com/developer-guide/platformos-check/checks/';
+        const malformed = allChecks
+            .map((check) => ({ code: check.meta.code, url: check.meta.docs.url }))
+            .filter(({ url }) => url !== undefined &&
+            (!url.startsWith(BASE) || !/^[a-z0-9-]+$/.test(url.slice(BASE.length))))
+            .map(({ code, url }) => `${code} -> ${url}`);
+        expect(malformed).toEqual([]);
+    });
+});
+//# sourceMappingURL=check-docs.spec.js.map

package/dist/context.d.ts

@@ -0,0 +1,34 @@
+/** The per-server context and the request-path deadlines — shared INFRASTRUCTURE. */
+import type { Logger } from './logger.js';
+/**
+ * Per-server context threaded into every handler.
+ *
+ * NO CACHE HANDLES HERE, and their absence is the point. check-node keeps ONE lazy `App`
+ * per project at process level and reconciles it per call, so a cache nobody has to
+ * remember to pass is a cache no call path can forget — do not reintroduce a handle here
+ * (see check-node's "Process-level state"). Impact is likewise DERIVED per request from
+ * the project's text (`impact/project-scan.ts`), so nothing can be stale.
+ */
+export interface SupervisorContext {
+    /** Absolute project root that buffers are validated against. */
+    projectDir: string;
+    log: Logger;
+    /**
+     * Whether cross-file impact runs. OPTIONAL AND DEFAULTING TO ON: impact is a safety
+     * feature, so a context that forgets to mention it must get the safe behaviour rather than
+     * silently lose the check. Only an explicit `false` — from `--no-impact` or
+     * `POS_SUPERVISOR_NO_IMPACT` — turns it off.
+     */
+    impactEnabled?: boolean;
+}
+/**
+ * Deadline for impact. Much tighter than the lint's, which is a function of admitted bytes
+ * and lives in `cost-model.ts` — deliberately not re-exported from here.
+ *
+ * A BACKSTOP, NOT THE BOUND. A lint is synchronous CPU work and no timer preempts it (see
+ * `deadline.ts`), so what actually limits impact is bounded INPUT — `MAX_CANDIDATE_BYTES` and
+ * `MAX_DEPENDANTS_LINTED` in `cost-model.ts`, both derived to fit inside this number. This
+ * catches what those cannot: a stalled read, or a project large enough that the read alone
+ * runs long. Exceeding it costs only the answer, which has an `unavailable` state.
+ */
+export declare const IMPACT_DEADLINE_MS = 2000;

package/dist/context.js

@@ -0,0 +1,12 @@
+/**
+ * Deadline for impact. Much tighter than the lint's, which is a function of admitted bytes
+ * and lives in `cost-model.ts` — deliberately not re-exported from here.
+ *
+ * A BACKSTOP, NOT THE BOUND. A lint is synchronous CPU work and no timer preempts it (see
+ * `deadline.ts`), so what actually limits impact is bounded INPUT — `MAX_CANDIDATE_BYTES` and
+ * `MAX_DEPENDANTS_LINTED` in `cost-model.ts`, both derived to fit inside this number. This
+ * catches what those cannot: a stalled read, or a project large enough that the read alone
+ * runs long. Exceeding it costs only the answer, which has an `unavailable` state.
+ */
+export const IMPACT_DEADLINE_MS = 2_000;
+//# sourceMappingURL=context.js.map