@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/parser/expression-references.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Upstream references inside `[expr: port="..."]` bindings.
+ *
+ * An expression may name `Start.<param>` or `<instanceId>.<outputPort>`,
+ * with any further property access after the port (`Start.expense.id`).
+ * Each reference is a data dependency of the bound port on that upstream
+ * port. The parser turns it into a connection flagged `derived`, so every
+ * consumer of `workflow.connections` (ordering, cycle detection, queries,
+ * the editor, the durable graph) sees the edge without knowing about
+ * expressions. The generator fetches the referenced values and substitutes
+ * them into the expression before evaluating it.
+ *
+ * What counts as a reference is decided syntactically, with the TypeScript
+ * parser rather than a regex, so text inside string literals is never
+ * mistaken for one and `${Start.path}` inside a template literal is:
+ *
+ * - the expression is parsed as TypeScript, and only a property access whose
+ *   object is a bare identifier is a candidate (`a.b`, not `f().b` or
+ *   `x[0].b`), and only dot access is recognised, not `Start["path"]`
+ * - the identifier must be `Start` or an instance id of this workflow, and
+ *   the property must be a declared data port of it
+ * - an identifier that is also a module-level binding of the file (an
+ *   import, a const, a class) is ambiguous when its property is a port, and
+ *   is left as plain JavaScript otherwise. Node type functions do not count
+ *   as shadowing bindings: `@node route route` is the common naming style
+ *   and `route.risk` on a function is never what an author means
+ *
+ * Anything that is not a reference is plain JavaScript, exactly as before.
+ */
+import type { TConnectionAST, TNodeInstanceAST, TNodeTypeAST, TPortDefinition } from '../ast/types';
+export interface ExpressionReference {
+    /** `Start` or an instance id */
+    root: string;
+    /** The port read on the root */
+    port: string;
+    /** Character offsets of the `root.port` text inside the expression */
+    start: number;
+    end: number;
+}
+/**
+ * Every `identifier.property` access in an expression whose identifier is one
+ * of the candidates. Nested access (`Start.expense.id`) yields one reference
+ * for `Start.expense`. The trailing `.id` stays in the expression text.
+ */
+export declare function findExpressionReferences(expression: string, candidates: ReadonlySet<string>): ExpressionReference[];
+/**
+ * Replace each reference's `root.port` text with the value `replacement`
+ * returns for it. Offsets are applied from the end so earlier ones stay valid.
+ */
+export declare function rewriteExpressionReferences(expression: string, refs: readonly ExpressionReference[], replacement: (ref: ExpressionReference) => string): string;
+export interface ExpandExpressionReferencesInput {
+    instances: TNodeInstanceAST[];
+    connections: TConnectionAST[];
+    findNodeType: (name: string) => TNodeTypeAST | undefined;
+    startPorts: Record<string, TPortDefinition>;
+    /** Top-level bindings of the file that are not node type functions */
+    moduleBindings: ReadonlySet<string>;
+    errors: string[];
+}
+/**
+ * Resolve every reference in every instance expression and append one
+ * derived connection per distinct (source port, target port) pair. Problems
+ * are reported as parse errors, phrased like the `@path` errors: the
+ * instance and port they concern come first.
+ */
+export declare function expandExpressionReferences(input: ExpandExpressionReferencesInput): void;
+/**
+ * Names declared at the top level of a source file that could be read by a
+ * bare identifier inside an expression: imports, variables, functions,
+ * classes and enums. Node type functions are excluded on purpose; see the
+ * module comment.
+ */
+export declare function collectModuleBindings(sourceFile: {
+    getImportDeclarations(): Array<{
+        getDefaultImport(): {
+            getText(): string;
+        } | undefined;
+        getNamespaceImport(): {
+            getText(): string;
+        } | undefined;
+        getNamedImports(): Array<{
+            getAliasNode(): {
+                getText(): string;
+            } | undefined;
+            getName(): string;
+        }>;
+    }>;
+    getVariableDeclarations(): Array<{
+        getName(): string;
+    }>;
+    getFunctions(): Array<{
+        getName(): string | undefined;
+    }>;
+    getClasses(): Array<{
+        getName(): string | undefined;
+    }>;
+    getEnums(): Array<{
+        getName(): string;
+    }>;
+}, nodeTypeFunctionNames: ReadonlySet<string>): Set<string>;
+//# sourceMappingURL=expression-references.d.ts.map

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

