analysis_context.ts

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

Analysis functions follow a two-tier error model:

Accumulated (non-fatal) - Collected in AnalysisContext, analysis continues: - Type resolution failures (complex generics, circular refs) - Missing or unparseable JSDoc - Individual member/prop extraction failures - The return value is still valid but may have partial data

Thrown (fatal) - Analysis cannot continue for this file: - File not found or unreadable - Syntax errors preventing parsing - svelte2tsx transformation failures - Svelte version incompatibility

Usage Pattern

const ctx = new AnalysisContext();
const results = files.map(f => {
  try {
    return library_analyze_module(f, program, options, ctx);
  } catch (e) {
    // Fatal error - log and skip this file
    console.error(`Failed to analyze ${f.id}: ${e}`);
    return null;
  }
});

// Results are valid even with accumulated errors
// Check ctx for diagnostics to display to user
if (ctx.has_errors()) {
  for (const err of ctx.errors()) {
    console.error(format_diagnostic(err));
  }
}

@example const ctx = new AnalysisContext(); // ... analysis functions add diagnostics via ctx.add(...) if (ctx.has_errors()) { for (const err of ctx.errors()) { console.error(${err.file}:${err.line}: ${err.message}); } }

Declarations
#

12 declarations

view source

AnalysisContext
#

analysis_context.ts view source

Context for collecting diagnostics during source analysis.

Thread an instance through analysis functions to collect errors and warnings without halting analysis. After analysis completes, check has_errors() and report collected diagnostics.

examples

Example 1

`diagnostics`

type Array<Diagnostic>

readonly

`add`

Add a diagnostic to the collection.

type (diagnostic: Diagnostic): void

`diagnostic`

type Diagnostic

returns void

`has_errors`

Check if any errors were collected.

type (): boolean

returns boolean

`has_warnings`

Check if any warnings were collected.

type (): boolean

returns boolean

`errors`

Get all error diagnostics.

type (): Diagnostic[]

returns Diagnostic[]

`warnings`

Get all warning diagnostics.

type (): Diagnostic[]

returns Diagnostic[]

`by_kind`

Get diagnostics of a specific kind.

type <K extends DiagnosticKind>(kind: K): (Extract<TypeExtractionDiagnostic, { kind: K; }> | Extract<SignatureAnalysisDiagnostic, { ...; }> | Extract<...> | Extract<...> | Extract<...>)[]

`kind`

type K

returns

(Extract<TypeExtractionDiagnostic, { kind: K; }> | Extract<SignatureAnalysisDiagnostic, { kind: K; }> | Extract<...> | Extract<...> | Extract<...>)[]

BaseDiagnostic
#

analysis_context.ts view source

BaseDiagnostic

Base diagnostic fields shared by all diagnostic types.

`kind`

type DiagnosticKind

`file`

File path relative to project root (display with './' prefix).

type string

`line`

Line number (1-based), or null if location unavailable.

type number | null

`column`

Column number (1-based), or null if location unavailable.

type number | null

`message`

Human-readable description of the issue.

type string

`severity`

type DiagnosticSeverity

ClassMemberDiagnostic
#

analysis_context.ts view source

ClassMemberDiagnostic

Class member analysis failed.

inheritance

extends:

BaseDiagnostic

`kind`

type 'class_member_failed'

`class_name`

Name of the class.

type string

`member_name`

Name of the member that failed.

type string

Diagnostic
#

analysis_context.ts view source

Diagnostic

Union of all diagnostic types.

DiagnosticKind
#

analysis_context.ts view source

DiagnosticKind

Discriminant for diagnostic types.

DiagnosticSeverity
#

analysis_context.ts view source

DiagnosticSeverity

Diagnostic severity levels.

- error: Analysis failed, declaration may be incomplete or missing data - warning: Partial success, something seems off but analysis continued

format_diagnostic
#

analysis_context.ts view source

(diagnostic: Diagnostic, options?: FormatDiagnosticOptions | undefined): string

Format a diagnostic for display.

`diagnostic`

The diagnostic to format

type Diagnostic

`options?`

Formatting options

type FormatDiagnosticOptions | undefined

optional

returns

string

Formatted string like './file.ts:10:5: error: message'

FormatDiagnosticOptions
#

analysis_context.ts view source

FormatDiagnosticOptions

Options for formatting diagnostics.

`prefix`

Prefix for file path (default: './').

type string

`strip_base`

Base path to strip from absolute file paths (e.g., process.cwd()).

type string

ModuleSkippedDiagnostic
#

analysis_context.ts view source

ModuleSkippedDiagnostic

Module was skipped during analysis. Could be due to missing source file in program or no analyzer available.

inheritance

extends:

BaseDiagnostic

`kind`

type 'module_skipped'

`reason`

Reason the module was skipped.

type 'not_in_program' | 'no_analyzer'

SignatureAnalysisDiagnostic
#

analysis_context.ts view source

SignatureAnalysisDiagnostic

Function/method signature analysis failed.

inheritance

extends:

BaseDiagnostic

`kind`

type 'signature_analysis_failed'

`function_name`

Name of the function or method.

type string

SveltePropDiagnostic
#

analysis_context.ts view source

SveltePropDiagnostic

Svelte prop type resolution failed.

inheritance

extends:

BaseDiagnostic

`kind`

type 'svelte_prop_failed'

`component_name`

Name of the component.

type string

`prop_name`

Name of the prop.

type string

TypeExtractionDiagnostic
#

analysis_context.ts view source

TypeExtractionDiagnostic

Type extraction failed (e.g., complex or recursive types).

inheritance

extends:

BaseDiagnostic

`kind`

type 'type_extraction_failed'

`symbol_name`

Name of the symbol whose type couldn't be extracted.

type string

Imported by
#

library_generate.ts