reqon-dsl 0.2.0

package/src/interpreter/progress.test.ts

@@ -0,0 +1,276 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { MissionExecutor } from './executor.js';
+import type {
+  ProgressCallbacks,
+  ExecutionStartEvent,
+  ExecutionCompleteEvent,
+  StageStartEvent,
+  StageCompleteEvent,
+} from './executor.js';
+import type { ReqonProgram, MissionDefinition } from '../ast/nodes.js';
+
+function createTestProgram(stages: string[]): ReqonProgram {
+  const actions = stages.map((name) => ({
+    type: 'ActionDefinition' as const,
+    name,
+    steps: [],
+  }));
+
+  const pipeline = {
+    type: 'PipelineDefinition' as const,
+    stages: stages.map((action) => ({ action })),
+  };
+
+  const mission: MissionDefinition = {
+    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] as ExecutionCompleteEvent;
+      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: StageStartEvent[] = [];
+      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: StageCompleteEvent[] = [];
+      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: string[] = [];
+
+      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: string[] = [];
+
+      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/src/interpreter/schema-matcher.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from 'vitest';
+import { matchesSchema, findMatchingSchema } from './schema-matcher.js';
+import type { SchemaDefinition } from 'vague-lang';
+
+describe('Schema Matcher', () => {
+  describe('matchesSchema', () => {
+    const userSchema: SchemaDefinition = {
+      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: SchemaDefinition = {
+      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: SchemaDefinition = {
+      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<string, SchemaDefinition>([
+      ['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/src/interpreter/schema-matcher.ts

@@ -0,0 +1,168 @@
+import type { SchemaDefinition, FieldDefinition, FieldType } 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 function matchesSchema(value: unknown, schema: SchemaDefinition): boolean {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  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: unknown, fieldType: FieldType): boolean {
+  // 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: unknown, typeName: string): boolean {
+
+  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: unknown,
+  schemas: Map<string, SchemaDefinition>,
+  schemaNames: string[]
+): string | undefined {
+  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/src/interpreter/signals.ts

@@ -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 {
+  constructor(public backoff?: { maxAttempts: number; backoff: string; initialDelay: number }) {
+    super('Retry action');
+    this.name = 'RetrySignal';
+  }
+}
+
+/**
+ * Signal thrown when a match arm triggers jump
+ */
+export class JumpSignal extends Error {
+  constructor(
+    public action: string,
+    public then?: 'retry' | 'continue'
+  ) {
+    super(`Jump to action: ${action}`);
+    this.name = 'JumpSignal';
+  }
+}
+
+/**
+ * Signal thrown when a match arm triggers queue
+ */
+export class QueueSignal extends Error {
+  constructor(
+    public value: unknown,
+    public target?: string
+  ) {
+    super('Queue for later processing');
+    this.name = 'QueueSignal';
+  }
+}
+
+/**
+ * Error thrown when a match step has no matching arm
+ */
+export class NoMatchError extends Error {
+  constructor(public value: unknown) {
+    super('No matching schema found for response');
+    this.name = 'NoMatchError';
+  }
+}
+
+/**
+ * Error thrown when a match arm triggers an abort
+ */
+export class AbortError extends Error {
+  constructor(message?: string) {
+    super(message ?? 'Execution aborted');
+    this.name = 'AbortError';
+  }
+}