@@ -0,0 +1,69 @@
+/**
+ * Node types the caller supplies at parse time instead of the parser finding
+ * them in source (runtime-loaded or foreign pack nodes described by a wire
+ * manifest).
+ *
+ * Decides how such a descriptor becomes a full node type (which mandatory
+ * STEP ports it gets, which async/expression/durable flags carry over) and
+ * how it merges with the node types found in source: it fills a missing name,
+ * replaces a port-less `@fwImport` stub, and otherwise yields to the source.
+ */
+import type { TNodeTypeAST } from '../ast/types';
+/**
+ * Minimal external node type descriptor.
+ * Carries just enough information for the parser to validate node references
+ * and infer port directions. Passed with each request from the client layer.
+ */
+export type TExternalNodeType = {
+    name: string;
+    functionName?: string;
+    ports?: Array<{
+        name: string;
+        type?: string;
+        direction?: string;
+        defaultLabel?: string;
+    }>;
+    /**
+     * Whether the node's implementation is async (returns a Promise). The
+     * code generator emits `await` for the node's call ONLY when its
+     * nodeType is async. A missing/false value generates a synchronous
+     * call. Carrying it on the wire matters for runtime-provided foreign
+     * nodes resolved from a pack manifest (the on-device case): e.g.
+     * pack-core's `waitForApproval` is async, and without `isAsync` the
+     * generated workflow calls it un-awaited, so its resolved
+     * `{ approved, onSuccess, ... }` read back as `undefined` on a pending
+     * Promise and every downstream gate silently takes its `!execute` /
+     * failure path.
+     */
+    isAsync?: boolean;
+    /**
+     * Whether the node is an `@expression` node (data-in, data-out, no
+     * `execute` step port, so the generator calls it WITHOUT the leading
+     * `execute` argument and auto-sets `onSuccess`/`onFailure`). Carrying
+     * it on the wire matters for runtime-provided foreign nodes resolved
+     * from a pack manifest (the on-device case): e.g. pack-core's
+     * `resolveMonth(spec)` / `resolveFiscalYear(spec)` are expression
+     * nodes, and without `expression` the generated workflow calls them
+     * with the regular `(execute, ...args)` signature, so the boolean
+     * `execute` lands in the first data parameter (`spec`) and the node
+     * throws (`(spec ?? '').trim is not a function`) at run time.
+     */
+    expression?: boolean;
+    /** Explicit compiler-known durable gate boundary. */
+    durableGate?: 'approval' | 'input' | 'agent' | 'timer';
+    /** Requires the durable idempotency/receipt effect contract. */
+    durableEffect?: boolean;
+    /** Explicitly safe to restore/skip without an effect receipt. */
+    durablePure?: boolean;
+    /** Retry/fallback behavior implemented inside the external adapter. */
+    resilience?: {
+        retries?: number;
+        fallback?: string;
+    };
+};
+/**
+ * Merge external (runtime-loaded) node types into `nodeTypes`, in place, so the
+ * parser can validate references to them.
+ */
+export declare function mergeExternalNodeTypes(nodeTypes: TNodeTypeAST[], externalNodeTypes: TExternalNodeType[]): void;
+//# sourceMappingURL=external-node-types.d.ts.map

package/dist/{function-like.d.ts → parser/function-like.d.ts}

