@synergenius/flow-weaver 0.2.0

package/dist/types/branded-ports.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Branded Port Types
+ *
+ * Provides compile-time type safety for port handling using TypeScript's
+ * branded types pattern. Prevents accidental mixing of port categories.
+ *
+ * Categories:
+ * - MandatoryPort: Reserved ports (execute, onSuccess, onFailure, start, success, failure)
+ * - ScopedPort: Ports belonging to a scope (forEach, map, etc.)
+ * - RegularPort: All other ports
+ */
+import type { TPortDefinition } from '../ast/types.js';
+/**
+ * Reserved port name constants.
+ * Use these instead of magic strings.
+ */
+export declare const PortName: {
+    readonly EXECUTE: "execute";
+    readonly ON_SUCCESS: "onSuccess";
+    readonly ON_FAILURE: "onFailure";
+    readonly START: "start";
+    readonly SUCCESS: "success";
+    readonly FAILURE: "failure";
+};
+export type PortNameType = (typeof PortName)[keyof typeof PortName];
+/**
+ * External mandatory port names.
+ */
+export declare const EXTERNAL_MANDATORY_PORTS: readonly ["execute", "onSuccess", "onFailure"];
+/**
+ * Scoped mandatory port names.
+ */
+export declare const SCOPED_MANDATORY_PORTS: readonly ["start", "success", "failure"];
+/**
+ * Brand symbol for MandatoryPort.
+ */
+declare const MandatoryPortBrand: unique symbol;
+/**
+ * Brand symbol for ScopedPort.
+ */
+declare const ScopedPortBrand: unique symbol;
+/**
+ * Brand symbol for RegularPort.
+ */
+declare const RegularPortBrand: unique symbol;
+/**
+ * A mandatory port (execute, onSuccess, onFailure, or scoped equivalents).
+ * Cannot be assigned from RegularPort.
+ */
+export type MandatoryPort = TPortDefinition & {
+    readonly [MandatoryPortBrand]: never;
+};
+/**
+ * A scoped port (has a scope property).
+ * Enforces that scope is defined.
+ */
+export type ScopedPort = TPortDefinition & {
+    readonly scope: string;
+    readonly [ScopedPortBrand]: never;
+};
+/**
+ * A regular port (not mandatory, not scoped).
+ */
+export type RegularPort = TPortDefinition & {
+    readonly [RegularPortBrand]: never;
+};
+/**
+ * Union of all branded port types.
+ */
+export type BrandedPort = MandatoryPort | ScopedPort | RegularPort;
+/**
+ * Named port with brand information.
+ */
+export interface NamedMandatoryPort {
+    name: string;
+    port: MandatoryPort;
+}
+/**
+ * Named scoped port.
+ */
+export interface NamedScopedPort {
+    name: string;
+    port: ScopedPort;
+    scope: string;
+}
+/**
+ * Named regular port.
+ */
+export interface NamedRegularPort {
+    name: string;
+    port: RegularPort;
+}
+/**
+ * Type guard to check if a port is mandatory.
+ * Works for both external (execute, onSuccess, onFailure) and scoped (start, success, failure).
+ */
+export declare function isMandatoryPort(name: string, port: TPortDefinition): port is MandatoryPort;
+/**
+ * Type guard to check if a port is scoped.
+ */
+export declare function isScopedPort(port: TPortDefinition | undefined): port is ScopedPort;
+/**
+ * Type guard to check if a port is regular (not mandatory).
+ */
+export declare function isRegularPort(name: string, port: TPortDefinition): port is RegularPort;
+/**
+ * Assert that a port is mandatory and return typed version.
+ * @throws Error if port is not mandatory
+ */
+export declare function toMandatoryPort(name: string, port: TPortDefinition): NamedMandatoryPort;
+/**
+ * Assert that a port is scoped and return typed version.
+ * @throws Error if port is not scoped
+ */
+export declare function toScopedPort(port: TPortDefinition): ScopedPort;
+/**
+ * Entry in an ordered port list.
+ */
+export interface OrderedPortEntry<T extends TPortDefinition = TPortDefinition> {
+    name: string;
+    port: T;
+    order: number;
+}
+/**
+ * Array of ports with ordering information.
+ */
+export type OrderedPorts<T extends TPortDefinition = TPortDefinition> = OrderedPortEntry<T>[];
+/**
+ * Get the order value from a port's metadata.
+ * Returns Infinity if no order is set.
+ */
+export declare function getPortOrder(port: TPortDefinition): number;
+/**
+ * Create an ordered port list from a port record.
+ * Sorts by metadata.order, with unordered ports at the end.
+ */
+export declare function createOrderedPorts<T extends TPortDefinition>(ports: Record<string, T>): OrderedPorts<T>;
+/**
+ * Extract mandatory ports from a port record.
+ */
+export type ExtractMandatoryPorts<T extends Record<string, TPortDefinition>> = {
+    [K in keyof T as K extends 'execute' | 'onSuccess' | 'onFailure' | 'start' | 'success' | 'failure' ? K : never]: T[K];
+};
+/**
+ * Extract regular (non-mandatory) ports from a port record.
+ */
+export type ExtractRegularPorts<T extends Record<string, TPortDefinition>> = {
+    [K in keyof T as K extends 'execute' | 'onSuccess' | 'onFailure' | 'start' | 'success' | 'failure' ? never : K]: T[K];
+};
+export {};
+//# sourceMappingURL=branded-ports.d.ts.map

