@backstage/migrate-policy-query-user

Name: migrate-policy-query-user codemod
Availability: InStock

Backstage 1.51.0 migration codemod that updates usages of the now-removed token, expiresInSeconds, and identity fields on PolicyQueryUser from @backstage/plugin-permission-node.

What it does

Field removals

In Backstage 1.51.0, the PolicyQueryUser type from @backstage/plugin-permission-node removed the token, expiresInSeconds, and identity fields. This codemod detects and migrates these usages.

Destructuring patterns

Removes token and expiresInSeconds from destructuring patterns and renames identity to info:

ts

When identity is aliased ({ identity: userIdentity }), the alias is preserved under the new key ({ info: userIdentity }).

Property access

Renames identity member access to info:

ts

Mock object literals

Detects mock object literals that match the PolicyQueryUser shape (containing credentials plus token or identity) and removes the deprecated fields while preserving nested object structure:

ts

TODO comments

When token is used in statements (e.g., passed to downstream APIs), the codemod inserts a TODO comment indicating manual migration to coreServices.auth credentials is needed:

ts

Import gating

The codemod only transforms files that import from @backstage/plugin-permission-node, avoiding false positives on unrelated identity or token usages.

Known limitations

Untyped parameters: Destructuring patterns are only transformed when the parameter has an explicit PolicyQueryUser type annotation. Untyped parameters require manual migration or the AI fixup step.
expiresInSeconds member access: While expiresInSeconds is removed from destructuring patterns and object literals, member access like user.expiresInSeconds may need the AI fixup step.

Optional: AI fixup step

Enable with --param aiFixup=true to address edge cases:

Handles token usages that need migration to coreServices.auth credentials
Catches untyped PolicyQueryUser parameters
Verifies remaining identity references are migrated

Installation

bash

Usage (from this repo)

bash

Development

From the repo root:

bash

Or from this package directory:

bash

Registry

Ready to contribute?

backstage/migrate-policy-query-user

Run locally