{"record":{"id":"c2957c12f62561f7","repo":"oxc-project/oxc","slug":"include-a-description-after-the-ts-ts-comment-na","errorCode":null,"errorMessage":"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.","messagePattern":"Include a description after the @ts-(.+?) directive to explain why the @ts-(.+?) is necessary\\. The description must be (.+?) characters or longer\\.","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/typescript/ban_ts_comment.rs","lineNumber":30,"sourceCode":"    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.\")\n    .with_label(span)\n}\n\nfn comment_description_not_match_pattern(\n    ts_comment_name: &str,\n    pattern: &str,\n    span: Span,\n) -> OxcDiagnostic {\n    OxcDiagnostic::warn(format!(\n        \"The description for the @ts-{ts_comment_name} directive must match the {pattern} format.\"\n    ))\n    .with_help(format!(\"Update the description after @ts-{ts_comment_name} to match the required pattern: {pattern}.\"))\n    .with_label(span)\n}","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/typescript/ban_ts_comment.rs#L12-L48","documentation":"Warning emitted by oxlint rule typescript/ban-ts-comment via comment_requires_description() (crates/oxc_linter/src/rules/typescript/ban_ts_comment.rs:30). When the option minimum-description-length is set, every @ts-ignore, @ts-expect-error, @ts-nocheck, or @ts-check directive must be followed by a description of at least min_len characters; this diagnostic fires when the description is missing or too short.","triggerScenarios":"oxlint runs with ban-ts-comment configured with 'minimum-description-length' (e.g. 3) and the source contains a directive like '// @ts-ignore' or '// @ts-expect-error: x' with no description or one shorter than the configured length; the span labels the directive comment.","commonSituations":"Enabling the strict/recommended oxlint preset in CI; inheriting legacy suppression comments written before the option was turned on; writing a terse '// @ts-ignore: fix later' that falls under the configured threshold.","solutions":["Append a description of at least the configured length, e.g. '// @ts-ignore: TS2345 - SDK returns number|string until v3 ships'","Switch to '@ts-expect-error' with the same descriptive comment so the suppression errors out once the underlying problem is fixed","Fix the underlying type error and delete the directive entirely","If the policy is too strict, lower 'minimum-description-length' or remove it from .oxlintrc.json"],"exampleFix":"// before\n// @ts-ignore\nJSON.parse(raw);\n\n// after\n// @ts-ignore: TS2345 - raw is a trusted internal payload, validated at the boundary\nJSON.parse(raw);","handlingStrategy":"validation","validationCode":"const BARE = /\\/\\/\\s*@ts-(ignore|expect-error|nocheck|check)\\s*$/;\nconst DESCRIBED = /@ts-(ignore|expect-error|nocheck|check):\\s*(.*)$/;\nfor (const [i, line] of source.split('\\n').entries()) {\n  if (BARE.test(line) || (DESCRIBED.test(line) && DESCRIBED.exec(line)![1].trim().length < MIN_LEN)) {\n    fail(`line ${i + 1}: @ts- directive missing a ${MIN_LEN}+ char description`);\n  }\n}","typeGuard":"function isDirectiveDescribed(comment: string, minLen = 3): boolean {\n  const m = comment.match(/@ts-(?:ignore|expect-error|nocheck|check):\\s*(.*)$/);\n  return m !== null && m[1].trim().length >= minLen;\n}","tryCatchPattern":null,"preventionTips":["Turn on minimum-description-length in the shared config early so all new suppressions carry reasons","Standardize the description format as 'TS<code> - reason'","Prefer @ts-expect-error, which self-destructs when the suppressed error disappears","Run oxlint in a pre-commit hook so bare directives never reach CI"],"tags":["typescript","oxlint","lint","ts-ignore","suppression","comment-directive"],"backgroundTag":"ts-ignore-description-required","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}