package/dist/types/branded-ports.js

@@ -0,0 +1,121 @@
+/**
+ * Branded Port Types
+ *
+ * Provides compile-time type safety for port handling using TypeScript's
+ * branded types pattern. Prevents accidental mixing of port categories.
+ *
+ * Categories:
+ * - MandatoryPort: Reserved ports (execute, onSuccess, onFailure, start, success, failure)
+ * - ScopedPort: Ports belonging to a scope (forEach, map, etc.)
+ * - RegularPort: All other ports
+ */
+// =============================================================================
+// Port Name Constants
+// =============================================================================
+/**
+ * Reserved port name constants.
+ * Use these instead of magic strings.
+ */
+export const PortName = {
+    // External mandatory ports
+    EXECUTE: 'execute',
+    ON_SUCCESS: 'onSuccess',
+    ON_FAILURE: 'onFailure',
+    // Scoped mandatory ports
+    START: 'start',
+    SUCCESS: 'success',
+    FAILURE: 'failure',
+};
+/**
+ * External mandatory port names.
+ */
+export const EXTERNAL_MANDATORY_PORTS = [
+    PortName.EXECUTE,
+    PortName.ON_SUCCESS,
+    PortName.ON_FAILURE,
+];
+/**
+ * Scoped mandatory port names.
+ */
+export const SCOPED_MANDATORY_PORTS = [
+    PortName.START,
+    PortName.SUCCESS,
+    PortName.FAILURE,
+];
+// =============================================================================
+// Type Guards
+// =============================================================================
+/**
+ * Type guard to check if a port is mandatory.
+ * Works for both external (execute, onSuccess, onFailure) and scoped (start, success, failure).
+ */
+export function isMandatoryPort(name, port) {
+    const isScoped = port.scope !== undefined;
+    if (isScoped) {
+        return SCOPED_MANDATORY_PORTS.includes(name);
+    }
+    return EXTERNAL_MANDATORY_PORTS.includes(name);
+}
+/**
+ * Type guard to check if a port is scoped.
+ */
+export function isScopedPort(port) {
+    return port !== undefined && typeof port.scope === 'string';
+}
+/**
+ * Type guard to check if a port is regular (not mandatory).
+ */
+export function isRegularPort(name, port) {
+    return !isMandatoryPort(name, port);
+}
+// =============================================================================
+// Assertion Functions
+// =============================================================================
+/**
+ * Assert that a port is mandatory and return typed version.
+ * @throws Error if port is not mandatory
+ */
+export function toMandatoryPort(name, port) {
+    if (!isMandatoryPort(name, port)) {
+        throw new Error(`"${name}" is not a mandatory port`);
+    }
+    return { name, port: port };
+}
+/**
+ * Assert that a port is scoped and return typed version.
+ * @throws Error if port is not scoped
+ */
+export function toScopedPort(port) {
+    if (!isScopedPort(port)) {
+        throw new Error(`Port is not a scoped port (no scope property)`);
+    }
+    return port;
+}
+/**
+ * Get the order value from a port's metadata.
+ * Returns Infinity if no order is set.
+ */
+export function getPortOrder(port) {
+    const order = port.metadata?.order;
+    return typeof order === 'number' ? order : Infinity;
+}
+/**
+ * Create an ordered port list from a port record.
+ * Sorts by metadata.order, with unordered ports at the end.
+ */
+export function createOrderedPorts(ports) {
+    const entries = Object.entries(ports).map(([name, port]) => ({
+        name,
+        port,
+        order: getPortOrder(port),
+    }));
+    // Sort by order (lower first), then by name for stable sort
+    entries.sort((a, b) => {
+        if (a.order !== b.order) {
+            return a.order - b.order;
+        }
+        return a.name.localeCompare(b.name);
+    });
+    return entries;
+}
+//# sourceMappingURL=branded-ports.js.map

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Type exports for flow-weaver
+ */
+export * from './branded-ports.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * Type exports for flow-weaver
+ */
+export * from './branded-ports.js';
+//# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -0,0 +1,139 @@
+import type { TDataType } from "./ast/types.js";
+/**
+ * Configuration for a single port on a node type.
+ * Defines the data type, display label, default value, and behavioral flags.
+ */
+export interface PortConfig {
+    type: TDataType;
+    label?: string;
+    defaultValue?: unknown;
+    expression?: string;
+    optional?: boolean;
+    hidden?: boolean;
+    failure?: boolean;
+}
+/**
+ * Determines how a node evaluates incoming execution signals before firing.
+ * - `"CONJUNCTION"` - All incoming signals must be present (AND logic).
+ * - `"DISJUNCTION"` - Any single incoming signal triggers execution (OR logic).
+ * - `"CUSTOM"` - Execution timing is controlled by custom logic.
+ */
+export type ExecutionSignalEvaluation = "CONJUNCTION" | "DISJUNCTION" | "CUSTOM";
+/**
+ * Default configuration embedded in a node type definition.
+ * Provides pull-execution settings, label, and description that apply
+ * unless overridden at the instance level.
+ */
+export interface ParsedTNodeTypeDefaultConfig {
+    pullExecution?: {
+        triggerPort: string;
+    };
+    label?: string;
+    description?: string;
+}
+/**
+ * A fully parsed node type definition extracted from source code.
+ * Contains the node's name, function reference, port definitions, execution
+ * semantics, and source location metadata.
+ */
+export interface ParsedNodeType {
+    name: string;
+    functionName: string;
+    inputs: Record<string, PortConfig>;
+    outputs: Record<string, PortConfig>;
+    functionText: string;
+    executeWhen: ExecutionSignalEvaluation;
+    defaultConfig?: ParsedTNodeTypeDefaultConfig;
+    scope?: string;
+    label?: string;
+    description?: string;
+    sourceLocation: {
+        file: string;
+        line: number;
+    };
+}
+/**
+ * Per-instance configuration for a node within a workflow.
+ * Overrides the node type's default config with instance-specific
+ * settings such as position, label, and execution behavior.
+ */
+export interface ParsedTNodeInstanceConfig {
+    pullExecution?: {
+        triggerPort: string;
+    };
+    label?: string;
+    description?: string;
+    executeWhen?: ExecutionSignalEvaluation;
+    x?: number;
+    y?: number;
+    color?: string;
+}
+/**
+ * A parsed node instance within a workflow definition.
+ * References a node type by name and carries optional per-instance configuration,
+ * scope membership, and visual state.
+ */
+export interface ParsedNodeInstance {
+    id: string;
+    type: string;
+    config?: ParsedTNodeInstanceConfig;
+    parentScope?: string;
+    minimized?: boolean;
+}
+/**
+ * A reference to a specific port on a specific node, used in connection definitions.
+ */
+export interface TPortReference {
+    node: string;
+    port: string;
+}
+/**
+ * A fully parsed workflow definition extracted from source code.
+ * Contains the workflow's node instances, connections, port definitions,
+ * optional layout/scope metadata, and source location.
+ */
+export interface ParsedWorkflowDefinition {
+    name: string;
+    functionName: string;
+    instances: ParsedNodeInstance[];
+    connections: Array<{
+        from: TPortReference;
+        to: TPortReference;
+    }>;
+    scopes?: Record<string, string[]>;
+    /**
+     * Optional layout information for visual editor integration.
+     * Maps node names to {x, y} coordinates.
+     * Not required for code-first workflows.
+     */
+    layout?: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    startPorts: Record<string, PortConfig>;
+    exitPorts: Record<string, PortConfig>;
+    description?: string;
+    sourceLocation: {
+        file: string;
+        line: number;
+    };
+}
+/**
+ * Top-level parse result for a single source file.
+ * Aggregates all node type definitions and workflow definitions found in the file.
+ */
+export interface ParsedWorkflow {
+    filePath: string;
+    nodeTypes: ParsedNodeType[];
+    workflows: ParsedWorkflowDefinition[];
+}
+/**
+ * Normalizes a port definition to a full {@link PortConfig} object.
+ * If the input is a string, it is treated as the data type name and wrapped
+ * in a minimal PortConfig. If already a PortConfig, it is returned as-is.
+ *
+ * @param portDef - A data type string or a full PortConfig object.
+ * @returns A normalized PortConfig.
+ */
+export declare function normalizePortConfig(portDef: string | PortConfig): PortConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,15 @@
+/**
+ * Normalizes a port definition to a full {@link PortConfig} object.
+ * If the input is a string, it is treated as the data type name and wrapped
+ * in a minimal PortConfig. If already a PortConfig, it is returned as-is.
+ *
+ * @param portDef - A data type string or a full PortConfig object.
+ * @returns A normalized PortConfig.
+ */
+export function normalizePortConfig(portDef) {
+    if (typeof portDef === "string") {
+        return { type: portDef };
+    }
+    return portDef;
+}
+//# sourceMappingURL=types.js.map

