diagramming-code · diff
git:20260912.5c5b759 to git:20260912.07a8a1b
54 added, 34 removed. Audit A to A.
---
name: diagramming-code
- description: 'Use when asked for a call graph, class hierarchy, dependency map, containment or complexity view, or data-flow view. Not for embedding: use embed-diagram. Not for architecture: use visual-diagram.'
- disable-model-invocation: true
+ description: 'Use when asked for a call graph, class hierarchy, dependency map, containment or complexity view, a data-flow view, including attack-surface views, or to render an offline Mermaid diagram and embed it in a document. Modes: code-derived or document-embed. Not for interactive architecture visuals: use visual-diagram. Not for remote, credential, publish, deploy, or irreversible changes.'
---
- # Diagramming code
+ # Diagramming code and embedding diagrams
## Contract
| Field | Bound contract |
|---|---|
- | Trigger | The user asks for a call graph, class hierarchy, module dependency map, containment view, complexity heatmap, or attack-surface/data-flow view derived from code. |
- | Authority | Reversible local: writes only generated Mermaid graph text or an embedded Mermaid diagram to the local response or a named local file; rollback is deleting the emitted artifact. No remote mutation. No source mutation. |
- | Side effect | Generated Mermaid graph text or an embedded Mermaid diagram in the local response or a named local file. |
- | Done | The requested graph type is non-empty or honestly explains why no matching edges exist, is scoped to a readable size, and uses valid Mermaid syntax. |
+ | Trigger | The user asks for a code-derived call graph, class hierarchy, module dependency map, containment view, complexity heatmap, or a data-flow view, including an attack-surface view, or asks to render a Mermaid diagram offline and embed it in a document. |
+ | Authority | `code-derived` reads target code and writes only Mermaid graph text to the response or a named local file; it does not mutate source. `document-embed` writes Mermaid source, SVG, PNG, and (when supported) Excalidraw files only in the selected output directory and edits the existing target document to embed the render. Both modes are reversible local work with no remote mutation. |
+ | Side effect | `code-derived` emits a fenced Mermaid graph. `document-embed` emits the `.mmd`, rendered SVG and PNG, an optional Excalidraw scene, and an embedded SVG or PNG in the target document. |
+ | Done | `code-derived` produces valid, readable Mermaid with at least one node or an explanatory singleton. `document-embed` embeds a rendered diagram in the target document, keeps the `.mmd` source and rendered artifacts in the output directory, and states any Excalidraw limitation. |
## Inputs
- - Target code directory or path (required).
- - Diagram type, one of: call-graph, class-hierarchy, module-deps, containment, complexity, data-flow (required).
- - Focus node (optional; required for call-graph and data-flow on non-trivial codebases).
- - Traversal depth (optional; default 2).
- - Layout direction, TB or LR (optional; default TB; prefer LR for module-deps).
- - Complexity threshold (optional; default 10; only for complexity).
- - Source language or auto (optional; default auto).
+ - Mode (optional): `code-derived` or `document-embed`; when omitted, infer it from the request as specified in step 1.
+ - `code-derived` mode:
+ - Target code directory or path (required).
+ - Diagram type, one of: call-graph, class-hierarchy, module-deps, containment, complexity, data-flow (use this type for attack-surface views) (required).
+ - Focus node (optional; required for call-graph and data-flow on non-trivial codebases).
+ - Traversal depth (optional; default 2).
+ - Layout direction, TB or LR (optional; default TB; prefer LR for module-deps).
+ - Complexity threshold (optional; default 10; only for complexity).
+ - Source language or auto (optional; default auto).
+ - `document-embed` mode:
+ - Diagram request: an English description of the structure to diagram, or Mermaid source (required).
+ - Target document path (required). The document must exist and be writable.
+ - Output directory (optional): `./diagrams/` when the cwd is a git repo, otherwise `/tmp/odin-diagrams/`.
+ - Output slug (optional): derive kebab-case from the diagram subject, 40 characters or fewer.
+ - Embed location (optional) and placed width in inches (optional; when omitted, let `mmdc` retain its intrinsic output width).
## Procedure
- 1. Confirm the target directory and diagram type. Do not widen to other types or mutate source files. Done when: the target directory and diagram type are confirmed.
+ 1. Select the mode from the request and bind its inputs: honor an explicitly supplied `code-derived` or `document-embed`; otherwise choose `document-embed` for an offline Mermaid render or document-embedding request and `code-derived` for a code-relationship request. In `code-derived`, confirm the target code path and diagram type, using `data-flow` for an attack-surface request. In `document-embed`, confirm the target document exists and is writable, choose the output directory and slug, accept an optional positive placed width in inches, and bound all writes to that directory and document. Done when: the mode, required inputs, output location, optional width, and write boundary are explicit.
- 2. Read and search the target code to derive graph edges from its actual structure. Do not invent relationships. Map the request to its diagram type and Mermaid form:
- - call-graph → `flowchart`; edges from call relationships; arrow style by confidence: `-->` certain (direct call), `-.->` inferred (attribute access on non-self), `..->` uncertain (dynamic dispatch).
- - class-hierarchy → `classDiagram`; `<|--` inherits, `<|..` implements.
- - module-deps → `flowchart LR`; edges from import relationships.
- - containment → `classDiagram` with member lists; edges from containment relationships.
- - complexity → `flowchart` with `classDef` styles; include only nodes meeting the threshold; color scale: `low` green CC < 5, `medium` yellow CC 5-10, `high` red CC > 10.
- - data-flow → `flowchart`; paths from entrypoints (user input, API endpoints) to sensitive functions; style entrypoints blue. Without focus, target the top 10 complexity hotspots reachable from entrypoints.
+ 2. Derive or author Mermaid source from grounded input. In `code-derived`, read and search the target code and derive actual relationships without inventing edges:
+ - call-graph → `flowchart`; direct calls use `-->`, inferred attribute access uses `-.->`, and uncertain dynamic dispatch uses `..->`.
+ - class-hierarchy → `classDiagram`; inheritance uses `<|--` and implementation uses `<|..`.
+ - module-deps → `flowchart LR` with import edges.
+ - containment → `classDiagram` with member lists and containment edges.
+ - complexity → `flowchart` with `classDef` styles; include nodes meeting the threshold, using low green for CC < 5, medium yellow for CC 5-10, and high red for CC > 10.
+ - data-flow (including attack-surface scope) → `flowchart` from entrypoints such as user input or API endpoints to sensitive functions, with blue entrypoint styles; without a focus, target the top 10 complexity hotspots reachable from entrypoints.
+ In `document-embed`, author Mermaid from the description or accept the supplied source; prefer `graph LR` for pipelines and flows and `graph TD` for hierarchies, keep labels short, put detail in edge labels, and keep each diagram to 5-15 nodes. Split a larger request into multiple diagrams and explain the split. Done when: the source and its diagram type are grounded and ready for normalization or rendering.
- Done when: edges are derived from actual structure and mapped to the diagram type's Mermaid form.
+ 3. Normalize and scope the source. For `code-derived`, replace every node-ID character other than alphanumerics and `_` with `_`, prefix `n_` when the result starts with a digit, quote labels as `["..."]`, escape literal quotes as `#quot;`, and use fully qualified module-prefixed IDs to avoid reserved words such as `end`, `graph`, `subgraph`, `style`, `classDef`, and `click`. Center call-graph and data-flow output on the focus node, use depth 2 by default, and reduce depth or narrow focus when the graph would exceed roughly 100 nodes. For `document-embed`, keep the authored source within the 5-15-node range or use the declared split; flowcharts can become editable Excalidraw scenes, while sequence, state, gantt, and other non-flowchart types remain SVG/PNG outputs. Done when: IDs and labels are safe, and each mode's graph is within its readability bound.
- 3. Sanitize every node ID: replace any non-alphanumeric character except `_` with `_`, and prefix `n_` if the result starts with a digit. Quote all labels with `["..."]`; escape a literal `"` in a label as `#quot;`. Use fully qualified IDs (module-prefixed) to avoid reserved words `end`, `graph`, `subgraph`, `style`, `classDef`, `click`. Done when: every node ID and label is sanitized and escaped.
+ 4. Produce the mode-specific source. For `code-derived`, verify the source is a `flowchart` or `classDiagram` and contains at least one node; if no required edges exist, use one explanatory node rather than fabricating relationships. For `document-embed`, write the source of truth to `<outdir>/<slug>.mmd`, then verify that `mmdc` (Mermaid CLI) is installed and executable. If it is absent, stop with `npm install -g @mermaid-js/mermaid-cli` and do not use a CDN or remote fallback. Done when: code output is structurally valid or has an explanatory singleton, or the document mode has a written `.mmd` and a confirmed offline renderer.
- 4. Scope the graph to a readable size. Center call-graph and data-flow diagrams on the focus node for non-trivial codebases. Use the default depth of 2. If the graph would exceed roughly 100 nodes, narrow the focus or reduce the depth rather than emit an unreadable diagram. Done when: the graph is centered on the focus node where required and stays within the readable size bound.
+ 5. Verify or render the result. For `code-derived`, re-check Mermaid syntax and retain the valid source for delivery. For `document-embed`, run `mmdc -i <outdir>/<slug>.mmd -o <outdir>/<slug>.svg`, showing any parse error, repairing the source, and retrying until the SVG is valid; then run `mmdc -i <outdir>/<slug>.mmd -o <outdir>/<slug>.png` and add `-w <placed-width-inches*300>` only when a positive placed-width input was supplied. If PNG rasterization fails, mount the SVG in a headless browser and take a screenshot. Done when: code mode has valid Mermaid, or document mode has rendered SVG and PNG artifacts from the local source.
- 5. Verify the output starts with `flowchart` or `classDiagram` and contains at least one node with valid Mermaid syntax. If no edges of the required type exist, emit a single-node diagram with an explanatory message instead of failing or fabricating edges. Done when: the output is valid Mermaid with at least one node, or a single-node explanatory diagram is emitted.
+ 6. Complete document artifacts and embedding. In `document-embed`, for a flowchart check whether the local Mermaid-to-Excalidraw support or converter script is available and, when it is, write `<outdir>/<slug>.excalidraw`; for every other Mermaid type, skip that artifact and state that it is not Excalidraw-editable. Embed the SVG (preferred) or PNG in the target document at the requested location. Do not ship a source-only or partially rendered result. Done when: the rendered diagram is embedded and every produced artifact is under the chosen output directory.
- 6. Wrap the result in a ` ```mermaid ` fence and deliver it. Done when: the fenced mermaid block is delivered.
+ 7. Deliver the result. In `code-derived`, wrap the graph in a ` ```mermaid ` fence. In `document-embed`, show the PNG, list the `.mmd`, `.svg`, `.png`, optional `.excalidraw`, and edited-document paths, and note that the Excalidraw scene opens at excalidraw.com. Done when: the requested response or embedded document and its artifact paths are presented.
+ 8. For changes, edit the `.mmd` source and repeat rendering from step 5; for a user-edited Excalidraw round-trip, load that scene and export SVG and PNG without changing the Mermaid source. Re-run the code-derived path from source when its input code or diagram request changes. Done when: the changed source and all dependent renders are synchronized.
+
## Failure and recovery
- - No matching edges (e.g., no inheritance edges in a Go or C codebase): emit a single-node explanatory diagram; do not invent edges.
- - Empty or malformed output: re-check the diagram-type mapping and node ID sanitization; do not hand-wave or suppress the error.
- - Graph too large (>100 nodes): apply focus or reduce depth; never emit an unreadable graph.
- - Language auto-detection wrong: re-derive with an explicit language.
- - Rollback: delete the emitted artifact. No source mutation occurred, so no source rollback is needed.
- - Blocked result: report exactly which diagram type and target could not be resolved and why; do not claim the done predicate holds.
+ - No matching code-derived edges: emit a single explanatory node; do not invent edges.
+ - Empty or malformed code-derived output: re-check diagram mapping and node-ID sanitization; do not suppress the error.
+ - Code-derived graph too large (>100 nodes): apply focus or reduce depth; never emit an unreadable graph.
+ - Wrong code language auto-detection: re-derive with an explicit language.
+ - Missing document renderer: stop with `npm install -g @mermaid-js/mermaid-cli`; do not improvise a remote fallback.
+ - Mermaid parse error: show the parse error, repair the `.mmd` source, and retry; do not deliver broken artifacts.
+ - Excalidraw conversion unavailable or unsupported for a non-flowchart: skip only that artifact, deliver SVG and PNG, and state the limitation.
+ - PNG rasterization failure: fall back to a headless-browser screenshot of the SVG.
+ - Missing or unwritable target document: stop and state its path; do not create or embed elsewhere.
+ - Partial document result: remove unrendered or partial artifacts; a `.mmd` file alone is not a diagram.
+ - Rollback: delete generated code-mode artifacts or the document-mode output-directory files and revert the target-document embed edit.
+ - Supplied placed width is missing its required positive value: stop before PNG rendering and report that the width must be positive in inches; when no width is supplied, use the renderer's intrinsic output width.
+ - Blocked result: report the exact mode, target, or diagram type that could not be resolved and why; do not claim the done predicate holds.
+
## Output
- A fenced `mermaid` code block (`flowchart` or `classDiagram`) scoped to a readable size, or a single-node explanatory diagram when no matching edges exist, ordered confirm → derive-edges → sanitize → scope → verify → deliver.
+
+ - `code-derived`: a fenced `mermaid` code block (`flowchart` or `classDiagram`) scoped to a readable size, or a single-node explanatory diagram when no matching edges exist.
+ - `document-embed`: the embedded rendered diagram in the target document, with Mermaid source (`.mmd`), SVG, PNG, and (for supported flowcharts) an editable Excalidraw scene in the output directory; report `DONE` only after embedding is confirmed and `BLOCKED` when the renderer or document is unavailable.