Improve memory usage during canonicalization (#19171)

This PR drastically improves the memory usage when performing
canonicalization if you swap out the underlying DesignSystem often. This
will be most noticeable in Intellisense.

The big issue we had is that we used module scoped Map objects where we
cache data based on the DesignSystem. If you then create new design
systems (often), then the cache would just keep growing and growing.

This PR solves that by essentially storing all the caches on the Design
System itself. This way, when you throw away a Design System, all the
caches go with it.

Another approach would've been to use a WeakMap, but then we would have
to make sure that no strong references to the DesignSystem exist
anywhere else, otherwise we would still have the same memory issues.

Note: make sure to go commit by commit and use `?w=1` to ignore
whitespace changes.

## Test plan

1. All existing tests pass

Not super sure how to test this as part of the test suite without making
it slow But I also don't think that's super necessary either. Here is an
experiment I did where I introduce 5 design systems:
<img width="1326" height="274" alt="image"
src="https://github.com/user-attachments/assets/817025e3-0f5b-44be-949b-54ed08f5b3fb"
/>

On the current `main` branch, this looks like:
<img width="619" height="69" alt="image"
src="https://github.com/user-attachments/assets/588ae99b-c978-4c01-bfd1-5cc0725723a8"
/>


In this PR, the memory usage looks like:
<img width="512" height="56" alt="image"
src="https://github.com/user-attachments/assets/0052ad21-7b99-4edf-8a14-8ccef52362db"
/>

The memory usage is stable, but to actually prove that we can still
track multiple design systems, let's track them all in a `Set` so
garbage collection cannot get rid of the unused design system objects:
<img width="847" height="230" alt="image"
src="https://github.com/user-attachments/assets/5f044927-3d53-4c15-8145-78eb2b4d6d54"
/>

Now we're sort of back to the current situation on `main`:
<img width="507" height="53" alt="image"
src="https://github.com/user-attachments/assets/868c0238-8646-41ce-8151-e0ef6dd17d64"
/>

Author: RobinMalfait

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

@@ -1,23 +1,23 @@
 import { cloneCandidate } from '../../../../tailwindcss/src/candidate'
-import { createSignatureOptions } from '../../../../tailwindcss/src/canonicalize-candidates'
+import {
+  PRE_COMPUTED_VARIANTS_KEY,
+  prepareDesignSystemStorage,
+  VARIANT_SIGNATURE_KEY,
+} from '../../../../tailwindcss/src/canonicalize-candidates'
 import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
-import {
-  computeVariantSignature,
-  preComputedVariants,
-} from '../../../../tailwindcss/src/signatures'
 import type { Writable } from '../../../../tailwindcss/src/types'
 import { replaceObject } from '../../../../tailwindcss/src/utils/replace-object'
 import { walkVariants } from '../../utils/walk-variants'
 
 export function migrateArbitraryVariants(
-  designSystem: DesignSystem,
+  baseDesignSystem: DesignSystem,
   _userConfig: Config | null,
   rawCandidate: string,
 ): string {
-  let signatureOptions = createSignatureOptions(designSystem)
-  let signatures = computeVariantSignature.get(signatureOptions)
-  let variants = preComputedVariants.get(signatureOptions)
+  let designSystem = prepareDesignSystemStorage(baseDesignSystem)
+  let signatures = designSystem.storage[VARIANT_SIGNATURE_KEY]
+  let variants = designSystem.storage[PRE_COMPUTED_VARIANTS_KEY]
 
   for (let readonlyCandidate of designSystem.parseCandidate(rawCandidate)) {
     // We are only interested in the variants

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

@@ -1,9 +1,12 @@
 import fs from 'node:fs/promises'
 import path, { extname } from 'node:path'
-import { createSignatureOptions } from '../../../../tailwindcss/src/canonicalize-candidates'
+import {
+  createSignatureOptions,
+  prepareDesignSystemStorage,
+  UTILITY_SIGNATURE_KEY,
+} from '../../../../tailwindcss/src/canonicalize-candidates'
 import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
-import { computeUtilitySignature } from '../../../../tailwindcss/src/signatures'
 import { DefaultMap } from '../../../../tailwindcss/src/utils/default-map'
 import { spliceChangesIntoString, type StringChange } from '../../utils/splice-changes-into-string'
 import { extractRawCandidates } from './candidates'
@@ -40,7 +43,8 @@ export const DEFAULT_MIGRATIONS: Migration[] = [
   migrateModernizeArbitraryValues,
 ]
 
-let migrateCached = new DefaultMap((designSystem: DesignSystem) => {
+let migrateCached = new DefaultMap((baseDesignSystem: DesignSystem) => {
+  let designSystem = prepareDesignSystemStorage(baseDesignSystem)
   let options = createSignatureOptions(designSystem)
 
   return new DefaultMap((userConfig: Config | null) => {
@@ -57,7 +61,7 @@ let migrateCached = new DefaultMap((designSystem: DesignSystem) => {
       // Verify that the candidate actually makes sense at all. E.g.: `duration`
       // is not a valid candidate, but it will parse because `duration-<number>`
       // exists.
-      let signature = computeUtilitySignature.get(options).get(rawCandidate)
+      let signature = designSystem.storage[UTILITY_SIGNATURE_KEY].get(options).get(rawCandidate)
       if (typeof signature !== 'string') return original
 
       return rawCandidate