@@ -30,11 +30,18 @@ export interface FunctionLike {
  * Scan a source file and return every function-like declaration that could
  * carry @flowWeaver annotations:
  *
- *  1. Classic `function foo() {}`         — FunctionDeclaration (existing)
- *  2. `const foo = () => {}`              — ArrowFunction assigned to variable
- *  3. `const foo = function() {}`         — FunctionExpression assigned to variable
+ *  1. Classic `function foo() {}`         : FunctionDeclaration (existing)
+ *  2. `const foo = () => {}`              : ArrowFunction assigned to variable
+ *  3. `const foo = function() {}`         : FunctionExpression assigned to variable
  *
  * The returned list preserves source order.
  */
 export declare function extractFunctionLikes(sourceFile: SourceFile): FunctionLike[];
+/**
+ * Warnings for functions annotated `@flowWeaver` that are not at the top
+ * level of the file. Only top-level functions are read as node types and
+ * workflows, so a nested one is skipped; without a word the author sees an
+ * unknown node type and no reason.
+ */
+export declare function nestedAnnotationWarnings(sourceFile: SourceFile): string[];
 //# sourceMappingURL=function-like.d.ts.map

package/dist/parser/generated-sections.d.ts

@@ -0,0 +1,25 @@
+/**
+ * In-place generation markers.
+ *
+ * `fw compile` writes generated code into the authored file between these
+ * marker comments. The parser has to recognize and strip those sections before
+ * it reads annotations, and the in-place generator writes them, so the markers
+ * and the helpers that detect and remove them live here, below both.
+ */
+export declare const MARKERS: {
+    RUNTIME_START: string;
+    RUNTIME_END: string;
+    BODY_START: string;
+    BODY_END: string;
+    IMPORTS_START: string;
+    IMPORTS_END: string;
+};
+/**
+ * Check if source code has in-place generation markers
+ */
+export declare function hasInPlaceMarkers(source: string): boolean;
+/**
+ * Remove all generated sections from source code
+ */
+export declare function stripGeneratedSections(source: string): string;
+//# sourceMappingURL=generated-sections.d.ts.map

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

@@ -0,0 +1,67 @@
+/**
+ * How a workflow file's imports become node types.
+ *
+ * Decides which relative imports are followed (annotated sources only, data
+ * files skipped), how an imported file's node types, workflows and inferable
+ * functions are exposed through its named imports, how npm packages and
+ * `@fwImport` annotations are inferred from their `.d.ts` declarations
+ * (following re-export barrels), when a circular import is an error or a
+ * warning, and when a cached import result is still valid (the mtime of the
+ * file and of every file it read). The caches and the import stack are owned
+ * by the caller and passed in as an `ImportContext`.
+ */
+import type { Project } from 'ts-morph';
+import type { TNodeTypeAST } from '../ast/types';
+import type { LRUCache } from '../utils/lru-cache';
+import type { TagHandlerRegistry } from './tag-registry';
+import { type SourceImportResolver, type SourceOverrideLoader } from './module-resolution';
+/** A file the parse read, with the mtime it had. Cache entries are valid only while every one is unchanged. */
+export type FileDependency = {
+    path: string;
+    mtime: number;
+};
+/** True when every recorded dependency still has the mtime it had when the entry was cached. */
+export declare function dependenciesUnchanged(deps: FileDependency[]): boolean;
+/** A cached import: the node types a file (or an npm package, keyed `npm:<name>`) provides. */
+export type ImportCacheEntry = {
+    mtime: number;
+    nodeTypes: TNodeTypeAST[];
+    deps: FileDependency[];
+};
+/** The import state of one parser, shared by every import resolved during a parse. */
+export interface ImportContext {
+    project: Project;
+    tagRegistry: TagHandlerRegistry;
+    importCache: LRUCache<string, ImportCacheEntry>;
+    /** Files being processed, outermost first, for circular import detection. */
+    importStack: Set<string>;
+    /**
+     * Dependency recorders for the parses in progress: the outer entry belongs to
+     * the workflow file, and each imported file being processed pushes its own so
+     * its importCache entry can list what it read. A file read while any recorder
+     * is active is added to all of them.
+     */
+    dependencyRecorders: Map<string, number>[];
+}
+/**
+ * The node types `sourceFile` imports: named imports of npm packages (from
+ * their `.d.ts`) and of relative annotated sources (their node types,
+ * workflows and inferable functions). A missing relative source or a
+ * circular import throws.
+ */
+export declare function extractImportedNodeTypes(ctx: ImportContext, sourceFile: ReturnType<Project['addSourceFileAtPath']>, currentFilePath: string, importResolver?: SourceImportResolver, sourceLoader?: SourceOverrideLoader, warnings?: string[]): TNodeTypeAST[];
+/**
+ * Resolve an @fwImport annotation to a properly inferred node type.
+ * Supports both npm packages (e.g., "lodash") and relative paths (e.g., "./utils").
+ *
+ * @param imp - The import annotation from JSDoc
+ * @param currentFilePath - Path of the workflow file containing the @fwImport
+ * @param warnings - Array to collect warnings
+ * @returns Inferred TNodeTypeAST, or a stub if inference fails
+ */
+export declare function resolveImportAnnotation(ctx: ImportContext, imp: {
+    name: string;
+    functionName: string;
+    importSource: string;
+}, currentFilePath: string, warnings: string[]): TNodeTypeAST;
+//# sourceMappingURL=import-resolution.d.ts.map

package/dist/parser/import-stub.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The generic node type an `@fwImport` degrades to when its source cannot be
+ * read, and how to recognize one later.
+ *
+ * Decides the stub's shape (no inputs, a single `{ result }` output, marked as
+ * an expression) and the structural test that lets a real node type with the
+ * same name, supplied by the caller or found elsewhere, take its place.
+ */
+import type { TNodeTypeAST } from '../ast/types';
+/**
+ * Create a stub node type for @fwImport when proper inference fails.
+ * This provides graceful degradation rather than failing completely.
+ */
+export declare function createImportStub(imp: {
+    name: string;
+    functionName: string;
+    importSource: string;
+}): TNodeTypeAST;
+/**
+ * Is `nt` the generic import stub `createImportStub` emits when an
+ * `@fwImport` package cannot be resolved on disk? Such a stub carries an
+ * `importSource`, no inputs, and a single `{ result }` output. We detect
+ * it structurally (rather than tagging the AST) so a caller-supplied
+ * `externalNodeType` with the real port shape can replace it during the
+ * `fullParse` merge. A real imported type (resolved from a readable
+ * `.d.ts`) has its actual ports and is left untouched.
+ */
+export declare function isImportStub(nt: TNodeTypeAST): boolean;
+//# sourceMappingURL=import-stub.d.ts.map

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

