@tamagui/codemod-flat-values 0.0.0-bootstrap.0 → 3.0.0-beta.1093.1

package/src/provenance.ts

@@ -0,0 +1,210 @@
+// Only Tamagui style syntax converts. A `hoverStyle` object or a `$token` string
+// means nothing to Emotion, restyle, or a local `styled` helper, so a site is only
+// a conversion site when its binding is provably Tamagui.
+//
+// Provenance is followed through module specifiers, never guessed from a name:
+// an import from `tamagui`/`@tamagui/*`, a re-export chain of relative modules
+// ending in one, or a local value assigned from a Tamagui `styled()` call.
+
+import {
+  Node,
+  SyntaxKind,
+  type CallExpression,
+  type Identifier,
+  type JsxOpeningElement,
+  type JsxSelfClosingElement,
+  type SourceFile,
+} from 'ts-morph'
+
+const tamaguiModule = /^(tamagui|@tamagui\/)/
+
+/** the identifier a JSX tag or a call ultimately binds to (`Card.Header` → `Card`) */
+function rootIdentifier(node: Node): Identifier | null {
+  let current = node
+  while (Node.isPropertyAccessExpression(current)) current = current.getExpression()
+  return Node.isIdentifier(current) ? current : null
+}
+
+export function createProvenance(): {
+  isTamaguiElement: (opening: JsxOpeningElement | JsxSelfClosingElement) => boolean
+  isTamaguiStyledCall: (call: CallExpression) => boolean
+} {
+  const resolved = new Map<Node, boolean>()
+  const active = new Set<Node>()
+
+  /** whether a declaration binds a value that came from Tamagui */
+  const fromDeclaration = (declaration: Node): boolean => {
+    const cached = resolved.get(declaration)
+    if (cached !== undefined) return cached
+    // an export cycle must terminate, and a binding is not Tamagui until proven
+    if (active.has(declaration)) return false
+    active.add(declaration)
+    const answer = computeDeclaration(declaration)
+    active.delete(declaration)
+    resolved.set(declaration, answer)
+    return answer
+  }
+
+  /** the named export of a module reached by a relative specifier */
+  const fromModule = (
+    specifier: string,
+    source: SourceFile | undefined,
+    name: string
+  ): boolean => {
+    if (tamaguiModule.test(specifier)) return true
+    if (source === undefined) return false
+    return exportedBinding(source, name)
+  }
+
+  const bindings = new Map<string, boolean>()
+  const openBindings = new Set<string>()
+
+  const exportedBinding = (source: SourceFile, name: string): boolean => {
+    const key = `${source.getFilePath()}#${name}`
+    const cached = bindings.get(key)
+    if (cached !== undefined) return cached
+    // a re-export cycle must terminate, and a binding is not Tamagui until proven
+    if (openBindings.has(key)) return false
+    openBindings.add(key)
+    const answer = computeBinding(source, name)
+    openBindings.delete(key)
+    bindings.set(key, answer)
+    return answer
+  }
+
+  const computeBinding = (source: SourceFile, name: string): boolean => {
+    // the re-export walk runs first: it answers from the module specifier alone,
+    // without asking the checker to load a package's whole declaration file
+    for (const declaration of source.getExportDeclarations()) {
+      const specifier = declaration.getModuleSpecifierValue()
+      const named = declaration.getNamedExports()
+      if (specifier === undefined) {
+        // `export { View }`: the local binding is what carries the provenance
+        for (const element of named) {
+          if ((element.getAliasNode() ?? element.getNameNode()).getText() !== name) {
+            continue
+          }
+          if (fromDeclaration(element)) return true
+        }
+        continue
+      }
+      if (!named.length && !declaration.getNamespaceExport()) {
+        // `export * from '...'`: the name can come from any of them
+        if (fromModule(specifier, declaration.getModuleSpecifierSourceFile(), name)) {
+          return true
+        }
+        continue
+      }
+      for (const element of named) {
+        if ((element.getAliasNode() ?? element.getNameNode()).getText() !== name) continue
+        if (
+          fromModule(
+            specifier,
+            declaration.getModuleSpecifierSourceFile(),
+            element.getName()
+          )
+        ) {
+          return true
+        }
+      }
+    }
+
+    for (const [exportName, declarations] of source.getExportedDeclarations()) {
+      if (exportName !== name) continue
+      for (const declaration of declarations) {
+        if (fromDeclaration(declaration)) return true
+      }
+    }
+    return false
+  }
+
+  const computeDeclaration = (declaration: Node): boolean => {
+    if (Node.isImportSpecifier(declaration)) {
+      const importDeclaration = declaration.getImportDeclaration()
+      return fromModule(
+        importDeclaration.getModuleSpecifierValue(),
+        importDeclaration.getModuleSpecifierSourceFile(),
+        declaration.getName()
+      )
+    }
+    if (Node.isImportClause(declaration) || Node.isNamespaceImport(declaration)) {
+      const importDeclaration = declaration.getFirstAncestorByKindOrThrow(
+        SyntaxKind.ImportDeclaration
+      )
+      return tamaguiModule.test(importDeclaration.getModuleSpecifierValue())
+    }
+    if (Node.isExportSpecifier(declaration)) {
+      const exportDeclaration = declaration.getExportDeclaration()
+      const specifier = exportDeclaration.getModuleSpecifierValue()
+      if (specifier !== undefined) {
+        return fromModule(
+          specifier,
+          exportDeclaration.getModuleSpecifierSourceFile(),
+          declaration.getName()
+        )
+      }
+      // `export { View }`: whatever declares View in this file is the binding
+      for (const local of declaration.getLocalTargetDeclarations()) {
+        if (fromDeclaration(local)) return true
+      }
+      return false
+    }
+    if (Node.isVariableDeclaration(declaration)) {
+      const initializer = declaration.getInitializer()
+      return initializer !== undefined && isTamaguiValue(initializer)
+    }
+    return false
+  }
+
+  const fromIdentifier = (identifier: Identifier): boolean => {
+    const symbol = identifier.getSymbol()
+    if (symbol === undefined) return false
+    for (const declaration of symbol.getDeclarations()) {
+      if (fromDeclaration(declaration)) return true
+    }
+    // an alias the checker already followed across files
+    const aliased = symbol.getAliasedSymbol()
+    if (aliased === undefined) return false
+    for (const declaration of aliased.getDeclarations()) {
+      if (fromDeclaration(declaration)) return true
+    }
+    return false
+  }
+
+  const isTamaguiStyledCall = (call: CallExpression): boolean => {
+    const callee = rootIdentifier(call.getExpression())
+    if (callee === null || callee.getText() !== 'styled') return false
+    return fromIdentifier(callee)
+  }
+
+  /**
+   * A value re-bound from Tamagui: an alias (`const Sheet = SheetRaw as ...`), a
+   * member of one, or the result of a Tamagui factory (`styled`,
+   * `withStaticProperties`). A local factory over a Tamagui component is not one:
+   * whatever it returns is that function's contract, not Tamagui's.
+   */
+  function isTamaguiValue(expression: Node): boolean {
+    let current = expression
+    while (
+      Node.isParenthesizedExpression(current) ||
+      Node.isAsExpression(current) ||
+      Node.isNonNullExpression(current)
+    ) {
+      current = current.getExpression()
+    }
+    const identifier = rootIdentifier(
+      Node.isCallExpression(current) ? current.getExpression() : current
+    )
+    return identifier !== null && fromIdentifier(identifier)
+  }
+
+  return {
+    isTamaguiElement: (opening) => {
+      const tag = rootIdentifier(opening.getTagNameNode())
+      // a lowercase tag is an intrinsic element, never a Tamagui component
+      if (tag === null || !/^[A-Z_$]/.test(tag.getText())) return false
+      return fromIdentifier(tag)
+    },
+    isTamaguiStyledCall,
+  }
+}

