From 31d0c8a4f47ead36c9a63ac4d3bf27b55c05095a Mon Sep 17 00:00:00 2001
From: Erik Thorelli <ethorelli@gmail.com>
Date: Mon, 5 Oct 2026 19:29:26 -0700
Subject: [PATCH] chore(lint): require a reason on every lint and type-checker
 suppression (#16294)

---
 .../src/project/ProjectSetupScriptRunner.ts   |   4 +-
 .../components/files/BrowserDocumentFrame.tsx |   2 +-
 oxlint-plugin-t3code/index.ts                 |   2 +
 .../rules/require-suppression-reason.test.ts  | 117 ++++++++++++++++++
 .../rules/require-suppression-reason.ts       |  70 +++++++++++
 packages/shared/src/qrCode.ts                 |   2 +-
 vite.config.ts                                |   1 +
 7 files changed, 194 insertions(+), 4 deletions(-)
 create mode 100644 oxlint-plugin-t3code/rules/require-suppression-reason.test.ts
 create mode 100644 oxlint-plugin-t3code/rules/require-suppression-reason.ts

diff --git a/apps/server/src/project/ProjectSetupScriptRunner.ts b/apps/server/src/project/ProjectSetupScriptRunner.ts
index f97c0f4df9c0a1fc346aa6e86cd3e82462bf324a..956733ba8506afd5e0cb962a91bed1a9ddcf7364 100644
--- a/apps/server/src/project/ProjectSetupScriptRunner.ts
+++ b/apps/server/src/project/ProjectSetupScriptRunner.ts
@@ -144,11 +144,11 @@ function stripTerminalControl(text: string): string {
   return (
     text
       .replace(
-        // eslint-disable-next-line no-control-regex
+        // eslint-disable-next-line no-control-regex -- ANSI escape sequences start with ESC.
         /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[()][A-Za-z0-9]|\x1b[=>]/g,
         "",
       )
-      // eslint-disable-next-line no-control-regex
+      // eslint-disable-next-line no-control-regex -- removing control characters is the point.
       .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "")
   );
 }
