groundswell 0.0.1 → 0.0.2

package/src/__tests__/unit/workflow-detachChild.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { Workflow, WorkflowObserver, WorkflowEvent } from '../../index.js';
+
+class SimpleWorkflow extends Workflow {
+  async run(): Promise<string> {
+    this.setStatus('running');
+    this.setStatus('completed');
+    return 'done';
+  }
+}
+
+describe('Workflow.detachChild()', () => {
+  it('should remove child from parent.children array', () => {
+    // Arrange: Create parent with child
+    const parent = new SimpleWorkflow('Parent');
+    const child = new SimpleWorkflow('Child', parent);
+
+    // Assert: Verify child is in parent.children
+    expect(parent.children).toContain(child);
+
+    // Act: Call detachChild (will fail - method doesn't exist)
+    parent.detachChild(child);
+
+    // Assert: Verify child removed from parent.children
+    expect(parent.children).not.toContain(child);
+  });
+
+  it('should clear child.parent to null', () => {
+    // Arrange: Create parent with child
+    const parent = new SimpleWorkflow('Parent');
+    const child = new SimpleWorkflow('Child', parent);
+
+    // Assert: Verify child.parent is set
+    expect(child.parent).toBe(parent);
+
+    // Act: Call detachChild
+    parent.detachChild(child);
+
+    // Assert: Verify child.parent is null
+    expect(child.parent).toBeNull();
+  });
+
+  it('should remove child.node from parent.node.children array', () => {
+    // Arrange: Create parent with child
+    const parent = new SimpleWorkflow('Parent');
+    const child = new SimpleWorkflow('Child', parent);
+
+    // Assert: Verify child.node is in parent.node.children
+    expect(parent.getNode().children).toContain(child.getNode());
+
+    // Act: Call detachChild
+    parent.detachChild(child);
+
+    // Assert: Verify child.node removed from parent.node.children
+    expect(parent.getNode().children).not.toContain(child.getNode());
+  });
+
+  it('should emit childDetached event with correct payload', () => {
+    // Arrange: Create parent with observer
+    const parent = new SimpleWorkflow('Parent');
+    const events: WorkflowEvent[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: (event) => events.push(event),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    };
+
+    parent.addObserver(observer);
+
+    // Act: Create child (triggers attachChild event), then detach
+    const child = new SimpleWorkflow('Child', parent);
+    events.length = 0; // Clear attachChild events
+
+    parent.detachChild(child);
+
+    // Assert: Verify childDetached event was emitted
+    const detachEvent = events.find((e) => e.type === 'childDetached');
+    expect(detachEvent).toBeDefined();
+
+    // Assert: Verify event payload (with type guard for discriminated union)
+    expect(detachEvent?.type === 'childDetached' && detachEvent.parentId).toBe(parent.id);
+    expect(detachEvent?.type === 'childDetached' && detachEvent.childId).toBe(child.id);
+  });
+
+  it('should throw error when child is not attached to parent', () => {
+    // Arrange: Create parent and child separately (no attachment)
+    const parent = new SimpleWorkflow('Parent');
+    const child = new SimpleWorkflow('Child');
+
+    // Assert: Verify child is NOT in parent.children
+    expect(parent.children).not.toContain(child);
+
+    // Act & Assert: Calling detachChild should throw error
+    expect(() => parent.detachChild(child)).toThrow(
+      /not attached/i
+    );
+  });
+});

