svelte-docinfo 0.7.0 → 0.8.0

package/README.md

@@ -18,6 +18,9 @@ in the [npm package](https://www.npmjs.com/package/svelte-docinfo).
 npm i -D svelte-docinfo
 ```
 
+Peer dependencies: `svelte` 5+, `svelte2tsx`, `typescript` 5.9+, and `zod` 4+
+(npm 7+ installs them automatically).
+
 - [Quick start](#quick-start)
 - [Vite plugin](#vite-plugin)
 - [CLI](#cli)
@@ -50,7 +53,7 @@ which was more limited, lacking the fancy TS compiler usage, and grew slowly ove
 
 ## Quick start
 
-Given a project with a couple of files in `src/lib/`:
+Given a project with a `tsconfig.json` (at or above the project root) and a couple of files in `src/lib/`:
 
 ```ts
 // src/lib/math.ts
@@ -221,7 +224,7 @@ Plugin options:
 | `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.                                                                                |
+| `discovery`           | `'auto'`                                             | Discovery strategy: `'auto'` \| `'exports'` \| `'glob'`. `'exports'` is strict and fails if `package.json` exports is missing or resolves to no files.                                                                                |
 | `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.                                                                                                                                     |
@@ -269,7 +272,7 @@ All CLI options:
 | `-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                                              |
+| `--discovery <mode>`        | `auto` \| `exports` \| `glob` (default: `auto` — exports first, glob fallback). `exports` is strict and fails if package.json exports is missing or resolves to no files                                     |
 | `--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)                                                              |
@@ -282,7 +285,8 @@ All CLI options:
 
 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).
+Exit codes: 0 (success), 1 (analysis errors), 2 (CLI errors or a thrown analysis error, like a
+missing `tsconfig.json` or an `--on-duplicates throw` collision).
 
 See [examples/cli/](examples/cli/README.md) for more usage patterns.
 
@@ -326,11 +330,12 @@ 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
-- **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
+- **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
+- **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; 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
 - **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
 - **Class members**: public + protected fields, methods, constructors, getters/setters, generics; private (`private` and `#field`) excluded
