@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/testing/mock-approval.js

@@ -1,98 +0,0 @@
-/**
- * Mock Approval Provider for deterministic human-approval workflow testing.
- *
- * Mirrors the mock LLM provider pattern — pattern matching on prompts,
- * call recording, and configurable responses.
- *
- * Usage in vitest/jest tests:
- * ```typescript
- * import { createMockApprovalProvider } from 'flow-weaver/testing';
- *
- * const mockApproval = createMockApprovalProvider([
- *   { match: /expense/, response: { approved: true, reviewer: 'alice' } },
- *   { match: /delete/, response: { approved: false, response: 'Too risky' } },
- *   { match: /./, response: { approved: true } },
- * ]);
- *
- * // Inject globally for compiled workflows
- * (globalThis as unknown as { __fw_approval_provider__?: ApprovalProvider })
- *   .__fw_approval_provider__ = mockApproval;
- *
- * // After test
- * expect(mockApproval.getCallCount()).toBe(2);
- * ```
- */
-const FALLBACK_RESULT = {
-    approved: false,
-    response: '[Mock: no matching approval response configured]',
-};
-/**
- * Creates a mock approval provider with deterministic response matching.
- *
- * Responses are matched in order against the approval request prompt.
- * First match wins. If no response matches, a fallback result is returned.
- *
- * @param responses - Array of match/response pairs, checked in order
- * @param options - Configuration options
- * @returns A mock provider with call recording
- */
-export function createMockApprovalProvider(responses = [], options) {
-    const calls = [];
-    const useCounts = new Map();
-    const fallback = options?.fallbackResponse ?? FALLBACK_RESULT;
-    function findMatch(prompt) {
-        for (let i = 0; i < responses.length; i++) {
-            const def = responses[i];
-            // Check max uses
-            if (def.maxUses !== undefined) {
-                const used = useCounts.get(i) ?? 0;
-                if (used >= def.maxUses)
-                    continue;
-            }
-            const matches = typeof def.match === 'string'
-                ? prompt.includes(def.match)
-                : def.match.test(prompt);
-            if (matches) {
-                return { index: i, response: def };
-            }
-        }
-        return null;
-    }
-    return {
-        async requestApproval(request) {
-            const match = findMatch(request.prompt);
-            let result;
-            let matchedIndex;
-            if (match) {
-                matchedIndex = match.index;
-                useCounts.set(matchedIndex, (useCounts.get(matchedIndex) ?? 0) + 1);
-                result = { ...match.response.response };
-            }
-            else {
-                matchedIndex = -1;
-                result = { ...fallback };
-            }
-            calls.push({
-                request: { ...request },
-                matchedIndex,
-                result,
-                timestamp: Date.now(),
-            });
-            return result;
-        },
-        getCalls() {
-            return [...calls];
-        },
-        getCallCount() {
-            return calls.length;
-        },
-        reset() {
-            calls.length = 0;
-            useCounts.clear();
-        },
-        getCallsForResponse(index) {
-            return calls.filter((c) => c.matchedIndex === index);
-        },
-    };
-}
-//# sourceMappingURL=mock-approval.js.map

package/dist/testing/mock-llm.js

