@tamagui/codemod-flat-values 3.0.0-beta.889.1 → 3.0.0-beta.901.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tamagui/codemod-flat-values",
-  "version": "3.0.0-beta.889.1",
+  "version": "3.0.0-beta.901.1",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -26,14 +26,14 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@tamagui/helpers": "3.0.0-beta.889.1",
-    "@tamagui/language-service": "3.0.0-beta.889.1",
-    "@tamagui/shorthands": "3.0.0-beta.889.1",
-    "@tamagui/style-grammar": "3.0.0-beta.889.1",
+    "@tamagui/helpers": "3.0.0-beta.901.1",
+    "@tamagui/language-service": "3.0.0-beta.901.1",
+    "@tamagui/shorthands": "3.0.0-beta.901.1",
+    "@tamagui/style-grammar": "3.0.0-beta.901.1",
     "ts-morph": "^28.0.0"
   },
   "devDependencies": {
-    "@tamagui/build": "3.0.0-beta.889.1",
+    "@tamagui/build": "3.0.0-beta.901.1",
     "typescript": "~6.0.3"
   },
   "repository": {

package/src/builtInNames.ts

@@ -5,6 +5,8 @@ export const v6CodemodBuiltInNameReplacements = {
   // v3 removed backgroundActive after its component defaults had already
   // stopped resolving; press is the corrected active-state default
   backgroundActive: 'background-press',
+  // v3 configs no longer alias `true`; the default config pointed it at `4`
+  true: '4',
 } as const
 
 const builtInTokenPattern = new RegExp(

package/src/convert.ts

@@ -21,8 +21,10 @@ import {
   type JsxAttribute,
   type JsxOpeningElement,
   type JsxSelfClosingElement,
+  type NoSubstitutionTemplateLiteral,
   type ObjectLiteralExpression,
   type PropertyAssignment,
+  type StringLiteral,
 } from 'ts-morph'
 import type { ContainerPlan } from './containers'
 import {
@@ -45,6 +47,7 @@ import {
   sharedPayload,
   shorthands,
   styleProps,
+  tokenVariantProps,
   unitSuffix,
   type ConversionReason,
   type ConversionTargets,
@@ -179,6 +182,8 @@ export interface Site {
   members: Member[]
   comments: Map<number, readonly string[]>
   extras: Array<{ index: number; text: string }>
+  /** token variant values respelled in place; they count as converted output */
+  respelled: EmittedProgram[]
   warnings: Flag[]
   flags: Flag[]
   inventory: Flag[]
@@ -206,6 +211,7 @@ function createSite(
     members: [],
     comments: new Map(),
     extras: [],
+    respelled: [],
     warnings: [],
     flags: [],
     inventory: [],
@@ -263,6 +269,16 @@ function addAssessment(
   }
 }
 
+/** a member the conversion owns, so the rewrite prints it from the site's entries */
+function isConvertedName(name: string): boolean {
+  return (
+    name === 'group' ||
+    styleProps.has(name) ||
+    tokenVariantProps.has(name) ||
+    isLegacyConditionName(name)
+  )
+}
+
 function addFlag(list: Flag[], code: string, detail: string): void {
   if (!list.some((flag) => flag.code === code && flag.detail === detail)) {
     list.push({ code, detail })
@@ -276,21 +292,32 @@ function addNote(site: Site, note: string): void {
 const legacyPaletteStepPattern =
   /(?:^|[^\w-])\$?((?:gray|mauve|slate|sage|olive|sand|tomato|red|ruby|crimson|pink|plum|purple|violet|iris|indigo|blue|cyan|teal|jade|green|grass|bronze|gold|brown|orange|amber|yellow|lime|mint|sky)(?:1[0-2]|[1-9]))(?![\w-])/g
 
-function legacyPaletteStepWarning(prop: string, values: readonly string[]): Flag | null {
+const legacyTrueTokenPattern = /(?:^|[^\w-])\$true(?![\w-])/
+
+/** configuration risks visible in the authored literals of one value */
+function legacyTokenWarnings(prop: string, values: readonly string[]): Flag[] {
+  const warnings: Flag[] = []
+  if (values.some((value) => legacyTrueTokenPattern.test(value))) {
+    warnings.push({
+      code: 'legacy-true-token',
+      detail: `${prop} spelled the \`$true\` alias, written as \`4\` because the default config aliased it there; confirm the app's tokens agree`,
+    })
+  }
   const names = new Set<string>()
   for (const value of values) {
     legacyPaletteStepPattern.lastIndex = 0
     for (const match of value.matchAll(legacyPaletteStepPattern)) names.add(match[1])
   }
-  if (!names.size) return null
+  if (!names.size) return warnings
   const formatted = [...names]
     .sort()
     .map((name) => `\`${name}\``)
     .join(', ')
-  return {
+  warnings.push({
     code: 'legacy-palette-token',
     detail: `${prop} preserves ${formatted}, which @tamagui/config/v6 does not define; choose an absolute palette token or an adaptive colorN value`,
-  }
+  })
+  return warnings
 }
 
 // —— value classification ————————————————————————————————————————————————
@@ -304,8 +331,8 @@ interface Classification {
   dynamic: boolean
   /** a problem with the value itself, raised on sight */
   problem: Flag | null
-  /** a non-blocking configuration risk visible in the authored literals */
-  warning: Flag | null
+  /** non-blocking configuration risks visible in the authored literals */
+  warnings: Flag[]
   /** raised only when a clause forces the value into a program */
   blocked: Flag | null
   /** recorded for a migration that is not the flat-value migration */
@@ -317,7 +344,7 @@ const empty: Classification = {
   text: null,
   dynamic: false,
   problem: null,
-  warning: null,
+  warnings: [],
   blocked: null,
   inventory: null,
 }
@@ -402,7 +429,7 @@ function classifyDynamic(
       payload: interpolate(prop, tree.text, tree.kind, registry),
       text: rewrittenTokenText,
       dynamic: true,
-      warning: legacyPaletteStepWarning(prop, tree.strings),
+      warnings: legacyTokenWarnings(prop, tree.strings),
     }
   }
   if (tree) {
@@ -469,8 +496,9 @@ function pushBase(
   const index = site.index++
 
   if (literalString !== null) {
-    const warning = legacyPaletteStepWarning(prop, [literalString])
-    if (warning) addFlag(site.warnings, warning.code, warning.detail)
+    for (const warning of legacyTokenWarnings(prop, [literalString])) {
+      addFlag(site.warnings, warning.code, warning.detail)
+    }
     if (literalString.includes('$')) {
       site.legacy = true
       const allowed = assessProgram(site, prop, [])
@@ -588,8 +616,8 @@ function pushBase(
     site.legacy = true
     addFlag(site.flags, classified.problem.code, classified.problem.detail)
   }
-  if (classified.warning) {
-    addFlag(site.warnings, classified.warning.code, classified.warning.detail)
+  for (const warning of classified.warnings) {
+    addFlag(site.warnings, warning.code, warning.detail)
   }
   if (classified.inventory) {
     addFlag(site.inventory, classified.inventory.code, classified.inventory.detail)
@@ -824,12 +852,8 @@ function pushLegacy(
   for (let index = 0; index < evaluated.leaves.length; index++) {
     const leaf = evaluated.leaves[index]
     const classified = classifyDynamic(leaf.prop, leaf.expression, site.registry)
-    if (classified.warning) {
-      addFlag(
-        site.warnings,
-        classified.warning.code,
-        `${leaf.path}: ${classified.warning.detail}`
-      )
+    for (const warning of classified.warnings) {
+      addFlag(site.warnings, warning.code, `${leaf.path}: ${warning.detail}`)
     }
     if (classified.payload === null) {
       const flag = classified.problem ?? classified.blocked
@@ -1393,9 +1417,7 @@ function isConvertedJsxAttribute(attribute: Node): boolean {
   if (Node.isJsxSpreadAttribute(attribute)) return true
   if (!Node.isJsxAttribute(attribute)) return false
   const name = jsxAttributeName(attribute)
-  return (
-    !!name && (name === 'group' || styleProps.has(name) || isLegacyConditionName(name))
-  )
+  return !!name && isConvertedName(name)
 }
 
 function rewriteJsxSite(
@@ -1429,16 +1451,19 @@ function rewriteJsxSite(
   // impossible to review.
   //
   // The authored indentation is dropped from the prefix and the closing suffix
-  // so every emitted line is indented by replaceWithText alone. Keeping it would
-  // add to what ts-morph supplies and stagger the attributes, and taking control
-  // of the whitespace directly is not an option: SourceFile.replaceText forgets
-  // every node in the file and the rest of the pass then reads freed nodes.
+  // so every emitted line is indented by replaceWithText alone: ts-morph puts
+  // each new line at the element's own indentation, so an attribute line
+  // carries one relative step and the closing `>` none. Keeping the authored
+  // whitespace would add to what ts-morph supplies and stagger the attributes,
+  // and taking control of the whitespace directly is not an option:
+  // SourceFile.replaceText forgets every node in the file and the rest of the
+  // pass then reads freed nodes.
   const authoredMultiline =
     prefix.includes('\n') ||
     source.slice(first.getStart() - start, last.getEnd() - start).includes('\n')
   opening.replaceWithText(
     authoredMultiline
-      ? `${prefix.replace(/[ \t]+$/, '')}${rendered.join('\n')}${suffix.replace(/\n[ \t]+/, '\n')}`
+      ? `${prefix.replace(/[ \t]+$/, '')}${rendered.map((text) => `  ${text}`).join('\n')}${suffix.replace(/\n[ \t]+/, '\n')}`
       : `${prefix}${rendered.join(' ')}${suffix}`
   )
 }
@@ -1495,11 +1520,7 @@ export function convertJsxSite(
             if (name !== null) {
               // a member the conversion leaves authored has to print as the JSX
               // attribute it becomes here, not as the object member it was
-              if (
-                name === 'group' ||
-                styleProps.has(name) ||
-                isLegacyConditionName(name)
-              ) {
+              if (isConvertedName(name)) {
                 pushStyledProperty(
                   site,
                   name,
@@ -1553,6 +1574,10 @@ export function convertJsxSite(
       pushLegacy(site, name, text, jsxExpression(attribute), attribute)
       continue
     }
+    if (tokenVariantProps.has(name)) {
+      if (pushTokenVariant(site, name, attribute, text)) before.push(text)
+      continue
+    }
     if (!styleProps.has(name)) continue
     before.push(text)
 
@@ -1576,7 +1601,7 @@ export function convertJsxSite(
     line: sourceFile.getLineAndColumnAtPos(opening.getStart()).line,
     before: before.join(' '),
     after: entries.map((entry) => entry.text).join(' ') || '(no style props left)',
-    programs,
+    programs: [...programs, ...site.respelled],
     assessments: site.assessments,
     assessmentVerdict: assessmentVerdict(site.assessments),
     warnings: site.warnings,
@@ -1620,6 +1645,10 @@ function pushStyledProperty(
     pushLegacy(site, name, text, initializer, property)
     return
   }
+  if (tokenVariantProps.has(name)) {
+    pushTokenVariant(site, name, property, text)
+    return
+  }
   if (!styleProps.has(name)) return
 
   const literal =
@@ -1629,6 +1658,86 @@ function pushStyledProperty(
   pushBase(site, name, text, literal === null ? initializer : null, literal)
 }
 
+/**
+ * A variant prop whose value is a size token (`size="$4"`, `elevation="$2"`).
+ * No program is built for it, but v3 looks the value up as written and `$4`
+ * finds nothing, so every `$token` string literal in the value is respelled,
+ * a conditional on both arms. `$true` aliased the default size, which v3
+ * spells as the boolean. Returns whether the member is legacy at all:
+ * respelled, or flagged because it cannot be.
+ */
+function pushTokenVariant(
+  site: Site,
+  name: string,
+  node: JsxAttribute | PropertyAssignment,
+  text: string
+): boolean {
+  const index = site.index++
+  const initializer = node.getInitializer()
+  const value =
+    initializer !== undefined && Node.isJsxExpression(initializer)
+      ? initializer.getExpression()
+      : initializer
+  const literals =
+    value === undefined
+      ? []
+      : [value, ...value.getDescendants()].filter(
+          (candidate): candidate is StringLiteral | NoSubstitutionTemplateLiteral =>
+            (Node.isStringLiteral(candidate) ||
+              Node.isNoSubstitutionTemplateLiteral(candidate)) &&
+            candidate.getLiteralValue().startsWith('$')
+        )
+  if (value === undefined || literals.length === 0) {
+    site.members.push({ type: 'passthrough', index, text })
+    return false
+  }
+
+  const source = value.getText()
+  const start = value.getStart()
+  let rewritten = ''
+  let cursor = start
+  for (const literal of literals) {
+    let replacement = 'true'
+    if (literal.getLiteralValue() !== '$true') {
+      const flat = flatStringValue(literal.getLiteralValue(), site.registry)
+      if (flat.text === null) {
+        site.legacy = true
+        addFlag(
+          site.flags,
+          flat.error?.code ?? 'unsupported-legacy-value',
+          `${name}: ${flat.error?.message ?? `${literal.getText()} has no flat spelling`}`
+        )
+        site.members.push({ type: 'passthrough', index, text })
+        return true
+      }
+      const quote = literal.getText()[0]
+      replacement = `${quote}${flat.text}${quote}`
+    }
+    rewritten += source.slice(cursor - start, literal.getStart() - start)
+    rewritten += replacement
+    cursor = literal.getEnd()
+  }
+  rewritten += source.slice(cursor - start)
+
+  site.legacy = true
+  const output = Node.isJsxAttribute(node)
+    ? Node.isStringLiteral(initializer)
+      ? rewritten === 'true'
+        ? name
+        : `${name}=${rewritten}`
+      : `${name}={${rewritten}}`
+    : site.kind === 'jsx'
+      ? `${name}={${rewritten}}`
+      : textWithOuterComments(node, `${node.getNameNode().getText()}: ${rewritten}`)
+  site.members.push({ type: 'passthrough', index, text: output })
+  site.respelled.push({
+    name,
+    value: rewritten,
+    dynamic: literals.length !== 1 || literals[0] !== value,
+  })
+  return true
+}
+
 export function convertStyleObject(
   object: ObjectLiteralExpression,
   kind: SiteKind,
@@ -1651,11 +1760,7 @@ export function convertStyleObject(
           if (Node.isPropertyAssignment(nested)) {
             const name = propertyName(nested.getNameNode())
             if (name !== null) {
-              if (
-                name === 'group' ||
-                styleProps.has(name) ||
-                isLegacyConditionName(name)
-              ) {
+              if (isConvertedName(name)) {
                 pushStyledProperty(site, name, nested)
               } else {
                 site.members.push({
@@ -1697,8 +1802,7 @@ export function convertStyleObject(
     }
     const name = propertyName(nameNode)
     if (name === null) continue
-    if (!styleProps.has(name) && !isLegacyConditionName(name) && name !== 'group')
-      continue
+    if (!isConvertedName(name)) continue
     before.push(compact(property.getText()))
     pushStyledProperty(site, name, property)
   }
@@ -1713,7 +1817,7 @@ export function convertStyleObject(
     line: sourceFile.getLineAndColumnAtPos(object.getStart()).line,
     before: before.join(', '),
     after: entries.map((entry) => entry.text).join(', ') || '(no style props left)',
-    programs,
+    programs: [...programs, ...site.respelled],
     assessments: site.assessments,
     assessmentVerdict: assessmentVerdict(site.assessments),
     warnings: site.warnings,
@@ -1742,9 +1846,7 @@ function isConvertedStyledProperty(property: Node): boolean {
   const nameNode = property.getNameNode()
   if (Node.isComputedPropertyName(nameNode)) return false
   const name = propertyName(nameNode)
-  return (
-    !!name && (name === 'group' || styleProps.has(name) || isLegacyConditionName(name))
-  )
+  return !!name && isConvertedName(name)
 }
 
 function allCommentTexts(node: Node): string[] {
@@ -1762,7 +1864,7 @@ function allCommentTexts(node: Node): string[] {
     .map((entry) => entry[1])
 }
 
-function textWithOuterComments(node: Node): string {
+function textWithOuterComments(node: Node, text = node.getText()): string {
   const comments = new Map<number, string>()
   for (const range of [
     ...node.getLeadingCommentRanges(),
@@ -1773,7 +1875,9 @@ function textWithOuterComments(node: Node): string {
   const prefix = [...comments.entries()]
     .sort((left, right) => left[0] - right[0])
     .map((entry) => entry[1])
-  return [...prefix, node.getText()].join('\n')
+  // the member sits one step inside its object and rewriteStyleObject supplies
+  // that step for the first line only, so the lines after a comment carry it
+  return [...prefix, text].join('\n  ')
 }
 
 function rewriteStyleObject(

package/src/grammar.ts

@@ -87,6 +87,16 @@ export const styleProps: ReadonlySet<string> = new Set<string>([
   ...Object.values(shorthands),
 ])
 
+/**
+ * variant props whose values are size tokens. no program is built for them,
+ * but v3 reads the value as a size-scale key and a `$` spelling finds nothing
+ */
+export const tokenVariantProps: ReadonlySet<string> = new Set<string>([
+  'size',
+  'elevation',
+  'iconSize',
+])
+
 /** the media keys of the V6 default config, plus the two motion queries */
 export const codemodMediaNames: readonly string[] = [
   ...defaultMediaKeys,

package/src/index.ts

@@ -4,6 +4,7 @@ import { dirname, relative, resolve } from 'node:path'
 import { resolveTamaguiHost } from '@tamagui/language-service/host'
 import { stylePropsTextOnly } from '@tamagui/helpers'
 import {
+  IndentationText,
   ModuleKind,
   ModuleResolutionKind,
   Node,
@@ -34,6 +35,7 @@ import {
 } from './grammar'
 import { createProvenance } from './provenance'
 import { renderReport, type FileReport } from './report'
+import { convertSheetFrames } from './sheetAnatomy'
 
 type Provenance = ReturnType<typeof createProvenance>
 
@@ -86,6 +88,11 @@ function collectFiles(inputs: readonly string[]): {
   const project = new Project({
     tsConfigFilePath,
     skipAddingFilesFromTsConfig: true,
+    // ts-morph re-indents every multi-line replacement from the indentation it
+    // computes for the node with this unit. The default four-space unit puts a
+    // JSX child two columns past where two-space source authored it, and every
+    // attribute line of a rewritten element staggered with it
+    manipulationSettings: { indentationText: IndentationText.TwoSpaces },
     compilerOptions: {
       allowJs: false,
       jsx: 4,
@@ -226,6 +233,26 @@ function variantSites(
 ): SiteReport[] {
   const sites: SiteReport[] = []
 
+  // variant defaults are spelled like the props they set, so a size token here
+  // needs the same respelling as one on an element
+  const defaults = config.getProperty('defaultVariants')
+  if (Node.isPropertyAssignment(defaults)) {
+    const object = unwrapExpression(defaults.getInitializerOrThrow())
+    if (Node.isObjectLiteralExpression(object)) {
+      const site = convertStyleObject(
+        object,
+        'styled',
+        `${label} defaultVariants`,
+        registry,
+        containers,
+        targets,
+        host,
+        write
+      )
+      if (site) sites.push(site)
+    }
+  }
+
   const variants = config.getProperty('variants')
   if (Node.isPropertyAssignment(variants)) {
     const object = unwrapExpression(variants.getInitializerOrThrow())
@@ -311,6 +338,9 @@ function inspectFile(
   provenance: Provenance,
   write: boolean
 ): FileReport {
+  // the anatomy rewrite runs first so the Background it adds, and the surface
+  // props it moves there, go through the flat-value conversion below
+  const sheetFrames = convertSheetFrames(sourceFile, provenance, write)
   const containers = planContainers(sourceFile, registry)
   const targets = conversionTargets(sourceFile.getFilePath())
   const sites: SiteReport[] = []
@@ -375,6 +405,7 @@ function inspectFile(
     file: relative(projectRoot, sourceFile.getFilePath()),
     sites,
     functionalVariants,
+    sheetFrames,
   }
 }
 
@@ -528,5 +559,5 @@ if (write) {
 console.log(`wrote ${reportPath}`)
 if (write) console.log(`rewrote ${written} source files`)
 console.log(
-  `${summary.sites} style sites: ${summary.clean - summary.waiting} clean, ${summary.needsRelocation} need relocation, ${summary.unknownHost} unknown host, ${summary.ineligible} ineligible, ${summary.waiting} waiting on runtime support, ${summary.flagged} syntax-flagged; ${summary.functionalVariantSites} functional variants: ${summary.functionalVariantConverted} automatic, ${summary.functionalVariantFlagged} flagged; ${summary.ignoredFiles} source files ignored`
+  `${summary.sites} style sites: ${summary.clean - summary.waiting} clean, ${summary.needsRelocation} need relocation, ${summary.unknownHost} unknown host, ${summary.ineligible} ineligible, ${summary.waiting} waiting on runtime support, ${summary.flagged} syntax-flagged; ${summary.functionalVariantSites} functional variants: ${summary.functionalVariantConverted} automatic, ${summary.functionalVariantFlagged} flagged; ${summary.sheetFrames} Sheet.Frame sites: ${summary.sheetFramesFlagged} need review; ${summary.ignoredFiles} source files ignored`
 )

package/src/report.ts

@@ -1,10 +1,12 @@
 import type { Flag, SiteReport } from './convert'
 import type { FunctionalVariantReport } from './functionalVariants'
+import type { SheetFrameReport } from './sheetAnatomy'
 
 export interface FileReport {
   file: string
   sites: SiteReport[]
   functionalVariants: FunctionalVariantReport[]
+  sheetFrames: SheetFrameReport[]
 }
 
 function countCodes(flags: Iterable<Flag>): Array<[string, number]> {
@@ -31,6 +33,9 @@ export interface ReportSummary {
   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
 }
 
 export function renderReport(
@@ -42,6 +47,8 @@ export function renderReport(
 ): { 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 convertedFunctionalVariants = functionalVariants.filter((site) => site.converted)
   const flaggedFunctionalVariants = functionalVariants.filter((site) => !site.converted)
   const clean = sites.filter(
@@ -72,22 +79,17 @@ export function renderReport(
       site.warnings.length === 0 &&
       site.assessmentVerdict === 'clean'
   ).length
-  const readyFiles = files.filter(
-    (file) =>
-      (file.sites.length > 0 || file.functionalVariants.length > 0) &&
-      file.sites.every((site) => site.legacyLeft === 0) &&
-      file.functionalVariants.every((site) => site.converted)
-  )
-  const filesWithSites = files.filter(
-    (file) => file.sites.length > 0 || file.functionalVariants.length > 0
-  ).length
-  const blockedFiles = files
-    .filter(
-      (file) =>
-        file.sites.some((site) => site.legacyLeft > 0) ||
-        file.functionalVariants.some((site) => !site.converted)
-    )
-    .map((file) => file.file)
+  const touched = (file: FileReport) =>
+    file.sites.length > 0 ||
+    file.functionalVariants.length > 0 ||
+    file.sheetFrames.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)
+  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(),
@@ -119,6 +121,8 @@ export function renderReport(
     `- ${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`,
     '',
     '### Functional variant flag reasons',
     '',
@@ -128,7 +132,7 @@ export function renderReport(
     '',
     '### Remaining manual migration',
     '',
-    `${readyFiles.length} of ${filesWithSites} files have no legacy condition object or flagged functional variant left after`,
+    `${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(', ')
@@ -188,8 +192,30 @@ export function renderReport(
   }
 
   for (const file of files) {
-    if (!file.sites.length && !file.functionalVariants.length) continue
+    if (!touched(file)) continue
     lines.push('', `## \`${file.file}\``, '')
+    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'})`,
@@ -295,6 +321,8 @@ export function renderReport(
       functionalVariantConverted: convertedFunctionalVariants.length,
       functionalVariantFlagged: flaggedFunctionalVariants.length,
       functionalVariantFlags: Object.fromEntries(functionalFlagCounts),
+      sheetFrames: sheetFrames.length,
+      sheetFramesFlagged: flaggedSheetFrames.length,
     },
   }
 }