api #

Persistent language-service handle that drives a ts.Program incrementally.

Owns the LS, document registry, and a Map<path, {content, version}> of "owned" files (real source files + virtuals pushed via setFile). Files not in the owned map are read from disk on demand by the LS host.

Each setFile(path, content) bumps the version when content differs from cache, so the next getProgram() reparses only the changed file. Calling getProgram() with no version bumps returns the same ts.Program as the previous call (reference-stable when nothing changed).

Options for createAnalysisLanguageService.

Minimal logger interface for analysis functions.

Intentionally narrow so that both @fuzdev/fuz_util's Logger class and Vite's built-in logger satisfy it without adapters or casts.

Options for createAnalysisProgram.

Persistent analysis handle.

Concurrency: not safe across overlapping calls. Serialize externally (each caller awaits the previous setFile/setFiles before starting the next). The LS underneath is sync, but the resolver phase awaits I/O for async resolvers (Vite/Rollup), so the session does cross await boundaries.

Cache-hit semantics: per-entry, all-or-nothing. The implementation must not split the guarantee across separate caches (e.g. transform-cache hit + lex re-run). The match criterion is mode-discriminated:

• lex+resolve mode: existing.content === incoming.content AND existing.resolverIdentity === incoming.resolverIdentity.
• pre-resolved mode: existing.content === incoming.content AND arraysShallowEqual(existing.preResolvedDepsSnapshot, incoming.dependencies).

Mode flips (an entry previously ingested as lex+resolve now arrives with dependencies, or vice versa) always cache-miss.

Promise resolution: setFile / setFiles resolve only after the serial LS push (phase 3) completes for every file in the batch. Awaiting the returned promise is sufficient — no separate flush step.

Options for createAnalysisSession.

documentRegistry flows through to the underlying LanguageService only. tsconfig and compilerOptions flow to both the LS *and* the lazy default ImportResolver (getDefaultResolver re-invokes loadTsconfig with them to produce a merged ts.CompilerOptions for module resolution). The two paths share the same merge semantics — user-supplied compilerOptions override parsed tsconfig keys, but never bypass the tsconfig.json file requirement.

projectRoot and virtualFiles from the LS options shape are excluded — the session derives projectRoot from sourceOptions and manages svelte2tsx virtuals internally per file.

Analyze library source files and extract metadata (one-shot).

Wraps a single-use AnalysisSession. For repeated analyses of the same source set (e.g., a Vite plugin reacting to file edits), use createAnalysisSession directly.

Run the two-phase analysis loop on pre-prepared inputs.

Inputs to analyzeCore. The caller (one-shot wrapper or session.query) is responsible for normalizing sourceOptions, obtaining the program, and pre-transforming Svelte files into svelteVirtualFiles.

transformFailedIds carries the IDs of .svelte files whose svelte2tsx transform threw at ingest. The dispatch synthesizes a placeholder ModuleJson (partial: true, empty declarations) for each so consumers see the file's existence in modules even though analysis couldn't run. Identifying these via a sibling Set keeps svelteVirtualFiles a clean "files we can analyze" map; the failure side-channel doesn't pollute it.

Analyze a TypeScript symbol and extract rich metadata.

This is a high-level function that combines TSDoc parsing with TypeScript type analysis to produce complete declaration metadata. Suitable for use in documentation generators, IDE integrations, and other tooling.

Analyze all exports from a TypeScript source file.

Extracts the module-level comment via extractModuleComment (skipped for svelte2tsx virtual files — see the inline note), star exports via extractStarExports, and all exported declarations with complete metadata. Handles re-exports by:

• Same-name re-exports: tracked in reExports for alsoExportedFrom building
• Renamed re-exports: included as new declarations with aliasOf metadata
• Star exports (export * from): tracked in starExports for namespace-level info
• Direct external re-exports: tracked in externalReExports/externalStarExports (specifier as written; import-then-export and source-chained forms stay silent)

This is a mid-level function (above the individual extract* helpers, below analyze) suitable for building documentation, API explorers, or analysis tools. For standard SvelteKit library layouts, use createSourceOptions(process.cwd()).

Analyze a library from files on disk with automatic file discovery.

Recommended high-level API for one-shot use (CLI, build-time generation):

1. Discovery — discoverSourceFiles (exports-first, glob fallback)
2. Ingest — push discovered files into a single-use session
3. Analysis — session.query()

Options for analyzeFromFiles.

Analyze a single non-Svelte source file and extract module metadata.

Options for analyze.

Requires pre-loaded SourceFileInfo arrays — use analyzeFromFiles for automatic file discovery and loading from disk, or createAnalysisSession for incremental use.

