@carto/ps-react-ui 5.3.0 → 6.1.0

package/src/migration/v4/transforms/helpers.ts

@@ -0,0 +1,369 @@
+/**
+ * Shared surgery for the rule transforms.
+ *
+ * Everything here is deliberately conservative about *where* it writes. A
+ * codemod that moves a prop into `sx` has to merge with an `sx` that is
+ * already there, and one that cannot finish the job has to say so in the
+ * file rather than leave the site looking migrated.
+ *
+ * The narrowing helpers exist because ast-types describes several fields as
+ * unions wide enough to be `unknown` in practice — an `ImportSpecifier`'s
+ * `imported` can be an `Identifier` or a `StringLiteral`. Reading them
+ * through `nameOf` keeps the transforms readable and the types honest.
+ */
+import type {
+  API,
+  ASTPath,
+  Collection,
+  JSCodeshift,
+  JSXAttribute,
+  JSXElement,
+  JSXExpressionContainer,
+  JSXOpeningElement,
+  ObjectExpression,
+} from 'jscodeshift'
+
+export interface RuleContext {
+  j: JSCodeshift
+  root: Collection
+  path: string
+  api: API
+}
+
+/** Anything that can stand on the right of `=` in an expression position. */
+export type Expression = Exclude<
+  JSXExpressionContainer['expression'],
+  { type: 'JSXEmptyExpression' }
+>
+
+/** The value of a node that is a string literal, or undefined otherwise. */
+export function stringValue(node: unknown): string | undefined {
+  if (typeof node !== 'object' || node === null) return undefined
+  const { type, value } = node as { type?: unknown; value?: unknown }
+  if (type !== 'StringLiteral' && type !== 'Literal') return undefined
+  return typeof value === 'string' ? value : undefined
+}
+
+/** A node that recast will print leading comments for. */
+interface Commentable {
+  comments?: { value: string }[] | null
+}
+
+/** Prefix for every comment a rule leaves behind, so they are greppable. */
+export const TODO = 'TODO(mui9):'
+
+/** The `name` of an identifier-ish node, or '' when it is something else. */
+export function nameOf(node: unknown): string {
+  if (typeof node !== 'object' || node === null) return ''
+  const { name } = node as { name?: unknown }
+  return typeof name === 'string' ? name : ''
+}
+
+/** The type of a path's parent node, or '' at the root. */
+export function parentType(path: ASTPath): string {
+  const parent = path.parent as ASTPath | null
+  const node = parent?.node as { type?: unknown } | undefined
+  return typeof node?.type === 'string' ? node.type : ''
+}
+
+/**
+ * Leaves a `TODO(mui9)` comment above the statement containing `path`.
+ *
+ * Used by the rules that have no mechanical rewrite — `freeSolo` narrowing,
+ * a `Grid container` whose parent we cannot see. Dropping them silently
+ * would be worse than the checker this replaces: the run would report
+ * success over code that still has to be read.
+ *
+ * Idempotent: running the codemod twice does not stack comments.
+ */
+export function annotate(
+  j: JSCodeshift,
+  path: ASTPath,
+  message: string,
+): boolean {
+  let host: ASTPath | null = path
+  while (host && !j.Statement.check(host.node)) {
+    host = (host.parent as ASTPath | null) ?? null
+  }
+  if (!host) return false
+
+  // A comment on the declaration inside `export const x = …` prints between
+  // the two keywords, and the next run anchors on a different node and adds
+  // a second copy. Climbing to the export keeps one stable host.
+  const wrapper = host.parent as ASTPath | null
+  if (
+    wrapper &&
+    (parentType(host) === 'ExportNamedDeclaration' ||
+      parentType(host) === 'ExportDefaultDeclaration')
+  ) {
+    host = wrapper
+  }
+
+  const node = host.node as Commentable
+  const text = ` ${TODO} ${message}`
+  const comments = node.comments ?? []
+  if (comments.some((comment) => comment.value === text)) return false
+
+  node.comments = [...comments, j.commentLine(text, true, false)]
+  return true
+}
+
+/** The opening element's name, for `<Grid>` / `<Mui.Grid>` alike. */
+export function elementName(node: JSXOpeningElement): string {
+  const { name } = node
+  if (name.type === 'JSXIdentifier') return name.name
+  if (name.type === 'JSXMemberExpression') return nameOf(name.property)
+  return ''
+}
+
+/** Every JSX element in the file whose tag is one of `names`. */
+export function elementsNamed(
+  j: JSCodeshift,
+  root: Collection,
+  names: readonly string[],
+): Collection<JSXElement> {
+  return root
+    .find(j.JSXElement)
+    .filter((path) => names.includes(elementName(path.node.openingElement)))
+}
+
+/** The named attribute of an opening element, if it is written plainly. */
+export function attribute(
+  node: JSXOpeningElement,
+  name: string,
+): JSXAttribute | undefined {
+  return node.attributes?.find(
+    (attr): attr is JSXAttribute =>
+      attr.type === 'JSXAttribute' && nameOf(attr.name) === name,
+  )
+}
+
+/** Drops the named attributes from an opening element. */
+export function removeAttributes(
+  node: JSXOpeningElement,
+  names: readonly string[],
+): void {
+  node.attributes = node.attributes?.filter(
+    (attr) =>
+      !(attr.type === 'JSXAttribute' && names.includes(nameOf(attr.name))),
+  )
+}
+
+/**
+ * The expression behind an attribute value: `foo='bar'` gives the string
+ * literal, `foo={expr}` gives `expr`, and a bare `foo` gives `true`.
+ */
+export function attributeValue(j: JSCodeshift, attr: JSXAttribute): Expression {
+  const { value } = attr
+  if (value == null) return j.booleanLiteral(true)
+  if (value.type === 'JSXExpressionContainer') {
+    return value.expression.type === 'JSXEmptyExpression'
+      ? j.booleanLiteral(true)
+      : value.expression
+  }
+  return value
+}
+
+/** Merges entries into the element's `sx`. See `mergeIntoObjectProp`. */
+export function mergeIntoSx(
+  j: JSCodeshift,
+  opening: JSXOpeningElement,
+  entries: readonly (readonly [string, Expression])[],
+): boolean {
+  return mergeIntoObjectProp(j, opening, 'sx', entries)
+}
+
+/**
+ * Merges `{ [key]: value }` into an object-valued prop, creating it if
+ * absent. This is the shape of most of the v9 migration: a prop that used
+ * to stand alone folds into `sx` or into `slotProps`.
+ *
+ * A target that is not an object literal — a variable, an array, a spread —
+ * is not something we can merge into safely, so the caller is told no and
+ * annotates instead.
+ */
+export function mergeIntoObjectProp(
+  j: JSCodeshift,
+  opening: JSXOpeningElement,
+  prop: string,
+  entries: readonly (readonly [string, Expression])[],
+): boolean {
+  if (entries.length === 0) return true
+  const properties = entries.map(([key, value]) =>
+    j.objectProperty(
+      /^[A-Za-z_$][\w$]*$/.test(key) ? j.identifier(key) : j.stringLiteral(key),
+      value,
+    ),
+  )
+
+  const existing = attribute(opening, prop)
+  if (!existing) {
+    opening.attributes = [
+      ...(opening.attributes ?? []),
+      j.jsxAttribute(
+        j.jsxIdentifier(prop),
+        j.jsxExpressionContainer(j.objectExpression(properties)),
+      ),
+    ]
+    return true
+  }
+
+  const value = existing.value
+  if (
+    value?.type !== 'JSXExpressionContainer' ||
+    value.expression.type !== 'ObjectExpression'
+  ) {
+    return false
+  }
+
+  // Existing keys win: the author wrote them against the new API, the prop
+  // we are moving is the legacy spelling of the same thing.
+  const object: ObjectExpression = value.expression
+  const present = new Set(
+    object.properties.flatMap((property) =>
+      property.type === 'ObjectProperty' ? [nameOf(property.key)] : [],
+    ),
+  )
+  object.properties = [
+    ...object.properties,
+    ...properties.filter((property) => !present.has(nameOf(property.key))),
+  ]
+  return true
+}
+
+/** Whether an import brings in a value or only a type. */
+export type ImportKind = 'value' | 'type'
+
+/**
+ * The kind of an import declaration or of a single specifier, defaulting to
+ * a value import.
+ *
+ * Takes `unknown` because ast-types does not declare `importKind` on
+ * `ImportSpecifier` at all, though both the parser and recast carry it.
+ */
+export function importKind(node: unknown): ImportKind {
+  if (typeof node !== 'object' || node === null) return 'value'
+  return (node as { importKind?: unknown }).importKind === 'type'
+    ? 'type'
+    : 'value'
+}
+
+/**
+ * Adds a named import to `source`, reusing an existing declaration.
+ *
+ * `kind` has to be carried across: moving a specifier out of
+ * `import type { AlertProps } from '@mui/lab'` into a value import turns a
+ * type into a runtime binding, which fails under `verbatimModuleSyntax` and
+ * at runtime for a type-only export.
+ */
+export function ensureImport(
+  j: JSCodeshift,
+  root: Collection,
+  source: string,
+  imported: string,
+  kind: ImportKind = 'value',
+): void {
+  const declarations = root
+    .find(j.ImportDeclaration)
+    .filter(
+      (path) =>
+        path.node.source.value === source && importKind(path.node) === kind,
+    )
+
+  const already = declarations
+    .find(j.ImportSpecifier)
+    .some((path) => nameOf(path.node.imported) === imported)
+  if (already) return
+
+  const specifier = j.importSpecifier(j.identifier(imported))
+  const [first] = declarations.paths()
+  if (first) {
+    first.node.specifiers = [...(first.node.specifiers ?? []), specifier]
+    return
+  }
+
+  const declaration = j.importDeclaration([specifier], j.stringLiteral(source))
+  declaration.importKind = kind
+  const [program] = root.find(j.Program).paths()
+  program?.node.body.unshift(declaration)
+}
+
+/** Drops a named import, and the whole declaration once it is empty. */
+export function removeImport(
+  j: JSCodeshift,
+  root: Collection,
+  source: string,
+  imported: string,
+): void {
+  root
+    .find(j.ImportDeclaration)
+    .filter((path) => path.node.source.value === source)
+    .forEach((path) => {
+      path.node.specifiers = (path.node.specifiers ?? []).filter(
+        (specifier) =>
+          !(
+            specifier.type === 'ImportSpecifier' &&
+            nameOf(specifier.imported) === imported
+          ),
+      )
+      if ((path.node.specifiers ?? []).length === 0) j(path).remove()
+    })
+}
+
+/** Whether the identifier is still referenced anywhere outside imports. */
+export function isUsed(
+  j: JSCodeshift,
+  root: Collection,
+  name: string,
+): boolean {
+  return (
+    root
+      .find(j.Identifier, { name })
+      .filter((path) => parentType(path) !== 'ImportSpecifier')
+      .size() > 0 || root.find(j.JSXIdentifier, { name }).size() > 0
+  )
+}
+
+/**
+ * Visits every `Identifier` and `JSXIdentifier` in the file.
+ *
+ * A rename has to reach both — `import { AiTool }` and `<AiTool />` are
+ * different node types — and the two cannot be searched in one pass because
+ * their builders have different types.
+ */
+export function eachIdentifier(
+  j: JSCodeshift,
+  root: Collection,
+  visit: (node: { name: string }, parent: string) => void,
+): void {
+  root.find(j.Identifier).forEach((path) => {
+    visit(path.node, parentType(path))
+  })
+  root.find(j.JSXIdentifier).forEach((path) => {
+    visit(path.node, parentType(path))
+  })
+}
+
+/**
+ * The module a local name is imported from, or undefined when it is not
+ * imported at all.
+ *
+ * Used to tell a Material UI component apart from one that merely takes a
+ * prop with the same name. `@mui/codemod` matches on the prop, not on where
+ * the component came from, so it happily rewrites a third party's API.
+ */
+export function importSourceOf(
+  j: JSCodeshift,
+  root: Collection,
+  local: string,
+): string | undefined {
+  let source: string | undefined
+  root.find(j.ImportDeclaration).forEach((path) => {
+    if (source !== undefined) return
+    const found = (path.node.specifiers ?? []).some(
+      (specifier) => nameOf(specifier.local) === local,
+    )
+    if (found) source = stringValue(path.node.source)
+  })
+  return source
+}

