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} --type call-graph
--focus main --depth 2

Output 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-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 --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="{lang}") engine.preanalysis()

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

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.

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