analyze-core.ts

Inputs to analyzeCore. The caller (one-shot wrapper or session.query) is responsible for normalizing sourceOptions, obtaining the program, and pre-transforming Svelte files into svelteVirtualFiles.

transformFailedIds carries the IDs of .svelte files whose svelte2tsx transform threw at ingest. The dispatch synthesizes a placeholder ModuleJson (partial: true, empty declarations) for each so consumers see the file's existence in modules even though analysis couldn't run. Identifying these via a sibling Set keeps svelteVirtualFiles a clean "files we can analyze" map; the failure side-channel doesn't pollute it.

Analyze a single non-Svelte source file and extract module metadata.

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.

See AnalyzeResultJsonWire for the serialized input-side shape published on virtual:svelte-docinfo.

Serialized wire shape of an analysis result, as published by the Vite plugin on virtual:svelte-docinfo — the input-side counterpart to AnalyzeResultJson (the validated output of .parse()).

The two fields are deliberately asymmetric:

• modules is ModuleJsonInput (the z.input of ModuleJson) because the plugin runs it through compactReplacer, which strips .default([]) arrays and .default(false) booleans. Default-bearing fields therefore arrive undefined.
• diagnostics is the output Diagnostic — the plugin serializes it without the replacer, and Diagnostic has no defaults to strip, so the array is always present and the shape matches runtime exactly.

Consumers restore defaults by parsing through AnalyzeResultJson.

Note this describes the Vite virtual module specifically. The CLI runs the whole envelope through compactReplacer, so its JSON may additionally omit an empty diagnostics array — CLI consumers should parse through AnalyzeResultJson rather than assume this shape.

Run the diagnostic boundary passes in their required order: virtual position remap first (remapVirtualDiagnosticPositions), then path normalization (normalizeDiagnosticPaths — it strips the virtual suffix the remap matches file against, so the reverse order silently keeps virtual positions). The one call for callers assembling modules themselves through analyzeModule / analyzeSvelteModule; using it makes the ordering unrepresentable instead of a contract to remember. Omit virtualFiles when no Svelte virtuals are in play.

Normalize the paths a Diagnostic carries 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. A file outside the root gets the ../ form, matching module paths in printed type text — and making the documented "rejoin with projectRoot to get an absolute path" actually hold for it, which dropping the leading slash did not.

message gets the same treatment as file, by textual substitution. A message is free-form, and not every path in one comes from a field this pass can see — import_parse_failed wraps an es-module-lexer error that embeds the file name itself. Scrubbing here means the contract holds for the whole record rather than one field, so a producer can't reintroduce an absolute path through prose.

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. Hand it absolute paths. An already-relative file is left alone (relativizing it would resolve against cwd), so this pass can only correct the absolute form — a relative path on a base other than the project root passes through and ships as-is.

Normalize the absolute module paths TypeScript embeds in printed type text, in place.

The checker prints a module object as typeof import("<absolute path>"), which reaches output through every checker-printed field — typeSignature on declarations and members, returnType, and the text/name of a TypeJson node. Left alone it makes output machine-dependent (two checkouts of the same source produce different bytes), publishes local filesystem paths on any site that renders typeSignature, and exposes the svelte2tsx virtual suffix that stripVirtualSuffix exists to hide.

A path that resolves to a module in this output is rewritten to that module's ModuleJson.path, so the string doubles as a lookup key: a consumer linkifies with modules.find((m) => m.path === s) and reads a miss as "not a module here." See createModulePathNormalizer for the remaining tiers.

Runs as a whole-output pass rather than at the ~20 typeToString / signatureToString call sites, so a new printing site can't miss it.

Behavior selector for duplicate declaration names across modules.

• 'throw' — throw an Error listing every duplicate (strict flat-namespace enforcement)
• 'warn' — log to log.error and continue
• OnDuplicatesCallback — custom handler

Omitted entirely: no dispatch runs, but a duplicate_declaration diagnostic is still emitted into the diagnostics array for every collision (the diagnostic is the data; this option is the action).

'throw' trade-off: the throw fires after diagnostics are emitted but before the result is returned, so 'throw' callers never reach the diagnostics array. Callers that want fail-fast *and* diagnostic access should omit onDuplicates and inspect themselves:

Or use an OnDuplicatesCallback and stash the data before throwing.

Custom callback for handling duplicate declaration names.

Use the 'throw' or 'warn' shortcuts on onDuplicates for the common cases. Pass a function to fully control reporting.

Convenience OnDuplicatesCallback that throws on any duplicate.