groundswell 0.0.2 → 1.0.0

package/src/__tests__/unit/cache-key.test.ts

@@ -1,182 +0,0 @@
-/**
- * Unit tests for cache key generation
- */
-
-import { describe, it, expect } from 'vitest';
-import { z } from 'zod';
-import {
-  deterministicStringify,
-  generateCacheKey,
-  getSchemaHash,
-} from '../../cache/cache-key.js';
-
-describe('deterministicStringify', () => {
-  it('should produce same output for same object regardless of key order', () => {
-    const obj1 = { b: 2, a: 1 };
-    const obj2 = { a: 1, b: 2 };
-
-    expect(deterministicStringify(obj1)).toBe(deterministicStringify(obj2));
-  });
-
-  it('should handle primitives correctly', () => {
-    expect(deterministicStringify(null)).toBe('null');
-    expect(deterministicStringify(undefined)).toBe('undefined');
-    expect(deterministicStringify(true)).toBe('true');
-    expect(deterministicStringify(false)).toBe('false');
-    expect(deterministicStringify(42)).toBe('42');
-    expect(deterministicStringify('hello')).toBe('"hello"');
-  });
-
-  it('should handle arrays correctly', () => {
-    expect(deterministicStringify([1, 2, 3])).toBe('[1,2,3]');
-    expect(deterministicStringify(['a', 'b'])).toBe('["a","b"]');
-  });
-
-  it('should handle nested objects with sorted keys', () => {
-    const obj = { z: { b: 2, a: 1 }, y: [3, 2, 1] };
-    const result = deterministicStringify(obj);
-
-    // Keys should be sorted: y before z, a before b
-    expect(result).toBe('{"y":[3,2,1],"z":{"a":1,"b":2}}');
-  });
-
-  it('should throw on circular references', () => {
-    const obj: Record<string, unknown> = { a: 1 };
-    obj.self = obj;
-
-    expect(() => deterministicStringify(obj)).toThrow(
-      'Converting circular structure to JSON'
-    );
-  });
-
-  it('should handle Date objects', () => {
-    const date = new Date('2024-01-15T10:30:00.000Z');
-    const result = deterministicStringify(date);
-
-    expect(result).toBe('"2024-01-15T10:30:00.000Z"');
-  });
-
-  it('should handle Map objects', () => {
-    const map = new Map([
-      ['z', 1],
-      ['a', 2],
-    ]);
-    const result = deterministicStringify(map);
-
-    // Keys should be sorted in the output
-    expect(result).toContain('Map{');
-    expect(result).toContain('"a"');
-    expect(result).toContain('"z"');
-  });
-
-  it('should handle Set objects', () => {
-    const set = new Set([3, 1, 2]);
-    const result = deterministicStringify(set);
-
-    expect(result).toContain('Set{');
-  });
-});
-
-describe('getSchemaHash', () => {
-  it('should produce consistent hash for same schema', () => {
-    const schema1 = z.object({ name: z.string() });
-    const schema2 = z.object({ name: z.string() });
-
-    expect(getSchemaHash(schema1)).toBe(getSchemaHash(schema2));
-  });
-
-  it('should produce different hashes for different schemas', () => {
-    const schema1 = z.object({ name: z.string() });
-    const schema2 = z.object({ age: z.number() });
-
-    expect(getSchemaHash(schema1)).not.toBe(getSchemaHash(schema2));
-  });
-
-  it('should handle undefined schema', () => {
-    expect(getSchemaHash(undefined)).toBe('no-schema');
-  });
-
-  it('should produce 64-character hex string', () => {
-    const schema = z.object({ value: z.number() });
-    const hash = getSchemaHash(schema);
-
-    expect(hash).toMatch(/^[a-f0-9]{64}$/);
-  });
-});
-
-describe('generateCacheKey', () => {
-  it('should produce same key for identical inputs', () => {
-    const inputs1 = {
-      user: 'Hello',
-      model: 'claude-sonnet-4-20250514',
-      data: { value: 42 },
-    };
-    const inputs2 = {
-      user: 'Hello',
-      model: 'claude-sonnet-4-20250514',
-      data: { value: 42 },
-    };
-
-    expect(generateCacheKey(inputs1)).toBe(generateCacheKey(inputs2));
-  });
-
-  it('should produce different keys for different inputs', () => {
-    const inputs1 = {
-      user: 'Hello',
-      model: 'claude-sonnet-4-20250514',
-    };
-    const inputs2 = {
-      user: 'Goodbye',
-      model: 'claude-sonnet-4-20250514',
-    };
-
-    expect(generateCacheKey(inputs1)).not.toBe(generateCacheKey(inputs2));
-  });
-
-  it('should produce 64-character hex string', () => {
-    const key = generateCacheKey({
-      user: 'Test',
-      model: 'claude-sonnet-4-20250514',
-    });
-
-    expect(key).toMatch(/^[a-f0-9]{64}$/);
-  });
-
-  it('should include tools in key generation (sorted)', () => {
-    const toolSchema = { type: 'object' as const, properties: {}, required: [] };
-    const inputs1 = {
-      user: 'Hello',
-      model: 'claude-sonnet-4-20250514',
-      tools: [
-        { name: 'tool_b', description: 'B', input_schema: toolSchema },
-        { name: 'tool_a', description: 'A', input_schema: toolSchema },
-      ],
-    };
-    const inputs2 = {
-      user: 'Hello',
-      model: 'claude-sonnet-4-20250514',
-      tools: [
-        { name: 'tool_a', description: 'A', input_schema: toolSchema },
-        { name: 'tool_b', description: 'B', input_schema: toolSchema },
-      ],
-    };
-
-    // Same tools in different order should produce same key
-    expect(generateCacheKey(inputs1)).toBe(generateCacheKey(inputs2));
-  });
-
-  it('should include schema hash in key', () => {
-    const schema = z.object({ result: z.string() });
-    const inputs1 = {
-      user: 'Hello',
-      model: 'claude-sonnet-4-20250514',
-      responseFormat: schema,
-    };
-    const inputs2 = {
-      user: 'Hello',
-      model: 'claude-sonnet-4-20250514',
-    };
-
-    expect(generateCacheKey(inputs1)).not.toBe(generateCacheKey(inputs2));
-  });
-});

