@codyswann/lisa 1.0.0

package/eslint-plugin-code-organization/README.md

@@ -0,0 +1,149 @@
+# eslint-plugin-code-organization
+
+ESLint plugin to enforce code organization standards for the PropSwap frontend application.
+
+## Rules
+
+### `enforce-statement-order`
+
+Enforces the standard statement order in all functions:
+
+1. **Definitions** - Variable declarations (`const`, `let`, `var`) and function declarations
+2. **Side effects** - Expression statements that are function calls
+3. **Return statement** - Final return
+
+This rule applies to all functions: React components, hooks, utilities, and plain JavaScript functions.
+
+**Examples:**
+
+❌ Incorrect - side effect before definition:
+
+```javascript
+function process() {
+  initialize(); // Side effect
+  const config = getConfig(); // Definition after side effect - WRONG
+  return config;
+}
+```
+
+❌ Incorrect - definition after side effect (React):
+
+```typescript
+const useExample = () => {
+  useEffect(() => {}, []); // Side effect
+
+  const data = useMemo(() => [], []); // Definition after side effect - WRONG
+
+  return data;
+};
+```
+
+✅ Correct - Proper order:
+
+```javascript
+function process() {
+  // 1. Definitions
+  const config = getConfig();
+  const options = { debug: true };
+
+  // 2. Side effects
+  initialize();
+  logger.info("starting");
+
+  // 3. Return
+  return config;
+}
+```
+
+✅ Correct - React hook with proper order:
+
+```typescript
+const useExample = () => {
+  // 1. Definitions
+  const [state, setState] = useState(null);
+  const data = useMemo(() => [], []);
+  const handleClick = useCallback(() => {}, []);
+
+  // 2. Side effects
+  useEffect(() => {}, []);
+
+  // 3. Return
+  return data;
+};
+```
+
+## Installation
+
+This plugin is installed locally as a file dependency:
+
+```json
+{
+  "devDependencies": {
+    "eslint-plugin-code-organization": "file:./eslint-plugin-code-organization"
+  }
+}
+```
+
+## Usage
+
+### ESLint 9 Flat Config (Recommended)
+
+```javascript
+// eslint.config.mjs
+import codeOrganizationPlugin from './eslint-plugin-code-organization/index.js';
+
+export default [
+  {
+    plugins: {
+      'code-organization': codeOrganizationPlugin,
+    },
+    rules: {
+      'code-organization/enforce-statement-order': 'error',
+    },
+  },
+];
+```
+
+### Legacy Config (.eslintrc.json)
+
+```json
+{
+  "plugins": ["code-organization"],
+  "rules": {
+    "code-organization/enforce-statement-order": "error"
+  }
+}
+```
+
+## Special Cases
+
+### Guard Clauses
+
+If statements (often used for early returns/guard clauses) are intentionally excluded from this rule. They can appear anywhere in the function:
+
+```typescript
+function processUser(userId: string) {
+  // Guard clause - allowed anywhere
+  if (!userId) {
+    return null;
+  }
+
+  const user = getUser(userId);
+  validateUser(user);
+  return user;
+}
+```
+
+### React Hooks
+
+For React hooks, the definitions category includes:
+- `useState`, `useRef`, `useMemo`, `useCallback` (return values to variables)
+- Any hook that returns a value assigned to a variable
+
+Side effects include:
+- `useEffect`, `useLayoutEffect` (no return value used)
+- Any expression statement with function calls
+
+## Version
+
+1.0.0

package/eslint-plugin-code-organization/__tests__/enforce-statement-order.test.js

