svelte-docinfo 0.5.4 → 0.6.0

package/dist/analyze-core.js

@@ -17,24 +17,35 @@
  * - `AnalyzeResultJson` / `OnDuplicates` / `OnDuplicatesCallback` — shared types
  *   surfaced through the main barrel directly from this module.
  * - `throwOnDuplicates` — convenience callback paired with `OnDuplicates`.
+ * - `finalizeDiagnostics` — the diagnostic boundary passes (virtual position
+ *   remap, then path normalization) in their required order; the one call for
+ *   callers assembling modules themselves.
  * - `normalizeDiagnosticPaths` — boundary helper for build-tool integrations
  *   that bypass the session and collect their own diagnostics.
+ * - `normalizeModulePathsInTypes` — output pass rewriting the absolute module
+ *   paths the checker embeds in printed type text. Runs inside `analyzeCore`;
+ *   exposed for the same reason as `normalizeDiagnosticPaths`, so a caller
+ *   assembling modules itself through `analyzeModule` can meet the same
+ *   output contract.
  *
  * @internal — module split is implementation detail; consumers go through
  * `analyze.ts` / `session.ts` for the stable surface.
  *
  * @module
  */
+import { relative } from 'node:path';
 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 { analyzeSvelteModule, remapVirtualDiagnosticPositions } from './svelte.js';
+import { scrubVirtualSuffixes, stripVirtualSuffix, getComponentName } from './source.js';
 import { extractPath, extractDependencies } from './source-config.js';
-import { toPosixPath } from './paths.js';
-import { sortModules, findDuplicates, mergeReExports, resolveComponentAliases, compareStrings, } from './postprocess.js';
+import { toPosixPath, isAbsolutePosixPath } from './paths.js';
+import { buildAliasRegistry } from './typescript-alias-registry.js';
+import { createExtractContext } from './typescript-extract-shared.js';
+import { sortModules, findDuplicates, mergeReExports, resolveComponentAliases, compareStrings } from './postprocess.js';
 /**
  * Convenience `OnDuplicatesCallback` that throws on any duplicate.
  *
@@ -63,18 +74,30 @@ const formatDuplicates = (duplicates) => {
         '(2) add /** @nodocs */ to exclude from documentation.\n' +
         details);
 };
-const emitDuplicateDiagnostics = (diagnostics, duplicates) => {
+/**
+ * Emit one `duplicate_declaration` per colliding name.
+ *
+ * The record carries both path bases on purpose: `file` names a file
+ * (project-root-relative, like every diagnostic) while `modules` and the
+ * message name modules (`ModuleJson.path`, relative to `sourceRoot`).
+ *
+ * @param sourceIdsByModulePath - `ModuleJson.path` → absolute source id, since
+ *   `DuplicateDeclaration` carries only the module path. Covers every module
+ *   `duplicates` can name by construction — `findDuplicates` reports paths of
+ *   the modules handed to it — so the lookup's fallback never fires.
+ */
+const emitDuplicateDiagnostics = (diagnostics, duplicates, sourceIdsByModulePath) => {
     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,
+            file: sourceIdsByModulePath.get(first.module) ?? first.module,
             line: first.declaration.sourceLine,
             message: `Duplicate declaration "${name}" defined in: ${modules.join(', ')}`,
             severity: 'warning',
             declarationName: name,
-            modules,
+            modules
         });
     }
 };
@@ -119,7 +142,7 @@ const dispatchOnDuplicates = (mode, duplicates, log) => {
  */
 export const AnalyzeResultJson = z.strictObject({
     modules: z.array(ModuleJson).default([]),
-    diagnostics: z.array(Diagnostic).default([]),
+    diagnostics: z.array(Diagnostic).default([])
 });
 const toModuleJson = (raw) => {
     const filtered = raw.declarations.filter((d) => !d.nodocs).map((d) => d.declaration);
@@ -151,7 +174,7 @@ const toModuleJson = (raw) => {
         reExports,
         externalReExports,
         externalStarExports: raw.externalStarExports,
-        ...(raw.moduleComment ? { moduleComment: raw.moduleComment } : {}),
+        ...(raw.moduleComment ? { moduleComment: raw.moduleComment } : {})
     });
 };
 // Module dispatch
