Published as svelte-docinfo to npm:

The tool's main function is outputting JSON, and there are several integration paths, in rough order from most opinionated to most flexible:

For SvelteKit and Vite projects, the Vite plugin is the recommended path. It runs the analysis at build time and serves the result as a virtual module with HMR:

Run the CLI to inspect a project from the command line:

For standalone use or custom build tools, two functions cover most cases. analyzeFromFiles handles file discovery automatically:

If your build tool already has file contents in memory, use analyze directly to skip file discovery. See the build tools guide for the full integration surface:

For long-lived consumers (Vite plugin, LSP-style tools) that re-analyze the same source set repeatedly, createAnalysisSession returns a persistent handle backed by a TypeScript LanguageService. Parsed ASTs and svelte2tsx output are reused across calls. The one-shot analyze and analyzeFromFiles are thin wrappers over single-use sessions. See the session guide for the full incremental API.

See the API reference for all exported functions and types.

A few constructs are silently skipped: standalone namespace Foo {} declarations (namespace re-exports are supported), decorators, and per-parameter doc fields beyond @param descriptions. ParameterJson deliberately doesn't carry @example/@deprecated/@since/@see/@throws. Per the TSDoc spec, those tags are scoped to the function symbol and live on the parent declaration.

• full type resolution: infers complex types without manual annotations, including generics, imported types, and inferred return types, with source locations for every declaration
• TSDoc/JSDoc parsing: extracts standard tags (@param, @returns, @example, @deprecated, etc.) plus @nodocs to exclude from docs and @mutates to flag side effects
• Svelte 5 components: analyzes components via svelte2tsx, extracting prop types, defaults, bindability, snippet parameters, children detection, and exported template snippets
• Svelte 5 reactivity runes: detects $state, $state.raw, $derived, and $derived.by on variables and class fields and exposes them via the reactivity field. Detection is syntactic, so the same patterns can be captured in any analyzed file
• re-export tracking: alsoExportedFrom arrays, aliasOf for renames, default-slot entries named "default", and export * from patterns
• dependency graphs: tracks imports between modules and computes dependents
• function overloads: captures all public overload signatures with per-overload JSDoc
• build-tool agnostic: works with any source: file system, build pipeline, or in-memory
• diagnostic collection: accumulates warnings and errors without halting, so you can report problems in batch

svelte-docinfo is largely inspired by sveld, a Svelte component documentation generator that walks the AST and infers types from JSDoc annotations and literal values. svelte-docinfo instead uses the TypeScript compiler API (via svelte2tsx) as its source of truth, so it resolves imported types, generics, and complex inferred types without requiring @type annotations. It also analyzes TypeScript modules, not just .svelte files.

svelte-docinfo additionally tracks re-exports across modules, computes dependency graphs, and records source locations. It does not currently support Svelte 4 features like legacy slots, dispatched events, or the context API. Svelte 5 replaces most of these with snippets and callback props.

Discovery defaults to package.json exports, falling back to glob. -i forces explicit patterns; --discovery glob skips exports; --discovery exports is strict (fails when exports is missing).

--source-dir sets the source directory (default src/lib, repeatable for monorepos) and seeds the implicit include glob. --source-root controls module-path stripping in the output (defaults to the single --source-dir or their longest common prefix).

Compact JSON pairs well with jq:

JSON goes to stdout; info, warnings, and errors go to stderr, so the terminal interleaves them, but > and | capture clean JSON. -q/--quiet silences info; warnings and errors still print.

Exit codes: 0 success, 1 analysis errors, 2 CLI errors.

• Arrows point from importer to imported: X depends on Y. Reads with gravity, so dependencies fall downward toward the foundation.
• Layers are assigned by longest-path-from-sink. A module's layer is one plus the deepest layer it transitively depends on. Sinks (no internal imports) land at the bottom.
• Hover a module to isolate its immediate neighbors. Edges split by direction: what the module depends on and what depends on it.

The bottom rows are the primitives that nothing in the library depends on transitively: path normalization, types, concurrency caps, the diagnostics schema. The middle rows are the per-kind TypeScript extractors and the file-system helpers. The top rows are the orchestrators: the persistent session on top of core analysis, then the one-shot wrappers, then the vite plugin and cli entries.

Across 30 modules and 69 internal imports, the graph is naturally acyclic, so no back-edges had to be reversed to lay it out.

The layout is precomputed at build time by dependency_graph.gen.json.ts, which reads library.json (itself generated by library.gen.ts via analyze) and runs a Sugiyama-style layered layout: longest-path-from-sink for layer assignment, dummy nodes on long edges, median-heuristic crossing reduction. The result is a small JSON sibling the Svelte component renders to SVG. No layout libraries. About 300 lines, end to end.