package/src/migration/v4/transforms/meridian-5.ts

@@ -0,0 +1,163 @@
+/**
+ * Meridian 2.14 → 5.1.1 rewrites.
+ *
+ * The jump that needed no source change in the reference migration. What is
+ * here covers the two earlier majors a codebase may be coming through, plus
+ * the one API that moved in 5.
+ */
+import {
+  annotate,
+  eachIdentifier,
+  isUsed,
+  nameOf,
+  parentType,
+  removeImport,
+  type RuleContext,
+} from './helpers'
+
+/**
+ * Meridian 3.0.0 renames, old → new.
+ *
+ * A `Map`, not an object literal, because the key comes from the source: an
+ * identifier called `toString` or `constructor` reaches `Object.prototype`
+ * through a literal, and the function it finds there is truthy. Indexing a
+ * lookup table by an arbitrary identifier name once rewrote
+ * `value.toString()` into the printed source of `Object.prototype.toString`.
+ */
+const RENAMED_API = new Map([
+  ['AiTool', 'McpTool'],
+  ['CodeAreaProps', 'CodeAreaFieldProps'],
+])
+
+/** `AiTool` → `McpTool`, `CodeAreaProps` → `CodeAreaFieldProps`. */
+export function meridianRenamedApi({ j, root }: RuleContext): number {
+  let changed = 0
+
+  eachIdentifier(j, root, (node) => {
+    const renamed = RENAMED_API.get(node.name)
+    if (renamed === undefined) return
+    node.name = renamed
+    changed += 1
+  })
+
+  return changed
+}
+
+/**
+ * `cartoThemeOptions as unknown as Theme` → the exported `theme`.
+ *
+ * Meridian 5 exports a built theme; reading the options object and casting
+ * it into a `Theme` was always a lie, and in 5 the two have diverged enough
+ * that the cast produces wrong values rather than a type error.
+ */
+export function cartoThemeOptions({ j, root }: RuleContext): number {
+  let changed = 0
+
+  const imports = root.find(j.ImportSpecifier, {
+    imported: { name: 'cartoThemeOptions' },
+  })
+  if (imports.size() === 0) return 0
+
+  // Renaming into `theme` is only safe if nothing else owns that name here.
+  const local = isUsed(j, root, 'theme') ? 'cartoTheme' : 'theme'
+
+  imports.forEach((path) => {
+    // Replacing the whole specifier, not its `imported` identifier: recast
+    // patches a mutated node in place and would print `{ theme }`, dropping
+    // the `as cartoTheme` the rest of the file is about to rely on.
+    j(path).replaceWith(
+      j.importSpecifier(j.identifier('theme'), j.identifier(local)),
+    )
+    changed += 1
+  })
+
+  root
+    .find(j.Identifier, { name: 'cartoThemeOptions' })
+    .filter((path) => parentType(path) !== 'ImportSpecifier')
+    .forEach((path) => {
+      path.node.name = local
+      changed += 1
+    })
+
+  // `x as unknown as Theme` around the value it now already is.
+  root
+    .find(j.TSAsExpression)
+    .filter((path) => {
+      const inner = path.node.expression
+      return (
+        inner.type === 'TSAsExpression' &&
+        inner.expression.type === 'Identifier' &&
+        inner.expression.name === local
+      )
+    })
+    .forEach((path) => {
+      j(path).replaceWith(j.identifier(local))
+      changed += 1
+    })
+
+  // That cast was often the file's only use of `Theme`, and an import left
+  // behind with no user is a compile error under `noUnusedLocals` — caused
+  // by this rule, so it cleans up after itself.
+  if (changed > 0 && !isUsed(j, root, 'Theme')) {
+    removeImport(j, root, '@mui/material', 'Theme')
+  }
+
+  return changed
+}
+
+/** The Builder widgets Meridian 4.0.0 removed, and their prop types. */
+const REMOVED_WIDGETS = [
+  'PieWidgetUI',
+  'TimeSeriesWidgetUI',
+  'CategoryWidgetUI',
+  'HistogramWidgetUI',
+  'ScatterPlotWidgetUI',
+  'TableWidgetUI',
+  'RangeWidgetUI',
+  'FormulaWidgetUI',
+]
+
+const REMOVED_WIDGET_NAMES = new Set([
+  ...REMOVED_WIDGETS,
+  ...REMOVED_WIDGETS.map((name) => `${name}Props`),
+])
+
+/**
+ * Flags imports of the widgets Meridian 4.0.0 removed.
+ *
+ * No rewrite: the replacement is either `@carto/ps-react-ui`'s own widget,
+ * with a different API, or Meridian's new `./charts` and `./hooks` subpaths.
+ * Only flagged when the import is FROM Meridian — codebases routinely define
+ * their own `CategoryWidgetUI`, and matching the bare name turned a real
+ * finding into a page of noise on the project template, where 19 of 40
+ * matches were the app's own components.
+ */
+export function meridianRemovedWidgets({ j, root }: RuleContext): number {
+  let changed = 0
+
+  root
+    .find(j.ImportDeclaration)
+    .filter((path) =>
+      String(path.node.source.value ?? '').startsWith('@carto/meridian-ds'),
+    )
+    .forEach((path) => {
+      const hit = (path.node.specifiers ?? []).some(
+        (specifier) =>
+          specifier.type === 'ImportSpecifier' &&
+          REMOVED_WIDGET_NAMES.has(nameOf(specifier.imported)),
+      )
+      if (!hit) return
+
+      if (
+        annotate(
+          j,
+          path,
+          'Meridian 4.0.0 removed the Builder chart widgets and their prop types. Use `@carto/ps-react-ui`, Meridian `./charts`, or declare the shape locally.',
+        )
+      ) {
+        changed += 1
+      }
+    })
+
+  return changed
+}