@@ -1,119 +0,0 @@
-/**
- * Mock LLM Provider for deterministic agent workflow testing.
- *
- * Usage in vitest/jest tests:
- * ```typescript
- * import { createMockLlmProvider } from 'flow-weaver/testing';
- *
- * const mockLlm = createMockLlmProvider([
- *   { match: /search/, response: { content: null, toolCalls: [{ id: '1', name: 'search', arguments: { q: 'test' } }], finishReason: 'tool_calls' } },
- *   { match: /./, response: { content: 'Default answer', toolCalls: [], finishReason: 'stop' } },
- * ]);
- *
- * // Inject globally for compiled workflows
- * (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ = mockLlm;
- *
- * // After test
- * expect(mockLlm.getCallCount()).toBe(2);
- * expect(mockLlm.getTotalTokens()).toBe(150);
- * ```
- */
-const DEFAULT_USAGE = {
-    promptTokens: 50,
-    completionTokens: 25,
-    totalTokens: 75,
-};
-const FALLBACK_RESPONSE = {
-    content: '[Mock: no matching response configured]',
-    toolCalls: [],
-    finishReason: 'stop',
-    usage: DEFAULT_USAGE,
-};
-/**
- * Creates a mock LLM provider with deterministic response matching.
- *
- * Responses are matched in order against the last user message content.
- * First match wins. If no response matches, a fallback response is returned.
- *
- * @param responses - Array of match/response pairs, checked in order
- * @param options - Configuration options
- * @returns A mock provider with call recording and token tracking
- */
-export function createMockLlmProvider(responses = [], options) {
-    const calls = [];
-    const useCounts = new Map();
-    const defaultUsage = options?.defaultUsage ?? DEFAULT_USAGE;
-    const fallback = {
-        ...FALLBACK_RESPONSE,
-        ...(options?.fallbackResponse ?? {}),
-        usage: options?.fallbackResponse?.usage ?? defaultUsage,
-    };
-    function findMatch(lastMessage) {
-        for (let i = 0; i < responses.length; i++) {
-            const def = responses[i];
-            // Check max uses
-            if (def.maxUses !== undefined) {
-                const used = useCounts.get(i) ?? 0;
-                if (used >= def.maxUses)
-                    continue;
-            }
-            const matches = typeof def.match === 'string'
-                ? lastMessage.includes(def.match)
-                : def.match.test(lastMessage);
-            if (matches) {
-                return { index: i, response: def };
-            }
-        }
-        return null;
-    }
-    return {
-        async chat(messages, chatOptions) {
-            const lastUserMessage = [...messages].reverse().find((m) => m.role === 'user')?.content ?? '';
-            const match = findMatch(lastUserMessage);
-            let response;
-            let matchedIndex;
-            if (match) {
-                matchedIndex = match.index;
-                useCounts.set(matchedIndex, (useCounts.get(matchedIndex) ?? 0) + 1);
-                response = {
-                    content: match.response.response.content ?? null,
-                    toolCalls: match.response.response.toolCalls ?? [],
-                    finishReason: match.response.response.finishReason ?? 'stop',
-                    usage: match.response.usage ?? defaultUsage,
-                };
-            }
-            else {
-                matchedIndex = -1;
-                response = { ...fallback };
-            }
-            calls.push({
-                messages: [...messages],
-                options: chatOptions,
-                matchedIndex,
-                response,
-                timestamp: Date.now(),
-            });
-            return response;
-        },
-        getCalls() {
-            return [...calls];
-        },
-        getCallCount() {
-            return calls.length;
-        },
-        getTotalTokens() {
-            return calls.reduce((sum, call) => sum + (call.response.usage?.totalTokens ?? 0), 0);
-        },
-        getTokenUsage() {
-            return calls.map((call) => call.response.usage ?? defaultUsage);
-        },
-        reset() {
-            calls.length = 0;
-            useCounts.clear();
-        },
-        getCallsForResponse(index) {
-            return calls.filter((c) => c.matchedIndex === index);
-        },
-    };
-}
-//# sourceMappingURL=mock-llm.js.map

package/dist/testing/recorder.js

@@ -1,70 +0,0 @@
-/**
- * Recording LLM Provider — wraps a real provider and records all interactions.
- *
- * Usage:
- * ```typescript
- * import { createRecordingProvider } from 'flow-weaver/testing';
- *
- * const recorder = createRecordingProvider(realLlmProvider);
- *
- * // Use recorder.provider as the LLM provider in your workflow
- * (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ = recorder.provider;
- *
- * // Run workflow...
- *
- * // Get the recording for later replay
- * const recording = recorder.getRecording();
- * const json = JSON.stringify(recording, null, 2);
- * // Save to disk, fixture file, etc.
- * ```
- */
-/**
- * Creates a recording LLM provider that wraps a real provider.
- *
- * Every call to `chat()` is passed through to the real provider,
- * and the input/output/timing is recorded for later replay.
- *
- * @param realProvider - The real LLM provider to wrap
- * @param metadata - Optional metadata to include in the recording
- * @returns A recording provider with access to the recorded data
- */
-export function createRecordingProvider(realProvider, metadata) {
-    const steps = [];
-    const createdAt = new Date().toISOString();
-    const provider = {
-        async chat(messages, options) {
-            const startTime = Date.now();
-            const timestamp = new Date(startTime).toISOString();
-            const response = await realProvider.chat(messages, options);
-            const durationMs = Date.now() - startTime;
-            steps.push({
-                index: steps.length,
-                input: {
-                    messages: [...messages],
-                    ...(options ? { options: { ...options } } : {}),
-                },
-                output: { ...response },
-                timestamp,
-                durationMs,
-            });
-            return response;
-        },
-    };
-    return {
-        provider,
-        getRecording() {
-            return {
-                steps: steps.map((s) => ({ ...s })),
-                metadata: { ...(metadata ?? {}) },
-                createdAt,
-            };
-        },
-        getCallCount() {
-            return steps.length;
-        },
-        reset() {
-            steps.length = 0;
-        },
-    };
-}
-//# sourceMappingURL=recorder.js.map

package/dist/testing/replayer.js

