@synergenius/flow-weaver 0.20.4 → 0.20.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. package/dist/api/validate.js +2 -0
  2. package/dist/cli/flow-weaver.mjs +396 -23
  3. package/dist/cli/templates/workflows/ai-agent.js +4 -1
  4. package/dist/cli/templates/workflows/ai-rag.js +1 -1
  5. package/dist/cli/templates/workflows/ai-react.js +3 -1
  6. package/dist/cli/templates/workflows/foreach.js +1 -0
  7. package/dist/doc-metadata/extractors/error-codes.d.ts +1 -1
  8. package/dist/doc-metadata/extractors/error-codes.js +50 -0
  9. package/dist/friendly-errors.js +65 -0
  10. package/dist/generated-version.d.ts +1 -1
  11. package/dist/generated-version.js +1 -1
  12. package/dist/generator/code-utils.js +24 -7
  13. package/dist/mcp/response-utils.js +8 -0
  14. package/dist/validation/design-rules.d.ts +61 -0
  15. package/dist/validation/design-rules.js +377 -0
  16. package/docs/reference/error-codes.md +74 -0
  17. package/package.json +5 -1
package/docs/reference/error-codes.md CHANGED
@@ -631,6 +631,73 @@ These codes apply to AI agent workflows that use LLM, tool-executor, and memory
631
631
  >
632
632
  > **What to do:** Connect the tool executor's data output ports (e.g., `result`) to downstream nodes that consume the data.
633
633
 
634
+ ### Design Quality Rules
635
+
636
+ These rules detect common workflow design problems that compile fine but indicate poor structure. All are warnings or info-level, suppressible with `@suppress`.
637
+
638
+ #### DESIGN_ASYNC_NO_ERROR_PATH (warning)
639
+
640
+ | Field | Value |
641
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
642
+ | Severity | Warning |
643
+ | Meaning | An async node has no onFailure connection. Async operations (network calls, file I/O, AI calls) can fail, and errors will be silently lost. |
644
+ | Common Causes | Adding an async node and connecting onSuccess but forgetting to wire onFailure. |
645
+ | Fix | Connect the node's `onFailure` port to an error handler, retry node, or `Exit.onFailure`. |
646
+
647
+ #### DESIGN_SCOPE_NO_FAILURE_EXIT (warning)
648
+
649
+ | Field | Value |
650
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
651
+ | Severity | Warning |
652
+ | Meaning | A scope node (retry/forEach) has no failure path out. If all iterations fail, execution stalls with no error surfaced upstream. |
653
+ | Common Causes | Creating a forEach or retry scope and only wiring the success path. |
654
+ | Fix | Connect the scope node's `onFailure` port to propagate errors. |
655
+
656
+ #### DESIGN_UNBOUNDED_RETRY (warning)
657
+
658
+ | Field | Value |
659
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
660
+ | Severity | Warning |
661
+ | Meaning | A scope node with retry/loop semantics (detected by name) has no visible attempt limit input. This could loop indefinitely on persistent failures. |
662
+ | Common Causes | Creating a custom retry loop without a maxAttempts or retries parameter. |
663
+ | Fix | Add a `maxAttempts` or `retries` input port to the node type, or use a counter to break out. |
664
+
665
+ #### DESIGN_FANOUT_NO_FANIN (warning)
666
+
667
+ | Field | Value |
668
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
669
+ | Severity | Warning |
670
+ | Meaning | A node fans out to 3+ step targets, but those paths never converge to a shared downstream node. Data from parallel branches may be lost. |
671
+ | Common Causes | Dispatching work to multiple parallel branches without a merge point before Exit. |
672
+ | Fix | Add a merge node downstream where parallel branches converge, or use a merge strategy on the target port. |
673
+
674
+ #### DESIGN_EXIT_DATA_UNREACHABLE (warning)
675
+
676
+ | Field | Value |
677
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
678
+ | Severity | Warning |
679
+ | Meaning | An Exit data port has no incoming connection and no pull-execution node provides it. Extends UNREACHABLE_EXIT_PORT with pull-execution awareness. |
680
+ | Common Causes | Declaring an exit port but never connecting any node output to it, and no pull-execution node wires to it. |
681
+ | Fix | Connect a node's data output to the Exit port, or add a pull-execution node that computes the value on demand. |
682
+
683
+ #### DESIGN_PULL_CANDIDATE (warning)
684
+
685
+ | Field | Value |
686
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
687
+ | Severity | Warning |
688
+ | Meaning | A node has no incoming step connection but its data outputs are consumed downstream. Without pullExecution, the node may never execute. |
689
+ | Common Causes | Adding a node and connecting its data outputs to downstream nodes but forgetting a step trigger or pullExecution config. |
690
+ | Fix | Add `[pullExecution: execute]` to the `@node` annotation so the node runs on demand. |
691
+
692
+ #### DESIGN_PULL_UNUSED (warning)
693
+
694
+ | Field | Value |
695
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
696
+ | Severity | Warning |
697
+ | Meaning | A node is marked with pullExecution but no downstream node reads its data output. Pull execution requires a consumer to trigger. |
698
+ | Common Causes | Setting pullExecution on a node but then not connecting any of its data outputs. |
699
+ | Fix | Connect a data output to a downstream node, or remove the pullExecution config if the node isn't needed. |
700
+
634
701
  ---
635
702
 
636
703
  ## Quick Reference: Error Severity Summary
@@ -690,4 +757,11 @@ These codes apply to AI agent workflows that use LLM, tool-executor, and memory
690
757
  | AGENT_MISSING_MEMORY_IN_LOOP | Loop has LLM but no conversation memory node |
691
758
  | AGENT_LLM_NO_FALLBACK | LLM onFailure routes directly to Exit |
692
759
  | AGENT_TOOL_NO_OUTPUT_HANDLING | Tool executor data outputs all unconnected |
760
+ | DESIGN_ASYNC_NO_ERROR_PATH | Async node has no onFailure connection |
761
+ | DESIGN_SCOPE_NO_FAILURE_EXIT | Scope node has no failure path out |
762
+ | DESIGN_UNBOUNDED_RETRY | Retry scope has no visible attempt limit |
763
+ | DESIGN_FANOUT_NO_FANIN | Fan-out to multiple step targets with no merge back |
764
+ | DESIGN_EXIT_DATA_UNREACHABLE | Exit data port has no connection and no pull-execution provider |
765
+ | DESIGN_PULL_CANDIDATE | Node has no step trigger but its outputs are consumed downstream |
766
+ | DESIGN_PULL_UNUSED | Pull-execution node has no downstream consumers |
693
767
  <!-- AUTO:END warning_summary_table -->
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@synergenius/flow-weaver",
3
- "version": "0.20.4",
3
+ "version": "0.20.6",
4
4
  "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
5
5
  "private": false,
6
6
  "type": "module",
@@ -86,6 +86,10 @@
86
86
  "./executor": {
87
87
  "types": "./dist/mcp/workflow-executor.d.ts",
88
88
  "default": "./dist/mcp/workflow-executor.js"
89
+ },
90
+ "./context": {
91
+ "types": "./dist/context/index.d.ts",
92
+ "default": "./dist/context/index.js"
89
93
  }
90
94
  },
91
95
  "bin": {