groundswell 0.0.1 → 0.0.2

package/src/__tests__/adversarial/deep-hierarchy-stress.test.ts

@@ -0,0 +1,213 @@
+/**
+ * Deep Hierarchy Stress Tests
+ *
+ * These stress tests validate the Workflow class handles deep hierarchies (1000+ levels)
+ * without stack overflow or performance issues in getRoot() and isDescendantOf() methods.
+ *
+ * Pattern 8 from plan/docs/bugfix-architecture/implementation_patterns.md:
+ * "Test deep hierarchies (1000+ levels) to ensure no stack overflow in getRoot() or isDescendantOf()"
+ *
+ * Related: plan/bugfix/P1M3T1S1/PRP.md
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { Workflow } from '../../index.js';
+
+/**
+ * SimpleWorkflow class for testing
+ * Pattern from: src/__tests__/adversarial/circular-reference.test.ts:20-26
+ */
+class SimpleWorkflow extends Workflow {
+  async run(): Promise<string> {
+    this.setStatus('running');
+    this.setStatus('completed');
+    return 'done';
+  }
+}
+
+describe('Deep Hierarchy Stress Tests', () => {
+  /**
+   * Setup: Mock console methods to capture error messages
+   * Pattern from: src/__tests__/adversarial/circular-reference.test.ts:33-37
+   */
+  beforeEach(() => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  /**
+   * Teardown: Restore all mocks to prevent test pollution
+   * CRITICAL: Always use vi.restoreAllMocks() in afterEach
+   * Pattern from: src/__tests__/adversarial/circular-reference.test.ts:43-45
+   */
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  /**
+   * Test 1: Deep Hierarchy Creation (1000+ levels)
+   *
+   * Validates that a chain of 1000+ nested workflows can be created
+   * using loop iteration (not recursion to avoid test-side stack overflow).
+   *
+   * Pattern from: src/__tests__/adversarial/edge-case.test.ts:264-282
+   * Modified to test 1000+ levels instead of 100
+   */
+  it('should create 1000+ level deep workflow hierarchy', () => {
+    const DEPTH = 1000;
+    let lastWorkflow: any = null;
+
+    for (let i = 0; i < DEPTH; i++) {
+      const name = `Workflow-${i}`;
+
+      // Use constructor with parent parameter for auto-attachment
+      // Pattern from: workflow.ts:113-116 (constructor auto-attaches when parent provided)
+      lastWorkflow = new SimpleWorkflow(name, lastWorkflow);
+    }
+
+    // Verify hierarchy depth by walking parent chain
+    let depth = 0;
+    let current: any = lastWorkflow;
+    while (current.parent) {
+      depth++;
+      current = current.parent;
+    }
+
+    // depth should be DEPTH - 1 because root (first workflow) has no parent
+    expect(depth).toBe(DEPTH - 1);
+  });
+
+  /**
+   * Test 2: getRoot() Stress Test
+   *
+   * Validates that getRoot() can be called on the deepest child
+   * and returns the root workflow without stack overflow.
+   *
+   * getRoot() implementation at workflow.ts:184-212 uses iterative while loop
+   * with Set<Workflow> for cycle detection, so it should handle deep chains.
+   *
+   * CRITICAL: getRoot() is protected - must cast to 'any' for testing
+   */
+  it('should call getRoot() on deepest child without stack overflow', () => {
+    const DEPTH = 1000;
+    const root = new SimpleWorkflow('Root');
+    let current: any = root;
+
+    // Build deep hierarchy using constructor with parent
+    for (let i = 0; i < DEPTH; i++) {
+      const child = new SimpleWorkflow(`Child-${i}`, current);
+      current = child;
+    }
+
+    // getRoot() is protected - cast to any
+    const foundRoot = (current as any).getRoot();
+
+    // Verify correct root returned
+    expect(foundRoot.id).toBe(root.id);
+    expect(foundRoot.node.name).toBe('Root');
+  });
+
+  /**
+   * Test 3: isDescendantOf() Stress Test
+   *
+   * Validates that isDescendantOf() can be called on deep chains
+   * without stack overflow.
+   *
+   * isDescendantOf() should use iterative while loop similar to getRoot()
+   * with cycle detection to handle deep chains safely.
+   *
+   * CRITICAL: isDescendantOf() is private - must cast to 'any' for testing
+   * CRITICAL: Test both positive and negative cases
+   */
+  it('should call isDescendantOf() without stack overflow on deep hierarchy', () => {
+    const DEPTH = 1000;
+    const root = new SimpleWorkflow('Root');
+    let current: any = root;
+
+    // Build deep hierarchy
+    for (let i = 0; i < DEPTH; i++) {
+      const child = new SimpleWorkflow(`Child-${i}`, current);
+      current = child;
+    }
+
+    // isDescendantOf is private - cast to any
+    // Test positive case: deepest child IS descendant of root
+    const isDescendant = (current as any).isDescendantOf(root);
+    expect(isDescendant).toBe(true);
+
+    // Test negative case: root is NOT descendant of deepest child
+    const notDescendant = (root as any).isDescendantOf(current);
+    expect(notDescendant).toBe(false);
+  });
+
+  /**
+   * Test 4: Performance Threshold Test
+   *
+   * Validates that deep tree operations complete within acceptable time.
+   * Since getRoot() and isDescendantOf() use iterative algorithms,
+   * they should complete in < 100ms even for 1000-level deep chains.
+   *
+   * This test ensures O(n) iterative performance, not O(n) recursive overhead.
+   */
+  it('should complete deep tree operations within acceptable time', () => {
+    const DEPTH = 1000;
+    const root = new SimpleWorkflow('Root');
+    let current: any = root;
+
+    // Build deep hierarchy
+    for (let i = 0; i < DEPTH; i++) {
+      current = new SimpleWorkflow(`Child-${i}`, current);
+    }
+
+    // Measure getRoot() performance
+    const startTime = performance.now();
+    const foundRoot = (current as any).getRoot();
+    const getRootDuration = performance.now() - startTime;
+
+    expect(foundRoot.id).toBe(root.id);
+    expect(getRootDuration).toBeLessThan(100); // Should be very fast (< 100ms)
+
+    // Measure isDescendantOf() performance
+    const measureStart = performance.now();
+    const isDescendant = (current as any).isDescendantOf(root);
+    const checkDuration = performance.now() - measureStart;
+
+    expect(isDescendant).toBe(true);
+    expect(checkDuration).toBeLessThan(100); // Should be very fast (< 100ms)
+
+    // Total operations should complete well under 1 second
+    const totalStartTime = performance.now();
+    for (let i = 0; i < 100; i++) {
+      (current as any).getRoot();
+      (current as any).isDescendantOf(root);
+    }
+    const totalDuration = performance.now() - totalStartTime;
+    expect(totalDuration).toBeLessThan(1000); // 100 iterations in < 1 second
+  });
+
+  /**
+   * Test 5: Extreme Deep Hierarchy (2000 levels)
+   *
+   * Tests an even deeper hierarchy to ensure safety margin.
+   * JavaScript V8 call stack is ~10,000-15,000 frames,
+   * so testing at 2000 levels provides a 20% safety margin.
+   */
+  it('should handle 2000 level deep hierarchy without issues', () => {
+    const DEPTH = 2000;
+    const root = new SimpleWorkflow('Root');
+    let current: any = root;
+
+    // Build deep hierarchy
+    for (let i = 0; i < DEPTH; i++) {
+      current = new SimpleWorkflow(`Child-${i}`, current);
+    }
+
+    // Both operations should work without stack overflow
+    const foundRoot = (current as any).getRoot();
+    expect(foundRoot.id).toBe(root.id);
+
+    const isDescendant = (current as any).isDescendantOf(root);
+    expect(isDescendant).toBe(true);
+  });
+});

package/src/__tests__/adversarial/e2e-prd-validation.test.ts

@@ -0,0 +1,448 @@
+/**
+ * End-to-End PRD Validation Tests
+ * Creative testing of actual implementation against PRD requirements
+ */
+
+import { describe, it, expect } from 'vitest';
+import { Workflow, Step, Task, ObservedState } from '../../index.js';
+import { WorkflowTreeDebugger } from '../../debugger/tree-debugger.js';
+import type { WorkflowEvent, WorkflowError } from '../../types/index.js';
+
+describe('End-to-End PRD Validation', () => {
+  describe('PRD Example from Section 13', () => {
+    // PRD provides an example TDD workflow - let's test it exactly
+    it('should support the exact TDD workflow example from PRD', async () => {
+      class TestCycleWorkflow extends Workflow {
+        @ObservedState()
+        currentTest!: string;
+
+        @Step({ snapshotState: true })
+        async generateTest() {
+          this.currentTest = 'test-example';
+          return 'generated';
+        }
+
+        @Step()
+        async runTest() {
+          this.logger.info('Running test');
+          return 'passed';
+        }
+
+        @Step()
+        async updateImplementation() {
+          return 'updated';
+        }
+
+        async run() {
+          await this.generateTest();
+          await this.runTest();
+          await this.updateImplementation();
+        }
+      }
+
+      class TDDOrchestrator extends Workflow {
+        @Step({ logStart: true })
+        async setupEnvironment() {
+          this.logger.info('Environment setup complete');
+        }
+
+        @Task()
+        async runCycle() {
+          return new TestCycleWorkflow('Cycle', this);
+        }
+
+        async run() {
+          await this.setupEnvironment();
+          await this.runCycle();
+          await this.children[0].run();
+        }
+      }
+
+      const workflow = new TDDOrchestrator();
+      await workflow.run();
+
+      // Verify hierarchy
+      expect(workflow.children.length).toBe(1);
+      expect(workflow.children[0].node.name).toBe('Cycle');
+
+      // Verify state was captured
+      expect(workflow.children[0].node.stateSnapshot).not.toBeNull();
+      expect(workflow.children[0].node.stateSnapshot?.currentTest).toBe('test-example');
+    });
+  });
+
+  describe('PRD: Restart Semantics - Error Analysis', () => {
+    it('should capture error state for parent restart decision', async () => {
+      let capturedError: WorkflowError | undefined;
+
+      class ChildWorkflow extends Workflow {
+        @ObservedState()
+        attemptCount = 0;
+
+        @Step()
+        async failingOperation() {
+          this.attemptCount++;
+          this.logger.info(`Attempt ${this.attemptCount}`);
+          if (this.attemptCount < 3) {
+            throw new Error('Not ready yet');
+          }
+          return 'success';
+        }
+
+        async run() {
+          return this.failingOperation();
+        }
+      }
+
+      class ParentWorkflow extends Workflow {
+        @Task()
+        async spawnChild() {
+          return new ChildWorkflow('Child', this);
+        }
+
+        async run() {
+          await this.spawnChild();
+
+          // Subscribe to errors for restart logic
+          this.addObserver({
+            onLog: () => {},
+            onEvent: (e) => {
+              if (e.type === 'error') {
+                capturedError = e.error;
+              }
+            },
+            onStateUpdated: () => {},
+            onTreeChanged: () => {},
+          });
+
+          try {
+            await this.children[0].run();
+          } catch (err) {
+            // Analyze error and state for restart decision
+            expect(capturedError).toBeDefined();
+            expect(capturedError!.state.attemptCount).toBeGreaterThan(0);
+            expect(capturedError!.logs.length).toBeGreaterThan(0);
+
+            // Could decide to retry based on capturedError.state
+            // For this test, we just verified the error has all needed info
+          }
+        }
+      }
+
+      const workflow = new ParentWorkflow();
+      await workflow.run();
+    });
+  });
+
+  describe('PRD: @Step trackTiming default behavior', () => {
+    it('should track timing by default when not specified (true by default)', async () => {
+      const events: WorkflowEvent[] = [];
+
+      class TestWorkflow extends Workflow {
+        @Step() // No options - should default to trackTiming: true
+        async testStep() {
+          return 'done';
+        }
+
+        async run() {
+          return this.testStep();
+        }
+      }
+
+      const workflow = new TestWorkflow();
+      workflow.addObserver({
+        onLog: () => {},
+        onEvent: (e) => events.push(e),
+        onStateUpdated: () => {},
+        onTreeChanged: () => {},
+      });
+
+      await workflow.run();
+
+      const stepEndEvent = events.find(e => e.type === 'stepEnd');
+      expect(stepEndEvent).toBeDefined();
+      if (stepEndEvent?.type === 'stepEnd') {
+        expect(typeof stepEndEvent.duration).toBe('number');
+        expect(stepEndEvent.duration).toBeGreaterThanOrEqual(0);
+      }
+    });
+  });
+
+  describe('PRD: Tree Debugger API Completeness', () => {
+    it('should implement all required methods from WorkflowTreeDebugger', async () => {
+      class TestWorkflow extends Workflow {
+        async run() {
+          this.logger.info('Test log');
+        }
+      }
+
+      const workflow = new TestWorkflow();
+      const treeDebugger = new WorkflowTreeDebugger(workflow);
+
+      // Test getTree()
+      const tree = treeDebugger.getTree();
+      expect(tree).toBeDefined();
+      expect(tree.id).toBe(workflow.id);
+
+      // Test getNode()
+      const node = treeDebugger.getNode(workflow.id);
+      expect(node).toBeDefined();
+      expect(node!.id).toBe(workflow.id);
+
+      // Test events observable
+      expect(treeDebugger.events).toBeDefined();
+      expect(typeof treeDebugger.events.subscribe).toBe('function');
+
+      // Test toTreeString()
+      const treeString = treeDebugger.toTreeString();
+      expect(typeof treeString).toBe('string');
+      expect(treeString.length).toBeGreaterThan(0);
+
+      // Test toLogString()
+      await workflow.run();
+      const logString = treeDebugger.toLogString();
+      expect(typeof logString).toBe('string');
+      expect(logString).toContain('Test log');
+    });
+  });
+
+  describe('PRD: WorkflowError Complete Structure', () => {
+    it('should include all required fields per PRD Section 5.1', async () => {
+      class TestWorkflow extends Workflow {
+        @ObservedState()
+        contextData = 'important';
+
+        @Step()
+        async failingStep() {
+          this.logger.info('About to fail');
+          throw new Error('Intentional failure');
+        }
+
+        async run() {
+          try {
+            await this.failingStep();
+          } catch (err) {
+            const wfError = err as WorkflowError;
+
+            // Verify all required fields from PRD Section 5.1
+            expect(wfError.message).toBe('Intentional failure');
+            expect(wfError.original).toBeDefined();
+            expect(wfError.workflowId).toBeDefined();
+            expect(wfError.stack).toBeDefined();
+            expect(wfError.state).toBeDefined();
+            expect(wfError.logs).toBeDefined();
+            expect(Array.isArray(wfError.logs)).toBe(true);
+            expect(wfError.state.contextData).toBe('important');
+            expect(wfError.logs.some(l => l.message.includes('About to fail'))).toBe(true);
+          }
+        }
+      }
+
+      const workflow = new TestWorkflow();
+      await workflow.run();
+    });
+  });
+
+  describe('PRD: Root-Only Observer Restriction', () => {
+    it('should only allow observers on root workflow', async () => {
+      class ChildWorkflow extends Workflow {
+        async run() {
+          return 'done';
+        }
+      }
+
+      class ParentWorkflow extends Workflow {
+        async run() {
+          const child = new ChildWorkflow('Child', this);
+
+          // Should throw when trying to add observer to non-root
+          expect(() => {
+            child.addObserver({
+              onLog: () => {},
+              onEvent: () => {},
+              onStateUpdated: () => {},
+              onTreeChanged: () => {},
+            });
+          }).toThrow('Observers can only be added to root workflows');
+        }
+      }
+
+      const workflow = new ParentWorkflow();
+      await workflow.run();
+    });
+  });
+
+  describe('PRD: Step Snapshot Timing', () => {
+    it('should snapshot state AFTER step completion', async () => {
+      class TestWorkflow extends Workflow {
+        @ObservedState()
+        value = 'before';
+
+        @Step({ snapshotState: true })
+        async changeAndSnapshot() {
+          this.value = 'after';
+          // Snapshot should capture 'after' since it's after step completion
+          return 'done';
+        }
+
+        async run() {
+          await this.changeAndSnapshot();
+          return this.node.stateSnapshot;
+        }
+      }
+
+      const workflow = new TestWorkflow();
+      const snapshot = await workflow.run();
+
+      expect(snapshot?.value).toBe('after');
+    });
+  });
+
+  describe('Creative: Real-world TDD Workflow Scenario', () => {
+    it('should handle realistic test-driven development cycle', async () => {
+      const testResults: string[] = [];
+
+      class TestWorkflow extends Workflow {
+        @ObservedState()
+        testName = '';
+
+        @ObservedState()
+        passed = false;
+
+        @Step({ logStart: true, logFinish: true })
+        async writeTest(testName: string) {
+          this.testName = testName;
+          this.logger.info(`Writing test: ${testName}`);
+        }
+
+        @Step({ trackTiming: true })
+        async runTest() {
+          this.logger.info('Running test...');
+          // Simulate test failure
+          this.passed = false;
+          throw new Error('Test failed: Implementation missing');
+        }
+
+        @Step()
+        async writeCode() {
+          this.logger.info('Writing implementation...');
+          this.passed = true;
+        }
+
+        async run(testName: string) {
+          await this.writeTest(testName);
+          try {
+            await this.runTest();
+          } catch (err) {
+            // Test failed - write code
+            await this.writeCode();
+            // Retry test
+            this.passed = true;
+          }
+        }
+      }
+
+      class Orchestrator extends Workflow {
+        @Task()
+        async runTestCycle(testName: string) {
+          return new TestWorkflow('TestCycle', this);
+        }
+
+        async run() {
+          const testNames = ['shouldAdd', 'shouldSubtract', 'shouldMultiply'];
+
+          for (const name of testNames) {
+            await this.runTestCycle(name);
+            const testWf = this.children[this.children.length - 1];
+            await testWf.run(name);
+            testResults.push(`${name}:${testWf.node.status}`);
+          }
+        }
+      }
+
+      const workflow = new Orchestrator();
+      await workflow.run();
+
+      expect(workflow.children.length).toBe(3);
+      expect(testResults.length).toBe(3);
+    });
+  });
+
+  describe('Creative: Nested Error Propagation', () => {
+    it('should properly handle errors at multiple hierarchy levels', async () => {
+      const errorsAtLevel: { level: string; error: string }[] = [];
+
+      class Level3Workflow extends Workflow {
+        @ObservedState()
+        level = 3;
+
+        @Step()
+        async doWork() {
+          throw new Error('Level 3 error');
+        }
+
+        async run() {
+          return this.doWork();
+        }
+      }
+
+      class Level2Workflow extends Workflow {
+        @ObservedState()
+        level = 2;
+
+        @Task()
+        async spawnLevel3() {
+          return new Level3Workflow('Level3', this);
+        }
+
+        async run() {
+          await this.spawnLevel3();
+          try {
+            await this.children[0].run();
+          } catch (err) {
+            errorsAtLevel.push({ level: '2', error: (err as any).message });
+            throw new Error('Level 2 wrapper error');
+          }
+        }
+      }
+
+      class Level1Workflow extends Workflow {
+        @ObservedState()
+        level = 1;
+
+        @Task()
+        async spawnLevel2() {
+          return new Level2Workflow('Level2', this);
+        }
+
+        async run() {
+          await this.spawnLevel2();
+          try {
+            await this.children[0].run();
+          } catch (err) {
+            errorsAtLevel.push({ level: '1', error: (err as any).message });
+          }
+        }
+      }
+
+      const workflow = new Level1Workflow();
+
+      // Add observer to capture all errors
+      workflow.addObserver({
+        onLog: () => {},
+        onEvent: (e) => {
+          if (e.type === 'error') {
+            errorsAtLevel.push({ level: 'observer', error: e.error.message });
+          }
+        },
+        onStateUpdated: () => {},
+        onTreeChanged: () => {},
+      });
+
+      await workflow.run();
+
+      // Should have captured errors at multiple levels
+      expect(errorsAtLevel.length).toBeGreaterThan(0);
+    });
+  });
+});