/diagramming-code

name: diagramming-code
description: >
  Generates Mermaid diagrams from Trailmark code graphs. Produces call graphs,
  class hierarchies, module dependency maps, containment diagrams, complexity
  heatmaps, and attack surface data flow visualizations. Use when visualizing
  code architecture, drawing call graphs, generating class diagrams, creating
  dependency maps, producing complexity heatmaps, or visualizing data flow
  and attack surface paths as Mermaid diagrams.

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. Trailmark 0.4.0 includes a native `trailmark diagram` command; use it only after a version/command check, otherwise use this skill's bundled script.

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 tool install trailmark
# Python snippets: uv run --with trailmark python -   (a tool env is not importable)

**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.

Version Gate

Check whether native v0.4 diagram support exists:

trailmark diagram --help 2>/dev/null || uv run trailmark diagram --help 2>/dev/null

If this succeeds, you may use `trailmark diagram`. If it fails, use `uv run {baseDir}/scripts/diagram.py`, which keeps the older skill workflow intact. Do not assume the native CLI exists on Trailmark 0.2.x.

---

Quick Start

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

# Trailmark 0.4.0+ equivalent after the Version Gate succeeds
uv run trailmark diagram \
    --target {targetDir} --language auto --type call-graph \
    --focus <function> --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](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 (or native trailmark diagram on v0.4+)
• [ ] 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. Do not run `engine.preanalysis()` for a diagram: the diagram
command builds its own graph and does not use pre-analysis data, so every
diagram type is identical with or without it. `data-flow` uses the
entrypoints Trailmark records while parsing.

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.
If the native v0.4 CLI is available, either command is acceptable; prefer the
bundled script when you need behavior consistent with this skill's references.

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

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

---

## Script Reference

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

or, on Trailmark 0.4.0+:

uv run trailmark diagram [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

```bash
# Call graph centered on a function
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -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/ -l auto -T module-deps --direction LR

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

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

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

---

Customization

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

**Depth:*