@@ -0,0 +1,468 @@
+/* eslint-disable max-lines -- comprehensive test coverage requires extensive test cases */
+/**
+ * Tests for enforce-statement-order ESLint rule
+ *
+ * Enforces the order: definitions → side effects → return
+ * 1. Definitions: const/let/var declarations, function declarations
+ * 2. Side effects: Expression statements that are function calls
+ * 3. Return statement
+ */
+const { RuleTester } = require("eslint");
+
+const rule = require("../rules/enforce-statement-order");
+
+/** Message data constants for test assertions */
+const DEFINITIONS = "Definitions";
+const SIDE_EFFECTS = "Side effects";
+const RETURN_STATEMENT = "Return statement";
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2020,
+    sourceType: "module",
+    parserOptions: {
+      ecmaFeatures: {
+        jsx: true,
+      },
+    },
+  },
+});
+
+ruleTester.run("enforce-statement-order", rule, {
+  valid: [
+    // ===== BASIC PATTERNS =====
+
+    // Correct order: definitions → side effects → return
+    {
+      code: `
+        function example() {
+          const x = 1;
+          doSomething();
+          return x;
+        }
+      `,
+    },
+
+    // Definitions only (no side effects)
+    {
+      code: `
+        function example() {
+          const x = 1;
+          const y = 2;
+          return x + y;
+        }
+      `,
+    },
+
+    // Multiple side effects in correct position
+    {
+      code: `
+        function example() {
+          const x = 1;
+          doSomething();
+          doSomethingElse();
+          logger.info("done");
+          return x;
+        }
+      `,
+    },
+
+    // Function declaration followed by side effect
+    {
+      code: `
+        function example() {
+          const x = 1;
+          function helper() {}
+          doSomething();
+          return x;
+        }
+      `,
+    },
+
+    // No return statement (void function)
+    {
+      code: `
+        function example() {
+          const x = 1;
+          doSomething();
+        }
+      `,
+    },
+
+    // Only side effects (no definitions, no return)
+    {
+      code: `
+        function example() {
+          doSomething();
+          doSomethingElse();
+        }
+      `,
+    },
+
+    // ===== REACT PATTERNS =====
+
+    // React hook with correct order
+    {
+      code: `
+        const useExample = () => {
+          const [state, setState] = useState(null);
+          const data = useMemo(() => [], []);
+          const handleClick = useCallback(() => {}, []);
+
+          useEffect(() => {}, []);
+
+          return data;
+        };
+      `,
+    },
+
+    // React component with correct order
+    {
+      code: `
+        const MyComponent = () => {
+          const [state, setState] = useState(null);
+          const data = useMemo(() => [], []);
+
+          useEffect(() => {}, []);
+          logRender();
+
+          return <div>{data}</div>;
+        };
+      `,
+    },
+
+    // React component function declaration
+    {
+      code: `
+        function MyComponent() {
+          const [state, setState] = useState(null);
+          const handleClick = useCallback(() => {}, []);
+
+          useEffect(() => {}, []);
+
+          return <div />;
+        }
+      `,
+    },
+
+    // Early return pattern after side effects is valid
+    {
+      code: `
+        const MyComponent = () => {
+          const [loading, setLoading] = useState(true);
+
+          useEffect(() => {}, []);
+
+          if (loading) return null;
+
+          return <div />;
+        };
+      `,
+    },
+
+    // Early return with block statement after side effects
+    {
+      code: `
+        const MyComponent = () => {
+          const data = useMemo(() => [], []);
+
+          useEffect(() => {}, []);
+
+          if (!data) {
+            return null;
+          }
+
+          return <div />;
+        };
+      `,
+    },
+
+    // ===== ARROW FUNCTIONS =====
+
+    // Arrow function with correct order
+    {
+      code: `
+        const process = () => {
+          const config = getConfig();
+          initialize();
+          return config;
+        };
+      `,
+    },
+
+    // ===== EDGE CASES =====
+
+    // Empty function
+    {
+      code: `
+        function empty() {}
+      `,
+    },
+
+    // Only return
+    {
+      code: `
+        function getValue() {
+          return 42;
+        }
+      `,
+    },
+
+    // Nested functions are checked independently
+    {
+      code: `
+        function outer() {
+          const x = 1;
+          const inner = () => {
+            const y = 2;
+            doSomething();
+            return y;
+          };
+          doSomething();
+          return x;
+        }
+      `,
+    },
+  ],
+
+  invalid: [
+    // ===== BASIC VIOLATIONS =====
+
+    // Definition after side effect
+    {
+      code: `
+        function example() {
+          doSomething();
+          const x = 1;
+          return x;
+        }
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: SIDE_EFFECTS,
+          },
+        },
+      ],
+    },
+
+    // Side effect after return
+    {
+      code: `
+        function example() {
+          const x = 1;
+          return x;
+          doSomething();
+        }
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: SIDE_EFFECTS,
+            previous: RETURN_STATEMENT,
+          },
+        },
+      ],
+    },
+
+    // Definition after return
+    {
+      code: `
+        function example() {
+          return 1;
+          const x = 2;
+        }
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: RETURN_STATEMENT,
+          },
+        },
+      ],
+    },
+
+    // Multiple violations
+    {
+      code: `
+        function example() {
+          doSomething();
+          const x = 1;
+          return x;
+          const y = 2;
+        }
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: SIDE_EFFECTS,
+          },
+        },
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: RETURN_STATEMENT,
+          },
+        },
+      ],
+    },
+
+    // ===== NON-REACT VIOLATIONS =====
+
+    // Plain function call before definition
+    {
+      code: `
+        function process() {
+          initialize();
+          const config = {};
+          return config;
+        }
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: SIDE_EFFECTS,
+          },
+        },
+      ],
+    },
+
+    // Logger call before definition
+    {
+      code: `
+        function getData() {
+          logger.info("fetching");
+          const data = fetch();
+          return data;
+        }
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: SIDE_EFFECTS,
+          },
+        },
+      ],
+    },
+
+    // Console.log before definition
+    {
+      code: `
+        function debug() {
+          console.log("starting");
+          const value = compute();
+          return value;
+        }
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: SIDE_EFFECTS,
+          },
+        },
+      ],
+    },
+
+    // ===== REACT VIOLATIONS =====
+
+    // Variable after useEffect
+    {
+      code: `
+        const useExample = () => {
+          useEffect(() => {}, []);
+          const data = useMemo(() => [], []);
+          return data;
+        };
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: SIDE_EFFECTS,
+          },
+        },
+      ],
+    },
+
+    // useCallback after useEffect
+    {
+      code: `
+        const MyComponent = () => {
+          const [state, setState] = useState(null);
+          useEffect(() => {}, []);
+          const handleClick = useCallback(() => {}, []);
+          return <div />;
+        };
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: SIDE_EFFECTS,
+          },
+        },
+      ],
+    },
+
+    // Function declaration after side effect
+    {
+      code: `
+        function MyComponent() {
+          useEffect(() => {}, []);
+          function handleClick() {}
+          return <div />;
+        }
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: SIDE_EFFECTS,
+          },
+        },
+      ],
+    },
+
+    // ===== ARROW FUNCTION VIOLATIONS =====
+
+    // Arrow function with side effect before definition
+    {
+      code: `
+        const process = () => {
+          initialize();
+          const config = getConfig();
+          return config;
+        };
+      `,
+      errors: [
+        {
+          messageId: "wrongOrder",
+          data: {
+            current: DEFINITIONS,
+            previous: SIDE_EFFECTS,
+          },
+        },
+      ],
+    },
+  ],
+});
+
+console.log("All enforce-statement-order tests passed!");
+/* eslint-enable max-lines -- comprehensive test coverage requires extensive test cases */

package/eslint-plugin-code-organization/index.js

@@ -0,0 +1,23 @@
+/**
+ * ESLint plugin for code organization standards
+ *
+ * This plugin enforces code organization patterns for all functions
+ * in the frontend application. Supports ESLint 9 flat config format.
+ *
+ * Rules:
+ * - enforce-statement-order: Ensures statements follow the order (definitions -> side effects -> return)
+ * @module eslint-plugin-code-organization
+ */
+const enforceStatementOrder = require("./rules/enforce-statement-order");
+
+const plugin = {
+  meta: {
+    name: "eslint-plugin-code-organization",
+    version: "1.0.0",
+  },
+  rules: {
+    "enforce-statement-order": enforceStatementOrder,
+  },
+};
+
+module.exports = plugin;

package/eslint-plugin-code-organization/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "eslint-plugin-code-organization",
+  "version": "1.0.0",
+  "description": "ESLint plugin to enforce code organization standards",
+  "main": "index.js",
+  "private": true,
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  }
+}