@epilot/zenith-react 0.2.0-next.3 → 0.2.0-next.4

package/codemods/migrate/lib/run-migration.ts

@@ -0,0 +1,528 @@
+/**
+ * The entry algorithm shared by `from-volt.ts` and `from-base-elements.ts`:
+ *
+ * 1. Find what the file imports from the legacy package (named imports, aliases resolved).
+ * 2. Run every registry rule that handles at least one of those names (or an imported module).
+ * 3. Rebuild the imports from the rules' decisions: moved names go onto the Zenith import, kept
+ *    names stay on the legacy import with a TODO, names no rule claimed are kept with a generic
+ *    TODO, dropped names vanish, and a default or namespace import is kept with a TODO.
+ * 4. Report every TODO as `<line> <Component>: <message>` and return the new source when the
+ *    file changed.
+ */
+import type {
+  API,
+  ASTPath,
+  Collection,
+  FileInfo,
+  JSCodeshift,
+  ImportDeclaration,
+  ImportSpecifier,
+  Options,
+} from "jscodeshift"
+import {
+  addToZenithImport,
+  hoistLeadingComments,
+  importedNames,
+  isBoundAnywhere,
+  isFirstStatementAfterDirective,
+  programIfFirstStatement,
+  referenceSeesBinding,
+  isTopLevelBound,
+  localNames,
+  renameBinding,
+  valueUses,
+  type ImportedName,
+  type Moved,
+} from "./imports"
+import { makeJsxHelpers } from "./jsx"
+import { detectQuote } from "./source"
+import { attachTodoComment, formatReport, formatTodo, lineOf } from "./todo"
+import {
+  ZENITH,
+  type MigrateContext,
+  type MigrationRule,
+  type TodoEntry,
+} from "./types"
+
+export type MigrationOptions = {
+  file: FileInfo
+  api: API
+  options: Options
+  /** The legacy package, e.g. `@epilot/base-elements`. */
+  source: string
+  rules: readonly MigrationRule[]
+  /** Message for a name no rule handles. Receives the name. */
+  unhandled?: (name: string) => string
+}
+
+export function runMigration({
+  file,
+  api,
+  options,
+  source,
+  rules,
+  unhandled = () =>
+    `no Zenith rule; still imported from ${source} (migrate by hand or drop)`,
+}: MigrationOptions): string | undefined {
+  void options
+  const j = api.jscodeshift
+  const root = j(file.source)
+  const quote = detectQuote(file.source)
+  const jsx = makeJsxHelpers(j)
+
+  const legacyImports = root.find(j.ImportDeclaration).filter((p) => {
+    const value = String(p.node.source.value)
+    return value === source || value.startsWith(`${source}/`)
+  })
+  const rulesByModule = new Map<string, MigrationRule>()
+  for (const rule of rules)
+    for (const m of rule.handlesModules ?? []) rulesByModule.set(m, rule)
+  const importsModule = (m: string) =>
+    root.find(j.ImportDeclaration, { source: { value: m } }).size() > 0
+  const hasRuleWork = rules.some((r) =>
+    (r.handlesModules ?? []).some(importsModule)
+  )
+  const otherReferences = findOtherReferences(j, root, source)
+  if (
+    legacyImports.size() === 0 &&
+    !hasRuleWork &&
+    otherReferences.length === 0
+  )
+    return undefined
+
+  const names = importedNames(j, root, source)
+  const byImported = new Map<string, ImportedName>()
+  for (const n of names) byImported.set(n.imported, n)
+  const ruleByName = new Map<string, MigrationRule>()
+  for (const rule of rules) {
+    for (const name of rule.handles) {
+      if (ruleByName.has(name))
+        throw new Error(`migrate: two rules handle ${name} for ${source}`)
+      ruleByName.set(name, rule)
+    }
+  }
+
+  const todos: TodoEntry[] = []
+  const moves = new Map<string, { module: string; target: string }>()
+  const keeps = new Map<string, string | undefined>()
+  const drops = new Set<string>()
+  const zenithNames = () => localNames(importedNames(j, root, ZENITH))
+  const removedDeclarations = new Set<ImportDeclaration>()
+
+  const ctx: MigrateContext = {
+    j,
+    root,
+    file,
+    source,
+    names: localNames(names),
+    get zenith() {
+      return zenithNames()
+    },
+    jsx,
+    move(name, target = name) {
+      ctx.moveTo(ZENITH, name, target)
+    },
+    moveTo(module, name, target = name) {
+      if (!byImported.has(name)) return
+      keeps.delete(name)
+      moves.set(name, { module, target })
+    },
+    keep(name, message) {
+      if (!byImported.has(name)) return
+      moves.delete(name)
+      keeps.set(name, message)
+    },
+    valueUses(name) {
+      const local = byImported.get(name)?.local
+      return local
+        ? valueUses(j, root, local)
+        : (root.find(j.Identifier, { name: "\0" }) as never)
+    },
+    moveElements(name, target = name) {
+      const entry = byImported.get(name)
+      if (!entry) return undefined
+      const uses = valueUses(j, root, entry.local)
+      if (uses.size() === 0) {
+        ctx.move(name, target)
+        return entry.local
+      }
+      const local = ctx.ensureZenith(target)
+      ctx.elements(name).forEach((path) => jsx.rename(path.node, local))
+      uses.forEach((path) => {
+        let statement = (j(path).closest(j.Statement).paths()[0] ??
+          path) as ASTPath
+        const parentType = String(statement.parent?.node.type ?? "")
+        if (/^Export(Named|Default)Declaration$/.test(parentType))
+          statement = statement.parent
+        ctx.todo(
+          statement,
+          name,
+          `${j(path.parent.node as never).toSource()}: ${name} is used as a value here, so it stays on ${source}; ${target} from Zenith has a different API, migrate this use by hand`
+        )
+      })
+      ctx.keep(name)
+      return local
+    },
+    drop(name) {
+      if (!byImported.has(name)) return
+      moves.delete(name)
+      keeps.delete(name)
+      drops.add(name)
+    },
+    todo(path, component, message) {
+      todos.push({ line: lineOf(path), component, message })
+      attachTodoComment(j, path, formatTodo(component, message))
+    },
+    ensureZenith(name) {
+      const existing = zenithNames()[name]
+      if (existing) return existing
+      // A legacy import of the same name that another rule already moved onto Zenith's `name`
+      // becomes that binding; otherwise the name is taken and the alias is merged by the
+      // post-pass below if the move comes later.
+      const movedToSelf =
+        moves.get(name)?.module === ZENITH && moves.get(name)?.target === name
+      const local =
+        (isBoundAnywhere(j, root, name) || byImported.has(name)) && !movedToSelf
+          ? `Zenith${name}`
+          : name
+      const anchor =
+        legacyImports.paths()[0] ?? root.find(j.ImportDeclaration).paths()[0]
+      if (anchor) {
+        const program = programIfFirstStatement(anchor)
+        const afterDirective = isFirstStatementAfterDirective(anchor)
+        const inserted = addToZenithImport(
+          j,
+          root,
+          ZENITH,
+          [{ imported: name, local, typeOnly: false }],
+          anchor,
+          quote
+        )
+        if (inserted.length && (program || afterDirective))
+          hoistLeadingComments(anchor.node, program ?? inserted[0])
+      } else {
+        root
+          .get()
+          .node.program.body.unshift(
+            j.importDeclaration(
+              [
+                j.importSpecifier(
+                  j.identifier(name),
+                  local === name ? null : j.identifier(local)
+                ),
+              ],
+              j.stringLiteral(ZENITH)
+            )
+          )
+      }
+      return local
+    },
+    elements(name) {
+      const local = byImported.get(name)?.local
+      return root
+        .find(j.JSXElement)
+        .filter((p) => !!local && jsx.tagName(p.node) === local) as never
+    },
+    imports(moduleSpecifier) {
+      return root.find(j.ImportDeclaration, {
+        source: { value: moduleSpecifier },
+      })
+    },
+    removeImport(path) {
+      removedDeclarations.add(path.node)
+      path.prune()
+    },
+  }
+
+  // 2. Rules.
+  const ran = new Set<MigrationRule>()
+  for (const rule of rules) {
+    const wanted =
+      rule.handles.some((n) => byImported.has(n)) ||
+      (rule.handlesModules ?? []).some(importsModule)
+    if (!wanted || ran.has(rule)) continue
+    ran.add(rule)
+    rule.migrate(ctx)
+  }
+
+  // 3. Imports.
+  for (const n of names) {
+    if (drops.has(n.imported)) continue
+    if (moves.has(n.imported) || keeps.has(n.imported)) continue
+    keeps.set(n.imported, unhandled(n.imported))
+  }
+
+  const declarations = root
+    .find(j.ImportDeclaration, { source: { value: source } })
+    .paths()
+  for (const declaration of declarations) {
+    if (removedDeclarations.has(declaration.node)) continue
+    const specifiers = declaration.node.specifiers ?? []
+    // The declaration's own comments, before any TODO is attached to it below.
+    const originalComments = [...(declaration.node.comments ?? [])]
+    const moved = new Map<string, Moved[]>()
+    const kept: typeof specifiers = []
+    for (const s of specifiers) {
+      if (s.type !== "ImportSpecifier") {
+        const kind =
+          s.type === "ImportDefaultSpecifier" ? "default" : "namespace"
+        const local = String(s.local?.name ?? "")
+        todos.push({
+          line: lineOf(declaration),
+          component: local,
+          message: `${kind} import of ${source}: import the named exports instead, then rerun`,
+        })
+        attachTodoComment(
+          j,
+          declaration,
+          formatTodo(
+            local,
+            `${kind} import of ${source}: import the named exports instead, then rerun`
+          )
+        )
+        kept.push(s)
+        continue
+      }
+      const entry = byImported.get(String(s.imported.name))!
+      if (drops.has(entry.imported)) continue
+      const move = moves.get(entry.imported)
+      if (move === undefined) {
+        kept.push(s)
+        const message = keeps.get(entry.imported)
+        if (message === undefined) continue
+        todos.push({
+          line: lineOf(declaration),
+          component: entry.imported,
+          message,
+        })
+        attachTodoComment(j, declaration, formatTodo(entry.imported, message))
+        continue
+      }
+      const { module, target } = move
+      const aliased = entry.local !== entry.imported
+      let local = entry.local
+      if (!aliased && target !== entry.local) {
+        // `target` is free when nothing binds it, when the module already imports it under its
+        // own name, or when the binding is a legacy specifier being moved to that same name (so
+        // after the rewrite both names are the one Zenith export).
+        const movedToSelf =
+          byImported.has(target) &&
+          moves.get(target)?.module === module &&
+          moves.get(target)?.target === target
+        const taken =
+          (isTopLevelBound(j, root, target) ||
+            referenceSeesBinding(j, root, entry.local, target)) &&
+          localNames(importedNames(j, root, module))[target] !== target &&
+          !movedToSelf
+        if (!taken) {
+          renameBinding(j, root, entry.local, target)
+          local = target
+        } else {
+          // Something in scope of a use is already called `target` (a prop, a local, another
+          // import): import under an alias so no use is captured.
+          const alias = `Zenith${target}`
+          if (
+            !isBoundAnywhere(j, root, alias) &&
+            !referenceSeesBinding(j, root, entry.local, alias)
+          ) {
+            renameBinding(j, root, entry.local, alias)
+            local = alias
+          }
+        }
+      }
+      const list = moved.get(module) ?? []
+      list.push({ imported: target, local, typeOnly: entry.typeOnly })
+      moved.set(module, list)
+    }
+    // Zenith first so it sits right above the legacy import; other modules follow it.
+    const modules = [...moved.keys()].sort((a, b) =>
+      a === ZENITH ? -1 : b === ZENITH ? 1 : a.localeCompare(b)
+    )
+    // Decided before the inserts below push the declaration down the body.
+    const program = programIfFirstStatement(declaration)
+    const afterDirective = isFirstStatementAfterDirective(declaration)
+    const inserted = modules.flatMap((module) =>
+      addToZenithImport(j, root, module, moved.get(module)!, declaration, quote)
+    )
+    if (program && (inserted.length || kept.length === 0)) {
+      // A file-leading comment stays at the top of the file.
+      hoistLeadingComments(declaration.node, program, originalComments)
+    } else if (afterDirective && inserted.length) {
+      // After `"use client"` the directive stays first; the comment heads the inserted import.
+      hoistLeadingComments(declaration.node, inserted[0], originalComments)
+    } else if (kept.length === 0) {
+      // A removed import's comments move to what now stands in its place.
+      const body = (declaration.parent.node as { body?: unknown[] }).body ?? []
+      const next = (inserted[0] ?? body[body.indexOf(declaration.node) + 1]) as
+        { comments?: unknown[] | null } | undefined
+      if (next)
+        hoistLeadingComments(declaration.node, next as never, originalComments)
+    }
+    if (kept.length === 0) declaration.prune()
+    else declaration.node.specifiers = kept
+  }
+
+  // `ensureZenith(X)` before another rule moved the legacy X onto Zenith's X leaves the Zenith
+  // import with both `X` and `X as ZenithX`: one export, two bindings. Merge them.
+  root
+    .find(j.ImportDeclaration, { source: { value: ZENITH } })
+    .forEach((declaration) => {
+      const specifiers = (declaration.node.specifiers ?? []).filter(
+        (s): s is ImportSpecifier => s.type === "ImportSpecifier"
+      )
+      const plain = new Set(
+        specifiers
+          .filter(
+            (s) =>
+              String(s.local?.name ?? s.imported.name) ===
+              String(s.imported.name)
+          )
+          .map((s) => String(s.imported.name))
+      )
+      const aliases = specifiers.filter(
+        (s) =>
+          String(s.local?.name) === `Zenith${String(s.imported.name)}` &&
+          plain.has(String(s.imported.name))
+      )
+      for (const alias of aliases) {
+        renameBinding(
+          j,
+          root,
+          String(alias.local?.name),
+          String(alias.imported.name)
+        )
+        declaration.node.specifiers = declaration.node.specifiers!.filter(
+          (s) => s !== alias
+        )
+      }
+    })
+
+  // Legacy references that are not import declarations: reported, never rewritten.
+  for (const { path, component, message } of otherReferences) {
+    todos.push({ line: lineOf(path), component, message })
+    attachTodoComment(j, path, formatTodo(component, message))
+  }
+
+  // Subpath imports a rule did not claim (rules may have pruned theirs, hence the re-find).
+  root.find(j.ImportDeclaration).forEach((p) => {
+    const value = String(p.node.source.value)
+    if (!value.startsWith(`${source}/`) || rulesByModule.has(value)) return
+    const message = `subpath import ${value}: no rule; import from ${source} or drop it`
+    todos.push({ line: lineOf(p), component: value, message })
+    attachTodoComment(j, p, formatTodo(value, message))
+  })
+
+  // 4. Report.
+  todos.sort((a, b) => a.line - b.line)
+  for (const t of todos) api.report(formatReport(t))
+
+  const output = applySemicolonStyle(root.toSource(), file.source)
+  return output === file.source ? undefined : output
+}
+
+type OtherReference = { path: ASTPath; component: string; message: string }
+
+/**
+ * References to the legacy package outside `import` declarations: re-exports, dynamic imports,
+ * `require`, and test mocks. None has a safe rewrite; each gets a TODO with the fix.
+ */
+function findOtherReferences(
+  j: JSCodeshift,
+  root: Collection,
+  source: string
+): OtherReference[] {
+  const found: OtherReference[] = []
+  const isLegacy = (value: unknown) =>
+    typeof value === "string" &&
+    (value === source || value.startsWith(`${source}/`))
+  const literalValue = (node: { type: string; value?: unknown } | undefined) =>
+    node && (node.type === "StringLiteral" || node.type === "Literal")
+      ? node.value
+      : undefined
+
+  root.find(j.ExportNamedDeclaration).forEach((path) => {
+    const value = literalValue(path.node.source as never)
+    if (!isLegacy(value)) return
+    const names = (path.node.specifiers ?? [])
+      .map((s) => String((s as { exported: { name: string } }).exported.name))
+      .join(", ")
+    found.push({
+      path: path as ASTPath,
+      component: names || "re-export",
+      message: `re-exported from ${value}: migrate the files importing it to @epilot/zenith-react, then delete this re-export`,
+    })
+  })
+  root.find(j.ExportAllDeclaration).forEach((path) => {
+    const value = literalValue(path.node.source as never)
+    if (!isLegacy(value)) return
+    found.push({
+      path: path as ASTPath,
+      component: "export *",
+      message: `re-exports all of ${value}: migrate the files importing from here to @epilot/zenith-react, then delete this re-export`,
+    })
+  })
+  root.find(j.CallExpression).forEach((path) => {
+    const callee = path.node.callee as {
+      type: string
+      name?: string
+      object?: { type: string; name?: string }
+      property?: { type: string; name?: string }
+    }
+    const first = literalValue(path.node.arguments[0] as never)
+    if (!isLegacy(first)) return
+    const statement = (j(path).closest(j.Statement).paths()[0] ??
+      path) as ASTPath
+    if (callee.type === "Import") {
+      found.push({
+        path: statement,
+        component: "import()",
+        message: `dynamic import of ${first}: no rewrite; import the named exports from @epilot/zenith-react statically, or migrate the awaited names by hand`,
+      })
+    } else if (callee.type === "Identifier" && callee.name === "require") {
+      found.push({
+        path: statement,
+        component: "require",
+        message: `require of ${first}: no rewrite; import the named exports from @epilot/zenith-react`,
+      })
+    } else if (
+      callee.type === "MemberExpression" &&
+      callee.property?.type === "Identifier" &&
+      /^(mock|unmock|doMock|requireActual|requireMock|importActual)$/.test(
+        String(callee.property.name)
+      ) &&
+      callee.object?.type === "Identifier" &&
+      /^(jest|vi)$/.test(String(callee.object.name))
+    ) {
+      found.push({
+        path: statement,
+        component: `${callee.object.name}.${callee.property.name}`,
+        message: `test mock of ${first}: point it at @epilot/zenith-react once the code under test is migrated, or delete it`,
+      })
+    }
+  })
+  return found
+}
+
+/**
+ * recast prints every reprinted statement with a semicolon (a rebuilt import, a `return (…)`
+ * whose JSX changed) whatever the file does. In a file that writes none, strip the semicolon
+ * from the lines the migration produced; lines the file already had keep theirs.
+ */
+export function applySemicolonStyle(output: string, original: string): string {
+  const originalLines = original.split("\n")
+  const code = originalLines.filter((line) => line.trim() !== "")
+  if (code.length === 0) return output
+  const withSemicolon = code.filter((line) => /;[ \t]*$/.test(line)).length
+  // Prettier's `semi: false` leaves a file with (nearly) no line-ending semicolons; a file with
+  // 1 in 10 or more writes them and is left alone.
+  if (withSemicolon * 10 >= code.length) return output
+  const known = new Set(originalLines)
+  return output
+    .split("\n")
+    .map((line) =>
+      /;[ \t]*$/.test(line) && !known.has(line) && !/^\s*for\b/.test(line)
+        ? line.replace(/;[ \t]*$/, "")
+        : line
+    )
+    .join("\n")
+}

