Skip to content

Commit 3061529

Browse files
chore(lint): a new React effect states its reason instead of raising the budget
The budget rule told authors to try a ref callback or a store, which rewarded hiding lifecycle work instead of judging an effect by its purpose. An effect with `// oxlint-disable-next-line t3code/react-effect-budget -- <why>` above it is now left out of the count, so the reason sits on the effect where reviewers see it. The message asks whether the work is synchronization that belongs in render or a handler, and no longer suggests refs or stores. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 2ee1529 commit 3061529

3 files changed

Lines changed: 27 additions & 4 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,7 @@ Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/
194194
options, and pass combinators as additional function-builder arguments.
195195
- Inferred types over annotations. `any` is the enemy.
196196
- Default to no comment. Write one only for a constraint, an external quirk, or an invariant the code can't show, in one line where you can and four at most. Don't restate names or signatures, narrate steps, record history, or explain the fix you just made; the PR carries that. `t3code/no-low-value-comments` enforces the length cap and the mechanical cases.
197-
- React effects are a last resort: derive in render, act in handlers, reset with `key`, or use a ref callback or store. The `t3code/react-effect-budget` lint rule holds each file to its entry in `scripts/effect-budget.json`; raise an entry only in the PR that needs the effect, and lower it when you remove one.
197+
- React effects are for synchronizing with something outside React. Derive in render and act in handlers instead of syncing state, but don't hide real lifecycle work in refs or stores to dodge one. The `t3code/react-effect-budget` lint rule holds each file to its count in `scripts/effect-budget.json`; a new effect states its reason with `// oxlint-disable-next-line t3code/react-effect-budget -- <why>`.
198198
- Our users drive agents all day and notice a dropped frame, a lying spinner, and a stale label. No continuously repainting animations; they peg the GPU on high-refresh displays.
199199
- If a rule here fights the task in front of you, say so loudly and get a human sign-off before breaking it.
200200

‎oxlint-plugin-t3code/rules/react-effect-budget.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,5 +46,15 @@ const alias = useEffect;
4646
`,
4747
);
4848

49+
unbudgeted.valid(
50+
"does not count an effect that states its reason",
51+
`export function New() {
52+
// oxlint-disable-next-line t3code/react-effect-budget -- subscribes to the window's resize events
53+
React.useEffect(() => {});
54+
return null;
55+
}
56+
`,
57+
);
58+
4959
lint("apps/web/src/Panel.test.tsx").valid("skips test files", component(3));
5060
});

‎oxlint-plugin-t3code/rules/react-effect-budget.ts‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,12 @@ const EFFECT_HOOKS = new Set(["useEffect", "useLayoutEffect", "useInsertionEffec
99
const EFFECT_HOOK_TEXT = /use(?:Layout|Insertion)?Effect/;
1010
const UNBUDGETED_FILE = /\.test\.[cm]?[jt]sx?$|[\\/](?:test|__tests__)[\\/]/;
1111
const budgets: Readonly<Record<string, number>> = budget;
12+
const JUSTIFIED = /oxlint-disable-next-line[^\n]*t3code\/react-effect-budget\s+--\s*\S/;
13+
14+
// An effect with a stated reason on the line above is a reviewed decision: it is not counted, and it
15+
// is always reported so that the suppression comment above it is used.
16+
const isJustified = (lines: ReadonlyArray<string>, line: number): boolean =>
17+
JUSTIFIED.test(lines[line - 2] ?? "");
1218

1319
const isEffectHookCall = (node: ESTree.CallExpression): boolean => {
1420
const callee = unwrapExpression(node.callee);
@@ -39,18 +45,25 @@ export default defineRule({
3945
if (UNBUDGETED_FILE.test(context.filename) || !EFFECT_HOOK_TEXT.test(context.sourceCode.text)) {
4046
return {};
4147
}
48+
const lines = context.sourceCode.text.split("\n");
4249
const calls: Array<ESTree.CallExpression> = [];
50+
const justified: Array<ESTree.CallExpression> = [];
4351
return {
4452
CallExpression(node) {
45-
if (isEffectHookCall(node)) calls.push(node);
53+
if (!isEffectHookCall(node)) return;
54+
(isJustified(lines, node.loc.start.line) ? justified : calls).push(node);
4655
},
4756
"Program:exit"() {
57+
for (const node of justified) {
58+
context.report({ node, message: "A React effect with a stated reason." });
59+
}
4860
const allowed = budgetFor(context.filename);
4961
if (calls.length <= allowed) return;
5062
const message =
5163
`This file has ${calls.length} React ${calls.length === 1 ? "effect" : "effects"} against a budget of ${allowed}. ` +
52-
"Prefer deriving in render, event handlers, a `key` reset, an element-owned ref callback, or a store. " +
53-
`If an effect is genuinely right, raise this file's entry in ${BUDGET_FILE} in the same PR.`;
64+
"First ask whether this is synchronization that belongs in render or in the handler that causes it. " +
65+
"If an effect is the honest model, say why on the line above it: " +
66+
"`// oxlint-disable-next-line t3code/react-effect-budget -- <why>`.";
5467
for (const node of calls.slice(allowed)) context.report({ node, message });
5568
},
5669
};

0 commit comments

Comments
 (0)