@@ -348,6 +353,8 @@ 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
+- `@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
 [discussions](https://github.com/fuzdev/svelte-docinfo/discussions) are welcome!

package/dist/analyze-core.d.ts

@@ -1,21 +1,21 @@
 /**
  * Pure two-phase analysis orchestrator.
  *
- * Extracted from `analyze.ts` to break what would otherwise be a circular
- * import: `session.ts` → `analyze.ts` (for the orchestrator) → `session.ts`
- * (for the wrappers). With the orchestrator here, both `session.ts` and
- * `analyze.ts` import downward into this module without depending on each
- * other.
+ * Separate from `analyze.ts` so `session.ts` (which needs the orchestrator)
+ * and `analyze.ts` (which needs the session) both import downward into this
+ * module without a cycle.
  *
  * Public surface:
  *
  * - `analyzeCore` — runs phase 1 module dispatch + phase 2 re-export merge,
  *   returns `AnalyzeResultJson`. Caller supplies pre-prepared inputs (program,
  *   svelte virtuals, transform-failed IDs).
- * - `analyzeModule` — the per-module dispatcher (TS / Svelte / CSS / JSON).
- *   `@internal`; exposed for tests and power users via the subpath.
- * - `AnalyzeResultJson` / `OnDuplicates` / `OnDuplicatesCallback` — shared types
- *   surfaced through the main barrel directly from this module.
+ * - `analyzeModule` — the per-module dispatcher for non-Svelte files (TS / CSS /
+ *   JSON; Svelte needs `analyzeSvelteModule`). `@internal`; exposed for tests
+ *   and power users via the subpath.
+ * - `AnalyzeResultJson` / `AnalyzeResultJsonWire` / `OnDuplicates` /
+ *   `OnDuplicatesCallback` — shared types surfaced through the main barrel
+ *   directly from this module.
  * - `throwOnDuplicates` — convenience callback paired with `OnDuplicates`.
  * - `finalizeDiagnostics` — the diagnostic boundary passes (virtual position
  *   remap, then path normalization) in their required order; the one call for
@@ -28,8 +28,9 @@
  *   assembling modules itself through `analyzeModule` can meet the same
  *   output contract.
  *
- * @internal — module split is implementation detail; consumers go through
- * `analyze.ts` / `session.ts` for the stable surface.
+ * The barrel-surfaced schemas, types, and `throwOnDuplicates` are stable API.
+ * Everything else is subpath-only; `analyzeCore` and `analyzeModule` are
+ * `@internal`.
  *
  * @module
  */
@@ -1464,12 +1465,8 @@ export interface AnalyzeResultJsonWire {
     diagnostics: Array<Diagnostic>;
 }
 /**
- * Analyze a single non-Svelte source file and extract module metadata.
- *
- * @internal Single-module dispatcher used internally by the two-phase
- * orchestrator. Importable from `svelte-docinfo/analyze-core.js` for tests
- * and power users — not part of the stable barrel API and not guaranteed
- * across minor versions.
+ * Analyze a single non-Svelte source file and extract module metadata — the
+ * per-module dispatcher behind `analyzeCore`.
  *
  * Dispatches on file type:
  * - TypeScript/JS → `analyzeTypescriptModule`
@@ -1487,6 +1484,9 @@ export interface AnalyzeResultJsonWire {
  * `aliasRegistry` is optional at this boundary: direct callers assembling
  * modules themselves get written-name recovery only, while `analyzeCore`
  * passes the registry its pre-pass built (see `buildAliasRegistry`).
+ *
+ * @internal Importable from `svelte-docinfo/analyze-core.js` for tests and
+ * power users; not stable API.
  */
 export declare const analyzeModule: (sourceFile: SourceFileInfo & {
     dependents?: ReadonlyArray<string>;
@@ -1517,11 +1517,35 @@ export interface AnalyzeCoreInputs {
      * context for `resolveComponentAliases` — their modules never emit and
      * their analysis diagnostics are dropped (`partial` on the canonical
      * propagates to the filled alias instead).
+     *
+     * Resolution requires the component's virtual to exist — via the context
+     * closure (`analyzeFromFiles` included) or by passing the file as `analyze()`
+     * input. Without it a gated component re-export degrades silently to an
+     * empty `kind: 'variable'` husk.
      */
     contextSvelteFiles?: ReadonlyArray<SourceFileInfo>;
     onDuplicates?: OnDuplicates;
     log?: AnalysisLog;
 }
+/**
+ * Run the two-phase analysis loop on pre-prepared inputs. The orchestrator
+ * behind `session.query`, and so behind the one-shot wrappers, which query a
+ * single-use session.
+ *
+ * Runs the alias-registry pre-pass (`buildAliasRegistry`) over the emitted
+ * set, then phase 1: per-file dispatch (TS / Svelte / CSS / JSON /
+ * placeholder for transform-failed Svelte), plus gated Svelte canonicals
+ * analyzed as fill context. Phase 2: re-export merge, component-alias fill,
+ * sort, duplicate detection, and module-path normalization in printed types
+ * (`normalizeModulePathsInTypes`), then `finalizeDiagnostics`.
+ *
+ * Dependents are read from `sourceFile.dependents` via `extractDependencies`;
+ * `analyzeCore` does not compute them. `session.query` runs
+ * `computeDependents` on the emitted set before invoking this.
+ *
+ * @internal Importable from `svelte-docinfo/analyze-core.js` for tests and
+ * power users; not stable API.
+ */
 export declare const analyzeCore: (inputs: AnalyzeCoreInputs) => AnalyzeResultJson;
 /**
  * Run the diagnostic boundary passes in their required order: virtual
@@ -1533,7 +1557,7 @@ export declare const analyzeCore: (inputs: AnalyzeCoreInputs) => AnalyzeResultJs
  * ordering unrepresentable instead of a contract to remember. Omit
  * `virtualFiles` when no Svelte virtuals are in play.
  *
- * @mutates diagnostics — rewrites positions, `file`, and `message`
+ * @mutates diagnostics - rewrites positions, `file`, and `message`
  */
 export declare const finalizeDiagnostics: (diagnostics: Array<Diagnostic>, options: {
     projectRoot: string;
@@ -1547,9 +1571,8 @@ export declare const finalizeDiagnostics: (diagnostics: Array<Diagnostic>, optio
  * paths (svelte2tsx output like `Foo.svelte.__svelte2tsx__.ts`). This pass
  * collapses both to the public contract: a path relative to `projectRoot`
  * with no leading slash and no `./` prefix. A file outside the root gets the
- * `../` form, matching module paths in printed type text — and making the
- * documented "rejoin with `projectRoot` to get an absolute path" actually
- * hold for it, which dropping the leading slash did not.
+ * `../` form, matching module paths in printed type text — so the documented
+ * "rejoin with `projectRoot` to get an absolute path" holds for it too.
  *
  * `message` gets the same treatment as `file`, by textual substitution. A
  * message is free-form, and not every path in one comes from a field this
@@ -1565,7 +1588,7 @@ export declare const finalizeDiagnostics: (diagnostics: Array<Diagnostic>, optio
  * pass can only correct the absolute form — a relative path on a base other
  * than the project root passes through and ships as-is.
  *
- * @mutates diagnostics — rewrites each diagnostic's `file` and `message`
+ * @mutates diagnostics - rewrites each diagnostic's `file` and `message`
  * @see `finalizeDiagnostics` — when Svelte virtuals are in play, the position
  * remap must run before this pass (it strips the suffix the remap matches on)
  */
@@ -1576,22 +1599,27 @@ export declare const normalizeDiagnosticPaths: (diagnostics: Array<Diagnostic>,
  *
  * The checker prints a module object as `typeof import("<absolute path>")`,
  * which reaches output through every checker-printed field — `typeSignature`
- * on declarations and members, `returnType`, and the `text`/`name` of a
- * `TypeJson` node. Left alone it makes output machine-dependent (two checkouts
+ * on declarations and members, `returnType`, and the `text` of a
+ * `TypeJson` node (a module object is a terminal `other` node, never a
+ * `reference`). Left alone it makes output machine-dependent (two checkouts
  * of the same source produce different bytes), publishes local filesystem
  * paths on any site that renders `typeSignature`, and exposes the svelte2tsx
- * virtual suffix that `stripVirtualSuffix` exists to hide.
+ * virtual suffix that `stripVirtualSuffix` exists to hide. A written
+ * `import('./x').T` annotation resolves to the type's own name and never
+ * carries a path.
  *
  * A path that resolves to a module in this output is rewritten to that
  * module's `ModuleJson.path`, so the string doubles as a lookup key: a
  * consumer linkifies with `modules.find((m) => m.path === s)` and reads a miss
  * as "not a module here." See `createModulePathNormalizer` for the remaining
- * tiers.
+ * tiers. The string's shape doesn't distinguish them (`sub/nested.ts` and
+ * `pkg/index.d.ts` look alike) — the lookup does, which keeps `sourceRoot` out
+ * of the output envelope.
  *
  * Runs as a whole-output pass rather than at the ~20 `typeToString` /
  * `signatureToString` call sites, so a new printing site can't miss it.
  *
- * @mutates modules — rewrites printed type text on declarations and members
+ * @mutates modules - rewrites printed type text on declarations and members
  */
 export declare const normalizeModulePathsInTypes: (modules: Array<ModuleJson>, options: ModuleSourceOptions, program: ts.Program) => void;
 //# sourceMappingURL=analyze-core.d.ts.map

package/dist/analyze-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze-core.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/analyze-core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"analyze-core.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/analyze-core.ts"],"names":[],"mappings":"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"}

package/dist/analyze-core.js

@@ -1,21 +1,21 @@
 /**
  * Pure two-phase analysis orchestrator.
  *
- * Extracted from `analyze.ts` to break what would otherwise be a circular
- * import: `session.ts` → `analyze.ts` (for the orchestrator) → `session.ts`
- * (for the wrappers). With the orchestrator here, both `session.ts` and
- * `analyze.ts` import downward into this module without depending on each
- * other.
+ * Separate from `analyze.ts` so `session.ts` (which needs the orchestrator)
+ * and `analyze.ts` (which needs the session) both import downward into this
+ * module without a cycle.
  *
  * Public surface:
  *
  * - `analyzeCore` — runs phase 1 module dispatch + phase 2 re-export merge,
  *   returns `AnalyzeResultJson`. Caller supplies pre-prepared inputs (program,
  *   svelte virtuals, transform-failed IDs).
- * - `analyzeModule` — the per-module dispatcher (TS / Svelte / CSS / JSON).
- *   `@internal`; exposed for tests and power users via the subpath.
- * - `AnalyzeResultJson` / `OnDuplicates` / `OnDuplicatesCallback` — shared types
- *   surfaced through the main barrel directly from this module.
+ * - `analyzeModule` — the per-module dispatcher for non-Svelte files (TS / CSS /
+ *   JSON; Svelte needs `analyzeSvelteModule`). `@internal`; exposed for tests
+ *   and power users via the subpath.
+ * - `AnalyzeResultJson` / `AnalyzeResultJsonWire` / `OnDuplicates` /
+ *   `OnDuplicatesCallback` — shared types surfaced through the main barrel
+ *   directly from this module.
  * - `throwOnDuplicates` — convenience callback paired with `OnDuplicates`.
  * - `finalizeDiagnostics` — the diagnostic boundary passes (virtual position
  *   remap, then path normalization) in their required order; the one call for
@@ -28,8 +28,9 @@
  *   assembling modules itself through `analyzeModule` can meet the same
  *   output contract.
  *
- * @internal — module split is implementation detail; consumers go through
- * `analyze.ts` / `session.ts` for the stable surface.
+ * The barrel-surfaced schemas, types, and `throwOnDuplicates` are stable API.
+ * Everything else is subpath-only; `analyzeCore` and `analyzeModule` are
+ * `@internal`.
  *
  * @module
  */
@@ -179,12 +180,8 @@ const toModuleJson = (raw) => {
 };
 // Module dispatch
 /**
- * Analyze a single non-Svelte source file and extract module metadata.
- *
- * @internal Single-module dispatcher used internally by the two-phase
- * orchestrator. Importable from `svelte-docinfo/analyze-core.js` for tests
- * and power users — not part of the stable barrel API and not guaranteed
- * across minor versions.
+ * Analyze a single non-Svelte source file and extract module metadata — the
+ * per-module dispatcher behind `analyzeCore`.
  *
  * Dispatches on file type:
  * - TypeScript/JS → `analyzeTypescriptModule`
@@ -202,6 +199,9 @@ const toModuleJson = (raw) => {
  * `aliasRegistry` is optional at this boundary: direct callers assembling
  * modules themselves get written-name recovery only, while `analyzeCore`
  * passes the registry its pre-pass built (see `buildAliasRegistry`).
+ *
+ * @internal Importable from `svelte-docinfo/analyze-core.js` for tests and
+ * power users; not stable API.
  */
 export const analyzeModule = (sourceFile, program, options, diagnostics, log, aliasRegistry) => {
     const checker = program.getTypeChecker();
@@ -270,23 +270,6 @@ export const analyzeModule = (sourceFile, program, options, diagnostics, log, al
     }
     return toModuleJson(raw);
 };
-/**
- * Run the two-phase analysis loop on pre-prepared inputs.
- *
- * @internal Shared two-phase orchestrator used internally by `session.query`
- * and the one-shot wrappers. Importable from `svelte-docinfo/analyze-core.js`
- * for tests and power users — not part of the stable barrel API and not
- * guaranteed across minor versions.
- *
- * Phase 1: per-file dispatch (TS / Svelte / CSS / JSON / placeholder for
- * transform-failed Svelte). Phase 2: re-export merge, component-alias fill,
- * sort, duplicate detection. Diagnostic paths are normalized to
- * project-root-relative form before return.
- *
- * Dependents are read from `sourceFile.dependents` (caller-supplied via
- * `extractDependencies`); `analyzeCore` does not compute them. `session.query`
- * runs `computeDependents` on the owned set before invoking this.
- */
 /**
  * Analyze the gated Svelte canonicals referenced by an emitted component
  * alias, as `resolveComponentAliases` fill context only (see
@@ -320,6 +303,25 @@ const analyzeContextComponents = (contextSvelteFiles, emittedModules, inputs, al
     }
     return contextModules;
 };
+/**
+ * Run the two-phase analysis loop on pre-prepared inputs. The orchestrator
+ * behind `session.query`, and so behind the one-shot wrappers, which query a
+ * single-use session.
+ *
+ * Runs the alias-registry pre-pass (`buildAliasRegistry`) over the emitted
+ * set, then phase 1: per-file dispatch (TS / Svelte / CSS / JSON /
+ * placeholder for transform-failed Svelte), plus gated Svelte canonicals
+ * analyzed as fill context. Phase 2: re-export merge, component-alias fill,
+ * sort, duplicate detection, and module-path normalization in printed types
+ * (`normalizeModulePathsInTypes`), then `finalizeDiagnostics`.
+ *
+ * Dependents are read from `sourceFile.dependents` via `extractDependencies`;
+ * `analyzeCore` does not compute them. `session.query` runs
+ * `computeDependents` on the emitted set before invoking this.
+ *
+ * @internal Importable from `svelte-docinfo/analyze-core.js` for tests and
+ * power users; not stable API.
+ */
 export const analyzeCore = (inputs) => {
     const { sourceFiles, sourceOptions, program, svelteVirtualFiles, transformFailedIds, contextSvelteFiles, onDuplicates, log } = inputs;
     const checker = program.getTypeChecker();
@@ -445,7 +447,7 @@ export const analyzeCore = (inputs) => {
  * ordering unrepresentable instead of a contract to remember. Omit
  * `virtualFiles` when no Svelte virtuals are in play.
  *
- * @mutates diagnostics — rewrites positions, `file`, and `message`
+ * @mutates diagnostics - rewrites positions, `file`, and `message`
  */
 export const finalizeDiagnostics = (diagnostics, options) => {
     if (options.virtualFiles) {
@@ -461,9 +463,8 @@ export const finalizeDiagnostics = (diagnostics, options) => {
  * paths (svelte2tsx output like `Foo.svelte.__svelte2tsx__.ts`). This pass
  * collapses both to the public contract: a path relative to `projectRoot`
  * with no leading slash and no `./` prefix. A file outside the root gets the
- * `../` form, matching module paths in printed type text — and making the
- * documented "rejoin with `projectRoot` to get an absolute path" actually
- * hold for it, which dropping the leading slash did not.
+ * `../` form, matching module paths in printed type text — so the documented
+ * "rejoin with `projectRoot` to get an absolute path" holds for it too.
  *
  * `message` gets the same treatment as `file`, by textual substitution. A
  * message is free-form, and not every path in one comes from a field this
@@ -479,7 +480,7 @@ export const finalizeDiagnostics = (diagnostics, options) => {
  * pass can only correct the absolute form — a relative path on a base other
  * than the project root passes through and ships as-is.
  *
- * @mutates diagnostics — rewrites each diagnostic's `file` and `message`
+ * @mutates diagnostics - rewrites each diagnostic's `file` and `message`
  * @see `finalizeDiagnostics` — when Svelte virtuals are in play, the position
  * remap must run before this pass (it strips the suffix the remap matches on)
  */
@@ -500,7 +501,7 @@ export const normalizeDiagnosticPaths = (diagnostics, projectRoot) => {
         }
         else if (isAbsolutePosixPath(file)) {
             // Outside the root. Relativize rather than dropping the leading slash,
-            // which produced a string that reads as root-relative but resolves
+            // which would produce a string that reads as root-relative but resolves
             // somewhere else entirely. A path already relative is left alone —
             // `relative` would resolve it against `cwd`.
             file = toPosixPath(relative(root, file));
@@ -745,22 +746,27 @@ const rewriteTypeText = (value, rewrite) => {
  *
  * The checker prints a module object as `typeof import("<absolute path>")`,
  * which reaches output through every checker-printed field — `typeSignature`
- * on declarations and members, `returnType`, and the `text`/`name` of a
- * `TypeJson` node. Left alone it makes output machine-dependent (two checkouts
+ * on declarations and members, `returnType`, and the `text` of a
+ * `TypeJson` node (a module object is a terminal `other` node, never a
+ * `reference`). Left alone it makes output machine-dependent (two checkouts
  * of the same source produce different bytes), publishes local filesystem
  * paths on any site that renders `typeSignature`, and exposes the svelte2tsx
- * virtual suffix that `stripVirtualSuffix` exists to hide.
+ * virtual suffix that `stripVirtualSuffix` exists to hide. A written
+ * `import('./x').T` annotation resolves to the type's own name and never
+ * carries a path.
  *
  * A path that resolves to a module in this output is rewritten to that
  * module's `ModuleJson.path`, so the string doubles as a lookup key: a
  * consumer linkifies with `modules.find((m) => m.path === s)` and reads a miss
  * as "not a module here." See `createModulePathNormalizer` for the remaining
- * tiers.
+ * tiers. The string's shape doesn't distinguish them (`sub/nested.ts` and
+ * `pkg/index.d.ts` look alike) — the lookup does, which keeps `sourceRoot` out
+ * of the output envelope.
  *
  * Runs as a whole-output pass rather than at the ~20 `typeToString` /
  * `signatureToString` call sites, so a new printing site can't miss it.
  *
- * @mutates modules — rewrites printed type text on declarations and members
+ * @mutates modules - rewrites printed type text on declarations and members
  */
 export const normalizeModulePathsInTypes = (modules, options, program) => {
     const rewrite = createModulePathNormalizer(modules, options, program);

package/dist/analyze.d.ts

@@ -1,8 +1,8 @@
 /**
  * One-shot analysis wrappers — `analyze` and `analyzeFromFiles`.
  *
- * Both wrap a single-use `AnalysisSession`: `createSession → setFiles → query
- * → dispose`. Incremental consumers (Vite plugin, LSP) should use
+ * Both wrap a single-use `AnalysisSession`: `createAnalysisSession → setFiles →
+ * query → dispose`. Incremental consumers (Vite plugin, LSP) should use
  * `createAnalysisSession` directly so parsed ASTs and svelte2tsx output
  * survive between calls.
  *
@@ -82,37 +82,16 @@ export interface AnalyzeFromFilesOptions {
     /** Optional logger for status and diagnostic messages. */
     log?: AnalysisLog;
     /**
-     * Glob patterns to include (relative to `projectRoot`; an absolute pattern
-     * inside the root relativizes, an out-of-root one throws — see
-     * `normalizeIncludePatterns`).
-     *
-     * Filters glob-based discovery. Providing `include` under the default
-     * `discovery: 'auto'` collapses the chain to glob immediately; combining
-     * with `discovery: 'exports'` throws.
-     *
-     * Explicit patterns also widen the source scope: their static bases join
-     * `sourceOptions.sourcePaths` (see `widenSourcePathsForInclude`), so
-     * include-discovered files outside the configured source paths still emit
-     * modules, with paths relative to the widened set's common root. A pattern
-     * with no static base (`'**\/*.ts'`, a literal root file) scopes the whole
-     * project root as source and logs an info line; an out-of-root base
-     * (`'../other/**'`) throws.
-     *
-     * When omitted, the glob fallback derives an include from
-     * `sourceOptions.sourcePaths` via `deriveIncludePatterns`, so custom
-     * `sourcePaths` (e.g., `['packages/foo']`) survive the fallback instead of
-     * silently defaulting to `src/lib`.
+     * Glob patterns to include, relative to `projectRoot`. Collapses
+     * `discovery: 'auto'` to glob (combining with `'exports'` throws), and each
+     * pattern's static base widens `sourceOptions.sourcePaths` so the matched
+     * files emit modules (see `createSourceOptionsWithInclude`).
      */
     include?: Array<string>;
     /**
-     * Glob patterns to exclude — takes precedence over `sourceOptions.exclude`
-     * (no merge between the two). An array replaces the default patterns
-     * wholesale; the callback form extends them without restating them
-     * (`(defaults) => [...defaults, '**\/*.gen.ts']` — see `ExcludeOption`).
-     * The callback always receives the built-in defaults, even when
-     * `sourceOptions.exclude` is also set (that value is superseded whole).
-     * The always-on baseline (`node_modules` + dot-directories below a matched
-     * source path) applies beneath it and is unaffected by overrides.
+     * Glob patterns to exclude — supersedes `sourceOptions.exclude` whole (no
+     * merge; the callback form still receives the built-in defaults). An array
+     * replaces the defaults, a callback extends them — see `ExcludeOption`.
      */
     exclude?: ExcludeOption;
     /**
@@ -156,7 +135,9 @@ export interface AnalyzeFromFilesOptions {
  * 3. **Analysis** — `session.query()`
  *
  * @returns analyzed modules + concatenated ingest, discovery, and query diagnostics
- * @throws Error if `sourceOptions` validation fails or `tsconfig.json` is missing
+ * @throws Error on invalid or contradictory options, a missing `tsconfig.json`,
+ *   failed strict `'exports'` discovery, or a collision under
+ *   `onDuplicates: 'throw'`
  */
 export declare const analyzeFromFiles: (options: AnalyzeFromFilesOptions) => Promise<AnalyzeResultJson>;
 //# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAEN,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAEN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;OAMG;IACH,WAAW,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC3C,sEAAsE;IACtE,aAAa,EAAE,mBAAmB,CAAC;IACnC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAAU,SAAS,cAAc,KAAG,OAAO,CAAC,iBAAiB,CAwBhF,CAAC;AAIF;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAC5B,SAAS,uBAAuB,KAC9B,OAAO,CAAC,iBAAiB,CAwH3B,CAAC"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAEN,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAEN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;OAMG;IACH,WAAW,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC3C,sEAAsE;IACtE,aAAa,EAAE,mBAAmB,CAAC;IACnC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAAU,SAAS,cAAc,KAAG,OAAO,CAAC,iBAAiB,CAwBhF,CAAC;AAIF;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAC5B,SAAS,uBAAuB,KAC9B,OAAO,CAAC,iBAAiB,CAwH3B,CAAC"}

package/dist/analyze.js

@@ -1,8 +1,8 @@
 /**
  * One-shot analysis wrappers — `analyze` and `analyzeFromFiles`.
  *
- * Both wrap a single-use `AnalysisSession`: `createSession → setFiles → query
- * → dispose`. Incremental consumers (Vite plugin, LSP) should use
+ * Both wrap a single-use `AnalysisSession`: `createAnalysisSession → setFiles →
+ * query → dispose`. Incremental consumers (Vite plugin, LSP) should use
  * `createAnalysisSession` directly so parsed ASTs and svelte2tsx output
  * survive between calls.
  *
@@ -70,7 +70,9 @@ export const analyze = async (options) => {
  * 3. **Analysis** — `session.query()`
  *
  * @returns analyzed modules + concatenated ingest, discovery, and query diagnostics
- * @throws Error if `sourceOptions` validation fails or `tsconfig.json` is missing
+ * @throws Error on invalid or contradictory options, a missing `tsconfig.json`,
+ *   failed strict `'exports'` discovery, or a collision under
+ *   `onDuplicates: 'throw'`
  */
 export const analyzeFromFiles = async (options) => {
     const { projectRoot, include, exclude, resolveDependencies: shouldResolveDependencies = true, resolveImport, sourceOptions, onDuplicates, log, discovery, distDir } = options;

package/dist/cli.d.ts

@@ -36,12 +36,8 @@ export interface CliOptions {
      * File patterns to exclude (undefined = use defaults — test/spec files and
      * `internal/` directories).
      *
-     * When provided, **fully replaces** the defaults — no array merge. Passing
-     * a custom `--exclude` pattern drops the default test/spec/`internal/`
-     * filters unless the caller re-includes them explicitly (the API's
-     * exclude-callback form has no CLI equivalent). The always-on baseline
-     * (`node_modules` + dot-directories below a source path) applies beneath
-     * it and is unaffected by overrides.
+     * When provided, **fully replaces** the defaults (the API's callback form
+     * has no CLI equivalent) — see `ExcludeOption`.
      */
     exclude?: Array<string>;
     /** Output file path (undefined = stdout). */
@@ -105,7 +101,8 @@ export interface CliOptions {
  * Run the CLI with the given arguments.
  *
  * @param argv - command line arguments (defaults to `process.argv`)
- * @returns exit code: 0 for success, 1 if errors in diagnostics, 2 for CLI errors
+ * @returns exit code: 0 for success, 1 if errors in diagnostics, 2 for CLI errors or any
+ *   thrown analysis error (including an `--on-duplicates throw` collision)
  */
 export declare const runCli: (argv?: Array<string>) => Promise<number>;
 export {};

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAUhD,4CAA4C;AAC5C,QAAA,MAAM,oBAAoB,4BAA6B,CAAC;AACxD,KAAK,gBAAgB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAS9D;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB,sFAAsF;IACtF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAU,OAAM,KAAK,CAAC,MAAM,CAAgB,KAAG,OAAO,CAAC,MAAM,CA6N/E,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAUhD,4CAA4C;AAC5C,QAAA,MAAM,oBAAoB,4BAA6B,CAAC;AACxD,KAAK,gBAAgB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAS9D;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB,sFAAsF;IACtF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAU,OAAM,KAAK,CAAC,MAAM,CAAgB,KAAG,OAAO,CAAC,MAAM,CA6N/E,CAAC"}

package/dist/cli.js

@@ -24,7 +24,7 @@ import picomatch from 'picomatch';
 import { analyzeFromFiles } from './analyze.js';
 import { DEFAULT_SOURCE_OPTIONS } from './source-config.js';
 import { hasErrors } from './diagnostics.js';
-import { to_error_message } from './error.js';
+import { toErrorMessage } from './error.js';
 import { compactReplacer } from './declaration-helpers.js';
 /** Collect repeatable option values into an array. */
 const collect = (value, previous) => previous ? [...previous, value] : [value];
@@ -38,7 +38,8 @@ const isDiscoveryFlag = (value) => DISCOVERY_VALUES.includes(value);
  * Run the CLI with the given arguments.
  *
  * @param argv - command line arguments (defaults to `process.argv`)
- * @returns exit code: 0 for success, 1 if errors in diagnostics, 2 for CLI errors
+ * @returns exit code: 0 for success, 1 if errors in diagnostics, 2 for CLI errors or any
+ *   thrown analysis error (including an `--on-duplicates throw` collision)
  */
 export const runCli = async (argv = process.argv) => {
     // Track exit code from action (commander actions don't return values)
@@ -197,7 +198,7 @@ Examples:
         catch (error) {
             // Friendly one-line error for users; full stack only on DEBUG=1
             // so CI logs and bug reports can still capture it on demand.
-            const message = to_error_message(error);
+            const message = toErrorMessage(error);
             console.error(`error: ${message}`);
             if (process.env.DEBUG) {
                 console.error(error);