ESLint: Ban `@ts-ignore` in favour of `@ts-expect-error` by manzoorwanijk · Pull Request #81148 · WordPress/gutenberg

manzoorwanijk · 2026-08-04T11:00:54Z

What?

Enables @typescript-eslint/ban-ts-comment so @ts-ignore is an error and @ts-expect-error requires a description, then fixes every existing violation.

Why?

@ts-ignore keeps silently passing once the error it was added for is gone, so stale suppressions accumulate unnoticed. @ts-expect-error fails when it is no longer needed, which surfaces them.

That is exactly what happened here: of the 117 @ts-ignore comments on trunk, 35 (30%) were stale — they suppressed nothing. Several also carried reasons that were no longer true, such as // @ts-ignore - Preferences package is not typed when @wordpress/preferences has been typed for a while.

Follow up to #80832 (comment).

How?

The rule is added to the repo config in tools/eslint/config.mjs. Defaults are kept, so @ts-expect-error needs a description of at least 3 characters. It applies to .js as well as .ts/.tsx — the rule only walks the comment list, so it works under the Babel parser too.

The 177 violations were resolved as:

	Count
`@ts-ignore` converted to `@ts-expect-error` with a description	82
`@ts-ignore` deleted as stale	35
Bare `@ts-expect-error` given a description	60

Each description states the reason TypeScript actually reports, taken from the compiler rather than guessed. Every directive was temporarily neutralised and tsc --build re-run to capture the real diagnostic, then restored.

Some paths get no signal from the build: tsconfig.base.json excludes **/test/**, and tools/ and routes/ are not in any TypeScript project. Directives there were checked against a temporary project extending tsconfig.base.json, and against lib.dom.d.ts and package metadata where that was the relevant fact.

Unrelated drive-by: one pre-existing import/order error in packages/components/src/button/test/index.tsx is fixed, because the pre-commit hook lints staged files under the strict config and it blocked the commit.

Testing Instructions

npm run lint:js passes.
npx tsc --build from the repo root exits cleanly.
Add // @ts-ignore anywhere and confirm linting fails with a message pointing at @ts-expect-error.
Add a bare // @ts-expect-error and confirm linting asks for a description.

Use of AI Tools

Authored with Claude Code, then audited with Codex specifically for the factual accuracy of the new comments. That audit caught descriptions that named the wrong cause and four directives that suppressed nothing; each finding was re-verified against real tsc output before being applied. I have reviewed and take responsibility for the changes.

`@ts-ignore` keeps silently passing once the error it was added for is gone, leaving dead suppressions behind. Enable `@typescript-eslint/ban-ts-comment` so `@ts-ignore` and `@ts-nocheck` are errors, and `@ts-expect-error` requires a description. The rule only walks the comment list, so it applies to JSDoc-typed `.js` files as well as `.ts`/`.tsx`. Existing violations are fixed in follow-up commits.

The `@wordpress/preferences` package is typed now, so these suppressions no longer suppress anything. Confirmed via `tsc --build`, which reports them as unused `@ts-expect-error` directives once converted.

…ect-error` Convert the live suppressions and describe what each one covers. Drop the ones `tsc` reports as unused, which no longer suppress anything.

Describe each live suppression with the reason `tsc` actually reports, and drop the directives that no longer suppress anything. Also corrects the Boot and Blocks descriptions from the previous commit.

…s-ignore` Describe each live suppression with the reason `tsc` reports, and drop the ones that suppress nothing. `tools/` and `routes/` belong to no TypeScript project, so their directives were checked against a temporary project built on `tsconfig.base.json`.

Describe each remaining suppression and drop the ones that suppress nothing. Test directories excluded from the build were checked against a temporary project so the descriptions match a real diagnostic.

`@types/react@18` does not declare `inert` at all, so saying its types do not accept the string form wrongly implies a boolean form works.

Several descriptions named the wrong cause: the failing overload in `rtl.js` is a missing index signature on `CSSProperties`, the story layout error is union narrowing rather than an unknown property, and the DataViews test error comes from the spread `onClick` handler. Four directives in the Upload Media tests suppressed nothing, since the preceding `in` guard already narrows the object. Test descriptions now name the type that is violated rather than only stating that the input is deliberately invalid.

github-actions · 2026-08-04T11:06:04Z

Size Change: 0 B

Total Size: 7.81 MB

_{compressed-size-action}

github-actions · 2026-08-04T11:10:50Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2026-08-04T11:28:18Z

Flaky tests detected in 99ac5c3.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/30903043886
📝 Reported issues:

[Flaky Test] does not dirty related template parts or navigation menus when rendered in the post editor #79294 in /test/e2e/specs/editor/blocks/navigation-passive-rendering.spec.js

aduth

This is great to keep our disabling truthful to the code 👍

I left some comments about specific instances as I was reviewing them. I don't expect those to be addressed here; in fact, I'd prefer they weren't addressed here, and I understand the backfilled descriptions to justify their existence as intended at the time. I'm hopeful that requiring descriptions will push against the instinct to add disabling comments when a better solution might exist.

aduth · 2026-08-04T17:47:35Z

 * External dependencies
 */
