reqon-dsl 0.2.0

package/dist/interpreter/progress.test.js

@@ -0,0 +1,216 @@
+import { describe, it, expect, vi } from 'vitest';
+import { MissionExecutor } from './executor.js';
+function createTestProgram(stages) {
+    const actions = stages.map((name) => ({
+        type: 'ActionDefinition',
+        name,
+        steps: [],
+    }));
+    const pipeline = {
+        type: 'PipelineDefinition',
+        stages: stages.map((action) => ({ action })),
+    };
+    const mission = {
+        type: 'MissionDefinition',
+        name: 'TestMission',
+        sources: [],
+        stores: [],
+        schemas: [],
+        actions,
+        pipeline,
+    };
+    return {
+        type: 'ReqonProgram',
+        statements: [mission],
+    };
+}
+describe('Progress Callbacks', () => {
+    describe('onExecutionStart', () => {
+        it('is called when execution begins', async () => {
+            const onExecutionStart = vi.fn();
+            const executor = new MissionExecutor({
+                progress: { onExecutionStart },
+            });
+            await executor.execute(createTestProgram(['StepA', 'StepB']));
+            expect(onExecutionStart).toHaveBeenCalledOnce();
+            expect(onExecutionStart).toHaveBeenCalledWith(expect.objectContaining({
+                mission: 'TestMission',
+                stageCount: 2,
+                isResume: false,
+            }));
+        });
+        it('includes executionId from ephemeral execution', async () => {
+            const onExecutionStart = vi.fn();
+            const executor = new MissionExecutor({
+                progress: { onExecutionStart },
+            });
+            await executor.execute(createTestProgram(['StepA']));
+            expect(onExecutionStart).toHaveBeenCalledWith(expect.objectContaining({
+                executionId: 'ephemeral',
+            }));
+        });
+        it('includes executionId when persistence enabled', async () => {
+            const onExecutionStart = vi.fn();
+            const executor = new MissionExecutor({
+                persistState: true,
+                dataDir: '.reqon-test-progress',
+                progress: { onExecutionStart },
+            });
+            await executor.execute(createTestProgram(['StepA']));
+            expect(onExecutionStart).toHaveBeenCalledWith(expect.objectContaining({
+                executionId: expect.stringMatching(/^exec_/),
+            }));
+        });
+        it('includes metadata if provided', async () => {
+            const onExecutionStart = vi.fn();
+            const executor = new MissionExecutor({
+                metadata: { tenant: 'acme', userId: '123' },
+                progress: { onExecutionStart },
+            });
+            await executor.execute(createTestProgram(['StepA']));
+            expect(onExecutionStart).toHaveBeenCalledWith(expect.objectContaining({
+                metadata: { tenant: 'acme', userId: '123' },
+            }));
+        });
+    });
+    describe('onExecutionComplete', () => {
+        it('is called when execution finishes successfully', async () => {
+            const onExecutionComplete = vi.fn();
+            const executor = new MissionExecutor({
+                progress: { onExecutionComplete },
+            });
+            await executor.execute(createTestProgram(['StepA', 'StepB']));
+            expect(onExecutionComplete).toHaveBeenCalledOnce();
+            expect(onExecutionComplete).toHaveBeenCalledWith(expect.objectContaining({
+                mission: 'TestMission',
+                success: true,
+                stagesCompleted: 2,
+                stagesFailed: 0,
+                errors: [],
+            }));
+        });
+        it('includes duration', async () => {
+            const onExecutionComplete = vi.fn();
+            const executor = new MissionExecutor({
+                progress: { onExecutionComplete },
+            });
+            await executor.execute(createTestProgram(['StepA']));
+            const event = onExecutionComplete.mock.calls[0][0];
+            expect(event.duration).toBeGreaterThanOrEqual(0);
+        });
+    });
+    describe('onStageStart', () => {
+        it('is called for each stage', async () => {
+            const onStageStart = vi.fn();
+            const executor = new MissionExecutor({
+                progress: { onStageStart },
+            });
+            await executor.execute(createTestProgram(['StepA', 'StepB', 'StepC']));
+            expect(onStageStart).toHaveBeenCalledTimes(3);
+        });
+        it('includes stage index and name', async () => {
+            const events = [];
+            const executor = new MissionExecutor({
+                progress: {
+                    onStageStart: (e) => events.push(e),
+                },
+            });
+            await executor.execute(createTestProgram(['Fetch', 'Process', 'Store']));
+            expect(events[0]).toMatchObject({
+                stageIndex: 0,
+                stageName: 'Fetch',
+                totalStages: 3,
+            });
+            expect(events[1]).toMatchObject({
+                stageIndex: 1,
+                stageName: 'Process',
+                totalStages: 3,
+            });
+            expect(events[2]).toMatchObject({
+                stageIndex: 2,
+                stageName: 'Store',
+                totalStages: 3,
+            });
+        });
+    });
+    describe('onStageComplete', () => {
+        it('is called for each stage', async () => {
+            const onStageComplete = vi.fn();
+            const executor = new MissionExecutor({
+                progress: { onStageComplete },
+            });
+            await executor.execute(createTestProgram(['StepA', 'StepB']));
+            expect(onStageComplete).toHaveBeenCalledTimes(2);
+        });
+        it('includes success status and duration', async () => {
+            const events = [];
+            const executor = new MissionExecutor({
+                progress: {
+                    onStageComplete: (e) => events.push(e),
+                },
+            });
+            await executor.execute(createTestProgram(['StepA']));
+            expect(events[0]).toMatchObject({
+                stageIndex: 0,
+                stageName: 'StepA',
+                success: true,
+            });
+            expect(events[0].duration).toBeGreaterThanOrEqual(0);
+            expect(events[0].error).toBeUndefined();
+        });
+    });
+    describe('callback order', () => {
+        it('fires callbacks in correct order', async () => {
+            const callOrder = [];
+            const executor = new MissionExecutor({
+                progress: {
+                    onExecutionStart: () => callOrder.push('execStart'),
+                    onExecutionComplete: () => callOrder.push('execComplete'),
+                    onStageStart: (e) => callOrder.push(`stageStart:${e.stageName}`),
+                    onStageComplete: (e) => callOrder.push(`stageComplete:${e.stageName}`),
+                },
+            });
+            await executor.execute(createTestProgram(['A', 'B']));
+            expect(callOrder).toEqual([
+                'execStart',
+                'stageStart:A',
+                'stageComplete:A',
+                'stageStart:B',
+                'stageComplete:B',
+                'execComplete',
+            ]);
+        });
+    });
+    describe('real-time UI example', () => {
+        it('can build a progress tracker', async () => {
+            const progressLog = [];
+            const executor = new MissionExecutor({
+                progress: {
+                    onExecutionStart: (e) => {
+                        progressLog.push(`Starting ${e.mission} (${e.stageCount} stages)`);
+                    },
+                    onStageStart: (e) => {
+                        const pct = Math.round((e.stageIndex / e.totalStages) * 100);
+                        progressLog.push(`[${pct}%] Running ${e.stageName}...`);
+                    },
+                    onStageComplete: (e) => {
+                        const pct = Math.round(((e.stageIndex + 1) / e.totalStages) * 100);
+                        progressLog.push(`[${pct}%] ${e.stageName} ${e.success ? 'done' : 'failed'}`);
+                    },
+                    onExecutionComplete: (e) => {
+                        progressLog.push(`Finished: ${e.success ? 'SUCCESS' : 'FAILED'} in ${e.duration}ms`);
+                    },
+                },
+            });
+            await executor.execute(createTestProgram(['Fetch', 'Process', 'Store']));
+            expect(progressLog[0]).toBe('Starting TestMission (3 stages)');
+            expect(progressLog[1]).toBe('[0%] Running Fetch...');
+            expect(progressLog[2]).toBe('[33%] Fetch done');
+            expect(progressLog[3]).toBe('[33%] Running Process...');
+            expect(progressLog[4]).toBe('[67%] Process done');
+            expect(progressLog[5]).toBe('[67%] Running Store...');
+            expect(progressLog[6]).toBe('[100%] Store done');
+            expect(progressLog[7]).toMatch(/^Finished: SUCCESS in \d+ms$/);
+        });
+    });
+});

