feat(v1.55.0): add remove-relations-compatibility-config codemod

[schultzp2020]

Summary

codemods/v1.55.0/remove-relations-compatibility-config/
├── scripts/codemod.ts
-│   line/indent regex over root text
+│   YAML AST traversal: document -> mapping pairs (`field('key')` / `field('value')`)
+│   batched `commitEdits` on targeted pair ranges
+│   safe flow-root handling: remove only `catalog` pair, keep sibling pairs
+│   preserve catalog comments by converting emptied block to `catalog: {}` when needed
└── tests/
+    remove-direct-child-non-two-space-indent/
+    remove-flow-mapping-child/
+    remove-flow-root-preserve-siblings/
+    remove-quoted-keys/
+    multi-document-preserve-comment-when-catalog-emptied/
+    comment-only-catalog-preserved-when-key-removed/
+    flow-already-migrated-noop/

Independent internal review signed off on HEAD f3be127: AST path and fixture coverage reviewed; 16/16 fixtures and workflow validation passed, with no P1/P2 blockers. PR is ready for review; no formal GitHub review has been submitted.

Closes #150

Evidence

• Before (red): new fixture failed, proving prior data-loss path in flow root mapping

  yarn workspace @backstage/remove-relations-compatibility-config test
  ...
  ---- remove-flow-root-preserve-siblings ----
  Output mismatch for test 'remove-flow-root-preserve-siblings':
  -{ app: { title: Backstage } }
  

• After (green): fixture and full package suite pass

  yarn workspace @backstage/remove-relations-compatibility-config test
  running 12 tests
  ...
  test remove-flow-root-preserve-siblings                   ... ok
  test comment-only-catalog-preserved-when-key-removed      ... ok
  ...
  test result: ok. 12 passed; 0 failed
  ✅ Workflow definition is valid
  

• Repo checks:

  yarn format:check   # pass
  yarn lint           # pass
  yarn test           # pass
  yarn check:changed  # pass (includes README freshness)
  

• Performance audit (workflow path, selective app-config globs):

  Corpus:
    - 1800 non-target files
    - 120 included app-config*.yaml no-op files
    - 120 non-included yaml files
    - edited corpus adds 17 true-positive files
  
  No-op timings (ms): 2085, 2234, 1971
  Real timings  (ms): 2087, 2163, 2090
  
  Metrics:
    no-op: key_removed=0, empty_catalog_removed=0
    real : key_removed=17, empty_catalog_removed=0
  

Approved clean-source QA (read-only)

• Local workflow dry-run on Backstage 0863f0349c63fa7475b89aed71b6fb8214791394: rc=0 (~4s), zero direct catalog.enableRelationsCompatibility keys among 7 tracked app-config YAMLs, zero edits; source SHA/status unchanged.
• Local workflow dry-run on detached community-plugins 4c760a005dd582df1a61aec39ae50ad565f6dbbc: rc=0 (~4s), zero target keys among 110 tracked app-config YAMLs, zero edits; source SHA/status unchanged. Original dirty checkout untouched.
• Positive removals/comment preservation and idempotence are fixture/workflow-supported, not observed as real-source edits here. Final review found no blocker; low-risk gap: no explicit fixture for target key last in a flow mapping (comma-before code path reviewed).

Merge Danger

Door: two-way

Codemod package-only changes + fixtures + generated README index update; revert is a normal git revert.

Blast Radius: low

Scope limited to @backstage/remove-relations-compatibility-config YAML transform behavior and docs index ordering; no runtime app/library behavior changes.

[schultzp2020]

Review-blocked: current transform selects YAML keys with root-text regex/indentation parsing rather than parser-backed YAML path traversal. This can miss valid mapping forms/indentation and violates issue #150 detection requirements. PR kept draft pending correction, fixtures, and fresh review; do not merge yet.

[schultzp2020]

Fresh corrected review still blocks readiness: flow-mapping edits rebuild from pair text and may drop unrelated YAML comments between pairs. Add red fixtures for flow catalog and flow-root siblings with comments, then remove only target pair/comma tokens (or conservatively TODO/skip if preservation cannot be proven); rerun exact-head gates and review. PR stays draft.

[schultzp2020]

Final review at 37421a3 remains blocked: empty catalog: # keep note with sole target key loses inline header comment; README also needs comment-preservation exception. Read-only local-workflow QA on clean source snapshots is finishing at this head; sole corrective writer will add red header-comment fixture, preserve it, update README, rerun exact-head CI and fresh review. Keep draft.

[schultzp2020]

Fresh actual-diff review at 1b5d388 found another P1: flow-style catalog: { enableRelationsCompatibility: true } with preservable unrelated comment is removed wholesale when target is sole flow pair (scripts/codemod.ts:439-449), unlike block branch comment protection. 15 fixtures/full gates/CI green but miss flow-empty comment case; sole writer adding red fixture + preservation, bounded repro, exact-head checks/review. Keep draft. Reviewer’s separate Codemod CLI probe hung and was terminated with supervisor approval; that probe is unverified, not a pass.