package/src/__tests__/unit/cache.test.ts

@@ -1,172 +0,0 @@
-/**
- * Unit tests for LLMCache
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import { LLMCache } from '../../cache/cache.js';
-
-describe('LLMCache', () => {
-  let cache: LLMCache;
-
-  beforeEach(() => {
-    cache = new LLMCache({ maxItems: 10 });
-  });
-
-  describe('get/set', () => {
-    it('should store and retrieve values', async () => {
-      await cache.set('key1', { data: 'test' });
-      const result = await cache.get('key1');
-
-      expect(result).toEqual({ data: 'test' });
-    });
-
-    it('should return undefined for missing keys', async () => {
-      const result = await cache.get('nonexistent');
-
-      expect(result).toBeUndefined();
-    });
-
-    it('should update existing keys', async () => {
-      await cache.set('key1', 'first');
-      await cache.set('key1', 'second');
-
-      const result = await cache.get('key1');
-      expect(result).toBe('second');
-    });
-  });
-
-  describe('has', () => {
-    it('should return true for existing keys', async () => {
-      await cache.set('key1', 'value');
-
-      expect(cache.has('key1')).toBe(true);
-    });
-
-    it('should return false for missing keys', () => {
-      expect(cache.has('nonexistent')).toBe(false);
-    });
-  });
-
-  describe('bust', () => {
-    it('should remove specific key', async () => {
-      await cache.set('key1', 'value1');
-      await cache.set('key2', 'value2');
-
-      await cache.bust('key1');
-
-      expect(cache.has('key1')).toBe(false);
-      expect(cache.has('key2')).toBe(true);
-    });
-
-    it('should not throw for missing keys', async () => {
-      await expect(cache.bust('nonexistent')).resolves.not.toThrow();
-    });
-  });
-
-  describe('bustPrefix', () => {
-    it('should remove all keys with given prefix', async () => {
-      await cache.set('key1', 'value1', { prefix: 'group-a' });
-      await cache.set('key2', 'value2', { prefix: 'group-a' });
-      await cache.set('key3', 'value3', { prefix: 'group-b' });
-
-      await cache.bustPrefix('group-a');
-
-      expect(cache.has('key1')).toBe(false);
-      expect(cache.has('key2')).toBe(false);
-      expect(cache.has('key3')).toBe(true);
-    });
-
-    it('should not throw for nonexistent prefix', async () => {
-      await expect(cache.bustPrefix('nonexistent')).resolves.not.toThrow();
-    });
-  });
-
-  describe('clear', () => {
-    it('should remove all entries', async () => {
-      await cache.set('key1', 'value1');
-      await cache.set('key2', 'value2');
-
-      await cache.clear();
-
-      expect(cache.size).toBe(0);
-    });
-
-    it('should reset metrics', async () => {
-      await cache.set('key1', 'value1');
-      await cache.get('key1'); // hit
-      await cache.get('key2'); // miss
-
-      await cache.clear();
-
-      const metrics = cache.metrics();
-      expect(metrics.hits).toBe(0);
-      expect(metrics.misses).toBe(0);
-    });
-  });
-
-  describe('metrics', () => {
-    it('should track hits and misses', async () => {
-      await cache.set('key1', 'value1');
-
-      await cache.get('key1'); // hit
-      await cache.get('key1'); // hit
-      await cache.get('key2'); // miss
-
-      const metrics = cache.metrics();
-      expect(metrics.hits).toBe(2);
-      expect(metrics.misses).toBe(1);
-      expect(metrics.hitRate).toBeCloseTo(66.67, 0);
-    });
-
-    it('should track size', async () => {
-      await cache.set('key1', 'value1');
-      await cache.set('key2', 'value2');
-
-      const metrics = cache.metrics();
-      expect(metrics.size).toBe(2);
-    });
-  });
-
-  describe('LRU eviction', () => {
-    it('should evict least recently used items when maxItems exceeded', async () => {
-      const smallCache = new LLMCache({ maxItems: 3 });
-
-      await smallCache.set('key1', 'value1');
-      await smallCache.set('key2', 'value2');
-      await smallCache.set('key3', 'value3');
-      await smallCache.set('key4', 'value4');
-
-      // key1 should be evicted (least recently used)
-      expect(smallCache.has('key1')).toBe(false);
-      expect(smallCache.has('key4')).toBe(true);
-    });
-
-    it('should update LRU order on get', async () => {
-      const smallCache = new LLMCache({ maxItems: 3 });
-
-      await smallCache.set('key1', 'value1');
-      await smallCache.set('key2', 'value2');
-      await smallCache.set('key3', 'value3');
-
-      // Access key1 to make it most recently used
-      await smallCache.get('key1');
-
-      // Add new item, should evict key2 instead of key1
-      await smallCache.set('key4', 'value4');
-
-      expect(smallCache.has('key1')).toBe(true);
-      expect(smallCache.has('key2')).toBe(false);
-    });
-  });
-
-  describe('keys', () => {
-    it('should return iterator of all keys', async () => {
-      await cache.set('key1', 'value1');
-      await cache.set('key2', 'value2');
-
-      const keys = Array.from(cache.keys());
-      expect(keys).toContain('key1');
-      expect(keys).toContain('key2');
-    });
-  });
-});

package/src/__tests__/unit/context.test.ts

@@ -1,217 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import {
-  getExecutionContext,
-  requireExecutionContext,
-  runInContext,
-  runInContextSync,
-  hasExecutionContext,
-  createChildContext,
-  type AgentExecutionContext,
-} from '../../core/context.js';
-import type { WorkflowNode, WorkflowEvent } from '../../types/index.js';
-import { Workflow, WorkflowObserver, ObservedState } from '../../index.js';
-
-describe('AgentExecutionContext', () => {
-  const createMockNode = (name: string): WorkflowNode => ({
-    id: `node-${name}`,
-    name,
-    parent: null,
-    children: [],
-    status: 'running',
-    logs: [],
-    events: [],
-    stateSnapshot: null,
-  });
-
-  const createMockContext = (name: string): AgentExecutionContext => ({
-    workflowNode: createMockNode(name),
-    emitEvent: () => {},
-    workflowId: `workflow-${name}`,
-  });
-
-  it('should return undefined outside of context', () => {
-    expect(getExecutionContext()).toBeUndefined();
-  });
-
-  it('should throw when requiring context outside of context', () => {
-    expect(() => requireExecutionContext('test operation')).toThrow(
-      'test operation called outside of workflow context'
-    );
-  });
-
-  it('should detect context availability', () => {
-    expect(hasExecutionContext()).toBe(false);
-  });
-
-  it('should provide context within runInContext', async () => {
-    const ctx = createMockContext('test');
-
-    await runInContext(ctx, async () => {
-      expect(hasExecutionContext()).toBe(true);
-      expect(getExecutionContext()).toBe(ctx);
-      expect(requireExecutionContext('test')).toBe(ctx);
-    });
-
-    // Context should be gone after run completes
-    expect(hasExecutionContext()).toBe(false);
-  });
-
-  it('should provide context within sync runInContextSync', () => {
-    const ctx = createMockContext('test');
-
-    runInContextSync(ctx, () => {
-      expect(hasExecutionContext()).toBe(true);
-      expect(getExecutionContext()).toBe(ctx);
-    });
-
-    expect(hasExecutionContext()).toBe(false);
-  });
-
-  it('should propagate context through nested async calls', async () => {
-    const ctx = createMockContext('root');
-
-    const nested = async () => {
-      const innerCtx = getExecutionContext();
-      return innerCtx?.workflowNode.name;
-    };
-
-    await runInContext(ctx, async () => {
-      const name = await nested();
-      expect(name).toBe('root');
-    });
-  });
-
-  it('should create child context with new node', async () => {
-    const parentCtx = createMockContext('parent');
-    const childNode = createMockNode('child');
-
-    await runInContext(parentCtx, async () => {
-      const childCtx = createChildContext(childNode);
-      expect(childCtx).toBeDefined();
-      expect(childCtx?.workflowNode).toBe(childNode);
-      expect(childCtx?.workflowId).toBe(parentCtx.workflowId);
-    });
-  });
-
-  it('should return undefined for child context when not in context', () => {
-    const childNode = createMockNode('child');
-    const childCtx = createChildContext(childNode);
-    expect(childCtx).toBeUndefined();
-  });
-
-  it('should allow nested contexts', async () => {
-    const outerCtx = createMockContext('outer');
-    const innerCtx = createMockContext('inner');
-
-    await runInContext(outerCtx, async () => {
-      expect(getExecutionContext()?.workflowNode.name).toBe('outer');
-
-      await runInContext(innerCtx, async () => {
-        expect(getExecutionContext()?.workflowNode.name).toBe('inner');
-      });
-
-      // Should restore outer context
-      expect(getExecutionContext()?.workflowNode.name).toBe('outer');
-    });
-  });
-
-  it('should capture emitted events', async () => {
-    const events: WorkflowEvent[] = [];
-    const node = createMockNode('test');
-    const ctx: AgentExecutionContext = {
-      workflowNode: node,
-      emitEvent: (event) => events.push(event),
-      workflowId: 'wf-1',
-    };
-
-    await runInContext(ctx, async () => {
-      const currentCtx = requireExecutionContext('emit');
-      currentCtx.emitEvent({
-        type: 'stepStart',
-        node: currentCtx.workflowNode,
-        step: 'test-step',
-      });
-    });
-
-    expect(events).toHaveLength(1);
-    expect(events[0].type).toBe('stepStart');
-  });
-});
-
-describe('WorkflowContext', () => {
-  // Test workflow class with @ObservedState decorated fields
-  class StatefulTestWorkflow extends Workflow {
-    @ObservedState()
-    stepCount: number = 0;
-
-    @ObservedState({ redact: true })
-    apiKey: string = 'secret-key-123';
-
-    @ObservedState({ hidden: true })
-    internalCounter: number = 42;
-  }
-
-  it('should capture state and logs in step() error handler', async () => {
-    // Arrange: Create observer to capture error events
-    const events: WorkflowEvent[] = [];
-
-    const observer: WorkflowObserver = {
-      onLog: () => {},
-      onEvent: (event) => events.push(event),
-      onStateUpdated: () => {},
-      onTreeChanged: () => {},
-    };
-
-    // Arrange: Create workflow with @ObservedState fields using functional executor
-    const workflow = new StatefulTestWorkflow(
-      { name: 'StepErrorTest' },
-      async (ctx) => {
-        // Modify @ObservedState fields on the workflow instance
-        (workflow as any).stepCount = 5;
-        (workflow as any).apiKey = 'updated-key';
-        (workflow as any).internalCounter = 99;
-
-        // Execute a step that will fail - THIS TRIGGERS WorkflowContext.step() ERROR HANDLER
-        await ctx.step('failing-step', async () => {
-          throw new Error('Test error from step');
-        });
-      }
-    );
-
-    // Act: Attach observer and trigger error
-    workflow.addObserver(observer);
-    await expect(workflow.run()).rejects.toThrow('Test error from step');
-
-    // Assert: Verify error event was emitted
-    const errorEvents = events.filter((e) => e.type === 'error');
-    expect(errorEvents.length).toBeGreaterThanOrEqual(1);
-
-    // Assert: Verify error structure
-    const errorEvent = errorEvents[0];
-    expect(errorEvent.error).toBeDefined();
-    expect(errorEvent.error.message).toBe('Test error from step');
-
-    // Assert: Verify @ObservedState fields were captured in state
-    expect(errorEvent.error.state).toBeDefined();
-    expect(typeof errorEvent.error.state).toBe('object');
-
-    // Assert: Verify public field value is captured
-    expect(errorEvent.error.state.stepCount).toBe(5);
-
-    // Assert: Verify redacted field shows '***'
-    expect(errorEvent.error.state.apiKey).toBe('***');
-
-    // Assert: Verify hidden field is NOT in state
-    expect('internalCounter' in errorEvent.error.state).toBe(false);
-
-    // Assert: Verify logs array is present (may be empty)
-    expect(errorEvent.error.logs).toBeDefined();
-    expect(Array.isArray(errorEvent.error.logs)).toBe(true);
-
-    // Assert: Verify workflow status
-    expect(workflow.status).toBe('failed');
-
-    // Assert: Verify workflowId is captured
-    expect(errorEvent.error.workflowId).toBe(workflow.id);
-  });
-});

package/src/__tests__/unit/decorators.test.ts

@@ -1,100 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { Workflow, Step, Task, ObservedState, getObservedState, WorkflowEvent, WorkflowObserver } from '../../index.js';
-
-describe('@Step decorator', () => {
-  class StepTestWorkflow extends Workflow {
-    stepCalled = false;
-
-    @Step({ trackTiming: true })
-    async myStep(): Promise<string> {
-      this.stepCalled = true;
-      return 'step result';
-    }
-
-    async run(): Promise<void> {
-      await this.myStep();
-    }
-  }
-
-  it('should execute the original method', async () => {
-    const wf = new StepTestWorkflow();
-    await wf.run();
-    expect(wf.stepCalled).toBe(true);
-  });
-
-  it('should emit stepStart and stepEnd events', async () => {
-    const wf = new StepTestWorkflow();
-    const events: WorkflowEvent[] = [];
-
-    wf.addObserver({
-      onLog: () => {},
-      onEvent: (e) => events.push(e),
-      onStateUpdated: () => {},
-      onTreeChanged: () => {},
-    });
-
-    await wf.run();
-
-    const startEvent = events.find((e) => e.type === 'stepStart');
-    const endEvent = events.find((e) => e.type === 'stepEnd');
-
-    expect(startEvent).toBeDefined();
-    expect(endEvent).toBeDefined();
-    if (endEvent?.type === 'stepEnd') {
-      expect(endEvent.duration).toBeGreaterThanOrEqual(0);
-    }
-  });
-
-  it('should wrap errors in WorkflowError', async () => {
-    class FailingWorkflow extends Workflow {
-      @Step()
-      async failingStep(): Promise<void> {
-        throw new Error('Step failed');
-      }
-
-      async run(): Promise<void> {
-        await this.failingStep();
-      }
-    }
-
-    const wf = new FailingWorkflow();
-
-    await expect(wf.run()).rejects.toMatchObject({
-      message: 'Step failed',
-      workflowId: wf.id,
-    });
-  });
-});
-
-describe('@ObservedState decorator', () => {
-  class StateTestWorkflow extends Workflow {
-    @ObservedState()
-    publicField: string = 'public';
-
-    @ObservedState({ redact: true })
-    secretField: string = 'secret';
-
-    @ObservedState({ hidden: true })
-    hiddenField: string = 'hidden';
-
-    async run(): Promise<void> {}
-  }
-
-  it('should include public fields in snapshot', () => {
-    const wf = new StateTestWorkflow();
-    const state = getObservedState(wf);
-    expect(state.publicField).toBe('public');
-  });
-
-  it('should redact secret fields', () => {
-    const wf = new StateTestWorkflow();
-    const state = getObservedState(wf);
-    expect(state.secretField).toBe('***');
-  });
-
-  it('should exclude hidden fields', () => {
-    const wf = new StateTestWorkflow();
-    const state = getObservedState(wf);
-    expect('hiddenField' in state).toBe(false);
-  });
-});