@synergenius/flow-weaver 0.2.0

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

@@ -0,0 +1,68 @@
+/**
+ * @module jsdoc-port-sync/port-parser
+ *
+ * Parse and update @input/@output/@step annotations in JSDoc.
+ * Uses Chevrotain for parsing, browser-compatible.
+ */
+import type { TPortDefinition } from '../ast/types.js';
+/**
+ * Check if the code has any @scope declarations in JSDoc.
+ * Used to automatically determine if the node should be in scoped mode.
+ *
+ * @param functionText - The function text containing JSDoc
+ * @returns true if the code has @scope declarations, false otherwise
+ */
+export declare function hasScopes(functionText: string): boolean;
+/**
+ * Get all scope names declared in the code via @scope tags.
+ *
+ * @param functionText - The function text containing JSDoc
+ * @returns Array of scope names
+ */
+export declare function getScopeNames(functionText: string): string[];
+/**
+ * Check if the code has any orphan port lines (type but no name).
+ * Used to skip rename detection when user is editing port names.
+ */
+export declare function hasOrphanPortLines(functionText: string): {
+    inputs: boolean;
+    outputs: boolean;
+};
+/**
+ * Extract port names from incomplete JSDoc lines.
+ * These are lines where the user is still typing.
+ * Used to prevent generating duplicate tags for ports being edited.
+ */
+export declare function getIncompletePortNames(functionText: string): {
+    inputs: Set<string>;
+    outputs: Set<string>;
+    steps: Set<string>;
+};
+/**
+ * Check if a line is incomplete (port tag but not fully valid).
+ * Also detects "incomplete description" patterns like "@input name -" (dash but no text).
+ */
+export declare function isIncompletePortLine(line: string): boolean;
+/**
+ * Parse @input/@output/@step annotations from function text.
+ * Uses Chevrotain for parsing, browser-compatible.
+ *
+ * Types are derived from signature, not JSDoc:
+ * - JSDoc provides metadata: name, optional, default, scope, label, order, placement
+ * - Types are inferred from function signature using inferDataTypeFromTS()
+ * - @step annotation marks explicit STEP/control-flow ports
+ * - Reserved ports (execute, onSuccess, onFailure) auto-detect as STEP
+ */
+export declare function parsePortsFromFunctionText(functionText: string): {
+    inputs: Record<string, TPortDefinition>;
+    outputs: Record<string, TPortDefinition>;
+};
+/**
+ * Update @input/@output annotations in function text.
+ * Preserves other JSDoc content (description, @label, @scope, etc.).
+ *
+ * @param signatureInputOrder - Optional array of input names in signature order.
+ *        When provided, new inputs are inserted at the correct position based on signature.
+ */
+export declare function updatePortsInFunctionText(functionText: string, inputs: Record<string, TPortDefinition>, outputs: Record<string, TPortDefinition>, signatureInputOrder?: string[]): string;
+//# sourceMappingURL=port-parser.d.ts.map

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

