@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/deployment/targets/openapi-parts.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The pieces an export target's OpenAPI document is made of: a port's
+ * schema, the POST operation that runs a workflow or a node type, and the
+ * endpoints every generated service has. `BaseExportTarget` composes them
+ * into the node-type, multi-workflow and bundle documents.
+ */
+/** A port as the export targets describe it. */
+export interface OpenApiPort {
+    dataType?: string;
+    label?: string;
+    tsType?: string;
+    optional?: boolean;
+}
+/** The POST operation that runs a node type, its request and result built from its ports. */
+export declare function nodeTypeOperation(nodeType: {
+    name: string;
+    functionName: string;
+    description?: string;
+    inputs: Record<string, OpenApiPort>;
+    outputs: Record<string, OpenApiPort>;
+}, operationId: string): object;
+/** The POST operation that runs a workflow; its parameters are the workflow's own. */
+export declare function workflowOperation(workflow: {
+    name: string;
+    functionName: string;
+    description?: string;
+}, operationId: string, parametersDescription: string): object;
+/** `GET /api/functions`: the registered functions a workflow parameter can name. */
+export declare function functionsEndpoint(): object;
+/** `GET /api/openapi.json`: the document itself. */
+export declare function specEndpoint(): object;
+/** A function parameter: a registry ID, or one with arguments bound in advance. */
+export declare const FUNCTION_REFERENCE_SCHEMA: {
+    oneOf: ({
+        type: string;
+        description: string;
+        properties?: undefined;
+        required?: undefined;
+    } | {
+        type: string;
+        properties: {
+            registryId: {
+                type: string;
+                description: string;
+            };
+            partialArgs: {
+                type: string;
+                description: string;
+                additionalProperties: boolean;
+            };
+        };
+        required: string[];
+        description?: undefined;
+    })[];
+    description: string;
+};
+/** The tags the generated documents use, by name. */
+export declare const TAGS: {
+    readonly workflows: {
+        readonly name: "workflows";
+        readonly description: "Workflow execution endpoints";
+    };
+    readonly nodeTypes: {
+        readonly name: "node-types";
+        readonly description: "Node type execution endpoints";
+    };
+    readonly functions: {
+        readonly name: "functions";
+        readonly description: "Function registry endpoints";
+    };
+    readonly documentation: {
+        readonly name: "documentation";
+        readonly description: "API documentation";
+    };
+};
+/**
+ * The document around the paths. It is a deep copy, so the constants above
+ * are never shared with a caller that edits what it is given.
+ */
+export declare function openApiDocument(opts: {
+    title: string;
+    version: string;
+    baseUrl?: string;
+    description: string;
+    paths: Record<string, object>;
+    tags: ReadonlyArray<{
+        name: string;
+        description: string;
+    }>;
+    components?: object;
+}): object;
+//# sourceMappingURL=openapi-parts.d.ts.map

package/dist/diagram/arms.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Keeping a branch arm next to the gate it leaves.
+ *
+ * Rows reach `buildLanes` in flattened source order, and only a loop body is
+ * pulled inline after its owner. A failure arm stays wherever it was
+ * declared, so `router:fail -> fallback` lands four rows below `router` with
+ * the happy path in between and the fail line drawn straight through steps
+ * that have nothing to do with it. On the weaver-bot topology that is two
+ * fail lines and a return line in flight at once, none of them grouped.
+ *
+ * This reorders the rows so an arm's own chain follows its gate, and reports
+ * the span each arm occupies so the renderer can band it the way it bands a
+ * scope body.
+ *
+ * A pure pass over the flat row list, run before lanes are assigned, so the
+ * lane and merge logic underneath is untouched.
+ */
+/** What the ordering needs to know about a step. The process model has all of it. */
+export interface ArmStep {
+    id: string;
+    /** Which of its owner's scopes this step sits in, when the owner has several. */
+    inScope?: string | null;
+    children: ArmStep[];
+    successTo: string[];
+    failureTo: string[];
+    reads: Array<{
+        from: string;
+    }>;
+    produces: Array<{
+        to: string[];
+    }>;
+    entered: Array<{
+        from: string;
+        arm: 'ok' | 'fail';
+    }>;
+    pull?: boolean;
+}
+/** A row before lanes are assigned. */
+export interface FlatRow<S extends ArmStep = ArmStep> {
+    id: string;
+    step: S | null;
+    depth: number;
+    owner: string | null;
+}
+/**
+ * The rows one gate's failure arm owns, for the band behind them.
+ *
+ * Only the failure arm is recorded: the success arm is the trunk carrying on,
+ * which needs no band of its own.
+ */
+export interface ArmSpan {
+    /** The gate the arm leaves. */
+    gate: string;
+    /** Row ids, in order. A failure that fans out contributes each strand. */
+    ids: string[];
+}
+/**
+ * Reorder `flat` so each gate's failure arm sits directly beneath it.
+ *
+ * Gates are taken in row order, so an outer gate is served before the gates
+ * nested inside its arm and the two never fight over a row.
+ */
+export declare function orderArms<S extends ArmStep>(flat: Array<FlatRow<S>>, exitFrom?: Array<{
+    from: string;
+    arm: 'ok' | 'fail';
+}>): {
+    flat: Array<FlatRow<S>>;
+    arms: ArmSpan[];
+};
+//# sourceMappingURL=arms.d.ts.map

