{"record":{"id":"d1caa92a144ed6b6","repo":"oxc-project/oxc","slug":"do-not-use-ts-ts-comment-name-because-it-alters","errorCode":null,"errorMessage":"Do not use @ts-{ts_comment_name} because it alters compilation errors.","messagePattern":"Do not use @ts-(.+?) because it alters compilation errors\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/typescript/ban_ts_comment.rs","lineNumber":16,"sourceCode":"use cow_utils::CowUtils;\nuse lazy_regex::Regex;\nuse oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::Span;\nuse schemars::JsonSchema;\nuse serde::Deserialize;\n\nuse crate::{\n    context::{ContextHost, LintContext},\n    rule::{DefaultRuleConfig, Rule},\n    utils::deserialize_required_regex_option,\n};\n\nfn comment(ts_comment_name: &str, span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(format!(\n        \"Do not use @ts-{ts_comment_name} because it alters compilation errors.\"\n    ))\n    .with_help(format!(\"Remove the @ts-{ts_comment_name} directive and fix the underlying TypeScript error instead. If you must suppress an error, consider using @ts-expect-error with a descriptive comment explaining why it's necessary.\"))\n    .with_label(span)\n}\n\nfn ignore_instead_of_expect_error(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Use \\\"@ts-expect-error\\\" instead of @ts-ignore, as \\\"@ts-ignore\\\" will do nothing if the following line is error-free.\")\n        .with_help(\"Replace \\\"@ts-ignore\\\" with \\\"@ts-expect-error\\\".\")\n        .with_label(span)\n}\n\nfn comment_requires_description(ts_comment_name: &str, min_len: u64, span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(format!(\n        \"Include a description after the @ts-{ts_comment_name} directive to explain why the @ts-{ts_comment_name} is necessary. The description must be {min_len} characters or longer.\"\n    ))\n    .with_help(format!(\"Add a description after @ts-{ts_comment_name} that is at least {min_len} characters long, explaining why the directive is necessary. For example: `// @ts-{ts_comment_name}: TS2345 - This is a known limitation with third-party types`\"))\n    .with_note(\"Requiring descriptions ensures that developers document why they're suppressing TypeScript errors, making it easier for future maintainers to understand the context and decide if the suppression is still necessary.\")","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/typescript/ban_ts_comment.rs#L1-L34","documentation":"Diagnostic from oxlint's port of @typescript-eslint/ban-ts-comment. Compiler-directive comments that suppress TypeScript errors (`@ts-ignore`, `@ts-nocheck` by default) silently mask real type problems, so the rule bans them and tells you to fix the underlying error. Defaults: ts-ignore and ts-nocheck banned, ts-expect-error allowed only with a description (minimumDescriptionLength 3), ts-check allowed. This base 'Do not use @ts-X' message is the banned-directive diagnostic.","triggerScenarios":"A `// @ts-ignore` or `// @ts-nocheck` comment when the directive's config is true (banned) — both are banned out of the box; also any directive configured `true` that appears in code. (A description-less `@ts-expect-error` under its allow-with-description default produces the sibling comment_requires_description diagnostic instead; missing-description `@ts-ignore` under allow-with-description produces the ignore_instead_of_expect_error diagnostic.)","commonSituations":"Suppressing noisy third-party typing issues and never revisiting; migrating JS→TS files sprinkled with @ts-ignore; bulk `@ts-nocheck` on legacy files to get CI green; upgrading TypeScript versions that surface new errors.","solutions":["Fix the underlying type error and delete the directive (the only real fix).","If suppression is legitimate and temporary, switch to `// @ts-expect-error: <why>` — it errors out once the underlying error disappears, unlike @ts-ignore.","Configure per-directive policy instead of banning: e.g. `{ \"ts-ignore\": \"allow-with-description\", \"ts-nocheck\": false }` with a minimumDescriptionLength.","For whole-file legacy opts, scope an inline disable comment narrowly rather than disabling the rule repo-wide."],"exampleFix":"// before\n// @ts-ignore\nconst total: number = \"42\";\n\n// after\nconst total: number = 42;\n// or, when suppression is justified:\n// @ts-expect-error: legacy payload types are wrong until v2\nconst total: number = readLegacy();","handlingStrategy":"validation","validationCode":"oxlint --ts-plugin src/ # ban-ts-comment defaults: ts-ignore/ts-nocheck banned\n\n# measure suppression debt before cleanup\nrg -n --no-ignore '@ts-(ignore|nocheck)' src/ | wc -l","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Fix the type error instead of suppressing it; delete directives as soon as they go stale.","When suppression is warranted, use @ts-expect-error with a description (default minimumDescriptionLength is 3).","Track the count of directives over time so suppression debt does not grow invisibly.","Use @ts-nocheck only as a scoped, time-boxed migration tool, never permanently."],"tags":["typescript","ts-comment","suppression","oxlint","lint","restriction"],"backgroundTag":"ts-comment-suppression","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}