@@ -0,0 +1,579 @@
+/**
+ * @module jsdoc-port-sync/port-parser
+ *
+ * Parse and update @input/@output/@step annotations in JSDoc.
+ * Uses Chevrotain for parsing, browser-compatible.
+ */
+import { generateJSDocPortTag } from '../annotation-generator.js';
+import { isExecutePort, isSuccessPort, isFailurePort, isScopedMandatoryPort } from '../constants.js';
+import { inferDataTypeFromTS } from '../type-mappings.js';
+import { parsePortLine, parsePortsFromJSDoc, isValidPortLine as chevrotainIsValidPortLine, } from '../chevrotain-parser/port-parser.js';
+import { JSDOC_BLOCK_REGEX, PORT_TAG_REGEX, ORPHAN_PORT_LINE_REGEX } from './constants.js';
+import { parseFunctionSignature, parseReturnTypeFieldsWithTypes } from './signature-parser.js';
+// =============================================================================
+// Scope Detection
+// =============================================================================
+/** Match @scope tags: @scope name */
+const SCOPE_TAG_REGEX = /\*\s*@scope\s+(\w+)/g;
+/**
+ * Check if the code has any @scope declarations in JSDoc.
+ * Used to automatically determine if the node should be in scoped mode.
+ *
+ * @param functionText - The function text containing JSDoc
+ * @returns true if the code has @scope declarations, false otherwise
+ */
+export function hasScopes(functionText) {
+    const jsdocMatch = functionText.match(JSDOC_BLOCK_REGEX);
+    if (!jsdocMatch)
+        return false;
+    SCOPE_TAG_REGEX.lastIndex = 0;
+    return SCOPE_TAG_REGEX.test(jsdocMatch[0]);
+}
+/**
+ * Get all scope names declared in the code via @scope tags.
+ *
+ * @param functionText - The function text containing JSDoc
+ * @returns Array of scope names
+ */
+export function getScopeNames(functionText) {
+    const jsdocMatch = functionText.match(JSDOC_BLOCK_REGEX);
+    if (!jsdocMatch)
+        return [];
+    const scopes = [];
+    SCOPE_TAG_REGEX.lastIndex = 0;
+    let match;
+    while ((match = SCOPE_TAG_REGEX.exec(jsdocMatch[0])) != null) {
+        scopes.push(match[1]);
+    }
+    return scopes;
+}
+// =============================================================================
+// Orphan/Incomplete Port Detection
+// =============================================================================
+/**
+ * Check if the code has any orphan port lines (type but no name).
+ * Used to skip rename detection when user is editing port names.
+ */
+export function hasOrphanPortLines(functionText) {
+    const jsdocMatch = functionText.match(JSDOC_BLOCK_REGEX);
+    if (!jsdocMatch)
+        return { inputs: false, outputs: false };
+    const lines = jsdocMatch[0].split('\n');
+    let hasOrphanInputs = false;
+    let hasOrphanOutputs = false;
+    for (const line of lines) {
+        const orphanMatch = line.match(ORPHAN_PORT_LINE_REGEX);
+        if (orphanMatch) {
+            const [, tagType] = orphanMatch;
+            if (tagType === 'input')
+                hasOrphanInputs = true;
+            else
+                hasOrphanOutputs = true;
+        }
+    }
+    return { inputs: hasOrphanInputs, outputs: hasOrphanOutputs };
+}
+/**
+ * Extract port names from incomplete JSDoc lines.
+ * These are lines where the user is still typing.
+ * Used to prevent generating duplicate tags for ports being edited.
+ */
+export function getIncompletePortNames(functionText) {
+    const inputs = new Set();
+    const outputs = new Set();
+    const steps = new Set();
+    const jsdocMatch = functionText.match(JSDOC_BLOCK_REGEX);
+    if (!jsdocMatch)
+        return { inputs, outputs, steps };
+    const lines = jsdocMatch[0].split('\n');
+    for (const line of lines) {
+        // Check if it looks like a port line but doesn't parse
+        if (!PORT_TAG_REGEX.test(line))
+            continue;
+        if (chevrotainIsValidPortLine(line))
+            continue;
+        // Try to extract partial port name from incomplete line
+        const partialMatch = line.match(/\*\s*@(input|output|step)\s+\[?(\w+)/);
+        if (partialMatch) {
+            const [, tagType, portName] = partialMatch;
+            if (tagType === 'input') {
+                inputs.add(portName);
+            }
+            else if (tagType === 'output') {
+                outputs.add(portName);
+            }
+            else if (tagType === 'step') {
+                steps.add(portName);
+            }
+        }
+    }
+    return { inputs, outputs, steps };
+}
+/**
+ * Check if a line is incomplete (port tag but not fully valid).
+ * Also detects "incomplete description" patterns like "@input name -" (dash but no text).
+ */
+export function isIncompletePortLine(line) {
+    if (!PORT_TAG_REGEX.test(line))
+        return false;
+    // Check if Chevrotain considers it invalid
+    if (!chevrotainIsValidPortLine(line))
+        return true;
+    // Also treat trailing dash (user typing description) as incomplete
+    const cleanLine = line.replace(/^\s*\*\s*/, '').trim();
+    if (/\s-\s*$/.test(cleanLine))
+        return true;
+    return false;
+}
+// =============================================================================
+// Port Parsing
+// =============================================================================
+/**
+ * Parse @input/@output/@step annotations from function text.
+ * Uses Chevrotain for parsing, browser-compatible.
+ *
+ * Types are derived from signature, not JSDoc:
+ * - JSDoc provides metadata: name, optional, default, scope, label, order, placement
+ * - Types are inferred from function signature using inferDataTypeFromTS()
+ * - @step annotation marks explicit STEP/control-flow ports
+ * - Reserved ports (execute, onSuccess, onFailure) auto-detect as STEP
+ */
+export function parsePortsFromFunctionText(functionText) {
+    const inputs = {};
+    const outputs = {};
+    const jsdocMatch = functionText.match(JSDOC_BLOCK_REGEX);
+    if (!jsdocMatch) {
+        return { inputs, outputs };
+    }
+    const jsdoc = jsdocMatch[0];
+    // Parse function signature to get types
+    const { params } = parseFunctionSignature(functionText);
+    const returnFields = parseReturnTypeFieldsWithTypes(functionText);
+    // Build lookup maps for signature types and optionality
+    const paramTypeMap = new Map();
+    const paramOptionalMap = new Map();
+    for (const param of params) {
+        if (param.tsType) {
+            paramTypeMap.set(param.name, param.tsType);
+        }
+        if (param.optional) {
+            paramOptionalMap.set(param.name, true);
+        }
+    }
+    const returnTypeMap = new Map();
+    for (const field of returnFields) {
+        returnTypeMap.set(field.name, field.tsType);
+    }
+    // Parse @scope declarations from JSDoc
+    const declaredScopes = new Set();
+    SCOPE_TAG_REGEX.lastIndex = 0;
+    let scopeMatch;
+    while ((scopeMatch = SCOPE_TAG_REGEX.exec(jsdoc)) != null) {
+        declaredScopes.add(scopeMatch[1]);
+    }
+    // Get valid scope names from @scope tags
+    // Also infer from callback parameters as fallback
+    const inferredScopes = new Set(params.filter((p) => p.tsType?.includes('=>')).map((p) => p.name));
+    // Combine declared @scope tags with inferred callback scopes
+    const allKnownScopes = new Set([...declaredScopes, ...inferredScopes]);
+    // If any scope is declared/known, accept any scope: attribute value
+    // This allows @scope processItem with scope:iteration - user knows what they're doing
+    const hasAnyScope = allKnownScopes.size > 0;
+    const validateScope = (scope) => {
+        if (!scope)
+            return undefined;
+        // If we have any declared/inferred scopes, accept any scope attribute
+        // (user may use different naming convention)
+        if (hasAnyScope)
+            return scope;
+        return undefined;
+    };
+    // Parse ports using Chevrotain
+    const portResults = parsePortsFromJSDoc(jsdoc);
+    for (const port of portResults) {
+        const { type, name, scope, order, placement, description, defaultValue, isOptional } = port;
+        if (type === 'step') {
+            // @step ports are always STEP type
+            const portDef = {
+                dataType: 'STEP',
+                ...(description && { label: description }),
+            };
+            // Determine if input or output from signature
+            const isInput = paramTypeMap.has(name);
+            const isOutput = returnTypeMap.has(name);
+            if (isInput) {
+                inputs[name] = portDef;
+            }
+            else if (isOutput) {
+                outputs[name] = portDef;
+            }
+            else {
+                // Default to output for custom STEP ports
+                outputs[name] = portDef;
+            }
+            continue;
+        }
+        if (type === 'input') {
+            // First port wins - skip duplicates
+            if (inputs[name])
+                continue;
+            const validatedScope = validateScope(scope);
+            // Determine type from signature or default to ANY
+            let dataType;
+            let tsType;
+            // Reserved external STEP ports (execute) are always STEP
+            // Scoped mandatory ports (success, failure) are STEP only when scoped
+            const isExternalStepPort = isExecutePort(name);
+            const isScopedStepPort = validatedScope && isScopedMandatoryPort(name);
+            if (isExternalStepPort || isScopedStepPort) {
+                dataType = 'STEP';
+            }
+            else {
+                tsType = paramTypeMap.get(name);
+                dataType = tsType ? inferDataTypeFromTS(tsType) : 'ANY';
+            }
+            // Optional if marked in JSDoc or in signature
+            const signatureOptional = paramOptionalMap.get(name) || false;
+            const portOptional = isOptional || signatureOptional;
+            const metadata = {};
+            if (order !== undefined)
+                metadata.order = order;
+            if (placement)
+                metadata.placement = placement;
+            inputs[name] = {
+                dataType,
+                ...(tsType && { tsType }),
+                ...(portOptional && { optional: true }),
+                ...(defaultValue && { default: parseDefaultValue(defaultValue) }),
+                ...(validatedScope && { scope: validatedScope }),
+                ...(description && { label: description }),
+                ...(Object.keys(metadata).length > 0 && { metadata }),
+            };
+        }
+        if (type === 'output') {
+            // First port wins - skip duplicates
+            if (outputs[name])
+                continue;
+            const validatedScope = validateScope(scope);
+            // Determine type from signature or default to ANY
+            let dataType;
+            let tsType;
+            // Reserved external STEP ports (onSuccess, onFailure) are always STEP
+            // Scoped mandatory ports (start, success, failure) are STEP only when scoped
+            const isExternalStepPort = isSuccessPort(name) || isFailurePort(name);
+            const isScopedStepPort = validatedScope && isScopedMandatoryPort(name);
+            if (isExternalStepPort || isScopedStepPort) {
+                dataType = 'STEP';
+            }
+            else {
+                tsType = returnTypeMap.get(name);
+                dataType = tsType ? inferDataTypeFromTS(tsType) : 'ANY';
+            }
+            const metadata = {};
+            if (order !== undefined)
+                metadata.order = order;
+            if (placement)
+                metadata.placement = placement;
+            outputs[name] = {
+                dataType,
+                ...(tsType && { tsType }),
+                ...(validatedScope && { scope: validatedScope }),
+                ...(description && { label: description }),
+                ...(Object.keys(metadata).length > 0 && { metadata }),
+            };
+        }
+    }
+    return { inputs, outputs };
+}
+// =============================================================================
+// Port Update
+// =============================================================================
+/**
+ * Update @input/@output annotations in function text.
+ * Preserves other JSDoc content (description, @label, @scope, etc.).
+ *
+ * @param signatureInputOrder - Optional array of input names in signature order.
+ *        When provided, new inputs are inserted at the correct position based on signature.
+ */
+export function updatePortsInFunctionText(functionText, inputs, outputs, signatureInputOrder) {
+    const jsdocMatch = functionText.match(JSDOC_BLOCK_REGEX);
+    // Get port names from incomplete JSDoc lines (user still typing)
+    const incompletePortNames = getIncompletePortNames(functionText);
+    // Generate new port tags (skip ports with incomplete lines)
+    const inputTags = Object.entries(inputs)
+        .filter(([name]) => !incompletePortNames.inputs.has(name))
+        .map(([name, port]) => ` * ${generateJSDocPortTag(name, port, 'input')}`);
+    const outputTags = Object.entries(outputs)
+        .filter(([name]) => !incompletePortNames.outputs.has(name))
+        .map(([name, port]) => ` * ${generateJSDocPortTag(name, port, 'output')}`);
+    if (!jsdocMatch) {
+        // No existing JSDoc - create new one
+        const newJsDoc = ['/**', ' * @flowWeaver nodeType', ...inputTags, ...outputTags, ' */'].join('\n');
+        return newJsDoc + '\n' + functionText;
+    }
+    // Parse existing JSDoc to preserve non-port content
+    const existingJsDoc = jsdocMatch[0];
+    const lines = existingJsDoc.split('\n');
+    const preservedLines = [];
+    let hasFlowWeaverTag = false;
+    // Track which ports we've seen in the existing JSDoc
+    const seenInputs = new Set();
+    const seenOutputs = new Set();
+    // Track orphan incomplete lines
+    const orphanInputLines = [];
+    const orphanOutputLines = [];
+    // Track last input/output line indices for proper insertion ordering
+    let lastInputLineIndex = -1;
+    let lastOutputLineIndex = -1;
+    for (const line of lines) {
+        // Always preserve opening and closing
+        if (line.trim() === '/**' || line.trim() === '*/') {
+            preservedLines.push(line);
+            continue;
+        }
+        // Check if this is a port line
+        if (PORT_TAG_REGEX.test(line)) {
+            // Check if this is an orphan line (just tag, no name)
+            const orphanMatch = line.match(ORPHAN_PORT_LINE_REGEX);
+            if (orphanMatch) {
+                const [, tagType] = orphanMatch;
+                const lineIndex = preservedLines.length;
+                preservedLines.push(line);
+                if (tagType === 'input') {
+                    orphanInputLines.push({ index: lineIndex, type: 'ANY' });
+                    lastInputLineIndex = lineIndex;
+                }
+                else if (tagType === 'output' || tagType === 'step') {
+                    orphanOutputLines.push({ index: lineIndex, type: 'ANY' });
+                    lastOutputLineIndex = lineIndex;
+                }
+                continue;
+            }
+            // Preserve incomplete port lines (user still typing)
+            if (isIncompletePortLine(line)) {
+                const lineIndex = preservedLines.length;
+                preservedLines.push(line);
+                const partialMatch = line.match(/\*\s*@(input|output|step)\s+\[?(\w+)/);
+                if (partialMatch) {
+                    const [, tagType, portName] = partialMatch;
+                    if (tagType === 'input') {
+                        seenInputs.add(portName);
+                        lastInputLineIndex = lineIndex;
+                    }
+                    else if (tagType === 'output') {
+                        seenOutputs.add(portName);
+                        lastOutputLineIndex = lineIndex;
+                    }
+                    else if (tagType === 'step') {
+                        seenInputs.add(portName);
+                        seenOutputs.add(portName);
+                    }
+                }
+                continue;
+            }
+            // Parse the port line using Chevrotain
+            const cleanLine = line.replace(/^\s*\*\s*/, '').trim();
+            const parsed = parsePortLine(cleanLine, []);
+            if (parsed) {
+                const lineIndex = preservedLines.length;
+                if (parsed.type === 'input') {
+                    if (!inputs[parsed.name])
+                        continue; // Port removed
+                    preservedLines.push(line.trimEnd());
+                    seenInputs.add(parsed.name);
+                    lastInputLineIndex = lineIndex;
+                }
+                else if (parsed.type === 'output') {
+                    if (!outputs[parsed.name])
+                        continue; // Port removed
+                    preservedLines.push(line.trimEnd());
+                    seenOutputs.add(parsed.name);
+                    lastOutputLineIndex = lineIndex;
+                }
+                else if (parsed.type === 'step') {
+                    const isInput = inputs[parsed.name] !== undefined;
+                    const isOutput = outputs[parsed.name] !== undefined;
+                    if (!isInput && !isOutput)
+                        continue; // Port removed
+                    preservedLines.push(line.trimEnd());
+                    if (isInput) {
+                        seenInputs.add(parsed.name);
+                        lastInputLineIndex = lineIndex;
+                    }
+                    if (isOutput) {
+                        seenOutputs.add(parsed.name);
+                        lastOutputLineIndex = lineIndex;
+                    }
+                }
+                continue;
+            }
+            // Port tag but doesn't parse - preserve it
+            preservedLines.push(line);
+            continue;
+        }
+        // Track if we have @flowWeaver tag
+        if (line.includes('@flowWeaver')) {
+            hasFlowWeaverTag = true;
+        }
+        // Preserve all other lines
+        preservedLines.push(line);
+    }
+    // Build new JSDoc
+    const newLines = [...preservedLines];
+    // If no @flowWeaver tag, add it
+    if (!hasFlowWeaverTag) {
+        newLines.splice(1, 0, ' * @flowWeaver nodeType');
+    }
+    // Find ports that need to be added (not already in JSDoc)
+    const inputsToAdd = Object.entries(inputs).filter(([name]) => !seenInputs.has(name) && !incompletePortNames.inputs.has(name));
+    const outputsToAdd = Object.entries(outputs).filter(([name]) => !seenOutputs.has(name) && !incompletePortNames.outputs.has(name));
+    // Fill in orphan lines first
+    const remainingInputsToAdd = [];
+    for (const [name, port] of inputsToAdd) {
+        const orphanIndex = orphanInputLines.findIndex((o) => o.type === port.dataType);
+        if (orphanIndex !== -1) {
+            const orphan = orphanInputLines[orphanIndex];
+            newLines[orphan.index] = ` * ${generateJSDocPortTag(name, port, 'input')}`;
+            orphanInputLines.splice(orphanIndex, 1);
+        }
+        else if (orphanInputLines.length > 0) {
+            const orphan = orphanInputLines.shift();
+            newLines[orphan.index] = ` * ${generateJSDocPortTag(name, port, 'input')}`;
+        }
+        else {
+            remainingInputsToAdd.push([name, port]);
+        }
+    }
+    const remainingOutputsToAdd = [];
+    for (const [name, port] of outputsToAdd) {
+        const orphanIndex = orphanOutputLines.findIndex((o) => o.type === port.dataType);
+        if (orphanIndex !== -1) {
+            const orphan = orphanOutputLines[orphanIndex];
+            newLines[orphan.index] = ` * ${generateJSDocPortTag(name, port, 'output')}`;
+            orphanOutputLines.splice(orphanIndex, 1);
+        }
+        else if (orphanOutputLines.length > 0) {
+            const orphan = orphanOutputLines.shift();
+            newLines[orphan.index] = ` * ${generateJSDocPortTag(name, port, 'output')}`;
+        }
+        else {
+            remainingOutputsToAdd.push([name, port]);
+        }
+    }
+    // Generate tags for remaining ports
+    const newOutputTags = remainingOutputsToAdd.map(([name, port]) => ` * ${generateJSDocPortTag(name, port, 'output')}`);
+    // Insert NEW port tags at proper positions
+    const closingIndex = newLines.findIndex((l) => l.trim() === '*/');
+    if (newOutputTags.length > 0) {
+        const outputInsertIndex = lastOutputLineIndex >= 0
+            ? lastOutputLineIndex + 1
+            : lastInputLineIndex >= 0
+                ? lastInputLineIndex + 1
+                : closingIndex;
+        newLines.splice(outputInsertIndex, 0, ...newOutputTags);
+    }
+    if (remainingInputsToAdd.length > 0) {
+        const flowWeaverIndex = newLines.findIndex((l) => l.includes('@flowWeaver'));
+        // Separate scoped inputs from non-scoped inputs
+        const scopedInputsToAdd = remainingInputsToAdd.filter(([_, port]) => port.scope);
+        const nonScopedInputsToAdd = remainingInputsToAdd.filter(([_, port]) => !port.scope);
+        if (signatureInputOrder && signatureInputOrder.length > 0 && nonScopedInputsToAdd.length > 0) {
+            // Build a map of existing input names to their line indices
+            const existingInputLineIndices = {};
+            for (let i = 0; i < newLines.length; i++) {
+                const line = newLines[i];
+                const cleanLine = line.replace(/^\s*\*\s*/, '').trim();
+                const parsed = parsePortLine(cleanLine, []);
+                if (parsed && parsed.type === 'input') {
+                    existingInputLineIndices[parsed.name] = i;
+                }
+            }
+            // Insert each new non-scoped input at the correct position
+            const sortedInputsToAdd = nonScopedInputsToAdd
+                .map(([name, port]) => ({
+                name,
+                port,
+                sigIndex: signatureInputOrder.indexOf(name),
+            }))
+                .filter((item) => item.sigIndex !== -1)
+                .sort((a, b) => b.sigIndex - a.sigIndex);
+            for (const { name, port, sigIndex } of sortedInputsToAdd) {
+                const newTag = ` * ${generateJSDocPortTag(name, port, 'input')}`;
+                let insertIndex = -1;
+                for (let i = sigIndex + 1; i < signatureInputOrder.length; i++) {
+                    const nextName = signatureInputOrder[i];
+                    if (existingInputLineIndices[nextName] !== undefined) {
+                        insertIndex = existingInputLineIndices[nextName];
+                        break;
+                    }
+                }
+                if (insertIndex !== -1) {
+                    newLines.splice(insertIndex, 0, newTag);
+                    for (const [portName, idx] of Object.entries(existingInputLineIndices)) {
+                        if (idx >= insertIndex) {
+                            existingInputLineIndices[portName] = idx + 1;
+                        }
+                    }
+                    existingInputLineIndices[name] = insertIndex;
+                }
+                else {
+                    for (let i = sigIndex - 1; i >= 0; i--) {
+                        const prevName = signatureInputOrder[i];
+                        if (existingInputLineIndices[prevName] !== undefined) {
+                            insertIndex = existingInputLineIndices[prevName] + 1;
+                            break;
+                        }
+                    }
+                    if (insertIndex === -1) {
+                        insertIndex = flowWeaverIndex >= 0 ? flowWeaverIndex + 1 : 1;
+                    }
+                    newLines.splice(insertIndex, 0, newTag);
+                    for (const [portName, idx] of Object.entries(existingInputLineIndices)) {
+                        if (idx >= insertIndex) {
+                            existingInputLineIndices[portName] = idx + 1;
+                        }
+                    }
+                    existingInputLineIndices[name] = insertIndex;
+                }
+            }
+        }
+        else if (nonScopedInputsToAdd.length > 0) {
+            const nonScopedInputTags = nonScopedInputsToAdd.map(([name, port]) => ` * ${generateJSDocPortTag(name, port, 'input')}`);
+            const inputInsertIndex = lastInputLineIndex >= 0
+                ? lastInputLineIndex + 1
+                : flowWeaverIndex >= 0
+                    ? flowWeaverIndex + 1
+                    : 1;
+            newLines.splice(inputInsertIndex, 0, ...nonScopedInputTags);
+        }
+        // Insert scoped inputs after outputs (standard port order: inputs, scoped outputs, scoped inputs, outputs)
+        if (scopedInputsToAdd.length > 0) {
+            const scopedInputTags = scopedInputsToAdd.map(([name, port]) => ` * ${generateJSDocPortTag(name, port, 'input')}`);
+            // Insert after the last output line, or after inputs if no outputs
+            const closingIdx = newLines.findIndex((l) => l.trim() === '*/');
+            const insertIdx = lastOutputLineIndex >= 0
+                ? lastOutputLineIndex + 1
+                : closingIdx >= 0
+                    ? closingIdx
+                    : newLines.length - 1;
+            newLines.splice(insertIdx, 0, ...scopedInputTags);
+        }
+    }
+    const newJsDoc = newLines.join('\n');
+    return functionText.replace(JSDOC_BLOCK_REGEX, newJsDoc);
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Parse default value from string.
+ */
+function parseDefaultValue(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+//# sourceMappingURL=port-parser.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * @module jsdoc-port-sync/rename
+ *
+ * Port renaming and code rename synchronization.
+ */
+/**
+ * Rename a port in both JSDoc and function signature.
+ * For input ports: renames @input tag and function parameter
+ * For output ports: renames @output tag and return type field
+ * For scoped ports: also updates callback parameter/return names
+ */
+export declare function renamePortInCode(code: string, oldPortName: string, newPortName: string, portType: "input" | "output"): string;
+/**
+ * Sync renames between JSDoc ports and function signature using before/after diff.
+ *
+ * @param previousCode - The code before the edit
+ * @param currentCode - The code after the edit
+ * @returns The synchronized code
+ */
+export declare function syncCodeRenames(previousCode: string, currentCode: string): string;
+//# sourceMappingURL=rename.d.ts.map