Programmatic entry points (analyze, analyzeFromFiles) return both modules and accumulated diagnostics:

All surfaces emit this shape. The CLI's stdout JSON and the Vite plugin's virtual module both expose modules and diagnostics (matching AnalyzeResultJson). The CLI runs output through compactReplacer so empty arrays strip on the wire (an empty-project run emits {}); parse JSON consumers through AnalyzeResultJson to restore Zod defaults.

A ModuleJson describes a single source file and its exports:

• path: file path relative to the source root (e.g., "math.ts")
• declarations: exported items from this module
• moduleComment: file-level JSDoc comment, if present
• dependencies: paths of modules this file imports
• dependents: paths of modules that import this file
• starExports: export * from './module' patterns

Array fields (declarations, dependencies, etc.) are omitted from JSON when empty and default to [] at runtime after parsing.

Each declaration is a DeclarationJson, a discriminated union on the kind field with nine variants:

• "function": adds parameters, returnType, returnDescription, overloads
• "variable": adds optional defaultValue (from @default), plus reactivity when the initializer is a Svelte rune ($state, $state.raw, $derived, $derived.by)
• "class": adds members, extends, implements
• "interface": adds members, extends
• "type": adds members, intersects
• "enum": adds members (enum values)
• "component": adds props, intersects, acceptsChildren, lang (Svelte components)
• "snippet": adds parameters (exported Svelte template snippets)
• "namespace": adds module (the source module path projected under this binding); synthesized for export * as ns from './x'

Shared fields on all variants:

• name, kind: identity. Default exports carry name === "default" (see Re-exports below)
• docComment: JSDoc comment text
• typeSignature: full type as a string
• sourceLine: line number in the source file
• modifiers: e.g., "readonly", "static", "getter"
• genericParams: type parameters with constraints and defaults
• examples, deprecatedMessage, seeAlso, throws, since: from standard JSDoc tags
• mutates: from the non-standard @mutates tag, stored as Record<string, string> mapping target keys to descriptions. Keys are typically parameter names but compound paths (this.foo) and external state references are accepted as-is
• alsoExportedFrom: modules that re-export this declaration
• aliasOf: original name if this is a renamed re-export
• partial: true when extraction failed partway through the declaration, indicating incomplete data

Declarations tagged with @nodocs are excluded from the output entirely and are also excluded from duplicate name checking.

Re-exports are encoded with two shapes, chosen by content:

• Same-name: the canonical declaration carries an alsoExportedFrom array listing the modules that re-export it. One declaration, multiple import paths.
• Renamed: a synthesized declaration appears in the re-exporting module with aliasOf: {module, name} pointing at the canonical. Inherits typeSignature, docComment, parameters, reactivity, and defaultValue from the canonical; sourceLine is undefined.
• Star exports: export * from './x' patterns are tracked separately on ModuleJson.starExports and don't synthesize per-declaration entries.

When a re-export statement carries its own JSDoc or @nodocs, an alias is also synthesized in the re-exporting module so the local content has somewhere to live, even when the name is unchanged. The trigger is "presence of local content," not "presence of rename." Local doc-comment fields apply first and stick; canonical fields only fill gaps. @nodocs on a re-export suppresses both the link and the synthesis.

Default-slot entries carry name === "default" (see the shared-fields note above for why). Renames out of the default slot (export {default as Foo} from './x') carry name: "Foo" and aliasOf: {module, name: "default"}. Duplicate-name checks skip "default" since the default slot is module-scoped per the JS spec.

Namespace re-exports (export * as ns from './x') synthesize a NamespaceDeclarationJson with module pointing at the source the namespace projects. Consumers render ns.a / ns.b by reading the source module's declarations; namespaces don't inline members.

Classes, interfaces, types, and enums can contain MemberJson entries in their members arrays. MemberJson is a discriminated union on kind with three variants:

• "function": methods and call signatures. Adds parameters, returnType, returnDescription, overloads
• "constructor": class constructors and construct signatures. Adds parameters, overloads
• "variable": properties, accessors, and index signatures. Adds optional defaultValue (from @default), plus reactivity for class fields initialized with a Svelte rune

Member kind is restricted to these three variants. Nesting is exactly one level deep: members never contain their own members.

Member name is the user-chosen identifier in most cases, but three synthesized sentinels appear when no source identifier exists: "constructor" (class constructor), "(construct)" (construct signature on an interface or type alias), and "(call)" (call signature on an interface or type alias).

Component declarations have a props array of ComponentPropJson entries:

