@platformos/platformos-mcp-supervisor 0.0.2 → 0.2.0

package/dist/enrich/enrich.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The PURE enrichment stage: what the supervisor adds to a diagnostic beyond what the
+ * engine reported.
+ *
+ * It adds exactly two things, and **authors neither of them**:
+ *
+ *   `see_also`  the check's own documentation page, from check-common `meta.docs.url`.
+ *   `hint`      the docset entry for the symbol the diagnostic is about, rendered by the
+ *               same function every editor hover uses.
+ *
+ * The restraint is the design. The supervisor ships no documentation (ARCHITECTURE.md
+ * §Invariants #6): the words an agent reads come from `filters.json` / `tags.json` /
+ * `objects.json` and from the check registry, both owned and tested where they are
+ * published. A hint composed here would be a second source of truth that goes stale.
+ *
+ * PURE, and mechanically so: no `fs`, no `process`, no import of `lint/`, nothing async.
+ * The docset arrives already resolved to plain arrays, so "no I/O below the lint edge" is a
+ * matter of shape rather than of trust.
+ */
+import type { FilterEntry, LiquidHtmlNode, ObjectEntry, TagEntry } from '@platformos/platformos-check-common';
+import type { ValidateCodeDiagnostic } from '../result/types.js';
+/**
+ * The docset, resolved to data.
+ *
+ * Plain arrays rather than the `AugmentedPlatformOSDocset` itself, whose methods return
+ * promises and would let a future edit `await` inside the pure stage. The caller resolves it
+ * once per request and hands over the result.
+ */
+export interface DocsetVocabulary {
+    filters: readonly FilterEntry[];
+    tags: readonly TagEntry[];
+    objects: readonly ObjectEntry[];
+}
+/**
+ * The checks for which a published SIGNATURE is the answer.
+ *
+ * Policy, not documentation — a statement about which findings an agent can act on with a
+ * signature in front of it, the same kind of judgement as `BLOCKING_CHECKS`. Each entry
+ * says why, because "it seemed relevant" is how this grows into noise.
+ *
+ * DEFAULTS TO SILENCE. A check not listed gets no hint, so a check added upstream cannot
+ * start emitting an unrelated wall of markdown before anyone has looked at it.
+ *
+ * A list rather than a structural rule, because no structural rule separates the useful
+ * case from the useless one: `{% render 'ghost' %}` resolves to the `render` TAG, so
+ * rendering whatever symbol an offense sits on answers "'ghost' does not exist" with
+ * general documentation about how `render` works.
+ */
+export declare const SIGNATURE_HINT_CHECKS: ReadonlySet<string>;
+/** One diagnostic, with the buffer offset the engine reported it at. */
+export interface EnrichInput {
+    diagnostic: ValidateCodeDiagnostic;
+    /**
+     * 0-based offset of the offense start, in the buffer as sent. Carried alongside rather
+     * than added to `ValidateCodeDiagnostic`, which an agent reads.
+     *
+     * OPTIONAL, and absence means "do not resolve a symbol for this one" — not spelled as an
+     * out-of-range sentinel, which only LOOKS inert: `findCurrentNode` always answers, and at
+     * an impossible offset it answers `Document`.
+     */
+    startIndex?: number;
+}
+/** Everything enrichment reads. All of it data; none of it fetched here. */
+export interface EnrichContext {
+    /**
+     * The buffer's Liquid tree, as returned by the lint that produced these diagnostics.
+     *
+     * `undefined` for a buffer with no Liquid tree — GraphQL, YAML, or a file that did not
+     * parse. Those diagnostics simply get no symbol hint; the check's documentation URL
+     * still attaches, because it does not depend on the tree.
+     */
+    ast?: LiquidHtmlNode;
+    vocabulary: DocsetVocabulary;
+}
+/**
+ * Attach what we can to each diagnostic, and nothing we cannot.
+ *
+ * Returns NEW objects; the inputs are not mutated. A diagnostic gains a key only when there
+ * is a real value for it — never an empty string or a placeholder — so an agent can read
+ * absence as "nothing more is known".
+ *
+ * ONE HINT PER SYMBOL PER FILE. A signature is ~880 bytes of markdown and it is the SAME
+ * bytes every time the symbol is misused, so repeats would spend the diagnostic budget
+ * (`result/response-budget.ts`) restating one paragraph. The FIRST occurrence keeps it,
+ * 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

@@ -0,0 +1,136 @@
+// Deep import, NOT the package root: measured at +5 ms against +110 ms, the difference
+// being the css / json / graphql language services this package never uses. The bin is
+// launched once per agent session, so that is paid every session. See ADR 002 Amendment 1.
+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.
+ *
+ * Policy, not documentation — a statement about which findings an agent can act on with a
+ * signature in front of it, the same kind of judgement as `BLOCKING_CHECKS`. Each entry
+ * says why, because "it seemed relevant" is how this grows into noise.
+ *
+ * DEFAULTS TO SILENCE. A check not listed gets no hint, so a check added upstream cannot
+ * start emitting an unrelated wall of markdown before anyone has looked at it.
+ *
+ * A list rather than a structural rule, because no structural rule separates the useful
+ * case from the useless one: `{% render 'ghost' %}` resolves to the `render` TAG, so
+ * rendering whatever symbol an offense sits on answers "'ghost' does not exist" with
+ * general documentation about how `render` works.
+ */
+export const SIGNATURE_HINT_CHECKS = new Set([
+    // "given 1, expected 2" — the published arity IS the fix, and it is the one thing the
+    // message cannot carry without restating the documentation.
+    'FilterArity',
+    // An argument of the wrong type. What the filter actually accepts is the answer, and
+    // the parameter list is where it is written down.
+    'ValidFilterArgumentTypes',
+    // The same for a tag's arguments: `{% for x in y limit: 'ten' %}` is answered by the
+    // `for` entry's parameter types.
+    'ValidTagArgumentTypes',
+]);
+/**
+ * Attach what we can to each diagnostic, and nothing we cannot.
+ *
+ * Returns NEW objects; the inputs are not mutated. A diagnostic gains a key only when there
+ * is a real value for it — never an empty string or a placeholder — so an agent can read
+ * absence as "nothing more is known".
+ *
+ * ONE HINT PER SYMBOL PER FILE. A signature is ~880 bytes of markdown and it is the SAME
+ * bytes every time the symbol is misused, so repeats would spend the diagnostic budget
+ * (`result/response-budget.ts`) restating one paragraph. The FIRST occurrence keeps it,
+ * which is also the one truncation keeps: the cap retains the top of the file.
+ */
+export function enrichDiagnostics(inputs, context) {
+    const rendered = new Set();
+    return inputs.map(({ diagnostic, startIndex }) => {
+        const enriched = { ...diagnostic };
+        const url = checkDocs(diagnostic.check)?.url;
+        if (url)
+            enriched.see_also = url;
+        const hint = hintFor(diagnostic.check, startIndex, context, rendered);
+        if (hint)
+            enriched.hint = hint;
+        return enriched;
+    });
+}
+/**
+ * The rendered docset entry for the symbol at `offset`, when the docset publishes one and
+ * this file has not already been shown it.
+ *
+ * NOTHING when it does not: a symbol the docset has never heard of has no signature to
+ * show, and the engine's own `suggestions` are what help there.
+ *
+ * Searched from the offset OUTWARDS through the ancestors — `{% for x in y limit: 'ten' %}`
+ * reports on the argument, and the `for` entry that answers it is three levels up.
+ *
+ * `rendered` is mutated only when a hint is actually produced, so an unpublished symbol
+ * cannot consume the slot its name has and silence a later published one.
+ */
+function hintFor(check, offset, context, rendered) {
+    if (!SIGNATURE_HINT_CHECKS.has(check))
+        return undefined;
+    if (!context.ast || offset === undefined)
+        return undefined;
+    const symbol = documentedSymbolAt(context.ast, offset);
+    if (!symbol)
+        return undefined;
+    const key = `${symbol.kind}:${symbol.name}`;
+    if (rendered.has(key))
+        return undefined;
+    const entry = entryFor(symbol, context.vocabulary);
+    if (!entry)
+        return undefined;
+    rendered.add(key);
+    return render(entry, undefined, symbol.kind);
+}
+/** The published entry for a symbol, matched by exact name within its own kind. */
+function entryFor(symbol, vocabulary) {
+    const entries = symbol.kind === 'filter'
+        ? vocabulary.filters
+        : symbol.kind === 'tag'
+            ? vocabulary.tags
+            : 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/enrich/enrich.spec.d.ts

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

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