yaml-flow 2.1.0 → 2.2.0

package/README.md

@@ -748,6 +748,78 @@ See the [examples/graph-of-graphs/](./examples/graph-of-graphs/) directory for c
 
 ---
 
+## Execution Plan (Dry Run)
+
+Compute the full execution plan from a graph config without running anything — like `terraform plan` for workflows.
+
+```typescript
+import { planExecution } from 'yaml-flow/event-graph';
+
+const plan = planExecution(graph);
+
+plan.phases;          // [['prep'], ['copy'], ['evidence'], ['synthesis'], ['analyze'], ['health', 'report'], ['archive']]
+plan.depth;           // 7
+plan.maxParallelism;  // 2
+plan.entryPoints;     // ['prep']
+plan.leafTasks;       // ['archive']
+plan.conflicts;       // { 'output-token': ['task-a', 'task-b'] }  — multiple producers
+plan.unreachableTokens; // ['human-approval']  — required but no task produces it
+plan.blockedTasks;    // ['approve']  — blocked by unreachable tokens
+plan.dependencies;    // { 'copy': ['prep'], 'evidence': ['copy'], ... }
+```
+
+---
+
+## Mermaid Diagrams
+
+Generate Mermaid syntax from any config — useful for docs, debugging, and CI reports.
+
+```typescript
+import { graphToMermaid, flowToMermaid } from 'yaml-flow/event-graph';
+
+// Event graph → dependency diagram
+console.log(graphToMermaid(graph));
+// graph TD
+//   build([build])
+//   test[test]
+//   deploy[[deploy]]
+//   build -->|artifact| test
+//   test -->|tested| deploy
+
+// Step machine → flowchart
+console.log(flowToMermaid(flow));
+// graph TD
+//   START(( ))
+//   START --> classify
+//   classify -->|billing| handle
+//   handle -->|resolved| done
+//   done([done: resolved])
+```
+
+Options: `{ direction: 'LR' | 'TD', showTokens: boolean, title: string }`.  
+Entry points (no requires) get rounded shapes, leaf tasks get double-bracketed shapes, unreachable deps get warning markers.
+
+---
+
+## Loading & Exporting Graph Configs
+
+```typescript
+import { loadGraphConfig, exportGraphConfig, exportGraphConfigToFile } from 'yaml-flow/event-graph';
+
+// Load from file, URL, JSON string, or object (validates automatically)
+const graph = await loadGraphConfig('./pipeline.yaml');
+const graph2 = await loadGraphConfig('https://example.com/graph.json');
+
+// Export to string
+const json = exportGraphConfig(graph);                         // JSON (default)
+const yaml = exportGraphConfig(graph, { format: 'yaml' });     // YAML
+
+// Export to file (format auto-detected from extension)
+await exportGraphConfigToFile(graph, './output/pipeline.yaml');
+```
+
+---
+
 ## Package Exports
 
 ```typescript
@@ -761,6 +833,8 @@ import { applyStepResult, checkCircuitBreaker, createInitialState } from 'yaml-f
 // Event Graph only
 import { next, apply, applyAll, getCandidateTasks } from 'yaml-flow/event-graph';
 import { createInitialExecutionState, isExecutionComplete, detectStuckState } from 'yaml-flow/event-graph';
+import { planExecution, graphToMermaid, flowToMermaid } from 'yaml-flow/event-graph';
+import { loadGraphConfig, validateGraphConfig, exportGraphConfig } from 'yaml-flow/event-graph';
 import { TASK_STATUS, COMPLETION_STRATEGIES, CONFLICT_STRATEGIES } from 'yaml-flow/event-graph';
 
 // Stores
@@ -808,6 +882,13 @@ import { FlowEngine, createEngine } from 'yaml-flow';  // aliases for StepMachin
 | `isExecutionComplete(graph, state)` | Check completion against configured strategy |
 | `detectStuckState({graph, state, ...})` | Check if execution is stuck |
 | `addDynamicTask(graph, name, config)` | Immutably add a task to a graph config |
+| `planExecution(graph)` | Dry-run: compute phases, parallelism, conflicts, unreachable tokens |
+| `graphToMermaid(graph, options?)` | Generate Mermaid dependency diagram from an event-graph |
+| `flowToMermaid(flow, options?)` | Generate Mermaid flowchart from a step-machine |
+| `loadGraphConfig(source)` | Load + validate a YAML/JSON/URL graph config |
+| `validateGraphConfig(config)` | Validate a GraphConfig, returns error strings |
+| `exportGraphConfig(config, options?)` | Export a GraphConfig to JSON or YAML string |
+| `exportGraphConfigToFile(config, path)` | Export a GraphConfig to a file |
 
 ### Event Types (for `apply()`)
 

package/dist/{constants-D1fTEbbM.d.ts → constants-Bwvkbr5s.d.cts}

@@ -1,3 +1,5 @@
+import { e as StepFlowConfig } from './types-FZ_eyErS.cjs';
+
 /**
  * Event Graph — Core Types
  *
@@ -311,6 +313,131 @@ declare function detectStuckState(params: {
     completionResult?: CompletionResult;
 }): StuckDetection;
 
+/**
+ * Event Graph — Execution Plan (Dry Run)
+ *
+ * Compute the full execution plan from a GraphConfig without running anything.
+ * Shows phases (what runs in parallel), dependency edges, and potential issues.
+ *
+ * Pure function — no I/O, no side effects.
+ */
+
+interface ExecutionPlan {
+    /** Ordered phases — tasks within a phase can run in parallel */
+    phases: string[][];
+    /** Dependency edges: taskName → tasks it depends on */
+    dependencies: Record<string, string[]>;
+    /** Tasks that provide conflicts (same output from multiple tasks) */
+    conflicts: Record<string, string[]>;
+    /** Tasks that have no requires (entry points) */
+    entryPoints: string[];
+    /** Tasks that nothing depends on (leaf nodes) */
+    leafTasks: string[];
+    /** Tokens required but not produced by any task */
+    unreachableTokens: string[];
+    /** Tasks blocked by unreachable tokens */
+    blockedTasks: string[];
+    /** Total number of phases (depth of the graph) */
+    depth: number;
+    /** Max parallelism (widest phase) */
+    maxParallelism: number;
+}
+/**
+ * Compute a full execution plan from a graph config.
+ *
+ * Shows the order tasks would execute, what can run in parallel,
+ * where conflicts exist, and what's unreachable — all without
+ * actually running anything.
+ *
+ * @param graph - The event-graph configuration
+ * @returns ExecutionPlan with phases, dependencies, conflicts, and diagnostics
+ */
+declare function planExecution(graph: GraphConfig): ExecutionPlan;
+
+/**
+ * Mermaid Diagram Export
+ *
+ * Generate Mermaid diagram strings from GraphConfig (event-graph)
+ * and StepFlowConfig (step-machine). Useful for documentation,
+ * debugging, and CI reports.
+ *
+ * Pure functions — no I/O, no side effects.
+ */
+
+interface MermaidOptions {
+    /** Diagram direction: TB (top-bottom), LR (left-right), etc. Default: 'TD' */
+    direction?: 'TD' | 'TB' | 'LR' | 'RL' | 'BT';
+    /** Show token labels on edges. Default: true */
+    showTokens?: boolean;
+    /** Title comment at top. Default: graph.id or 'Event Graph' */
+    title?: string;
+}
+/**
+ * Generate a Mermaid dependency graph from an event-graph config.
+ *
+ * Tasks are nodes. Edges represent token dependencies:
+ * if task B requires token X and task A provides X, then A --> B.
+ *
+ * @param graph - Event graph configuration
+ * @param options - Diagram options
+ * @returns Mermaid diagram string
+ */
+declare function graphToMermaid(graph: GraphConfig, options?: MermaidOptions): string;
+/**
+ * Generate a Mermaid flowchart from a step-machine config.
+ *
+ * Steps are nodes. Transitions are labeled edges.
+ * Terminal states are shown as filled/rounded nodes.
+ *
+ * @param flow - Step machine flow configuration
+ * @param options - Diagram options
+ * @returns Mermaid diagram string
+ */
+declare function flowToMermaid(flow: StepFlowConfig, options?: MermaidOptions): string;
+
+/**
+ * Event Graph — Loader & Exporter
+ *
+ * Load GraphConfig from YAML/JSON files or strings, and export back.
+ * Mirrors the step-machine's loadStepFlow/validateStepFlowConfig pattern.
+ */
+
+/**
+ * Validate a GraphConfig object. Returns an array of error strings.
+ * Empty array = valid config.
+ */
+declare function validateGraphConfig(config: unknown): string[];
+/**
+ * Load a GraphConfig from a file path, URL, JSON string, or object.
+ * Validates the config and throws if invalid.
+ *
+ * @param source - File path (.yaml/.yml/.json), URL, JSON string, or GraphConfig object
+ * @returns Validated GraphConfig
+ */
+declare function loadGraphConfig(source: string | GraphConfig): Promise<GraphConfig>;
+interface ExportOptions {
+    /** Output format. Default: 'json' */
+    format?: 'json' | 'yaml';
+    /** Indentation for JSON (default: 2) or YAML */
+    indent?: number;
+}
+/**
+ * Export a GraphConfig to a JSON or YAML string.
+ *
+ * @param config - The graph configuration to export
+ * @param options - Export format options
+ * @returns Serialized config string
+ */
+declare function exportGraphConfig(config: GraphConfig, options?: ExportOptions): string;
+/**
+ * Export a GraphConfig to a file.
+ *
+ * @param config - The graph configuration to export
+ * @param filePath - Output file path (.json or .yaml/.yml)
+ * @param options - Export format options (format auto-detected from extension if not specified)
+ */
+declare function exportGraphConfigToFile(config: GraphConfig, filePath: string, options?: ExportOptions): Promise<void>;
+
 /**
  * Event Graph — Constants
  */
@@ -327,4 +454,4 @@ declare const DEFAULTS: {
     readonly MAX_ITERATIONS: 1000;
 };
 
-export { getRepeatableMax as $, type AgentActionEvent as A, getAllTasks as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, getCandidateTasks as F, type GraphConfig as G, getProvides as H, type InjectTokensEvent as I, getRequires as J, getTask as K, hasTask as L, isExecutionComplete as M, isNonActiveTask as N, isRepeatableTask as O, isTaskCompleted as P, isTaskRunning as Q, next as R, type SchedulerResult as S, type TaskConfig as T, type RepeatableConfig as U, type TaskCircuitBreakerConfig as V, type TaskMessage as W, type TaskProgressEvent as X, type TaskRetryConfig as Y, addKeyToProvides as Z, addKeyToRequires as _, CONFLICT_STRATEGIES as a, groupTasksByProvides as a0, hasOutputConflict as a1, removeKeyFromProvides as a2, removeKeyFromRequires as a3, type CompletionResult as b, type CompletionStrategy as c, type ConflictStrategy as d, EXECUTION_STATUS as e, type ExecutionConfig as f, type ExecutionMode as g, type ExecutionState as h, type ExecutionStatus as i, type GraphEvent as j, type GraphSettings as k, type StuckDetection as l, TASK_STATUS as m, type TaskCompletedEvent as n, type TaskCreationEvent as o, type TaskFailedEvent as p, type TaskStartedEvent as q, type TaskState as r, type TaskStatus as s, addDynamicTask as t, apply as u, applyAll as v, computeAvailableOutputs as w, createDefaultTaskState as x, createInitialExecutionState as y, detectStuckState as z };
+export { next as $, type AgentActionEvent as A, createInitialExecutionState as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, detectStuckState as F, type GraphConfig as G, exportGraphConfig as H, type InjectTokensEvent as I, exportGraphConfigToFile as J, flowToMermaid as K, getAllTasks as L, type MermaidOptions as M, getCandidateTasks as N, getProvides as O, getRequires as P, getTask as Q, graphToMermaid as R, type SchedulerResult as S, type TaskConfig as T, hasTask as U, isExecutionComplete as V, isNonActiveTask as W, isRepeatableTask as X, isTaskCompleted as Y, isTaskRunning as Z, loadGraphConfig as _, CONFLICT_STRATEGIES as a, planExecution as a0, validateGraphConfig as a1, type RepeatableConfig as a2, type TaskCircuitBreakerConfig as a3, type TaskMessage as a4, type TaskProgressEvent as a5, type TaskRetryConfig as a6, addKeyToProvides as a7, addKeyToRequires as a8, getRepeatableMax as a9, groupTasksByProvides as aa, hasOutputConflict as ab, removeKeyFromProvides as ac, removeKeyFromRequires as ad, type CompletionResult as b, type CompletionStrategy as c, type ConflictStrategy as d, EXECUTION_STATUS as e, type ExecutionConfig as f, type ExecutionMode as g, type ExecutionPlan as h, type ExecutionState as i, type ExecutionStatus as j, type ExportOptions as k, type GraphEvent as l, type GraphSettings as m, type StuckDetection as n, TASK_STATUS as o, type TaskCompletedEvent as p, type TaskCreationEvent as q, type TaskFailedEvent as r, type TaskStartedEvent as s, type TaskState as t, type TaskStatus as u, addDynamicTask as v, apply as w, applyAll as x, computeAvailableOutputs as y, createDefaultTaskState as z };

package/dist/{constants-D1fTEbbM.d.cts → constants-Ewufm5cK.d.ts}

@@ -1,3 +1,5 @@
+import { e as StepFlowConfig } from './types-FZ_eyErS.js';
+
 /**
  * Event Graph — Core Types
  *
@@ -311,6 +313,131 @@ declare function detectStuckState(params: {
     completionResult?: CompletionResult;
 }): StuckDetection;
 
+/**
+ * Event Graph — Execution Plan (Dry Run)
+ *
+ * Compute the full execution plan from a GraphConfig without running anything.
+ * Shows phases (what runs in parallel), dependency edges, and potential issues.
+ *
+ * Pure function — no I/O, no side effects.
+ */
+
+interface ExecutionPlan {
+    /** Ordered phases — tasks within a phase can run in parallel */
+    phases: string[][];
+    /** Dependency edges: taskName → tasks it depends on */
+    dependencies: Record<string, string[]>;
+    /** Tasks that provide conflicts (same output from multiple tasks) */
+    conflicts: Record<string, string[]>;
+    /** Tasks that have no requires (entry points) */
+    entryPoints: string[];
+    /** Tasks that nothing depends on (leaf nodes) */
+    leafTasks: string[];
+    /** Tokens required but not produced by any task */
+    unreachableTokens: string[];
+    /** Tasks blocked by unreachable tokens */
+    blockedTasks: string[];
+    /** Total number of phases (depth of the graph) */
+    depth: number;
+    /** Max parallelism (widest phase) */
+    maxParallelism: number;
+}
+/**
+ * Compute a full execution plan from a graph config.
+ *
+ * Shows the order tasks would execute, what can run in parallel,
+ * where conflicts exist, and what's unreachable — all without
+ * actually running anything.
+ *
+ * @param graph - The event-graph configuration
+ * @returns ExecutionPlan with phases, dependencies, conflicts, and diagnostics
+ */
+declare function planExecution(graph: GraphConfig): ExecutionPlan;
+
+/**
+ * Mermaid Diagram Export
+ *
+ * Generate Mermaid diagram strings from GraphConfig (event-graph)
+ * and StepFlowConfig (step-machine). Useful for documentation,
+ * debugging, and CI reports.
+ *
+ * Pure functions — no I/O, no side effects.
+ */
+
+interface MermaidOptions {
+    /** Diagram direction: TB (top-bottom), LR (left-right), etc. Default: 'TD' */
+    direction?: 'TD' | 'TB' | 'LR' | 'RL' | 'BT';
+    /** Show token labels on edges. Default: true */
+    showTokens?: boolean;
+    /** Title comment at top. Default: graph.id or 'Event Graph' */
+    title?: string;
+}
+/**
+ * Generate a Mermaid dependency graph from an event-graph config.
+ *
+ * Tasks are nodes. Edges represent token dependencies:
+ * if task B requires token X and task A provides X, then A --> B.
+ *
+ * @param graph - Event graph configuration
+ * @param options - Diagram options
+ * @returns Mermaid diagram string
+ */
+declare function graphToMermaid(graph: GraphConfig, options?: MermaidOptions): string;
+/**
+ * Generate a Mermaid flowchart from a step-machine config.
+ *
+ * Steps are nodes. Transitions are labeled edges.
+ * Terminal states are shown as filled/rounded nodes.
+ *
+ * @param flow - Step machine flow configuration
+ * @param options - Diagram options
+ * @returns Mermaid diagram string
+ */
+declare function flowToMermaid(flow: StepFlowConfig, options?: MermaidOptions): string;
+
+/**
+ * Event Graph — Loader & Exporter
+ *
+ * Load GraphConfig from YAML/JSON files or strings, and export back.
+ * Mirrors the step-machine's loadStepFlow/validateStepFlowConfig pattern.
+ */
+
+/**
+ * Validate a GraphConfig object. Returns an array of error strings.
+ * Empty array = valid config.
+ */
+declare function validateGraphConfig(config: unknown): string[];
+/**
+ * Load a GraphConfig from a file path, URL, JSON string, or object.
+ * Validates the config and throws if invalid.
+ *
+ * @param source - File path (.yaml/.yml/.json), URL, JSON string, or GraphConfig object
+ * @returns Validated GraphConfig
+ */
+declare function loadGraphConfig(source: string | GraphConfig): Promise<GraphConfig>;
+interface ExportOptions {
+    /** Output format. Default: 'json' */
+    format?: 'json' | 'yaml';
+    /** Indentation for JSON (default: 2) or YAML */
+    indent?: number;
+}
+/**
+ * Export a GraphConfig to a JSON or YAML string.
+ *
+ * @param config - The graph configuration to export
+ * @param options - Export format options
+ * @returns Serialized config string
+ */
+declare function exportGraphConfig(config: GraphConfig, options?: ExportOptions): string;
+/**
+ * Export a GraphConfig to a file.
+ *
+ * @param config - The graph configuration to export
+ * @param filePath - Output file path (.json or .yaml/.yml)
+ * @param options - Export format options (format auto-detected from extension if not specified)
+ */
+declare function exportGraphConfigToFile(config: GraphConfig, filePath: string, options?: ExportOptions): Promise<void>;
+
 /**
  * Event Graph — Constants
  */
@@ -327,4 +454,4 @@ declare const DEFAULTS: {
     readonly MAX_ITERATIONS: 1000;
 };
 
-export { getRepeatableMax as $, type AgentActionEvent as A, getAllTasks as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, getCandidateTasks as F, type GraphConfig as G, getProvides as H, type InjectTokensEvent as I, getRequires as J, getTask as K, hasTask as L, isExecutionComplete as M, isNonActiveTask as N, isRepeatableTask as O, isTaskCompleted as P, isTaskRunning as Q, next as R, type SchedulerResult as S, type TaskConfig as T, type RepeatableConfig as U, type TaskCircuitBreakerConfig as V, type TaskMessage as W, type TaskProgressEvent as X, type TaskRetryConfig as Y, addKeyToProvides as Z, addKeyToRequires as _, CONFLICT_STRATEGIES as a, groupTasksByProvides as a0, hasOutputConflict as a1, removeKeyFromProvides as a2, removeKeyFromRequires as a3, type CompletionResult as b, type CompletionStrategy as c, type ConflictStrategy as d, EXECUTION_STATUS as e, type ExecutionConfig as f, type ExecutionMode as g, type ExecutionState as h, type ExecutionStatus as i, type GraphEvent as j, type GraphSettings as k, type StuckDetection as l, TASK_STATUS as m, type TaskCompletedEvent as n, type TaskCreationEvent as o, type TaskFailedEvent as p, type TaskStartedEvent as q, type TaskState as r, type TaskStatus as s, addDynamicTask as t, apply as u, applyAll as v, computeAvailableOutputs as w, createDefaultTaskState as x, createInitialExecutionState as y, detectStuckState as z };
+export { next as $, type AgentActionEvent as A, createInitialExecutionState as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, detectStuckState as F, type GraphConfig as G, exportGraphConfig as H, type InjectTokensEvent as I, exportGraphConfigToFile as J, flowToMermaid as K, getAllTasks as L, type MermaidOptions as M, getCandidateTasks as N, getProvides as O, getRequires as P, getTask as Q, graphToMermaid as R, type SchedulerResult as S, type TaskConfig as T, hasTask as U, isExecutionComplete as V, isNonActiveTask as W, isRepeatableTask as X, isTaskCompleted as Y, isTaskRunning as Z, loadGraphConfig as _, CONFLICT_STRATEGIES as a, planExecution as a0, validateGraphConfig as a1, type RepeatableConfig as a2, type TaskCircuitBreakerConfig as a3, type TaskMessage as a4, type TaskProgressEvent as a5, type TaskRetryConfig as a6, addKeyToProvides as a7, addKeyToRequires as a8, getRepeatableMax as a9, groupTasksByProvides as aa, hasOutputConflict as ab, removeKeyFromProvides as ac, removeKeyFromRequires as ad, type CompletionResult as b, type CompletionStrategy as c, type ConflictStrategy as d, EXECUTION_STATUS as e, type ExecutionConfig as f, type ExecutionMode as g, type ExecutionPlan as h, type ExecutionState as i, type ExecutionStatus as j, type ExportOptions as k, type GraphEvent as l, type GraphSettings as m, type StuckDetection as n, TASK_STATUS as o, type TaskCompletedEvent as p, type TaskCreationEvent as q, type TaskFailedEvent as r, type TaskStartedEvent as s, type TaskState as t, type TaskStatus as u, addDynamicTask as v, apply as w, applyAll as x, computeAvailableOutputs as y, createDefaultTaskState as z };