@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/types.d.ts

@@ -1,139 +0,0 @@
-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

@@ -1,15 +0,0 @@
-/**
- * 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.js

@@ -1,27 +0,0 @@
-/**
- * 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.js

@@ -1,40 +0,0 @@
-/**
- * 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.js

@@ -1,81 +0,0 @@
-/**
- * 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. Explicit order metadata is always preserved
- * 3. Mandatory ports without explicit orders get negative slots (-N, ..., -1)
- *    so they always sort before any user-specified [order:0] data port
- * 4. Regular ports without explicit orders fill non-negative slots (0+),
- *    skipping any slots already occupied by explicit orders
- *
- * @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;
-        // Collect all explicitly occupied order slots
-        const occupied = new Set();
-        for (const [, portDef] of portsInScope) {
-            const order = portDef.metadata?.order;
-            if (typeof order === "number") {
-                occupied.add(order);
-            }
-        }
-        // Helper: find next available slot starting from `from`
-        function nextSlot(from) {
-            while (occupied.has(from))
-                from++;
-            occupied.add(from);
-            return from;
-        }
-        // Separate mandatory from regular ports (only those needing implicit orders)
-        const mandatoryNeedOrder = portsInScope.filter(([name, def]) => isMandatoryPort(name, isScoped) && def.metadata?.order === undefined);
-        const regularNeedOrder = portsInScope.filter(([name, def]) => !isMandatoryPort(name, isScoped) && def.metadata?.order === undefined);
-        // Mandatory ports fill negative slots so they always sort before [order:0] data ports
-        let slot = -mandatoryNeedOrder.length;
-        for (const [, portDef] of mandatoryNeedOrder) {
-            if (!portDef.metadata)
-                portDef.metadata = {};
-            slot = nextSlot(slot);
-            portDef.metadata.order = slot;
-            slot++;
-        }
-        // Regular ports fill non-negative slots, skipping occupied ones
-        slot = Math.max(slot, 0);
-        for (const [, portDef] of regularNeedOrder) {
-            if (!portDef.metadata)
-                portDef.metadata = {};
-            slot = nextSlot(slot);
-            portDef.metadata.order = slot;
-            slot++;
-        }
-    }
-}
-//# sourceMappingURL=port-ordering.js.map

package/dist/utils/port-tag-utils.js

@@ -1,41 +0,0 @@
-/**
- * Port tag validation utilities
- * Shared logic for determining port tag types (@input, @output, @step)
- */
-import { isExecutePort, isSuccessPort, isFailurePort, isScopedMandatoryPort } from "../constants.js";
-/**
- * Check if a port name is a reserved STEP port.
- * Includes both external (execute, onSuccess, onFailure) and scoped (start, success, failure).
- */
-export function isReservedStepPort(name) {
-    return isExecutePort(name) || isSuccessPort(name) || isFailurePort(name) || isScopedMandatoryPort(name);
-}
-/**
- * Determine if a port should use the @step tag.
- * Returns true only for custom STEP ports (not reserved ones).
- */
-export function shouldUseStepTag(portName, port) {
-    if (port.dataType !== "STEP")
-        return false;
-    // Reserved STEP ports use @input/@output, not @step
-    const isExternalReserved = isExecutePort(portName) || isSuccessPort(portName) || isFailurePort(portName);
-    if (isExternalReserved)
-        return false;
-    // Scoped mandatory ports also use @input/@output
-    if (port.scope && isScopedMandatoryPort(portName))
-        return false;
-    return true;
-}
-/**
- * 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 function getPortTagType(portName, port, direction) {
-    if (shouldUseStepTag(portName, port)) {
-        return "step";
-    }
-    return direction;
-}
-//# sourceMappingURL=port-tag-utils.js.map

package/dist/utils/string-distance.js

@@ -1,56 +0,0 @@
-/**
- * Levenshtein distance and fuzzy matching utilities
- */
-/**
- * Compute the Levenshtein edit distance between two strings.
- */
-export function levenshteinDistance(a, b) {
-    const la = a.length;
-    const lb = b.length;
-    if (la === 0)
-        return lb;
-    if (lb === 0)
-        return la;
-    // Use single-row optimization
-    let prev = Array.from({ length: lb + 1 }, (_, i) => i);
-    let curr = new Array(lb + 1);
-    for (let i = 1; i <= la; i++) {
-        curr[0] = i;
-        for (let j = 1; j <= lb; j++) {
-            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-            curr[j] = Math.min(curr[j - 1] + 1, // insertion
-            prev[j] + 1, // deletion
-            prev[j - 1] + cost // substitution
-            );
-        }
-        [prev, curr] = [curr, prev];
-    }
-    return prev[lb];
-}
-/**
- * Compute an adaptive max edit distance based on target string length.
- * Short strings get a tighter threshold to avoid nonsensical suggestions.
- */
-function adaptiveMaxDistance(target) {
-    const len = target.length;
-    if (len <= 3)
-        return 1;
-    if (len <= 6)
-        return 2;
-    return 3;
-}
-/**
- * Find the closest matches from a list of candidates.
- * Returns candidates within maxDistance, sorted by distance (ascending).
- * When maxDistance is not provided, uses a length-proportional default.
- */
-export function findClosestMatches(target, candidates, maxDistance) {
-    const effectiveMax = maxDistance ?? adaptiveMaxDistance(target);
-    const scored = candidates
-        .filter((c) => c !== target)
-        .map((c) => ({ name: c, distance: levenshteinDistance(target, c) }))
-        .filter((s) => s.distance <= effectiveMax)
-        .sort((a, b) => a.distance - b.distance);
-    return scored.map((s) => s.name);
-}
-//# sourceMappingURL=string-distance.js.map

