@hatem427/code-guard-ci 2.2.8 → 3.0.0

package/config/react.config.ts

@@ -16,6 +16,21 @@ import { registerRules, Rule } from './guidelines.config';
 const reactRules: Rule[] = [
   // ── NEW: React 19+ Features ────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: react-use-hook
+  // ROLE: Recommend React 19 use() hook for promise/context unwrapping
+  // PURPOSE: use() replaces .then() chains and useContext() with a
+  //          single API that works in both Server and Client Components.
+  //          It suspends the component until the promise resolves.
+  // EXAMPLE:
+  //   WRONG:
+  //     const data = await fetchData().then(res => res.json());
+  //     const theme = useContext(ThemeContext);
+  //   RIGHT:
+  //     import { use } from 'react';
+  //     const data = use(fetchData());
+  //     const theme = use(ThemeContext);
+  // ─────────────────────────────────────────
   {
     id: 'react-use-hook',
     label: 'Use use() hook for unwrapping promises and context',
@@ -27,13 +42,12 @@ const reactRules: Rule[] = [
     customCheck: (file) => {
       const violations: Array<{ line: number | null; message: string }> = [];
       
-      // Flag promise handling that could use use()
       if (/\.then\s*\(|async\s*\(\s*\).*=>.*=>/.test(file.content) && 
           !file.content.includes('use(')) {
         violations.push({
           line: null,
           message:
-            'Found promise handling. Use React 19 use() hook to unwrap promises directly.\n\nWhy: use() is cleaner than .then() for unwrapping server component promises.\n\n- const data = await fetchData().then(res => res.json());\n\n+ import { use } from "react";\n+ const data = use(fetchData());\n+ // Or for context\n+ const theme = use(ThemeContext);',
+            'Found promise handling. Use React 19 use() hook to unwrap promises directly.',
         });
       }
       return violations;
@@ -42,6 +56,26 @@ const reactRules: Rule[] = [
     category: 'React 19',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-use-action-state
+  // ROLE: Enforce React 19 form handling pattern
+  // PURPOSE: useActionState() eliminates manual pending/error state
+  //          management for forms. It handles submission state, errors,
+  //          and progressive enhancement automatically.
+  // EXAMPLE:
+  //   WRONG:
+  //     const [pending, setPending] = useState(false);
+  //     const handleSubmit = async (e) => {
+  //       setPending(true);
+  //       await submitForm();
+  //       setPending(false);
+  //     };
+  //   RIGHT:
+  //     const [state, formAction, isPending] = useActionState(submit, initialState);
+  //     <form action={formAction}>
+  //       <button disabled={isPending}>{isPending ? 'Loading...' : 'Submit'}</button>
+  //     </form>
+  // ─────────────────────────────────────────
   {
     id: 'react-use-action-state',
     label: 'Use useActionState() for form handling',
@@ -53,14 +87,13 @@ const reactRules: Rule[] = [
     customCheck: (file) => {
       const violations: Array<{ line: number | null; message: string }> = [];
       
-      // Flag traditional form handling in client components
       if (/use\(["']use client['"], \{.*\}|<form\s+onSubmit|useState.*pending|useState.*loading/.test(file.content) && 
           !file.content.includes('useActionState') &&
           file.content.includes("'use client'")) {
         violations.push({
           line: null,
           message:
-            'Form with manual state management detected. Use useActionState() for simpler form handling in React 19.\n\nWhy: useActionState() handles pending states, actions, and errors automatically.\n\n- const [pending, setPending] = useState(false);\n- const handleSubmit = async (e) => {\n-   setPending(true);\n-   await submitForm();\n-   setPending(false);\n- };\n\n+ const [state, formAction, isPending] = useActionState(submit, initialState);\n+ <form action={formAction}>\n+   <button disabled={isPending}>{isPending ? "Loading..." : "Submit"}</button>',
+            'Form with manual state management detected. Use useActionState() for simpler form handling in React 19.',
         });
       }
       return violations;
@@ -69,6 +102,24 @@ const reactRules: Rule[] = [
     category: 'React 19',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-use-transition
+  // ROLE: Recommend non-blocking UI updates for expensive operations
+  // PURPOSE: useTransition() marks state updates as low-priority so the
+  //          UI stays responsive during expensive re-renders (filtering,
+  //          sorting, searching large datasets).
+  // EXAMPLE:
+  //   WRONG:
+  //     const [query, setQuery] = useState('');
+  //     const handleChange = (e) => setQuery(e.target.value);
+  //     // UI freezes during expensive filtering
+  //   RIGHT:
+  //     const [isPending, startTransition] = useTransition();
+  //     const handleChange = (e) => {
+  //       startTransition(() => setQuery(e.target.value));
+  //     };
+  //     // UI stays responsive, shows pending state
+  // ─────────────────────────────────────────
   {
     id: 'react-use-transition',
     label: 'Use useTransition() for non-blocking updates',
@@ -80,14 +131,13 @@ const reactRules: Rule[] = [
     customCheck: (file) => {
       const violations: Array<{ line: number | null; message: string }> = [];
       
-      // Flag expensive state updates without useTransition
       if (/filter|search|sort|debounce/.test(file.content) && 
           /useState\s*\(/.test(file.content) &&
           !file.content.includes('useTransition')) {
         violations.push({
           line: null,
           message:
-            'Found filter/search logic. Use useTransition() to keep UI responsive during expensive updates.\n\nWhy: useTransition marks updates as non-blocking (lower priority), preventing UI freeze.\n\n- const [query, setQuery] = useState("");\n- const handleChange = (e) => setQuery(e.target.value);\n\n+ const [isPending, startTransition] = useTransition();\n+ const handleChange = (e) => {\n+   startTransition(() => setQuery(e.target.value));\n+ };',
+            'Found filter/search logic. Use useTransition() to keep UI responsive during expensive updates.',
         });
       }
       return violations;
@@ -96,6 +146,28 @@ const reactRules: Rule[] = [
     category: 'React 19',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-use-optimistic
+  // ROLE: Recommend optimistic UI updates for async actions
+  // PURPOSE: useOptimistic() shows instant feedback to the user while
+  //          the server processes the request. If the server fails, the
+  //          state automatically rolls back.
+  // EXAMPLE:
+  //   WRONG:
+  //     const handleLike = async () => {
+  //       await api.like(postId); // User waits...
+  //       refetch();
+  //     };
+  //   RIGHT:
+  //     const [optimisticLikes, addOptimistic] = useOptimistic(
+  //       likes,
+  //       (state, newLike) => [...state, newLike]
+  //     );
+  //     const handleLike = async () => {
+  //       addOptimistic(newLike); // Instant feedback
+  //       await api.like(postId);
+  //     };
+  // ─────────────────────────────────────────
   {
     id: 'react-use-optimistic',
     label: 'Use useOptimistic() for optimistic updates',
@@ -107,7 +179,6 @@ const reactRules: Rule[] = [
     customCheck: (file) => {
       const violations: Array<{ line: number | null; message: string }> = [];
       
-      // Flag async form handlers without useOptimistic
       const hasAsyncHandler = /const\s+handle\w+\s*=\s*async\s*\(|async\s+function\s+handle/i.test(file.content);
       const hasOptimistic = /useOptimistic/i.test(file.content);
       
@@ -116,7 +187,7 @@ const reactRules: Rule[] = [
           if (/const\s+handle\w+\s*=\s*async|async\s+function\s+handle/i.test(file.lines[i])) {
             violations.push({
               line: i + 1,
-              message: `Async form handler found. Use useOptimistic() for instant UI feedback:\n\nExample:\nconst [optimisticItems, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]);\n\nThen: addOptimistic(newItem);`,
+              message: `Async form handler found. Use useOptimistic() for instant UI feedback.`,
             });
             break;
           }
@@ -131,6 +202,27 @@ const reactRules: Rule[] = [
 
   // ── Server Components (Next.js 13+, React Canary) ────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: react-server-functions
+  // ROLE: Recommend "use server" directive for secure server logic
+  // PURPOSE: Server Functions run entirely on the server, enabling
+  //          direct database access, secret handling, and mutations
+  //          without creating API routes.
+  // EXAMPLE:
+  //   WRONG:
+  //     // pages/api/user.ts (API route approach)
+  //     export async function POST(req) {
+  //       const data = await req.json();
+  //       await db.users.create(data);
+  //     }
+  //   RIGHT:
+  //     // actions/user.ts
+  //     'use server';
+  //     export async function createUser(formData: FormData) {
+  //       await db.users.create(Object.fromEntries(formData));
+  //       revalidatePath('/users');
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'react-server-functions',
     label: 'Use Server Functions with "use server" directive',
@@ -143,6 +235,24 @@ const reactRules: Rule[] = [
     category: 'React Server Functions',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-server-client-boundary
+  // ROLE: Validate "use client" boundary placement
+  // PURPOSE: Unnecessarily marking components as "use client" prevents
+  //          server-side rendering optimizations and increases the
+  //          JavaScript bundle sent to the browser.
+  // EXAMPLE:
+  //   WRONG:
+  //     'use client'; // No hooks, no interactivity!
+  //     export default function StaticCard({ title }) {
+  //       return <div>{title}</div>;
+  //     }
+  //   RIGHT:
+  //     // No directive needed — Server Component by default
+  //     export default function StaticCard({ title }) {
+  //       return <div>{title}</div>;
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'react-server-client-boundary',
     label: 'Verify "use client" boundaries',
@@ -158,7 +268,6 @@ const reactRules: Rule[] = [
       const hasHooks = /use(State|Effect|Context|Reducer|Callback|Memo|Ref|Transition|OptimisticOptimistic)\s*\(/.test(file.content);
       const hasExport = /export\s+(default\s+)?function|export\s+(default\s+)?const/.test(file.content);
 
-      // If no hooks but has "use client", might be misplaced
       if (hasUseClient && !hasHooks && hasExport) {
         violations.push({
           line: 1,
@@ -174,6 +283,26 @@ const reactRules: Rule[] = [
 
   // ── Hooks ──────────────────────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: react-no-useeffect-no-deps
+  // ROLE: Block useEffect without dependency array
+  // PURPOSE: Missing dependency array causes useEffect to run after
+  //          EVERY render, leading to infinite loops, stale closures,
+  //          and severe performance issues.
+  // EXAMPLE:
+  //   WRONG:
+  //     useEffect(() => {
+  //       fetchData();
+  //     }); // Runs on every render!
+  //   RIGHT:
+  //     useEffect(() => {
+  //       fetchData();
+  //     }, []); // Runs once on mount
+  //     // With dependencies:
+  //     useEffect(() => {
+  //       fetchData(id);
+  //     }, [id]); // Runs when id changes
+  // ─────────────────────────────────────────
   {
     id: 'react-no-useeffect-no-deps',
     label: 'useEffect must have dependency array',
@@ -189,9 +318,7 @@ const reactRules: Rule[] = [
       for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
 
-        // Detect useEffect( without a closing bracket on subsequent lines containing dependency array
         if (/useEffect\s*\(\s*\(\s*\)\s*=>\s*\{/.test(line)) {
-          // Look ahead for the closing of useEffect — find , [] or , [deps])
           let foundDeps = false;
           let parenDepth = 0;
           for (let j = i; j < Math.min(i + 50, lines.length); j++) {
@@ -199,7 +326,6 @@ const reactRules: Rule[] = [
               if (ch === '(') parenDepth++;
               if (ch === ')') parenDepth--;
             }
-            // Check if the dependency array is present
             if (/\]\s*\)\s*;?\s*$/.test(lines[j]) || /,\s*\[/.test(lines[j])) {
               foundDeps = true;
               break;
@@ -210,7 +336,7 @@ const reactRules: Rule[] = [
           if (!foundDeps) {
             violations.push({
               line: i + 1,
-              message: 'useEffect without dependency array detected. Always specify dependencies.💡 How to fix: Missing dependency array causes infinite re-renders or stale closures.\n\n- useEffect(() => {\n-   fetchData();\n- });\n\n+ useEffect(() => {\n+   fetchData();\n+ }, []);\n+\n+ // With dependencies\n+ useEffect(() => {\n+   fetchData(id);\n+ }, [id]);',
+              message: 'useEffect without dependency array detected. Always specify dependencies.',
             });
           }
         }
@@ -222,6 +348,18 @@ const reactRules: Rule[] = [
     category: 'React Hooks',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-no-inline-styles
+  // ROLE: Block inline style objects in JSX
+  // PURPOSE: Inline style={{ }} creates a new object on every render,
+  //          preventing React's reconciliation from skipping unchanged
+  //          elements. Use Tailwind or CSS modules instead.
+  // EXAMPLE:
+  //   WRONG:
+  //     <div style={{ color: 'red', fontSize: '1rem' }}>Hello</div>
+  //   RIGHT:
+  //     <div className="text-red-500 text-base">Hello</div>
+  // ─────────────────────────────────────────
   {
     id: 'react-no-inline-styles',
     label: 'No inline style objects',
@@ -234,6 +372,21 @@ const reactRules: Rule[] = [
     category: 'Styling',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-no-direct-dom
+  // ROLE: Block direct DOM manipulation in React components
+  // PURPOSE: React maintains a virtual DOM — direct DOM manipulation
+  //          bypasses React's reconciliation and causes state
+  //          inconsistencies, hydration errors, and bugs.
+  // EXAMPLE:
+  //   WRONG:
+  //     document.getElementById('input').value = 'hello';
+  //     document.querySelector('.modal').classList.add('open');
+  //   RIGHT:
+  //     const inputRef = useRef<HTMLInputElement>(null);
+  //     const [isOpen, setIsOpen] = useState(false);
+  //     inputRef.current!.value = 'hello';
+  // ─────────────────────────────────────────
   {
     id: 'react-no-direct-dom',
     label: 'No direct DOM manipulation',
@@ -248,6 +401,20 @@ const reactRules: Rule[] = [
 
   // ── Component patterns ─────────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: react-no-react-fc
+  // ROLE: Block deprecated React.FC type
+  // PURPOSE: React.FC implicitly includes children, has issues with
+  //          generics, and doesn't work well with defaultProps. Direct
+  //          prop typing is cleaner and more explicit.
+  // EXAMPLE:
+  //   WRONG:
+  //     const UserCard: React.FC<Props> = ({ name }) => { ... };
+  //   RIGHT:
+  //     function UserCard({ name }: Props): React.ReactNode { ... }
+  //     // Or:
+  //     const UserCard = ({ name }: Props) => { ... };
+  // ─────────────────────────────────────────
   {
     id: 'react-no-react-fc',
     label: 'Do not use React.FC',
@@ -260,6 +427,17 @@ const reactRules: Rule[] = [
     category: 'TypeScript',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-explicit-return-types
+  // ROLE: Recommend explicit return types for component functions
+  // PURPOSE: Explicit return types catch accidental non-JSX returns,
+  //          prevent undefined leaks, and improve code documentation.
+  // EXAMPLE:
+  //   WRONG:
+  //     export function UserCard(props: Props) { ... }
+  //   RIGHT:
+  //     export function UserCard(props: Props): React.ReactNode { ... }
+  // ─────────────────────────────────────────
   {
     id: 'react-explicit-return-types',
     label: 'Add explicit return types for components',
@@ -272,6 +450,18 @@ const reactRules: Rule[] = [
     category: 'TypeScript',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-no-prop-spreading
+  // ROLE: Discourage prop spreading for API clarity
+  // PURPOSE: Spreading props ({...props}) hides the component API,
+  //          passes unintended props, and breaks TypeScript strictness.
+  //          Explicitly passing required props is safer and self-documenting.
+  // EXAMPLE:
+  //   WRONG:
+  //     <Button {...props} />
+  //   RIGHT:
+  //     <Button onClick={props.onClick} disabled={props.disabled} label={props.label} />
+  // ─────────────────────────────────────────
   {
     id: 'react-no-prop-spreading',
     label: 'Avoid prop spreading ({...props})',
@@ -289,6 +479,20 @@ const reactRules: Rule[] = [
   // NOTE: 'react-no-dangerously-set-html' removed — covered by ESLint 'react/no-danger' rule
   // NOTE: 'no-eval' removed — covered by ESLint 'no-eval' rule
 
+  // ─────────────────────────────────────────
+  // RULE: no-hardcoded-credentials
+  // ROLE: Block hardcoded secrets in source code
+  // PURPOSE: Hardcoded API keys, passwords, and tokens get committed to
+  //          git, leaked in public repos, and exposed in client bundles.
+  //          Always use environment variables (.env).
+  // EXAMPLE:
+  //   WRONG:
+  //     const apiKey = 'sk-1234567890abcdef';
+  //     const password = 'admin123';
+  //   RIGHT:
+  //     const apiKey = process.env.API_KEY;
+  //     const password = process.env.ADMIN_PASSWORD;
+  // ─────────────────────────────────────────
   {
     id: 'no-hardcoded-credentials',
     label: 'No hardcoded credentials',
@@ -327,6 +531,20 @@ const reactRules: Rule[] = [
     category: 'Security',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: require-https
+  // ROLE: Block insecure HTTP URLs in source code
+  // PURPOSE: HTTP transmits data in plain text — passwords, tokens, and
+  //          user data can be intercepted. HTTPS is mandatory for all
+  //          production API calls and external resources.
+  // EXAMPLE:
+  //   WRONG:
+  //     fetch('http://api.example.com/users');
+  //   RIGHT:
+  //     fetch('https://api.example.com/users');
+  //     // localhost is exempt:
+  //     fetch('http://localhost:3000/api');
+  // ─────────────────────────────────────────
   {
     id: 'require-https',
     label: 'Require HTTPS URLs',
@@ -341,6 +559,19 @@ const reactRules: Rule[] = [
 
   // ── Performance Rules ──────────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: react-no-anonymous-functions-in-render
+  // ROLE: Block anonymous functions in JSX event handlers
+  // PURPOSE: Arrow functions in props create a new function reference on
+  //          every render, defeating React.memo and causing child
+  //          components to re-render unnecessarily.
+  // EXAMPLE:
+  //   WRONG:
+  //     <Button onClick={() => handleClick(id)} />
+  //   RIGHT:
+  //     const handleButtonClick = useCallback(() => handleClick(id), [id]);
+  //     <Button onClick={handleButtonClick} />
+  // ─────────────────────────────────────────
   {
     id: 'react-no-anonymous-functions-in-render',
     label: 'No anonymous functions in JSX props',
@@ -353,6 +584,19 @@ const reactRules: Rule[] = [
     category: 'Performance',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-missing-key-prop
+  // ROLE: Block list rendering without key props
+  // PURPOSE: React uses key to identify which items changed, were added,
+  //          or removed. Missing keys cause UI bugs and poor performance.
+  //          Array index as key causes issues with reordering.
+  // EXAMPLE:
+  //   WRONG:
+  //     items.map(item => <Card title={item.name} />);
+  //     items.map((item, i) => <Card key={i} title={item.name} />);
+  //   RIGHT:
+  //     items.map(item => <Card key={item.id} title={item.name} />);
+  // ─────────────────────────────────────────
   {
     id: 'react-missing-key-prop',
     label: 'Missing key prop in list',
@@ -367,9 +611,7 @@ const reactRules: Rule[] = [
 
       for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
-        // Detect .map( with JSX but no key prop nearby
         if (/\.\s*map\s*\(/.test(line)) {
-          // Look ahead for JSX opening tag
           let foundKey = false;
           for (let j = i; j < Math.min(i + 10, lines.length); j++) {
             if (/key\s*=/.test(lines[j])) {
@@ -378,7 +620,6 @@ const reactRules: Rule[] = [
             }
           }
           
-          // Check if there's JSX in the map
           let hasJsx = false;
           for (let j = i; j < Math.min(i + 10, lines.length); j++) {
             if (/<[A-Z]/.test(lines[j]) || /<[a-z]/.test(lines[j])) {
@@ -402,6 +643,20 @@ const reactRules: Rule[] = [
     category: 'Performance',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: no-large-bundle-imports
+  // ROLE: Block large library wildcard imports
+  // PURPOSE: Importing entire lodash (~70KB) or moment (~290KB) when
+  //          you only need one function wastes bandwidth. Use specific
+  //          imports for tree-shaking support.
+  // EXAMPLE:
+  //   WRONG:
+  //     import _ from 'lodash';
+  //     import moment from 'moment';
+  //   RIGHT:
+  //     import get from 'lodash/get';
+  //     import { format } from 'date-fns';
+  // ─────────────────────────────────────────
   {
     id: 'no-large-bundle-imports',
     label: 'Avoid large library imports',
@@ -418,6 +673,19 @@ const reactRules: Rule[] = [
 
   // ── Accessibility Rules ────────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: require-button-type
+  // ROLE: Enforce type attribute on all button elements
+  // PURPOSE: Buttons default to type="submit", which triggers form
+  //          submission unexpectedly. Always specify type explicitly
+  //          to prevent accidental form submissions.
+  // EXAMPLE:
+  //   WRONG:
+  //     <button onClick={handleClick}>Click me</button>
+  //   RIGHT:
+  //     <button type="button" onClick={handleClick}>Click me</button>
+  //     <button type="submit">Submit</button>
+  // ─────────────────────────────────────────
   {
     id: 'require-button-type',
     label: 'Buttons must have type attribute',
@@ -448,6 +716,21 @@ const reactRules: Rule[] = [
 
   // ── Additional Performance Rules ───────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: react-prefer-lazy-loading
+  // ROLE: Recommend code splitting for route components
+  // PURPOSE: Eagerly importing all page components increases the initial
+  //          bundle size. React.lazy() + Suspense splits code by route,
+  //          loading pages only when navigated to.
+  // EXAMPLE:
+  //   WRONG:
+  //     import Dashboard from '../pages/Dashboard';
+  //     import Settings from '../pages/Settings';
+  //   RIGHT:
+  //     const Dashboard = lazy(() => import('../pages/Dashboard'));
+  //     const Settings = lazy(() => import('../pages/Settings'));
+  //     <Suspense fallback={<Spinner />}><Dashboard /></Suspense>
+  // ─────────────────────────────────────────
   {
     id: 'react-prefer-lazy-loading',
     label: 'Consider lazy loading for routes',
@@ -460,6 +743,22 @@ const reactRules: Rule[] = [
     category: 'Performance',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-memo-expensive-components
+  // ROLE: Recommend React.memo for large render trees
+  // PURPOSE: Components with expensive render logic (>500 chars of JSX)
+  //          should be wrapped in React.memo to skip re-renders when
+  //          props haven't changed.
+  // EXAMPLE:
+  //   WRONG:
+  //     export function DataTable({ rows }) {
+  //       // ... 500+ lines of complex rendering
+  //     }
+  //   RIGHT:
+  //     export const DataTable = memo(function DataTable({ rows }) {
+  //       // ... 500+ lines of complex rendering
+  //     });
+  // ─────────────────────────────────────────
   {
     id: 'react-memo-expensive-components',
     label: 'Consider React.memo for expensive renders',
@@ -472,6 +771,21 @@ const reactRules: Rule[] = [
     category: 'Performance',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: no-object-array-in-deps
+  // ROLE: Block unstable references in hook dependency arrays
+  // PURPOSE: Objects and arrays create new references on every render.
+  //          Putting them in dependency arrays triggers hooks on every
+  //          render, defeating the purpose of the dependency array.
+  // EXAMPLE:
+  //   WRONG:
+  //     useEffect(() => { ... }, [{ id: 1 }]);
+  //     useMemo(() => { ... }, [[1, 2, 3]]);
+  //   RIGHT:
+  //     useEffect(() => { ... }, [id]);
+  //     const configRef = useRef(config); // stable reference
+  //     useEffect(() => { ... }, [configRef]);
+  // ─────────────────────────────────────────
   {
     id: 'no-object-array-in-deps',
     label: 'Avoid objects/arrays in dependency arrays',
@@ -486,6 +800,18 @@ const reactRules: Rule[] = [
 
   // ── Additional Best Practice Rules ────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: react-use-fragments
+  // ROLE: Recommend React fragments over wrapper divs
+  // PURPOSE: Unnecessary wrapper <div>s add DOM nodes, break CSS layouts
+  //          (flexbox, grid), increase memory usage, and cause
+  //          accessibility issues with screen readers.
+  // EXAMPLE:
+  //   WRONG:
+  //     return (<div><Header /><Content /></div>);
+  //   RIGHT:
+  //     return (<><Header /><Content /></>);
+  // ─────────────────────────────────────────
   {
     id: 'react-use-fragments',
     label: 'Use React fragments instead of divs',
@@ -498,6 +824,18 @@ const reactRules: Rule[] = [
     category: 'Best Practices',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: prefer-optional-chaining
+  // ROLE: Recommend modern null-safe access patterns
+  // PURPOSE: Chained && checks are verbose and error-prone. Optional
+  //          chaining (?.) is built into the language, more readable,
+  //          and handles null/undefined safely.
+  // EXAMPLE:
+  //   WRONG:
+  //     user && user.profile && user.profile.name
+  //   RIGHT:
+  //     user?.profile?.name
+  // ─────────────────────────────────────────
   {
     id: 'prefer-optional-chaining',
     label: 'Use optional chaining',
@@ -510,6 +848,18 @@ const reactRules: Rule[] = [
     category: 'Modern Syntax',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: prefer-nullish-coalescing
+  // ROLE: Recommend ?? over || for default values
+  // PURPOSE: || treats 0, '', and false as falsy and replaces them.
+  //          ?? only replaces null/undefined, preserving valid falsy
+  //          values like 0 (count) and '' (empty string).
+  // EXAMPLE:
+  //   WRONG:
+  //     const count = data.count || 10; // 0 becomes 10!
+  //   RIGHT:
+  //     const count = data.count ?? 10; // 0 stays 0
+  // ─────────────────────────────────────────
   {
     id: 'prefer-nullish-coalescing',
     label: 'Use nullish coalescing (??)',
@@ -522,6 +872,24 @@ const reactRules: Rule[] = [
     category: 'Modern Syntax',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-error-boundary-usage
+  // ROLE: Recommend error boundaries for crash prevention
+  // PURPOSE: Without error boundaries, a single thrown error crashes
+  //          the entire React app. Error boundaries catch render errors
+  //          and display fallback UI instead.
+  // EXAMPLE:
+  //   WRONG:
+  //     <App>
+  //       <BuggyComponent /> {/* Crash kills entire app */}
+  //     </App>
+  //   RIGHT:
+  //     <App>
+  //       <ErrorBoundary fallback={<ErrorPage />}>
+  //         <BuggyComponent /> {/* Crash is contained */}
+  //       </ErrorBoundary>
+  //     </App>
+  // ─────────────────────────────────────────
   {
     id: 'react-error-boundary-usage',
     label: 'Consider error boundaries',
@@ -534,6 +902,19 @@ const reactRules: Rule[] = [
     category: 'Error Handling',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: no-sync-external-calls
+  // ROLE: Block synchronous external API calls
+  // PURPOSE: Synchronous fetch/XHR blocks the main thread, freezing
+  //          the UI completely. Always use async/await for API calls,
+  //          file operations, and external services.
+  // EXAMPLE:
+  //   WRONG:
+  //     const data = fetch('/api/data'); // No await!
+  //   RIGHT:
+  //     const data = await fetch('/api/data');
+  //     const json = await data.json();
+  // ─────────────────────────────────────────
   {
     id: 'no-sync-external-calls',
     label: 'Avoid synchronous external calls',
@@ -546,6 +927,18 @@ const reactRules: Rule[] = [
     category: 'Async Patterns',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: react-prefer-controlled-inputs
+  // ROLE: Recommend controlled components over uncontrolled
+  // PURPOSE: Controlled components (value + onChange) keep React as the
+  //          single source of truth. Uncontrolled (defaultValue + ref)
+  //          creates two sources of truth and makes validation harder.
+  // EXAMPLE:
+  //   WRONG:
+  //     <input defaultValue="hello" ref={inputRef} />
+  //   RIGHT:
+  //     <input value={name} onChange={(e) => setName(e.target.value)} />
+  // ─────────────────────────────────────────
   {
     id: 'react-prefer-controlled-inputs',
     label: 'Prefer controlled components',
@@ -560,6 +953,23 @@ const reactRules: Rule[] = [
 
   // NOTE: 'no-index-as-key' removed — covered by ESLint 'react/no-array-index-key' rule
 
+  // ─────────────────────────────────────────
+  // RULE: react-cleanup-effects
+  // ROLE: Enforce cleanup functions in side-effect hooks
+  // PURPOSE: useEffect with subscriptions, timers, or event listeners
+  //          must return a cleanup function. Without it, listeners
+  //          accumulate on every re-render, causing memory leaks.
+  // EXAMPLE:
+  //   WRONG:
+  //     useEffect(() => {
+  //       window.addEventListener('resize', handleResize);
+  //     }, []);
+  //   RIGHT:
+  //     useEffect(() => {
+  //       window.addEventListener('resize', handleResize);
+  //       return () => window.removeEventListener('resize', handleResize);
+  //     }, []);
+  // ─────────────────────────────────────────
   {
     id: 'react-cleanup-effects',
     label: 'Cleanup side effects',
@@ -572,6 +982,20 @@ const reactRules: Rule[] = [
     category: 'Memory Management',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: prefer-const-assertion
+  // ROLE: Recommend const assertions for literal types
+  // PURPOSE: "as const" narrows types to literal values and makes
+  //          objects/arrays readonly, improving type safety and
+  //          enabling discriminated unions.
+  // EXAMPLE:
+  //   WRONG:
+  //     const ROLES: string[] = ['admin', 'user', 'viewer'];
+  //     // Type: string[] — loses literal type info
+  //   RIGHT:
+  //     const ROLES = ['admin', 'user', 'viewer'] as const;
+  //     // Type: readonly ['admin', 'user', 'viewer']
+  // ─────────────────────────────────────────
   {
     id: 'prefer-const-assertion',
     label: 'Use const assertions for literal types',