@codyswann/lisa 1.0.0

package/all/copy-overwrite/.claude/skills/coding-philosophy/references/function-structure.md

@@ -0,0 +1,416 @@
+# Function Structure Reference
+
+This document defines the required ordering of statements within functions, hooks, and components.
+
+## The Three Sections
+
+Every function body follows this order:
+
+```
+1. VARIABLES & STATE
+   - Variable declarations (const)
+   - useState hooks
+   - useQuery/useMutation hooks
+   - useMemo computations
+   - useCallback handlers
+   - Regular function definitions
+
+2. SIDE EFFECTS
+   - useEffect hooks
+   - Function calls with no return value
+
+3. RETURN
+   - Return statement (always last)
+```
+
+## ESLint Enforcement
+
+This ordering is enforced by the `code-organization/enforce-hook-order` ESLint rule.
+
+```
+Expected order: variables/state/functions → useEffects → return statement
+```
+
+## Hook Structure
+
+### Complete Example
+
+```typescript
+export const usePlayerData = (playerId: string): UsePlayerDataReturn => {
+  // ========================================
+  // 1. VARIABLES & STATE
+  // ========================================
+
+  // UI state
+  const [isExpanded, setIsExpanded] = useState(false);
+  const [searchQuery, setSearchQuery] = useState("");
+
+  // External hooks
+  const { colors } = useTheme();
+  const router = useRouter();
+
+  // GraphQL queries
+  const { data, loading, refetch } = useQuery(GetPlayerDocument, {
+    variables: { playerId },
+    skip: !playerId,
+  });
+
+  // Derived state with useMemo
+  const playerName = useMemo(
+    () => data?.player?.name ?? "Unknown",
+    [data?.player?.name]
+  );
+
+  const filteredStats = useMemo(
+    () => data?.stats?.filter(s => s.name.includes(searchQuery)) ?? [],
+    [data?.stats, searchQuery]
+  );
+
+  // Handlers with useCallback
+  const handleRefresh = useCallback(() => {
+    refetch();
+  }, [refetch]);
+
+  const handleNavigate = useCallback(() => {
+    if (!playerId) {
+      console.error("Cannot navigate: player ID is missing");
+      return;
+    }
+    router.push(`/players/${playerId}/details`);
+  }, [playerId, router]);
+
+  // Helper functions (defined as const arrow functions or regular functions)
+  const formatPlayerLabel = (name: string, position: string): string => {
+    return `${name} (${position})`;
+  };
+
+  // ========================================
+  // 2. SIDE EFFECTS
+  // ========================================
+
+  useEffect(() => {
+    console.log("Player loaded:", playerName);
+  }, [playerName]);
+
+  useEffect(() => {
+    if (data?.player) {
+      trackAnalytics("player_viewed", { playerId });
+    }
+  }, [data?.player, playerId]);
+
+  // ========================================
+  // 3. RETURN
+  // ========================================
+
+  return {
+    playerName,
+    filteredStats,
+    isExpanded,
+    loading,
+    handleRefresh,
+    handleNavigate,
+    formatPlayerLabel,
+    setIsExpanded,
+    setSearchQuery,
+  };
+};
+```
+
+## Container Component Structure
+
+### Complete Example
+
+```typescript
+const PlayerCardContainer: React.FC<PlayerCardContainerProps> = ({
+  playerId,
+  onPress,
+  showDetails = false,
+}) => {
+  // ========================================
+  // 1. VARIABLES & STATE
+  // ========================================
+
+  // Theme and styling
+  const { colors } = useTheme();
+  const { width } = useWindowDimensions();
+  const isDark = useColorScheme() === "dark";
+
+  // Local state
+  const [isHovered, setIsHovered] = useState(false);
+
+  // Data fetching
+  const { data, loading, error } = useQuery(GetPlayerDocument, {
+    variables: { playerId },
+  });
+
+  // Derived values
+  const player = data?.player;
+
+  const cardStyle = useMemo(
+    () => ({
+      backgroundColor: isDark ? colors.cardDark : colors.cardLight,
+      maxWidth: width > 768 ? 400 : width - 32,
+    }),
+    [isDark, colors, width]
+  );
+
+  const formattedStats = useMemo(
+    () => player?.stats?.map(s => ({
+      ...s,
+      displayValue: formatStatValue(s.value, s.type),
+    })) ?? [],
+    [player?.stats]
+  );
+
+  // Handlers
+  const handlePress = useCallback(() => {
+    if (!playerId) {
+      console.error("Cannot navigate: player ID is missing");
+      return;
+    }
+    onPress?.(playerId);
+  }, [playerId, onPress]);
+
+  const handleHoverIn = useCallback(() => {
+    setIsHovered(true);
+  }, []);
+
+  const handleHoverOut = useCallback(() => {
+    setIsHovered(false);
+  }, []);
+
+  // ========================================
+  // 2. SIDE EFFECTS
+  // ========================================
+
+  useEffect(() => {
+    if (player) {
+      console.log("Player card rendered:", player.name);
+    }
+  }, [player]);
+
+  // ========================================
+  // 3. RETURN
+  // ========================================
+
+  // Early returns are acceptable after side effects
+  if (loading) {
+    return <LoadingSkeleton />;
+  }
+
+  if (error) {
+    return <ErrorCard message={error.message} />;
+  }
+
+  return (
+    <PlayerCardView
+      player={player}
+      stats={formattedStats}
+      cardStyle={cardStyle}
+      isHovered={isHovered}
+      showDetails={showDetails}
+      onPress={handlePress}
+      onHoverIn={handleHoverIn}
+      onHoverOut={handleHoverOut}
+    />
+  );
+};
+```
+
+## Utility Function Structure
+
+### Pure Function Example
+
+```typescript
+export const calculateTeamRankings = (
+  players: readonly Player[],
+  teamId: string
+): TeamRanking => {
+  // ========================================
+  // 1. VARIABLES & DERIVED VALUES
+  // ========================================
+
+  const validPlayers = players.filter(p => p.team && p.score != null);
+
+  const teamScores = validPlayers.reduce(
+    (acc, player) => {
+      const id = player.team.id;
+      const existing = acc[id];
+      return {
+        ...acc,
+        [id]: {
+          teamId: id,
+          totalScore: (existing?.totalScore ?? 0) + player.score,
+          count: (existing?.count ?? 0) + 1,
+        },
+      };
+    },
+    {} as Record<string, { teamId: string; totalScore: number; count: number }>
+  );
+
+  const rankings = Object.values(teamScores).map(t => ({
+    teamId: t.teamId,
+    avgScore: t.totalScore / t.count,
+  }));
+
+  const sorted = [...rankings].sort((a, b) => b.avgScore - a.avgScore);
+
+  const targetRank = sorted.findIndex(r => r.teamId === teamId) + 1;
+
+  // ========================================
+  // 2. NO SIDE EFFECTS IN PURE FUNCTIONS
+  // ========================================
+
+  // ========================================
+  // 3. RETURN
+  // ========================================
+
+  return {
+    rank: targetRank || null,
+    totalTeams: sorted.length,
+    avgScore: teamScores[teamId]?.totalScore / teamScores[teamId]?.count ?? 0,
+  };
+};
+```
+
+## Helper Function Extraction
+
+When reducing cognitive complexity, extract helper functions and place them between types and the main component.
+
+### File Structure
+
+```typescript
+// ========================================
+// TYPES
+// ========================================
+
+interface Props {
+  readonly players: readonly Player[];
+  readonly isDark: boolean;
+}
+
+// ========================================
+// HELPER FUNCTIONS
+// ========================================
+
+/**
+ * Renders the loading skeleton state.
+ * @param props - Component properties
+ * @param props.isDark - Whether dark mode is active
+ * @returns Loading skeleton UI
+ */
+function renderLoadingState(props: { readonly isDark: boolean }) {
+  const { isDark } = props;
+  return <LoadingSkeleton isDark={isDark} />;
+}
+
+/**
+ * Renders the empty state when no players exist.
+ * @param props - Component properties
+ * @param props.message - Message to display
+ * @returns Empty state UI
+ */
+function renderEmptyState(props: { readonly message: string }) {
+  const { message } = props;
+  return <EmptyState message={message} />;
+}
+
+// ========================================
+// MAIN COMPONENT
+// ========================================
+
+export const PlayerListView = memo(function PlayerListView({
+  players,
+  isDark,
+}: Props) {
+  if (!players.length) {
+    return renderEmptyState({ message: "No players found" });
+  }
+
+  return (
+    <Box>
+      {players.map(player => (
+        <PlayerCard key={player.id} player={player} />
+      ))}
+    </Box>
+  );
+});
+```
+
+## Common Mistakes
+
+### Wrong: useEffect Before useMemo
+
+```typescript
+// WRONG
+useEffect(() => {
+  console.log("Value:", computedValue);
+}, [computedValue]);
+
+const computedValue = useMemo(() => calculate(data), [data]);
+
+// CORRECT
+const computedValue = useMemo(() => calculate(data), [data]);
+
+useEffect(() => {
+  console.log("Value:", computedValue);
+}, [computedValue]);
+```
+
+### Wrong: Return Before useEffect
+
+```typescript
+// WRONG
+const Component = () => {
+  const data = useData();
+
+  if (!data) {
+    return null; // Early return before useEffect!
+  }
+
+  useEffect(() => {
+    // This breaks the rules of hooks
+  }, []);
+
+  return <View />;
+};
+
+// CORRECT
+const Component = () => {
+  const data = useData();
+
+  useEffect(() => {
+    if (data) {
+      // Handle data
+    }
+  }, [data]);
+
+  if (!data) {
+    return null;
+  }
+
+  return <View />;
+};
+```
+
+### Wrong: Handler Definition After useEffect
+
+```typescript
+// WRONG
+useEffect(() => {
+  handleInit();
+}, [handleInit]);
+
+const handleInit = useCallback(() => {
+  // ...
+}, []);
+
+// CORRECT
+const handleInit = useCallback(() => {
+  // ...
+}, []);
+
+useEffect(() => {
+  handleInit();
+}, [handleInit]);
+```

