@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/skills/i18n-nextintl/scripts/extract-hardcoded.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""
+Extract Hardcoded Strings Script
+
+Finds hardcoded user-facing strings in React/TypeScript components that should
+be translated using next-intl.
+
+Usage:
+    python extract-hardcoded.py --path PATH [--dry-run]
+
+Options:
+    --path PATH     Path to scan for hardcoded strings
+    --dry-run       Preview findings without file details
+    --ignore-tests  Skip test files (*.test.*, *.spec.*, *.cy.*)
+"""
+
+import os
+import re
+import sys
+import argparse
+from pathlib import Path
+from typing import List, Dict, Tuple
+
+
+def get_active_theme() -> str:
+    """Get active theme from environment or default."""
+    return os.environ.get('NEXT_PUBLIC_ACTIVE_THEME', 'default')
+
+
+def should_ignore_file(file_path: str, ignore_tests: bool) -> bool:
+    """Check if file should be ignored."""
+    ignore_patterns = [
+        'node_modules',
+        '.next',
+        'dist',
+        '.git',
+        '__pycache__',
+        'messages/',  # Translation files themselves
+        '.json',
+        '.md',
+        '.css',
+        '.scss',
+    ]
+
+    if ignore_tests:
+        ignore_patterns.extend(['.test.', '.spec.', '.cy.'])
+
+    for pattern in ignore_patterns:
+        if pattern in file_path:
+            return True
+
+    return False
+
+
+def extract_jsx_strings(content: str, file_path: str) -> List[Dict]:
+    """Extract potential hardcoded strings from JSX/TSX content."""
+    findings = []
+
+    # Pattern 1: Strings in JSX text content (between > and <)
+    # Matches: >Hello World< but not >{variable}<
+    jsx_text_pattern = r'>([A-Z][^<>{}\n]{2,})<'
+    for match in re.finditer(jsx_text_pattern, content):
+        text = match.group(1).strip()
+        if text and not text.startswith('{') and len(text) > 2:
+            line_num = content[:match.start()].count('\n') + 1
+            findings.append({
+                'type': 'jsx_text',
+                'text': text[:80] + ('...' if len(text) > 80 else ''),
+                'line': line_num,
+                'file': file_path,
+                'suggestion': suggest_key(text)
+            })
+
+    # Pattern 2: Hardcoded strings in common props (title, placeholder, label, etc.)
+    prop_patterns = [
+        (r'title=["\']([^"\']+)["\']', 'title_prop'),
+        (r'placeholder=["\']([^"\']+)["\']', 'placeholder_prop'),
+        (r'label=["\']([^"\']+)["\']', 'label_prop'),
+        (r'alt=["\']([^"\']+)["\']', 'alt_prop'),
+        (r'aria-label=["\']([^"\']+)["\']', 'aria_label_prop'),
+        (r'description=["\']([^"\']+)["\']', 'description_prop'),
+    ]
+
+    for pattern, prop_type in prop_patterns:
+        for match in re.finditer(pattern, content, re.IGNORECASE):
+            text = match.group(1).strip()
+            # Skip if it looks like a variable or translation key
+            if text and not text.startswith('{') and not is_likely_non_text(text):
+                line_num = content[:match.start()].count('\n') + 1
+                findings.append({
+                    'type': prop_type,
+                    'text': text[:60] + ('...' if len(text) > 60 else ''),
+                    'line': line_num,
+                    'file': file_path,
+                    'suggestion': suggest_key(text)
+                })
+
+    # Pattern 3: String literals that look like user-facing text
+    # This catches: const message = "Welcome back!"
+    string_literal_pattern = r'(?:const|let|var)\s+\w+\s*=\s*["\']([A-Z][^"\']{5,})["\']'
+    for match in re.finditer(string_literal_pattern, content):
+        text = match.group(1).strip()
+        if not is_likely_non_text(text):
+            line_num = content[:match.start()].count('\n') + 1
+            findings.append({
+                'type': 'string_literal',
+                'text': text[:60] + ('...' if len(text) > 60 else ''),
+                'line': line_num,
+                'file': file_path,
+                'suggestion': suggest_key(text)
+            })
+
+    return findings
+
+
+def is_likely_non_text(text: str) -> bool:
+    """Check if string is likely NOT user-facing text."""
+    # Skip URLs, paths, technical strings
+    non_text_indicators = [
+        text.startswith('http'),
+        text.startswith('/'),
+        text.startswith('@'),
+        text.startswith('#'),
+        '.com' in text,
+        '.org' in text,
+        text.isupper() and '_' in text,  # Constants like API_URL
+        len(text.split()) == 1 and text.islower(),  # Single lowercase word
+        re.match(r'^[a-z-]+$', text),  # kebab-case identifiers
+        re.match(r'^[a-zA-Z]+\.[a-zA-Z.]+$', text),  # Dot notation
+    ]
+    return any(non_text_indicators)
+
+
+def suggest_key(text: str) -> str:
+    """Suggest a translation key based on the text."""
+    # Take first few words, convert to camelCase
+    words = re.sub(r'[^a-zA-Z\s]', '', text).lower().split()[:4]
+    if not words:
+        return 'common.text'
+
+    # Convert to camelCase
+    key = words[0] + ''.join(w.title() for w in words[1:])
+    return f'common.{key}'
+
+
+def scan_directory(path: str, ignore_tests: bool) -> List[Dict]:
+    """Scan directory for hardcoded strings."""
+    all_findings = []
+    path_obj = Path(path)
+
+    if path_obj.is_file():
+        files = [path_obj]
+    else:
+        files = list(path_obj.rglob('*.tsx')) + list(path_obj.rglob('*.ts'))
+
+    for file_path in files:
+        str_path = str(file_path)
+        if should_ignore_file(str_path, ignore_tests):
+            continue
+
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+
+            # Skip files that already use translations properly
+            if 'useTranslations' in content or 'getTranslations' in content:
+                # Still check for any remaining hardcoded strings
+                pass
+
+            findings = extract_jsx_strings(content, str_path)
+            all_findings.extend(findings)
+
+        except Exception as e:
+            print(f"Warning: Could not read {file_path}: {e}")
+
+    return all_findings
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Find hardcoded strings')
+    parser.add_argument('--path', required=True, help='Path to scan')
+    parser.add_argument('--dry-run', action='store_true', help='Preview without details')
+    parser.add_argument('--ignore-tests', action='store_true', help='Skip test files')
+
+    args = parser.parse_args()
+
+    if not os.path.exists(args.path):
+        print(f"Error: Path not found: {args.path}")
+        return 1
+
+    print(f"\n{'=' * 60}")
+    print(f"SCANNING FOR HARDCODED STRINGS")
+    print(f"{'=' * 60}")
+    print(f"Path: {args.path}")
+    print(f"Ignore tests: {args.ignore_tests}")
+    print(f"{'=' * 60}\n")
+
+    findings = scan_directory(args.path, args.ignore_tests)
+
+    if not findings:
+        print("No hardcoded strings found.")
+        return 0
+
+    # Group by file
+    by_file: Dict[str, List[Dict]] = {}
+    for finding in findings:
+        file_path = finding['file']
+        if file_path not in by_file:
+            by_file[file_path] = []
+        by_file[file_path].append(finding)
+
+    print(f"Found {len(findings)} potential hardcoded strings in {len(by_file)} files:\n")
+
+    if args.dry_run:
+        # Summary only
+        for file_path, file_findings in sorted(by_file.items()):
+            rel_path = os.path.relpath(file_path)
+            print(f"  {rel_path}: {len(file_findings)} findings")
+    else:
+        # Detailed output
+        for file_path, file_findings in sorted(by_file.items()):
+            rel_path = os.path.relpath(file_path)
+            print(f"\n{'-' * 60}")
+            print(f"FILE: {rel_path}")
+            print(f"{'-' * 60}")
+
+            for finding in file_findings:
+                print(f"  Line {finding['line']}: [{finding['type']}]")
+                print(f"    Text: \"{finding['text']}\"")
+                print(f"    Suggested key: {finding['suggestion']}")
+                print()
+
+    print(f"\n{'=' * 60}")
+    print(f"SUMMARY: {len(findings)} hardcoded strings in {len(by_file)} files")
+    print(f"{'=' * 60}")
+    print("\nTo fix:")
+    print("  1. Import useTranslations: import { useTranslations } from 'next-intl'")
+    print("  2. Add translations to core/messages/{locale}/ or theme messages")
+    print("  3. Replace hardcoded text with t('key')")
+    print()
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/claude/skills/i18n-nextintl/scripts/validate-translations.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""
+Validate Translations Script
+
+Compares translation files between locales to find missing keys.
+Validates EN and ES translation completeness.
+
+Usage:
+    python validate-translations.py [--theme THEME] [--strict]
+
+Options:
+    --theme THEME   Theme to validate (default: from NEXT_PUBLIC_ACTIVE_THEME or 'default')
+    --strict        Exit with error if missing keys found
+    --core-only     Only validate core messages
+    --theme-only    Only validate theme messages
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Set, Tuple
+
+
+def get_active_theme() -> str:
+    """Get active theme from environment or default."""
+    return os.environ.get('NEXT_PUBLIC_ACTIVE_THEME', 'default')
+
+
+def flatten_keys(obj: dict, prefix: str = '') -> Set[str]:
+    """Flatten nested dict to set of dot-notation keys."""
+    keys = set()
+    for key, value in obj.items():
+        full_key = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, dict):
+            keys.update(flatten_keys(value, full_key))
+        else:
+            keys.add(full_key)
+    return keys
+
+
+def load_json_file(file_path: Path) -> dict:
+    """Load JSON file and return dict."""
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            return json.load(f)
+    except FileNotFoundError:
+        return {}
+    except json.JSONDecodeError as e:
+        print(f"  Warning: Invalid JSON in {file_path}: {e}")
+        return {}
+
+
+def load_core_messages(locale: str) -> dict:
+    """Load core messages for a locale by combining all JSON files."""
+    core_path = Path(f'core/messages/{locale}')
+    if not core_path.exists():
+        return {}
+
+    combined = {}
+    for json_file in core_path.glob('*.json'):
+        data = load_json_file(json_file)
+        # Use filename (without extension) as namespace
+        namespace = json_file.stem
+        if namespace == 'index':
+            continue
+        combined[namespace] = data
+
+    return combined
+
+
+def load_theme_messages(theme: str, locale: str) -> dict:
+    """Load theme messages for a locale."""
+    theme_path = Path(f'contents/themes/{theme}/messages/{locale}.json')
+    return load_json_file(theme_path)
+
+
+def compare_translations(
+    en_keys: Set[str],
+    es_keys: Set[str],
+    source_name: str
+) -> Tuple[Set[str], Set[str]]:
+    """Compare EN and ES keys, return missing in each."""
+    missing_in_es = en_keys - es_keys
+    missing_in_en = es_keys - en_keys
+    return missing_in_es, missing_in_en
+
+
+def validate_core_messages() -> Tuple[int, int]:
+    """Validate core messages between EN and ES."""
+    print("\n" + "=" * 60)
+    print("VALIDATING CORE MESSAGES")
+    print("=" * 60)
+
+    en_messages = load_core_messages('en')
+    es_messages = load_core_messages('es')
+
+    if not en_messages:
+        print("  Warning: No English core messages found at core/messages/en/")
+        return 0, 0
+
+    en_keys = flatten_keys(en_messages)
+    es_keys = flatten_keys(es_messages)
+
+    print(f"  EN keys: {len(en_keys)}")
+    print(f"  ES keys: {len(es_keys)}")
+
+    missing_in_es, missing_in_en = compare_translations(en_keys, es_keys, "core")
+
+    total_missing = len(missing_in_es) + len(missing_in_en)
+
+    if missing_in_es:
+        print(f"\n  Missing in ES ({len(missing_in_es)}):")
+        for key in sorted(missing_in_es)[:20]:
+            print(f"    - {key}")
+        if len(missing_in_es) > 20:
+            print(f"    ... and {len(missing_in_es) - 20} more")
+
+    if missing_in_en:
+        print(f"\n  Extra in ES (not in EN) ({len(missing_in_en)}):")
+        for key in sorted(missing_in_en)[:10]:
+            print(f"    - {key}")
+        if len(missing_in_en) > 10:
+            print(f"    ... and {len(missing_in_en) - 10} more")
+
+    if total_missing == 0:
+        print("\n  Core messages: COMPLETE")
+
+    return len(missing_in_es), len(missing_in_en)
+
+
+def validate_theme_messages(theme: str) -> Tuple[int, int]:
+    """Validate theme messages between EN and ES."""
+    print("\n" + "=" * 60)
+    print(f"VALIDATING THEME MESSAGES: {theme}")
+    print("=" * 60)
+
+    en_messages = load_theme_messages(theme, 'en')
+    es_messages = load_theme_messages(theme, 'es')
+
+    if not en_messages:
+        print(f"  Warning: No English theme messages found for theme '{theme}'")
+        return 0, 0
+
+    en_keys = flatten_keys(en_messages)
+    es_keys = flatten_keys(es_messages)
+
+    print(f"  EN keys: {len(en_keys)}")
+    print(f"  ES keys: {len(es_keys)}")
+
+    missing_in_es, missing_in_en = compare_translations(en_keys, es_keys, f"theme-{theme}")
+
+    total_missing = len(missing_in_es) + len(missing_in_en)
+
+    if missing_in_es:
+        print(f"\n  Missing in ES ({len(missing_in_es)}):")
+        for key in sorted(missing_in_es)[:20]:
+            print(f"    - {key}")
+        if len(missing_in_es) > 20:
+            print(f"    ... and {len(missing_in_es) - 20} more")
+
+    if missing_in_en:
+        print(f"\n  Extra in ES (not in EN) ({len(missing_in_en)}):")
+        for key in sorted(missing_in_en)[:10]:
+            print(f"    - {key}")
+        if len(missing_in_en) > 10:
+            print(f"    ... and {len(missing_in_en) - 10} more")
+
+    if total_missing == 0:
+        print("\n  Theme messages: COMPLETE")
+
+    return len(missing_in_es), len(missing_in_en)
+
+
+def check_custom_roles_in_core() -> List[str]:
+    """Check if custom roles are incorrectly defined in core messages."""
+    print("\n" + "=" * 60)
+    print("CHECKING CUSTOM ROLES POLICY")
+    print("=" * 60)
+
+    core_en = load_core_messages('en')
+    violations = []
+
+    # Custom roles that should NEVER be in core
+    forbidden_roles = ['editor', 'moderator', 'contributor', 'reviewer', 'publisher']
+
+    # Check teams.roles namespace
+    teams_roles = core_en.get('teams', {}).get('roles', {})
+    for role in forbidden_roles:
+        if role in teams_roles:
+            violations.append(f"teams.roles.{role}")
+
+    if violations:
+        print(f"\n  VIOLATION: Custom roles found in core/messages/")
+        print(f"  These should be in theme messages only:")
+        for v in violations:
+            print(f"    - {v}")
+    else:
+        print("\n  Custom roles policy: OK")
+
+    return violations
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Validate translations')
+    parser.add_argument('--theme', default=None, help='Theme to validate')
+    parser.add_argument('--strict', action='store_true', help='Exit with error if issues found')
+    parser.add_argument('--core-only', action='store_true', help='Only validate core messages')
+    parser.add_argument('--theme-only', action='store_true', help='Only validate theme messages')
+
+    args = parser.parse_args()
+
+    theme = args.theme or get_active_theme()
+
+    print(f"\n{'=' * 60}")
+    print(f"TRANSLATION VALIDATION")
+    print(f"{'=' * 60}")
+    print(f"Theme: {theme}")
+    print(f"Strict mode: {args.strict}")
+    print(f"{'=' * 60}")
+
+    total_issues = 0
+
+    # Validate core messages
+    if not args.theme_only:
+        missing_es, extra_es = validate_core_messages()
+        total_issues += missing_es
+
+        # Check custom roles policy
+        role_violations = check_custom_roles_in_core()
+        total_issues += len(role_violations)
+
+    # Validate theme messages
+    if not args.core_only:
+        missing_es, extra_es = validate_theme_messages(theme)
+        total_issues += missing_es
+
+    # Summary
+    print("\n" + "=" * 60)
+    print("SUMMARY")
+    print("=" * 60)
+
+    if total_issues == 0:
+        print("  All translations are complete!")
+        print("=" * 60 + "\n")
+        return 0
+    else:
+        print(f"  Total issues found: {total_issues}")
+        print("=" * 60 + "\n")
+
+        if args.strict:
+            print("Strict mode: Exiting with error due to missing translations")
+            return 1
+
+        return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/claude/skills/impact-analysis/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: impact-analysis
+description: |
+  Impact analysis for understanding how code changes affect the system.
+  Covers git diff analysis, entity mapping, flow identification, and regression suggestions.
+  Use this skill when analyzing branches, planning testing, or understanding change scope.
+allowed-tools: Read, Glob, Grep, Bash(git:*)
+version: 1.0.0
+---
+
+# Impact Analysis Skill
+
+Analyze the potential impact of code changes on the system.
+
+## Overview
+
+Impact analysis identifies what parts of the system may be affected by a code change. Think of it like a **domino effect** - pushing one domino (making a change) may cause others to fall.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. Git Diff                                                │
+│     ↓                                                       │
+│     Gets list of modified files                             │
+│                                                             │
+│  2. Classification                                          │
+│     ↓                                                       │
+│     Groups by type: API, UI, DB, Tests                      │
+│                                                             │
+│  3. Entity Mapping                                          │
+│     ↓                                                       │
+│     Relates files to system entities                        │
+│                                                             │
+│  4. Flow Lookup                                             │
+│     ↓                                                       │
+│     Queries registries for related flows                    │
+│                                                             │
+│  5. Suggestions                                             │
+│     ↓                                                       │
+│     Generates list of potentially affected areas            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## When to Use This Skill
+
+- Analyzing a feature branch before merge
+- Planning regression testing scope
+- Understanding the blast radius of a change
+- Identifying related tests to run
+- Code review impact assessment
+
+## Analysis Capabilities
+
+### What It CAN Identify
+
+| Capability | Example |
+|------------|---------|
+| Modified files | "5 files changed in /products" |
+| Direct dependencies | "Orders depends on Products" |
+| Existing tests | "3 tests cover this area" |
+| Documented flows | "Checkout flow uses this component" |
+| Entity relationships | "FK relationship to customers" |
+
+### What It CANNOT Identify
+
+| Limitation | Reason |
+|------------|--------|
+| Business impact | Doesn't know business rules |
+| Real severity | Cannot prioritize by criticality |
+| Undocumented dependencies | Only sees what's in code |
+| Complex side effects | Doesn't execute the code |
+| Runtime behavior | Static analysis only |
+
+## Output Format
+
+```markdown
+## Impact Analysis: feature/new-pricing
+
+### Files Modified (23 files)
+| Type | Count | Key Files |
+|------|-------|-----------|
+| API | 5 | orders/service.ts, payments/route.ts |
+| UI | 12 | CheckoutForm.tsx, OrderSummary.tsx |
+| DB | 2 | 001_add_payment_status.sql |
+| Tests | 4 | checkout.cy.ts |
+
+### Entities Affected
+- **products**: API and UI modifications
+- **orders**: Potentially affected (FK relationship)
+- **payments**: New functionality
+
+### Flows Potentially Impacted
+- Complete checkout flow
+- Order confirmation flow
+- Payment processing flow
+
+### Regression Suggestions
+| Confidence | Area | Reason |
+|------------|------|--------|
+| High | Product CRUD | Direct changes |
+| Medium | Order totals | Uses pricing |
+| Low | Sales reports | May reference products |
+
+### Related Tests
+- checkout.cy.ts (@uat, @flow-checkout)
+- orders.cy.ts (@api, @entity-orders)
+- payments.cy.ts (@api)
+```
+
+## Confidence Levels
+
+| Level | Meaning | Recommendation |
+|-------|---------|----------------|
+| **High** | Direct dependency found | Test this area |
+| **Medium** | Indirect dependency | Consider testing |
+| **Low** | Possible relationship | Evaluate with context |
+
+## Interpreting Results
+
+### Correct Interpretation
+
+- "Analysis suggests pricing is directly affected"
+- "Orders might be affected because it uses prices"
+- "Should verify with dev team about reports impact"
+
+### Incorrect Interpretation
+
+- "Analysis says I MUST test everything listed"
+- "If not in the list, there's no risk"
+- "This is the complete list of affected areas"
+
+## Complementing the Analysis
+
+Technical analysis should be complemented with:
+
+### 1. Business Knowledge
+
+- What areas are critical for the business?
+- Are there special seasons or events?
+- Which customers use these features?
+
+### 2. Bug History
+
+- Have there been bugs in these areas before?
+- Are there known "fragile" areas?
+
+### 3. Developer Conversation
+
+- What exactly changed?
+- Are there impacts the code doesn't show?
+- Are there affected external dependencies?
+
+## Usage Examples
+
+### Analyze a Branch
+
+```bash
+# Get diff from main
+git diff main...feature/checkout-v2 --name-only
+
+# Classify files
+# API: src/app/api/**
+# UI: src/components/**, src/app/(routes)/**
+# DB: migrations/**
+# Tests: cypress/**, __tests__/**
+```
+
+### Map to Entities
+
+```typescript
+// File path patterns to entities
+const entityPatterns = {
+  'entities/products': 'products',
+  'entities/orders': 'orders',
+  'api/v1/products': 'products',
+  'components/Product': 'products',
+}
+```
+
+### Lookup Related Flows
+
+```typescript
+// Query FLOW_REGISTRY for flows using affected entities
+const affectedFlows = Object.entries(FLOW_REGISTRY)
+  .filter(([_, flow]) =>
+    flow.entities.some(e => affectedEntities.includes(e))
+  )
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/impact:analyze [branch]` | Analyze branch impact |
+| `/impact:regression [feature]` | Identify regression areas |
+
+## Important Notes
+
+1. **This is a starting point** - not a definitive list
+2. **Complements human judgment** - doesn't replace it
+3. **Static analysis only** - cannot predict runtime behavior
+4. **Business context required** - you decide what's critical
+
+The analysis is an **assistance tool**. YOU decide what to test and with what priority.