Add support for import attributes in ambient module declarations

[jonathantneal]

Summary

This PR adds complete support for import attributes in ambient module declarations, including syntax, semantic behavior, and diagnostics.

// Declare ambient module with import attributes
declare module '*.css' with { type: 'css' } {
  const stylesheet: CSSStyleSheet;
  export default stylesheet;
}

// Import with matching attributes - resolves correctly
import styles from 'styles.css' with { type: 'css' };
// styles: CSSStyleSheet ✅

// Import without attributes - doesn't match
import styles2 from 'styles2.css';
// styles2: any ❌
// Error TS18063: No ambient module declaration matches import of 'styles2.css' with the specified import attributes.

Implementation

Phase 1: Syntax Support

• Reuses existing ImportAttributes infrastructure from import statements
• Adds optional withClause field to ModuleDeclaration AST nodes
• Updates parser to recognize with { ... } syntax after module name
• Updates factory, emitter, and visitor functions to preserve the clause

Phase 2: Semantic Behavior

• Module Resolution: Imports with attributes now match ambient declarations with matching attributes
• Type Checking: Imports get correct types from matching ambient declarations
• Attribute Matching Logic:
  • Exact match required: same keys and values
  • If neither has attributes, they match
  • If only one has attributes, they don't match
  • Works for both exact module names and wildcard patterns (*.css)

Phase 3: Validation & Diagnostics

• New Error TS18063: "No ambient module declaration matches import of '{0}' with the specified import attributes."
• New Error TS18062: "Module '{0}' was resolved to '{1}', but import attributes do not match the ambient module declaration."
• Helpful error messages when imports don't match declarations due to attribute mismatches

Testing

• Syntax tests: Verify parsing and emission of import attributes in ambient modules
• Semantic tests: Verify imports match declarations based on attributes
• Diagnostic tests: Verify appropriate error messages for mismatches
• All tests passing: 99,248 out of 99,252 tests (4 pre-existing macOS symlink failures)
• Public API baseline updated

Use Cases

This enables TypeScript to properly type imports based on their attributes:

// CSS Modules
declare module '*.css' with { type: 'css' } {
  const stylesheet: CSSStyleSheet;
  export default stylesheet;
}

// JSON imports
declare module '*.json' with { type: 'json' } {
  const data: any;
  export default data;
}

// WebAssembly modules
declare module '*.wasm' with { type: 'module' } {
  const module: WebAssembly.Module;
  export default module;
}

Related

• Aligns with TC39 Import Attributes proposal
• Enables better typing for module formats that require import attributes
• Foundation for future enhancements to module resolution

[typescript-bot]

This PR doesn't have any linked issues. Please open an issue that references this PR. From there we can discuss and prioritise.

[typescript-bot]

This PR doesn't have any linked issues. Please open an issue that references this PR. From there we can discuss and prioritise.

[typescript-bot]

Looks like you're introducing a change to the public API surface area. If this includes breaking changes, please document them on our wiki's API Breaking Changes page.

Also, please make sure @DanielRosenwasser and @RyanCavanaugh are aware of the changes, just as a heads up.

[Copilot]

Pull request overview

This PR adds support for import attributes syntax in ambient module declarations, enabling developers to specify import attributes (e.g., with { type: 'css' }) when declaring ambient modules. This is a syntax-only change that lays the foundation for future semantic behavior.

Changes:

• Added optional withClause field to ModuleDeclaration AST nodes
• Updated parser to recognize and parse with { ... } syntax after ambient module names
• Updated factory, emitter, visitor, and transformer functions to handle the new field
• Added comprehensive test coverage with baselines

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/cases/conformance/ambient/ambientModuleWithImportAttributes.ts	New test file demonstrating various uses of import attributes in ambient module declarations
tests/baselines/reference/api/typescript.d.ts	Public API baseline updated with new withClause parameter in factory methods and parent type
tests/baselines/reference/ambientModuleWithImportAttributes.types	Type baseline showing type inference works correctly
tests/baselines/reference/ambientModuleWithImportAttributes.symbols	Symbol baseline showing symbol resolution works correctly
tests/baselines/reference/ambientModuleWithImportAttributes.js	JavaScript output baseline showing modules are properly emitted
tests/baselines/reference/ambientModuleWithImportAttributes.errors.txt	Error baseline showing expected module resolution errors
src/compiler/visitorPublic.ts	Updated visitor to visit withClause field when traversing ModuleDeclaration nodes
src/compiler/types.ts	Added withClause field to ModuleDeclaration interface and updated parent type for ImportAttributes
src/compiler/transformers/declarations.ts	Updated transformer to preserve withClause when creating and updating module declarations
src/compiler/parser.ts	Added parsing logic to recognize import attributes after ambient module names
src/compiler/factory/nodeFactory.ts	Updated factory methods to accept and handle withClause parameter
src/compiler/emitter.ts	Updated emitter to output withClause when emitting module declarations

Comments suppressed due to low confidence (1)

src/compiler/factory/nodeFactory.ts:4566

• The withClause field should have its transform flags propagated in the non-ambient module case for consistency with how other optional child nodes like body are handled. Add propagateChildFlags(node.withClause) to the transform flags calculation on line 4561-4564.

While ambient modules (which have the simplified transform flags on line 4558) won't be affected since they overwrite the flags, propagating the flags ensures correctness if the factory API is used to create non-ambient module declarations with a withClause (even though the parser doesn't do this).

        node.withClause = withClause;
        if (modifiersToFlags(node.modifiers) & ModifierFlags.Ambient) {
            node.transformFlags = TransformFlags.ContainsTypeScript;
        }
        else {
            node.transformFlags |= propagateChildrenFlags(node.modifiers) |
                propagateChildFlags(node.name) |
                propagateChildFlags(node.body) |
                TransformFlags.ContainsTypeScript;
        }
        node.transformFlags &= ~TransformFlags.ContainsPossibleTopLevelAwait; // Module declarations cannot contain `await`.

[jonathantneal]

@microsoft-github-policy-service agree