Merge pull request #95 from backstage/fix/recipe-aifixup-and-workspace-member

fix: recipe aiFixup forwarding and workspace member skip

Author: schultzp2020

.agents/skills/validate-codemod-recipe/SKILL.md

@@ -103,6 +103,19 @@ The codemod modifies code it should not touch. Root causes:
 - **Name collision**: A field name like `token` or `loading` exists in
   unrelated code. Fix: verify the field belongs to the target type before
   transforming.
+- **Workspace member bleed**: A dependency-adding codemod modifies every
+  sub-package in a monorepo when the workspace root already provides the
+  dependency. Use judgement — sometimes sub-packages legitimately need
+  their own entry (published packages, version pinning). When the codemod
+  was designed to target only the workspace root (workflow excludes
+  `packages/**`), add a guard in the transform (e.g., check for a
+  `workspaces` field). When it makes sense for both root and members,
+  consider a param like `skipWorkspaceMembers` to let users choose.
+- **Workflow glob paths shift with `--target`**: A workflow that excludes
+  `packages/**/package.json` works with `--target .` but not `--target
+packages`, because `include`/`exclude` resolve relative to the target
+  root. Transforms that should only hit the repo root need guards in the
+  transform code itself, not just workflow globs.
 
 #### Redundant transforms
 
@@ -259,3 +272,16 @@ over-restrict the scope.
 - **lint-staged interference.** The repo's pre-commit hooks may reformat files
   via prettier. If prettier and a generator script (like `yarn readme`)
   disagree on formatting, the generator should run prettier as its last step.
+- **`params` must be forwarded in recipes.** When a sub-codemod declares
+  `params:` (e.g., `aiFixup`), the recipe workflow must also declare those
+  params at its own top level and forward them via `args:` on each step that
+  uses them. Without this, the codemod CLI crashes with
+  `Variable identifier is not bound to anything by context: "params.xxx"`.
+  Compare against v1.50.0+ recipes for the correct pattern.
+- **Cross-version audit.** Before fixing one recipe, `grep -r` across all
+  version directories for the same pattern. A bug in one recipe's
+  `params`/`args` setup is likely repeated in adjacent versions.
+- **JSON test fixtures and `JSON.stringify`.** When a transform round-trips
+  through `JSON.stringify`, arrays are expanded to one-element-per-line.
+  Test fixture `input.json` and `expected.json` must match this expanded
+  format or the test runner reports a false mismatch.

.changeset/fix-recipe-aifixup-workspace.md

@@ -0,0 +1,11 @@
+---
+'@backstage/add-jest-peer-dependency': patch
+'@backstage/v1-48-0-migration-recipe': patch
+'@backstage/v1-49-0-migration-recipe': patch
+---
+
+Fix recipe validation issues found during v1.45–v1.49 testing against the Backstage monorepo:
+
+- **v1.46.0 `add-jest-peer-dependency`**: Skip workspace member packages that inherit jest from the workspace root. Previously the codemod added redundant `jest`, `@types/jest`, `@jest/environment-jsdom-abstract`, and `jsdom` devDependencies to every sub-package even when the workspace root already provides them.
+- **v1.48.0 migration recipe**: Add `params.aiFixup` declaration and forward `args: ['aiFixup']` to `migrate-surface-to-bg-system` and `migrate-column-config-to-react-element`. Without this, running the recipe fails with `Variable identifier is not bound to anything by context: "params.aiFixup"`.
+- **v1.49.0 migration recipe**: Same `params.aiFixup` fix — add declaration and forward to `remove-create-public-sign-in-app`.

codemods/v1.46.0/add-jest-peer-dependency/scripts/codemod.ts

@@ -65,6 +65,12 @@ const transform: Codemod<JSON> = async (root, options) => {
     return null
   }
 
+  // Skip workspace member packages — they inherit jest from the workspace root.
+  // Only the root package.json (which has a "workspaces" field) should be modified.
+  if (!pkg.workspaces) {
+    return null
+  }
+
   // Check if jest is already present
   const hasJest = pkg.dependencies?.jest !== undefined || pkg.devDependencies?.jest !== undefined
 

codemods/v1.46.0/add-jest-peer-dependency/tests/already-has-jest/expected.json

@@ -1,5 +1,11 @@
 {
   "name": "my-backstage-app",
+  "workspaces": {
+    "packages": [
+      "packages/*",
+      "plugins/*"
+    ]
+  },
   "devDependencies": {
     "@backstage/cli": "^0.35.0",
     "jest": "^29.0.0"

codemods/v1.46.0/add-jest-peer-dependency/tests/already-has-jest/input.json

@@ -1,5 +1,11 @@
 {
   "name": "my-backstage-app",
+  "workspaces": {
+    "packages": [
+      "packages/*",
+      "plugins/*"
+    ]
+  },
   "devDependencies": {
     "@backstage/cli": "^0.35.0",
     "jest": "^29.0.0"

codemods/v1.46.0/add-jest-peer-dependency/tests/jest30-default/expected.json

@@ -1,5 +1,11 @@
 {
   "name": "my-backstage-app",
+  "workspaces": {
+    "packages": [
+      "packages/*",
+      "plugins/*"
+    ]
+  },
   "devDependencies": {
     "@backstage/cli": "^0.35.0",
     "@jest/environment-jsdom-abstract": "^30",

codemods/v1.46.0/add-jest-peer-dependency/tests/jest30-default/input.json

@@ -1,5 +1,11 @@
 {
   "name": "my-backstage-app",
+  "workspaces": {
+    "packages": [
+      "packages/*",
+      "plugins/*"
+    ]
+  },
   "devDependencies": {
     "@backstage/cli": "^0.35.0"
   }

codemods/v1.46.0/add-jest-peer-dependency/tests/jest30-with-existing-deps/expected.json

@@ -1,6 +1,12 @@
 {
   "name": "my-backstage-app",
   "version": "1.0.0",
+  "workspaces": {
+    "packages": [
+      "packages/*",
+      "plugins/*"
+    ]
+  },
   "dependencies": {
     "@backstage/core-plugin-api": "^1.0.0"
   },

codemods/v1.46.0/add-jest-peer-dependency/tests/jest30-with-existing-deps/input.json

@@ -1,6 +1,12 @@
 {
   "name": "my-backstage-app",
   "version": "1.0.0",
+  "workspaces": {
+    "packages": [
+      "packages/*",
+      "plugins/*"
+    ]
+  },
   "dependencies": {
     "@backstage/core-plugin-api": "^1.0.0"
   },

codemods/v1.46.0/add-jest-peer-dependency/tests/workspace-member-skipped/expected.json

@@ -0,0 +1,7 @@
+{
+  "name": "@backstage/plugin-catalog",
+  "devDependencies": {
+    "@backstage/cli": "^0.35.0",
+    "typescript": "^5.0.0"
+  }
+}