sveast 0.1.0 → 0.3.0

package/README.md

@@ -32,9 +32,9 @@ sveast is a drop-in for `parse` in most tools: change the import, and pass `loc:
 | | svelte/compiler | sveast |
 |:---|:---|:---|
 | `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` |
+| 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`) |
+| Scope | Parsing, `parseCss`, analysis, compilation | Parsing (`parse`, `parseModule`, `isValidType`) |
 | 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 |
 
 ## API
@@ -48,15 +48,30 @@ sveast is a drop-in for `parse` in most tools: change the import, and pass `loc:
 
 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).
+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"`.
 
 ### `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`.
 
+### `isValidType(text) => boolean`
+
+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; a `//` comment runs to the end of the line, so check for one before embedding the text ahead of more code on the same line. Results aren't cached; memoize if you check the same text often.
+
 ### Types
 
-`AST` is svelte's `AST` namespace (`AST.Root`, `AST.RegularElement`, `AST.CSS.Rule`, ...), with `name_loc`, a comment's `loc`, and `Root.instance`/`module` made optional, since they can be absent. `ParseOptions` is exported too.
+`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` is exported too.
+
+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`.
+
+```ts
+import { parseModule, type TSInterfaceDeclaration } from "sveast";
+
+const interfaces: TSInterfaceDeclaration[] = [];
+for (const node of parseModule(source, { typescript: true }).body) {
+  if (node.type === "TSInterfaceDeclaration") interfaces.push(node);
+}
+```
 
 ## Recipes
 
@@ -67,11 +82,18 @@ import { parse } from "sveast";
 
 function componentsUsed(source: string): string[] {
   const names = new Set<string>();
-  const visit = (node: unknown): void => {
-    if (!node || typeof node !== "object") return;
-    const { type, name } = node as { type?: string; name?: string };
-    if (type === "Component" && name) names.add(name);
-    for (const child of Object.values(node)) visit(child);
+  const visit = (node: object): void => {
+    if (
+      "type" in node &&
+      node.type === "Component" &&
+      "name" in node &&
+      typeof node.name === "string"
+    ) {
+      names.add(node.name);
+    }
+    for (const child of Object.values(node)) {
+      if (typeof child === "object" && child !== null) visit(child);
+    }
   };
   visit(parse(source, { css: false }).fragment);
   return [...names]; // ["Button", "Modal.Root"]