package/dist/diagram/ascii-renderer.d.ts

@@ -6,7 +6,7 @@
  * - renderASCIICompact: single-row compact node boxes
  * - renderText: structured text listing (most LLM-parseable)
  */
-import type { DiagramGraph } from './types.js';
+import type { DiagramGraph } from './types';
 export declare function renderASCII(graph: DiagramGraph): string;
 export declare function renderASCIICompact(graph: DiagramGraph): string;
 export declare function renderText(graph: DiagramGraph): string;

package/dist/diagram/geometry.d.ts

@@ -1,31 +1,24 @@
-import type { TWorkflowAST } from '../ast/types.js';
-import type { DiagramNode, DiagramPort, DiagramGraph, DiagramOptions } from './types.js';
-export declare const PORT_RADIUS = 7;
-export declare const PORT_SIZE: number;
-export declare const PORT_GAP = 8;
-export declare const PORT_PADDING_Y = 18;
-export declare const NODE_MIN_WIDTH = 90;
-export declare const NODE_MIN_HEIGHT = 90;
-export declare const BORDER_RADIUS = 6;
-export declare const LAYER_GAP_X = 300;
-export declare const LABEL_CLEARANCE = 42;
-export declare const MIN_EDGE_GAP = 112;
-export declare const NODE_GAP_Y = 60;
-export declare const LABEL_HEIGHT = 20;
-export declare const LABEL_GAP = 12;
-export declare const SCOPE_PADDING_X = 140;
-export declare const SCOPE_PADDING_Y = 40;
-export declare const SCOPE_PORT_COLUMN = 50;
-export declare const SCOPE_INNER_GAP_X = 240;
-export declare const ORTHOGONAL_DISTANCE_THRESHOLD = 300;
-export declare const STUB_DISTANCE_THRESHOLD = 500;
-export declare const STUB_LENGTH = 30;
-/** Measure text width using pre-computed Montserrat 600/10px SVG character widths */
-export declare function measureText(text: string): number;
-/** Compute the full badge width for a port label (matches renderer badge layout) */
-export declare function portBadgeWidth(port: DiagramPort): number;
-export declare function computeNodeDimensions(node: DiagramNode): void;
-export declare function computePortPositions(node: DiagramNode): void;
-export declare function computeConnectionPath(sx: number, sy: number, tx: number, ty: number): string;
+/**
+ * The laid-out diagram graph behind the ASCII and text renderers and
+ * `fw describe`: every node box, port dot and connection path of a workflow
+ * with its coordinates.
+ *
+ * buildDiagramGraph decides the order of the steps. Each step lives in
+ * src/diagram/graph/:
+ *
+ * - nodes: the Start, Exit and instance boxes, their ports and base size
+ * - scopes: scope children, inner ports, the grown parent box, scope wiring
+ * - placement: x and y of each top-level box from the layout's layers
+ * - bounds: shifting into a padded frame and the final bounds
+ * - routing: which connections are drawn, their stubs and their paths
+ * - ports / metrics: port order and positions; sizes and text widths
+ */
+import type { TWorkflowAST } from '../ast/types';
+import type { DiagramGraph, DiagramOptions } from './types';
+export { PORT_RADIUS, PORT_SIZE, PORT_GAP, PORT_PADDING_Y, NODE_MIN_WIDTH, NODE_MIN_HEIGHT, LABEL_HEIGHT, LABEL_GAP, measureText, portBadgeWidth, } from './graph/metrics';
+export { SCOPE_PADDING_X, SCOPE_PADDING_Y, SCOPE_PORT_COLUMN, SCOPE_INNER_GAP_X } from './graph/scopes';
+export { STUB_DISTANCE_THRESHOLD, computeConnectionPath } from './graph/routing';
+export { computeNodeDimensions } from './graph/nodes';
+export { computePortPositions } from './graph/ports';
 export declare function buildDiagramGraph(ast: TWorkflowAST, options?: DiagramOptions): DiagramGraph;
 //# sourceMappingURL=geometry.d.ts.map

