@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/type-checker.js

@@ -1,190 +0,0 @@
-/**
- * Type Checker Module
- *
- * Provides TypeScript-level type compatibility checking using ts-morph and TypeScript's compiler API.
- * This enables proper structural typing and subtype checking beyond simple string comparison.
- */
-/**
- * Safe runtime coercions that JavaScript handles automatically.
- * These are source -> target pairs where coercion is safe and predictable.
- */
-const SAFE_COERCIONS = [
-    ["number", "string"], // Number.toString()
-    ["boolean", "string"], // Boolean.toString()
-];
-/**
- * Check if a source type can be safely coerced to a target type at runtime.
- *
- * @param sourceText - The source type as a string
- * @param targetText - The target type as a string
- * @returns true if the coercion is safe
- */
-export function isRuntimeCoercible(sourceText, targetText) {
-    const sourceLower = sourceText.toLowerCase();
-    const targetLower = targetText.toLowerCase();
-    for (const [from, to] of SAFE_COERCIONS) {
-        if (sourceLower === from && targetLower === to) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Check type compatibility between two ts-morph Type objects.
- *
- * This uses TypeScript's actual type system for proper structural typing:
- * - Structural typing (duck typing)
- * - Inheritance (Admin extends User)
- * - Generics (Array<T>, Promise<T>)
- * - Union/Intersection types
- * - Type narrowing
- *
- * @param sourceType - The source type (from output port)
- * @param targetType - The target type (from input port)
- * @param typeChecker - Optional ts-morph TypeChecker for advanced assignability checks
- * @returns TTypeCompatibility result
- */
-export function checkTypeCompatibility(sourceType, targetType, typeChecker) {
-    const sourceText = sourceType.getText();
-    const targetText = targetType.getText();
-    // Exact string match - fastest path
-    if (sourceText === targetText) {
-        return {
-            isCompatible: true,
-            reason: "exact",
-            sourceType: sourceText,
-            targetType: targetText,
-        };
-    }
-    // Try TypeScript's native assignability check if typeChecker is available
-    if (typeChecker) {
-        // Access the internal TypeScript compiler's type checker
-        const tsTypeChecker = typeChecker.compilerObject;
-        if (tsTypeChecker.isTypeAssignableTo) {
-            const isAssignable = tsTypeChecker.isTypeAssignableTo(sourceType.compilerType, targetType.compilerType);
-            if (isAssignable) {
-                return {
-                    isCompatible: true,
-                    reason: "assignable",
-                    sourceType: sourceText,
-                    targetType: targetText,
-                };
-            }
-        }
-    }
-    // Fallback: Check inheritance via base types
-    if (isSubtypeViaBaseTypes(sourceType, targetType)) {
-        return {
-            isCompatible: true,
-            reason: "assignable",
-            sourceType: sourceText,
-            targetType: targetText,
-        };
-    }
-    // Check for safe runtime coercions (NUMBER→STRING, BOOLEAN→STRING)
-    if (isRuntimeCoercible(sourceText, targetText)) {
-        return {
-            isCompatible: true,
-            reason: "coercible",
-            sourceType: sourceText,
-            targetType: targetText,
-        };
-    }
-    // Types are incompatible
-    return {
-        isCompatible: false,
-        reason: "incompatible",
-        sourceType: sourceText,
-        targetType: targetText,
-        errorMessage: `Type '${sourceText}' is not assignable to type '${targetText}'`,
-    };
-}
-/**
- * Check if sourceType is a subtype of targetType via inheritance chain.
- * Uses getBaseTypes() to traverse the type hierarchy.
- */
-function isSubtypeViaBaseTypes(sourceType, targetType) {
-    const targetText = targetType.getText();
-    const visited = new Set();
-    function checkBaseTypes(type) {
-        const typeText = type.getText();
-        // Avoid infinite loops
-        if (visited.has(typeText))
-            return false;
-        visited.add(typeText);
-        // Check if this type matches target
-        if (typeText === targetText)
-            return true;
-        // Check base types recursively
-        try {
-            const baseTypes = type.getBaseTypes();
-            for (const baseType of baseTypes) {
-                if (checkBaseTypes(baseType))
-                    return true;
-            }
-        }
-        catch {
-            // Some types don't have base types
-        }
-        return false;
-    }
-    // Check if source's base types include target
-    try {
-        const baseTypes = sourceType.getBaseTypes();
-        for (const baseType of baseTypes) {
-            if (checkBaseTypes(baseType))
-                return true;
-        }
-    }
-    catch {
-        // Some types don't have base types
-    }
-    return false;
-}
-/**
- * Check type compatibility using string representations.
- * Fallback for JSON-loaded workflows without ts-morph Type objects.
- *
- * @param sourceText - The source type as a string
- * @param targetText - The target type as a string
- * @returns TTypeCompatibility result
- */
-export function checkTypeCompatibilityFromStrings(sourceText, targetText) {
-    // Exact string match
-    if (sourceText === targetText) {
-        return {
-            isCompatible: true,
-            reason: "exact",
-            sourceType: sourceText,
-            targetType: targetText,
-        };
-    }
-    // any is compatible with everything
-    if (sourceText === "any" || targetText === "any") {
-        return {
-            isCompatible: true,
-            reason: "assignable",
-            sourceType: sourceText,
-            targetType: targetText,
-        };
-    }
-    // Check for safe runtime coercions
-    if (isRuntimeCoercible(sourceText, targetText)) {
-        return {
-            isCompatible: true,
-            reason: "coercible",
-            sourceType: sourceText,
-            targetType: targetText,
-        };
-    }
-    // String comparison can't determine structural compatibility
-    // Mark as incompatible, but the validator may want to be lenient
-    return {
-        isCompatible: false,
-        reason: "incompatible",
-        sourceType: sourceText,
-        targetType: targetText,
-        errorMessage: `Type '${sourceText}' is not assignable to type '${targetText}'`,
-    };
-}
-//# sourceMappingURL=type-checker.js.map

package/dist/type-mappings.js

@@ -1,131 +0,0 @@
-export const PORT_TYPE_MAPPINGS = {
-    STRING: {
-        typescript: 'string',
-        description: 'Text value',
-    },
-    NUMBER: {
-        typescript: 'number',
-        description: 'Numeric value',
-    },
-    BOOLEAN: {
-        typescript: 'boolean',
-        description: 'True or false value',
-    },
-    ARRAY: {
-        typescript: 'unknown[]',
-        description: 'Array of values',
-    },
-    OBJECT: {
-        typescript: 'Record<string, unknown>',
-        description: 'Object with properties',
-    },
-    FUNCTION: {
-        typescript: '(...args: unknown[]) => unknown',
-        description: 'Function or callback',
-    },
-    ANY: {
-        typescript: 'unknown',
-        description: 'Any type of value',
-    },
-    STEP: {
-        typescript: 'boolean',
-        description: 'Control flow signal (boolean in public API)',
-    },
-};
-export function mapToTypeScript(portType, tsType) {
-    const mapping = PORT_TYPE_MAPPINGS[portType];
-    if (!mapping) {
-        console.warn(`Unknown port type: ${portType}, defaulting to 'unknown'`);
-        return 'unknown';
-    }
-    // For non-primitive types, use tsType if provided — BUT strip types
-    // that contain absolute paths (import("/absolute/path").Type) which
-    // break when the file is compiled on a different machine or moved.
-    if (tsType &&
-        (portType === 'OBJECT' || portType === 'ANY' || portType === 'ARRAY' || portType === 'FUNCTION')) {
-        // Strip types with absolute import paths — they break on other machines
-        if (tsType.includes('import(')) {
-            return mapping.typescript;
-        }
-        return tsType;
-    }
-    return mapping.typescript;
-}
-export function isValidPortType(type) {
-    return type in PORT_TYPE_MAPPINGS;
-}
-export function getAllPortTypes() {
-    return Object.keys(PORT_TYPE_MAPPINGS);
-}
-export function getPortTypeDescription(portType) {
-    return PORT_TYPE_MAPPINGS[portType]?.description;
-}
-/**
- * Infer TDataType from a TypeScript type string.
- * This is the reverse mapping: TypeScript type → Flow Weaver semantic type.
- *
- * @param tsType - The TypeScript type string (e.g., "string", "number[]", "User")
- * @returns The corresponding TDataType for color/category mapping
- *
- * @example
- * inferDataTypeFromTS("string") // → "STRING"
- * inferDataTypeFromTS("number") // → "NUMBER"
- * inferDataTypeFromTS("boolean") // → "BOOLEAN"
- * inferDataTypeFromTS("User[]") // → "ARRAY"
- * inferDataTypeFromTS("Array<number>") // → "ARRAY"
- * inferDataTypeFromTS("Map<string, User>") // → "OBJECT"
- * inferDataTypeFromTS("(x: number) => string") // → "FUNCTION"
- */
-export function inferDataTypeFromTS(tsType) {
-    const normalized = tsType.trim();
-    // Exact primitive matches
-    if (normalized === 'string')
-        return 'STRING';
-    if (normalized === 'number')
-        return 'NUMBER';
-    if (normalized === 'boolean')
-        return 'BOOLEAN';
-    // Any/unknown fallback
-    if (normalized === 'any' || normalized === 'unknown' || normalized === 'never') {
-        return 'ANY';
-    }
-    // Void (rare, but handle it)
-    if (normalized === 'void' || normalized === 'undefined' || normalized === 'null') {
-        return 'ANY';
-    }
-    // Array patterns: T[], Array<T>, ReadonlyArray<T>
-    if (normalized.endsWith('[]') ||
-        normalized.startsWith('Array<') ||
-        normalized.startsWith('ReadonlyArray<')) {
-        return 'ARRAY';
-    }
-    // Function patterns: () => T, (args) => T, Function
-    if (normalized.includes('=>') || normalized === 'Function' || normalized.startsWith('(')) {
-        return 'FUNCTION';
-    }
-    // Promise unwrapping: Promise<T> → infer from T
-    if (normalized.startsWith('Promise<') && normalized.endsWith('>')) {
-        const inner = normalized.slice(8, -1);
-        return inferDataTypeFromTS(inner);
-    }
-    // Union types: handle T | undefined and T | null as optional types
-    if (normalized.includes('|')) {
-        // Split by | and filter out undefined/null
-        const parts = normalized.split('|').map((p) => p.trim());
-        const nonNullParts = parts.filter((p) => p !== 'undefined' && p !== 'null');
-        if (nonNullParts.length === 1) {
-            // This is an optional type (T | undefined or T | null) - infer from T
-            return inferDataTypeFromTS(nonNullParts[0]);
-        }
-        // True union type - default to ANY
-        return 'ANY';
-    }
-    // Intersection types: if contains &, default to OBJECT
-    if (normalized.includes('&')) {
-        return 'OBJECT';
-    }
-    // Generic object types (Map, Set, Record, etc.) → OBJECT
-    // Any remaining complex type → OBJECT
-    return 'OBJECT';
-}
-//# sourceMappingURL=type-mappings.js.map

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

@@ -1,151 +0,0 @@
-/**
- * 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

@@ -1,121 +0,0 @@
-/**
- * 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

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

package/dist/types/index.js

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