package/src/__tests__/unit/workflow-emitEvent-childDetached.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from 'vitest';
+import { Workflow, WorkflowObserver, WorkflowEvent } from '../../index.js';
+
+class SimpleWorkflow extends Workflow {
+  async run(): Promise<string> {
+    this.setStatus('running');
+    this.setStatus('completed');
+    return 'done';
+  }
+}
+
+describe('emitEvent() - childDetached Tree Update Events', () => {
+  it('should call onTreeChanged() when childDetached event is emitted', () => {
+    // Arrange: Create parent with observer tracking callbacks
+    const parent = new SimpleWorkflow('Parent');
+    const events: WorkflowEvent[] = [];
+    const treeChanges: any[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: (e) => events.push(e),
+      onStateUpdated: () => {},
+      onTreeChanged: (root) => treeChanges.push(root),
+    };
+
+    parent.addObserver(observer);
+
+    // Act: Detach child (which emits childDetached event)
+    const child = new SimpleWorkflow('Child', parent);
+    events.length = 0; // Clear attachChild events
+    treeChanges.length = 0; // Clear attachChild tree changes
+
+    parent.detachChild(child);
+
+    // Assert: Verify childDetached event was emitted
+    const detachEvent = events.find((e) => e.type === 'childDetached');
+    expect(detachEvent).toBeDefined();
+    expect(detachEvent?.type === 'childDetached' && detachEvent.parentId).toBe(parent.id);
+
+    // CRITICAL ASSERTION: onTreeChanged() must be called
+    expect(treeChanges.length).toBe(1);
+    expect(treeChanges[0]).toBe(parent.getNode()); // Receives root node
+  });
+
+  it('should call onEvent() before onTreeChanged() for childDetached', () => {
+    // Arrange: Track call order
+    const parent = new SimpleWorkflow('Parent');
+    const callOrder: string[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: () => callOrder.push('onEvent'),
+      onStateUpdated: () => {},
+      onTreeChanged: () => callOrder.push('onTreeChanged'),
+    };
+
+    parent.addObserver(observer);
+
+    // Act
+    const child = new SimpleWorkflow('Child', parent);
+    callOrder.length = 0; // Clear attachChild call order
+    parent.detachChild(child);
+
+    // Assert: Verify order
+    expect(callOrder).toEqual(['onEvent', 'onTreeChanged']);
+  });
+
+  it('should include childDetached in tree update event types', () => {
+    // This test verifies the implementation at the code level
+    // Access the emitEvent method and verify it triggers onTreeChanged for childDetached
+    const workflow = new SimpleWorkflow('Test');
+
+    // Access private emitEvent method for testing
+    const emitEvent = (workflow as any).emitEvent.bind(workflow);
+
+    // Track if onTreeChanged was called
+    let onTreeChangedCalled = false;
+    const mockObserver = {
+      onLog: () => {},
+      onEvent: () => {},
+      onStateUpdated: () => {},
+      onTreeChanged: () => { onTreeChangedCalled = true; },
+    };
+
+    // Mock getRootObservers to return test observer
+    (workflow as any).getRootObservers = () => [mockObserver];
+
+    // Emit childDetached event
+    emitEvent({
+      type: 'childDetached',
+      parentId: workflow.id,
+      childId: 'test-child-id',
+    });
+
+    // Assert: onTreeChanged should be called
+    expect(onTreeChangedCalled).toBe(true);
+  });
+
+  it('should pass correct root node to onTreeChanged() after detach', () => {
+    // Arrange: Create multi-level tree
+    const root = new SimpleWorkflow('Root');
+    const parent = new SimpleWorkflow('Parent', root);
+    const child = new SimpleWorkflow('Child', parent);
+
+    const treeChangedRoots: any[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: () => {},
+      onStateUpdated: () => {},
+      onTreeChanged: (rootNode) => treeChangedRoots.push(rootNode),
+    };
+
+    root.addObserver(observer);
+
+    // Clear events from tree construction
+    treeChangedRoots.length = 0;
+
+    // Act: Detach child from parent
+    parent.detachChild(child);
+
+    // Assert: onTreeChanged should receive root node (from root workflow)
+    expect(treeChangedRoots.length).toBe(1);
+    expect(treeChangedRoots[0]).toBe(root.getNode());
+  });
+
+  it('should trigger onTreeChanged for both attach and detach operations', () => {
+    // Arrange: Track tree changes
+    const parent = new SimpleWorkflow('Parent');
+    const treeChanges: any[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: () => {},
+      onStateUpdated: () => {},
+      onTreeChanged: (root) => treeChanges.push({ operation: 'treeChanged', root }),
+    };
+
+    parent.addObserver(observer);
+
+    // Act 1: Attach child
+    const child = new SimpleWorkflow('Child', parent);
+    const attachCount = treeChanges.length;
+
+    // Act 2: Detach child
+    treeChanges.length = 0; // Clear to only track detach
+    parent.detachChild(child);
+
+    // Assert: Both attach and detach should trigger onTreeChanged
+    expect(treeChanges.length).toBe(1);
+    expect(treeChanges[0].root).toBe(parent.getNode());
+  });
+});