• name, type: prop name and TypeScript type
• optional: whether the prop is optional
• description: from JSDoc on the prop
• defaultValue: default value as a string, if present
• bindable: set when the prop is declared with the $bindable() rune, so <Foo bind:value /> is supported. Modeled here (not via the variable-level reactivity field) because $props/$bindable are component-prop concerns
• parameters: structured parameters for snippet-typed props (e.g., Snippet<[text: string]>), absent for non-snippet props
• examples, deprecatedMessage, seeAlso, throws, since: symbol-scope JSDoc tags parsed from the prop's own doc comment (same shape as the declaration shared fields)

Asymmetry with ParameterJson. Props carry the symbol-scope tag fields above; function parameters deliberately don't. A prop is a named slot with its own documentation surface. A parameter is positional, and its @example/@deprecated/@since/@see/@throws belong on the enclosing function symbol per the TSDoc spec. Per-parameter content lives on ParameterJson.description from @param only.

Functions, snippets, constructors, and snippet-typed component props use ParameterJson entries in their parameters arrays:

• name: parameter name (e.g., "options", "...args")
• type: resolved TypeScript type as a string
• optional: whether the parameter has a ? token
• rest: whether the parameter uses rest syntax (...args)
• description: from @param JSDoc
• defaultValue: default value expression from the source, if present

Functions and constructors with multiple signatures use OverloadJson entries in their overloads arrays. Each overload captures only signature-scope content, the fields that can vary meaningfully per signature:

• typeSignature: the full overload signature as a string
• parameters: parameter list for this overload, with per-overload @param descriptions
• returnType: return type for this overload (functions only)
• genericParams: type parameters for this overload
• docComment: per-overload JSDoc text, if present
• returnDescription: from @returns on this overload

Symbol-scope JSDoc tags (@example, @deprecated, @since, @see, @throws, @mutates) describe the function as a whole and live on the parent declaration only, not duplicated per overload. The primary overload's JSDoc feeds the parent's symbol-level extraction; placing one of those tags on a non-primary overload signature emits a misplaced_tag warning and the tag is dropped (no synthetic content, no silent loss). Typo'd or stale @param keys produce unknown_param warnings the same way.

The reactivity field appears on VariableDeclarationJson and VariableMemberJson when the initializer is a value-producing Svelte rune call: $state, $state.raw, $derived, or $derived.by. Detection is purely syntactic and runs on every analyzed file regardless of extension, capturing the same patterns in a plain .ts file as in .svelte.ts or a component's <script>.

It covers variables (top-level and class fields). Function parameters and destructured bindings are not annotated even when the value flows from a rune. $props and $bindable are component-prop concerns and surface on ComponentPropJson's bindable field instead.

Declarations and members with type parameters use GenericParamJson entries in their genericParams arrays:

• name: type parameter name (e.g., "T")
• constraint: extends constraint, if present
• defaultType: default type, if present

Type signatures are opaque strings produced by the TypeScript compiler. To discover which in-project declaration names appear in a type string (e.g., for rendering clickable links), use findTypeReferences:

When scanning many type strings against the same set of names, pre-compile the patterns with buildTypeReferencePatterns to avoid recompiling regexes on every call.

By default, output uses compact JSON via compactReplacer: empty arrays, false booleans, and undefined fields are stripped, so optional, acceptsChildren, partial, rest, bindable, and similar fields vanish from the wire form when their value is the default. After parsing with the Zod schemas from types.ts (or AnalyzeResultJson for the full {modules, diagnostics} envelope), all defaults are restored, and the round-trip is lossless.

Raw-JSON consumers (e.g., jq, hand-rolled pipelines that skip .parse()) must treat absent as false; a literal decl.optional === false check silently fails because the key is gone. Use the schemas, or truthy/falsy checks (if (decl.optional) …) on raw JSON.

A TypeScript function:

A Svelte component with a snippet prop, children, and an exported snippet:

A rune module exporting reactive state (e.g., a .svelte.ts file):

A function defined in math.ts and re-exported under a new name from the barrel index.ts. The canonical entry carries alsoExportedFrom if any module re-exports it under the same name. Renames synthesize a separate declaration with aliasOf:

See the types module for the full Zod schemas, and the API reference for all exported types.

Two tags vary per overload signature; the rest describe the symbol as a whole.

• Signature-scope: @param and @returns. These flow to the matching overload's parameters[i].description / returnDescription. Each overload can carry its own.
• Symbol-scope: @example, @deprecated, @since, @see, @throws, @mutates, @default, @nodocs. These describe the symbol as a whole and live on the parent declaration only.

