svelte-docinfo 0.1.0

package/dist/analyze-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-core.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/analyze-core.ts"],"names":[],"mappings":"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"}

package/dist/analyze-core.js

@@ -0,0 +1,324 @@
+/**
+ * Pure two-phase analysis orchestrator.
+ *
+ * Extracted from `analyze.ts` to break what would otherwise be a circular
+ * import: `session.ts → analyze.ts (for the orchestrator) → session.ts (for
+ * the wrappers)`. With the orchestrator here, both `session.ts` and
+ * `analyze.ts` import downward into this module without depending on each
+ * other.
+ *
+ * Public surface:
+ *
+ * - `analyzeCore` — runs phase 1 module dispatch + phase 2 re-export merge,
+ *   returns `AnalyzeResultJson`. Caller supplies pre-prepared inputs (program,
+ *   svelte virtuals, transform-failed IDs).
+ * - `analyzeModule` — the per-module dispatcher (TS / Svelte / CSS / JSON).
+ *   `@internal`; exposed for tests and power users via the subpath.
+ * - `AnalyzeResultJson` / `OnDuplicates` / `OnDuplicatesCallback` — shared types
+ *   surfaced through the main barrel directly from this module.
+ * - `throwOnDuplicates` — convenience callback paired with `OnDuplicates`.
+ * - `normalizeDiagnosticPaths` — boundary helper for build-tool integrations
+ *   that bypass the session and collect their own diagnostics.
+ *
+ * @internal — module split is implementation detail; consumers go through
+ * `analyze.ts` / `session.ts` for the stable surface.
+ *
+ * @module
+ */
+import ts from 'typescript';
+import { z } from 'zod';
+import { ModuleJson } from './types.js';
+import { Diagnostic } from './diagnostics.js';
+import { analyzeTypescriptModule } from './typescript-exports.js';
+import { analyzeSvelteModule } from './svelte.js';
+import { stripVirtualSuffix, getComponentName } from './source.js';
+import { extractPath, extractDependencies } from './source-config.js';
+import { toPosixPath } from './paths.js';
+import { sortModules, findDuplicates, mergeReExports, resolveComponentAliases, } from './postprocess.js';
+/**
+ * Convenience `OnDuplicatesCallback` that throws on any duplicate.
+ *
+ * @throws Error listing every duplicate name and module location
+ */
+export const throwOnDuplicates = (duplicates) => {
+    if (duplicates.size === 0)
+        return;
+    throw new Error(formatDuplicates(duplicates));
+};
+const formatDuplicates = (duplicates) => {
+    const details = Array.from(duplicates)
+        .map(([name, occurrences]) => {
+        const locations = occurrences
+            .map(({ declaration, module }) => {
+            const lineInfo = declaration.sourceLine !== undefined ? `:${declaration.sourceLine}` : '';
+            return `    - ${module}${lineInfo} (${declaration.kind})`;
+        })
+            .join('\n');
+        return `  "${name}" found in:\n${locations}`;
+    })
+        .join('\n');
+    return (`Found ${duplicates.size} duplicate declaration name${duplicates.size === 1 ? '' : 's'} across modules. ` +
+        'The flat namespace requires unique names. To resolve: ' +
+        '(1) rename one of the conflicting declarations, or ' +
+        '(2) add /** @nodocs */ to exclude from documentation.\n' +
+        details);
+};
+const emitDuplicateDiagnostics = (diagnostics, duplicates) => {
+    for (const [name, occurrences] of duplicates) {
+        const first = occurrences[0];
+        const modules = occurrences.map((o) => o.module);
+        diagnostics.push({
+            kind: 'duplicate_declaration',
+            file: first.module,
+            line: first.declaration.sourceLine,
+            message: `Duplicate declaration "${name}" defined in: ${modules.join(', ')}`,
+            severity: 'warning',
+            declarationName: name,
+            modules,
+        });
+    }
+};
+const dispatchOnDuplicates = (mode, duplicates, log) => {
+    if (duplicates.size === 0)
+        return;
+    if (mode === 'throw') {
+        throw new Error(formatDuplicates(duplicates));
+    }
+    const errorLog = log ?? { error: (msg) => console.error(msg) };
+    if (mode === 'warn') {
+        errorLog.error(formatDuplicates(duplicates));
+        return;
+    }
+    mode(duplicates, errorLog);
+};
+// ── Result types ─────────────────────────────────────────────────────────────
+/**
+ * Result of `analyze`, `analyzeFromFiles`, and `AnalysisSession.query`.
+ *
+ * Modules sorted alphabetically by `path`. Diagnostics are query-time
+ * (analysis-pass) diagnostics only when produced by `session.query`; one-shot
+ * wrappers concatenate ingest + query diagnostics into this same array.
+ *
+ * ## Schema-validated round-trip
+ *
+ * The envelope is a Zod schema (`AnalyzeResultJson`) — both fields default to
+ * `[]`, so `JSON.stringify(result, compactReplacer)` strips empty arrays on
+ * the wire and `AnalyzeResultJson.parse(JSON.parse(json))` restores them.
+ * Consumers programmatically ingesting analysis JSON should parse through the
+ * schema to get defaults restored; raw-JSON consumers (e.g., `jq`) treat
+ * missing keys as null-equivalent (`jq '.diagnostics | length'` returns `0`
+ * on `{}`) and don't need the parse step.
+ *
+ * Construction sites (one-shot wrappers, `session.query`) hand back hand-built
+ * objects without re-running `.parse()` — the inner `modules` and
+ * `diagnostics` arrays are already Zod-validated upstream, and the envelope
+ * schema is the type contract, not a validation gate.
+ */
+export const AnalyzeResultJson = z.strictObject({
+    modules: z.array(ModuleJson).default([]),
+    diagnostics: z.array(Diagnostic).default([]),
+});
+const toModuleAnalyzeResult = (raw) => {
+    const filtered = raw.declarations.filter((d) => !d.nodocs).map((d) => d.declaration);
+    const module = ModuleJson.parse({
+        path: raw.path,
+        declarations: filtered,
+        dependencies: raw.dependencies,
+        dependents: raw.dependents,
+        starExports: raw.starExports,
+        ...(raw.moduleComment ? { moduleComment: raw.moduleComment } : {}),
+    });
+    return { module, reExports: raw.reExports };
+};
+// ── Module dispatch ──────────────────────────────────────────────────────────
+/**
+ * Analyze a single non-Svelte source file and extract module metadata.
+ *
+ * @internal Single-module dispatcher used internally by the two-phase
+ * orchestrator. Importable from `svelte-docinfo/analyze-core.js` for tests
+ * and power users — not part of the stable barrel API and not guaranteed
+ * across minor versions.
+ *
+ * Dispatches on file type:
+ * - TypeScript/JS → `analyzeTypescriptModule`
+ * - CSS/JSON → minimal module (no declarations, dependency tracking only)
+ * - Svelte → `module_skipped: requires_program` (callers using session API
+ *   should not reach this path; the session pre-handles Svelte)
+ *
+ * Returns `undefined` when the file is skipped; the diagnostic is added to
+ * `diagnostics` so the caller can keep iterating.
+ */
+export const analyzeModule = (sourceFile, program, options, diagnostics, log) => {
+    const checker = program.getTypeChecker();
+    const modulePath = extractPath(sourceFile.id, options);
+    const analyzerType = options.getAnalyzerType(sourceFile.id);
+    let raw;
+    if (analyzerType === 'svelte') {
+        diagnostics.push({
+            kind: 'module_skipped',
+            file: modulePath,
+            message: 'Svelte files require program integration. Use createAnalysisSession or analyze()/analyzeFromFiles() instead.',
+            severity: 'warning',
+            reason: 'requires_program',
+        });
+        log?.warn(`Svelte file skipped in analyzeModule: ${sourceFile.id}`);
+        return undefined;
+    }
+    else if (analyzerType === 'typescript') {
+        const tsSourceFile = program.getSourceFile(sourceFile.id);
+        if (!tsSourceFile) {
+            diagnostics.push({
+                kind: 'module_skipped',
+                file: modulePath,
+                message: `Could not get source file from program: ${sourceFile.id}`,
+                severity: 'warning',
+                reason: 'not_in_program',
+            });
+            log?.warn(`Could not get source file from program: ${sourceFile.id}`);
+            return undefined;
+        }
+        raw = analyzeTypescriptModule(sourceFile, tsSourceFile, modulePath, checker, options, diagnostics);
+    }
+    else if (analyzerType === 'css' || analyzerType === 'json') {
+        const { dependencies, dependents } = extractDependencies(sourceFile, options);
+        raw = {
+            path: modulePath,
+            declarations: [],
+            dependencies,
+            dependents,
+            starExports: [],
+            reExports: [],
+        };
+    }
+    else {
+        diagnostics.push({
+            kind: 'module_skipped',
+            file: modulePath,
+            message: `No analyzer for file type: ${sourceFile.id}`,
+            severity: 'warning',
+            reason: 'no_analyzer',
+        });
+        log?.warn(`No analyzer for file: ${sourceFile.id}`);
+        return undefined;
+    }
+    return toModuleAnalyzeResult(raw);
+};
+/**
+ * Run the two-phase analysis loop on pre-prepared inputs.
+ *
+ * @internal Shared two-phase orchestrator used internally by `session.query`
+ * and the one-shot wrappers. Importable from `svelte-docinfo/analyze-core.js`
+ * for tests and power users — not part of the stable barrel API and not
+ * guaranteed across minor versions.
+ *
+ * Phase 1: per-file dispatch (TS / Svelte / CSS / JSON / placeholder for
+ * transform-failed Svelte). Phase 2: re-export merge, component-alias fill,
+ * sort, duplicate detection. Diagnostic paths are normalized to
+ * project-root-relative form before return.
+ *
+ * Dependents are read from `sourceFile.dependents` (caller-supplied via
+ * `extractDependencies`); `analyzeCore` does not compute them. `session.query`
+ * runs `computeDependents` on the owned set before invoking this.
+ */
+export const analyzeCore = (inputs) => {
+    const { sourceFiles, sourceOptions, program, svelteVirtualFiles, transformFailedIds, onDuplicates, log, } = inputs;
+    const checker = program.getTypeChecker();
+    const diagnostics = [];
+    const modules = [];
+    const collectedReExports = [];
+    // Phase 1: analyze every module, collect re-exports
+    for (const sourceFile of sourceFiles) {
+        // Failed-transform Svelte file: synthesize placeholder ModuleJson so
+        // the modules array reflects the full owned set. The originating
+        // transform_failed ingest diagnostic carries the cause; this slot
+        // is purely structural.
+        if (transformFailedIds?.has(sourceFile.id)) {
+            const modulePath = extractPath(sourceFile.id, sourceOptions);
+            const componentName = getComponentName(modulePath);
+            const { dependencies, dependents } = extractDependencies(sourceFile, sourceOptions);
+            modules.push(ModuleJson.parse({
+                path: modulePath,
+                declarations: [],
+                dependencies,
+                dependents,
+                starExports: [],
+                partial: true,
+            }));
+            log?.warn(`Svelte component ${componentName} marked partial (transform failed at ingest)`);
+            continue;
+        }
+        let result;
+        const virtualFile = svelteVirtualFiles.get(sourceFile.id);
+        if (virtualFile) {
+            const modulePath = extractPath(sourceFile.id, sourceOptions);
+            const raw = analyzeSvelteModule(sourceFile, modulePath, checker, sourceOptions, diagnostics, program, virtualFile);
+            if (raw) {
+                result = toModuleAnalyzeResult(raw);
+            }
+            else {
+                log?.error(`Svelte module analysis failed: ${sourceFile.id}`);
+            }
+        }
+        else {
+            result = analyzeModule(sourceFile, program, sourceOptions, diagnostics, log);
+        }
+        if (!result)
+            continue;
+        modules.push(result.module);
+        for (const reExport of result.reExports) {
+            collectedReExports.push({ reExportingModule: result.module.path, reExport });
+        }
+    }
+    // Phase 2a: build alsoExportedFrom arrays
+    mergeReExports(modules, collectedReExports);
+    // Phase 2b: fill component-only fields on renamed component aliases —
+    // canonical components are only fully populated after phase 1 finishes.
+    resolveComponentAliases(modules);
+    const sortedModules = sortModules(modules);
+    // Always run duplicate detection so a `duplicate_declaration` diagnostic
+    // reaches consumers regardless of `onDuplicates`. The `onDuplicates`
+    // callback/shortcut still fires for callers that want fail-fast or custom
+    // handling — diagnostics is the data, `onDuplicates` is the action.
+    const duplicates = findDuplicates(sortedModules);
+    emitDuplicateDiagnostics(diagnostics, duplicates);
+    if (onDuplicates) {
+        dispatchOnDuplicates(onDuplicates, duplicates, log);
+    }
+    normalizeDiagnosticPaths(diagnostics, sourceOptions.projectRoot);
+    return {
+        modules: sortedModules,
+        diagnostics,
+    };
+};
+/**
+ * Normalize `Diagnostic.file` to project-root-relative form, in place.
+ *
+ * Producers inside the analysis pipeline can write absolute paths or virtual
+ * paths (svelte2tsx output like `Foo.svelte.__svelte2tsx__.ts`). This pass
+ * collapses both to the public contract: a path relative to `projectRoot`
+ * with no leading slash and no `./` prefix.
+ *
+ * Exposed for build-tool integrations that bypass the session and collect
+ * their own discovery/dep diagnostics — they need the same normalization to
+ * match the public contract.
+ *
+ * @mutates diagnostics — rewrites each diagnostic's `file` field
+ */
+export const normalizeDiagnosticPaths = (diagnostics, projectRoot) => {
+    const prefix = projectRoot.endsWith('/') ? projectRoot : projectRoot + '/';
+    for (const d of diagnostics) {
+        // Posixify so producers that emitted native-separator paths (e.g., a
+        // custom discovery layer building `path.relative` results on Windows)
+        // match the POSIX prefix derived from the normalized projectRoot.
+        let file = toPosixPath(stripVirtualSuffix(d.file));
+        if (file.startsWith(prefix)) {
+            file = file.slice(prefix.length);
+        }
+        else if (file.startsWith('/')) {
+            // Absolute path outside projectRoot — drop leading slash so display
+            // stays consistent.
+            file = file.slice(1);
+        }
+        d.file = file;
+    }
+};

