svelte-docinfo 0.1.0

package/dist/declaration-helpers.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Utility functions for working with declaration and member types.
+ *
+ * Display formatting, code generation, serialization, type narrowing,
+ * and type reference discovery for `DeclarationJson` and `MemberJson`.
+ *
+ * @see `types.ts` for `DeclarationJson`, `MemberJson` Zod schemas
+ *
+ * @module
+ */
+import type { DeclarationJson, MemberJson, DeclarationKind, MemberKind } from './types.js';
+/**
+ * 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).
+ *
+ * @example
+ * ```ts
+ * const result = await analyze({sourceFiles, sourceOptions});
+ * const json = JSON.stringify(result, compactReplacer);
+ * // On the consumer side, restore Zod defaults:
+ * const restored = AnalyzeResultJson.parse(JSON.parse(json));
+ * ```
+ */
+export declare const compactReplacer: (_key: string, value: unknown) => unknown;
+/**
+ * Format declaration or member name with generic parameters for display.
+ *
+ * Default-slot entries return the literal `'default'` (the symbol's actual
+ * name in JS). Renderers that want a richer label (PascalCased module path,
+ * an explicit "default export" header) should branch on `name === 'default'`
+ * themselves before calling this.
+ *
+ * @see `generateImport` for the divergent default-slot fallback used in
+ *   import-statement generation (PascalCased module path, since an import
+ *   needs a JS identifier binding, not a label).
+ *
+ * @param declaration - the `DeclarationJson` or `MemberJson` to format
+ * @returns name with generic parameters appended (e.g., `Map<K, V>`)
+ *
+ * @example
+ * ```ts
+ * getDisplayName({name: 'Map', kind: 'type', genericParams: [{name: 'K'}, {name: 'V'}]})
+ * // => 'Map<K, V>'
+ * ```
+ */
+export declare const getDisplayName: (declaration: DeclarationJson | MemberJson) => string;
+/**
+ * Generate TypeScript import statement for a declaration.
+ *
+ * Produces `import type` for type/interface declarations, `import` for values.
+ *
+ * **Default export handling**: when `declaration.name === 'default'`, emits
+ * `import X from '...'` with the binding derived by PascalCasing the module
+ * path. (`'default'` is the symbol's actual name in JS — `import X from 'mod'`
+ * is sugar for `import {default as X} from 'mod'`.)
+ *
+ * @see `getDisplayName` for the divergent default-slot fallback used as a
+ *   display label (the literal `'default'`, since a label has no use for a
+ *   synthesized JS binding).
+ *
+ * @param declaration - the `DeclarationJson` to generate an import for
+ * @param modulePath - module path relative to source root (e.g., `foo.ts`)
+ * @param libraryName - package name for the import specifier (e.g., `@pkg/lib`)
+ * @returns formatted import statement string
+ *
+ * @example
+ * ```ts
+ * generateImport({name: 'Foo', kind: 'type'}, 'foo.ts', '@pkg/lib')
+ * // => "import type {Foo} from '@pkg/lib/foo.js';"
+ *
+ * generateImport({name: 'default', kind: 'function'}, 'foo-bar.ts', '@pkg/lib')
+ * // => "import FooBar from '@pkg/lib/foo-bar.js';"
+ * ```
+ */
+export declare const generateImport: (declaration: DeclarationJson, modulePath: string, libraryName: string) => string;
+/**
+ * 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.
+ *
+ * @param declarationNames - set of known in-project declaration names
+ * @returns array of `[name, pattern]` pairs for use with `findTypeReferences`
+ *
+ * @example
+ * ```ts
+ * const names = new Set(modules.flatMap(m => m.declarations.map(d => d.name)));
+ * const patterns = buildTypeReferencePatterns(names);
+ * for (const decl of declarations) {
+ *   const refs = findTypeReferences(decl.typeSignature, patterns);
+ * }
+ * ```
+ */
+export declare const buildTypeReferencePatterns: (declarationNames: ReadonlySet<string>) => Array<[string, RegExp]>;
+/**
+ * Find in-project declaration names referenced in a type string.
+ *
+ * Uses identifier-boundary matching to find which known declaration names appear
+ * in an opaque type string (e.g., `typeSignature`, `returnType`, parameter `type`).
+ * Enables consumers to render clickable type links without needing access to
+ * the TypeScript type checker.
+ *
+ * Handles identifiers starting with `$` (e.g., `$state`) which `\b` does not
+ * recognize as word boundaries.
+ *
+ * Accepts either a `ReadonlySet<string>` (convenience) or pre-compiled patterns
+ * from `buildTypeReferencePatterns` (performance). Use pre-compiled patterns
+ * when scanning many type strings against the same declaration set.
+ *
+ * **Known limitations**: Identifier-boundary matching can produce false positives
+ * when a declaration name appears as a property key in an object literal type
+ * (e.g., `{ Foo: string }` when `Foo` is a declaration). This is rare in practice.
+ *
+ * @param typeString - opaque type string from analysis output
+ * @param declarationNames - set of names or pre-compiled patterns from `buildTypeReferencePatterns`
+ * @returns array of declaration names found in the type string
+ *
+ * @example
+ * ```ts
+ * const names = new Set(modules.flatMap(m => m.declarations.map(d => d.name)));
+ * findTypeReferences('Map<string, ModuleJson[]>', names)
+ * // => ['ModuleJson']
+ * ```
+ */
+export declare const findTypeReferences: (typeString: string, declarationNames: ReadonlySet<string> | Array<[string, RegExp]>) => Array<string>;
+/**
+ * Narrow a declaration by kind for type-safe field access.
+ *
+ * Works with both `DeclarationJson` (top-level) and `MemberJson` (nested).
+ * Accepts `DeclarationKind | MemberKind` so `isKind(member, 'constructor')` compiles.
+ *
+ * @example
+ * ```ts
+ * if (isKind(declaration, 'function')) {
+ *   declaration.parameters; // FunctionDeclarationJson — has parameters
+ *   declaration.returnType; // has returnType
+ * }
+ * if (isKind(member, 'constructor')) {
+ *   member.parameters; // ConstructorMemberJson — has parameters
+ * }
+ * ```
+ */
+export declare const isKind: <K extends DeclarationKind | MemberKind>(declaration: DeclarationJson | MemberJson, kind: K) => declaration is Extract<DeclarationJson | MemberJson, {
+    kind: K;
+}>;
+//# sourceMappingURL=declaration-helpers.d.ts.map

