@smeltjs/core 0.1.0

package/dist/plan/planners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planners.d.ts","sourceRoot":"","sources":["../../src/plan/planners.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,wBAAwB,CAAC;CAChD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ;gCACA,qBAAqB,KAAG,OAAO;mCAC5B,qBAAqB,KAAG,OAAO;CAEyB,CAAC;AAEjF,2FAA2F;AAC3F,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,QAAQ,CAAC;AAE7C,mFAAmF;AACnF,eAAO,MAAM,UAAU,EAA4B,SAAS,QAAQ,EAAE,CAAC;AAEvE,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D"}

package/dist/plan/planners.js

@@ -0,0 +1,26 @@
+import { LexicalPlanner } from './lexical.js';
+import { StructuralPlanner } from './structural.js';
+/**
+ * The one registry of planner strategies — string in, constructed {@link Planner} out.
+ *
+ * This object is the single place the strategy names live. `createSmelter` builds from
+ * it, `--strategy` and `smelt.config.json` validation accept exactly its keys, and the
+ * `--help` text renders its keys — so a strategy cannot exist in one of those faces and
+ * be missing from another. Before this registry the pair was restated in three places,
+ * which is how help text rots.
+ *
+ * `'structural'` parses every language named in {@link STRUCTURAL_LANGUAGES} with a
+ * bundled grammar and throws {@link GrammarUnavailableError} for anything else — never
+ * a silent lexical fallback. See {@link StructuralPlanner}.
+ */
+export const PLANNERS = {
+    lexical: (options) => new LexicalPlanner(options.lexical ?? {}),
+    structural: (options) => new StructuralPlanner(options.structural ?? {}),
+};
+/** The registry's keys, in declaration order, for help text and error messages. */
+export const STRATEGIES = Object.keys(PLANNERS);
+/** The one membership test `--strategy` and config validation both use. */
+export function isStrategy(value) {
+    return Object.hasOwn(PLANNERS, value);
+}
+//# sourceMappingURL=planners.js.map

package/dist/plan/planners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planners.js","sourceRoot":"","sources":["../../src/plan/planners.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAYpD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,OAAO,EAAE,CAAC,OAA8B,EAAW,EAAE,CAAC,IAAI,cAAc,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IAC/F,UAAU,EAAE,CAAC,OAA8B,EAAW,EAAE,CACtD,IAAI,iBAAiB,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;CAC6B,CAAC;AAKjF,mFAAmF;AACnF,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAwB,CAAC;AAEvE,2EAA2E;AAC3E,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AACxC,CAAC"}

package/dist/plan/structural.d.ts