@@ -0,0 +1,209 @@
+/**
+ * What the JSDoc parser hands back.
+ *
+ * A `@flowWeaver nodeType` block becomes a `JSDocNodeTypeConfig` and a
+ * `@flowWeaver workflow` block a `JSDocWorkflowConfig`: plain records of what
+ * the tags said, with port types already read from the function signature.
+ * Turning them into AST nodes, expanding the sugar tags and validating the
+ * graph happen later, in node-inference and workflow-extraction.
+ */
+import type { TDataType, TPortConfig, TMergeStrategy, TNodeTagAST, TSerializableValue, THttpRoute, TCoerceTargetType } from '../../ast/types';
+export interface JSDocNodeTypeConfig {
+    name?: string;
+    label?: string;
+    description?: string;
+    color?: string;
+    icon?: string;
+    tags?: Array<{
+        label: string;
+        tooltip?: string;
+    }>;
+    executeWhen?: string;
+    scope?: string;
+    expression?: boolean;
+    /** Retry/fallback behavior implemented inside the node adapter. */
+    resilience?: {
+        retries?: number;
+        fallback?: string;
+    };
+    defaultConfig?: {
+        pullExecution?: {
+            triggerPort: string;
+        };
+        label?: string;
+        description?: string;
+    };
+    inputs?: Record<string, {
+        type: TDataType;
+        defaultValue?: unknown;
+        optional?: boolean;
+        label?: string;
+        expression?: string;
+        scope?: string;
+        mergeStrategy?: TMergeStrategy;
+        hidden?: boolean;
+        metadata?: {
+            order?: number;
+        };
+        tsType?: string;
+    }>;
+    outputs?: Record<string, {
+        type: TDataType;
+        label?: string;
+        scope?: string;
+        hidden?: boolean;
+        metadata?: {
+            order?: number;
+        };
+        tsType?: string;
+    }>;
+    /** Per-target deploy config from @deploy annotations on nodeType */
+    deploy?: Record<string, Record<string, unknown>>;
+}
+export interface JSDocWorkflowConfig {
+    name?: string;
+    description?: string;
+    strictTypes?: boolean;
+    /** NPM package imports - external node types persisted in JSDoc */
+    imports?: Array<{
+        name: string;
+        functionName: string;
+        importSource: string;
+    }>;
+    instances?: Array<{
+        id: string;
+        type: string;
+        parentScope?: string;
+        label?: string;
+        portConfigs?: TPortConfig[];
+        pullExecution?: {
+            triggerPort: string;
+        };
+        minimized?: boolean;
+        color?: string;
+        icon?: string;
+        tags?: TNodeTagAST[];
+        width?: number;
+        height?: number;
+        sourceLocation?: {
+            line: number;
+            column: number;
+        };
+        /** Generic `[key: "value"]` bracket attributes, kept for packs to read. */
+        attributes?: Record<string, string>;
+        suppressWarnings?: string[];
+    }>;
+    connections?: Array<{
+        from: {
+            node: string;
+            port: string;
+            scope?: string;
+        };
+        to: {
+            node: string;
+            port: string;
+            scope?: string;
+        };
+        sourceLocation?: {
+            line: number;
+            column: number;
+        };
+        /** Explicit coercion from `@connect a.b -> c.d as <type>`. */
+        coerce?: TCoerceTargetType;
+    }>;
+    scopes?: Record<string, string[]>;
+    startPorts?: Record<string, {
+        dataType?: TDataType;
+        label?: string;
+        optional?: boolean;
+        default?: TSerializableValue;
+        metadata?: {
+            order?: number;
+        };
+    }>;
+    returnPorts?: Record<string, {
+        dataType: TDataType;
+        label?: string;
+        metadata?: {
+            order?: number;
+        };
+    }>;
+    /** When true, auto-wire linear connections between nodes in declaration order */
+    autoConnect?: boolean;
+    /** @map sugar macros that expand to full scope patterns */
+    maps?: Array<{
+        instanceId: string;
+        childId: string;
+        sourceNode: string;
+        sourcePort: string;
+        inputPort?: string;
+        outputPort?: string;
+    }>;
+    /** @path sugar macros that expand to multi-step execution routes with scope walking */
+    paths?: Array<{
+        steps: Array<{
+            node: string;
+            route?: 'ok' | 'fail';
+        }>;
+    }>;
+    /** @fanOut macros that expand to 1-to-N connections */
+    fanOuts?: Array<{
+        source: {
+            node: string;
+            port: string;
+        };
+        targets: Array<{
+            node: string;
+            port?: string;
+        }>;
+    }>;
+    /** @fanIn macros that expand to N-to-1 connections */
+    fanIns?: Array<{
+        sources: Array<{
+            node: string;
+            port?: string;
+        }>;
+        target: {
+            node: string;
+            port: string;
+        };
+    }>;
+    /** @coerce macros that expand to synthetic coercion nodes + connections */
+    coercions?: Array<{
+        instanceId: string;
+        source: {
+            node: string;
+            port: string;
+        };
+        target: {
+            node: string;
+            port: string;
+        };
+        targetType: 'string' | 'number' | 'boolean' | 'json' | 'object';
+    }>;
+    /** @trigger annotation: event name and/or cron schedule */
+    trigger?: {
+        event?: string;
+        cron?: string;
+    };
+    /** @http annotations: the routes the workflow is served on */
+    http?: THttpRoute[];
+    /** @cancelOn annotation: cancel on matching external event */
+    cancelOn?: {
+        event: string;
+        match?: string;
+        timeout?: string;
+    };
+    /** @retries annotation: retry count */
+    retries?: number;
+    /** @timeout annotation: function-level timeout */
+    timeout?: string;
+    /** @throttle annotation: rate limiting */
+    throttle?: {
+        limit: number;
+        period?: string;
+    };
+    /** @deploy target key=value pairs */
+    deploy?: Record<string, Record<string, unknown>>;
+}
+//# sourceMappingURL=config-types.d.ts.map

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

