@orcalang/orca-lang 0.1.17 → 0.1.19

package/src/parser/dt-parser.ts

@@ -0,0 +1,289 @@
+// Decision Table Parser
+// Parses ## conditions, ## actions, ## rules sections from markdown elements
+
+import {
+  ConditionDef, ConditionType, ActionOutputDef, ActionType,
+  CellValue, Rule, DecisionTableDef,
+} from './dt-ast.js';
+
+interface MdHeading { kind: 'heading'; level: number; text: string; line: number }
+interface MdTable { kind: 'table'; headers: string[]; rows: string[][]; line: number }
+interface MdBulletList { kind: 'bullets'; items: string[]; line: number }
+interface MdBlockquote { kind: 'blockquote'; text: string; line: number }
+interface MdParagraph { kind: 'paragraph'; text: string; line: number }
+interface MdSeparator { kind: 'separator'; line: number }
+
+type MdElement = MdHeading | MdTable | MdBulletList | MdBlockquote | MdParagraph | MdSeparator;
+
+function findColumnIndex(headers: string[], name: string): number {
+  return headers.findIndex(h => h.toLowerCase() === name.toLowerCase());
+}
+
+// --- Cell Value Parsing ---
+
+function parseCellValue(text: string | undefined): CellValue {
+  if (!text || text.trim() === '' || text.trim() === '-') {
+    return { kind: 'any' };
+  }
+
+  const trimmed = text.trim();
+
+  // Negated: !value (bare '!' with no value falls through to exact match)
+  if (trimmed.startsWith('!')) {
+    const negatedValue = trimmed.slice(1);
+    if (negatedValue) {
+      return { kind: 'negated', value: negatedValue };
+    }
+  }
+
+  // Set: a,b,c
+  if (trimmed.includes(',')) {
+    return { kind: 'set', values: trimmed.split(',').map(v => v.trim()).filter(Boolean) };
+  }
+
+  // Exact match
+  return { kind: 'exact', value: trimmed };
+}
+
+// --- Section Parsers ---
+
+function parseConditionsTable(table: MdTable): ConditionDef[] {
+  const nameIdx = findColumnIndex(table.headers, 'name');
+  const typeIdx = findColumnIndex(table.headers, 'type');
+  const valuesIdx = findColumnIndex(table.headers, 'values');
+
+  return table.rows.map(row => {
+    const name = (nameIdx >= 0 ? row[nameIdx] : '') || '';
+    const typeStr = (typeIdx >= 0 ? row[typeIdx] : '') || 'string';
+    const valuesStr = (valuesIdx >= 0 ? row[valuesIdx] : '') || '';
+
+    const type: ConditionType = typeStr.trim() as ConditionType;
+
+    // Bool conditions auto-populate values ['true', 'false'] when Values column is empty
+    let values: string[];
+    let range: { min: number; max: number } | undefined;
+
+    if (type === 'bool') {
+      values = valuesStr.trim() ? valuesStr.split(',').map(v => v.trim()) : ['true', 'false'];
+    } else if (type === 'int_range') {
+      // Parse min..max format
+      const rangeMatch = valuesStr.match(/(\d+)\s*\.\.\s*(\d+)/);
+      if (rangeMatch) {
+        range = { min: parseInt(rangeMatch[1], 10), max: parseInt(rangeMatch[2], 10) };
+        values = [];
+      } else {
+        values = [];
+      }
+    } else {
+      // enum or string - comma-separated values
+      values = valuesStr ? valuesStr.split(',').map(v => v.trim()).filter(Boolean) : [];
+    }
+
+    const condition: ConditionDef = { name: name.trim(), type, values };
+    if (range) condition.range = range;
+
+    return condition;
+  }).filter(c => c.name !== '');
+}
+
+function parseActionsTable(table: MdTable): ActionOutputDef[] {
+  const nameIdx = findColumnIndex(table.headers, 'name');
+  const typeIdx = findColumnIndex(table.headers, 'type');
+  const descIdx = findColumnIndex(table.headers, 'description');
+  const valuesIdx = findColumnIndex(table.headers, 'values');
+
+  return table.rows.map(row => {
+    const name = (nameIdx >= 0 ? row[nameIdx] : '') || '';
+    const typeStr = (typeIdx >= 0 ? row[typeIdx] : '') || 'string';
+    const desc = descIdx >= 0 ? (row[descIdx] || '').trim() : '';
+    const valuesStr = valuesIdx >= 0 ? (row[valuesIdx] || '').trim() : '';
+
+    const type: ActionType = typeStr.trim() as ActionType;
+    const action: ActionOutputDef = {
+      name: name.trim(),
+      type,
+      description: desc || undefined,
+    };
+
+    if (valuesStr && type === 'enum') {
+      action.values = valuesStr.split(',').map(v => v.trim()).filter(Boolean);
+    }
+
+    return action;
+  }).filter(a => a.name !== '');
+}
+
+function parseRulesTable(
+  table: MdTable,
+  conditionNames: Set<string>,
+  actionNames: Set<string>
+): { rules: Rule[]; warnings: string[] } {
+  const warnings: string[] = [];
+  const rules: Rule[] = [];
+
+  // Determine column types from headers
+  const columnTypes: Array<{ name: string; type: 'condition' | 'action' | 'skip' }> = [];
+
+  for (const header of table.headers) {
+    const trimmed = header.trim();
+    const lower = trimmed.toLowerCase();
+
+    if (lower === '#') {
+      columnTypes.push({ name: '#', type: 'skip' });
+    } else if (trimmed.startsWith('→ ') || trimmed.startsWith('-> ')) {
+      // Action column - strip prefix
+      const actionName = trimmed.replace(/^→\s*/, '').replace(/^->\s*/, '');
+      columnTypes.push({ name: actionName, type: 'action' });
+
+      if (!actionNames.has(actionName)) {
+        warnings.push(`Unknown action column: "${actionName}" (not declared in ## actions)`);
+      }
+    } else {
+      // Condition column
+      columnTypes.push({ name: trimmed, type: 'condition' });
+
+      if (!conditionNames.has(trimmed)) {
+        warnings.push(`Unknown condition column: "${trimmed}" (not declared in ## conditions)`);
+      }
+    }
+  }
+
+  // Parse each row
+  for (let rowIdx = 0; rowIdx < table.rows.length; rowIdx++) {
+    const row = table.rows[rowIdx];
+    const rule: Rule = {
+      conditions: new Map(),
+      actions: new Map(),
+    };
+
+    for (let colIdx = 0; colIdx < columnTypes.length && colIdx < row.length; colIdx++) {
+      const col = columnTypes[colIdx];
+      const cell = row[colIdx];
+
+      if (col.type === 'skip') {
+        // Rule numbering column - parse as optional number
+        const num = parseInt(cell?.trim() || '', 10);
+        if (!isNaN(num)) {
+          rule.number = num;
+        }
+      } else if (col.type === 'condition') {
+        const cellValue = parseCellValue(cell);
+        rule.conditions.set(col.name, cellValue);
+      } else if (col.type === 'action') {
+        const value = cell?.trim() || '';
+        if (value) {
+          rule.actions.set(col.name, value);
+        }
+      }
+    }
+
+    rules.push(rule);
+  }
+
+  return { rules, warnings };
+}
+
+// --- Main Decision Table Parser ---
+
+export function parseDecisionTable(elements: MdElement[]): { decisionTable: DecisionTableDef; warnings: string[] } {
+  let tableName = '';
+  let description: string | undefined;
+  let conditions: ConditionDef[] = [];
+  let actions: ActionOutputDef[] = [];
+  let rules: Rule[] = [];
+  let policy: 'first-match' | 'all-match' = 'first-match';
+  const warnings: string[] = [];
+
+  // Track current section
+  let currentSection: 'conditions' | 'actions' | 'rules' | null = null;
+  let currentTable: MdTable | null = null;
+
+  // Collect description from paragraphs before first ## heading
+  const descriptionParts: string[] = [];
+
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+
+    if (el.kind === 'heading') {
+      if (el.level === 1 && el.text.startsWith('decision_table ')) {
+        tableName = el.text.slice(15).trim();
+        continue;
+      }
+
+      if (el.level === 2) {
+        const sectionName = el.text.toLowerCase();
+
+        // Before processing first section, capture accumulated description
+        if (currentSection === null && descriptionParts.length > 0) {
+          description = descriptionParts.join(' ').trim();
+        }
+
+        if (sectionName === 'conditions') {
+          currentSection = 'conditions';
+        } else if (sectionName === 'actions') {
+          currentSection = 'actions';
+        } else if (sectionName === 'rules') {
+          currentSection = 'rules';
+        } else if (sectionName === 'metadata') {
+          currentSection = null; // metadata doesn't have a table
+        } else {
+          currentSection = null;
+        }
+        currentTable = null;
+        continue;
+      }
+
+      // Reset section on unknown headings
+      currentSection = null;
+      currentTable = null;
+    }
+
+    // Accumulate description from paragraphs and blockquotes before first section
+    if (currentSection === null) {
+      if (el.kind === 'paragraph') {
+        descriptionParts.push(el.text);
+      } else if (el.kind === 'blockquote') {
+        descriptionParts.push(el.text);
+      }
+    }
+
+    // Capture tables for current section
+    if (el.kind === 'table' && currentSection !== null) {
+      if (currentSection === 'conditions') {
+        conditions = parseConditionsTable(el);
+      } else if (currentSection === 'actions') {
+        actions = parseActionsTable(el);
+      } else if (currentSection === 'rules') {
+        const result = parseRulesTable(el, new Set(conditions.map(c => c.name)), new Set(actions.map(a => a.name)));
+        rules = result.rules;
+        warnings.push(...result.warnings);
+      }
+      currentTable = el;
+    }
+  }
+
+  const decisionTable: DecisionTableDef = {
+    name: tableName,
+    description,
+    conditions,
+    actions,
+    rules,
+    policy,
+  };
+
+  return { decisionTable, warnings };
+}
+
+// Parse a chunk of markdown elements that represents a single decision table
+// Returns null if the chunk doesn't start with # decision_table
+export function parseDecisionTableChunk(chunk: MdElement[]): DecisionTableDef | null {
+  if (chunk.length === 0) return null;
+
+  const firstHeading = chunk.find(el => el.kind === 'heading' && el.level === 1) as MdHeading | undefined;
+  if (!firstHeading || !firstHeading.text.startsWith('decision_table ')) {
+    return null;
+  }
+
+  const { decisionTable } = parseDecisionTable(chunk);
+  return decisionTable;
+}