Placing a symbol-scope tag on a non-primary overload emits misplaced_tag and the tag is dropped, with no synthetic content and no silent loss. Move it to the primary signature (typically the first overload, or the implementation signature's JSDoc which feeds the symbol-level extraction). See diagnostics for the diagnostic details.

@param keys are matched against actual parameter names. The leading - separator is stripped (TypeScript's parser keeps it as syntax, not content). Destructured parameters match the outer binding name, not inner properties.

When a key doesn't match any parameter (a typo, a stale doc after a rename, or a description of a destructured property), the description is dropped and an unknown_param diagnostic fires with the orphaned key. Fix the JSDoc rather than relying on the silent fallback.

Non-standard tag for documenting mutations to parameters or external state. Same key - description format as @param, but keys are not validated against the parameter list. Anything goes:

• a parameter name: @mutates options - sets defaults in place
• a compound path: @mutates this.cache - inserts the result
• an external state reference: @mutates global_registry - registers the handler

The output is a Record<string, string> mapping each key to its description. Consumers decide how to render or group by key shape.

@nodocs on a declaration removes it from the analysis output entirely. Two follow-on effects:

• Flat-namespace duplicate checking skips it: a hidden helper named parse can coexist with a public parse in another module without triggering duplicate_declaration.
• Re-export synthesis is suppressed: @nodocs on a re-export statement drops both the alsoExportedFrom link and any synthesized alias declaration. The canonical entry stays untouched.

A comment tagged @module attaches to the file rather than to the next declaration. The text lands on ModuleJson.moduleComment and is suppressed from any declaration docComment that might otherwise capture it.

Svelte files have a second module-comment source: an HTML comment directly above <script>. When both an HTML and a JSDoc @module comment supply a value for the same target, duplicate_comment fires with commentType: "module_comment". The same diagnostic covers declaration-level collisions (commentType: "doc_comment").

A re-export that carries its own JSDoc synthesizes an alias in the re-exporting module so the local content has somewhere to live, even when the name is unchanged. See Re-exports for the full encoding rules and merge order.

Three diagnostic kinds surface tag-handling problems:

• misplaced_tag: symbol-scope tag on a non-primary overload signature
• unknown_param: @param key with no matching parameter
• duplicate_comment: two sources supplied a comment for the same target (HTML + JSDoc @module, or any other collision)

All three are warnings; analysis still completes and the declaration is included. See tsdoc.ts for the parser internals and diagnostics for the full diagnostic schema.

Accumulated (non-fatal): appended to the Diagnostic array, analysis continues. Covers type resolution failures, member or prop extraction failures, and JSDoc tag misuse. The return value is still valid but may carry partial: true on affected declarations.

Thrown (fatal): a small set of setup-level conditions throws from public entry points: missing tsconfig.json, Svelte <5 detected, or discovery: 'exports' mode with no resolvable exports. Wrap the top-level analyze / analyzeFromFiles call if you want to handle these. svelte2tsx transformation failures are not thrown; they flow as transform_failed diagnostics.

diagnostics is a plain Array<Diagnostic>, no wrapper, no methods. Round-trips through JSON.stringify / z.array(Diagnostic).parse, so it serializes alongside modules in CLI output and rehydrates cleanly.

Each Diagnostic carries:

• kind: discriminant, one per failure mode (see table below)
• severity: "error" or "warning"
• file: POSIX-form, project-relative (no leading ./). Rejoin with projectRoot for absolute paths.
• line, column: 1-based, optional. Absent when there's no precise AST node (e.g., a module-level skip)
• message: human-readable description
• additional fields specific to the variant: symbolName, className, tagName, etc.

Severity is stable per kind: every kind below is warning severity except transform_failed and module_unreadable, which are always error.

Each variant is a strict Zod object with its own extra fields. Use byKind to narrow to a specific variant for typed access:

severity says how loud to be about a problem; partial: true says a specific declaration or member has incomplete data, typically from type_extraction_failed, signature_analysis_failed, class_member_failed, or svelte_prop_failed. Branch on partial directly; no need to cross-reference diagnostics by file and line.

The diagnostics array is a plain Array<Diagnostic>: construct with [] and mutate with Array.push. Read helpers:

• hasErrors, hasWarnings: boolean checks by severity
• errorsOf, warningsOf: filter by severity
• byKind: filter by kind, narrowed to the matching variant
• formatDiagnostic: format as './file.ts:10:5: error: message' (the './' prefix is fixed)

The CLI always emits the structured diagnostics field alongside modules in JSON output, and also prints warnings and errors to stderr:

Programmatically:

The Vite plugin's virtual module exports both modules and diagnostics, so SvelteKit apps can render a doc-warnings page without re-running analysis:

Optional scalar fields (line, column) drop on serialize per the same compact-output rules as the rest of the schema. See output format for the full rule. The Vite plugin's virtual module exposes modules and diagnostics as separate ES module exports, so they're always present even when empty. See diagnostics.ts for the Zod schemas and helper signatures.