svelte-docinfo 0.1.0

package/dist/diagnostics.js

@@ -0,0 +1,377 @@
+/**
+ * Diagnostic collection for source analysis.
+ *
+ * Provides structured error/warning collection during TypeScript and Svelte
+ * analysis, replacing silent catch blocks with actionable diagnostics.
+ *
+ * ## Error Handling Contract
+ *
+ * The pipeline accumulates failures into the `diagnostics` array and keeps
+ * going — analysis continues, declarations/members reach the output with
+ * `partial: true` when extraction failed mid-flight, and the caller decides
+ * how to react. Producers include type resolution failures, individual
+ * member/prop extraction failures, svelte2tsx transform failures, source-map
+ * construction failures, import lex / resolver failures, and duplicate
+ * declarations.
+ *
+ * A small set of conditions still throws from public entry points — these are
+ * setup-level, not per-file: missing `tsconfig.json` (`loadTsconfig`), Svelte
+ * <5 detected (`transformSvelteSource`), or strict `discovery: 'exports'`
+ * mode with no resolvable exports (`discoverSourceFiles`). Wrap the top-level
+ * `analyze` / `analyzeFromFiles` call if you want to handle these.
+ *
+ * ## Usage Pattern
+ *
+ * ```ts
+ * const {modules, diagnostics} = await analyze({sourceFiles, sourceOptions});
+ *
+ * if (hasErrors(diagnostics)) {
+ *   for (const err of errorsOf(diagnostics)) {
+ *     console.error(formatDiagnostic(err));
+ *   }
+ * }
+ * for (const warning of warningsOf(diagnostics)) {
+ *   console.warn(formatDiagnostic(warning));
+ * }
+ * ```
+ *
+ * ## Schema-Validated Plain Data
+ *
+ * `AnalyzeResultJson.diagnostics` is `Array<Diagnostic>` — no wrapper object,
+ * no methods, no private fields. Round-trip-safe through `JSON.stringify` /
+ * `z.array(Diagnostic).parse` and symmetric with `AnalyzeResultJson.modules`
+ * (also Zod-validated). The full envelope is itself a Zod schema
+ * (`AnalyzeResultJson` in `analyze-core.ts`) with both fields defaulting to
+ * `[]`, so the whole `{modules, diagnostics}` shape round-trips through
+ * `JSON.stringify(result, compactReplacer)` / `AnalyzeResultJson.parse` even
+ * when one or both arrays are empty (the wire form becomes `{}` and `.parse()`
+ * restores the defaults). Use the free helpers `hasErrors`, `errorsOf`,
+ * `byKind` for queries; mutate the array with native `Array.push`.
+ *
+ * ## File Path Contract
+ *
+ * `Diagnostic.file` is always project-root-relative — no leading slash,
+ * no `./` prefix. `analyze` / `analyzeFromFiles` normalize paths from all
+ * sources (extraction, discovery, dependency resolution) before returning.
+ * Consumers that need an absolute path can rejoin with `projectRoot`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+// ── Severity ─────────────────────────────────────────────────────────────────
+/**
+ * Diagnostic severity levels.
+ *
+ * - `'error'` — analysis failed, declaration may be incomplete or missing data
+ * - `'warning'` — partial success, something seems off but analysis continued
+ */
+export const DiagnosticSeverity = z.enum(['error', 'warning']);
+// ── Kind ─────────────────────────────────────────────────────────────────────
+/**
+ * Discriminant for `Diagnostic` variant types.
+ */
+export const DiagnosticKind = z.enum([
+    'type_extraction_failed',
+    'signature_analysis_failed',
+    'class_member_failed',
+    'svelte_prop_failed',
+    'module_skipped',
+    'module_unreadable',
+    'import_parse_failed',
+    'duplicate_comment',
+    'misplaced_tag',
+    'unknown_param',
+    'source_map_failed',
+    'duplicate_declaration',
+    'transform_failed',
+    'resolver_failed',
+]);
+// ── Variants ─────────────────────────────────────────────────────────────────
+/**
+ * Base diagnostic fields shared by every variant.
+ *
+ * `line` / `column` are 1-based and `.optional()` — absent when the diagnostic
+ * has no precise source location (e.g., a module-level skip with no specific
+ * AST node). Mirrors the rest of the schema's "absent = missing key" rule;
+ * use `??` at the call site if you need a placeholder.
+ */
+const baseDiagnosticFields = {
+    /**
+     * File path relative to project root (no leading slash, no `./` prefix).
+     *
+     * Normalized at every public API boundary — `session.setFile`/`setFiles`
+     * (ingest-time), `session.query` (query-time, via `analyzeCore`), and the
+     * one-shot wrappers `analyze` / `analyzeFromFiles`. Producers inside the
+     * pipeline may write absolute or virtual paths (e.g.,
+     * `Foo.svelte.__svelte2tsx__.ts`); normalization rewrites them to
+     * project-relative form before they reach consumers.
+     */
+    file: z.string(),
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.number().int().positive().optional(),
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.number().int().positive().optional(),
+    /** Human-readable description of the issue. */
+    message: z.string(),
+    severity: DiagnosticSeverity,
+};
+/**
+ * Type extraction failed (e.g., complex or recursive types).
+ */
+export const TypeExtractionDiagnostic = z.strictObject({
+    kind: z.literal('type_extraction_failed'),
+    ...baseDiagnosticFields,
+    /** Name of the symbol whose type couldn't be extracted. */
+    symbolName: z.string(),
+});
+/**
+ * Function/method signature analysis failed.
+ */
+export const SignatureAnalysisDiagnostic = z.strictObject({
+    kind: z.literal('signature_analysis_failed'),
+    ...baseDiagnosticFields,
+    /** Name of the function or method. */
+    functionName: z.string(),
+});
+/**
+ * Class member analysis failed.
+ */
+export const ClassMemberDiagnostic = z.strictObject({
+    kind: z.literal('class_member_failed'),
+    ...baseDiagnosticFields,
+    /** Name of the class. */
+    className: z.string(),
+    /** Name of the member that failed. */
+    memberName: z.string(),
+});
+/**
+ * Svelte prop type resolution failed.
+ */
+export const SveltePropDiagnostic = z.strictObject({
+    kind: z.literal('svelte_prop_failed'),
+    ...baseDiagnosticFields,
+    /** Name of the component. */
+    componentName: z.string(),
+    /** Name of the prop. */
+    propName: z.string(),
+});
+/**
+ * Module was skipped during the analysis pass.
+ *
+ * Always `warning` severity — the rest of the analysis still runs and the
+ * module's absence in `modules` reflects the skip. Reasons:
+ *
+ * - `not_in_program` — the file wasn't in the `ts.Program` (race between
+ *   session ingest and `query`, or virtual file missing for a `.svelte`)
+ * - `no_analyzer` — file extension didn't match any analyzer
+ * - `requires_program` — Svelte file reached the non-Svelte dispatcher (caller
+ *   should use the session API instead of `analyzeModule` directly)
+ *
+ * Discovery-time file-read failures are a separate kind: `module_unreadable`.
+ */
+export const ModuleSkippedDiagnostic = z.strictObject({
+    kind: z.literal('module_skipped'),
+    ...baseDiagnosticFields,
+    /** Reason the module was skipped. */
+    reason: z.enum(['not_in_program', 'no_analyzer', 'requires_program']),
+});
+/**
+ * File discovered via package.json `exports` exists but couldn't be read.
+ *
+ * Always `error` severity — discovery-time, emitted by `discoverFromExports`
+ * when `readFile` fails (permission denied, FS error). Distinct from
+ * `module_skipped` so severity is a stable per-kind property and downstream
+ * consumers can route discovery failures separately from analysis-pass skips.
+ */
+export const ModuleUnreadableDiagnostic = z.strictObject({
+    kind: z.literal('module_unreadable'),
+    ...baseDiagnosticFields,
+});
+/**
+ * Import parsing failed during dependency resolution.
+ */
+export const ImportParseDiagnostic = z.strictObject({
+    kind: z.literal('import_parse_failed'),
+    ...baseDiagnosticFields,
+});
+/**
+ * Duplicate comment sources detected (e.g., both HTML and JSDoc `@module`,
+ * or both HTML `@component` and JSDoc for component `docComment`).
+ */
+export const DuplicateCommentDiagnostic = z.strictObject({
+    kind: z.literal('duplicate_comment'),
+    ...baseDiagnosticFields,
+    /** Which comment type is duplicated. */
+    commentType: z.enum(['module_comment', 'doc_comment']),
+});
+/**
+ * Symbol-scope JSDoc tag (`@example`, `@deprecated`, `@since`, `@see`,
+ * `@throws`, `@mutates`, `@default`, `@nodocs`) found on a non-primary overload
+ * signature.
+ *
+ * Symbol-scope tags describe the function as a whole, not individual
+ * signatures. The primary signature's JSDoc feeds the parent declaration's
+ * symbol-level extraction; tags on non-primary overload signatures are
+ * silently dropped from output. This diagnostic surfaces them so authors
+ * can move them to the primary signature.
+ *
+ * `@default` and `@nodocs` are included here even though overloads never
+ * carry a `defaultValue` or per-overload exclusion: their presence on a
+ * non-primary signature is always a misplacement.
+ */
+export const MisplacedTagDiagnostic = z.strictObject({
+    kind: z.literal('misplaced_tag'),
+    ...baseDiagnosticFields,
+    /** The tag name without the `@` prefix (e.g., `'example'`, `'deprecated'`). */
+    tagName: z.enum([
+        'example',
+        'deprecated',
+        'since',
+        'see',
+        'throws',
+        'mutates',
+        'default',
+        'nodocs',
+    ]),
+    /** Name of the function or method whose overload carries the misplaced tag. */
+    functionName: z.string(),
+});
+/**
+ * `@param` tag references a name that doesn't match any actual parameter.
+ *
+ * Usually a typo (`@param argz` for parameter `args`) or stale doc after a
+ * rename. The description is dropped; analysis continues.
+ */
+export const UnknownParamDiagnostic = z.strictObject({
+    kind: z.literal('unknown_param'),
+    ...baseDiagnosticFields,
+    /** The `@param` key that didn't match a real parameter. */
+    paramName: z.string(),
+    /** Name of the function or method. */
+    functionName: z.string(),
+});
+/**
+ * A declaration `name` appears in more than one module.
+ *
+ * Library docs assume a flat namespace — two modules exporting the same name
+ * collide when consumers `import {name}`. Emitted at `warning` severity so
+ * the analysis result remains usable; consumers who want it fatal can promote
+ * via `onDuplicates: 'throw'` or by inspecting the diagnostic. The default
+ * slot (`name === 'default'`) is excluded — every module owns its own.
+ */
+export const DuplicateDeclarationDiagnostic = z.strictObject({
+    kind: z.literal('duplicate_declaration'),
+    ...baseDiagnosticFields,
+    /** The duplicated declaration name. */
+    declarationName: z.string(),
+    /** Module paths where the name was defined (>= 2). */
+    modules: z.array(z.string()).min(2),
+});
+/**
+ * Source map parsing failed for a Svelte virtual file.
+ *
+ * Analysis continues using virtual-file positions, so downstream `line`/`column`
+ * fields on other diagnostics may point into the svelte2tsx-generated TS rather
+ * than the original `.svelte` source. Rare; usually signals a malformed or
+ * incompatible svelte2tsx output.
+ *
+ * Emitted at ingest time by `transformSvelteSource` (in `svelte.ts`); flows
+ * through `setFile`/`setFiles` ingest diagnostics rather than the analysis
+ * pass.
+ */
+export const SourceMapFailedDiagnostic = z.strictObject({
+    kind: z.literal('source_map_failed'),
+    ...baseDiagnosticFields,
+});
+/**
+ * svelte2tsx transform threw for a `.svelte` file.
+ *
+ * Unrecoverable at ingest — the file's owned-entry stays in the session
+ * (`virtual: undefined`, `unfilteredDeps: []`, `transformFailed: true`) so
+ * `query()` can synthesize a placeholder `ModuleJson` (`partial: true`,
+ * empty `declarations`). The originating error message lives in `message`;
+ * this diagnostic is the authoritative cause-of-failure signal.
+ */
+export const TransformFailedDiagnostic = z.strictObject({
+    kind: z.literal('transform_failed'),
+    ...baseDiagnosticFields,
+});
+/**
+ * Import resolver threw while resolving a specifier.
+ *
+ * Distinguishes a buggy resolver from a legitimately unresolvable specifier:
+ * resolvers that return `null` for unknown specifiers stay silent (the normal
+ * "external package" case); resolvers that *throw* surface here so consumers
+ * can fix the resolver. Recoverable — the session treats the throw as `null`
+ * and continues, so analysis still runs but with a missing dependency edge.
+ *
+ * Emitted at ingest time by the session's resolve phase.
+ */
+export const ResolverFailedDiagnostic = z.strictObject({
+    kind: z.literal('resolver_failed'),
+    ...baseDiagnosticFields,
+    /** The import specifier the resolver failed on. */
+    specifier: z.string(),
+});
+/**
+ * Discriminated union of all diagnostic variants.
+ */
+export const Diagnostic = z.discriminatedUnion('kind', [
+    TypeExtractionDiagnostic,
+    SignatureAnalysisDiagnostic,
+    ClassMemberDiagnostic,
+    SveltePropDiagnostic,
+    ModuleSkippedDiagnostic,
+    ModuleUnreadableDiagnostic,
+    ImportParseDiagnostic,
+    DuplicateCommentDiagnostic,
+    MisplacedTagDiagnostic,
+    UnknownParamDiagnostic,
+    SourceMapFailedDiagnostic,
+    DuplicateDeclarationDiagnostic,
+    TransformFailedDiagnostic,
+    ResolverFailedDiagnostic,
+]);
+// ── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Check if any error-severity diagnostics were collected.
+ */
+export const hasErrors = (diagnostics) => diagnostics.some((d) => d.severity === 'error');
+/**
+ * Check if any warning-severity diagnostics were collected.
+ */
+export const hasWarnings = (diagnostics) => diagnostics.some((d) => d.severity === 'warning');
+/**
+ * Get all error-severity diagnostics.
+ */
+export const errorsOf = (diagnostics) => diagnostics.filter((d) => d.severity === 'error');
+/**
+ * Get all warning-severity diagnostics.
+ */
+export const warningsOf = (diagnostics) => diagnostics.filter((d) => d.severity === 'warning');
+/**
+ * Get diagnostics of a specific kind, narrowed to the matching variant.
+ */
+export const byKind = (diagnostics, kind) => diagnostics.filter((d) => d.kind === kind);
+/**
+ * Format a diagnostic for display.
+ *
+ * Assumes `diagnostic.file` is project-root-relative (the contract enforced
+ * by `analyze` / `analyzeFromFiles`). The displayed path is prefixed with `./`.
+ *
+ * @param diagnostic - the diagnostic to format
+ * @returns formatted string like `'./file.ts:10:5: error: message'`
+ *
+ * @example
+ * ```ts
+ * for (const d of errorsOf(diagnostics)) {
+ *   console.error(formatDiagnostic(d));
+ * }
+ * ```
+ */
+export const formatDiagnostic = (diagnostic) => {
+    const { file, line, column, severity, message } = diagnostic;
+    const location = line !== undefined ? (column !== undefined ? `${line}:${column}` : `${line}`) : '';
+    const filePart = location ? `./${file}:${location}` : `./${file}`;
+    return `${filePart}: ${severity}: ${message}`;
+};

