@synergenius/flow-weaver 0.33.1 → 0.44.0

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

@@ -0,0 +1,15 @@
+/**
+ * @module jsdoc-port-sync/apply-diff
+ *
+ * Applies a port diff to code as targeted text edits, without regenerating
+ * existing lines, so lines the user is still typing survive. Decides where a
+ * new tag goes so the standard order holds: inputs, scoped outputs, scoped
+ * inputs, outputs. Type changes edit the signature, since types come from it.
+ */
+import type { TPortDiff } from "./diff";
+/**
+ * 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=apply-diff.d.ts.map

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

@@ -0,0 +1,17 @@
+/**
+ * @module jsdoc-port-sync/callback-signature
+ *
+ * Writes scoped ports into the node function's callback parameters: for each
+ * scope, its scoped outputs become the callback's parameters and its scoped
+ * inputs the fields of the callback's return type.
+ */
+import type { TPortDefinition } from "../ast/types";
+type PortEntry = [string, TPortDefinition];
+type FunctionType = "declaration" | "arrow" | "expression";
+/**
+ * Update the callback of every scope that has ports. A scope's own name is not
+ * a callback parameter, and FUNCTION outputs are not either.
+ */
+export declare function syncScopeCallbacks(functionText: string, scopedInputs: PortEntry[], scopedOutputs: PortEntry[], functionType: FunctionType): string;
+export {};
+//# sourceMappingURL=callback-signature.d.ts.map

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

@@ -1,9 +1,12 @@
 /**
  * @module jsdoc-port-sync/diff
  *
- * Port diff system for UI sync without regeneration.
+ * Port diff system for UI sync without regeneration: computes what changed
+ * between two port lists and regenerates all port tags in canonical order.
+ * Applying a diff to code lives in apply-diff.
  */
-import type { TPortDefinition } from "../ast/types.js";
+import type { TPortDefinition } from "../ast/types";
+export { applyPortsDiffToCode } from "./apply-diff";
 /**
  * Represents a diff between two port arrays
  */
