@platformos/platformos-mcp-supervisor 0.0.2 → 0.2.0

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[];

package/dist/impact/diff.js

@@ -0,0 +1,33 @@
+/** The comparison key: what makes two findings the same finding. */
+function identityOf(diagnostic) {
+    return `${diagnostic.check}\u0000${diagnostic.line}\u0000${diagnostic.column}`;
+}
+/**
+ * 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 function introducedDiagnostics(after, before) {
+    if (after.length === 0)
+        return [];
+    const remaining = new Map();
+    for (const diagnostic of before) {
+        const key = identityOf(diagnostic);
+        remaining.set(key, (remaining.get(key) ?? 0) + 1);
+    }
+    const introduced = [];
+    for (const diagnostic of after) {
+        const key = identityOf(diagnostic);
+        const unmatched = remaining.get(key) ?? 0;
+        // Each `before` occurrence cancels exactly one `after` occurrence, so a code that
+        // legitimately fires twice does not swallow a third.
+        if (unmatched > 0)
+            remaining.set(key, unmatched - 1);
+        else
+            introduced.push(diagnostic);
+    }
+    return introduced;
+}
+//# sourceMappingURL=diff.js.map

package/dist/impact/impact.d.ts

@@ -0,0 +1,21 @@
+import { type DocsetVocabulary } from '../enrich/enrich.js';
+import type { BatchBuffer, runBatchLint } from '../lint/lint-batch.js';
+import type { ValidateCodeImpact } from '../result/types.js';
+import type { ProjectScan } from './project-scan.js';
+/** Everything one impact pass needs. The lint seam is injected so the contract is testable. */
+export interface ImpactInput {
+    projectDir: string;
+    /** The changeset, exactly as the primary lint received it. */
+    buffers: readonly BatchBuffer[];
+    scan: ProjectScan;
+    lint: typeof runBatchLint;
+    docset: () => Promise<DocsetVocabulary>;
+    log: (message: string) => void;
+}
+/**
+ * The impact of the whole changeset, per requested buffer key.
+ *
+ * Throws only on real I/O failure — the caller degrades that to `unavailable` for every
+ * buffer, because a failure here says nothing about any of them.
+ */
+export declare function runImpact(input: ImpactInput): Promise<Map<string, ValidateCodeImpact>>;

package/dist/impact/impact.js