Result of analyze, analyzeFromFiles, and AnalysisSession.query.

Modules sorted alphabetically by path. Diagnostics are query-time (analysis-pass) diagnostics only when produced by session.query; one-shot wrappers concatenate ingest + query diagnostics into this same array.

Schema-validated round-trip

The envelope is a Zod schema (AnalyzeResultJson) — both fields default to [], so JSON.stringify(result, compactReplacer) strips empty arrays on the wire and AnalyzeResultJson.parse(JSON.parse(json)) restores them. Consumers programmatically ingesting analysis JSON should parse through the schema to get defaults restored; raw-JSON consumers (e.g., jq) treat missing keys as null-equivalent (jq '.diagnostics | length' returns 0 on {}) and don't need the parse step.

Construction sites (one-shot wrappers, session.query) hand back hand-built objects without re-running .parse() — the inner modules and diagnostics arrays are already Zod-validated upstream, and the envelope schema is the type contract, not a validation gate.

See AnalyzeResultJsonWire for the serialized input-side shape published on virtual:svelte-docinfo.

Serialized wire shape of an analysis result, as published by the Vite plugin on virtual:svelte-docinfo — the input-side counterpart to AnalyzeResultJson (the validated output of .parse()).

The two fields are deliberately asymmetric:

• modules is ModuleJsonInput (the z.input of ModuleJson) because the plugin runs it through compactReplacer, which strips .default([]) arrays and .default(false) booleans. Default-bearing fields therefore arrive undefined.
• diagnostics is the output Diagnostic — the plugin serializes it without the replacer, and Diagnostic has no defaults to strip, so the array is always present and the shape matches runtime exactly.

Consumers restore defaults by parsing through AnalyzeResultJson.

Note this describes the Vite virtual module specifically. The CLI runs the whole envelope through compactReplacer, so its JSON may additionally omit an empty diagnostics array — CLI consumers should parse through AnalyzeResultJson rather than assume this shape.

Analyzer type for source files.

• 'typescript' — TypeScript/JS files analyzed via TypeScript compiler API
• 'svelte' — Svelte components analyzed via svelte2tsx + TypeScript compiler API
• 'css' — CSS files included as modules with no declarations
• 'json' — JSON files included as modules with no declarations

Analyze a Svelte module using checker-backed analysis.

Requires the svelte2tsx virtual output to be included in the TypeScript program (via createAnalysisProgram({ virtualFiles })). Provides full type resolution for:

• Imported prop types (let {x}: ImportedProps = $props())
• <script module> exports (constants, types, re-exports)
• Star exports and re-exports from Svelte files

Analyze a TypeScript file and extract module metadata.

Wraps analyzeExports and adds dependency information via extractDependencies from the source file info if available.

This is a high-level function suitable for building documentation or library metadata. For lower-level analysis, use analyzeExports directly.

Apply parsed TSDoc metadata to a declaration.

Consolidates the common pattern of assigning TSDoc fields to declarations, with conditional assignment for array fields (only if non-empty).

Pre-compile identifier-boundary patterns for a set of declaration names.

When scanning many type strings against the same declaration set, call this once and pass the result to findTypeReferences to avoid recompiling regexes on every call.

Get diagnostics of a specific kind, narrowed to the matching variant.

A class declaration. Has members, extends, implements.

Class member analysis failed.

Clean raw JSDoc comment text by removing comment markers and leading asterisks.

