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, 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

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.

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).

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).

Falls back to appending .svelte when the bare specifier doesn't resolve — lets .svelte imports work without polluting the consumer's tsconfig.

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).

Extract class information with rich member metadata.

Extract dependencies and dependents for a module from source file info.

Filters to only include source modules (excludes external packages, node_modules, tests). Returns sorted arrays of module paths (relative to sourceRoot) for deterministic output.

Native paths in sourceFile.dependencies/dependents are accepted — isSource and extractPath posixify their inputs, so direct callers with hand-built input need not pre-normalize.

Accepts SourceFileInfo plus an optional dependents field — the public input type carries only dependencies (caller-supplied opt-in), while dependents is computed downstream by computeDependents and flows through as an enriched shape.

Extract enum member information from an enum declaration.

Iterates node.members to extract each enum member's name, initializer value, type, and JSDoc. Members are represented as MemberJson with kind 'variable'.

Extract function/method information including parameters with descriptions and default values.

Extract @module comment from HTML comments in Svelte source.

Scans all <!-- ... --> comments for one containing @module at the start of a line. This allows @component and @module to coexist as separate HTML comments. Works for template-only components.

Extract modifier keywords from a node's modifiers.

Returns an array of modifier strings like ['public', 'readonly', 'static'].

Extract module-level comment.

Extract module path relative to source root from absolute source ID.

Uses proper path semantics: strips projectRoot/sourceRoot/ prefix.

Extract the content of the main <script> tag from Svelte source.

Matches <script> with any attributes (e.g., lang, generics) but excludes module scripts (<script module>, <script context="module">).

Extract parameters from a TypeScript signature with TSDoc descriptions and default values.

Shared helper for extracting parameter information from both standalone functions and class methods/constructors.

Extract structured parameters from a Snippet<[...]> type.

Snippet is an interface, so type arguments are on TypeReference (accessed via checker.getTypeArguments), not on aliasTypeArguments (which is only for type aliases).

Returns full ParameterJson input objects (with optional and rest always set) for runtime consistency with extractSignatureParameters in typescript-extract-shared.ts.

Extract module-level comment from Svelte script content.

Parses the script content as TypeScript and delegates to extractModuleComment for the shared @module tag detection logic.

Extract properties from a type alias via the TypeScript checker API.

Handles object literals, intersections, mapped types (Partial, Pick, Readonly, etc.), type references, and function types. Extracts: - Named properties (with readonly/optional detection, TSDoc from declarations) - Index signatures (string/number) - Call signatures ((call)) - Construct signatures ((construct))

Extract type/interface information with rich property metadata.

Extract variable information.