package/dist/utils/error-utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Utility functions for consistent error handling across the codebase.
+ * Replaces 60+ occurrences of: error instanceof Error ? error.message : String(error)
+ */
+/**
+ * Extracts a string message from any error value.
+ * Handles Error instances, strings, numbers, null, undefined, and objects.
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Wraps an error with additional context, preserving the original error as cause.
+ * Useful for adding context while propagating errors up the call stack.
+ */
+export declare function wrapError(error: unknown, context: string): Error;
+//# sourceMappingURL=error-utils.d.ts.map

package/dist/utils/error-utils.js

@@ -0,0 +1,27 @@
+/**
+ * Utility functions for consistent error handling across the codebase.
+ * Replaces 60+ occurrences of: error instanceof Error ? error.message : String(error)
+ */
+/**
+ * Extracts a string message from any error value.
+ * Handles Error instances, strings, numbers, null, undefined, and objects.
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+/**
+ * Wraps an error with additional context, preserving the original error as cause.
+ * Useful for adding context while propagating errors up the call stack.
+ */
+export function wrapError(error, context) {
+    const message = `${context}: ${getErrorMessage(error)}`;
+    const wrapped = new Error(message);
+    if (error instanceof Error) {
+        wrapped.cause = error;
+    }
+    return wrapped;
+}
+//# sourceMappingURL=error-utils.js.map