package/dist/discovery.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Source file discovery — exports-first with glob fallback.
+ *
+ * Used by `analyzeFromFiles` to locate source files from a project root.
+ * Build tool integrations using `analyze` should construct `SourceFileInfo[]`
+ * from their own module graph instead.
+ *
+ * @see `exports.ts` for `discoverFromExports` (package.json exports → source files)
+ * @see `files.ts` for `globFiles` (glob-based discovery)
+ *
+ * @module
+ */
+import type { SourceFileInfo } from './source.js';
+import { type ModuleSourceOptions } from './source-config.js';
+import type { Diagnostic } from './diagnostics.js';
+import type { AnalysisLog } from './log.js';
+/**
+ * Discovery strategy for source files.
+ *
+ * - `'auto'` (default) — try package.json `exports` first, fall back to glob
+ *   patterns when `exports` is missing or resolves to nothing
+ * - `'exports'` — package.json `exports` only, **throw** if `exports` is missing
+ *   or resolves to no source files (strict mode for libraries that should
+ *   always declare their public surface via `exports`)
+ * - `'glob'` — skip `exports` entirely, use glob patterns
+ *
+ * Providing `include` patterns implies `'glob'` semantics regardless of mode
+ * — when `discovery: 'auto'` and `include` is set, the auto fallback chain
+ * collapses to glob immediately. Combining `discovery: 'exports'` with
+ * `include` is a configuration error (the modes are contradictory) and
+ * throws at discovery time.
+ */
+export type Discovery = 'auto' | 'exports' | 'glob';
+/** Options for `discoverSourceFiles`. */
+export interface DiscoverSourceFilesOptions {
+    /**
+     * Source options used to resolve the source directory for exports-based discovery.
+     *
+     * `sourceOptions.projectRoot` is the resolution base for `include` globs and the
+     * `sourceOptions.exclude` glob patterns. Build via `createSourceOptions` (which
+     * normalizes) or pass a normalized return from `normalizeSourceOptions`.
+     *
+     * `sourceOptions.exclude` is the single source of truth for exclusion globs —
+     * applied at both this discovery stage and analysis time (via `isSource()`).
+     */
+    sourceOptions: ModuleSourceOptions;
+    /**
+     * Glob patterns to include (relative to `projectRoot`).
+     *
+     * Filter for glob-based discovery. When `discovery` is `'auto'` (default),
+     * providing `include` collapses the chain to glob immediately. Combining
+     * `include` with `discovery: 'exports'` throws.
+     *
+     * When omitted, the glob fallback derives an include pattern from
+     * `sourceOptions.sourcePaths` via `deriveIncludePatterns`, so custom
+     * `sourcePaths` (e.g., `['packages/foo']`) discover files instead of
+     * silently defaulting to `src/lib`.
+     */
+    include?: Array<string>;
+    /**
+     * Discovery strategy.
+     *
+     * @default 'auto'
+     * @see {@link Discovery} for semantics of each variant
+     */
+    discovery?: Discovery;
+    /**
+     * Dist directory name relative to `projectRoot`, used for exports-based discovery.
+     *
+     * Maps dist paths from package.json exports back to source paths.
+     *
+     * @default 'dist'
+     */
+    distDir?: string;
+    /** Optional logger for status messages. */
+    log?: AnalysisLog;
+}
+/** Result of `discoverSourceFiles`. */
+export interface DiscoverSourceFilesResult {
+    /** Discovered source files with content already loaded. */
+    files: Array<SourceFileInfo>;
+    /** Diagnostics collected during discovery (e.g., malformed package.json exports). */
+    diagnostics: Array<Diagnostic>;
+}
+/**
+ * Discover source files from a project root.
+ *
+ * Used internally by `analyzeFromFiles` for the discovery step. Standalone
+ * consumers can call it directly when they want the discovered file list
+ * without running full analysis.
+ *
+ * Strategy is selected by `discovery`:
+ * - `'auto'` (default) — try `exports` first, fall back to glob.
+ * - `'exports'` — `exports` only; **throws** if `exports` is missing or
+ *   resolves to no source files. Combining with `include` is a configuration
+ *   error and also throws.
+ * - `'glob'` — glob only; `include` parameterizes the search.
+ *
+ * Exclusion globs come from `sourceOptions.exclude` (the single source of
+ * truth, also applied at analysis time by `isSource()`).
+ *
+ * @param options - discovery configuration
+ * @returns discovered files (content loaded) and any diagnostics from the exports step
+ * @throws Error in strict `'exports'` mode when `exports` is missing or
+ *   resolves to no source files, or when `include` is combined with
+ *   `discovery: 'exports'`.
+ *
+ * @example
+ * ```ts
+ * const sourceOptions = createSourceOptions(process.cwd());
+ * const {files, diagnostics} = await discoverSourceFiles({sourceOptions});
+ * ```
+ */
+export declare const discoverSourceFiles: (options: DiscoverSourceFilesOptions) => Promise<DiscoverSourceFilesResult>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,aAAa,CAAC;AAChD,OAAO,EAAC,KAAK,mBAAmB,EAAgB,MAAM,oBAAoB,CAAC;AAC3E,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,UAAU,CAAC;AAI1C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpD,yCAAyC;AACzC,MAAM,WAAW,0BAA0B;IAC1C;;;;;;;;;OASG;IACH,aAAa,EAAE,mBAAmB,CAAC;IAEnC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAExB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,WAAW,CAAC;CAClB;AAED,uCAAuC;AACvC,MAAM,WAAW,yBAAyB;IACzC,2DAA2D;IAC3D,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC7B,qFAAqF;IACrF,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,mBAAmB,GAC/B,SAAS,0BAA0B,KACjC,OAAO,CAAC,yBAAyB,CAgGnC,CAAC"}

