Add canonical class diagnostics

packages/tailwindcss-language-server/tests/diagnostics/diagnostics.test.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs/promises'
 import { expect, test } from 'vitest'
 import { withFixture } from '../common'
-import { css, defineTest } from '../../src/testing'
+import { css, defineTest, json } from '../../src/testing'
 import { createClient } from '../utils/client'
 
 withFixture('basic', (c) => {
@@ -425,3 +425,51 @@
     ])
   },
 })
+
+defineTest({
+  name: 'Shows warning when using non-canonical classes',
+  fs: {
+    'app.css': css`
+      @import 'tailwindcss';
+    `,
+  },
+  prepare: async ({ root }) => ({
+    client: await createClient({
+      root,
+      settings: {
+        tailwindCSS: {
+          lint: { usedNonCanonicalClass: 'warning' },
+        },
+      },
+    }),
+  }),
+  handle: async ({ client }) => {
+    let doc = await client.open({
+      lang: 'html',
+      text: '<div class="[@media_print]:flex [color:red]/50">',
+    })
+
+    let diagnostics = await doc.diagnostics()
+
+    expect(diagnostics).toEqual([
+      {
+        code: 'usedNonCanonicalClass',
+        message: 'The class "[@media_print]:flex" is usually written as "print:flex"',
+        range: {
+          start: { line: 0, character: 12 },
+          end: { line: 0, character: 31 },
+        },
+        severity: 2,
+      },
+      {
+        code: 'usedNonCanonicalClass',
+        message: 'The class "[color:red]/50" is usually written as "text-[red]/50"',
+        range: {
+          start: { line: 0, character: 32 },
+          end: { line: 0, character: 46 },
+        },
+        severity: 2,
+      },
+    ])
+  },
+})

packages/tailwindcss-language-service/src/diagnostics/canonical-classes.ts

@@ -0,0 +1,52 @@
+import type { TextDocument } from 'vscode-languageserver-textdocument'
+import type { State, Settings } from '../util/state'
+import { type UsedNonCanonicalClassDiagnostic, DiagnosticKind } from './types'
+import { findClassListsInDocument, getClassNamesInClassList } from '../util/find'
+
+export async function getUsedNonCanonicalClassDiagnostics(
+  state: State,
+  document: TextDocument,
+  settings: Settings,
+): Promise<UsedNonCanonicalClassDiagnostic[]> {
+  if (!state.v4) return []
+  if (!state.designSystem.canonicalizeCandidates) return []
+
+  let severity = settings.tailwindCSS.lint.usedNonCanonicalClass
+  if (severity === 'ignore') return []
+
+  let diagnostics: UsedNonCanonicalClassDiagnostic[] = []
+
+  let classLists = await findClassListsInDocument(state, document)
+
+  for (let classList of classLists) {
+    let classNames = getClassNamesInClassList(classList, [])
+
+    // What if:
+    // We pass in the entire class list. This would allow `canonicalizeCandidates` to canonicalize class *lists* too.
+    // e.g. `[font-size:0.875rem] [line-height:0.25rem]` to `text-sm/3`
+    //
+    // What if the output class list is re-sorted? Maybe it shouldn't be because otherwise that
+    // would be weird DX. Like at that point its about "this list isn't written how it should be"
+    // but that could be because of sorting *or* non-canonical classes.
+    //
+    // So maybe output order needs to be preserved but then where do you put the new class?
+    for (let className of classNames) {
+      let canonicalized = state.designSystem.canonicalizeCandidates([className.className])[0]
+      let isCanonical = canonicalized === className.className
+
+      if (isCanonical) continue
+
+      diagnostics.push({
+        code: DiagnosticKind.UsedNonCanonicalClass,
+        range: className.range,
+        severity:
+          severity === 'error'
+            ? 1 /* DiagnosticSeverity.Error */
+            : 2 /* DiagnosticSeverity.Warning */,
+        message: `The class \`${className.className}\` is usually written as \`${canonicalized}\``,
+      })
+    }
+  }
+
+  return diagnostics
+}

packages/tailwindcss-language-service/src/diagnostics/diagnosticsProvider.ts

@@ -10,6 +10,7 @@ import { getInvalidTailwindDirectiveDiagnostics } from './getInvalidTailwindDire
 import { getRecommendedVariantOrderDiagnostics } from './getRecommendedVariantOrderDiagnostics'
 import { getInvalidSourceDiagnostics } from './getInvalidSourceDiagnostics'
 import { getUsedBlocklistedClassDiagnostics } from './getUsedBlocklistedClassDiagnostics'
