svelte-docinfo 0.11.0 → 0.13.0

package/README.md

@@ -18,8 +18,8 @@ in the [npm package](https://www.npmjs.com/package/svelte-docinfo).
 npm i -D svelte-docinfo
 ```
 
-Peer dependencies: `svelte` 5+, `svelte2tsx`, `typescript` 5.9+ or 6, and `zod` 4+
-(npm 7+ installs them automatically), plus an optional `vite` 6+ for the Vite plugin.
+Peer dependencies: `svelte` 5+, `svelte2tsx`, and `typescript` 5.9+ or 6 (npm 7+
+installs them automatically), plus an optional `vite` 6+ for the Vite plugin.
 
 - [Quick start](#quick-start)
 - [Vite plugin](#vite-plugin)
@@ -186,6 +186,19 @@ All three produce the same JSON shape:
 }
 ```
 
+Defaulted fields are left out of the JSON: empty arrays and `false` flags. To restore them
+and validate the shape, parse it with `parseAnalyzeResult` (`parseModuleJson` for one module,
+`parseDiagnostics` for diagnostics alone):
+
+```ts
+import { parseAnalyzeResult } from 'svelte-docinfo';
+
+const { modules, diagnostics } = parseAnalyzeResult(JSON.parse(json));
+```
+
+The parse helpers are the stable entry point. The schemas behind them (`AnalyzeResultJson`,
+`ModuleJson`, `DeclarationJson`, …) are exported too, as [valibot](https://valibot.dev/) schemas.
+
 The [extraction demo](https://svelte-docinfo.fuz.dev/demo/extraction) has more examples,
 and see the docs for the complete [output format](https://svelte-docinfo.fuz.dev/docs/output-format).
 You may also want to browse the [test fixtures](https://github.com/fuzdev/svelte-docinfo/tree/main/src/test/fixtures).
@@ -232,6 +245,9 @@ Plugin options:
 | `resolveDependencies` | `true`                                               | Resolve import dependencies. When `false`, `dependencies`/`dependents` stay empty.                                                                                                                                     |
 | `hmrDebounceMs`       | `100`                                                | Dev re-analysis debounce delay in milliseconds.                                                                                                                                                                        |
 | `onDuplicates`        | —                                                    | Opt-in check that names are unique across modules, for packages with a flat export namespace: `'diagnostic'` \| `'warn'` \| `'throw'`. Off by default.                                                                |
+| `tsconfig`            | `'tsconfig.json'`                                    | Path to the tsconfig, relative to `projectRoot`, or `false` to analyze without one (built-in strict options, with `compilerOptions` merged on top). |
+| `compilerOptions`     | —                                                    | Compiler options merged over the tsconfig's, per key. |
+| `rootFileNames`       | the tsconfig's roots                                 | The program's root files in place of the tsconfig's: a list, or a function over the tsconfig's roots (`declarationFileRoots`, from `svelte-docinfo/typescript-program.js`, keeps the declaration files). Narrowing speeds up cold analysis; an ambient type declared in a dropped root resolves to `any`. |
 
 Source-scope notes (shared with the [CLI](#cli) and `analyzeFromFiles`):
 
@@ -281,6 +297,8 @@ All CLI options:
 | `--only <pattern>`          | Glob filter applied to module paths in output (repeatable). Full project is still analyzed (re-exports/dependents stay correct); diagnostics aren't filtered                                  |
 | `--no-resolve-dependencies` | Disable dependency resolution                                                                                                                                                                 |
 | `--pretty`                  | Pretty-print JSON output (default: compact)                                                                                                                                                   |
+| `--tsconfig <path>`         | Path to the tsconfig, relative to project root (default: `tsconfig.json`, searched upward from project root) |
+| `--no-tsconfig`             | Analyze without a tsconfig, using built-in strict compiler options |
 | `-q, --quiet`               | Suppress info messages on stderr (warnings and errors still print)                                                                                                                            |
 | `--on-duplicates <mode>`    | Opt-in check that names are unique across modules, for packages with a flat export namespace: `diagnostic` \| `warn` \| `throw` (default: off)                                                |
 | `-V, --version`             | Show version number                                                                                                                                                                           |
@@ -334,7 +352,7 @@ See the [API docs](https://svelte-docinfo.fuz.dev/docs/api) for the full referen
 - **Full type resolution**: infers complex types without manual annotations, including generics, imported types, and inferred return types
 - **Structured types**: an optional `typeInfo` tree (`TypeJson`) beside the flat type strings on props, parameters, return types (`returnTypeInfo`, overloads included), members, and variable/type declarations — union and intersection members (alias names kept), reference type arguments, and array/tuple elements, so a union alias documents more than its own name. Absent wherever the flat string already says everything; `typeJsonToTokens`/`typeJsonToText` render it
 - **TSDoc/JSDoc parsing**: the common doc tags (`@param`, `@returns`, `@throws`, `@example`, `@deprecated`, `@internal`, `@see`, `@since`, `@default`) plus `@nodocs`, `@mutates`, and `@module` for file-level comments; divergent spellings parse as synonyms (`@return`, `@defaultValue`). `@internal` marks unstable API (`internalMessage`) but stays documented — `@nodocs` is the exclusion. Dotted `@param obj.prop` tags fill `propertyDescriptions`, and inline `{@link}` survives in extracted text
-- **Alias-lost name recovery**: TypeScript drops the name of an alias over an indexed access or conditional (`type Foo = z.infer<typeof S>`) and expands its structure at every use. `typeInfo` recovers it as `{kind: 'reference', name}`, from the written annotation where there is one and otherwise from a registry of the project's exported aliases (those references also carry `module` for exact linking). Losses nothing recovers surface as `alias_lost` warnings
+- **Alias-lost name recovery**: TypeScript drops the name of an alias over an indexed access or conditional (`type Foo = z.infer<typeof S>`, or valibot's `v.InferOutput<typeof S>`) and expands its structure at every use. `typeInfo` recovers it as `{kind: 'reference', name}`, from the written annotation where there is one and otherwise from a registry of the project's exported aliases (those references also carry `module` for exact linking). Losses nothing recovers surface as `alias_lost` warnings
 - **Merged value+type symbols**: `export const Foo = z.strictObject({...})` + `export type Foo = z.infer<typeof Foo>` documents the type meaning (structure and members), with `mergedValue: true` marking the name as also a runtime value; JSDoc falls back to the const's docs, and `generateImport` emits a value import
 - **Svelte 5 component props**: extracts prop types, descriptions, defaults, and bindability via svelte2tsx, in source order (destructured external props follow, in destructuring order); generic components carry `genericParams`, and JS components (no `lang="ts"`) are supported — props come from the JSDoc `@type` on `$props()` or are inferred from untyped destructuring
 - **External types**: props and members contributed by external packages (e.g. `HTMLButtonAttributes`) are filtered out and named in `externalTypes` — on components, type aliases, interfaces, and classes, including bags reached through local base types. A component prop named in the `$props()` destructuring (`let {type = 'button', ...rest} = $props()`) is documented anyway, since the component handles it
@@ -354,8 +372,7 @@ Known gaps:
 
 - context tracking (transitive detection of common patterns seems tractable)
 - standalone `namespace Foo {}` declarations and decorators are not yet supported
-- Svelte 4 legacy features (slots, events, `$restProps`) are out of scope — Svelte 5 snippets and callback props replace most of them
-- legacy `export let` props aren't extracted (the component gets zero props), but a `legacy_props` warning names them
+- legacy `export let` components document their props (all `bindable`), and a legacy component's default `<slot />` sets `acceptsChildren`, but named slots, slot props, events, and `$$restProps` aren't modeled — Svelte 5 snippets and callback props replace most of them
 - `@nodocs` applies to declarations and export statements only; on a member or component prop it's ignored without a warning
 
 [Issues](https://github.com/fuzdev/svelte-docinfo/issues) for bugs and