@synergenius/flow-weaver 0.33.2 → 0.44.0

package/dist/parser/jsdoc/runtime-tags.d.ts

@@ -0,0 +1,65 @@
+/**
+ * How a workflow's runtime tags are read: what starts it, how it is served,
+ * what bounds it, and where it is deployed.
+ *
+ * `@trigger` (core `event=`/`cron=` forms, accumulated across tags; any other
+ * form goes to a pack's `_trigger` handler), `@http` routes (method, path and
+ * options checked here; a duplicate route keeps the first), `@cancelOn`,
+ * `@throttle`, `@retries` and `@timeout` (an unquoted duration is accepted as
+ * the quoted string), and `@deploy <target> key=value ...`, which node types
+ * use too. A bad line is a warning and is dropped; the workflow still parses.
+ */
+import type { JSDocTag } from 'ts-morph';
+import type { THttpRoute } from '../../ast/types';
+import type { TagHandlerRegistry } from '../tag-registry';
+import type { JSDocWorkflowConfig } from './config-types';
+/**
+ * Parse @trigger tag using Chevrotain parser.
+ *
+ * Core parses the built-in `event=` / `cron=` forms. Any other form is a
+ * pack's to interpret: a pack registers a `_trigger` handler and core hands
+ * the line to it. Core itself knows nothing about the domains a pack adds.
+ */
+export declare function parseTriggerTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[], tagRegistry?: TagHandlerRegistry): void;
+/**
+ * Parse @cancelOn tag using Chevrotain parser.
+ */
+export declare function parseCancelOnTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+/**
+ * Parse @throttle tag using Chevrotain parser.
+ */
+export declare function parseThrottleTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+/** Parse @retries tag. The grammar rejects `3abc` and warns; a negative value also warns. */
+export declare function parseRetriesTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+/**
+ * Parse @timeout tag. The duration is a quoted string in the grammar
+ * (`@timeout "30m"`); an unquoted value is accepted as the same string.
+ */
+export declare function parseTimeoutTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+/**
+ * Parse @http tag: the route a workflow is served on.
+ * Format: @http METHOD /path [mode=sync|async] [auth=bearer|none] [callback]
+ *
+ * Examples:
+ *   @http POST /reviews
+ *   @http GET /reviews/:path
+ *   @http POST /reviews mode=async callback
+ *
+ * Several @http tags give several routes. A bad line is a warning and the
+ * route is dropped; the workflow still parses.
+ */
+export declare function parseHttpTag(tag: JSDocTag, config: {
+    http?: THttpRoute[];
+}, warnings: string[]): void;
+/**
+ * Parse @deploy tag.
+ * Format: @deploy <target> key=value key2="value with spaces" key3=123 key4=true
+ *
+ * Examples:
+ *   @deploy my-target durableSteps=true framework="next" retries=3
+ *   @deploy another-target memory=256 timeout=30 tags="a,b"
+ *
+ * Values are auto-coerced: "true"/"false" → boolean, numeric strings → number.
+ */
+export declare function parseDeployTag(tag: JSDocTag, deployMap: Record<string, Record<string, unknown>>): void;
+//# sourceMappingURL=runtime-tags.d.ts.map

