@codyswann/lisa 1.55.2 → 1.56.0

package/plugins/src/expo/skills/reduce-complexity/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: reduce-complexity
+description: This skill provides strategies and patterns for reducing cognitive complexity in React components. It should be used when ESLint reports sonarjs/cognitive-complexity violations, when refactoring complex View components, or when planning how to break down large components. The skill enforces this project's Container/View pattern requirements when extracting components.
+---
+
+# Reduce Complexity
+
+This skill provides systematic approaches for reducing cognitive complexity in React components while adhering to this project's Container/View pattern requirements.
+
+## When to Use This Skill
+
+- ESLint reports `sonarjs/cognitive-complexity` violations (threshold: 28)
+- A View component exceeds 200 lines
+- A component has deeply nested conditionals or repeated patterns
+- Planning refactoring of a complex component
+- Deciding between extracting helper functions vs full components
+
+## Complexity Sources in React Components
+
+Cognitive complexity increases with:
+
+| Source                 | Complexity Impact | Common in View Components |
+| ---------------------- | ----------------- | ------------------------- |
+| Nested conditionals    | +1 per nesting    | Yes                       |
+| Ternary expressions    | +1 each           | Yes                       |
+| Logical operators (&&) | +1 each           | Yes                       |
+| Loops (map, filter)    | +1 each           | Yes                       |
+| Switch/case statements | +1 per case       | Rare                      |
+| Catch blocks           | +1 each           | No (Container only)       |
+| Nested functions       | +1 per nesting    | Yes                       |
+
+## Decision Framework: Helper Function vs Full Component
+
+Before extracting code, determine the appropriate strategy:
+
+### Extract as Helper Function When:
+
+- The JSX renders a static or simple section with no logic of its own
+- The section does not need its own state, hooks, or callbacks
+- The pattern appears only in this file
+- The complexity comes from rendering, not behavior
+
+```tsx
+// Helper function - no logic, just rendering
+function renderSectionHeader(props: {
+  readonly title: string;
+  readonly count: number;
+}) {
+  return (
+    <HStack className="justify-between">
+      <Text className="font-bold">{props.title}</Text>
+      <Text className="text-sm">({props.count})</Text>
+    </HStack>
+  );
+}
+```
+
+### Extract as Full Component (Container/View) When:
+
+- The section has reusable logic or could be used elsewhere
+- The section would benefit from its own state management
+- The pattern repeats across multiple files
+- The section has 3+ props that could be simplified with a Container
+- Extracting would create a meaningful, named abstraction
+
+```
+FilterChipList/
+├── FilterChipListContainer.tsx  # Handles selection logic
+├── FilterChipListView.tsx       # Renders chip list
+└── index.tsx                    # Exports Container
+```
+
+## Refactoring Process
+
+### Step 1: Analyze Complexity Sources
+
+Run ESLint to identify the violation:
+
+```bash
+bun run lint 2>&1 | grep "cognitive-complexity"
+```
+
+> **Note:** Replace `bun` with your project's package manager (`npm`, `yarn`, `pnpm`) as needed.
+
+Read the file and identify:
+
+1. Which function has the violation (line number from ESLint)
+2. What patterns repeat (copy-pasted JSX with slight variations)
+3. What conditionals nest deeply (ternaries inside ternaries)
+4. What could be pre-computed in Container
+
+### Step 2: Choose Extraction Strategy
+
+Use the decision framework above. For View components:
+
+| Situation                  | Strategy                          |
+| -------------------------- | --------------------------------- |
+| Repeated JSX, no logic     | Helper function                   |
+| Repeated JSX, needs props  | Helper function with props object |
+| Repeated pattern, 3+ files | Full Container/View component     |
+| Complex section, own state | Full Container/View component     |
+| Deeply nested ternaries    | Pre-compute flags in Container    |
+
+### Step 3: Write Tests First (TDD)
+
+Before refactoring, ensure test coverage exists:
+
+```bash
+# Check existing coverage
+bun run test:unit --coverage --collectCoverageFrom='<file-path>'
+```
+
+If no tests exist, write tests that verify current behavior before refactoring.
+
+### Step 4: Implement Extraction
+
+For helper functions, see `references/extraction-strategies.md`.
+For full components, use the Container/View pattern skill.
+
+### Step 5: Verify Complexity Resolved
+
+```bash
+bun run lint 2>&1 | grep "cognitive-complexity"
+bun run test:unit
+```
+
+## Quick Fixes for Common Patterns
+
+### Repeated Conditional Styling
+
+**Before (high complexity):**
+
+```tsx
+<Pressable
+  style={{
+    backgroundColor: selected.includes(item) ? colors.primary : colors.bg,
+    borderColor: selected.includes(item) ? colors.primary : colors.border,
+  }}
+>
+  <Text style={{ color: selected.includes(item) ? "#FFF" : colors.text }}>
+    {item}
+  </Text>
+</Pressable>
+```
+
+**After (reduced complexity):**
+
+```tsx
+// In Container - pre-compute selection state
+const itemStates = useMemo(
+  () =>
+    items.map(item => ({
+      item,
+      isSelected: selected.includes(item),
+    })),
+  [items, selected]
+);
+
+// In View - simple conditional
+<Pressable style={isSelected ? styles.selected : styles.default}>
+  <Text style={isSelected ? styles.selectedText : styles.defaultText}>
+    {item}
+  </Text>
+</Pressable>;
+```
+
+### Repeated Section Patterns
+
+**Before (4x repeated pattern = high complexity):**
+
+```tsx
+{positions.length > 0 && (
+  <VStack>
+    <Text>Positions</Text>
+    <HStack>{positions.map(p => <Chip key={p} ... />)}</HStack>
+  </VStack>
+)}
+{tags.length > 0 && (
+  <VStack>
+    <Text>Tags</Text>
+    <HStack>{tags.map(t => <Chip key={t.id} ... />)}</HStack>
+  </VStack>
+)}
+// ... repeated 2 more times
+```
+
+**After (extract FilterChipList component):**
+
+```tsx
+<FilterChipList
+  title="Positions"
+  items={positions}
+  selectedItems={filters.positions}
+  onToggle={onPositionToggle}
+/>
+<FilterChipList
+  title="Tags"
+  items={tags}
+  selectedItems={filters.tags}
+  onToggle={onTagToggle}
+/>
+```
+
+### Nested Ternaries
+
+**Before:**
+
+```tsx
+{
+  isLoading ? (
+    <Spinner />
+  ) : hasError ? (
+    <Error />
+  ) : isEmpty ? (
+    <Empty />
+  ) : (
+    <Content />
+  );
+}
+```
+
+**After (pre-compute state in Container):**
+
+```tsx
+// Container
+const viewState = useMemo(() => {
+  if (isLoading) return "loading";
+  if (hasError) return "error";
+  if (isEmpty) return "empty";
+  return "content";
+}, [isLoading, hasError, isEmpty]);
+
+// View - map directly
+const VIEW_STATES = {
+  loading: <Spinner />,
+  error: <Error />,
+  empty: <Empty />,
+  content: <Content />,
+} as const;
+
+{
+  VIEW_STATES[viewState];
+}
+```
+
+## Reference Documentation
+
+For detailed patterns and complete examples:
+
+- `references/extraction-strategies.md` - Helper function patterns and when to use each
+- `references/refactoring-patterns.md` - Step-by-step refactoring examples with before/after code

