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
trailmarkskill) - Mutation testing triage (use the
genotoxicskill) - Architecture diagrams not derived from code (draw by hand)
Prerequisites
trailmark must be installed. If uv run trailmark fails, run:
uv pip install trailmarkDO 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 2Output is raw Mermaid text. Wrap in a fenced code block:
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-flowFor 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 responseStep 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_queryCustomization
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