package/src/migration/v4/transforms/ps-react-ui.ts

@@ -0,0 +1,99 @@
+/**
+ * `@carto/ps-react-ui` rewrites for the major that ships Material UI v9.
+ *
+ * Not a Material UI jump: the library itself removed widgets v1 and moved
+ * widgets v2 onto the `widgets` paths v1 used to occupy.
+ */
+import { WIDGETS_V1_ONLY } from '../widgets-v1'
+import type { ASTPath } from 'jscodeshift'
+import { annotate, nameOf, stringValue, type RuleContext } from './helpers'
+
+const V2 = '@carto/ps-react-ui/widgets-v2'
+const WIDGETS = '@carto/ps-react-ui/widgets'
+
+/** The specifier, if it is `…/widgets-v2` or one of its subpaths. */
+function renamedV2(specifier: string): string | undefined {
+  if (specifier !== V2 && !specifier.startsWith(`${V2}/`)) return undefined
+  return WIDGETS + specifier.slice(V2.length)
+}
+
+function isWidgetsPath(specifier: string | undefined): boolean {
+  return (
+    specifier !== undefined &&
+    (specifier === WIDGETS || specifier.startsWith(`${WIDGETS}/`))
+  )
+}
+
+/**
+ * `@carto/ps-react-ui/widgets-v2/*` → `@carto/ps-react-ui/widgets/*`.
+ *
+ * Every string literal, not only import sources: `vi.mock(…)`, `import(…)`
+ * and `export … from` carry the same specifier, and a mock left on the old
+ * path silently stops mocking anything.
+ */
+export function widgetsV2Path({ j, root }: RuleContext): number {
+  let changed = 0
+
+  root.find(j.StringLiteral).forEach((path) => {
+    const renamed = renamedV2(path.node.value)
+    if (renamed === undefined) return
+    path.node.value = renamed
+    changed += 1
+  })
+
+  return changed
+}
+
+/** The same rename in stylesheets and docs, whose snippets people copy. */
+export function widgetsV2PathText(source: string): string {
+  return source.replace(/@carto\/ps-react-ui\/widgets-v2(?![\w-])/g, WIDGETS)
+}
+
+/**
+ * Flags imports of names only widgets v1 exported.
+ *
+ * No rewrite: v1 and v2 differ in shape (config objects against composers,
+ * one global store against one store per widget), and the mapping is the v1
+ * → v2 migration guide, not a table. The widgets paths still resolve after
+ * the upgrade, so without this the only signal is `has no exported member`.
+ */
+export function widgetsV1Removed({ j, root }: RuleContext): number {
+  let changed = 0
+
+  const flag = (path: ASTPath, names: string[]) => {
+    const removed = names.filter((name) => WIDGETS_V1_ONLY.has(name))
+    if (removed.length === 0) return
+    const message = `Widgets v1 is removed and \`${removed.join('`, `')}\` ${removed.length === 1 ? 'has' : 'have'} no v2 export. Migrate this widget with the v1 → v2 guide (react-ui/widgets/migration-v1-to-v2).`
+    if (annotate(j, path, message)) changed += 1
+  }
+
+  // The name asked of the module: `imported` on an import, `local` on a
+  // re-export. Default and namespace imports name nothing in the module.
+  root
+    .find(j.ImportDeclaration)
+    .filter((path) => isWidgetsPath(stringValue(path.node.source)))
+    .forEach((path) => {
+      flag(
+        path,
+        (path.node.specifiers ?? []).flatMap((specifier) =>
+          specifier.type === 'ImportSpecifier'
+            ? [nameOf(specifier.imported)]
+            : [],
+        ),
+      )
+    })
+
+  root
+    .find(j.ExportNamedDeclaration)
+    .filter((path) => isWidgetsPath(stringValue(path.node.source)))
+    .forEach((path) => {
+      flag(
+        path,
+        (path.node.specifiers ?? []).flatMap((specifier) =>
+          specifier.type === 'ExportSpecifier' ? [nameOf(specifier.local)] : [],
+        ),
+      )
+    })
+
+  return changed
+}