@carto/ps-react-ui 5.3.0 → 6.1.0

package/src/migration/v4/migration.test.ts

@@ -0,0 +1,772 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import jscodeshift from 'jscodeshift'
+import type { API, Options } from 'jscodeshift'
+import { RULES, JUMPS, jumpsFor } from './rules'
+import { REMOVED_OUTLINE_ICONS, replacementFor } from './icons'
+import { consolidateClassName, consolidateSelectors } from './classes'
+import transform from './transform'
+
+const DOCS = join(import.meta.dirname, '../../../../../docs/migration')
+
+const j = jscodeshift.withParser('tsx')
+
+/** jscodeshift's stats and report only matter to its CLI output. */
+const noop = (): void => undefined
+
+const api = {
+  jscodeshift: j,
+  j,
+  stats: noop,
+  report: noop,
+} as unknown as API
+
+/** Runs the codemod the way jscodeshift would, and returns what it printed. */
+function run(
+  source: string,
+  options: Options = {},
+  path = 'src/component.tsx',
+): string {
+  return transform({ path, source }, api, options) ?? source
+}
+
+describe('rule set', () => {
+  it('has unique ids', () => {
+    const ids = RULES.map((rule) => rule.id)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it('gives every rule something to do', () => {
+    // A rule with neither an `apply` nor an `applyText` would be documented
+    // and then silently skipped — the failure mode this codemod replaced.
+    for (const rule of RULES) {
+      expect(rule.apply ?? rule.applyText, rule.id).toBeDefined()
+    }
+  })
+
+  it('says what it does about every rule', () => {
+    // The `action` is what a reader sees next to a rule id in a diff or in
+    // the exported data, so an empty one makes the rule undocumented in
+    // practice even though the guide covers its jump.
+    for (const rule of RULES) {
+      expect(rule.action.length, rule.id).toBeGreaterThan(20)
+    }
+  })
+
+  it('covers every jump in the guide', () => {
+    const guide = readFileSync(join(DOCS, 'mui-9-meridian-5.md'), 'utf8')
+    for (const heading of [
+      'Jump 1 — Material UI v5 → v6',
+      'Jump 2 — Material UI v6 → v7',
+      'Jump 3 — Material UI v7 → v9',
+      'Jump 4 — Meridian 2.14 → 5.1.1',
+      'Jump 5 — `@carto/ps-react-ui` widgets v1 is removed',
+    ]) {
+      expect(guide).toContain(heading)
+    }
+  })
+
+  it('runs the Grid rules in an order that composes', () => {
+    // `grid-legacy` renames the element so `grid-item-prop` can convert its
+    // props; the other order leaves a migrated name with v1 props.
+    const ids = RULES.filter((rule) => rule.jump === 'v6-v7').map(
+      (rule) => rule.id,
+    )
+    expect(ids.indexOf('grid-legacy')).toBeLessThan(
+      ids.indexOf('grid-item-prop'),
+    )
+  })
+})
+
+describe('jumpsFor', () => {
+  it('routes a v5 + Meridian 2 codebase through every jump', () => {
+    expect(jumpsFor(5, 2)).toEqual([
+      'v5-v6',
+      'v6-v7',
+      'v7-v9',
+      'meridian-5',
+      'ps-react-ui',
+    ])
+  })
+
+  it('skips the jumps already done', () => {
+    expect(jumpsFor(7, 2)).toEqual(['v7-v9', 'meridian-5', 'ps-react-ui'])
+    expect(jumpsFor(9, 2)).toEqual(['meridian-5', 'ps-react-ui'])
+  })
+
+  // The widgets move ships in the same major, whatever MUI the app is on.
+  it('leaves only the ps-react-ui jump once on v9 + Meridian 5', () => {
+    expect(jumpsFor(9, 5)).toEqual(['ps-react-ui'])
+  })
+
+  // There is no @mui/material v8; 7 upgrades straight to 9.
+  it('does not invent a v8 step', () => {
+    expect(jumpsFor(7, 5)).toEqual(['v7-v9', 'ps-react-ui'])
+  })
+})
+
+describe('the transform entry point', () => {
+  it('leaves a file it did not change completely alone', () => {
+    // This is what keeps the codemod from having the defect it documents in
+    // MUI's: recast reprints whatever it prints, and a run that prints every
+    // file it parsed buries its real changes in added semicolons.
+    const source = 'const a = 1\nexport default a\n'
+    expect(transform({ path: 'src/a.ts', source }, api, {})).toBeUndefined()
+  })
+
+  it('runs only the requested jump', () => {
+    const source = "<Typography color='text.secondary' />"
+    expect(run(source, { jump: 'v5-v6' })).toBe(source)
+    expect(run(source, { jump: 'v7-v9' })).toContain('sx=')
+  })
+
+  it('rejects a jump that does not exist', () => {
+    expect(() => run('const a = 1', { jump: 'v7-v8' })).toThrow(/Unknown jump/)
+  })
+
+  it('rewrites a stylesheet it cannot parse', () => {
+    const css = '.MuiButton-textPrimary { color: red; }'
+    expect(run(css, {}, 'src/app.css')).toBe(
+      '.MuiButton-text.MuiButton-colorPrimary { color: red; }',
+    )
+  })
+
+  it('rewrites the icons in documentation, which no codemod touches', () => {
+    const mdx = "import { ErrorOutline } from '@mui/icons-material'"
+    expect(run(mdx, {}, 'docs/icons.mdx')).toContain('ErrorOutlineOutlined')
+  })
+})
+
+describe('jump 1 — v5 to v6', () => {
+  it('turns a ListItem with removed props into a ListItemButton', () => {
+    const output = run(
+      [
+        "import { ListItem } from '@mui/material'",
+        'const A = () => <ListItem button selected>x</ListItem>',
+      ].join('\n'),
+      { jump: 'v5-v6' },
+    )
+    expect(output).toContain('<ListItemButton selected>')
+    expect(output).toContain('</ListItemButton>')
+    expect(output).toContain('ListItemButton')
+    expect(output).not.toContain('<ListItem ')
+  })
+
+  it("moves Typography's color callback into sx and leaves the dot path", () => {
+    const callback = run(
+      '<Typography color={(theme) => theme.palette.text.secondary} />',
+      { jump: 'v5-v6' },
+    )
+    expect(callback).toContain('sx={{')
+    expect(callback).toContain('color: (theme) => theme.palette.text.secondary')
+
+    // The dot-path spelling survives until v9; touching it here would be a
+    // change the reader cannot explain at this jump.
+    const dotPath = "<Typography color='text.secondary' />"
+    expect(run(dotPath, { jump: 'v5-v6' })).toBe(dotPath)
+  })
+
+  it('rewrites an hr query a vertical Divider no longer answers', () => {
+    const output = run(
+      "expect(container.querySelectorAll('hr')).toHaveLength(2)",
+      { jump: 'v5-v6' },
+    )
+    expect(output).toContain(".querySelectorAll('.MuiDivider-root')")
+  })
+})
+
+describe('jump 2 — v6 to v7', () => {
+  it('converts Grid breakpoints into size', () => {
+    const output = run('<Grid container><Grid item xs={12} md={8} /></Grid>', {
+      jump: 'v6-v7',
+    })
+    expect(output).toContain('size={{')
+    expect(output).toContain('xs: 12')
+    expect(output).toContain('md: 8')
+    expect(output).not.toContain('item')
+  })
+
+  it('collapses a single breakpoint instead of writing an object', () => {
+    expect(run('<Grid item xs={8} />', { jump: 'v6-v7' })).toContain('size={8}')
+  })
+
+  it('reads a bare breakpoint as the v7 grow', () => {
+    expect(run('<Grid item xs />', { jump: 'v6-v7' })).toContain(
+      "size={'grow'}",
+    )
+  })
+
+  it('renames GridLegacy and migrates its props in the same run', () => {
+    const output = run(
+      [
+        "import { GridLegacy } from '@mui/material'",
+        'const A = () => <GridLegacy item xs={6} />',
+      ].join('\n'),
+      { jump: 'v6-v7' },
+    )
+    expect(output).not.toContain('GridLegacy')
+    expect(output).toContain('size={6}')
+  })
+
+  it('flags a Grid container that sets no width of its own', () => {
+    const output = run('<Grid container spacing={2} />', { jump: 'v6-v7' })
+    expect(output).toContain('TODO(mui9)')
+    expect(output).toContain('shrinks to its content')
+  })
+
+  it('leaves a Grid container that already sets a width alone', () => {
+    const output = run("<Grid container sx={{ width: '100%' }} />", {
+      jump: 'v6-v7',
+    })
+    expect(output).not.toContain('TODO(mui9)')
+  })
+
+  it('sends a named deep import to the package root, and renames Variant', () => {
+    const output = run(
+      "import type { Variant } from '@mui/material/styles/createTypography'",
+      { jump: 'v6-v7' },
+    )
+    expect(output).toContain("from '@mui/material'")
+    expect(output).toContain('TypographyVariant')
+  })
+
+  it('keeps a default deep import on its own entry point', () => {
+    // `@mui/material` has no default export to take `Box` from.
+    const output = run("import Box from '@mui/material/Box/Box'", {
+      jump: 'v6-v7',
+    })
+    expect(output).toContain("from '@mui/material/Box'")
+  })
+
+  it('does not strand a named type on a component entry point', () => {
+    // `@mui/material/TablePagination` does not re-export this; the root does.
+    const output = run(
+      "import type { TablePaginationActionsProps } from '@mui/material/TablePagination/TablePaginationActions'",
+      { jump: 'v6-v7' },
+    )
+    expect(output).toContain("from '@mui/material'")
+  })
+
+  it('moves the graduated lab imports to core and leaves Timeline behind', () => {
+    const output = run("import { Alert, Timeline } from '@mui/lab'", {
+      jump: 'v6-v7',
+    })
+    expect(output).toMatch(/import \{\s*Alert\s*\} from '@mui\/material'/)
+    expect(output).toMatch(/Timeline.*from '@mui\/lab'/)
+  })
+
+  it('keeps a lab import type-only when it was type-only', () => {
+    // Landing `import type { AlertProps }` as a value import creates a
+    // runtime binding for something that only exists in the type system.
+    const output = run("import type { AlertProps } from '@mui/lab'", {
+      jump: 'v6-v7',
+    })
+    expect(output).toMatch(
+      /import type \{[^}]*AlertProps[^}]*\} from '@mui\/material'/,
+    )
+  })
+
+  it('removes both spellings of the dead Slider narrowing', () => {
+    const cast = run('<Slider onChange={(_, v) => setWidth(v as number)} />', {
+      jump: 'v6-v7',
+    })
+    expect(cast).toContain('setWidth(v)')
+
+    const guard = run(
+      '<Slider onChange={(_, v) => setWidth(Array.isArray(v) ? v[0]! : v)} />',
+      { jump: 'v6-v7' },
+    )
+    expect(guard).toContain('setWidth(v)')
+  })
+})
+
+describe('jump 3 — v7 to v9', () => {
+  it('moves system props into sx', () => {
+    const output = run("<Box display='flex' mt={2} />", { jump: 'v7-v9' })
+    expect(output).toContain('sx={{')
+    expect(output).toContain("display: 'flex'")
+    expect(output).toContain('mt: 2')
+  })
+
+  it('merges into an sx that is already there without overwriting it', () => {
+    const output = run("<Box display='flex' sx={{ mt: 4 }} />", {
+      jump: 'v7-v9',
+    })
+    expect(output).toContain('mt: 4')
+    expect(output).toContain("display: 'flex'")
+  })
+
+  it('flags a palette path written into an inline style', () => {
+    const output = run("<div style={{ backgroundColor: 'primary.main' }} />", {
+      jump: 'v7-v9',
+    })
+    expect(output).toContain('TODO(mui9)')
+    expect(output).toContain('primary.main')
+    // Annotated, never rewritten: only the author knows whether the element
+    // should take `sx` instead or resolve the path before painting.
+    expect(output).toContain("style={{ backgroundColor: 'primary.main' }}")
+  })
+
+  it('leaves an inline style holding a real CSS colour alone', () => {
+    const source =
+      "<div style={{ backgroundColor: '#ff0000', color: color }} />"
+    expect(run(source, { jump: 'v7-v9' })).not.toContain('TODO(mui9)')
+  })
+
+  it('folds prop bags into slotProps', () => {
+    const output = run('<Dialog PaperProps={{ elevation: 0 }} />', {
+      jump: 'v7-v9',
+    })
+    expect(output).toContain('slotProps={{')
+    expect(output).toContain('paper:')
+    expect(output).not.toContain('PaperProps')
+  })
+
+  it('renames inputProps to the htmlInput slot, not to input', () => {
+    // The two are different slots and the names invite the wrong mapping.
+    const output = run('<TextField inputProps={{ maxLength: 3 }} />', {
+      jump: 'v7-v9',
+    })
+    expect(output).toContain('htmlInput:')
+  })
+
+  it('renames components and componentsProps', () => {
+    const output = run(
+      '<Badge components={{ Root: R }} componentsProps={{}} />',
+      {
+        jump: 'v7-v9',
+      },
+    )
+    expect(output).toContain('slots={{')
+    expect(output).toContain('slotProps={{}}')
+  })
+
+  it('moves a dot-path color into sx and leaves the component prop alone', () => {
+    expect(run("<Chip color='text.secondary' />", { jump: 'v7-v9' })).toContain(
+      'sx=',
+    )
+    const ownProp = "<Chip color='primary' />"
+    expect(run(ownProp, { jump: 'v7-v9' })).toBe(ownProp)
+  })
+
+  it('removes disableEscapeKeyDown, and says so where behaviour changes', () => {
+    const silent = run('<Popover disableEscapeKeyDown />', { jump: 'v7-v9' })
+    expect(silent).not.toContain('disableEscapeKeyDown')
+    expect(silent).not.toContain('TODO(mui9)')
+
+    const behavioural = run('<Dialog disableEscapeKeyDown onClose={close} />', {
+      jump: 'v7-v9',
+    })
+    expect(behavioural).not.toContain('disableEscapeKeyDown')
+    expect(behavioural).toContain('escapeKeyDown')
+  })
+
+  it('writes a file whose only change is an annotation', () => {
+    // A rule that cannot rewrite falls back to a comment. If that fallback
+    // does not count as a change, `transform` returns undefined and the
+    // comment is dropped on the floor — the rule reports nothing and the
+    // breakage ships. One case per fallback:
+    const fallbacks = [
+      "<Typography fontWeight='medium' sx={styles.noWrap}>hi</Typography>",
+      '<Dialog PaperProps={{ elevation: 0 }} slotProps={other} />',
+      "<Chip color='text.secondary' sx={styles.chip} />",
+    ]
+
+    for (const source of fallbacks) {
+      expect(run(source, { jump: 'v7-v9' })).toContain('TODO(mui9)')
+    }
+
+    expect(
+      run('<Typography color={(t) => t.palette.error.main} sx={styles.x} />', {
+        jump: 'v5-v6',
+      }),
+    ).toContain('TODO(mui9)')
+  })
+
+  it('leaves a lookalike prop bag on a third-party component alone', () => {
+    const source = [
+      "import { LassoToolsUI } from '@carto/ps-react-ui'",
+      '<LassoToolsUI PaperProps={{ elevation: 0 }} />',
+    ].join('\n')
+    const output = run(source, { jump: 'v7-v9' })
+    expect(output).toContain('PaperProps=')
+    expect(output).not.toContain('slotProps')
+    expect(output).not.toContain('TODO(mui9)')
+  })
+
+  it('flags a slot rewrite that landed off Material UI', () => {
+    const thirdParty = [
+      "import { LassoToolsUI } from '@carto/ps-react-ui'",
+      '<LassoToolsUI slotProps={{ paper: { elevation: 0 } }} />',
+    ].join('\n')
+    const flagged = run(thirdParty, { jump: 'v7-v9' })
+    expect(flagged).toContain('TODO(mui9)')
+    expect(flagged).toContain('@carto/ps-react-ui')
+
+    // The same prop on a real MUI component is the rewrite working.
+    const mui = [
+      "import { Dialog } from '@mui/material'",
+      '<Dialog slotProps={{ paper: { elevation: 0 } }} />',
+    ].join('\n')
+    expect(run(mui, { jump: 'v7-v9' })).not.toContain('TODO(mui9)')
+
+    // A locally defined component is the author's on both sides.
+    const local = [
+      "import { Panel } from './panel'",
+      '<Panel slotProps={{ paper: {} }} />',
+    ].join('\n')
+    expect(run(local, { jump: 'v7-v9' })).toContain('TODO(mui9)')
+  })
+
+  it('turns TablePagination slots.actions back into ActionsComponent', () => {
+    const output = run('<TablePagination slots={{ actions: Actions }} />', {
+      jump: 'v7-v9',
+    })
+    expect(output).toContain('ActionsComponent={Actions}')
+    expect(output).not.toContain('slots=')
+  })
+
+  it('renames the Autocomplete tag renderer and its component props', () => {
+    const output = run(
+      '<Autocomplete renderTags={render} PaperComponent={P} />',
+      { jump: 'v7-v9' },
+    )
+    expect(output).toContain('renderValue=')
+    expect(output).toContain('paper: P')
+  })
+
+  it('splits a consolidated class name in a selector', () => {
+    const output = run(
+      "const S = styled(Box)({ '& .MuiButton-textPrimary': { color: 'red' } })",
+      { jump: 'v7-v9' },
+    )
+    expect(output).toContain('.MuiButton-text.MuiButton-colorPrimary')
+  })
+
+  it('flags a styled() wrapper aimed at MUI internals', () => {
+    const output = run(
+      "const S = styled(Box)({ '& .MuiListItemIcon-root': { minWidth: 56 } })",
+      { jump: 'v7-v9' },
+    )
+    expect(output).toContain('TODO(mui9)')
+  })
+
+  it('does not flag a styled() wrapper that owns all its selectors', () => {
+    const output = run("const S = styled(Box)({ color: 'red' })", {
+      jump: 'v7-v9',
+    })
+    expect(output).not.toContain('TODO(mui9)')
+  })
+
+  it('renames a removed icon to the one with identical path data', () => {
+    const output = run(
+      "import { ErrorOutline } from '@mui/icons-material'\nconst A = () => <ErrorOutline />",
+      { jump: 'v7-v9' },
+    )
+    expect(output).toContain('ErrorOutlineOutlined')
+    // NOT `ErrorOutlined`, which compiles and draws a filled circle.
+    expect(output).not.toMatch(/\bErrorOutlined\b/)
+  })
+
+  it('renames the data-testid that goes with the icon', () => {
+    expect(
+      run("screen.getByTestId('DeleteOutlineIcon')", { jump: 'v7-v9' }),
+    ).toContain('DeleteOutlineOutlinedIcon')
+  })
+
+  it('flags a removed icon that has no equivalent instead of guessing', () => {
+    const output = run("import { PeopleOutline } from '@mui/icons-material'", {
+      jump: 'v7-v9',
+    })
+    expect(output).toContain('TODO(mui9)')
+    expect(output).toContain('PeopleOutline')
+  })
+
+  it('asks about a name that looks like a naive rename', () => {
+    const output = run("import { ErrorOutlined } from '@mui/icons-material'", {
+      jump: 'v7-v9',
+    })
+    expect(output).toContain('TODO(mui9)')
+    expect(output).toContain('is NOT ErrorOutline')
+  })
+
+  it('turns a role attribute selector into a role query', () => {
+    expect(
+      run('page.locator(\'[role="button"]\')', { jump: 'v7-v9' }),
+    ).toContain("getByRole('button')")
+  })
+
+  it('flags a MenuItem mounted bare in a test', () => {
+    const bare = run('render(<MenuItem />)', { jump: 'v7-v9' })
+    expect(bare).toContain('TODO(mui9)')
+
+    const wrapped = run('render(<MenuList><MenuItem /></MenuList>)', {
+      jump: 'v7-v9',
+    })
+    expect(wrapped).not.toContain('TODO(mui9)')
+  })
+})
+
+describe('jump 4 — Meridian 5', () => {
+  it('reads the exported theme and drops the cast', () => {
+    const output = run(
+      [
+        "import { cartoThemeOptions } from '@carto/meridian-ds/theme'",
+        'const t = cartoThemeOptions as unknown as Theme',
+      ].join('\n'),
+      { jump: 'meridian-5' },
+    )
+    expect(output).toContain('theme')
+    expect(output).not.toContain('cartoThemeOptions')
+    expect(output).not.toContain('as unknown as')
+  })
+
+  it('aliases the import when the file already binds `theme`', () => {
+    // A consumer that re-exports its own `theme` is the normal case, so the
+    // import has to come in under another name and every reference has to
+    // follow it.
+    const output = run(
+      [
+        "import { cartoThemeOptions } from '@carto/meridian-ds/theme'",
+        'export const theme = createTheme(cartoThemeOptions as ThemeOptions)',
+      ].join('\n'),
+      { jump: 'meridian-5' },
+    )
+    expect(output).toContain('theme as cartoTheme')
+    expect(output).toContain('cartoTheme as ThemeOptions')
+    expect(output).toContain('export const theme =')
+  })
+
+  it('drops the `Theme` import the removed cast was the only user of', () => {
+    const output = run(
+      [
+        "import { createTheme, type Theme } from '@mui/material'",
+        "import { cartoThemeOptions } from '@carto/meridian-ds/theme'",
+        'const t = createTheme(cartoThemeOptions as unknown as Theme)',
+      ].join('\n'),
+      { jump: 'meridian-5' },
+    )
+    expect(output).not.toMatch(/type Theme/)
+    expect(output).toContain('createTheme')
+  })
+
+  it('keeps `Theme` when something else still uses it', () => {
+    const output = run(
+      [
+        "import { type Theme } from '@mui/material'",
+        "import { cartoThemeOptions } from '@carto/meridian-ds/theme'",
+        'const t = cartoThemeOptions as unknown as Theme',
+        'export function use(x: Theme): Theme { return x }',
+      ].join('\n'),
+      { jump: 'meridian-5' },
+    )
+    expect(output).toContain('Theme')
+  })
+
+  it('renames the Meridian 3 API', () => {
+    expect(
+      run("import { AiTool } from '@carto/meridian-ds'", {
+        jump: 'meridian-5',
+      }),
+    ).toContain('McpTool')
+  })
+
+  it('flags a removed widget only when it comes from Meridian', () => {
+    const fromMeridian = run(
+      "import { PieWidgetUI } from '@carto/meridian-ds'",
+      { jump: 'meridian-5' },
+    )
+    expect(fromMeridian).toContain('TODO(mui9)')
+
+    const ownComponent = "import { PieWidgetUI } from './widgets'"
+    expect(run(ownComponent, { jump: 'meridian-5' })).toBe(ownComponent)
+  })
+})
+
+describe('ps-react-ui', () => {
+  const jump = 'ps-react-ui'
+
+  it('moves every widgets-v2 specifier, mocks and dynamic imports too', () => {
+    const output = run(
+      [
+        "import { Widget } from '@carto/ps-react-ui/widgets-v2'",
+        "import { BarSkeleton } from '@carto/ps-react-ui/widgets-v2/bar'",
+        "vi.mock('@carto/ps-react-ui/widgets-v2/stores')",
+        "const pie = () => import('@carto/ps-react-ui/widgets-v2/pie')",
+      ].join('\n'),
+      { jump },
+    )
+    expect(output).not.toContain('widgets-v2')
+    expect(output).toContain("from '@carto/ps-react-ui/widgets'")
+    expect(output).toContain("from '@carto/ps-react-ui/widgets/bar'")
+    expect(output).toContain("vi.mock('@carto/ps-react-ui/widgets/stores')")
+    expect(output).toContain("import('@carto/ps-react-ui/widgets/pie')")
+  })
+
+  it('moves the specifier in docs as well', () => {
+    const mdx =
+      "```tsx\nimport { Widget } from '@carto/ps-react-ui/widgets-v2'\n```"
+    expect(run(mdx, { jump }, 'docs/widgets.mdx')).toBe(
+      "```tsx\nimport { Widget } from '@carto/ps-react-ui/widgets'\n```",
+    )
+  })
+
+  it('flags a name only v1 exported, and says which', () => {
+    const output = run(
+      "import { barConfig, BarSkeleton } from '@carto/ps-react-ui/widgets/bar'",
+      { jump },
+    )
+    expect(output).toMatch(/TODO\(mui9\).*`barConfig`/)
+    expect(output).not.toMatch(/TODO\(mui9\).*BarSkeleton/)
+  })
+
+  it('flags a v1 re-export too', () => {
+    const output = run(
+      "export { WidgetWrapper } from '@carto/ps-react-ui/widgets'",
+      { jump },
+    )
+    expect(output).toContain('TODO(mui9)')
+  })
+
+  it('leaves v2 imports alone, before and after the rename', () => {
+    // A second run sees v2 on the `widgets` paths; flagging it there would
+    // bury the real v1 leftovers.
+    const v2 = "import { Widget } from '@carto/ps-react-ui/widgets-v2'"
+    const once = run(v2, { jump })
+    expect(once).not.toContain('TODO')
+    expect(run(once, { jump })).toBe(once)
+  })
+
+  it('ignores the same names from any other module', () => {
+    const own = "import { WidgetWrapper } from './widgets'"
+    expect(run(own, { jump })).toBe(own)
+  })
+})
+
+describe('annotations', () => {
+  const STYLED =
+    "export const S = styled(Box)({ '& .MuiListItemIcon-root': { minWidth: 56 } })"
+
+  it('comments above the export, not between export and const', () => {
+    const output = run(STYLED, { jump: 'v7-v9' })
+    expect(output).toMatch(/TODO\(mui9\)[\s\S]*export const S/)
+    expect(output).not.toMatch(/export\s*\/\/ TODO/)
+  })
+
+  it('does not stack a second comment on a second run', () => {
+    // The codemod is run again after a jump is fixed up, and an annotation
+    // that re-anchors on a different node each time multiplies.
+    const once = run(STYLED, { jump: 'v7-v9' })
+    const twice = run(once, { jump: 'v7-v9' })
+    expect(twice).toBe(once)
+    expect(once.match(/TODO\(mui9\)/g)).toHaveLength(1)
+  })
+})
+
+describe('names that collide with Object.prototype', () => {
+  // Every lookup table here is keyed by a name read out of the source. A
+  // plain object indexed that way answers for `toString`, `valueOf`,
+  // `constructor` and friends with whatever `Object.prototype` holds — and
+  // the function it returns is truthy, so a rename rule accepted it and
+  // printed its source into the file. `value.toString()` came out as
+  // `value.function toString() { [native code] }()`, which does not parse.
+  const COLLIDING = [
+    'toString',
+    'valueOf',
+    'constructor',
+    'hasOwnProperty',
+    'propertyIsEnumerable',
+  ]
+
+  it('leaves them alone at every jump', () => {
+    for (const name of COLLIDING) {
+      for (const jump of JUMPS) {
+        const source = `const a = value.${name}()`
+        expect(run(source, { jump }), `${name} at ${jump}`).toBe(source)
+      }
+    }
+  })
+
+  it('reports no replacement for one in the icon table', () => {
+    for (const name of COLLIDING) {
+      expect(replacementFor(name), name).toBeUndefined()
+    }
+  })
+})
+
+describe('class consolidation', () => {
+  it('splits a compound class into slot plus modifier', () => {
+    expect(consolidateClassName('MuiButton-textPrimary')).toEqual([
+      'MuiButton-text',
+      'MuiButton-colorPrimary',
+    ])
+    expect(consolidateClassName('MuiChip-labelSmall')).toEqual([
+      'MuiChip-label',
+      'MuiChip-sizeSmall',
+    ])
+  })
+
+  it('handles both spellings of the size modifier', () => {
+    // `textSizeSmall` on Button, plain `labelSmall` on Chip.
+    expect(consolidateClassName('MuiButton-textSizeSmall')).toEqual([
+      'MuiButton-text',
+      'MuiButton-sizeSmall',
+    ])
+  })
+
+  it('leaves a class that is already a v9 one alone', () => {
+    // These are the RESULT of the consolidation; splitting them again would
+    // produce `MuiButton-color`, which does not exist.
+    expect(consolidateClassName('MuiButton-colorPrimary')).toBeNull()
+    expect(consolidateClassName('MuiChip-sizeSmall')).toBeNull()
+    expect(consolidateClassName('MuiButton-root')).toBeNull()
+  })
+
+  it('keeps the separator a selector needs and a class list needs', () => {
+    expect(consolidateSelectors('.MuiButton-textPrimary')).toBe(
+      '.MuiButton-text.MuiButton-colorPrimary',
+    )
+    expect(consolidateSelectors('MuiButton-textPrimary')).toBe(
+      'MuiButton-text MuiButton-colorPrimary',
+    )
+  })
+})
+
+describe('the removed icon table', () => {
+  it('appends Outlined to the whole name, never swapping the suffix', () => {
+    for (const [removed, replacement] of Object.entries(
+      REMOVED_OUTLINE_ICONS,
+    )) {
+      if (replacement === null) continue
+      expect(replacement, removed).toBe(`${removed}Outlined`)
+    }
+  })
+
+  it('admits the four glyphs v9 has no equivalent for', () => {
+    const missing = Object.entries(REMOVED_OUTLINE_ICONS)
+      .filter(([, replacement]) => replacement === null)
+      .map(([name]) => name)
+    expect(missing).toEqual([
+      'CheckCircleOutline',
+      'DoneOutline',
+      'ModeEditOutline',
+      'PeopleOutline',
+    ])
+  })
+
+  it('covers all 17 removed icons', () => {
+    expect(Object.keys(REMOVED_OUTLINE_ICONS)).toHaveLength(17)
+  })
+})
+
+describe('the jump list', () => {
+  it('has a rule for every jump', () => {
+    for (const jump of JUMPS) {
+      expect(
+        RULES.some((rule) => rule.jump === jump),
+        jump,
+      ).toBe(true)
+    }
+  })
+})