@synergenius/flow-weaver 0.2.0

package/dist/jsdoc-port-sync/signature-parser.js

@@ -0,0 +1,559 @@
+/**
+ * @module jsdoc-port-sync/signature-parser
+ *
+ * Parse TypeScript function signatures to extract parameters and return types.
+ * Browser-compatible (regex-based, no ts-morph).
+ */
+import { FUNC_DECL_START, ARROW_START, RETURN_OBJECT_REGEX, RESERVED_RETURN_FIELDS, findBalancedClose, splitParams, } from "./constants.js";
+// =============================================================================
+// Function Signature Parsing
+// =============================================================================
+/**
+ * Parse function signature to extract parameters.
+ * Supports both function declarations and arrow functions.
+ * Uses balanced paren matching to handle nested callback types.
+ */
+export function parseFunctionSignature(functionText) {
+    const params = [];
+    let functionType = "expression";
+    let paramsStr = "";
+    // Try function declaration first - use balanced matching for nested parens
+    const funcDeclMatch = functionText.match(FUNC_DECL_START);
+    if (funcDeclMatch && funcDeclMatch.index !== undefined) {
+        functionType = "declaration";
+        const openParenIndex = funcDeclMatch.index + funcDeclMatch[0].length - 1;
+        const closeParenIndex = findBalancedClose(functionText, openParenIndex);
+        if (closeParenIndex !== -1) {
+            paramsStr = functionText.substring(openParenIndex + 1, closeParenIndex);
+        }
+    }
+    else {
+        // Try arrow function
+        const arrowMatch = functionText.match(ARROW_START);
+        if (arrowMatch && arrowMatch.index !== undefined) {
+            functionType = "arrow";
+            const openParenIndex = arrowMatch.index + arrowMatch[0].length - 1;
+            const closeParenIndex = findBalancedClose(functionText, openParenIndex);
+            if (closeParenIndex !== -1) {
+                paramsStr = functionText.substring(openParenIndex + 1, closeParenIndex);
+            }
+        }
+    }
+    if (!paramsStr.trim()) {
+        return { params, functionType };
+    }
+    // Parse individual parameters
+    const paramTokens = splitParams(paramsStr);
+    paramTokens.forEach((paramStr, index) => {
+        const param = parseParam(paramStr.trim(), index);
+        if (param) {
+            params.push(param);
+        }
+    });
+    return { params, functionType };
+}
+/**
+ * Parse a single parameter string like "name?: type = default"
+ * Handles multiline callback types with nested parens/braces.
+ */
+function parseParam(paramStr, position) {
+    if (!paramStr)
+        return null;
+    const trimmed = paramStr.trim();
+    if (!trimmed)
+        return null;
+    // Extract name first (must be valid identifier)
+    const nameMatch = trimmed.match(/^(\w+)(\?)?/);
+    if (!nameMatch)
+        return null;
+    const name = nameMatch[1];
+    const questionMark = nameMatch[2];
+    let rest = trimmed.substring(nameMatch[0].length).trim();
+    let tsType;
+    let defaultValue;
+    // Check for type annotation (: type)
+    if (rest.startsWith(":")) {
+        rest = rest.substring(1).trim();
+        // Find where type ends - either at unbalanced = (not =>) or end of string
+        let depth = 0;
+        let typeEnd = rest.length;
+        for (let i = 0; i < rest.length; i++) {
+            const ch = rest[i];
+            if (ch === "(" || ch === "{" || ch === "[" || ch === "<") {
+                depth++;
+            }
+            else if (ch === ")" || ch === "}" || ch === "]" || ch === ">") {
+                depth--;
+            }
+            else if (ch === "=" && depth === 0) {
+                // Check if this is => (arrow) vs = (assignment)
+                if (rest[i + 1] === ">") {
+                    i++; // skip >
+                    continue;
+                }
+                typeEnd = i;
+                break;
+            }
+        }
+        tsType = rest.substring(0, typeEnd).trim();
+        rest = rest.substring(typeEnd).trim();
+    }
+    // Check for default value (= value)
+    if (rest.startsWith("=")) {
+        defaultValue = rest.substring(1).trim();
+    }
+    const hasDefault = defaultValue !== undefined;
+    const optional = !!questionMark || hasDefault;
+    return {
+        name,
+        tsType: tsType || undefined,
+        optional,
+        defaultValue,
+        position,
+    };
+}
+// =============================================================================
+// Return Type Parsing
+// =============================================================================
+/**
+ * Parse return statement to extract object field names.
+ * Returns unique field names from all return statements.
+ */
+export function parseReturnFields(functionText) {
+    const fields = new Set();
+    RETURN_OBJECT_REGEX.lastIndex = 0;
+    let match;
+    while ((match = RETURN_OBJECT_REGEX.exec(functionText)) != null) {
+        const objectContent = match[1];
+        const fieldParts = objectContent.split(",");
+        for (const part of fieldParts) {
+            const trimmed = part.trim();
+            if (!trimmed)
+                continue;
+            // Check for "key: value" pattern
+            const colonMatch = trimmed.match(/^(\w+)\s*:/);
+            if (colonMatch) {
+                const fieldName = colonMatch[1];
+                if (!RESERVED_RETURN_FIELDS.includes(fieldName)) {
+                    fields.add(fieldName);
+                }
+            }
+            else {
+                // Shorthand property - just the identifier
+                const shorthandMatch = trimmed.match(/^(\w+)$/);
+                if (shorthandMatch) {
+                    const fieldName = shorthandMatch[1];
+                    if (!RESERVED_RETURN_FIELDS.includes(fieldName)) {
+                        fields.add(fieldName);
+                    }
+                }
+            }
+        }
+    }
+    return Array.from(fields);
+}
+/**
+ * Parse return body fields WITH inferred types.
+ * Analyzes `return { field: value }` statements to infer types from values.
+ *
+ * @returns Map of field name → inferred TypeScript type
+ */
+export function parseReturnBodyFieldsWithTypes(functionText) {
+    const fields = new Map();
+    RETURN_OBJECT_REGEX.lastIndex = 0;
+    let match;
+    while ((match = RETURN_OBJECT_REGEX.exec(functionText)) != null) {
+        const objectContent = match[1];
+        const fieldParts = objectContent.split(",");
+        for (const part of fieldParts) {
+            const trimmed = part.trim();
+            if (!trimmed)
+                continue;
+            // Check for "key: value" pattern
+            const colonMatch = trimmed.match(/^(\w+)\s*:\s*(.+)$/);
+            if (colonMatch) {
+                const fieldName = colonMatch[1];
+                const value = colonMatch[2].trim();
+                if (!RESERVED_RETURN_FIELDS.includes(fieldName)) {
+                    const inferredType = inferTypeFromValue(value);
+                    if (!fields.has(fieldName) || fields.get(fieldName) === "any") {
+                        fields.set(fieldName, inferredType);
+                    }
+                }
+            }
+            else {
+                // Shorthand property - just the identifier
+                const shorthandMatch = trimmed.match(/^(\w+)$/);
+                if (shorthandMatch) {
+                    const fieldName = shorthandMatch[1];
+                    if (!RESERVED_RETURN_FIELDS.includes(fieldName) && !fields.has(fieldName)) {
+                        fields.set(fieldName, "any");
+                    }
+                }
+            }
+        }
+    }
+    return fields;
+}
+/**
+ * Infer TypeScript type from a value in return statement.
+ * Simple heuristic-based detection.
+ */
+function inferTypeFromValue(value) {
+    value = value.trim();
+    if (value.startsWith("["))
+        return "any[]";
+    if (value.startsWith("{"))
+        return "any";
+    if (/^["'`]/.test(value))
+        return "string";
+    if (/^-?\d+(\.\d+)?$/.test(value))
+        return "number";
+    if (value === "true" || value === "false")
+        return "boolean";
+    if (value === "null" || value === "undefined")
+        return "any";
+    return "any";
+}
+/**
+ * Parse return type annotation fields from function signature.
+ * Matches:
+ * - function foo(): { fieldName: type, ... }
+ * - const foo: TFlowWeaverNodeType<{...}, { fieldName: type, ... }> = ...
+ */
+export function parseReturnTypeFields(functionText) {
+    // Try standard return type syntax first: ): { ... } or )=> { ... }
+    let returnTypeMatch = functionText.match(/\)\s*:\s*\{([^}]+)\}\s*(?:\{|=>)/);
+    // If not found, try TFlowWeaverNodeType<InputType, OutputType> syntax
+    if (!returnTypeMatch) {
+        const genericStart = functionText.indexOf("TFlowWeaverNodeType<");
+        if (genericStart !== -1) {
+            let braceCount = 0;
+            let inFirstParam = false;
+            let firstParamEnd = -1;
+            let secondParamStart = -1;
+            let secondParamEnd = -1;
+            for (let i = genericStart + "TFlowWeaverNodeType<".length; i < functionText.length; i++) {
+                const char = functionText[i];
+                if (char === "{") {
+                    if (!inFirstParam && braceCount === 0) {
+                        inFirstParam = true;
+                    }
+                    else if (firstParamEnd !== -1 && secondParamStart === -1) {
+                        secondParamStart = i + 1;
+                    }
+                    braceCount++;
+                }
+                else if (char === "}") {
+                    braceCount--;
+                    if (braceCount === 0) {
+                        if (inFirstParam && firstParamEnd === -1) {
+                            firstParamEnd = i;
+                            inFirstParam = false;
+                        }
+                        else if (secondParamStart !== -1) {
+                            secondParamEnd = i;
+                            break;
+                        }
+                    }
+                }
+            }
+            if (secondParamStart !== -1 && secondParamEnd !== -1) {
+                const objectContent = functionText.substring(secondParamStart, secondParamEnd);
+                returnTypeMatch = [functionText, objectContent];
+            }
+        }
+    }
+    if (!returnTypeMatch)
+        return [];
+    const fields = [];
+    const objectContent = returnTypeMatch[1];
+    const fieldParts = objectContent.split(/[,;]/);
+    for (const part of fieldParts) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const colonMatch = trimmed.match(/^(\w+)\s*:/);
+        if (colonMatch) {
+            const fieldName = colonMatch[1];
+            if (!RESERVED_RETURN_FIELDS.includes(fieldName)) {
+                fields.push(fieldName);
+            }
+        }
+    }
+    return fields;
+}
+/**
+ * Parse return type fields WITH their TypeScript types.
+ * Returns array of { name, tsType } for each field in the return type.
+ */
+export function parseReturnTypeFieldsWithTypes(functionText) {
+    const fields = [];
+    // Match return type: ): { field: type; ... } or ): Promise<{ field: type; ... }>
+    const returnTypeMatch = functionText.match(/\)\s*:\s*(?:Promise\s*<\s*)?\{([^}]+)\}/);
+    if (!returnTypeMatch)
+        return fields;
+    const returnTypeContent = returnTypeMatch[1];
+    // Parse individual fields: name: type or name?: type
+    const fieldRegex = /(\w+)\s*\??\s*:\s*([^;,}]+)/g;
+    let match;
+    while ((match = fieldRegex.exec(returnTypeContent)) != null) {
+        const [, name, tsType] = match;
+        fields.push({ name, tsType: tsType.trim() });
+    }
+    return fields;
+}
+/**
+ * Split object type fields by comma or semicolon, respecting nested angle brackets,
+ * square brackets, braces, and parentheses.
+ * e.g. "report: Record<string, unknown>; count: number" → ["report: Record<string, unknown>", "count: number"]
+ */
+function splitObjectFields(content) {
+    const result = [];
+    let current = "";
+    let angleDepth = 0;
+    let bracketDepth = 0;
+    let braceDepth = 0;
+    let parenDepth = 0;
+    for (const char of content) {
+        if (char === "<")
+            angleDepth++;
+        else if (char === ">" && angleDepth > 0)
+            angleDepth--;
+        else if (char === "[")
+            bracketDepth++;
+        else if (char === "]" && bracketDepth > 0)
+            bracketDepth--;
+        else if (char === "{")
+            braceDepth++;
+        else if (char === "}" && braceDepth > 0)
+            braceDepth--;
+        else if (char === "(")
+            parenDepth++;
+        else if (char === ")" && parenDepth > 0)
+            parenDepth--;
+        else if ((char === "," || char === ";") && angleDepth === 0 && bracketDepth === 0 && braceDepth === 0 && parenDepth === 0) {
+            result.push(current);
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim()) {
+        result.push(current);
+    }
+    return result;
+}
+/**
+ * Parse input type fields from TFlowWeaverNodeType<{inputs}, {outputs}> syntax.
+ * Returns field names and their types from the first type parameter (input type).
+ */
+export function parseInputTypeFields(functionText) {
+    const genericStart = functionText.indexOf("TFlowWeaverNodeType<");
+    if (genericStart === -1)
+        return [];
+    let braceCount = 0;
+    let firstParamStart = -1;
+    let firstParamEnd = -1;
+    for (let i = genericStart + "TFlowWeaverNodeType<".length; i < functionText.length; i++) {
+        const char = functionText[i];
+        if (char === "{") {
+            if (braceCount === 0) {
+                firstParamStart = i + 1;
+            }
+            braceCount++;
+        }
+        else if (char === "}") {
+            braceCount--;
+            if (braceCount === 0) {
+                firstParamEnd = i;
+                break;
+            }
+        }
+    }
+    if (firstParamStart === -1 || firstParamEnd === -1)
+        return [];
+    const objectContent = functionText.substring(firstParamStart, firstParamEnd);
+    const fields = [];
+    const fieldParts = splitObjectFields(objectContent);
+    for (const part of fieldParts) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const colonMatch = trimmed.match(/^(\w+)\s*:\s*(.+)$/);
+        if (colonMatch) {
+            fields.push({ name: colonMatch[1], tsType: colonMatch[2].trim() });
+        }
+    }
+    return fields;
+}
+// =============================================================================
+// Type Mapping
+// =============================================================================
+/**
+ * Map TypeScript type to port type.
+ */
+export function tsTypeToPortType(tsType) {
+    if (!tsType)
+        return "ANY";
+    const normalized = tsType.trim().toLowerCase();
+    switch (normalized) {
+        case "number":
+            return "NUMBER";
+        case "string":
+            return "STRING";
+        case "boolean":
+            return "BOOLEAN";
+        case "any[]":
+        case "array":
+            return "ARRAY";
+        case "object":
+            return "OBJECT";
+        case "function":
+            return "FUNCTION";
+        default:
+            return "ANY";
+    }
+}
+/**
+ * Map port type to TypeScript type string.
+ */
+export function portTypeToTsType(portType) {
+    switch (portType) {
+        case "NUMBER":
+            return "number";
+        case "STRING":
+            return "string";
+        case "BOOLEAN":
+            return "boolean";
+        case "ARRAY":
+            return "any[]";
+        case "OBJECT":
+            return "any";
+        case "FUNCTION":
+            return "(...args: any[]) => any";
+        case "STEP":
+            return "boolean";
+        case "ANY":
+        default:
+            return "any";
+    }
+}
+// =============================================================================
+// Callback Type Parsing
+// =============================================================================
+/**
+ * Parse callback type string to extract params and return type.
+ * E.g., "(execute: boolean, item: string) => { result: number }"
+ */
+export function parseCallbackType(callbackType) {
+    const params = [];
+    const returnFields = [];
+    let returnType = "";
+    const arrowIdx = callbackType.indexOf("=>");
+    if (arrowIdx === -1)
+        return { params, returnType, returnFields };
+    const beforeArrow = callbackType.substring(0, arrowIdx).trim();
+    const openParen = beforeArrow.indexOf("(");
+    const closeParen = beforeArrow.lastIndexOf(")");
+    if (openParen === -1 || closeParen === -1)
+        return { params, returnType, returnFields };
+    const paramsStr = beforeArrow.substring(openParen + 1, closeParen);
+    const paramTokens = splitParams(paramsStr);
+    for (const token of paramTokens) {
+        const trimmed = token.trim();
+        if (!trimmed)
+            continue;
+        const colonIdx = trimmed.indexOf(":");
+        if (colonIdx !== -1) {
+            const name = trimmed.substring(0, colonIdx).trim().replace(/\?$/, "");
+            const typeStr = trimmed.substring(colonIdx + 1).trim();
+            params.push({ name, typeStr });
+        }
+    }
+    returnType = callbackType.substring(arrowIdx + 2).trim();
+    const returnMatch = returnType.match(/^\{\s*([\s\S]*?)\s*\}$/);
+    if (returnMatch) {
+        const fieldsStr = returnMatch[1];
+        const fieldParts = fieldsStr.split(/[;\n]/).filter(s => s.trim());
+        for (const part of fieldParts) {
+            const trimmed = part.trim();
+            if (!trimmed)
+                continue;
+            const colonIdx = trimmed.indexOf(":");
+            if (colonIdx !== -1) {
+                const name = trimmed.substring(0, colonIdx).trim();
+                const typeStr = trimmed.substring(colonIdx + 1).trim();
+                returnFields.push({ name, typeStr });
+            }
+        }
+    }
+    return { params, returnType, returnFields };
+}
+/**
+ * Build callback type string from scoped ports, preserving existing non-scoped params.
+ * Scoped OUTPUT ports → callback parameters
+ * Scoped INPUT ports → callback return type
+ */
+export function buildCallbackType(callbackParams, callbackReturns, existingCallbackType) {
+    const scopedParamNames = new Set(callbackParams.map(([name]) => name));
+    const scopedReturnNames = new Set(callbackReturns.map(([name]) => name));
+    const isParamsMultiline = existingCallbackType?.includes("(\n") || false;
+    const isReturnMultiline = existingCallbackType?.match(/=>\s*\{\n/) != null;
+    const scopedParamsList = callbackParams
+        .sort((a, b) => (a[1].metadata?.order ?? Infinity) - (b[1].metadata?.order ?? Infinity))
+        .map(([name, port]) => `${name}: ${portTypeToTsType(port.dataType)}`);
+    let preservedParams = [];
+    let preservedReturns = [];
+    if (existingCallbackType) {
+        const parsed = parseCallbackType(existingCallbackType);
+        preservedParams = parsed.params
+            .filter(({ name }) => !scopedParamNames.has(name))
+            .map(({ name, typeStr }) => `${name}: ${typeStr}`);
+        preservedReturns = parsed.returnFields
+            .filter(({ name }) => !scopedReturnNames.has(name))
+            .map(({ name, typeStr }) => `${name}: ${typeStr}`);
+    }
+    const allParamsList = [...preservedParams, ...scopedParamsList].filter(Boolean);
+    const scopedReturnFields = callbackReturns
+        .sort((a, b) => (a[1].metadata?.order ?? Infinity) - (b[1].metadata?.order ?? Infinity))
+        .map(([name, port]) => `${name}: ${portTypeToTsType(port.dataType)}`);
+    const allReturnFields = [...preservedReturns, ...scopedReturnFields];
+    let paramsStr;
+    if (isParamsMultiline && allParamsList.length > 0) {
+        paramsStr = `\n    ${allParamsList.join(",\n    ")},\n  `;
+    }
+    else {
+        paramsStr = allParamsList.join(", ");
+    }
+    if (isReturnMultiline && allReturnFields.length > 0) {
+        const returnFieldsStr = allReturnFields.map(f => `    ${f};`).join("\n");
+        return `(${paramsStr}) => {\n${returnFieldsStr}\n  }`;
+    }
+    else {
+        const returnFieldsStr = allReturnFields.join("; ");
+        return `(${paramsStr}) => { ${returnFieldsStr} }`;
+    }
+}
+/**
+ * Check if callback signature already has all required ports.
+ * Returns true if no update needed.
+ */
+export function callbackHasAllPorts(callbackType, callbackParams, callbackReturns) {
+    for (const [name] of callbackParams) {
+        const paramRegex = new RegExp(`\\b${name}\\s*:`);
+        if (!paramRegex.test(callbackType))
+            return false;
+    }
+    for (const [name] of callbackReturns) {
+        const arrowIdx = callbackType.indexOf("=>");
+        if (arrowIdx === -1)
+            return false;
+        const returnPart = callbackType.substring(arrowIdx);
+        const returnRegex = new RegExp(`\\b${name}\\s*:`);
+        if (!returnRegex.test(returnPart))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=signature-parser.js.map

package/dist/jsdoc-port-sync/sync.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module jsdoc-port-sync/sync
+ *
+ * Bidirectional sync between JSDoc annotations and TypeScript signatures.
+ * - syncSignatureToJSDoc: Code → JSDoc (regenerate tags from signature)
+ * - syncJSDocToSignature: JSDoc → Code (add params/fields to signature)
+ */
+import type { TPortDefinition } from "../ast/types.js";
+/**
+ * Sync function signature to JSDoc (Code → JSDoc).
+ *
+ * **What it does:**
+ * - Adds `@input` tags for params in signature but not in JSDoc
+ * - Adds `@output` tags for return fields not in JSDoc
+ * - Removes orphan `@input`/`@output` tags (port deleted from signature)
+ * - Preserves existing JSDoc content (description, `@label`, etc.)
+ *
+ * **When to call:** Only on explicit format (Ctrl+P), NOT every keystroke.
+ */
+export declare function syncSignatureToJSDoc(functionText: string): string;
+/**
+ * Sync JSDoc to function signature (JSDoc → Code).
+ *
+ * **What it does:**
+ * - Adds missing params from `@input` tags to function signature
+ * - Updates return type with fields from `@output` tags
+ * - Ensures `execute: boolean` is first param
+ * - Builds/updates callback types for scoped ports
+ *
+ * **When to call:** On every keystroke during editing.
+ */
+export declare function syncJSDocToSignature(functionText: string, authoritativePorts?: {
+    inputs?: Record<string, TPortDefinition>;
+    outputs?: Record<string, TPortDefinition>;
+}): string;
+//# sourceMappingURL=sync.d.ts.map