svelte-docinfo 0.5.4 → 0.6.0

package/README.md

@@ -8,9 +8,9 @@
 svelte-docinfo extracts JSON describing the exports
 of TypeScript and Svelte modules for open-ended use cases
 like docs, code search, and dev tools.
-It uses
-[svelte2tsx](https://github.com/sveltejs/language-tools/tree/master/packages/svelte2tsx)
-and the TypeScript compiler API to resolve types, track exports+imports, and extract semantic details.
+It uses the TypeScript compiler API
+and [svelte2tsx](https://github.com/sveltejs/language-tools/tree/master/packages/svelte2tsx)
+to resolve types, track exports+imports, and extract semantic details.
 It includes a Vite plugin, CLI, and programmatic API
 in the [npm package](https://www.npmjs.com/package/svelte-docinfo).
 
@@ -44,7 +44,9 @@ and [fuz_ui](https://github.com/fuzdev/fuz_ui) components.
 
 **AI disclosure:** the code and docs beyond the intro
 were mostly written by Claude Code with uneven human guidance.
-The first release took 5 months of intermittent work and ~500 manual commits.
+The first release took 5 months of intermittent work and ~500 manual commits
+to [extract its initial implementation from fuz_ui](https://github.com/fuzdev/fuz_ui/pull/107),
+which was more limited, lacking the fancy TS compiler usage, and grew slowly over years without AI assistance.
 
 ## Quick start
 
@@ -73,7 +75,7 @@ export const add = (a: number, b: number): number => a + b;
 	let {
 		result = $bindable(0),
 		mode = 'add',
-		disabled = false,
+		disabled = false
 	}: {
 		/** Current result (bindable). */
 		result?: number;
@@ -93,7 +95,7 @@ Three ways to integrate `svelte-docinfo`:
 // vite.config.ts
 import svelteDocinfo from 'svelte-docinfo/vite.js';
 
-export default defineConfig({plugins: [sveltekit(), svelteDocinfo()]});
+export default defineConfig({ plugins: [sveltekit(), svelteDocinfo()] });
 // then anywhere in your app:
 // import {modules} from 'virtual:svelte-docinfo';
 ```
@@ -107,9 +109,9 @@ npx svelte-docinfo --pretty
 3. [API](#api) - programmatic access for build tools, custom pipelines, and standalone scripts:
 
 ```ts
-import {analyzeFromFiles} from 'svelte-docinfo';
+import { analyzeFromFiles } from 'svelte-docinfo';
 
-const {modules} = await analyzeFromFiles({projectRoot: process.cwd()});
+const { modules } = await analyzeFromFiles({ projectRoot: process.cwd() });
 ```
 
 All three produce the same JSON shape:
@@ -137,6 +139,13 @@ All three produce the same JSON shape:
 						{
 							"name": "mode",
 							"type": "\"add\" | \"multiply\"",
+							"typeInfo": {
+								"kind": "union",
+								"members": [
+									{ "kind": "literal", "value": "add", "text": "\"add\"" },
+									{ "kind": "literal", "value": "multiply", "text": "\"multiply\"" }
+								]
+							},
 							"optional": true,
 							"description": "Operation mode.",
 							"defaultValue": "'add'"
@@ -162,8 +171,8 @@ All three produce the same JSON shape:
 					"typeSignature": "(a: number, b: number): number",
 					"sourceLine": 7,
 					"parameters": [
-						{"name": "a", "type": "number", "description": "first number"},
-						{"name": "b", "type": "number", "description": "second number"}
+						{ "name": "a", "type": "number", "description": "first number" },
+						{ "name": "b", "type": "number", "description": "second number" }
 					],
 					"returnType": "number",
 					"returnDescription": "the sum"
@@ -174,23 +183,21 @@ All three produce the same JSON shape:
 }
 ```
 
-For examples of source input paired with the exact JSON `svelte-docinfo` emits:
-
-- see svelte-docinfo's own source code's extracted JSON at
-  [svelte-docinfo.fuz.dev/demo/extraction](https://svelte-docinfo.fuz.dev/demo/extraction)
-- browse the [test fixtures](https://github.com/fuzdev/svelte-docinfo/tree/main/src/test/fixtures)
+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).
 
 ## Vite plugin
 
 1. Add the plugin to `vite.config.ts`:
 
 ```ts
-import {defineConfig} from 'vite';
-import {sveltekit} from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+import { sveltekit } from '@sveltejs/kit/vite';
 import svelteDocinfo from 'svelte-docinfo/vite.js';
 
 export default defineConfig({
-	plugins: [sveltekit(), svelteDocinfo()],
+	plugins: [sveltekit(), svelteDocinfo()]
 });
 ```
 
@@ -203,23 +210,30 @@ export default defineConfig({
 3. Import the virtual module anywhere in your app:
 
 ```ts
-import {modules, diagnostics} from 'virtual:svelte-docinfo';
+import { modules, diagnostics } from 'virtual:svelte-docinfo';
 // or: import data from 'virtual:svelte-docinfo';
 ```
 
 Plugin options:
 
-| Option                | Default                            | Description                                                                                                                                |
-| --------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `projectRoot`         | Vite's resolved `config.root`      | Absolute path to project root.                                                                                                             |
-| `include`             | —                                  | Glob patterns to include (relative to `projectRoot`). Collapses `discovery: 'auto'` to glob; combining with `discovery: 'exports'` throws. |
-| `exclude`             | `['**/*.test.ts', '**/*.spec.ts']` | Glob patterns to exclude (fully replaces defaults — does not merge with `**/*.test.ts`, `**/*.spec.ts`).                                   |
-| `discovery`           | `'auto'`                           | Discovery strategy: `'auto'` \| `'exports'` \| `'glob'`. `'exports'` is strict and fails if `package.json` exports is missing or empty.    |
-| `distDir`             | `'dist'`                           | Dist directory name for exports-based discovery.                                                                                           |
-| `sourceOptions`       | `{sourcePaths: ['src/lib'], …}`    | Partial overrides for default source options (SvelteKit `src/lib` layout).                                                                 |
-| `resolveDependencies` | `true`                             | Resolve import dependencies. When `false`, `dependencies`/`dependents` stay empty.                                                         |
-| `onDuplicates`        | —                                  | Dispatch on duplicate declaration names: `'throw'` \| `'warn'` \| callback. Diagnostic emits regardless of dispatch.                       |
-| `hmrDebounceMs`       | `100`                              | HMR debounce delay in milliseconds.                                                                                                        |
+| Option                | Default                                              | Description                                                                                                                                                                                                            |
+| --------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `projectRoot`         | Vite's resolved `config.root`                        | Absolute path to project root.                                                                                                                                                                                         |
+| `include`             | —                                                    | Glob patterns to include (relative to `projectRoot`; absolute inside it accepted). Collapses `discovery: 'auto'` to glob; combining with `discovery: 'exports'` throws. Widens the source scope — see the notes below. |
+| `exclude`             | `['**/*.test.ts', '**/*.spec.ts', '**/internal/**']` | Glob patterns to exclude. An array fully replaces the defaults; the callback form extends them (`(defaults) => [...defaults, '**/*.gen.ts']`). The always-on baseline below still applies.                             |
+| `discovery`           | `'auto'`                                             | Discovery strategy: `'auto'` \| `'exports'` \| `'glob'`. `'exports'` is strict and fails if `package.json` exports is missing or empty.                                                                                |
+| `distDir`             | `'dist'`                                             | Dist directory name for exports-based discovery.                                                                                                                                                                       |
+| `sourceOptions`       | `{sourcePaths: ['src/lib'], …}`                      | Partial overrides for default source options (SvelteKit `src/lib` layout).                                                                                                                                             |
+| `resolveDependencies` | `true`                                               | Resolve import dependencies. When `false`, `dependencies`/`dependents` stay empty.                                                                                                                                     |
+| `onDuplicates`        | —                                                    | Dispatch on duplicate declaration names: `'throw'` \| `'warn'` \| callback. Diagnostic emits regardless of dispatch.                                                                                                   |
+| `hmrDebounceMs`       | `100`                                                | HMR debounce delay in milliseconds.                                                                                                                                                                                    |
+
+Source-scope notes (shared with the [CLI](#cli) and `analyzeFromFiles`):
+
+- Explicit `include` patterns **widen the source scope**: each pattern's static base joins `sourceOptions.sourcePaths`, so include-discovered files emit modules (with paths relative to the widened set's common root) and the dev-mode watcher tracks them. A pattern with no base (`'**/*.ts'`, a literal root file) scopes the whole project root as source and logs an info line naming it.
+- An **always-on baseline** applies beneath any `exclude`: `node_modules` and dot-directories below a matched source path are never source. It's matched relative to the matched source path — an explicit dot-directory source path (`sourcePaths: ['.hidden/src']`) still works — and is independent of `exclude` overrides. `dist`/`build`/`coverage` are ordinary names and stay in.
+- The **`src/lib/internal/` convention**: `internal/` directories are excluded by default (the `**/internal/**` default pattern) — internal modules ship in the package for public modules to import but aren't documented. Packages typically pair the directory with an `"./internal/*": null` package.json exports entry blocking consumer imports; exports-based discovery honors null-target keys with Node's best-match resolution semantics, so blocked subpaths are never discovered. Internal modules stay live in dev: the analysis session owns them as watched context files, so editing an internal type re-analyzes the public modules that use it. A public re-export of an internal symbol (`export { x } from './internal/helper.js'`) documents at the re-export site as a full synthesized declaration. Re-include internal modules wholesale with the exclude callback: `exclude: (defaults) => defaults.filter((p) => p !== '**/internal/**')`.
+- Paths and patterns resolve against `projectRoot`: absolute entries inside the root are accepted (stored root-relative), and anything resolving outside the root **throws** at options creation instead of silently emitting nothing — a root-anchored `'/src/lib'` is filesystem-absolute, not shorthand for `'src/lib'`.
 
 The options interface is `VitePluginSvelteDocinfoOptions` from `svelte-docinfo/vite.js` (not re-exported from the main barrel).
 See the [docs site](https://svelte-docinfo.fuz.dev/) and [examples/vite/](examples/vite/README.md) for more.
@@ -249,22 +263,24 @@ stderr (warnings and errors still print).
 
 All CLI options:
 
-| Flag                        | Description                                                                                                                                                  |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `[project-root]`            | Project root directory (default: cwd)                                                                                                                        |
-| `-i, --include <pattern>`   | Include pattern (repeatable, replaces exports discovery; incompatible with `--discovery exports`)                                                            |
-| `-e, --exclude <pattern>`   | Exclude glob, applied at discovery and analysis (repeatable; fully replaces defaults — does not merge with `**/*.test.ts`, `**/*.spec.ts`)                   |
-| `-o, --output <file>`       | Output file (default: stdout; pass `-` for explicit stdout, so `-o "$OUT"` works when `$OUT=-`)                                                              |
-| `--discovery <mode>`        | `auto` \| `exports` \| `glob` (default: `auto` — exports first, glob fallback). `exports` is strict and fails if package.json exports is missing             |
-| `--dist-dir <dir>`          | Dist directory for exports discovery (default: dist)                                                                                                         |
-| `--source-dir <dir>`        | Source directory relative to project root (default: src/lib). Repeatable for monorepos; drives the implicit include glob when no `--include` is provided     |
-| `--source-root <dir>`       | Source root for module-path stripping (default: single source-dir or longest common prefix; pass `.` for project-relative paths)                             |
-| `--on-duplicates <mode>`    | Dispatch on duplicate declaration names: `throw` \| `warn` (default: emit `duplicate_declaration` diagnostic, no dispatch)                                   |
-| `--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)                                                                                                                  |
-| `-q, --quiet`               | Suppress info messages on stderr (warnings and errors still print)                                                                                           |
-| `-V, --version`             | Show version number                                                                                                                                          |
+| Flag                        | Description                                                                                                                                                                                   |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[project-root]`            | Project root directory (default: cwd)                                                                                                                                                         |
+| `-i, --include <pattern>`   | Include pattern (repeatable, replaces exports discovery, widens the source scope; incompatible with `--discovery exports`)                                                                    |
+| `-e, --exclude <pattern>`   | Exclude glob, applied at discovery and analysis (repeatable; fully replaces the defaults `**/*.test.ts`, `**/*.spec.ts`, `**/internal/**` — no merge; the always-on baseline applies beneath) |
+| `-o, --output <file>`       | Output file (default: stdout; pass `-` for explicit stdout, so `-o "$OUT"` works when `$OUT=-`)                                                                                               |
+| `--discovery <mode>`        | `auto` \| `exports` \| `glob` (default: `auto` — exports first, glob fallback). `exports` is strict and fails if package.json exports is missing                                              |
+| `--dist-dir <dir>`          | Dist directory for exports discovery (default: dist)                                                                                                                                          |
+| `--source-dir <dir>`        | Source directory, relative to project root or absolute inside it (default: src/lib). Repeatable for monorepos; drives the implicit include glob when no `--include` is provided               |
+| `--source-root <dir>`       | Source root for module-path stripping (default: single source-dir or longest common prefix; pass `.` for project-relative paths)                                                              |
+| `--on-duplicates <mode>`    | Dispatch on duplicate declaration names: `throw` \| `warn` (default: emit `duplicate_declaration` diagnostic, no dispatch)                                                                    |
+| `--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)                                                                                                                                                   |
+| `-q, --quiet`               | Suppress info messages on stderr (warnings and errors still print)                                                                                                                            |
+| `-V, --version`             | Show version number                                                                                                                                                                           |
+
+The [Vite plugin](#vite-plugin)'s source-scope notes apply here too: explicit `--include` patterns widen the source scope (module paths become relative to the widened root, and a pattern with no base scopes the whole project root and logs an info line); `node_modules` and dot-directories below a source dir are always excluded regardless of `--exclude`; absolute paths and patterns inside the project root are accepted, and out-of-root ones fail loudly.
 
 Exit codes: 0 (success), 1 (analysis errors), 2 (CLI errors).
 
@@ -284,9 +300,9 @@ For most projects, `analyzeFromFiles` is all you need. It reads your `package.js
 to discover source files, falling back to glob patterns:
 
 ```ts
-import {analyzeFromFiles} from 'svelte-docinfo';
+import { analyzeFromFiles } from 'svelte-docinfo';
 
-const {modules} = await analyzeFromFiles({projectRoot: process.cwd()});
+const { modules } = await analyzeFromFiles({ projectRoot: process.cwd() });
 ```
 
 Pass `include` for custom patterns or `discovery: 'glob'` to always use glob.
@@ -294,7 +310,7 @@ Use `discovery: 'exports'` for strict mode that throws if `package.json` has no
 When you already have file contents in memory,
 use `analyze` instead of `analyzeFromFiles` to skip file discovery.
 For just the discovery step (without running analysis), use
-`discoverSourceFiles` from `svelte-docinfo/discovery.js`.
+`discoverSourceFiles` (also in the main `svelte-docinfo` import).
 
 For long-lived consumers (a Vite plugin reacting to file edits, an LSP-style tool),
 `createAnalysisSession` returns a persistent handle that reuses parsed ASTs across calls
@@ -310,7 +326,10 @@ See the [API docs](https://svelte-docinfo.fuz.dev/docs/api) for the full referen
 ## Features
 
 - **Full type resolution**: infers complex types without manual annotations, including generics, imported types, and inferred return types
-- **TSDoc/JSDoc parsing**: standard tags (`@param`, `@returns`, `@throws`, `@example`, `@deprecated`, `@see`, `@since`, `@default`) plus `@nodocs`, `@mutates`, and `@module` for file-level comments
+- **Structured types**: an optional `typeInfo` tree (`TypeJson`) beside the flat type strings on props, parameters, return types (`returnTypeInfo`, overloads included), type members, and variable/type declarations — union and intersection members (alias names kept, enum members as `{value, text}` pairs), reference type arguments (named generic instantiations like `Snippet<[a: string]>` classify as references), array and tuple elements (with `readonly` markers), so a union alias documents more than its own name — and absent wherever the flat string already says everything
+- **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`, TSDoc's `@defaultValue`). `@internal` is a marker (`internalMessage`, prose kept), not an exclusion — that's `@nodocs`
+- **Alias-lost name recovery**: schema-inferred aliases (`type Foo = z.infer<typeof S>` — any indexed-access or conditional right-hand side) lose their name in the checker, which expands their structure at every use; `typeInfo` recovers the name as `{kind: 'reference', name}` from the written annotation where one exists, and — via an identity-keyed registry of the analyzed set's exported lost aliases — at unannotated inferred positions too, `null`-bearing optionals included; registry-recovered references also carry `module` (the declaring module's `ModuleJson.path`, always an emitted module) for collision-exact linking. Losses nothing recovers surface as `alias_lost` warnings (readable degradations like `z.enum` literal unions and `.brand()` intersections excluded)
+- **Merged value+type symbols**: `export const Foo = z.strictObject({...})` + `export type Foo = z.infer<typeof Foo>` (one symbol, both spaces) documents the type meaning — structure and members like the un-merged equivalent — with `mergedValue: true` marking the name as also importable as 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
 - **Svelte 5 snippets**: `kind: 'snippet'` for template snippets (with structured parameters), `acceptsChildren` on components
 - **Svelte 5 reactivity runes**: detects `$state`, `$state.raw`, `$derived`, `$derived.by` on variables and class fields (`reactivity` field) — syntactic detection, surfaces wherever the rune pattern appears