[Andrew Branch (andrewbranch)]

Fixes #64362

Limitations

Normally content mappers that specify outputExtensions participate fully in rewriteRelativeImportExtensions. As an example, the Ember content mapper registers "outputExtensions": { ".gts": ".js" } because an external build tool compiles .gts files to .js outputs. This controls two behaviors by TypeScript: (1) the declaration file output for a Component.gts file will be Component.d.ts, to correspond with the Component.js file produced by the external tool; and (2) the build will require --rewriteRelativeImportExtensions to be enabled so an import of

import Component from "./Component.gts";

can be rewritten as import Component from "./Component.js" in TypeScript's output. Dynamic imports like

await import(path + "/Component.gts");

also get routed through a helper that replaces the trailing .gts with .js.

This logic gets more complicated when a content mapper that uses outputExtensions also uses an include filter, because it's harder to tell, in a single-file emit context, whether the file resolved by a given import is governed by a content mapper registration that contributes a module specifier rewrite.

Restrictions on imports affected by rootDirs and moduleSuffixes

These two options can cause false negative or false positives on whether a module specifier should be rewritten that can only be resolved by probing module resolution, which breaks the rule that module specifiers must be safely rewritable by looking only at configuration and the single file being processed. An single example exercising the ambiguity created by each:

{
  "compilerOptions": {
    "rootDirs": ["src", "types"],
    "moduleSuffixes": [".ios", ".android", ""],
  },
  "contentMappers": [{
    "package": "example-mapper",
    "extensions": [".foo"],
    "include": ["src", "**/*.android.foo"],
    "outputExtensions": { ".foo": ".js" },
  }]
}

// src/main.ts
import Component from "./Component.foo";

To decide whether "./Component.foo" should be rewritten to "./Component.js", you have to know what file it actually resolved to:

• If it's found in src, it should be rewritten
• but if it's found in types, it shouldn't,
• UNLESS types/Component.ios.foo does not exist AND types/Component.android.foo does exist

Since this is undecidable in a single-file context, we use the following process to decide whether to issue a diagnostic:

1. Assume a naive path-based resolution of "./Component.foo" from src to be src/Component.foo
2. Test that naive resolution against the content mapper's include—it passes, so assume that rewriting should happen
3. Check what the actual resolved file from the program was and test that against the content mapper's include
4. If the answer from (3) disagrees with the answer from (2), issue an error.

This process means you can use moduleSuffixes and rootDirs in combination with an extension-rewriting content mapper, just not in a way where the presence or absence of other files on disk can change the answer of whether a given import resolves to a content-mapped file or not.

Restrictions on dynamic imports

Non-literal import calls and require calls get a runtime helper with rewriteRelativeImportExtensions such that await import(dir + "./Component.foo") can have its .foo suffix rewritten to .js at runtime. If a content mapper uses both outputExtensions and an include, the include glob would have to be evaluated at runtime inside that helper to determine whether the rewriting should happen. That would be more complex and expensive than what it's worth, so using a dynamic import under these circumstances requires setting --disableDynamicImportRewriting (#65289) to make it explicit that you are opting out of getting the runtime rewriting helper.

[Copilot]

🟡 Changes recommended

Declaration emit and resolution use different suffixes for overlapping filtered extensions, preventing declaration-only consumers from resolving imports even when the emitted declaration exists.

1 open issue

• Declaration fallback mismatches overlapping filtered extensions · New

4 resolved since last review

• Suffix resolution misses files matching overlapping mapper extensions
• Checker rejects compatible tslib helpers for filtered mappings
• Declaration fallback breaks for compound extensions with moduleSuffixes
• Include filters are missing from the transform fingerprint

2 files not reviewed

• tsc/internal/diagnostics/diagnostics_generated.go: Generated file
• tsc/internal/lsp/lsproto/lsp_generated.go: Generated file

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Human assessment is needed because mapper inclusion and extension-fallback interactions can break module resolution, while relative-pattern registrations introduce a separate client compatibility risk.

No open issues 🎉

1 resolved since last review

• Declaration fallback mismatches overlapping filtered extensions

2 files not reviewed

• tsc/internal/diagnostics/diagnostics_generated.go: Generated file
• tsc/internal/lsp/lsproto/lsp_generated.go: Generated file

_{Review effort: Balanced}