package/src/__tests__/unit/workflow-isDescendantOf.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect } from "vitest";
+import { Workflow } from "../../core/workflow.js";
+
+/**
+ * Test suite for public isDescendantOf() API.
+ *
+ * These tests verify that the isDescendantOf() method is publicly accessible
+ * without requiring (as any) type casting, following the P1.M3.T4.S2 PRP
+ * implementation for making this method public.
+ */
+describe("Workflow.isDescendantOf() - Public API", () => {
+  describe("Public API Accessibility", () => {
+    it("should be publicly accessible without casting to any", () => {
+      const root = new Workflow("root");
+      const child = new Workflow("child", root);
+
+      // This should work without (as any) cast - verifies public visibility
+      const result = child.isDescendantOf(root);
+
+      expect(result).toBe(true);
+    });
+
+    it("should return true for direct parent relationship", () => {
+      const root = new Workflow("root");
+      const child = new Workflow("child", root);
+
+      const result = child.isDescendantOf(root);
+
+      expect(result).toBe(true);
+    });
+
+    it("should return true for nested descendant relationship", () => {
+      const root = new Workflow("root");
+      const level1 = new Workflow("level1", root);
+      const level2 = new Workflow("level2", level1);
+      const level3 = new Workflow("level3", level2);
+
+      expect(level1.isDescendantOf(root)).toBe(true);
+      expect(level2.isDescendantOf(root)).toBe(true);
+      expect(level3.isDescendantOf(root)).toBe(true);
+      expect(level3.isDescendantOf(level1)).toBe(true);
+    });
+
+    it("should return false for unrelated workflows", () => {
+      const tree1 = new Workflow("tree1");
+      const tree2 = new Workflow("tree2");
+
+      const result = tree1.isDescendantOf(tree2);
+
+      expect(result).toBe(false);
+    });
+
+    it("should return false when checking root against descendant", () => {
+      const root = new Workflow("root");
+      const child = new Workflow("child", root);
+
+      const result = root.isDescendantOf(child);
+
+      expect(result).toBe(false);
+    });
+
+    it("should return false for root checking itself", () => {
+      const root = new Workflow("root");
+
+      const result = root.isDescendantOf(root);
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe("Use Case: Hierarchy Validation", () => {
+    it("should support validating workflow belongs to specific hierarchy", () => {
+      const productionRoot = new Workflow("production-root");
+      const stagingRoot = new Workflow("staging-root");
+
+      const prodWorkflow = new Workflow("prod-workflow", productionRoot);
+      const stagingWorkflow = new Workflow("staging-workflow", stagingRoot);
+
+      expect(prodWorkflow.isDescendantOf(productionRoot)).toBe(true);
+      expect(prodWorkflow.isDescendantOf(stagingRoot)).toBe(false);
+      expect(stagingWorkflow.isDescendantOf(stagingRoot)).toBe(true);
+      expect(stagingWorkflow.isDescendantOf(productionRoot)).toBe(false);
+    });
+  });
+
+  describe("Use Case: Circular Reference Prevention", () => {
+    it("should support validation before attaching to prevent circular references", () => {
+      const root = new Workflow("root");
+      const child = new Workflow("child", root);
+      const grandchild = new Workflow("grandchild", child);
+
+      // grandchild should NOT be attachable to root (would create cycle)
+      expect(grandchild.isDescendantOf(root)).toBe(true);
+
+      // Unrelated workflow should be attachable
+      const unrelated = new Workflow("unrelated");
+      expect(unrelated.isDescendantOf(root)).toBe(false);
+    });
+  });
+
+  describe("Use Case: Conditional Logic Based on Ancestry", () => {
+    it("should support conditional execution based on hierarchy position", () => {
+      const productionRoot = new Workflow("production-root");
+      const developmentRoot = new Workflow("development-root");
+
+      const prodBatch = new Workflow("prod-batch", productionRoot);
+      const devBatch = new Workflow("dev-batch", developmentRoot);
+
+      // Simulate conditional logic
+      const isInProduction = prodBatch.isDescendantOf(productionRoot);
+      const isProductionWorkflow = devBatch.isDescendantOf(productionRoot);
+
+      expect(isInProduction).toBe(true);
+      expect(isProductionWorkflow).toBe(false);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle workflows with no parent", () => {
+      const orphan = new Workflow("orphan");
+      const root = new Workflow("root");
+
+      const result = orphan.isDescendantOf(root);
+
+      expect(result).toBe(false);
+    });
+
+    it("should handle sibling relationships correctly", () => {
+      const root = new Workflow("root");
+      const sibling1 = new Workflow("sibling1", root);
+      const sibling2 = new Workflow("sibling2", root);
+
+      // Siblings are not descendants of each other
+      expect(sibling1.isDescendantOf(sibling2)).toBe(false);
+      expect(sibling2.isDescendantOf(sibling1)).toBe(false);
+    });
+
+    it("should handle complex multi-level hierarchies", () => {
+      const root = new Workflow("root");
+      const branch1 = new Workflow("branch1", root);
+      const branch2 = new Workflow("branch2", root);
+      const leaf1a = new Workflow("leaf1a", branch1);
+      const leaf1b = new Workflow("leaf1b", branch1);
+      const leaf2a = new Workflow("leaf2a", branch2);
+
+      // All leafs should be descendants of root
+      expect(leaf1a.isDescendantOf(root)).toBe(true);
+      expect(leaf1b.isDescendantOf(root)).toBe(true);
+      expect(leaf2a.isDescendantOf(root)).toBe(true);
+
+      // Leaf1a should not be descendant of branch2
+      expect(leaf1a.isDescendantOf(branch2)).toBe(false);
+
+      // Leaf2a should not be descendant of branch1
+      expect(leaf2a.isDescendantOf(branch1)).toBe(false);
+    });
+  });
+
+  describe("Edge Cases: Circular Reference Detection", () => {
+    it("should throw error when circular reference is detected", () => {
+      // Arrange: Create parent and child workflows with circular reference
+      const parent = new Workflow("Parent");
+      const child = new Workflow("Child", parent);
+      const unrelated = new Workflow("Unrelated");
+
+      // Act: Create circular reference manually
+      // This simulates a bug or malicious input that creates a cycle
+      // Normal attachChild() prevents this, so we bypass normal safeguards
+      parent.parent = child;
+
+      // Assert: isDescendantOf should throw error for circular reference
+      // We use 'unrelated' as the ancestor to force traversal through the cycle
+      // If we used 'child', the method would return true immediately before
+      // detecting the cycle (since child === child at first iteration)
+      expect(() => parent.isDescendantOf(unrelated)).toThrow(
+        "Circular parent-child relationship detected",
+      );
+    });
+  });
+});