@platformos/platformos-mcp-supervisor 0.0.2 → 0.1.0

package/dist/enrich/enrich.spec.js

@@ -0,0 +1,184 @@
+/**
+ * Enrichment is a pure function, so these run without a project, a server, or a lint.
+ *
+ * The AST is produced by parsing a snippet directly — the same parser the engine uses — so
+ * the fixtures state exactly what an agent sent, and the offsets are the ones an offense
+ * would carry.
+ */
+import { toLiquidHtmlAST } from '@platformos/liquid-html-parser';
+import { allChecks } from '@platformos/platformos-check-common';
+import { describe, expect, it } from 'vitest';
+import { checkDocs } from '../check-docs.js';
+import { enrichDiagnostics, SIGNATURE_HINT_CHECKS } from './enrich.js';
+/**
+ * A docset stand-in, deliberately tiny and DECLARED HERE.
+ *
+ * This is the sanctioned exception to "measure against the real documents": the subject is
+ * the enrichment code path, and these entries are INPUT to it, not a claim about what
+ * platformOS publishes. Asserting against the shipped docset would pin this file's
+ * expectations to a rendering of real documentation, which a docs release would then break
+ * without anything here being wrong.
+ */
+const VOCABULARY = {
+    filters: [
+        { name: 'hash_merge', description: 'Merges two hashes.', summary: 'Merge hashes.' },
+    ],
+    tags: [{ name: 'for', description: 'Iterates over an array.' }],
+    objects: [
+        { name: 'context', description: 'The request context.' },
+    ],
+};
+/**
+ * What the shared renderer makes of each fixture entry, written out rather than derived.
+ *
+ * These are what an AGENT receives, so they are pinned whole: a derived expectation
+ * (`toEqual(render(entry, …))`) would restate the call under test and pass however the
+ * output changed. The renderer is the language server's and is tested there — what this
+ * file owns is that the right ENTRY reaches it, under the right KIND, and that the result
+ * is passed on unaltered.
+ */
+const REFERENCE = 'https://documentation.platformos.com/api-reference/liquid';
+const RENDERED = {
+    hash_merge: `### hash_merge\nMerge hashes.\n\nMerges two hashes.\n\n---\n\n[platformOS Reference](${REFERENCE}/filters#hash_merge)`,
+    for: `### for\nIterates over an array.\n\n---\n\n[platformOS Reference](${REFERENCE}/loops#for)`,
+    context: `### context\nThe request context.`,
+};
+const diagnostic = (check) => ({
+    check,
+    severity: 'error',
+    message: `${check} fired`,
+    line: 1,
+    column: 1,
+});
+const enrichOne = (check, source, startIndex) => enrichDiagnostics([{ diagnostic: diagnostic(check), startIndex }], {
+    ast: toLiquidHtmlAST(source),
+    vocabulary: VOCABULARY,
+})[0];
+describe('Unit: enrichDiagnostics', () => {
+    it('attaches the check documentation URL, taken from the registry', () => {
+        // Derived, not pasted: the expectation moves with the registry.
+        const expected = checkDocs('FilterArity')?.url;
+        expect(enrichOne('FilterArity', '{{ null | hash_merge }}', 8)?.see_also).toEqual(expected);
+    });
+    it('renders the published signature for a filter used wrongly', () => {
+        const result = enrichOne('FilterArity', '{{ null | hash_merge }}', 8);
+        expect(result?.hint).toEqual(RENDERED.hash_merge);
+    });
+    it('reaches an enclosing TAG when the offense is reported on its argument', () => {
+        // `{% for x in (1..3) limit: 'ten' %}` — the offense lands on the string, three
+        // levels below the tag whose entry answers it.
+        const source = "{% for x in (1..3) limit: 'ten' %}{% endfor %}";
+        const result = enrichOne('ValidTagArgumentTypes', source, source.indexOf("'ten'"));
+        expect(result?.hint).toEqual(RENDERED.for);
+    });
+    it('renders an OBJECT entry, under the object kind', () => {
+        // The third of the three kinds, and the one whose rendering differs visibly: an
+        // object publishes no reference URL, so the entry ends at its description. Rendering
+        // it as a filter would append a `/filters#context` link that goes nowhere.
+        const result = enrichOne('ValidFilterArgumentTypes', '{{ context | hash_merge }}', 4);
+        expect(result?.hint).toEqual(RENDERED.context);
+    });
+    /**
+     * THE case that decided enrichment is opt-in per check. `{% render 'ghost' %}` resolves
+     * to the `render` TAG, so rendering "whatever symbol is here" answered a missing-partial
+     * error with ~500 bytes of general documentation about how `render` works, on a blocking
+     * check that fires constantly, about a partial that is not a docset symbol at all.
+     */
+    it('adds NO signature for a check a signature does not answer', () => {
+        const result = enrichOne('MissingPartial', "{% render 'ghost' %}", 10);
+        expect(result?.hint).toBeUndefined();
+        // ...but the documentation URL still attaches: that part is about the CHECK, and is
+        // useful whatever the finding.
+        expect(result?.see_also).toEqual(checkDocs('MissingPartial')?.url);
+    });
+    it('adds no signature for a symbol the docset does not publish', () => {
+        // An unknown filter has no entry by definition — the engine's suggestions are the
+        // answer there, and this must not invent a substitute.
+        const result = enrichOne('ValidFilterArgumentTypes', '{{ x | no_such_filter_xyz: 1 }}', 6);
+        expect(result?.hint).toBeUndefined();
+    });
+    it('leaves a diagnostic untouched when there is nothing to add', () => {
+        // `CheckError` is check-common's code for "a check crashed on this file". It reaches an
+        // agent as an ordinary offense and is NOT a registered check, so there is no
+        // documentation URL for it — and with no tree there is no signature either. Every
+        // optional field must be ABSENT rather than empty: an agent reads absence as "nothing
+        // more is known".
+        const [result] = enrichDiagnostics([{ diagnostic: diagnostic('CheckError'), startIndex: 0 }], {
+            ast: undefined,
+            vocabulary: VOCABULARY,
+        });
+        expect(result).toEqual({
+            check: 'CheckError',
+            severity: 'error',
+            message: 'CheckError fired',
+            line: 1,
+            column: 1,
+        });
+    });
+    /**
+     * A repeated mistake must not buy a repeated paragraph. The signature is ~880 bytes and
+     * identical every time, against a 32 KiB diagnostic budget: twenty of them once cost
+     * 26 KiB and truncated the findings an agent actually needed. The FIRST occurrence keeps
+     * the hint, which is also the one truncation keeps.
+     */
+    it('renders a symbol ONCE per file, however many findings name it', () => {
+        const source = '{{ null | hash_merge }}{{ null | hash_merge }}{{ null | hash_merge }}';
+        const results = enrichDiagnostics([8, 31, 54].map((startIndex) => ({ diagnostic: diagnostic('FilterArity'), startIndex })), { ast: toLiquidHtmlAST(source), vocabulary: VOCABULARY });
+        // The later two keep their `see_also` — deduplication is about the bulk, not about
+        // withholding the answer.
+        expect(results.map((result) => [result.hint, result.see_also !== undefined])).toEqual([
+            [RENDERED.hash_merge, true],
+            [undefined, true],
+            [undefined, true],
+        ]);
+    });
+    it('renders each DISTINCT symbol, so deduplication cannot silence a second one', () => {
+        // The control for the test above: a suppression keyed on anything coarser than the
+        // symbol — "one hint per file", "one per check" — passes that one and fails this.
+        const source = "{{ null | hash_merge }}{% for x in (1..3) limit: 'ten' %}{% endfor %}";
+        const results = enrichDiagnostics([
+            { diagnostic: diagnostic('FilterArity'), startIndex: 8 },
+            { diagnostic: diagnostic('ValidTagArgumentTypes'), startIndex: source.indexOf("'ten'") },
+        ], { ast: toLiquidHtmlAST(source), vocabulary: VOCABULARY });
+        expect(results.map((result) => result.hint)).toEqual([RENDERED.hash_merge, RENDERED.for]);
+    });
+    /**
+     * No offset means no symbol — never a symbol resolved at a guessed one.
+     *
+     * The offset is absent only when `startIndexes` got out of step with the diagnostics it
+     * is index-aligned with, which is a bug rather than a state; the answer to it is the
+     * finding with no hint, not the finding with a plausible wrong one.
+     */
+    it('adds no signature when the offense carries no offset', () => {
+        const withoutOffset = enrichOne('FilterArity', '{{ null | hash_merge }}');
+        // The control is the first test in this group: the same call WITH the offset renders.
+        expect({ hint: withoutOffset?.hint, see_also: withoutOffset?.see_also !== undefined }).toEqual({
+            hint: undefined,
+            see_also: true,
+        });
+    });
+    it('does not mutate its input', () => {
+        const input = diagnostic('FilterArity');
+        const before = { ...input };
+        enrichDiagnostics([{ diagnostic: input, startIndex: 8 }], {
+            ast: toLiquidHtmlAST('{{ null | hash_merge }}'),
+            vocabulary: VOCABULARY,
+        });
+        expect(input).toEqual(before);
+    });
+});
+describe('Unit: SIGNATURE_HINT_CHECKS', () => {
+    /**
+     * The same guard `BLOCKING_CHECKS` carries, for the same reason: a hand-written set of
+     * check codes goes stale silently when one is renamed upstream, and a stale entry here
+     * means a hint that quietly stopped appearing.
+     *
+     * Deliberately NOT the converse — a new check must default to silence, so membership is
+     * never required of one.
+     */
+    it('names only checks that are registered in check-common', () => {
+        const registered = new Set(allChecks.map((check) => check.meta.code));
+        expect([...SIGNATURE_HINT_CHECKS].filter((code) => !registered.has(code))).toEqual([]);
+    });
+});
+//# sourceMappingURL=enrich.spec.js.map