@@ -0,0 +1,54 @@
+/**
+ * How a workflow block's graph tags are read.
+ *
+ * `@fwImport` (npm node types), `@node` (instances, with their port order,
+ * labels and expressions folded into port configs and the tag's line kept as
+ * the source location), `@connect`, `@scope`, and the sugar tags `@map`,
+ * `@path`, `@fanOut`, `@fanIn` and `@coerce`, which are recorded here and
+ * expanded later. Node positions are no longer part of the grammar: a leftover
+ * `@position` line or `[position: x y]` attribute is dropped with a warning.
+ * A line the grammar rejects is a warning and is skipped.
+ */
+import type { JSDocTag } from 'ts-morph';
+import type { JSDocWorkflowConfig } from './config-types';
+export declare const positionGone: (where: string) => string;
+/**
+ * Parse @fwImport tag for npm package node types.
+ * Format: @fwImport nodeName functionName from "packageName"
+ * Examples:
+ *   @fwImport npm/autoprefixer/autoprefixer autoprefixer from "autoprefixer"
+ *   @fwImport npm/lodash/map map from "lodash"
+ * Note: We use @fwImport instead of @import because TypeScript treats @import specially
+ * and truncates the first word as a type annotation.
+ */
+export declare function parseImportTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+/**
+ * Parse @node tag using Chevrotain parser.
+ * Supports: @node instanceId nodeType [parentScope] [label: "..."] [portOrder: port=N] [portLabel: port="label"] [expr: port="val"] [minimized] [pullExecution: triggerPort]
+ */
+export declare function parseNodeTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+/**
+ * Parse @connect tag using Chevrotain parser.
+ * Supports: node.port -> node.port and node.port:scope -> node.port:scope
+ */
+export declare function parseConnectTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+/**
+ * Parse @scope tag using Chevrotain parser.
+ * Format: @scope scopeName [child1, child2] or @scope container.scopeName [child1, child2]
+ */
+export declare function parseScopeTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+/**
+ * Parse @map tag using Chevrotain parser.
+ * Format: @map instanceId childNode over source.port
+ * Or:     @map instanceId childNode(inputPort -> outputPort) over source.port
+ */
+export declare function parseMapTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+/**
+ * Parse @path tag using Chevrotain parser.
+ * Format: @path Start -> validator:ok -> classifier -> urgencyRouter:fail -> escalate -> Exit
+ */
+export declare function parsePathTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+export declare function parseFanOutTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+export declare function parseFanInTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+export declare function parseCoerceTag(tag: JSDocTag, config: JSDocWorkflowConfig, warnings: string[]): void;
+//# sourceMappingURL=graph-tags.d.ts.map