package/dist/analyze.d.ts

@@ -0,0 +1,137 @@
+/**
+ * One-shot analysis wrappers — `analyze` and `analyzeFromFiles`.
+ *
+ * Both wrap a single-use `AnalysisSession`: `createSession → setFiles → query
+ * → dispose`. Incremental consumers (Vite plugin, LSP) should use
+ * `createAnalysisSession` directly so parsed ASTs and svelte2tsx output
+ * survive between calls.
+ *
+ * - `analyzeFromFiles` — high-level: file discovery from disk + dependency
+ *   resolution + analysis. Recommended for CLI / build-time generation.
+ * - `analyze` — mid-level: caller supplies `SourceFileInfo[]`. For build-tool
+ *   integrations that own discovery but don't run incrementally.
+ *
+ * @see `session.ts` for the persistent session API
+ * @see `analyze-core.ts` for the two-phase orchestrator
+ *
+ * @module
+ */
+import type { AnalysisLog } from './log.js';
+import { type ModuleSourceOptions, type SourceOptionsDefaults } from './source-config.js';
+import { type Discovery } from './discovery.js';
+import { type ResolveImport } from './dep-resolver.js';
+import { type AnalyzeResultJson, type OnDuplicates } from './analyze-core.js';
+import type { SourceFileInfo } from './source.js';
+/**
+ * Options for `analyze`.
+ *
+ * Requires pre-loaded `SourceFileInfo` arrays — use `analyzeFromFiles` for
+ * automatic file discovery and loading from disk, or `createAnalysisSession`
+ * for incremental use.
+ */
+export interface AnalyzeOptions {
+    /** Source files to analyze (must have content loaded). */
+    sourceFiles: ReadonlyArray<SourceFileInfo>;
+    /** Module source options for path extraction and source filtering. */
+    sourceOptions: ModuleSourceOptions;
+    /** Behavior when duplicate declaration names are found across modules. */
+    onDuplicates?: OnDuplicates;
+    /** Optional logger for status and diagnostic messages. */
+    log?: AnalysisLog;
+    /**
+     * Optional custom import resolver for the session default — a bare
+     * `ResolveImportFn` or a token-paired `ImportResolver` (see `ResolveImport`).
+     * For one-shot `analyze()` the session is single-use, so a bare function is
+     * the natural form; pass an `ImportResolver` with a stable `identity` only if
+     * you have a reason to control the cache scope.
+     */
+    resolveImport?: ResolveImport;
+}
+/**
+ * Analyze library source files and extract metadata (one-shot).
+ *
+ * Wraps a single-use `AnalysisSession`. For repeated analyses of the same
+ * source set (e.g., a Vite plugin reacting to file edits), use
+ * `createAnalysisSession` directly.
+ *
+ * @returns analyzed modules (sorted alphabetically) + concatenated ingest +
+ *   query diagnostics
+ * @throws Error if `sourceOptions` validation fails or `tsconfig.json` is
+ *   missing at `projectRoot`. Also propagates `onDuplicates: 'throw'` errors.
+ */
+export declare const analyze: (options: AnalyzeOptions) => Promise<AnalyzeResultJson>;
+/**
+ * Options for `analyzeFromFiles`.
+ *
+ * @see `AnalyzeOptions` for the build-tool-integration API where you supply
+ *   `sourceFiles` and a fully-formed `sourceOptions: ModuleSourceOptions` directly.
+ */
+export interface AnalyzeFromFilesOptions {
+    /** Absolute path to project root directory. */
+    projectRoot: string;
+    /** Partial overrides for default source options (SvelteKit `src/lib` layout). */
+    sourceOptions?: Partial<SourceOptionsDefaults>;
+    /** Behavior when duplicate declaration names are found across modules. */
+    onDuplicates?: OnDuplicates;
+    /** Optional logger for status and diagnostic messages. */
+    log?: AnalysisLog;
+    /**
+     * Glob patterns to include (relative to `projectRoot`).
+     *
+     * Filters glob-based discovery. Providing `include` under the default
+     * `discovery: 'auto'` collapses the chain to glob immediately; combining
+     * with `discovery: 'exports'` throws.
+     *
+     * When omitted, the glob fallback derives an include from
+     * `sourceOptions.sourcePaths` via `deriveIncludePatterns`, so custom
+     * `sourcePaths` (e.g., `['packages/foo']`) survive the fallback instead of
+     * silently defaulting to `src/lib`.
+     */
+    include?: Array<string>;
+    /** Glob patterns to exclude — fully replaces `sourceOptions.exclude` (no merge). */
+    exclude?: Array<string>;
+    /**
+     * Whether to resolve import dependencies (default `true`).
+     *
+     * When `false`, the session uses a no-op resolver that always returns
+     * `null`, so `ModuleJson.dependencies` / `dependents` stay empty.
+     * `analyzeFromFiles`'s discovery layer does not pre-populate
+     * `SourceFileInfo.dependencies`, so the session's pre-resolved fast path
+     * isn't reachable through this API — to exercise it, drive `analyze` or
+     * `createAnalysisSession` directly with files whose `dependencies` field
+     * is already filled in by your build tool.
+     *
+     * @default `true`
+     */
+    resolveDependencies?: boolean;
+    /**
+     * Optional custom import resolver — a bare `ResolveImportFn` or a
+     * token-paired `ImportResolver` (see `ResolveImport`). One-shot use doesn't
+     * benefit from a stable cache identity, so the bare function form is the
+     * natural choice here; for long-lived consumers (Vite plugin, LSP) construct
+     * an `ImportResolver` with a stable `identity` and pass it via
+     * `createAnalysisSession` so cache hits survive across calls.
+     *
+     * Cannot be combined with `resolveDependencies: false` — resolution is then
+     * off, so the resolver would never be consulted; passing both throws.
+     */
+    resolveImport?: ResolveImport;
+    /** Discovery strategy for source files. @default 'auto' */
+    discovery?: Discovery;
+    /** Dist directory name for exports-based discovery. @default 'dist' */
+    distDir?: string;
+}
+/**
+ * Analyze a library from files on disk with automatic file discovery.
+ *
+ * Recommended high-level API for one-shot use (CLI, build-time generation):
+ *
+ * 1. **Discovery** — `discoverSourceFiles` (exports-first, glob fallback)
+ * 2. **Ingest** — push discovered files into a single-use session
+ * 3. **Analysis** — `session.query()`
+ *
+ * @returns analyzed modules + concatenated ingest, discovery, and query diagnostics
+ * @throws Error if `sourceOptions` validation fails or `tsconfig.json` is missing
+ */
+export declare const analyzeFromFiles: (options: AnalyzeFromFilesOptions) => Promise<AnalyzeResultJson>;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,UAAU,CAAC;AAE1C,OAAO,EAEN,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAsB,KAAK,SAAS,EAAC,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAiB,KAAK,aAAa,EAAC,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAEN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,aAAa,CAAC;AAIhD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,0DAA0D;IAC1D,WAAW,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC3C,sEAAsE;IACtE,aAAa,EAAE,mBAAmB,CAAC;IACnC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAAU,SAAS,cAAc,KAAG,OAAO,CAAC,iBAAiB,CAkBhF,CAAC;AAIF;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,aAAa,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC/C,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,oFAAoF;IACpF,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAC5B,SAAS,uBAAuB,KAC9B,OAAO,CAAC,iBAAiB,CAqG3B,CAAC"}