package/codemods/migrate/lib/source.ts

@@ -0,0 +1,6 @@
+/** Which quote the file prefers in its import declarations (ties go to double). */
+export function detectQuote(source: string): "single" | "double" {
+  const singles = (source.match(/from\s+'[^']+'/g) ?? []).length
+  const doubles = (source.match(/from\s+"[^"]+"/g) ?? []).length
+  return singles > doubles ? "single" : "double"
+}

package/codemods/migrate/lib/todo.ts

@@ -0,0 +1,107 @@
+/**
+ * TODO bookkeeping: one comment in the code and one report line per finding. Report lines are
+ * `<line> <Component>: <message>`; jscodeshift prefixes the file path (` REP <path> …`).
+ */
+import type { ASTPath, JSCodeshift } from "jscodeshift"
+import { TODO_TAG, type TodoEntry } from "./types"
+
+export function formatTodo(component: string, message: string): string {
+  return `${TODO_TAG}: ${component}: ${message}`
+}
+
+export function formatReport(entry: TodoEntry): string {
+  return `${entry.line} ${entry.component}: ${entry.message}`
+}
+
+/**
+ * Attaches the TODO comment where it is legal and nearest: a JSX comment sibling when the node
+ * sits among JSX children (walking up to the enclosing child when it is nested in an attribute),
+ * otherwise a leading block comment on the node itself (recast prints it before the node; for a
+ * JSX root the element's own line keeps the report's line number).
+ */
+export function attachTodoComment(
+  j: JSCodeshift,
+  path: ASTPath,
+  text: string
+): void {
+  let current: ASTPath | null = path
+  while (current) {
+    const parent = current.parent?.node as { type?: string } | undefined
+    if (parent?.type === "JSXElement" || parent?.type === "JSXFragment") {
+      if (hasJsxSiblingComment(current, text)) return
+      const empty = j.jsxEmptyExpression()
+      ;(empty as { comments?: unknown[] }).comments = [
+        j.commentBlock(` ${text} `, false, true),
+      ]
+      current.insertBefore(j.jsxExpressionContainer(empty))
+      current.insertBefore(j.jsxText("\n"))
+      return
+    }
+    if (!parent || /Statement$|Declaration$/.test(String(current.node.type)))
+      break
+    const type = String(current.node.type)
+    if (!type.startsWith("JSX")) break
+    current = current.parent
+  }
+  // A declaration inside `export …` takes its comment on the export, not between the keywords.
+  const parentType = String(path.parent?.node?.type ?? "")
+  if (/^Export(Named|Default)Declaration$/.test(parentType)) path = path.parent
+  const node = path.node as {
+    type: string
+    comments?: unknown[]
+    openingElement?: { comments?: unknown[] }
+  }
+  const target =
+    node.type === "JSXElement" && node.openingElement
+      ? node.openingElement
+      : node
+  if (hasComment(target.comments, text)) return
+  target.comments = [
+    ...(target.comments ?? []),
+    j.commentBlock(` ${text} `, true, false),
+  ]
+}
+
+type CommentLike = { value?: string }
+
+/** Reruns must not stack the same TODO twice: the comment is already there. */
+export function hasComment(
+  comments: unknown[] | undefined,
+  text: string
+): boolean {
+  return (comments ?? []).some((c) =>
+    String((c as CommentLike).value ?? "").includes(text)
+  )
+}
+
+function hasJsxSiblingComment(path: ASTPath, text: string): boolean {
+  const siblings =
+    (
+      path.parent.node as {
+        children?: {
+          type: string
+          value?: string
+          expression?: { comments?: unknown[] }
+        }[]
+      }
+    ).children ?? []
+  let index = siblings.indexOf(path.node as never) - 1
+  while (index >= 0) {
+    const sibling = siblings[index]
+    if (sibling.type === "JSXText" && !sibling.value?.trim()) {
+      index -= 1
+      continue
+    }
+    return (
+      sibling.type === "JSXExpressionContainer" &&
+      sibling.expression?.comments !== undefined &&
+      hasComment(sibling.expression.comments, text)
+    )
+  }
+  return false
+}
+
+export function lineOf(path: ASTPath): number {
+  const loc = (path.node as { loc?: { start: { line: number } } }).loc
+  return loc?.start.line ?? 0
+}