svelte-docinfo 0.1.0

package/dist/source.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Source file type predicates and path helpers.
+ *
+ * Pure functions for detecting file types by extension and extracting
+ * component names from paths. No configuration dependency — these are
+ * the building blocks used by `source-config.ts`.
+ *
+ * @see `source-config.ts` for configuration-aware functions (`isSource`, `extractPath`, etc.)
+ * @see `analyze.ts` for consumers (`analyze`, `analyzeFromFiles`)
+ *
+ * @module
+ */
+/**
+ * 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
+ */
+export type AnalyzerType = 'typescript' | 'svelte' | 'css' | 'json';
+/**
+ * File information for source analysis.
+ *
+ * Provides file content to analysis functions from any source:
+ * file system, build pipeline, or in-memory.
+ *
+ * Note: `content` is required to keep analysis functions pure (no hidden I/O).
+ * Callers are responsible for reading file content before analysis.
+ */
+export interface SourceFileInfo {
+    /** Absolute path to the file. */
+    id: string;
+    /** File content (required - analysis functions don't read from disk). */
+    content: string;
+    /**
+     * Pre-resolved absolute file paths of modules this file imports.
+     *
+     * **Opt-in optimization** — when supplied, the session treats this as the
+     * authoritative dependency set for the file and skips its own lex+resolve
+     * pass for this entry. Build-tool integrations (e.g., Gro's filer) that
+     * already maintain a dependency graph can hand it over directly instead of
+     * paying the lex+resolve cost twice.
+     *
+     * **Omit (undefined) → default behavior** — the session lexes import
+     * specifiers from `content` and resolves them via its `ImportResolver`.
+     * This is the right choice when the caller doesn't already have a graph.
+     *
+     * Only include resolved local imports — node_modules paths are filtered
+     * out at storage time by the configured `isSource` predicate either way.
+     *
+     * **Trust contract** — the session treats this array as authoritative and
+     * does not cross-check against the file's `content`. Edges declared here
+     * are accepted as-is, even if the source code doesn't actually import them;
+     * edges that *are* in `content` but missing from this array are silently
+     * omitted. The lex+resolve fallback path has no such hole — its edges are
+     * always grounded in syntactic imports. Build-tool integrations that
+     * supply this field own the correctness of the graph they hand over.
+     *
+     * Type-only imports (`import type {...}`) are the most common asymmetry
+     * versus the lex+resolve path: the default lex (`es-module-lexer`) keeps
+     * them; pre-resolved callers backed by a Gro-style filer typically drop
+     * them. Both are intentional within their respective contracts.
+     *
+     * Cache semantics: the session compares this array element-wise (shallow
+     * equality) against the snapshot stored from the prior call — a fresh
+     * array with identical contents cache-hits, while any length, element, or
+     * order difference invalidates. Callers that produce fresh arrays per
+     * call (e.g., Gro's `[...filer.dependencies.keys()]`) reuse the cache
+     * cleanly across persistent-session calls.
+     *
+     * Order is significant. Reordering without a content change is treated
+     * as a real change — sort upstream if you want order-insensitive caching.
+     * Map-iteration-order callers (e.g., a Gro filer emitting
+     * `[...filer.dependencies.keys()]`) are naturally stable across calls for
+     * the same content, so no defensive sort is needed there.
+     */
+    dependencies?: ReadonlyArray<string>;
+}
+/**
+ * Default analyzer resolver based on file extension.
+ *
+ * - `.svelte` → `'svelte'`
+ * - `.ts`, `.js` → `'typescript'`
+ * - `.css` → `'css'`
+ * - `.json` → `'json'`
+ * - Other extensions → `null` (skip)
+ */
+export declare const getDefaultAnalyzer: (path: string) => AnalyzerType | null;
+/**
+ * Extract component name from a Svelte module path.
+ *
+ * @example
+ * ```ts
+ * getComponentName('Alert.svelte') // => 'Alert'
+ * getComponentName('components/Button.svelte') // => 'Button'
+ * ```
+ */
+export declare const getComponentName: (modulePath: string) => string;
+/**
+ * Check if a path is a TypeScript or JS file.
+ *
+ * Includes both `.ts` and `.js` files since JS files are valid in TS projects.
+ * Excludes `.d.ts` declaration files — use a custom `getAnalyzerType` to include them.
+ */
+export declare const isTypescript: (path: string) => boolean;
+/** Check if a path is a Svelte component file. */
+export declare const isSvelte: (path: string) => boolean;
+/** Check if a path is a CSS file. */
+export declare const isCss: (path: string) => boolean;
+/** Check if a path is a JSON file. */
+export declare const isJson: (path: string) => boolean;
+/**
+ * Suffix appended to `.svelte` file paths to create virtual TypeScript file paths.
+ *
+ * Used by svelte2tsx integration: `Component.svelte` → `Component.svelte.__svelte2tsx__.ts`.
+ */
+export declare const SVELTE_VIRTUAL_SUFFIX = ".__svelte2tsx__.ts";
+/**
+ * Strip the svelte2tsx virtual file suffix from a path, if present.
+ *
+ * Maps `Component.svelte.__svelte2tsx__.ts` back to `Component.svelte`.
+ * Returns the path unchanged if the suffix is not present.
+ */
+export declare const stripVirtualSuffix: (path: string) => string;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,YAAY,GAAG,IAMhE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,YAAY,MAAM,KAAG,MACG,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,OAC8B,CAAC;AAE3E,kDAAkD;AAClD,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,OAAmC,CAAC;AAE5E,qCAAqC;AACrC,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,KAAG,OAAgC,CAAC;AAEtE,sCAAsC;AACtC,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,KAAG,OAAiC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,MACyC,CAAC"}

