(wip) Significant cleanup of BAML Graphs

[cg-jl]

Taking a look at how the current implementation of BAML Graphs works, & working
through data separation to make DX & understanding the pipeline easier.

So far:

• Java-style "hoard-it-all" builder that owns everything. Not bad on its own, just not correctly applied here.
• Lots of .clone() where a & is enough. Missing a couple of places due to required lifetime separations.
• Too much coupling in builder between pre-built data structures & builder-local DS.
• Seemingly, too many stages/abstractions in the pipeline:
  • HeaderIndex usefulness is indeterminate. The tree structure it contains is not homogeneous enough
    to make for direct traversal, & that shows up in GraphBuilder.
  • Graph is a useful but not-needed yet separation.
• Currently simplifying the logic. That will show how much information is required.

---

Important

Refactor BAML Graphs by modularizing diagram generation, simplifying graph logic, and renaming for clarity.

• Refactoring:
  • Move BamlVisDiagramGenerator logic to diagram_generator module in baml_vis.
  • Split graph logic into graph.rs for better separation of concerns.
• Renaming:
  • Rename BamlVisDiagramGenerator to diagram_generator in imports and usage across generate_mermaid_headers.rs, runtime_interface.rs, and mermaid_graph_tests.rs.
• Code Simplification:
  • Simplify graph building logic by reducing unnecessary abstractions and stages.
  • Remove redundant .clone() calls where & references suffice.
• Miscellaneous:
  • Update SHOW_CALL_NODES constant usage in diagram_generator.rs and graph.rs.

