@paths.design/caws-cli 7.0.2 → 8.0.0

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

@@ -0,0 +1,370 @@
+---
+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
+
+# Check test quality metrics
+caws metrics track --metric="test_coverage" --value=85
+caws metrics track --metric="mutation_score" --value=70
+
+# Update progress with test completion
+caws progress update --criterion-id="TEST-001" --status="completed" --tests-passing=25
+```
+
+### 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

@@ -0,0 +1,33 @@
+---
+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

@@ -0,0 +1,23 @@
+---
+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

@@ -0,0 +1,23 @@
+---
+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

@@ -0,0 +1,36 @@
+---
+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

@@ -0,0 +1,20 @@
+---
+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

@@ -0,0 +1,16 @@
+---
+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

@@ -0,0 +1,89 @@
+---
+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.