@paths.design/caws-cli 10.2.0 → 11.1.0

package/dist/templates/.cursor/rules/02-quality-gates.mdc

@@ -1,368 +0,0 @@
----
-description: Comprehensive testing standards and verification requirements
-globs:
-alwaysApply: true
----
-
-# Testing Standards & Verification Requirements
-
-## Testing Pyramid Requirements
-
-### Unit Tests (Foundation Layer)
-
-- **Coverage Thresholds**: 80% line coverage, 90% branch coverage minimum
-- **Test Isolation**: Each test completely independent, no shared state
-- **Mock Strategy**: Mock external dependencies, test business logic in isolation
-- **Naming Convention**: `describe('ComponentName', () => { it('should do something', () => {}) })`
-- **Assertion Style**: Use descriptive assertions, avoid generic `toBe(true)`
-
-### Integration Tests (Middle Layer)
-
-- **Database Integration**: Real database connections, not mocked
-- **External APIs**: Test actual HTTP calls with proper error handling
-- **Component Communication**: Test inter-component contracts
-- **Setup/Teardown**: Proper database seeding and cleanup
-- **Async Handling**: All async operations properly awaited and tested
-
-### End-to-End Tests (Top Layer)
-
-- **Full User Journeys**: Complete workflows from start to finish
-- **Real Browsers**: Use actual browser automation, not mocked DOM
-- **Data Persistence**: Verify data survives application restarts
-- **Performance Baselines**: Include timing assertions where relevant
-
-## Test Quality Standards
-
-### Test Structure Requirements
-
-```typescript
-describe('ComponentName', () => {
-  describe('when condition A', () => {
-    it('should behave correctly', () => {
-      // Given: Setup preconditions
-      // When: Execute the action
-      // Then: Verify the outcome
-    });
-  });
-});
-```
-
-### Edge Case Coverage
-
-- **Null/Undefined**: Test with null, undefined, empty arrays, empty objects
-- **Boundary Values**: Test minimums, maximums, and edge boundaries
-- **Error Conditions**: Test all error paths and exception handling
-- **Concurrency**: Test race conditions and concurrent access
-- **Resource Limits**: Test memory limits, timeouts, rate limits
-
-### Test Data Management
-
-- **Realistic Fixtures**: Use representative data, not just minimal examples
-- **Factory Pattern**: Create test data factories for consistent object creation
-- **Cleanup Strategy**: Ensure tests don't leave persistent state
-- **Isolation**: Tests must not interfere with each other
-
-## Verification Requirements
-
-### Pre-Commit Verification
-
-- [ ] All unit tests pass (`npm test`)
-- [ ] No tests skipped in production code
-- [ ] Coverage thresholds met
-- [ ] No console errors or warnings in tests
-- [ ] Database tests use real connections
-
-### Integration Verification
-
-- [ ] Database schema matches migrations
-- [ ] External API contracts validated
-- [ ] Authentication/authorization tested
-- [ ] Error handling verified end-to-end
-
-### Performance Verification
-
-- [ ] Response times within documented SLAs
-- [ ] Memory usage within limits
-- [ ] Database query performance acceptable
-- [ ] Concurrent user load handled
-
-## Test Infrastructure Standards
-
-### Testing Tools & Frameworks
-
-- **Test Runner**: Jest, Vitest, or equivalent with parallel execution
-- **Assertion Library**: Built-in assertions with descriptive matchers
-- **Mocking**: Comprehensive mocking for external dependencies
-- **Coverage**: Istanbul/NYC for coverage reporting
-- **CI Integration**: Automated test execution in CI pipeline
-
-### Database Testing
-
-- **Test Database**: Separate database instance for tests
-- **Schema Sync**: Automatic schema setup/teardown
-- **Data Seeding**: Deterministic test data seeding
-- **Transaction Rollback**: Tests wrapped in transactions for cleanup
-
-### CI/CD Testing
-
-- **Parallel Execution**: Tests run in parallel for speed
-- **Flaky Test Detection**: Automatic retry for known flaky tests
-- **Coverage Reporting**: Coverage reports uploaded to CI
-- **Test Result Storage**: Historical test results tracked
-
-## Testing Anti-Patterns (Forbidden)
-
-### ❌ Mocking Core Business Logic
-
-```typescript
-// DON'T: Mock the function you're supposed to test
-jest.mock('./businessLogic', () => ({
-  calculateTotal: jest.fn(() => 100),
-}));
-
-test('calculateTotal', () => {
-  expect(calculateTotal()).toBe(100); // Tests the mock, not the logic
-});
-```
-
-### ❌ Testing Implementation Details
-
-```typescript
-// DON'T: Test private methods or internal state
-test('internal counter increments', () => {
-  component.privateCounter = 5; // Accessing private state
-  expect(component.privateCounter).toBe(5);
-});
-```
-
-### ❌ Inadequate Error Testing
-
-```typescript
-// DON'T: Generic error testing
-test('throws error', () => {
-  expect(() => riskyOperation()).toThrow(); // Too vague
-});
-```
-
-### ❌ No Cleanup in Integration Tests
-
-```typescript
-// DON'T: Leave test data behind
-test('creates user', async () => {
-  await createUser({ name: 'test' });
-  // No cleanup - data persists
-});
-```
-
-## Testing Best Practices
-
-### ✅ Proper Error Testing
-
-```typescript
-test('throws specific error for invalid input', () => {
-  expect(() => validateEmail('invalid')).toThrow(ValidationError);
-  expect(() => validateEmail('invalid')).toThrow('Invalid email format');
-});
-```
-
-### ✅ Realistic Test Data
-
-```typescript
-const realisticUser = {
-  id: 'user-123',
-  email: 'user@example.com',
-  name: 'John Doe',
-  createdAt: new Date('2024-01-01'),
-  preferences: { theme: 'dark', notifications: true },
-};
-```
-
-### ✅ Proper Async Testing
-
-```typescript
-test('resolves with correct data', async () => {
-  const result = await fetchUserData('user-123');
-  expect(result).toEqual(expectedUserData);
-});
-```
-
-### ✅ Database Test Cleanup
-
-```typescript
-describe('UserService', () => {
-  let dbClient;
-
-  beforeEach(async () => {
-    dbClient = await createTestDbConnection();
-    await seedTestData(dbClient);
-  });
-
-  afterEach(async () => {
-    await cleanupTestData(dbClient);
-    await dbClient.end();
-  });
-});
-```
-
-## Test Documentation Requirements
-
-### Test Comments for Complex Logic
-
-```typescript
-test('calculates compound interest with monthly compounding', () => {
-  // Formula: A = P(1 + r/n)^(nt)
-  // Where: A = final amount, P = principal, r = rate, n = compounding frequency, t = time
-  const principal = 1000;
-  const rate = 0.05; // 5%
-  const compoundingFrequency = 12; // monthly
-  const timeInYears = 2;
-
-  const result = calculateCompoundInterest(principal, rate, compoundingFrequency, timeInYears);
-  const expected = 1104.54; // Pre-calculated expected value
-
-  expect(result).toBeCloseTo(expected, 2);
-});
-```
-
-### Test Coverage Comments
-
-```typescript
-// Test Coverage:
-// ✅ Happy path: valid input -> correct output
-// ✅ Edge case: zero principal -> zero result
-// ✅ Edge case: negative rate -> throws error
-// ✅ Error case: invalid compounding frequency -> throws error
-// ✅ Boundary: very large numbers -> handles precision
-```
-
-## Performance Testing Standards
-
-### Response Time Assertions
-
-```typescript
-test('responds within SLA', async () => {
-  const startTime = Date.now();
-  const result = await expensiveOperation();
-  const duration = Date.now() - startTime;
-
-  expect(duration).toBeLessThan(5000); // 5 second SLA
-  expect(result).toBeDefined();
-});
-```
-
-### Load Testing Guidelines
-
-- Test with realistic concurrent users
-- Include warm-up periods
-- Measure 95th percentile response times
-- Test memory usage under load
-- Verify graceful degradation
-
-## Mutation Testing Standards
-
-### Mutation Operators to Cover
-
-- **Arithmetic Operators**: `+`, `-`, `*`, `/`, `%`
-- **Logical Operators**: `&&`, `||`, `!`
-- **Comparison Operators**: `==`, `!=`, `<`, `>`, `<=`, `>=`
-- **Conditional Boundaries**: `if` conditions, ternary operators
-- **Return Statements**: Missing/incorrect returns
-- **Variable Assignments**: Wrong variable assignments
-
-### Mutation Score Targets
-
-- **Critical Components**: 80%+ mutation score
-- **Business Logic**: 70%+ mutation score
-- **Utilities**: 60%+ mutation score
-- **UI Components**: 50%+ mutation score (may be lower due to test complexity)
-
-## Accessibility Testing (Web Components)
-
-### Screen Reader Testing
-
-```typescript
-test("is accessible to screen readers", () => {
-  render(<Button>Click me</Button>);
-
-  // Test ARIA labels
-  expect(screen.getByRole("button")).toHaveAttribute("aria-label", "Click me");
-
-  // Test keyboard navigation
-  userEvent.tab();
-  expect(screen.getByRole("button")).toHaveFocus();
-});
-```
-
-### Color Contrast Testing
-
-```typescript
-test("meets color contrast requirements", () => {
-  render(<Text variant="error">Error message</Text>);
-
-  const element = screen.getByText("Error message");
-  const styles = window.getComputedStyle(element);
-
-  // Verify contrast ratio programmatically
-  expect(
-    getContrastRatio(styles.color, styles.backgroundColor)
-  ).toBeGreaterThan(4.5);
-});
-```
-
-## Execution Discipline
-
-- Run unit tests and lints after any major change; iterate until green.
-- If the project defines an engine, confirm Node version via console before running scripts.
-- `.env` files exist; do **not** attempt to cat protected dotfiles. Use framework tooling or documented env loaders.
-
-## Commits
-
-- `--no-verify` is **not allowed**. If hooks fail, **fix the cause** or split work into smaller audited commits.
-- Commit subjects: **what + why** in one sentence. Bodies for context only when needed.
-
-## TODOs & Placeholders
-
-Tag placeholders explicitly in code:
-
-- `// TODO: ...` (critical, must block if reached)
-- `// PLACEHOLDER: ...` (non-critical placeholder, warn)
-- `// MOCK DATA: ...` (remove before release)
-
-**Critical TODOs**: throw at execution site with clear message.
-
-## Diagrams/Charts
-
-- In Markdown, use **Mermaid** only. Ensure contrast (dark text on light, light on dark backgrounds).
-
-## CAWS Integration
-
-### Quality Gate Commands
-
-```bash
-# Run comprehensive test suite
-caws quality-gates --test-coverage --mutation-testing
-
-# Metrics are tracked automatically via working state
-
-# Verify acceptance criteria for test completion
-caws verify-acs --spec-id <id>
-```
-
-### Test Analysis
-
-```bash
-# Analyze test patterns and budget prediction
-caws test-analysis assess-budget
-caws test-analysis analyze-patterns
-caws test-analysis find-similar
-```
-
-## Acceptance
-
-- `test`, `lint`, `typecheck` succeed.
-- No TODOs executed at runtime.
-- No style violations flagged by project linters.
-- Coverage thresholds met (80%+ line, 90%+ branch)
-- Mutation testing scores meet targets (70%+ for critical components)
-- All integration tests use real database connections
-- Performance tests meet documented SLAs