package/dist/validation/agent-detection.js

@@ -1,115 +0,0 @@
-/**
- * Agent Node Detection
- *
- * Multi-signal detection to classify workflow nodes by their agent role.
- * Uses a priority hierarchy: port signatures > visual annotations > name heuristics.
- */
-// ---------------------------------------------------------------------------
-// Signal matchers (ordered by priority)
-// ---------------------------------------------------------------------------
-/** Port-based detection — most reliable since port names define the contract */
-const PORT_SIGNATURES = [
-    {
-        // LLM node: has 'messages' input AND ('content' or 'toolCalls' output)
-        role: 'llm',
-        match: (nt) => {
-            const hasMessagesInput = 'messages' in nt.inputs;
-            const hasContentOutput = 'content' in nt.outputs;
-            const hasToolCallsOutput = 'toolCalls' in nt.outputs;
-            return hasMessagesInput && (hasContentOutput || hasToolCallsOutput);
-        },
-    },
-    {
-        // Tool executor: has 'toolCall' input AND 'result' output
-        role: 'tool-executor',
-        match: (nt) => {
-            const hasToolCallInput = 'toolCall' in nt.inputs || 'toolCalls' in nt.inputs;
-            const hasResultOutput = 'result' in nt.outputs || 'resultMessage' in nt.outputs;
-            return hasToolCallInput && hasResultOutput;
-        },
-    },
-    {
-        // Human approval: has ('approved' AND 'rejected') outputs
-        role: 'human-approval',
-        match: (nt) => {
-            return 'approved' in nt.outputs && 'rejected' in nt.outputs;
-        },
-    },
-    {
-        // Memory: has 'conversationId' input AND 'messages' output
-        role: 'memory',
-        match: (nt) => {
-            const hasConversationIdInput = 'conversationId' in nt.inputs;
-            const hasMessagesOutput = 'messages' in nt.outputs;
-            return hasConversationIdInput && hasMessagesOutput;
-        },
-    },
-];
-/** Icon-based detection — reliable when present, from @icon annotation */
-const ICON_MAP = {
-    psychology: 'llm',
-    build: 'tool-executor',
-    verified: 'human-approval',
-    database: 'memory',
-};
-/** Color-based detection — weaker signal, only used to confirm */
-const COLOR_MAP = {
-    purple: 'llm',
-    cyan: 'tool-executor',
-    orange: 'human-approval',
-};
-/** Name pattern heuristics — fallback only */
-const NAME_PATTERNS = [
-    { role: 'llm', pattern: /^(llm|chat|completion|model|ai)/i },
-    { role: 'tool-executor', pattern: /^(tool|action|execute|exec)/i },
-    { role: 'human-approval', pattern: /^(human|approv|review|gate)/i },
-    { role: 'memory', pattern: /^(memory|conversation|history|context)/i },
-];
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Detect the agent role of a node type using multi-signal analysis.
- *
- * Priority:
- * 1. Port signature patterns (strongest — defines the contract)
- * 2. @icon annotation (strong — explicit visual intent)
- * 3. @color annotation (weak — only used to break ties)
- * 4. Function name heuristics (weakest — fallback only)
- *
- * @returns The detected role, or null if the node is not an agent node
- */
-export function detectNodeRole(nodeType) {
-    // 1. Port signatures (highest confidence)
-    for (const sig of PORT_SIGNATURES) {
-        if (sig.match(nodeType)) {
-            return sig.role;
-        }
-    }
-    // 2. Icon annotation
-    const icon = nodeType.visuals?.icon;
-    if (icon && icon in ICON_MAP) {
-        return ICON_MAP[icon];
-    }
-    // 3. Color annotation (only if it maps unambiguously)
-    const color = nodeType.visuals?.color;
-    if (color && color in COLOR_MAP) {
-        return COLOR_MAP[color];
-    }
-    // 4. Function name heuristics
-    const name = nodeType.functionName || nodeType.name;
-    for (const { role, pattern } of NAME_PATTERNS) {
-        if (pattern.test(name)) {
-            return role;
-        }
-    }
-    return null;
-}
-/**
- * Convenience: find all node types in a workflow that match a specific role.
- * Returns array of [instanceId, nodeType] pairs for all instances with that role.
- */
-export function findNodesByRole(nodeTypes, role) {
-    return nodeTypes.filter((nt) => detectNodeRole(nt) === role);
-}
-//# sourceMappingURL=agent-detection.js.map