@platformos/platformos-mcp-supervisor 0.1.0 → 0.2.0

package/README.md

@@ -51,11 +51,26 @@ input { file_path, content } | { files: [...] }
   → ValidateCodeResult
 ```
 
-The lint and the blast radius run concurrently; the lint is the long pole and the blast
-radius hides behind it. Nothing is cached between calls on the blast-radius side: it reads
-the project's edge sources, keeps the few that could name the edited file, and resolves
-their references through `platformos-graph` — so the answer is fresh by construction rather
-than by revalidating a stored graph.
+Impact reports one thing: **what your change breaks in files you are not editing**. It finds
+the edited file's dependants through `platformos-graph`, lints them twice — once with your
+changeset applied, once without — and reports only the findings the change INTRODUCED. Those
+findings are the check engine's own, so they arrive with the same message, severity,
+documentation link and fixes as any other diagnostic; nothing about "what is broken" is
+re-derived here.
+
+The project READ overlaps the primary lint, but the two impact lint passes cannot: they share
+check-node's process-wide `App`, which has no lock. So the primary lint runs first and is
+never delayed by, or lost to, impact.
+
+Two bounds keep it affordable, both measured and both reported when hit — `IMPACT_DEADLINE_MS`
+cannot bound this work, since a lint is synchronous CPU and no timer preempts it:
+`MAX_CANDIDATE_BYTES` caps the text discovery will parse, and `MAX_DEPENDANTS_LINTED` caps how
+many dependants get linted. Start the server with `--no-impact` (or
+`POS_SUPERVISOR_NO_IMPACT=1`) to switch the whole stage off; results then carry
+`impact.status: "disabled"`.
+
+It never answers "who depends on this file": `{% render var %}` names its target at runtime,
+so that question has no sound static answer and no count is published in place of one.
 
 ## What this package is not
 

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/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/context.d.ts

@@ -6,21 +6,29 @@ import type { Logger } from './logger.js';
  * 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"). The blast radius is likewise DERIVED per
- * request from the project's text (`impact/project-scan.ts`), so nothing can be stale.
+ * (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 the blast radius. 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.
+ * 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.
  *
- * Tight because the work is small — one project read (235 ms measured on a 2,615-file
- * project) plus a name filter and a handful of parses, p50 9 ms / p90 63 ms per file — and
- * because exceeding it costs only the answer, which has an `unavailable` state. The tail it
- * exists for is real but rare: the most-referenced partial measured took ~1 s.
+ * 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

@@ -1,11 +1,12 @@
 /**
- * Deadline for the blast radius. 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.
+ * 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.
  *
- * Tight because the work is small — one project read (235 ms measured on a 2,615-file
- * project) plus a name filter and a handful of parses, p50 9 ms / p90 63 ms per file — and
- * because exceeding it costs only the answer, which has an `unavailable` state. The tail it
- * exists for is real but rare: the most-referenced partial measured took ~1 s.
+ * 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

package/dist/cost-model.d.ts

@@ -126,3 +126,63 @@ export declare function lintDeadlineMs(bytes: number): number;
  * cap from the deadline ceiling instead of from a round multiple of the per-buffer bound.
  */
 export declare function maxBytesWithin(deadlineMs: number): number;
+/**
+ * How many DEPENDANTS one request will lint when computing impact.
+ *
+ * THE REAL BOUND ON IMPACT, and not a nicety. `IMPACT_DEADLINE_MS` cannot bound this work:
+ * a lint is synchronous CPU on the one event loop, so no timer preempts it (see
+ * `deadline.ts`). Bounding the INPUT is the only defence, exactly as `MAX_BUFFER_BYTES` is
+ * for the primary lint.
+ *
+ * DERIVED from the deadline it has to fit inside, on the worst project scale:
+ *
+ *   impact deadline                                     2 000 ms
+ *   less the project read at 10k files                  ~ 850 ms
+ *   leaves for both lint passes                         ~1 150 ms
+ *
+ * Measured twice-lint cost, and the same {@link LOAD_FACTOR} the lint deadline uses:
+ *
+ *   100 dependants   258 ms idle    774 ms loaded   -> 1 624 ms total, FITS
+ *   200 dependants   487 ms idle  1 460 ms loaded   -> over
+ *   311 dependants   716 ms idle  2 147 ms loaded   -> over on its own
+ *
+ * 311 is not hypothetical: it is the most-depended-on file measured on a real 2 615-file
+ * application (`lib/current_profile`). The same measurement puts 99.37% of targets at 100
+ * dependants or fewer — p50 1, p90 4, p99 59 — so the bound is hit rarely and, when it is,
+ * IT IS REPORTED (`unchecked_dependants`) rather than silently shortening the analysis.
+ */
+export declare const MAX_DEPENDANTS_LINTED = 100;
+/**
+ * Cost of DISCOVERING dependants, per KiB of candidate text.
+ *
+ * Discovery parses every file whose text contains the target's name and resolves its
+ * references through the graph, so it scales with the BYTES it must parse rather than with
+ * the file count. Measured on a real 2 615-file application across four very differently
+ * shaped targets: 12.82, 12.52, 8.59 and 14.60 ms/KiB. Held above the slowest observed, for
+ * the same reason {@link LINT_MS_PER_KIB} is.
+ */
+export declare const DISCOVERY_MS_PER_KIB = 15;
+/**
+ * How much candidate text one target's discovery will parse before giving up.
+ *
+ * WHY A BOUND AT ALL, and why it is not {@link MAX_DEPENDANTS_LINTED}: that one bounds the
+ * two lint passes, which happen AFTER discovery. Discovery itself was unbounded, and the
+ * most-referenced file on a real application (`lib/current_profile`, 312 candidates) cost
+ * 4.7 s and then returned `unavailable` anyway — seconds spent to reach "I do not know".
+ * The candidate byte total is known from a substring scan, before a single parse, so the
+ * same answer costs milliseconds instead.
+ *
+ * DERIVED from what has to fit inside `IMPACT_DEADLINE_MS`:
+ *
+ *   impact deadline                                    2 000 ms
+ *   less the project read                              ~ 235 ms
+ *   less both lint passes at the dependant bound       ~ 258 ms
+ *   leaves for discovery                              ~1 507 ms
+ *   at {@link DISCOVERY_MS_PER_KIB}                     ~100 KiB
+ *
+ * Held at 64 KiB rather than 100, because 100 spends the entire remaining budget and leaves
+ * nothing for a larger project's read. Measured against the same application: candidate text
+ * is p50 1 KiB, p90 13, p95 23, p99 143 — so 64 KiB is nearly 3x the p95 and turns away
+ * 2.51% of targets, each in a few milliseconds instead of several seconds.
+ */
+export declare const MAX_CANDIDATE_BYTES: number;

package/dist/cost-model.js

@@ -134,4 +134,64 @@ export function lintDeadlineMs(bytes) {
 export function maxBytesWithin(deadlineMs) {
     return Math.floor(deadlineMs / DEADLINE_MS_PER_KIB) * 1024;
 }
+/**
+ * How many DEPENDANTS one request will lint when computing impact.
+ *
+ * THE REAL BOUND ON IMPACT, and not a nicety. `IMPACT_DEADLINE_MS` cannot bound this work:
+ * a lint is synchronous CPU on the one event loop, so no timer preempts it (see
+ * `deadline.ts`). Bounding the INPUT is the only defence, exactly as `MAX_BUFFER_BYTES` is
+ * for the primary lint.
+ *
+ * DERIVED from the deadline it has to fit inside, on the worst project scale:
+ *
+ *   impact deadline                                     2 000 ms
+ *   less the project read at 10k files                  ~ 850 ms
+ *   leaves for both lint passes                         ~1 150 ms
+ *
+ * Measured twice-lint cost, and the same {@link LOAD_FACTOR} the lint deadline uses:
+ *
+ *   100 dependants   258 ms idle    774 ms loaded   -> 1 624 ms total, FITS
+ *   200 dependants   487 ms idle  1 460 ms loaded   -> over
+ *   311 dependants   716 ms idle  2 147 ms loaded   -> over on its own
+ *
+ * 311 is not hypothetical: it is the most-depended-on file measured on a real 2 615-file
+ * application (`lib/current_profile`). The same measurement puts 99.37% of targets at 100
+ * dependants or fewer — p50 1, p90 4, p99 59 — so the bound is hit rarely and, when it is,
+ * IT IS REPORTED (`unchecked_dependants`) rather than silently shortening the analysis.
+ */
+export const MAX_DEPENDANTS_LINTED = 100;
+/**
+ * Cost of DISCOVERING dependants, per KiB of candidate text.
+ *
+ * Discovery parses every file whose text contains the target's name and resolves its
+ * references through the graph, so it scales with the BYTES it must parse rather than with
+ * the file count. Measured on a real 2 615-file application across four very differently
+ * shaped targets: 12.82, 12.52, 8.59 and 14.60 ms/KiB. Held above the slowest observed, for
+ * the same reason {@link LINT_MS_PER_KIB} is.
+ */
+export const DISCOVERY_MS_PER_KIB = 15;
+/**
+ * How much candidate text one target's discovery will parse before giving up.
+ *
+ * WHY A BOUND AT ALL, and why it is not {@link MAX_DEPENDANTS_LINTED}: that one bounds the
+ * two lint passes, which happen AFTER discovery. Discovery itself was unbounded, and the
+ * most-referenced file on a real application (`lib/current_profile`, 312 candidates) cost
+ * 4.7 s and then returned `unavailable` anyway — seconds spent to reach "I do not know".
+ * The candidate byte total is known from a substring scan, before a single parse, so the
+ * same answer costs milliseconds instead.
+ *
+ * DERIVED from what has to fit inside `IMPACT_DEADLINE_MS`:
+ *
+ *   impact deadline                                    2 000 ms
+ *   less the project read                              ~ 235 ms
+ *   less both lint passes at the dependant bound       ~ 258 ms
+ *   leaves for discovery                              ~1 507 ms
+ *   at {@link DISCOVERY_MS_PER_KIB}                     ~100 KiB
+ *
+ * Held at 64 KiB rather than 100, because 100 spends the entire remaining budget and leaves
+ * nothing for a larger project's read. Measured against the same application: candidate text
+ * is p50 1 KiB, p90 13, p95 23, p99 143 — so 64 KiB is nearly 3x the p95 and turns away
+ * 2.51% of targets, each in a few milliseconds instead of several seconds.
+ */
+export const MAX_CANDIDATE_BYTES = 64 * 1024;
 //# sourceMappingURL=cost-model.js.map

package/dist/enrich/enrich.d.ts

@@ -85,3 +85,21 @@ export interface EnrichContext {
  * which is also the one truncation keeps: the cap retains the top of the file.
  */
 export declare function enrichDiagnostics(inputs: readonly EnrichInput[], context: EnrichContext): ValidateCodeDiagnostic[];
+/**
+ * Enrich a whole lint pass, reusing ONE docset resolution for every file in it.
+ *
+ * Shared by the primary lint and by the impact diff, so a finding reported in a file the
+ * agent is not editing carries the same documentation URL and the same hint as one in a file
+ * it is. A failure here degrades to unenriched findings rather than losing them: enrichment
+ * is additive, and dropping a diagnostic because its docs could not be read would trade a
+ * real finding for a cosmetic one.
+ */
+export declare function enrichBatch(lint: EnrichableBatch, resolve: () => Promise<DocsetVocabulary>, log: (message: string) => void): Promise<Map<string, ValidateCodeDiagnostic[]>>;
+/** The part of a lint pass {@link enrichBatch} reads — structural, so impact can pass its own. */
+export interface EnrichableBatch {
+    diagnostics: Map<string, ValidateCodeDiagnostic[]>;
+    sources?: Map<string, {
+        ast?: LiquidHtmlNode;
+        startIndexes: number[];
+    }>;
+}

package/dist/enrich/enrich.js

@@ -4,6 +4,10 @@
 import { render } from '@platformos/platformos-language-server-common/dist/docset/index.js';
 import { checkDocs } from '../check-docs.js';
 import { documentedSymbolAt } from './symbol.js';
+// Local, matching `validate-buffers.ts` and `transport/process-guards.ts`, which each carry
+// their own. Three copies is a smell worth collapsing into one shared helper — separately,
+// not in the middle of a feature.
+const describe = (error) => (error instanceof Error ? error.message : String(error));
 /**
  * The checks for which a published SIGNATURE is the answer.
  *
@@ -94,4 +98,39 @@ function entryFor(symbol, vocabulary) {
             : vocabulary.objects;
     return entries.find((entry) => entry.name === symbol.name);
 }
+/**
+ * Enrich a whole lint pass, reusing ONE docset resolution for every file in it.
+ *
+ * Shared by the primary lint and by the impact diff, so a finding reported in a file the
+ * agent is not editing carries the same documentation URL and the same hint as one in a file
+ * it is. A failure here degrades to unenriched findings rather than losing them: enrichment
+ * is additive, and dropping a diagnostic because its docs could not be read would trade a
+ * real finding for a cosmetic one.
+ */
+export async function enrichBatch(lint, resolve, log) {
+    let found = 0;
+    for (const diagnostics of lint.diagnostics.values())
+        found += diagnostics.length;
+    if (found === 0)
+        return lint.diagnostics;
+    try {
+        const vocabulary = await resolve();
+        return new Map([...lint.diagnostics].map(([key, diagnostics]) => {
+            const source = lint.sources?.get(key);
+            // `startIndexes` is index-aligned with `diagnostics` by construction in
+            // `runBatchLint`; a missing entry can only mean the two got out of step, so the
+            // offset is passed as ABSENT rather than as an out-of-range sentinel that would
+            // resolve to some unrelated symbol.
+            const inputs = diagnostics.map((diagnostic, index) => ({
+                diagnostic,
+                startIndex: source?.startIndexes[index],
+            }));
+            return [key, enrichDiagnostics(inputs, { ast: source?.ast, vocabulary })];
+        }));
+    }
+    catch (error) {
+        log(`enrichment failed, returning findings unenriched: ${describe(error)}`);
+        return lint.diagnostics;
+    }
+}
 //# sourceMappingURL=enrich.js.map

package/dist/impact/dependants.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Which files depend on the one being edited — the input to the lint diff, and nothing more.
+ *
+ * This module answers only "which files should I lint to find out what this change broke".
+ * It never decides whether something IS broken: that is the check engine's job, and the
+ * whole point of the diff is to stop reimplementing it here.
+ *
+ * NO EDGE-KIND FILTER, deliberately. An earlier version kept only `render`/`include`/
+ * `function` because it compared arguments by hand and any other kind produced false
+ * positives. The engine has no such problem — a `{% background %}` caller, a layout edge or
+ * an asset reference can each be broken by an edit — so every kind is a dependant here.
+ *
+ * `null` means NOT LOOKED AT: too much candidate text to examine inside the deadline. It is
+ * not "no dependants" and must never be reported as one.
+ *
+ * SOUND, NOT COMPLETE, and the gap is not closable. Every edge platformos-graph records
+ * names its target with a STATIC STRING LITERAL, so a dependant's text must contain the
+ * target's logical name; filtering on that is a sound over-approximation leaving few
+ * survivors (measured p50 1, p90 6 candidates on a 2,615-file project), and 0 of 8,464 real
+ * edges were dropped by it. What it cannot see is a caller that names its target at runtime
+ * or does not parse — see `frontier.ts`, which reports exactly that gap rather than hiding
+ * it.
+ */
+import { type UriString } from '@platformos/platformos-check-common';
+import type { ProjectScan } from './project-scan.js';
+/**
+ * Whether this file could have dependants AT ALL — decidable from its path alone, with no
+ * project read and no parse.
+ *
+ * TWO CONDITIONS, and both are load-bearing:
+ *
+ *   - it must be a resolvable edge TARGET, which means Liquid or GraphQL. Schema,
+ *     custom-model-type and translation YAML are deliberately excluded: they are wired by
+ *     model, table or translation-key NAME rather than by file reference (ADR 004), so the
+ *     graph holds no edge to them and asking would silently answer "nothing depends on this".
+ *     Giving those files real dependants is TASK-95, in the graph rather than here.
+ *   - it must have a logical NAME, since a reference spells one. A source in no platformOS
+ *     directory has none and so cannot be referenced.
+ *
+ * Asked twice on purpose: by the orchestrator, to skip reading the project for a changeset
+ * that cannot use it, and by impact itself. One predicate, so the two cannot disagree about
+ * whether that read was needed.
+ */
+export declare function canHaveDependants(uri: UriString, rootUri: UriString): boolean;
+/**
+ * The distinct files that reference `fileUri`, excluding anything in `exclude`.
+ *
+ * `exclude` carries the changeset: a file being edited is already reported on its own terms,
+ * and linting it again as somebody's dependant would report the same finding twice. It also
+ * makes the scan's text the DISK text for every dependant returned, which is exactly what
+ * the diff's baseline pass needs — the scan overlays buffers, so excluding them is what
+ * keeps the baseline honest without a second read.
+ */
+export declare function dependantsOf(scan: ProjectScan, fileUri: UriString, name: string, exclude: ReadonlySet<UriString>): Promise<UriString[] | null>;
+/**
+ * A dependant as the lint takes it: an absolute path and the text on disk.
+ *
+ * Carries its own `uri` rather than relying on position, because {@link toDependantBuffers}
+ * can DROP an entry — zipping the result back against the input by index would then pair
+ * every later buffer with the wrong file, silently.
+ */
+export interface DependantBuffer {
+    uri: UriString;
+    filePath: string;
+    content: string;
+}
+/**
+ * Turn dependant URIs into lint buffers, reading their text from the scan the discovery
+ * already paid for rather than going back to disk.
+ *
+ * `path.fsPath` is check-common's own URI-to-path conversion, not a local spelling of it: on
+ * Windows a URI and a filesystem path differ in separator AND in how the drive letter is
+ * encoded, and a hand-rolled conversion is the mistake that only the Windows CI job catches.
+ */
+export declare function toDependantBuffers(uris: readonly UriString[], sources: ReadonlyMap<UriString, string>): DependantBuffer[];

package/dist/impact/dependants.js

@@ -0,0 +1,104 @@
+/**
+ * Which files depend on the one being edited — the input to the lint diff, and nothing more.
+ *
+ * This module answers only "which files should I lint to find out what this change broke".
+ * It never decides whether something IS broken: that is the check engine's job, and the
+ * whole point of the diff is to stop reimplementing it here.
+ *
+ * NO EDGE-KIND FILTER, deliberately. An earlier version kept only `render`/`include`/
+ * `function` because it compared arguments by hand and any other kind produced false
+ * positives. The engine has no such problem — a `{% background %}` caller, a layout edge or
+ * an asset reference can each be broken by an edit — so every kind is a dependant here.
+ *
+ * `null` means NOT LOOKED AT: too much candidate text to examine inside the deadline. It is
+ * not "no dependants" and must never be reported as one.
+ *
+ * SOUND, NOT COMPLETE, and the gap is not closable. Every edge platformos-graph records
+ * names its target with a STATIC STRING LITERAL, so a dependant's text must contain the
+ * target's logical name; filtering on that is a sound over-approximation leaving few
+ * survivors (measured p50 1, p90 6 candidates on a 2,615-file project), and 0 of 8,464 real
+ * edges were dropped by it. What it cannot see is a caller that names its target at runtime
+ * or does not parse — see `frontier.ts`, which reports exactly that gap rather than hiding
+ * it.
+ */
+import { path, SourceCodeType } from '@platformos/platformos-check-common';
+import { MAX_CANDIDATE_BYTES } from '../cost-model.js';
+import { sourceCodeTypeOf, uriToName } from '@platformos/platformos-common';
+import { extractFileReferences, toSourceCode } from '@platformos/platformos-graph';
+/**
+ * Whether this file could have dependants AT ALL — decidable from its path alone, with no
+ * project read and no parse.
+ *
+ * TWO CONDITIONS, and both are load-bearing:
+ *
+ *   - it must be a resolvable edge TARGET, which means Liquid or GraphQL. Schema,
+ *     custom-model-type and translation YAML are deliberately excluded: they are wired by
+ *     model, table or translation-key NAME rather than by file reference (ADR 004), so the
+ *     graph holds no edge to them and asking would silently answer "nothing depends on this".
+ *     Giving those files real dependants is TASK-95, in the graph rather than here.
+ *   - it must have a logical NAME, since a reference spells one. A source in no platformOS
+ *     directory has none and so cannot be referenced.
+ *
+ * Asked twice on purpose: by the orchestrator, to skip reading the project for a changeset
+ * that cannot use it, and by impact itself. One predicate, so the two cannot disagree about
+ * whether that read was needed.
+ */
+export function canHaveDependants(uri, rootUri) {
+    const type = sourceCodeTypeOf(uri);
+    const isEdgeTarget = type === SourceCodeType.LiquidHtml || type === SourceCodeType.GraphQL;
+    return isEdgeTarget && uriToName(uri, rootUri)?.name !== undefined;
+}
+/**
+ * The distinct files that reference `fileUri`, excluding anything in `exclude`.
+ *
+ * `exclude` carries the changeset: a file being edited is already reported on its own terms,
+ * and linting it again as somebody's dependant would report the same finding twice. It also
+ * makes the scan's text the DISK text for every dependant returned, which is exactly what
+ * the diff's baseline pass needs — the scan overlays buffers, so excluding them is what
+ * keeps the baseline honest without a second read.
+ */
+export async function dependantsOf(scan, fileUri, name, exclude) {
+    const sources = await scan.sources();
+    const candidates = [...sources].filter(([uri, source]) => !exclude.has(uri) && uri !== fileUri && source.includes(name));
+    // BOUNDED BEFORE THE EXPENSIVE PART. Parsing is what discovery costs, and the byte total
+    // is known from the substring scan already done — so a file referenced from too much text
+    // to examine says so in milliseconds instead of spending seconds to reach the same answer.
+    const bytes = candidates.reduce((total, [, source]) => total + Buffer.byteLength(source), 0);
+    if (bytes > MAX_CANDIDATE_BYTES)
+        return null;
+    const perCandidate = await Promise.all(candidates.map(async ([uri, source]) => {
+        const sourceCode = await toSourceCode(uri, source);
+        const references = await extractFileReferences(scan.rootUri, uri, sourceCode, {
+            fs: scan.fs,
+        });
+        // The name filter over-approximates; resolving through the graph's OWN resolver is
+        // what makes the answer exact. A file that merely mentions the name contributes
+        // nothing.
+        return references.some((reference) => reference.target.uri === fileUri) ? uri : undefined;
+    }));
+    return perCandidate
+        .filter((uri) => uri !== undefined)
+        .sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Turn dependant URIs into lint buffers, reading their text from the scan the discovery
+ * already paid for rather than going back to disk.
+ *
+ * `path.fsPath` is check-common's own URI-to-path conversion, not a local spelling of it: on
+ * Windows a URI and a filesystem path differ in separator AND in how the drive letter is
+ * encoded, and a hand-rolled conversion is the mistake that only the Windows CI job catches.
+ */
+export function toDependantBuffers(uris, sources) {
+    const buffers = [];
+    for (const uri of uris) {
+        const content = sources.get(uri);
+        // A URI the scan does not hold cannot be linted from it. Unreachable — every dependant
+        // came OUT of this map — but defaulting to empty text would lint a file as blank and
+        // report every one of its findings as newly caused.
+        if (content === undefined)
+            continue;
+        buffers.push({ uri, filePath: path.fsPath(uri), content });
+    }
+    return buffers;
+}
+//# sourceMappingURL=dependants.js.map

package/dist/impact/diff.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a change INTRODUCED in a file it did not edit.
+ *
+ * PURE, and deliberately the whole definition of "relevant". The alternative — an allowlist
+ * of check codes that count as cross-file — rots the first time a check is added, and it
+ * asks the wrong question anyway: a `DeprecatedFrontmatterField` already in a dependant is
+ * irrelevant because it was there BEFORE, not because of its code. Relevance is CAUSAL, so
+ * it is computed by comparing the same file linted twice rather than by classifying codes.
+ *
+ * IDENTITY IS (check, line, column). The dependant's own text is byte-identical across the
+ * two passes — only the files it depends on changed — so positions are stable and cannot
+ * drift under the comparison. Matching on the code alone would let a pre-existing
+ * `UnknownFilter` on line 90 mask a new one on line 3.
+ *
+ * A MULTISET, not a set: two offenses can legitimately share a code and a position is the
+ * only thing that separates them, so the count at each identity is what carries over. Three
+ * `before` and four `after` at one identity means one new, not none.
+ */
+import type { ValidateCodeDiagnostic } from '../result/types.js';
+/**
+ * The diagnostics in `after` that are not in `before`, preserving `after`'s order.
+ *
+ * `before` is the file as it stands with NONE of the changeset overlaid; `after` is the same
+ * file with the changeset applied. Everything returned is therefore attributable to the
+ * change.
+ */
+export declare function introducedDiagnostics(after: readonly ValidateCodeDiagnostic[], before: readonly ValidateCodeDiagnostic[]): ValidateCodeDiagnostic[];