package/dist/templates/.cursor/rules/03-naming-and-refactor.mdc

@@ -1,33 +0,0 @@
----
-description: Canonical naming; forbid enhanced/new/final forks; refactor rules
-globs:
-alwaysApply: true
----
-
-# Canonical Naming & Refactor Rules
-
-## No Duplicate/Fork Names
-
-Reject or remove modules/files named with these modifiers:
-`enhanced | unified | better | new | next | final | copy | revamp | improved` (case-insensitive).
-
-**Pre-flight check (human-run or agent-run shell):**
-
-```bash
-rg -n --no-ignore -g '!node_modules' '(?i)\b(enhanced|unified|better|new|next|final|copy|revamp|improved)\b'
-rg -n --no-ignore -g '!node_modules' '(?i)(enhanced|unified|new|final|copy).*\.([tj]sx?|mjs|cjs|mts|cts)$'
-```
-
-If hits exist in proposed filenames/symbols: **do not proceed**. Use **purpose-first canonical names** and edit the existing module.
-
-## Refactor Strategy
-
-- **Merge, then delete**: If two files cover one domain, merge into the canonical name, update imports, remove the duplicate.
-- Prefer **Strategy** + feature flags over file forks.
-- Every refactor must include tests proving no behavior change (or updated tests + CHANGELOG if behavior changes).
-
-## Acceptance
-
-- No banned modifiers present in filenames or public symbols.
-- Imports updated; build is green.
-- Duplicates removed from tree.

