@stigmer/react 0.5.0 → 1.0.0

package/src/workflow/useWorkflowTopology.ts

@@ -0,0 +1,229 @@
+"use client";
+
+import { useMemo } from "react";
+import { parse as parseYaml } from "yaml";
+
+/** A node in the workflow topology graph. */
+export interface TopologyNode {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: string;
+  readonly category: TopologyNodeCategory;
+  /** Layout position computed by dagre (set after layout). */
+  x: number;
+  y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** An edge in the workflow topology graph. */
+export interface TopologyEdge {
+  readonly source: string;
+  readonly target: string;
+  readonly label?: string;
+}
+
+export type TopologyNodeCategory =
+  | "start"
+  | "end"
+  | "ai"
+  | "control_flow"
+  | "invocation"
+  | "data"
+  | "governance"
+  | "event"
+  | "unspecified";
+
+/** Return value of {@link useWorkflowTopology}. */
+export interface UseWorkflowTopologyReturn {
+  readonly nodes: readonly TopologyNode[];
+  readonly edges: readonly TopologyEdge[];
+}
+
+const AI_KINDS = new Set(["agent_call", "llm_call", "eval"]);
+const CONTROL_FLOW_KINDS = new Set(["switch_case", "for_each", "fork", "try_catch"]);
+const INVOCATION_KINDS = new Set(["http_call", "grpc_call", "activity_call", "run_workflow"]);
+const DATA_KINDS = new Set(["set_vars", "transform"]);
+const GOVERNANCE_KINDS = new Set(["human_input", "validate"]);
+const EVENT_KINDS = new Set(["listen", "wait", "emit_event", "notification", "raise_error"]);
+
+const NODE_WIDTH = 180;
+const NODE_HEIGHT = 40;
+
+/**
+ * Behavior hook that computes a DAG topology from workflow YAML.
+ *
+ * Parses the YAML into tasks and builds a node + edge graph suitable
+ * for rendering. Handles sequential flow, explicit `flow.then` directives,
+ * and `switch_case` branching edges.
+ *
+ * Returns stable refs (DD-010) — the result is memoized and only
+ * recomputed when the YAML content changes.
+ *
+ * @param yaml - The current workflow YAML string (or `null`/empty to skip).
+ *
+ * @since T10 (YAML Editor with Graph Preview)
+ */
+export function useWorkflowTopology(
+  yaml: string | null,
+): UseWorkflowTopologyReturn {
+  return useMemo(() => {
+    if (!yaml?.trim()) return EMPTY_TOPOLOGY;
+
+    try {
+      return computeTopology(yaml);
+    } catch {
+      return EMPTY_TOPOLOGY;
+    }
+  }, [yaml]);
+}
+
+const EMPTY_TOPOLOGY: UseWorkflowTopologyReturn = { nodes: [], edges: [] };
+
+// ---------------------------------------------------------------------------
+// Topology computation
+// ---------------------------------------------------------------------------
+
+interface RawTask {
+  name: string;
+  kind: string;
+  task_config?: Record<string, unknown>;
+  taskConfig?: Record<string, unknown>;
+  flow?: { then?: string };
+  export?: { as?: string };
+}
+
+function computeTopology(yaml: string): UseWorkflowTopologyReturn {
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(yaml);
+  } catch {
+    return EMPTY_TOPOLOGY;
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return EMPTY_TOPOLOGY;
+  }
+
+  const doc = parsed as Record<string, unknown>;
+  const spec = doc.spec as Record<string, unknown> | undefined;
+  if (!spec) return EMPTY_TOPOLOGY;
+
+  const rawTasks = spec.tasks;
+  if (!Array.isArray(rawTasks) || rawTasks.length === 0) return EMPTY_TOPOLOGY;
+
+  const tasks = rawTasks.filter(
+    (t): t is RawTask =>
+      t != null && typeof t === "object" && typeof (t as RawTask).name === "string",
+  );
+
+  if (tasks.length === 0) return EMPTY_TOPOLOGY;
+
+  const nodes: TopologyNode[] = [];
+  const edges: TopologyEdge[] = [];
+  const taskNameSet = new Set(tasks.map((t) => t.name));
+
+  const startNode: TopologyNode = {
+    id: "__start__",
+    label: "Start",
+    kind: "start",
+    category: "start",
+    x: 0, y: 0,
+    width: NODE_WIDTH, height: NODE_HEIGHT,
+  };
+  nodes.push(startNode);
+
+  for (const task of tasks) {
+    nodes.push({
+      id: task.name,
+      label: task.name,
+      kind: task.kind || "unspecified",
+      category: categorizeKind(task.kind),
+      x: 0, y: 0,
+      width: NODE_WIDTH, height: NODE_HEIGHT,
+    });
+  }
+
+  // Edge: start → first task
+  edges.push({ source: "__start__", target: tasks[0].name });
+
+  const tasksWithEndFlow = new Set<string>();
+
+  for (let i = 0; i < tasks.length; i++) {
+    const task = tasks[i];
+    const thenTarget = task.flow?.then;
+
+    if (thenTarget === "end") {
+      tasksWithEndFlow.add(task.name);
+      continue;
+    }
+
+    if (thenTarget && taskNameSet.has(thenTarget)) {
+      edges.push({ source: task.name, target: thenTarget });
+      continue;
+    }
+
+    // switch_case: add edges for each case
+    const config = task.task_config ?? task.taskConfig;
+    if (task.kind === "switch_case" && config) {
+      const cases = (config as Record<string, unknown>).cases;
+      if (Array.isArray(cases)) {
+        let hasDefault = false;
+        for (const c of cases) {
+          if (c && typeof c === "object") {
+            const caseObj = c as Record<string, unknown>;
+            const caseThen = caseObj.then as string | undefined;
+            if (caseThen && taskNameSet.has(caseThen)) {
+              edges.push({
+                source: task.name,
+                target: caseThen,
+                label: (caseObj.name as string) || undefined,
+              });
+              if (!(caseObj.when as string)) hasDefault = true;
+            }
+          }
+        }
+        if (!hasDefault && i < tasks.length - 1) {
+          edges.push({ source: task.name, target: tasks[i + 1].name });
+        }
+        continue;
+      }
+    }
+
+    // Default: sequential to next task
+    if (i < tasks.length - 1) {
+      edges.push({ source: task.name, target: tasks[i + 1].name });
+    } else {
+      tasksWithEndFlow.add(task.name);
+    }
+  }
+
+  // Add end node if any tasks flow to "end" or the last task has no explicit successor
+  if (tasksWithEndFlow.size > 0) {
+    const endNode: TopologyNode = {
+      id: "__end__",
+      label: "End",
+      kind: "end",
+      category: "end",
+      x: 0, y: 0,
+      width: NODE_WIDTH, height: NODE_HEIGHT,
+    };
+    nodes.push(endNode);
+
+    for (const name of tasksWithEndFlow) {
+      edges.push({ source: name, target: "__end__" });
+    }
+  }
+
+  return { nodes, edges };
+}
+
+function categorizeKind(kind: string): TopologyNodeCategory {
+  if (AI_KINDS.has(kind)) return "ai";
+  if (CONTROL_FLOW_KINDS.has(kind)) return "control_flow";
+  if (INVOCATION_KINDS.has(kind)) return "invocation";
+  if (DATA_KINDS.has(kind)) return "data";
+  if (GOVERNANCE_KINDS.has(kind)) return "governance";
+  if (EVENT_KINDS.has(kind)) return "event";
+  return "unspecified";
+}

