@synergenius/flow-weaver 0.2.0

package/dist/parser.d.ts

@@ -0,0 +1,204 @@
+import { Project } from 'ts-morph';
+import type { TNodeTypeAST, TWorkflowAST, TPatternAST } from './ast/types.js';
+export interface ParseResult {
+    workflows: TWorkflowAST[];
+    nodeTypes: TNodeTypeAST[];
+    patterns: TPatternAST[];
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * 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;
+    }>;
+};
+/** Exposed for tests that need direct access to the shared ts-morph Project */
+export declare function getParserProject(): Project;
+export declare class AnnotationParser {
+    private project;
+    private importCache;
+    private importStack;
+    private parseCache;
+    constructor();
+    private computeHash;
+    private detectMinorEdit;
+    private patchAST;
+    parse(filePath: string, externalNodeTypes?: TExternalNodeType[]): ParseResult;
+    private fullParse;
+    /**
+     * Parse workflow from a string instead of a file path.
+     * Useful for testing and in-memory operations.
+     *
+     * Note: Imports from other workflow files are NOT supported in this mode
+     * since there's no filesystem context. Use parse() for files with imports.
+     *
+     * @param code - TypeScript source code containing workflow definitions
+     * @param virtualPath - Virtual file path for error messages (default: 'virtual.ts')
+     * @returns ParseResult with workflows and nodeTypes
+     */
+    parseFromString(code: string, virtualPath?: string): ParseResult;
+    clearCache(): void;
+    /** Clear only the parse result cache, keeping the import/node-type cache intact. */
+    clearParseCache(): void;
+    private resolveModulePath;
+    private extractImportedNodeTypes;
+    /**
+     * Resolve npm package imports to node types by reading `.d.ts` declarations.
+     * Only named imports of exported functions are resolved.
+     */
+    private resolveNpmPackageTypes;
+    /**
+     * 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
+     */
+    private resolveImportAnnotation;
+    /**
+     * Resolve a relative path @fwImport to a node type by reading the local file.
+     * Includes circular dependency detection using importStack.
+     */
+    private resolveLocalImportAnnotation;
+    /**
+     * Resolve an npm package @fwImport to a node type by reading .d.ts declarations.
+     */
+    private resolveNpmImportAnnotation;
+    /**
+     * Create a stub node type for @fwImport when proper inference fails.
+     * This provides graceful degradation rather than failing completely.
+     */
+    private createImportStub;
+    private extractNodeTypes;
+    /**
+     * Extract workflow signatures (metadata only) without validating instances.
+     * This enables same-file workflow invocation by making workflow ports available
+     * before the full workflow extraction pass.
+     */
+    private extractWorkflowSignatures;
+    /**
+     * Convert a workflow to a node type.
+     * This allows workflows to be used as nodes in other workflows.
+     */
+    private workflowToNodeType;
+    private extractWorkflows;
+    /**
+     * Extract patterns from a source file.
+     * Patterns are defined with @flowWeaver pattern annotation.
+     */
+    private extractPatterns;
+    /**
+     * Infer a TNodeTypeAST from a single function's TypeScript signature.
+     * Shared helper used by both same-file and cross-file inference.
+     */
+    private inferNodeTypeFromFunction;
+    /**
+     * Pre-infer ALL unannotated functions from a source file.
+     * Used for imported files so the named-import filter can scope them.
+     */
+    private inferAllUnannotatedFunctions;
+    /**
+     * 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.
+     */
+    private inferNodeTypesFromUnannotated;
+    /**
+     * Expand a @map macro into synthetic node type, instances, connections, and scope.
+     *
+     * @map loop proc over scan.files
+     *
+     * Expands to:
+     * - A synthetic MAP_ITERATOR node type for "loop" with scoped ports
+     * - An instance "loop" of that synthetic type
+     * - The child instance "proc" placed inside loop.iterate scope
+     * - All scoped connections auto-generated
+     * - Upstream connection from scan.files -> loop.items
+     */
+    private expandMapMacro;
+    /**
+     * Expand @path macros into multi-step execution routes with scope walking.
+     * Processes all paths together for shared deduplication.
+     */
+    private expandPathMacros;
+    /**
+     * 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
+     */
+    private generateAutoConnections;
+    private parseStartPorts;
+    private parseExitPorts;
+    /**
+     * Extract schema breakdown for complex types (interfaces/objects).
+     * Returns a map of property names to their TypeScript type strings.
+     */
+    private extractTypeSchema;
+    private inferPortType;
+    /**
+     * Check if a function has a valid @flowWeaver annotation (nodeType, workflow, or pattern).
+     * Avoids false positives from file-level JSDoc that mentions @flowWeaver in description text.
+     */
+    private hasFlowWeaverAnnotation;
+    /**
+     * Generate an annotation suggestion for ghost-text autocomplete.
+     * Analyzes the function nearest to cursorLine, diffs inferred ports against
+     * any existing @flowWeaver annotation, and returns only the missing lines.
+     */
+    generateAnnotationSuggestion(content: string, cursorLine: number, virtualPath?: string): {
+        text: string;
+        insertLine: number;
+        replaceLinesCount: number;
+    } | null;
+    /**
+     * Check if a function's JSDoc marks it as a workflow (vs nodeType).
+     */
+    private isWorkflowBlock;
+    /**
+     * Generate missing @connect suggestions for a workflow block.
+     * Finds @node declarations, resolves their types, and suggests connections
+     * for matching port names that aren't already wired.
+     */
+    private generateWorkflowStructureSuggestion;
+    /**
+     * Extract port names that are already annotated in a function's JSDoc.
+     * Returns sets of input and output port names found in existing annotations.
+     */
+    private extractExistingAnnotatedPorts;
+    private capitalize;
+}
+export declare const parser: AnnotationParser;
+/**
+ * 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=parser.d.ts.map