typescript-decompiler/docs/phase-docs/phase-9-patch-capture-and-replay.md

Phase 9 — replay maintained transforms

Goal

Replay externally authored maintained transforms onto the regularized canonical editable tree so upgrades can carry your changes forward automatically where safe.

Script

scripts/replay-transforms.js

Workflow

1. load maintained transforms from long-lived stable metadata
2. target those transforms against the regularized upstream-derived tree produced by Phase 8
3. replay transforms in deterministic dependency-aware order
4. prefer jscodeshift codemods in MVP while allowing other deterministic transform forms when explicitly supported
5. emit explicit conflicts instead of forcing weak or unsafe replays
6. produce replay reports for applied, skipped, and conflicting transforms

Transform metadata

• transform ID
• transform type
• stable file, module, segment, or lineage anchor
• codemod path or AST selector
• inputs
• declared dependency or ordering metadata
• replay status

Constraints

• transform authoring and capture are outside the numbered upstream-processing pipeline
• do not derive transforms from git diffs inside this phase
• do not auto-apply destructive file removals in MVP
• do not apply weak-match replays

Verification

• replay transforms onto the same run successfully
• replay them onto a lightly changed regularized run successfully
• fail with an explicit conflict on an incompatible upstream change
• confirm the replayed tree parses, builds, and runs maintained/basic tests after replay