svelte-docinfo 0.1.0

package/dist/diagnostics.d.ts

@@ -0,0 +1,650 @@
+/**
+ * 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';
+/**
+ * Diagnostic severity levels.
+ *
+ * - `'error'` — analysis failed, declaration may be incomplete or missing data
+ * - `'warning'` — partial success, something seems off but analysis continued
+ */
+export declare const DiagnosticSeverity: z.ZodEnum<{
+    error: "error";
+    warning: "warning";
+}>;
+export type DiagnosticSeverity = z.infer<typeof DiagnosticSeverity>;
+/**
+ * Discriminant for `Diagnostic` variant types.
+ */
+export declare const DiagnosticKind: z.ZodEnum<{
+    type_extraction_failed: "type_extraction_failed";
+    signature_analysis_failed: "signature_analysis_failed";
+    class_member_failed: "class_member_failed";
+    svelte_prop_failed: "svelte_prop_failed";
+    module_skipped: "module_skipped";
+    module_unreadable: "module_unreadable";
+    import_parse_failed: "import_parse_failed";
+    duplicate_comment: "duplicate_comment";
+    misplaced_tag: "misplaced_tag";
+    unknown_param: "unknown_param";
+    source_map_failed: "source_map_failed";
+    duplicate_declaration: "duplicate_declaration";
+    transform_failed: "transform_failed";
+    resolver_failed: "resolver_failed";
+}>;
+export type DiagnosticKind = z.infer<typeof DiagnosticKind>;
+/**
+ * Type extraction failed (e.g., complex or recursive types).
+ */
+export declare const TypeExtractionDiagnostic: z.ZodObject<{
+    /** Name of the symbol whose type couldn't be extracted. */
+    symbolName: z.ZodString;
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"type_extraction_failed">;
+}, z.core.$strict>;
+export type TypeExtractionDiagnostic = z.infer<typeof TypeExtractionDiagnostic>;
+/**
+ * Function/method signature analysis failed.
+ */
+export declare const SignatureAnalysisDiagnostic: z.ZodObject<{
+    /** Name of the function or method. */
+    functionName: z.ZodString;
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"signature_analysis_failed">;
+}, z.core.$strict>;
+export type SignatureAnalysisDiagnostic = z.infer<typeof SignatureAnalysisDiagnostic>;
+/**
+ * Class member analysis failed.
+ */
+export declare const ClassMemberDiagnostic: z.ZodObject<{
+    /** Name of the class. */
+    className: z.ZodString;
+    /** Name of the member that failed. */
+    memberName: z.ZodString;
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"class_member_failed">;
+}, z.core.$strict>;
+export type ClassMemberDiagnostic = z.infer<typeof ClassMemberDiagnostic>;
+/**
+ * Svelte prop type resolution failed.
+ */
+export declare const SveltePropDiagnostic: z.ZodObject<{
+    /** Name of the component. */
+    componentName: z.ZodString;
+    /** Name of the prop. */
+    propName: z.ZodString;
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"svelte_prop_failed">;
+}, z.core.$strict>;
+export type SveltePropDiagnostic = z.infer<typeof SveltePropDiagnostic>;
+/**
+ * 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 declare const ModuleSkippedDiagnostic: z.ZodObject<{
+    /** Reason the module was skipped. */
+    reason: z.ZodEnum<{
+        not_in_program: "not_in_program";
+        no_analyzer: "no_analyzer";
+        requires_program: "requires_program";
+    }>;
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"module_skipped">;
+}, z.core.$strict>;
+export type ModuleSkippedDiagnostic = z.infer<typeof ModuleSkippedDiagnostic>;
+/**
+ * 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 declare const ModuleUnreadableDiagnostic: z.ZodObject<{
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"module_unreadable">;
+}, z.core.$strict>;
+export type ModuleUnreadableDiagnostic = z.infer<typeof ModuleUnreadableDiagnostic>;
+/**
+ * Import parsing failed during dependency resolution.
+ */
+export declare const ImportParseDiagnostic: z.ZodObject<{
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"import_parse_failed">;
+}, z.core.$strict>;
+export type ImportParseDiagnostic = z.infer<typeof ImportParseDiagnostic>;
+/**
+ * Duplicate comment sources detected (e.g., both HTML and JSDoc `@module`,
+ * or both HTML `@component` and JSDoc for component `docComment`).
+ */
+export declare const DuplicateCommentDiagnostic: z.ZodObject<{
+    /** Which comment type is duplicated. */
+    commentType: z.ZodEnum<{
+        module_comment: "module_comment";
+        doc_comment: "doc_comment";
+    }>;
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"duplicate_comment">;
+}, z.core.$strict>;
+export type DuplicateCommentDiagnostic = z.infer<typeof DuplicateCommentDiagnostic>;
+/**
+ * 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 declare const MisplacedTagDiagnostic: z.ZodObject<{
+    /** The tag name without the `@` prefix (e.g., `'example'`, `'deprecated'`). */
+    tagName: z.ZodEnum<{
+        default: "default";
+        throws: "throws";
+        since: "since";
+        mutates: "mutates";
+        deprecated: "deprecated";
+        example: "example";
+        see: "see";
+        nodocs: "nodocs";
+    }>;
+    /** Name of the function or method whose overload carries the misplaced tag. */
+    functionName: z.ZodString;
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"misplaced_tag">;
+}, z.core.$strict>;
+export type MisplacedTagDiagnostic = z.infer<typeof MisplacedTagDiagnostic>;
+/**
+ * `@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 declare const UnknownParamDiagnostic: z.ZodObject<{
+    /** The `@param` key that didn't match a real parameter. */
+    paramName: z.ZodString;
+    /** Name of the function or method. */
+    functionName: z.ZodString;
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"unknown_param">;
+}, z.core.$strict>;
+export type UnknownParamDiagnostic = z.infer<typeof UnknownParamDiagnostic>;
+/**
+ * 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 declare const DuplicateDeclarationDiagnostic: z.ZodObject<{
+    /** The duplicated declaration name. */
+    declarationName: z.ZodString;
+    /** Module paths where the name was defined (>= 2). */
+    modules: z.ZodArray<z.ZodString>;
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"duplicate_declaration">;
+}, z.core.$strict>;
+export type DuplicateDeclarationDiagnostic = z.infer<typeof DuplicateDeclarationDiagnostic>;
+/**
+ * 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 declare const SourceMapFailedDiagnostic: z.ZodObject<{
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"source_map_failed">;
+}, z.core.$strict>;
+export type SourceMapFailedDiagnostic = z.infer<typeof SourceMapFailedDiagnostic>;
+/**
+ * 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 declare const TransformFailedDiagnostic: z.ZodObject<{
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"transform_failed">;
+}, z.core.$strict>;
+export type TransformFailedDiagnostic = z.infer<typeof TransformFailedDiagnostic>;
+/**
+ * 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 declare const ResolverFailedDiagnostic: z.ZodObject<{
+    /** The import specifier the resolver failed on. */
+    specifier: z.ZodString;
+    /**
+     * 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.ZodString;
+    /** Line number (1-based), absent if location unavailable. */
+    line: z.ZodOptional<z.ZodNumber>;
+    /** Column number (1-based), absent if location unavailable. */
+    column: z.ZodOptional<z.ZodNumber>;
+    /** Human-readable description of the issue. */
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    kind: z.ZodLiteral<"resolver_failed">;
+}, z.core.$strict>;
+export type ResolverFailedDiagnostic = z.infer<typeof ResolverFailedDiagnostic>;
+/**
+ * Discriminated union of all diagnostic variants.
+ */
+export declare const Diagnostic: z.ZodDiscriminatedUnion<[
+    typeof TypeExtractionDiagnostic,
+    typeof SignatureAnalysisDiagnostic,
+    typeof ClassMemberDiagnostic,
+    typeof SveltePropDiagnostic,
+    typeof ModuleSkippedDiagnostic,
+    typeof ModuleUnreadableDiagnostic,
+    typeof ImportParseDiagnostic,
+    typeof DuplicateCommentDiagnostic,
+    typeof MisplacedTagDiagnostic,
+    typeof UnknownParamDiagnostic,
+    typeof SourceMapFailedDiagnostic,
+    typeof DuplicateDeclarationDiagnostic,
+    typeof TransformFailedDiagnostic,
+    typeof ResolverFailedDiagnostic
+], 'kind'>;
+export type Diagnostic = z.infer<typeof Diagnostic>;
+/**
+ * Check if any error-severity diagnostics were collected.
+ */
+export declare const hasErrors: (diagnostics: Array<Diagnostic>) => boolean;
+/**
+ * Check if any warning-severity diagnostics were collected.
+ */
+export declare const hasWarnings: (diagnostics: Array<Diagnostic>) => boolean;
+/**
+ * Get all error-severity diagnostics.
+ */
+export declare const errorsOf: (diagnostics: Array<Diagnostic>) => Array<Diagnostic>;
+/**
+ * Get all warning-severity diagnostics.
+ */
+export declare const warningsOf: (diagnostics: Array<Diagnostic>) => Array<Diagnostic>;
+/**
+ * Get diagnostics of a specific kind, narrowed to the matching variant.
+ */
+export declare const byKind: <K extends DiagnosticKind>(diagnostics: Array<Diagnostic>, kind: K) => Array<Extract<Diagnostic, {
+    kind: K;
+}>>;
+/**
+ * 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 declare const formatDiagnostic: (diagnostic: Diagnostic) => string;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

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