package/dist/source.js

@@ -0,0 +1,68 @@
+/**
+ * Source file type predicates and path helpers.
+ *
+ * Pure functions for detecting file types by extension and extracting
+ * component names from paths. No configuration dependency — these are
+ * the building blocks used by `source-config.ts`.
+ *
+ * @see `source-config.ts` for configuration-aware functions (`isSource`, `extractPath`, etc.)
+ * @see `analyze.ts` for consumers (`analyze`, `analyzeFromFiles`)
+ *
+ * @module
+ */
+/**
+ * Default analyzer resolver based on file extension.
+ *
+ * - `.svelte` → `'svelte'`
+ * - `.ts`, `.js` → `'typescript'`
+ * - `.css` → `'css'`
+ * - `.json` → `'json'`
+ * - Other extensions → `null` (skip)
+ */
+export const getDefaultAnalyzer = (path) => {
+    if (isSvelte(path))
+        return 'svelte';
+    if (isTypescript(path))
+        return 'typescript';
+    if (isCss(path))
+        return 'css';
+    if (isJson(path))
+        return 'json';
+    return null;
+};
+/**
+ * Extract component name from a Svelte module path.
+ *
+ * @example
+ * ```ts
+ * getComponentName('Alert.svelte') // => 'Alert'
+ * getComponentName('components/Button.svelte') // => 'Button'
+ * ```
+ */
+export const getComponentName = (modulePath) => modulePath.replace(/^.*\//, '').replace(/\.svelte$/, '');
+/**
+ * Check if a path is a TypeScript or JS file.
+ *
+ * Includes both `.ts` and `.js` files since JS files are valid in TS projects.
+ * Excludes `.d.ts` declaration files — use a custom `getAnalyzerType` to include them.
+ */
+export const isTypescript = (path) => (path.endsWith('.ts') && !path.endsWith('.d.ts')) || path.endsWith('.js');
+/** Check if a path is a Svelte component file. */
+export const isSvelte = (path) => path.endsWith('.svelte');
+/** Check if a path is a CSS file. */
+export const isCss = (path) => path.endsWith('.css');
+/** Check if a path is a JSON file. */
+export const isJson = (path) => path.endsWith('.json');
+/**
+ * Suffix appended to `.svelte` file paths to create virtual TypeScript file paths.
+ *
+ * Used by svelte2tsx integration: `Component.svelte` → `Component.svelte.__svelte2tsx__.ts`.
+ */
+export const SVELTE_VIRTUAL_SUFFIX = '.__svelte2tsx__.ts';
+/**
+ * Strip the svelte2tsx virtual file suffix from a path, if present.
+ *
+ * Maps `Component.svelte.__svelte2tsx__.ts` back to `Component.svelte`.
+ * Returns the path unchanged if the suffix is not present.
+ */
+export const stripVirtualSuffix = (path) => path.endsWith(SVELTE_VIRTUAL_SUFFIX) ? path.slice(0, -SVELTE_VIRTUAL_SUFFIX.length) : path;

package/dist/svelte.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Svelte component analysis helpers.
+ *
+ * Extracts metadata from Svelte components using svelte2tsx transformations:
+ *
+ * - Component props with types and JSDoc
+ * - Component-level documentation
+ * - Type information
+ *
+ * Workflow: Transform Svelte to TypeScript via svelte2tsx, parse the transformed
+ * TypeScript with the TS Compiler API, extract component-level JSDoc from original source.
+ *
+ * **Svelte 5 only**: The svelte2tsx output format changed significantly between versions.
+ * This module requires Svelte 5+ and will throw a clear error if an older version is detected.
+ * There is no Svelte 4 compatibility layer.
+ *
+ * @see `typescript-exports.ts` for `analyzeExports`, `extractModuleComment`
+ * @see `typescript-extract-shared.ts` for `parseGenericParam`, `filterIntersectionProperties`
+ * @see `typescript-program.ts` for `IsExternalFile`, `createIsExternalFile`
+ * @see `tsdoc.ts` for `parseComment`, `applyToDeclaration`
+ * @see `source.ts` for `SourceFileInfo`, `getComponentName`
+ *
+ * @module
+ */
+import { TraceMap } from '@jridgewell/trace-mapping';
+import ts from 'typescript';
+import type { ParameterJsonInput } from './types.js';
+import type { ModuleAnalysis } from './declaration-build.js';
+import { type SourceFileInfo } from './source.js';
+import { type ModuleSourceOptions } from './source-config.js';
+import { type Diagnostic } from './diagnostics.js';
+/** Resolved source map type (avoids repeating the verbose `InstanceType<...>` inline). */
+type SourceMap = InstanceType<typeof TraceMap>;
+/**
+ * Pre-transformed Svelte virtual file data.
+ *
+ * Produced by `transformSvelteSource` and consumed by `analyzeSvelteModule`
+ * to provide checker-backed analysis of Svelte components.
+ */
+export interface SvelteVirtualFile {
+    /** Path used for the virtual file in the TypeScript program. */
+    virtualPath: string;
+    /** svelte2tsx transformed TypeScript content. */
+    content: string;
+    /** Source map for position mapping back to the original `.svelte` file. */
+    sourceMap: SourceMap | null;
+    /** Script language. `undefined` means TypeScript (default), `'js'` for JavaScript-only components. */
+    lang: 'js' | undefined;
+}
+/**
+ * Result of `transformSvelteSource` — a virtual file (when transform succeeded)
+ * plus any ingest-time diagnostics produced during the transform.
+ *
+ * `virtual` is `undefined` when svelte2tsx threw; in that case `diagnostics`
+ * contains a `transform_failed` entry. When the transform succeeded but source
+ * map construction failed, `virtual` is populated and `diagnostics` contains a
+ * `source_map_failed` entry. The session's owned-entry stores both — the
+ * virtual (or `transformFailed: true` flag) and the ingest diagnostics.
+ */
+export interface TransformResult {
+    virtual: SvelteVirtualFile | undefined;
+    diagnostics: Array<Diagnostic>;
+}
+/**
+ * Pre-transform a Svelte source file via svelte2tsx.
+ *
+ * Produces a `SvelteVirtualFile` containing the transformed TypeScript content
+ * and source map. The virtual file can be included in a TypeScript program
+ * (via `createAnalysisProgram({ virtualFiles })`) so that the checker can
+ * resolve imported types, `<script module>` exports, and re-exports.
+ *
+ * Errors at ingest are returned via `diagnostics` rather than thrown:
+ * - svelte2tsx throws → `transform_failed`, `virtual: undefined`
+ * - source map construction fails → `source_map_failed`, virtual populated
+ *
+ * Diagnostic file paths are the original `.svelte` source ID; downstream
+ * normalization rewrites them to project-root-relative form.
+ *
+ * @param sourceFile - the Svelte source file with content loaded
+ * @returns virtual file data (or `undefined` on transform failure) plus ingest diagnostics
+ * @throws Error if Svelte version is below 5 (checked once on first call)
+ */
+export declare const transformSvelteSource: (sourceFile: SourceFileInfo) => TransformResult;
+/**
+ * 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">`).
+ *
+ * @returns the script tag content, or undefined if no matching script tag is found
+ */
+export declare const extractScriptContent: (svelteSource: string) => string | undefined;
+/**
+ * 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.
+ *
+ * @param svelteSource - the full Svelte source code
+ * @returns the cleaned module comment text, or undefined if no `@module` HTML comment found
+ */
+export declare const extractHtmlModuleComment: (svelteSource: string) => string | undefined;
+/**
+ * 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.
+ *
+ * @param scriptContent - the content of the `<script>` tag
+ * @returns the cleaned module comment text, or undefined if none found
+ */
+export declare const extractSvelteModuleComment: (scriptContent: string) => string | undefined;
+/**
+ * Check if a type string represents a `Snippet` type.
+ *
+ * Uses the already-resolved type string (from `checker.typeToString`) for reliable
+ * detection. `Snippet` is an interface (not a type alias), so `aliasSymbol` is
+ * not available — type string matching is the reliable detection path.
+ */
+export declare const isSnippetTypeString: (typeString: string) => boolean;
+/**
+ * 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`.
+ *
+ * @returns array of parameter info for the snippet's tuple type arguments,
+ *   or `[]` for bare `Snippet` / `Snippet<[]>`
+ */
+export declare const extractSnippetParameters: (snippetType: ts.Type, checker: ts.TypeChecker) => Array<ParameterJsonInput>;
+/**
+ * Check if a return type string matches svelte2tsx's snippet return type pattern.
+ *
+ * svelte2tsx transforms exported snippets into arrow functions with
+ * `ReturnType<import('svelte').Snippet>` as the return type annotation.
+ * The resolved return type includes `unique symbol` (from Svelte's non-exported
+ * `SnippetReturn` unique symbol) intersected with the branded render message.
+ * We match on both parts to avoid false positives — the branded message alone
+ * could theoretically be crafted by user code, but the `unique symbol` intersection
+ * cannot since `SnippetReturn` is not exported from svelte.
+ */
+export declare const isSnippetReturnType: (returnType: string) => boolean;
+/**
+ * Synthesize a `Snippet<[...]>` type string from structured parameters.
+ *
+ * Used for `kind: 'snippet'` declarations where the raw svelte2tsx type
+ * is implementation noise. Produces type strings consistent with how
+ * the checker formats Snippet types on props.
+ */
+export declare const synthesizeSnippetTypeSignature: (parameters: Array<ParameterJsonInput>) => string;
+/**
+ * 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
+ *
+ * @param sourceFile - the original Svelte source file
+ * @param modulePath - module path relative to source root
+ * @param checker - TypeScript type checker (from the program containing virtual files)
+ * @param options - module source options for path extraction
+ * @param diagnostics - diagnostics collector for non-fatal issues
+ * @param program - TypeScript program containing the virtual file
+ * @param virtualFile - pre-transformed virtual file data
+ * @returns module analysis with declarations, re-exports, and star exports;
+ *   `undefined` if the virtual file is not found in the program
+ */
+export declare const analyzeSvelteModule: (sourceFile: SourceFileInfo & {
+    dependents?: ReadonlyArray<string>;
+}, modulePath: string, checker: ts.TypeChecker, options: ModuleSourceOptions, diagnostics: Array<Diagnostic>, program: ts.Program, virtualFile: SvelteVirtualFile) => ModuleAnalysis | undefined;
+export {};
+//# sourceMappingURL=svelte.d.ts.map

package/dist/svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAC,QAAQ,EAAsB,MAAM,2BAA2B,CAAC;AAGxE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,KAAK,EAA2C,kBAAkB,EAAC,MAAM,YAAY,CAAC;AAC7F,OAAO,KAAK,EAGX,cAAc,EACd,MAAM,wBAAwB,CAAC;AAKhC,OAAO,EAAC,KAAK,cAAc,EAA0C,MAAM,aAAa,CAAC;AACzF,OAAO,EAAC,KAAK,mBAAmB,EAAsB,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAC,KAAK,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,0FAA0F;AAC1F,KAAK,SAAS,GAAG,YAAY,CAAC,OAAO,QAAQ,CAAC,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IACjC,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,sGAAsG;IACtG,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACvC,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB,GAAI,YAAY,cAAc,KAAG,eAoDlE,CAAC;AAkHF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,cAAc,MAAM,KAAG,MAAM,GAAG,SAcpE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GAAI,cAAc,MAAM,KAAG,MAAM,GAAG,SA0BxE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GAAI,eAAe,MAAM,KAAG,MAAM,GAAG,SAU3E,CAAC;AA0PF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,YAAY,MAAM,KAAG,OAExD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,GACpC,aAAa,EAAE,CAAC,IAAI,EACpB,SAAS,EAAE,CAAC,WAAW,KACrB,KAAK,CAAC,kBAAkB,CAqB1B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,YAAY,MAAM,KAAG,OAKxD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,GAAI,YAAY,KAAK,CAAC,kBAAkB,CAAC,KAAG,MAGtF,CAAC;AA8NF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mBAAmB,GAC/B,YAAY,cAAc,GAAG;IAAC,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAC,EACjE,YAAY,MAAM,EAClB,SAAS,EAAE,CAAC,WAAW,EACvB,SAAS,mBAAmB,EAC5B,aAAa,KAAK,CAAC,UAAU,CAAC,EAC9B,SAAS,EAAE,CAAC,OAAO,EACnB,aAAa,iBAAiB,KAC5B,cAAc,GAAG,SAuNnB,CAAC"}