@codyswann/lisa 1.0.0

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

@@ -0,0 +1,157 @@
+/**
+ * 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);
+        }
+      },
+    };
+  },
+};

package/expo/copy-overwrite/.claude/skills/apollo-client/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: apollo-client
+description: This skill should be used when writing or modifying GraphQL operations, hooks, or mutations using Apollo Client 3.10. It enforces best practices for optimistic responses, cache updates, and TypeScript type generation. Use this skill when creating new queries/mutations, reviewing Apollo code, or troubleshooting cache issues.
+---
+
+# Apollo Client 3.10
+
+## Overview
+
+This skill provides best practices for Apollo Client 3.10 in this codebase, ensuring consistent patterns for GraphQL operations, optimistic UI updates, cache management, and TypeScript type safety.
+
+## Quick Reference
+
+### Generator Commands
+
+After modifying any `operations.graphql` file, run the appropriate generator:
+
+```bash
+bun run generate:types:dev        # Development environment
+bun run generate:types:staging    # Staging environment
+bun run generate:types:production # Production environment
+```
+
+> **Note:** Replace `bun` with your project's package manager (`npm`, `yarn`, `pnpm`) as needed.
+
+### Import Pattern
+
+All GraphQL types, hooks, and documents must come from generated types:
+
+```typescript
+import {
+  useGetPlayerQuery,
+  useUpdatePlayerMutation,
+  GetPlayerQuery,
+  PlayerFragment,
+  ListPlayersDocument,
+} from "@/generated/graphql";
+```
+
+## Core Rules
+
+### 1. Only Use Generated Types
+
+Import all GraphQL-related types from `@/generated/graphql`. Never define manual TypeScript types for GraphQL entities.
+
+```typescript
+// CORRECT
+import { PlayerFragment, useUpdatePlayerMutation } from "@/generated/graphql";
+
+// INCORRECT - Never do this
+type Player = { id: string; name: string };
+```
+
+### 2. Never Modify Generated Files
+
+The `generated/graphql.ts` file is auto-generated by codegen. To change types:
+
+1. Edit the appropriate `operations.graphql` file in the feature directory
+2. Run `bun run generate:types:dev`
+3. Import the newly generated types
+
+### 3. Always Run Generator After Schema Changes
+
+After modifying any `operations.graphql` file, immediately run the generator before committing. Verify changes compile with `bun run typecheck`.
+
+### 4. Always Include Optimistic Response
+
+Every mutation must include an `optimisticResponse` for instant UI feedback:
+
+```typescript
+const [updatePlayer] = useUpdatePlayerMutation({
+  optimisticResponse: variables => ({
+    __typename: "Mutation",
+    updatePlayer: {
+      __typename: "Player",
+      id: variables.id,
+      name: variables.input.name,
+      updatedAt: new Date().toISOString(),
+    },
+  }),
+});
+```
+
+Key requirements:
+
+- Always include `__typename` for every object in the response
+- Always include `id` for cache normalization
+- Use temporary IDs for new objects (e.g., `crypto.randomUUID()`)
+- Include all fields that the mutation returns
+
+### 5. Always Update Cache
+
+Every mutation must handle cache updates using one of these strategies:
+
+**Automatic Updates** - When mutation returns the full entity with `id` and `__typename`, Apollo updates automatically. No extra code needed.
+
+**cache.modify** - For adding/removing items from lists:
+
+```typescript
+const [addPlayer] = useAddPlayerMutation({
+  optimisticResponse: {
+    /* ... */
+  },
+  update(cache, { data }) {
+    cache.modify({
+      fields: {
+        players(existingPlayers = [], { readField }) {
+          const newRef = cache.writeFragment({
+            data: data.addPlayer,
+            fragment: PlayerFragmentDoc,
+          });
+          return [...existingPlayers, newRef];
+        },
+      },
+    });
+  },
+});
+```
+
+**refetchQueries** - Fallback for complex scenarios:
+
+```typescript
+const [complexMutation] = useComplexMutation({
+  refetchQueries: ["ListPlayers"],
+  awaitRefetchQueries: true,
+});
+```
+
+## Operations.graphql Structure
+
+### Fragment-First Pattern
+
+Define fragments before queries/mutations that use them:
+
+```graphql
+# 1. Fragments first
+fragment PlayerFragment on Player {
+  id
+  knownName
+  firstName
+  lastName
+  team {
+    id
+    name
+  }
+}
+
+# 2. Queries second
+query GetPlayer($id: ID!) {
+  player(id: $id) {
+    ...PlayerFragment
+  }
+}
+
+# 3. Mutations last
+mutation UpdatePlayer($id: ID!, $input: UpdatePlayerInput!) {
+  updatePlayer(id: $id, input: $input) {
+    ...PlayerFragment
+  }
+}
+```
+
+### Include Required Fields
+
+Mutations must return all fields needed for cache updates:
+
+```graphql
+mutation AddPlayerToKanban($input: AddPlayerToKanbanInput!) {
+  addPlayerToKanban(input: $input) {
+    id # Required for cache normalization
+    position
+    notes
+    kanbanPhaseId
+    kanbanPhase {
+      # Include related objects
+      id
+      name
+    }
+    createdAt
+    updatedAt
+  }
+}
+```
+
+## Query Best Practices
+
+### Fetch Policies
+
+```typescript
+// Frequently changing data - balance speed and freshness
+fetchPolicy: "cache-and-network";
+
+// Stable reference data - prioritize cache
+fetchPolicy: "cache-first";
+
+// Always-fresh data - skip cache
+fetchPolicy: "network-only";
+```
+
+### Skip When Variables Undefined
+
+```typescript
+const { data } = useGetPlayerQuery({
+  variables: { id: playerId! },
+  skip: !playerId,
+});
+```
+
+### Error Handling
+
+Use `onError` callback instead of try/catch with console.log:
+
+```typescript
+const [mutation] = useMutation(MUTATION, {
+  onError: error => {
+    setErrorState("Failed to update. Please try again.");
+  },
+});
+```
+
+## Complete Mutation Pattern
+
+Reference `references/mutation-patterns.md` for comprehensive examples of the complete mutation pattern including optimistic responses, cache updates, and error handling.
+
+## Validation Checklist
+
+When writing or reviewing Apollo code, verify:
+
+- [ ] All types imported from `@/generated/graphql`
+- [ ] No manual type definitions for GraphQL entities
+- [ ] Every mutation has `optimisticResponse`
+- [ ] Every mutation has cache update strategy
+- [ ] `__typename` included in all optimistic response objects
+- [ ] `id` included in all optimistic response objects
+- [ ] Queries use appropriate `fetchPolicy`
+- [ ] Queries use `skip` when variables may be undefined
+- [ ] Error handling via `onError` callback
+- [ ] Generator was run after operations.graphql changes