groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/docs/research/P1M1T2S1/test-patterns.md

@@ -1,153 +0,0 @@
-# Test Patterns Research: P1.M1.T2.S1
-
-## Reference Test Pattern from P1.M1.T1.S1
-
-**File**: `src/__tests__/adversarial/parent-validation.test.ts`
-
-### Complete Reference Pattern
-
-```typescript
-/**
- * Parent Validation Tests (TDD Red Phase)
- *
- * These tests validate the attachChild() method properly prevents
- * attaching a child workflow that already has a different parent.
- *
- * This is the RED phase of TDD - tests are written to FAIL initially,
- * documenting the expected behavior before implementation.
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { Workflow } from '../../index.js';
-
-/**
- * SimpleWorkflow class for testing
- * Pattern from: src/__tests__/unit/workflow.test.ts:4-11
- */
-class SimpleWorkflow extends Workflow {
-  async run(): Promise<string> {
-    this.setStatus('running');
-    this.setStatus('completed');
-    return 'done';
-  }
-}
-
-describe('Adversarial: Parent Validation', () => {
-  /**
-   * Setup: Mock console methods to capture error messages
-   * Pattern from: research/console-mocking.md "Basic Spying Patterns"
-   */
-  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
-   */
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  /**
-   * Primary failing test for parent validation bug
-   *
-   * Bug: attachChild() only checks if child is already attached to THIS workflow
-   * It does NOT check if child already has a different parent
-   *
-   * Expected: Error thrown with message containing 'already has a parent'
-   * Actual: No error thrown, inconsistent tree state created
-   *
-   * Pattern from: research/error-assertions.md "Partial Message Matching"
-   */
-  it('should throw when attaching child that already has a different parent', () => {
-    // ARRANGE: Create two parent workflows
-    const parent1 = new SimpleWorkflow('Parent1');
-    const parent2 = new SimpleWorkflow('Parent2');
-
-    // ARRANGE: Create child with parent1 (constructor auto-attaches)
-    // CRITICAL: Constructor calls parent.attachChild(this) at workflow.ts:113-116
-    const child = new SimpleWorkflow('Child', parent1);
-
-    // Verify initial state
-    expect(child.parent).toBe(parent1);
-    expect(parent1.children).toContain(child);
-
-    // ACT & ASSERT: Attempting to attach child to parent2 should throw
-    // This test FAILS because attachChild() doesn't check child.parent !== this
-    expect(() => parent2.attachChild(child)).toThrow('already has a parent');
-  });
-});
-```
-
-## Key Test Pattern Elements
-
-### 1. Console Mocking Pattern
-```typescript
-beforeEach(() => {
-  vi.spyOn(console, 'log').mockImplementation(() => {});
-  vi.spyOn(console, 'error').mockImplementation(() => {});
-  vi.spyOn(console, 'warn').mockImplementation(() => {});
-});
-
-afterEach(() => {
-  vi.restoreAllMocks();
-});
-```
-
-### 2. Error Assertion Pattern
-```typescript
-// Partial message matching (recommended)
-expect(() => parent2.attachChild(child)).toThrow('already has a parent');
-
-// Exact message matching
-expect(() => parent.attachChild(child)).toThrow(
-  'Child already attached to this workflow'
-);
-
-// Regex pattern matching
-expect(() => operation()).toThrow(/circular|cycle|ancestor/);
-```
-
-### 3. Test Fixture Pattern
-```typescript
-class SimpleWorkflow extends Workflow {
-  async run(): Promise<string> {
-    this.setStatus('running');
-    this.setStatus('completed');
-    return 'done';
-  }
-}
-```
-
-## Test Framework Details
-
-- **Framework**: Vitest
-- **Config**: `vitest.config.ts`
-- **Test location**: `src/__tests__/adversarial/`
-- **Run command**: `npm test`
-- **Watch mode**: `npm run test:watch`
-
-## Test File Structure
-
-```
-src/__tests__/
-├── unit/              # Unit tests for individual components
-├── integration/       # Integration tests
-└── adversarial/       # Edge case and failure mode testing
-```
-
-## Adapting Pattern for Circular Reference Tests
-
-For P1.M1.T2.S1, we need to test TWO scenarios:
-
-1. **Immediate circular reference**: `child.attachChild(parent)`
-2. **Ancestor circular reference**: `root -> child1 -> child2 -> root` (multi-level)
-
-Both tests should:
-- Follow the same console mocking pattern
-- Use SimpleWorkflow fixture
-- Assert error message contains 'circular' OR 'cycle' OR 'ancestor'
-- Be in the adversarial test directory

