feat(#77): group mermaid nodes by file into subgraph blocks

[zaebee]

Summary

• MermaidCompiler.compile() now groups nodes by file_path into subgraph blocks when the graph spans multiple files
• Single-file graphs render flat — no behaviour change for existing callers
• Extracted _normalize_id to module level (was a pure function with no self dependency)
• 4 new tests covering: flat single-file, subgraph presence, node placement, cross-file edges

Before / After

Before (flat, 8 nodes from 4 files — hard to read):

graph TD
  n_abc["IngestionPipeline.run (pipeline.py:45)"]:::classNode
  n_def["ResolverEngine (engine.py:12)"]:::classNode
  ...

After (grouped by file):

graph TD
  subgraph n_sg1["pipeline.py"]
    n_abc["IngestionPipeline.run (pipeline.py:45)"]:::classNode
  end
  subgraph n_sg2["engine.py"]
    n_def["ResolverEngine (engine.py:12)"]:::classNode
  end
  n_abc -->|CALLS| n_def

Test plan

• CI green
• /guardian review 👀

Closes #77

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[zaebee]

/guardian review

[github-actions]

Pull Request Review: Mermaid Compiler Refactor & Subgraph Support

Status: ⚠️ Conditional Approval (Pending Import Verification)

🛡️ Guardian's Summary

The refactor of the MermaidCompiler is architecturally sound. Moving from a monolithic compile method to a decomposed, single-responsibility pattern significantly improves maintainability and readability. The addition of subgraph grouping based on file_path provides the high-fidelity visualization required for mission-critical intelligence, preventing "spaghetti graphs" in large repositories.

The implementation correctly respects the project Ontology, specifically regarding the handling of raw_call: prefixes for unresolved edges.

---

🔍 Detailed Findings

1. Correctness: Potential Missing Import

• Issue: The new module-level function _normalize_id utilizes hashlib.md5. While the logic is deterministic (meeting our standards), the import hashlib statement is not present in the provided diff.
• Reason: If hashlib is not already imported in the existing src/cgis/query/mermaid.py file, this will result in a NameError at runtime.
• Suggested Fix: Ensure import hashlib is present at the top of src/cgis/query/mermaid.py.

2. Type Safety & Determinism

• Status: PASSED
• Observation: The code strictly adheres to type discipline. All new methods (_render_node_line, _render_subgraphs, _render_edges) have full type annotations.
• Observation: The use of hashlib.md5(..., usedforsecurity=False) is an excellent choice. It ensures determinism for ID generation while explicitly signaling that this is not a security-sensitive operation, which is a best practice for high-performance engine components.

3. Architectural Alignment

• Status: PASSED
• Observation: The logic for "phantom nodes" (nodes appearing in edges but not in the primary node list) is robust. By updating the id_map during the edge rendering pass, you prevent duplicate node declarations in the Mermaid output, maintaining a clean graph structure.
• Ontology Compliance: The stripping of _RAW_CALL_PREFIX and the conditional application of _UNRESOLVED_STYLE perfectly aligns with the unresolved_call_prefix convention defined in the project ontology.

4. Testing Mandate

• Status: PASSED
• Observation: The addition of unit tests in tests/unit/test_mermaid.py is thorough. Specifically, test_compile_subgraph_contains_its_nodes verifies the semantic correctness of the grouping logic, ensuring that the structural hierarchy of the graph is preserved in the visual representation.

---

🛠️ Final Recommendations

1. Verify Import: Confirm import hashlib is included in the file.
2. Minor Refinement (Optional): In _render_edges, you are mutating the id_map dictionary. While this is safe here because id_map is a local variable within compile, it is a side effect. Given the complexity of graph compilers, this is acceptable, but ensure future developers are aware that _render_edges is not a "pure" function.

Once the import is verified, this PR is ready for merge.