^{This description was created by for 9ec5b21. You can customize this summary. It will automatically update as commits are pushed.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
promptfiddle	Error			Oct 17, 2025 8:34pm

💡 Enable Vercel Agent with $100 free credit for automated AI reviews

[entelligence-ai-pr-reviews]

🔒 Entelligence AI Vulnerability Scanner

✅ No security vulnerabilities found!

Your code passed our comprehensive security analysis.

---

[entelligence-ai-pr-reviews]

LGTM 👍

[github-actions]

🌿 Preview your docs: https://boundary-preview-98691528-bc41-4c2a-8f18-a2c61cc470bf.docs.buildwithfern.com

[github-actions]

https://sage-backend-2asd5zgw1-baml.vercel.app

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 9ec5b21 in 2 minutes and 38 seconds. Click for details.

• Reviewed 1648 lines of code in 8 files
• Skipped 0 files when reviewing.
• Skipped posting 8 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. engine/baml-lib/ast/examples/generate_mermaid_headers.rs:3

• Draft comment:
  Good update – using 'diagram_generator' instead of the deprecated builder. Ensure example reflects the new API.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 30% <= threshold 50% The comment is informative and suggests ensuring that examples reflect the new API. However, it doesn't ask for a specific test or code change, nor does it provide a specific suggestion or question about the code. It seems to be more of a reminder than a specific actionable comment.

2. engine/baml-lib/ast/src/ast.rs:32

• Draft comment:
  Re-exporting the new 'diagram_generator' module replaces the old BamlVisDiagramGenerator – looks correct.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% This comment is purely informative and does not provide any actionable feedback or suggestions. It simply states that the re-export looks correct, which is not useful for the PR author.

3. engine/baml-lib/ast/src/ast/baml_vis.rs:18

• Draft comment:
  Deprecated code for BamlVisDiagramGenerator has been removed in favor of the new module. This cleanup is clear.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% This comment is purely informative, stating that deprecated code has been removed. It doesn't provide any actionable feedback or suggestions for improvement.

4. engine/baml-lib/ast/src/ast/baml_vis/graph.rs:604

• Draft comment:
  Unreachable code detected in 'merge_by_pos': the early 'return' prevents the subsequent iterator implementation from ever executing. Consider removing the dead code.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 0% vs. threshold = 50% In Rust, when you define a type and implement traits for it within a function body, those definitions are part of the function's scope and are used to define the return type. The return statement here returns a value of type State, which needs the following definitions to be valid. This is not dead code - it's required for the function to work correctly. Could this be a case where the linter is correctly identifying that code after a return statement is technically unreachable, even if the code is needed for type definitions? No, this is a misunderstanding of Rust's scoping rules. The struct and impl blocks are declarations that are part of the function's scope and are required for the return type to be valid. They are not executable code that would be unreachable. The comment is incorrect. The code after the return statement contains necessary type definitions that are part of the function's scope and are required for the returned iterator type to work.

5. engine/baml-lib/baml/tests/mermaid_graph_tests.rs:4

• Draft comment:
  Test update: Using 'diagram_generator' module now; snapshot tests align with the new API.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% This comment is purely informative, providing details about a test update and alignment with a new API. It doesn't suggest any changes or ask for confirmation on specific code behavior.

6. engine/baml-runtime/src/runtime/runtime_interface.rs:175

• Draft comment:
  Function 'function_graph' now uses 'diagram_generator::generate_headers_flowchart' correctly; verify that this integration reflects intended graph-generation behavior.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% The comment is asking the PR author to verify the integration, which violates the rule against asking for confirmation of intention or behavior. It does not provide a specific suggestion or point out a specific issue with the code.

7. engine/baml-lib/ast/src/ast/baml_vis/graph.rs:107

• Draft comment:
  Typo in comment: "precomuted" should be "precomputed".
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% The rules say not to make purely informative comments and to only comment if there is clearly a code change required. While this is technically a code change, it's an extremely minor typo fix in a doc comment that doesn't affect functionality. The rules suggest focusing on more substantive issues. The typo could theoretically cause confusion for future developers reading the docs. Documentation quality is important. While docs are important, this typo is extremely minor and obvious - any reader would understand the intended meaning. The cost of the review comment outweighs the tiny benefit. This comment should be deleted as it violates the rule about not making purely informative comments and focusing only on substantive issues that require code changes.

8. engine/baml-lib/ast/src/ast/baml_vis/graph.rs:240

• Draft comment:
  Typo in comment: "wont" should be "want".
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 0% vs. threshold = 50% The rules state not to make purely informative comments and to avoid obvious or unimportant changes. While this is technically about a change (new file), fixing a typo in a comment has no functional impact and is a very minor issue. Comments should focus on code quality issues that require action. The typo could be confusing to future readers since "wont" is a real word with a different meaning than "want". Documentation clarity has value. While clear documentation is good, this is an internal comment about implementation details. The typo does not significantly impact understanding since the meaning is clear from context. The comment should be deleted as it points out a trivial issue that does not meaningfully impact code quality or functionality.

Workflow ID: wflow_ToyGhJNLECHQjSnd

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[github-actions]

🌿 Preview your docs: https://boundary-preview-2f74f435-6ddf-4892-aef1-07eda235335e.docs.buildwithfern.com

[github-actions]

https://sage-backend-p2srp8c6e-baml.vercel.app

[codecov]

Codecov Report

❌ Patch coverage is 0% with 625 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
engine/baml-lib/ast/src/ast/baml_vis/graph.rs	0.00%	483 Missing ⚠️
...baml-lib/ast/src/ast/baml_vis/diagram_generator.rs	0.00%	129 Missing ⚠️
.../baml-lib/ast/src/ast/baml_vis/header_collector.rs	0.00%	12 Missing ⚠️
...gine/baml-runtime/src/runtime/runtime_interface.rs	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

🌿 Preview your docs: https://boundary-preview-bc0ce846-4ef2-4613-a7f1-b74d3c43aaa1.docs.buildwithfern.com

[github-actions]

https://sage-backend-253n7twtm-baml.vercel.app

[github-actions]

🌿 Preview your docs: https://boundary-preview-132cf8c6-0c3c-4eff-976d-5b4dc1b46def.docs.buildwithfern.com

[github-actions]

https://sage-backend-9u9of45e1-baml.vercel.app