package/dist/discovery.js

@@ -0,0 +1,126 @@
+/**
+ * Source file discovery — exports-first with glob fallback.
+ *
+ * Used by `analyzeFromFiles` to locate source files from a project root.
+ * Build tool integrations using `analyze` should construct `SourceFileInfo[]`
+ * from their own module graph instead.
+ *
+ * @see `exports.ts` for `discoverFromExports` (package.json exports → source files)
+ * @see `files.ts` for `globFiles` (glob-based discovery)
+ *
+ * @module
+ */
+import { getSourceRoot } from './source-config.js';
+import { globFiles, deriveIncludePatterns } from './files.js';
+import { discoverFromExports } from './exports.js';
+/**
+ * Discover source files from a project root.
+ *
+ * Used internally by `analyzeFromFiles` for the discovery step. Standalone
+ * consumers can call it directly when they want the discovered file list
+ * without running full analysis.
+ *
+ * Strategy is selected by `discovery`:
+ * - `'auto'` (default) — try `exports` first, fall back to glob.
+ * - `'exports'` — `exports` only; **throws** if `exports` is missing or
+ *   resolves to no source files. Combining with `include` is a configuration
+ *   error and also throws.
+ * - `'glob'` — glob only; `include` parameterizes the search.
+ *
+ * Exclusion globs come from `sourceOptions.exclude` (the single source of
+ * truth, also applied at analysis time by `isSource()`).
+ *
+ * @param options - discovery configuration
+ * @returns discovered files (content loaded) and any diagnostics from the exports step
+ * @throws Error in strict `'exports'` mode when `exports` is missing or
+ *   resolves to no source files, or when `include` is combined with
+ *   `discovery: 'exports'`.
+ *
+ * @example
+ * ```ts
+ * const sourceOptions = createSourceOptions(process.cwd());
+ * const {files, diagnostics} = await discoverSourceFiles({sourceOptions});
+ * ```
+ */
+export const discoverSourceFiles = async (options) => {
+    const { sourceOptions, include, discovery = 'auto', distDir, log } = options;
+    const { projectRoot, exclude } = sourceOptions;
+    // Reject contradictory configurations early. `include` parameterizes glob,
+    // so combining it with strict `'exports'` is a user error rather than a
+    // silent override.
+    if (discovery === 'exports' && include) {
+        throw new Error("discovery: 'exports' is incompatible with `include` — `include` is a glob filter. " +
+            "Use discovery: 'glob' (with include) or remove include for strict exports mode.");
+    }
+    // `include` collapses 'auto' to glob immediately — exports-discovery has
+    // no concept of include patterns, so honoring `include` under 'auto' would
+    // silently drop the user's filter on packages that have an `exports` field.
+    const effectiveStrategy = discovery === 'auto' && include ? 'glob' : discovery;
+    let files = null;
+    let diagnostics = [];
+    if (effectiveStrategy === 'exports' || effectiveStrategy === 'auto') {
+        const sourceDir = getSourceRoot(sourceOptions);
+        // Exports discovery is single-`sourceDir`-only: it maps every dist path
+        // through one source-dir prefix. When `sourcePaths.length > 1` and the
+        // auto-derived (or explicit) `sourceRoot` is `''`, every dist entry
+        // would resolve to project-root-relative paths instead of the user's
+        // actual subdirs — exports discovery cannot represent the layout.
+        // Short-circuit instead of letting it silently produce zero files
+        // (under 'auto' that falls through harmlessly to glob, but under
+        // 'exports' it would throw the misleading generic "resolved to no
+        // source files" error).
+        if (sourceOptions.sourcePaths.length > 1 && sourceDir === '') {
+            if (effectiveStrategy === 'exports') {
+                throw new Error("discovery: 'exports' failed — source paths share no common prefix " +
+                    `(sourcePaths=${JSON.stringify(sourceOptions.sourcePaths)}, sourceRoot=''), ` +
+                    'so exports discovery cannot map dist paths to source files. ' +
+                    "Use discovery: 'auto' (default) or 'glob' for this layout, or " +
+                    'restructure to a single source root.');
+            }
+            log?.info('Source paths share no common prefix — exports discovery cannot represent this layout; falling back to glob patterns');
+        }
+        else {
+            const exportsResult = await discoverFromExports({
+                projectRoot,
+                exclude,
+                sourceDir,
+                distDir,
+            });
+            const { files: exportsFiles, diagnostics: exportsDiagnostics } = exportsResult;
+            diagnostics = exportsDiagnostics;
+            if (exportsFiles && exportsFiles.length > 0) {
+                files = exportsFiles;
+                log?.info(`Discovered ${files.length} source files from package.json exports`);
+            }
+            else if (effectiveStrategy === 'exports') {
+                // Strict mode: no fallback. Throw with a message that names the
+                // failure mode so users can fix the package.json or relax the strictness.
+                const reason = exportsFiles === null
+                    ? 'no `exports` field found in package.json'
+                    : '`exports` field present but resolved to no source files';
+                throw new Error(`discovery: 'exports' failed — ${reason}. ` +
+                    `Use discovery: 'auto' (default) to fall back to glob, or fix the package.json exports mapping.`);
+            }
+            else if (exportsFiles === null) {
+                log?.info('No package.json exports found, falling back to glob patterns');
+            }
+            else {
+                log?.warn('Package.json exports found but resolved no source files — falling back to glob patterns');
+            }
+        }
+    }
+    // Fall back to glob-based discovery (auto fallback or explicit glob mode).
+    // Derive include from `sourceOptions.sourcePaths` when none is supplied so
+    // custom `sourcePaths` (e.g. `['packages/foo']`) discover files instead of
+    // silently defaulting to `src/lib`. Mirrors the CLI's prior local
+    // derivation — single source of truth lives here now.
+    if (!files) {
+        files = await globFiles({
+            projectRoot,
+            include: include ?? deriveIncludePatterns(sourceOptions.sourcePaths),
+            exclude,
+        });
+        log?.info(`Discovered ${files.length} source files via glob`);
+    }
+    return { files, diagnostics };
+};