package/dist/diagram/graph/bounds.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The graph's coordinate frame and its bounds.
+ *
+ * Decides where the drawing starts and how big it is: once the boxes are
+ * placed, every coordinate is shifted so the node boxes, their labels and
+ * their port label badges sit a fixed padding inside the top-left corner, and
+ * after routing the bounds grow to cover any connection path that leaves
+ * that area, moving the origin when a path runs above or left of it.
+ */
+import type { DiagramConnection, DiagramGraph, DiagramNode } from '../types';
+/** Extent of the node boxes, labels and port badges before normalization. */
+export interface NodeExtent {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/**
+ * Measure the extent of the nodes (include scope children and port labels),
+ * then shift every node, scope child and port so the extent starts at
+ * (PADDING, PADDING). Returns the extent measured before the shift.
+ */
+export declare function normalizeNodes(nodes: DiagramNode[]): NodeExtent;
+/**
+ * The graph's bounds: the normalized node extent plus padding, extended to
+ * include every connection path (top-level and inside scopes), since routes
+ * can go outside the node area.
+ */
+export declare function graphBounds(extent: NodeExtent, connections: DiagramConnection[], nodes: DiagramNode[]): DiagramGraph['bounds'];
+//# sourceMappingURL=bounds.d.ts.map

package/dist/diagram/graph/metrics.d.ts

@@ -0,0 +1,21 @@
+import type { DiagramPort } from '../types';
+export declare const PORT_RADIUS = 7;
+export declare const PORT_SIZE: number;
+export declare const PORT_GAP = 8;
+export declare const PORT_PADDING_Y = 18;
+export declare const NODE_MIN_WIDTH = 90;
+export declare const NODE_MIN_HEIGHT = 90;
+export declare const LABEL_CLEARANCE = 42;
+export declare const LABEL_HEIGHT = 24;
+export declare const LABEL_GAP = 12;
+/** Measure text width using pre-computed Montserrat 600/10px SVG character widths */
+export declare function measureText(text: string): number;
+/** Compute the full badge width for a port label (matches renderer badge layout) */
+export declare function portBadgeWidth(port: DiagramPort): number;
+/** Total extent of a port label from the port dot center outward (badge + gap + dot radius) */
+export declare function portLabelExtent(port: DiagramPort): number;
+/** Estimate the maximum port label badge extent beyond the node edge */
+export declare function maxPortLabelExtent(ports: readonly DiagramPort[]): number;
+/** Height of a column of `count` ports, padding included (0 for no ports). */
+export declare function portsColumnHeight(count: number): number;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/diagram/graph/nodes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What box each node is before it is placed.
+ *
+ * Decides a node's ports, label, colour, icon and base size: the Start and
+ * Exit boxes with their mandatory step ports, instance boxes from their node
+ * type (with synthesized step ports, which a pull-style expression node does
+ * not get), and the explicit `[size: W H]` override that wins over any
+ * computed size.
+ */
+import type { TNodeTypeAST, TWorkflowAST } from '../../ast/types';
+import type { DiagramNode } from '../types';
+/** Node types by name, and also by function name where that differs. */
+export declare function buildNodeTypeMap(ast: TWorkflowAST): Map<string, TNodeTypeAST>;
+/** Size a node box to fit its taller port column, never below the minimum. */
+export declare function computeNodeDimensions(node: DiagramNode): void;
+/** The Start box: the workflow's start ports, with a mandatory execute STEP port. */
+export declare function buildStartNode(ast: TWorkflowAST): DiagramNode;
+/** The Exit box: the workflow's exit ports, with mandatory onSuccess/onFailure STEP ports. */
+export declare function buildExitNode(ast: TWorkflowAST): DiagramNode;
+/**
+ * Which STEP ports (execute/onSuccess/onFailure) each instance actually wires.
+ * Used to hide the synthesized step ports on pull-style expression nodes.
+ */
+export declare function collectWiredStepPorts(ast: TWorkflowAST): Map<string, Set<string>>;
+/** Build an instance box (shared by the main graph and scope sub-graphs). */
+export declare function buildInstanceNode(instId: string, instNodeType: string, instConfig: {
+    label?: string;
+    color?: string;
+    icon?: string;
+} | undefined, nodeTypeMap: Map<string, TNodeTypeAST>, theme?: 'dark' | 'light', connectedStepPorts?: Set<string>): DiagramNode;
+/** Apply explicit [size: W H] annotations to top-level boxes: a hard override, not a floor. */
+export declare function applySizeOverrides(ast: TWorkflowAST, diagramNodes: Map<string, DiagramNode>, scopedChildren: Set<string>): void;
+//# sourceMappingURL=nodes.d.ts.map

package/dist/diagram/graph/placement.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Where each top-level node box sits.
+ *
+ * Decides x and y from the layers `layoutWorkflow` assigns: layers run left
+ * to right, the boxes in a layer stack centred on y = 0, the gap between two
+ * layers widens so opposing port labels never touch, and a node that lands
+ * inside a widened scope box is pushed right, along with everything after it.
+ */
+import type { DiagramNode } from '../types';
+/**
+ * Assign coordinates to nodes using auto-layout layer assignments.
+ * Gap between layers adapts to port label extents so labels never overlap,
+ * while using LAYER_GAP_X as the target center-to-center distance.
+ */
+export declare function assignLayerCoordinates(layers: string[][], diagramNodes: Map<string, DiagramNode>): void;
+/**
+ * After layout, resolve overlaps caused by expanded scope boxes. Only checks
+ * nodes immediately after a scope parent. When a node falls inside the
+ * expanded scope box, shift it and all further-right nodes to clear.
+ */
+export declare function resolvePostLayoutOverlaps(diagramNodes: Map<string, DiagramNode>): void;
+//# sourceMappingURL=placement.d.ts.map

package/dist/diagram/graph/ports.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Which ports a node shows, in what order, and where their dots sit.
+ *
+ * Decides the port list drawn on a node edge from a set of port definitions:
+ * hidden ports and ports that belong to a scope are left off, the rest are
+ * ordered by their metadata order (execute, onSuccess and onFailure first),
+ * and each dot is placed down the edge at a fixed pitch.
+ */
+import type { TPortDefinition } from '../../ast/types';
+import type { DiagramNode, DiagramPort } from '../types';
+/**
+ * Get ordered ports from a port definition record using metadata.order.
+ * Uses assignImplicitPortOrders to ensure all ports have proper ordering
+ * (mandatory ports like execute/onSuccess/onFailure get precedence).
+ */
+export declare function orderedPorts(ports: Record<string, TPortDefinition>, direction: 'INPUT' | 'OUTPUT'): DiagramPort[];
+export declare function filterHiddenPorts(ports: Record<string, TPortDefinition>): Record<string, TPortDefinition>;
+export declare function filterNonScopedPorts(ports: Record<string, TPortDefinition>): Record<string, TPortDefinition>;
+/** Place a node's input dots on its left edge and output dots on its right edge. */
+export declare function computePortPositions(node: DiagramNode): void;
+/** Place a column of port dots at x = `cx`, top-aligned to `nodeY`. */
+export declare function positionPortList(ports: DiagramPort[], cx: number, nodeY: number): void;
+//# sourceMappingURL=ports.d.ts.map

package/dist/diagram/graph/routing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Which connections are drawn and the path each one takes.
+ *
+ * Decides the top-level connection list (connections that stay inside a
+ * scope are left to the scope), the order connections are routed in (short
+ * spans first, so track allocation is deterministic), the stubs drawn past
+ * each port label, which connections are too long to draw in full, and the
+ * orthogonal route around the node boxes, falling back to a straight line
+ * when no route is found. Top-level and scope connections share one track
+ * allocator so their routes do not overlap.
+ */
+import type { TWorkflowAST } from '../../ast/types';
+import type { DiagramConnection, DiagramNode, DiagramPort } from '../types';
+export declare const STUB_DISTANCE_THRESHOLD = 500;
+/** Straight-line fallback when orthogonal routing fails (matches platform behaviour). */
+export declare function computeConnectionPath(sx: number, sy: number, tx: number, ty: number): string;
+/** A top-level connection with its resolved ports, waiting to be routed. */
+export interface PendingConnection {
+    fromNodeId: string;
+    fromPortName: string;
+    toNodeId: string;
+    toPortName: string;
+    sourcePort: DiagramPort;
+    targetPort: DiagramPort;
+    fromPortIndex: number;
+    toPortIndex: number;
+}
+/**
+ * Resolve the top-level connections to their ports. Scope-qualified
+ * connections and connections that stay inside one scope (child to child,
+ * child to its parent, parent to its child) are skipped: the scope draws
+ * those. A connection that crosses a scope boundary finds its scope child.
+ */
+export declare function collectExternalConnections(ast: TWorkflowAST, diagramNodes: Map<string, DiagramNode>, scopedChildren: Set<string>): PendingConnection[];
+/**
+ * Route the top-level connections, then recompute every scope connection's
+ * path with the same router. Call after the coordinates are normalized.
+ */
+export declare function routeConnections(pendingConnections: PendingConnection[], nodes: DiagramNode[], theme: 'dark' | 'light'): DiagramConnection[];
+//# sourceMappingURL=routing.d.ts.map

package/dist/diagram/graph/scopes.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How a scoped node draws its scope inside its own box.
+ *
+ * Decides which instances are scope children (from `ast.scopes` and from
+ * scope-qualified connections), which of the parent's ports move to the
+ * scope's inner edges, how big the parent box grows to hold its children,
+ * where the children and inner ports sit once the parent is placed, and the
+ * connections drawn inside the scope, including the implicit start, success
+ * and failure wiring when none is written.
+ */
+import type { TNodeTypeAST, TWorkflowAST } from '../../ast/types';
+import type { DiagramNode } from '../types';
+export declare const SCOPE_PADDING_X = 140;
+export declare const SCOPE_PADDING_Y = 40;
+export declare const SCOPE_PORT_COLUMN = 45;
+export declare const SCOPE_INNER_GAP_X = 240;
+/**
+ * Every scope, keyed `parentId.scopeName`, and the set of all scope children.
+ * Explicit `ast.scopes` come first; scopes implied by per-port scope
+ * qualifiers on connections (`:scopeName`) are added when not already listed.
+ */
+export declare function collectScopes(ast: TWorkflowAST): {
+    allScopes: Record<string, string[]>;
+    scopedChildren: Set<string>;
+};
+/** Build every scope's sub-graph into its parent box, growing the parent to fit. */
+export declare function buildScopeSubGraphs(ast: TWorkflowAST, diagramNodes: Map<string, DiagramNode>, allScopes: Record<string, string[]>, nodeTypeMap: Map<string, TNodeTypeAST>, theme: 'dark' | 'light'): void;
+/** Position scope children and ports relative to the parent's final position */
+export declare function finalizeScopePositions(parentNode: DiagramNode, ast: TWorkflowAST, theme?: 'dark' | 'light'): void;
+//# sourceMappingURL=scopes.d.ts.map

package/dist/diagram/index.d.ts

@@ -1,31 +1,23 @@
-import type { TWorkflowAST } from '../ast/types.js';
-import type { DiagramOptions } from './types.js';
-export type { DiagramOptions } from './types.js';
-export { renderASCII, renderASCIICompact, renderText } from './ascii-renderer.js';
+import type { TWorkflowAST } from '../ast/types';
+import type { DiagramOptions } from './types';
+export type { DiagramOptions } from './types';
+export { renderASCII, renderASCIICompact, renderText } from './ascii-renderer';
+export { buildProcessModel } from './process-view';
+export type { ProcessModel, ProcessStep, ProcessKind } from './process-view';
+export { renderSpineSVG } from './spine';
+export type { SpineOptions } from './spine';
+export { buildLanes, edgePath } from './lanes';
+export type { LaneGraph, LaneRow, LaneEdge, LaneStep, LaneModel, EdgeKind } from './lanes';
+export { stepLabel } from './labels';
 /**
- * Render a workflow AST to an SVG string.
+ * Render a workflow AST as an SVG: the spine the console draws -- steps in
+ * run order with the control flow as lanes beside them -- made still.
  */
 export declare function workflowToSVG(ast: TWorkflowAST, options?: DiagramOptions): string;
-/**
- * Parse TypeScript source code and render the first (or named) workflow to SVG.
- */
+/** Parse TypeScript source and render the first (or named) workflow as an SVG. */
 export declare function sourceToSVG(code: string, options?: DiagramOptions): string;
-/**
- * Parse a workflow file (resolves imports) and render the first (or named) workflow to SVG.
- */
+/** Parse a workflow file (resolving imports) and render the first (or named) workflow as an SVG. */
 export declare function fileToSVG(filePath: string, options?: DiagramOptions): string;
-/**
- * Render a workflow AST to a self-contained interactive HTML page.
- */
-export declare function workflowToHTML(ast: TWorkflowAST, options?: DiagramOptions): string;
-/**
- * Parse TypeScript source code and render the first (or named) workflow to interactive HTML.
- */
-export declare function sourceToHTML(code: string, options?: DiagramOptions): string;
-/**
- * Parse a workflow file and render the first (or named) workflow to interactive HTML.
- */
-export declare function fileToHTML(filePath: string, options?: DiagramOptions): string;
 export declare function workflowToASCII(ast: TWorkflowAST, options?: DiagramOptions): string;
 export declare function sourceToASCII(code: string, options?: DiagramOptions): string;
 export declare function fileToASCII(filePath: string, options?: DiagramOptions): string;