@@ -0,0 +1,68 @@
+import type { ElisionPlan, LanguageId, PlanInput, Planner } from '../types.ts';
+export declare const STRUCTURAL_PLANNER_ID = "structural/v1";
+/**
+ * The languages this planner actually parses — a derived view of the registry: every
+ * {@link LanguageProfile} that carries a `structure` section, in registry order. A
+ * language appears here only once its node kinds are mapped in its profile
+ * (`src/lang/<id>.ts`), because claiming a language before that would produce markers
+ * that mislabel what they collapsed.
+ *
+ * Exported for the totality guard (`test/guards/structural-totality.test.ts`): every
+ * language named here must have a fixture, a snapshot and a doc-comment case, so a
+ * language cannot be claimed without tests.
+ */
+export declare const STRUCTURAL_LANGUAGES: readonly LanguageId[];
+/**
+ * Historically the union of the claimed ids; every `LanguageId` carries a profile
+ * now, so the compile-time totality this type enforced lives on the registry
+ * (`Record<LanguageId, LanguageProfile>`) instead.
+ */
+export type StructuralLanguage = LanguageId;
+export interface StructuralPlannerOptions {
+    /**
+     * Never collapse a sibling group smaller than this. Defaults to 1 — the byte
+     * profitability check already refuses collapses that would not pay for their marker.
+     */
+    readonly minSiblings?: number;
+    /** Focus matching is substring, case-insensitive by default — same as lexical. */
+    readonly caseSensitive?: boolean;
+}
+/**
+ * The structural planner — the reason smelt exists.
+ *
+ * It parses with the language's tree-sitter grammar, finds the top-level declarations
+ * whose text matches the caller's focus, keeps each match whole — signature line,
+ * attached doc comment, body — and collapses each contiguous run of non-matching
+ * *siblings* into one marker that names them from the parse tree: `collapsed 3 sibling
+ * functions`. Structure is what makes that explanation possible; a line window can only
+ * ever say "collapsed 40 lines".
+ *
+ * It throws {@link GrammarUnavailableError} rather than falling back to the lexical
+ * planner, and that is the deliberate part. A silent fallback would mean a caller who
+ * asked for structural planning, and whose grammar failed to load, gets line-window
+ * output labelled `structural/v1` — plausible, wrong, and undetectable from the
+ * outside. A caller who wants the fallback asks for it, by planning lexically itself.
+ */
+export declare class StructuralPlanner implements Planner {
+    readonly id = "structural/v1";
+    readonly options: StructuralPlannerOptions;
+    constructor(options?: StructuralPlannerOptions);
+    plan(input: PlanInput): Promise<ElisionPlan>;
+}
+/**
+ * The planner as a function, exported like {@link planLexical} so it can be tested and
+ * reused directly. Deterministic: same text, same language, same focus, same options —
+ * byte-identical plan.
+ *
+ * `budgetBytes` is a target, not a guarantee, for the same reason it is in the lexical
+ * planner: once every non-matching sibling run is collapsed there is nothing left to
+ * cut except the declarations the caller asked to keep, and an optimizer that silently
+ * drops the thing you searched for is the exact failure this design refuses. Callers
+ * who need a hard ceiling check `outputBytes` and decide.
+ *
+ * @throws {GrammarUnavailableError} when the language is not one this planner parses,
+ *   when the grammar cannot be loaded, or when the parser produces no tree. Never a
+ *   lexical fallback.
+ */
+export declare function planStructural(input: PlanInput, options?: StructuralPlannerOptions): Promise<ElisionPlan>;
+//# sourceMappingURL=structural.d.ts.map

package/dist/plan/structural.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural.d.ts","sourceRoot":"","sources":["../../src/plan/structural.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EAEV,SAAS,EAET,OAAO,EACR,MAAM,aAAa,CAAC;AAIrB,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,UAAU,EAA0B,CAAC;AAEjF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAQ5C,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AA+BD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAkB,YAAW,OAAO;IAC/C,QAAQ,CAAC,EAAE,mBAAyB;IACpC,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAE3C,YAAY,OAAO,GAAE,wBAA6B,EAEjD;IAED,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAE3C;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,WAAW,CAAC,CA8BtB"}

package/dist/plan/structural.js

