reqon-dsl 0.2.0

package/src/oas/loader.ts

@@ -0,0 +1,126 @@
+import SwaggerParser from '@apidevtools/swagger-parser';
+import type { OpenAPI, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+
+export type OpenAPISpec = OpenAPIV3.Document | OpenAPIV3_1.Document;
+
+export interface OASOperation {
+  operationId: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+  parameters?: OpenAPIV3.ParameterObject[];
+  requestBody?: OpenAPIV3.RequestBodyObject;
+  responses?: OpenAPIV3.ResponsesObject;
+  security?: OpenAPIV3.SecurityRequirementObject[];
+}
+
+export interface OASSource {
+  spec: OpenAPISpec;
+  baseUrl: string;
+  operations: Map<string, OASOperation>;
+  schemas: Map<string, OpenAPIV3.SchemaObject>;
+}
+
+// Cache loaded specs to avoid re-parsing
+const specCache = new Map<string, OASSource>();
+
+export async function loadOAS(specPath: string, forceReload = false): Promise<OASSource> {
+  if (!forceReload && specCache.has(specPath)) {
+    return specCache.get(specPath)!;
+  }
+
+  const api = await SwaggerParser.dereference(specPath) as OpenAPISpec;
+
+  const baseUrl = extractBaseUrl(api);
+  const operations = extractOperations(api);
+  const schemas = extractSchemas(api);
+
+  const source: OASSource = {
+    spec: api,
+    baseUrl,
+    operations,
+    schemas,
+  };
+
+  specCache.set(specPath, source);
+  return source;
+}
+
+function extractBaseUrl(spec: OpenAPISpec): string {
+  if (spec.servers && spec.servers.length > 0) {
+    return spec.servers[0].url;
+  }
+  return '';
+}
+
+function extractOperations(spec: OpenAPISpec): Map<string, OASOperation> {
+  const operations = new Map<string, OASOperation>();
+
+  if (!spec.paths) return operations;
+
+  for (const [path, pathItem] of Object.entries(spec.paths)) {
+    if (!pathItem) continue;
+
+    const methods = ['get', 'post', 'put', 'patch', 'delete'] as const;
+
+    for (const method of methods) {
+      const operation = pathItem[method] as OpenAPIV3.OperationObject | undefined;
+      if (!operation?.operationId) continue;
+
+      operations.set(operation.operationId, {
+        operationId: operation.operationId,
+        method: method.toUpperCase() as OASOperation['method'],
+        path,
+        parameters: operation.parameters as OpenAPIV3.ParameterObject[],
+        requestBody: operation.requestBody as OpenAPIV3.RequestBodyObject,
+        responses: operation.responses as OpenAPIV3.ResponsesObject,
+        security: operation.security,
+      });
+    }
+  }
+
+  return operations;
+}
+
+function extractSchemas(spec: OpenAPISpec): Map<string, OpenAPIV3.SchemaObject> {
+  const schemas = new Map<string, OpenAPIV3.SchemaObject>();
+
+  const components = spec.components;
+  if (!components?.schemas) return schemas;
+
+  for (const [name, schema] of Object.entries(components.schemas)) {
+    schemas.set(name, schema as OpenAPIV3.SchemaObject);
+  }
+
+  return schemas;
+}
+
+export function resolveOperation(source: OASSource, operationId: string): OASOperation {
+  const operation = source.operations.get(operationId);
+  if (!operation) {
+    const available = Array.from(source.operations.keys()).slice(0, 5).join(', ');
+    throw new Error(
+      `Operation '${operationId}' not found in OAS spec. Available: ${available}...`
+    );
+  }
+  return operation;
+}
+
+export function getResponseSchema(
+  source: OASSource,
+  operationId: string,
+  statusCode = '200'
+): OpenAPIV3.SchemaObject | undefined {
+  const operation = resolveOperation(source, operationId);
+
+  const response = operation.responses?.[statusCode] as OpenAPIV3.ResponseObject | undefined;
+  if (!response?.content) return undefined;
+
+  const jsonContent = response.content['application/json'];
+  if (!jsonContent?.schema) return undefined;
+
+  return jsonContent.schema as OpenAPIV3.SchemaObject;
+}
+
+export function clearCache(): void {
+  specCache.clear();
+}

package/src/oas/oas.test.ts

@@ -0,0 +1,254 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { loadOAS, resolveOperation, getResponseSchema, clearCache } from './loader.js';
+import { validateResponse } from './validator.js';
+import { ReqonLexer } from '../lexer/index.js';
+import { ReqonParser } from '../parser/parser.js';
+
+describe('OAS Loader', () => {
+  beforeAll(() => {
+    clearCache();
+  });
+
+  it('loads and parses an OpenAPI spec', async () => {
+    const source = await loadOAS('./examples/petstore/openapi.yaml');
+
+    expect(source.baseUrl).toBe('https://api.petstore.example.com/v1');
+    expect(source.operations.size).toBe(3);
+    expect(source.schemas.size).toBe(2);
+  });
+
+  it('resolves operations by operationId', async () => {
+    const source = await loadOAS('./examples/petstore/openapi.yaml');
+
+    const listPets = resolveOperation(source, 'listPets');
+    expect(listPets.method).toBe('GET');
+    expect(listPets.path).toBe('/pets');
+
+    const getPet = resolveOperation(source, 'getPet');
+    expect(getPet.method).toBe('GET');
+    expect(getPet.path).toBe('/pets/{petId}');
+
+    const createPet = resolveOperation(source, 'createPet');
+    expect(createPet.method).toBe('POST');
+    expect(createPet.path).toBe('/pets');
+  });
+
+  it('throws for unknown operationId', async () => {
+    const source = await loadOAS('./examples/petstore/openapi.yaml');
+
+    expect(() => resolveOperation(source, 'unknownOp')).toThrow(/not found/);
+  });
+
+  it('extracts response schemas', async () => {
+    const source = await loadOAS('./examples/petstore/openapi.yaml');
+
+    const schema = getResponseSchema(source, 'getPet');
+    expect(schema).toBeDefined();
+    expect(schema?.type).toBe('object');
+    expect(schema?.properties).toHaveProperty('id');
+    expect(schema?.properties).toHaveProperty('name');
+  });
+});
+
+describe('OAS Validator', () => {
+  it('validates a valid response', () => {
+    const schema = {
+      type: 'object' as const,
+      required: ['id', 'name'],
+      properties: {
+        id: { type: 'string' as const },
+        name: { type: 'string' as const },
+        age: { type: 'integer' as const, minimum: 0 },
+      },
+    };
+
+    const data = { id: '123', name: 'Fluffy', age: 3 };
+    const result = validateResponse(data, schema);
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('catches missing required properties', () => {
+    const schema = {
+      type: 'object' as const,
+      required: ['id', 'name'],
+      properties: {
+        id: { type: 'string' as const },
+        name: { type: 'string' as const },
+      },
+    };
+
+    const data = { id: '123' }; // missing 'name'
+    const result = validateResponse(data, schema);
+
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.path === 'name')).toBe(true);
+  });
+
+  it('catches type mismatches', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: {
+        age: { type: 'integer' as const },
+      },
+    };
+
+    const data = { age: 'not a number' };
+    const result = validateResponse(data, schema);
+
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].path).toBe('age');
+  });
+
+  it('validates arrays', () => {
+    const schema = {
+      type: 'array' as const,
+      items: {
+        type: 'object' as const,
+        required: ['id'],
+        properties: {
+          id: { type: 'string' as const },
+        },
+      },
+    };
+
+    const validData = [{ id: '1' }, { id: '2' }];
+    expect(validateResponse(validData, schema).valid).toBe(true);
+
+    const invalidData = [{ id: '1' }, { noId: true }];
+    const result = validateResponse(invalidData, schema);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].path).toBe('[1].id');
+  });
+});
+
+describe('OAS Parser Integration', () => {
+  function parse(source: string) {
+    const lexer = new ReqonLexer(source);
+    const tokens = lexer.tokenize();
+    const parser = new ReqonParser(tokens);
+    return parser.parse();
+  }
+
+  it('parses source with OAS spec path', () => {
+    const source = `
+      mission TestOAS {
+        source Petstore from "./examples/petstore.yaml" {
+          auth: bearer
+        }
+
+        store pets: memory("pets")
+
+        action FetchPets {
+          call Petstore.listPets
+
+          store response.pets -> pets {
+            key: .id
+          }
+        }
+
+        run FetchPets
+      }
+    `;
+
+    const program = parse(source);
+    expect(program.type).toBe('ReqonProgram');
+
+    const mission = program.statements[0];
+    if (mission.type === 'MissionDefinition') {
+      expect(mission.sources[0].specPath).toBe('./examples/petstore.yaml');
+      expect(mission.sources[0].config.base).toBeUndefined();
+
+      const action = mission.actions[0];
+      const fetchStep = action.steps[0];
+      if (fetchStep.type === 'FetchStep') {
+        expect(fetchStep.operationRef).toBeDefined();
+        expect(fetchStep.operationRef?.source).toBe('Petstore');
+        expect(fetchStep.operationRef?.operationId).toBe('listPets');
+        expect(fetchStep.method).toBeUndefined();
+        expect(fetchStep.path).toBeUndefined();
+      }
+    }
+  });
+
+  it('parses source with OAS and explicit base URL override', () => {
+    const source = `
+      mission TestOAS {
+        source Petstore from "./examples/petstore.yaml" {
+          auth: bearer,
+          base: "https://staging.petstore.com/v1"
+        }
+
+        store pets: memory("pets")
+
+        action Fetch {
+          get "/custom-path"
+          store response -> pets { key: .id }
+        }
+
+        run Fetch
+      }
+    `;
+
+    const program = parse(source);
+    const mission = program.statements[0];
+    if (mission.type === 'MissionDefinition') {
+      expect(mission.sources[0].specPath).toBe('./examples/petstore.yaml');
+      expect(mission.sources[0].config.base).toBe('https://staging.petstore.com/v1');
+    }
+  });
+
+  it('supports both OAS call and traditional HTTP methods in same mission', () => {
+    const source = `
+      mission MixedFetch {
+        source Petstore from "./examples/petstore.yaml" {
+          auth: bearer
+        }
+
+        source Legacy {
+          auth: bearer,
+          base: "https://legacy.api.com"
+        }
+
+        store pets: memory("pets")
+
+        action FetchFromOAS {
+          call Petstore.listPets
+          store response.pets -> pets { key: .id }
+        }
+
+        action FetchFromLegacy {
+          get "/old-endpoint" {
+            source: Legacy
+          }
+          store response -> pets { key: .id }
+        }
+
+        run FetchFromOAS then FetchFromLegacy
+      }
+    `;
+
+    const program = parse(source);
+    const mission = program.statements[0];
+    if (mission.type === 'MissionDefinition') {
+      expect(mission.sources).toHaveLength(2);
+
+      const oasAction = mission.actions[0];
+      const legacyAction = mission.actions[1];
+
+      const oasFetch = oasAction.steps[0];
+      const legacyFetch = legacyAction.steps[0];
+
+      if (oasFetch.type === 'FetchStep' && legacyFetch.type === 'FetchStep') {
+        // OAS call
+        expect(oasFetch.operationRef).toBeDefined();
+        expect(oasFetch.method).toBeUndefined();
+
+        // Traditional HTTP method
+        expect(legacyFetch.operationRef).toBeUndefined();
+        expect(legacyFetch.method).toBe('GET');
+      }
+    }
+  });
+});

