Improve performance of cloning AST nodes (#19067)

This PR improves the performance of when we need to clone some AST
nodes. We have a few places where we clone `Candidate`, `Variant` and
CSS `AST` nodes.

Right now we use `structuredClone`, which works, but it is a generic
solution. However, we do know the exact structure of these AST nodes, so
we can write specialized clone functions that are much faster.

## Test plan

1. All the tests still pass with this change
2. The performance is better:

```
  cloneCandidate - src/candidate.bench.ts > Candidate cloning
    1.72x faster than cloneCandidate (spread)
    74.03x faster than structuredClone

  cloneAstNode() - src/ast.bench.ts > Cloning AST nodes
    1.15x faster than cloneAstNode (with spread)
    33.54x faster than structuredClone()
```

Ready for review, but should be merged after #19059

Author: RobinMalfait

packages/@tailwindcss-upgrade/src/codemods/template/candidates.ts

@@ -1,5 +1,5 @@
 import { Scanner } from '@tailwindcss/oxide'
-import type { Candidate } from '../../../../tailwindcss/src/candidate'
+import { cloneCandidate, type Candidate } from '../../../../tailwindcss/src/candidate'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
 
 export async function extractRawCandidates(
@@ -18,7 +18,7 @@ export async function extractRawCandidates(
 
 // Create a basic stripped candidate without variants or important flag
 export function baseCandidate<T extends Candidate>(candidate: T) {
-  let base = structuredClone(candidate)
+  let base = cloneCandidate(candidate)
 
   base.important = false
   base.variants = []

packages/@tailwindcss-upgrade/src/codemods/template/migrate-arbitrary-variants.ts

@@ -1,3 +1,4 @@
+import { cloneCandidate } from '../../../../tailwindcss/src/candidate'
 import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
 import {
@@ -22,7 +23,7 @@ export function migrateArbitraryVariants(
 
     // The below logic makes use of mutation. Since candidates in the
     // DesignSystem are cached, we can't mutate them directly.
-    let candidate = structuredClone(readonlyCandidate) as Writable<typeof readonlyCandidate>
+    let candidate = cloneCandidate(readonlyCandidate) as Writable<typeof readonlyCandidate>
 
     for (let [variant] of walkVariants(candidate)) {
       if (variant.kind === 'compound') continue

packages/@tailwindcss-upgrade/src/codemods/template/migrate-automatic-var-injection.ts

@@ -1,7 +1,8 @@
 import { walk, WalkAction } from '../../../../tailwindcss/src/ast'
-import { type Candidate, type Variant } from '../../../../tailwindcss/src/candidate'
+import { cloneCandidate, type Candidate, type Variant } from '../../../../tailwindcss/src/candidate'
 import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
+import type { Writable } from '../../../../tailwindcss/src/types'
 import * as ValueParser from '../../../../tailwindcss/src/value-parser'
 
 export function migrateAutomaticVarInjection(
@@ -12,7 +13,7 @@ export function migrateAutomaticVarInjection(
   for (let readonlyCandidate of designSystem.parseCandidate(rawCandidate)) {
     // The below logic makes extended use of mutation. Since candidates in the
     // DesignSystem are cached, we can't mutate them directly.
-    let candidate = structuredClone(readonlyCandidate) as Candidate
+    let candidate = cloneCandidate(readonlyCandidate) as Writable<Candidate>
 
     let didChange = false
 

packages/@tailwindcss-upgrade/src/codemods/template/migrate-camelcase-in-named-value.ts

@@ -1,3 +1,4 @@
+import { cloneCandidate } from '../../../../tailwindcss/src/candidate'
 import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
 import * as version from '../../utils/version'
@@ -15,7 +16,7 @@ export function migrateCamelcaseInNamedValue(
 
   for (let candidate of designSystem.parseCandidate(rawCandidate)) {
     if (candidate.kind !== 'functional') continue
-    let clone = structuredClone(candidate)
+    let clone = cloneCandidate(candidate)
     let didChange = false
 
     if (

packages/@tailwindcss-upgrade/src/codemods/template/migrate-legacy-arbitrary-values.ts

@@ -1,4 +1,4 @@
-import { parseCandidate } from '../../../../tailwindcss/src/candidate'
+import { cloneCandidate, parseCandidate } from '../../../../tailwindcss/src/candidate'
 import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
 import { segment } from '../../../../tailwindcss/src/utils/segment'
@@ -9,7 +9,7 @@ export function migrateLegacyArbitraryValues(
   rawCandidate: string,
 ): string {
   for (let candidate of parseCandidate(rawCandidate, designSystem)) {
-    let clone = structuredClone(candidate)
+    let clone = cloneCandidate(candidate)
     let changed = false
 
     // Convert commas to spaces. E.g.: [auto,1fr] to [auto_1fr]

packages/@tailwindcss-upgrade/src/codemods/template/migrate-legacy-classes.ts

@@ -1,7 +1,7 @@
 import { __unstable__loadDesignSystem } from '@tailwindcss/node'
 import path from 'node:path'
 import url from 'node:url'
-import type { Candidate } from '../../../../tailwindcss/src/candidate'
+import { cloneCandidate, type Candidate } from '../../../../tailwindcss/src/candidate'
 import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
 import { DefaultMap } from '../../../../tailwindcss/src/utils/default-map'
@@ -100,7 +100,7 @@ export async function migrateLegacyClasses(
 
       // Re-apply the variants and important flag from the original candidate.
       // E.g.: `hover:blur!` -> `blur` -> `blur-sm` -> `hover:blur-sm!`
-      let newCandidate = structuredClone(newBaseCandidate) as Candidate
+      let newCandidate = cloneCandidate(newBaseCandidate) as Candidate
       newCandidate.variants = candidate.variants
       newCandidate.important = candidate.important
 

packages/@tailwindcss-upgrade/src/codemods/template/migrate-modernize-arbitrary-values.ts

@@ -1,4 +1,4 @@
-import { parseCandidate } from '../../../../tailwindcss/src/candidate'
+import { cloneCandidate, parseCandidate } from '../../../../tailwindcss/src/candidate'
 import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
 import { replaceObject } from '../../../../tailwindcss/src/utils/replace-object'
@@ -10,7 +10,7 @@ export function migrateModernizeArbitraryValues(
   rawCandidate: string,
 ): string {
   for (let candidate of parseCandidate(rawCandidate, designSystem)) {
-    let clone = structuredClone(candidate)
+    let clone = cloneCandidate(candidate)
     let changed = false
 
     for (let [variant] of walkVariants(clone)) {

packages/tailwindcss/src/apply.ts

@@ -1,5 +1,5 @@
 import { Features } from '.'
-import { rule, toCss, walk, WalkAction, type AstNode } from './ast'
+import { cloneAstNode, rule, toCss, walk, WalkAction, type AstNode } from './ast'
 import { compileCandidates } from './compile'
 import type { DesignSystem } from './design-system'
 import type { SourceLocation } from './source-maps/source'
@@ -249,7 +249,7 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
           let candidate = compiled.nodeSorting.get(node)?.candidate
           let candidateOffset = candidate ? candidateOffsets[candidate] : undefined
 
-          node = structuredClone(node)
+          node = cloneAstNode(node)
 
           if (!src || !candidate || candidateOffset === undefined) {
             // While the original nodes may have come from an `@utility` we still

packages/tailwindcss/src/ast.bench.ts

@@ -1,5 +1,5 @@
-import { bench } from 'vitest'
-import { toCss } from './ast'
+import { bench, describe } from 'vitest'
+import { cloneAstNode, toCss, type AstNode } from './ast'
 import * as CSS from './css-parser'
 
 const css = String.raw
@@ -19,10 +19,46 @@ const input = css`
 `
 const ast = CSS.parse(input)
 
-bench('toCss', () => {
-  toCss(ast)
+describe('AST to CSS', () => {
+  bench('toCss', () => {
+    toCss(ast)
+  })
+
+  bench('toCss with source maps', () => {
+    toCss(ast, true)
+  })
 })
 
-bench('toCss with source maps', () => {
-  toCss(ast, true)
+describe('Cloning AST nodes', () => {
+  bench('cloneAstNode()', () => {
+    ast.map(cloneAstNode)
+  })
+
+  bench('cloneAstNode (with spread)', () => {
+    ast.map(cloneAstNodeSpread)
+  })
+
+  bench('structuredClone()', () => {
+    structuredClone(ast)
+  })
 })
+
+function cloneAstNodeSpread<T extends AstNode>(node: T): T {
+  switch (node.kind) {
+    case 'rule':
+    case 'at-rule':
+    case 'at-root':
+      return { ...node, nodes: node.nodes.map(cloneAstNodeSpread) }
+
+    case 'context':
+      return { ...node, context: { ...node.context }, nodes: node.nodes.map(cloneAstNodeSpread) }
+
+    case 'declaration':
+    case 'comment':
+      return { ...node }
+
+    default:
+      node satisfies never
+      throw new Error(`Unknown node kind: ${(node as any).kind}`)
+  }
+}

packages/tailwindcss/src/ast.ts

@@ -122,6 +122,68 @@ export function atRoot(nodes: AstNode[]): AtRoot {
   }
 }
 
+export function cloneAstNode<T extends AstNode>(node: T): T {
+  switch (node.kind) {
+    case 'rule':
+      return {
+        kind: node.kind,
+        selector: node.selector,
+        nodes: node.nodes.map(cloneAstNode),
+        src: node.src,
+        dst: node.dst,
+      } satisfies StyleRule as T
+
+    case 'at-rule':
+      return {
+        kind: node.kind,
+        name: node.name,
+        params: node.params,
+        nodes: node.nodes.map(cloneAstNode),
+        src: node.src,
+        dst: node.dst,
+      } satisfies AtRule as T
+
+    case 'at-root':
+      return {
+        kind: node.kind,
+        nodes: node.nodes.map(cloneAstNode),
+        src: node.src,
+        dst: node.dst,
+      } satisfies AtRoot as T
+
+    case 'context':
+      return {
+        kind: node.kind,
+        context: { ...node.context },
+        nodes: node.nodes.map(cloneAstNode),
+        src: node.src,
+        dst: node.dst,
+      } satisfies Context as T
+
+    case 'declaration':
+      return {
+        kind: node.kind,
+        property: node.property,
+        value: node.value,
+        important: node.important,
+        src: node.src,
+        dst: node.dst,
+      } satisfies Declaration as T
+
+    case 'comment':
+      return {
+        kind: node.kind,
+        value: node.value,
+        src: node.src,
+        dst: node.dst,
+      } satisfies Comment as T
+
+    default:
+      node satisfies never
+      throw new Error(`Unknown node kind: ${(node as any).kind}`)
+  }
+}
+
 export const enum WalkAction {
   /** Continue walking, which is the default */
   Continue,