sveast 0.6.0 → 0.8.0

package/README.md

@@ -1,8 +1,10 @@
 # sveast
 
-> Zero-dependency Svelte 5 parser. svelte/compiler's exact AST, 2× faster.
+> Zero-dependency Svelte 5 parser: svelte/compiler's AST, 2.4× faster.
 
-Parse `.svelte` components, including `<script lang="ts">`, into the same AST, and the same errors, as `svelte/compiler`'s `parse(source, { modern: true })`. sveast bundles acorn and its own TypeScript plugin, so it has no dependencies, and it runs anywhere: no Node APIs.
+Parse `.svelte` components, including `<script lang="ts">`, into the same AST, and the same errors, as `svelte/compiler`'s `parse(source, { modern: true })`. sveast has no dependencies and uses no Node APIs, so it runs in the browser as well as in Node, Bun and Deno.
+
+It's for tools that analyze components statically, such as documentation and type generators that read a component's props, events and slots. They need only the AST, but parse every component in a library, often on every change. [sveld](https://github.com/carbon-design-system/sveld), which generates TypeScript definitions and documentation for Svelte components, uses it.
 
 ```sh
 bun i sveast
@@ -17,6 +19,21 @@ ast.instance?.content.body; // [VariableDeclaration]
 ast.fragment.nodes; // [Text, RegularElement]
 ```
 
+| Function | For | Import from |
+|:---|:---|:---|
+| [`parse`](#parsesource-options--astroot) | A component's AST, the same as svelte's | `sveast` |
+| [`parseSections`](#parsesectionssource-options--astroot) | A component's AST without the markup: its `<script>`s, `<style>` and `<svelte:options>` | `sveast` |
+| [`parseModule`](#parsemodulesource-options--program) | A `.js` or `.ts` module's AST, the same as a component's `<script>` | `sveast` |
+| [`parseImportsExports`](#parseimportsexportssource-options--moduledeclaration) | A module's `import` and `export` statements, without parsing the rest | `sveast` |
+| [`lexImportsExports`](#leximportsexportssource--lexedstatement) | Their offsets, sources and names, without loading a parser | `sveast/lexer` |
+| [`lexComponent`](#lexcomponentsource--lexedcomponent) | A component's `<script>`s, `<style>` and `<svelte:options>`, with their attributes and offsets, without loading a parser | `sveast/lexer` |
+| [`createParser`, `createModuleParser`](#smaller-bundles-sveastcore-and-sveastmodule) | The parsers without TypeScript, named HTML entities or the template parser, for a smaller bundle | `sveast/core`, `sveast/module` |
+| [`isValidType`](#isvalidtypetext-options--boolean) | Whether a JSDoc type is safe to copy into a `.d.ts` | `sveast` |
+| [`isRunesMode`](#isrunesmodesource--boolean) | Whether svelte compiles a component in runes mode, mostly without parsing it | `sveast` |
+| [`walk`, `visitorKeys`, `markupVisitorKeys`](#walknode-visitor-keys--void) | Visit, skip, stop at or replace nodes, in the whole AST or only the markup | `sveast`, `sveast/walk` |
+| [`isReference`](#isreferencenode-parent--boolean), [`extractIdentifiers`](#extractidentifierspattern--identifier) | Which identifiers are references, and which ones a pattern declares | `sveast`, `sveast/walk` |
+| [`createLocator`](#createlocatorsource--offset--position) | Lines and columns for the nodes you report, without parsing with `loc` | `sveast`, `sveast/walk` |
+
 ## Migrating from svelte/compiler
 
 sveast is a drop-in for `parse` in most tools: change the import, and pass `loc: true` if you read line and column numbers.
@@ -34,41 +51,105 @@ sveast is a drop-in for `parse` in most tools: change the import, and pass `loc:
 | `loc`, `name_loc` | Always | With `loc: true`; otherwise only `start`/`end` offsets, for a faster parse and a smaller AST |
 | Errors | `CompileError` | `ParseError`: same `code`, `message`, `position`, `start`, `end` and `frame`; no `filename`; `reason`, the message without its link |
 | AST formats | Modern, legacy (`modern: false`), error-tolerant (`loose`) | Modern |
-| Scope | Parsing, `parseCss`, analysis, compilation | Parsing (`parse`, `parseModule`, `parseImportsExports`, `isValidType`), walking the AST (`walk`, `visitorKeys`), and finding references and bindings (`isReference`, `extractIdentifiers`) |
-| Non-ASCII identifiers | acorn's tables, Unicode 17 | The engine's own Unicode data, which is smaller to ship: the same as acorn's in Node 24 and Bun; an engine on another Unicode version differs on the letters added in between |
-| TypeScript-only errors | Reported, e.g. modifier order or initializers in ambient contexts | Not reported: 108 of the 2,449 TypeScript conformance tests acorn-typescript rejects still parse |
+| Non-ASCII identifiers | Its own Unicode 17 tables | The JavaScript engine's Unicode data, which is smaller to ship: the same in Node 24 and Bun; an engine on another Unicode version differs on the letters added in between |
+| TypeScript-only errors | Reported, e.g. modifier order or initializers in ambient contexts | Not reported: code that only TypeScript's own checks reject still parses |
+
+## Examples
+
+**List the components a file renders**, e.g. to build a dependency graph:
+
+```ts
+import { parse, walk } from "sveast";
+
+function componentsUsed(source: string): string[] {
+  const names = new Set<string>();
+  walk(parse(source, { css: false }).fragment, {
+    enter(node) {
+      if (node.type === "Component") names.add(node.name);
+    },
+  });
+  return [...names]; // ["Button", "Modal.Root"]
+}
+```
+
+**Report syntax errors**, e.g. in a pre-commit check, with svelte's own messages:
+
+```ts
+import { ParseError, parse } from "sveast";
+
+try {
+  parse(source, { css: false });
+} catch (error) {
+  if (!(error instanceof ParseError)) throw error;
+  console.error(`${file}:${error.start?.line}:${error.start?.column} ${error.code}\n${error.frame}`);
+}
+```
+
+[`examples/`](examples) has runnable versions of these and more, each a CLI you can point at your own components: a module graph, unused imports and variables, unused CSS classes, runes-or-legacy detection, `$props()` and their defaults, `.d.ts` props from JSDoc, and styles without parsing them.
+
+## Parity and performance
+
+- **svelte/compiler parity.** Tested on over 12,000 components: carbon-components-svelte, svelte's own test suite, bits-ui, shadcn-svelte, skeleton, flowbite-svelte, svelte.dev, immich, SvelteKit, melt-ui, layerchart and paneforge. Every one either parses to svelte's AST, `loc` included, or throws svelte's error with the same code, message, position and frame. A differential fuzzer compares the two parsers on mutated components.
+- **TypeScript.** `<script lang="ts">` and `.ts` modules parse to svelte's AST, key order and `loc` included, on 6,604 real-world modules and on all but 2 of the 9,586 TypeScript conformance tests svelte parses.
+- **About 2.4× faster** than svelte/compiler, and its ASTs retain about half the memory.
+- **A smaller bundle and a faster load:** `parse` is less than half of svelte/compiler's size, and a fresh process imports it in about 5 ms against 45 ms.
+
+Apple M2, medians of warm calls. The corpus is `tests/corpus`: all of carbon-components-svelte plus svelte's and sveld's test inputs.
+
+| Input | sveast | sveast, `loc: true` | svelte/compiler |
+|:---|:---|:---|:---|
+| Corpus, 400 components, 1.5 MB | **64.7 ms** | 84.0 ms | 155 ms (2.4×) |
+| Carbon's 5 largest components, 318 kB | **13.8 ms** | | 31.3 ms (2.3×) |
+| `lang="ts"` components, 22 files | **0.79 ms** | | 2.40 ms (3.0×) |
+
+| `parse` alone, minified for the browser | Gzipped |
+|:---|:---|
+| svelte/compiler | 126.7 kB |
+| sveast | **58.5 kB** |
+| `sveast/core`'s `createParser()`, without TypeScript and named HTML entities | **41.0 kB** |
+
+In a fresh process, importing the parser takes 5.3 ms with sveast and 44.7 ms with `svelte/compiler`, and a first parse of the whole corpus takes 65 ms against 161 ms. Keeping ten parses of the corpus alive retains 154 MB with sveast, 268 MB with `loc: true`, and 293 MB with `svelte/compiler`.
 
 ## API
 
 ### `parse(source, options?) => AST.Root`
 
-| Option | Description |
-|:---|:---|
-| `loc` | Add `loc` (line and column) to script and expression nodes, and `name_loc` to elements, attributes and directives, as svelte does. Default `false`: they cost time and memory, and most tools only need `start`/`end`. |
-| `css` | Parse `<style>` into rules and selectors. With `false`, `css` keeps its `start`, `end` and `content`, but `children` and `comments` are empty and CSS syntax errors aren't reported. Default `true`. |
-| `script` | Parse each `<script>`'s JavaScript or TypeScript. With `false`, `instance` and `module` keep their attributes, `start` and `end`, and `content` is a `Program` with its `start` and `end` but an empty `body`; the scripts' comments aren't in `comments`, and their syntax errors aren't reported. Expressions in the markup are still parsed. For a pass that only reads the markup, such as collecting which components a file renders and with what props; on the benchmark corpus, it parses 3.4× faster. Default `true`. |
-| `comments` | Collect JavaScript comments, in scripts, expressions and tags. With `false`, `comments` is empty and no node has `leadingComments` or `trailingComments`, including the HTML comment before a `<script>` that svelte copies into its `content.leadingComments`. HTML comments in the markup and CSS comments are kept. For tools that never read comments; on Carbon's components, it parses 3 to 6% faster and the ASTs take 8% less memory. Default `true`. |
+| Option | Default | Description |
+|:---|:---|:---|
+| `loc` | `false` | Add `loc` (line and column) to script and expression nodes, and `name_loc` to elements, attributes and directives, as svelte does. They cost time and memory, and most tools only need `start`/`end`. |
+| `css` | `true` | Parse `<style>` into rules and selectors. With `false`, `css` keeps its `start`, `end` and `content`, but `children` and `comments` are empty and CSS syntax errors aren't reported. It also keeps `<style lang="scss">` from failing to parse as CSS. |
+| `script` | `true` | Parse each `<script>`. With `false`, `instance` and `module` keep their attributes, `start` and `end`, and `content` is a `Program` with an empty `body`; their comments aren't collected and their syntax errors aren't reported. Expressions in the markup are still parsed. For a pass that only reads the markup; 3.4× faster on the benchmark corpus. |
+| `comments` | `true` | Collect JavaScript comments, in scripts, expressions and tags. With `false`, `comments` is empty and no node has `leadingComments` or `trailingComments`, including the HTML comment before a `<script>` that svelte copies into its `content.leadingComments`. HTML and CSS comments are kept. 3 to 6% faster, and 8% less memory. |
 
 With `loc: true`, the result equals svelte's. With the defaults, it's svelte's without `loc` and `name_loc`.
 
-A syntax error throws a `ParseError` with svelte's `code` (e.g. `"block_unclosed"`), `message`, `position` (`[start, end]` offsets), `start`/`end` (`{ line, column, character }`) and `frame` (the source around the error). `message` is always the reason, a line break, then the link to the error's docs, `https://svelte.dev/e/${code}`. `reason` has the reason on its own, e.g. `"Unexpected token"`.
+A syntax error throws a `ParseError` with svelte's `code` (e.g. `"block_unclosed"`), `message`, `position` (`[start, end]` offsets), `start`/`end` (`{ line, column, character }`) and `frame` (the source around the error). `message` is always the reason, a line break, then the link to the error's docs, `https://svelte.dev/e/${code}`; `reason` is the reason on its own, e.g. `"Unexpected token"`.
+
+### `parseSections(source, options?) => AST.Root`
+
+`parse` for a pass that only reads a component's scripts, such as its props or its module script's exports: the top-level `<script>`s, `<style>` and `<svelte:options>` are parsed as `parse` parses them, and the markup between them is skipped as [`lexComponent`](#lexcomponentsource--lexedcomponent) skips it. `fragment.nodes` is empty, `comments` has only the scripts' comments, and the markup's syntax errors aren't reported; the rest is `parse`'s, offsets and the HTML comment before a `<script>` included. It takes `parse`'s options, and on the benchmark corpus it's 1.5× faster, where most of what's left is the scripts. It's a function of its own so that a bundle with only `parse` doesn't carry the lexer; `createParser` doesn't return it.
+
+```ts
+import { parseSections } from "sveast";
+
+const { instance, module } = parseSections(source, { css: false });
+module?.content.body; // the module script's statements, with parse's offsets
+```
 
 ### `parseModule(source, options?) => Program`
 
-Parses a JavaScript or TypeScript module, such as a `.ts` file a component imports, the way a component's `<script>` is parsed: estree plus TypeScript nodes, with comments attached as `leadingComments`/`trailingComments`. Options: `typescript` and `loc`, both default `false`, and `comments`, default `true`; with `false`, no node has `leadingComments` or `trailingComments`.
+Parses a JavaScript or TypeScript module, such as a `.ts` file a component imports, into the same AST a component's `<script>` gets, with comments attached as `leadingComments`/`trailingComments`. Options: `typescript` and `loc`, default `false`, and `comments`, default `true`.
 
 ### `parseImportsExports(source, options?) => ModuleDeclaration[]`
 
-A module's top-level `import` and `export` statements, without parsing the rest, e.g. to rewrite a component's imports or follow a module graph. Each node is the one `parseModule(source, { comments: false })` has for that statement, so `start`, `end`, `specifiers` (with `imported`, `local` and `importKind`) and `source` are all there: `ImportDeclaration`, `ExportNamedDeclaration`, `ExportDefaultDeclaration` and `ExportAllDeclaration`, and, in TypeScript, `TSImportEqualsDeclaration`, `TSExportAssignment` and `TSNamespaceExportDeclaration`. `import(...)` and `import.meta` are expressions, so they aren't returned. Unlike a regex, it never matches an `import` in a comment, a string, a template or a nested block such as `declare module "a" { ... }`.
-
-The rest is skipped by a tokenizer that only tracks strings, comments, templates, regular expressions and brackets, and only the statements it finds are parsed. A syntax error in one of them throws `parseModule`'s `ParseError`, including a name exported twice; errors elsewhere aren't reported.
+A module's top-level `import` and `export` statements, without parsing the rest, e.g. to rewrite a component's imports or follow a module graph. Each node is the one `parseModule(source, { comments: false })` has for that statement: `ImportDeclaration`, `ExportNamedDeclaration`, `ExportDefaultDeclaration` and `ExportAllDeclaration`, and, in TypeScript, `TSImportEqualsDeclaration`, `TSExportAssignment` and `TSNamespaceExportDeclaration`. `import(...)` and `import.meta` are expressions, so they aren't returned. Unlike a regex, it never matches an `import` in a comment, a string, a template or a nested block such as `declare module "a" { ... }`.
 
-| Option | Description |
-|:---|:---|
-| `typescript` | Parse TypeScript: `import type`, `export type`, `import a = require("a")`. Default `false`. |
-| `localExports` | Return the exports of the module's own bindings, such as `export let a`, `export function b() {}`, `export { c }` and `export default d`, which are parsed in full. With `false`, only imports and the exports that have a `from` (`export * from "e"`, `export { f } from "f"`, `export import`) are returned, and the rest is skipped. Default `true`. |
+It stops after the last `import` or `export` that could start a statement, so the code after a component's imports is never read: on Carbon's component scripts, it takes a third of `parseModule`'s time, and about a seventh with `localExports: false`. A syntax error in a statement it returns throws a `ParseError`, including a name exported twice; errors elsewhere aren't reported.
 
-On Carbon's 327 component scripts, mostly JSDoc-documented `export let` props, it takes 10.7 ms against `parseModule`'s 33.8 ms, and 4.5 ms with `localExports: false`; the largest script, 63 kB, takes 0.37 ms against 2.7 ms. It checks the TypeScript conformance tests, kit, immich and bits-ui against `parseModule`, with an `import` inserted after every top-level statement: the same nodes on all 24,354 modules.
+| Option | Default | Description |
+|:---|:---|:---|
+| `typescript` | `false` | Parse TypeScript: `import type`, `export type`, `import a = require("a")`. |
+| `localExports` | `true` | Return the exports of the module's own bindings, such as `export let a`, `export function b() {}`, `export { c }` and `export default d`, parsed in full. With `false`, only imports and the exports that have a `from` (`export * from "e"`, `export { f } from "f"`, `export import`) are returned. |
 
 ```ts
 import { parseImportsExports } from "sveast";
@@ -80,209 +161,183 @@ function dependencies(source: string, typescript = false): string[] {
 }
 ```
 
-### `createParser(support?) => { parse, parseModule, parseImportsExports }` from `sveast/core`
+### `lexImportsExports(source) => LexedStatement[]`
 
-`parse`, `parseModule` and `parseImportsExports` without the two parts most tools can do without: the TypeScript plugin and the table of HTML's named character references. Together they're about a third of a bundle: `parse` and `parseModule` from `sveast` minify to 57.3 kB gzipped, and from `createParser()` to 40.3 kB. Pass back the parts you need; with both, the parsers are the same as `sveast`'s.
+From `sveast/lexer`, and also `sveast`. A module's top-level `import` statements and `export … from` re-exports, read by hand instead of parsed, for a tool on a hot or eagerly loaded path, such as a preprocessor that rewrites a component's imports, that needs each statement's offsets, source and names, but not the AST. `sveast/lexer` loads no parser, so a fresh process imports it in 1.4 ms, and on Carbon's component scripts it takes 40% of the time `parseImportsExports` takes with `localExports: false`.
 
-```ts
-import { createParser } from "sveast/core";
-import { typescript } from "sveast/typescript";
+It finds the statements `parseImportsExports` returns with `localExports: false`, with the same offsets, sources and names. It doesn't check syntax and never throws: a statement it can't read, such as `import { a from "a"` or `import a = require("a")`, has `source: null` and no specifiers, and ends where it stopped reading. `import type` and `type` before a name are always read.
 
-const { parse, parseModule, parseImportsExports } = createParser({ typescript });
+```ts
+import { lexImportsExports } from "sveast/lexer";
+
+for (const statement of lexImportsExports(source)) {
+  statement.kind; // "import" | "export"
+  statement.start; // offset of `import` or `export`
+  statement.end; // after the `;`, or the last token without one
+  statement.source; // { value: "carbon-components-svelte", start, end } (quotes included), or null
+  statement.typeOnly; // `import type …` or `export type …`
+  statement.specifiers;
+  // import: { kind: "default" | "namespace" | "named", imported, local, typeOnly, start, end }
+  // export: { kind: "all" | "namespace" | "named", local, exported, typeOnly, start, end }
+}
 ```
 
-| Support | Without it |
-|:---|:---|
-| `typescript` from `sveast/typescript` (+8.8 kB gzipped) | A component with `<script lang="ts">`, or `parseModule` or `parseImportsExports` with `typescript: true`, throws an `Error`, not a `ParseError`: a missing import, not a syntax error, and never a JavaScript AST of TypeScript |
-| `entities` from `sveast/entities` (+10.0 kB gzipped) | Text and attribute values decode numeric references, such as `&#169;`, and `&amp;`, `&apos;`, `&gt;`, `&lt;` and `&quot;`, but leave other names, such as `&copy;`, as written, so `Text.data` differs from svelte's where the source uses them |
+| Specifier | `import` | `export … from` |
+|:---|:---|:---|
+| `a` in `import a` | `default`, `imported: "default"`, `local: "a"` | |
+| `* as a` | `namespace`, `imported: "*"`, `local: "a"` | `namespace`, `local: "*"`, `exported: "a"` |
+| `*` | | `all`, `local: "*"`, `exported: null` |
+| `b as c`, `"b-c" as d` | `named`, `imported: "b"`, `local: "c"` | `named`, `local: "b"`, `exported: "c"` |
 
-`sveast/core` also exports `ParseError`, the same class as `sveast`'s, and the types.
+Names are as the module sees them: escapes decoded, and a string name without its quotes. A specifier's `typeOnly` is also `true` in an `import type` or `export type`. Its `start` is that of `type` before the name, if any, and `end` is after the last name; for `export *`, after the `*`.
 
-### `isValidType(text, options?) => boolean`
+### `lexComponent(source) => LexedComponent`
 
-Whether `text` is exactly one TypeScript type, such as a JSDoc `{"sm" | "lg"}` a tool is about to copy into a `.d.ts`. The text is parsed as a type on its own, not wrapped in a statement, so a `;`, a line break or a `}` in it can't end the type and smuggle in a statement: `string; let x = 1` and `{ a: string } }` are `false`. Whitespace and comments around the type are allowed. Results aren't cached; memoize if you check the same text often.
+From `sveast/lexer`, and also `sveast`. A component's top-level `<script>`, `<script module>`, `<style>` and `<svelte:options>`, with their attributes and the offsets of their tags and content, found without parsing: e.g. to read a component's scripts and their imports, its language or its options, or to rewrite a script, on a path that can't afford a parser. On the benchmark corpus it's about 50× faster than `parse`.
 
-A `//` comment runs to the end of the line, so `string // the size` is a valid type but breaks `CustomEvent<${text}>`. Pass `inline: true` when the text goes before more code on the same line: it's then also `false` unless every `//` comment in the text ends with a line break. Block comments and `//` inside strings, as in `"http://a" | "https://b"`, are fine either way.
+It skips the markup by tracking only tags, attribute values, blocks, and the brackets, strings, comments and templates of each `{…}` expression, so a `<script>` in `<svelte:head>`, a block, an attribute, an expression or an HTML comment isn't one, and it stops after the last `<script`, `<style` or `<svelte:options`. Where `parse` accepts the component, the sections are its `instance`, `module`, `css` and `options`, with the same offsets, into the source without a leading byte order mark. It doesn't check syntax and never throws.
 
-### `walk(node, visitor) => void`
+```ts
+import { lexComponent } from "sveast/lexer";
+
+const { typescript, instance, module, css, options } = lexComponent(source);
+typescript; // whether `parse` reads it as TypeScript, decided by the first <script> with a lang
+instance?.content; // { start, end }: source.slice(start, end) is the script
+instance?.attributes; // [{ name: "lang", value: "ts", start, end }]
+module?.context; // "module"
+options?.attributes; // [{ name: "runes", value: "{true}", start, end }]
+```
 
-Visits `node` and every node under it, depth-first and in source order, calling `visitor.enter(node, parent, key, index)` before a node's children and `visitor.leave(node, parent, key, index)` after them. `parent[key]` is the node, or `parent[key][index]` when the field is an array; all three are `null` for the node you pass. Return `SKIP` from `enter` to skip the node's children; `leave` is still called, so a stack you push in `enter` and pop in `leave` stays balanced. Return `STOP` from `enter` or `leave` to end the walk there: no more `enter` or `leave` calls, not even `leave` on the node's ancestors, e.g. to find the first use of a rune. Return another node from `enter` to put it in this one's place: `walk` writes it to `parent[key]` (or `parent[key][index]`), then calls `enter` on it and visits its children instead, and `leave` gets the replacement. So `return node.expression` on each `TSAsExpression` strips `a as B as C` down to `a`, one layer per `enter`. The node you pass to `walk` can't be replaced. Any other return value, `false` included, is ignored, so an expression-bodied `enter: (node) => node.type === "Component" && names.add(node.name)` still visits every node. Checking `node.type` narrows `node`.
+An attribute's `value` is as written, without its quotes: character references aren't decoded, an expression keeps its braces, and an attribute without a value has `true`.
 
-It works on any node the parsers return: a component's `Root`, a `Fragment`, an expression, a `parseModule` program, a `<style>`'s rules. It only reads the fields that hold child nodes, so it never descends into `loc`, comments or strings, and it throws on a node type it doesn't know. Two exceptions to source order: a component's sections are visited in scope order, `module`, `instance`, `fragment`, then `css`; and a template literal's `quasis` come before its `expressions`. `Root.options` isn't a node, so `<svelte:options>`'s attributes aren't visited; read them from `ast.options?.attributes`. acorn shares one `Identifier` between both names of `import { a }`, so it's visited once as `imported` and once as `local`, and likewise as `local` and `exported` in `export { a }`.
+`typescript` is what `createParser` needs to know to load the TypeScript parser only for the components that use it:
 
-`visitorKeys` is the table `walk` reads: the fields of each node type that hold child nodes, in source order, e.g. `visitorKeys.IfBlock` is `["test", "consequent", "alternate"]`. Use it with another walker, or to write your own.
+```ts
+import { createParser } from "sveast/core";
+import { lexComponent } from "sveast/lexer";
 
-### `isReference(node, parent) => boolean`
+let parser = createParser();
+let loaded = false;
 
-Whether `node` is an `Identifier` that names a variable, function, class, import or other binding, where it's declared or where it's used, given the `parent` `walk` passes. It's the check svelte's analyzer makes, from the [`is-reference`](https://github.com/Rich-Harris/is-reference) package: `false` for a property or method name (`b` in `a.b`, `{ b: a }` and `class { b() {} }`, unless computed), the renamed side of an import or export (`b` in `import { b as a }` and `export { a as b }`), and labels. Unlike `is-reference`, it's also `false` for `import` and `new` in `import.meta` and `new.target`, an import attribute's key, and `b` in `export * as b from`, and for any node that isn't an `Identifier`.
+async function parseComponent(source: string) {
+  if (!loaded && lexComponent(source).typescript) {
+    const { typescript } = await import("sveast/typescript");
+    parser = createParser({ typescript });
+    loaded = true;
+  }
+  return parser.parse(source);
+}
+```
 
-TypeScript nodes hold types, so an `Identifier` whose parent is a TypeScript node isn't a reference (`B` in `let a: B`, `typeof b` in a type, interface and type alias names), except where it's a value: the expression of `as`, `satisfies`, `<T>a`, `a!`, `a<T>` and `export =`, an enum member's initializer, a parameter property (`a` in `constructor(private a)`), an enum's name, and the name and target of `import a = b`. Names of namespaces and of functions without a body (overloads, `declare function`) aren't references.
+### Smaller bundles: `sveast/core` and `sveast/module`
 
-acorn shares one `Identifier` between both names of `import { a }` and `export { a }`, and `walk` visits it twice, so it's a reference on both visits.
+`createParser(support?)` from `sveast/core` returns `parse`, `parseModule` and `parseImportsExports` without the TypeScript parser and the table of HTML's named character references, which most tools can do without. `createModuleParser(support?)` from `sveast/module` returns `parseModule` and `parseImportsExports` without the template parser either, for tools that read `.js` and `.ts` files but never components, such as a bundler plugin following a module graph. Pass back the parts you need; with them, the parsers are the same as `sveast`'s.
 
 ```ts
-import { isReference, parseModule, walk } from "sveast";
+import { createParser } from "sveast/core";
+import { typescript } from "sveast/typescript";
 
-const used = new Set<string>();
-walk(parseModule("const a = b.c({ d: e });"), {
-  enter(node, parent) {
-    if (node.type === "Identifier" && isReference(node, parent)) used.add(node.name);
-  },
-});
-used; // Set { "a", "b", "e" }
+const { parse, parseModule, parseImportsExports } = createParser({ typescript });
 ```
 
-### `extractIdentifiers(pattern) => Identifier[]`
+| Support | Without it |
+|:---|:---|
+| `typescript` from `sveast/typescript` | A component with `<script lang="ts">`, or `typescript: true`, throws an `Error`, not a `ParseError`: a missing import, not a syntax error, and never a JavaScript AST of TypeScript |
+| `entities` from `sveast/entities` (`createParser` only) | Numeric references, such as `&#169;`, and `&amp;`, `&apos;`, `&gt;`, `&lt;` and `&quot;` are decoded, but other names, such as `&copy;`, are left as written, so `Text.data` differs from svelte's where the source uses them |
 
-The `Identifier` nodes a pattern binds, in source order, as svelte's `extract_identifiers` returns them: `a`, `c`, `d`, `e` and `f` in `let { a, b: [c, ...d], e = 1, ...f } = x`. Property keys, defaults and type annotations aren't included. It returns nodes rather than names, so you keep their positions; `.map((node) => node.name)` for the names.
+Both also export `ParseError`, the same class as `sveast`'s, and the node types.
 
-It takes any binding or assignment target: a declarator's `id`, a function's params, including a parameter property (`a` in `constructor(private a)`), a catch clause's `param`, an each block's `context`, a snippet's `parameters`, or an assignment's `left`. A member expression binds nothing, so `[a.b, c] = x` yields only `c`, as in svelte. On an assignment's `left`, `a!`, `a as T`, `a satisfies T` and `<T>a` yield `a`.
+### `isValidType(text, options?) => boolean`
 
-```ts
-import { extractIdentifiers, parseModule } from "sveast";
+Whether `text` is exactly one TypeScript type, such as a JSDoc `{"sm" | "lg"}` a tool is about to copy into a `.d.ts`. The text is parsed as a type on its own, not wrapped in a statement, so a `;`, a line break or a `}` in it can't end the type and smuggle in a statement: `string; let x = 1` and `{ a: string } }` are `false`. Whitespace and comments around the type are allowed. Results aren't cached.
 
-const [declaration] = parseModule("let { a, b: [c] } = x;").body;
-if (declaration.type === "VariableDeclaration") {
-  declaration.declarations.flatMap((d) => extractIdentifiers(d.id)).map((node) => node.name); // ["a", "c"]
-}
-```
+A `//` comment runs to the end of the line, so `string // the size` is a valid type but breaks `CustomEvent<${text}>`. Pass `inline: true` when the text goes before more code on the same line: it's then also `false` unless every `//` comment in it ends with a line break.
 
-`walk`, `SKIP`, `STOP`, `visitorKeys`, `Visitor`, `isReference`, `extractIdentifiers` and the types are also exported from `sveast/walk`, which loads neither acorn nor the parser: for code that walks ASTs it gets from elsewhere, such as a cache, and must not pay for loading the parser. They're the same values as `sveast`'s.
+### `isRunesMode(source) => boolean`
 
-```ts
-import { STOP, walk } from "sveast/walk";
-```
+Whether svelte compiles the component in runes mode, as `compile(source).metadata.runes` says: by `<svelte:options runes>` if it has one, otherwise by whether it uses a rune, such as `$state` or `$props`, or `await` outside a function in its instance script or markup. A `$state` that subscribes to a store named `state`, or that a function declares, isn't a rune, as in svelte. E.g. to track a migration to Svelte 5, or to pick the rules a linter applies.
 
-### Types
+Most components are decided without parsing: `<svelte:options>` is read with `lexComponent`, a component without a rune's name or `await` isn't in runes mode, and one whose scripts call a rune in a way that can't be a declaration, a method, a type or a store is. The rest is parsed, without the markup unless a rune's name or `await` is in it, and a syntax error there throws a `ParseError`. On 12,808 components from other Svelte projects, it takes a twelfth of the time parsing them does.
 
-`AST` is svelte's `AST` namespace (`AST.Root`, `AST.RegularElement`, `AST.CSS.Rule`, ...), corrected to match what the parser returns: `name_loc` and a comment's `loc` are optional, `Root.instance`/`module` are absent rather than `null` when there's no such `<script>`, `Root.js` is declared, and every directive has `modifiers`. `ParseOptions`, `ParseModuleOptions` and `ParseImportsExportsOptions` are exported too.
+### `walk(node, visitor, keys?) => void`
 
-The estree node types are exported as well (`Program`, `Node`, `Statement`, `Expression`, `Identifier`, ...), so you don't need `@types/estree`. They're estree's, plus what the parser adds: `start`/`end` on every node, and the TypeScript plugin's nodes (`TSInterfaceDeclaration`, `TSTypeAnnotation`, `TSTypeReference`, ...; `TSNode` is their union) and fields (`typeAnnotation`, `typeParameters`, `typeArguments`, `returnType`, `importKind`/`exportKind`, ...). The TypeScript nodes are in the `Statement`, `Declaration` and `Expression` unions, so checking `node.type` narrows to them. Where the grammar only allows a string, such as an import's `source`, the type is `StringLiteral`, a `Literal` whose `value` is a `string`.
+Visits `node` and every node under it, depth-first and in source order, calling `visitor.enter(node, parent, key, index)` before a node's children and `visitor.leave(node, parent, key, index)` after them. `parent[key]` is the node, or `parent[key][index]` when the field is an array; all three are `null` for the node you pass. Checking `node.type` narrows `node`.
 
-```ts
-import { parseModule, type TSInterfaceDeclaration } from "sveast";
+What `enter` and `leave` return controls the walk:
 
-const interfaces: TSInterfaceDeclaration[] = [];
-for (const node of parseModule(source, { typescript: true }).body) {
-  if (node.type === "TSInterfaceDeclaration") interfaces.push(node);
-}
-```
+- **`SKIP`** from `enter` skips the node's children. `leave` is still called, so a stack you push in `enter` and pop in `leave` stays balanced.
+- **`STOP`** from `enter` or `leave` ends the walk there, without `leave` on the node's ancestors, e.g. to find the first use of a rune.
+- **A node** from `enter` replaces this one: `walk` writes it to `parent[key]` (or `parent[key][index]`), then enters it and visits its children instead, and `leave` gets the replacement. `return node.expression` on each `TSAsExpression` strips `a as B as C` down to `a`. The node you pass to `walk` can't be replaced.
+- **Anything else**, `false` included, is ignored, so `enter: (node) => node.type === "Component" && names.add(node.name)` still visits every node.
 
-## Recipes
+It works on any node the parsers return: a `Root`, a `Fragment`, an expression, a `Program`, a `<style>`'s rules. It never descends into `loc`, comments or strings, and throws on a node type it doesn't know. A component's sections are visited in scope order, `module`, `instance`, `fragment`, then `css`, and a template literal's `quasis` before its `expressions`. `<svelte:options>`'s attributes aren't visited; read them from `ast.options?.attributes`. In `import { a }` and `export { a }`, one `Identifier` is both names, so it's visited twice.
 
-**List the components a file renders**, e.g. to build a dependency graph:
+`visitorKeys` is the table `walk` reads: the fields of each node type that hold child nodes, in source order, e.g. `visitorKeys.IfBlock` is `["test", "consequent", "alternate"]`. Pass another table as `keys` to visit other fields; a node whose type it has no entry for throws. `markupVisitorKeys` visits only the markup: `Root`'s `fragment`, elements' attributes and fragments, attribute values and blocks' fragments, but no script, style or expression. For a query about the markup, such as the components a file renders or the classes it uses, it's 4.8× faster on the benchmark corpus than walking everything:
 
 ```ts
-import { parse, walk } from "sveast";
+import { markupVisitorKeys, walk } from "sveast";
 
-function componentsUsed(source: string): string[] {
-  const names = new Set<string>();
-  walk(parse(source, { css: false }).fragment, {
+walk(
+  ast,
+  {
     enter(node) {
       if (node.type === "Component") names.add(node.name);
     },
-  });
-  return [...names]; // ["Button", "Modal.Root"]
-}
+  },
+  markupVisitorKeys,
+);
 ```
 
-**Find the classes a component's styles declare but its markup never uses**, e.g. to report dead CSS. A `class={...}` expression is reported as `dynamic` rather than guessed at:
+`sveast/walk` exports `walk`, `SKIP`, `STOP`, `visitorKeys`, `markupVisitorKeys`, `isReference`, `extractIdentifiers`, `createLocator` and the types without loading a parser, for code that walks ASTs from elsewhere, such as a cache.
 
-```ts
-import { parse, walk } from "sveast";
+### `isReference(node, parent) => boolean`
 
-function unusedClasses(source: string): { unused: string[]; dynamic: boolean } {
-  const ast = parse(source);
-  const declared = new Set<string>();
-  const used = new Set<string>();
-  let dynamic = false;
-  if (ast.css) {
-    walk(ast.css, {
-      enter(node) {
-        if (node.type === "ClassSelector") declared.add(node.name);
-      },
-    });
-  }
-  walk(ast.fragment, {
-    enter(node) {
-      if (node.type === "ClassDirective") used.add(node.name);
-      if (node.type !== "Attribute" || node.name !== "class") return;
-      for (const part of node.value === true ? [] : [node.value].flat()) {
-        if (part.type === "ExpressionTag") dynamic = true;
-        else for (const name of part.data.split(/\s+/)) if (name) used.add(name);
-      }
-    },
-  });
-  return { unused: [...declared].filter((name) => !used.has(name)), dynamic };
-}
-```
+Whether `node` is an `Identifier` that names a variable, function, class, import or other binding, where it's declared or where it's used, given the `parent` `walk` passes. It's the check svelte's analyzer makes, from [`is-reference`](https://github.com/Rich-Harris/is-reference): `false` for a property or method name (`b` in `a.b`, `{ b: a }` and `class { b() {} }`, unless computed), the renamed side of an import or export (`b` in `import { b as a }` and `export { a as b }`), and labels. Unlike `is-reference`, it's also `false` for `import.meta` and `new.target`, an import attribute's key, and `b` in `export * as b from`.
 
-**Read the props a runes component declares:**
+In TypeScript, a name in a type isn't a reference (`B` in `let a: B`, interface and type alias names), but a value is: the expression of `as`, `satisfies`, `<T>a`, `a!`, `a<T>` and `export =`, an enum's name and member initializers, a parameter property (`a` in `constructor(private a)`), and both sides of `import a = b`. Names of namespaces and of functions without a body (overloads, `declare function`) aren't references.
 
 ```ts
-import { parse } from "sveast";
+import { isReference, parseModule, walk } from "sveast";
 
-function propNames(source: string): string[] {
-  for (const statement of parse(source).instance?.content.body ?? []) {
-    if (statement.type !== "VariableDeclaration") continue;
-    for (const { id, init } of statement.declarations) {
-      const isProps =
-        init?.type === "CallExpression" &&
-        init.callee.type === "Identifier" &&
-        init.callee.name === "$props";
-      if (isProps && id.type === "ObjectPattern") {
-        return id.properties.flatMap((p) =>
-          p.type === "Property" && p.key.type === "Identifier" ? [p.key.name] : [],
-        );
-      }
-    }
-  }
-  return [];
-}
+const used = new Set<string>();
+walk(parseModule("const a = b.c({ d: e });"), {
+  enter(node, parent) {
+    if (node.type === "Identifier" && isReference(node, parent)) used.add(node.name);
+  },
+});
+used; // Set { "a", "b", "e" }
 ```
 
-**Report syntax errors**, e.g. in a pre-commit check, with svelte's own messages:
+### `extractIdentifiers(pattern) => Identifier[]`
+
+The `Identifier` nodes a pattern binds, in source order, as svelte's `extract_identifiers` returns them: `a`, `c`, `d`, `e` and `f` in `let { a, b: [c, ...d], e = 1, ...f } = x`. Property keys, defaults and type annotations aren't included, and a member expression binds nothing, so `[a.b, c] = x` yields only `c`. It takes any binding or assignment target: a declarator's `id`, a function's params, including a parameter property, a catch clause's `param`, an each block's `context`, a snippet's `parameters`, or an assignment's `left`, where `a!`, `a as T`, `a satisfies T` and `<T>a` yield `a`.
 
 ```ts
-import { ParseError, parse } from "sveast";
+import { extractIdentifiers, parseModule } from "sveast";
 
-try {
-  parse(source, { css: false });
-} catch (error) {
-  if (!(error instanceof ParseError)) throw error;
-  console.error(`${file}:${error.start?.line}:${error.start?.column} ${error.code}\n${error.frame}`);
+const [declaration] = parseModule("let { a, b: [c] } = x;").body;
+if (declaration.type === "VariableDeclaration") {
+  declaration.declarations.flatMap((d) => extractIdentifiers(d.id)).map((node) => node.name); // ["a", "c"]
 }
 ```
 
-**Get a component's styles without parsing them:**
+### `createLocator(source) => (offset) => Position`
+
+A function from an offset to its `{ line, column }`, line from 1 and column from 0, as `loc: true` gives them: for a tool that parses without `loc`, which is faster, and needs lines only for what it reports. Lines are found on the first call, and each lookup starts its search at the line found last, so lookups in source order are fastest. Lines end at `\n`, as in the markup's `loc` and `ParseError`; acorn's `loc` in scripts and modules also ends them at a lone `\r`, U+2028 and U+2029. `parse` drops a leading byte order mark, so pass the source without one.
 
 ```ts
-import { parse } from "sveast";
+import { createLocator, parse, walk } from "sveast";
 
-const css = parse(source, { css: false }).css?.content.styles ?? "";
+const locate = createLocator(source);
+walk(parse(source), {
+  enter(node) {
+    if (node.type === "Component") console.log(node.name, locate(node.start).line);
+  },
+});
 ```
 
-## Features
-
-- **svelte/compiler parity.** Tested on over 12,000 components: carbon-components-svelte, svelte's own test suite, bits-ui, shadcn-svelte, skeleton, flowbite-svelte, svelte.dev, immich, SvelteKit, melt-ui, layerchart and paneforge. Every one either parses to svelte's AST, `loc` included, or throws svelte's error with the same code, message, position and frame. CI runs 442 of them, the smallest set that covers every parser line, AST shape and error code the full set does, and a differential fuzzer compares the two parsers on mutated components.
-- **TypeScript without acorn-typescript.** The built-in plugin produces the same AST as `@sveltejs/acorn-typescript`, key order and `loc` included, on 6,604 real-world modules and on all but 2 of the 9,586 TypeScript conformance tests that acorn-typescript parses. It rejects the same redeclarations, and supports decorators.
-- **About 2.4× faster than svelte/compiler** (2.2–3.0× depending on the input), and its ASTs retain 47% less memory without `loc`.
-- **Fast to load.** A fresh process imports sveast in about 5 ms, against about 45 ms for `svelte/compiler`.
-- **Zero dependencies,** types included. 67 kB gzipped, acorn included.
-
-## Benchmarks
-
-Apple M2, medians of warm calls. Each task parses every file in the set once. The corpus is `tests/corpus`: all of carbon-components-svelte plus svelte's and sveld's test inputs.
-
-| Input | sveast | sveast, `loc: true` | svelte/compiler |
-|:---|:---|:---|:---|
-| Corpus, 400 components, 1.5 MB | **64.7 ms** | 84.0 ms | 155 ms (2.4×) |
-| Carbon's 5 largest components, 318 kB | **13.8 ms** | | 31.3 ms (2.3×) |
-| `lang="ts"` components, 22 files | **0.79 ms** | | 2.40 ms (3.0×) |
+### Types
 
-| Input | sveast's TypeScript plugin | acorn-typescript |
-|:---|:---|:---|
-| Carbon's 98 `.d.ts` modules | **3.19 ms** | 8.07 ms (2.5×) |
-| The corpus's `lang="ts"` scripts on their own | **0.58 ms** | 1.29 ms (2.2×) |
+`AST` is svelte's `AST` namespace (`AST.Root`, `AST.RegularElement`, `AST.CSS.Rule`, ...), corrected to match what the parser returns: `name_loc` and a comment's `loc` are optional, `Root.instance`/`module` are absent rather than `null` when there's no such `<script>`, `Root.js` is declared, and every directive has `modifiers`. Each function's options and results are exported too, e.g. `ParseOptions` and `LexedStatement`.
 
-In a fresh process, importing the parser takes 5.3 ms with sveast and 44.7 ms with `svelte/compiler`, and a first parse of the whole corpus takes 65 ms against 161 ms. Keeping ten parses of the corpus alive retains 154 MB with sveast, 268 MB with `loc: true`, and 293 MB with `svelte/compiler`.
+The script's node types are exported as well (`Program`, `Node`, `Statement`, `Expression`, `Identifier`, ...), so you don't need a separate types package. They include `start`/`end` on every node, and the TypeScript nodes (`TSInterfaceDeclaration`, `TSTypeAnnotation`, ...; `TSNode` is their union) and fields (`typeAnnotation`, `typeParameters`, `returnType`, `importKind`, ...). The TypeScript nodes are in the `Statement`, `Declaration` and `Expression` unions, so checking `node.type` narrows to them. Where the grammar only allows a string, such as an import's `source`, the type is `StringLiteral`, a `Literal` whose `value` is a `string`.

package/core.d.ts

@@ -109,7 +109,7 @@ export interface ParseImportsExportsOptions {
     localExports?: boolean;
 }
 
-/** TypeScript support for {@link createParser}, from `sveast/typescript`. */
+/** TypeScript support for {@link createParser} and {@link createModuleParser}, from `sveast/typescript`. */
 export interface TypeScriptSupport {
     readonly support: "typescript";
 }

package/core.js

@@ -1 +1 @@
-import{m}from"./shared-rfyyd11j.js";import"./shared-f8ty80r9.js";import{e}from"./shared-3xek95jd.js";import{Ce}from"./shared-9f69x2q9.js";import{x}from"./shared-etx1q7m5.js";import{y}from"./shared-88pt6me6.js";import{Le,Ie}from"./shared-0ehch67h.js";function P(o={}){let p=Le(o.typescript),s={typescript:p,entityNames:Ie(o.entities)??Ce};return{parse:(t,r)=>m(t,r,s),parseModule:(t,r={})=>y(t,r,p),parseImportsExports:(t,r={})=>x(t,r,p)}}export{e as ParseError,P as createParser};
+import"./shared-2ahdjk78.js";import"./shared-e8rqjefv.js";import{e}from"./shared-j2msb2xj.js";import{O}from"./shared-657pk0sg.js";import{ue}from"./shared-j3kp940c.js";import"./shared-j60qxzy3.js";import{x}from"./shared-p0ybqcs7.js";import{g}from"./shared-918zqd7r.js";import{W,at}from"./shared-tscn5fn7.js";function u(o={}){let p=W(o.typescript),s={typescript:p,entityNames:at(o.entities)??ue};return{parse:(t,r)=>O(t,r,s),parseModule:(t,r={})=>x(t,r,p),parseImportsExports:(t,r={})=>g(t,r,p)}}export{e as ParseError,u as createParser};

package/entities.js

@@ -1 +1 @@
-import"./shared-9f69x2q9.js";import{k}from"./shared-y4gayx8p.js";import{Pe}from"./shared-0ehch67h.js";var p=Pe(k);export{p as entities};
+import"./shared-j3kp940c.js";import{y}from"./shared-e15f58b0.js";import{ot}from"./shared-tscn5fn7.js";var p=ot(y);export{p as entities};