package/plan/001_d3bb02af4886/docs/research/P1M1T2S1/workflow-class.md

@@ -1,132 +0,0 @@
-# Workflow Class Research: P1.M1.T2.S1
-
-## File Locations
-
-- **Main Implementation**: `/home/dustin/projects/groundswell/src/core/workflow.ts`
-- **Type Definitions**: `/home/dustin/projects/groundswell/src/types/workflow.ts`
-- **Event Types**: `/home/dustin/projects/groundswell/src/types/events.ts`
-
-## Current Class Structure
-
-```typescript
-export class Workflow<T = unknown> {
-  // Properties
-  public readonly id: string;
-  public parent: Workflow | null = null;
-  public children: Workflow[] = [];
-  public status: WorkflowStatus = 'idle';
-  protected readonly logger: WorkflowLogger;
-  protected readonly node: WorkflowNode;
-  private observers: WorkflowObserver[] = [];
-  private executor?: WorkflowExecutor<T>;
-  private config: WorkflowConfig;
-
-  // Constructor with overloads for both class-based and functional patterns
-  constructor(name?: string | WorkflowConfig, parentOrExecutor?: Workflow | WorkflowExecutor<T>)
-
-  // Key Methods
-  public attachChild(child: Workflow): void
-  public emitEvent(event: WorkflowEvent): void
-  public setStatus(status: WorkflowStatus): void
-  public snapshotState(): void
-  public addObserver(observer: WorkflowObserver): void
-  public removeObserver(observer: WorkflowObserver): void
-  public getNode(): WorkflowNode
-  public async run(...args: unknown[]): Promise<T | WorkflowResult<T>
-
-  // Private Methods
-  private getRootObservers(): WorkflowObserver[]
-  private getRoot(): Workflow
-  private async runFunctional(): Promise<WorkflowResult<T>>
-}
-```
-
-## Current attachChild() Implementation (lines 187-216)
-
-```typescript
-public attachChild(child: Workflow): void {
-  if (this.children.includes(child)) {
-    throw new Error('Child already attached to this workflow');
-  }
-
-  // Check if child already has a different parent
-  if (child.parent !== null && child.parent !== this) {
-    const errorMessage =
-      `Child '${child.node.name}' already has a parent '${child.parent.node.name}'. ` +
-      `A workflow can only have one parent. ` +
-      `Use detachChild() on '${child.parent.node.name}' first if you need to reparent.`;
-    console.error(errorMessage);
-    throw new Error(errorMessage);
-  }
-
-  // Update child's parent if it's currently null
-  if (child.parent === null) {
-    child.parent = this;
-  }
-
-  this.children.push(child);
-  this.node.children.push(child.node);
-
-  // Emit child attached event
-  this.emitEvent({
-    type: 'childAttached',
-    parentId: this.id,
-    child: child.node,
-  });
-}
-```
-
-## Key Observations
-
-1. **Parent Validation Already Implemented**: Lines 193-200 check if child has a different parent
-2. **No Circular Reference Detection**: The method does NOT check if `child` is an ancestor of `this`
-3. **Cycle Detection Exists**: `getRoot()` method uses Set-based cycle detection but only for traversal
-4. **Missing Helper Method**: `isDescendantOf()` is NOT implemented yet
-
-## Parent/Child Relationship Properties
-
-```typescript
-// Workflow class properties
-public parent: Workflow | null = null;
-public children: Workflow[] = [];
-
-// WorkflowNode interface properties
-export interface WorkflowNode {
-  parent: WorkflowNode | null;
-  children: WorkflowNode[];
-  // ... other properties
-}
-```
-
-## Existing Cycle Detection Pattern (from getRoot())
-
-```typescript
-private getRootObservers(): WorkflowObserver[] {
-  const visited = new Set<Workflow>();
-  let root: Workflow = this;
-  let current: Workflow | null = this;
-
-  while (current) {
-    if (visited.has(current)) {
-      throw new Error('Circular parent-child relationship detected');
-    }
-    visited.add(current);
-    root = current;
-    current = current.parent;
-  }
-
-  return root.observers;
-}
-```
-
-## Constructor Auto-Attach Behavior
-
-From `workflow.ts` lines 113-116:
-```typescript
-if (parentOrExecutor instanceof Workflow) {
-  parentOrExecutor.attachChild(this);
-  this.parent = parentOrExecutor;
-}
-```
-
-**CRITICAL**: When creating `new Workflow(name, parent)`, the constructor automatically calls `parent.attachChild(this)`.