@@ -175,19 +198,26 @@ const toModuleJson = (raw) => {
  * `alsoExportedFrom` on returned declarations is always empty from this path —
  * cross-module re-export resolution requires all modules (`mergeReExports`
  * consumes the returned module's `reExports` in phase 2).
+ *
+ * `aliasRegistry` is optional at this boundary: direct callers assembling
+ * modules themselves get written-name recovery only, while `analyzeCore`
+ * passes the registry its pre-pass built (see `buildAliasRegistry`).
  */
-export const analyzeModule = (sourceFile, program, options, diagnostics, log) => {
+export const analyzeModule = (sourceFile, program, options, diagnostics, log, aliasRegistry) => {
     const checker = program.getTypeChecker();
     const modulePath = extractPath(sourceFile.id, options);
+    // diagnostics carry the absolute id (see the `Diagnostic.file` schema doc);
+    // the returned `ModuleJson` keeps `modulePath`, a different base
+    const diagnosticFile = toPosixPath(sourceFile.id);
     const analyzerType = options.getAnalyzerType(sourceFile.id);
     let raw;
     if (analyzerType === 'svelte') {
         diagnostics.push({
             kind: 'module_skipped',
-            file: modulePath,
+            file: diagnosticFile,
             message: 'Svelte files require program integration. Use createAnalysisSession or analyze()/analyzeFromFiles() instead.',
             severity: 'warning',
-            reason: 'requires_program',
+            reason: 'requires_program'
         });
         log?.warn(`Svelte file skipped in analyzeModule: ${sourceFile.id}`);
         return undefined;
@@ -197,15 +227,22 @@ export const analyzeModule = (sourceFile, program, options, diagnostics, log) =>
         if (!tsSourceFile) {
             diagnostics.push({
                 kind: 'module_skipped',
-                file: modulePath,
-                message: `Could not get source file from program: ${sourceFile.id}`,
+                file: diagnosticFile,
+                // interpolating the same id as `file` keeps the two from naming the
+                // file differently — the message gets the same project-root scrub.
+                // The log line below keeps the raw id: logs are for developers,
+                // diagnostics ship.
+                message: `Could not get source file from program: ${diagnosticFile}`,
                 severity: 'warning',
-                reason: 'not_in_program',
+                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);
+        // the pass-scoped extraction context — constructed here because the
+        // dispatcher is where the program is in hand (see `analyzeExports`)
+        const ctx = createExtractContext(program, checker, options, diagnostics, aliasRegistry);
+        raw = analyzeTypescriptModule(sourceFile, tsSourceFile, modulePath, ctx, options);
     }
     else if (analyzerType === 'css' || analyzerType === 'json') {
         const { dependencies, dependents } = extractDependencies(sourceFile, options);
@@ -217,16 +254,16 @@ export const analyzeModule = (sourceFile, program, options, diagnostics, log) =>
             starExports: [],
             reExports: [],
             externalReExports: [],
-            externalStarExports: [],
+            externalStarExports: []
         };
     }
     else {
         diagnostics.push({
             kind: 'module_skipped',
-            file: modulePath,
-            message: `No analyzer for file type: ${sourceFile.id}`,
+            file: diagnosticFile,
+            message: `No analyzer for file type: ${diagnosticFile}`,
             severity: 'warning',
-            reason: 'no_analyzer',
+            reason: 'no_analyzer'
         });
         log?.warn(`No analyzer for file: ${sourceFile.id}`);
         return undefined;
@@ -250,11 +287,82 @@ export const analyzeModule = (sourceFile, program, options, diagnostics, log) =>
  * `extractDependencies`); `analyzeCore` does not compute them. `session.query`
  * runs `computeDependents` on the owned set before invoking this.
  */
+/**
+ * Analyze the gated Svelte canonicals referenced by an emitted component
+ * alias, as `resolveComponentAliases` fill context only (see
+ * `AnalyzeCoreInputs.contextSvelteFiles`). Unreferenced files are skipped
+ * entirely; analysis diagnostics are dropped — the canonical's `partial`
+ * flag propagates through the fill, which is the emitted signal.
+ */
+const analyzeContextComponents = (contextSvelteFiles, emittedModules, inputs, aliasRegistry) => {
+    const { sourceOptions, program, svelteVirtualFiles } = inputs;
+    const referenced = new Set();
+    for (const mod of emittedModules) {
+        for (const decl of mod.declarations) {
+            if (decl.kind === 'component' && decl.aliasOf)
+                referenced.add(decl.aliasOf.module);
+        }
+    }
+    const contextModules = [];
+    if (referenced.size === 0)
+        return contextModules;
+    for (const sourceFile of contextSvelteFiles) {
+        const modulePath = extractPath(sourceFile.id, sourceOptions);
+        if (!referenced.has(modulePath))
+            continue;
+        const virtualFile = svelteVirtualFiles.get(sourceFile.id);
+        if (!virtualFile)
+            continue;
+        const droppedDiagnostics = [];
+        const raw = analyzeSvelteModule(sourceFile, modulePath, program.getTypeChecker(), sourceOptions, droppedDiagnostics, program, virtualFile, aliasRegistry);
+        if (raw)
+            contextModules.push(toModuleJson(raw));
+    }
+    return contextModules;
+};
 export const analyzeCore = (inputs) => {
-    const { sourceFiles, sourceOptions, program, svelteVirtualFiles, transformFailedIds, onDuplicates, log, } = inputs;
+    const { sourceFiles, sourceOptions, program, svelteVirtualFiles, transformFailedIds, contextSvelteFiles, onDuplicates, log } = inputs;
     const checker = program.getTypeChecker();
     const diagnostics = [];
+    // Registry pre-pass: register the emitted set's exported lost aliases
+    // before any extraction, so every `resolveTypeInfo` call this cycle can
+    // consult a complete registry. Svelte modules are reached through their
+    // svelte2tsx virtuals (`program.getSourceFile(<.svelte id>)` is undefined);
+    // CSS/JSON have no exports and analyzer-less files no program file. Gated
+    // context files are deliberately absent — their aliases must not register
+    // (emitted references always have a doc page to link).
+    const registrySources = [];
+    for (const sourceFile of sourceFiles) {
+        if (transformFailedIds?.has(sourceFile.id))
+            continue;
+        const virtualFile = svelteVirtualFiles.get(sourceFile.id);
+        const programFile = virtualFile
+            ? program.getSourceFile(virtualFile.virtualPath)
+            : sourceOptions.getAnalyzerType(sourceFile.id) === 'typescript'
+                ? program.getSourceFile(sourceFile.id)
+                : undefined;
+        if (!programFile)
+            continue;
+        registrySources.push({
+            sourceFile: programFile,
+            modulePath: extractPath(sourceFile.id, sourceOptions)
+        });
+    }
+    const aliasRegistry = buildAliasRegistry(registrySources, checker);
     const modules = [];
+    // `ModuleJson.path` → the absolute id it was extracted from, so a
+    // module-path-keyed pass can still report a project-root-relative
+    // `Diagnostic.file` (`emitDuplicateDiagnostics` is the consumer). The two
+    // bases differ, and the reverse direction isn't reconstructible:
+    // `extractPath`'s no-prefix fallback returns the absolute path, so
+    // prepending `sourceRoot` to a module path can concatenate into nonsense.
+    // Recording the id the loop already holds keeps them exact.
+    const sourceIdsByModulePath = new Map();
+    // the one way to add a module, so a new branch can't record only half of it
+    const pushModule = (mod, sourceId) => {
+        sourceIdsByModulePath.set(mod.path, toPosixPath(sourceId));
+        modules.push(mod);
+    };
     // Phase 1: analyze every module (forward re-export edges land on `ModuleJson.reExports`)
     for (const sourceFile of sourceFiles) {
         // Failed-transform Svelte file: synthesize placeholder ModuleJson so
@@ -265,14 +373,14 @@ export const analyzeCore = (inputs) => {
             const modulePath = extractPath(sourceFile.id, sourceOptions);
             const componentName = getComponentName(modulePath);
             const { dependencies, dependents } = extractDependencies(sourceFile, sourceOptions);
-            modules.push(ModuleJson.parse({
+            pushModule(ModuleJson.parse({
                 path: modulePath,
                 declarations: [],
                 dependencies,
                 dependents,
                 starExports: [],
-                partial: true,
-            }));
+                partial: true
+            }), sourceFile.id);
             log?.warn(`Svelte component ${componentName} marked partial (transform failed at ingest)`);
             continue;
         }
@@ -280,7 +388,7 @@ export const analyzeCore = (inputs) => {
         const virtualFile = svelteVirtualFiles.get(sourceFile.id);
         if (virtualFile) {
             const modulePath = extractPath(sourceFile.id, sourceOptions);
-            const raw = analyzeSvelteModule(sourceFile, modulePath, checker, sourceOptions, diagnostics, program, virtualFile);
+            const raw = analyzeSvelteModule(sourceFile, modulePath, checker, sourceOptions, diagnostics, program, virtualFile, aliasRegistry);
             if (raw) {
                 mod = toModuleJson(raw);
             }
@@ -289,50 +397,100 @@ export const analyzeCore = (inputs) => {
             }
         }
         else {
-            mod = analyzeModule(sourceFile, program, sourceOptions, diagnostics, log);
+            mod = analyzeModule(sourceFile, program, sourceOptions, diagnostics, log, aliasRegistry);
         }
         if (!mod)
             continue;
-        modules.push(mod);
+        pushModule(mod, sourceFile.id);
     }
+    // Phase 1.5: gated Svelte canonicals as fill context — kept out of
+    // `mergeReExports` (their edges would back-link modules absent from
+    // output) and out of the emitted set.
+    const contextModules = contextSvelteFiles?.length
+        ? analyzeContextComponents(contextSvelteFiles, modules, inputs, aliasRegistry)
+        : [];
     // Phase 2a: build alsoExportedFrom arrays from the modules' forward edges
-    mergeReExports(modules);
+    const mergedModules = mergeReExports(modules);
     // 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);
+    // Gated canonicals extend the lookup without joining the output.
+    const resolvedModules = resolveComponentAliases(mergedModules, contextModules);
+    const sortedModules = sortModules(resolvedModules);
     // 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);
+    emitDuplicateDiagnostics(diagnostics, duplicates, sourceIdsByModulePath);
     if (onDuplicates) {
         dispatchOnDuplicates(onDuplicates, duplicates, log);
     }
-    normalizeDiagnosticPaths(diagnostics, sourceOptions.projectRoot);
+    normalizeModulePathsInTypes(sortedModules, sourceOptions, program);
+    finalizeDiagnostics(diagnostics, {
+        projectRoot: sourceOptions.projectRoot,
+        virtualFiles: svelteVirtualFiles.values()
+    });
     return {
         modules: sortedModules,
-        diagnostics,
+        diagnostics
     };
 };
 /**
- * Normalize `Diagnostic.file` to project-root-relative form, in place.
+ * 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.
+ *
+ * @mutates diagnostics — rewrites positions, `file`, and `message`
+ */
+export const finalizeDiagnostics = (diagnostics, options) => {
+    if (options.virtualFiles) {
+        remapVirtualDiagnosticPositions(diagnostics, options.virtualFiles);
+    }
+    normalizeDiagnosticPaths(diagnostics, options.projectRoot);
+};
+/**
+ * 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.
+ * 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.
+ * 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.
  *
- * @mutates diagnostics — rewrites each diagnostic's `file` field
+ * @mutates diagnostics — rewrites each diagnostic's `file` and `message`
+ * @see `finalizeDiagnostics` — when Svelte virtuals are in play, the position
+ * remap must run before this pass (it strips the suffix the remap matches on)
  */
 export const normalizeDiagnosticPaths = (diagnostics, projectRoot) => {
-    const prefix = projectRoot.endsWith('/') ? projectRoot : projectRoot + '/';
+    const root = projectRoot.endsWith('/') ? projectRoot.slice(0, -1) : projectRoot;
+    const prefix = root + '/';
     for (const d of diagnostics) {
+        if (d.message.includes(prefix)) {
+            d.message = d.message.split(prefix).join('');
+        }
+        d.message = scrubVirtualSuffixes(d.message);
         // 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.
@@ -340,11 +498,273 @@ export const normalizeDiagnosticPaths = (diagnostics, projectRoot) => {
         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);
+        else if (isAbsolutePosixPath(file)) {
+            // Outside the root. Relativize rather than dropping the leading slash,
+            // which produced a string that reads as root-relative but resolves
+            // somewhere else entirely. A path already relative is left alone —
+            // `relative` would resolve it against `cwd`.
+            file = toPosixPath(relative(root, file));
         }
         d.file = file;
     }
 };
+/**
+ * Extensions TypeScript elides when it prints a module specifier inside a type
+ * (`typeof import("…/dep")` for `…/dep.ts`), in module-resolution preference
+ * order.
+ *
+ * Order encodes preference, not match order: `elidedExtensionOf` takes the
+ * *longest* match, so `.d.ts` beats `.ts` on `b.d.ts` regardless of position.
+ * That frees the order to break the tie when two program files elide to the
+ * same path — which is the only thing standing between this pass and a
+ * dependence on `program.getSourceFiles()` iteration order, in a pass whose
+ * whole purpose is output that doesn't vary between machines.
+ */
+const ELIDED_MODULE_EXTENSIONS = [
+    '.ts',
+    '.tsx',
+    '.mts',
+    '.cts',
+    '.d.ts',
+    '.d.mts',
+    '.d.cts',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs'
+];
+/** The longest elided extension `path` ends with, or `undefined`. */
+const elidedExtensionOf = (path) => {
+    let longest;
+    for (const ext of ELIDED_MODULE_EXTENSIONS) {
+        if (path.endsWith(ext) && (longest === undefined || ext.length > longest.length)) {
+            longest = ext;
+        }
+    }
+    return longest;
+};
+const stripElidedExtension = (path) => {
+    const ext = elidedExtensionOf(path);
+    return ext === undefined ? path : path.slice(0, -ext.length);
+};
+/** Lower wins. Ranks two files that elide to the same path by resolution preference. */
+const elidedExtensionRank = (path) => {
+    const ext = elidedExtensionOf(path);
+    return ext === undefined
+        ? ELIDED_MODULE_EXTENSIONS.length
+        : ELIDED_MODULE_EXTENSIONS.indexOf(ext);
+};
+/**
+ * Matches a double-quoted absolute path inside printed type text — the
+ * checker's `import("…")` form. Deliberately not anchored to the `import(`
+ * wrapper: the pass fails open, and the resolution check downstream is the
+ * real guard.
+ *
+ * The absolute-path alternation mirrors `isAbsolutePosixPath` — same rule, but
+ * this one has to match *inside* a larger string rather than test a whole one.
+ */
+const QUOTED_ABSOLUTE_PATH_RE = /"((?:\/|[A-Za-z]:\/)[^"\n]*)"/g;
+/**
+ * Keys holding author-written text or already-relative paths, never printed
+ * type text. Skipped by the walk so a doc comment, a raw `defaultValue`, or a
+ * written heritage field can't be rewritten — `extends` and `implements` are
+ * `getText()` of the written node, and `externalTypes` is written text with
+ * identifier-scoped splices (rename resolution, type-parameter substitution),
+ * never a checker print.
+ *
+ * A denylist rather than an allowlist of type-bearing keys, deliberately: the
+ * failure this pass exists to prevent is a *missed* type field, so it should
+ * fail open. A new author-text field added later gets walked, but the rewrite
+ * still only fires on a quoted absolute path resolving to a loaded file — the
+ * resolution check, not this list, is the real guard.
+ */
+const NON_TYPE_TEXT_KEYS = new Set([
+    'dependencies',
+    'dependents',
+    'deprecatedMessage',
+    'description',
+    'defaultValue',
+    'docComment',
+    'examples',
+    'extends',
+    'externalStarExports',
+    'externalTypes',
+    'implements',
+    'internalMessage',
+    'module',
+    'moduleComment',
+    'mutates',
+    'path',
+    'propertyDescriptions',
+    'returnDescription',
+    'seeAlso',
+    'since',
+    'specifier',
+    'starExports',
+    'throws'
+]);
+/**
+ * Build the printed-path → public-path mapper for one analysis run.
+ *
+ * Tiers, in order: a module in this output emits its `ModuleJson.path`; a
+ * package emits the tail after the last `node_modules/`; everything else is
+ * relative to `projectRoot`, which covers both an in-project file that emits
+ * no module and an out-of-project one (`../sibling/src/x.ts`).
+ *
+ * The relative form is not *guaranteed* stable across machines — a target with
+ * no near common ancestor gets a `../` run whose length tracks how deep
+ * `projectRoot` happens to sit. It's still strictly better than the absolute
+ * path it replaces: stable whenever the layout is (the sibling-repo and
+ * monorepo cases this actually arises from), and it never carries a home
+ * directory.
+ */
+const createModulePathNormalizer = (modules, options, program) => {
+    const modulePaths = new Set(modules.map((m) => m.path));
+    const programFiles = new Set();
+    // Recovers the extension the checker elided. Two program files can elide to
+    // the same path (`a.ts` beside `a.d.ts`), and picking the wrong one costs
+    // more than it looks: `byModule` is keyed on the resolved path, so a wrong
+    // pick *misses* tier 1 and silently degrades to a root-relative path. Ranked
+    // by resolution preference rather than first-wins, so the choice doesn't
+    // ride on `getSourceFiles()` order.
+    const byElidedExtension = new Map();
+    // Resolved absolute → `ModuleJson.path`, built from the program files that
+    // actually became modules. Keyed on the *resolved* path — the same form the
+    // lookup computes — so no extension guess enters tier 1. Keying on the
+    // elided form instead would collide `Foo.svelte` with a sibling
+    // `Foo.svelte.ts` (the Svelte 5 rune-module idiom), and let a non-module
+    // `.d.ts` sibling claim a module's key.
+    const byModule = new Map();
+    for (const sourceFile of program.getSourceFiles()) {
+        const fileName = toPosixPath(sourceFile.fileName);
+        programFiles.add(fileName);
+        const elided = stripElidedExtension(fileName);
+        const incumbent = byElidedExtension.get(elided);
+        if (incumbent === undefined || elidedExtensionRank(fileName) < elidedExtensionRank(incumbent)) {
+            byElidedExtension.set(elided, fileName);
+        }
+        const real = toPosixPath(stripVirtualSuffix(fileName));
+        const modulePath = extractPath(real, options);
+        if (modulePaths.has(modulePath))
+            byModule.set(real, modulePath);
+    }
+    const cache = new Map();
+    return (printed) => {
+        const cached = cache.get(printed);
+        if (cached !== undefined)
+            return cached;
+        const posix = toPosixPath(printed);
+        // Only rewrite a path naming a file this program actually loaded. A
+        // string-literal type that happens to look like one (`type P = "/usr/bin"`)
+        // resolves to nothing and is left alone.
+        const resolved = programFiles.has(posix) ? posix : byElidedExtension.get(posix);
+        if (resolved === undefined) {
+            cache.set(printed, printed);
+            return printed;
+        }
+        // Strip after resolving: the checker elides the virtual's `.ts`, so the
+        // printed form (`Foo.svelte.__svelte2tsx__`) doesn't carry the full suffix.
+        const real = toPosixPath(stripVirtualSuffix(resolved));
+        const modulePath = byModule.get(real);
+        // Last, not first: pnpm nests the real package under its store entry
+        // (`node_modules/.pnpm/pkg@1/node_modules/pkg/…`), and a hoisted monorepo
+        // dep can sit above `projectRoot` — both want the innermost segment. This
+        // tier running before the `projectRoot` one is what covers out-of-root
+        // dependencies, leaving only out-of-root *source* to fall through.
+        const packageIndex = real.lastIndexOf('/node_modules/');
+        let normalized;
+        if (modulePath !== undefined) {
+            normalized = modulePath;
+        }
+        else if (packageIndex !== -1) {
+            normalized = real.slice(packageIndex + '/node_modules/'.length);
+        }
+        else {
+            // One `relative` covers both remaining tiers: in-project files come
+            // back root-relative, out-of-project ones as `../…`. The `../` prefix
+            // is a usable marker — a `ModuleJson.path` can never start with it
+            // (out-of-root source paths throw in `normalizeSourceOptions`) and
+            // neither can a package specifier, so it reads unambiguously as
+            // "outside this project."
+            normalized = toPosixPath(relative(options.projectRoot, real));
+        }
+        cache.set(printed, normalized);
+        return normalized;
+    };
+};
+/**
+ * Idempotent: a rewritten string no longer matches, because every tier but the
+ * out-of-project one emits a relative path and the pattern requires a leading
+ * `/` (or drive letter). Load-bearing — phase 2 shares structure between
+ * modules (`mergeReExports`, `resolveComponentAliases` copy only what changes),
+ * so one array can be reached through more than one declaration.
+ */
+const replaceQuotedPaths = (text, rewrite) => {
+    if (!text.includes('"'))
+        return text;
+    return text.replace(QUOTED_ABSOLUTE_PATH_RE, (match, path) => {
+        const normalized = rewrite(path);
+        return normalized === path ? match : `"${normalized}"`;
+    });
+};
+const rewriteTypeText = (value, rewrite) => {
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const entry = value[i];
+            if (typeof entry === 'string') {
+                value[i] = replaceQuotedPaths(entry, rewrite);
+            }
+            else {
+                rewriteTypeText(entry, rewrite);
+            }
+        }
+        return;
+    }
+    if (value === null || typeof value !== 'object')
+        return;
+    const record = value;
+    // A `TypeJson` literal node's `text`/`value` are the author's literal type,
+    // not a printed module reference.
+    if (record.kind === 'literal')
+        return;
+    for (const key of Object.keys(record)) {
+        if (NON_TYPE_TEXT_KEYS.has(key))
+            continue;
+        const entry = record[key];
+        if (typeof entry === 'string') {
+            record[key] = replaceQuotedPaths(entry, rewrite);
+        }
+        else {
+            rewriteTypeText(entry, rewrite);
+        }
+    }
+};
+/**
+ * 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.
+ *
+ * @mutates modules — rewrites printed type text on declarations and members
+ */
+export const normalizeModulePathsInTypes = (modules, options, program) => {
+    const rewrite = createModulePathNormalizer(modules, options, program);
+    for (const mod of modules) {
+        rewriteTypeText(mod, rewrite);
+    }
+};