diagramming-code

Diagramming Code

Generates Mermaid diagrams from Trailmark's code graph. A pre-made script handles Mermaid syntax generation; Claude selects the diagram type and parameters.

When to Use

• Visualizing call paths between functions
• Drawing class inheritance hierarchies
• Mapping module import dependencies
• Showing class structure with members
• Highlighting complexity hotspots with color coding
• Tracing data flow from entrypoints to sensitive functions

When NOT to Use

• Querying the graph without visualization (use the trailmark skill)
• Mutation testing triage (use the genotoxic skill)
• Architecture diagrams not derived from code (draw by hand)

Prerequisites

trailmark must be installed. If uv run trailmark fails, run:

uv pip install trailmark

DO NOT fall back to hand-writing Mermaid from source code reading. The script uses Trailmark's parsed graph for accuracy. If installation fails, report the error to the user.

---

Quick Start

uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --language auto --type call-graph \
    --focus main --depth 2

Output is raw Mermaid text. Wrap in a fenced code block:

```mermaid
flowchart TB
    ...
```

---

Diagram Types

├─ "Who calls what?"               → --type call-graph
├─ "Class inheritance?"             → --type class-hierarchy
├─ "Module dependencies?"           → --type module-deps
├─ "Class members and structure?"   → --type containment
├─ "Where is complexity highest?"   → --type complexity
└─ "Path from input to function?"   → --type data-flow

For detailed examples of each type, see references/diagram-types.md.

---

Workflow

Diagram Progress:
- [ ] Step 1: Verify trailmark is installed
- [ ] Step 2: Identify diagram type from user request
- [ ] Step 3: Determine focus node and parameters
- [ ] Step 4: Run diagram.py script
- [ ] Step 5: Verify output is non-empty and well-formed
- [ ] Step 6: Embed diagram in response

Step 1: Run uv run trailmark analyze --language auto --summary {targetDir}. Install if it fails. Then run pre-analysis via the programmatic API:

from trailmark.query.api import QueryEngine

engine = QueryEngine.from_directory("{targetDir}", language="auto")
engine.preanalysis()

Pre-analysis enriches the graph with blast radius, taint propagation, and privilege boundary data used by data-flow diagrams.

If auto-detection is wrong for the target, rerun with an explicit language or comma-separated list such as python,rust.

Step 2: Match the user's request to a --type using the decision tree above.

Step 3: For call-graph and data-flow, identify the focus function. Default --depth 2. Use --direction LR for dependency flows.

Step 4: Run the script and capture stdout.

Step 5: Check: output starts with flowchart or classDiagram, contains at least one node. If empty or malformed, consult references/mermaid-syntax.md.

Step 6: Wrap output in ```mermaid ``` code fence.

---

Script Reference

uv run {baseDir}/scripts/diagram.py [OPTIONS]

Argument	Short	Default	Description
--target	-t	required	Directory to analyze
--language	-l	python	Source language
--type	-T	required	Diagram type (see above)
--focus	-f	none	Center diagram on this node
--depth	-d	2	BFS traversal depth
--direction		TB	Layout: TB (top-bottom) or LR (left-right)
--threshold		10	Min complexity for complexity type

Examples

# Call graph centered on a function
uv run {baseDir}/scripts/diagram.py -t src/ -T call-graph -f parse_file

# Class hierarchy for a Rust project
uv run {baseDir}/scripts/diagram.py -t src/ -l rust -T class-hierarchy

# Module dependency map, left-to-right
uv run {baseDir}/scripts/diagram.py -t src/ -T module-deps --direction LR

# Class members
uv run {baseDir}/scripts/diagram.py -t src/ -T containment

# Complexity heatmap (threshold 5)
uv run {baseDir}/scripts/diagram.py -t src/ -T complexity --threshold 5

# Data flow from entrypoints to a specific function
uv run {baseDir}/scripts/diagram.py -t src/ -T data-flow -f execute_query

---

Customization

Direction: Use TB (default) for hierarchical views, LR for left-to-right flows like dependency chains.

Depth: Increase --depth to see more of the call graph. Decrease to reduce clutter. The script warns if the diagram exceeds 100 nodes.

Focus: Always use --focus for call-graph on non-trivial codebases. For data-flow, omitting focus auto-targets the top 10 complexity hotspots.

Language: Prefer --language auto for polyglot or unfamiliar repos. Use an explicit language only when you know the target is single-language or you need to exclude unrelated components.

---

Supporting Documentation

• references/diagram-types.md - Detailed docs and Mermaid examples for each diagram type
• references/mermaid-syntax.md - ID sanitization, escaping, style definitions, and common pitfalls