package/dist/interpreter/schema-matcher.d.ts

@@ -0,0 +1,16 @@
+import type { SchemaDefinition } from 'vague-lang';
+/**
+ * Check if a value matches a schema definition.
+ *
+ * Matching rules:
+ * - All required fields (non-optional) must be present
+ * - Field types must match (string, int, decimal, boolean, date)
+ * - Extra fields are allowed (open schema)
+ * - Nested objects are not deeply validated (future enhancement)
+ */
+export declare function matchesSchema(value: unknown, schema: SchemaDefinition): boolean;
+/**
+ * Find the first matching schema from a list.
+ * Returns the schema name or undefined if no match.
+ */
+export declare function findMatchingSchema(value: unknown, schemas: Map<string, SchemaDefinition>, schemaNames: string[]): string | undefined;

package/dist/interpreter/schema-matcher.js

@@ -0,0 +1,136 @@
+/**
+ * Check if a value matches a schema definition.
+ *
+ * Matching rules:
+ * - All required fields (non-optional) must be present
+ * - Field types must match (string, int, decimal, boolean, date)
+ * - Extra fields are allowed (open schema)
+ * - Nested objects are not deeply validated (future enhancement)
+ */
+export function matchesSchema(value, schema) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    for (const field of schema.fields) {
+        const fieldValue = obj[field.name];
+        const isOptional = field.optional === true;
+        // Required field must be present
+        if (fieldValue === undefined) {
+            if (!isOptional) {
+                return false;
+            }
+            continue;
+        }
+        // Null is allowed for optional fields
+        if (fieldValue === null && isOptional) {
+            continue;
+        }
+        // Check type if present
+        if (!matchesFieldType(fieldValue, field.fieldType)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Check if a value matches the expected field type
+ */
+function matchesFieldType(value, fieldType) {
+    // Handle primitive types
+    if (fieldType.type === 'PrimitiveType') {
+        return matchesPrimitiveType(value, fieldType.name);
+    }
+    // Handle collection types (arrays)
+    if (fieldType.type === 'CollectionType') {
+        if (!Array.isArray(value)) {
+            return false;
+        }
+        // For now, don't validate element types
+        return true;
+    }
+    // Handle object/reference types
+    if (fieldType.type === 'ReferenceType') {
+        // For now, just check it's an object
+        return typeof value === 'object' && value !== null;
+    }
+    // Handle superposition types (unions) - any option matching is ok
+    if (fieldType.type === 'SuperpositionType') {
+        // Would need to check each option - be permissive for now
+        return true;
+    }
+    // Handle generator types (faker, etc.) - can't validate statically
+    if (fieldType.type === 'GeneratorType') {
+        return true;
+    }
+    // Handle expression types - can't validate statically
+    if (fieldType.type === 'ExpressionType') {
+        return true;
+    }
+    // Handle range types - check it's a number in range
+    if (fieldType.type === 'RangeType') {
+        return typeof value === 'number';
+    }
+    // Handle ordered sequence types (tuples)
+    if (fieldType.type === 'OrderedSequenceType') {
+        return Array.isArray(value);
+    }
+    // Unknown type - be permissive
+    return true;
+}
+/**
+ * Check if a value matches a primitive type
+ */
+function matchesPrimitiveType(value, typeName) {
+    switch (typeName) {
+        case 'string':
+            return typeof value === 'string';
+        case 'int':
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'decimal':
+        case 'number':
+        case 'float':
+        case 'double':
+            return typeof value === 'number';
+        case 'boolean':
+        case 'bool':
+            return typeof value === 'boolean';
+        case 'date':
+        case 'datetime':
+            // Accept strings (ISO format) or Date objects
+            if (value instanceof Date)
+                return true;
+            if (typeof value === 'string') {
+                const parsed = Date.parse(value);
+                return !isNaN(parsed);
+            }
+            return false;
+        case 'any':
+            return true;
+        default:
+            // Unknown primitive - be permissive
+            return true;
+    }
+}
+/**
+ * Find the first matching schema from a list.
+ * Returns the schema name or undefined if no match.
+ */
+export function findMatchingSchema(value, schemas, schemaNames) {
+    for (const name of schemaNames) {
+        // Handle wildcard
+        if (name === '_') {
+            return '_';
+        }
+        const schema = schemas.get(name);
+        if (!schema) {
+            // Schema not found - skip
+            continue;
+        }
+        if (matchesSchema(value, schema)) {
+            return name;
+        }
+    }
+    return undefined;
+}

package/dist/interpreter/schema-matcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/interpreter/schema-matcher.test.js

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest';
+import { matchesSchema, findMatchingSchema } from './schema-matcher.js';
+describe('Schema Matcher', () => {
+    describe('matchesSchema', () => {
+        const userSchema = {
+            type: 'SchemaDefinition',
+            name: 'User',
+            fields: [
+                {
+                    type: 'FieldDefinition',
+                    name: 'id',
+                    fieldType: { type: 'PrimitiveType', name: 'int' },
+                },
+                {
+                    type: 'FieldDefinition',
+                    name: 'name',
+                    fieldType: { type: 'PrimitiveType', name: 'string' },
+                },
+                {
+                    type: 'FieldDefinition',
+                    name: 'email',
+                    fieldType: { type: 'PrimitiveType', name: 'string' },
+                    optional: true,
+                },
+            ],
+        };
+        it('matches valid object with all required fields', () => {
+            const value = { id: 1, name: 'Alice' };
+            expect(matchesSchema(value, userSchema)).toBe(true);
+        });
+        it('matches valid object with optional field', () => {
+            const value = { id: 1, name: 'Alice', email: 'alice@example.com' };
+            expect(matchesSchema(value, userSchema)).toBe(true);
+        });
+        it('matches object with extra fields (open schema)', () => {
+            const value = { id: 1, name: 'Alice', extra: 'ignored' };
+            expect(matchesSchema(value, userSchema)).toBe(true);
+        });
+        it('rejects object missing required field', () => {
+            const value = { id: 1 }; // missing 'name'
+            expect(matchesSchema(value, userSchema)).toBe(false);
+        });
+        it('rejects wrong type for field', () => {
+            const value = { id: 'not-a-number', name: 'Alice' };
+            expect(matchesSchema(value, userSchema)).toBe(false);
+        });
+        it('rejects null value', () => {
+            expect(matchesSchema(null, userSchema)).toBe(false);
+        });
+        it('rejects primitive value', () => {
+            expect(matchesSchema('string', userSchema)).toBe(false);
+        });
+        it('allows null for optional fields', () => {
+            const value = { id: 1, name: 'Alice', email: null };
+            expect(matchesSchema(value, userSchema)).toBe(true);
+        });
+    });
+    describe('findMatchingSchema', () => {
+        const successSchema = {
+            type: 'SchemaDefinition',
+            name: 'SuccessResponse',
+            fields: [
+                {
+                    type: 'FieldDefinition',
+                    name: 'data',
+                    fieldType: { type: 'ReferenceType', path: { type: 'QualifiedName', parts: ['object'] } },
+                },
+                {
+                    type: 'FieldDefinition',
+                    name: 'status',
+                    fieldType: { type: 'PrimitiveType', name: 'string' },
+                },
+            ],
+        };
+        const errorSchema = {
+            type: 'SchemaDefinition',
+            name: 'ErrorResponse',
+            fields: [
+                {
+                    type: 'FieldDefinition',
+                    name: 'error',
+                    fieldType: { type: 'PrimitiveType', name: 'string' },
+                },
+                {
+                    type: 'FieldDefinition',
+                    name: 'code',
+                    fieldType: { type: 'PrimitiveType', name: 'int' },
+                },
+            ],
+        };
+        const schemas = new Map([
+            ['SuccessResponse', successSchema],
+            ['ErrorResponse', errorSchema],
+        ]);
+        it('finds matching schema in order', () => {
+            const successValue = { data: { id: 1 }, status: 'ok' };
+            const result = findMatchingSchema(successValue, schemas, ['SuccessResponse', 'ErrorResponse']);
+            expect(result).toBe('SuccessResponse');
+        });
+        it('finds second schema if first does not match', () => {
+            const errorValue = { error: 'Not found', code: 404 };
+            const result = findMatchingSchema(errorValue, schemas, ['SuccessResponse', 'ErrorResponse']);
+            expect(result).toBe('ErrorResponse');
+        });
+        it('returns undefined if no schema matches', () => {
+            const value = { random: 'value' };
+            const result = findMatchingSchema(value, schemas, ['SuccessResponse', 'ErrorResponse']);
+            expect(result).toBeUndefined();
+        });
+        it('handles wildcard pattern', () => {
+            const value = { random: 'value' };
+            const result = findMatchingSchema(value, schemas, ['SuccessResponse', 'ErrorResponse', '_']);
+            expect(result).toBe('_');
+        });
+        it('respects schema order (first match wins)', () => {
+            // Create a schema that matches both
+            const ambiguousValue = { data: {}, status: 'ok', error: 'msg', code: 500 };
+            const result = findMatchingSchema(ambiguousValue, schemas, ['SuccessResponse', 'ErrorResponse']);
+            expect(result).toBe('SuccessResponse'); // First match wins
+        });
+    });
+});

package/dist/interpreter/signals.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Execution control flow signals
+ *
+ * These are used for non-exceptional control flow during pipeline execution.
+ * They extend Error for easy stack-based propagation but represent expected
+ * flow control, not actual errors.
+ */
+/**
+ * Signal thrown when a match arm triggers skip
+ */
+export declare class SkipSignal extends Error {
+    constructor();
+}
+/**
+ * Signal thrown when a match arm triggers retry
+ */
+export declare class RetrySignal extends Error {
+    backoff?: {
+        maxAttempts: number;
+        backoff: string;
+        initialDelay: number;
+    } | undefined;
+    constructor(backoff?: {
+        maxAttempts: number;
+        backoff: string;
+        initialDelay: number;
+    } | undefined);
+}
+/**
+ * Signal thrown when a match arm triggers jump
+ */
+export declare class JumpSignal extends Error {
+    action: string;
+    then?: "retry" | "continue" | undefined;
+    constructor(action: string, then?: "retry" | "continue" | undefined);
+}
+/**
+ * Signal thrown when a match arm triggers queue
+ */
+export declare class QueueSignal extends Error {
+    value: unknown;
+    target?: string | undefined;
+    constructor(value: unknown, target?: string | undefined);
+}
+/**
+ * Error thrown when a match step has no matching arm
+ */
+export declare class NoMatchError extends Error {
+    value: unknown;
+    constructor(value: unknown);
+}
+/**
+ * Error thrown when a match arm triggers an abort
+ */
+export declare class AbortError extends Error {
+    constructor(message?: string);
+}

package/dist/interpreter/signals.js

@@ -0,0 +1,73 @@
+/**
+ * Execution control flow signals
+ *
+ * These are used for non-exceptional control flow during pipeline execution.
+ * They extend Error for easy stack-based propagation but represent expected
+ * flow control, not actual errors.
+ */
+/**
+ * Signal thrown when a match arm triggers skip
+ */
+export class SkipSignal extends Error {
+    constructor() {
+        super('Skip remaining steps');
+        this.name = 'SkipSignal';
+    }
+}
+/**
+ * Signal thrown when a match arm triggers retry
+ */
+export class RetrySignal extends Error {
+    backoff;
+    constructor(backoff) {
+        super('Retry action');
+        this.backoff = backoff;
+        this.name = 'RetrySignal';
+    }
+}
+/**
+ * Signal thrown when a match arm triggers jump
+ */
+export class JumpSignal extends Error {
+    action;
+    then;
+    constructor(action, then) {
+        super(`Jump to action: ${action}`);
+        this.action = action;
+        this.then = then;
+        this.name = 'JumpSignal';
+    }
+}
+/**
+ * Signal thrown when a match arm triggers queue
+ */
+export class QueueSignal extends Error {
+    value;
+    target;
+    constructor(value, target) {
+        super('Queue for later processing');
+        this.value = value;
+        this.target = target;
+        this.name = 'QueueSignal';
+    }
+}
+/**
+ * Error thrown when a match step has no matching arm
+ */
+export class NoMatchError extends Error {
+    value;
+    constructor(value) {
+        super('No matching schema found for response');
+        this.value = value;
+        this.name = 'NoMatchError';
+    }
+}
+/**
+ * Error thrown when a match arm triggers an abort
+ */
+export class AbortError extends Error {
+    constructor(message) {
+        super(message ?? 'Execution aborted');
+        this.name = 'AbortError';
+    }
+}

package/dist/interpreter/step-handlers/for-handler.d.ts

@@ -0,0 +1,17 @@
+import type { ForStep, ActionStep } from '../../ast/nodes.js';
+import type { StepHandler, StepHandlerDeps } from './types.js';
+import type { ExecutionContext } from '../context.js';
+export interface ForHandlerDeps extends StepHandlerDeps {
+    executeStep: (step: ActionStep, actionName: string, ctx: ExecutionContext) => Promise<void>;
+    actionName: string;
+}
+/**
+ * Handles for...in...where iteration steps
+ */
+export declare class ForHandler implements StepHandler<ForStep> {
+    private deps;
+    constructor(deps: ForHandlerDeps);
+    execute(step: ForStep): Promise<void>;
+    private getCollection;
+    private executeForItem;
+}