package/src/parser/markdown-parser.ts

@@ -10,6 +10,8 @@ import {
   ReachabilityProperty, PassesThroughProperty, RespondsProperty,
   InvariantProperty, InvokeDef,
 } from './ast.js';
+import { DecisionTableDef } from './dt-ast.js';
+import { parseDecisionTable } from './dt-parser.js';
 
 // ============================================================
 // Phase 1: Structural Markdown Parsing
@@ -790,7 +792,7 @@ function parseMachineFromElements(elements: MdElement[]): MachineDef {
   return machine;
 }
 
-function parseMarkdownSemantic(elements: MdElement[]): MachineDef[] {
+function parseMarkdownSemantic(elements: MdElement[]): { machines: MachineDef[]; decisionTables: DecisionTableDef[] } {
   // Split elements by --- separators for multi-machine files
   const chunks: MdElement[][] = [];
   let currentChunk: MdElement[] = [];
@@ -809,8 +811,33 @@ function parseMarkdownSemantic(elements: MdElement[]): MachineDef[] {
     chunks.push(currentChunk);
   }
 
-  // Parse each chunk as a separate machine
-  return chunks.map(chunk => parseMachineFromElements(chunk));
+  // Parse each chunk based on its H1 heading type
+  const machines: MachineDef[] = [];
+  const decisionTables: DecisionTableDef[] = [];
+
+  for (const chunk of chunks) {
+    // Find ALL H1 headings in the chunk to determine what it contains
+    const headings = chunk.filter(el => el.kind === 'heading' && el.level === 1) as MdHeading[];
+
+    // Check if chunk contains a decision_table (must be first H1 to be recognized as DT chunk)
+    const firstHeading = headings[0];
+    if (firstHeading?.text.startsWith('decision_table ')) {
+      const { decisionTable } = parseDecisionTable(chunk);
+      decisionTables.push(decisionTable);
+    } else if (firstHeading?.text.startsWith('machine ')) {
+      // First heading is machine - parse entire chunk as machine
+      machines.push(parseMachineFromElements(chunk));
+    } else {
+      // First heading is not machine or decision_table - scan for machine heading
+      const machineHeading = headings.find(h => h.text.startsWith('machine '));
+      if (machineHeading) {
+        machines.push(parseMachineFromElements(chunk));
+      }
+      // Skip chunks without a recognized machine or decision_table heading
+    }
+  }
+
+  return { machines, decisionTables };
 }
 
 function parseEffectsTable(table: MdTable): EffectDef[] {
@@ -834,8 +861,8 @@ function parsePropertiesList(list: MdBulletList): Property[] {
 
 export function parseMarkdown(source: string): ParseResult {
   const elements = parseMarkdownStructure(source);
-  const machines = parseMarkdownSemantic(elements);
-  return { file: { machines }, tokens: [] };
+  const { machines, decisionTables } = parseMarkdownSemantic(elements);
+  return { file: { machines, decisionTables }, tokens: [] };
 }
 
 /**

package/src/skills.ts

@@ -7,6 +7,8 @@ import { checkProperties } from './verifier/properties.js';
 import { compileToXState } from './compiler/xstate.js';
 import { compileToMermaid } from './compiler/mermaid.js';
 import { MachineDef, StateDef, GuardExpression, Type } from './parser/ast.js';
+import { verifyDecisionTable, verifyDecisionTables } from './verifier/dt-verifier.js';
+import { compileDecisionTableToTypeScript, compileDecisionTableToJSON } from './compiler/dt-compiler.js';
 import { loadConfig, resolveConfigOverrides } from './config/index.js';
 import { createProvider } from './llm/index.js';
 import type { LLMProvider } from './llm/index.js';
@@ -45,7 +47,12 @@ export interface SkillError {
   location?: {
     state?: string;
     event?: string;
-    transition?: string;
+    transition?: string | { source?: string; target?: string; event?: string }; // string for machine errors, object for DT errors
+    // Decision table specific
+    rule?: number;
+    condition?: string;
+    action?: string;
+    decisionTable?: string;
   };
   suggestion?: string;
 }
@@ -1677,3 +1684,269 @@ function extractMachineNameFromSource(orca: string): string {
   const match = orca.match(/^(?:#\s+)?machine\s+(\w+)/m);
   return match ? match[1] : 'Unknown';
 }
+
+// ============================================================
+// Decision Table Skills
+// ============================================================
+
+export interface VerifyDTSkillResult {
+  status: 'valid' | 'invalid';
+  decisionTable: string;
+  conditions: number;
+  actions: number;
+  rules: number;
+  errors: SkillError[];
+}
+
+export interface CompileDTSkillResult {
+  status: 'success' | 'error';
+  target: 'typescript' | 'json';
+  output: string;
+  warnings: SkillError[];
+}
+
+/**
+ * Parse a decision table from source.
+ */
+export function parseDTSkill(input: SkillInput): { status: 'success' | 'error'; decisionTables?: object[]; error?: string } {
+  try {
+    const source = resolveSource(input);
+    const { file } = parseMarkdown(source);
+
+    if (file.decisionTables.length === 0) {
+      return { status: 'error', error: 'No decision table found in source' };
+    }
+
+    // Return all decision tables as plain objects
+    const tables = file.decisionTables.map(dt => ({
+      name: dt.name,
+      description: dt.description,
+      conditions: dt.conditions.map(c => ({
+        name: c.name,
+        type: c.type,
+        values: c.values,
+        range: c.range,
+      })),
+      actions: dt.actions.map(a => ({
+        name: a.name,
+        type: a.type,
+        description: a.description,
+        values: a.values,
+      })),
+      rules: dt.rules.map(r => ({
+        number: r.number,
+        conditions: Object.fromEntries(r.conditions),
+        actions: Object.fromEntries(r.actions),
+      })),
+      policy: dt.policy,
+    }));
+
+    return { status: 'success', decisionTables: tables };
+  } catch (err) {
+    return { status: 'error', error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Verify a decision table.
+ */
+export function verifyDTSkill(input: SkillInput): VerifyDTSkillResult {
+  try {
+    const source = resolveSource(input);
+    const { file } = parseMarkdown(source);
+
+    if (file.decisionTables.length === 0) {
+      return {
+        status: 'invalid',
+        decisionTable: '',
+        conditions: 0,
+        actions: 0,
+        rules: 0,
+        errors: [{ code: 'DT_NOT_FOUND', message: 'No decision table found in source', severity: 'error' }],
+      };
+    }
+
+    // Verify all decision tables
+    const verification = verifyDecisionTables(file.decisionTables);
+
+    // Return result for the first decision table
+    const dt = file.decisionTables[0];
+    const errors: SkillError[] = [];
+    for (const e of verification.errors) {
+      const loc = e.location;
+      errors.push({
+        code: e.code,
+        message: e.message,
+        severity: e.severity as 'error' | 'warning',
+        location: loc ? {
+          state: loc.state,
+          event: loc.event,
+          rule: loc.rule,
+          condition: loc.condition,
+          action: loc.action,
+          decisionTable: loc.decisionTable,
+        } : undefined,
+        suggestion: e.suggestion,
+      });
+    }
+
+    return {
+      status: verification.valid ? 'valid' : 'invalid',
+      decisionTable: dt.name,
+      conditions: dt.conditions.length,
+      actions: dt.actions.length,
+      rules: dt.rules.length,
+      errors,
+    };
+  } catch (err) {
+    return {
+      status: 'invalid',
+      decisionTable: '',
+      conditions: 0,
+      actions: 0,
+      rules: 0,
+      errors: [{ code: 'PARSE_ERROR', message: err instanceof Error ? err.message : String(err), severity: 'error' }],
+    };
+  }
+}
+
+/**
+ * Compile a decision table to TypeScript or JSON.
+ */
+export function compileDTSkill(input: SkillInput, target: 'typescript' | 'json' = 'typescript'): CompileDTSkillResult {
+  try {
+    const source = resolveSource(input);
+    const { file } = parseMarkdown(source);
+
+    if (file.decisionTables.length === 0) {
+      return {
+        status: 'error',
+        target,
+        output: '',
+        warnings: [{ code: 'DT_NOT_FOUND', message: 'No decision table found in source', severity: 'error' }],
+      };
+    }
+
+    const dt = file.decisionTables[0];
+    const output = target === 'json'
+      ? compileDecisionTableToJSON(dt)
+      : compileDecisionTableToTypeScript(dt);
+
+    return { status: 'success', target, output, warnings: [] };
+  } catch (err) {
+    return {
+      status: 'error',
+      target,
+      output: '',
+      warnings: [{ code: 'COMPILE_ERROR', message: err instanceof Error ? err.message : String(err), severity: 'error' }],
+    };
+  }
+}
+
+// Decision table syntax reference for LLM generation
+const DT_SYNTAX_REFERENCE = `
+# decision_table Name
+
+## conditions
+
+| Name | Type | Values |
+|------|------|--------|
+| field_name | enum | value1, value2 |
+| is_active | bool | |
+| count | int_range | 1..100 |
+
+## actions
+
+| Name | Type | Description |
+|------|------|-------------|
+| result | enum | Result description |
+| flag | bool | Whether something |
+
+## rules
+
+| condition1 | condition2 | → action1 | → action2 |
+|------------|-----------|----------|-----------|
+| value1 | - | result1 | true |
+| value2 | !value3 | result2 | false |
+
+Notes:
+- "-" in a condition cell means "any" (wildcard)
+- "!value" negates a value
+- "a,b" matches any of the values (OR semantics)
+- Rules are evaluated top-to-bottom; first match wins
+`;
+
+/**
+ * Generate a decision table from natural language spec.
+ */
+export async function generateDTSkill(spec: string, configPath?: string): Promise<{
+  status: 'success' | 'error' | 'requires_refinement';
+  decisionTable?: string;
+  orca?: string;
+  verification?: VerifyDTSkillResult;
+  error?: string;
+}> {
+  const config = loadConfig(configPath);
+  const provider = createProvider(config.provider, {
+    api_key: config.api_key,
+    base_url: config.base_url,
+    model: config.model,
+    max_tokens: config.max_tokens,
+    temperature: config.temperature,
+  });
+
+  if (!provider) {
+    return { status: 'error', error: 'No LLM provider configured' };
+  }
+
+  const prompt = `Generate a decision table in .orca.md format based on the following specification.
+
+${DT_SYNTAX_REFERENCE}
+
+Specification:
+${spec}
+
+Respond with the decision table only, no explanation.`;
+
+  try {
+    const response = await provider.complete({
+      messages: [{ role: 'user', content: prompt }],
+      model: '',
+      max_tokens: config.max_tokens || 2048,
+      temperature: 0.7,
+    });
+
+    const orca = stripCodeFence(response.content);
+
+    // Verify the generated decision table
+    const { file } = parseMarkdown(orca);
+    if (file.decisionTables.length === 0) {
+      return { status: 'error', error: 'Generated content does not contain a valid decision table', orca };
+    }
+
+    const verification = verifyDecisionTables(file.decisionTables);
+
+    return {
+      status: verification.valid ? 'success' : 'requires_refinement',
+      decisionTable: file.decisionTables[0].name,
+      orca,
+      verification: verification.valid ? undefined : {
+        status: 'invalid',
+        decisionTable: file.decisionTables[0].name,
+        conditions: file.decisionTables[0].conditions.length,
+        actions: file.decisionTables[0].actions.length,
+        rules: file.decisionTables[0].rules.length,
+        errors: verification.errors.map(e => ({
+          code: e.code,
+          message: e.message,
+          severity: e.severity,
+          location: e.location,
+          suggestion: e.suggestion,
+        })),
+      },
+    };
+  } catch (err) {
+    return { status: 'error', error: err instanceof Error ? err.message : String(err) };
+  }
+}
+

package/src/tools.ts

@@ -143,4 +143,57 @@ export const ORCA_TOOLS: ToolDef[] = [
       required: [],
     },
   },
+  {
+    name: 'parse_decision_table',
+    description:
+      'Parse decision table from .orca.md source → JSON (conditions, actions, rules). Syntax: # decision_table Name, ## conditions table, ## actions table, ## rules table. Can be standalone or combined with machines in the same file.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source: { type: 'string', description: 'Raw .orca.md content containing a # decision_table heading.' },
+      },
+      required: ['source'],
+    },
+  },
+  {
+    name: 'verify_decision_table',
+    description:
+      'Verify decision table: checks completeness (all condition combinations covered), consistency (no contradictory rules), redundancy. Returns structured errors with codes and suggestions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source: { type: 'string', description: 'Raw .orca.md content containing a # decision_table heading.' },
+      },
+      required: ['source'],
+    },
+  },
+  {
+    name: 'compile_decision_table',
+    description:
+      'Compile verified decision table to TypeScript evaluator function or portable JSON. Run verify_decision_table first. target: "typescript" (default) or "json".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source: { type: 'string', description: 'Raw .orca.md content containing a # decision_table heading.' },
+        target: {
+          type: 'string',
+          enum: ['typescript', 'json'],
+          description: 'Compilation target (default: typescript)',
+        },
+      },
+      required: ['source'],
+    },
+  },
+  {
+    name: 'generate_decision_table',
+    description:
+      'Generate a decision table in .orca.md format from a natural language spec. Always verify_decision_table next. Requires LLM API key.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec: { type: 'string', description: 'Natural language description of the decision logic' },
+      },
+      required: ['spec'],
+    },
+  },
 ];