[5.3] Deprecated types (AssertEntry, AssertClause) redefined as type aliases, rather than interfaces

[bradzacher]

🔎 Search Terms

AssertEntry, AssertClause, deprecated

🕗 Version & Regression Information

• This changed between versions 5.2 and 5.3

Background

TypeScript/src/compiler/types.ts

Lines 3665 to 3669 in 0abfb52

	/** @deprecated */
	export type AssertEntry = ImportAttribute;
	/** @deprecated */
	export type AssertClause = ImportAttributes;

In TS 5.3 import assertions were replaced with import attributes.
The old AST nodes were retained in the in the codebase with @deprecated markers.
However they were converted from interfaces to type aliases.

This has caused issues with @typescript-eslint because our tooling supports back to TypeScript 4.4 (before the import assertions were added).
Our types have a deep relationship with the TS AST types - so in order for us to support eslint plugin consumers on older TS versions we need to be able to reference both new and old AST nodes.

In order to do this we resort to a bit of a hack where we leverage interface declaration merging.
In a nutshell we declare an empty interface within the typescript module. On older versions of TS without the required AST node this defines the name so that our types compile fine for the user. On newer versions of TS with the required AST node - the declaration is a no-op.

This strategy has worked well for us for quite a few years! However with the release of 5.3 we now have a unique situation where an AST node was added AND removed within our supported version ranges. This would be fine for us and our trick would work - if it weren't for the fact that the nodes were redefined as type aliases, rather than interfaces with extends. This means we can't declaration merge them as before and instead we generate TS errors.

When Josh added the hack for the new nodes he added a // @ts-ignore to our codebase to silence the TS error and (as we've just learned) the line comment is elided from the .d.ts output. This means that anyone on TS 5.3 will see a type error.
In testing we can't even use a jsdoc /** @ts-ignore */ here because TS will still error on the typescript lib side.

Could we consider changing the types instead so that they export the deprecated nodes as follows:

    /** @deprecated */
    interface AssertEntry extends ImportAttribute {}
    /** @deprecated */
    interface AssertClause extends ImportAttributes {}

Additional information about the issue

For reference - we did work with the beta and RC locally within our repo to test this out.
However this problem wasn't visible within our repo because we have skipLibCheck: true.
So within the typescript-estree package the error was suppressed by the // @ts-ignore, and in the consuming packages the error was suppressed by skipLibCheck.

Additionally we didn't have a chance to try our release in a separate repo that used TS 5.3RC.

This is something we'll need to think about in future (cc @JoshuaKGoldberg)