chore(lint): a new React effect states its reason instead of raising the budget

AGENTS.md

@@ -194,7 +194,7 @@ Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/
   options, and pass combinators as additional function-builder arguments.
 - Inferred types over annotations. `any` is the enemy.
 - 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.
-- 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.
+- 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>`.
 - 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.
 - If a rule here fights the task in front of you, say so loudly and get a human sign-off before breaking it.
 

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

@@ -46,5 +46,15 @@ const alias = useEffect;
 `,
   );
 
+  unbudgeted.valid(
+    "does not count an effect that states its reason",
+    `export function New() {
+  // oxlint-disable-next-line t3code/react-effect-budget -- subscribes to the window's resize events
+  React.useEffect(() => {});
+  return null;
+}
+`,
+  );
+
   lint("apps/web/src/Panel.test.tsx").valid("skips test files", component(3));
 });

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

@@ -9,6 +9,12 @@ const EFFECT_HOOKS = new Set(["useEffect", "useLayoutEffect", "useInsertionEffec
 const EFFECT_HOOK_TEXT = /use(?:Layout|Insertion)?Effect/;
 const UNBUDGETED_FILE = /\.test\.[cm]?[jt]sx?$|[\\/](?:test|__tests__)[\\/]/;
 const budgets: Readonly<Record<string, number>> = budget;
+const JUSTIFIED = /oxlint-disable-next-line[^\n]*t3code\/react-effect-budget\s+--\s*\S/;
+
+// An effect with a stated reason on the line above is a reviewed decision: it is not counted, and it
+// is always reported so that the suppression comment above it is used.
+const isJustified = (lines: ReadonlyArray<string>, line: number): boolean =>
+  JUSTIFIED.test(lines[line - 2] ?? "");
 
 const isEffectHookCall = (node: ESTree.CallExpression): boolean => {
   const callee = unwrapExpression(node.callee);
@@ -39,18 +45,25 @@ export default defineRule({
     if (UNBUDGETED_FILE.test(context.filename) || !EFFECT_HOOK_TEXT.test(context.sourceCode.text)) {
       return {};
     }
+    const lines = context.sourceCode.text.split("\n");
     const calls: Array<ESTree.CallExpression> = [];
+    const justified: Array<ESTree.CallExpression> = [];
     return {
       CallExpression(node) {
-        if (isEffectHookCall(node)) calls.push(node);
+        if (!isEffectHookCall(node)) return;
+        (isJustified(lines, node.loc.start.line) ? justified : calls).push(node);
       },
       "Program:exit"() {
+        for (const node of justified) {
+          context.report({ node, message: "A React effect with a stated reason." });
+        }
         const allowed = budgetFor(context.filename);
         if (calls.length <= allowed) return;
         const message =
           `This file has ${calls.length} React ${calls.length === 1 ? "effect" : "effects"} against a budget of ${allowed}. ` +
-          "Prefer deriving in render, event handlers, a `key` reset, an element-owned ref callback, or a store. " +
-          `If an effect is genuinely right, raise this file's entry in ${BUDGET_FILE} in the same PR.`;
+          "First ask whether this is synchronization that belongs in render or in the handler that causes it. " +
+          "If an effect is the honest model, say why on the line above it: " +
+          "`// oxlint-disable-next-line t3code/react-effect-budget -- <why>`.";
         for (const node of calls.slice(allowed)) context.report({ node, message });
       },
     };