@@ -0,0 +1,458 @@
+import { Parser } from 'web-tree-sitter';
+import { GrammarUnavailableError, MissingMarkerPricingError } from '../errors.js';
+import { profileFor, structuralLanguages } from '../lang/registry.js';
+import { loadGrammar } from './grammar.js';
+export const STRUCTURAL_PLANNER_ID = 'structural/v1';
+/**
+ * The languages this planner actually parses — a derived view of the registry: every
+ * {@link LanguageProfile} that carries a `structure` section, in registry order. A
+ * language appears here only once its node kinds are mapped in its profile
+ * (`src/lang/<id>.ts`), because claiming a language before that would produce markers
+ * that mislabel what they collapsed.
+ *
+ * Exported for the totality guard (`test/guards/structural-totality.test.ts`): every
+ * language named here must have a fixture, a snapshot and a doc-comment case, so a
+ * language cannot be claimed without tests.
+ */
+export const STRUCTURAL_LANGUAGES = structuralLanguages();
+/**
+ * Every elision this planner produces carries this rule id, and the profitability
+ * check below prices the marker that rule would earn — so the two must not drift.
+ */
+const SIBLING_COLLAPSE_RULE = 'sibling-collapse';
+/**
+ * The structural planner — the reason smelt exists.
+ *
+ * It parses with the language's tree-sitter grammar, finds the top-level declarations
+ * whose text matches the caller's focus, keeps each match whole — signature line,
+ * attached doc comment, body — and collapses each contiguous run of non-matching
+ * *siblings* into one marker that names them from the parse tree: `collapsed 3 sibling
+ * functions`. Structure is what makes that explanation possible; a line window can only
+ * ever say "collapsed 40 lines".
+ *
+ * It throws {@link GrammarUnavailableError} rather than falling back to the lexical
+ * planner, and that is the deliberate part. A silent fallback would mean a caller who
+ * asked for structural planning, and whose grammar failed to load, gets line-window
+ * output labelled `structural/v1` — plausible, wrong, and undetectable from the
+ * outside. A caller who wants the fallback asks for it, by planning lexically itself.
+ */
+export class StructuralPlanner {
+    id = STRUCTURAL_PLANNER_ID;
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    plan(input) {
+        return planStructural(input, this.options);
+    }
+}
+/**
+ * The planner as a function, exported like {@link planLexical} so it can be tested and
+ * reused directly. Deterministic: same text, same language, same focus, same options —
+ * byte-identical plan.
+ *
+ * `budgetBytes` is a target, not a guarantee, for the same reason it is in the lexical
+ * planner: once every non-matching sibling run is collapsed there is nothing left to
+ * cut except the declarations the caller asked to keep, and an optimizer that silently
+ * drops the thing you searched for is the exact failure this design refuses. Callers
+ * who need a hard ceiling check `outputBytes` and decide.
+ *
+ * @throws {GrammarUnavailableError} when the language is not one this planner parses,
+ *   when the grammar cannot be loaded, or when the parser produces no tree. Never a
+ *   lexical fallback.
+ */
+export async function planStructural(input, options = {}) {
+    const language = assertStructuralLanguage(input.language);
+    // The runtime backstop for JS callers: TypeScript makes `pricing` required, but a
+    // JS caller can omit it, and the honest answer is a named refusal rather than the
+    // planner quietly pricing markers itself — the inversion the seam removed.
+    const pricing = input.pricing;
+    if (pricing === undefined)
+        throw new MissingMarkerPricingError(STRUCTURAL_PLANNER_ID);
+    const grammar = await loadGrammar(language);
+    const parser = new Parser();
+    let tree = null;
+    try {
+        parser.setLanguage(grammar);
+        tree = parser.parse(input.text);
+        if (tree === null) {
+            throw new GrammarUnavailableError(`smelt: the ${language} parser returned no tree. Structural planning cannot ` +
+                `proceed, and it does not fall back to lexical — a caller who wants the ` +
+                `fallback plans lexically itself.`);
+        }
+        return {
+            planner: STRUCTURAL_PLANNER_ID,
+            language: input.language,
+            elisions: planFromTree(tree, input, options, language),
+        };
+    }
+    finally {
+        tree?.delete();
+        parser.delete();
+    }
+}
+function assertStructuralLanguage(language) {
+    for (const supported of STRUCTURAL_LANGUAGES) {
+        if (language === supported)
+            return supported;
+    }
+    const named = `${STRUCTURAL_LANGUAGES.slice(0, -1).join(', ')} and ${STRUCTURAL_LANGUAGES[STRUCTURAL_LANGUAGES.length - 1]}`;
+    throw new GrammarUnavailableError(`smelt: structural planning covers ${named} in this ` +
+        `slice; got "${language}". It does not fall back to the lexical planner — output ` +
+        `labelled structural/v1 that is really line windows would be undetectable from ` +
+        `the outside. Use the lexical planner explicitly if that is what you want.`);
+}
+function planFromTree(tree, input, options, language) {
+    const profile = profileFor(language);
+    // assertStructuralLanguage admits only languages whose profile carries a
+    // `structure` section — that is the definition of a structural language — so the
+    // assertion states a fact the seam already proved.
+    const structure = profile.structure;
+    const pricing = input.pricing;
+    // The marker lands as a line comment in every structural language (the profile's
+    // markerLeader), and a line comment comments out everything to the end of its
+    // line — so a collapse is only legal where nothing kept follows on the marker's
+    // own line. See the flush below.
+    const markerIsLineComment = profile.markerLeader !== undefined;
+    const units = unitsOf(tree.rootNode, input.text, structure);
+    const matched = matchUnits(units, input, options);
+    const minSiblings = options.minSiblings ?? 1;
+    const toByte = utf8OffsetIndex(input.text, units.flatMap((unit) => [unit.start, unit.end]));
+    const elisions = [];
+    let run = [];
+    const flush = () => {
+        if (run.length === 0)
+            return;
+        const group = run;
+        run = [];
+        if (group.length < minSiblings)
+            return;
+        // A line-comment marker swallows the rest of its line. When the run's last unit
+        // ends mid-line — python's `stmt_a(); stmt_b()` puts two top-level statements on
+        // one line — the marker's `# ` leader would comment out the *kept* code after it.
+        // Refusing the collapse is the honest move; extending the range would elide code
+        // no unit accounted for.
+        if (markerIsLineComment && !restOfLineIsBlank(input.text, group[group.length - 1].end)) {
+            return;
+        }
+        const start = toByte.get(group[0].start);
+        const end = toByte.get(group[group.length - 1].end);
+        const cutBytes = end - start;
+        const explanation = explain(group);
+        // Profitability, priced rather than estimated: ask the MarkerPricing seam for the
+        // exact cost of the marker this cut would earn — the explanation's length varies
+        // with kind diversity, and the pricing carries the language's comment leader (or a
+        // caller's custom builder), so a fixed estimate can pass a cut whose marker is
+        // bigger than what it removes, and a marker that costs more than it removes grows
+        // the output.
+        const markerBytes = pricing.costBytes({ rule: SIBLING_COLLAPSE_RULE, explanation }, cutBytes);
+        if (cutBytes <= markerBytes)
+            return;
+        elisions.push({
+            range: { start, end },
+            reason: { rule: SIBLING_COLLAPSE_RULE, explanation },
+        });
+    };
+    for (let i = 0; i < units.length; i += 1) {
+        if (matched[i] === true || units[i].pinned === true) {
+            flush();
+        }
+        else {
+            run.push(units[i]);
+        }
+    }
+    flush();
+    return elisions;
+}
+/** True when nothing but whitespace follows `index` on its own line. */
+function restOfLineIsBlank(text, index) {
+    for (let i = index; i < text.length; i += 1) {
+        const ch = text[i];
+        if (ch === '\n')
+            return true;
+        if (!/\s/.test(ch))
+            return false;
+    }
+    return true;
+}
+/**
+ * Group the root's named children into units: each declaration plus the comment block
+ * — and, in rust, the outer attributes — attached to it. A comment attaches when only
+ * blank-free whitespace separates it from what follows — one newline at most — so a doc
+ * comment travels with its declaration, while a comment left floating above a blank
+ * line stands alone.
+ *
+ * Attributes attach *unconditionally*: tree-sitter-rust parses `#[inline]` as a
+ * top-level sibling of the item it decorates, but the language's own rule is that an
+ * outer attribute modifies the next item, blank lines or not. So once an attribute is
+ * pending, the whole pending prefix (doc comments included) rides forward to the next
+ * declaration — treating it as its own unit would let a collapse strip `#[derive(…)]`
+ * and the doc comment above it off a kept declaration.
+ */
+function unitsOf(root, text, structure) {
+    const units = [];
+    /** Comments and attributes waiting to attach to the next declaration. */
+    let pending = [];
+    /** Once true, blank lines no longer detach the pending prefix — see above. */
+    let pendingHasAttribute = false;
+    const flushPending = () => {
+        if (pending.length === 0)
+            return;
+        units.push({
+            start: pending[0].startIndex,
+            end: pending[pending.length - 1].endIndex,
+            kind: pendingHasAttribute ? 'attribute' : 'comment',
+            pinned: !pendingHasAttribute && pending.some((node) => pinnedComment(node, text, structure)),
+        });
+        pending = [];
+        pendingHasAttribute = false;
+    };
+    for (const child of root.namedChildren) {
+        if (child === null)
+            continue;
+        if (structure.ridesBackwardTypes?.has(child.type) === true && units.length > 0) {
+            // A node that is grammatically part of the *previous* statement, parsed as a
+            // top-level sibling: tree-sitter-ruby emits a heredoc's body as a sibling of
+            // the statement holding its `<<~SQL` opener. Splitting them lets a collapse
+            // keep the opener and cut the body — an unterminated heredoc that swallows
+            // every kept declaration after it, without a single ERROR node to show for
+            // it. The body extends the preceding unit instead, so opener and body are
+            // kept whole or collapsed whole, always.
+            flushPending();
+            const last = units[units.length - 1];
+            units[units.length - 1] = { ...last, end: child.endIndex };
+            continue;
+        }
+        if (structure.pinnedTypes?.has(child.type) === true ||
+            pinnedDirective(child, text, structure)) {
+            // A pinned node (php's `<?php` tag, a `#!` shebang line, c's `#pragma once`)
+            // is its own uncollapsible unit — nothing attaches to it, and no run may
+            // swallow it.
+            flushPending();
+            units.push({
+                start: child.startIndex,
+                end: child.endIndex,
+                kind: kindOf(child, structure),
+                pinned: true,
+            });
+            continue;
+        }
+        const isComment = structure.commentTypes.has(child.type);
+        const isAttribute = structure.attributeTypes.has(child.type);
+        if (isComment || isAttribute) {
+            if (pending.length > 0 &&
+                !pendingHasAttribute &&
+                !adjacent(text, pending[pending.length - 1].endIndex, child.startIndex)) {
+                flushPending();
+            }
+            pending.push(child);
+            pendingHasAttribute ||= isAttribute;
+            continue;
+        }
+        // tree-sitter-kotlin extends the import_list node over a doc comment that
+        // follows it, so the KDoc of the first documented declaration after the imports
+        // would be collapsed *with the imports* — a kept declaration losing its attached
+        // doc comment. Split such trailing comments off: the unit ends at its last
+        // non-comment token, and the comments ride forward like any other pending block.
+        const { end: childEnd, trailing } = structure.trailingCommentSplitTypes?.has(child.type) === true
+            ? splitTrailingComments(child, structure)
+            : { end: child.endIndex, trailing: [] };
+        const attached = pending.length > 0 &&
+            (pendingHasAttribute ||
+                adjacent(text, pending[pending.length - 1].endIndex, child.startIndex));
+        if (attached && pending.some((node) => pinnedComment(node, text, structure))) {
+            // A pinned comment (`//go:build`) governs the file, not the declaration it
+            // happens to touch — keep it a standalone, uncollapsible unit either way.
+            flushPending();
+            units.push({
+                start: child.startIndex,
+                end: childEnd,
+                kind: kindOf(child, structure),
+            });
+        }
+        else if (attached) {
+            units.push({
+                start: pending[0].startIndex,
+                end: childEnd,
+                kind: kindOf(child, structure),
+            });
+            pending = [];
+            pendingHasAttribute = false;
+        }
+        else {
+            flushPending();
+            units.push({
+                start: child.startIndex,
+                end: childEnd,
+                kind: kindOf(child, structure),
+            });
+        }
+        for (const comment of trailing)
+            pending.push(comment);
+    }
+    flushPending();
+    return units;
+}
+/** Whether this comment node is one the language pins to the file. See {@link Unit}. */
+function pinnedComment(node, text, structure) {
+    if (structure.pinnedCommentPattern === undefined)
+        return false;
+    if (!structure.commentTypes.has(node.type))
+        return false;
+    return structure.pinnedCommentPattern.test(text.slice(node.startIndex, node.endIndex));
+}
+/**
+ * Whether this non-comment node is pinned by a per-type text pattern. C's
+ * `#pragma once` is a `preproc_call` like any other pragma, but collapsing it
+ * silently changes header inclusion semantics — the same class as `//go:build`, on a
+ * node kind a comment pattern cannot reach.
+ */
+function pinnedDirective(node, text, structure) {
+    const pattern = structure.pinnedPatternsByType?.[node.type];
+    if (pattern === undefined)
+        return false;
+    return pattern.test(text.slice(node.startIndex, node.endIndex));
+}
+/**
+ * The end of `node`'s last non-comment token, and every comment node after it. Used
+ * for node types the grammar extends over comments that belong to what follows —
+ * kotlin's import_list swallowing the next declaration's KDoc.
+ */
+function splitTrailingComments(node, structure) {
+    const comments = [];
+    let end = node.startIndex;
+    const walk = (current) => {
+        if (structure.commentTypes.has(current.type)) {
+            comments.push(current);
+            return;
+        }
+        let hasChildren = false;
+        for (const child of current.children) {
+            if (child === null)
+                continue;
+            hasChildren = true;
+            walk(child);
+        }
+        if (!hasChildren && current.endIndex > end)
+            end = current.endIndex;
+    };
+    for (const child of node.children) {
+        if (child !== null)
+            walk(child);
+    }
+    return { end, trailing: comments.filter((comment) => comment.startIndex >= end) };
+}
+/** Nothing but whitespace between the two indices, and at most one newline. */
+function adjacent(text, end, start) {
+    const between = text.slice(end, start);
+    if (!/^\s*$/.test(between))
+        return false;
+    return (between.match(/\n/g) ?? []).length <= 1;
+}
+function matchUnits(units, input, options) {
+    const caseSensitive = options.caseSensitive ?? false;
+    const focus = (input.focus ?? []).filter((term) => term.length > 0);
+    const needles = caseSensitive ? focus : focus.map((term) => term.toLowerCase());
+    return units.map((unit) => {
+        if (needles.length === 0)
+            return false;
+        const raw = input.text.slice(unit.start, unit.end);
+        const haystack = caseSensitive ? raw : raw.toLowerCase();
+        return needles.some((needle) => haystack.includes(needle));
+    });
+}
+/**
+ * Law 2, for this rule: the explanation names the *kind* and the *count*, read off the
+ * parse tree — `collapsed 3 sibling functions` — never a line count as the claim. A
+ * mixed run says what it mixed: `collapsed 4 sibling declarations (3 functions,
+ * 1 class)` — and when the run holds anything that is not a declaration (a statement,
+ * a floating comment, an unparsed region), the heading says `nodes`, because calling
+ * a parse error a declaration would be the marker lying about the tree.
+ */
+function explain(group) {
+    const counts = new Map();
+    for (const unit of group)
+        counts.set(unit.kind, (counts.get(unit.kind) ?? 0) + 1);
+    const total = group.length;
+    if (counts.size === 1) {
+        const kind = group[0].kind;
+        return `collapsed ${String(total)} sibling ${countNoun(kind, total)}`;
+    }
+    const parts = [...counts.entries()].map(([kind, count]) => `${String(count)} ${countNoun(kind, count)}`);
+    const heading = [...counts.keys()].every((kind) => !NON_DECLARATION_KINDS.has(kind))
+        ? 'declarations'
+        : 'nodes';
+    return `collapsed ${String(total)} sibling ${heading} (${parts.join(', ')})`;
+}
+/** The kind labels that are not declarations, so a mixed heading never overclaims. */
+const NON_DECLARATION_KINDS = new Set([
+    'statement',
+    'comment',
+    'unparsed region',
+    'package clause',
+    'package header',
+    'package declaration',
+    'attribute',
+    'command',
+    'variable assignment',
+    'include directive',
+    'shebang',
+    'php tag',
+    'html section',
+    'heredoc body',
+    'preprocessor directive',
+    'preprocessor conditional',
+]);
+function countNoun(kind, count) {
+    if (count === 1)
+        return kind;
+    if (/[^aeiou]y$/.test(kind))
+        return `${kind.slice(0, -1)}ies`;
+    return /(?:s|sh|ch)$/.test(kind) ? `${kind}es` : `${kind}s`;
+}
+/**
+ * The kind of a declaration, unwrapping wrappers (`export …`, `@decorator`) so the
+ * marker names what it hides. What the language's map does not name is still labelled
+ * honestly — see {@link LanguageStructure.kindLabels} for the labelling rules.
+ */
+function kindOf(node, structure) {
+    const wrapperFallback = structure.wrapperTypes[node.type];
+    if (wrapperFallback !== undefined) {
+        for (const child of node.namedChildren) {
+            if (child === null || structure.commentTypes.has(child.type))
+                continue;
+            const label = structure.kindLabels[child.type];
+            if (label !== undefined)
+                return label;
+        }
+        return wrapperFallback;
+    }
+    const label = structure.kindLabels[node.type];
+    if (label !== undefined)
+        return label;
+    if (node.type === 'ERROR')
+        return 'unparsed region';
+    if (node.type.endsWith('_statement') || node.type === 'statement_block')
+        return 'statement';
+    return 'declaration';
+}
+/**
+ *
+ * web-tree-sitter reports positions in code units of the JS string it parsed;
+ * {@link ElisionPlan} ranges are UTF-8 bytes. Because every converted index is a parse
+ * node boundary, a range can never split a multi-byte character — a node boundary is
+ * always a character boundary. One forward pass, so the conversion is linear.
+ */
+function utf8OffsetIndex(text, indices) {
+    const sorted = [...new Set(indices)].toSorted((a, b) => a - b);
+    const map = new Map();
+    let previousIndex = 0;
+    let previousByte = 0;
+    for (const index of sorted) {
+        previousByte += Buffer.byteLength(text.slice(previousIndex, index), 'utf8');
+        previousIndex = index;
+        map.set(index, previousByte);
+    }
+    return map;
+}
+//# sourceMappingURL=structural.js.map

