@planningcenter/tapestry-migration-cli 3.2.3-rc.8 → 3.3.0-rc.0

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "@planningcenter/tapestry-migration-cli",
-  "version": "3.2.3-rc.8",
+  "version": "3.3.0-rc.0",
   "description": "CLI tool for Tapestry migrations",
   "type": "module",
   "main": "dist/index.js",
-  "bin": {
-    "tapestry-migration-cli": "./src/index.ts"
-  },
+  "bin": "./src/index.ts",
   "scripts": {
     "build": "vite build",
     "dev": "tsc --watch",
@@ -32,7 +30,7 @@
   },
   "devDependencies": {
     "@emotion/react": "^11.14.0",
-    "@planningcenter/tapestry": "^3.2.3-rc.8",
+    "@planningcenter/tapestry": "^3.3.0-rc.0",
     "@planningcenter/tapestry-react": "^4.11.5",
     "@types/jscodeshift": "^17.3.0",
     "@types/node": "^20.0.0",
@@ -52,5 +50,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "370843598ae9aaeb9e975b4659173743cb7e519e"
+  "gitHead": "7fd3d76244befe3a32ba0a79ff512f7c31db40b2"
 }

package/src/components/preflight/index.ts

@@ -0,0 +1,90 @@
+import { Transform } from "jscodeshift"
+
+import { createAsPropCommentTransform } from "./transforms/commentOnAsProp"
+import { createStylePropsCleanupTransform } from "./transforms/convertStyleProps"
+
+const TAPESTRY_REACT_PACKAGE = "@planningcenter/tapestry-react"
+
+/**
+ * Collect every top-level named import from @planningcenter/tapestry-react
+ * (e.g. `import { Stack, Box as MyBox } from "@planningcenter/tapestry-react"`
+ * yields ["Stack", "Box"]). We target the *imported* name, not the local
+ * alias, because `attributeTransformFactory` already resolves aliases via
+ * `getImportName`.
+ *
+ * Member-expression targets like `<Link.Inline>` are intentionally out of
+ * scope — they're handled by the dedicated `run link` migration.
+ */
+function collectTapestryReactImports(
+  fileInfo: Parameters<Transform>[0],
+  api: Parameters<Transform>[1]
+): string[] {
+  const j = api.jscodeshift
+  const source = j(fileInfo.source)
+  const names = new Set<string>()
+
+  source
+    .find(j.ImportDeclaration, {
+      source: { value: TAPESTRY_REACT_PACKAGE },
+    })
+    .forEach((path) => {
+      path.node.specifiers?.forEach((spec) => {
+        if (
+          spec.type === "ImportSpecifier" &&
+          spec.imported.type === "Identifier"
+        ) {
+          names.add(spec.imported.name)
+        }
+      })
+    })
+
+  return [...names]
+}
+
+/**
+ * The `preflight` orchestrator: a cross-component assessment pass for
+ * tapestry-react. It applies each registered transform to every imported
+ * tapestry-react component in each file so the resulting report can scope
+ * the migration. Current transforms:
+ *  - shorthand style-prop conversion (`createStylePropsCleanupTransform`)
+ *  - `as={...}` TODO annotation (`createAsPropCommentTransform`) — flags call
+ *    sites because `@planningcenter/tapestry` does not support the `as` prop
+ *
+ * Note: applying this pass produces inline `style={{}}` objects, which is
+ * rarely the desired end state and can negatively impact rendering
+ * performance. Run with `--dry-run` for assessment and use the per-component
+ * migrations (e.g. `run button`) for the real conversion.
+ */
+const transform: Transform = (fileInfo, api, options) => {
+  const componentNames = collectTapestryReactImports(fileInfo, api)
+  if (componentNames.length === 0) {
+    return null
+  }
+
+  let currentSource = fileInfo.source
+  let hasAnyChanges = false
+
+  const transformBuilders = [
+    createStylePropsCleanupTransform,
+    createAsPropCommentTransform,
+  ]
+
+  for (const componentName of componentNames) {
+    for (const build of transformBuilders) {
+      const individualTransform = build(componentName)
+      const result = individualTransform(
+        { ...fileInfo, source: currentSource },
+        api,
+        options
+      )
+      if (result && result !== currentSource) {
+        currentSource = result as string
+        hasAnyChanges = true
+      }
+    }
+  }
+
+  return hasAnyChanges ? currentSource : null
+}
+
+export default transform

