Code Flow Graph

This skill generates interactive HTML node-graph diagrams to visualize codebase structure, class relationships, and function call chains. It should be used when the user asks to visualize, diagram, or map out code architecture, module dependencies, class hierarchies, or UI event flows. It also supports UI layout visualization — generating interactive nested widget hierarchy diagrams for Qt, React, or other UI frameworks (triggered by "UI layout", "widget hierarchy", "界面布局", "控件层级" keywords). The output is a standalone HTML+JS viewer with draggable nodes, bezier-curve connections, group boxes, sidebar navigation, global search (Ctrl+K), call-chain detail panel, localStorage position persistence, click-to-copy function name, Ctrl+Z undo layout moves, interactive widget-box tree with resize handles, and Catppuccin Mocha dark theme.

# Code Flow Graph

Generate interactive node-graph HTML diagrams that visualize code structure and call relationships.

## When to Use

- User requests code structure visualization, architecture diagrams, or call-chain mapping
- User wants to understand how classes/modules/functions relate to each other
- User wants to see UI event flows (button click → handler → business logic) — UI projects only
- User asks to "diagram", "visualize", "map out", or "graph" the code

## Architecture

The output consists of two files placed in a dedicated folder:

1. **`code_flow_graph.html`** — rendering engine (from this skill's `example/code_flow_graph.html` template)
2. **`code_flow_graph_data.js`** — diagram data (generated per-project)

The HTML loads the JS via `<script src="code_flow_graph_data.js">` and must be in the same directory.

> **Important**: The HTML template lives in **this skill's repository**, not in the user's project. See Step 3 for the correct procedure to locate and copy it.

## Workflow

> **Core principle**: Start fast, go deep on demand. Immediately generate an Overview diagram upon receiving a request — no upfront questions about scope or language. Offer deeper analysis options after the Overview is delivered.

### Step 1: Analyze Project & Determine Scope

Begin analysis **immediately** upon receiving the user's request. Do NOT ask any scoping or language questions.

#### Scope Rules

- If the user's request **explicitly names a module or directory** (e.g., "分析 core 模块", "visualize the auth/ package"), restrict analysis to that scope only.
- Otherwise, analyze the **entire project**.

#### Analysis Procedure

1. Read the project's top-level structure: README, entry scripts (`__main__.py`, `main.py`, `index.ts`, `app.py`), config files (`setup.py`, `pyproject.toml`, `package.json`, `Cargo.toml`), and directory layout
2. Determine whether the project has a **UI layer** (Qt, React, Web, etc.) or is **non-UI** (CLI, library, backend, pipeline, etc.)
3. Identify all major modules/packages and their purposes within the determined scope
4. Discover the **main execution entry points** within the scope:
   - **CLI entry points** — `if __name__ == '__main__'`, Click/Typer/argparse commands, `console_scripts`
   - **Public API functions** — exported functions in `__init__.py`, decorated endpoints (`@app.route`, `@api_view`)
   - **Pipeline/task entry points** — Celery tasks, Airflow DAGs, scheduled jobs
   - **Hook/plugin entry points** — registered callbacks, plugin `activate()` methods
   - **Class constructors + primary methods** — the main "do something" methods of core classes
   - **UI entry points** (UI projects only) — main window creation, app initialization, route/page registration
5. **Assess function importance** — For each function/method discovered, evaluate its importance based on how many **project-internal** functions it calls or is called by. This determines whether it appears in the diagram (see Function Importance Filtering below).

#### Function Importance Filtering

Determine which functions to **include** or **exclude** from the generated diagrams. The goal is to produce detailed yet noise-free graphs that show meaningful business logic.

**Include** a function if it meets ANY of these criteria:
- It is an entry point (CLI, API, pipeline, hook, UI init)
- It calls **2 or more** other project-internal functions (high fan-out = orchestration logic)
- It is called by **3 or more** different project-internal call sites (high fan-in = shared core logic)
- It contains branching/dispatch logic (if/match/switch that routes to different code paths)
- It performs state mutation, data transformation, or coordinates multi-step workflows

**Exclude** a function if it meets ALL of these criteria:
- It calls **0–1** project-internal functions (low fan-out)
- It is a simple accessor/getter/setter (e.g., `get_name()`, `set_value()`, `is_valid()`)
- It is a thin wrapper around a single external API call with no project-internal logic
- It is a utility/helper doing generic work not specific to the project's domain (e.g., `format_string()`, `ensure_dir()`, `clamp()`, `retry()`)
- It is a logging, validation, or type-checking function with no side effects on business state

**When in doubt**, include the function — it is better to show slightly more detail than to miss important logic. Excluded functions can still appear as `children` (collapsed sub-items) inside their caller's attr if they contribute to understanding the call flow.

#### Language Default

Use **Chinese (中文)** for all `desc`, `sig` hint text, `io` labels, section titles, and `navSub` in the generated data. Switch to another language only if the user explicitly requests it.

### Step 2: Create Output Folder

Create the visualization output inside the project's `docs/` directory:

1. Check if `<project>/docs/` exists. If not, create it.
2. Create the output folder at `<project>/docs/code_graph/`.
3. If the user specifies a custom location, use that instead.

The final output path is always `<project>/docs/code_graph/` unless overridden by the user.

### Step 3: Copy the HTML Engine

The HTML viewer template is located at `example/code_flow_graph.html` **relative to this skill's definition file (SKILL.md)**. It is NOT inside the user's project.

#### How to locate the template

1. Determine the **skill directory** — the folder containing this SKILL.md file. The skill loading mechanism provides this path; it is typically visible in the file paths used when the skill was loaded.
2. Construct the template path: `<skill_directory>/example/code_flow_graph.html`
3. Use `read_file` to read the template's complete content from that path.
4. Use `write_to_file` to write the content to `<output_folder>/code_flow_graph.html`.

**Do NOT modify the HTML content.** Copy it verbatim.

> **Common failure mode**: If you try to read `example/code_flow_graph.html` as a relative path, it resolves against the user's project root — where the file does not exist. You MUST use the absolute path based on the skill's installation directory.

#### Engine Features (built-in, code_flow_graph.html)

1. **Search** — Ctrl+K opens search box; fuzzy-matches function names across ALL diagrams; click to jump cross-diagram
2. **Collapsed Children Redirect** — When children are collapsed, connections redirect to the parent attr instead of disappearing
3. **Click Blank to Deselect** — Click any blank area in the viewport to clear all highlights and close the detail panel
4. **Enhanced Legend** — Node type badges (CLASS/MODULE/FUNC/ENTRY/DATA/UI CLASS) on header; `external: true` nodes get dashed border + EXT tag; connection color semantics (call/data/extern/signal) with gradient indicating direction
5. **Signature Tooltips** — Hover any function attr to see full signature; callChain attrs show "Click to view call chain →" hint
6. **Call Chain Detail Panel** — Click attrs with `callChain` to open right-side interactive call tree; each item shows a `desc` (description) explaining what the function does; clicking any item with a matching graph node highlights that node and pans the viewport to it
7. **Field Detail Panel** — Click attrs with `fieldDetail` (typically on `data` type nodes) to open right-side field computation panel; shows field name, type, summary, and all computation modes with ordered step lists. Function names in steps are auto-highlighted as `<code>` elements
8. **Position Persistence** — Node positions saved to localStorage per diagram; "Reset Layout" restores defaults
9. **Click to Copy** — Clicking any function attr automatically copies the function name to clipboard and shows a toast notification
10. **Undo Layout Moves** — Ctrl+Z undoes the last node/group drag operation (up to 50 steps); undo stack is cleared when switching diagrams
11. **Connection Anchor via offsetTop** — Connection line anchors use `offsetTop`/`offsetParent` chain (NOT `getBoundingClientRect`) to compute attr Y-offset within a n