package/dist/utils/lru-cache.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal LRU cache using ES6 Map insertion-order semantics.
+ * When capacity is exceeded, the least-recently-used entry is evicted.
+ */
+export declare class LRUCache<K, V> {
+    private map;
+    private readonly maxSize;
+    constructor(maxSize: number);
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): void;
+    clear(): void;
+    get size(): number;
+}
+//# sourceMappingURL=lru-cache.d.ts.map

package/dist/utils/lru-cache.js

@@ -0,0 +1,40 @@
+/**
+ * Minimal LRU cache using ES6 Map insertion-order semantics.
+ * When capacity is exceeded, the least-recently-used entry is evicted.
+ */
+export class LRUCache {
+    map = new Map();
+    maxSize;
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const value = this.map.get(key);
+        if (value !== undefined) {
+            // Move to end (most recently used)
+            this.map.delete(key);
+            this.map.set(key, value);
+        }
+        return value;
+    }
+    has(key) {
+        return this.map.has(key);
+    }
+    set(key, value) {
+        if (this.map.has(key)) {
+            this.map.delete(key);
+        }
+        this.map.set(key, value);
+        while (this.map.size > this.maxSize) {
+            const firstKey = this.map.keys().next().value;
+            this.map.delete(firstKey);
+        }
+    }
+    clear() {
+        this.map.clear();
+    }
+    get size() {
+        return this.map.size;
+    }
+}
+//# sourceMappingURL=lru-cache.js.map