+import { getUsedNonCanonicalClassDiagnostics } from './canonical-classes'
 
 export async function doValidate(
   state: State,
@@ -24,6 +25,7 @@ export async function doValidate(
     DiagnosticKind.InvalidSourceDirective,
     DiagnosticKind.RecommendedVariantOrder,
     DiagnosticKind.UsedBlocklistedClass,
+    DiagnosticKind.UsedNonCanonicalClass,
   ],
 ): Promise<AugmentedDiagnostic[]> {
   const settings = await state.editor.getConfiguration(document.uri)
@@ -57,6 +59,9 @@ export async function doValidate(
         ...(only.includes(DiagnosticKind.UsedBlocklistedClass)
           ? await getUsedBlocklistedClassDiagnostics(state, document, settings)
           : []),
+        ...(only.includes(DiagnosticKind.UsedNonCanonicalClass)
+          ? await getUsedNonCanonicalClassDiagnostics(state, document, settings)
+          : []),
       ]
     : []
 }

packages/tailwindcss-language-service/src/diagnostics/types.ts

@@ -11,6 +11,7 @@ export enum DiagnosticKind {
   InvalidSourceDirective = 'invalidSourceDirective',
   RecommendedVariantOrder = 'recommendedVariantOrder',
   UsedBlocklistedClass = 'usedBlocklistedClass',
+  UsedNonCanonicalClass = 'usedNonCanonicalClass',
 }
 
 export type CssConflictDiagnostic = Diagnostic & {
@@ -111,6 +112,16 @@ export function isUsedBlocklistedClass(
   return diagnostic.code === DiagnosticKind.UsedBlocklistedClass
 }
 
+export type UsedNonCanonicalClassDiagnostic = Diagnostic & {
+  code: DiagnosticKind.UsedNonCanonicalClass
+}
+
+export function isUsedNonCanonicalClass(
+  diagnostic: AugmentedDiagnostic,
+): diagnostic is UsedNonCanonicalClassDiagnostic {
+  return diagnostic.code === DiagnosticKind.UsedNonCanonicalClass
+}
+
 export type AugmentedDiagnostic =
   | CssConflictDiagnostic
   | InvalidApplyDiagnostic
@@ -121,3 +132,4 @@ export type AugmentedDiagnostic =
   | InvalidSourceDirectiveDiagnostic
   | RecommendedVariantOrderDiagnostic
   | UsedBlocklistedClassDiagnostic
+  | UsedNonCanonicalClassDiagnostic

packages/tailwindcss-language-service/src/util/state.ts

@@ -66,6 +66,7 @@ export type TailwindCssSettings = {
     invalidSourceDirective: DiagnosticSeveritySetting
     recommendedVariantOrder: DiagnosticSeveritySetting
     usedBlocklistedClass: DiagnosticSeveritySetting
+    usedNonCanonicalClass: DiagnosticSeveritySetting
   }
   experimental: {
     classRegex: string[] | [string, string][]
@@ -205,6 +206,7 @@ export function getDefaultTailwindSettings(): Settings {
         invalidSourceDirective: 'error',
         recommendedVariantOrder: 'warning',
         usedBlocklistedClass: 'warning',
+        usedNonCanonicalClass: 'ignore',
       },
       showPixelEquivalents: true,
       includeLanguages: {},

packages/tailwindcss-language-service/src/util/v4/design-system.ts

@@ -38,9 +38,14 @@ export interface DesignSystem {
   getClassList(): ClassEntry[]
   getVariants(): VariantEntry[]
 
-  // Optional because it did not exist in earlier v4 alpha versions
+  // Added in v4.0.0-alpha.24
   resolveThemeValue?(path: string, forceInline?: boolean): string | undefined
+
+  // Added in v4.0.0-alpha.26
   invalidCandidates?: Set<string>
+
+  // Added in v4.1.15
+  canonicalizeCandidates?(classes: string[]): string[]
 }
 
 export interface DesignSystem {

packages/vscode-tailwindcss/README.md

@@ -183,6 +183,19 @@ Class variants not in the recommended order (applies in [JIT mode](https://tailw
 
 Usage of class names that have been blocklisted via `@source not inline(…)`. **Default: `warning`**
 
+#### `tailwindCSS.lint.usedNonCanonicalClass`
+
+Usage of class names that are not in the most "standardized" form. **Default: `ignore`**
+
+Some examples of the changes this makes:
+
+| Class                 | Canonical Form |
+| --------------------- | -------------- |
+| `[color:red]/100`     | `text-[red]`   |
+| `[@media_print]:flex` | `print:flex`   |
+
+This feature is off by default as it has a non-trivial performance and memory cost on startup and when editing your CSS.
+
 ### `tailwindCSS.inspectPort`
 
 Enable the Node.js inspector agent for the language server and listen on the specified port. **Default: `null`**

packages/vscode-tailwindcss/package.json

@@ -316,6 +316,17 @@
           "markdownDescription": "Usage of class names that have been blocklisted via `@source not inline(…)`",
           "scope": "language-overridable"
         },
+        "tailwindCSS.lint.usedNonCanonicalClass": {
+          "type": "string",
+          "enum": [
+            "ignore",
+            "warning",
+            "error"
+          ],
+          "default": "warning",
+          "markdownDescription": "Usage of class names that may be written in a more optimal form",
+          "scope": "language-overridable"
+        },
         "tailwindCSS.experimental.classRegex": {
           "type": "array",
           "scope": "language-overridable"