reqon-dsl 0.2.0 → 0.3.0

package/src/loader/index.ts

@@ -1,288 +0,0 @@
-import { readFile, readdir, stat } from 'node:fs/promises';
-import { resolve, join, dirname, basename } from 'node:path';
-import { ReqonLexer } from '../lexer/index.js';
-import { ReqonParser } from '../parser/index.js';
-import type { ReqonProgram, MissionDefinition, ActionDefinition, Statement } from '../ast/nodes.js';
-
-export interface LoadResult {
-  program: ReqonProgram;
-  /** Base directory for the mission (folder path or file's parent) */
-  baseDir: string;
-  /** All source files that were loaded */
-  sourceFiles: string[];
-}
-
-/** Supported file extensions, in order of preference */
-export const SUPPORTED_EXTENSIONS = ['.vague', '.reqon'] as const;
-export type SupportedExtension = (typeof SUPPORTED_EXTENSIONS)[number];
-
-export interface LoadOptions {
-  /** File extension to look for (default: tries '.vague' then '.reqon') */
-  extension?: SupportedExtension;
-}
-
-/**
- * Load a mission from a file or folder.
- *
- * Single file mode:
- *   loadMission('./sync-invoices.reqon')
- *   Returns the parsed program from that file.
- *
- * Folder mode:
- *   loadMission('./sync-invoices/')
- *   Looks for mission.reqon (root) and merges all *.reqon action files.
- *   Actions are resolved by name from the `run` pipeline.
- */
-export async function loadMission(
-  path: string,
-  options: LoadOptions = {}
-): Promise<LoadResult> {
-  const absolutePath = resolve(path);
-  const stats = await stat(absolutePath);
-
-  if (stats.isDirectory()) {
-    return loadMissionFolder(absolutePath, options);
-  } else {
-    return loadMissionFile(absolutePath);
-  }
-}
-
-/**
- * Load a single .reqon file
- */
-async function loadMissionFile(filePath: string): Promise<LoadResult> {
-  const source = await readFile(filePath, 'utf-8');
-  const program = parseSource(source, filePath);
-
-  return {
-    program,
-    baseDir: dirname(filePath),
-    sourceFiles: [filePath],
-  };
-}
-
-/**
- * Load a mission from a folder.
- *
- * Expected structure:
- *   mission-name/
- *   ├── mission.reqon      # Root file with mission definition (sources, stores, pipeline)
- *   ├── fetch-list.reqon   # Action file
- *   ├── hydrate.reqon      # Action file
- *   └── normalize.reqon    # Action file
- *
- * The root file (mission.reqon) contains:
- * - source definitions
- * - store definitions
- * - schema definitions
- * - the pipeline (run X then Y then Z)
- * - optionally inline actions
- *
- * Action files contain standalone action definitions that get merged in.
- */
-async function loadMissionFolder(
-  folderPath: string,
-  options: LoadOptions
-): Promise<LoadResult> {
-  // Find root file - try extensions in order of preference
-  const extensionsToTry = options.extension
-    ? [options.extension]
-    : SUPPORTED_EXTENSIONS;
-
-  let rootFilePath: string | null = null;
-  let ext: SupportedExtension | null = null;
-
-  for (const extension of extensionsToTry) {
-    const candidatePath = join(folderPath, `mission${extension}`);
-    try {
-      await stat(candidatePath);
-      rootFilePath = candidatePath;
-      ext = extension;
-      break;
-    } catch {
-      // Try next extension
-    }
-  }
-
-  if (!rootFilePath || !ext) {
-    const tried = extensionsToTry.map(e => `mission${e}`).join(' or ');
-    throw new Error(
-      `Mission folder must contain a root file (${tried}). ` +
-      `Not found in: ${folderPath}`
-    );
-  }
-
-  // Load root file
-  const rootSource = await readFile(rootFilePath, 'utf-8');
-  const rootProgram = parseSource(rootSource, rootFilePath);
-
-  // Find all other action files in the folder (same extension as root)
-  const rootFileName = basename(rootFilePath);
-  const files = await readdir(folderPath);
-  const actionFiles = files.filter(
-    f => f.endsWith(ext) && f !== rootFileName
-  );
-
-  const sourceFiles = [rootFilePath];
-  const externalActions: ActionDefinition[] = [];
-
-  // Parse each action file
-  for (const file of actionFiles) {
-    const filePath = join(folderPath, file);
-    sourceFiles.push(filePath);
-
-    const source = await readFile(filePath, 'utf-8');
-    const actionProgram = parseSource(source, filePath);
-
-    // Extract action definitions from the file
-    for (const stmt of actionProgram.statements) {
-      if (stmt.type === 'ActionDefinition') {
-        externalActions.push(stmt);
-      } else if (stmt.type === 'MissionDefinition') {
-        throw new Error(
-          `Action file '${file}' should not contain a mission definition. ` +
-          `Only '${rootFileName}' should define the mission.`
-        );
-      }
-    }
-  }
-
-  // Merge external actions into the mission
-  const mergedProgram = mergeActions(rootProgram, externalActions);
-
-  // Validate that all actions referenced in the pipeline exist
-  validatePipelineActions(mergedProgram);
-
-  return {
-    program: mergedProgram,
-    baseDir: folderPath,
-    sourceFiles,
-  };
-}
-
-/**
- * Parse source code into a program
- */
-function parseSource(source: string, filePath: string): ReqonProgram {
-  const lexer = new ReqonLexer(source);
-  const tokens = lexer.tokenize();
-  const parser = new ReqonParser(tokens, source, filePath);
-  return parser.parse();
-}
-
-/**
- * Merge external actions into the mission definition
- */
-function mergeActions(
-  program: ReqonProgram,
-  externalActions: ActionDefinition[]
-): ReqonProgram {
-  // Find the mission in the program
-  const missionIndex = program.statements.findIndex(
-    (s): s is MissionDefinition => s.type === 'MissionDefinition'
-  );
-
-  if (missionIndex === -1) {
-    throw new Error('Root file must contain a mission definition');
-  }
-
-  const mission = program.statements[missionIndex] as MissionDefinition;
-
-  // Build a map of existing actions
-  const actionMap = new Map<string, ActionDefinition>();
-  for (const action of mission.actions) {
-    actionMap.set(action.name, action);
-  }
-
-  // Add external actions (error if duplicate)
-  for (const action of externalActions) {
-    if (actionMap.has(action.name)) {
-      throw new Error(
-        `Duplicate action definition: '${action.name}'. ` +
-        `Action names must be unique across all files.`
-      );
-    }
-    actionMap.set(action.name, action);
-  }
-
-  // Create updated mission with all actions
-  const updatedMission: MissionDefinition = {
-    ...mission,
-    actions: Array.from(actionMap.values()),
-  };
-
-  // Return updated program
-  const updatedStatements = [...program.statements];
-  updatedStatements[missionIndex] = updatedMission;
-
-  return {
-    type: 'ReqonProgram',
-    statements: updatedStatements,
-  };
-}
-
-/**
- * Validate that all actions referenced in the pipeline exist
- */
-function validatePipelineActions(program: ReqonProgram): void {
-  const mission = program.statements.find(
-    (s): s is MissionDefinition => s.type === 'MissionDefinition'
-  );
-
-  if (!mission) return;
-
-  const actionNames = new Set(mission.actions.map(a => a.name));
-
-  for (const stage of mission.pipeline.stages) {
-    const stageActions = stage.actions ?? (stage.action ? [stage.action] : []);
-
-    for (const actionName of stageActions) {
-      if (!actionNames.has(actionName)) {
-        throw new Error(
-          `Pipeline references unknown action: '${actionName}'. ` +
-          `Available actions: ${Array.from(actionNames).join(', ')}`
-        );
-      }
-    }
-  }
-}
-
-/**
- * Check if a path is a mission folder (contains mission.vague or mission.reqon)
- */
-export async function isMissionFolder(path: string): Promise<boolean> {
-  try {
-    const absolutePath = resolve(path);
-    const stats = await stat(absolutePath);
-
-    if (!stats.isDirectory()) return false;
-
-    // Check for any supported root file
-    for (const ext of SUPPORTED_EXTENSIONS) {
-      try {
-        await stat(join(absolutePath, `mission${ext}`));
-        return true;
-      } catch {
-        // Try next extension
-      }
-    }
-    return false;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Get the mission name from a path (folder name or file name without extension)
- */
-export function getMissionName(path: string): string {
-  const absolutePath = resolve(path);
-  const name = basename(absolutePath);
-
-  for (const ext of SUPPORTED_EXTENSIONS) {
-    if (name.endsWith(ext)) {
-      return name.slice(0, -ext.length);
-    }
-  }
-  return name;
-}

package/src/loader/loader.test.ts

@@ -1,360 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdir, writeFile, rm } from 'node:fs/promises';
-import { join } from 'node:path';
-import { loadMission, isMissionFolder, getMissionName } from './index.js';
-
-const TEST_DIR = '.test-missions';
-
-describe('Mission Loader', () => {
-  beforeEach(async () => {
-    await mkdir(TEST_DIR, { recursive: true });
-  });
-
-  afterEach(async () => {
-    await rm(TEST_DIR, { recursive: true, force: true });
-  });
-
-  describe('single file loading', () => {
-    it('loads a single .reqon file', async () => {
-      const filePath = join(TEST_DIR, 'simple.reqon');
-      await writeFile(filePath, `
-        mission Simple {
-          source Api {
-            auth: none,
-            base: "https://api.example.com"
-          }
-
-          store data: memory("items")
-
-          action Fetch {
-            get "/items" { source: Api }
-            store response -> data
-          }
-
-          run Fetch
-        }
-      `);
-
-      const result = await loadMission(filePath);
-
-      expect(result.sourceFiles).toHaveLength(1);
-      expect(result.sourceFiles[0]).toContain('simple.reqon');
-
-      const mission = result.program.statements.find(
-        s => s.type === 'MissionDefinition'
-      );
-      expect(mission).toBeDefined();
-      expect((mission as any).name).toBe('Simple');
-      expect((mission as any).actions).toHaveLength(1);
-    });
-
-    it('loads a single .vague file', async () => {
-      const filePath = join(TEST_DIR, 'simple.vague');
-      await writeFile(filePath, `
-        mission Simple {
-          source Api {
-            auth: none,
-            base: "https://api.example.com"
-          }
-
-          store data: memory("items")
-
-          action Fetch {
-            fetch GET "/items" { source: Api }
-            store response -> data
-          }
-
-          run Fetch
-        }
-      `);
-
-      const result = await loadMission(filePath);
-
-      expect(result.sourceFiles).toHaveLength(1);
-      expect(result.sourceFiles[0]).toContain('simple.vague');
-
-      const mission = result.program.statements.find(
-        s => s.type === 'MissionDefinition'
-      );
-      expect(mission).toBeDefined();
-      expect((mission as any).name).toBe('Simple');
-    });
-  });
-
-  describe('folder loading', () => {
-    it('loads mission from folder with separate action files', async () => {
-      const missionDir = join(TEST_DIR, 'sync-invoices');
-      await mkdir(missionDir, { recursive: true });
-
-      // Root mission file
-      await writeFile(join(missionDir, 'mission.reqon'), `
-        mission SyncInvoices {
-          source Xero {
-            auth: oauth2,
-            base: "https://api.xero.com"
-          }
-
-          store invoices: memory("invoices")
-          store details: memory("invoice_details")
-
-          run FetchList then Hydrate
-        }
-      `);
-
-      // Action files
-      await writeFile(join(missionDir, 'fetch-list.reqon'), `
-        action FetchList {
-          get "/invoices" { source: Xero }
-          store response -> invoices
-        }
-      `);
-
-      await writeFile(join(missionDir, 'hydrate.reqon'), `
-        action Hydrate {
-          for invoice in invoices {
-            get "/invoices/{invoice.id}" { source: Xero }
-            store response -> details
-          }
-        }
-      `);
-
-      const result = await loadMission(missionDir);
-
-      expect(result.sourceFiles).toHaveLength(3);
-      expect(result.baseDir).toContain('sync-invoices');
-
-      const mission = result.program.statements.find(
-        s => s.type === 'MissionDefinition'
-      );
-      expect(mission).toBeDefined();
-      expect((mission as any).name).toBe('SyncInvoices');
-      expect((mission as any).actions).toHaveLength(2);
-
-      const actionNames = (mission as any).actions.map((a: any) => a.name);
-      expect(actionNames).toContain('FetchList');
-      expect(actionNames).toContain('Hydrate');
-    });
-
-    it('errors if mission.reqon is missing from folder', async () => {
-      const missionDir = join(TEST_DIR, 'no-root');
-      await mkdir(missionDir, { recursive: true });
-
-      await writeFile(join(missionDir, 'action.reqon'), `
-        action SomeAction {
-          get "/test" { source: Api }
-        }
-      `);
-
-      await expect(loadMission(missionDir)).rejects.toThrow(
-        /must contain a root file/
-      );
-    });
-
-    it('errors if action file contains a mission definition', async () => {
-      const missionDir = join(TEST_DIR, 'bad-action');
-      await mkdir(missionDir, { recursive: true });
-
-      await writeFile(join(missionDir, 'mission.reqon'), `
-        mission Main {
-          source Api { auth: none, base: "https://api.example.com" }
-          store data: memory("data")
-          run Fetch
-        }
-      `);
-
-      await writeFile(join(missionDir, 'nested.reqon'), `
-        mission NestedMission {
-          source Api { auth: none, base: "https://other.com" }
-          store data: memory("data")
-          run Something
-        }
-      `);
-
-      await expect(loadMission(missionDir)).rejects.toThrow(
-        /should not contain a mission definition/
-      );
-    });
-
-    it('errors on duplicate action names', async () => {
-      const missionDir = join(TEST_DIR, 'duplicate');
-      await mkdir(missionDir, { recursive: true });
-
-      await writeFile(join(missionDir, 'mission.reqon'), `
-        mission Main {
-          source Api { auth: none, base: "https://api.example.com" }
-          store data: memory("data")
-
-          action Fetch {
-            get "/a" { source: Api }
-          }
-
-          run Fetch
-        }
-      `);
-
-      await writeFile(join(missionDir, 'fetch.reqon'), `
-        action Fetch {
-          get "/b" { source: Api }
-        }
-      `);
-
-      await expect(loadMission(missionDir)).rejects.toThrow(
-        /Duplicate action definition: 'Fetch'/
-      );
-    });
-
-    it('errors if pipeline references unknown action', async () => {
-      const missionDir = join(TEST_DIR, 'unknown-action');
-      await mkdir(missionDir, { recursive: true });
-
-      await writeFile(join(missionDir, 'mission.reqon'), `
-        mission Main {
-          source Api { auth: none, base: "https://api.example.com" }
-          store data: memory("data")
-
-          action Fetch {
-            get "/items" { source: Api }
-          }
-
-          run Fetch then NonExistent
-        }
-      `);
-
-      await expect(loadMission(missionDir)).rejects.toThrow(
-        /Pipeline references unknown action: 'NonExistent'/
-      );
-    });
-
-    it('supports inline actions alongside external files', async () => {
-      const missionDir = join(TEST_DIR, 'mixed');
-      await mkdir(missionDir, { recursive: true });
-
-      await writeFile(join(missionDir, 'mission.reqon'), `
-        mission Mixed {
-          source Api { auth: none, base: "https://api.example.com" }
-          store data: memory("data")
-
-          action InlineAction {
-            get "/inline" { source: Api }
-          }
-
-          run InlineAction then ExternalAction
-        }
-      `);
-
-      await writeFile(join(missionDir, 'external.reqon'), `
-        action ExternalAction {
-          get "/external" { source: Api }
-          store response -> data
-        }
-      `);
-
-      const result = await loadMission(missionDir);
-
-      const mission = result.program.statements.find(
-        s => s.type === 'MissionDefinition'
-      );
-      expect((mission as any).actions).toHaveLength(2);
-    });
-  });
-
-  describe('isMissionFolder', () => {
-    it('returns true for folder with mission.reqon', async () => {
-      const missionDir = join(TEST_DIR, 'valid-folder');
-      await mkdir(missionDir, { recursive: true });
-      await writeFile(join(missionDir, 'mission.reqon'), 'mission X { run A }');
-
-      expect(await isMissionFolder(missionDir)).toBe(true);
-    });
-
-    it('returns true for folder with mission.vague', async () => {
-      const missionDir = join(TEST_DIR, 'vague-folder');
-      await mkdir(missionDir, { recursive: true });
-      await writeFile(join(missionDir, 'mission.vague'), 'mission X { run A }');
-
-      expect(await isMissionFolder(missionDir)).toBe(true);
-    });
-
-    it('returns false for folder without mission.reqon', async () => {
-      const missionDir = join(TEST_DIR, 'invalid-folder');
-      await mkdir(missionDir, { recursive: true });
-
-      expect(await isMissionFolder(missionDir)).toBe(false);
-    });
-
-    it('returns false for a file', async () => {
-      const filePath = join(TEST_DIR, 'file.reqon');
-      await writeFile(filePath, 'mission X { run A }');
-
-      expect(await isMissionFolder(filePath)).toBe(false);
-    });
-  });
-
-  describe('getMissionName', () => {
-    it('extracts name from folder path', () => {
-      expect(getMissionName('/path/to/sync-invoices')).toBe('sync-invoices');
-    });
-
-    it('extracts name from .reqon file path', () => {
-      expect(getMissionName('/path/to/sync-invoices.reqon')).toBe('sync-invoices');
-    });
-
-    it('extracts name from .vague file path', () => {
-      expect(getMissionName('/path/to/sync-invoices.vague')).toBe('sync-invoices');
-    });
-  });
-
-  describe('.vague file priority', () => {
-    it('prefers .vague over .reqon in folder mode', async () => {
-      const missionDir = join(TEST_DIR, 'both-extensions');
-      await mkdir(missionDir, { recursive: true });
-
-      // Create both files - .vague should be preferred
-      await writeFile(join(missionDir, 'mission.vague'), `
-        mission FromVague {
-          source Api { auth: none, base: "https://api.example.com" }
-          store data: memory("data")
-          action Fetch { fetch GET "/vague" { source: Api } }
-          run Fetch
-        }
-      `);
-      await writeFile(join(missionDir, 'mission.reqon'), `
-        mission FromReqon {
-          source Api { auth: none, base: "https://api.example.com" }
-          store data: memory("data")
-          action Fetch { fetch GET "/reqon" { source: Api } }
-          run Fetch
-        }
-      `);
-
-      const result = await loadMission(missionDir);
-      const mission = result.program.statements.find(
-        s => s.type === 'MissionDefinition'
-      );
-      expect((mission as any).name).toBe('FromVague');
-    });
-
-    it('loads folder with mission.vague and .vague action files', async () => {
-      const missionDir = join(TEST_DIR, 'vague-folder-mode');
-      await mkdir(missionDir, { recursive: true });
-
-      await writeFile(join(missionDir, 'mission.vague'), `
-        mission VagueMode {
-          source Api { auth: none, base: "https://api.example.com" }
-          store data: memory("data")
-          run Fetch
-        }
-      `);
-      await writeFile(join(missionDir, 'fetch.vague'), `
-        action Fetch {
-          fetch GET "/items" { source: Api }
-        }
-      `);
-
-      const result = await loadMission(missionDir);
-      expect(result.sourceFiles).toHaveLength(2);
-      expect(result.sourceFiles[0]).toContain('mission.vague');
-      expect(result.sourceFiles[1]).toContain('fetch.vague');
-    });
-  });
-});

package/src/oas/index.ts

@@ -1,4 +0,0 @@
-export { loadOAS, resolveOperation, getResponseSchema, clearCache } from './loader.js';
-export type { OASSource, OASOperation, OpenAPISpec } from './loader.js';
-export { validateResponse } from './validator.js';
-export type { ValidationResult, ValidationError } from './validator.js';