package/dist/parser/jsdoc/node-type-block.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How a `@flowWeaver nodeType` (or `@flowWeaver node`) JSDoc block becomes a
+ * node-type config.
+ *
+ * Picks the first JSDoc block that declares one, takes the free text above
+ * the tags as the description, and reads each tag in order: the presentation
+ * tags (`@name`, `@label`, `@color`, `@icon`, `@tag`, ...), execution tags
+ * (`@executeWhen`, `@scope`, `@expression`, `@pullExecution`,
+ * `@resilience`), ports (see port-tags) and `@deploy`. `@flowWeaver node` is
+ * the shorthand for an expression node. A workflow-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 { JSDocNodeTypeConfig } from './config-types';
+/**
+ * Parse @flowWeaver nodeType from JSDoc comments.
+ * When a TagHandlerRegistry is provided, unknown tags are checked against it
+ * before being reported as warnings.
+ */
+export declare function parseNodeType(func: FunctionLike, warnings: string[], tagRegistry?: TagHandlerRegistry): JSDocNodeTypeConfig | null;
+//# sourceMappingURL=node-type-block.d.ts.map

package/dist/parser/jsdoc/parse-line-once.d.ts

@@ -0,0 +1,11 @@
+/**
+ * When a rejected annotation line gets a fallback warning: only when the
+ * grammar rejected it without saying why, so each bad line is reported once.
+ */
+/**
+ * Run a line parser so each bad line is reported once. When the parser already
+ * said why it rejected the line, that warning stands alone; `fallback` is used
+ * only when the line was rejected without one (a line the lexer cannot read).
+ */
+export declare function parseLineOnce<T>(parse: (line: string, warnings: string[]) => T | null, line: string, warnings: string[], fallback: string): T | null;
+//# sourceMappingURL=parse-line-once.d.ts.map

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