package/plugins/src/expo/skills/reduce-complexity/references/extraction-strategies.md

@@ -0,0 +1,456 @@
+# Extraction Strategies
+
+This reference provides detailed patterns for extracting code to reduce cognitive complexity.
+
+## Strategy 1: Helper Functions in View Files
+
+Helper functions are the simplest extraction strategy. Use them for rendering logic that doesn't need its own component lifecycle.
+
+### Pattern: Render Helper with Props Object
+
+Always use a props object (not positional arguments) for type safety and clarity:
+
+```tsx
+/**
+ * Renders a section header with title and count.
+ * @param props - Helper function properties
+ * @param props.title - Section title text
+ * @param props.count - Item count to display
+ * @param props.colors - Theme colors object
+ */
+function renderSectionHeader(props: {
+  readonly title: string;
+  readonly count: number;
+  readonly colors: KanbanColors;
+}) {
+  const { title, count, colors } = props;
+  return (
+    <HStack className="items-center justify-between py-2">
+      <Text
+        className="text-xs font-semibold uppercase tracking-wider"
+        style={{ color: colors.textMuted }}
+      >
+        {title}
+      </Text>
+      <Text className="text-xs" style={{ color: colors.textSecondary }}>
+        ({count})
+      </Text>
+    </HStack>
+  );
+}
+```
+
+### Pattern: Conditional Render Helper
+
+For sections that render conditionally based on data:
+
+```tsx
+/**
+ * Renders the empty state when no items exist.
+ * @param props - Helper function properties
+ * @param props.message - Empty state message
+ * @param props.colors - Theme colors object
+ */
+function renderEmptyState(props: {
+  readonly message: string;
+  readonly colors: KanbanColors;
+}) {
+  const { message, colors } = props;
+  return (
+    <Box
+      className="items-center justify-center p-8"
+      style={{ backgroundColor: colors.cardBackground }}
+    >
+      <Text style={{ color: colors.textMuted }}>{message}</Text>
+    </Box>
+  );
+}
+
+// Usage in View
+const ListView = ({ items, isEmpty, colors }: Props) => (
+  <Box>
+    {isEmpty
+      ? renderEmptyState({ message: "No items found", colors })
+      : items.map(item => <Item key={item.id} item={item} />)}
+  </Box>
+);
+```
+
+### Pattern: List Item Render Helper
+
+For repeated item rendering with complex styling:
+
+```tsx
+/**
+ * Renders a selectable chip/pill item.
+ * @param props - Helper function properties
+ * @param props.label - Display text for the chip
+ * @param props.isSelected - Whether the chip is currently selected
+ * @param props.colors - Theme colors for styling
+ * @param props.onPress - Callback when chip is pressed
+ */
+function renderChip(props: {
+  readonly label: string;
+  readonly isSelected: boolean;
+  readonly colors: KanbanColors;
+  readonly onPress: () => void;
+}) {
+  const { label, isSelected, colors, onPress } = props;
+  return (
+    <Pressable
+      onPress={onPress}
+      style={{
+        paddingHorizontal: 10,
+        paddingVertical: 5,
+        borderRadius: 6,
+        backgroundColor: isSelected ? colors.primary : colors.cardBackground,
+        borderWidth: 1,
+        borderColor: isSelected ? colors.primary : colors.border,
+      }}
+    >
+      <Text
+        className="text-xs font-medium"
+        style={{ color: isSelected ? "#FFFFFF" : colors.textSecondary }}
+      >
+        {label}
+      </Text>
+    </Pressable>
+  );
+}
+```
+
+### When NOT to Use Helper Functions
+
+Do not use helper functions when:
+
+1. **The helper would need hooks** - Extract as full component instead
+2. **The helper is used in multiple files** - Extract as shared component
+3. **The helper has complex event handling** - Container should handle this
+4. **The helper exceeds 30 lines** - Consider full component extraction
+
+## Strategy 2: Pre-compute in Container
+
+Move complexity from View to Container by pre-computing values.
+
+### Pattern: Selection State Pre-computation
+
+**Before (complexity in View):**
+
+```tsx
+// View has repeated .includes() checks
+<Pressable
+  style={{
+    backgroundColor: filters.positions.includes(position)
+      ? colors.primary
+      : colors.cardBackground,
+  }}
+/>
+```
+
+**After (pre-computed in Container):**
+
+```tsx
+// Container
+const positionItems = useMemo(
+  () =>
+    availablePositions.map(position => ({
+      value: position,
+      label: position,
+      isSelected: filters.positions.includes(position),
+    })),
+  [availablePositions, filters.positions]
+);
+
+// View - simple prop access
+{
+  positionItems.map(({ value, label, isSelected }) => (
+    <Chip
+      key={value}
+      label={label}
+      isSelected={isSelected}
+      onPress={() => onPositionToggle(value)}
+    />
+  ));
+}
+```
+
+### Pattern: View State Enumeration
+
+**Before (nested ternaries):**
+
+```tsx
+{
+  isLoading ? (
+    <Spinner />
+  ) : error ? (
+    <ErrorView error={error} />
+  ) : data.length === 0 ? (
+    <EmptyState />
+  ) : (
+    <DataList data={data} />
+  );
+}
+```
+
+**After (enumerated state):**
+
+```tsx
+// Container
+type ViewState = "loading" | "error" | "empty" | "ready";
+
+const viewState = useMemo((): ViewState => {
+  if (isLoading) return "loading";
+  if (error) return "error";
+  if (data.length === 0) return "empty";
+  return "ready";
+}, [isLoading, error, data.length]);
+
+// View - switch or map
+const ComponentView = ({ viewState, data, error }: Props) => (
+  <Box>
+    {viewState === "loading" && <Spinner />}
+    {viewState === "error" && <ErrorView error={error} />}
+    {viewState === "empty" && <EmptyState />}
+    {viewState === "ready" && <DataList data={data} />}
+  </Box>
+);
+```
+
+### Pattern: Style Pre-computation
+
+**Before (inline style objects create complexity and perf issues):**
+
+```tsx
+<Box
+  style={{
+    backgroundColor: isDark ? colors.dark.bg : colors.light.bg,
+    padding: isCompact ? 8 : 16,
+    borderRadius: isRounded ? 12 : 0,
+  }}
+/>
+```
+
+**After (computed style in Container):**
+
+```tsx
+// Container
+const boxStyle = useMemo(
+  () => ({
+    backgroundColor: isDark ? colors.dark.bg : colors.light.bg,
+    padding: isCompact ? 8 : 16,
+    borderRadius: isRounded ? 12 : 0,
+  }),
+  [isDark, isCompact, isRounded, colors]
+);
+
+// View
+<Box style={boxStyle} />;
+```
+
+## Strategy 3: Full Component Extraction
+
+When helper functions aren't sufficient, extract a full Container/View component.
+
+### Decision Checklist
+
+Extract as full component when 3+ of these apply:
+
+- [ ] Pattern repeats in 2+ files
+- [ ] Section needs its own state
+- [ ] Section has 4+ props
+- [ ] Section has callbacks that could be simplified
+- [ ] Section represents a meaningful domain concept
+- [ ] Section could be tested independently
+
+### Extraction Steps
+
+1. **Identify the repeated/complex pattern**
+2. **Define the component's props interface**
+3. **Create directory structure:**
+   ```text
+   ComponentName/
+   ├── ComponentNameContainer.tsx
+   ├── ComponentNameView.tsx
+   └── index.tsx
+   ```
+4. **Write Container with logic/state**
+5. **Write View with pure rendering**
+6. **Update parent to use new component**
+7. **Write tests for new component**
+
+### Example: Extracting FilterChipList
+
+**Before (in FilterModalView.tsx):**
+
+```tsx
+{
+  /* Positions - repeated pattern */
+}
+{
+  availablePositions.length > 0 && (
+    <VStack className="gap-3">
+      <Text style={{ color: colors.textMuted }}>Positions</Text>
+      <HStack className="flex-wrap gap-2">
+        {availablePositions.map(position => (
+          <Pressable
+            key={position}
+            onPress={() => onPositionToggle(position)}
+            style={{
+              backgroundColor: filters.positions.includes(position)
+                ? colors.primary
+                : colors.cardBackground,
+              // ... more styles
+            }}
+          >
+            <Text>{position}</Text>
+          </Pressable>
+        ))}
+      </HStack>
+    </VStack>
+  );
+}
+
+{
+  /* Tags - same pattern with slight variation */
+}
+{
+  availableTags.length > 0 && (
+    <VStack className="gap-3">
+      <Text style={{ color: colors.textMuted }}>Tags</Text>
+      <HStack className="flex-wrap gap-2">
+        {availableTags.map(tag => (
+          <Pressable
+            key={tag.id}
+            onPress={() => onTagToggle(tag.id)}
+            // ... same pattern
+          >
+            <Text>{tag.name}</Text>
+          </Pressable>
+        ))}
+      </HStack>
+    </VStack>
+  );
+}
+```
+
+**After (FilterChipList component):**
+
+```tsx
+// FilterChipListContainer.tsx
+interface FilterChipListProps {
+  readonly title: string;
+  readonly items: readonly { id: string; label: string; color?: string }[];
+  readonly selectedIds: readonly string[];
+  readonly colors: KanbanColors;
+  readonly onToggle: (id: string) => void;
+}
+
+const FilterChipListContainer = ({
+  title,
+  items,
+  selectedIds,
+  colors,
+  onToggle,
+}: FilterChipListProps) => {
+  const chipItems = useMemo(
+    () =>
+      items.map(item => ({
+        ...item,
+        isSelected: selectedIds.includes(item.id),
+      })),
+    [items, selectedIds]
+  );
+
+  const handleToggle = useCallback(
+    (id: string) => () => onToggle(id),
+    [onToggle]
+  );
+
+  return (
+    <FilterChipListView
+      title={title}
+      items={chipItems}
+      colors={colors}
+      onToggle={handleToggle}
+    />
+  );
+};
+```
+
+```tsx
+// FilterChipListView.tsx
+interface FilterChipListViewProps {
+  readonly title: string;
+  readonly items: readonly {
+    id: string;
+    label: string;
+    color?: string;
+    isSelected: boolean;
+  }[];
+  readonly colors: KanbanColors;
+  readonly onToggle: (id: string) => () => void;
+}
+
+const FilterChipListView = ({
+  title,
+  items,
+  colors,
+  onToggle,
+}: FilterChipListViewProps) => (
+  <VStack className="gap-3">
+    <Text
+      className="text-xs font-semibold uppercase tracking-wider"
+      style={{ color: colors.textMuted }}
+    >
+      {title}
+    </Text>
+    <HStack className="flex-wrap gap-2">
+      {items.map(({ id, label, color, isSelected }) => (
+        <Pressable
+          key={id}
+          onPress={onToggle(id)}
+          style={{
+            paddingHorizontal: 10,
+            paddingVertical: 5,
+            borderRadius: 6,
+            backgroundColor: isSelected
+              ? (color ?? colors.primary)
+              : colors.cardBackground,
+            borderWidth: 1,
+            borderColor: isSelected ? (color ?? colors.primary) : colors.border,
+          }}
+        >
+          <Text
+            className="text-xs font-medium"
+            style={{ color: isSelected ? "#FFFFFF" : colors.textSecondary }}
+          >
+            {label}
+          </Text>
+        </Pressable>
+      ))}
+    </HStack>
+  </VStack>
+);
+
+FilterChipListView.displayName = "FilterChipListView";
+export default memo(FilterChipListView);
+```
+
+**Usage in parent:**
+
+```tsx
+<FilterChipList
+  title="Positions"
+  items={positionItems}
+  selectedIds={filters.positions}
+  colors={colors}
+  onToggle={onPositionToggle}
+/>
+<FilterChipList
+  title="Tags"
+  items={tagItems}
+  selectedIds={filters.tags}
+  colors={colors}
+  onToggle={onTagToggle}
+/>
+```