Migrate utilities in CSS files imported into layers (#14617)

When a stylesheet is imported with `@import “…” layer(utilities)` that
means that all classes in that stylesheet and any of its imported
stylesheets become candidates for `@utility` conversion.

Doing this correctly requires us to place `@utility` rules into separate
stylesheets (usually) and replicate the import tree without layers as
`@utility` MUST be root-level. If a file consists of only utilities we
won't create a separate file for it and instead place the `@utility`
rules in the same stylesheet.

Been doing a LOT of pairing with @RobinMalfait on this one but I think
this is finally ready to be looked at

---------

Co-authored-by: Robin Malfait <[email protected]>

Author: thecrypticace

integrations/upgrade/index.test.ts

@@ -41,6 +41,7 @@ interface TestContext {
     write(filePath: string, content: string): Promise<void>
     read(filePath: string): Promise<string>
     glob(pattern: string): Promise<[string, string][]>
+    dumpFiles(pattern: string): Promise<string>
     expectFileToContain(
       filePath: string,
       contents: string | string[] | RegExp | RegExp[],
@@ -113,7 +114,7 @@ export function test(
                   if (execOptions.ignoreStdErr !== true) console.error(stderr)
                   reject(error)
                 } else {
-                  resolve(stdout.toString())
+                  resolve(stdout.toString() + '\n\n' + stderr.toString())
                 }
               },
             )
@@ -306,6 +307,31 @@ export function test(
               }),
             )
           },
