interface:
  display_name: "Code Diagrams"
  short_description: "Generate architecture diagrams from Trailmark code graphs"
  icon_small: "assets/trail-of-bits-mark.svg"
  icon_large: "assets/trail-of-bits-mark.svg"
  brand_color: "#D83A34"

# Diagram Types

## Contents

- [Call graph](#call-graph)
- [Class hierarchy](#class-hierarchy)
- [Module dependencies](#module-dependencies)
- [Containment](#containment)
- [Complexity heatmap](#complexity-heatmap)
- [Attack surface / data flow](#attack-surface--data-flow)

---

## Call Graph

Shows which functions call which. Built from `callers_of` / `callees_of`
queries and `calls` edges.

**Mermaid type:** `flowchart`

**When to use `--focus`:** Almost always. Without focus, large codebases
produce unreadable diagrams. Start with `--depth 2` and increase if needed.

**Arrow styles reflect edge confidence:**
- Solid (`-->`) = certain (direct call)
- Dashed (`-.->`) = inferred (attribute access on non-self)
- Dotted (`..->`) = uncertain (dynamic dispatch)

**Example output:**

```mermaid
flowchart TB
    query_api_QueryEngine_callers_of["callers_of, method"]
    query_api_QueryEngine_callees_of["callees_of, method"]
    query_api_QueryEngine_paths_between["paths_between, method"]
    storage_graph_store_GraphStore_find_node_id["find_node_id, method"]
    query_api_QueryEngine_callers_of --> storage_graph_store_GraphStore_find_node_id
    query_api_QueryEngine_callees_of --> storage_graph_store_GraphStore_find_node_id
    query_api_QueryEngine_paths_between --> storage_graph_store_GraphStore_find_node_id
```

**Script invocation:**

```bash
uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --type call-graph \
    --focus QueryEngine --depth 2
```

---

## Class Hierarchy

Shows inheritance (`<|--`) and interface implementation (`<|..`)
relationships between classes, structs, interfaces, and traits.

**Mermaid type:** `classDiagram`

**Limitations:** Languages without class inheritance (e.g., Go, C) produce
empty diagrams. The script emits a note node in that case.

**Example output:**

```mermaid
classDiagram
    class models_nodes_CodeUnit {
        class
    }
    class models_edges_CodeEdge {
        class
    }
    models_nodes_CodeUnit <|-- models_nodes_Parameter
```

**Script invocation:**

```bash
uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --type class-hierarchy
```

---

## Module Dependencies

Shows import relationships between modules. Built from `imports` edges.

**Mermaid type:** `flowchart`

**Best with `--direction LR`** for left-to-right dependency flow.

**Example output:**

```mermaid
flowchart LR
    query_api["api, module"]
    storage_graph_store["graph_store, module"]
    models_nodes["nodes, module"]
    query_api --> storage_graph_store
    storage_graph_store --> models_nodes
```

**Script invocation:**

```bash
uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --type module-deps --direction LR
```

---

## Containment

Shows classes and their member functions/methods using `contains` edges.

**Mermaid type:** `classDiagram` (with member lists)

**Example output:**

```mermaid
classDiagram
    class storage_graph_store_GraphStore {
        +callers_of()
        +callees_of()
        +paths_between() list
        +find_node() CodeUnit
    }
```

**Script invocation:**

```bash
uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --type containment
```

---

## Complexity Heatmap

Shows functions color-coded by cyclomatic complexity with call edges
between them. Only nodes meeting `--threshold` are included.

**Mermaid type:** `flowchart` with `classDef` styles

**Color scale:**
- Green (`low`): CC < 5
- Yellow (`medium`): CC 5-10
- Red (`high`): CC > 10

**Example output:**

```mermaid
flowchart TB
    parsers_python_parser_parse_file["parse_file, method, CC=15"]:::high
    parsers_python_parser_visit_class["visit_class, method, CC=8"]:::medium
    parsers_python_parser_parse_file --> parsers_python_parser_visit_class
    classDef low fill:rgba(40,167,69,0.2),stroke:#28a745,color:#28a745
    classDef medium fill:rgba(255,193,7,0.2),stroke:#e6a817,color:#e6a817
    classDef high fill:rgba(220,53,69,0.2),stroke:#dc3545,color:#dc3545
```

**Script invocation:**

```bash
uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --type complexity --threshold 5
```

---

## Attack Surface / Data Flow

Shows paths from entrypoints (user input, API endpoints) to sensitive
functions. Entrypoints are styled distinctly (rounded rectangles, blue).

**Mermaid type:** `flowchart`

Without `--focus`, the script targets the top 10 complexity hotspots
reachable from entrypoints. With `--focus`, it shows all paths from
entrypoints to the specified function.

**Example output:**

```mermaid
flowchart TB
    handle_request(["handle_request, function"]):::entrypoint
    validate_input["validate_input, function"]
    execute_query["execute_query, function"]
    handle_request --> validate_input
    validate_input --> execute_query
    classDef entrypoint fill:rgba(0,123,255,0.2),stroke:#007bff,color:#007bff
```

**Script invocation:**

```bash
# Focus on a specific sensitive function
uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --type data-flow \
    --focus execute_query

# Auto-detect: entrypoints to top complexity hotspots
uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --type data-flow
```

# Mermaid Syntax Reference

Pitfalls and edge cases when generating Mermaid from code graph data.

## Contents

- [Node ID sanitization](#node-id-sanitization)
- [Label escaping](#label-escaping)
- [Style definitions](#style-definitions)
- [Edge confidence styling](#edge-confidence-styling)
- [Common pitfalls](#common-pitfalls)

---

## Node ID Sanitization

Trailmark node IDs use `module:Class.method` format. Mermaid node IDs
only allow `[a-zA-Z0-9_]`.

**Rules applied by `diagram.py`:**
- Replace any non-alphanumeric character (except `_`) with `_`
- Prefix with `n_` if the result starts with a digit

**Examples:**

| Trailmark ID | Mermaid ID |
|---|---|
| `query.api:QueryEngine.callers_of` | `query_api_QueryEngine_callers_of` |
| `3rdparty:init` | `n_3rdparty_init` |

---

## Label Escaping

Node labels are wrapped in double quotes to safely include special
characters:

```
    node_id["label with (parens) and: colons"]
```

If the label itself contains double quotes, replace `"` with `#quot;`
(Mermaid's HTML entity escape).

---

## Style Definitions

Use `classDef` to define reusable styles and `:::` to apply them:

```mermaid
flowchart TB
    A["Low complexity"]:::low
    B["High complexity"]:::high
    classDef low fill:rgba(40,167,69,0.2),stroke:#28a745,color:#28a745
    classDef high fill:rgba(220,53,69,0.2),stroke:#dc3545,color:#dc3545
```

The script defines three classes for complexity heatmaps:
- `low` (green): CC < 5
- `medium` (yellow): CC 5-10
- `high` (red): CC > 10

And one for data flow:
- `entrypoint` (blue): marks untrusted input sources

---

## Edge Confidence Styling

Arrow syntax varies by edge confidence:

| Confidence | Arrow | Meaning |
|---|---|---|
| `certain` | `-->` | Direct call or `self.method()` |
| `inferred` | `-.->` | Attribute access on non-self object |
| `uncertain` | `..->` | Dynamic dispatch, reflection |

For class diagrams, arrows are different:
- `<\|--` = inherits
- `<\|..` = implements

---

## Common Pitfalls

**Reserved words as node IDs:** `end`, `graph`, `subgraph`, `style`,
`classDef`, `click` are reserved. The sanitization function avoids most
conflicts since it replaces special characters, but single-word function
names matching reserved words can still collide. Workaround: use the full
qualified ID which includes the module prefix.

**Leading digits:** Mermaid node IDs cannot start with a digit. The
script prefixes `n_` in this case.

**Diagram size:** Mermaid renderers struggle with >100 nodes. The script
warns when this limit is exceeded and suggests using `--focus` to scope
the diagram.

**Empty diagrams:** When no edges of the required type exist (e.g., no
`inherits` edges in a Go codebase), the script emits a single-node
diagram with an explanatory message rather than failing.

**Parentheses in labels:** Mermaid interprets `()` as rounded-rectangle
node shape. Always use quoted labels (`["label"]`) to avoid accidental
shape changes.

# /// script
# requires-python = ">=3.12"
# dependencies = ["trailmark"]
# ///
"""Generate Mermaid diagrams from Trailmark code graphs.

Thin wrapper — all logic lives in ``trailmark.diagram``.
Run via ``uv run {this_file} --target ... --type ...``.
"""

from __future__ import annotations

import sys

from trailmark.diagram import main

if __name__ == "__main__":
    sys.exit(main())