@synergenius/flow-weaver 0.2.0

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

@@ -0,0 +1,41 @@
+/**
+ * @module jsdoc-port-sync/constants
+ *
+ * Regex patterns and helper functions for JSDoc port parsing.
+ * Browser-compatible (no ts-morph dependency).
+ *
+ * NOTE: Port parsing now uses Chevrotain. These patterns are for
+ * JSDoc block detection, validation, and edge cases only.
+ */
+/** Match JSDoc block */
+export declare const JSDOC_BLOCK_REGEX: RegExp;
+/** Detect port-related lines (input, output, step) */
+export declare const PORT_TAG_REGEX: RegExp;
+/** Regex to detect orphan incomplete lines (tag but no name) */
+export declare const ORPHAN_PORT_LINE_REGEX: RegExp;
+/** Detect @scope declarations (global flag for iterating) */
+export declare const SCOPE_TAG_REGEX: RegExp;
+/** Match function declaration start: function name( */
+export declare const FUNC_DECL_START: RegExp;
+/** Match arrow function start: const/let/var name = ( */
+export declare const ARROW_START: RegExp;
+/** Match return object: return { ... } */
+export declare const RETURN_OBJECT_REGEX: RegExp;
+/** Reserved parameter names to skip */
+export declare const RESERVED_PARAMS: string[];
+/** Reserved return field names to skip */
+export declare const RESERVED_RETURN_FIELDS: string[];
+/**
+ * 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;
+/**
+ * Find the index of the closing paren/brace that matches the opening at startIndex.
+ */
+export declare function findBalancedClose(text: string, startIndex: number): number;
+/**
+ * Split parameters string by comma, handling nested braces, parens, and angles
+ */
+export declare function splitParams(paramsStr: string): string[];
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1,103 @@
+/**
+ * @module jsdoc-port-sync/constants
+ *
+ * Regex patterns and helper functions for JSDoc port parsing.
+ * Browser-compatible (no ts-morph dependency).
+ *
+ * NOTE: Port parsing now uses Chevrotain. These patterns are for
+ * JSDoc block detection, validation, and edge cases only.
+ */
+import { isExecutePort, isSuccessPort, isFailurePort, isScopedMandatoryPort } from "../constants.js";
+// =============================================================================
+// JSDoc Block Regex
+// =============================================================================
+/** Match JSDoc block */
+export const JSDOC_BLOCK_REGEX = /\/\*\*[\s\S]*?\*\//;
+// =============================================================================
+// Port Tag Detection (not parsing - Chevrotain handles that)
+// =============================================================================
+/** Detect port-related lines (input, output, step) */
+export const PORT_TAG_REGEX = /^\s*\*\s*@(input|output|step)\b/;
+/** Regex to detect orphan incomplete lines (tag but no name) */
+export const ORPHAN_PORT_LINE_REGEX = /^\s*\*\s*@(input|output|step)\s*$/;
+/** Detect @scope declarations (global flag for iterating) */
+export const SCOPE_TAG_REGEX = /@scope\s+(\w+)/g;
+// =============================================================================
+// Function Signature Regexes
+// =============================================================================
+/** Match function declaration start: function name( */
+export const FUNC_DECL_START = /(?:async\s+)?function\s+\w+\s*\(/;
+/** Match arrow function start: const/let/var name = ( */
+export const ARROW_START = /(?:const|let|var)\s+\w+\s*=\s*(?:async\s*)?\(/;
+/** Match return object: return { ... } */
+export const RETURN_OBJECT_REGEX = /return\s*\{([^}]+)\}/g;
+// =============================================================================
+// Reserved Names
+// =============================================================================
+/** Reserved parameter names to skip */
+export const RESERVED_PARAMS = ["execute"];
+/** Reserved return field names to skip */
+export const RESERVED_RETURN_FIELDS = ["onSuccess", "onFailure"];
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * 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);
+}
+/**
+ * Find the index of the closing paren/brace that matches the opening at startIndex.
+ */
+export function findBalancedClose(text, startIndex) {
+    const openChar = text[startIndex];
+    const closeChar = openChar === "(" ? ")" : openChar === "{" ? "}" : "]";
+    let depth = 1;
+    for (let i = startIndex + 1; i < text.length; i++) {
+        if (text[i] === openChar)
+            depth++;
+        else if (text[i] === closeChar) {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Split parameters string by comma, handling nested braces, parens, and angles
+ */
+export function splitParams(paramsStr) {
+    const result = [];
+    let current = "";
+    let braceDepth = 0;
+    let angleDepth = 0;
+    let parenDepth = 0;
+    for (const char of paramsStr) {
+        if (char === "{")
+            braceDepth++;
+        else if (char === "}")
+            braceDepth--;
+        else if (char === "<")
+            angleDepth++;
+        else if (char === ">" && angleDepth > 0)
+            angleDepth--;
+        else if (char === "(")
+            parenDepth++;
+        else if (char === ")")
+            parenDepth--;
+        else if (char === "," && braceDepth === 0 && angleDepth === 0 && parenDepth === 0) {
+            result.push(current);
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim()) {
+        result.push(current);
+    }
+    return result;
+}
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,76 @@
+/**
+ * @module jsdoc-port-sync/diff
+ *
+ * Port diff system for UI sync without regeneration.
+ */
+import type { TPortDefinition } from "../ast/types.js";
+/**
+ * Represents a diff between two port arrays
+ */
+export interface TPortDiff {
+    added: Array<{
+        name: string;
+        type: string;
+        direction: "INPUT" | "OUTPUT";
+        label?: string;
+        scope?: string;
+        placement?: string;
+    }>;
+    removed: Array<{
+        name: string;
+        direction: "INPUT" | "OUTPUT";
+    }>;
+    renamed: Array<{
+        from: string;
+        to: string;
+        direction: "INPUT" | "OUTPUT";
+    }>;
+    labelChanged: Array<{
+        name: string;
+        label: string;
+        direction: "INPUT" | "OUTPUT";
+        type: string;
+        scope?: string;
+    }>;
+    typeChanged: Array<{
+        name: string;
+        type: string;
+        direction: "INPUT" | "OUTPUT";
+    }>;
+}
+/**
+ * Compute the diff between two port arrays.
+ * Used to detect what changed when user edits ports via UI.
+ */
+export declare function computePortsDiff(before: Array<{
+    name: string;
+    type: string;
+    direction: string;
+    label?: string;
+    scope?: string;
+    placement?: string;
+}>, after: Array<{
+    name: string;
+    type: string;
+    direction: string;
+    label?: string;
+    scope?: string;
+    placement?: string;
+}>): TPortDiff;
+/**
+ * Format/regenerate all port tags in JSDoc.
+ * AGGRESSIVE MODE - for Cmd+Shift+P formatting.
+ *
+ * Unlike updatePortsInFunctionText() which preserves incomplete lines,
+ * this function:
+ * 1. Removes ALL existing port lines (valid or invalid)
+ * 2. Regenerates them in proper order based on [order:N] metadata
+ * 3. Ensures consistent formatting
+ */
+export declare function formatPortsInFunctionText(functionText: string, inputs: Record<string, TPortDefinition>, outputs: Record<string, TPortDefinition>): string;
+/**
+ * Apply a port diff to code without regenerating existing lines.
+ * This preserves incomplete/in-progress lines the user is typing.
+ */
+export declare function applyPortsDiffToCode(code: string, diff: TPortDiff): string;
+//# sourceMappingURL=diff.d.ts.map

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

@@ -0,0 +1,319 @@
+/**
+ * @module jsdoc-port-sync/diff
+ *
+ * Port diff system for UI sync without regeneration.
+ */
+import { generateJSDocPortTag } from "../annotation-generator.js";
+import { JSDOC_BLOCK_REGEX, PORT_TAG_REGEX } from "./constants.js";
+import { portTypeToTsType } from "./signature-parser.js";
+// =============================================================================
+// Diff Computation
+// =============================================================================
+/**
+ * Compute the diff between two port arrays.
+ * Used to detect what changed when user edits ports via UI.
+ */
+export function computePortsDiff(before, after) {
+    const diff = { added: [], removed: [], renamed: [], labelChanged: [], typeChanged: [] };
+    const beforeMap = new Map(before.map(p => [p.name, p]));
+    const afterMap = new Map(after.map(p => [p.name, p]));
+    // Find removed ports
+    for (const [name, port] of beforeMap) {
+        if (!afterMap.has(name)) {
+            diff.removed.push({ name, direction: port.direction });
+        }
+    }
+    // Find added ports, label changes, and type changes
+    for (const [name, port] of afterMap) {
+        if (!beforeMap.has(name)) {
+            diff.added.push({
+                name,
+                type: port.type,
+                direction: port.direction,
+                label: port.label,
+                scope: port.scope,
+                placement: port.placement
+            });
+        }
+        else {
+            const beforePort = beforeMap.get(name);
+            if (beforePort.label !== port.label && port.label) {
+                diff.labelChanged.push({
+                    name,
+                    label: port.label,
+                    direction: port.direction,
+                    type: port.type,
+                    scope: port.scope
+                });
+            }
+            if (beforePort.type !== port.type) {
+                diff.typeChanged.push({
+                    name,
+                    type: port.type,
+                    direction: port.direction
+                });
+            }
+        }
+    }
+    // Detect renames: exactly one removed and one added with same type/direction
+    if (diff.removed.length === 1 && diff.added.length === 1) {
+        const removed = diff.removed[0];
+        const added = diff.added[0];
+        const removedPort = before.find(p => p.name === removed.name);
+        if (removedPort && removedPort.type === added.type && removedPort.direction === added.direction) {
+            diff.renamed.push({ from: removed.name, to: added.name, direction: added.direction });
+            diff.removed = [];
+            diff.added = [];
+        }
+    }
+    return diff;
+}
+// =============================================================================
+// Format Ports (Aggressive Mode)
+// =============================================================================
+/**
+ * Format/regenerate all port tags in JSDoc.
+ * AGGRESSIVE MODE - for Cmd+Shift+P formatting.
+ *
+ * Unlike updatePortsInFunctionText() which preserves incomplete lines,
+ * this function:
+ * 1. Removes ALL existing port lines (valid or invalid)
+ * 2. Regenerates them in proper order based on [order:N] metadata
+ * 3. Ensures consistent formatting
+ */
+export function formatPortsInFunctionText(functionText, inputs, outputs) {
+    const jsdocMatch = functionText.match(JSDOC_BLOCK_REGEX);
+    // Helper to safely get order from metadata (metadata is Record<string, unknown>)
+    const getOrder = (port) => {
+        const order = port.metadata?.order;
+        return typeof order === "number" ? order : Infinity;
+    };
+    // Sort by order metadata
+    const sortedInputs = Object.entries(inputs)
+        .sort((a, b) => getOrder(a[1]) - getOrder(b[1]));
+    const sortedOutputs = Object.entries(outputs)
+        .sort((a, b) => getOrder(a[1]) - getOrder(b[1]));
+    // Separate into 4 groups based on scope
+    const externalInputs = sortedInputs.filter(([_, p]) => !p.scope);
+    const scopedInputs = sortedInputs.filter(([_, p]) => p.scope);
+    const externalOutputs = sortedOutputs.filter(([_, p]) => !p.scope);
+    const scopedOutputs = sortedOutputs.filter(([_, p]) => p.scope);
+    // Generate tags in correct order
+    const externalInputTags = externalInputs.map(([name, port]) => ` * ${generateJSDocPortTag(name, port, "input")}`);
+    const scopedOutputTags = scopedOutputs.map(([name, port]) => ` * ${generateJSDocPortTag(name, port, "output")}`);
+    const scopedInputTags = scopedInputs.map(([name, port]) => ` * ${generateJSDocPortTag(name, port, "input")}`);
+    const externalOutputTags = externalOutputs.map(([name, port]) => ` * ${generateJSDocPortTag(name, port, "output")}`);
+    // Combined order
+    const allPortTags = [...externalInputTags, ...scopedOutputTags, ...scopedInputTags, ...externalOutputTags];
+    if (!jsdocMatch) {
+        const newJsDoc = [
+            "/**",
+            " * @flowWeaver nodeType",
+            ...allPortTags,
+            " */",
+        ].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;
+    for (const line of lines) {
+        if (line.trim() === "/**" || line.trim() === "*/") {
+            preservedLines.push(line);
+            continue;
+        }
+        // REMOVE ALL port lines (aggressive mode)
+        if (PORT_TAG_REGEX.test(line)) {
+            continue;
+        }
+        if (line.includes("@flowWeaver")) {
+            hasFlowWeaverTag = true;
+        }
+        preservedLines.push(line);
+    }
+    const newLines = [...preservedLines];
+    if (!hasFlowWeaverTag) {
+        newLines.splice(1, 0, " * @flowWeaver nodeType");
+    }
+    // Remove trailing empty JSDoc lines before inserting ports
+    // This prevents extra blank lines between @label and port tags
+    // Matches: " *", " * ", empty lines, or lines with only whitespace
+    let closingIdx = newLines.findIndex((l) => l.trim() === "*/");
+    while (closingIdx > 1) {
+        const prevLine = newLines[closingIdx - 1];
+        const isEmptyJsDocLine = /^\s*\*\s*$/.test(prevLine); // " *" or " * "
+        const isBlankLine = prevLine.trim() === ""; // empty or whitespace only
+        if (isEmptyJsDocLine || isBlankLine) {
+            newLines.splice(closingIdx - 1, 1);
+            closingIdx--;
+        }
+        else {
+            break;
+        }
+    }
+    // Insert ALL port tags before closing */
+    const insertIndex = newLines.findIndex((l) => l.trim() === "*/");
+    newLines.splice(insertIndex, 0, ...allPortTags);
+    const newJsDoc = newLines.join("\n");
+    return functionText.replace(JSDOC_BLOCK_REGEX, newJsDoc);
+}
+// =============================================================================
+// Apply Diff
+// =============================================================================
+/**
+ * Apply a port diff to code without regenerating existing lines.
+ * This preserves incomplete/in-progress lines the user is typing.
+ */
+export function applyPortsDiffToCode(code, diff) {
+    let result = code;
+    // 1. Remove ports
+    for (const { name, direction } of diff.removed) {
+        const tag = direction === "INPUT" ? "@input" : "@output";
+        const lineRegex = new RegExp(`^\\s*\\*\\s*${tag}\\s+\\[?${name}\\]?(?:[^\\S\\n]+|[^\\S\\n]*-|[^\\S\\n]*\\[order|$).*$\\n?`, "gm");
+        result = result.replace(lineRegex, "");
+    }
+    // 2. Rename ports
+    for (const { from, to, direction } of diff.renamed) {
+        const tag = direction === "INPUT" ? "@input" : "@output";
+        const renameRegex = new RegExp(`(${tag}\\s+)(\\[?)${from}(\\]?\\b)`, "g");
+        result = result.replace(renameRegex, `$1$2${to}$3`);
+    }
+    // 3. Update labels
+    for (const { name, label, direction, scope } of diff.labelChanged) {
+        const tag = direction === "INPUT" ? "@input" : "@output";
+        const labelRegex = new RegExp(`(\\*\\s*${tag}\\s+\\[?${name}\\]?)(?:\\s+scope:\\w+)?(?:\\s+\\[order:\\s*\\d+\\])?(?:\\s+-\\s+[^\\n]*)?`, "g");
+        const beforeReplace = result;
+        result = result.replace(labelRegex, `$1${scope ? ` scope:${scope}` : ""} - ${label}`);
+        if (result === beforeReplace) {
+            const scopePart = scope ? ` scope:${scope}` : "";
+            const labelPart = ` - ${label}`;
+            const newLine = ` * ${tag} ${name}${scopePart}${labelPart}`;
+            result = result.replace(/(\n)(\s*\*\/)/, `$1${newLine}\n$2`);
+        }
+    }
+    // 4. Update types in signature (not JSDoc - types come from signature)
+    // Handle simple types and the standard function type we generate: (...args: any[]) => any
+    for (const { name, type, direction } of diff.typeChanged) {
+        const tsType = portTypeToTsType(type);
+        // Pattern for simple types: word characters, [], and optional ?
+        const simpleTypePattern = `[\\w\\[\\]\\?]+`;
+        // Pattern for the standard function type we generate: (...args: any[]) => any
+        // This is safe to replace because we know its exact structure
+        const standardFunctionPattern = `\\(\\.\\.\\.args:\\s*any\\[\\]\\)\\s*=>\\s*any`;
+        if (direction === "INPUT") {
+            // Try simple type first
+            const simpleParamRegex = new RegExp(`(\\b${name}\\??\\s*):\\s*(${simpleTypePattern})\\s*([,)])`, "g");
+            const beforeSimple = result;
+            result = result.replace(simpleParamRegex, `$1: ${tsType}$3`);
+            // If no change, try standard function type pattern
+            if (result === beforeSimple) {
+                const funcParamRegex = new RegExp(`(\\b${name}\\??\\s*):\\s*(${standardFunctionPattern})\\s*([,)])`, "g");
+                result = result.replace(funcParamRegex, `$1: ${tsType}$3`);
+            }
+        }
+        else {
+            // OUTPUT type change: ONLY modify within the return type annotation, NOT return statements in body
+            // Return type annotation is between "): {" and the closing "}" before "{" or "=>" (function body)
+            const returnTypeMatch = result.match(/(\)\s*:\s*)(\{[^}]+\})(\s*(?:\{|=>))/);
+            if (returnTypeMatch) {
+                const beforeReturnType = result.substring(0, returnTypeMatch.index + returnTypeMatch[1].length);
+                const returnTypeContent = returnTypeMatch[2];
+                const afterReturnType = result.substring(returnTypeMatch.index + returnTypeMatch[1].length + returnTypeContent.length);
+                // Only apply replacement within the return type annotation
+                const simpleReturnRegex = new RegExp(`(\\b${name}\\s*):\\s*(${simpleTypePattern})\\s*([,;}])`, "g");
+                let newReturnType = returnTypeContent.replace(simpleReturnRegex, `$1: ${tsType}$3`);
+                // If no change, try standard function type pattern
+                if (newReturnType === returnTypeContent) {
+                    const funcReturnRegex = new RegExp(`(\\b${name}\\s*):\\s*(${standardFunctionPattern})\\s*([,;}])`, "g");
+                    newReturnType = returnTypeContent.replace(funcReturnRegex, `$1: ${tsType}$3`);
+                }
+                result = beforeReturnType + newReturnType + afterReturnType;
+            }
+        }
+    }
+    // 5. Add new ports
+    for (const { name, direction, label, scope, placement } of diff.added) {
+        const tag = direction === "INPUT" ? "@input" : "@output";
+        const existsRegex = new RegExp(`@${tag === "@input" ? "input" : "output"}\\s+\\[?${name}[\\]\\s\\[\\-]?`, "i");
+        if (existsRegex.test(result)) {
+            continue;
+        }
+        const scopePart = scope ? ` scope:${scope}` : "";
+        const placementPart = placement ? ` [placement:${placement}]` : "";
+        const labelPart = label ? ` - ${label}` : "";
+        const newLine = ` * ${tag} ${name}${scopePart}${placementPart}${labelPart}`;
+        if (direction === "INPUT" && !scope) {
+            const firstScopedOutputMatch = result.match(/(\n)(\s*\*\s*@output\s+\w+\s+scope:)/);
+            if (firstScopedOutputMatch) {
+                result = result.replace(/(\n)(\s*\*\s*@output\s+\w+\s+scope:)/, `$1${newLine}\n$2`);
+            }
+            else {
+                const firstScopedInputMatch = result.match(/(\n)(\s*\*\s*@input\s+\w+\s+scope:)/);
+                if (firstScopedInputMatch) {
+                    result = result.replace(/(\n)(\s*\*\s*@input\s+\w+\s+scope:)/, `$1${newLine}\n$2`);
+                }
+                else {
+                    const firstOutputMatch = result.match(/(\n)(\s*\*\s*@output\s+)/);
+                    if (firstOutputMatch) {
+                        result = result.replace(/(\n)(\s*\*\s*@output\s+)/, `$1${newLine}\n$2`);
+                    }
+                    else {
+                        result = result.replace(/(\n)(\s*\*\/)/, `$1${newLine}\n$2`);
+                    }
+                }
+            }
+        }
+        else if (direction === "OUTPUT" && scope) {
+            const lines = result.split("\n");
+            let insertIndex = -1;
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (/@input\s+\w+/.test(line) && line.includes("scope:")) {
+                    insertIndex = i;
+                    break;
+                }
+            }
+            if (insertIndex === -1) {
+                for (let i = 0; i < lines.length; i++) {
+                    const line = lines[i];
+                    if (/@output\s+\w+/.test(line) && !line.includes("scope:")) {
+                        insertIndex = i;
+                        break;
+                    }
+                }
+            }
+            if (insertIndex !== -1) {
+                lines.splice(insertIndex, 0, newLine);
+                result = lines.join("\n");
+            }
+            else {
+                result = result.replace(/(\n)(\s*\*\/)/, `$1${newLine}\n$2`);
+            }
+        }
+        else if (direction === "INPUT" && scope) {
+            const lines = result.split("\n");
+            let insertIndex = -1;
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (/@output\s+\w+/.test(line) && !line.includes("scope:")) {
+                    insertIndex = i;
+                    break;
+                }
+            }
+            if (insertIndex !== -1) {
+                lines.splice(insertIndex, 0, newLine);
+                result = lines.join("\n");
+            }
+            else {
+                result = result.replace(/(\n)(\s*\*\/)/, `$1${newLine}\n$2`);
+            }
+        }
+        else {
+            result = result.replace(/(\n)(\s*\*\/)/, `$1${newLine}\n$2`);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=diff.js.map

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

@@ -0,0 +1,42 @@
+/**
+ * @module jsdoc-port-sync
+ *
+ * Browser-compatible bidirectional sync between JSDoc annotations and TypeScript
+ * signatures. Uses regex only - no ts-morph dependency.
+ *
+ * ## Dual Source of Truth
+ *
+ * | Aspect         | Source        | Notes |
+ * |----------------|---------------|-------|
+ * | Port EXISTENCE | **Signature** | Params + return fields define what ports exist |
+ * | Port TYPES     | **Signature** | Types inferred from TypeScript signature |
+ * | Port METADATA  | **JSDoc**     | Labels, order, placement, scope |
+ *
+ * ## Sync Flow
+ *
+ * ```
+ * Keystroke → syncJSDocToSignature (preserves signature, adds from JSDoc)
+ *
+ * Ctrl+P → syncSignatureToJSDoc (regenerates JSDoc) → syncJSDocToSignature
+ * ```
+ *
+ * ## Key Functions
+ *
+ * - {@link parsePortsFromFunctionText} - Extract ports from JSDoc
+ * - {@link syncJSDocToSignature} - JSDoc → Signature (add params/return fields)
+ * - {@link syncSignatureToJSDoc} - Signature → JSDoc (regenerate tags)
+ * - {@link syncCodeRenames} - Position-based rename detection
+ * - {@link computePortsDiff} / {@link applyPortsDiffToCode} - Diff-based updates
+ */
+export type { TPortDefinition, TDataType } from "../ast/types.js";
+export type { ParsedParam } from "./signature-parser.js";
+export type { TPortDiff } from "./diff.js";
+export { JSDOC_BLOCK_REGEX, PORT_TAG_REGEX, ORPHAN_PORT_LINE_REGEX, SCOPE_TAG_REGEX, FUNC_DECL_START, ARROW_START, RETURN_OBJECT_REGEX, RESERVED_PARAMS, RESERVED_RETURN_FIELDS, isReservedStepPort, findBalancedClose, splitParams, } from "./constants.js";
+export { parsePortLine, isValidPortLine } from "../chevrotain-parser/port-parser.js";
+export type { PortParseResult } from "../chevrotain-parser/port-parser.js";
+export { parseFunctionSignature, parseReturnFields, parseReturnBodyFieldsWithTypes, parseReturnTypeFields, parseReturnTypeFieldsWithTypes, parseInputTypeFields, tsTypeToPortType, portTypeToTsType, parseCallbackType, buildCallbackType, callbackHasAllPorts, } from "./signature-parser.js";
+export { hasScopes, getScopeNames, hasOrphanPortLines, getIncompletePortNames, parsePortsFromFunctionText, updatePortsInFunctionText, } from "./port-parser.js";
+export { syncSignatureToJSDoc, syncJSDocToSignature, } from "./sync.js";
+export { renamePortInCode, syncCodeRenames, } from "./rename.js";
+export { computePortsDiff, formatPortsInFunctionText, applyPortsDiffToCode, } from "./diff.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,45 @@
+/**
+ * @module jsdoc-port-sync
+ *
+ * Browser-compatible bidirectional sync between JSDoc annotations and TypeScript
+ * signatures. Uses regex only - no ts-morph dependency.
+ *
+ * ## Dual Source of Truth
+ *
+ * | Aspect         | Source        | Notes |
+ * |----------------|---------------|-------|
+ * | Port EXISTENCE | **Signature** | Params + return fields define what ports exist |
+ * | Port TYPES     | **Signature** | Types inferred from TypeScript signature |
+ * | Port METADATA  | **JSDoc**     | Labels, order, placement, scope |
+ *
+ * ## Sync Flow
+ *
+ * ```
+ * Keystroke → syncJSDocToSignature (preserves signature, adds from JSDoc)
+ *
+ * Ctrl+P → syncSignatureToJSDoc (regenerates JSDoc) → syncJSDocToSignature
+ * ```
+ *
+ * ## Key Functions
+ *
+ * - {@link parsePortsFromFunctionText} - Extract ports from JSDoc
+ * - {@link syncJSDocToSignature} - JSDoc → Signature (add params/return fields)
+ * - {@link syncSignatureToJSDoc} - Signature → JSDoc (regenerate tags)
+ * - {@link syncCodeRenames} - Position-based rename detection
+ * - {@link computePortsDiff} / {@link applyPortsDiffToCode} - Diff-based updates
+ */
+// Constants (kept for JSDoc detection/validation - Chevrotain handles parsing)
+export { JSDOC_BLOCK_REGEX, PORT_TAG_REGEX, ORPHAN_PORT_LINE_REGEX, SCOPE_TAG_REGEX, FUNC_DECL_START, ARROW_START, RETURN_OBJECT_REGEX, RESERVED_PARAMS, RESERVED_RETURN_FIELDS, isReservedStepPort, findBalancedClose, splitParams, } from "./constants.js";
+// Chevrotain-based port parsing (replaces regex patterns)
+export { parsePortLine, isValidPortLine } from "../chevrotain-parser/port-parser.js";
+// Signature parsing
+export { parseFunctionSignature, parseReturnFields, parseReturnBodyFieldsWithTypes, parseReturnTypeFields, parseReturnTypeFieldsWithTypes, parseInputTypeFields, tsTypeToPortType, portTypeToTsType, parseCallbackType, buildCallbackType, callbackHasAllPorts, } from "./signature-parser.js";
+// Port parsing
+export { hasScopes, getScopeNames, hasOrphanPortLines, getIncompletePortNames, parsePortsFromFunctionText, updatePortsInFunctionText, } from "./port-parser.js";
+// Sync functions
+export { syncSignatureToJSDoc, syncJSDocToSignature, } from "./sync.js";
+// Rename functions
+export { renamePortInCode, syncCodeRenames, } from "./rename.js";
+// Diff functions
+export { computePortsDiff, formatPortsInFunctionText, applyPortsDiffToCode, } from "./diff.js";
+//# sourceMappingURL=index.js.map