package/dist/templates/.cursor/rules/04-logging-language-style.mdc

@@ -1,23 +0,0 @@
----
-description: Logging, language tone, emoji policy
-globs:
-alwaysApply: true
----
-
-# Logging & Language
-
-## Clarity over chronology
-
-Remove "phase/week" phrasing in docs/logs. State the **specific improvement**:
-
-- ❌ "PHASE 1 optimization"
-- ✅ "Initialize workload analyzer for parallelization"
-
-## Emojis
-
-- Emojis are banned across code, docs, and commits.
-- Exception (debug logs only): ⚠️, ✅, 🚫.
-
-## Commit Tone
-
-Professional, neutral, and specific. Avoid hype or vague framing.

package/dist/templates/.cursor/rules/05-safe-defaults-guards.mdc

@@ -1,23 +0,0 @@
----
-description: Safe defaults, guard clauses, early returns
-globs:
-alwaysApply: false
----
-
-# Safe Defaults & Guard Clauses
-
-## Intent
-
-Minimize null/undefined faults and nesting.
-
-## Guidelines (language-agnostic)
-
-- Prefer **guard clauses** at top of function to fail fast.
-- Default parameter objects in signatures.
-- Prefer **short-circuiting** / optional access / null-coalescing where supported.
-- Loop defensively on possibly-empty collections.
-
-## Acceptance
-
-- No deep nesting introduced where guard clauses apply.
-- Inputs validated at boundaries; failures are explicit and early.

