Internal refactor, introduce AtRule (#14802)

This PR introduces an internal refactor where we introduce the `AtRule`
CSS Node in our AST.

The motivation for this is that in a lot of places we need to
differentiate between a `Rule` and an `AtRule`. We often do this with
code that looks like this:

```ts
rule.selector[0] === '@' && rule.selector.startsWith('@media')
```

Another issue we have is that we often need to check for `'@media '`
including the space, because we don't want to match `@mediafoobar` if
somebody has this in their CSS. Alternatively, if you CSS is minified
then it could be that you have a rule that looks like
`@media(width>=100px)`, in this case we _also_ have to check for
`@media(`.

Here is a snippet of code that we have in our codebase:

```ts
// Find at-rules rules
if (node.kind === 'rule') {
  if (
    node.selector[0] === '@' &&
    (node.selector.startsWith('@media ') ||
      node.selector.startsWith('@media(') ||
      node.selector.startsWith('@Custom-Media ') ||
      node.selector.startsWith('@Custom-Media(') ||
      node.selector.startsWith('@container ') ||
      node.selector.startsWith('@container(') ||
      node.selector.startsWith('@supports ') ||
      node.selector.startsWith('@supports(')) &&
    node.selector.includes(THEME_FUNCTION_INVOCATION)
  ) {
    node.selector = substituteFunctionsInValue(node.selector, resolveThemeValue)
  }
}
```

Which will now be replaced with a much simpler version:
```ts
// Find at-rules rules
if (node.kind === 'at-rule') {
  if (
    (node.name === '@media' ||
      node.name === '@Custom-Media' ||
      node.name === '@container' ||
      node.name === '@supports') &&
    node.params.includes(THEME_FUNCTION_INVOCATION)
  ) {
    node.params = substituteFunctionsInValue(node.params, resolveThemeValue)
  }
}
```

Checking for all the cases from the first snippet is not the end of the
world, but it is error prone. It's easy to miss a case.

A direct comparison is also faster than comparing via the
`startsWith(…)` function.

---

Note: this is only a refactor without changing other code _unless_ it
was required to make the tests pass. The tests themselves are all
passing and none of them changed (because the behavior should be the
same).
The one exception is the tests where we check the parsed AST, which now
includes `at-rule` nodes instead of `rule` nodes when we have an
at-rule.

Author: RobinMalfait

packages/@tailwindcss-upgrade/src/template/codemods/variant-order.ts

@@ -57,16 +57,14 @@ function isAtRuleVariant(designSystem: DesignSystem, variant: Variant) {
     return true
   }
   let stack = getAppliedNodeStack(designSystem, variant)
-  return stack.every((node) => node.kind === 'rule' && node.selector[0] === '@')
+  return stack.every((node) => node.kind === 'at-rule')
 }
 
 function isCombinatorVariant(designSystem: DesignSystem, variant: Variant) {
   let stack = getAppliedNodeStack(designSystem, variant)
   return stack.some(
     (node) =>
       node.kind === 'rule' &&
-      // Ignore at-rules as they are hoisted
-      node.selector[0] !== '@' &&
       // Combinators include any of the following characters
       (node.selector.includes(' ') ||
         node.selector.includes('>') ||

packages/@tailwindcss-upgrade/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "extends": "../tsconfig.base.json",
   "compilerOptions": {
-    "allowSyntheticDefaultImports":true
-  }
+    "allowSyntheticDefaultImports": true,
+  },
 }

packages/tailwindcss/src/apply.ts

@@ -5,28 +5,21 @@ import { escape } from './utils/escape'
 
 export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
   walk(ast, (node, { replaceWith }) => {
-    if (node.kind !== 'rule') return
+    if (node.kind !== 'at-rule') return
 
     // Do not allow `@apply` rules inside `@keyframes` rules.
-    if (node.selector[0] === '@' && node.selector.startsWith('@keyframes')) {
+    if (node.name === '@keyframes') {
       walk(node.nodes, (child) => {
-        if (
-          child.kind === 'rule' &&
-          child.selector[0] === '@' &&
-          child.selector.startsWith('@apply ')
-        ) {
+        if (child.kind === 'at-rule' && child.name === '@apply') {
           throw new Error(`You cannot use \`@apply\` inside \`@keyframes\`.`)
         }
       })
       return WalkAction.Skip
     }
 
-    if (!(node.selector[0] === '@' && node.selector.startsWith('@apply '))) return
+    if (node.name !== '@apply') return
 
-    let candidates = node.selector
-      .slice(7 /* Ignore `@apply ` when parsing the selector */)
-      .trim()
-      .split(/\s+/g)
+    let candidates = node.params.split(/\s+/g)
 
     // Replace the `@apply` rule with the actual utility classes
     {
@@ -43,7 +36,7 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
       // don't want the wrapping selector.
       let newNodes: AstNode[] = []
       for (let candidateNode of candidateAst) {
-        if (candidateNode.kind === 'rule' && candidateNode.selector[0] !== '@') {
+        if (candidateNode.kind === 'rule') {
           for (let child of candidateNode.nodes) {
             newNodes.push(child)
           }

packages/tailwindcss/src/ast.test.ts

@@ -1,5 +1,5 @@
 import { expect, it } from 'vitest'
-import { context, decl, rule, toCss, walk } from './ast'
+import { context, decl, styleRule, toCss, walk } from './ast'
 import * as CSS from './css-parser'
 
 it('should pretty print an AST', () => {
@@ -16,13 +16,13 @@ it('should pretty print an AST', () => {
 
 it('allows the placement of context nodes', () => {
   const ast = [
-    rule('.foo', [decl('color', 'red')]),
+    styleRule('.foo', [decl('color', 'red')]),
     context({ context: 'a' }, [
-      rule('.bar', [
+      styleRule('.bar', [
         decl('color', 'blue'),
         context({ context: 'b' }, [
           //
-          rule('.baz', [decl('color', 'green')]),
+          styleRule('.baz', [decl('color', 'green')]),
         ]),
       ]),
     ]),

packages/tailwindcss/src/ast.ts

@@ -1,9 +1,20 @@
-export type Rule = {
+import { parseAtRule } from './css-parser'
+
+const AT_SIGN = 0x40
+
+export type StyleRule = {
   kind: 'rule'
   selector: string
   nodes: AstNode[]
 }
 
+export type AtRule = {
+  kind: 'at-rule'
+  name: string
+  params: string
+  nodes: AstNode[]
+}
+
 export type Declaration = {
   kind: 'declaration'
   property: string
@@ -27,16 +38,34 @@ export type AtRoot = {
   nodes: AstNode[]
 }
 
-export type AstNode = Rule | Declaration | Comment | Context | AtRoot
+export type Rule = StyleRule | AtRule
+export type AstNode = StyleRule | AtRule | Declaration | Comment | Context | AtRoot
 
-export function rule(selector: string, nodes: AstNode[]): Rule {
+export function styleRule(selector: string, nodes: AstNode[] = []): StyleRule {
   return {
     kind: 'rule',
     selector,
     nodes,
   }
 }
 
+export function atRule(name: string, params: string = '', nodes: AstNode[] = []): AtRule {
+  return {
+    kind: 'at-rule',
+    name,
+    params,
+    nodes,
+  }
+}
+
+export function rule(selector: string, nodes: AstNode[] = []): StyleRule | AtRule {
+  if (selector.charCodeAt(0) === AT_SIGN) {
+    return parseAtRule(selector, nodes)
+  }
+
+  return styleRule(selector, nodes)
+}
+
 export function decl(property: string, value: string | undefined): Declaration {
   return {
     kind: 'declaration',
@@ -126,7 +155,7 @@ export function walk(
     // Skip visiting the children of this node
     if (status === WalkAction.Skip) continue
 
-    if (node.kind === 'rule') {
+    if (node.kind === 'rule' || node.kind === 'at-rule') {
       walk(node.nodes, visit, path, context)
     }
   }
@@ -152,7 +181,7 @@ export function walkDepth(
     let path = [...parentPath, node]
     let parent = parentPath.at(-1) ?? null
 
-    if (node.kind === 'rule') {
+    if (node.kind === 'rule' || node.kind === 'at-rule') {
       walkDepth(node.nodes, visit, path, context)
     } else if (node.kind === 'context') {
       walkDepth(node.nodes, visit, parentPath, { ...context, ...node.context })
@@ -185,7 +214,16 @@ export function toCss(ast: AstNode[]) {
 
     // Rule
     if (node.kind === 'rule') {
-      if (node.selector === '@tailwind utilities') {
+      css += `${indent}${node.selector} {\n`
+      for (let child of node.nodes) {
+        css += stringify(child, depth + 1)
+      }
+      css += `${indent}}\n`
+    }
+
+    // AtRule
+    else if (node.kind === 'at-rule') {
+      if (node.name === '@tailwind' && node.params === 'utilities') {
         for (let child of node.nodes) {
           css += stringify(child, depth)
         }
@@ -199,20 +237,21 @@ export function toCss(ast: AstNode[]) {
       // ```css
       // @layer base, components, utilities;
       // ```
-      if (node.selector[0] === '@' && node.nodes.length === 0) {
-        return `${indent}${node.selector};\n`
+      else if (node.nodes.length === 0) {
+        return `${indent}${node.name} ${node.params};\n`
       }
 
-      if (node.selector[0] === '@' && node.selector.startsWith('@property ') && depth === 0) {
+      //
+      else if (node.name === '@property' && depth === 0) {
         // Don't output duplicate `@property` rules
-        if (seenAtProperties.has(node.selector)) {
+        if (seenAtProperties.has(node.params)) {
           return ''
         }
 
         // Collect fallbacks for `@property` rules for Firefox support
         // We turn these into rules on `:root` or `*` and some pseudo-elements
         // based on the value of `inherits``
-        let property = node.selector.replace(/@property\s*/g, '')
+        let property = node.params
         let initialValue = null
         let inherits = false
 
@@ -231,10 +270,10 @@ export function toCss(ast: AstNode[]) {
           propertyFallbacksUniversal.push(decl(property, initialValue ?? 'initial'))
         }
 
-        seenAtProperties.add(node.selector)
+        seenAtProperties.add(node.params)
       }
 
-      css += `${indent}${node.selector} {\n`
+      css += `${indent}${node.name}${node.params ? ` ${node.params} ` : ' '}{\n`
       for (let child of node.nodes) {
         css += stringify(child, depth + 1)
       }
@@ -292,7 +331,7 @@ export function toCss(ast: AstNode[]) {
 
   if (fallbackAst.length) {
     fallback = stringify(
-      rule('@supports (-moz-orient: inline)', [rule('@layer base', fallbackAst)]),
+      atRule('@supports', '(-moz-orient: inline)', [atRule('@layer', 'base', fallbackAst)]),
     )
   }
 

packages/tailwindcss/src/at-import.ts

@@ -1,4 +1,4 @@
-import { context, rule, walk, WalkAction, type AstNode } from './ast'
+import { atRule, context, walk, WalkAction, type AstNode } from './ast'
 import * as CSS from './css-parser'
 import * as ValueParser from './value-parser'
 
@@ -13,15 +13,9 @@ export async function substituteAtImports(
   let promises: Promise<void>[] = []
 
   walk(ast, (node, { replaceWith }) => {
-    if (
-      node.kind === 'rule' &&
-      node.selector[0] === '@' &&
-      node.selector.toLowerCase().startsWith('@import ')
-    ) {
+    if (node.kind === 'at-rule' && node.name === '@import') {
       try {
-        let { uri, layer, media, supports } = parseImportParams(
-          ValueParser.parse(node.selector.slice(8)),
-        )
+        let { uri, layer, media, supports } = parseImportParams(ValueParser.parse(node.params))
 
         // Skip importing data or remote URIs
         if (uri.startsWith('data:')) return
@@ -132,15 +126,15 @@ function buildImportNodes(
   let root = importedAst
 
   if (layer !== null) {
-    root = [rule('@layer ' + layer, root)]
+    root = [atRule('@layer', layer, root)]
   }
 
   if (media !== null) {
-    root = [rule('@media ' + media, root)]
+    root = [atRule('@media', media, root)]
   }
 
   if (supports !== null) {
-    root = [rule(`@supports ${supports[0] === '(' ? supports : `(${supports})`}`, root)]
+    root = [atRule('@supports', supports[0] === '(' ? supports : `(${supports})`, root)]
   }
 
   return root

packages/tailwindcss/src/compat/apply-compat-hooks.ts

@@ -1,4 +1,4 @@
-import { rule, toCss, walk, WalkAction, type AstNode } from '../ast'
+import { styleRule, toCss, walk, WalkAction, type AstNode } from '../ast'
 import type { DesignSystem } from '../design-system'
 import { segment } from '../utils/segment'
 import { applyConfigToTheme } from './apply-config-to-theme'
@@ -34,15 +34,15 @@ export async function applyCompatibilityHooks({
   let configPaths: { id: string; base: string }[] = []
 
   walk(ast, (node, { parent, replaceWith, context }) => {
-    if (node.kind !== 'rule' || node.selector[0] !== '@') return
+    if (node.kind !== 'at-rule') return
 
     // Collect paths from `@plugin` at-rules
-    if (node.selector === '@plugin' || node.selector.startsWith('@plugin ')) {
+    if (node.name === '@plugin') {
       if (parent !== null) {
         throw new Error('`@plugin` cannot be nested.')
       }
 
-      let pluginPath = node.selector.slice(9, -1)
+      let pluginPath = node.params.slice(1, -1)
       if (pluginPath.length === 0) {
         throw new Error('`@plugin` must have a path.')
       }
@@ -100,7 +100,7 @@ export async function applyCompatibilityHooks({
     }
 
     // Collect paths from `@config` at-rules
-    if (node.selector === '@config' || node.selector.startsWith('@config ')) {
+    if (node.name === '@config') {
       if (node.nodes.length > 0) {
         throw new Error('`@config` cannot have a body.')
       }
@@ -109,7 +109,7 @@ export async function applyCompatibilityHooks({
         throw new Error('`@config` cannot be nested.')
       }
 
-      configPaths.push({ id: node.selector.slice(9, -1), base: context.base })
+      configPaths.push({ id: node.params.slice(1, -1), base: context.base })
       replaceWith([])
       return
     }
@@ -268,15 +268,15 @@ function upgradeToFullPluginSupport({
     let wrappingSelector = resolvedConfig.important
 
     walk(ast, (node, { replaceWith, parent }) => {
-      if (node.kind !== 'rule') return
-      if (node.selector !== '@tailwind utilities') return
+      if (node.kind !== 'at-rule') return
+      if (node.name !== '@tailwind' || node.params !== 'utilities') return
 
       // The AST node was already manually wrapped so there's nothing to do
       if (parent?.kind === 'rule' && parent.selector === wrappingSelector) {
         return WalkAction.Stop
       }
 
-      replaceWith(rule(wrappingSelector, [node]))
+      replaceWith(styleRule(wrappingSelector, [node]))
 
       return WalkAction.Stop
     })

packages/tailwindcss/src/compat/apply-keyframes-to-theme.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from 'vitest'
-import { decl, rule, toCss } from '../ast'
+import { atRule, decl, styleRule, toCss } from '../ast'
 import { buildDesignSystem } from '../design-system'
 import { Theme } from '../theme'
 import { applyKeyframesToTheme } from './apply-keyframes-to-theme'
@@ -58,15 +58,15 @@ test('will append to the default keyframes with new keyframes', () => {
   let design = buildDesignSystem(theme)
 
   theme.addKeyframes(
-    rule('@keyframes slide-in', [
-      rule('from', [decl('opacity', 'translateX(0%)')]),
-      rule('to', [decl('opacity', 'translateX(100%)')]),
+    atRule('@keyframes', 'slide-in', [
+      styleRule('from', [decl('opacity', 'translateX(0%)')]),
+      styleRule('to', [decl('opacity', 'translateX(100%)')]),
     ]),
   )
   theme.addKeyframes(
-    rule('@keyframes slide-out', [
-      rule('from', [decl('opacity', 'translateX(100%)')]),
-      rule('to', [decl('opacity', 'translateX(0%)')]),
+    atRule('@keyframes', 'slide-out', [
+      styleRule('from', [decl('opacity', 'translateX(100%)')]),
+      styleRule('to', [decl('opacity', 'translateX(0%)')]),
     ]),
   )
 

packages/tailwindcss/src/compat/apply-keyframes-to-theme.ts

@@ -1,4 +1,4 @@
-import { rule, type Rule } from '../ast'
+import { atRule, type AtRule } from '../ast'
 import type { DesignSystem } from '../design-system'
 import type { ResolvedConfig } from './config/types'
 import { objectToAst } from './plugin-api'
@@ -13,11 +13,11 @@ export function applyKeyframesToTheme(
   }
 }
 
-export function keyframesToRules(resolvedConfig: Pick<ResolvedConfig, 'theme'>): Rule[] {
-  let rules: Rule[] = []
+export function keyframesToRules(resolvedConfig: Pick<ResolvedConfig, 'theme'>): AtRule[] {
+  let rules: AtRule[] = []
   if ('keyframes' in resolvedConfig.theme) {
     for (let [name, keyframe] of Object.entries(resolvedConfig.theme.keyframes)) {
-      rules.push(rule(`@keyframes ${name}`, objectToAst(keyframe as any)))
+      rules.push(atRule('@keyframes', name, objectToAst(keyframe as any)))
     }
   }
   return rules