diagramming-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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的代码图生成Mermaid图表。内置脚本负责Mermaid语法生成，Claude会选择图表类型和参数。

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)

无需可视化的图查询需求（请使用
```
trailmark
```
skill）
突变测试分类（请使用
```
genotoxic
```
skill）
非基于代码生成的架构图（请手动绘制）

Prerequisites

前置条件

trailmark must be installed. If

uv run trailmark

fails, run:

bash

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.

trailmark 必须已安装。如果

uv run trailmark

执行失败，请运行：

bash

uv pip install trailmark

请勿通过阅读源代码手动编写Mermaid代码。脚本使用Trailmark解析得到的图来保证准确性。如果安装失败，请向用户报告错误。

Quick Start

快速开始

bash

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:

markdown

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

bash

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

输出为原始Mermaid文本，请用围栏代码块包裹：

markdown

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

├─ "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

如需查看每种类型的详细示例，请参阅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:

python

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

classDiagram

, contains at least one node. If empty or malformed, consult references/mermaid-syntax.md.

Step 6: Wrap output in

```mermaid ```

code fence.

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

步骤1： 运行

uv run trailmark analyze --summary {targetDir}

。如果运行失败请先安装。然后通过编程API运行预分析：

python

from trailmark.query.api import QueryEngine

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

预分析会为图补充影响范围、污染传播和权限边界数据，供

data-flow

图表使用。

步骤2： 参考上述决策树，将用户请求匹配到对应的

--type

参数。

步骤3： 对于

call-graph

和

data-flow

类型，确定焦点函数。默认

--depth 2

。依赖流可使用

--direction LR

参数。

步骤4： 运行脚本并捕获标准输出。

步骤5： 检查：输出以

flowchart

或

classDiagram

开头，包含至少一个节点。如果输出为空或格式错误，请参考references/mermaid-syntax.md。

步骤6： 将输出包裹在

```mermaid ```

代码围栏中。

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

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

参数	简写	默认值	描述
`--target`	`-t`	必填	待分析的目录
`--language`	`-l`	`python`	源代码语言
`--type`	`-T`	必填	图表类型（参考上文）
`--focus`	`-f`	无	以该节点为中心展示图表
`--depth`	`-d`	`2`	BFS遍历深度
`--direction`	无	`TB`	布局： `TB` （从上到下）或 `LR` （从左到右）
`--threshold`	无	`10`	`complexity` 类型的最低复杂度阈值

Examples

示例

bash

undefined

bash

undefined

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

---

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.

布局方向： 层级视图使用默认的

TB

，依赖链等从左到右的流程使用

LR

。

深度： 增大

--depth

可查看更多调用图内容，减小可减少杂乱。如果图表节点超过100个，脚本会发出警告。

焦点： 对于非小型代码库的

call-graph

，请始终使用

--focus

参数。对于

data-flow

类型，省略focus参数会自动定位到Top10复杂度热点。

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

references/diagram-types.md - 各类图表的详细文档和Mermaid示例
references/mermaid-syntax.md - ID清理、转义、样式定义和常见问题