claude-plugins-official/modernize-preflight.md at bec8d7c93ae523e1cb3204eb061c801eaff017e5

mirror of https://github.com/anthropics/claude-plugins-official.git synced 2026-06-13 22:26:03 -03:00

code-modernization: vendor d3, viewer robustness, status command, pipeline fixes

Viewer (assets/topology-viewer.html):
- inline a minified d3 subset (hierarchy/pack, zoom, selection,
  interpolateZoom, ease; ISC license) instead of loading from a CDN —
  the page is now fully self-contained and works on air-gapped networks
- handle duplicate node ids (unique-suffix; edges bind to the first
  occurrence) and store parent references directly, fixing
  level-of-detail and selection corruption with messy generated data
- share one reveal rule between drawing, edge culling, and hit-testing
  so edges no longer draw into collapsed containers
- pre-bucket edges by kind and keep a per-node adjacency map; the
  hover/selection pass no longer scans every edge each frame
- cancel in-flight fly-to animations when a new one starts; clamp
  fly-to zoom to the zoom extent; derive max zoom from the smallest
  leaf so deep estates stay reachable
- render dead-end candidates (new deadEnds field) with a dashed
  outline and a sidebar badge
- clicking a node during a flow walkthrough exits the walkthrough;
  search results clear on selection and Escape; surrogate-safe label
  truncation; clearer stats line; explicit empty-topology message

Commands:
- new /modernize-status: read-only progress report — artifact inventory
  with timestamps, staleness flags, secrets-hygiene checks, next step
- map: deadEnds in the topology schema; datastore names must be logical
  identifiers with credentials stripped from URLs/DSNs
- brief: read topology.json + .mmd files (not the interactive HTML);
  staleness check against inputs; effort unit aligned to person-months
- transform: secret-safe characterization-test prompt; diff -y fallback
  when delta is missing; credential-safe diff selection
- reimagine: target vision is everything after the first argument (was
  silently truncated to one word); masking rules in spec/scaffold/
  handoff prompts
- brief/transform/reimagine: human-approval gates phrased as explicit
  stop-and-wait instead of 'enter plan mode'
- preflight: delta in the tool table; brief added to the verdict list
- README: preflight/status in the workflow; legacy/ deny list also
  covers Write; plugin + marketplace descriptions updated

2026-06-09 08:48:04 -07:00

4.2 KiB

Raw Blame History

description	argument-hint
Environment readiness check — analysis tools, build toolchain, source completeness, telemetry access	<system-dir> [target-stack]

Check whether this environment is ready to analyze — and eventually transform — legacy/$1, and tell the user exactly what to fix before the other commands run into it. Modernization sessions fail late and confusingly when this isn't done: assessment metrics silently degrade without analysis tools, characterization tests can't run without a build toolchain, and dependency maps come out wrong when half the source isn't in the tree.

Run every check even when an early one fails — the point is one complete readiness report, not the first error.

Check 1 — Detect the stack

Fingerprint legacy/$1 from file extensions and manifests: languages, build system, deployment/config descriptors. This drives which checks below apply. Report what was detected and the rough file split.

Check 2 — Analysis tooling

For each, check availability (command -v) and report version, what it's used for, and what degrades without it:

Tool	Used by	Without it
`scc` (or `cloc`)	assess	LOC/complexity fall back to `find`+`wc`; COCOMO estimate gets coarser
`lizard`	assess --portfolio	complexity estimated from decision-keyword counts
`glow`	all	markdown artifacts render as plain text
`delta`	transform	side-by-side diffs fall back to `diff -y`

Include the platform's install one-liner for anything missing (brew install scc, apt install cloc, pip install lizard, …).

Check 3 — Build toolchain (smoke test, not just presence)

Identify the compiler/interpreter for the detected legacy stack — e.g. GnuCOBOL (cobc) for COBOL, JDK + Maven/Gradle for Java, cc/make for C, dotnet for .NET. Then prove it works on this codebase: pick one representative source file and run a syntax-only compile (cobc -fsyntax-only, javac, gcc -fsyntax-only, …).

A failed smoke test is the most valuable output of this command — report the actual error and diagnose it: missing copybook/include path, missing dialect flag (-std=ibm etc.), fixed vs free format, missing dependency jar. These are the errors that otherwise surface mid-/modernize-transform with much less context.

If the user passed a [target-stack], do the same for it: runtime, package manager, test framework (mvn -v, npm -v, pytest --version, …).

Check 4 — Source completeness

The dependency map is only as good as what's in the tree. Check for the detected stack's equivalents of:

Referenced-but-missing includes — copybooks (COPY X with no X.cpy), headers, imports that resolve nowhere. Count and list the top missing names.
Deployment/config descriptors — JCL for batch COBOL, CICS CSD definitions, web.xml/route configs, cron/scheduler definitions. Without these, entry-point detection and the code↔storage join in /modernize-map are guesswork.
Data definitions — DDL, schemas, copybook record layouts, ORM mappings.
Binary-only artifacts — load modules, jars, DLLs with no matching source. These become unmappable black boxes; flag them now.

Check 5 — Optional context

Production telemetry — is an observability/APM MCP server connected, or are batch job logs / runtime exports available? (Enables the runtime overlay in /modernize-assess Step 4 and timing annotations in /modernize-map.)
Version control history — is legacy/$1 under git with meaningful history? (Change-frequency data sharpens risk ranking.)

Report

Write analysis/$1/PREFLIGHT.md: a status table — one row per check, status ✅ / ⚠️ / ❌, what was found, and the fix for anything not green — followed by a Ready / Ready-with-gaps / Not ready verdict per command:

assess + map + extract-rules — need Checks 1–2 green-ish and Check 4's missing-include count low
brief — needs only the three discovery artifacts; no tooling
transform + reimagine — additionally need Check 3 green for both legacy and target stacks
harden — needs Check 2 plus any stack-specific SAST tooling found

Print the table in the session too, and end with the single most important fix if anything is red.

4.2 KiB Raw Blame History Unescape Escape