package/dist/parser/jsdoc/signature-types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What type a port gets from the function signature.
+ *
+ * The signature is the interface: a node type's input is typed by its
+ * parameter, its output by the field of its (Promise-unwrapped) return value,
+ * and a scoped port by the callback parameter its scope names (a scoped input
+ * by a field of the callback's return, a scoped output by one of the
+ * callback's parameters). A `[type:X]` modifier only fills in when the
+ * signature gives nothing usable, and disagreeing with a usable signature is a
+ * warning. Workflow `@param`/`@returns` read the field out of the params or
+ * return type text.
+ */
+import type { Type, Symbol as TsMorphSymbol } from 'ts-morph';
+import type { FunctionLike } from '../function-like';
+import type { TDataType } from '../../ast/types';
+/**
+ * `Promise<T>` becomes `T`; any other type is returned as is. An async node
+ * type or callback returns a Promise, and its data ports are the fields of the
+ * resolved value, not of the Promise.
+ */
+export declare function unwrapPromise(type: Type): Type;
+/**
+ * Get the type of a property Symbol.
+ */
+export declare function getPropertyType(property: TsMorphSymbol, containerType: Type): Type | undefined;
+/**
+ * Type a scoped port from the callback parameter its scope names. A scoped
+ * INPUT port is a field of the callback's return value; a scoped OUTPUT port
+ * is one of the callback's parameters. The ts-morph Type API reads both, so
+ * generics and nested objects work. A missing callback or field is a warning
+ * and the port is ANY.
+ */
+export declare function typeScopedPort(direction: 'INPUT' | 'OUTPUT', name: string, scope: string, func: FunctionLike, warnings: string[]): {
+    type: TDataType;
+    tsType?: string;
+};
+/**
+ * Reconcile a `[type:X]` modifier with the type inferred from the signature.
+ *
+ * The signature is the interface, so when it gives a usable type that type
+ * stands and a disagreeing modifier is a warning. When the signature gives
+ * nothing usable (no matching parameter or return field, or `any`), the
+ * modifier is the only type information there is and it is honoured.
+ * A modifier that is not a port type is a warning and ignored.
+ */
+export declare function applyDeclaredType(direction: 'input' | 'output', name: string, declared: string | undefined, inferred: TDataType, tsType: string | undefined, func: FunctionLike, warnings: string[]): TDataType;
+/**
+ * The `name: type` field of an object type's text, with the type as group 1.
+ * Anchored at a field boundary so `id` does not match inside `valid: boolean`.
+ */
+export declare function objectFieldPattern(name: string): RegExp;
+//# sourceMappingURL=signature-types.d.ts.map

package/dist/parser/jsdoc/workflow-block.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How a `@flowWeaver workflow` JSDoc block becomes a workflow config.
+ *
+ * Picks the first JSDoc block that declares one, takes the free text above
+ * the tags as the description (in-place compilation regenerates this block
+ * from the AST, so anything not captured here is lost on the next compile),
+ * and reads each tag in order: identity and options (`@name`, `@description`,
+ * `@strictTypes`, `@autoConnect`), the graph (see graph-tags), runtime tags
+ * (see runtime-tags), and the `@param`/`@returns` ports (see port-tags). A
+ * node-type-only tag, or one no handler knows, is a warning (with the closest
+ * known tag as a hint); a tag a pack registered goes to its handler.
+ */
+import type { FunctionLike } from '../function-like';
+import type { TagHandlerRegistry } from '../tag-registry';
+import type { JSDocWorkflowConfig } from './config-types';
+/**
+ * Parse @flowWeaver workflow from JSDoc comments.
+ * When a TagHandlerRegistry is provided, unknown tags are checked against it
+ * before being reported as warnings.
+ */
+export declare function parseWorkflow(func: FunctionLike, warnings: string[], tagRegistry?: TagHandlerRegistry): JSDocWorkflowConfig | null;
+//# sourceMappingURL=workflow-block.d.ts.map

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

@@ -0,0 +1,23 @@
+/**
+ * JSDoc annotation parser for Flow Weaver
+ *
+ * Reads a function's `@flowWeaver nodeType` or `@flowWeaver workflow` JSDoc
+ * block into a config. The work is split by responsibility under `./jsdoc/`:
+ *
+ * - node-type-block: the `@flowWeaver nodeType` block and its tags
+ * - workflow-block: the `@flowWeaver workflow` block and its tags
+ * - port-tags: `@input`/`@output`/`@step` and `@param`/`@returns` ports
+ * - signature-types: port types read from the function signature
+ * - graph-tags: `@node`, `@connect`, `@scope` and the sugar tags
+ * - runtime-tags: `@trigger`, `@http`, `@cancelOn`, `@throttle`, `@retries`,
+ *   `@timeout` and `@deploy`
+ * - config-types: the config shapes both blocks produce
+ */
+import { parseNodeType } from './jsdoc/node-type-block';
+import { parseWorkflow } from './jsdoc/workflow-block';
+export type { JSDocNodeTypeConfig, JSDocWorkflowConfig } from './jsdoc/config-types';
+export declare const jsdocParser: {
+    parseNodeType: typeof parseNodeType;
+    parseWorkflow: typeof parseWorkflow;
+};
+//# sourceMappingURL=jsdoc-parser.d.ts.map

package/dist/parser/macro-expansion.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Workflow macro expansion.
+ *
+ * These functions expand the @map / @path / @fanOut / @fanIn / @coerce macros
+ * into instances, connections and scopes, and generate the implicit
+ * @autoConnect connections. All inputs and outputs are explicit parameters.
+ */
+import type { TNodeTypeAST, TPortDefinition, TConnectionAST, TNodeInstanceAST, TWorkflowMacro } from '../ast/types';
+export declare function expandMapMacro(mapConfig: {
+    instanceId: string;
+    childId: string;
+    sourceNode: string;
+    sourcePort: string;
+    inputPort?: string;
+    outputPort?: string;
+}, instances: TNodeInstanceAST[], connections: TConnectionAST[], scopes: Record<string, string[]>, availableNodeTypes: TNodeTypeAST[], macros: TWorkflowMacro[], errors: string[], _warnings: string[]): void;
+/**
+ * Expand @path macros into multi-step execution routes with scope walking.
+ * Processes all paths together for shared deduplication.
+ */
+export declare function expandPathMacros(pathConfigs: Array<{
+    steps: Array<{
+        node: string;
+        route?: 'ok' | 'fail';
+    }>;
+}>, instances: TNodeInstanceAST[], connections: TConnectionAST[], availableNodeTypes: TNodeTypeAST[], startPorts: Record<string, TPortDefinition>, exitPorts: Record<string, TPortDefinition>, macros: TWorkflowMacro[], errors: string[], _warnings: string[]): void;
+/**
+ * Expand @fanOut macros into 1-to-N connections.
+ */
+export declare function expandFanOutMacros(fanOutConfigs: Array<{
+    source: {
+        node: string;
+        port: string;
+    };
+    targets: Array<{
+        node: string;
+        port?: string;
+    }>;
+}>, instances: TNodeInstanceAST[], connections: TConnectionAST[], startPorts: Record<string, TPortDefinition>, exitPorts: Record<string, TPortDefinition>, macros: TWorkflowMacro[], errors: string[]): void;
+/**
+ * Expand @fanIn macros into N-to-1 connections.
+ */
+export declare function expandFanInMacros(fanInConfigs: Array<{
+    sources: Array<{
+        node: string;
+        port?: string;
+    }>;
+    target: {
+        node: string;
+        port: string;
+    };
+}>, instances: TNodeInstanceAST[], connections: TConnectionAST[], startPorts: Record<string, TPortDefinition>, exitPorts: Record<string, TPortDefinition>, macros: TWorkflowMacro[], errors: string[]): void;
+/**
+ * Expand @coerce macros into synthetic coercion node instances + connections.
+ */
+export declare function expandCoerceMacros(coerceConfigs: Array<{
+    instanceId: string;
+    source: {
+        node: string;
+        port: string;
+    };
+    target: {
+        node: string;
+        port: string;
+    };
+    targetType: 'string' | 'number' | 'boolean' | 'json' | 'object';
+}>, instances: TNodeInstanceAST[], connections: TConnectionAST[], startPorts: Record<string, TPortDefinition>, exitPorts: Record<string, TPortDefinition>, macros: TWorkflowMacro[], errors: string[]): void;
+/**
+ * Generate automatic connections for @autoConnect workflows.
+ * Wires nodes in declaration order as a linear pipeline:
+ * Start -> first node -> second node -> ... -> last node -> Exit
+ *
+ * For each consecutive pair:
+ * - Connect execute flow: previous.onSuccess -> next.execute
+ * - Connect data ports where output name matches input name
+ * For first node: Start.execute -> first.execute + match Start data ports to first inputs
+ * For last node: last.onSuccess -> Exit.execute + match last outputs to Exit ports
+ */
+export declare function generateAutoConnections(instances: TNodeInstanceAST[], availableNodeTypes: TNodeTypeAST[], startPorts: Record<string, TPortDefinition>, exitPorts: Record<string, TPortDefinition>): TConnectionAST[];
+//# sourceMappingURL=macro-expansion.d.ts.map

package/dist/parser/module-resolution.d.ts

@@ -0,0 +1,38 @@
+/**
+ * How an import specifier in a workflow file becomes a file the parser reads.
+ *
+ * Decides which file a relative specifier points at (extension probing, the
+ * ESM `.js` to `.ts` fallback, directory `package.json` main and index files),
+ * which `.d.ts` a re-export in a package declaration points at, which
+ * extensions can carry annotations at all, and how an in-memory source
+ * override graph is loaded into the ts-morph Project before a parse.
+ */
+import type { Project } from 'ts-morph';
+export type SourceImportResolver = (specifier: string, importer: string) => string | undefined;
+export type SourceOverrideLoader = (filePath: string) => string | undefined;
+/**
+ * Extensions of files that can carry `@flowWeaver` annotations. A relative
+ * import of anything else (`./data.json`, `./styles.css`) is application data
+ * the workflow uses, not a node-type source, and is skipped by the parser.
+ */
+export declare const SOURCE_EXTENSIONS: Set<string>;
+/**
+ * The file a relative `moduleSpecifier` in `currentDir` points at, or null.
+ * A `package.json` that cannot be read while probing a directory is reported
+ * to `warnings`.
+ */
+export declare function resolveModulePath(moduleSpecifier: string, currentDir: string, warnings?: string[]): string | null;
+/**
+ * Resolve a relative re-export specifier (as written in a `.d.ts`, which
+ * commonly points at the compiled `.js`, e.g. `./node-types/index.js`) to
+ * the matching `.d.ts` on disk. Tries the literal `.d.ts`, the `.js`->`.d.ts`
+ * swap, and the `<dir>/index.d.ts` directory form.
+ */
+export declare function resolveReExportedDts(baseDir: string, spec: string): string | null;
+/**
+ * Load every relative import of `source` that `sourceLoader` overrides into
+ * `project`, depth first, so the virtual graph is in place before the
+ * importer's types are read. `seen` guards cycles.
+ */
+export declare function preloadSourceOverrides(project: Project, importer: string, source: string, importResolver: SourceImportResolver | undefined, sourceLoader: SourceOverrideLoader, seen: Set<string>): void;
+//# sourceMappingURL=module-resolution.d.ts.map

package/dist/parser/node-inference.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Node-type extraction and inference.
+ *
+ * extractNodeTypes walks a source file's @flowWeaver-annotated (and inferable)
+ * functions into TNodeTypeAST[]. The infer* functions derive node types from
+ * bare function signatures (expression mode), and hasFlowWeaverAnnotation detects
+ * the annotation. The tag-handler registry used by extractNodeTypes is passed
+ * in explicitly.
+ */
+import { type SourceFile } from 'ts-morph';
+import { type FunctionLike } from './function-like';
+import type { TNodeTypeAST } from '../ast/types';
+import type { TagHandlerRegistry } from './tag-registry';
+export declare function extractNodeTypes(sourceFile: SourceFile, warnings: string[], tagRegistry: TagHandlerRegistry): TNodeTypeAST[];
+/**
+ * Infer a node type from a bare function signature (expression mode), without
+ * an explicit @flowWeaver nodeType annotation.
+ */
+export declare function inferNodeTypeFromFunction(fn: FunctionLike, name: string, filePath: string): TNodeTypeAST;
+/**
+ * Pre-infer ALL unannotated functions from a source file.
+ * Used for imported files so the named-import filter can scope them.
+ */
+export declare function inferAllUnannotatedFunctions(sourceFile: SourceFile, existingNodeTypes: TNodeTypeAST[]): TNodeTypeAST[];
+/**
+ * Auto-infer node types from unannotated functions referenced by @node.
+ *
+ * When a workflow references a function via @node that has no @flowWeaver
+ * nodeType annotation, we infer an expression node type from its TypeScript
+ * signature. Phase 1: same-file functions only.
+ */
+export declare function inferNodeTypesFromUnannotated(sourceFile: SourceFile, existingNodeTypes: TNodeTypeAST[], localNodeTypes: TNodeTypeAST[], warnings: string[]): TNodeTypeAST[];
+/**
+ * Detect whether a function carries a valid @flowWeaver annotation
+ * (nodeType, its `node` shorthand, or workflow). Avoids false positives from
+ * file-level JSDoc that merely mentions @flowWeaver in description text.
+ */
+export declare function hasFlowWeaverAnnotation(fn: FunctionLike): boolean;
+//# sourceMappingURL=node-inference.d.ts.map

package/dist/parser/npm-node-types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Filling in the ports of npm node types after a parse.
+ *
+ * Decides how a node type that came from an npm package (one with an
+ * `importSource`) gets its full port list and async-ness back from the
+ * package's exports, since the `@fwImport` annotation persisted in the source
+ * only records its name, function and package. A node type the package does
+ * not export is left as it is.
+ */
+import type { TWorkflowAST } from '../ast/types';
+/**
+ * Resolve npm node types by re-reading their .d.ts files.
+ * This fills in the full port information that isn't stored in @fwImport annotations.
+ *
+ * When workflows are parsed, npm node types from @fwImport annotations only contain
+ * minimal stub information (name, functionName, importSource). This function re-resolves
+ * the full port definitions from the actual .d.ts files of the npm packages.
+ *
+ * @param ast - The workflow AST with potentially stub npm node types
+ * @param workdir - Directory to search for node_modules (typically the workflow file's directory)
+ * @returns Updated AST with fully resolved npm node types
+ */
+export declare function resolveNpmNodeTypes(ast: TWorkflowAST, workdir: string): TWorkflowAST;
+//# sourceMappingURL=npm-node-types.d.ts.map

package/dist/parser/pack-handlers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Loading the parser extensions an installed marketplace pack ships.
+ *
+ * Decides what a pack contributes to parsing and validation: its tag handlers
+ * and their serializers go into the given tag registry, its validation rule
+ * sets into the global validation rule registry. A module that fails to load
+ * is skipped, since the pack may not be built.
+ */
+import type { TagHandlerRegistry } from './tag-registry';
+/** Discover the packs installed under `projectDir` and register their tag handlers and validation rule sets. */
+export declare function registerPackHandlers(tagRegistry: TagHandlerRegistry, projectDir: string): Promise<void>;
+//# sourceMappingURL=pack-handlers.d.ts.map

package/dist/parser/path-data-resolution.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The one rule for the data edges a `@path` implies.
+ *
+ * `@path` writes the control flow. For data, each step's non-control input
+ * ports resolve by name: walk backward through the path to the nearest
+ * ancestor that has a same-name output port, and wire it. This module is the
+ * single place that rule lives. The parser uses it to add the edges, the sugar
+ * optimizer uses it to check that a path is still consistent with the
+ * connection set, and the annotation generators use it to decide which
+ * `@connect` lines a `@path` already covers.
+ *
+ * Exit participates like any other step: a port declared with `@returns`
+ * resolves to the nearest ancestor output of the same name. One deliberate
+ * exception: a `Start` param never resolves straight to an Exit port. That
+ * would echo an input as an output and could hide a missing producer, so a
+ * pass-through has to be written as an explicit `@connect`.
+ */
+export interface PathStepRef {
+    node: string;
+    route?: string;
+}
+export interface PathDataEdge {
+    from: {
+        node: string;
+        port: string;
+    };
+    to: {
+        node: string;
+        port: string;
+    };
+}
+export interface PathPortLookup {
+    /** Data + control input ports of a step (Exit's are its `@returns` ports). */
+    inputs(nodeId: string): Record<string, unknown>;
+    /** Data + control output ports of a step (Start's are its `@param` ports). */
+    outputs(nodeId: string): Record<string, unknown>;
+}
+/**
+ * Whether a single connection is of the shape a `@path` implies between two of
+ * its steps: same port name on both ends, a data port, and not a `Start`
+ * param passed straight through to `Exit`.
+ */
+export declare function isPathImpliedDataEdge(fromNode: string, fromPort: string, toNode: string, toPort: string): boolean;
+/**
+ * The data edges a path implies, in path order. For each step after the
+ * first, every non-control input port is matched against the nearest
+ * ancestor with a same-name output. The nearest ancestor decides: when it is
+ * `Start` and the step is `Exit`, no edge is implied and no farther ancestor
+ * is tried.
+ */
+export declare function impliedPathDataEdges(steps: readonly PathStepRef[], ports: PathPortLookup): PathDataEdge[];
+/**
+ * The data edges implied for one step, `steps[stepIndex]`, from the steps
+ * before it. The parser calls this per consecutive pair so that the data
+ * edges of a step are added right after its control-flow edge. Connection
+ * order is part of a workflow's graph fingerprint and must stay stable.
+ */
+export declare function impliedPathDataEdgesInto(steps: readonly PathStepRef[], stepIndex: number, ports: PathPortLookup): PathDataEdge[];
+/**
+ * Whether every edge a path implies is accounted for in a connection set. An
+ * implied edge is satisfied when it exists, or when the author wired that
+ * target port to something else explicitly (the parser then leaves the port
+ * alone, so the path is still consistent).
+ */
+export declare function pathDataEdgesSatisfied(steps: readonly PathStepRef[], ports: PathPortLookup, connections: readonly {
+    from: {
+        node: string;
+        port: string;
+    };
+    to: {
+        node: string;
+        port: string;
+    };
+}[]): boolean;
+//# sourceMappingURL=path-data-resolution.d.ts.map

package/dist/parser/port-inference.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Workflow port inference from TypeScript signatures.
+ *
+ * parseStartPorts / parseExitPorts derive a workflow's Start/Exit port
+ * definitions from a function's signature and its parsed @flowWeaver config.
+ * extractTypeSchema / isExpandableObjectType / inferPortType map ts-morph Types
+ * to Flow Weaver data types, and capitalize is a shared label helper.
+ */
+import type { FunctionLike } from './function-like';
+import { jsdocParser } from './jsdoc-parser';
+import type { TPortDefinition } from '../ast/types';
+export declare function parseStartPorts(fn: FunctionLike, config?: ReturnType<typeof jsdocParser.parseWorkflow>): Record<string, TPortDefinition>;
+export declare function parseExitPorts(fn: FunctionLike, config: ReturnType<typeof jsdocParser.parseWorkflow>, warnings?: string[]): Record<string, TPortDefinition>;
+export declare function capitalize(str: string): string;
+//# sourceMappingURL=port-inference.d.ts.map

package/dist/{resolve-package-types.d.ts → parser/resolve-package-types.d.ts}

@@ -14,4 +14,8 @@
  * @returns Absolute path to the `.d.ts` file, or null
  */
 export declare function resolvePackageTypesPath(packageSpecifier: string, fromDir: string, nodeModulesOverride?: string): string | null;
+/**
+ * Walk up from `fromDir` collecting all `node_modules` directories.
+ */
+export declare function findNodeModulesDirs(fromDir: string): string[];
 //# sourceMappingURL=resolve-package-types.d.ts.map

package/dist/parser/serialize-deploy-annotations.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared JSDoc emission for pack-contributed deploy namespaces.
+ *
+ * The parser delegates tag PARSING to pack tag handlers (TagHandlerRegistry).
+ * This is the symmetric reverse: during JSDoc regeneration, each namespace in
+ * `options.deploy` is handed to its registered serializer, which emits the
+ * annotation lines that reproduce it. Without this, tags a pack learned to
+ * parse after core froze its hardcoded emitters were silently dropped on
+ * regeneration (e.g. @matrix, @artifact, @service from a pack).
+ */
+/**
+ * Serialize every pack deploy namespace back to JSDoc comment lines.
+ *
+ * @param deploy - `options.deploy`, mapping namespace → accumulated tag data.
+ * @returns full comment lines (each already prefixed with ` * `), in a stable
+ *   namespace order so regeneration is deterministic.
+ */
+export declare function serializePackDeployAnnotations(deploy: Record<string, Record<string, unknown>> | undefined): string[];
+//# sourceMappingURL=serialize-deploy-annotations.d.ts.map

package/dist/parser/tag-registry.d.ts

@@ -22,14 +22,36 @@ export type TRegisteredTagHandler = {
     scope: 'workflow' | 'nodeType' | 'both';
     handler: TTagHandlerFn;
 };
+/**
+ * The reverse of a tag handler: given a namespace's accumulated deploy data
+ * (the object a handler populated during parsing), produce the JSDoc annotation
+ * lines that regenerate it. Each returned string is a full comment line,
+ * including the leading ` * ` prefix (e.g. ` * @secret NPM_TOKEN`).
+ *
+ * Registered per namespace so JSDoc regeneration stays symmetric with parsing:
+ * whatever tags a pack learns to parse, it also emits, with no core changes needed.
+ */
+export type TTagSerializerFn = (deployData: Record<string, unknown>) => string[];
 /**
  * Registry mapping tag names to pack-provided handler functions.
  * Used by the JSDoc parser to delegate tags it doesn't natively handle.
  */
 export declare class TagHandlerRegistry {
     private handlers;
+    private serializers;
     /** Register a handler for one or more tag names. */
     register(tags: string[], namespace: string, scope: 'workflow' | 'nodeType' | 'both', handler: TTagHandlerFn): void;
+    /**
+     * Register (or clear) the serializer for a namespace. Passing `undefined`
+     * removes it, keeping round-trip emission symmetric with parsing.
+     */
+    registerSerializer(namespace: string, serializer: TTagSerializerFn | undefined): void;
+    /**
+     * Serialize a namespace's deploy data back to JSDoc annotation lines.
+     * Returns `[]` when no serializer is registered for the namespace or the
+     * serializer produced nothing.
+     */
+    serialize(namespace: string, deployData: Record<string, unknown>): string[];
     /** Check if a handler is registered for the given tag. */
     has(tagName: string): boolean;
     /** Get all registered tag names. */

package/dist/parser/workflow-extraction.d.ts

@@ -0,0 +1,39 @@
+/**
+ * How a source file's `@flowWeaver workflow` functions become workflow ASTs.
+ *
+ * Decides the two passes over a file: a signature pass (name, Start and Exit
+ * ports, async-ness) that lets workflows in the same file call each other as
+ * node types, and the full pass that turns a workflow's JSDoc config into
+ * instances and connections, expands its macros (`@autoConnect`, `@map`,
+ * `@path`, `@fanOut`, `@fanIn`, `@coerce`, `[expr: ...]` references), picks
+ * the node types the workflow carries (with `@fwImport` types and their stub
+ * fallbacks), and builds its options. Resolving an `@fwImport` is delegated to
+ * the caller, which owns the import state.
+ */
+import type { SourceFile } from 'ts-morph';
+import type { TNodeTypeAST, TWorkflowAST } from '../ast/types';
+import type { TagHandlerRegistry } from './tag-registry';
+/** Resolves one `@fwImport` annotation of the workflow in `currentFilePath` to a node type. */
+export type ImportAnnotationResolver = (imp: {
+    name: string;
+    functionName: string;
+    importSource: string;
+}, currentFilePath: string, warnings: string[]) => TNodeTypeAST;
+/**
+ * First pass: each workflow's name, Start and Exit ports and async-ness, with
+ * no instances or connections, so same-file workflows can be offered as node
+ * types before the full pass.
+ */
+export declare function extractWorkflowSignatures(sourceFile: SourceFile, filePath: string, warnings: string[], tagRegistry: TagHandlerRegistry): TWorkflowAST[];
+/**
+ * Convert a workflow to a node type.
+ * This allows workflows to be used as nodes in other workflows.
+ */
+export declare function workflowToNodeType(workflow: TWorkflowAST): TNodeTypeAST;
+/**
+ * Full pass: build the AST of every `@flowWeaver workflow` function in
+ * `sourceFile` against `availableNodeTypes`. Problems go to `errors` and
+ * `warnings`; each `@fwImport` is resolved through `resolveImport`.
+ */
+export declare function extractWorkflows(sourceFile: SourceFile, availableNodeTypes: TNodeTypeAST[], filePath: string, errors: string[], warnings: string[], tagRegistry: TagHandlerRegistry, resolveImport: ImportAnnotationResolver): TWorkflowAST[];
+//# sourceMappingURL=workflow-extraction.d.ts.map