groundswell 0.0.1 → 0.0.2

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T3S3/PRP.md

@@ -0,0 +1,454 @@
+name: "P1.M3.T3.S3 - Verify Tests for Workflow Name Validation"
+description: |
+
+---
+
+## Goal
+
+**Feature Goal**: Verify that comprehensive tests exist for the workflow name validation implementation and that all tests pass.
+
+**Deliverable**: Verification report confirming test coverage is complete and all validation tests pass.
+
+**Success Definition**:
+- All workflow name validation tests exist in `src/__tests__/unit/workflow.test.ts`
+- All 28 workflow tests pass (verified via `npm test -- workflow.test.ts`)
+- Test coverage includes all validation scenarios from S1 decision document
+- Test patterns follow project conventions (vitest, expect().toThrow())
+
+## User Persona (if applicable)
+
+**Target User**: QA Engineer, Developer reviewing test coverage, or Future Maintainer
+
+**Use Case**: Confirming that workflow name validation is properly tested before marking P1.M3.T3 complete
+
+**User Journey**:
+1. Review this PRP to understand what tests should exist
+2. Run the test suite to verify all tests pass
+3. Review test code to understand validation coverage
+4. Document results for task completion
+
+**Pain Points Addressed**:
+- Ensures validation is tested before considering task complete
+- Provides clear verification steps for quality assurance
+- Documents test coverage for future reference
+
+## Why
+
+- **Quality Assurance**: Validation logic must be tested to prevent regressions
+- **Task Completion**: P1.M3.T3 requires tests before marking complete
+- **Documentation**: Future maintainers need to know what's tested
+- **Relationship to S2**: Tests were implemented as part of P1M3T3S2 Task 3, this task verifies completion
+
+## What
+
+Verify that the workflow name validation tests implemented in P1M3T3S2 are comprehensive and passing.
+
+### Success Criteria
+
+- [ ] All workflow name validation tests exist
+- [ ] All tests pass: `npm test -- workflow.test.ts`
+- [ ] Test coverage matches S1 decision document requirements
+- [ ] Both constructor patterns (class-based and functional) are tested
+
+## Important Note
+
+**Tests were already implemented in P1M3T3S2 Task 3**. This PRP is a verification task to confirm the tests are complete and passing. The test suite was created as part of the validation implementation to ensure immediate feedback during development.
+
+## All Needed Context
+
+### Context Completeness Check
+
+_Before using this PRP, validate: "If someone knew nothing about this codebase, would they have everything needed to verify the tests are complete?"_
+
+✅ **YES** - This PRP includes:
+- Exact file path and line numbers for existing tests
+- Complete list of test scenarios covered
+- Reference to S1 decision document for validation rules
+- Reference to S2 PRP that implemented the tests
+- Commands to run and verify tests
+
+### Documentation & References
+
+```yaml
+# MUST READ - Include these in your context window
+- file: src/__tests__/unit/workflow.test.ts
+  why: Contains the complete workflow name validation test suite (lines 13-85)
+  pattern: Uses `describe('Workflow Name Validation')` with 13 test cases
+  critical: Tests cover all validation rules from S1 decision document
+
+- file: src/__tests__/unit/workflow.test.ts:13-85
+  why: This is the complete validation test suite implemented in S2
+  pattern: Uses `expect(() => new SimpleWorkflow('')).toThrow()` for error testing
+  gotcha: Tests both class-based and functional constructor patterns
+
+- url: file:///home/dustin/projects/groundswell/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T3S2/PRP.md
+  why: Contains the implementation PRP that included Task 3 to create these tests
+  critical: Task 3 explicitly specified the test suite requirements
+
+- url: file:///home/dustin/projects/groundswell/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M3T3S1/DECISION.md
+  why: Contains the validation rules that the tests must verify
+  section: Rules 1-5 specify exact validation behavior
+
+- file: src/core/workflow.ts:98-107
+  why: Contains the validation implementation that the tests verify
+  pattern: Throws `Error` for empty/whitespace names and names > 100 chars
+
+- file: vitest.config.ts
+  why: Test configuration - confirms vitest is the test framework
+  pattern: `include: ['src/__tests__/**/*.test.ts']`
+```
+
+### Current Codebase tree (run `tree` in the root of the project) to get an overview of the codebase
+
+```bash
+/home/dustin/projects/groundswell
+├── src/
+│   ├── core/
+│   │   └── workflow.ts          # Contains validation implementation (lines 98-107)
+│   └── __tests__/
+│       ├── adversarial/
+│       │   └── edge-case.test.ts
+│       └── unit/
+│           └── workflow.test.ts  # CONTAINS VALIDATION TESTS (lines 13-85)
+├── plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/
+│   ├── P1M3T3S2/PRP.md          # Implementation PRP that included tests
+│   └── P1M3T3S3/PRP.md          # This verification PRP
+```
+
+### Desired Codebase tree with files to be added and responsibility of file
+
+```bash
+# No new files to be added for this verification task
+# The test file already exists at:
+└── __tests__/
+    └── unit/
+        └── workflow.test.ts     # VERIFICATION TARGET (lines 13-85)
+```
+
+### Known Gotchas of our codebase & Library Quirks
+
+```typescript
+// CRITICAL: Tests were already implemented in P1M3T3S2 Task 3
+// Do NOT create new tests - verify existing tests are complete
+
+// The test suite is comprehensive and includes:
+// - Empty string rejection
+// - Whitespace-only rejection (spaces, tabs, newlines, mixed)
+// - Name exceeding 100 characters rejection
+// - Exactly 100 characters acceptance (boundary test)
+// - Valid names with leading/trailing whitespace acceptance
+// - Undefined/null names using class name (existing behavior)
+// - Both constructor patterns (class-based and functional)
+
+// GOTCHA: Tests use expect().toThrow() for validation error testing
+// This is the standard pattern for constructor validation in this codebase
+
+// GOTCHA: Tests are in a describe block titled 'Workflow Name Validation'
+// This is separate from the main 'Workflow' describe block
+
+// GOTCHA: The SimpleWorkflow class is used as the test fixture
+// It extends Workflow with a minimal run() method
+```
+
+## Implementation Blueprint
+
+### Data models and structure
+
+No new data models. This is a verification task for existing tests.
+
+### Existing Test Coverage (Already Implemented)
+
+The following tests exist at `src/__tests__/unit/workflow.test.ts:13-85`:
+
+```yaml
+Test Suite: "Workflow Name Validation"
+
+Test 1: "should reject empty string name"
+  - Validates: Empty string ('') throws error
+  - Expected: "Workflow name cannot be empty or whitespace only"
+
+Test 2: "should reject whitespace-only name (spaces)"
+  - Validates: '   ' (3 spaces) throws error
+  - Expected: "Workflow name cannot be empty or whitespace only"
+
+Test 3: "should reject whitespace-only name (tabs)"
+  - Validates: '\t\t' (2 tabs) throws error
+  - Expected: "Workflow name cannot be empty or whitespace only"
+
+Test 4: "should reject whitespace-only name (newlines)"
+  - Validates: '\n\n' (2 newlines) throws error
+  - Expected: "Workflow name cannot be empty or whitespace only"
+
+Test 5: "should reject whitespace-only name (mixed whitespace)"
+  - Validates: '  \t\n  ' (mixed) throws error
+  - Expected: "Workflow name cannot be empty or whitespace only"
+
+Test 6: "should reject name exceeding 100 characters"
+  - Validates: 101 character name throws error
+  - Expected: "Workflow name cannot exceed 100 characters"
+
+Test 7: "should accept name with exactly 100 characters"
+  - Validates: 100 character name is accepted
+  - Boundary test: Exact maximum length
+
+Test 8: "should accept valid names with leading/trailing whitespace"
+  - Validates: '  MyWorkflow  ' is accepted as-is
+  - Confirms: No auto-trimming behavior
+
+Test 9: "should use class name when name is undefined"
+  - Validates: undefined uses class name
+  - Existing behavior preserved
+
+Test 10: "should use class name when name is null"
+  - Validates: null uses class name
+  - Existing behavior preserved
+
+Test 11: "should validate both constructor patterns - class-based with empty name"
+  - Validates: Class-based pattern rejects empty names
+
+Test 12: "should validate both constructor patterns - functional with empty name"
+  - Validates: Functional pattern rejects empty names
+
+Test 13: "should validate both constructor patterns - functional with whitespace name"
+  - Validates: Functional pattern rejects whitespace names
+
+Test 14: "should validate both constructor patterns - functional with name exceeding 100 characters"
+  - Validates: Functional pattern rejects long names
+
+Test 15: "should accept valid name in functional pattern"
+  - Validates: Functional pattern accepts valid names
+```
+
+### Verification Tasks (ordered by dependencies)
+
+```yaml
+Task 1: VERIFY test suite exists
+  - LOCATION: src/__tests__/unit/workflow.test.ts
+  - CHECK: Lines 13-85 contain "Workflow Name Validation" describe block
+  - VERIFY: All 15 test cases listed above are present
+  - CONFIRM: Tests use expect().toThrow() pattern for validation
+  - DOCUMENT: List any missing test scenarios if found
+
+Task 2: RUN tests to verify they pass
+  - COMMAND: npm test -- workflow.test.ts
+  - EXPECT: All 28 tests in workflow.test.ts pass
+  - VERIFY: Specifically the 15 validation tests pass
+  - DOCUMENT: Any failing tests and their errors
+
+Task 3: VERIFY test coverage matches S1 decision document
+  - REFERENCE: plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M3T3S1/DECISION.md
+  - CHECK: Rule 1 (Empty/Whitespace rejection) - Tests 1-5 cover this
+  - CHECK: Rule 2 (Max 100 characters) - Tests 6-7 cover this
+  - CHECK: Rule 3 (Valid names accepted) - Tests 8, 15 cover this
+  - CHECK: Rule 4 (No auto-trimming) - Test 8 covers this
+  - CHECK: Rule 5 (Undefined behavior) - Tests 9-10 cover this
+  - DOCUMENT: Any gaps in coverage
+
+Task 4: VERIFY both constructor patterns are tested
+  - CHECK: Class-based pattern (new Workflow(name, parent)) - Tests 1-10
+  - CHECK: Functional pattern (new Workflow(config, executor)) - Tests 11-15
+  - CONFIRM: Both patterns tested for validation
+  - DOCUMENT: Any missing pattern coverage
+
+Task 5: CREATE verification report
+  - SUMMARY: All tests exist and pass
+  - COVERAGE: List all validation scenarios covered
+  - RESULTS: Test pass count and duration
+  - CONCLUSION: Task P1M3T3S3 complete
+```
+
+### Implementation Patterns & Key Details
+
+```typescript
+// EXISTING TEST PATTERN (for reference only):
+
+// The test suite uses this pattern for validation testing:
+describe('Workflow Name Validation', () => {
+  it('should reject empty string name', () => {
+    expect(() => new SimpleWorkflow(''))
+      .toThrow('Workflow name cannot be empty or whitespace only');
+  });
+
+  it('should reject whitespace-only name (spaces)', () => {
+    expect(() => new SimpleWorkflow('   '))
+      .toThrow('Workflow name cannot be empty or whitespace only');
+  });
+
+  // Boundary testing
+  it('should accept name with exactly 100 characters', () => {
+    const exactly100 = 'a'.repeat(100);
+    const wf = new SimpleWorkflow(exactly100);
+    expect(wf.getNode().name).toBe(exactly100);
+    expect(wf.getNode().name.length).toBe(100);
+  });
+
+  // Both constructor patterns
+  it('should validate both constructor patterns - functional with empty name', () => {
+    expect(() => new Workflow({ name: '' }, async () => {}))
+      .toThrow('Workflow name cannot be empty or whitespace only');
+  });
+});
+
+// KEY PATTERN: expect(() => new Workflow(invalidName)).toThrow(errorMessage)
+// This is the standard pattern for constructor validation in this codebase
+```
+
+### Integration Points
+
+```yaml
+VERIFICATION:
+  - test_file: "src/__tests__/unit/workflow.test.ts:13-85"
+  - validation_implementation: "src/core/workflow.ts:98-107"
+  - decision_document: "plan/.../docs/P1M3T3S1/DECISION.md"
+  - implementation_prp: "plan/.../P1M3T3S2/PRP.md"
+
+TEST_EXECUTION:
+  - command: "npm test -- workflow.test.ts"
+  - expected: "All 28 tests pass"
+  - duration: "Should complete in < 1 second"
+```
+
+## Validation Loop
+
+### Level 1: Test Existence Verification
+
+```bash
+# Verify test suite exists
+grep -n "Workflow Name Validation" src/__tests__/unit/workflow.test.ts
+
+# Expected: Line 13 contains "describe('Workflow Name Validation'"
+# Expected: Lines 14-85 contain the test cases
+```
+
+### Level 2: Test Execution (Component Validation)
+
+```bash
+# Run the workflow test suite
+npm test -- workflow.test.ts
+
+# Expected Output:
+# ✓ src/__tests__/unit/workflow.test.ts  (28 tests)
+# Test Files  1 passed (1)
+#      Tests  28 passed (28)
+
+# If any tests fail:
+# 1. Read the error output
+# 2. Check if it's a validation test failure
+# 3. Investigate the failure cause
+# 4. Document findings
+```
+
+### Level 3: Coverage Verification (System Validation)
+
+```bash
+# Verify all validation scenarios are tested
+
+# Check for empty string test
+grep -n "empty string name" src/__tests__/unit/workflow.test.ts
+
+# Check for whitespace tests
+grep -n "whitespace-only name" src/__tests__/unit/workflow.test.ts
+
+# Check for max length test
+grep -n "exceeding 100 characters" src/__tests__/unit/workflow.test.ts
+
+# Check for boundary test (exactly 100)
+grep -n "exactly 100 characters" src/__tests__/unit/workflow.test.ts
+
+# Check for both constructor patterns
+grep -n "both constructor patterns" src/__tests__/unit/workflow.test.ts
+
+# Expected: All grep commands find matches
+```
+
+### Level 4: Documentation Verification
+
+```bash
+# Count the number of validation tests
+grep -c "it('.*should" src/__tests__/unit/workflow.test.ts | head -15
+
+# Expected: At least 15 test cases in the validation suite
+
+# Verify test file follows project conventions
+head -5 src/__tests__/unit/workflow.test.ts
+
+# Expected:
+# import { describe, it, expect } from 'vitest';
+# import { Workflow, ... } from '../../index.js';
+```
+
+## Final Validation Checklist
+
+### Technical Validation
+
+- [ ] Test suite exists at `src/__tests__/unit/workflow.test.ts:13-85`
+- [ ] All 28 workflow tests pass: `npm test -- workflow.test.ts`
+- [ ] Tests cover empty string rejection
+- [ ] Tests cover whitespace-only rejection (spaces, tabs, newlines, mixed)
+- [ ] Tests cover max length rejection (> 100 chars)
+- [ ] Tests cover boundary case (exactly 100 chars)
+- [ ] Tests cover valid names with leading/trailing whitespace
+- [ ] Tests cover undefined/null using class name
+- [ ] Tests cover both constructor patterns (class-based and functional)
+
+### Feature Validation
+
+- [ ] Test coverage matches S1 decision document requirements
+- [ ] All validation rules from S1 are tested
+- [ ] Error message assertions are exact (not regex)
+- [ ] Boundary testing is present (100 chars)
+- [ ] Both constructor patterns are validated
+
+### Code Quality Validation
+
+- [ ] Tests follow project conventions (vitest, expect().toThrow())
+- [ ] Test descriptions are clear and descriptive
+- [ ] Test fixture (SimpleWorkflow) is appropriate
+- [ ] No duplicate test scenarios
+
+### Documentation & Deployment
+
+- [ ] This PRP documents the verification process
+- [ ] Test coverage is documented for future reference
+- [ ] Relationship to S2 implementation is clear
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ Don't create new tests - they already exist from S2
+- ❌ Don't modify existing tests unless they're failing
+- ❌ Don't skip verification steps - all must be completed
+- ❌ Don't assume tests pass without running them
+- ❌ Don't forget to document any gaps found in coverage
+- ❌ Don't mark task complete without full verification
+
+## Verification Report Template
+
+After completing the verification tasks, document results:
+
+```yaml
+Verification Date: [DATE]
+Verifier: [NAME]
+
+Test Suite Location: src/__tests__/unit/workflow.test.ts:13-85
+Test Count: 15 validation tests (of 28 total workflow tests)
+
+Test Results:
+- Command Run: npm test -- workflow.test.ts
+- Tests Passed: [NUMBER]
+- Tests Failed: [NUMBER]
+- Duration: [TIME]
+
+Coverage Analysis:
+✓ Rule 1 (Empty/Whitespace): Tests 1-5
+✓ Rule 2 (Max 100 chars): Tests 6-7
+✓ Rule 3 (Valid names): Tests 8, 15
+✓ Rule 4 (No auto-trim): Test 8
+✓ Rule 5 (Undefined behavior): Tests 9-10
+✓ Both constructor patterns: Tests 11-15
+
+Gaps Found: [LIST ANY GAPS OR "NONE"]
+
+Conclusion: [COMPLETE / INCOMPLETE with reasons]
+```