package/dist/plan/structural.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural.js","sourceRoot":"","sources":["../../src/plan/structural.ts"],"names":[],"mappings":"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"}

package/dist/repomap/cache.d.ts

@@ -0,0 +1,53 @@
+import type { FileTags } from './tags.ts';
+import type { LanguageId } from '../types.ts';
+/**
+ * The repo map's disk cache — per-file tags, keyed by content hash, JSON on disk.
+ *
+ * Modelled on Aider's repo-map tags cache (https://aider.chat/docs/repomap.html),
+ * with one deliberate substitution: Aider persists through SQLite; this repo ships
+ * zero new runtime dependencies, so entries are plain JSON files under a directory
+ * **the caller explicitly hands in**. smelt never writes outside a store or cache it
+ * was handed — no default location, no home-directory guessing.
+ *
+ * The key is a content hash over the tag-format version, the language, and the file's
+ * exact text. That is the whole invalidation story: edit a file and its key changes,
+ * so the stale entry is simply never looked up again. Nothing needs a timestamp.
+ *
+ * A corrupt entry — unparseable JSON, or JSON of the wrong shape — is **discarded
+ * loudly, never trusted**: the entry file is deleted, the tags are re-extracted from
+ * source, and the caller's result carries a warning naming the file. Trusting a
+ * damaged cache would silently drop symbols from the map, which is this project's
+ * signature failure mode.
+ */
+/** The format name every cache entry carries. */
+export declare const TAGS_CACHE_FORMAT = "smelt-repomap-tags";
+/** Bump this when the tag shape changes: old entries then miss instead of misleading. */
+export declare const TAGS_CACHE_VERSION = 1;
+/**
+ * The cache key for one file's tags. The version and language are part of the hashed
+ * material, so a format bump or a re-detected language can never resurrect an entry
+ * extracted under different rules.
+ */
+export declare function tagsCacheKey(language: LanguageId, content: string): string;
+/** What `read()` reports about one lookup. */
+export type TagsCacheLookup = FileTags | 'corrupt' | undefined;
+export declare class TagsCache {
+    #private;
+    /** `dir` is the directory the caller handed in; entries live under `<dir>/tags/`. */
+    constructor(dir: string);
+    /**
+     * The cached tags under `key`, `undefined` on a miss, `'corrupt'` when an entry
+     * existed but could not be trusted — in which case it has already been deleted, so
+     * the corruption is reported exactly once and never re-read.
+     */
+    read(key: string): TagsCacheLookup;
+    /**
+     * Persist one file's tags. Written to a temp name and renamed into place, so a
+     * concurrent reader never sees a half-written entry; both writers of the same key
+     * are writing identical bytes (the key covers the content), so last-rename-wins is
+     * harmless. No fsync: unlike the elision store, every entry here is derivable from
+     * source, so losing one to a crash costs a re-parse, not a broken promise.
+     */
+    write(key: string, tags: FileTags): void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/repomap/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/repomap/cache.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAiB,QAAQ,EAAgB,MAAM,WAAW,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,8CAA8C;AAC9C,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/D,qBAAa,SAAS;;IAGpB,qFAAqF;IACrF,YAAY,GAAG,EAAE,MAAM,EAGtB;IAED;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAqBjC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAWvC;CAeF"}