/**
 * JSDoc annotation parser for Flow Weaver
 *
 * Parses @flowWeaver annotations from JSDoc comments.
 */
import type { FunctionLike } from './function-like.js';
import type { TDataType, TPortConfig, TMergeStrategy, TNodeTagAST } from './ast/types.js';
import type { TagHandlerRegistry } from './parser/tag-registry.js';
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;
    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;
        x?: number;
        y?: number;
        sourceLocation?: {
            line: number;
            column: number;
        };
        /** CI/CD job group */
        job?: string;
        /** CI/CD deployment environment */
        environment?: string;
        suppressWarnings?: string[];
    }>;
    connections?: Array<{
        from: {
            node: string;
            port: string;
            scope?: string;
        };
        to: {
            node: string;
            port: string;
            scope?: string;
        };
        sourceLocation?: {
            line: number;
            column: number;
        };
    }>;
    scopes?: Record<string, string[]>;
    layout?: Record<string, {
        x: number;
        y: number;
    }>;
    startPorts?: Record<string, {
        dataType?: TDataType;
        label?: string;
        metadata?: {
            order?: number;
        };
    }>;
    returnPorts?: Record<string, {
        dataType: TDataType;
        label?: string;
        metadata?: {
            order?: number;
        };
    }>;
    positions?: Record<string, {
        x: number;
        y: 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;
    };
    /** @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>>;
}
export interface JSDocPatternConfig {
    name?: string;
    description?: string;
    instances?: Array<{
        id: string;
        nodeType: string;
        config?: {
            x?: number;
            y?: number;
        };
    }>;
    connections?: Array<{
        from: {
            node: string;
            port: string;
        };
        to: {
            node: string;
            port: string;
        };
    }>;
    ports?: Array<{
        direction: 'IN' | 'OUT';
        name: string;
        description?: string;
    }>;
    positions?: Record<string, {
        x: number;
        y: number;
    }>;
}
export declare class JSDocParser {
    /**
     * Parse @flowWeaver nodeType from JSDoc comments.
     * When a TagHandlerRegistry is provided, unknown tags are checked against it
     * before being reported as warnings.
     */
    parseNodeType(func: FunctionLike, warnings: string[], tagRegistry?: TagHandlerRegistry): JSDocNodeTypeConfig | null;
    /**
     * Parse @flowWeaver workflow from JSDoc comments.
     * When a TagHandlerRegistry is provided, unknown tags are checked against it
     * before being reported as warnings.
     */
    parseWorkflow(func: FunctionLike, warnings: string[], tagRegistry?: TagHandlerRegistry): JSDocWorkflowConfig | null;
    /**
     * Parse @flowWeaver pattern from JSDoc comments
     */
    parsePattern(func: FunctionLike, warnings: string[]): JSDocPatternConfig | null;
    /**
     * Parse @node tag for patterns.
     * Format: @node instanceId nodeType
     */
    private parsePatternNodeTag;
    /**
     * Parse @position tag for patterns.
     * Format: @position nodeId x y
     */
    private parsePatternPositionTag;
    /**
     * Parse @connect tag for patterns.
     * Supports IN/OUT pseudo-nodes: IN.port -> node.port, node.port -> OUT.port
     */
    private parsePatternConnectTag;
    /**
     * Parse @port tag for patterns.
     * Format: @port IN.name - description OR @port OUT.name - description
     */
    private parsePatternPortTag;
    /**
     * Parse @input tag using Chevrotain parser.
     * Supports: @input name, @input [name], @input [name=default]
     * With optional: scope:scopeName, [order:N], [placement:TOP/BOTTOM], - description
     */
    private parseInputTag;
    /**
     * Parse @output tag using Chevrotain parser.
     * Supports: @output name, scope:scopeName, [order:N], - description
     */
    private parseOutputTag;
    /**
     * Parse @step tag using Chevrotain parser.
     * Used for explicit STEP/control-flow ports that are not reserved.
     */
    private parseStepTag;
    /**
     * Parse @return/@returns tag for workflow functions using Chevrotain.
     * Format: @returns name [order:N] - Description (type inferred from signature)
     */
    private parseReturnTag;
    /**
     * Parse @param tag for workflow functions using Chevrotain.
     * Format: @param name [order:N] - Description (type inferred from signature)
     */
    private parseParamTag;
    /**
     * 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.
     */
    private parseImportTag;
    /**
     * Parse @node tag using Chevrotain parser.
     * Supports: @node instanceId nodeType [parentScope] [label: "..."] [portOrder: port=N] [portLabel: port="label"] [expr: port="val"] [minimized] [pullExecution: triggerPort]
     */
    private parseNodeTag;
    /**
     * Parse @position tag using Chevrotain parser.
     * Supports: @position nodeId x y
     */
    private parsePositionTag;
    /**
     * Parse @connect tag using Chevrotain parser.
     * Supports: node.port -> node.port and node.port:scope -> node.port:scope
     */
    private parseConnectTag;
    /**
     * Parse @scope tag using Chevrotain parser.
     * Format: @scope scopeName [child1, child2] or @scope container.scopeName [child1, child2]
     */
    private parseScopeTag;
    /**
     * Parse @map tag using Chevrotain parser.
     * Format: @map instanceId childNode over source.port
     * Or:     @map instanceId childNode(inputPort -> outputPort) over source.port
     */
    private parseMapTag;
    /**
     * Parse @path tag using Chevrotain parser.
     * Format: @path Start -> validator:ok -> classifier -> urgencyRouter:fail -> escalate -> Exit
     */
    private parsePathTag;
    private parseFanOutTag;
    private parseFanInTag;
    private parseCoerceTag;
    /**
     * Parse @trigger tag using Chevrotain parser.
     * Delegates unrecognized trigger formats to the tag registry (e.g. CI/CD triggers).
     */
    private parseTriggerTag;
    /**
     * Parse @cancelOn tag using Chevrotain parser.
     */
    private parseCancelOnTag;
    /**
     * Parse @throttle tag using Chevrotain parser.
     */
    private parseThrottleTag;
    /**
     * Parse @deploy tag.
     * Format: @deploy <target> key=value key2="value with spaces" key3=123 key4=true
     *
     * Examples:
     *   @deploy github-actions action="actions/checkout@v4"
     *   @deploy my-target durableSteps=true framework="next" retries=3
     *   @deploy another-target memory=256 timeout=30
     *
     * Values are auto-coerced: "true"/"false" → boolean, numeric strings → number.
     */
    private parseDeployTag;
    /**
     * Parse default value from string
     */
    private parseDefaultValue;
}
export declare const jsdocParser: JSDocParser;
//# sourceMappingURL=jsdoc-parser.d.ts.map