cursor-quality-suite 1.0.0

package/commands/code-quality/visualize-architecture.md

@@ -0,0 +1,464 @@
+---
+description: Generate Mermaid diagrams for code architecture visualization (v4.1 Frontend-Enhanced)
+category: Analysis & Documentation
+aliases: [diagram, architecture, mermaid, sequence, class, xstate, dataflow]
+---
+
+# Visualize Architecture - Generate Diagrams (v4.1)
+
+Create visual diagrams (Mermaid) for architecture, data flow, component relationships, and **frontend-specific patterns**.
+
+## Usage
+
+```
+/visualize-architecture {SCOPE}
+/visualize-architecture {SCOPE} --type={diagram_type}
+/visualize-architecture {SCOPE} --data-flow           # Props vs Context analysis
+/visualize-architecture {SCOPE} --boundaries          # Suspense/Error boundaries
+/visualize-architecture {SCOPE} --xstate              # XState-compatible state chart
+```
+
+## Diagram Types
+
+### Available Types
+
+| Type         | Use Case                                    |
+| ------------ | ------------------------------------------- |
+| `component`  | Component hierarchy and relationships       |
+| `sequence`   | Request/data flow through system            |
+| `class`      | Class/interface relationships               |
+| `state`      | State machine for complex logic             |
+| `flowchart`  | Decision trees and workflows                |
+| `er`         | Entity relationships (data models)          |
+| `dataflow`   | **NEW:** Props vs Context data flow         |
+| `boundaries` | **NEW:** Suspense/ErrorBoundary locations   |
+| `xstate`     | **NEW:** XState-compatible state definition |
+
+### Auto-Detection
+
+If `--type` not specified, I'll auto-detect based on scope:
+
+-   React components → `component` diagram
+-   API/hooks → `sequence` diagram
+-   Types/interfaces → `class` diagram
+-   State machines / reducers → `state` diagram
+-   Context providers → `dataflow` diagram
+
+## Examples
+
+### Component Hierarchy
+
+```
+/visualize-architecture src/features/checkout/src/components/Packages
+```
+
+Output:
+
+```mermaid
+graph TD
+    subgraph Packages
+        A[PackagesV2] --> B[ProtectionPackageCard]
+        A --> C[ExtrasPackageCard]
+        A --> D[PackagesSkeleton]
+
+        B --> E[LineItems]
+        B --> F[PackageHeader]
+        B --> G[PackagePricing]
+
+        E --> H[LineItem]
+        E --> I[TooltipTitle]
+    end
+
+    style A fill:#ff6b35
+    style B fill:#4ecdc4
+    style C fill:#4ecdc4
+```
+
+### Sequence Diagram (Data Flow)
+
+```
+/visualize-architecture useBookingData --type=sequence
+```
+
+Output:
+
+```mermaid
+sequenceDiagram
+    participant C as Component
+    participant H as useBookingData
+    participant API as BookingAPI
+    participant S as Store
+
+    C->>H: Initialize hook
+    H->>API: fetchBooking(id)
+    API-->>H: BookingResponse
+    H->>S: updateStore(data)
+    S-->>C: Re-render with data
+
+    Note over H: AbortController cleanup on unmount
+```
+
+### State Diagram
+
+```
+/visualize-architecture BookingFlow --type=state
+```
+
+Output:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Loading: fetchBooking
+    Loading --> Success: data received
+    Loading --> Error: request failed
+    Success --> Updating: modifyBooking
+    Updating --> Success: update complete
+    Error --> Loading: retry
+    Success --> [*]: complete
+```
+
+### Class Diagram (Types)
+
+```
+/visualize-architecture src/types/Booking --type=class
+```
+
+Output:
+
+```mermaid
+classDiagram
+    class Booking {
+        +string id
+        +BookingStatus status
+        +Vehicle vehicle
+        +Customer customer
+        +getTotal() number
+    }
+
+    class Vehicle {
+        +string id
+        +string name
+        +VehicleCategory category
+    }
+
+    class Customer {
+        +string id
+        +string email
+        +Address address
+    }
+
+    Booking "1" --> "1" Vehicle
+    Booking "1" --> "1" Customer
+```
+
+## AI Execution
+
+When user runs `/visualize-architecture {SCOPE}`:
+
+### Step 1: Analyze Scope
+
+```
+1. Identify files/folders in scope
+2. Detect primary pattern (components, hooks, types)
+3. Select appropriate diagram type
+4. Extract relationships
+```
+
+### Step 2: Generate Diagram
+
+```
+1. Parse code structure
+2. Identify nodes (components, functions, types)
+3. Map relationships (imports, props, calls)
+4. Generate Mermaid syntax
+```
+
+### Step 3: Render
+
+```mermaid
+{generated_diagram}
+```
+
+### Step 4: Offer Variations
+
+```
+📊 Architecture Diagram Generated
+
+Variations available:
+1. Add more detail (show props/methods)
+2. Simplify (high-level only)
+3. Different view (sequence instead of component)
+4. Focus on specific path
+
+Which variation? (1/2/3/4/done)
+```
+
+## Integration
+
+### With Documentation
+
+```
+/visualize-architecture {SCOPE} --output=docs/architecture/
+```
+
+Creates:
+
+-   `{scope}-diagram.md` with Mermaid
+-   Links from relevant component docs
+
+### With PR Description
+
+```
+/visualize-architecture --pr-diff
+```
+
+Generates diagram showing:
+
+-   Files changed
+-   Relationships affected
+-   New connections added
+
+## Tips
+
+1. **Start broad, then narrow**
+
+    ```
+    /visualize-architecture src/features/checkout  # Overview
+    /visualize-architecture src/features/checkout/src/hooks  # Focus
+    ```
+
+2. **Use for onboarding**
+
+    ```
+    /visualize-architecture --key-flows
+    ```
+
+    Generates diagrams for critical paths
+
+3. **Before refactoring**
+    ```
+    /visualize-architecture {target} --show-coupling
+    ```
+    Highlights tightly coupled components
+
+---
+
+## 🆕 Frontend-Specific Diagrams (v4.1)
+
+### Data Flow Diagram (Props vs Context)
+
+```
+/visualize-architecture src/features/checkout/src/components/Checkout --data-flow
+```
+
+Output:
+
+```mermaid
+graph TD
+    subgraph "Data Sources"
+        API[BookingAPI]
+        CTX[BookingContext]
+        PROPS[Parent Props]
+    end
+
+    subgraph "Components"
+        A[CheckoutPage]
+        B[VehicleSection]
+        C[ProtectionSection]
+        D[PaymentSection]
+    end
+
+    API -->|"useBookingData()"| A
+    A -->|"Context.Provider"| CTX
+
+    CTX -.->|"useBooking()"| B
+    CTX -.->|"useBooking()"| C
+    CTX -.->|"useBooking()"| D
+
+    A -->|"vehicle: Vehicle"| B
+    A -->|"packages: Package[]"| C
+
+    style CTX fill:#e1f5fe
+    style PROPS fill:#fff3e0
+
+    classDef contextData stroke:#0288d1,stroke-width:2px
+    classDef propData stroke:#ff9800,stroke-width:2px
+```
+
+**Legend:**
+
+-   Solid lines = Props drilling
+-   Dashed lines = Context consumption
+-   Blue = Context-based data
+-   Orange = Prop-based data
+
+### Suspense & Error Boundaries Map
+
+```
+/visualize-architecture src/features/checkout --boundaries
+```
+
+Output:
+
+```mermaid
+graph TD
+    subgraph "App Root"
+        ROOT[App]
+        EB1[ErrorBoundary: AppError]
+    end
+
+    subgraph "Routes"
+        R1[/checkout]
+        R2[/checkout/payment]
+    end
+
+    subgraph "Suspense Zones"
+        S1[Suspense: CheckoutSkeleton]
+        S2[Suspense: PaymentSkeleton]
+    end
+
+    subgraph "Async Components"
+        AC1[VehicleDetails - lazy]
+        AC2[PackageList - lazy]
+        AC3[PaymentForm - lazy]
+    end
+
+    ROOT --> EB1
+    EB1 --> R1
+    EB1 --> R2
+
+    R1 --> S1
+    S1 --> AC1
+    S1 --> AC2
+
+    R2 --> S2
+    S2 --> AC3
+
+    style EB1 fill:#ffcdd2
+    style S1 fill:#c8e6c9
+    style S2 fill:#c8e6c9
+
+    classDef errorBoundary fill:#ffcdd2,stroke:#c62828
+    classDef suspense fill:#c8e6c9,stroke:#2e7d32
+```
+
+**Analysis includes:**
+
+-   ErrorBoundary coverage (red zones)
+-   Suspense boundaries (green zones)
+-   Lazy-loaded components
+-   Missing boundaries (warnings)
+
+### XState-Compatible State Chart
+
+```
+/visualize-architecture useCheckoutFlow --xstate
+```
+
+Output:
+
+```mermaid
+stateDiagram-v2
+    [*] --> idle
+
+    state idle {
+        [*] --> ready
+    }
+
+    idle --> loading: FETCH_VEHICLE
+    loading --> vehicleLoaded: VEHICLE_SUCCESS
+    loading --> error: VEHICLE_ERROR
+
+    vehicleLoaded --> selectingPackages: CONTINUE
+    selectingPackages --> packageSelected: SELECT_PACKAGE
+    packageSelected --> selectingPackages: CHANGE_PACKAGE
+    packageSelected --> payment: CONTINUE_TO_PAYMENT
+
+    payment --> processing: SUBMIT
+    processing --> success: PAYMENT_SUCCESS
+    processing --> error: PAYMENT_ERROR
+
+    error --> idle: RETRY
+    success --> [*]
+```
+
+**XState Export:**
+
+```typescript
+// Generated XState machine definition
+export const checkoutMachine = createMachine({
+    id: 'checkout',
+    initial: 'idle',
+    states: {
+        idle: {
+            on: { FETCH_VEHICLE: 'loading' },
+        },
+        loading: {
+            invoke: {
+                src: 'fetchVehicle',
+                onDone: 'vehicleLoaded',
+                onError: 'error',
+            },
+        },
+        // ... full machine
+    },
+});
+```
+
+### Component Render Tree with Re-render Analysis
+
+```
+/visualize-architecture {SCOPE} --render-analysis
+```
+
+Shows:
+
+-   Which components re-render on state changes
+-   Memo boundaries
+-   Context consumer impact zones
+
+```mermaid
+graph TD
+    subgraph "Re-renders on booking change"
+        A[CheckoutPage 🔄]
+        B[VehicleSection 🔄]
+        C[PriceDisplay 🔄]
+    end
+
+    subgraph "Memoized (stable)"
+        D[Header ⚡]
+        E[Footer ⚡]
+        F[StaticContent ⚡]
+    end
+
+    A --> B
+    A --> C
+    A --> D
+    A --> E
+
+    style A fill:#ffecb3
+    style B fill:#ffecb3
+    style C fill:#ffecb3
+    style D fill:#c8e6c9
+    style E fill:#c8e6c9
+```
+
+**Legend:**
+
+-   🔄 Yellow = Re-renders on state change
+-   ⚡ Green = Memoized / Stable
+
+## Integration with /plan-and-budget
+
+When running `/plan-and-budget`, optionally generate:
+
+```
+/plan-and-budget "Add new feature" --with-diagram
+```
+
+Includes architecture diagram in the plan showing:
+
+-   Current state
+-   Proposed changes
+-   Impact zones

package/commands/testing/mutation-audit.md

@@ -0,0 +1,229 @@
+---
+description: Run mutation tests to verify test quality, catch shallow coverage
+category: Testing
+aliases: [mutation, test-quality]
+---
+
+# Mutation Audit - Test Quality via Mutation Testing
+
+Run mutation tests to verify test suite effectiveness and catch shallow coverage.
+
+## Usage
+
+```
+/mutation-audit {FILE_PATH}
+/mutation-audit {PR_NUMBER}
+/mutation-audit --scope changed      # Only mutate changed files
+/mutation-audit --threshold 80       # Fail if mutation score < 80%
+```
+
+## What This Does
+
+1. **Introduces mutations** - Small code changes (mutants)
+2. **Runs test suite** - Checks if tests catch mutations
+3. **Calculates mutation score** - % of mutants killed
+4. **Identifies weak tests** - Tests that don't catch logic changes
+5. **Suggests improvements** - Better assertions for coverage
+
+## Mutation Types
+
+| Mutation        | Example                       | What It Tests        |
+| --------------- | ----------------------------- | -------------------- |
+| **Boundary**    | `>` → `>=`                    | Off-by-one errors    |
+| **Negation**    | `true` → `false`              | Boolean logic        |
+| **Arithmetic**  | `+` → `-`                     | Math operations      |
+| **Return**      | `return x` → `return null`    | Return value usage   |
+| **Conditional** | `if(a && b)` → `if(a \|\| b)` | Logic branches       |
+| **Remove**      | `fn()` → `// fn()`            | Side effect reliance |
+
+## Output Format
+
+````
+📋 Running mutation audit on PackagesV2.tsx...
+
+════════════════════════════════════════════════════════════════
+  MUTATION TESTING RESULTS
+════════════════════════════════════════════════════════════════
+
+File: src/features/checkout/src/components/CoverageAndAddOns/PackagesV2.tsx
+Tests: PackagesV2.test.tsx (12 test cases)
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Mutants | 45 |
+| Killed | 32 |
+| Survived | 13 |
+| **Mutation Score** | **71%** 🟠 |
+
+## Survived Mutants (Tests Failed to Catch)
+
+### 🔴 Critical: Logic not tested
+
+| Line | Original | Mutation | Why It Matters |
+|------|----------|----------|----------------|
+| 78 | `price > 0` | `price >= 0` | Zero-price packages slip through |
+| 112 | `isSelected && isAvailable` | `isSelected \|\| isAvailable` | Wrong selection state |
+| 145 | `return total` | `return 0` | Total calculation not verified |
+
+### 🟠 Medium: Weak assertions
+
+| Line | Original | Mutation | Issue |
+|------|----------|----------|-------|
+| 56 | `setLoading(true)` | `// removed` | Loading state not asserted |
+| 89 | `onSelect(pkg)` | `// removed` | Callback not verified |
+
+### 🟢 Minor: Edge cases
+
+| Line | Original | Mutation | Issue |
+|------|----------|----------|-------|
+| 23 | `packages.length` | `packages.length + 1` | Off-by-one not tested |
+
+════════════════════════════════════════════════════════════════
+  SURVIVING MUTANT DETAILS
+════════════════════════════════════════════════════════════════
+
+## Mutant #1: Boundary Condition (Line 78)
+
+**Original:**
+```typescript
+if (price > 0) {
+    showPrice = true;
+}
+````
+
+**Mutation:**
+
+```typescript
+if (price >= 0) {
+    // Changed > to >=
+    showPrice = true;
+}
+```
+
+**Why survived:** No test checks behavior when `price === 0`
+
+**Suggested test:**
+
+```typescript
+it('should hide price when price is exactly 0', () => {
+    render(<PackagesV2 packages={[{ price: 0 }]} />);
+    expect(screen.queryByTestId('price-display')).not.toBeInTheDocument();
+});
+```
+
+---
+
+## Mutant #2: Callback Removal (Line 89)
+
+**Original:**
+
+```typescript
+const handleSelect = (pkg: IPackage) => {
+    onSelect(pkg);
+    setSelected(pkg.id);
+};
+```
+
+**Mutation:**
+
+```typescript
+const handleSelect = (pkg: IPackage) => {
+    // onSelect(pkg);  // Removed
+    setSelected(pkg.id);
+};
+```
+
+**Why survived:** Test only checks UI state, not callback invocation
+
+**Suggested test:**
+
+```typescript
+it('should call onSelect with package when clicked', () => {
+    const onSelect = jest.fn();
+    render(<PackagesV2 onSelect={onSelect} packages={mockPackages} />);
+
+    userEvent.click(screen.getByTestId('package-premium'));
+
+    expect(onSelect).toHaveBeenCalledWith(
+        expect.objectContaining({ id: 'premium' })
+    );
+});
+```
+
+════════════════════════════════════════════════════════════════
+RECOMMENDATIONS
+════════════════════════════════════════════════════════════════
+
+## Test Quality Score: 71% (🟠 Needs Improvement)
+
+### Priority Fixes:
+
+1. **Add boundary tests** (3 mutants)
+
+    - Test `price === 0` case
+    - Test empty `packages` array
+    - Test single-item arrays
+
+2. **Assert callbacks** (2 mutants)
+
+    - Verify `onSelect` is called
+    - Verify `onChange` is called with correct args
+
+3. **Check return values** (1 mutant)
+    - Assert calculated total
+    - Don't just check "truthy"
+
+### Good Practices Already Present:
+
+✅ Error states tested
+✅ Loading states tested
+✅ Render without crash
+
+### Target: 85% mutation score for critical paths
+
+════════════════════════════════════════════════════════════════
+MUTATION SCORE HISTORY
+════════════════════════════════════════════════════════════════
+
+| Date          | Score | Change |
+| ------------- | ----- | ------ |
+| 2024-12-23    | 71%   | -      |
+| (After fixes) | ~85%  | +14%   |
+
+````
+
+## Commands Used
+
+```bash
+# Using Stryker for mutation testing
+npx stryker run --mutate "src/features/checkout/src/**/*.tsx"
+
+# Quick mutation check (fewer mutators)
+npx stryker run --mutators "['BooleanLiteral', 'ConditionalExpression']"
+
+# Generate HTML report
+npx stryker run --reporters html
+````
+
+## Mutation Score Thresholds
+
+| Score   | Rating       | Action                   |
+| ------- | ------------ | ------------------------ |
+| 90-100% | ✅ Excellent | Maintain                 |
+| 80-89%  | ✅ Good      | Minor improvements       |
+| 70-79%  | 🟠 Fair      | Add missing assertions   |
+| 60-69%  | 🟠 Poor      | Significant test gaps    |
+| <60%    | 🔴 Critical  | Major refactoring needed |
+
+## AI Execution
+
+When user runs `/mutation-audit {PATH}`:
+
+1. **Parse code** - Identify mutable expressions
+2. **Generate mutants** - Create code variations
+3. **Run tests** - Execute against mutants
+4. **Analyze survivors** - Why tests didn't catch them
+5. **Generate suggestions** - Specific test improvements
+6. **Report score** - With historical comparison