package/all/copy-overwrite/.claude/skills/coding-philosophy/references/immutable-patterns.md

@@ -0,0 +1,316 @@
+# Immutable Patterns Reference
+
+This document provides comprehensive examples of immutable patterns used in this codebase.
+
+## Building Lookup Objects with Reduce
+
+### Basic Pattern
+
+```typescript
+const colorMap =
+  edges?.reduce(
+    (acc, edge) => (edge.color ? { ...acc, [edge.tagId]: edge.color } : acc),
+    {} as Record<string, string>
+  ) ?? {};
+```
+
+### With Null Safety
+
+```typescript
+const boardColorMap =
+  data?.edges?.reduce(
+    (acc, edge) => (edge.color ? { ...acc, [edge.tagId]: edge.color } : acc),
+    {} as Record<string, string>
+  ) ?? {};
+```
+
+### Accumulating Multiple Properties
+
+```typescript
+const teamGprAccumulator = validPlayers.reduce(
+  (acc, player) => {
+    const teamId = player.team?.id;
+    if (!teamId) return acc;
+
+    const existing = acc[teamId];
+    return {
+      ...acc,
+      [teamId]: {
+        teamId,
+        teamName: player.team.name,
+        gprSum: (existing?.gprSum ?? 0) + player.gpr,
+        playerCount: (existing?.playerCount ?? 0) + 1,
+      },
+    };
+  },
+  {} as Record<
+    string,
+    { teamId: string; teamName: string; gprSum: number; playerCount: number }
+  >
+);
+```
+
+### With Parallel Array Lookups (using index)
+
+```typescript
+const formattedMetricsMap = useMemo(
+  () =>
+    metrics.reduce(
+      (acc, metric, index) => ({
+        ...acc,
+        [metric.displayName]: formattedMetrics[index],
+      }),
+      {} as Record<string, ICompositeMetric>
+    ),
+  [metrics, formattedMetrics]
+);
+```
+
+## Record vs Map
+
+Always prefer `Record<string, T>` over `Map<string, T>` for simple lookups.
+
+### Record Pattern (Preferred)
+
+```typescript
+type UserNameMap = Record<string, string>;
+const userNames: UserNameMap = { id1: "John Doe", id2: "Jane Smith" };
+
+// Access
+const name = userNames[userId];
+const hasPlayer = playerId in playersOnKanban;
+```
+
+### Why Not Map
+
+```typescript
+// Avoid this pattern
+const lookup = new Map<string, User>();
+users.forEach(u => lookup.set(u.id, u));
+const user = lookup.get(userId);
+
+// Use this instead
+const lookup = users.reduce(
+  (acc, u) => ({ ...acc, [u.id]: u }),
+  {} as Record<string, User>
+);
+const user = lookup[userId];
+```
+
+## Array Transformations
+
+### Spread Before Sort
+
+Never sort in place. Always spread first.
+
+```typescript
+// Correct
+const sorted = [...Object.values(seasonData)].sort((a, b) =>
+  a.season > b.season ? 1 : -1
+);
+
+// Incorrect - mutates original
+const sorted = seasonData.sort((a, b) => a.season - b.season);
+```
+
+### Filter with Boolean
+
+```typescript
+const validPlayers = leaguePlayers.filter(
+  Boolean
+) as readonly PlayerWithScores[];
+```
+
+### Map for Transformation
+
+```typescript
+const teamGprData: readonly TeamGprData[] = Object.values(
+  teamGprAccumulator
+).map(team => ({
+  teamId: team.teamId,
+  teamName: team.teamName,
+  averageGpr: team.playerCount > 0 ? team.gprSum / team.playerCount : 0,
+}));
+```
+
+### Updating Array Item at Index
+
+```typescript
+// Correct - creates new array
+const updated = current.map((item, idx) => (idx === target ? newItem : item));
+
+// Incorrect - mutation
+current[target] = newItem;
+```
+
+### Adding to Array
+
+```typescript
+// Correct
+const withNew = [...existing, newItem];
+
+// Incorrect
+existing.push(newItem);
+```
+
+### Removing from Array
+
+```typescript
+// Correct
+const without = items.filter(item => item.id !== idToRemove);
+
+// Incorrect
+const idx = items.findIndex(item => item.id === idToRemove);
+items.splice(idx, 1);
+```
+
+## Object Updates
+
+### Spread for Updates
+
+```typescript
+// Correct
+const updated = { ...user, name: "New Name" };
+
+// Incorrect
+user.name = "New Name";
+```
+
+### Nested Object Updates
+
+```typescript
+const updated = {
+  ...state,
+  user: {
+    ...state.user,
+    profile: {
+      ...state.user.profile,
+      avatar: newAvatar,
+    },
+  },
+};
+```
+
+### Conditional Property Addition
+
+```typescript
+const result = {
+  ...baseObj,
+  ...(condition && { optionalProp: value }),
+};
+```
+
+## Conditional Values Without Let
+
+### Ternary for Simple Conditions
+
+```typescript
+// Correct
+const status = isComplete ? "done" : "pending";
+
+// Incorrect
+let status = "pending";
+if (isComplete) {
+  status = "done";
+}
+```
+
+### Ternary Chain for Multiple Conditions
+
+```typescript
+const priority = score > 90 ? "high" : score > 70 ? "medium" : "low";
+```
+
+### Nullish Coalescing
+
+```typescript
+const displayName = user.name ?? "Unknown User";
+const count = existing?.count ?? 0;
+```
+
+### Optional Chaining with Nullish Coalescing
+
+```typescript
+const firstName =
+  user.cognitoUser?.Attributes?.find(attr => attr.Name === "given_name")
+    ?.Value ?? "";
+```
+
+## Apollo Reactive Variables
+
+### Immutable Updates
+
+```typescript
+// Direct update for simple values
+isLoadingVar(true);
+errorVar("Error message");
+
+// Spread for array updates
+messagesVar([...messagesVar(), newMessage]);
+
+// Spread for complex updates
+const current = messagesVar();
+messagesVar([...current, newMessage]);
+```
+
+### Operation Hooks for Complex Updates
+
+```typescript
+export const useMessageOperations = () => {
+  const addMessage = useCallback((message: IMessage) => {
+    const current = messagesVar();
+    messagesVar([...current, message]);
+  }, []);
+
+  const clearMessages = useCallback(() => {
+    messagesVar([]);
+  }, []);
+
+  return { addMessage, clearMessages };
+};
+```
+
+## Readonly Types
+
+### Function Parameters
+
+```typescript
+export const calculateTeamGprRank = (
+  leaguePlayers: readonly (PlayerWithScores | null | undefined)[],
+  myTeamId: string | null | undefined
+): number | null => {
+  // ...
+};
+```
+
+### Apollo Cache Modifiers
+
+```typescript
+modify({
+  fields: {
+    myField(existingData: readonly { __ref: string }[] = [], { readField }) {
+      return existingData.filter(ref => readField("id", ref) !== idToRemove);
+    },
+  },
+});
+```
+
+## Testing Immutability
+
+### Verify New Object Creation
+
+```typescript
+test("should create new object on each reduce iteration", () => {
+  expect(result1).not.toBe(result2); // Different references
+  expect(result1).toEqual(result2); // Same values
+});
+```
+
+### Verify Record vs Map
+
+```typescript
+test("should return plain object, not Map", () => {
+  expect(result).toBeInstanceOf(Object);
+  expect(result).not.toBeInstanceOf(Map);
+});
+```