@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/skills/cypress-selectors/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: cypress-selectors
+description: |
+  3-level selector system for testing: CORE_SELECTORS + BLOCK_SELECTORS + THEME_SELECTORS.
+  Provides helpers sel(), cySelector(), entitySelectors() for components and POMs.
+  Use this skill when working with data-cy attributes, POMs, or Cypress tests.
+allowed-tools: Read, Glob, Grep, Bash(python:*)
+version: 1.1.0
+---
+
+# Cypress Selectors System
+
+Centralized `data-cy` selector system for Cypress testing.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────┐
+│           CORE (Read-Only)              │
+│  core/lib/test/core-selectors.ts        │
+│  core/lib/test/selector-factory.ts      │
+└─────────────────┬───────────────────────┘
+                  │ imports
+                  ▼
+┌─────────────────────────────────────────┐
+│         THEME (Editable)                │
+│  contents/themes/{theme}/lib/selectors.ts│
+│  ├── BLOCK_SELECTORS                    │
+│  ├── DEVTOOLS_SELECTORS                 │
+│  ├── THEME_SELECTORS = {                │
+│  │     ...CORE_SELECTORS,               │
+│  │     blocks: BLOCK_SELECTORS,         │
+│  │     devtools: DEVTOOLS_SELECTORS     │
+│  │   }                                  │
+│  └── exports: sel, cySelector, etc.     │
+└─────────────────┬───────────────────────┘
+                  │ re-exports
+                  ▼
+┌─────────────────────────────────────────┐
+│  tests/cypress/src/selectors.ts         │
+│  (re-exports for test files)            │
+└─────────────────┬───────────────────────┘
+                  │ imports
+        ┌─────────┴─────────┐
+        ▼                   ▼
+┌───────────────┐   ┌───────────────┐
+│  Components   │   │     POMs      │
+│  sel('x.y')   │   │ cySelector()  │
+└───────────────┘   └───────────────┘
+```
+
+## When to Use This Skill
+
+- Adding `data-cy` attributes to components
+- Creating new BLOCK_SELECTORS for a block
+- Working with Page Object Models (POMs)
+- Validating selector coverage in UI
+- Writing Cypress E2E tests
+
+## Key Functions
+
+### `sel(path: string, replacements?: object)`
+
+Use in **components** to get the selector string for `data-cy`:
+
+```typescript
+// In block component: contents/themes/{theme}/blocks/{block-name}/component.tsx
+import { sel } from '../../lib/selectors'
+
+// Static selector - note the 'blocks.' prefix for block selectors
+<section data-cy={sel('blocks.hero.container')}>
+  <h2 data-cy={sel('blocks.hero.title')}>{title}</h2>
+</section>
+
+// Dynamic selector with replacement
+{items.map((item, index) => (
+  <div data-cy={sel('blocks.faqAccordion.item', { index: String(index) })}>
+    {item.content}
+  </div>
+))}
+
+// Core selectors (no 'blocks.' prefix)
+<button data-cy={sel('auth.login.submit')}>Login</button>
+```
+
+### `cySelector(path: string, replacements?: object)`
+
+Use in **POMs and Cypress tests** to get the CSS selector `[data-cy="..."]`:
+
+```typescript
+// In POM: contents/themes/{theme}/tests/cypress/src/features/MyPOM.ts
+import { BasePOM } from '../core/BasePOM'
+import { cySelector } from '../selectors'
+
+export class HeroPOM extends BasePOM {
+  get selectors() {
+    return {
+      container: cySelector('blocks.hero.container'),
+      title: cySelector('blocks.hero.title'),
+    }
+  }
+
+  // Dynamic selectors
+  getItem(index: number) {
+    return cy.get(cySelector('blocks.faqAccordion.item', { index: String(index) }))
+  }
+
+  // Factory method
+  static create(): HeroPOM {
+    return new HeroPOM()
+  }
+}
+```
+
+```typescript
+// In test file: contents/themes/{theme}/tests/cypress/e2e/blocks/hero.cy.ts
+import { cySelector } from '../../src/selectors'
+
+describe('Hero Block', () => {
+  it('should display the hero', () => {
+    cy.get(cySelector('blocks.hero.container')).should('be.visible')
+  })
+})
+```
+
+### `entitySelectors(slug: string)`
+
+Get all selectors for a specific entity:
+
+```typescript
+import { entitySelectors } from '../../src/selectors'
+
+const taskSelectors = entitySelectors('tasks')
+// Returns: { table, row, createBtn, editBtn, ... }
+```
+
+## Selector Paths
+
+**IMPORTANT:** Block selectors use the `blocks.` prefix because BLOCK_SELECTORS is nested under `blocks:` in THEME_SELECTORS:
+
+```typescript
+// Block selectors - use 'blocks.' prefix
+sel('blocks.hero.container')           // → 'block-hero'
+sel('blocks.faqAccordion.item', { index: '0' })  // → 'faq-item-0'
+sel('blocks.pricingTable.plan', { index: '1' }) // → 'pricing-plan-1'
+
+// Core selectors - no prefix
+sel('auth.login.form')                 // → 'login-form'
+sel('entity.table', { slug: 'tasks' }) // → 'tasks-table'
+
+// Devtools selectors - use 'devtools.' prefix
+sel('devtools.scheduledActions.table') // → 'scheduled-actions-table'
+```
+
+## Naming Conventions
+
+### Static Selectors
+```
+domain-element
+```
+Examples:
+- `block-hero` (block container)
+- `login-form` (core component)
+- `nav-main` (navigation element)
+
+### Dynamic Selectors with Placeholders
+```
+{placeholder}-element-{placeholder}
+```
+Placeholders:
+- `{index}` - Array index (most common for blocks)
+- `{slug}` - Entity slug (tasks, customers, pages)
+- `{id}` - Record ID
+- `{name}` - Field name
+- `{action}` - Action name (edit, delete)
+
+Examples:
+- `faq-item-{index}` → `faq-item-0`
+- `{slug}-row-{id}` → `tasks-row-123`
+- `field-{name}` → `field-email`
+
+## File Locations
+
+| Type | Location | Who Modifies |
+|------|----------|--------------|
+| Core selectors | `core/lib/test/core-selectors.ts` | Core maintainers only |
+| Selector factory | `core/lib/test/selector-factory.ts` | Core maintainers only |
+| Block selectors | `contents/themes/{theme}/lib/selectors.ts` | Theme developers |
+| Test re-exports | `contents/themes/{theme}/tests/cypress/src/selectors.ts` | Auto (re-exports) |
+| POMs | `contents/themes/{theme}/tests/cypress/src/features/*POM.ts` | Test developers |
+
+## Adding New Selectors
+
+### For Block Components
+
+Edit `contents/themes/{theme}/lib/selectors.ts`, add to BLOCK_SELECTORS:
+
+```typescript
+export const BLOCK_SELECTORS = {
+  // ... existing blocks
+  myNewBlock: {
+    container: 'block-my-new-block',
+    title: 'my-block-title',
+    item: 'my-block-item-{index}',
+  }
+}
+```
+
+Then use in component with `blocks.` prefix:
+```tsx
+// contents/themes/{theme}/blocks/my-new-block/component.tsx
+import { sel } from '../../lib/selectors'
+
+<section data-cy={sel('blocks.myNewBlock.container')}>
+  <h2 data-cy={sel('blocks.myNewBlock.title')}>{title}</h2>
+</section>
+```
+
+### For Core Components
+
+Edit `core/lib/test/core-selectors.ts`:
+
+```typescript
+export const CORE_SELECTORS = {
+  // ... existing selectors
+  myNewFeature: {
+    container: 'my-feature-container',
+    list: 'my-feature-list',
+    item: 'my-feature-item-{id}',
+  }
+}
+```
+
+### For DevTools Components
+
+Edit `contents/themes/{theme}/lib/selectors.ts`, add to DEVTOOLS_SELECTORS:
+
+```typescript
+export const DEVTOOLS_SELECTORS = {
+  // ... existing selectors
+  myDevTool: {
+    page: 'devtools-my-tool-page',
+    table: 'my-tool-table',
+  }
+}
+```
+
+## Anti-Patterns
+
+```typescript
+// ❌ NEVER: Hardcoded data-cy in component
+<button data-cy="submit-btn">
+
+// ❌ NEVER: Direct selector string in test
+cy.get('[data-cy="submit-btn"]')
+
+// ❌ NEVER: Missing 'blocks.' prefix for block selectors
+sel('hero.container')  // Wrong!
+sel('blocks.hero.container')  // Correct!
+
+// ❌ NEVER: Import from core in theme components
+import { sel } from '@/core/lib/test'  // Wrong!
+import { sel } from '../../lib/selectors'  // Correct!
+
+// ❌ NEVER: Add selector without UI element
+// Only add selectors for existing UI elements
+```
+
+## Validation Scripts
+
+### Validate all selectors use sel()
+```bash
+python .claude/skills/cypress-selectors/scripts/validate-selectors.py
+```
+
+### Find elements missing data-cy
+```bash
+python .claude/skills/cypress-selectors/scripts/extract-missing.py --path contents/themes/default/blocks/
+```
+
+### Generate block selectors for new block
+```bash
+# Basic generation
+python .claude/skills/cypress-selectors/scripts/generate-block-selectors.py --block my-new-block
+
+# Analyze existing block and generate full example
+python .claude/skills/cypress-selectors/scripts/generate-block-selectors.py --block faq-accordion --analyze --full
+
+# Just show selector entry without instructions
+python .claude/skills/cypress-selectors/scripts/generate-block-selectors.py --block my-block --dry-run
+```
+
+## Checklist
+
+Before committing UI changes:
+
+- [ ] All interactive elements have `data-cy={sel('...')}`
+- [ ] Block selectors use `sel('blocks.{blockName}.{element}')` path
+- [ ] New selectors added to BLOCK_SELECTORS or CORE_SELECTORS
+- [ ] POM updated with new selectors using `cySelector()`
+- [ ] Selector validation test created in `_selectors/*.cy.ts`
+- [ ] No hardcoded `data-cy` strings in components
+- [ ] No direct core imports in theme files
+
+## References
+
+- Load `references/architecture.md` for detailed architecture
+- Load `references/naming-conventions.md` for naming rules
+- Load `references/anti-patterns.md` for common mistakes

package/claude/skills/cypress-selectors/scripts/extract-missing.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""
+Extract Missing Selectors Script
+
+Finds interactive elements (buttons, inputs, links, forms) that are missing
+data-cy attributes.
+
+Usage:
+    python extract-missing.py --path PATH [--output OUTPUT]
+
+Options:
+    --path PATH      Directory to scan
+    --output OUTPUT  Output file for results (default: stdout)
+    --format FORMAT  Output format: text, json, markdown (default: text)
+"""
+
+import os
+import re
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import List, Dict, Set
+
+# Interactive elements that should have data-cy
+INTERACTIVE_ELEMENTS = [
+    'button',
+    'Button',
+    'input',
+    'Input',
+    'select',
+    'Select',
+    'textarea',
+    'Textarea',
+    'form',
+    'Form',
+    'a',
+    'Link',
+]
+
+# Pattern to find JSX elements
+JSX_ELEMENT_PATTERN = re.compile(
+    r'<(' + '|'.join(INTERACTIVE_ELEMENTS) + r')\s+([^>]*?)(?:/>|>)',
+    re.IGNORECASE | re.DOTALL
+)
+
+# Pattern to check if data-cy exists
+DATA_CY_PATTERN = re.compile(r'data-cy')
+
+
+def find_tsx_files(path: str) -> List[Path]:
+    """Find all TSX files in the given path."""
+    root = Path(path)
+    return list(root.rglob("*.tsx"))
+
+
+def analyze_file(file_path: Path) -> Dict:
+    """Find interactive elements missing data-cy."""
+    missing = []
+    has_selector = []
+
+    with open(file_path, 'r', encoding='utf-8') as f:
+        content = f.read()
+        lines = content.split('\n')
+
+    # Track line numbers
+    for line_num, line in enumerate(lines, 1):
+        for match in JSX_ELEMENT_PATTERN.finditer(line):
+            element_type = match.group(1)
+            attributes = match.group(2)
+
+            element_info = {
+                'line': line_num,
+                'element': element_type,
+                'attributes': attributes[:100] + '...' if len(attributes) > 100 else attributes,
+                'context': line.strip()[:120]
+            }
+
+            if DATA_CY_PATTERN.search(attributes):
+                has_selector.append(element_info)
+            else:
+                # Skip if it has onClick/onChange but might be internal
+                if 'data-cy' not in line:
+                    missing.append(element_info)
+
+    return {
+        'file': str(file_path),
+        'missing': missing,
+        'has_selector': has_selector,
+        'coverage': len(has_selector) / (len(missing) + len(has_selector)) * 100 if (missing or has_selector) else 100
+    }
+
+
+def suggest_selector(element: str, attributes: str, file_path: str) -> str:
+    """Suggest a selector name based on context."""
+    # Extract common attributes that might give hints
+    name_match = re.search(r'name=["\']([^"\']+)["\']', attributes)
+    id_match = re.search(r'id=["\']([^"\']+)["\']', attributes)
+    type_match = re.search(r'type=["\']([^"\']+)["\']', attributes)
+
+    # Get component name from file path
+    component = Path(file_path).stem.lower().replace('-', '.').replace('_', '.')
+
+    if name_match:
+        return f"{component}.{name_match.group(1)}"
+    if id_match:
+        return f"{component}.{id_match.group(1)}"
+    if type_match:
+        return f"{component}.{type_match.group(1)}.{element.lower()}"
+
+    return f"{component}.{element.lower()}"
+
+
+def print_text_report(results: List[Dict]):
+    """Print plain text report."""
+    total_missing = 0
+    total_with = 0
+
+    print("\n" + "=" * 70)
+    print("MISSING DATA-CY ATTRIBUTES REPORT")
+    print("=" * 70)
+
+    for result in results:
+        if result['missing']:
+            print(f"\n{result['file']}")
+            print(f"Coverage: {result['coverage']:.1f}%")
+            print("-" * 50)
+
+            for elem in result['missing']:
+                total_missing += 1
+                suggestion = suggest_selector(elem['element'], elem['attributes'], result['file'])
+                print(f"  Line {elem['line']}: <{elem['element']}> missing data-cy")
+                print(f"    Suggestion: data-cy={{sel('{suggestion}')}}")
+
+        total_with += len(result['has_selector'])
+
+    print("\n" + "=" * 70)
+    print(f"SUMMARY")
+    print("-" * 70)
+    print(f"Files scanned: {len(results)}")
+    print(f"Elements with data-cy: {total_with}")
+    print(f"Elements missing data-cy: {total_missing}")
+
+    if total_missing + total_with > 0:
+        coverage = total_with / (total_missing + total_with) * 100
+        print(f"Overall coverage: {coverage:.1f}%")
+    print("=" * 70 + "\n")
+
+
+def print_markdown_report(results: List[Dict]):
+    """Print markdown report."""
+    print("# Missing data-cy Attributes Report\n")
+
+    total_missing = sum(len(r['missing']) for r in results)
+    total_with = sum(len(r['has_selector']) for r in results)
+
+    print(f"**Files scanned:** {len(results)}")
+    print(f"**Elements with data-cy:** {total_with}")
+    print(f"**Elements missing data-cy:** {total_missing}\n")
+
+    for result in results:
+        if result['missing']:
+            print(f"## {result['file']}\n")
+            print(f"Coverage: {result['coverage']:.1f}%\n")
+            print("| Line | Element | Suggested Selector |")
+            print("|------|---------|-------------------|")
+
+            for elem in result['missing']:
+                suggestion = suggest_selector(elem['element'], elem['attributes'], result['file'])
+                print(f"| {elem['line']} | `<{elem['element']}>` | `{suggestion}` |")
+
+            print("")
+
+
+def print_json_report(results: List[Dict]):
+    """Print JSON report."""
+    output = {
+        'summary': {
+            'files_scanned': len(results),
+            'total_missing': sum(len(r['missing']) for r in results),
+            'total_with_selector': sum(len(r['has_selector']) for r in results),
+        },
+        'files': []
+    }
+
+    for result in results:
+        if result['missing']:
+            file_data = {
+                'path': result['file'],
+                'coverage': result['coverage'],
+                'missing': []
+            }
+            for elem in result['missing']:
+                file_data['missing'].append({
+                    'line': elem['line'],
+                    'element': elem['element'],
+                    'suggestion': suggest_selector(elem['element'], elem['attributes'], result['file'])
+                })
+            output['files'].append(file_data)
+
+    print(json.dumps(output, indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Find elements missing data-cy')
+    parser.add_argument('--path', required=True, help='Directory to scan')
+    parser.add_argument('--format', choices=['text', 'json', 'markdown'], default='text')
+    parser.add_argument('--output', help='Output file (default: stdout)')
+
+    args = parser.parse_args()
+
+    # Find files
+    files = find_tsx_files(args.path)
+
+    if not files:
+        print(f"No .tsx files found in {args.path}")
+        return 1
+
+    # Analyze files
+    results = [analyze_file(f) for f in files]
+
+    # Output
+    if args.output:
+        original_stdout = sys.stdout
+        sys.stdout = open(args.output, 'w')
+
+    if args.format == 'json':
+        print_json_report(results)
+    elif args.format == 'markdown':
+        print_markdown_report(results)
+    else:
+        print_text_report(results)
+
+    if args.output:
+        sys.stdout.close()
+        sys.stdout = original_stdout
+        print(f"Report written to {args.output}")
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())