package/src/oas/validator.ts

@@ -0,0 +1,299 @@
+import type { OpenAPIV3 } from 'openapi-types';
+
+type ArraySchemaObject = OpenAPIV3.ArraySchemaObject;
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+}
+
+export interface ValidationError {
+  path: string;
+  message: string;
+  expected?: string;
+  actual?: string;
+}
+
+export function validateResponse(
+  data: unknown,
+  schema: OpenAPIV3.SchemaObject,
+  path = ''
+): ValidationResult {
+  const errors: ValidationError[] = [];
+
+  validateValue(data, schema, path, errors);
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+function validateValue(
+  value: unknown,
+  schema: OpenAPIV3.SchemaObject,
+  path: string,
+  errors: ValidationError[]
+): void {
+  // Handle nullable
+  if (value === null) {
+    if (schema.nullable) return;
+    errors.push({ path, message: 'Value is null but schema is not nullable' });
+    return;
+  }
+
+  // Handle undefined/missing
+  if (value === undefined) {
+    // Required check happens at object level
+    return;
+  }
+
+  // Check type
+  const schemaType = schema.type;
+
+  switch (schemaType) {
+    case 'string':
+      validateString(value, schema, path, errors);
+      break;
+    case 'number':
+    case 'integer':
+      validateNumber(value, schema, path, errors);
+      break;
+    case 'boolean':
+      validateBoolean(value, path, errors);
+      break;
+    case 'array':
+      validateArray(value, schema, path, errors);
+      break;
+    case 'object':
+      validateObject(value, schema, path, errors);
+      break;
+    default:
+      // No type specified, or unknown type - allow anything
+      break;
+  }
+
+  // Check enum
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push({
+      path,
+      message: `Value not in enum`,
+      expected: schema.enum.join(' | '),
+      actual: String(value),
+    });
+  }
+}
+
+function validateString(
+  value: unknown,
+  schema: OpenAPIV3.SchemaObject,
+  path: string,
+  errors: ValidationError[]
+): void {
+  if (typeof value !== 'string') {
+    errors.push({
+      path,
+      message: 'Expected string',
+      expected: 'string',
+      actual: typeof value,
+    });
+    return;
+  }
+
+  if (schema.minLength !== undefined && value.length < schema.minLength) {
+    errors.push({
+      path,
+      message: `String too short`,
+      expected: `>= ${schema.minLength} chars`,
+      actual: `${value.length} chars`,
+    });
+  }
+
+  if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+    errors.push({
+      path,
+      message: `String too long`,
+      expected: `<= ${schema.maxLength} chars`,
+      actual: `${value.length} chars`,
+    });
+  }
+
+  if (schema.pattern) {
+    const regex = new RegExp(schema.pattern);
+    if (!regex.test(value)) {
+      errors.push({
+        path,
+        message: `String does not match pattern`,
+        expected: schema.pattern,
+        actual: value,
+      });
+    }
+  }
+}
+
+function validateNumber(
+  value: unknown,
+  schema: OpenAPIV3.SchemaObject,
+  path: string,
+  errors: ValidationError[]
+): void {
+  if (typeof value !== 'number') {
+    errors.push({
+      path,
+      message: 'Expected number',
+      expected: schema.type ?? 'number',
+      actual: typeof value,
+    });
+    return;
+  }
+
+  if (schema.type === 'integer' && !Number.isInteger(value)) {
+    errors.push({
+      path,
+      message: 'Expected integer',
+      expected: 'integer',
+      actual: String(value),
+    });
+  }
+
+  if (schema.minimum !== undefined && value < schema.minimum) {
+    errors.push({
+      path,
+      message: `Number below minimum`,
+      expected: `>= ${schema.minimum}`,
+      actual: String(value),
+    });
+  }
+
+  if (schema.maximum !== undefined && value > schema.maximum) {
+    errors.push({
+      path,
+      message: `Number above maximum`,
+      expected: `<= ${schema.maximum}`,
+      actual: String(value),
+    });
+  }
+}
+
+function validateBoolean(
+  value: unknown,
+  path: string,
+  errors: ValidationError[]
+): void {
+  if (typeof value !== 'boolean') {
+    errors.push({
+      path,
+      message: 'Expected boolean',
+      expected: 'boolean',
+      actual: typeof value,
+    });
+  }
+}
+
+function validateArray(
+  value: unknown,
+  schema: OpenAPIV3.SchemaObject,
+  path: string,
+  errors: ValidationError[]
+): void {
+  if (!Array.isArray(value)) {
+    errors.push({
+      path,
+      message: 'Expected array',
+      expected: 'array',
+      actual: typeof value,
+    });
+    return;
+  }
+
+  if (schema.minItems !== undefined && value.length < schema.minItems) {
+    errors.push({
+      path,
+      message: `Array too short`,
+      expected: `>= ${schema.minItems} items`,
+      actual: `${value.length} items`,
+    });
+  }
+
+  if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+    errors.push({
+      path,
+      message: `Array too long`,
+      expected: `<= ${schema.maxItems} items`,
+      actual: `${value.length} items`,
+    });
+  }
+
+  // Validate items
+  const arraySchema = schema as OpenAPIV3.ArraySchemaObject;
+  if (arraySchema.items) {
+    const itemSchema = arraySchema.items as OpenAPIV3.SchemaObject;
+    value.forEach((item, index) => {
+      validateValue(item, itemSchema, `${path}[${index}]`, errors);
+    });
+  }
+}
+
+function validateObject(
+  value: unknown,
+  schema: OpenAPIV3.SchemaObject,
+  path: string,
+  errors: ValidationError[]
+): void {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    errors.push({
+      path,
+      message: 'Expected object',
+      expected: 'object',
+      actual: Array.isArray(value) ? 'array' : typeof value,
+    });
+    return;
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  // Check required properties
+  if (schema.required) {
+    for (const prop of schema.required) {
+      if (!(prop in obj)) {
+        errors.push({
+          path: path ? `${path}.${prop}` : prop,
+          message: `Missing required property`,
+        });
+      }
+    }
+  }
+
+  // Validate properties
+  const properties = schema.properties as Record<string, OpenAPIV3.SchemaObject> | undefined;
+  if (properties) {
+    for (const [key, propSchema] of Object.entries(properties)) {
+      if (key in obj) {
+        const propPath = path ? `${path}.${key}` : key;
+        validateValue(obj[key], propSchema, propPath, errors);
+      }
+    }
+  }
+
+  // Handle additionalProperties
+  if (schema.additionalProperties === false) {
+    const allowedKeys = new Set(Object.keys(properties ?? {}));
+    for (const key of Object.keys(obj)) {
+      if (!allowedKeys.has(key)) {
+        errors.push({
+          path: path ? `${path}.${key}` : key,
+          message: `Unexpected property`,
+        });
+      }
+    }
+  } else if (typeof schema.additionalProperties === 'object') {
+    const additionalSchema = schema.additionalProperties as OpenAPIV3.SchemaObject;
+    const allowedKeys = new Set(Object.keys(properties ?? {}));
+    for (const [key, val] of Object.entries(obj)) {
+      if (!allowedKeys.has(key)) {
+        const propPath = path ? `${path}.${key}` : key;
+        validateValue(val, additionalSchema, propPath, errors);
+      }
+    }
+  }
+}