package/src/components/preflight/transforms/commentOnAsProp.ts

@@ -0,0 +1,38 @@
+import { Transform } from "jscodeshift"
+
+import { addCommentToAttribute } from "../../shared/actions/addCommentToAttribute"
+import { getAttribute } from "../../shared/actions/getAttribute"
+import { attributeTransformFactory } from "../../shared/transformFactories/attributeTransformFactory"
+
+const COMMENT =
+  "The `as` prop is not supported in @planningcenter/tapestry. Review this usage and migrate to a supported API before upgrading."
+
+const ANNOTATION_MARKER = "TODO: tapestry-migration (as):"
+
+/**
+ * Builds a transform that flags `as={...}` usage on a single tapestry-react
+ * component with a TODO comment. `@planningcenter/tapestry` does not support
+ * the `as` prop, so these call sites need manual review before upgrading.
+ *
+ * The transform is idempotent: re-running it on an already-annotated file
+ * does not stack duplicate comments.
+ */
+export function createAsPropCommentTransform(componentName: string): Transform {
+  return attributeTransformFactory({
+    condition: (element) => Boolean(getAttribute({ element, name: "as" })),
+    targetComponent: componentName,
+    targetPackage: "@planningcenter/tapestry-react",
+    transform: (element, { j }) => {
+      const attribute = getAttribute({ element, name: "as" })
+      if (!attribute) return false
+
+      const alreadyAnnotated = attribute.comments?.some((comment) =>
+        comment.value.includes(ANNOTATION_MARKER)
+      )
+      if (alreadyAnnotated) return false
+
+      addCommentToAttribute({ attribute, j, text: COMMENT })
+      return true
+    },
+  })
+}

package/src/components/preflight/transforms/convertStyleProps.test.ts

