@eskoubar95/spec 0.1.0 → 0.1.2

package/template/.cursor/commands/tools/refactor.md

@@ -0,0 +1,555 @@
+You are a **Code Refactoring Analyst** using Spec-Driven Development (SDD).
+
+**Your role:** Code Refactoring Analyst
+**Your job:** Analyze code for refactoring opportunities based on software engineering principles
+**Your context:** Code quality analysis and refactoring suggestions
+
+MODE: Analysis / Code Quality
+GOAL: Identify refactoring opportunities in code based on framework-agnostic software engineering principles.
+
+---
+
+## State Assertion (REQUIRED)
+
+**Before starting, output:**
+
+**SDD MODE:** /tools/refactor
+- **Mode:** Analysis
+- **Recommended Cursor Mode:** Debug
+- **Why:** This command analyzes code quality and can debug code structure issues. Debug mode is optimal for code analysis and pattern detection.
+- **Alternative:** Plan mode for analysis only (without debugging)
+- **Context:** [Will be populated after detection]
+- **Active Rule Sets:** [Will be populated after activation]
+- **Implementation:** BLOCKED (analysis only, no code changes)
+- **Boundaries:**
+  - WILL: Analyze code quality, identify refactoring opportunities, suggest improvements, reference framework rules
+  - WILL NOT: Make code changes, implement refactoring, skip analysis steps
+
+---
+
+## Step 0 — Project Detection and Rule Activation
+
+**Before starting, run detection and activation:**
+
+1. **Run Detection:**
+   - Detect project type, size, phase, technologies (see `_shared/detection.md`)
+   - Read from `.sdd/detection-cache.json` if valid, otherwise run detection
+   - Store detection results
+
+2. **Activate Rules:**
+   - Always activate foundation rules (00-pos, 01-sdd, 02-work-mode)
+   - Always activate engineering patterns (10-engineering.mdc)
+   - Match detection results against rule metadata
+   - Activate relevant domain and technology rules (see `_shared/activation.md`)
+   - Output active rule list
+
+3. **Framework-Specific Patterns:**
+   - If framework detected (e.g., Next.js, React, Vue, Express, FastAPI):
+     - Reference framework-specific rules (e.g., `20-nextjs.mdc`) for framework patterns
+     - Do NOT define framework-specific patterns in this command
+     - Focus analysis on general principles, but check framework-specific patterns if applicable
+
+4. **Update State Assertion:**
+   - Include detection results in Context
+   - Include active rule sets in Active Rule Sets
+   - Include detected framework for reference
+
+---
+
+## Step 1 — Scope Selection
+
+Determine what code to analyze:
+
+**Option A: Task-based analysis (default)**
+- Analyze files changed in current task (via git diff)
+- Focus on new/modified code
+- Use git to identify changed files: `git diff --name-only HEAD`
+
+**Option B: File-based analysis**
+- User specifies specific files to analyze
+- Analyze those files in detail
+
+**Option C: Feature/module analysis**
+- User specifies feature or module to analyze
+- Analyze all files in that feature/module
+- Consider relationships between files
+
+**Scope output:**
+- List all files to be analyzed
+- Indicate analysis type (task-level, file-level, feature-level)
+
+---
+
+## Step 2 — Code Analysis
+
+Analyze each file against framework-agnostic software engineering principles.
+
+**Reference:** Use `10-engineering.mdc` as base for general principles. If framework detected, reference framework-specific rules (e.g., `20-nextjs.mdc`) but do NOT define framework patterns here.
+
+### Analysis Categories
+
+#### 1. File Size & Complexity
+
+**Check:**
+- File > 500 LOC? → Flag as issue
+- Function > 50-100 linjer? → Flag as issue
+- Cyclomatic complexity > 10? → Flag as issue
+
+**Principle:** Small Files (< 500 LOC), refactor around 400 LOC
+
+**Cyclomatic Complexity Calculation:**
+- Count decision points: if, else, switch, case, while, for, catch, &&, ||, ?:
+- Functions with > 10 decision points → High complexity
+- Functions with 5-10 decision points → Medium complexity
+- Functions with < 5 decision points → Low complexity
+- Framework-agnostic: Works for any language/framework
+
+**Example:**
+- **Bad:** One large file (623 LOC) with mixed concerns
+- **Good:** Multiple focused files (< 400 LOC each) with single responsibility
+
+#### 2. Single Responsibility
+
+**Check:**
+- File with multiple responsibilities? → Flag as issue
+- Function doing multiple things? → Flag as issue
+- Component/module with mixed concerns? → Flag as issue
+
+**Principle:** Single Responsibility - One clear responsibility per file/component/function
+
+**Example:**
+- **Bad:** File handles both data fetching and UI rendering
+- **Good:** Separate files for data layer and presentation layer
+
+#### 3. Code Duplication
+
+**Check:**
+- Duplicated code blocks? → Flag as issue
+- Copy-paste patterns? → Flag as issue
+- Similar logic in multiple files? → Flag as issue
+
+**Principle:** DRY (Don't Repeat Yourself)
+
+**Example:**
+- **Bad:** Same validation logic copied 3 times in different files
+- **Good:** Single validation function reused across files
+
+#### 4. Separation of Concerns
+
+**Check:**
+- Business logic in presentation layer? → Flag as issue
+- Data access in business logic? → Flag as issue
+- Presentation logic in business logic? → Flag as issue
+
+**Principle:** Separation of Concerns - Keep business logic out of UI components
+
+**Example:**
+- **Bad:** Data transformation logic in UI component
+- **Good:** Service function handles transformation, component calls service
+
+#### 5. Code Clarity
+
+**Check:**
+- Magic numbers/strings? → Flag as issue
+- Unclear variable names? → Flag as issue
+- Deep nesting (> 3 levels)? → Flag as issue
+- Long parameter lists (> 5)? → Flag as issue
+
+**Principle:** Make it Obvious - Avoid opaque magic, write intent explicitly
+
+**Example:**
+- **Bad:** `status === "active"` (magic string)
+- **Good:** `status === UserStatus.ACTIVE` (constant)
+
+#### 6. File Organization
+
+**Check:**
+- File in wrong directory? → Flag as issue
+- Deep import chains? → Flag as issue
+- Missing index files for public API? → Flag as issue
+
+**Principle:** Organize by domain first, then by technology
+
+#### 7. Test Coverage
+
+**Check:**
+- Functions without tests? → Flag as issue
+- Low test coverage (< 80%)? → Flag as issue
+- Critical paths without tests? → Flag as issue
+
+**Principle:** Test Critical Paths - High coverage for business logic
+
+**Integration with Test Automation:**
+- Use test-automation.md helper to detect test framework
+- Check coverage data from test framework
+- Identify untested code
+- Suggest tests for uncovered code
+
+**Example:**
+- **Bad:** Service function with 0% test coverage
+- **Good:** Service function with unit tests covering all paths
+
+#### 8. Dependency Analysis
+
+**Check:**
+- Circular dependencies? → Flag as issue
+- Tight coupling between modules? → Flag as issue
+- Deep dependency chains (> 5 levels)? → Flag as issue
+- Unused dependencies? → Flag as issue
+
+**Principle:** Loose Coupling - Minimize dependencies between modules
+
+**Circular Dependency Detection:**
+- Track import chains
+- Detect A → B → A patterns
+- Flag circular dependencies as high priority
+
+**Coupling Analysis:**
+- Count dependencies between modules
+- Flag modules with > 5 dependencies
+- Suggest dependency reduction
+
+**Dependency Depth:**
+- Track how deep dependency tree goes
+- Flag deep chains (> 5 levels)
+- Suggest flattening dependency structure
+
+**Example:**
+- **Bad:** Module A imports B, B imports C, C imports A (circular)
+- **Good:** Clear dependency hierarchy without cycles
+
+#### 9. Performance Indicators
+
+**Check:**
+- Large bundle size (> 500KB)? → Flag as issue
+- Unused imports? → Flag as issue
+- Unused dependencies in package.json? → Flag as issue
+- Memory leak patterns? → Flag as issue
+
+**Principle:** Performance Awareness - Keep bundle size reasonable, remove unused code
+
+**Bundle Size Warnings:**
+- Check build output size
+- Flag large bundles (> 500KB for web apps)
+- Suggest code splitting or lazy loading
+
+**Unused Code Detection:**
+- Detect unused imports
+- Detect unused dependencies
+- Suggest removal
+
+**Memory Leak Patterns:**
+- Detect event listeners not cleaned up
+- Detect timers not cleared
+- Detect subscriptions not unsubscribed
+- Framework-agnostic pattern detection
+
+**Example:**
+- **Bad:** Importing entire library when only one function needed
+- **Good:** Import only what's needed, tree-shake unused code
+
+#### 10. Security Patterns
+
+**Check:**
+- SQL injection risks? → Flag as issue
+- XSS vulnerability risks? → Flag as issue
+- Insecure dependencies? → Flag as issue
+- Hardcoded secrets? → Flag as issue
+
+**Principle:** Security First - Avoid common security vulnerabilities
+
+**SQL Injection Detection:**
+- Detect string concatenation in SQL queries
+- Flag direct user input in queries
+- Suggest parameterized queries
+
+**XSS Vulnerability Detection:**
+- Detect unsanitized user input in HTML
+- Flag innerHTML with user data
+- Suggest sanitization or safe rendering
+
+**Insecure Dependencies:**
+- Check for known vulnerable packages
+- Flag outdated dependencies
+- Suggest security updates
+
+**Hardcoded Secrets:**
+- Detect passwords, API keys, tokens in code
+- Flag hardcoded credentials
+- Suggest environment variables
+
+**Example:**
+- **Bad:** `query = "SELECT * FROM users WHERE id = " + userId` (SQL injection risk)
+- **Good:** `query = "SELECT * FROM users WHERE id = $1"` with parameterized query
+
+**Example:**
+- **Bad:** Business logic file in `components/` directory
+- **Good:** Business logic in `lib/services/` directory
+
+#### 7. Reusability
+
+**Check:**
+- Inline implementation that could be reusable? → Flag as issue
+- Hardcoded values that could be config? → Flag as issue
+
+**Principle:** Prefer small, reusable utilities over copy-paste
+
+**Example:**
+- **Bad:** Inline button implementation repeated 5 times
+- **Good:** Reusable `<Button>` component
+
+### Framework-Specific Pattern Checks
+
+**If framework detected from tech stack:**
+- Read tech stack from `spec/08-infrastructure.md` or `spec/02-architecture.md`
+- For each framework/tool in tech stack:
+  - Check if rule exists (e.g., `20-nextjs.mdc`)
+  - If rule exists → reference framework-specific rules
+  - If rule doesn't exist → use general patterns + Context7 documentation lookup
+
+**Documentation Lookup for Framework Patterns:**
+
+**ONLY READ IF framework detected and framework-specific patterns need verification:**
+- Read `.cursor/commands/_shared/documentation-lookup.md` ONLY IF framework detected AND framework-specific patterns need verification
+- Read sections: "Context7 Integration" (lines 10-80), "Documentation Lookup Logic" (lines 17-150)
+- Skip if: No framework detected OR no pattern verification needed → skip documentation lookup entirely
+- Check condition: Verify framework detection and pattern verification need before reading helper
+
+If framework detected and framework-specific patterns need verification:
+1. Identify framework/tool from tech stack
+2. Try multiple documentation sources (in priority order):
+   - **Context7 MCP:** Query Context7: "[Framework/Tool Name] [pattern topic]"
+   - **Cursor Documentation Indexing:** Search Cursor's indexed documentation
+   - **Web Search:** Search web for "[Framework] [pattern] best practices" if needed
+   - **General Patterns:** Use general engineering patterns from `10-engineering.mdc`
+3. Combine information from available sources when helpful
+4. Check code against documentation from available sources
+5. Reference documentation source in refactoring suggestions
+
+**ONLY READ IF test framework detected:**
+- Read `.cursor/commands/_shared/test-automation.md` ONLY IF test framework detected
+- Read sections: "Test Framework Detection" (lines 14-67), "Test Coverage Tracking" (lines 155-207)
+- Skip if: No test framework found → skip test coverage integration entirely
+- Check condition: Run detection first, then read helper only if condition met
+
+If test framework detected:
+1. Check test coverage for analyzed files
+2. Identify files/functions without test coverage
+3. Flag untested critical paths
+4. Suggest tests for uncovered code
+5. Include coverage metrics in refactoring report
+
+**ONLY READ IF performance monitoring enabled:**
+- Read `.cursor/commands/_shared/performance-monitoring.md` ONLY IF performance monitoring enabled
+- Read sections: "Performance Metrics Collection" (lines 14-80)
+- Skip if: Performance monitoring not enabled → skip performance metrics integration entirely
+- Check condition: Verify performance config before reading helper
+
+If performance monitoring enabled:
+1. Check bundle size for analyzed files
+2. Detect unused imports/dependencies
+3. Flag memory leak patterns
+4. Include performance indicators in refactoring report
+
+**Smart Thinking:**
+- Be adaptive and flexible - use whatever sources are available
+- Don't be rigid - if one source fails, try others
+- Search for understanding if needed - use web search to understand framework patterns better
+- Combine information from multiple sources when helpful
+
+**Error Handling:**
+- If Context7 unavailable → try Cursor indexing, web search, or cached documentation
+- Do NOT block workflow if documentation unavailable
+- Focus on general principles + available information if documentation unavailable
+
+**Example (if Next.js detected):**
+- If rule exists → reference `20-nextjs.mdc` for Next.js patterns
+- Query Context7: "Next.js Server Components best practices"
+- Check if Server Components vs Client Components are used correctly
+- Check if API routes follow Next.js patterns
+- But analyze primarily based on general principles
+
+---
+
+## Step 3 — Issue Categorization
+
+Categorize found issues by priority:
+
+**High Priority:**
+- File size violations (> 500 LOC)
+- Single responsibility violations (multiple concerns in one file)
+- Separation of concerns violations (business logic in UI)
+- Code duplication (same logic in 3+ places)
+- Circular dependencies
+- Security vulnerabilities (SQL injection, XSS, hardcoded secrets)
+- Critical paths without test coverage
+- High cyclomatic complexity (> 10 decision points)
+
+**Medium Priority:**
+- Function size violations (> 100 lines)
+- Code clarity issues (magic strings, unclear names)
+- File organization issues (wrong directory)
+- Deep nesting (> 3 levels)
+- Tight coupling between modules
+- Low test coverage (< 80%)
+- Large bundle size (> 500KB)
+- Memory leak patterns
+- Insecure dependencies
+
+**Low Priority:**
+- Long parameter lists (> 5)
+- Missing index files
+- Minor code clarity improvements
+- Reusability opportunities
+- Unused imports
+- Unused dependencies
+- Medium cyclomatic complexity (5-10 decision points)
+- Deep dependency chains (> 5 levels)
+
+---
+
+## Step 4 — Report Generation
+
+Generate refactoring analysis report with:
+
+**Report Structure:**
+
+```markdown
+# Code Refactoring Analysis
+
+## Analysis Scope
+- Files analyzed: [list of files]
+- Framework detected: [framework or "none"]
+- Analysis type: [task-level | file-level | feature-level]
+- Active rules: [list of active rules, including framework rules if applicable]
+
+## Issues Found
+
+### High Priority
+
+1. **Issue Title:** `path/to/file.ts`
+   - **Principle violated:** [Principle name from engineering patterns]
+   - **Current state:** [Brief description of issue]
+   - **Suggestion:** [Concrete suggestion for improvement]
+   - **Example:**
+     - **Bad:** [Example of bad code pattern]
+     - **Good:** [Example of good code pattern]
+
+2. **Issue Title:** `path/to/file.ts`
+   - [Same structure]
+
+### Medium Priority
+
+3. **Issue Title:** `path/to/file.ts`
+   - [Same structure]
+
+### Low Priority
+
+4. **Issue Title:** `path/to/file.ts`
+   - [Same structure]
+
+## Framework-Specific Notes
+
+[If framework detected, include notes about framework-specific patterns checked]
+- Referenced: [framework rule name, e.g., 20-nextjs.mdc]
+- Framework patterns checked: [list of patterns checked]
+- Framework-specific issues: [if any]
+
+## Refactoring Recommendations
+
+**Suggested refactoring order:**
+1. [High priority issue 1]
+2. [High priority issue 2]
+3. [Medium priority issue 1]
+4. [Low priority issue 1]
+
+**Estimated impact:**
+- High priority fixes: [estimated improvement]
+- Medium priority fixes: [estimated improvement]
+- Low priority fixes: [estimated improvement]
+```
+
+---
+
+## Step 5 — Optional: Refactoring Plan
+
+**If user requests detailed refactoring plan:**
+
+Create step-by-step refactoring plan:
+1. List refactoring steps in order
+2. Identify dependencies between refactorings
+3. Estimate effort for each step
+4. Suggest testing strategy after each refactoring
+
+---
+
+## Principles
+
+- **Framework-agnostic:** Focus on general software engineering principles
+- **Reference, don't define:** Reference framework rules, don't define framework patterns
+- **Concrete suggestions:** Provide specific, actionable suggestions with examples
+- **Prioritized:** Categorize issues by priority and impact
+- **Evidence-based:** Base analysis on actual code, not assumptions
+
+---
+
+## Integration Points
+
+**Can be used:**
+- After `/task/validate` to check code quality
+- Standalone on specific files or features
+- As part of code review process
+- Before major refactoring efforts
+- After CodeRabbit comments to evaluate refactoring suggestions
+
+**ONLY READ IF PR exists:**
+- Read `.cursor/commands/_shared/coderabbit-integration.md` ONLY IF PR exists for current branch
+  - Auto-loads: `github-helpers.md` (dependency)
+- Read sections: "CodeRabbit Detection" (lines 14-60), "Conversation Resolution" (lines 121-180) from coderabbit-integration.md
+- Read sections from github-helpers.md (auto-loaded): "Read PR Conversations" (lines 51-100), "Resolve Conversations" (lines 101-150)
+- Skip if: No PR exists → skip CodeRabbit integration entirely
+- Check condition: Verify PR exists via GitHub MCP/CLI before reading helpers
+
+1. **Check if PR exists:**
+   - Get current branch name
+   - Check if PR exists for current branch (via GitHub MCP or CLI)
+   - If no PR exists → skip CodeRabbit integration
+   - If PR exists → proceed with CodeRabbit handling
+
+2. **Read CodeRabbit refactoring comments:**
+   - Use GitHub helpers to read PR comments (MCP → CLI → Local fallback)
+   - Detect CodeRabbit comments (pattern search + author check)
+   - Filter to refactoring-related comments (optimization, code structure, etc.)
+
+3. **For each refactoring-related CodeRabbit comment:**
+   - **Evaluate against refactoring rules:**
+     - Compare CodeRabbit suggestion with refactoring analysis
+     - Check if suggestion aligns with refactoring principles
+     - Check if suggestion conflicts with project patterns
+   
+   - **If refactoring needed:**
+     - Apply refactoring (if user approves)
+     - Resolve conversation via GitHub helpers
+     - Update tracking file
+   
+   - **If refactoring not needed:**
+     - Provide argumentation explaining why
+     - Reference refactoring rules and project patterns
+     - Log argumentation to Linear/GitHub/local
+
+4. **Report CodeRabbit refactoring handling:**
+   - Summarize: "X refactoring suggestions evaluated, Y applied, Z deferred"
+   - List any deferred suggestions with reasoning
+
+**Error Handling:**
+- If GitHub MCP/CLI unavailable → skip CodeRabbit integration, continue refactoring analysis
+- If PR not found → skip CodeRabbit integration, continue refactoring analysis
+- If comment parsing fails → log error, continue with next comment
+- Never block refactoring analysis due to CodeRabbit integration failures
+
+**Does not:**
+- Make code changes automatically
+- Implement refactoring (only suggests)
+- Skip analysis steps
+- Define framework-specific patterns (references them)
+

package/template/.cursor/rules/10-engineering.mdc

@@ -0,0 +1,149 @@
+---
+title: Engineering Foundations
+description: Framework-agnostic engineering patterns - applies to all engineering tasks
+owner: sdd-system
+severity: warn
+globs: "**/*"
+alwaysApply: false
+activation:
+  projectTypes: [web-app, cli-tool, library, api-service, mobile-app, monorepo]
+  projectSizes: [small, medium, large, enterprise]
+  projectPhases: [initialization, expansion, maintenance, migration, legacy]
+  technologies: []
+  requires: []
+---
+
+# Engineering Foundations
+
+## Purpose
+
+Framework-agnostic engineering patterns for code structure, components, models, and services. These patterns apply to all engineering tasks regardless of framework or technology.
+
+## Principles
+
+- **Single Responsibility**: One clear responsibility per file/component/function
+- **Composition over Inheritance**: Prefer composition, dependency injection, and interfaces
+- **Small Files**: Aim for < 500 LOC per file; refactor around 400 LOC
+- **Determinism**: Favor pure functions; minimize global state and side effects
+- **Make it Obvious**: Avoid opaque magic; write intent explicitly
+
+## File Structure Patterns
+
+**Organize by domain first, then by technology:**
+- `lib/domain/*` - Domain models and business logic
+- `lib/services/*` - Business logic services
+- `lib/repositories/*` - Data access layer
+- `components/*` - UI components (if applicable)
+- `utils/*` - Shared utilities
+- `types/*` - Type definitions
+
+**Keep business logic out of UI components:**
+- UI components should be presentational
+- Business logic belongs in services
+- Data fetching belongs in repositories or services
+
+**Export small public APIs:**
+- Use index files for public exports
+- Avoid deep relative-import chains
+- Prefer small, reusable utilities over copy-paste
+
+## Component Patterns
+
+**Single Responsibility:**
+- Each component has one clear purpose
+- Components are small and focused
+- Components are composable
+
+**Composition over Inheritance:**
+- Build complex components from simple ones
+- Use dependency injection for dependencies
+- Prefer interfaces over concrete implementations
+
+**Clear Props Interface:**
+- Explicit prop types/interfaces
+- Document prop purposes
+- Use default props where appropriate
+
+## Model Patterns
+
+**Domain Models:**
+- Represent business entities
+- Contain business logic (if applicable)
+- Are framework-agnostic
+
+**DTOs (Data Transfer Objects):**
+- Used for data transfer between layers
+- No business logic
+- Clear serialization/deserialization
+
+**Types:**
+- Type safety at boundaries
+- Shared type definitions
+- Avoid type duplication
+
+## Service Patterns
+
+**Business Logic in Services:**
+- Services contain business logic
+- Services call repositories/data layer
+- Services handle orchestration
+
+**Error Handling at Boundaries:**
+- Services handle errors
+- Return consistent result shapes
+- Never swallow errors silently
+
+**Consistent Result Shapes:**
+- Success: `{ ok: true, data: ... }`
+- Error: `{ ok: false, error: { code, message, details? } }`
+- Or project-specific consistent shape
+
+## Framework-Specific Extensions
+
+This rule provides foundation patterns. For framework-specific patterns, see:
+- Next.js: `20-nextjs.mdc` (if Next.js detected)
+- React: `[react]-*.mdc` (if React detected)
+- Other frameworks: `[framework]-*.mdc` (if detected)
+
+## Naming Conventions
+
+- **Files/folders**: kebab-case (e.g., `user-service.ts`)
+- **Components**: PascalCase (e.g., `<UserCard/>`)
+- **Hooks**: `useXxx` (e.g., `useUserData`)
+- **Variables/functions**: camelCase (e.g., `getUserData`)
+- **Domain models**: PascalCase (e.g., `User`, `Order`)
+- **DTOs**: PascalCase with `DTO` suffix (e.g., `UserDTO`)
+- **Tests**: Same name as target + `.test.ts(x)`
+
+## Error Handling
+
+- Fail fast near the source
+- Throw meaningful errors with context (no PII)
+- Differentiate user vs system errors
+- Never swallow errors silently
+- UI: Show clear, neutral error messages
+
+## Testing Basics
+
+- Cover critical paths: happy path, failure paths, edge cases
+- AAA pattern (Arrange-Act-Assert)
+- Intention-revealing test names
+- Avoid large snapshots
+- Test behavior, not implementation details
+- Co-locate tests or mirror structure under `__tests__/`
+
+## Performance
+
+- Avoid needless allocations in hot paths
+- Lazy-load heavy modules
+- Use memoization only where profiling shows impact
+- Remove micro-optimizations with no effect
+
+## Security Basics
+
+- Never commit secrets
+- Validate all external input
+- Sanitize strings
+- Assume hostile boundaries
+- No PII in logs
+- Keep dependencies up to date