Skip to content

Commit d469f4f

Browse files
committed
chore(lint): require a reason on every lint and type-checker suppression
The Effect conventions review check asks every new suppression to say why, and most already do, with a `-- reason` suffix or a comment on the line above. Nothing enforced it, so four didn't. Add `t3code/require-suppression-reason`. It reads oxlint and ESLint directives through `getDisableDirectives()`, so it parses them the way oxlint applies them, and checks `@ts-*` directives for text after them. Give the four their reasons. `@effect-diagnostics` directives aren't covered yet.
1 parent 4df84a7 commit d469f4f

7 files changed

Lines changed: 169 additions & 4 deletions

File tree

‎apps/server/src/project/ProjectSetupScriptRunner.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -144,11 +144,11 @@ function stripTerminalControl(text: string): string {
144144
return (
145145
text
146146
.replace(
147-
// eslint-disable-next-line no-control-regex
147+
// eslint-disable-next-line no-control-regex -- ANSI escape sequences start with ESC.
148148
/\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[()][A-Za-z0-9]|\x1b[=>]/g,
149149
"",
150150
)
151-
// eslint-disable-next-line no-control-regex
151+
// eslint-disable-next-line no-control-regex -- removing control characters is the point.
152152
.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "")
153153
);
154154
}

‎apps/web/src/components/files/BrowserDocumentFrame.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ export function BrowserDocumentFrame(props: {
3434
}) {
3535
const className = "min-h-0 flex-1 border-0 bg-white";
3636
return props.pdf ? (
37-
// oxlint-disable-next-line react/iframe-missing-sandbox
37+
// oxlint-disable-next-line react/iframe-missing-sandbox -- the built-in PDF viewer needs an unsandboxed frame.
3838
<iframe
3939
key={props.src}
4040
src={`${props.src}${PDF_VIEWER_FRAGMENT}`}

‎oxlint-plugin-t3code/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import noMobileUniwindThemeEscapeHatches from "./rules/no-mobile-uniwind-theme-e
99
import noNativeTitleTooltip from "./rules/no-native-title-tooltip.ts";
1010
import noTestInLoop from "./rules/no-test-in-loop.ts";
1111
import noUnscopedHas from "./rules/no-unscoped-has.ts";
12+
import requireSuppressionReason from "./rules/require-suppression-reason.ts";
1213

1314
export default definePlugin({
1415
meta: {
@@ -24,5 +25,6 @@ export default definePlugin({
2425
"no-native-title-tooltip": noNativeTitleTooltip,
2526
"no-test-in-loop": noTestInLoop,
2627
"no-unscoped-has": noUnscopedHas,
28+
"require-suppression-reason": requireSuppressionReason,
2729
},
2830
});
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
import { assert, describe } from "@effect/vitest";
2+
3+
import { createOxlintRuleHarness } from "../test/utils.ts";
4+
5+
const rule = createOxlintRuleHarness("t3code/require-suppression-reason", {
6+
filename: "fixture.tsx",
7+
});
8+
9+
describe("t3code/require-suppression-reason", () => {
10+
rule.valid(
11+
"allows a directive with a -- reason",
12+
`
13+
// oxlint-disable-next-line no-control-regex -- ANSI sequences start with ESC.
14+
const ansi = /\\x1b\\[/;
15+
/* eslint-disable no-console -- this script reports to the terminal */
16+
`,
17+
);
18+
19+
rule.valid(
20+
"allows a directive explained by the comment above",
21+
`
22+
// Positions are stable for a given string.
23+
// oxlint-disable-next-line react/no-array-index-key
24+
const items = ["a"].map((item, index) => <li key={index}>{item}</li>);
25+
`,
26+
);
27+
28+
rule.valid(
29+
"allows stacked directives under one explanation",
30+
`
31+
// The fixture is invalid on purpose.
32+
// @ts-expect-error
33+
// oxlint-disable-next-line no-unused-vars
34+
const value: number = "text";
35+
`,
36+
);
37+
38+
rule.valid(
39+
"allows a TypeScript directive followed by its reason",
40+
`
41+
// @ts-expect-error the fixture passes a string on purpose
42+
const count: number = "text";
43+
`,
44+
);
45+
46+
rule.valid(
47+
"allows a directive in a JSX comment with a reason",
48+
`const el = <div>{/* oxlint-disable-next-line react/no-danger -- sanitized above */}</div>;`,
49+
);
50+
51+
rule.valid("ignores enable directives", `/* oxlint-enable no-console */`);
52+
53+
rule.invalid(
54+
"reports a lint directive without a reason",
55+
`
56+
// oxlint-disable-next-line no-control-regex
57+
const ansi = /\\x1b\\[/;
58+
`,
59+
(output) => {
60+
assert.match(output, /end the directive with `-- reason`/);
61+
},
62+
);
63+
64+
rule.invalid(
65+
"reports a file-level directive without a reason",
66+
`/* oxlint-disable eslint/no-useless-escape */`,
67+
);
68+
69+
rule.invalid(
70+
"reports a TypeScript directive without a reason",
71+
`
72+
// @ts-expect-error
73+
const count: number = "text";
74+
`,
75+
(output) => {
76+
assert.match(output, /write the reason after the directive/);
77+
},
78+
);
79+
80+
rule.invalid(
81+
"does not count a comment separated by a blank line",
82+
`
83+
// Positions are stable for a given string.
84+
85+
// oxlint-disable-next-line react/no-array-index-key
86+
const items = ["a"].map((item, index) => <li key={index}>{item}</li>);
87+
`,
88+
);
89+
90+
rule.invalid(
91+
"does not count a trailing comment on the code line above",
92+
`
93+
const first = 1; // the first value
94+
const second = 2; // oxlint-disable-line no-unused-vars
95+
`,
96+
);
97+
});
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
import { defineRule, type ESTree } from "@oxlint/plugins";
2+
3+
// Comments that switch a diagnostic off or on. None of them explains another.
4+
const DIRECTIVE_PATTERN =
5+
/^\s*\*?\s*(?:(?:oxlint|eslint)-(?:disable|enable)|@ts-(?:expect-error|ignore|nocheck)|@effect-diagnostics)/u;
6+
// TypeScript's own directives; whatever follows one is its reason.
7+
const TS_DIRECTIVE_PATTERN = /^\s*\*?\s*@ts-(?:expect-error|ignore|nocheck)(?![\w-])(.*)$/su;
8+
9+
/**
10+
* Reports a directive that disables a lint rule or the type checker without saying why. The reason
11+
* is a `-- reason` suffix (text after the directive, for `@ts-*`) or a comment on the line above.
12+
*/
13+
export default defineRule({
14+
meta: {
15+
type: "suggestion",
16+
docs: {
17+
description: "Require every lint or type-checker suppression to say why.",
18+
},
19+
},
20+
create(context) {
21+
const { sourceCode } = context;
22+
return {
23+
Program() {
24+
const comments = sourceCode.getAllComments();
25+
const ownLineCommentsByEndLine = new Map<number, ESTree.Comment>();
26+
for (const comment of comments) {
27+
const { line, column } = comment.loc.start;
28+
if ((sourceCode.lines[line - 1] ?? "").slice(0, column).trim() === "") {
29+
ownLineCommentsByEndLine.set(comment.loc.end.line, comment);
30+
}
31+
}
32+
33+
// A comment directly above explains a directive, even across other stacked directives.
34+
const explainedAbove = (directive: ESTree.Comment) => {
35+
let above = ownLineCommentsByEndLine.get(directive.loc.start.line - 1);
36+
while (above && DIRECTIVE_PATTERN.test(above.value)) {
37+
above = ownLineCommentsByEndLine.get(above.loc.start.line - 1);
38+
}
39+
return above !== undefined;
40+
};
41+
42+
for (const directive of sourceCode.getDisableDirectives().directives) {
43+
if (directive.type === "enable" || directive.justification?.trim()) continue;
44+
if (explainedAbove(directive.node)) continue;
45+
context.report({
46+
loc: directive.node.loc,
47+
message:
48+
"Say why: end the directive with `-- reason` or put a comment on the line above.",
49+
});
50+
}
51+
52+
for (const comment of comments) {
53+
const after = TS_DIRECTIVE_PATTERN.exec(comment.value)?.[1];
54+
if (after === undefined || after.replace(/^[\s:-]+/u, "").trim()) continue;
55+
if (explainedAbove(comment)) continue;
56+
context.report({
57+
loc: comment.loc,
58+
message:
59+
"Say why: write the reason after the directive or in a comment on the line above.",
60+
});
61+
}
62+
},
63+
};
64+
},
65+
});

‎packages/shared/src/qrCode.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
/* oxlint-disable eslint/no-useless-escape */
1+
/* oxlint-disable eslint/no-useless-escape -- vendored Project Nayuki code, kept as upstream wrote it. */
22
/*
33
* QR Code generator library (TypeScript)
44
*

‎vite.config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,7 @@ export default defineConfig({
170170
"t3code/no-test-in-loop": "error",
171171
"t3code/no-unscoped-has": "error",
172172
"t3code/namespace-node-imports": "error",
173+
"t3code/require-suppression-reason": "error",
173174
},
174175
overrides: [
175176
{

0 commit comments

Comments
 (0)