package/dist/enrich/symbol.d.ts

@@ -0,0 +1,16 @@
+import { type LiquidHtmlNode } from '@platformos/platformos-check-common';
+/** A symbol the docset may publish an entry for. */
+export interface DocumentedSymbol {
+    kind: 'filter' | 'tag' | 'object';
+    name: string;
+}
+/**
+ * The nearest enclosing node that names something the docset documents.
+ *
+ * Searched from the node the offset lands on OUTWARDS through its ancestors, nearest
+ * first, because an offense range often points INSIDE the construct it is about: the
+ * argument of a filter, the markup of a tag. Stopping at the first match is what makes
+ * `{{ x | hash_add_key: 'k' }}` resolve to the filter rather than to the tag or the
+ * output that contains it.
+ */
+export declare function documentedSymbolAt(ast: LiquidHtmlNode, offset: number): DocumentedSymbol | undefined;

package/dist/enrich/symbol.js

@@ -0,0 +1,58 @@
+/**
+ * Which documented symbol a diagnostic is ABOUT, resolved from the syntax tree.
+ *
+ * FROM THE TREE, never from the message: parsing names out of English wording this package
+ * does not own is forbidden (ARCHITECTURE.md §Invariants #2). The offense carries an offset
+ * and the buffer's tree comes back with it, so the name is read from the node the engine
+ * pointed at.
+ *
+ * `findCurrentNode` is check-common's, the same primitive the language server's hover,
+ * definition and highlight providers use, asked of the same tree the offense came from
+ * (`LintBufferResult.ast`, captured inside the buffer overlay for this).
+ */
+import { NodeTypes } from '@platformos/liquid-html-parser';
+import { findCurrentNode } from '@platformos/platformos-check-common';
+/**
+ * The nearest enclosing node that names something the docset documents.
+ *
+ * Searched from the node the offset lands on OUTWARDS through its ancestors, nearest
+ * first, because an offense range often points INSIDE the construct it is about: the
+ * argument of a filter, the markup of a tag. Stopping at the first match is what makes
+ * `{{ x | hash_add_key: 'k' }}` resolve to the filter rather than to the tag or the
+ * output that contains it.
+ */
+export function documentedSymbolAt(ast, offset) {
+    const [node, ancestors] = findCurrentNode(ast, offset);
+    // Nearest first: `ancestors` is root-to-parent, so it is walked backwards.
+    for (const candidate of [node, ...[...ancestors].reverse()]) {
+        const symbol = symbolOf(candidate);
+        if (symbol)
+            return symbol;
+    }
+    return undefined;
+}
+/**
+ * The symbol a single node names, if it names one.
+ *
+ * Only three node types qualify, matching the three things the docset publishes. A tag's
+ * `name` can be a `NamedTags` enum member rather than a plain string, and a variable
+ * lookup's can be `null` — `{{ ["a"][0] }}` subscripts an array literal, so the lookup has
+ * a position and no name — so both are checked rather than assumed. Unchecked, that null
+ * would be looked up in the docset as the string `"null"`.
+ */
+function symbolOf(node) {
+    switch (node.type) {
+        case NodeTypes.LiquidFilter:
+            return typeof node.name === 'string' ? { kind: 'filter', name: node.name } : undefined;
+        case NodeTypes.LiquidTag:
+        case NodeTypes.LiquidRawTag:
+            return typeof node.name === 'string' ? { kind: 'tag', name: node.name } : undefined;
+        case NodeTypes.VariableLookup:
+            return typeof node.name === 'string' && node.name.length > 0
+                ? { kind: 'object', name: node.name }
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=symbol.js.map

package/dist/enrich/symbol.spec.d.ts

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

package/dist/enrich/symbol.spec.js

@@ -0,0 +1,89 @@
+/**
+ * Symbol resolution is a pure function of a tree and an offset, so these run without a
+ * project, a docset or a lint.
+ *
+ * Every fixture is PARSED, never hand-built. The node shapes this module branches on —
+ * which construct yields a `VariableLookup`, when its `name` is null, how deep a tag sits
+ * above the argument an offense lands on — are the parser's answers and not anything this
+ * package gets to decide. Two of them were documented wrongly here until they were run.
+ */
+import { toLiquidHtmlAST } from '@platformos/liquid-html-parser';
+import { describe, expect, it } from 'vitest';
+import { documentedSymbolAt } from './symbol.js';
+/**
+ * Resolve one character INTO `needle`, so the offsets read as source rather than
+ * arithmetic.
+ *
+ * The `+ 1` is `findCurrentNode`'s contract, not a fudge: it takes a CURSOR position — a
+ * place between two characters — and its default coverage is `start < offset <= end`, so
+ * the position immediately before a node's first character still belongs to that node's
+ * parent. A real offense points inside the construct it is about, which is the same place.
+ */
+const symbolAt = (source, needle) => documentedSymbolAt(toLiquidHtmlAST(source), source.indexOf(needle) + 1);
+describe('Unit: documentedSymbolAt', () => {
+    it('resolves the FILTER an offense inside a filtered output is about', () => {
+        expect(symbolAt('{{ null | hash_merge }}', 'hash_merge')).toEqual({
+            kind: 'filter',
+            name: 'hash_merge',
+        });
+    });
+    it('prefers the nearest symbol, so a filter wins over the tag containing it', () => {
+        // The whole reason the walk stops at the first match: every filter is inside
+        // something, and the something is never the better answer.
+        expect(symbolAt('{% if true %}{{ x | hash_merge }}{% endif %}', 'hash_merge')).toEqual({
+            kind: 'filter',
+            name: 'hash_merge',
+        });
+    });
+    it('reaches an enclosing TAG when the offense lands on one of its arguments', () => {
+        // `'ten'` is a String inside a NamedArgument inside a ForMarkup inside the LiquidTag —
+        // three levels up, which is why this walks ancestors rather than reading one node.
+        expect(symbolAt("{% for x in (1..3) limit: 'ten' %}{% endfor %}", "'ten'")).toEqual({
+            kind: 'tag',
+            name: 'for',
+        });
+    });
+    it('resolves a RAW tag by name, exactly as an ordinary one', () => {
+        // A separate node type with a separate branch: `{% raw %}` is a `LiquidRawTag`, and
+        // the docset publishes it under the same `tags` list as `for`.
+        expect(symbolAt('{% raw %}x{% endraw %}', 'raw')).toEqual({ kind: 'tag', name: 'raw' });
+    });
+    it('resolves an OBJECT from a bare variable lookup, ignoring what is looked up on it', () => {
+        // `context.params.id` is ONE lookup named `context`; the docset publishes the drop,
+        // not each property path through it.
+        expect(symbolAt('{{ context.params.id }}', 'context')).toEqual({
+            kind: 'object',
+            name: 'context',
+        });
+    });
+    /**
+     * A `VariableLookup` whose `name` is null must resolve to NOTHING, not to the string
+     * `"null"`. `{{ ["a"][0] }}` subscripts an array literal, so the lookup carries a position
+     * and no name; deleting the null guard in `symbolOf` returns
+     * `{kind: 'object', name: 'null'}`, and a docset entry published under that name would be
+     * rendered as the explanation for an unrelated finding.
+     *
+     * The offset is the subscript, measured: at the array literal itself the answer is a
+     * `String` and this would pass for the wrong reason.
+     */
+    it('resolves nothing for a lookup that has no name', () => {
+        expect(documentedSymbolAt(toLiquidHtmlAST('{{ ["a"][0] }}'), 8)).toBeUndefined();
+    });
+    /**
+     * The CONTROL for the case above: the same subscript shape, with a name, does resolve.
+     * Without it, a guard wide enough to reject every lookup would pass.
+     */
+    it('CONTROL: the same subscript shape resolves when the lookup is named', () => {
+        expect(symbolAt('{{ a["k"] }}', 'a[')).toEqual({ kind: 'object', name: 'a' });
+    });
+    it('resolves nothing outside every construct, and nothing for plain markup', () => {
+        expect({
+            // What an out-of-range offset actually does — it is not an error, it answers the
+            // Document. `enrich` therefore checks for a MISSING offset rather than passing a
+            // sentinel, because a sentinel's silence here is an accident of this switch.
+            beforeTheDocument: documentedSymbolAt(toLiquidHtmlAST('{{ null | hash_merge }}'), -1),
+            plainHtml: symbolAt('<div>hello</div>', 'hello'),
+        }).toEqual({ beforeTheDocument: undefined, plainHtml: undefined });
+    });
+});
+//# sourceMappingURL=symbol.spec.js.map

package/dist/impact/impact.d.ts

@@ -0,0 +1,9 @@
+import { type AdapterInput } from '../adapter-input.js';
+import type { ValidateCodeImpact } from '../result/types.js';
+import type { ProjectScan } from './project-scan.js';
+/**
+ * Compute the edited file's blast radius from the project as it is right now.
+ * Reports `not_applicable` when nothing could reference the file by name, and
+ * throws only on real I/O failure — the caller degrades that to `unavailable`.
+ */
+export declare function runImpact(params: AdapterInput, scan: ProjectScan): Promise<ValidateCodeImpact>;

package/dist/impact/impact.js

@@ -0,0 +1,189 @@
+/**
+ * Impact (blast-radius) adapter — an I/O boundary on the request path (sibling
+ * to `lint/`).
+ *
+ * Answers the one question lint structurally cannot: "who DEPENDS ON the file
+ * being edited?" — its incoming references across the project.
+ *
+ * HOW, AND WHY IT IS NOT A GRAPH. Every edge platformos-graph records names its target with
+ * a STATIC STRING LITERAL: the operand of `render`/`include`/`function`/`background`/
+ * `graphql`, the operand of `asset_url`, or an explicit frontmatter `layout:` (an omitted
+ * `layout:` synthesizes no edge — see `traverse.ts`). So a file's dependents can only be
+ * among the edge sources whose TEXT contains its logical name, and filtering on that name is
+ * a sound over-approximation leaving few survivors (measured p50 1, p90 6 candidates on a
+ * 2,615-file project). Those are parsed and resolved with {@link extractFileReferences}, the
+ * SAME resolver `buildAppGraph` runs, so this answer cannot drift from the graph's — 80
+ * targets sampled across two real projects produced 0 mismatches on `(source, kind, args)`.
+ *
+ * THERE IS NO `computing` STATE. The answer is derived from the project as it is at request
+ * time, so it is fresh by construction. A failure or the deadline yields `unavailable`; a
+ * file the graph cannot model yields `not_applicable`; everything else is `computed`.
+ *
+ * The dependents list reads the CHANGESET, not just disk: `ProjectScan` overlays the buffers
+ * under validation, so a caller a buffer has just added or removed is counted.
+ */
+import { extractDocDefinition, path, SourceCodeType, } from '@platformos/platformos-check-common';
+import { sourceCodeTypeOf, uriToName } from '@platformos/platformos-common';
+import { extractFileReferences, toSourceCode, } from '@platformos/platformos-graph';
+import { toAbsoluteFilePath } from '../adapter-input.js';
+/** Number of referencing files listed in `sample`/`signature_risk` before truncating. */
+const SAMPLE_LIMIT = 10;
+/**
+ * The edge kinds whose call-site arguments are validated against a partial's
+ * `{% doc %}` `@param` contract — EXACTLY the kinds the `PartialCallArguments`
+ * lint check validates (`render`/`include` via its `RenderMarkup` handler,
+ * `function` via `FunctionMarkup`). `background`/`graphql`/`layout`/`asset` edges
+ * carry scheduling/operation arguments that are NOT `@param`s, so signature-impact
+ * must ignore them or it would flag correct calls (a false positive that the
+ * forward `PartialCallArguments` check never produces).
+ */
+const SIGNATURE_EDGE_KINDS = new Set(['render', 'include', 'function']);
+/**
+ * Whether the graph can model incoming references to `uri` — i.e. `uri` can be a
+ * resolvable edge TARGET (a Liquid page/layout/partial, or a GraphQL operation).
+ * Reuses check-common's canonical classifiers so this cannot drift from the
+ * graph's own edge resolution.
+ *
+ * Files that are NOT edge targets — schema / custom-model-type / translation YAML,
+ * or any unclassified file — are wired by model/table NAME, not by file reference
+ * (ADR 004), so the graph has no dependents for them and `total: 0` would be a
+ * false "safe to change". Those get `status: 'not_applicable'` instead.
+ */
+function isGraphTrackable(uri) {
+    // The graph's edge-target types, asked by extension. Naming the two explicitly keeps the
+    // YAML case visibly excluded, which is the distinction the docblock above turns on.
+    const type = sourceCodeTypeOf(uri);
+    return type === SourceCodeType.LiquidHtml || type === SourceCodeType.GraphQL;
+}
+/** A fresh zeroed dependents shape for every non-`computed` status. */
+const noDependents = () => ({
+    total: 0,
+    by_kind: {},
+    sample: [],
+});
+/**
+ * Compute the edited file's blast radius from the project as it is right now.
+ * Reports `not_applicable` when nothing could reference the file by name, and
+ * throws only on real I/O failure — the caller degrades that to `unavailable`.
+ */
+export async function runImpact(params, scan) {
+    const { projectDir, filePath, content } = params;
+    const rootUri = path.normalize(path.URI.file(projectDir));
+    const fileUri = path.normalize(path.URI.file(toAbsoluteFilePath(projectDir, filePath)));
+    // Applicability is a property of the FILE, independent of any scan: a non-trackable file
+    // has no dependency edges, and a file in no platformOS directory has no logical NAME for
+    // a reference to spell. `total: 0` for either would be a false "safe to change".
+    const name = uriToName(fileUri, rootUri)?.name;
+    if (!isGraphTrackable(fileUri) || name === undefined) {
+        return { scope: 'direct', status: 'not_applicable', dependents: noDependents() };
+    }
+    const dependents = await incomingReferences(scan, fileUri, name);
+    const signature = await docSignature(fileUri, content);
+    const signature_risk = signature && computeSignatureRisk(dependents, rootUri, signature);
+    return {
+        scope: 'direct',
+        status: 'computed',
+        dependents: summarizeDependents(dependents, rootUri),
+        ...(signature_risk ? { signature_risk } : {}),
+    };
+}
+/**
+ * Every reference in the project that resolves to `fileUri`.
+ *
+ * The name filter is what keeps this cheap, and it is sound rather than heuristic: an edge
+ * exists only where a static literal spells the target's logical name. Everything past the
+ * filter is exact — the survivors are resolved by the graph's own resolver, so a candidate
+ * that merely MENTIONS the name contributes no reference.
+ */
+async function incomingReferences(scan, fileUri, name) {
+    const sources = await scan.sources();
+    const candidates = [...sources].filter(([, source]) => source.includes(name));
+    const perCandidate = await Promise.all(candidates.map(async ([uri, source]) => {
+        const sourceCode = await toSourceCode(uri, source);
+        return extractFileReferences(scan.rootUri, uri, sourceCode, { fs: scan.fs });
+    }));
+    return perCandidate.flat().filter((reference) => reference.target.uri === fileUri);
+}
+/**
+ * Reduce the incoming reference edges of the edited file to the agent-facing
+ * summary: distinct referencing FILES (`total`), distinct files per edge kind
+ * (`by_kind`), and a capped, sorted `sample` of project-relative caller paths.
+ */
+function summarizeDependents(references, rootUri) {
+    // caller path (project-relative) → the edge kinds by which it references the file
+    const callers = new Map();
+    for (const ref of references) {
+        if (!ref.kind)
+            continue; // every graph edge carries a kind; defensive only
+        const caller = path.relative(ref.source.uri, rootUri);
+        const kinds = callers.get(caller) ?? new Set();
+        kinds.add(ref.kind);
+        callers.set(caller, kinds);
+    }
+    const by_kind = {};
+    for (const kinds of callers.values()) {
+        for (const kind of kinds)
+            by_kind[kind] = (by_kind[kind] ?? 0) + 1;
+    }
+    const sample = [...callers.keys()].sort((a, b) => a.localeCompare(b)).slice(0, SAMPLE_LIMIT);
+    return { total: callers.size, by_kind, sample };
+}
+/**
+ * The edited buffer's `{% doc %}` parameter contract (required + all declared
+ * names), or `null` when the buffer is non-Liquid, unparseable, or declares no
+ * `{% doc %}` block. Reuses check-common's `extractDocDefinition` — the same
+ * primitive the `PartialCallArguments` check reads for the doc case — so the
+ * two never diverge. `null` deliberately disables signature-impact: without an
+ * explicit contract we do NOT guess a signature (no false positives).
+ */
+async function docSignature(fileUri, content) {
+    const sourceCode = await toSourceCode(fileUri, content);
+    if (sourceCode.type !== SourceCodeType.LiquidHtml || sourceCode.ast instanceof Error)
+        return null;
+    const definition = await extractDocDefinition(fileUri, sourceCode.ast);
+    const parameters = definition.liquidDoc?.parameters;
+    if (!parameters || parameters.length === 0)
+        return null;
+    return {
+        required: parameters.filter((p) => p.required).map((p) => p.name),
+        allowed: parameters.map((p) => p.name),
+    };
+}
+/**
+ * The dependent callers whose passed arguments violate `signature` — missing a
+ * required `@param`, or passing one the `{% doc %}` block does not declare. The
+ * cross-file inverse of `PartialCallArguments`: it checks the edited file's
+ * contract against every existing caller at once. Deduplicated per caller,
+ * sorted, and capped.
+ */
+function computeSignatureRisk(references, rootUri, signature) {
+    const byCaller = new Map();
+    for (const ref of references) {
+        // Only the kinds whose args ARE `@param`s (see {@link SIGNATURE_EDGE_KINDS}) —
+        // a `{% background %}`/`{% graphql %}`/layout edge's args are not, and flagging
+        // them would be a false positive the forward check never makes.
+        if (!ref.kind || !SIGNATURE_EDGE_KINDS.has(ref.kind))
+            continue;
+        const args = ref.args ?? [];
+        const missing = signature.required.filter((param) => !args.includes(param));
+        const unexpected = args.filter((arg) => !signature.allowed.includes(arg));
+        if (missing.length === 0 && unexpected.length === 0)
+            continue;
+        const caller = path.relative(ref.source.uri, rootUri);
+        const entry = byCaller.get(caller) ?? { missing: new Set(), unexpected: new Set() };
+        for (const m of missing)
+            entry.missing.add(m);
+        for (const u of unexpected)
+            entry.unexpected.add(u);
+        byCaller.set(caller, entry);
+    }
+    return [...byCaller.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .slice(0, SAMPLE_LIMIT)
+        .map(([caller, { missing, unexpected }]) => ({
+        caller,
+        missing_required: [...missing].sort((a, b) => a.localeCompare(b)),
+        unexpected_args: [...unexpected].sort((a, b) => a.localeCompare(b)),
+    }));
+}
+//# sourceMappingURL=impact.js.map

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

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