diff --git a/apps/web/src/components/files/BrowserDocumentFrame.tsx b/apps/web/src/components/files/BrowserDocumentFrame.tsx
index 1665fccd29d436ea7b4e6c9b3e276fc2d25b2886..827a81f2c6ed3e60ef104392eab2264ebe210151 100644
--- a/apps/web/src/components/files/BrowserDocumentFrame.tsx
+++ b/apps/web/src/components/files/BrowserDocumentFrame.tsx
@@ -35,7 +35,7 @@ export function BrowserDocumentFrame(props: {
 }) {
   const className = "min-h-0 flex-1 border-0 bg-white";
   return props.pdf ? (
-    // oxlint-disable-next-line react/iframe-missing-sandbox
+    // oxlint-disable-next-line react/iframe-missing-sandbox -- the built-in PDF viewer needs an unsandboxed frame.
     <iframe
       key={props.src}
       src={`${props.src}${PDF_VIEWER_FRAGMENT}`}
diff --git a/oxlint-plugin-t3code/index.ts b/oxlint-plugin-t3code/index.ts
index 855ba1e7d098304f31fec76897ed328df15c1b29..ee0368b0f093915f45e69a833164e0eb07a114c0 100644
--- a/oxlint-plugin-t3code/index.ts
+++ b/oxlint-plugin-t3code/index.ts
@@ -9,6 +9,7 @@ import noMobileUniwindThemeEscapeHatches from "./rules/no-mobile-uniwind-theme-e
 import noNativeTitleTooltip from "./rules/no-native-title-tooltip.ts";
 import noTestInLoop from "./rules/no-test-in-loop.ts";
 import noUnscopedHas from "./rules/no-unscoped-has.ts";
+import requireSuppressionReason from "./rules/require-suppression-reason.ts";
 
 export default definePlugin({
   meta: {
@@ -24,5 +25,6 @@ export default definePlugin({
     "no-native-title-tooltip": noNativeTitleTooltip,
     "no-test-in-loop": noTestInLoop,
     "no-unscoped-has": noUnscopedHas,
+    "require-suppression-reason": requireSuppressionReason,
   },
 });
diff --git a/oxlint-plugin-t3code/rules/require-suppression-reason.test.ts b/oxlint-plugin-t3code/rules/require-suppression-reason.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2ce015567f231da4f7bf6a3fb159ec6bb7fef0c4
--- /dev/null
+++ b/oxlint-plugin-t3code/rules/require-suppression-reason.test.ts
@@ -0,0 +1,117 @@
+import { assert, describe } from "@effect/vitest";
+
+import { createOxlintRuleHarness } from "../test/utils.ts";
+
+const rule = createOxlintRuleHarness("t3code/require-suppression-reason", {
+  filename: "fixture.tsx",
+});
+
+describe("t3code/require-suppression-reason", () => {
+  rule.valid(
+    "allows a directive with a -- reason",
+    `
+      // oxlint-disable-next-line no-control-regex -- ANSI sequences start with ESC.
+      const ansi = /\\x1b\\[/;
+      /* eslint-disable no-console -- this script reports to the terminal */
+    `,
+  );
+
+  rule.valid(
+    "allows a directive explained by the comment above",
+    `
+      // Positions are stable for a given string.
+      // oxlint-disable-next-line react/no-array-index-key
+      const items = ["a"].map((item, index) => <li key={index}>{item}</li>);
+    `,
+  );
+
+  rule.valid(
+    "allows stacked directives under one explanation",
+    `
+      // The fixture is invalid on purpose.
+      // @ts-expect-error
+      // oxlint-disable-next-line no-unused-vars
+      const value: number = "text";
+    `,
+  );
+
+  rule.valid(
+    "allows a TypeScript directive followed by its reason",
+    `
+      // @ts-expect-error the fixture passes a string on purpose
+      const count: number = "text";
+    `,
+  );
+
+  rule.valid(
+    "allows a directive in a JSX comment with a reason",
+    `const el = <div>{/* oxlint-disable-next-line react/no-danger -- sanitized above */}</div>;`,
+  );
+
+  rule.valid("ignores enable directives", `/* oxlint-enable no-console */`);
+
+  rule.invalid(
+    "reports a lint directive without a reason",
+    `
+      // oxlint-disable-next-line no-control-regex
+      const ansi = /\\x1b\\[/;
+    `,
+    (output) => {
+      assert.match(output, /end the directive with `-- reason`/);
+    },
+  );
+
+  rule.invalid(
+    "reports a file-level directive without a reason",
+    `/* oxlint-disable eslint/no-useless-escape */`,
+  );
+
+  rule.invalid(
+    "reports a TypeScript directive without a reason",
+    `
+      // @ts-expect-error
+      const count: number = "text";
+    `,
+    (output) => {
+      assert.match(output, /write the reason after the directive/);
+    },
+  );
+
+  rule.invalid(
+    "does not count a comment separated by a blank line",
+    `
+      // Positions are stable for a given string.
+
+      // oxlint-disable-next-line react/no-array-index-key
+      const items = ["a"].map((item, index) => <li key={index}>{item}</li>);
+    `,
+  );
+
+  rule.valid(
+    "allows an empty comment line between the reason and the directive",
+    `
+      // Positions are stable for a given string.
+      //
+      // oxlint-disable-next-line react/no-array-index-key
+      const items = ["a"].map((item, index) => <li key={index}>{item}</li>);
+    `,
+  );
+
+  rule.invalid(
+    "does not count an empty comment above",
+    `
+      //
+      /* */
+      // oxlint-disable-next-line react/no-array-index-key
+      const items = ["a"].map((item, index) => <li key={index}>{item}</li>);
+    `,
+  );
+
+  rule.invalid(
+    "does not count a trailing comment on the code line above",
+    `
+      const first = 1; // the first value
+      const second = 2; // oxlint-disable-line no-unused-vars
+    `,
+  );
+});
diff --git a/oxlint-plugin-t3code/rules/require-suppression-reason.ts b/oxlint-plugin-t3code/rules/require-suppression-reason.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2f7387383880a590abdc296ed893a7bbe1b5937a
--- /dev/null
+++ b/oxlint-plugin-t3code/rules/require-suppression-reason.ts
@@ -0,0 +1,70 @@
+import { defineRule, type ESTree } from "@oxlint/plugins";
+
+// Comments that switch a diagnostic off or on. None of them explains another.
+const DIRECTIVE_PATTERN =
+  /^\s*\*?\s*(?:(?:oxlint|eslint)-(?:disable|enable)|@ts-(?:expect-error|ignore|nocheck)|@effect-diagnostics)/u;
+// TypeScript's own directives; whatever follows one is its reason.
+const TS_DIRECTIVE_PATTERN = /^\s*\*?\s*@ts-(?:expect-error|ignore|nocheck)(?![\w-])(.*)$/su;
+const EMPTY_COMMENT_PATTERN = /^[\s*]*$/u;
+
+/**
+ * Reports a directive that disables a lint rule or the type checker without saying why. The reason
+ * is a `-- reason` suffix (text after the directive, for `@ts-*`) or a comment on the line above.
+ */
+export default defineRule({
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Require every lint or type-checker suppression to say why.",
+    },
+  },
+  create(context) {
+    const { sourceCode } = context;
+    return {
+      Program() {
+        const comments = sourceCode.getAllComments();
+        const ownLineCommentsByEndLine = new Map<number, ESTree.Comment>();
+        for (const comment of comments) {
+          const { line, column } = comment.loc.start;
+          if ((sourceCode.lines[line - 1] ?? "").slice(0, column).trim() === "") {
+            ownLineCommentsByEndLine.set(comment.loc.end.line, comment);
+          }
+        }
+
+        // A comment directly above explains a directive, even across stacked directives and empty
+        // comment lines.
+        const explainedAbove = (directive: ESTree.Comment) => {
+          let above = ownLineCommentsByEndLine.get(directive.loc.start.line - 1);
+          while (
+            above &&
+            (DIRECTIVE_PATTERN.test(above.value) || EMPTY_COMMENT_PATTERN.test(above.value))
+          ) {
+            above = ownLineCommentsByEndLine.get(above.loc.start.line - 1);
+          }
+          return above !== undefined;
+        };
+
+        for (const directive of sourceCode.getDisableDirectives().directives) {
+          if (directive.type === "enable" || directive.justification?.trim()) continue;
+          if (explainedAbove(directive.node)) continue;
+          context.report({
+            loc: directive.node.loc,
+            message:
+              "Say why: end the directive with `-- reason` or put a comment on the line above.",
+          });
+        }
+
+        for (const comment of comments) {
+          const after = TS_DIRECTIVE_PATTERN.exec(comment.value)?.[1];
+          if (after === undefined || after.replace(/^[\s:-]+/u, "").trim()) continue;
+          if (explainedAbove(comment)) continue;
+          context.report({
+            loc: comment.loc,
+            message:
+              "Say why: write the reason after the directive or in a comment on the line above.",
+          });
+        }
+      },
+    };
+  },
+});
diff --git a/packages/shared/src/qrCode.ts b/packages/shared/src/qrCode.ts
index 273224a9a058e75878b4c399110c122cac5cc6e2..6c83d09df3322094ae1fba55f36443719546dcdd 100644
--- a/packages/shared/src/qrCode.ts
+++ b/packages/shared/src/qrCode.ts
@@ -1,4 +1,4 @@
-/* oxlint-disable eslint/no-useless-escape */
+/* oxlint-disable eslint/no-useless-escape -- vendored Project Nayuki code, kept as upstream wrote it. */
 /*
  * QR Code generator library (TypeScript)
  *
diff --git a/vite.config.ts b/vite.config.ts
index 0eee88e2ad0821287662ffdb17b6ee45afa8be0d..789ac38e20b64941a4b8dcc62ecd6200d224fbdd 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -170,6 +170,7 @@ export default defineConfig({
       "t3code/no-test-in-loop": "error",
       "t3code/no-unscoped-has": "error",
       "t3code/namespace-node-imports": "error",
+      "t3code/require-suppression-reason": "error",
     },
     overrides: [
       {
-- 
2.54.0