@@ -1,143 +0,0 @@
-/**
- * Replay LLM Provider — creates a mock provider from a recorded session.
- *
- * Usage:
- * ```typescript
- * import { createReplayProvider, loadRecording } from 'flow-weaver/testing';
- *
- * const recording = loadRecording(jsonFixture);
- * const replay = createReplayProvider(recording);
- *
- * // Use as LLM provider — calls are replayed in order
- * (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ = replay;
- *
- * // Run workflow — LLM calls return recorded responses, no network calls
- *
- * // All MockLlmProvider methods work: getCalls(), getTotalTokens(), etc.
- * expect(replay.getCallCount()).toBe(3);
- * ```
- */
-// ---------------------------------------------------------------------------
-// Replay provider factory
-// ---------------------------------------------------------------------------
-const ZERO_USAGE = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
-/**
- * Creates a MockLlmProvider that replays recorded LLM interactions in order.
- *
- * Each `chat()` call returns the next recorded response sequentially.
- * The returned provider implements the full MockLlmProvider interface,
- * so all existing assertion helpers and TokenTracker work out of the box.
- *
- * @param recording - The recording to replay (from createRecordingProvider or loadRecording)
- * @param options - Replay configuration
- * @returns A MockLlmProvider that replays recorded responses
- */
-export function createReplayProvider(recording, options) {
-    const strict = options?.strict ?? true;
-    const defaultUsage = options?.defaultUsage ?? ZERO_USAGE;
-    const steps = [...recording.steps];
-    let callIndex = 0;
-    const calls = [];
-    return {
-        async chat(messages, chatOptions) {
-            if (callIndex >= steps.length) {
-                if (strict) {
-                    throw new Error(`Replay exhausted: recording has ${steps.length} step(s) but call #${callIndex} was attempted. ` +
-                        `Set strict: false to return a fallback response instead.`);
-                }
-                // Non-strict: return an empty response
-                const fallback = {
-                    content: `[Replay exhausted at call #${callIndex}]`,
-                    toolCalls: [],
-                    finishReason: 'stop',
-                    usage: defaultUsage,
-                };
-                calls.push({
-                    messages: [...messages],
-                    options: chatOptions,
-                    matchedIndex: -1,
-                    response: fallback,
-                    timestamp: Date.now(),
-                });
-                callIndex++;
-                return fallback;
-            }
-            const step = steps[callIndex];
-            const response = {
-                content: step.output.content,
-                toolCalls: step.output.toolCalls ?? [],
-                finishReason: step.output.finishReason ?? 'stop',
-                usage: step.output.usage ?? defaultUsage,
-            };
-            calls.push({
-                messages: [...messages],
-                options: chatOptions,
-                matchedIndex: callIndex,
-                response,
-                timestamp: Date.now(),
-            });
-            callIndex++;
-            return response;
-        },
-        getCalls() {
-            return [...calls];
-        },
-        getCallCount() {
-            return calls.length;
-        },
-        getTotalTokens() {
-            return calls.reduce((sum, call) => sum + (call.response.usage?.totalTokens ?? 0), 0);
-        },
-        getTokenUsage() {
-            return calls.map((call) => call.response.usage ?? defaultUsage);
-        },
-        reset() {
-            calls.length = 0;
-            callIndex = 0;
-        },
-        getCallsForResponse(index) {
-            return calls.filter((c) => c.matchedIndex === index);
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// Loading helpers
-// ---------------------------------------------------------------------------
-/**
- * Parse a recording from JSON data.
- *
- * Accepts either a parsed object or a JSON string.
- * Validates the structure and returns a typed LlmRecording.
- *
- * @param data - JSON string or parsed object
- * @returns A validated LlmRecording
- */
-export function loadRecording(data) {
-    const parsed = typeof data === 'string' ? JSON.parse(data) : data;
-    if (!parsed || typeof parsed !== 'object') {
-        throw new Error('Invalid recording: expected an object');
-    }
-    const rec = parsed;
-    if (!Array.isArray(rec.steps)) {
-        throw new Error('Invalid recording: missing or invalid "steps" array');
-    }
-    // Validate each step has minimum required fields
-    for (let i = 0; i < rec.steps.length; i++) {
-        const step = rec.steps[i];
-        if (!step.output || typeof step.output !== 'object') {
-            throw new Error(`Invalid recording step ${i}: missing "output" object`);
-        }
-    }
-    return {
-        steps: rec.steps.map((step, i) => ({
-            index: step.index ?? i,
-            input: step.input ?? { messages: [] },
-            output: step.output,
-            timestamp: step.timestamp ?? '',
-            durationMs: step.durationMs ?? 0,
-        })),
-        metadata: rec.metadata ?? {},
-        createdAt: rec.createdAt ?? '',
-    };
-}
-//# sourceMappingURL=replayer.js.map

package/dist/testing/token-tracker.js

@@ -1,94 +0,0 @@
-/**
- * Token usage tracker for agent workflow tests.
- *
- * Accumulates token usage across LLM calls and provides
- * budget assertions for cost control testing.
- *
- * Usage:
- * ```typescript
- * import { TokenTracker, createMockLlmProvider } from 'flow-weaver/testing';
- *
- * const tracker = new TokenTracker();
- * const mockLlm = createMockLlmProvider([...]);
- *
- * // After running workflow
- * mockLlm.getCalls().forEach((call, i) => {
- *   tracker.track(`step-${i}`, call.response.usage);
- * });
- *
- * tracker.assertBelow(10000); // Fail if total exceeds budget
- * ```
- */
-export class TokenTracker {
-    steps = [];
-    /** Track token usage for a step */
-    track(step, usage) {
-        const normalized = {
-            promptTokens: usage?.promptTokens ?? 0,
-            completionTokens: usage?.completionTokens ?? 0,
-            totalTokens: usage?.totalTokens ?? 0,
-        };
-        this.steps.push({ step, usage: normalized, timestamp: Date.now() });
-    }
-    /** Total tokens across all tracked steps */
-    get total() {
-        return this.steps.reduce((sum, s) => sum + s.usage.totalTokens, 0);
-    }
-    /** Total prompt tokens */
-    get promptTokens() {
-        return this.steps.reduce((sum, s) => sum + s.usage.promptTokens, 0);
-    }
-    /** Total completion tokens */
-    get completionTokens() {
-        return this.steps.reduce((sum, s) => sum + s.usage.completionTokens, 0);
-    }
-    /** Number of tracked steps */
-    get stepCount() {
-        return this.steps.length;
-    }
-    /** Get all tracked steps */
-    getSteps() {
-        return [...this.steps];
-    }
-    /** Get usage for a specific step by name */
-    getStep(step) {
-        return this.steps.find((s) => s.step === step);
-    }
-    /**
-     * Assert total tokens are below a budget.
-     * Throws with a descriptive message if exceeded.
-     */
-    assertBelow(maxTokens) {
-        if (this.total > maxTokens) {
-            const breakdown = this.steps
-                .map((s) => `  ${s.step}: ${s.usage.totalTokens} tokens`)
-                .join('\n');
-            throw new Error(`Token budget exceeded: ${this.total} > ${maxTokens}\n` +
-                `Breakdown (${this.steps.length} steps):\n${breakdown}`);
-        }
-    }
-    /**
-     * Assert total tokens are above a minimum.
-     * Useful to verify the LLM was actually called.
-     */
-    assertAbove(minTokens) {
-        if (this.total < minTokens) {
-            throw new Error(`Token usage too low: ${this.total} < ${minTokens}. Was the LLM actually called?`);
-        }
-    }
-    /** Reset all tracking data */
-    reset() {
-        this.steps.length = 0;
-    }
-    /**
-     * Convenience: track all calls from a mock LLM provider.
-     * Uses call index as step name unless a nameResolver is provided.
-     */
-    trackFromCalls(calls, nameResolver) {
-        calls.forEach((call, i) => {
-            const step = nameResolver ? nameResolver(i) : `call-${i}`;
-            this.track(step, call.response.usage);
-        });
-    }
-}
-//# sourceMappingURL=token-tracker.js.map

package/dist/type-checker.d.ts

@@ -1,42 +0,0 @@
-/**
- * Type Checker Module
- *
- * Provides TypeScript-level type compatibility checking using ts-morph and TypeScript's compiler API.
- * This enables proper structural typing and subtype checking beyond simple string comparison.
- */
-import type { Type, TypeChecker } from "ts-morph";
-import type { TTypeCompatibility } from "./ast/types.js";
-/**
- * Check if a source type can be safely coerced to a target type at runtime.
- *
- * @param sourceText - The source type as a string
- * @param targetText - The target type as a string
- * @returns true if the coercion is safe
- */
-export declare function isRuntimeCoercible(sourceText: string, targetText: string): boolean;
-/**
- * Check type compatibility between two ts-morph Type objects.
- *
- * This uses TypeScript's actual type system for proper structural typing:
- * - Structural typing (duck typing)
- * - Inheritance (Admin extends User)
- * - Generics (Array<T>, Promise<T>)
- * - Union/Intersection types
- * - Type narrowing
- *
- * @param sourceType - The source type (from output port)
- * @param targetType - The target type (from input port)
- * @param typeChecker - Optional ts-morph TypeChecker for advanced assignability checks
- * @returns TTypeCompatibility result
- */
-export declare function checkTypeCompatibility(sourceType: Type, targetType: Type, typeChecker?: TypeChecker): TTypeCompatibility;
-/**
- * Check type compatibility using string representations.
- * Fallback for JSON-loaded workflows without ts-morph Type objects.
- *
- * @param sourceText - The source type as a string
- * @param targetText - The target type as a string
- * @returns TTypeCompatibility result
- */
-export declare function checkTypeCompatibilityFromStrings(sourceText: string, targetText: string): TTypeCompatibility;
-//# sourceMappingURL=type-checker.d.ts.map