Handle future and experimental config keys during upgrade

[thecrypticace]

Fixes #19342

[coderabbitai]

Walkthrough

Adds explicit support and validation for experimental and future config keys. The UserConfig and ResolvedConfig types gain an experimental field ('all' | Record<string, boolean> and Record<string, boolean> respectively). The JS config codemod now aborts migration if unknown future or experimental flags are present and treats those keys as top-level properties. Three integration tests were added to verify migration behavior, and CHANGELOG.md was updated.

Pre-merge checks

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and clearly summarizes the main change: handling future and experimental config keys during the upgrade process.
Description check	✅ Passed	The description references the linked issue #19342, which is directly related to handling future and experimental config keys during upgrade.
Linked Issues check	✅ Passed	The PR addresses the core requirement: making the upgrade tool handle future and experimental config keys gracefully so upgrades proceed without blocking migrations.
Out of Scope Changes check	✅ Passed	All changes are directly related to handling future and experimental config keys during upgrade; no out-of-scope modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 86e1a14 and 9c53d5e.

📒 Files selected for processing (1)

• packages/@tailwindcss-upgrade/src/codemods/config/migrate-js-config.ts (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/@tailwindcss-upgrade/src/codemods/config/migrate-js-config.ts

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/@tailwindcss-upgrade/src/codemods/config/migrate-js-config.ts (1)

405-416: Future/experimental validation logic is sound; consider a small naming cleanup

The changes in canMigrateConfig look good overall:

• Adding future and experimental to knownProperties removes the blanket rejection of any config that happened to use those options.
• The new guards that:
  • allow future: 'all'/experimental: 'all', and
  • require all object keys under future/experimental to be from a known allow‑list
    are a reasonable, conservative strategy for an auto‑migration: known flags migrate, unknown ones safely fall back to @config without guessing.

One small refinement to keep things clear:

• In the experimental block, the local variable is still named knownFutureFlags. Renaming it to something like knownExperimentalFlags would avoid confusion when reading this function in isolation.

Functionally this is fine as‑is; the rename is just for readability.

Also applies to: 430-452

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7c0eeaa and 86e1a14.

📒 Files selected for processing (5)

• CHANGELOG.md (1 hunks)
• integrations/upgrade/js-config.test.ts (1 hunks)
• packages/@tailwindcss-upgrade/src/codemods/config/migrate-js-config.ts (2 hunks)
• packages/tailwindcss/src/compat/config/resolve-config.ts (1 hunks)
• packages/tailwindcss/src/compat/config/types.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

integrations/upgrade/js-config.test.ts (1)

integrations/utils.ts (4)

• test (80-455)
• json (523-523)
• ts (520-520)
• css (518-518)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Linux / upgrade
• GitHub Check: Linux

🔇 Additional comments (6)

CHANGELOG.md (1)

17-17: Changelog entry is clear and consistent

The new “Upgrade: Handle future and experimental config keys” bullet matches the PR behavior and existing changelog style; nothing to change here.

packages/tailwindcss/src/compat/config/resolve-config.ts (1)

33-45: Initializing experimental in the minimal resolved config looks right

Adding experimental: {} to minimal keeps ResolvedConfig’s shape consistent with the types and with the existing future: {} handling. No issues here.

integrations/upgrade/js-config.test.ts (3)

1931-2006: LGTM! Correctly validates rejection of unknown future keys.

The test properly verifies that when an unknown future key is encountered, the migration is aborted and the config file is preserved with an @config reference. This is the correct defensive behavior.

---

2008-2083: LGTM! Correctly validates rejection of unknown experimental keys.

The test mirrors the unknown future keys test but for experimental configuration keys, ensuring both validation paths work correctly. When an unknown experimental key is encountered, migration is appropriately aborted and the config is preserved.

---

1845-1929: LGTM! Verification confirms all future/experimental keys are properly recognized.

The test correctly verifies that all used configuration keys are explicitly defined in the migration codemod's known flags lists:

• Future flags (hoverOnlyWhenSupported, respectDefaultRingColorOpacity, disableColorOpacityUtilitiesByDefault, relativeContentPathsByDefault) ✓
• Experimental flags (generalizedModifiers) ✓

The migration logic will successfully process these keys without bailing, and the test validates the expected output format with the empty config file and migrated CSS.

packages/tailwindcss/src/compat/config/types.ts (1)

108-116: LGTM! Clean and consistent type definitions for experimental config.

The type additions properly extend the configuration surface to support experimental keys, mirroring the existing future key structure. The UserConfig uses an optional field while ResolvedConfig requires it (which aligns with initialization to an empty object in resolve-config.ts).