package/dist/declaration-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declaration-helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/declaration-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAC,MAAM,YAAY,CAAC;AAIzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,EAAE,OAAO,OAAO,KAAG,OACqB,CAAC;AAIrF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,eAAe,GAAG,UAAU,KAAG,MAS1E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,cAAc,GAC1B,aAAa,eAAe,EAC5B,YAAY,MAAM,EAClB,aAAa,MAAM,KACjB,MAuBF,CAAC;AA6BF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,0BAA0B,GACtC,kBAAkB,WAAW,CAAC,MAAM,CAAC,KACnC,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,kBAAkB,GAC9B,YAAY,MAAM,EAClB,kBAAkB,WAAW,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAC7D,KAAK,CAAC,MAAM,CAYd,CAAC;AAIF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,eAAe,GAAG,UAAU,EAC5D,aAAa,eAAe,GAAG,UAAU,EACzC,MAAM,CAAC,KACL,WAAW,IAAI,OAAO,CAAC,eAAe,GAAG,UAAU,EAAE;IAAC,IAAI,EAAE,CAAC,CAAA;CAAC,CAA8B,CAAC"}

package/dist/declaration-helpers.js

@@ -0,0 +1,239 @@
+/**
+ * Utility functions for working with declaration and member types.
+ *
+ * Display formatting, code generation, serialization, type narrowing,
+ * and type reference discovery for `DeclarationJson` and `MemberJson`.
+ *
+ * @see `types.ts` for `DeclarationJson`, `MemberJson` Zod schemas
+ *
+ * @module
+ */
+// ── Serialization ───────────────────────────────────────────────────────────
+/**
+ * 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).
+ *
+ * @example
+ * ```ts
+ * const result = await analyze({sourceFiles, sourceOptions});
+ * const json = JSON.stringify(result, compactReplacer);
+ * // On the consumer side, restore Zod defaults:
+ * const restored = AnalyzeResultJson.parse(JSON.parse(json));
+ * ```
+ */
+export const compactReplacer = (_key, value) => (Array.isArray(value) && value.length === 0) || value === false ? undefined : value;
+// ── Display Helpers ─────────────────────────────────────────────────────────
+/**
+ * Format declaration or member name with generic parameters for display.
+ *
+ * Default-slot entries return the literal `'default'` (the symbol's actual
+ * name in JS). Renderers that want a richer label (PascalCased module path,
+ * an explicit "default export" header) should branch on `name === 'default'`
+ * themselves before calling this.
+ *
+ * @see `generateImport` for the divergent default-slot fallback used in
+ *   import-statement generation (PascalCased module path, since an import
+ *   needs a JS identifier binding, not a label).
+ *
+ * @param declaration - the `DeclarationJson` or `MemberJson` to format
+ * @returns name with generic parameters appended (e.g., `Map<K, V>`)
+ *
+ * @example
+ * ```ts
+ * getDisplayName({name: 'Map', kind: 'type', genericParams: [{name: 'K'}, {name: 'V'}]})
+ * // => 'Map<K, V>'
+ * ```
+ */
+export const getDisplayName = (declaration) => {
+    if (!declaration.genericParams.length)
+        return declaration.name;
+    const params = declaration.genericParams.map((p) => {
+        let param = p.name;
+        if (p.constraint)
+            param += ` extends ${p.constraint}`;
+        if (p.defaultType)
+            param += ` = ${p.defaultType}`;
+        return param;
+    });
+    return `${declaration.name}<${params.join(', ')}>`;
+};
+/**
+ * Generate TypeScript import statement for a declaration.
+ *
+ * Produces `import type` for type/interface declarations, `import` for values.
+ *
+ * **Default export handling**: when `declaration.name === 'default'`, emits
+ * `import X from '...'` with the binding derived by PascalCasing the module
+ * path. (`'default'` is the symbol's actual name in JS — `import X from 'mod'`
+ * is sugar for `import {default as X} from 'mod'`.)
+ *
+ * @see `getDisplayName` for the divergent default-slot fallback used as a
+ *   display label (the literal `'default'`, since a label has no use for a
+ *   synthesized JS binding).
+ *
+ * @param declaration - the `DeclarationJson` to generate an import for
+ * @param modulePath - module path relative to source root (e.g., `foo.ts`)
+ * @param libraryName - package name for the import specifier (e.g., `@pkg/lib`)
+ * @returns formatted import statement string
+ *
+ * @example
+ * ```ts
+ * generateImport({name: 'Foo', kind: 'type'}, 'foo.ts', '@pkg/lib')
+ * // => "import type {Foo} from '@pkg/lib/foo.js';"
+ *
+ * generateImport({name: 'default', kind: 'function'}, 'foo-bar.ts', '@pkg/lib')
+ * // => "import FooBar from '@pkg/lib/foo-bar.js';"
+ * ```
+ */
+export const generateImport = (declaration, modulePath, libraryName) => {
+    const jsPath = modulePath.replace(/\.ts$/, '.js');
+    const specifier = `${libraryName}/${jsPath}`;
+    // Default-slot entries — derive the import binding from the module path.
+    if (declaration.name === 'default') {
+        return `import ${pascalCaseFromModulePath(modulePath)} from '${specifier}';`;
+    }
+    // Components are default exports in Svelte
+    if (declaration.kind === 'component') {
+        return `import ${declaration.name} from '${specifier}';`;
+    }
+    // Namespace re-export: `export * as ns from './x'` in the source becomes
+    // `import * as ns from '<package>/<re-exporter>.js'` for consumers.
+    if (declaration.kind === 'namespace') {
+        return `import * as ${declaration.name} from '${specifier}';`;
+    }
+    const importKeyword = declaration.kind === 'type' || declaration.kind === 'interface' ? 'import type' : 'import';
+    return `${importKeyword} {${declaration.name}} from '${specifier}';`;
+};
+const pascalCaseFromModulePath = (modulePath) => {
+    const moduleName = modulePath.replace(/\.(js|ts|svelte)$/, '');
+    return moduleName
+        .split(/[-_/]/)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+};
+// ── Type Reference Helpers ─────────────────────────────────────────────────
+/**
+ * Escape special regex characters in a string.
+ */
+const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Matches TypeScript identifier characters (letters, digits, `_`, `$`). */
+const ID_CHAR = '[a-zA-Z0-9_$]';
+/**
+ * Build a regex that matches `name` only at identifier boundaries.
+ *
+ * Uses lookaround for `[a-zA-Z0-9_$]` instead of `\b` so that
+ * `$`-prefixed identifiers like `$state` are matched correctly.
+ */
+const buildIdentifierPattern = (name) => new RegExp('(?<!' + ID_CHAR + ')' + escapeRegex(name) + '(?!' + ID_CHAR + ')');
+/**
+ * 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.
+ *
+ * @param declarationNames - set of known in-project declaration names
+ * @returns array of `[name, pattern]` pairs for use with `findTypeReferences`
+ *
+ * @example
+ * ```ts
+ * const names = new Set(modules.flatMap(m => m.declarations.map(d => d.name)));
+ * const patterns = buildTypeReferencePatterns(names);
+ * for (const decl of declarations) {
+ *   const refs = findTypeReferences(decl.typeSignature, patterns);
+ * }
+ * ```
+ */
+export const buildTypeReferencePatterns = (declarationNames) => {
+    const patterns = [];
+    for (const name of declarationNames) {
+        if (name)
+            patterns.push([name, buildIdentifierPattern(name)]);
+    }
+    return patterns;
+};
+/**
+ * Find in-project declaration names referenced in a type string.
+ *
+ * Uses identifier-boundary matching to find which known declaration names appear
+ * in an opaque type string (e.g., `typeSignature`, `returnType`, parameter `type`).
+ * Enables consumers to render clickable type links without needing access to
+ * the TypeScript type checker.
+ *
+ * Handles identifiers starting with `$` (e.g., `$state`) which `\b` does not
+ * recognize as word boundaries.
+ *
+ * Accepts either a `ReadonlySet<string>` (convenience) or pre-compiled patterns
+ * from `buildTypeReferencePatterns` (performance). Use pre-compiled patterns
+ * when scanning many type strings against the same declaration set.
+ *
+ * **Known limitations**: Identifier-boundary matching can produce false positives
+ * when a declaration name appears as a property key in an object literal type
+ * (e.g., `{ Foo: string }` when `Foo` is a declaration). This is rare in practice.
+ *
+ * @param typeString - opaque type string from analysis output
+ * @param declarationNames - set of names or pre-compiled patterns from `buildTypeReferencePatterns`
+ * @returns array of declaration names found in the type string
+ *
+ * @example
+ * ```ts
+ * const names = new Set(modules.flatMap(m => m.declarations.map(d => d.name)));
+ * findTypeReferences('Map<string, ModuleJson[]>', names)
+ * // => ['ModuleJson']
+ * ```
+ */
+export const findTypeReferences = (typeString, declarationNames) => {
+    if (!typeString)
+        return [];
+    const patterns = Array.isArray(declarationNames)
+        ? declarationNames
+        : buildTypeReferencePatterns(declarationNames);
+    const refs = [];
+    for (const [name, pattern] of patterns) {
+        if (pattern.test(typeString)) {
+            refs.push(name);
+        }
+    }
+    return refs;
+};
+// ── Narrowed Declaration Types ──────────────────────────────────────────────
+/**
+ * Narrow a declaration by kind for type-safe field access.
+ *
+ * Works with both `DeclarationJson` (top-level) and `MemberJson` (nested).
+ * Accepts `DeclarationKind | MemberKind` so `isKind(member, 'constructor')` compiles.
+ *
+ * @example
+ * ```ts
+ * if (isKind(declaration, 'function')) {
+ *   declaration.parameters; // FunctionDeclarationJson — has parameters
+ *   declaration.returnType; // has returnType
+ * }
+ * if (isKind(member, 'constructor')) {
+ *   member.parameters; // ConstructorMemberJson — has parameters
+ * }
+ * ```
+ */
+export const isKind = (declaration, kind) => declaration.kind === kind;