Transforms /** ... *\/ style comments into clean text.

CLI options parsed from command line arguments.

JSON replacer that strips Zod default values for compact serialization.

Strips empty arrays and false booleans — both are Zod .default() values restored on .parse(), so the round-trip is lossless for svelte-docinfo types. Assumes all boolean fields in the schema default to false — a true-defaulted boolean would need its false values preserved, breaking the round-trip.

Root-value caveat: JSON.stringify([], compactReplacer) returns the JS undefined (not the string '[]'), and JSON.stringify(false, compactReplacer) returns the JS undefined too. Object-rooted callers (AnalyzeResultJson envelope, CLI output) don't hit this — empty inner arrays strip and AnalyzeResultJson.parse restores them on the consumer side. Array-rooted callers (Vite plugin, anyone splicing the JSON into a source template) must handle the empty case themselves before calling this; see vite.ts:updateOutputFromQuery for the pattern.

Two guard tests in declaration-helpers.test.ts lock this in:

• every z.boolean().default in types.ts uses false — source-regex check that fails on a new z.boolean().default(true).
• `parse → stringify(compactReplacer) → parse is a faithful round-trip across every variant` — exercises every variant and member through a full round-trip, catching regressions where a .default(false) or .default([]) is removed (or a new field is added that the replacer drops but Zod doesn't restore).

Case-insensitive string comparator for deterministic output ordering.

Case-folded comparison first (so Analyze and analyze sort together instead of all uppercase before all lowercase), then a code-unit tiebreak — so equal-ignoring-case strings still compare unequal and the result is an exact total order. Unlike localeCompare (host-locale/ICU-dependent, so byte-identical input can serialize in different orders on different machines), both passes use Unicode default mappings only and are environment-independent. All output ordering goes through this comparator — never bare localeCompare or default Array.prototype.sort.

A Svelte component declaration. Has props, intersects, acceptsChildren.

Component prop information for Svelte components.

Standalone schema (not extending ParameterJson) because component props have different semantics: named attributes with no positional order (<Foo {a} {b} /> = <Foo {b} {a} />), no rest parameters, and support for two-way binding via $bindable rune.

Compute bidirectional dependencies from source files.

This function ensures that if file A has file B in its dependencies, then file B will have file A in its dependents. This provides consistent output regardless of whether callers provide one-directional or bidirectional dependency information.

Returns new SourceFileInfo objects when computed dependents exist or when paths needed posixification; otherwise the original input objects flow through ===-equal (fast path for session callers, who already pass POSIX paths and may have no inferable dependents for a given file).

A constructor member (class constructor, construct signature). Has parameters, overloads — but not returnType/returnDescription (constructors always return their class).

name is narrowed to two literal sentinels: 'constructor' for class constructors and '(construct)' for interface/type-alias construct signatures (which share kind: 'constructor' but originate from getConstructSignatures() on a non-class type — no user-chosen identifier exists). The literal is preserved (rather than omitted) so getDisplayName and consumer renderers reading member.name keep working without a constructor-specific branch.

Create a persistent language service for incremental analysis.

The LS owns parsed source ASTs and checker state across calls. Use the returned handle to push file-content updates (setFile / deleteFile) between analysis passes; subsequent getProgram() calls return either the same ts.Program (no changes since last call) or a fresh one that reuses unchanged files via the document registry.

Create TypeScript program for one-shot analysis.

Use createAnalysisLanguageService instead when you need to analyze the same source set multiple times — the LS path reuses parsed ASTs and checker state across calls.

Create a persistent analysis session.

Create the default ImportResolver (TypeScript + tsconfig).

Uses ts.resolveModuleName against ts.sys directly — no ts.Program is built. Identity is a fresh symbol per call, so each session that constructs its own default gets a unique cache scope. Multiple sessions sharing one resolver instance share the cache scope (correct, since resolver state is shared too).

ts.resolveModuleName cannot resolve real .svelte files (no compiler option teaches it the extension), so relative and absolute .svelte specifiers — with or without the extension written — fall back to manual filesystem resolution against fromFile. Non-relative .svelte specifiers (tsconfig paths aliases, package subpaths) stay unresolved; supply a custom resolveImport for those setups.

Create an IsExternalFile predicate from ModuleSourceOptions.

A file is external if it is:

• Outside the project root
• Inside node_modules/
• A .d.ts declaration file outside the source root (catches framework-generated declarations like .svelte-kit/non-ambient.d.ts while keeping user .d.ts files in the source tree)

Create complete, normalized, validated source options from project root and optional overrides.

Merges overrides with DEFAULT_SOURCE_OPTIONS, then normalizes via normalizeSourceOptions — so the returned object always has an absolute projectRoot, slash-stripped path entries, and an explicit sourceRoot (auto-derived for multi-path layouts). Throws on validation failure.

Result of analyzing a single declaration.

Produced by analyzeDeclaration (in typescript-exports.ts) and Svelte component analysis. Used by analyzeModule to filter @nodocs declarations before output.

Uses DeclarationJsonBuild (not DeclarationJsonInput) because declarations are constructed incrementally — Zod validation happens at the ModuleJson.parse() boundary.

Metadata for an exported declaration (function, type, class, component, etc.).

Discriminated union on kind — each variant has only the fields relevant to that kind. Use isKind (in declaration-helpers.ts) to narrow, or check declaration.kind directly.

Permissive type for constructing declarations incrementally before Zod validation.

Used by internal analysis functions (analyzeDeclaration, extractFunctionInfo, etc.) that build declarations by mutating a plain object. The discriminated union schema validates the final shape at the ModuleJson.parse() boundary.

The kind of top-level exported declaration.

Does not include 'constructor' — constructors only appear as MemberKind (nested in classes, interfaces, or types with construct signatures), never as top-level module exports.

TypeScript modifier keywords extracted from declarations.

Only modifiers that appear on public API members are included. Private members (including #field syntax) are filtered out during analysis. Protected members are included as part of the extension API.

Default partial options for standard SvelteKit library structure.

Does not include projectRoot — use createSourceOptions to create complete options with your project root.

exclude is the single source of truth for filtering: globs applied at both discovery time (by globFiles/discoverFromExports) and analysis time (by isSource() against project-root-relative paths).

Build an include pattern array from source paths.

Each path becomes a <path>/**\/*.{ts,js,svelte,css,json} glob. Used by discoverSourceFiles to derive a default include from sourceOptions.sourcePaths when no explicit pattern is supplied — keeps the glob fallback consistent with custom sourcePaths instead of silently defaulting to src/lib.

Detect a Svelte 5 reactivity rune from a variable or property initializer.

Inspects the AST since runes erase to their inner type after type-checking. Returns undefined for any non-rune expression. See the Reactivity enum in types.ts for the rationale on running this on every file regardless of extension.

Discriminated union of all diagnostic variants.

Discriminant for Diagnostic variant types.

Diagnostic severity levels.

• 'error' — analysis failed, declaration may be incomplete or missing data
• 'warning' — partial success, something seems off but analysis continued

Discover source files using package.json exports field.

Reads package.json, parses exports, maps dist paths to source paths, expands wildcard patterns, and loads file content.

Returns {files: null} when no package.json or no exports field exists, signaling the caller to fall back to glob discovery. Returns {files: []} when exports exist but resolve no source files (likely misconfigured mapping).

For concrete exports, maps directly to source paths and verifies existence. For wildcard exports, globs the source directory for matching files.

Discover source files from a project root.

Used internally by analyzeFromFiles for the discovery step. Standalone consumers can call it directly when they want the discovered file list without running full analysis.

Strategy is selected by discovery:

• 'auto' (default) — try exports first, fall back to glob.
• 'exports' — exports only; throws if exports is missing or resolves to no source files. Combining with include is a configuration error and also throws.
• 'glob' — glob only; include parameterizes the search.

Exclusion globs come from sourceOptions.exclude (the single source of truth, also applied at analysis time by isSource()).

Options for discoverSourceFiles.

Result of discoverSourceFiles.

Discovery strategy for source files.

• 'auto' (default) — try package.json exports first, fall back to glob patterns when exports is missing or resolves to nothing
• 'exports' — package.json exports only, throw if exports is missing or resolves to no source files (strict mode for libraries that should always declare their public surface via exports)
• 'glob' — skip exports entirely, use glob patterns

Providing include patterns implies 'glob' semantics regardless of mode — when discovery: 'auto' and include is set, the auto fallback chain collapses to glob immediately. Combining discovery: 'exports' with include is a configuration error (the modes are contradictory) and throws at discovery time.

Duplicate comment sources detected (e.g., both HTML and JSDoc @module, or both HTML @component and JSDoc for component docComment).

A duplicate declaration with its full metadata and module path.

A declaration name appears in more than one module.

Library docs assume a flat namespace — two modules exporting the same name collide when consumers import {name}. Emitted at warning severity so the analysis result remains usable; consumers who want it fatal can promote via onDuplicates: 'throw' or by inspecting the diagnostic. The default slot (name === 'default') is excluded — every module owns its own.

Append a (call) or (construct) signature member to a declaration.

Captures the extraction logic shared by interface processing (extractTypeInfo) and type-alias property processing (extractTypeAliasProperties): type signature, parameters, generics, overloads, and TSDoc. The TSDoc source node is supplied by the caller — interfaces look it up in node.members (skipping TSDoc when no inline signature is declared, even if one is inherited), type aliases use sig.getDeclaration().

Ensure es-module-lexer's wasm runtime is initialized.

Idempotent and cheap after the first call. The session awaits this once at the top of setFiles so phase 1's per-file lex is purely synchronous.

An enum declaration. Has members for enum values.

Get all error-severity diagnostics.

A parsed entry from package.json exports field.

Options for discoverFromExports.

Result of discovering source files from package.json exports.

Self-contained: includes both the discovered files and any error diagnostics (e.g., files that exist but could not be read).

A module's resolved export surface — see resolveExportSurface.

One name on a module's resolved export surface.

A re-export whose immediate target is outside the analyzed source set — export {x} from 'pkg', export {x as y} from 'pkg', or export * as ns from 'pkg'.

specifier is the module specifier as written (usually a package name); there is no canonical declaration to resolve, so these entries are flat facts about the statement rather than edges into the module graph.

Only statements that *directly* reference the external specifier are captured. Forms that stay silent: import {x} from 'pkg'; export {x}; (import-then-export), re-export chains that reach a package through another source module (that module owns the entry), and specifiers the checker can't resolve. Statement-level @nodocs suppresses the entry.