package/dist/utils/port-ordering.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared port ordering utilities
+ * Extracted from parser.ts for reuse across the codebase
+ */
+import type { TPortDefinition } from "../ast/types.js";
+/**
+ * Check if a port is mandatory.
+ * External ports: execute, onSuccess, onFailure
+ * Scoped ports: start, success, failure
+ */
+export declare function isMandatoryPort(portName: string, isScoped: boolean): boolean;
+/**
+ * Assign implicit port orders with mandatory port precedence.
+ *
+ * Rules:
+ * 1. Ports are grouped by scope (undefined = external, string = scoped)
+ * 2. Within each scope group:
+ *    - Mandatory ports (execute, onSuccess, onFailure) get lower order values
+ *    - Regular ports get higher order values
+ * 3. Explicit order metadata is always preserved
+ * 4. If a regular port has explicit order 0, mandatory ports are pushed to order >= 1
+ *
+ * @param ports - Record of port definitions to process (mutated in place)
+ */
+export declare function assignImplicitPortOrders(ports: Record<string, TPortDefinition>): void;
+//# sourceMappingURL=port-ordering.d.ts.map

package/dist/utils/port-ordering.js

@@ -0,0 +1,88 @@
+/**
+ * Shared port ordering utilities
+ * Extracted from parser.ts for reuse across the codebase
+ */
+import { isExecutePort, isSuccessPort, isFailurePort, isScopedMandatoryPort } from "../constants.js";
+/**
+ * Check if a port is mandatory.
+ * External ports: execute, onSuccess, onFailure
+ * Scoped ports: start, success, failure
+ */
+export function isMandatoryPort(portName, isScoped) {
+    if (isScoped) {
+        return isScopedMandatoryPort(portName);
+    }
+    return isExecutePort(portName) || isSuccessPort(portName) || isFailurePort(portName);
+}
+/**
+ * Assign implicit port orders with mandatory port precedence.
+ *
+ * Rules:
+ * 1. Ports are grouped by scope (undefined = external, string = scoped)
+ * 2. Within each scope group:
+ *    - Mandatory ports (execute, onSuccess, onFailure) get lower order values
+ *    - Regular ports get higher order values
+ * 3. Explicit order metadata is always preserved
+ * 4. If a regular port has explicit order 0, mandatory ports are pushed to order >= 1
+ *
+ * @param ports - Record of port definitions to process (mutated in place)
+ */
+export function assignImplicitPortOrders(ports) {
+    // Group ports by scope
+    const scopeGroups = new Map();
+    for (const [portName, portDef] of Object.entries(ports)) {
+        const scopeKey = portDef.scope;
+        if (!scopeGroups.has(scopeKey)) {
+            scopeGroups.set(scopeKey, []);
+        }
+        scopeGroups.get(scopeKey).push([portName, portDef]);
+    }
+    // Process each scope group independently
+    for (const [scope, portsInScope] of scopeGroups.entries()) {
+        const isScoped = scope !== undefined;
+        // Separate mandatory from regular ports
+        const mandatoryPorts = portsInScope.filter(([name]) => isMandatoryPort(name, isScoped));
+        const regularPorts = portsInScope.filter(([name]) => !isMandatoryPort(name, isScoped));
+        // Find minimum explicit order among regular ports (if any)
+        let minRegularExplicitOrder = Infinity;
+        for (const [, portDef] of regularPorts) {
+            const order = portDef.metadata?.order;
+            if (typeof order === "number") {
+                minRegularExplicitOrder = Math.min(minRegularExplicitOrder, order);
+            }
+        }
+        // Determine starting order for mandatory ports
+        let mandatoryStartOrder = 0;
+        // If a regular port has explicit order 0 (or any low value),
+        // mandatory ports should be pushed after it
+        if (minRegularExplicitOrder !== Infinity && minRegularExplicitOrder === 0) {
+            // Count how many regular ports have explicit order 0
+            const regularPortsWithOrder0 = regularPorts.filter(([, p]) => p.metadata?.order === 0);
+            mandatoryStartOrder = regularPortsWithOrder0.length;
+        }
+        // Assign orders to mandatory ports (if they don't have explicit order)
+        let currentMandatoryOrder = mandatoryStartOrder;
+        for (const [, portDef] of mandatoryPorts) {
+            if (portDef.metadata?.order === undefined) {
+                // Assign implicit order
+                if (!portDef.metadata) {
+                    portDef.metadata = {};
+                }
+                portDef.metadata.order = currentMandatoryOrder++;
+            }
+        }
+        // Assign orders to regular ports (if they don't have explicit order)
+        // Regular ports start after mandatory ports
+        let currentRegularOrder = currentMandatoryOrder;
+        for (const [, portDef] of regularPorts) {
+            if (portDef.metadata?.order === undefined) {
+                // Assign implicit order
+                if (!portDef.metadata) {
+                    portDef.metadata = {};
+                }
+                portDef.metadata.order = currentRegularOrder++;
+            }
+        }
+    }
+}
+//# sourceMappingURL=port-ordering.js.map

package/dist/utils/port-tag-utils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Port tag validation utilities
+ * Shared logic for determining port tag types (@input, @output, @step)
+ */
+import type { TPortDefinition } from "../ast/types.js";
+/**
+ * Check if a port name is a reserved STEP port.
+ * Includes both external (execute, onSuccess, onFailure) and scoped (start, success, failure).
+ */
+export declare function isReservedStepPort(name: string): boolean;
+/**
+ * Determine if a port should use the @step tag.
+ * Returns true only for custom STEP ports (not reserved ones).
+ */
+export declare function shouldUseStepTag(portName: string, port: TPortDefinition): boolean;
+/**
+ * Get the JSDoc tag type for a port.
+ * - Custom STEP ports → "step"
+ * - Reserved STEP ports → direction ("input" or "output")
+ * - Data ports → direction ("input" or "output")
+ */
+export declare function getPortTagType(portName: string, port: TPortDefinition, direction: "input" | "output"): "input" | "output" | "step";
+//# sourceMappingURL=port-tag-utils.d.ts.map