Extract Stylesheet class

The purpose of the `Stylesheet` class is to collect and hold relevant information about CSS files that can be used for more advanced transformations.

Additionally this unlocks two things:
- Formatting only happens after all transformations have completed
- Files are only written once at the end — which will simplify the introduction of a `--dry-run` option in the future

Author: thecrypticace

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

@@ -1,16 +1,21 @@
 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) {
+  let stylesheet: Stylesheet
+
+  stylesheet = await Stylesheet.fromString(data)
+
   return postcss()
     .use(migrateAtLayerUtilities())
     .use(formatNodes())
-    .process(input, { from: expect.getState().testPath })
+    .process(stylesheet.root!, { from: expect.getState().testPath })
     .then((result) => result.css)
 }
 

packages/@tailwindcss-upgrade/src/index.test.ts

@@ -1,6 +1,8 @@
 import { __unstable__loadDesignSystem } from '@tailwindcss/node'
 import dedent from 'dedent'
+import postcss from 'postcss'
 import { expect, it } from 'vitest'
+import { formatNodes } from './codemods/format-nodes'
 import { migrateContents } from './migrate'
 
 const css = dedent
@@ -13,9 +15,15 @@ let designSystem = await __unstable__loadDesignSystem(
 )
 let config = { designSystem, userConfig: {}, newPrefix: null }
 