package/src/report.ts

@@ -0,0 +1,362 @@
+import type { Flag, SiteReport } from './convert'
+import type { FunctionalVariantReport } from './functionalVariants'
+import type { SheetFrameReport } from './sheetAnatomy'
+import type { TransitionReport } from './transition'
+
+export interface FileReport {
+  file: string
+  sites: SiteReport[]
+  functionalVariants: FunctionalVariantReport[]
+  sheetFrames: SheetFrameReport[]
+  transitions: TransitionReport[]
+}
+
+function countCodes(flags: Iterable<Flag>): Array<[string, number]> {
+  const counts = new Map<string, number>()
+  for (const flag of flags) counts.set(flag.code, (counts.get(flag.code) ?? 0) + 1)
+  return [...counts].sort(
+    ([leftCode, leftCount], [rightCode, rightCount]) =>
+      rightCount - leftCount || leftCode.localeCompare(rightCode)
+  )
+}
+
+export interface ReportSummary {
+  sites: number
+  clean: number
+  needsRelocation: number
+  unknownHost: number
+  ineligible: number
+  flagged: number
+  warnings: number
+  /** sites with nothing to convert until the runtime catches up */
+  waiting: number
+  ignoredFiles: number
+  functionalVariantSites: number
+  functionalVariantConverted: number
+  functionalVariantFlagged: number
+  functionalVariantFlags: Record<string, number>
+  sheetFrames: number
+  /** rewritten, but with a spread or a styled target a human has to place */
+  sheetFramesFlagged: number
+  transitions: number
+  /** v2 transitions the pass could not read statically */
+  transitionsFlagged: number
+}
+
+export function renderReport(
+  files: readonly FileReport[],
+  corpus: readonly string[],
+  registryDiagnostics: readonly string[],
+  ignoredFiles = 0,
+  write = false
+): { text: string; summary: ReportSummary } {
+  const sites = files.flatMap((file) => file.sites)
+  const functionalVariants = files.flatMap((file) => file.functionalVariants)
+  const sheetFrames = files.flatMap((file) => file.sheetFrames)
+  const flaggedSheetFrames = sheetFrames.filter((site) => site.flags.length > 0)
+  const transitions = files.flatMap((file) => file.transitions)
+  const flaggedTransitions = transitions.filter((site) => site.flags.length > 0)
+  const convertedFunctionalVariants = functionalVariants.filter((site) => site.converted)
+  const flaggedFunctionalVariants = functionalVariants.filter((site) => !site.converted)
+  const clean = sites.filter(
+    (site) =>
+      site.flags.length === 0 &&
+      site.warnings.length === 0 &&
+      site.assessmentVerdict === 'clean'
+  )
+  const flagged = sites.filter((site) => site.flags.length > 0)
+  const warnings = sites.filter((site) => site.warnings.length > 0)
+  const needsRelocation = sites.filter(
+    (site) => site.assessmentVerdict === 'needs-relocation'
+  )
+  const unknownHost = sites.filter((site) => site.assessmentVerdict === 'unknown-host')
+  const ineligible = sites.filter((site) => site.assessmentVerdict === 'ineligible')
+  const waiting = clean.filter((site) => site.programs.length === 0)
+  const jsx = sites.filter((site) => site.kind === 'jsx')
+  const styled = sites.filter((site) => site.kind === 'styled')
+  const cleanJsx = jsx.filter(
+    (site) =>
+      site.flags.length === 0 &&
+      site.warnings.length === 0 &&
+      site.assessmentVerdict === 'clean'
+  ).length
+  const cleanStyled = styled.filter(
+    (site) =>
+      site.flags.length === 0 &&
+      site.warnings.length === 0 &&
+      site.assessmentVerdict === 'clean'
+  ).length
+  const touched = (file: FileReport) =>
+    file.sites.length > 0 ||
+    file.functionalVariants.length > 0 ||
+    file.sheetFrames.length > 0 ||
+    file.transitions.length > 0
+  const blocked = (file: FileReport) =>
+    file.sites.some((site) => site.legacyLeft > 0) ||
+    file.functionalVariants.some((site) => !site.converted) ||
+    file.sheetFrames.some((site) => site.flags.length > 0) ||
+    file.transitions.some((site) => site.flags.length > 0)
+  const readyFiles = files.filter((file) => touched(file) && !blocked(file))
+  const filesWithSites = files.filter(touched).length
+  const blockedFiles = files.filter(blocked).map((file) => file.file)
+  const functionalFlagCounts = countCodes(
+    flaggedFunctionalVariants.flatMap((site) => [
+      ...new Map(site.flags.map((flag) => [flag.code, flag])).values(),
+    ])
+  )
+
+  const lines = [
+    '# Flat-values codemod dry-run',
+    '',
+    `Corpus: ${corpus.map((entry) => `\`${entry}\``).join(', ')}.`,
+    '',
+    write
+      ? 'Statically safe conversions were written in place. Flagged legacy syntax remains for manual migration.'
+      : 'Dry run only: no source files were written. Pass `--write` to apply statically safe conversions.',
+    '',
+    '## Summary',
+    '',
+    `- ${sites.length} conversion sites found`,
+    `- ${clean.length - waiting.length} converted with no open questions`,
+    `- ${needsRelocation.length} need relocation because the authored target or host cannot evaluate the conversion`,
+    `- ${unknownHost.length} have an unverified host type`,
+    `- ${ineligible.length} use properties that cannot carry flat clauses`,
+    `- ${waiting.length} have nothing to convert until the runtime catches up (see below)`,
+    `- ${flagged.length} have syntax or ordering flags for manual work`,
+    `- ${warnings.length} have configuration warnings for manual review`,
+    `- ${ignoredFiles} source files skipped by \`.tamagui-flat-values-ignore\` markers`,
+    `- ${jsx.length} JSX sites: ${cleanJsx} clean, ${jsx.length - cleanJsx} need review`,
+    `- ${styled.length} styled config sites: ${cleanStyled} clean, ${styled.length - cleanStyled} need review`,
+    `- ${functionalVariants.length} functional variant sites found`,
+    `- ${convertedFunctionalVariants.length} functional variants have automatic styled.dynamic rewrites`,
+    `- ${flaggedFunctionalVariants.length} functional variants need manual migration`,
+    `- ${sheetFrames.length} Sheet.Frame sites rewritten to Sheet.Container plus Sheet.Background`,
+    `- ${flaggedSheetFrames.length} Sheet.Frame sites need a human to place a spread or a styled target`,
+    `- ${transitions.length} v2 transition values rewritten to the v3 spelling`,
+    `- ${flaggedTransitions.length} v2 transition values need a hand migration`,
+    '',
+    '### Functional variant flag reasons',
+    '',
+    ...(functionalFlagCounts.length
+      ? functionalFlagCounts.map(([code, count]) => `- ${code}: ${count}`)
+      : ['- none']),
+    '',
+    '### Remaining manual migration',
+    '',
+    `${readyFiles.length} of ${filesWithSites} files have no legacy condition object, flagged functional variant, or flagged Sheet.Frame left after`,
+    'conversion. V3 has no compatibility setting; finish the remaining files directly:',
+    blockedFiles.length
+      ? blockedFiles.map((file) => `\`${file}\``).join(', ')
+      : 'every file in this corpus is fully migrated.',
+    '',
+    '### Flag reasons',
+    '',
+  ]
+
+  const flagCounts = countCodes(flagged.flatMap((site) => site.flags))
+  lines.push(
+    ...(flagCounts.length
+      ? flagCounts.map(([code, count]) => `- ${code}: ${count}`)
+      : ['- none'])
+  )
+
+  const warningCounts = countCodes(warnings.flatMap((site) => site.warnings))
+  lines.push(
+    '',
+    '### Configuration warning reasons',
+    '',
+    ...(warningCounts.length
+      ? warningCounts.map(([code, count]) => `- ${code}: ${count}`)
+      : ['- none'])
+  )
+
+  const inventoryCounts = countCodes(sites.flatMap((site) => site.inventory))
+  if (inventoryCounts.length) {
+    lines.push(
+      '',
+      '### Values left authored for another migration',
+      '',
+      'These are not flat-value migration work. The conversion keeps them exactly as',
+      'authored and records them so their follow-up migrations have a corpus inventory.',
+      '',
+      ...inventoryCounts.map(([code, count]) => `- ${code}: ${count}`)
+    )
+  }
+
+  const pendingCounts = countCodes(sites.flatMap((site) => site.pending))
+  if (pendingCounts.length) {
+    lines.push(
+      '',
+      '### Waiting on runtime support',
+      '',
+      'The conversion is known but not offered, because the runtime cannot read it yet.',
+      'Each pending reason below names the exact host or merge contract that must land',
+      'before the suggested source is safe to apply.',
+      '',
+      ...pendingCounts.map(([code, count]) => `- ${code}: ${count}`)
+    )
+  }
+
+  if (registryDiagnostics.length) {
+    lines.push('', '### Modifier registry diagnostics', '')
+    for (const diagnostic of registryDiagnostics) lines.push(`- ${diagnostic}`)
+  }
+
+  for (const file of files) {
+    if (!touched(file)) continue
+    lines.push('', `## \`${file.file}\``, '')
+    for (const site of file.transitions) {
+      lines.push(
+        `### ${site.label} at line ${site.line} (${site.flags.length ? 'review' : 'automatic'})`,
+        '',
+        'Before:',
+        '',
+        '```tsx',
+        site.before,
+        '```',
+        '',
+        'Automatic rewrite:',
+        '',
+        '```tsx',
+        site.after,
+        '```'
+      )
+      if (site.flags.length) {
+        lines.push('', 'Flags:', '')
+        for (const flag of site.flags) lines.push(`- **${flag.code}**: ${flag.detail}`)
+      }
+    }
+    for (const site of file.sheetFrames) {
+      lines.push(
+        `### ${site.label} at line ${site.line} (${site.flags.length ? 'review' : 'automatic'})`,
+        '',
+        'Before:',
+        '',
+        '```tsx',
+        site.before,
+        '```',
+        '',
+        'Automatic rewrite:',
+        '',
+        '```tsx',
+        site.after,
+        '```'
+      )
+      if (site.flags.length) {
+        lines.push('', 'Flags:', '')
+        for (const flag of site.flags) lines.push(`- **${flag.code}**: ${flag.detail}`)
+      }
+      lines.push('')
+    }
+    for (const site of file.functionalVariants) {
+      lines.push(
+        `### ${site.label} functional variant at line ${site.line} (${site.converted ? 'automatic' : 'manual'})`,
+        '',
+        'Before:',
+        '',
+        '```tsx',
+        site.before,
+        '```',
+        '',
+        site.converted ? 'Automatic rewrite:' : 'Left authored:',
+        '',
+        '```tsx',
+        site.after,
+        '```'
+      )
+      if (site.flags.length) {
+        lines.push('', 'Flags:', '')
+        for (const flag of site.flags) lines.push(`- **${flag.code}**: ${flag.detail}`)
+      }
+      if (site.draft) {
+        lines.push('', 'Generated `.resolve` draft:', '', '```tsx', site.draft, '```')
+      }
+      if (site.notes.length) {
+        lines.push('', 'Notes:', '')
+        for (const note of site.notes) lines.push(`- ${note}`)
+      }
+      lines.push('')
+    }
+    for (const site of file.sites) {
+      const status = [
+        site.assessmentVerdict === 'clean' ? null : site.assessmentVerdict,
+        site.flags.length ? 'syntax-blocked' : null,
+        site.warnings.length ? 'configuration-warning' : null,
+      ]
+        .filter(Boolean)
+        .join(', ')
+      lines.push(
+        `### ${site.label} at line ${site.line} (${status || 'clean'})`,
+        '',
+        'Before:',
+        '',
+        '```tsx',
+        site.before,
+        '```',
+        '',
+        'After:',
+        '',
+        '```tsx',
+        site.after,
+        '```'
+      )
+      if (site.flags.length) {
+        lines.push('', 'Flags:', '')
+        for (const flag of site.flags) lines.push(`- **${flag.code}**: ${flag.detail}`)
+      }
+      if (site.warnings.length) {
+        lines.push('', 'Configuration warnings:', '')
+        for (const warning of site.warnings) {
+          lines.push(`- **${warning.code}**: ${warning.detail}`)
+        }
+      }
+      if (site.assessments.length) {
+        lines.push('', 'Conversion assessment:', '')
+        for (const assessment of site.assessments) {
+          for (const reason of assessment.reasons) {
+            lines.push(
+              `- **${assessment.verdict}: ${assessment.property}**: ${reason.message}. Remedy: ${reason.remedy}.`
+            )
+          }
+        }
+      }
+      if (site.inventory.length) {
+        lines.push('', 'Left authored:', '')
+        for (const flag of site.inventory)
+          lines.push(`- **${flag.code}**: ${flag.detail}`)
+      }
+      if (site.pending.length) {
+        lines.push('', 'Waiting on runtime support:', '')
+        for (const flag of site.pending) lines.push(`- **${flag.code}**: ${flag.detail}`)
+      }
+      if (site.notes.length) {
+        lines.push('', 'Notes:', '')
+        for (const note of site.notes) lines.push(`- ${note}`)
+      }
+      lines.push('')
+    }
+  }
+
+  return {
+    text: `${lines.join('\n')}\n`,
+    summary: {
+      sites: sites.length,
+      clean: clean.length,
+      needsRelocation: needsRelocation.length,
+      unknownHost: unknownHost.length,
+      ineligible: ineligible.length,
+      flagged: flagged.length,
+      warnings: warnings.length,
+      waiting: waiting.length,
+      ignoredFiles,
+      functionalVariantSites: functionalVariants.length,
+      functionalVariantConverted: convertedFunctionalVariants.length,
+      functionalVariantFlagged: flaggedFunctionalVariants.length,
+      functionalVariantFlags: Object.fromEntries(functionalFlagCounts),
+      sheetFrames: sheetFrames.length,
+      sheetFramesFlagged: flaggedSheetFrames.length,
+      transitions: transitions.length,
+      transitionsFlagged: flaggedTransitions.length,
+    },
+  }
+}