package/dist/templates/.cursor/rules/06-typescript-conventions.mdc

@@ -1,36 +0,0 @@
----
-description: TypeScript/JS conventions (alias imports, const, types source of truth)
-globs:
-  - '**/*.ts'
-  - '**/*.tsx'
-  - '**/*.mts'
-  - '**/*.cts'
-alwaysApply: false
----
-
-# TS/JS Conventions
-
-## Variables
-
-- Prefer `const` over `let` where possible.
-
-## Imports
-
-- Use aliased imports from `@/` (mapped to `src`).
-- Replace deep relative paths (`../../x`) with `@/...` when available.
-
-## Types
-
-- Single source of truth at `src/types`.
-- Before creating a new type, check and extend the canonical definition.
-- Avoid duplicate declarations; prefer composition or augmentation.
-
-## Modularity
-
-- As files approach ~1000 LOC, evaluate separation of concerns; extract cohesive units.
-
-## Acceptance
-
-- No unnecessary `let`.
-- No duplicate type declarations.
-- No deep relative paths where alias exists.

package/dist/templates/.cursor/rules/07-process-ops.mdc

@@ -1,20 +0,0 @@
----
-description: Process discipline for local servers and hung commands
-globs:
-alwaysApply: true
----
-
-# Process Discipline
-
-## Servers
-
-- Before starting a dev server, check if one is already running on the port; reuse or stop it to avoid duplicates.
-- If multiple processes are attached to the port, list and kill explicitly; document PIDs in the PR note if non-obvious.
-
-## Hung/Canceled Commands
-
-If a command is canceled or stalls:
-
-1. Assume it hung or waited for input.
-2. Re-run with verbose/debug flags.
-3. Surface the prompt/interaction in the PR so reviewers understand the resolution.

