svelte-docinfo 0.1.0

package/dist/session.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Persistent analysis session — δ-shaped API over a `ts.LanguageService`.
+ *
+ * Maps cleanly onto LSP and Vite/HMR consumers:
+ *
+ * - `setFile` / `setFiles` — additive ingest; transform-if-Svelte, lex
+ *   specifiers, resolve imports (parallel), push content/virtual to the LS.
+ *   Returns ingest-time diagnostics + a `changed` flag. Cache-hit no-op
+ *   when content matches AND the mode-specific cache key matches (resolver
+ *   identity for lex+resolve, dependency-snapshot equality for pre-resolved).
+ * - `deleteFile` — drop owned entry, evict from LS.
+ * - `has` / `list` — owned-set introspection (covers what consumers used to
+ *   get from their own mirror caches).
+ * - `query` — sync analysis pass against the current owned set; returns
+ *   analysis-pass diagnostics only (ingest diagnostics surface via the
+ *   `setFile`/`setFiles` returns).
+ * - `dispose` — release LS resources.
+ *
+ * The session owns a single `Map<id, OwnedEntry>` covering content, svelte
+ * virtuals, unfiltered deps, the mode-specific cache key (resolver identity
+ * or pre-resolved snapshot), and ingest-time diagnostics. svelte2tsx runs
+ * at most once per content change. Resolver work parallelizes across the
+ * batch in phase 2 of the three-phase setFiles pipeline; fully pre-resolved
+ * batches skip phase 2 (and the default-resolver construction) entirely.
+ *
+ * @see `analyze-core.ts` for the two-phase analysis orchestrator
+ * @see `dep-resolver.ts` for the `ImportResolver` token contract
+ *
+ * @module
+ */
+import { type AnalysisLanguageServiceOptions } from './typescript-program.js';
+import type { Diagnostic } from './diagnostics.js';
+import type { AnalysisLog } from './log.js';
+import { type ResolveImport } from './dep-resolver.js';
+import type { SourceFileInfo } from './source.js';
+import { type ModuleSourceOptions } from './source-config.js';
+import { AnalyzeResultJson, type OnDuplicates } from './analyze-core.js';
+/**
+ * Options for a per-file or per-batch resolver override.
+ *
+ * Identity is required (not optional) — silently coalescing missing identities
+ * to a function reference would destroy cache reuse when the same logical
+ * resolver is wrapped in fresh closures across calls.
+ */
+export interface SetFileOptions {
+    /**
+     * Per-call override of the session-default resolver — a bare
+     * `ResolveImportFn` or a token-paired `ImportResolver` (see `ResolveImport`).
+     *
+     * A bare function is normalized with a fresh identity on each call, so the
+     * files touched by this call re-resolve rather than cache-hitting — the
+     * expected behavior for a deliberate one-off override. To reuse the resolve
+     * cache across calls, pass an `ImportResolver` with a stable `identity`.
+     */
+    resolveImport?: ResolveImport;
+}
+/**
+ * Result of `setFile` (single-file ingest).
+ *
+ * `changed` is `true` when content or the mode-specific cache key (resolver
+ * identity for lex+resolve; dependency snapshot for pre-resolved) differed
+ * from the cached entry — the owned entry was rewritten. An LS push
+ * accompanies the entry write only when the file is TS/JS or has a
+ * successful Svelte virtual; CSS/JSON and transform-failed Svelte rewrite
+ * the entry without touching the LS. `false` indicates a cache-hit no-op:
+ * the cached `ingestDiagnostics` are returned but no work ran.
+ */
+export interface SetFileResult {
+    /** Whether content or the mode-specific cache key differed from the cached entry. */
+    changed: boolean;
+    /** Ingest-time diagnostics for this file (durable on the entry). */
+    diagnostics: Array<Diagnostic>;
+}
+/**
+ * Result of `setFiles` (batch ingest).
+ *
+ * Carries both aggregate views (`changedIds`, pre-flattened `diagnostics`)
+ * and a structured `perFile` map. HMR-style consumers want
+ * `changedIds.size > 0` as the hot check; LSP-style consumers want per-file
+ * diagnostic association via `perFile`. Both are populated in the same
+ * single-pass walk over the batch — no extra cost.
+ */
+export interface SetFilesResult {
+    /**
+     * IDs whose content or mode-specific cache key differed from the cached
+     * entry — the subset of input file IDs that actually triggered work.
+     * Empty when every file was a cache-hit no-op.
+     */
+    changedIds: ReadonlySet<string>;
+    /**
+     * Pre-flattened union of every file's `ingestDiagnostics`. Consumers
+     * can group by `Diagnostic.file` for per-file publish.
+     */
+    diagnostics: Array<Diagnostic>;
+    /**
+     * Per-file `SetFileResult` keyed by input file ID. Use this when the
+     * grouping `Diagnostic.file` would do isn't enough — e.g., LSP wanting
+     * to publish empty-diagnostic-list updates for files that ingested
+     * cleanly.
+     */
+    perFile: ReadonlyMap<string, SetFileResult>;
+}
+/**
+ * Per-call input to `query`.
+ */
+export interface QueryOptions {
+    /** Behavior when duplicate declaration names are found across modules. */
+    onDuplicates?: OnDuplicates;
+    /** Per-call logger override (defaults to the session-level logger). */
+    log?: AnalysisLog;
+}
+/**
+ * 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.
+ */
+export interface AnalysisSession {
+    /**
+     * Ingest one file's content into the session. Idempotent on cache hit.
+     *
+     * @returns `{changed, diagnostics}` — `changed: false` indicates a
+     *   cache-hit no-op where the cached ingest diagnostics are returned.
+     */
+    setFile(file: SourceFileInfo, opts?: SetFileOptions): Promise<SetFileResult>;
+    /**
+     * Ingest a batch of files. Additive — never removes; use `deleteFile` for
+     * removal. Cache hits are folded into the result with `changed: false`.
+     */
+    setFiles(files: ReadonlyArray<SourceFileInfo>, opts?: SetFileOptions): Promise<SetFilesResult>;
+    /** Drop a file from the session and evict from the LS. */
+    deleteFile(id: string): Promise<void>;
+    /** Whether the given file ID is currently owned by the session. */
+    has(id: string): boolean;
+    /** Snapshot of currently-owned file IDs (sort order is insertion order). */
+    list(): ReadonlyArray<string>;
+    /**
+     * Run a two-phase analysis pass against the current owned set.
+     *
+     * @returns analyzed modules and analysis-pass diagnostics. Ingest
+     *   diagnostics from prior `setFile`/`setFiles` calls are NOT included
+     *   here — concat with those returns for the full picture.
+     * @throws Error if `onDuplicates: 'throw'` and duplicates exist
+     */
+    query(opts?: QueryOptions): AnalyzeResultJson;
+    /**
+     * Concatenated ingest-time diagnostics across every owned entry — the
+     * cumulative view of every `setFile`/`setFiles` return, kept current as
+     * entries are added/replaced/deleted.
+     *
+     * Lets long-lived consumers (Vite plugin, LSP) publish the full ingest
+     * picture without tracking per-batch returns themselves. Cheap: walks
+     * the owned map.
+     */
+    allIngestDiagnostics(): Array<Diagnostic>;
+    /**
+     * Release LS resources and clear the owned set. The session must not be
+     * used after disposal.
+     */
+    dispose(): void;
+}
+/**
+ * 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.
+ */
+export interface AnalysisSessionOptions extends Omit<AnalysisLanguageServiceOptions, 'projectRoot' | 'virtualFiles'> {
+    /**
+     * Module source options for path extraction and source filtering.
+     *
+     * Must be a fully-constructed `ModuleSourceOptions` — the session re-runs
+     * `normalizeSourceOptions` (idempotent) but does not apply any defaults.
+     * Pass through `createSourceOptions(projectRoot, overrides?)` to merge with
+     * `DEFAULT_SOURCE_OPTIONS`. (The `Partial<SourceOptionsDefaults>` ergonomic
+     * shape exists only on `AnalyzeFromFilesOptions.sourceOptions`, where the
+     * defaults merge happens inside `analyzeFromFiles`.)
+     */
+    sourceOptions: ModuleSourceOptions;
+    /**
+     * Session-default custom import resolver used when no per-call override is
+     * supplied — a bare `ResolveImportFn` or a token-paired `ImportResolver`
+     * (see `ResolveImport`). A bare function is normalized once at construction,
+     * so its synthesized identity is stable for the session's lifetime (cache
+     * reuse works). When omitted, the session lazily constructs the TS+tsconfig
+     * default on first use.
+     */
+    resolveImport?: ResolveImport;
+    /** Optional logger for session-level messages. */
+    log?: AnalysisLog;
+}
+/**
+ * Create a persistent analysis session.
+ *
+ * @example Vite plugin integration
+ * ```ts
+ * const session = createAnalysisSession({sourceOptions, resolveImport, log});
+ * await session.setFiles(initialFiles);
+ * const result = session.query();
+ * // on watcher events:
+ * await session.setFile({id, content});
+ * await session.deleteFile(removedId);
+ * const next = session.query();
+ * // on shutdown:
+ * session.dispose();
+ * ```
+ *
+ * @example One-shot via the public wrapper
+ * ```ts
+ * // Equivalent to `analyze(...)` — the wrapper goes through a session internally.
+ * const session = createAnalysisSession({sourceOptions});
+ * try {
+ *   await session.setFiles(sourceFiles);
+ *   return session.query({onDuplicates: 'throw'});
+ * } finally {
+ *   session.dispose();
+ * }
+ * ```
+ */
+export declare const createAnalysisSession: (options: AnalysisSessionOptions) => AnalysisSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAIN,KAAK,8BAA8B,EACnC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,UAAU,CAAC;AAE1C,OAAO,EAEN,KAAK,aAAa,EAKlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,aAAa,CAAC;AAChD,OAAO,EAAC,KAAK,mBAAmB,EAAmC,MAAM,oBAAoB,CAAC;AAG9F,OAAO,EAGN,iBAAiB,EACjB,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAC;AAG3B;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC7B,qFAAqF;IACrF,OAAO,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC;;;OAGG;IACH,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,uEAAuE;IACvE,GAAG,CAAC,EAAE,WAAW,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7E;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/F,0DAA0D;IAC1D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,mEAAmE;IACnE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,4EAA4E;IAC5E,IAAI,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9B;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAAC;IAC9C;;;;;;;;OAQG;IACH,oBAAoB,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1C;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CACnD,8BAA8B,EAC9B,aAAa,GAAG,cAAc,CAC9B;IACA;;;;;;;;;OASG;IACH,aAAa,EAAE,mBAAmB,CAAC;IACnC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,kDAAkD;IAClD,GAAG,CAAC,EAAE,WAAW,CAAC;CAClB;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,qBAAqB,GAAI,SAAS,sBAAsB,KAAG,eA6cvE,CAAC"}