[schultzp2020]

Summary

Adds the Backstage 1.56.0 migration recipe: codemods/v1.56.0/ (@backstage/v1-56-0-migration-recipe), one package bundling the deterministic transforms from #189, following the release-owned recipe layout of codemods/v1.55.0/.

codemods/v1.56.0/
├── workflow.yaml                  # runs every script in order
├── scripts/
│   ├── migrate-catalog-filters-to-query.ts        # EntityFilter.getCatalogQuery()
│   ├── remove-atlassian-username-resolver.ts      # TS resolver replacement
│   ├── remove-atlassian-username-resolver-yaml.ts # app-config TODO flag
│   ├── remove-total-items-option.ts               # streamEntities totalItems
│   └── move-bui-menusection-disabled-keys.ts      # BUI MenuSection disabledKeys
└── tests/                         # 25 fixture cases + workflow.test.ts

Highlights per step:

• Step 1 adds getCatalogQuery() next to (never replacing) deprecated getCatalogFilters(): literal CatalogFilters[] returns are translated to $any/$all predicates with singleton collapse and any-of value arrays; empty arrays return undefined; computed returns get a TODO(backstage-codemod) stub. Files that already define getCatalogQuery are skipped.
• Step 2 replaces the removed usernameMatchingUserEntityName with emailLocalPartMatchingUserEntityName and leaves a TODO suggesting emailMatchingUserEntityProfileEmail. Handles both import shapes of the removed collection (import { atlassianSignInResolvers } and import * as ns), drops the import when unused, and only flags the YAML resolver: key (choice between the two email resolvers is a data-alignment decision).
• Step 3 removes the deprecated-and-ignored totalItems option from streamEntities calls and StreamEntitiesRequest-typed literals, absorbing adjacent commas; GetEntitiesResponse.totalItems and unrelated fields stay untouched.
• Step 4 hoists MenuSection disabledKeys to the enclosing Menu; without a Menu, sets isDisabled on literal-keyed MenuItems; dynamic keys and pre-existing Menu disabledKeys get a TODO carrying the original prop.

Deviation from the issue table: step 2 is listed as one script, but run-recipe-tests enforces one fixture language per suite and each workflow step takes a single language, so it ships as two entrypoints (remove-atlassian-username-resolver.ts / -yaml.ts), mirroring the v1.54 rename-openapi-validate-command-* precedent.

No recipe-level aiFixup; ambiguity is always marked with TODO(backstage-codemod) (the README tells adopters to grep for it). Manual-only 1.56.0 changes are listed in the README's out-of-scope table.

Evidence

• Before: no codemods/v1.56.0/ package; upgrading to 1.56.0 leaves custom EntityFilters, the Atlassian resolver, totalItems options, and MenuSection disabledKeys broken/unmigrated.
  After: all repo gates pass — yarn format:check, yarn lint, yarn test (97 jssg suites incl. 25 new fixture cases, per-suite tsc, codemod workflow validate, node --test), and yarn check:changed (the CI gate). A whole-workflow dry-run + apply on a representative app produced exactly the before/after rewrites from the issue for all five steps; a no-op run on a clean tree completes in the same ~1s.

Merge Danger

Door: two-way (new package only; no existing codemod or tooling changed; deletions revert cleanly).

Blast Radius: additive. Consumers only pick this up by running the new recipe; the changeset is a minor initial release of a new package.