@@ -0,0 +1,42 @@
+/**
+ * How a port tag becomes a port.
+ *
+ * Node types declare ports with `@input`, `@output` and `@step`; workflows
+ * with `@param` and `@returns`. Each line goes through the port grammar, then
+ * this decides the port's type (reserved control ports are always STEP, the
+ * rest come from the signature, see signature-types), its label or
+ * `Expression:` description, optional flag, default value (JSON when it
+ * parses, the raw text otherwise), scope, merge strategy, visibility and
+ * order metadata. A second declaration of the same port is a warning and
+ * overwrites the first.
+ */
+import type { JSDocTag } from 'ts-morph';
+import type { FunctionLike } from '../function-like';
+import type { JSDocNodeTypeConfig, JSDocWorkflowConfig } from './config-types';
+/**
+ * Parse @input tag using Chevrotain parser.
+ * Supports: @input name, @input [name], @input [name=default]
+ * With optional: scope:scopeName, [order:N], [placement:TOP/BOTTOM], - description
+ */
+export declare function parseInputTag(tag: JSDocTag, config: JSDocNodeTypeConfig, func: FunctionLike, warnings: string[]): void;
+/**
+ * Parse @output tag using Chevrotain parser.
+ * Supports: @output name, scope:scopeName, [order:N], - description
+ */
+export declare function parseOutputTag(tag: JSDocTag, config: JSDocNodeTypeConfig, func: FunctionLike, warnings: string[]): void;
+/**
+ * Parse @step tag using Chevrotain parser.
+ * Used for explicit STEP/control-flow ports that are not reserved.
+ */
+export declare function parseStepTag(tag: JSDocTag, config: JSDocNodeTypeConfig, func: FunctionLike, warnings: string[]): void;
+/**
+ * Parse @return/@returns tag for workflow functions using Chevrotain.
+ * Format: @returns name [order:N] - Description (type inferred from signature)
+ */
+export declare function parseReturnTag(tag: JSDocTag, config: JSDocWorkflowConfig, func: FunctionLike | undefined, warnings: string[]): void;
+/**
+ * Parse @param tag for workflow functions using Chevrotain.
+ * Format: @param name [order:N] - Description (type inferred from signature)
+ */
+export declare function parseParamTag(tag: JSDocTag, config: JSDocWorkflowConfig, func: FunctionLike | undefined, warnings: string[]): void;
+//# sourceMappingURL=port-tags.d.ts.map