feat(mermaid): flow diagram thể hiện logic + call graph thay vì chuỗi thẳng

[hungpham10]

Vấn đề

Task yêu cầu: tạo Mermaid cho một hàm cụ thể để biết logic hàm làm gì và call đi đâu.

codegraph_mermaid (MCP) / mermaid (GraphQL) đã có kind: FLOW, nhưng control_flow chỉ:

• nối tuần tự mọi node trong flow.chain bằng nodes.windows(2), nên nhánh if/else, switch, vòng lặp đều bị vẽ thành một đường thẳng;
• bỏ qua hoàn toàn FlowResult.calls — không hiện line, condition, effect, callee;
• gộp chung call nội bộ và call ngoài repo (không phân biệt · ext).

Trong khi đó flow.calls đã có sẵn mọi thứ cần thiết (position, to_name, to_id, line, condition, effect).

Tái hiện (hàm mermaid tại query.rs:167)

Trước — chuỗi thẳng, mất hết nhánh và call-site info:

flowchart TD
  c0["mermaid"]
  c1["ctx.data::<Arc<AppState>>"]
  c2{"IF_TRUE"}
  c3(["RETURN"])
  ...
  c0 --> c1
  c1 --> c2
  c2 --> c3   (nối tuyến tính, không phải logic)

Thay đổi

crates/codegraph-api/src/mermaid.rs — viết lại control_flow dùng cả flow.calls:

• Điều kiện (IF_TRUE / IF_FALSE / SWITCH_CASE) → hình thoi, label kèm guard text lấy từ call record trong nhánh (IF_TRUE: !state.mermaid).
• Vòng lặp / kết thúc (LOOP, LOOP_BACK, RETURN, THROW, …) → stadium.
• Call → hộp chữ nhật: tên_callee · L<line> · if <condition> · <effect>.
• Call không resolve (ngoài repo) → hộp subroutine [[...]] + · ext.
• Cạnh suy từ marker, không nối tuyến tính:
  • IF_FALSE (else) rẽ từ chính node điều kiện if;
  • BRANCH_END hợp nhất nhánh (kể cả nhánh false khi không có else);
  • LOOP_BACK vẽ back edge về header loop;
  • SWITCH_CASE toả từ node entry của switch;
  • node thường nối tuần tự node liền trước; root không có cạnh vào.

Sau:

flowchart TD
  c0["mermaid"]
  c1[["ctx.data::<Arc<AppState>> · L174 · ext"]]
  c2{"IF_TRUE"}
  c3(["RETURN"])
  c4[["Err · L176 · if !state.mermaid · ext"]]
  c6(["BRANCH_END"])
  c7["parse_id · L180"]
  c10["api_for · L182"]
  c11{"SWITCH_CASE"}
  ...
  c1 --> c2
  c1 --> c6        (nhánh false)
  c2 --> c3 --> c4 --> c5 --> c6
  c10 --> c11
  c10 --> c18      (các case switch toả từ entry)
  c10 --> c24
  c10 --> c30

Ngoài ra cập nhật doc/mô tả:

• crates/codegraph-mcp/src/tools.rs: mô tả tool codegraph_mermaid nêu rõ FLOW thể hiện nhánh + call-site.
• crates/codegraph-graphql/src/types.rs: doc MermaidKind mô tả FLOW / CALLERS / CALLEES / IMPACT.

GraphQL

Không đổi schema, chỉ cải thiện nội dung trả về của field sẵn có:

{ mermaid(id: "156", kind: FLOW) }          # logic + call đi đâu
{ mermaid(id: "156", kind: CALLEES, depth: 2) }  # hàm gọi ai (graph LR)
{ mermaid(id: "156", kind: CALLERS, depth: 2) }  # ai gọi hàm
{ mermaid(id: "156", kind: IMPACT,  depth: 2) }  # bán kính ảnh hưởng

Server cần chạy serve --graphql --mermaid. MCP tương ứng serve --mcp --mermaid và codegraph_mermaid {node, kind, depth}.

Kiểm thử

• 6 unit test mới cho control_flow: if/else không nối tuyến tính, loop back edge, switch fan-out, label call (line/condition/effect/ext), guard của điều kiện, root không có cạnh vào.
• cargo test -p codegraph-api (10 integration + 6 unit) — pass.
• cargo clippy -p codegraph-api -p codegraph-graphql -p codegraph-mcp --all-targets -- -D warnings — sạch.
• Verify end-to-end qua GraphQL --mermaid trên chính repo này (hàm mermaid id 156).

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 2359af78-1531-480c-9d2a-62592a5d17c9

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.98387% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.00%. Comparing base (bf4fc84) to head (759728e).

Files with missing lines	Patch %	Lines
crates/codegraph-api/src/mermaid.rs	97.98%	5 Missing ⚠️

❌ Your patch status has failed because the patch coverage (97.98%) is below the target coverage (100.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #41      +/-   ##
==========================================
+ Coverage   77.66%   78.00%   +0.33%     
==========================================
  Files          94       94              
  Lines       22115    22348     +233     
==========================================
+ Hits        17176    17432     +256     
+ Misses       4939     4916      -23     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[codspeed]

Merging this PR will not alter performance

✅ 38 untouched benchmarks

---

_{Comparing feat/mermaid-flow-call-graph (759728e) with main (bf4fc84)}