mirror of
https://github.com/anthropics/claude-plugins-official.git
synced 2026-08-11 22:23:32 +00:00
code-modernization: interactive topology map, preflight command, persona flows
modernize-map previously rendered the call graph and data lineage as static Mermaid diagrams, which become unreadable once a node has ~10+ edges — exactly the shape of real legacy systems. It now builds an interactive viewer from a shipped template (assets/topology-viewer.html): a zoomable circle-pack of domains/modules sized by LOC, rendered to canvas with level-of-detail reveal, dependency edges with per-kind toggles, search with fly-to, a per-node detail sidebar, and a flow walkthrough mode. Small domain-level .mmd exports remain for docs. - topology.json now has a documented schema (hierarchy + edges + entry points + observations + flows) consumed by the viewer - map traces 2-4 business flows anchored to personas (claimant, operator, auditor), each step in plain business language mapped to the modules that implement it; the viewer plays them as numbered paths - brief gains a Business Walkthroughs section connecting each persona flow to the phase that replaces it - new modernize-preflight command: detects the stack, checks analysis tooling, smoke-compiles a real source file with the legacy toolchain, inventories missing copybooks/descriptors/binary-only artifacts, and writes a per-command readiness verdict - transform now verifies legacy + target toolchains before its plan gate instead of failing at test time - README: commands updated, optional-tooling section reframed as 'what to give Claude'
This commit is contained in:
Morgan Lunt
@@ -55,50 +55,108 @@ re-run and audited. Have it write a machine-readable
|
||||
`analysis/$1/topology.json` and print a human summary. Run it; show the
|
||||
summary (cap at ~200 lines for very large estates).
|
||||
|
||||
## Render
|
||||
`topology.json` must follow this schema — it feeds the interactive viewer:
|
||||
|
||||
From the extracted data, generate **three Mermaid diagrams** and write them
|
||||
to `analysis/$1/TOPOLOGY.html` as a self-contained page that renders in any
|
||||
browser.
|
||||
|
||||
The HTML page must use: dark `#1e1e1e` background, `#d4d4d4` text,
|
||||
`#cc785c` for `<h2>`/accents, `system-ui` font, all CSS **inline** (no
|
||||
external stylesheets). Load Mermaid from a CDN in `<head>`:
|
||||
|
||||
```html
|
||||
<script type="module">
|
||||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
|
||||
mermaid.initialize({ startOnLoad: true, theme: 'dark' });
|
||||
</script>
|
||||
```json
|
||||
{
|
||||
"system": "<display name>",
|
||||
"root": {
|
||||
"id": "sys", "name": "<system>", "kind": "system",
|
||||
"children": [
|
||||
{ "id": "dom:<domain>", "name": "<Domain>", "kind": "domain",
|
||||
"children": [
|
||||
{ "id": "<MODULE>", "name": "<MODULE>", "kind": "module",
|
||||
"language": "cobol", "loc": 1234, "file": "src/MODULE.cbl" }
|
||||
] },
|
||||
{ "id": "dom:data", "name": "Data stores", "kind": "domain",
|
||||
"children": [
|
||||
{ "id": "ds:<NAME>", "name": "<NAME>", "kind": "datastore" }
|
||||
] }
|
||||
]
|
||||
},
|
||||
"edges": [
|
||||
{ "source": "<id>", "target": "<id>", "kind": "call" }
|
||||
],
|
||||
"entryPoints": ["<id>", "..."],
|
||||
"observations": ["<architect observation>", "..."],
|
||||
"flows": [
|
||||
{ "name": "<business flow>", "persona": "<who experiences it>",
|
||||
"description": "<one sentence, plain language>",
|
||||
"steps": [
|
||||
{ "label": "<business-language step>", "nodes": ["<id>", "<id>"] }
|
||||
] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Each diagram goes in a `<pre class="mermaid">...</pre>` block. Do **not**
|
||||
wrap diagrams in markdown ` ``` ` fences inside the HTML.
|
||||
- Group leaf modules under `domain` containers (use the domains from
|
||||
`/modernize-assess` if available). Leaf kinds: `module`, `datastore`,
|
||||
`job`, `screen`. `loc` drives circle size — include it for modules.
|
||||
- Edge kinds: `call` (direct), `dispatch` (dynamic/router), `read`,
|
||||
`write`. Every edge endpoint must be a leaf id that exists in the tree.
|
||||
- `observations`: 3–7 architect observations — tight coupling clusters,
|
||||
single points of failure, service-extraction candidates, data stores
|
||||
with too many writers.
|
||||
- `flows` is the **persona walkthrough** section — see below.
|
||||
|
||||
1. **`graph TD` — Module call graph.** Cluster by domain (use `subgraph`).
|
||||
Highlight entry points in a distinct style. Cap at ~40 nodes — if larger,
|
||||
show domain-level with one expanded domain.
|
||||
## Persona flows
|
||||
|
||||
2. **`graph LR` — Data lineage.** Programs → data stores.
|
||||
Mark read vs write edges.
|
||||
Trace **2–4 end-to-end business flows**, each anchored to a persona —
|
||||
the people who experience the system, not the people who maintain it
|
||||
(e.g. for a benefits system: the claimant, the caseworker, the auditor;
|
||||
for billing: the customer, the billing operator). For each flow:
|
||||
|
||||
3. **`flowchart TD` — Critical path.** Trace ONE end-to-end business flow
|
||||
(e.g., "monthly billing run" or "process payment") through every program
|
||||
and data store it touches, in execution order. If production telemetry is
|
||||
available (see `/modernize-assess` Step 4), annotate each step with its
|
||||
p50/p99 wall-clock.
|
||||
- `name` + one-sentence `description` in plain business language —
|
||||
something a steering committee member relates to ("a claimant files a
|
||||
weekly claim"), not a data-flow label ("CLM batch ingest").
|
||||
- `steps`: 3–8 steps, each with a business-language `label` and the
|
||||
`nodes` (programs + data stores) that implement that step, in
|
||||
execution order.
|
||||
|
||||
Also export the three diagrams as standalone `.mmd` files for re-use:
|
||||
`analysis/$1/call-graph.mmd`, `analysis/$1/data-lineage.mmd`,
|
||||
`analysis/$1/critical-path.mmd`.
|
||||
This is the bridge between the technical map and non-technical
|
||||
stakeholders: the same diagram answers "which program does X" for
|
||||
engineers and "what happens when someone files a claim" for everyone else.
|
||||
|
||||
## Annotate
|
||||
## Render
|
||||
|
||||
Below each `<pre class="mermaid">` block in TOPOLOGY.html, add a `<ul>`
|
||||
with 3-5 **architect observations**: tight coupling clusters, single
|
||||
points of failure, candidates for service extraction, data stores
|
||||
touched by too many writers.
|
||||
`analysis/$1/TOPOLOGY.html` is an **interactive map**: a zoomable
|
||||
circle-pack of the whole system (domains as containers, modules sized by
|
||||
LOC) with dependency edges, search, per-node detail sidebar, edge-kind
|
||||
toggles, and a flow-walkthrough mode that plays each persona flow as a
|
||||
numbered path. Build it from the template that ships with this plugin —
|
||||
do not hand-write the viewer:
|
||||
|
||||
```bash
|
||||
python3 - "$CLAUDE_PLUGIN_ROOT/assets/topology-viewer.html" analysis/$1 <<'EOF'
|
||||
import json, sys
|
||||
tpl_path, out_dir = sys.argv[1], sys.argv[2]
|
||||
tpl = open(tpl_path).read()
|
||||
data = json.dumps(json.load(open(f"{out_dir}/topology.json")))
|
||||
html = tpl.replace("/*__TOPOLOGY_DATA__*/ null", "/*__TOPOLOGY_DATA__*/ " + data)
|
||||
open(f"{out_dir}/TOPOLOGY.html", "w").write(html)
|
||||
print(f"wrote {out_dir}/TOPOLOGY.html ({len(html):,} bytes)")
|
||||
EOF
|
||||
```
|
||||
|
||||
The viewer loads d3 from a CDN, so opening it needs network access; the
|
||||
rest is self-contained. If the data injection marker is missing from the
|
||||
output, the template was not found — check `$CLAUDE_PLUGIN_ROOT`.
|
||||
|
||||
Mermaid stays for **small, exportable** diagrams. Generate standalone
|
||||
`.mmd` files for reuse in docs and PRs — but keep each under ~40 edges;
|
||||
collapse to domain level if the full graph is bigger (dense Mermaid
|
||||
becomes unreadable, which is exactly what the interactive map is for):
|
||||
|
||||
- `analysis/$1/call-graph.mmd` — domain-level `graph TD`, entry points
|
||||
highlighted
|
||||
- `analysis/$1/data-lineage.mmd` — `graph LR`, programs → data stores,
|
||||
read vs write marked
|
||||
- `analysis/$1/critical-path.mmd` — `flowchart TD` of the primary flow
|
||||
from `flows`, annotated with p50/p99 wall-clock if telemetry is
|
||||
available (see `/modernize-assess` Step 4)
|
||||
|
||||
## Present
|
||||
|
||||
Tell the user to open `analysis/$1/TOPOLOGY.html` in a browser.
|
||||
Tell the user to open `analysis/$1/TOPOLOGY.html` in a browser, and to
|
||||
try: search for a module, click it to see its connections, and pick a
|
||||
persona flow from the walkthrough dropdown.
|
||||
|
||||
Reference in New Issue
Block a user