+          async dumpFiles(pattern: string) {
+            let files = await context.fs.glob(pattern)
+            return `\n${files
+              .slice()
+              .sort((a: [string], z: [string]) => {
+                let aParts = a[0].split('/')
+                let zParts = z[0].split('/')
+
+                let aFile = aParts.at(-1)
+                let zFile = aParts.at(-1)
+
+                // Sort by depth, shallow first
+                if (aParts.length < zParts.length) return -1
+                if (aParts.length > zParts.length) return 1
+
+                // Sort by filename, sort files named `index` before others
+                if (aFile?.startsWith('index')) return -1
+                if (zFile?.startsWith('index')) return 1
+
+                // Sort by filename, alphabetically
+                return a[0].localeCompare(z[0])
+              })
+              .map(([file, content]) => `--- ${file} ---\n${content || '<EMPTY>'}`)
+              .join('\n\n')}`
+          },
           async expectFileToContain(filePath, contents) {
             return retryAssertion(async () => {
               let fileContent = await this.read(filePath)

integrations/utils.ts

@@ -1,16 +1,40 @@
 import dedent from 'dedent'
 import postcss from 'postcss'
 import { describe, expect, it } from 'vitest'
+import { Stylesheet } from '../stylesheet'
 import { formatNodes } from './format-nodes'
 import { migrateAtLayerUtilities } from './migrate-at-layer-utilities'
 
 const css = dedent
 
-function migrate(input: string) {
+async function migrate(
+  data:
+    | string
+    | {
+        root: postcss.Root
+        layers?: string[]
+      },
+) {
+  let stylesheet: Stylesheet
+
+  if (typeof data === 'string') {
+    stylesheet = await Stylesheet.fromString(data)
+  } else {
+    stylesheet = await Stylesheet.fromRoot(data.root)
+
+    if (data.layers) {
+      let meta = { layers: data.layers }
+      let parent = await Stylesheet.fromString('.placeholder {}')
+
+      stylesheet.parents.add({ item: parent, meta })
+      parent.children.add({ item: stylesheet, meta })
+    }
+  }
+
   return postcss()
-    .use(migrateAtLayerUtilities())
+    .use(migrateAtLayerUtilities(stylesheet))
     .use(formatNodes())
-    .process(input, { from: expect.getState().testPath })
+    .process(stylesheet.root!, { from: expect.getState().testPath })
     .then((result) => result.css)
 }
 
@@ -820,3 +844,213 @@ it('should not lose attribute selectors', async () => {
     }"
   `)
 })
+
+describe('layered stylesheets', () => {
+  it('should transform classes to utilities inside a layered stylesheet (utilities)', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          /* Utility #1 */
+          .foo {
+            /* Declarations: */
+            color: red;
+          }
+        `),
+        layers: ['utilities'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "@utility foo {
+        /* Utility #1 */
+        /* Declarations: */
+        color: red;
+      }"
+    `)
+  })
+
+  it('should transform classes to utilities inside a layered stylesheet (components)', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          /* Utility #1 */
+          .foo {
+            /* Declarations: */
+            color: red;
+          }
+        `),
+        layers: ['components'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "@utility foo {
+        /* Utility #1 */
+        /* Declarations: */
+        color: red;
+      }"
+    `)
+  })
+
+  it('should NOT transform classes to utilities inside a non-utility, layered stylesheet', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          /* Utility #1 */
+          .foo {
+            /* Declarations: */
+            color: red;
+          }
+        `),
+        layers: ['foo'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "/* Utility #1 */
+      .foo {
+        /* Declarations: */
+        color: red;
+      }"
+    `)
+  })
+
+  it('should handle non-classes in utility-layered stylesheets', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          /* Utility #1 */
+          .foo {
+            /* Declarations: */
+            color: red;
+          }
+          #main {
+            color: red;
+          }
+        `),
+        layers: ['utilities'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "
+      #main {
+        color: red;
+      }
+
+      @utility foo {
+        /* Utility #1 */
+        /* Declarations: */
+        color: red;
+      }"
+    `)
+  })
+
+  it('should handle non-classes in utility-layered stylesheets', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          @layer utilities {
+            @layer utilities {
+              /* Utility #1 */
+              .foo {
+                /* Declarations: */
+                color: red;
+              }
+            }
+
+            /* Utility #2 */
+            .bar {
+              /* Declarations: */
+              color: red;
+            }
+
+            #main {
+              color: red;
+            }
+          }
+
+          /* Utility #3 */
+          .baz {
+            /* Declarations: */
+            color: red;
+          }
+
+          #secondary {
+            color: red;
+          }
+        `),
+        layers: ['utilities'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "@layer utilities {
+
+        #main {
+          color: red;
+        }
+      }
+
+      #secondary {
+        color: red;
+      }
+
+      @utility foo {
+        @layer utilities {
+          @layer utilities {
+            /* Utility #1 */
+            /* Declarations: */
+            color: red;
+          }
+        }
+      }
+
+      @utility bar {
+        @layer utilities {
+          /* Utility #2 */
+          /* Declarations: */
+          color: red;
+        }
+      }
+
+      @utility baz {
+        /* Utility #3 */
+        /* Declarations: */
+        color: red;
+      }"
+    `)
+  })
+
+  it('imports are preserved in layered stylesheets', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          @import 'thing';
+
+          .foo {
+            color: red;
+          }
+        `),
+        layers: ['utilities'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "@import 'thing';
+
+      @utility foo {
+        color: red;
+      }"
+    `)
+  })
+
+  it('charset is preserved in layered stylesheets', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          @charset "utf-8";
+
+          .foo {
+            color: red;
+          }
+        `),
+        layers: ['utilities'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "@charset "utf-8";
+
+      @utility foo {
+        color: red;
+      }"
+    `)
+  })
+})

packages/@tailwindcss-upgrade/src/codemods/migrate-at-layer-utilities.test.ts

@@ -1,9 +1,10 @@
 import { type AtRule, type Comment, type Plugin, type Rule } from 'postcss'
 import SelectorParser from 'postcss-selector-parser'
 import { segment } from '../../../tailwindcss/src/utils/segment'
+import { Stylesheet } from '../stylesheet'
 import { walk, WalkAction, walkDepth } from '../utils/walk'
 
-export function migrateAtLayerUtilities(): Plugin {
+export function migrateAtLayerUtilities(stylesheet: Stylesheet): Plugin {
   function migrate(atRule: AtRule) {
     // Only migrate `@layer utilities` and `@layer components`.
     if (atRule.params !== 'utilities' && atRule.params !== 'components') return
@@ -86,6 +87,12 @@ export function migrateAtLayerUtilities(): Plugin {
       clones.push(clone)
 
       walk(clone, (node) => {
+        if (node.type === 'atrule') {
+          if (!node.nodes || node.nodes?.length === 0) {
+            node.remove()
+          }
+        }
+
         if (node.type !== 'rule') return
 
         // Fan out each utility into its own rule.
@@ -186,7 +193,7 @@ export function migrateAtLayerUtilities(): Plugin {
 
       // Mark the node as pretty so that it gets formatted by Prettier later.
       clone.raws.tailwind_pretty = true
-      clone.raws.before += '\n\n'
+      clone.raws.before = `${clone.raws.before ?? ''}\n\n`
     }
 
     // Cleanup
@@ -259,7 +266,16 @@ export function migrateAtLayerUtilities(): Plugin {
 
   return {
     postcssPlugin: '@tailwindcss/upgrade/migrate-at-layer-utilities',
-    OnceExit: (root) => {
+    OnceExit: (root, { atRule }) => {
+      let layers = stylesheet.layers()
+      let isUtilityStylesheet = layers.has('utilities') || layers.has('components')
+
+      if (isUtilityStylesheet) {
+        let rule = atRule({ name: 'layer', params: 'utilities' })
+        rule.append(root.nodes)
+        root.append(rule)
+      }
+
       // Migrate `@layer utilities` and `@layer components` into `@utility`.
       // Using this instead of the visitor API in case we want to use
       // postcss-nesting in the future.
@@ -282,6 +298,17 @@ export function migrateAtLayerUtilities(): Plugin {
           }
         })
       }
+
+      // If the stylesheet is inside a layered import then we can remove the top-level layer directive we added
+      if (isUtilityStylesheet) {
+        root.each((node) => {
+          if (node.type !== 'atrule') return
+          if (node.name !== 'layer') return
+          if (node.params !== 'utilities') return
+
+          node.replaceWith(node.nodes ?? [])
+        })
+      }
     },
   }
 }

packages/@tailwindcss-upgrade/src/codemods/migrate-at-layer-utilities.ts

@@ -71,6 +71,7 @@ export function migrateMissingLayers(): Plugin {
         if (node.name === 'import') {
           if (lastLayer !== '' && !node.params.includes('layer(')) {
             node.params += ` layer(${lastLayer})`
+            node.raws.tailwind_injected_layer = true
           }
 
           if (bucket.length > 0) {
@@ -110,7 +111,7 @@ export function migrateMissingLayers(): Plugin {
       let target = nodes[0]
       let layerNode = new AtRule({
         name: 'layer',
-        params: layerName || firstLayerName || '',
+        params: targetLayerName,
         nodes: nodes.map((node) => {
           // Keep the target node as-is, because we will be replacing that one
           // with the new layer node.