package/dist/analyze.js

@@ -0,0 +1,148 @@
+/**
+ * One-shot analysis wrappers — `analyze` and `analyzeFromFiles`.
+ *
+ * Both wrap a single-use `AnalysisSession`: `createSession → setFiles → query
+ * → dispose`. Incremental consumers (Vite plugin, LSP) should use
+ * `createAnalysisSession` directly so parsed ASTs and svelte2tsx output
+ * survive between calls.
+ *
+ * - `analyzeFromFiles` — high-level: file discovery from disk + dependency
+ *   resolution + analysis. Recommended for CLI / build-time generation.
+ * - `analyze` — mid-level: caller supplies `SourceFileInfo[]`. For build-tool
+ *   integrations that own discovery but don't run incrementally.
+ *
+ * @see `session.ts` for the persistent session API
+ * @see `analyze-core.ts` for the two-phase orchestrator
+ *
+ * @module
+ */
+import { errorsOf, formatDiagnostic, warningsOf } from './diagnostics.js';
+import { createAnalysisSession } from './session.js';
+import { createSourceOptions, } from './source-config.js';
+import { discoverSourceFiles } from './discovery.js';
+import { noDepsResolver } from './dep-resolver.js';
+import { normalizeDiagnosticPaths, } from './analyze-core.js';
+/**
+ * Analyze library source files and extract metadata (one-shot).
+ *
+ * Wraps a single-use `AnalysisSession`. For repeated analyses of the same
+ * source set (e.g., a Vite plugin reacting to file edits), use
+ * `createAnalysisSession` directly.
+ *
+ * @returns analyzed modules (sorted alphabetically) + concatenated ingest +
+ *   query diagnostics
+ * @throws Error if `sourceOptions` validation fails or `tsconfig.json` is
+ *   missing at `projectRoot`. Also propagates `onDuplicates: 'throw'` errors.
+ */
+export const analyze = async (options) => {
+    const session = createAnalysisSession({
+        sourceOptions: options.sourceOptions,
+        log: options.log,
+        resolveImport: options.resolveImport,
+    });
+    try {
+        const ingest = await session.setFiles(options.sourceFiles);
+        const query = session.query({ onDuplicates: options.onDuplicates, log: options.log });
+        // Concat is safe by spec — ingest diagnostics are paths-normalized in
+        // session.setFiles; query diagnostics are normalized in analyze-core.
+        return {
+            modules: query.modules,
+            diagnostics: [...ingest.diagnostics, ...query.diagnostics],
+        };
+    }
+    finally {
+        session.dispose();
+    }
+};
+/**
+ * Analyze a library from files on disk with automatic file discovery.
+ *
+ * Recommended high-level API for one-shot use (CLI, build-time generation):
+ *
+ * 1. **Discovery** — `discoverSourceFiles` (exports-first, glob fallback)
+ * 2. **Ingest** — push discovered files into a single-use session
+ * 3. **Analysis** — `session.query()`
+ *
+ * @returns analyzed modules + concatenated ingest, discovery, and query diagnostics
+ * @throws Error if `sourceOptions` validation fails or `tsconfig.json` is missing
+ */
+export const analyzeFromFiles = async (options) => {
+    const { projectRoot, include, exclude, resolveDependencies: shouldResolveDependencies = true, resolveImport, sourceOptions, onDuplicates, log, discovery, distDir, } = options;
+    // A custom resolver with resolution turned off is a contradiction — the
+    // resolver would never be consulted. Fail fast rather than silently dropping
+    // it (mirrors the `discovery: 'exports'` + `include` config-error throw).
+    if (!shouldResolveDependencies && resolveImport !== undefined) {
+        throw new Error('`resolveImport` cannot be combined with `resolveDependencies: false` — ' +
+            'dependency resolution is disabled, so the resolver would never be consulted. ' +
+            'Remove `resolveImport`, or set `resolveDependencies: true` (the default).');
+    }
+    // Top-level `exclude` is an ergonomic shortcut that fully replaces
+    // `sourceOptions.exclude` (no array merge). Apply before
+    // `createSourceOptions` so the normalized options carry a single source
+    // of truth.
+    const mergedSourceOptions = exclude !== undefined ? { ...sourceOptions, exclude } : sourceOptions;
+    const resolvedSourceOptions = createSourceOptions(projectRoot, mergedSourceOptions);
+    const normalizedProjectRoot = resolvedSourceOptions.projectRoot;
+    // Step 1: discover files.
+    const { files: discoveredFiles, diagnostics: discoveryDiagnostics } = await discoverSourceFiles({
+        sourceOptions: resolvedSourceOptions,
+        include,
+        discovery,
+        distDir,
+        log,
+    });
+    // Step 2: build the session-default resolver. When dep-resolution is
+    // disabled, install the shared no-deps resolver so the session's lex+resolve
+    // passes surface no edges (faster than relying on the default resolver to
+    // return null for everything). Otherwise forward the caller's resolver — the
+    // session normalizes the `ResolveImport` union (bare fn or token-paired) and
+    // falls back to its TS+tsconfig default when undefined.
+    const sessionResolver = shouldResolveDependencies
+        ? resolveImport
+        : noDepsResolver;
+    // Step 3: ingest + analyze via single-use session.
+    const session = createAnalysisSession({
+        sourceOptions: resolvedSourceOptions,
+        log,
+        resolveImport: sessionResolver,
+    });
+    let result;
+    try {
+        const ingest = await session.setFiles(discoveredFiles);
+        const query = session.query({ onDuplicates, log });
+        result = {
+            modules: query.modules,
+            diagnostics: [...ingest.diagnostics, ...query.diagnostics],
+        };
+    }
+    finally {
+        session.dispose();
+    }
+    // Merge discovery diagnostics. `analyzeCore` and the session both already
+    // normalized their own; normalize discovery in place (idempotent for paths
+    // already project-relative) and append.
+    normalizeDiagnosticPaths(discoveryDiagnostics, normalizedProjectRoot);
+    for (const d of discoveryDiagnostics)
+        result.diagnostics.push(d);
+    if (log && shouldResolveDependencies) {
+        const totalDeps = result.modules.reduce((sum, m) => sum + m.dependencies.length, 0);
+        log.info(`Resolved ${totalDeps} module dependency edges`);
+    }
+    if (log && result.diagnostics.length > 0) {
+        const errors = errorsOf(result.diagnostics);
+        const warnings = warningsOf(result.diagnostics);
+        if (errors.length > 0) {
+            log.error(`Analysis completed with ${errors.length} error(s):`);
+            for (const diagnostic of errors) {
+                log.error(`  ${formatDiagnostic(diagnostic)}`);
+            }
+        }
+        if (warnings.length > 0) {
+            log.warn(`Analysis completed with ${warnings.length} warning(s):`);
+            for (const diagnostic of warnings) {
+                log.warn(`  ${formatDiagnostic(diagnostic)}`);
+            }
+        }
+    }
+    return result;
+};