package/dist/dep-resolver.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Import resolver primitives for the analysis session.
+ *
+ * Exposes the `ImportResolver` token contract (`{resolve, identity}`) plus
+ * building blocks the session uses inside its three-phase setFiles pipeline:
+ *
+ * - `ensureLexerReady` — one-time wasm init for `es-module-lexer`. Phase 1 is
+ *   sync per-file; the session awaits this once before the loop starts.
+ * - `lexImports` — sync specifier extraction from already-prepared content
+ *   (raw TS/JS, or svelte2tsx virtual content for `.svelte` files).
+ * - `createDefaultResolver` — the TS + tsconfig fallback used when neither
+ *   `AnalysisSessionOptions.resolveImport` nor a per-call override is provided.
+ *   Carries a fresh symbol identity per session (cache-key-safe).
+ * - `normalizeResolveImport` — coerces the public `ResolveImport` union (bare
+ *   function or token-paired resolver) to an `ImportResolver` at each boundary.
+ * - `wrapResolveImport` — the fn→token primitive behind `normalizeResolveImport`:
+ *   wraps a bare function in an `ImportResolver`, synthesizing a throwaway
+ *   identity unless a stable one is passed.
+ *
+ * @internal — subpath-importable for power users who want to drive resolution
+ * outside the session, but not part of the stable barrel surface.
+ *
+ * @see `session.ts` for the three-phase ingestion pipeline that consumes these
+ * @see `loadTsconfig` in `typescript-program.ts` for the TS module-resolution
+ *   compiler-options shortcut used by the default resolver
+ *
+ * @module
+ */
+import ts from 'typescript';
+/**
+ * Bare import-resolver function — the convenience form.
+ *
+ * Resolve an import specifier to an absolute file path, or `null` if the
+ * specifier is unresolvable (external package, missing file, etc.). May return
+ * synchronously or asynchronously; sync returns are awaited harmlessly in the
+ * session's parallel resolve phase.
+ *
+ * @param specifier - import specifier from source code
+ * @param fromFile - absolute path of the importing file
+ */
+export type ResolveImportFn = (specifier: string, fromFile: string) => string | null | Promise<string | null>;
+/**
+ * Token-paired import resolver.
+ *
+ * `identity` is a stable opaque token that keys the session's resolve cache
+ * alongside content. Cache hits require both (a) byte-for-byte identical
+ * source content and (b) identity equality. Naive function-reference keys
+ * would silently destroy cache reuse when callers wrap the resolver in fresh
+ * closures (a very common pattern in Vite/Rollup plugins) — opaque tokens
+ * lift the responsibility to the caller, where it can be done correctly.
+ */
+export interface ImportResolver {
+    /** Resolve an import specifier to an absolute file path, or `null`. */
+    resolve: ResolveImportFn;
+    /**
+     * Stable opaque token identifying this resolver's cache scope.
+     *
+     * Two `ImportResolver`s with `identity` `===` to each other are treated
+     * as cache-equivalent. `string` for human-readable identities (e.g.,
+     * `'vite-plugin-container'`); `symbol` for generated sentinels.
+     */
+    identity: string | symbol;
+}
+/**
+ * Public resolver shape accepted across the API — a bare `ResolveImportFn` or
+ * the token-paired `ImportResolver`.
+ *
+ * Every entry point that accepts `resolveImport` (`analyze`, `analyzeFromFiles`,
+ * `createAnalysisSession`, and the session's `setFile`/`setFiles` per-call
+ * override) takes this union, so the same value copy-pastes between them. Pass:
+ *
+ * - a **bare function** for the common case — a fresh cache identity is
+ *   synthesized at the boundary. Correct for one-shot use (`analyze`,
+ *   `analyzeFromFiles`) and for a session default (wrapped once at
+ *   construction, so identity is stable for the session's lifetime).
+ * - an **`ImportResolver`** with a stable `identity` when you need the session
+ *   to reuse its resolve cache across calls where the same logical resolver is
+ *   rebuilt as a fresh closure (Vite/Rollup plugins). A bare function handed to
+ *   a *per-call* `setFile`/`setFiles` override is treated as a distinct
+ *   resolver each call (fresh identity → touched files re-resolve), which is
+ *   the expected behavior for a deliberate one-off override.
+ */
+export type ResolveImport = ResolveImportFn | ImportResolver;
+/**
+ * Normalize the public `ResolveImport` union to an `ImportResolver`.
+ *
+ * Wraps a bare function via `wrapResolveImport` (fresh synthesized identity);
+ * passes a token-paired resolver through unchanged. `undefined` in, `undefined`
+ * out — callers fall back to the session default. Call once per logical
+ * resolver scope: at session construction for the default, per call for an
+ * override.
+ */
+export declare const normalizeResolveImport: (value: ResolveImport | undefined) => ImportResolver | undefined;
+/**
+ * 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.
+ */
+export declare const ensureLexerReady: () => Promise<void>;
+/**
+ * Lex import specifiers from prepared content.
+ *
+ * Sync — caller must have awaited `ensureLexerReady` at least once before
+ * invoking. For `.svelte` files, pass the svelte2tsx-transformed virtual
+ * content, not the raw `.svelte` source (which isn't lex-able as JS/TS).
+ *
+ * Dynamic imports (`import(specifier)` with non-literal arg) are omitted.
+ *
+ * @throws Error if lexing fails (malformed source). Callers should catch and
+ *   emit `import_parse_failed`.
+ *
+ * @param content - prepared file content (TS/JS, or svelte2tsx virtual)
+ * @param fileId - absolute file path (used for error messages)
+ * @returns specifiers in declaration order
+ */
+export declare const lexImports: (content: string, fileId: string) => Array<string>;
+/**
+ * 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.
+ *
+ * @param compilerOptions - parsed tsconfig (from `loadTsconfig`)
+ * @param projectRoot - absolute project root for the module-resolution cache
+ */
+export declare const createDefaultResolver: (compilerOptions: ts.CompilerOptions, projectRoot: string) => ImportResolver;
+/**
+ * Wrap a bare `resolveImport` function into an `ImportResolver` token.
+ *
+ * `identity` is optional; when omitted, a fresh `Symbol('wrapped')` is
+ * synthesized per call. The synthesized default suits single-use scopes —
+ * `normalizeResolveImport` relies on it to wrap a bare function for a one-shot
+ * `analyze` call or for a session default (wrapped once at construction, so the
+ * identity stays stable for the session's lifetime).
+ *
+ * For a long-lived session that re-wraps the *same* logical resolver across
+ * calls (Vite plugin, LSP), a throwaway identity cache-misses every time — the
+ * fresh `Symbol('wrapped')` never compares equal. Pass a stable `identity`
+ * here, or — simpler — construct an `ImportResolver` (`{resolve, identity}`)
+ * directly and pass it through the `ResolveImport` union.
+ */
+export declare const wrapResolveImport: (resolveImport: ResolveImportFn, identity?: string | symbol) => ImportResolver;
+/**
+ * Shared no-op `ImportResolver` for the "dependency resolution disabled" case.
+ *
+ * Stable string identity (`'no-deps'`) instead of a per-call symbol so that
+ * repeated ingests within a long-lived session cache-hit on identity. Each
+ * session still owns its own cache (entries live on the per-session `owned`
+ * map; sessions don't share state), but within one session every reference
+ * to `noDepsResolver` is `===` to every other — so a Vite re-save of
+ * byte-identical content with `resolveDependencies: false` exercises the
+ * cache-hit branch. The resolver always returns `null`, so any two calls
+ * with identical content under this identity produce identical resolution
+ * results — `string` identity correctly captures that. Used by both the
+ * one-shot `analyzeFromFiles` path and the long-lived Vite plugin
+ * (`resolveDependencies: false`).
+ */
+export declare const noDepsResolver: ImportResolver;
+//# sourceMappingURL=dep-resolver.d.ts.map

package/dist/dep-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dep-resolver.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/dep-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5B;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,KACZ,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE5C;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC9B,uEAAuE;IACvE,OAAO,EAAE,eAAe,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,cAAc,CAAC;AAE7D;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAClC,OAAO,aAAa,GAAG,SAAS,KAC9B,cAAc,GAAG,SAC6E,CAAC;AAElG;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAa,OAAO,CAAC,IAAI,CAErD,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,QAAQ,MAAM,KAAG,KAAK,CAAC,MAAM,CAOxE,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,GACjC,iBAAiB,EAAE,CAAC,eAAe,EACnC,aAAa,MAAM,KACjB,cAwBF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAC7B,eAAe,eAAe,EAC9B,WAAU,MAAM,GAAG,MAA0B,KAC3C,cAGD,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,cAG5B,CAAC"}