package/src/workflow/useWorkflowValidation.ts

@@ -0,0 +1,329 @@
+"use client";
+
+import { useMemo, useRef, useState, useEffect } from "react";
+import { parseDocument, type Document, type YAMLMap, type Pair, isMap, isSeq, isScalar } from "yaml";
+import type { Diagnostic } from "@codemirror/lint";
+import type { UseTaskKindRegistryReturn } from "./useTaskKindRegistry";
+import { TASK_NAME_PATTERN, TASK_NAME_PATTERN_ERROR } from "./canvas-constants";
+
+/** Return value of {@link useWorkflowValidation}. */
+export interface UseWorkflowValidationReturn {
+  /** CodeMirror-compatible diagnostics mapped to source positions. */
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+const DEBOUNCE_MS = 150;
+
+const VALID_TASK_KINDS = new Set([
+  "set_vars", "http_call", "grpc_call", "activity_call", "switch_case",
+  "for_each", "fork", "try_catch", "listen", "wait", "raise_error",
+  "run_workflow", "agent_call", "llm_call", "transform", "human_input",
+  "validate", "emit_event", "notification", "eval",
+]);
+
+/**
+ * Behavior hook that validates workflow YAML and produces CodeMirror diagnostics.
+ *
+ * The pipeline runs entirely client-side with 150ms debounce:
+ * 1. YAML syntax check (parse errors)
+ * 2. Structural validation (required fields: document, tasks)
+ * 3. Per-task kind validation (known kinds, required task fields)
+ * 4. Task config schema validation (against TaskKindRegistry JSON schemas)
+ * 5. Reference validation (flow.then targets, duplicate task names)
+ *
+ * Each diagnostic is source-mapped to exact character positions using the
+ * `yaml` library's CST range information.
+ *
+ * @param yaml - The current YAML content string.
+ * @param registry - The task kind registry for schema validation.
+ *
+ * @since T10 (YAML Editor with Graph Preview)
+ */
+export function useWorkflowValidation(
+  yaml: string,
+  registry: UseTaskKindRegistryReturn | null,
+): UseWorkflowValidationReturn {
+  const [diagnostics, setDiagnostics] = useState<readonly Diagnostic[]>([]);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const registryRef = useRef(registry);
+  registryRef.current = registry;
+
+  useEffect(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+
+    timerRef.current = setTimeout(() => {
+      const result = validateWorkflowYaml(yaml, registryRef.current);
+      setDiagnostics(result);
+    }, DEBOUNCE_MS);
+
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [yaml]);
+
+  return useMemo(() => ({ diagnostics }), [diagnostics]);
+}
+
+// ---------------------------------------------------------------------------
+// Core validation pipeline
+// ---------------------------------------------------------------------------
+
+function validateWorkflowYaml(
+  yaml: string,
+  registry: UseTaskKindRegistryReturn | null,
+): Diagnostic[] {
+  if (!yaml.trim()) return [];
+
+  const diags: Diagnostic[] = [];
+
+  let doc: Document;
+  try {
+    doc = parseDocument(yaml, { keepSourceTokens: true });
+  } catch {
+    diags.push({ from: 0, to: Math.min(yaml.length, 1), severity: "error", message: "Invalid YAML syntax" });
+    return diags;
+  }
+
+  for (const err of doc.errors) {
+    const [from, to] = err.pos ?? [0, 1];
+    diags.push({ from, to: Math.max(to, from + 1), severity: "error", message: err.message });
+  }
+  if (diags.length > 0) return diags;
+
+  const root = doc.contents;
+  if (!isMap(root)) {
+    diags.push({ from: 0, to: Math.min(yaml.length, 1), severity: "error", message: "Workflow YAML must be a mapping document" });
+    return diags;
+  }
+
+  validateStructure(root, diags, yaml);
+  validateTasks(root, diags, yaml, registry);
+
+  return diags;
+}
+
+// ---------------------------------------------------------------------------
+// Structural validation
+// ---------------------------------------------------------------------------
+
+function validateStructure(root: YAMLMap, diags: Diagnostic[], yaml: string): void {
+  const specNode = findMapValue(root, "spec");
+  if (!specNode || !isMap(specNode)) {
+    diags.push(diagAtKey(root, "spec", yaml, "error", "Missing required field: spec"));
+    return;
+  }
+
+  const docNode = findMapValue(specNode, "document");
+  if (!docNode || !isMap(docNode)) {
+    diags.push(diagAtKey(specNode, "document", yaml, "error", "Missing required field: spec.document"));
+  } else {
+    for (const field of ["namespace", "name", "version"] as const) {
+      const val = findScalarValue(docNode, field);
+      if (!val) {
+        diags.push(diagAtKey(docNode, field, yaml, "error", `Missing required field: spec.document.${field}`));
+      }
+    }
+  }
+
+  const tasksNode = findMapValue(specNode, "tasks");
+  if (!tasksNode || !isSeq(tasksNode) || tasksNode.items.length === 0) {
+    diags.push(diagAtKey(specNode, "tasks", yaml, "error", "Missing required field: spec.tasks (must be a non-empty list)"));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Task-level validation
+// ---------------------------------------------------------------------------
+
+function validateTasks(
+  root: YAMLMap,
+  diags: Diagnostic[],
+  yaml: string,
+  registry: UseTaskKindRegistryReturn | null,
+): void {
+  const specNode = findMapValue(root, "spec");
+  if (!specNode || !isMap(specNode)) return;
+
+  const tasksNode = findMapValue(specNode, "tasks");
+  if (!tasksNode || !isSeq(tasksNode)) return;
+
+  const taskNames = new Set<string>();
+  const allTaskNames: string[] = [];
+
+  for (const item of tasksNode.items) {
+    if (!isMap(item)) continue;
+
+    const nameNode = findPair(item, "name");
+    const nameVal = findScalarValue(item, "name");
+    const kindVal = findScalarValue(item, "kind");
+
+    if (!nameVal) {
+      const range = rangeOf(item, yaml);
+      diags.push({ from: range[0], to: range[1], severity: "error", message: "Task is missing required field: name" });
+      continue;
+    }
+
+    if (!TASK_NAME_PATTERN.test(nameVal)) {
+      const range = nameNode ? rangeOfPair(nameNode, yaml) : rangeOf(item, yaml);
+      diags.push({ from: range[0], to: range[1], severity: "error", message: `Task name "${nameVal}": ${TASK_NAME_PATTERN_ERROR}` });
+    }
+
+    if (taskNames.has(nameVal)) {
+      const range = nameNode ? rangeOfPair(nameNode, yaml) : rangeOf(item, yaml);
+      diags.push({ from: range[0], to: range[1], severity: "warning", message: `Duplicate task name: "${nameVal}"` });
+    }
+    taskNames.add(nameVal);
+    allTaskNames.push(nameVal);
+
+    if (!kindVal) {
+      const range = rangeOf(item, yaml);
+      diags.push({ from: range[0], to: range[1], severity: "error", message: `Task "${nameVal}" is missing required field: kind` });
+      continue;
+    }
+
+    if (!VALID_TASK_KINDS.has(kindVal)) {
+      const kindPair = findPair(item, "kind");
+      const range = kindPair ? rangeOfPair(kindPair, yaml) : rangeOf(item, yaml);
+      diags.push({ from: range[0], to: range[1], severity: "error", message: `Task "${nameVal}" has unknown kind: "${kindVal}"` });
+      continue;
+    }
+
+    const configNode = findMapValue(item, "task_config") ?? findMapValue(item, "taskConfig");
+    if (!configNode || !isMap(configNode)) {
+      const range = rangeOf(item, yaml);
+      diags.push({ from: range[0], to: range[1], severity: "error", message: `Task "${nameVal}" is missing required field: task_config` });
+    } else if (kindVal === "eval") {
+      validateEvalConfig(configNode, nameVal, diags, yaml);
+    }
+
+    validateFlowReferences(item, nameVal, allTaskNames, taskNames, diags, yaml);
+  }
+
+  // Second pass: validate all flow.then references point to existing tasks
+  for (const item of tasksNode.items) {
+    if (!isMap(item)) continue;
+    const nameVal = findScalarValue(item, "name");
+    if (!nameVal) continue;
+    validateFlowReferencesSecondPass(item, nameVal, taskNames, diags, yaml);
+  }
+}
+
+function validateFlowReferences(
+  _taskNode: YAMLMap,
+  _taskName: string,
+  _allNames: string[],
+  _nameSet: Set<string>,
+  _diags: Diagnostic[],
+  _yaml: string,
+): void {
+  // Placeholder — forward references are validated in the second pass
+}
+
+function validateFlowReferencesSecondPass(
+  taskNode: YAMLMap,
+  taskName: string,
+  taskNames: Set<string>,
+  diags: Diagnostic[],
+  yaml: string,
+): void {
+  const flowNode = findMapValue(taskNode, "flow");
+  if (!flowNode || !isMap(flowNode)) return;
+
+  const thenVal = findScalarValue(flowNode, "then");
+  if (!thenVal || thenVal === "end") return;
+
+  if (!taskNames.has(thenVal)) {
+    const thenPair = findPair(flowNode, "then");
+    const range = thenPair ? rangeOfPair(thenPair, yaml) : rangeOf(flowNode, yaml);
+    diags.push({
+      from: range[0],
+      to: range[1],
+      severity: "warning",
+      message: `Task "${taskName}" flow.then references unknown task "${thenVal}"`,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Kind-specific config validation
+// ---------------------------------------------------------------------------
+
+function validateEvalConfig(
+  configNode: YAMLMap,
+  taskName: string,
+  diags: Diagnostic[],
+  yaml: string,
+): void {
+  for (const field of ["model", "subject", "rubric"] as const) {
+    const val = findScalarValue(configNode, field);
+    if (!val) {
+      diags.push(
+        diagAtKey(configNode, field, yaml, "error", `Eval task "${taskName}" is missing required field: ${field}`),
+      );
+    }
+  }
+
+  const thresholdNode = findMapValue(configNode, "threshold");
+  if (thresholdNode && isScalar(thresholdNode)) {
+    const num = Number(thresholdNode.value);
+    if (!Number.isFinite(num) || num < 0 || num > 1) {
+      const pair = findPair(configNode, "threshold");
+      const range = pair ? rangeOfPair(pair, yaml) : rangeOf(configNode, yaml);
+      diags.push({ from: range[0], to: range[1], severity: "error", message: `Eval task "${taskName}": threshold must be between 0.0 and 1.0` });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// YAML node helpers
+// ---------------------------------------------------------------------------
+
+function findPair(map: YAMLMap, key: string): Pair | undefined {
+  for (const item of map.items) {
+    if (isScalar(item.key) && item.key.value === key) {
+      return item;
+    }
+  }
+  return undefined;
+}
+
+function findMapValue(map: YAMLMap, key: string): unknown {
+  const pair = findPair(map, key);
+  return pair?.value ?? undefined;
+}
+
+function findScalarValue(map: YAMLMap, key: string): string | undefined {
+  const val = findMapValue(map, key);
+  if (isScalar(val) && typeof val.value === "string") return val.value;
+  return undefined;
+}
+
+function rangeOf(node: unknown, yaml: string): [number, number] {
+  if (node && typeof node === "object" && "range" in node) {
+    const r = (node as { range?: [number, number, number] }).range;
+    if (r) return [r[0], Math.min(r[1], yaml.length)];
+  }
+  return [0, Math.min(yaml.length, 1)];
+}
+
+function rangeOfPair(pair: Pair, yaml: string): [number, number] {
+  const keyRange = rangeOf(pair.key, yaml);
+  const valRange = rangeOf(pair.value, yaml);
+  return [keyRange[0], Math.max(valRange[1], keyRange[1])];
+}
+
+function diagAtKey(
+  map: YAMLMap,
+  key: string,
+  yaml: string,
+  severity: Diagnostic["severity"],
+  message: string,
+): Diagnostic {
+  const pair = findPair(map, key);
+  if (pair) {
+    const range = rangeOfPair(pair, yaml);
+    return { from: range[0], to: range[1], severity, message };
+  }
+  const range = rangeOf(map, yaml);
+  return { from: range[0], to: Math.min(range[0] + 1, yaml.length), severity, message };
+}

package/src/workflow/useWorkflowYaml.ts

@@ -0,0 +1,49 @@
+"use client";
+
+import { useMemo } from "react";
+import { useWorkflow } from "./useWorkflow";
+import { serializeWorkflowYaml } from "./serialize-workflow-yaml";
+
+/** Return value of {@link useWorkflowYaml}. */
+export interface UseWorkflowYamlReturn {
+  /** The workflow resource serialized as canonical YAML, or `null` while loading. */
+  readonly yaml: string | null;
+  /** `true` while the workflow is being fetched. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** The resource ID (needed for the save/update path). */
+  readonly workflowId: string | null;
+  /** Discard cached data and re-fetch the workflow from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a Workflow and returns its YAML representation.
+ *
+ * Composes {@link useWorkflow} with {@link serializeWorkflowYaml} to
+ * provide a memoized YAML string ready for editor rendering.
+ *
+ * @param org - Organization slug, or `null` to skip fetching.
+ * @param slug - Workflow slug, or `null` to skip fetching.
+ *
+ * @since T10 (YAML Editor with Graph Preview)
+ */
+export function useWorkflowYaml(
+  org: string | null,
+  slug: string | null,
+): UseWorkflowYamlReturn {
+  const { workflow, isLoading, error, refetch } = useWorkflow(org, slug);
+
+  const yaml = useMemo<string | null>(() => {
+    if (!workflow) return null;
+    return serializeWorkflowYaml(workflow);
+  }, [workflow]);
+
+  const workflowId = workflow?.metadata?.id ?? null;
+
+  return useMemo(
+    () => ({ yaml, isLoading, error, workflowId, refetch }),
+    [yaml, isLoading, error, workflowId, refetch],
+  );
+}