svelte-shaker 0.17.0 → 0.18.0

package/README.md

@@ -49,19 +49,17 @@ npm i -D svelte-shaker   # requires svelte@^5
 
 Nothing else to install. The plugin picks its engine automatically (see
 [Options](#options)): if a **native (napi) Rust** binary loads it runs there —
-parsing with rsvelte in process, fastest, no size ceiling; otherwise a small/medium
-app runs on the **WASM Rust engine** (parsing with **rsvelte** from
-`@rsvelte/compiler`, a bundled WASM dependency — no peer, no platform-specific
-binary) and a large app on the **JS engine** with **svelte/compiler**. `engine` and
-`parser` let you pin the choice.
+parsing with rsvelte in process, by far the fastest; otherwise the shake runs on the
+**JS engine** with **svelte/compiler**, which needs no prebuilt binary and always
+works. Both shake **byte-identically**, so the fallback costs only build time.
+`engine` and `parser` let you pin the choice.
 
 ## Usage (Vite)
 
 Add the plugin **before** `svelte()`. By default it runs only in `vite build` —
 dev/HMR is a pass-through (opt into dev shaking with the `dev` option, see
 [Options](#options)). The engine is chosen automatically (native Rust if a binary
-loads, else WASM Rust for small/medium or JS for large), and every path falls back
-cleanly (see [Options](#options)).
+loads, else JS), and every path falls back cleanly (see [Options](#options)).
 
 ```ts
 // vite.config.ts
@@ -87,7 +85,7 @@ through your plugin's `resolveId`/`load` hooks; the unused-prop fold / constant
 fold / value-set narrowing shake only needs the `transform` swap. The
 environment-free engine and the in-browser playground parse with svelte/compiler
 — the Vite plugin's rsvelte selection is a plugin concern (it loads a Node-only
-WASM module); the engine takes an optional `parse` argument if you want to swap it.
+module); the engine takes an optional `parse` argument if you want to swap it.
 
 ### Options
 
@@ -107,9 +105,9 @@ shaker({
   verbose: false, // true = per-file size breakdown after the build
 
   // Engine is auto-selected; set these only to pin.
-  engine: 'auto', // 'auto' (native Rust if it loads, else WASM if <=~300, else JS) | 'js' | 'rust'
-  parser: undefined, // JS/WASM parse only (native always uses in-process rsvelte);
-  // default follows the engine (WASM->rsvelte, JS->svelte); set 'rsvelte' | 'svelte' to pin
+  engine: 'auto', // 'auto' (native Rust if it loads, else JS) | 'js' | 'rust'
+  parser: undefined, // JS engine only (native always uses in-process rsvelte);
+  // defaults to svelte/compiler; set 'rsvelte' to pin rsvelte instead
 
   dev: false, // default off: dev is a pass-through. 'incremental' (re-parse only
   // changed files) | 'coarse' (re-analyze everything) opts in; never monomorphizes
@@ -120,33 +118,25 @@ That list is exhaustive: any other key **fails the build**, naming the key and t
 options that do exist. A typo would otherwise be ignored — and a misspelled
 `preserve` ships the component you meant to protect, over-shaken.
 
-- **`engine`** — which engine runs the shake. There are two Rust engines (the same
-  analysis behind two frontends) plus the JS engine. The **native (napi)** engine
-  parses with rsvelte **in process** and keeps the ASTs Rust-side, so no
-  whole-program AST crosses a boundary — fastest, no size ceiling — but it ships as
-  a per-platform prebuilt binary that may not exist for every install. The **WASM**
-  engine is the same Rust engine, but the whole-program AST must cross the JS↔WASM
-  boundary as JSON (tens of MB past a few hundred components), so it only wins for
-  small/medium apps; the **JS** engine needs no boundary crossing, so it wins for a
-  large app when the native binary isn't available. **`'auto'`** (default) uses the
-  native engine if a binary loads (no size gate), else the WASM engine for a
-  small/medium app or the JS engine for a large one. **`'rust'`** forces a Rust
-  engine — native if it loads, else WASM (throwing if `@rsvelte/compiler` can't load
-  for the WASM fallback); **`'js'`** forces the JS engine. All three are
+- **`engine`** — which engine runs the shake. There are two. The **native (napi
+  Rust)** engine parses with rsvelte **in process** and keeps the ASTs Rust-side, so
+  no whole-program AST crosses a boundary — by far the fastest — but it ships as a
+  per-platform prebuilt binary that may not exist for every install. The **JS**
+  engine needs no prebuilt binary and always works. **`'auto'`** (default) uses the
+  native engine if a binary loads, else the JS engine. **`'rust'`** forces the native
+  engine, throwing if it can't be loaded; **`'js'`** forces the JS engine. Both are
   differentially tested to shake **byte-identically**, so this is **speed-only** — it
   never changes what ships.
-- **`parser`** — how the **JS / WASM** engines parse `.svelte`. It does **not** apply
-  to the native engine, which always parses with rsvelte in process. The default
-  **follows the engine**: **rsvelte** on the WASM engine (its AST crosses into Rust
-  directly), **svelte/compiler** on the JS engine (where rsvelte's parse is ~2× slower
-  with no downstream benefit). The choice is **soundness-neutral** — the engine reads
-  only UTF-16 `start`/`end`, so both parsers are differentially tested to produce
+- **`parser`** — how the **JS** engine parses `.svelte`. It does **not** apply to the
+  native engine, which always parses with rsvelte in process. It defaults to
+  **svelte/compiler**, because on the JS engine rsvelte's parse is ~2× slower with no
+  downstream benefit. The choice is **soundness-neutral** — the engine reads only
+  UTF-16 `start`/`end`, so both parsers are differentially tested to produce
   **byte-identical** output, never changing what renders. `parser: 'svelte'` also
   forces the native engine **off** (it can't honor svelte/compiler), so the shake uses
-  a JS/WASM engine with svelte/compiler. When rsvelte is the resolved JS-side parser
-  (`parser: 'rsvelte'`, or the WASM engine's default) and `@rsvelte/compiler` can't
-  load, the plugin **throws** rather than silently swapping (so the same source can't
-  shake differently on another machine); `parser: 'svelte'` is the explicit opt-out.
+  the JS engine. With an explicit `parser: 'rsvelte'` that `@rsvelte/compiler` can't
+  satisfy, the plugin **throws** rather than silently swapping (so the same source
+  can't shake differently on another machine); `parser: 'svelte'` is the opt-out.
 - **`monomorphize`** — the one shaking knob, **on** by default. A measured
   net-win gate only specializes a component when that strictly shrinks the whole
   program, so monomorphization **never bloats**: whatever the knobs are set to,

package/dist/analyze.d.ts

@@ -1,191 +1,16 @@
-import { type AnyNode, type Parse, type ParseCache, type Root } from './parse.js';
-import { type AnalyzeInput, type ComponentId, type ComponentPlan, type Literal } from './ir.js';
-import { type Span } from './dead.js';
-export type Resolve = (source: string, importer: ComponentId) => Promise<ComponentId | null> | ComponentId | null;
-export type ReadFile = (id: ComponentId) => Promise<string> | string;
-/** Synchronous variants of {@link Resolve}/{@link ReadFile} for callers that
- * cannot await — e.g. an ESLint rule, which runs synchronously. Used by
- * {@link buildAnalyzeInputSync}. */
-export type ResolveSync = (source: string, importer: ComponentId) => ComponentId | null;
-export type ReadFileSync = (id: ComponentId) => string;
-/**
- * The set of input names a child component can ever OBSERVE at runtime (docs
- * §PR4 reverse analysis).  In runes there is no `$$props`/`$$restProps`, so a
- * component reads an input only through its `$props()` destructure:
- *  - `{ kind: 'names' }` — a clean, rest-free ObjectPattern `$props()` (or no
- *    `$props()` at all, giving the empty set): the child can observe EXACTLY
- *    these declared external names, so a call-site input NOT in the set can
- *    never be seen and is safe to drop;
- *  - `{ kind: 'all' }` — anything we cannot pin down: a `...rest` (captures
- *    undeclared inputs), an Identifier/Array binding (`let p = $props()`),
- *    more than one `$props()` call, `$props()` outside a `let <pat> = …`
- *    declarator, or a component that observes slotted content outside `$props()`
- *    — a legacy `<slot>` element or a `$$slots` read (both legal in runes mode).
- *    Then any input might be observed, so nothing is dropped.
- */
-export type ReachableInputs = {
-    kind: 'all';
-} | {
-    kind: 'names';
-    names: Set<string>;
-};
-/** One declared prop in a `$props()` destructuring. */
-export interface PropDecl {
-    /** The EXTERNAL prop name — the destructure KEY (`prop` in `prop: alias`).
-     * Call sites pass this name, so value sets / dropping key off it. */
-    name: string;
-    /**
-     * The LOCAL binding name the entry introduces in the body — the destructure
-     * VALUE (`alias` in `prop: alias`, or the bare name for a shorthand `prop`),
-     * or `null` when the entry binds a NESTED pattern (`prop: { x }`) rather than a
-     * single identifier.  Body and template references use THIS name, not {@link
-     * name}, so folding/substitution must look props up by it (`prop` and its alias
-     * `alias` can even be different entities — e.g. a same-named import).  A `null`
-     * local is never foldable: there is no single identifier to substitute or drop.
-     */
-    local: string | null;
-    /** The `Property` node inside the `ObjectPattern` (for surgical removal). */
-    property: AnyNode;
-    /** Default value expression, if `name = <default>`. */
-    defaultExpr?: AnyNode | undefined;
-}
-/** Everything we learn from parsing one component, reused by the transform. */
-export interface FileModel {
-    id: ComponentId;
-    code: string;
-    ast: Root;
-    /**
-     * Tag name a call site renders -> resolved child component id.  Holds every
-     * attributable edge into this file: a bare local for a direct `.svelte`
-     * default or a simple barrel/named import (`Sub`), and a dotted member for a
-     * namespace render (`ns.Sub`).  {@link collectChildCalls} keys `<Tag .../>`
-     * sites off this map, so every kind feeds the child's value set.
-     */
-    imports: Map<string, ComponentId>;
-    /** Declared props, or `null` if the component has no `$props()` pattern. */
-    props: PropDecl[] | null;
-    /** The `let { ... } = $props()` declaration + its pattern, for editing. */
-    propsDeclaration?: AnyNode | undefined;
-    propsPattern?: AnyNode | undefined;
-    hasRestProp: boolean;
-    /**
-     * The inputs this component can observe (docs §PR4).  Drives the reverse pass:
-     * a call site of THIS component may drop an input outside {@link
-     * ReachableInputs}.  Computed syntactically from the `$props()` shape.
-     */
-    reachableInputs: ReachableInputs;
-    /**
-     * EXTERNAL names of props this component DECLARES but never READS (docs §PR7):
-     * destructured out of a clean `$props()` yet with zero value-position reference
-     * to their local binding anywhere in the instance script or template.  Such a
-     * prop is invisible to the child, so its call-site attribute is dead and — when
-     * safe — the declaration can be dropped.  Source-only (independent of the call
-     * sites), so it is computed ONCE here, never inside the fixpoint; the transform
-     * gates its use on the component's plan not being bailed.
-     */
-    unreadDeclaredProps: Set<string>;
-    /**
-     * Every `<Child .../>` instance THIS component renders, with the child it
-     * resolves to and the AST node (so the fixpoint can test whether the site
-     * falls inside a dead `{#if}` span of this component — docs §2.1).
-     */
-    childCalls: ChildCall[];
-    /**
-     * Names this component binds OUTSIDE the `$props()` pattern — local `let` /
-     * `function` declarations in the instance script, and every template-scope
-     * binder (`{#each … as ctx, i}`, destructure patterns, `{#snippet name(p)}`,
-     * `{#await … then v}` / `{:catch e}`, `let:` directives).  A declared prop
-     * whose name collides with any of these is a DIFFERENT entity inside that
-     * scope, so folding/substituting/dropping it would corrupt the binding (and
-     * often produce invalid Svelte).  We therefore never fold such a prop.
-     */
-    shadowedNames: Set<string>;
-    /**
-     * Names that appear as a `{@debug …}` argument.  Svelte requires those to be
-     * bare identifiers, so substituting a folded literal there is invalid and
-     * dropping the prop dangles the reference — we never fold a prop named here.
-     */
-    debugNames: Set<string>;
-    /**
-     * Names the component WRITES TO — reassigns (`p = …`, `p += …`), mutates with
-     * `++`/`--`, destructure-assigns (`({ p } = obj)`), or two-way `bind:`s.  A
-     * written prop is not a constant even when every call site passes the same
-     * literal: the write changes it at runtime, so folding it would substitute the
-     * literal into the write's target (`"a" = …`, `0++`, `bind:value={"a"}`) —
-     * invalid Svelte — and, more importantly, silently change what renders after
-     * the write.  We never fold such a prop, exactly like a shadowed one.
-     */
-    writtenNames: Set<string>;
-    /**
-     * Owner-local bindings that are provably a single primitive CONSTANT, keyed by
-     * the LOCAL name a forwarded call-site expression references (docs §13.1
-     * interprocedural pass-through).  Merged into the owner's fold env so that
-     * `<Child {count}/>` — where `count` is an unmutated `let count = $state(0)` or
-     * a `const count = 0` — folds in the child exactly as a call-site literal would,
-     * feeding BOTH constant fold and value-set narrowing.  A static property of the
-     * source (independent of the fixpoint's plans), so it is computed ONCE here.
-     * See {@link computeScriptConstEnv} for the (conservative) admission rules.
-     */
-    scriptConstEnv: ReadonlyMap<string, Literal>;
-    /**
-     * Resolved ids of CHILD components this file leaks as a value (escape, docs
-     * §4.1) — e.g. `<svelte:component this={Child}>`.  `analyze` unions these
-     * across the program and bails every escaped component completely, since its
-     * prop profile can no longer be observed from `<Child .../>` sites alone.
-     */
-    escapedComponents: Set<ComponentId>;
-    /** Reasons this whole component must be left untouched. */
-    bailReasons: string[];
-}
-/** One `<Child .../>` instance rendered by a component. */
-export interface ChildCall {
-    childId: ComponentId;
-    node: AnyNode;
-}
 /**
- * One value passed explicitly to a prop at one call site, after last-write-wins
- * has been resolved.  An explicit write is either a real attribute (`a={1}`) OR a
- * key expanded out of a statically-known object-literal spread (`{...{a:1}}`,
- * docs §4.1) — both name a prop and a value the same way.  `dynamic` means the
- * value is non-literal (`bind:`, a dynamic expression, or a spread key whose
- * value is non-literal): used, value not statically known.  `afterLastSpread`
- * records whether this write happened after the site's last *unknown* spread (one
- * we could not expand) — only then can no spread silently override it (docs §4.1,
- * "後勝ち順序で救う").  A known object-literal spread is expanded, not opaque, so
- * it never counts as an "unknown spread" here.
+ * Whole-program fixpoint core (docs ARCHITECTURE §2.1): build a model per file, then
+ * alternate collecting live call-site usage and recomputing plans until they stop
+ * changing. The environment-free engine entry ({@link analyzeInput}) and the
+ * lint-oriented {@link findNeverPassedProps} live here; resolution/IO is
+ * {@link buildAnalyzeInput} (crawl.ts), per-file facts are model.ts, call-site
+ * reading is call-site.ts.
  */
-export interface ExplicitProp {
-    value: Literal;
-    dynamic: boolean;
-    afterLastSpread: boolean;
-    /**
-     * For a `dynamic` write whose value is a single expression (`prop={expr}`, or a
-     * known-spread key `{...{prop: expr}}`), the raw expression node — kept so the
-     * fixpoint can try to fold it against the OWNING component's constFold env
-     * (interprocedural pass-through, docs §13.1).  Absent for a literal write, a
-     * `bind:` (a two-way write that must never fold), or a multi-part value.
-     */
-    expr?: AnyNode | undefined;
-}
-/** How a child component is called at one `<Child .../>` site. */
-export interface CallSite {
-    /**
-     * Did this site have at least one spread we could NOT statically expand (an
-     * identifier / call / `{...{…computed/nested…}}`)?  A fully-known object-literal
-     * spread is expanded into {@link ExplicitProp} writes instead, so it does not
-     * set this — only an opaque spread, which may set any prop, does (docs §4.1).
-     */
-    hadSpread: boolean;
-    /** Last-write-wins explicit props at this site, keyed by prop name. */
-    explicit: Map<string, ExplicitProp>;
-    /**
-     * The component that OWNS this call site (renders the `<Child .../>`).  The
-     * fixpoint uses it to evaluate a forwarded expression (`prop={ownerProp}`)
-     * against the owner's fold env — interprocedural pass-through (docs §13.1).
-     * `undefined` for callers that read a site outside the graph fixpoint (mono).
-     */
-    owner?: ComponentId | undefined;
-}
+import { type ParseCache } from './parse.js';
+import { type AnalyzeInput, type ComponentId, type ComponentPlan } from './ir.js';
+import { type Span } from './dead.js';
+import { type FileModel } from './model.js';
+import { type ReadFile, type Resolve } from './crawl.js';
 export interface AnalyzeResult {
     models: Map<ComponentId, FileModel>;
     plans: Map<ComponentId, ComponentPlan>;
@@ -224,45 +49,6 @@ export declare function analyzeInput(input: AnalyzeInput, parseCache?: ParseCach
  * stamping `forceBail` onto the models.
  */
 export declare function planFixpoint(models: Map<ComponentId, FileModel>): Map<ComponentId, ComponentPlan>;
-/**
- * The Shell-side resolution + IO layer (docs/RUST-MIGRATION.md §2.1): BFS-crawl
- * the component graph from `entries`, resolving every import edge and reading
- * every reachable `.svelte` file up front, into a batched {@link AnalyzeInput}.
- *
- * This is the half that STAYS in JS — it owns `this.resolve` / file IO for Vite
- * ecosystem compat (docs ARCHITECTURE §5/§9) — so the engine ({@link
- * analyzeInput}) consumes its output with no callback across the boundary.  The
- * traversal mirrors the old crawl exactly: direct default-`.svelte` children and
- * the barrel children a file actually RENDERS are followed (an unrendered barrel
- * import is never crawled — its `<Comp/>` site cannot exist, so it cannot taint a
- * value set), keeping the produced model set — and thus the output — identical.
- */
-/**
- * The three per-file facts the crawl needs to resolve edges — import specifiers,
- * rendered `<Local>` tag names, and `<ns.X>` member tag names. `null` when the file
- * has no instance script (nothing to attribute), matching the crawl's skip.
- */
-export interface CrawlFacts {
-    imports: ImportInfo[];
-    renderedTags: Set<string>;
-    memberTags: Set<string>;
-}
-/**
- * Source of {@link CrawlFacts} for one `(id, code)`. The default is a JS parse +
- * extraction ({@link jsCrawlFacts}); the native engine passes a provider backed by
- * `ShakeSession` facts, so the crawl resolves the SAME edges without the JS parse.
- */
-export type FactsProvider = (id: ComponentId, code: string) => CrawlFacts | null;
-/** The default facts provider: parse (svelte/compiler or rsvelte) and extract. */
-export declare function jsCrawlFacts(id: ComponentId, code: string, parseCache?: ParseCache, parse?: Parse): CrawlFacts | null;
-export declare function buildAnalyzeInput(entries: ComponentId | ComponentId[], resolve: Resolve, readFile: ReadFile, parseCache?: ParseCache, parse?: Parse, escaped?: ComponentId[], factsProvider?: FactsProvider): Promise<AnalyzeInput>;
-/**
- * Synchronous twin of {@link buildAnalyzeInput} for callers that cannot await
- * (an ESLint rule runs synchronously). Byte-for-byte the same crawl with sync
- * `resolve`/`readFile`; the `tests/build-analyze-input-sync` differential test
- * pins it identical to the async path, so keep the two bodies in lockstep.
- */
-export declare function buildAnalyzeInputSync(entries: ComponentId | ComponentId[], resolve: ResolveSync, readFile: ReadFileSync, parseCache?: ParseCache, parse?: Parse, escaped?: ComponentId[], factsProvider?: FactsProvider): AnalyzeInput;
 /**
  * Dead `{#if}` spans per component implied by `plans`, via the SAME shared
  * predicate the transform uses ({@link computeDeadSpans}).  A bailed component
@@ -317,34 +103,6 @@ export declare function findNeverPassedProps(input: AnalyzeInput): Map<Component
  * maps cleanly; an external name with no matching declared local is dropped.
  */
 export declare function remapToLocalNames<V>(map: Map<string, V>, model: FileModel): Map<string, V>;
-/**
- * The bare component tag names this file RENDERS (`<Local/>`, excluding dotted
- * `<ns.X/>` member tags). The Shell crawl uses this to resolve a barrel (a
- * `.js`/`.ts` re-export, which costs a module read+parse) only for named imports
- * actually rendered as a component — a value-only named import (a helper / type)
- * is never a `<Local>` call site, so following it would read+parse a module for
- * nothing. Skipping it only ever drops a non-call-site, so attribution (and the
- * resulting models) are unchanged.
- */
-export declare function renderedComponentTagNames(ast: Root): Set<string>;
-/**
- * Every dotted component tag a file renders (`<ns.Child/>` -> `"ns.Child"`).  The
- * Shell resolves each through its namespace import's barrel; bare `<Child/>` tags
- * have no dot and are bound by the plain import maps instead.
- */
-export declare function memberComponentTags(ast: Root): Set<string>;
-/**
- * Read one `<Child .../>` into a {@link CallSite}.  Attributes are in source
- * order, so we resolve last-write-wins (a later `a={…}` overrides an earlier
- * one) and record, per prop, whether its winning write came *after* the last
- * *unknown* spread — the only case a spread cannot silently override it (docs
- * §4.1).  A statically-known object-literal spread (`{...{a:1, b:2}}`) is not
- * opaque: we expand its keys into explicit writes at the spread's position, so it
- * both contributes those literals AND does not poison props it cannot set (docs
- * §4.1, "{...obj} が object literal ならキー展開").
- */
-export declare function readCallSite(component: AnyNode, owner?: ComponentId): CallSite;
-/** Decide what to fold for one component from its global usage. */
 /**
  * Whether a declared prop name is unsafe to fold/narrow/drop because it is also
  * bound elsewhere: shadowed by a local `let`/`function` or a template binder
@@ -357,11 +115,3 @@ export declare function readCallSite(component: AnyNode, owner?: ComponentId): C
  * monomorphization specialization (mono.ts) must honor this identically.
  */
 export declare function isFoldBlockedName(model: FileModel, name: string): boolean;
-export interface ImportInfo {
-    value: string;
-    local: string;
-    /** `default` for a default import, the exported name for a named import, or
-     * `*` for a namespace import. */
-    imported: string;
-}
-export declare function importSources(instance: AnyNode): Generator<ImportInfo>;