svelte-docinfo 0.1.0

package/dist/dep-resolver.js

@@ -0,0 +1,144 @@
+/**
+ * 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';
+import { init as esModuleLexerInit, parse as esModuleLexerParse } from 'es-module-lexer';
+/**
+ * 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 const normalizeResolveImport = (value) => value === undefined ? undefined : typeof value === 'function' ? wrapResolveImport(value) : value;
+/**
+ * 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 const ensureLexerReady = async () => {
+    await esModuleLexerInit;
+};
+/**
+ * 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 const lexImports = (content, fileId) => {
+    const [imports] = esModuleLexerParse(content, fileId);
+    const specifiers = [];
+    for (const imp of imports) {
+        if (imp.n)
+            specifiers.push(imp.n);
+    }
+    return specifiers;
+};
+/**
+ * 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 const createDefaultResolver = (compilerOptions, projectRoot) => {
+    const cache = ts.createModuleResolutionCache(projectRoot, ts.sys.useCaseSensitiveFileNames ? (f) => f : (f) => f.toLowerCase(), compilerOptions);
+    const resolve = (specifier, fromFile) => {
+        const result = ts.resolveModuleName(specifier, fromFile, compilerOptions, ts.sys, cache);
+        if (result.resolvedModule)
+            return result.resolvedModule.resolvedFileName;
+        // Fallback: try with .svelte extension. ts.resolveModuleName doesn't
+        // know about .svelte files unless explicitly configured.
+        if (!specifier.endsWith('.svelte')) {
+            const svelte = ts.resolveModuleName(specifier + '.svelte', fromFile, compilerOptions, ts.sys, cache);
+            if (svelte.resolvedModule)
+                return svelte.resolvedModule.resolvedFileName;
+        }
+        return null;
+    };
+    return { resolve, identity: Symbol('ts-default') };
+};
+/**
+ * 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 const wrapResolveImport = (resolveImport, identity = Symbol('wrapped')) => ({
+    resolve: resolveImport,
+    identity,
+});
+/**
+ * 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 const noDepsResolver = {
+    resolve: () => null,
+    identity: 'no-deps',
+};