@codyswann/lisa 1.50.1 → 1.50.3

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

@@ -0,0 +1,473 @@
+/**
+ * This file is managed by Lisa.
+ * Do not edit directly — changes will be overwritten on the next `lisa` run.
+ */
+
+/* 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,28 @@
+/**
+ * This file is managed by Lisa.
+ * Do not edit directly — changes will be overwritten on the next `lisa` run.
+ */
+
+/**
+ * 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": "@codyswann/eslint-plugin-code-organization",
+  "version": "1.0.0",
+  "description": "ESLint plugin to enforce code organization standards",
+  "main": "index.js",
+  "publishConfig": { "access": "public" },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  }
+}

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

@@ -0,0 +1,162 @@
+/**
+ * This file is managed by Lisa.
+ * Do not edit directly — changes will be overwritten on the next `lisa` run.
+ */
+
+/**
+ * ESLint rule to enforce statement order in all functions
+ *
+ * Enforces the following order:
+ * 1. Definitions: Variable declarations (const/let/var) and function declarations
+ * 2. Side effects: Expression statements that are function calls
+ * 3. Return statement
+ *
+ * Applies to all functions: hooks, components, utilities, etc.
+ * @type {import('eslint').Rule.RuleModule}
+ */
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Enforce statement order: definitions → side effects → return",
+      category: "Best Practices",
+      recommended: true,
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      wrongOrder:
+        "{{current}} should come before {{previous}}. Expected order: definitions → side effects → return statement",
+    },
+  },
+
+  create(context) {
+    const ORDER = {
+      DEFINITION: 1, // Variable declarations, function declarations
+      SIDE_EFFECT: 2, // Expression statements with function calls
+      RETURN: 3, // Return statement
+    };
+
+    const ORDER_NAMES = {
+      [ORDER.DEFINITION]: "Definitions",
+      [ORDER.SIDE_EFFECT]: "Side effects",
+      [ORDER.RETURN]: "Return statement",
+    };
+
+    /**
+     * Checks if an expression statement is a function call (side effect)
+     * @param {import('eslint').Rule.Node} statement - AST node
+     * @returns {boolean} True if this is a function call expression
+     */
+    function isFunctionCallExpression(statement) {
+      if (statement.type !== "ExpressionStatement") {
+        return false;
+      }
+
+      const expression = statement.expression;
+
+      // Direct call: doSomething() or object.method()
+      if (expression.type === "CallExpression") {
+        return true;
+      }
+
+      return false;
+    }
+
+    /**
+     * Determines the order category of a statement
+     * Guard clauses (if statements with early returns) are ignored and don't
+     * affect order validation - they can appear anywhere in the function.
+     * @param {import('eslint').Rule.Node} statement - AST node
+     * @returns {number|null} Order category value, or null to skip this statement
+     */
+    function getStatementOrder(statement) {
+      // Bare return statement (not in an if block)
+      if (statement.type === "ReturnStatement") {
+        return ORDER.RETURN;
+      }
+
+      // If statements are ignored - they may contain guard clauses (early returns)
+      // which are valid at any position in the function
+      if (statement.type === "IfStatement") {
+        return null;
+      }
+
+      // Variable declarations are definitions
+      if (statement.type === "VariableDeclaration") {
+        return ORDER.DEFINITION;
+      }
+
+      // Function declarations are definitions
+      if (statement.type === "FunctionDeclaration") {
+        return ORDER.DEFINITION;
+      }
+
+      // Expression statements with function calls are side effects
+      if (isFunctionCallExpression(statement)) {
+        return ORDER.SIDE_EFFECT;
+      }
+
+      // Default to null for other statements (they don't affect order)
+      return null;
+    }
+
+    /**
+     * Checks if a function body follows the correct statement order
+     * @param {import('eslint').Rule.Node} node - Function node
+     */
+    function checkBodyOrder(node) {
+      if (!node.body || node.body.type !== "BlockStatement") {
+        return;
+      }
+
+      const statements = node.body.body;
+      // eslint-disable-next-line functional/no-let -- ESLint plugin requires mutable tracking variable for order validation
+      let maxOrderSeen = 0;
+
+      statements.forEach(statement => {
+        const currentOrder = getStatementOrder(statement);
+
+        // Skip statements that don't affect order (e.g., if statements)
+        if (currentOrder === null) {
+          return;
+        }
+
+        if (currentOrder < maxOrderSeen) {
+          context.report({
+            node: statement,
+            messageId: "wrongOrder",
+            data: {
+              current: ORDER_NAMES[currentOrder],
+              previous: ORDER_NAMES[maxOrderSeen],
+            },
+          });
+        }
+
+        // Track the highest order we've seen so far
+        if (currentOrder > maxOrderSeen) {
+          maxOrderSeen = currentOrder;
+        }
+      });
+    }
+
+    return {
+      // Check all function declarations
+      FunctionDeclaration(node) {
+        checkBodyOrder(node);
+      },
+
+      // Check all arrow functions and function expressions assigned to variables
+      VariableDeclarator(node) {
+        if (
+          node.init &&
+          (node.init.type === "ArrowFunctionExpression" ||
+            node.init.type === "FunctionExpression")
+        ) {
+          checkBodyOrder(node.init);
+        }
+      },
+    };
+  },
+};