-// @ts-ignore
+// @ts-expect-error `hpq` does not ship type declarations.


For follow-up: The newest version does!

Addressed in #81199

aduth · 2026-08-04T17:58:27Z

 	if ( isValidElement( icon ) ) {
 		return cloneElement( icon, {
-			// @ts-ignore Just forwarding the size prop along
+			// @ts-expect-error `size` is forwarded but is not in the icon component overloads.


This code is a little odd, both in terms of whether it even makes sense to pass through all these props blindly, or if we could be doing a better job of typing it such that we don't need to disable. Cursory review with AI shows it might be possible but not entirely straight-forward.

aduth · 2026-08-04T18:02:57Z

+			// @ts-expect-error `cursor` is typed as `string`, but `null` clears it.
 			document.documentElement.style.cursor = null;


This looks like case where we're "doing it wrong" and could do this in a type-compliant way.

Suggested change

// @ts-expect-error `cursor` is typed as `string`, but `null` clears it.

document.documentElement.style.cursor = null;

document.documentElement.style.cursor = '';

Setting to empty string removes the proeprty.

Source:

If value is the empty string, invoke removeProperty() with property as argument and return.

https://drafts.csswg.org/cssom/#dom-cssstyledeclaration-setproperty

Setting to null is the same as setting to empty string.

Source:

Instead of being stringified to "null", which is the default, [a JavaScript null] will be converted to the empty string.

https://webidl.spec.whatwg.org/#LegacyNullToEmptyString

Suggested change

// @ts-expect-error `cursor` is typed as `string`, but `null` clears it.

document.documentElement.style.cursor = null;

document.documentElement.style.removeProperty( 'cursor' );

Ref: https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration/removeProperty

aduth · 2026-08-04T18:05:20Z

 			className="dataviews-footer"
-			// @ts-ignore
+			// @ts-expect-error `inert` is not declared in React 18's HTML attribute types.
 			inert={ isRefreshing ? 'true' : undefined }


We should think about how to support this in a cross-React 18/19 compatible way (cc @jsnajdr ).

aduth · 2026-08-04T18:09:23Z

 					value: filterInView.value,
-					// @ts-ignore
+					// @ts-expect-error `label` is a `string[]` here, but the element type expects a `string`.
 					label,


This seems like it might just be incorrect typings on label ?

It's typed as a string:

gutenberg/packages/dataviews/src/types/field-api.ts

Line 21 in ad0af52

label: string;

But then it's referenced as an array of two members, as we're constructing here:

gutenberg/packages/dataviews/src/utils/operators.tsx

Lines 230 to 231 in ad0af52

activeElements[ 0 ].label[ 0 ],

activeElements[ 0 ].label[ 1 ]

I guess it's a little tricky, because other places treat it as a string, it's just this "between" operator that's doing something unique. string | string[] could work as a type, but it overpromises for those other cases.

aduth · 2026-08-04T18:11:54Z

 	const visibleLockedFields = lockedFields.filter(
 		( { isVisibleFlag } ) =>
-			// @ts-expect-error
+			// @ts-expect-error A string key cannot index `View`.


This could probably be addressed by changing the typing above for isVisibleFlag: string to isVisibleFlag: 'showTitle' | 'showMedia' | 'showDescription' or some variation of keyof typeof view that reflects the fields we're expecting.

aduth · 2026-08-04T18:17:16Z

 			!! blockType?.supports?.__experimentalLayout;
 		const fallbackGapValue =
-			// @ts-expect-error
+			// @ts-expect-error `blockGap` support is typed as `boolean | AxialDirection[]`.


Maybe we should update the types to include __experimentalDefault ? We could debate whether to add types for experimental attributes, but there's plenty of precedent already in the same file.

aduth · 2026-08-04T18:20:17Z

+		// @ts-expect-error `backgroundImage` is a union whose other members have no `url`.
 		! backgroundStyle?.backgroundImage?.url


We could probably address this with effective narrowing / type predicates.

manzoorwanijk · 2026-08-05T04:35:26Z

I left some comments about specific instances as I was reviewing them. I don't expect those to be addressed here; in fact, I'd prefer they weren't addressed here, and I understand the backfilled descriptions to justify their existence as intended at the time.

Yes, my intension was to keep this PR free from any runtime changes and focus purely on getting the rule into trunk.

I'm hopeful that requiring descriptions will push against the instinct to add disabling comments when a better solution might exist.

My opinion is that the forced description will make people/agents think about the justification and may be that can help the root cause.

manzoorwanijk · 2026-08-05T04:35:58Z

@aduth I am merging this as is and then I will create a follow up PR or two to adress the concerns.

hpq 1.4.0 ships TypeScript declarations, so the two suppressions added in #81148 are no longer needed. Type the call sites against the new declarations.

manzoorwanijk · 2026-08-05T05:26:42Z

I have created the following PRs as follow ups to fix the easy ones here

…typing (#81200) * Components: Use removeProperty to clear the drag cursor Setting `style.cursor = null` relied on WebIDL's LegacyNullToEmptyString coercion and needed a `@ts-expect-error`. `removeProperty( 'cursor' )` does the same thing in a type-compliant way. * Types: Replace remaining input-control, icon, dataviews and styles ts-expect-errors Follow-up to review feedback on #81148: type each of these sites so the suppression is unnecessary rather than describing why it was needed. - Icon: type the cloned element's props as the sizing props it forwards. - Properties section: key `isVisibleFlag` to the `View` flags it indexes. - Block supports: type the object form of `spacing.blockGap`. - Background: narrow `backgroundImage` with a type predicate. Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org> Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>

manzoorwanijk added 9 commits August 4, 2026 15:22

Views: Drop stale @ts-ignore directives

d122236

The `@wordpress/preferences` package is typed now, so these suppressions no longer suppress anything. Confirmed via `tsc --build`, which reports them as unused `@ts-expect-error` directives once converted.

Blocks, Boot, Compose, Date, Sync: Replace @ts-ignore with `@ts-exp…

5270d94

…ect-error` Convert the live suppressions and describe what each one covers. Drop the ones `tsc` reports as unused, which no longer suppress anything.

Core Data, Editor, Fields: Replace @ts-ignore with @ts-expect-error

9241b10

Describe each live suppression with the reason `tsc` actually reports, and drop the directives that no longer suppress anything. Also corrects the Boot and Blocks descriptions from the previous commit.

Components, DataViews, Interactivity, Upload Media: Replace @ts-ignore

e2db290

Describe each remaining suppression and drop the ones that suppress nothing. Test directories excluded from the build were checked against a temporary project so the descriptions match a real diagnostic.

Components, DataViews: Correct the inert suppression descriptions

14de80f

`@types/react@18` does not declare `inert` at all, so saying its types do not accept the string form wrongly implies a boolean form works.

Components: Drop comments duplicated by the suppression descriptions

afb02be

manzoorwanijk added the [Type] Code Quality Issues or PRs that relate to code quality label Aug 4, 2026

manzoorwanijk requested review from Mamaduka, aduth, jsnajdr and tyxla August 4, 2026 11:10

manzoorwanijk marked this pull request as ready for review August 4, 2026 11:10

manzoorwanijk requested review from a team, DAreRodz, ajitbohra, gigitux, kevin940726, luisherranz, mmtr, nerrad, ntsekouras and oandregal as code owners August 4, 2026 11:10

aduth approved these changes Aug 4, 2026

View reviewed changes

manzoorwanijk merged commit c1d8367 into trunk Aug 5, 2026
78 of 86 checks passed

manzoorwanijk deleted the chore/eslint-ban-ts-ignore branch August 5, 2026 04:36

github-actions Bot added this to the Gutenberg 23.8 milestone Aug 5, 2026

manzoorwanijk mentioned this pull request Aug 5, 2026

Blocks: Update hpq to 1.4.0 and drop the ts-expect-error suppressions #81199

Merged

manzoorwanijk mentioned this pull request Aug 5, 2026

Types: Replace remaining @ts-expect-error suppressions with proper typing #81200

Merged

manzoorwanijk mentioned this pull request Aug 5, 2026

Blocks: Declare the @types/react-is devDependency #81203

Merged

		// @ts-expect-error `cursor` is typed as `string`, but `null` clears it.
		document.documentElement.style.cursor = null;

	// @ts-expect-error `cursor` is typed as `string`, but `null` clears it.
	document.documentElement.style.cursor = null;
	document.documentElement.style.removeProperty( 'cursor' );

	activeElements[ 0 ].label[ 0 ],
	activeElements[ 0 ].label[ 1 ]

		// @ts-expect-error `backgroundImage` is a union whose other members have no `url`.
		! backgroundStyle?.backgroundImage?.url

Uh oh!

Conversation

manzoorwanijk commented Aug 4, 2026

What?

Why?

How?

Testing Instructions

Use of AI Tools

Uh oh!

github-actions Bot commented Aug 4, 2026

Uh oh!

github-actions Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 4, 2026

Uh oh!

aduth left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manzoorwanijk commented Aug 5, 2026

Uh oh!

manzoorwanijk commented Aug 5, 2026

Uh oh!

Uh oh!

manzoorwanijk commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Aug 4, 2026 •

edited

Loading

manzoorwanijk commented Aug 5, 2026 •

edited

Loading