+function migrate(input: string, config: any) {
+  return migrateContents(input, config, expect.getState().testPath)
+    .then((result) => postcss([formatNodes()]).process(result.root, result.opts))
+    .then((result) => result.css)
+}
+
 it('should print the input as-is', async () => {
   expect(
-    await migrateContents(
+    await migrate(
       css`
         /* above */
         .foo/* after */ {
@@ -25,7 +33,6 @@ it('should print the input as-is', async () => {
         }
       `,
       config,
-      expect.getState().testPath,
     ),
   ).toMatchInlineSnapshot(`
     "/* above */
@@ -39,7 +46,7 @@ it('should print the input as-is', async () => {
 
 it('should migrate a stylesheet', async () => {
   expect(
-    await migrateContents(
+    await migrate(
       css`
         @tailwind base;
 
@@ -116,7 +123,7 @@ it('should migrate a stylesheet', async () => {
 
 it('should migrate a stylesheet (with imports)', async () => {
   expect(
-    await migrateContents(
+    await migrate(
       css`
         @import 'tailwindcss/base';
         @import './my-base.css';
@@ -137,7 +144,7 @@ it('should migrate a stylesheet (with imports)', async () => {
 
 it('should migrate a stylesheet (with preceding rules that should be wrapped in an `@layer`)', async () => {
   expect(
-    await migrateContents(
+    await migrate(
       css`
         @charset "UTF-8";
         @layer foo, bar, baz;
@@ -166,7 +173,7 @@ it('should migrate a stylesheet (with preceding rules that should be wrapped in
 
 it('should keep CSS as-is before existing `@layer` at-rules', async () => {
   expect(
-    await migrateContents(
+    await migrate(
       css`
         .foo {
           color: blue;

packages/@tailwindcss-upgrade/src/index.ts

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 
 import { globby } from 'globby'
+import fs from 'node:fs/promises'
 import path from 'node:path'
+import postcss from 'postcss'
+import { formatNodes } from './codemods/format-nodes'
 import { help } from './commands/help'
 import { migrate as migrateStylesheet } from './migrate'
 import { migratePostCSSConfig } from './migrate-postcss'
+import { Stylesheet } from './stylesheet'
 import { migrate as migrateTemplate } from './template/migrate'
 import { prepareConfig } from './template/prepare-config'
 import { args, type Arg } from './utils/args'
@@ -94,8 +98,42 @@ async function run() {
     // Ensure we are only dealing with CSS files
     files = files.filter((file) => file.endsWith('.css'))
 
+    // Analyze the stylesheets
+    let loadResults = await Promise.allSettled(files.map((filepath) => Stylesheet.load(filepath)))
+
+    // Load and parse all stylesheets
+    for (let result of loadResults) {
+      if (result.status === 'rejected') {
+        error(`${result.reason}`)
+      }
+    }
+
+    let stylesheets = loadResults
+      .filter((result) => result.status === 'fulfilled')
+      .map((result) => result.value)
+
     // Migrate each file
-    await Promise.allSettled(files.map((file) => migrateStylesheet(file, config)))
+    let migrateResults = await Promise.allSettled(
+      stylesheets.map((sheet) => migrateStylesheet(sheet, config)),
+    )
+
+    for (let result of migrateResults) {
+      if (result.status === 'rejected') {
+        error(`${result.reason}`)
+      }
+    }
+
+    // Format nodes
+    for (let sheet of stylesheets) {
+      await postcss([formatNodes()]).process(sheet.root!, { from: sheet.file! })
+    }
+
+    // Write all files to disk
+    for (let sheet of stylesheets) {
+      if (!sheet.file) continue
+
+      await fs.writeFile(sheet.file, sheet.root.toString())
+    }
 
     success('Stylesheet migration complete.')
   }

packages/@tailwindcss-upgrade/src/migrate.ts

@@ -1,36 +1,42 @@
-import fs from 'node:fs/promises'
-import path from 'node:path'
 import postcss from 'postcss'
 import type { Config } from 'tailwindcss'
 import type { DesignSystem } from '../../tailwindcss/src/design-system'
-import { formatNodes } from './codemods/format-nodes'
 import { migrateAtApply } from './codemods/migrate-at-apply'
 import { migrateAtLayerUtilities } from './codemods/migrate-at-layer-utilities'
 import { migrateMediaScreen } from './codemods/migrate-media-screen'
 import { migrateMissingLayers } from './codemods/migrate-missing-layers'
 import { migrateTailwindDirectives } from './codemods/migrate-tailwind-directives'
+import { Stylesheet } from './stylesheet'
 
 export interface MigrateOptions {
   newPrefix: string | null
   designSystem: DesignSystem
   userConfig: Config
 }
 
-export async function migrateContents(contents: string, options: MigrateOptions, file?: string) {
+export async function migrateContents(
+  stylesheet: Stylesheet | string,
+  options: MigrateOptions,
+  file?: string,
+) {
+  if (typeof stylesheet === 'string') {
+    stylesheet = await Stylesheet.fromString(stylesheet)
+    stylesheet.file = file ?? null
+  }
+
   return postcss()
     .use(migrateAtApply(options))
     .use(migrateMediaScreen(options))
     .use(migrateAtLayerUtilities())
     .use(migrateMissingLayers())
     .use(migrateTailwindDirectives(options))
-    .use(formatNodes())
-    .process(contents, { from: file })
-    .then((result) => result.css)
+    .process(stylesheet.root, { from: stylesheet.file ?? undefined })
 }
 
-export async function migrate(file: string, options: MigrateOptions) {
-  let fullPath = path.resolve(process.cwd(), file)
-  let contents = await fs.readFile(fullPath, 'utf-8')
+export async function migrate(stylesheet: Stylesheet, options: MigrateOptions) {
+  if (!stylesheet.file) {
+    throw new Error('Cannot migrate a stylesheet without a file path')
+  }
 
-  await fs.writeFile(fullPath, await migrateContents(contents, options, fullPath))
+  await migrateContents(stylesheet, options)
 }

packages/@tailwindcss-upgrade/src/stylesheet.ts

@@ -0,0 +1,51 @@
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import * as util from 'node:util'
+import * as postcss from 'postcss'
+
+export type StylesheetId = string
+
+export class Stylesheet {
+  /**
+   * The PostCSS AST that represents this stylesheet.
+   */
+  root: postcss.Root
+
+  /**
+   * The path to the file that this stylesheet was loaded from.
+   *
+   * If this stylesheet was not loaded from a file this will be `null`.
+   */
+  file: string | null = null
+
+  static async load(filepath: string) {
+    filepath = path.resolve(process.cwd(), filepath)
+
+    let css = await fs.readFile(filepath, 'utf-8')
+    let root = postcss.parse(css, { from: filepath })
+
+    return new Stylesheet(root, filepath)
+  }
+
+  static async fromString(css: string) {
+    let root = postcss.parse(css)
+
+    return new Stylesheet(root)
+  }
+
+  static async fromRoot(root: postcss.Root, file?: string) {
+    return new Stylesheet(root, file)
+  }
+
+  constructor(root: postcss.Root, file?: string) {
+    this.root = root
+    this.file = file ?? null
+  }
+
+  [util.inspect.custom]() {
+    return {
+      ...this,
+      root: this.root.toString(),
+    }
+  }
+}