package/dist/templates/.cursor/rules/08-solid-and-architecture.mdc

@@ -1,16 +0,0 @@
----
-description: Architecture invariants (SOLID) and change isolation
-globs:
-alwaysApply: true
----
-
-# Architecture Invariants
-
-- SRP: Each module/class has one reason to change.
-- OCP: Prefer extension points over editing stable internals.
-- LSP/ISP/DIP: Respect substitution; segregate interfaces; depend on abstractions.
-
-## Change Isolation
-
-- Introduce seams (interfaces/strategies) near integration points.
-- Add tests at seams; assert unchanged public behavior.

package/dist/templates/.cursor/rules/09-docstrings.mdc

@@ -1,89 +0,0 @@
----
-description: Language-specific docstring formats and checklists
-globs:
-alwaysApply: false
----
-
-# Docstrings by Language (Reference)
-
-Provide docstrings for public APIs and exported functions, using the language's native format. Include: summary, params, returns, errors, and an example if helpful.
-
-| Language | Doc Type | Include                                         |
-| -------- | -------- | ----------------------------------------------- |
-| C#       | XML      | `<summary>`, `<param>`, `<returns>`, exceptions |
-| C++      | Doxygen  | \brief, \param, \return, \exception             |
-| Go       | GoDoc    | Full-sentence summary; examples via `ExampleX`  |
-| Java     | Javadoc  | One-sentence summary; @param/@return/@throws    |
-| JS/TS    | JSDoc    | Description; @param/@returns; @example          |
-| Kotlin   | KDoc     | Summary; @param/@return; @throws                |
-| PHP      | PHPDoc   | Summary; @param/@return; @throws                |
-| Python   | PEP257   | One-liner; Args/Returns/Raises; example         |
-| Ruby     | RDoc     | Description; @param/@return; @raise             |
-| Rust     | rustdoc  | `///`; Examples/Panics/Errors sections          |
-| Swift    | DocC     | `///`; - Parameters/Returns/Throws; example     |
-
-## Examples by Language
-
-### C# (XML comments)
-
-```csharp
-/// <summary>
-///   Adds two integers.
-/// </summary>
-/// <param name="a">First integer.</param>
-/// <param name="b">Second integer.</param>
-/// <returns>The sum of <paramref name="a"/> and <paramref name="b"/>.</returns>
-/// <example>
-///   <code>
-///     var result = calculator.Add(2, 3); // 5
-///   </code>
-/// </example>
-public int Add(int a, int b) => a + b;
-```
-
-### JavaScript / TypeScript (JSDoc)
-
-```ts
-/**
- * Adds two numbers.
- *
- * @param {number} a - First number.
- * @param {number} b - Second number.
- * @returns {number} Sum of a and b.
- * @example
- *   add(2, 3); // 5
- */
-function add(a, b) {
-  return a + b;
-}
-```
-
-### Python (PEP 257 / Google style)
-
-```python
-def add(a: int, b: int) -> int:
-    """Add two integers.
-
-    Args:
-        a (int): First integer.
-        b (int): Second integer.
-
-    Returns:
-        int: Sum of a and b.
-
-    Raises:
-        ValueError: If a or b is negative.
-
-    Example:
-        >>> add(2, 3)
-        5
-    """
-    if a < 0 or b < 0:
-        raise ValueError("Negative not allowed")
-    return a + b
-```
-
-## Acceptance
-
-- Public APIs have docstrings in native style.
-- Docstrings describe behavior, inputs, outputs, and failure modes.