@@ -0,0 +1,160 @@
+/**
+ * Impact — what this change breaks in files the agent is NOT editing.
+ *
+ * Lint is per-file and forward-looking: it visits only the buffers it was sent, so a page
+ * that the edited partial has just broken is never even looked at. This stage looks at it,
+ * and it does so by ASKING THE CHECK ENGINE rather than by re-deriving the answer:
+ *
+ *   pass A   the dependants, linted with the changeset overlaid
+ *   pass B   the same dependants, linted with nothing overlaid
+ *   report   A \ B — exactly the findings this change introduced
+ *
+ * WHY A DIFF AND NOT A CHECK-CODE ALLOWLIST. An earlier version compared `{% doc %}`
+ * parameters by hand, which reimplemented `MissingRenderPartialArguments` with no message,
+ * no documentation link and an invented severity. The diff needs no list of "cross-file
+ * relevant" codes, because relevance is CAUSAL: a `DeprecatedFrontmatterField` already in a
+ * dependant is irrelevant for having been there BEFORE, not for its code. A check added
+ * upstream is covered on the day it ships, with no edit here.
+ *
+ * SERIALIZED, BY NECESSITY. `lintBuffers` overlays buffers into check-node's process-shared
+ * `App` and reverts them on the way out, and that App has no lock. Two lint passes therefore
+ * cannot overlap — with each other, or with the request's primary lint. The orchestrator
+ * runs the primary lint concurrently with the project SCAN (pure fs reads, no App) and only
+ * then runs these two passes, so the write gate is never delayed by, or lost to, impact.
+ *
+ * BOUNDED BY INPUT, NOT BY THE DEADLINE. `IMPACT_DEADLINE_MS` cannot bound this: a lint is
+ * synchronous CPU work and no timer preempts it. `MAX_CANDIDATE_BYTES` caps the text
+ * discovery will parse and `MAX_DEPENDANTS_LINTED` caps how many dependants are linted, both
+ * derived in `cost-model.ts` to fit inside that deadline. Hitting either is REPORTED —
+ * `status: unavailable` or `unchecked_dependants` — never silently absorbed.
+ *
+ * NOTHING HERE IS A CLEARANCE. A dependant that names its target at runtime, or that does
+ * not parse, is invisible to discovery — so an empty answer means no break was FOUND among
+ * the dependants that are visible, never that none exists.
+ */
+import { path } from '@platformos/platformos-check-common';
+import { uriToName } from '@platformos/platformos-common';
+import { toAbsoluteFilePath } from '../adapter-input.js';
+import { MAX_DEPENDANTS_LINTED } from '../cost-model.js';
+import { enrichBatch } from '../enrich/enrich.js';
+import { NOT_APPLICABLE_IMPACT, UNAVAILABLE_IMPACT } from '../result/impact-states.js';
+import { canHaveDependants, dependantsOf, toDependantBuffers } from './dependants.js';
+import { introducedDiagnostics } from './diff.js';
+/**
+ * The impact of the whole changeset, per requested buffer key.
+ *
+ * Throws only on real I/O failure — the caller degrades that to `unavailable` for every
+ * buffer, because a failure here says nothing about any of them.
+ */
+export async function runImpact(input) {
+    const { projectDir, buffers, scan } = input;
+    const rootUri = path.normalize(path.URI.file(projectDir));
+    const uriOf = (buffer) => path.normalize(path.URI.file(toAbsoluteFilePath(projectDir, buffer.filePath)));
+    // A file in the changeset is reported on its own terms. Excluding the whole changeset from
+    // every dependant set is also what makes the scan's text the DISK text for each dependant,
+    // which is exactly what pass B's baseline needs.
+    const changeset = new Set(buffers.map(uriOf));
+    const byBuffer = new Map();
+    const dependantsPerBuffer = new Map();
+    for (const buffer of buffers) {
+        const uri = uriOf(buffer);
+        // Applicability is a property of the FILE and needs no scan. The name is read separately
+        // because discovery needs the STRING while `canHaveDependants` answers a boolean; the
+        // second condition below narrows that string and is not a second rule.
+        const name = uriToName(uri, rootUri)?.name;
+        if (!canHaveDependants(uri, rootUri) || name === undefined) {
+            byBuffer.set(buffer.filePath, NOT_APPLICABLE_IMPACT());
+            continue;
+        }
+        const dependants = await dependantsOf(scan, uri, name, changeset);
+        // `null` is "too much candidate text to examine", NOT "no dependants". Reported as
+        // `unavailable`, which is what it is: the comparison did not run.
+        if (dependants === null) {
+            byBuffer.set(buffer.filePath, UNAVAILABLE_IMPACT());
+            continue;
+        }
+        dependantsPerBuffer.set(buffer.filePath, dependants);
+        byBuffer.set(buffer.filePath, { status: 'computed' });
+    }
+    const found = [...new Set([...dependantsPerBuffer.values()].flat())].sort((a, b) => a.localeCompare(b));
+    if (found.length === 0)
+        return byBuffer;
+    // BOUNDED INPUT, not a deadline: a lint is synchronous CPU work and no timer preempts it
+    // (see `deadline.ts`), so the only defence is refusing to start more of it than fits.
+    // Sorted first, so which dependants survive the bound is deterministic rather than
+    // whichever order a directory walk happened to produce.
+    const linted = new Set(found.slice(0, MAX_DEPENDANTS_LINTED));
+    const introduced = await introducedByDependant(input, [...linted]);
+    for (const [key, dependants] of dependantsPerBuffer) {
+        const checked = dependants.filter((uri) => linted.has(uri));
+        const breaks = checked
+            .map((uri) => ({ uri, diagnostics: introduced.get(uri) ?? [] }))
+            .filter(({ diagnostics }) => diagnostics.length > 0)
+            .map(({ uri, diagnostics }) => ({ file: path.relative(uri, rootUri), diagnostics }));
+        const impact = { status: 'computed' };
+        // Omitted when empty. An empty list reads as "checked, nothing depends on this that
+        // could break", which a scan of the dependants that happen to be VISIBLE cannot earn.
+        if (breaks.length > 0)
+            impact.breaks = breaks;
+        // Reported per buffer rather than per request: the bound is global, but whether it cost
+        // THIS buffer anything depends on how many of its own dependants fell past it.
+        if (checked.length < dependants.length) {
+            impact.unchecked_dependants = { returned: checked.length, total: dependants.length };
+        }
+        byBuffer.set(key, impact);
+    }
+    return byBuffer;
+}
+/**
+ * The findings each dependant gained because of the changeset, keyed by its URI.
+ *
+ * The two passes are AWAITED IN SEQUENCE, never raced: they share check-node's process-wide
+ * `App`, and an overlay installed by one while the other is reverting would corrupt both.
+ */
+async function introducedByDependant(input, dependants) {
+    const { projectDir, buffers, scan, lint, docset, log } = input;
+    const sources = await scan.sources();
+    const dependantBuffers = toDependantBuffers(dependants, sources);
+    const keyOf = new Map(dependantBuffers.map((buffer) => [buffer.filePath, buffer.uri]));
+    // WITH the changeset overlaid. The changeset's own buffers are included because a
+    // dependant must see the edit to be broken by it; their results are discarded here, since
+    // the primary lint already reported them.
+    const after = await lint({ projectDir, buffers: [...buffers, ...dependantBuffers] });
+    // Only a dependant that found something in pass A needs a baseline: the diff is A \ B, so
+    // an empty A is empty whatever B holds. Worth less than it looks — measured, a page
+    // reports `DeprecatedFrontmatterField` whatever it contains, so only partial dependants
+    // are ever clean enough to skip.
+    const withFindings = dependantBuffers.filter((buffer) => (after.diagnostics.get(buffer.filePath)?.length ?? 0) > 0);
+    const before = withFindings.length
+        ? await lint({ projectDir, buffers: withFindings })
+        : undefined;
+    const enriched = await enrichBatch(onlyDependants(after, keyOf), docset, log);
+    const introduced = new Map();
+    for (const [filePath, uri] of keyOf) {
+        const gained = introducedDiagnostics(enriched.get(filePath) ?? [], before?.diagnostics.get(filePath) ?? []);
+        if (gained.length > 0)
+            introduced.set(uri, gained);
+    }
+    return introduced;
+}
+/**
+ * Pass A narrowed to the dependants, so enrichment is not paid a second time for the
+ * changeset's own findings — the primary lint has already enriched those.
+ */
+function onlyDependants(pass, keyOf) {
+    const diagnostics = new Map();
+    const sources = new Map();
+    for (const key of keyOf.keys()) {
+        const found = pass.diagnostics.get(key);
+        // A dependant the lint DECLINED (excluded by config, say) has no diagnostics entry.
+        // Skipped rather than defaulted to `[]`, which would report it as checked and clean.
+        if (found === undefined)
+            continue;
+        diagnostics.set(key, found);
+        const source = pass.sources?.get(key);
+        if (source)
+            sources.set(key, source);
+    }
+    return { diagnostics, sources, notChecked: pass.notChecked };
+}
+//# sourceMappingURL=impact.js.map

package/dist/impact/impact.spec.d.ts

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