@@ -0,0 +1,333 @@
+import jscodeshift from "jscodeshift"
+import { describe, expect, it } from "vitest"
+
+import preflight from "../index"
+
+const j = jscodeshift.withParser("tsx")
+
+function applyPreflight(source: string, options = {}) {
+  const fileInfo = { path: "test.tsx", source }
+  const result = preflight(
+    fileInfo,
+    { j, jscodeshift: j, report: () => {}, stats: () => {} },
+    options
+  ) as string | null
+  return result || source
+}
+
+describe("preflight: convertStyleProps across all tapestry-react components", () => {
+  describe("discovery", () => {
+    it("no-ops when the file has no @planningcenter/tapestry-react imports", () => {
+      const source = `
+        import { Something } from "some-other-package"
+
+        export function TestComponent() {
+          return <Something padding={16} />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      // Style props on non-tapestry-react components are left alone.
+      expect(result).toContain("padding={16}")
+      expect(result).not.toContain("style={{")
+    })
+
+    it("leaves a same-named import from a different package untouched", () => {
+      const source = `
+        import { Stack } from "some-other-ui-lib"
+
+        export function TestComponent() {
+          return <Stack padding={16} margin={8} />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).toContain("padding={16}")
+      expect(result).toContain("margin={8}")
+      expect(result).not.toContain("style={{")
+    })
+  })
+
+  describe("unmigrated components (no dedicated per-component migration)", () => {
+    it("merges shorthand style props into style={{}} on Stack", () => {
+      const source = `
+        import { Stack } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <Stack padding={16} margin={8} />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).toMatchInlineSnapshot(`
+        "
+                import { Stack } from "@planningcenter/tapestry-react"
+
+                export function TestComponent() {
+                  return (
+                    <Stack
+                      style={{
+                        paddingTop: "128px",
+                        paddingRight: "128px",
+                        paddingBottom: "128px",
+                        paddingLeft: "128px",
+                        marginTop: "64px",
+                        marginRight: "64px",
+                        marginBottom: "64px",
+                        marginLeft: "64px"
+                      }} />
+                  );
+                }
+              "
+      `)
+    })
+
+    it("preserves the visible prop by routing it through style", () => {
+      const source = `
+        import { Box } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <Box visible={false} padding={8} />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).toContain("style={{")
+      expect(result).toContain('display: "none"')
+      expect(result).not.toContain("visible={false}")
+      expect(result).not.toContain("padding={8}")
+    })
+
+    it("leaves non-style props (like children and id) alone", () => {
+      const source = `
+        import { Stack } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <Stack id="main" padding={16}>hello</Stack>
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).toContain('id="main"')
+      expect(result).toContain(">hello</Stack>")
+      expect(result).not.toContain("padding={16}")
+    })
+  })
+
+  describe("multiple components in one file", () => {
+    it("applies style-prop cleanup independently to each imported component", () => {
+      const source = `
+        import { Stack, Box } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return (
+            <Stack padding={16}>
+              <Box margin={8} />
+            </Stack>
+          )
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).not.toContain("padding={16}")
+      expect(result).not.toContain("margin={8}")
+      expect(result.match(/style=\{\{/g)?.length ?? 0).toBeGreaterThanOrEqual(2)
+    })
+  })
+
+  describe("aliased imports", () => {
+    it("handles local aliases via the factory's getImportName resolution", () => {
+      const source = `
+        import { Stack as MyStack } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <MyStack padding={16} />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).not.toContain("padding={16}")
+      expect(result).toContain("style={{")
+    })
+  })
+
+  describe("components that already have dedicated migrations", () => {
+    it("still applies the generic cleanup to Checkbox (user chose to include all components)", () => {
+      const source = `
+        import { Checkbox } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <Checkbox visible={false} marginTop={16} label="Test" />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).toContain("style={{")
+      expect(result).toContain('display: "none"')
+      expect(result).not.toContain("visible={false}")
+      expect(result).not.toContain("marginTop={16}")
+    })
+  })
+
+  describe("import preservation", () => {
+    it("does not modify the import declaration", () => {
+      const source = `
+        import { Stack } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <Stack padding={16} />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).toContain(
+        'import { Stack } from "@planningcenter/tapestry-react"'
+      )
+    })
+  })
+
+  describe("as prop TODO annotation", () => {
+    it("adds a TODO comment when a tapestry-react component uses as={string}", () => {
+      const source = `
+        import { Box } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <Box as="section" />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).toMatch(/TODO: tapestry-migration \(as\):/)
+      expect(result).toContain("not supported in @planningcenter/tapestry")
+      // The `as` prop itself must be preserved — only a comment is added.
+      expect(result).toContain('as="section"')
+    })
+
+    it("adds a TODO comment when as={} references a component", () => {
+      const source = `
+        import { Box } from "@planningcenter/tapestry-react"
+        import { MyWrapper } from "./MyWrapper"
+
+        export function TestComponent() {
+          return <Box as={MyWrapper} />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).toMatch(/TODO: tapestry-migration \(as\):/)
+      expect(result).toContain("as={MyWrapper}")
+    })
+
+    it("leaves components without an as prop untouched by the as-prop transform", () => {
+      const source = `
+        import { Box } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <Box id="plain" />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).not.toMatch(/TODO: tapestry-migration \(as\):/)
+    })
+
+    it("does not flag as={} on non-tapestry-react components", () => {
+      const source = `
+        import { Box } from "some-other-ui-lib"
+
+        export function TestComponent() {
+          return <Box as="section" />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).not.toMatch(/TODO: tapestry-migration \(as\):/)
+    })
+
+    it("flags as={} across multiple different tapestry-react components", () => {
+      const source = `
+        import { Stack, Box } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return (
+            <Stack as="main">
+              <Box as="aside" />
+            </Stack>
+          )
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      const matches = result.match(/TODO: tapestry-migration \(as\):/g) ?? []
+      expect(matches.length).toBe(2)
+    })
+
+    it("is idempotent — a second run does not stack duplicate TODO comments", () => {
+      const source = `
+        import { Box } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <Box as="section" />
+        }
+      `
+
+      const firstPass = applyPreflight(source)
+      const secondPass = applyPreflight(firstPass)
+
+      const firstCount =
+        firstPass.match(/TODO: tapestry-migration \(as\):/g)?.length ?? 0
+      const secondCount =
+        secondPass.match(/TODO: tapestry-migration \(as\):/g)?.length ?? 0
+
+      expect(firstCount).toBe(1)
+      expect(secondCount).toBe(1)
+    })
+
+    it("handles aliased imports", () => {
+      const source = `
+        import { Box as MyBox } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <MyBox as="section" />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      expect(result).toMatch(/TODO: tapestry-migration \(as\):/)
+    })
+
+    it("still applies style-prop cleanup on the same element that has an as prop", () => {
+      const source = `
+        import { Box } from "@planningcenter/tapestry-react"
+
+        export function TestComponent() {
+          return <Box as="section" padding={16} />
+        }
+      `
+
+      const result = applyPreflight(source)
+
+      // as prop flagged with TODO
+      expect(result).toMatch(/TODO: tapestry-migration \(as\):/)
+      expect(result).toContain('as="section"')
+      // shorthand style prop still migrated
+      expect(result).toContain("style={{")
+      expect(result).not.toContain("padding={16}")
+    })
+  })
+})

package/src/components/preflight/transforms/convertStyleProps.ts

@@ -0,0 +1,29 @@
+import { Transform } from "jscodeshift"
+
+import { stackViewPlugin } from "../../../stubs/stackViewPlugin"
+import { stylePropTransformFactory } from "../../shared/transformFactories/stylePropTransformFactory"
+
+/**
+ * Builds a conservative, cross-component style-prop cleanup transform for a
+ * single tapestry-react component. The orchestrator calls this once per
+ * discovered named import from `@planningcenter/tapestry-react`.
+ *
+ * Deliberately minimal compared to per-component migrations:
+ * - Keeps only `visible` (universally kept by all existing migrations).
+ * - Uses `stackViewPlugin` — broadly correct for 7 of 8 existing components.
+ *   Link's text-plugin props stay with `run link`.
+ * - No `stylesToRemove` or `stylePropMapping` — those are genuinely
+ *   component-specific and belong in dedicated migrations.
+ */
+export function createStylePropsCleanupTransform(
+  componentName: string
+): Transform {
+  return stylePropTransformFactory({
+    plugin: stackViewPlugin,
+    stylePropMapping: {},
+    stylesToKeep: ["visible"],
+    stylesToRemove: [],
+    targetComponent: componentName,
+    targetPackage: "@planningcenter/tapestry-react",
+  })
+}

package/src/index.ts

@@ -70,6 +70,40 @@ program
     }
   })
 
+program
+  .command("preflight")
+  .description(
+    "Assess migration readiness across @planningcenter/tapestry-react usage. Surfaces shorthand style props and unsupported `as` prop usage so you can plan the work. Intended for assessment — running with changes applied converts shorthand style props to inline `style={{}}` objects, which is rarely the desired end state and can negatively impact rendering performance. Use the per-component migrations (e.g. `run button`) for the real conversion."
+  )
+  .requiredOption(
+    "-p, --path <path>",
+    "REQUIRED: The path to the folder/file to assess"
+  )
+  .option("-d, --dry-run", "Preview changes without writing to files")
+  .option("-v, --verbose", "Verbose output")
+  .option(
+    "-j, --js-theme <path>",
+    "Path to JavaScript theme file containing design tokens"
+  )
+  .option(
+    "-r, --report-path <path>",
+    "Path for the migration report. Creates a report when running with changes applied and does not create a report if no additional changes are required.",
+    "MIGRATION_REPORT.md"
+  )
+  .action((options) => {
+    console.log("🛫 Running tapestry-react preflight assessment...")
+    console.log(`📁 Target: ${options.path}`)
+    console.log(
+      `🔧 Mode: ${options.dryRun ? "Dry run (preview only)" : "Apply changes"}`
+    )
+    if (!options.dryRun) {
+      console.log(
+        "⚠️  Preflight is intended for assessment. Applying changes will convert shorthand style props to inline `style={{}}` objects, which is rarely the desired end state and can hurt rendering performance. Prefer `--dry-run` with `--report-path`."
+      )
+    }
+    runTransforms("preflight", options)
+  })
+
 program
   .command("help")
   .description("Show help information")

package/src/reportGenerator.ts

@@ -30,6 +30,8 @@ export const GLOBAL_MESSAGES = {
     "Buttons inside of Tapestry Group components are not supported and should not be migrated at this time.",
   checkbox:
     "Checkbox sizes have adjusted. Verify visual appearance as sizes may differ slightly.",
+  preflight:
+    "Preflight is an assessment pass. It surfaces shorthand style props and `as={...}` usage on tapestry-react components so you can scope the migration. Applying its changes converts shorthand style props into inline `style={{}}` objects — that is rarely the desired end state and can negatively impact rendering performance. Prefer running with `--dry-run` and `--report-path`, then use the per-component migrations (e.g. `run button`) for the real tapestry-react → tapestry conversion.",
   radio:
     "Radio sizes have adjusted. Verify visual appearance as sizes may differ slightly.",
   "toggle-switch":