@@ -68,9 +71,4 @@ export declare function computePortsDiff(before: Array<{
  * 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/incomplete-lines.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module jsdoc-port-sync/incomplete-lines
+ *
+ * Decides which JSDoc port lines the user is still typing, so a sync never
+ * rewrites or duplicates them: orphan lines (a tag with no name yet) and
+ * incomplete lines (a tag the port grammar does not accept yet).
+ */
+type PortTagType = 'input' | 'output' | 'step';
+/**
+ * The tag type and port name of a port line, read loosely enough to work on a
+ * line that does not parse yet (`@input [name` counts).
+ */
+export declare function partialPortTag(line: string): {
+    tagType: PortTagType;
+    portName: string;
+} | null;
+/**
+ * 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;
+export {};
+//# sourceMappingURL=incomplete-lines.d.ts.map

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

@@ -28,15 +28,15 @@
  * - {@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";
+export type { TPortDefinition, TDataType } from "../ast/types";
+export type { ParsedParam } from "./signature-parser";
+export type { TPortDiff } from "./diff";
+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";
+export { parsePortLine, isValidPortLine } from "../chevrotain-parser/port-parser";
+export type { PortParseResult } from "../chevrotain-parser/port-parser";
+export { parseFunctionSignature, parseReturnFields, parseReturnBodyFieldsWithTypes, parseReturnTypeFields, parseReturnTypeFieldsWithTypes, parseInputTypeFields, tsTypeToPortType, portTypeToTsType, parseCallbackType, buildCallbackType, callbackHasAllPorts, } from "./signature-parser";
+export { hasScopes, getScopeNames, hasOrphanPortLines, getIncompletePortNames, parsePortsFromFunctionText, updatePortsInFunctionText, } from "./port-parser";
+export { syncSignatureToJSDoc, syncJSDocToSignature, } from "./sync";
+export { renamePortInCode, syncCodeRenames, } from "./rename";
+export { computePortsDiff, formatPortsInFunctionText, applyPortsDiffToCode, } from "./diff";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,45 +1,88 @@
-/**
- * @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
+import {
+  applyPortsDiffToCode,
+  computePortsDiff,
+  formatPortsInFunctionText,
+  getIncompletePortNames,
+  getScopeNames,
+  hasOrphanPortLines,
+  hasScopes,
+  parsePortsFromFunctionText,
+  renamePortInCode,
+  syncCodeRenames,
+  syncJSDocToSignature,
+  syncSignatureToJSDoc,
+  updatePortsInFunctionText
+} from "../chunks/chunk-FMTLP5ZX.js";
+import {
+  ARROW_START,
+  FUNC_DECL_START,
+  JSDOC_BLOCK_REGEX,
+  ORPHAN_PORT_LINE_REGEX,
+  PORT_TAG_REGEX,
+  RESERVED_PARAMS,
+  RESERVED_RETURN_FIELDS,
+  RETURN_OBJECT_REGEX,
+  SCOPE_TAG_REGEX,
+  buildCallbackType,
+  callbackHasAllPorts,
+  findBalancedClose,
+  isReservedStepPort,
+  parseCallbackType,
+  parseFunctionSignature,
+  parseInputTypeFields,
+  parseReturnBodyFieldsWithTypes,
+  parseReturnFields,
+  parseReturnTypeFields,
+  parseReturnTypeFieldsWithTypes,
+  portTypeToTsType,
+  splitParams,
+  tsTypeToPortType
+} from "../chunks/chunk-NQNLUAPO.js";
+import "../chunks/chunk-VP2P3BPA.js";
+import "../chunks/chunk-E5WN7IGO.js";
+import {
+  isValidPortLine,
+  parsePortLine
+} from "../chunks/chunk-QYPORSLO.js";
+import "../chunks/chunk-R4QGNK34.js";
+import "../chunks/chunk-SEWDMQ6Q.js";
+export {
+  ARROW_START,
+  FUNC_DECL_START,
+  JSDOC_BLOCK_REGEX,
+  ORPHAN_PORT_LINE_REGEX,
+  PORT_TAG_REGEX,
+  RESERVED_PARAMS,
+  RESERVED_RETURN_FIELDS,
+  RETURN_OBJECT_REGEX,
+  SCOPE_TAG_REGEX,
+  applyPortsDiffToCode,
+  buildCallbackType,
+  callbackHasAllPorts,
+  computePortsDiff,
+  findBalancedClose,
+  formatPortsInFunctionText,
+  getIncompletePortNames,
+  getScopeNames,
+  hasOrphanPortLines,
+  hasScopes,
+  isReservedStepPort,
+  isValidPortLine,
+  parseCallbackType,
+  parseFunctionSignature,
+  parseInputTypeFields,
+  parsePortLine,
+  parsePortsFromFunctionText,
+  parseReturnBodyFieldsWithTypes,
+  parseReturnFields,
+  parseReturnTypeFields,
+  parseReturnTypeFieldsWithTypes,
+  portTypeToTsType,
+  renamePortInCode,
+  splitParams,
+  syncCodeRenames,
+  syncJSDocToSignature,
+  syncSignatureToJSDoc,
+  tsTypeToPortType,
+  updatePortsInFunctionText
+};

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

@@ -0,0 +1,66 @@
+/**
+ * @module jsdoc-port-sync/jsdoc-to-signature
+ *
+ * The JSDoc → Code steps of `syncJSDocToSignature`: decides which ports the
+ * signature is missing, and edits the parameter list and return type annotation
+ * to add them. It never removes a parameter: the signature is the source of
+ * truth for which ports exist, and JSDoc only carries their metadata, so users
+ * can add a parameter first and tag it later.
+ */
+import type { TPortDefinition } from "../ast/types";
+type PortRecord = Record<string, TPortDefinition>;
+type PortEntry = [string, TPortDefinition];
+type FunctionType = "declaration" | "arrow" | "expression";
+/** Ports supplied by the caller that override what the JSDoc says. */
+export interface AuthoritativePorts {
+    inputs?: PortRecord;
+    outputs?: PortRecord;
+}
+/**
+ * The ports to sync from: those tagged in JSDoc, each replaced by the caller's
+ * authoritative definition when one is given. An output without one picks up
+ * the type inferred from its returned value when its tag has no type.
+ */
+export declare function resolveSyncPorts(functionText: string, authoritativePorts?: AuthoritativePorts): {
+    inputs: PortRecord;
+    outputs: PortRecord;
+};
+/** What the JSDoc → Code sync will change. */
+export interface SignatureSyncPlan {
+    functionType: FunctionType;
+    hasExecuteParam: boolean;
+    /** Non-scoped inputs with no parameter yet, in `[order:N]` order. */
+    paramsToAdd: Array<{
+        name: string;
+        port: TPortDefinition;
+    }>;
+    nonScopedOutputs: PortRecord;
+    scopedInputs: PortEntry[];
+    scopedOutputs: PortEntry[];
+    /** True when nothing needs to change and the text can be returned as is. */
+    upToDate: boolean;
+}
+/**
+ * Compare the ports with the signature and decide what to change: which
+ * parameters to add, whether `execute` is missing, which outputs and scoped
+ * ports must be written into the signature, and whether the text is already
+ * up to date.
+ */
+export declare function planSignatureSync(functionText: string, inputs: PortRecord, outputs: PortRecord): SignatureSyncPlan;
+/** Insert `execute: boolean` as the first parameter. */
+export declare function ensureExecuteParam(text: string, functionType: FunctionType): string;
+/**
+ * Append parameters to the end of the list, following its layout: a list with
+ * a trailing comma or spanning several lines gets the new ones on a new line.
+ */
+export declare function appendParams(text: string, functionType: FunctionType, paramsToAdd: Array<{
+    name: string;
+    port: TPortDefinition;
+}>): string;
+/**
+ * Write the return type annotation `{ onSuccess; onFailure; ...outputs }` after
+ * the parameter list, replacing an existing object annotation there.
+ */
+export declare function syncReturnType(text: string, functionType: FunctionType, nonScopedOutputs: PortRecord): string;
+export {};
+//# sourceMappingURL=jsdoc-to-signature.d.ts.map

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

@@ -4,7 +4,8 @@
  * Parse and update @input/@output/@step annotations in JSDoc.
  * Uses Chevrotain for parsing, browser-compatible.
  */
-import type { TPortDefinition } from '../ast/types.js';
+import type { TPortDefinition, TSerializableValue } from '../ast/types';
+export { hasOrphanPortLines, getIncompletePortNames, isIncompletePortLine } from './incomplete-lines';
 /**
  * Check if the code has any @scope declarations in JSDoc.
  * Used to automatically determine if the node should be in scoped mode.
@@ -20,29 +21,6 @@ export declare function hasScopes(functionText: string): boolean;
  * @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.
@@ -65,4 +43,8 @@ export declare function parsePortsFromFunctionText(functionText: string): {
  *        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;
+/**
+ * Parse default value from string.
+ */
+export declare function parseDefaultValue(value: string): TSerializableValue;
 //# sourceMappingURL=port-parser.d.ts.map

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

@@ -0,0 +1,55 @@
+/**
+ * @module jsdoc-port-sync/port-tag-placement
+ *
+ * The steps of `updatePortsInFunctionText`: decides which existing JSDoc
+ * port lines stay (removed ports go, lines being typed stay as they are), and
+ * where the tag of each new port goes: into an orphan line first, then next to
+ * its signature neighbours, after the last line of its kind, or before the
+ * closing `*\/`.
+ */
+import type { TPortDefinition } from '../ast/types';
+type PortRecord = Record<string, TPortDefinition>;
+type PortEntry = [string, TPortDefinition];
+type Direction = 'input' | 'output';
+/** An orphan line (`@input` with no name yet) waiting for a port. */
+interface OrphanLine {
+    index: number;
+    type: string;
+}
+/** The existing JSDoc lines to keep, and what they say about the ports. */
+export interface PortLineScan {
+    preservedLines: string[];
+    hasFlowWeaverTag: boolean;
+    /** Ports that already have a line (complete or still being typed). */
+    seenInputs: Set<string>;
+    seenOutputs: Set<string>;
+    orphanInputLines: OrphanLine[];
+    orphanOutputLines: OrphanLine[];
+    /** Index in `preservedLines` of the last input / output line, or -1. */
+    lastInputLineIndex: number;
+    lastOutputLineIndex: number;
+}
+/**
+ * Walk the existing JSDoc lines and decide which to keep. Every non-port line
+ * is kept; port lines are kept unless their port was removed.
+ */
+export declare function scanPortLines(lines: string[], inputs: PortRecord, outputs: PortRecord): PortLineScan;
+/**
+ * Write new ports into orphan lines: an orphan of the port's type first, then
+ * the earliest orphan. Returns the ports left without a line.
+ */
+export declare function fillOrphanLines(newLines: string[], portsToAdd: PortEntry[], orphanLines: OrphanLine[], direction: Direction): PortEntry[];
+/**
+ * Insert new output tags after the last output line, else after the last input
+ * line, else before the closing `*\/`.
+ */
+export declare function insertOutputTags(newLines: string[], outputsToAdd: PortEntry[], scan: PortLineScan): void;
+/**
+ * Insert new input tags. Non-scoped inputs follow the signature order when one
+ * is given, else go after the last input line (or after `@flowWeaver`). Scoped
+ * inputs go after the last output line, else before the closing `*\/`, matching
+ * the standard order: inputs, scoped outputs, scoped inputs, outputs.
+ */
+export declare function insertInputTags(newLines: string[], inputsToAdd: PortEntry[], scan: PortLineScan, signatureInputOrder?: string[]): void;
+export {};
+//# sourceMappingURL=port-tag-placement.d.ts.map

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

@@ -0,0 +1,21 @@
+/**
+ * @module jsdoc-port-sync/scoped-ports
+ *
+ * Decides which scopes a node type declares and makes sure each one has its
+ * mandatory STEP ports: a `start` output and `success` / `failure` inputs.
+ */
+import type { TPortDefinition } from "../ast/types";
+type PortRecord = Record<string, TPortDefinition>;
+/**
+ * The scopes a node declares: every `@scope` tag in its JSDoc, plus any
+ * per-port `scope:name` whose name matches a callback parameter (confirming it
+ * is a real scope, not just a labeled port).
+ */
+export declare function collectDeclaredScopes(functionText: string, inputs: PortRecord, outputs: PortRecord, callbackNames: ReadonlyMap<string, unknown>): Set<string>;
+/**
+ * Add the mandatory ports of every scope to the given records, in place:
+ * `start` to the outputs, `success` and `failure` (marked as failure) to the inputs.
+ */
+export declare function addMandatoryScopedPorts(inputs: PortRecord, outputs: PortRecord, scopes: Iterable<string>): void;
+export {};
+//# sourceMappingURL=scoped-ports.d.ts.map

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

@@ -4,7 +4,7 @@
  * Parse TypeScript function signatures to extract parameters and return types.
  * Browser-compatible (regex-based, no ts-morph).
  */
-import type { TDataType } from "../ast/types.js";
+import type { TDataType } from "../ast/types";
 /** Parsed function parameter */
 export interface ParsedParam {
     name: string;
@@ -22,6 +22,13 @@ export declare function parseFunctionSignature(functionText: string): {
     params: ParsedParam[];
     functionType: "declaration" | "arrow" | "expression";
 };
+/**
+ * The raw text of the parameter list, up to the first `)`. Unlike
+ * {@link parseFunctionSignature} it does not balance parentheses, so for a
+ * callback parameter it stops inside the callback's own list. Used for checks
+ * that must also see names the parser skipped while the user is typing.
+ */
+export declare function rawParamListText(functionText: string): string;
 /**
  * Parse return statement to extract object field names.
  * Returns unique field names from all return statements.

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

@@ -0,0 +1,77 @@
+/**
+ * @module jsdoc-port-sync/signature-to-jsdoc
+ *
+ * The Code → JSDoc steps of `syncSignatureToJSDoc`: decides which ports
+ * the TypeScript signature implies, merges them into the ports already tagged
+ * in JSDoc, drops tags whose port no longer exists, and works out the order in
+ * which the signature lists its inputs.
+ */
+import type { TPortDefinition } from "../ast/types";
+import { type ParsedParam } from "./signature-parser";
+type PortRecord = Record<string, TPortDefinition>;
+/** What a callback parameter declares, used to decide which scoped inputs stay. */
+export interface CallbackShape {
+    hasReturnFields: boolean;
+    returnFieldNames: Set<string>;
+}
+/** Everything the Code → JSDoc sync reads from the function text. */
+export interface SignatureShape {
+    params: ParsedParam[];
+    /** Output field names: the return type annotation when present, else the return statements. */
+    returnFields: string[];
+    /** Types inferred from `return { ... }` values, keyed by field name. */
+    returnBodyFieldTypes: Map<string, string>;
+    /** Input fields from a `TFlowWeaverNodeType<{...}, {...}>` annotation. */
+    inputTypeFields: Array<{
+        name: string;
+        tsType: string;
+    }>;
+    /** Port names on JSDoc lines the user is still typing. */
+    incompletePortNames: {
+        inputs: Set<string>;
+        outputs: Set<string>;
+    };
+    /** Names of the non-callback parameters plus the annotated input fields. */
+    signatureParamNames: Set<string>;
+    /** The raw text of the parameter list, for checks the parsed params miss. */
+    rawSigText: string;
+    /** Callback parameters (scopes) by parameter name. */
+    callbacks: Map<string, CallbackShape>;
+}
+/**
+ * Read the signature facts the Code → JSDoc sync decides on. When the function
+ * has a return type annotation its fields win; otherwise the fields returned
+ * from the body are used.
+ */
+export declare function readSignatureShape(functionText: string): SignatureShape;
+/**
+ * Merge the signature's parameters into the JSDoc inputs. A parameter without a
+ * tag gets a new port typed from the signature; a tagged port takes the
+ * signature's type when that type is concrete, except that a STEP port is never
+ * downgraded to BOOLEAN. Names on lines still being typed are left alone.
+ */
+export declare function mergeSignatureInputs(existingInputs: PortRecord, shape: SignatureShape): PortRecord;
+/**
+ * Merge the signature's output fields into the JSDoc outputs. A field without a
+ * tag gets a new port typed from its returned value when one can be inferred.
+ */
+export declare function mergeSignatureOutputs(existingOutputs: PortRecord, shape: SignatureShape): PortRecord;
+/**
+ * Keep the inputs the signature still backs. An input survives when it is a
+ * parameter, a live scoped input, on a line still being typed, or carries user
+ * metadata (order or label) and its name still appears in the raw parameters.
+ */
+export declare function keepLiveInputs(mergedInputs: PortRecord, shape: SignatureShape): PortRecord;
+/**
+ * Keep the outputs the signature still backs: returned fields, scoped outputs,
+ * reserved ports, and names on lines still being typed.
+ */
+export declare function keepLiveOutputs(mergedOutputs: PortRecord, shape: SignatureShape): PortRecord;
+/**
+ * The order the signature lists its (non-callback) inputs in, used to place new
+ * input tags. The raw parameter text is preferred because it also sees names the
+ * parser skipped; the parsed params win when they found more.
+ */
+export declare function signatureInputOrder(shape: SignatureShape): string[];
+export {};
+//# sourceMappingURL=signature-to-jsdoc.d.ts.map

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

@@ -4,8 +4,11 @@
  * Bidirectional sync between JSDoc annotations and TypeScript signatures.
  * - syncSignatureToJSDoc: Code → JSDoc (regenerate tags from signature)
  * - syncJSDocToSignature: JSDoc → Code (add params/fields to signature)
+ *
+ * The steps of each direction live in signature-to-jsdoc / scoped-ports and
+ * jsdoc-to-signature / callback-signature; this module only sequences them.
  */
-import type { TPortDefinition } from "../ast/types.js";
+import type { TPortDefinition } from "../ast/types";
 /**
  * Sync function signature to JSDoc (Code → JSDoc).
  *

package/dist/marketplace/index.d.ts

@@ -1,11 +1,13 @@
 /**
  * @module marketplace
  *
- * Flow Weaver Marketplace — discover, install, and publish reusable
+ * Flow Weaver Marketplace: discover, install, and publish reusable
  * node types, workflows, and patterns via npm.
  */
-export type { TMarketplaceManifest, TManifestNodeType, TManifestWorkflow, TManifestPattern, TManifestExportTarget, TManifestPort, TValidationIssue, TValidationSeverity, TPackageValidationResult, TMarketplacePackageInfo, TInstalledPackage, TMarketInitConfig, TManifestTagHandler, TManifestValidationRuleSet, TManifestDocTopic, TManifestInitContribution, TManifestCliCommand, TManifestMcpTool, } from './types.js';
+export type { TMarketplaceManifest, TManifestNodeType, TManifestWorkflow, TManifestExportTarget, TManifestPort, TValidationIssue, TValidationSeverity, TPackageValidationResult, TMarketplacePackageInfo, TInstalledPackage, TMarketInitConfig, TManifestTagHandler, TManifestValidationRuleSet, TManifestDocTopic, TManifestInitContribution, TManifestCliCommand, TManifestMcpTool, } from './types.js';
 export { generateManifest, writeManifest, readManifest, type GenerateManifestOptions, type GenerateManifestResult, } from './manifest.js';
 export { validatePackage } from './validator.js';
-export { searchPackages, listInstalledPackages, getInstalledPackageManifest, discoverTagHandlers, discoverValidationRuleSets, discoverDocTopics, discoverInitContributions, discoverDeviceHandlers, type SearchOptions, type TDiscoveredTagHandler, type TDiscoveredValidationRuleSet, type TDiscoveredDocTopic, type TDiscoveredInitContribution, type TDiscoveredDeviceHandler, } from './registry.js';
+export { searchPackages, listInstalledPackages, getInstalledPackageManifest, discoverTagHandlers, discoverValidationRuleSets, discoverDocTopics, discoverInitContributions, type SearchOptions, type TDiscoveredTagHandler, type TDiscoveredValidationRuleSet, type TDiscoveredDocTopic, type TDiscoveredInitContribution, type TDiscoveredDeviceHandler, } from './registry.js';
+export { searchAllRegistries, type MultiRegistrySearch, type RegistrySearched } from './registry.js';
+export { resolveRegistries, readNpmConfig, parseNpmrc, nerfDart, PUBLIC_REGISTRY, type Registry } from './npmrc.js';
 //# sourceMappingURL=index.d.ts.map