fix(migrate): keep declare module 'vite' augmentations on 'vite'

Partially reverts e29973c. Through the core alias a preserved
declare module 'vite' augmentation reaches the same
@voidzero-dev/vite-plus-core module whose UserConfig types defineConfig
from vite-plus, so it keeps working after migration. vite-plus exports
no UserConfig symbol, so the rewritten declare module 'vite-plus'
augmentation merged with nothing and silently stopped applying. Users
extending vite-plus's own surface write declare module 'vite-plus'
directly.

Restores the #2004 config-files-only scoping for all vite specifiers,
flips the regression test to assert preservation, regenerates the
migration-rewrite-declare-module snapshot, and documents the rationale
in migrate-rules.md.

Author: fengmk2

crates/vite_migration/src/import_rewriter.rs

@@ -1571,25 +1571,6 @@ static PARSED_VITE_RULES: LazyLock<Vec<RuleConfig<SupportLang>>> = LazyLock::new
     ast_grep::load_rules(REWRITE_VITE_RULES).expect("failed to parse vite rewrite rules")
 });
 
-const VITE_DECLARE_MODULE_RULE_IDS: [&str; 2] =
-    ["rewrite-declare-module-vite", "rewrite-declare-module-vite-subpath"];
-
-/// The `declare module 'vite'` augmentation rules, applied in EVERY file (not
-/// only config entry files). The Issue #2004 config-file scoping covers value
-/// imports, whose unrewritten `vite` specifiers still resolve through the core
-/// alias; a module augmentation instead binds to the literal specifier of the
-/// import it augments, and the config's own import IS rewritten to `vite-plus`,
-/// so leaving the augmentation on `vite` would fail type-checking after
-/// migration.
-static PARSED_VITE_DECLARE_MODULE_RULES: LazyLock<Vec<RuleConfig<SupportLang>>> =
-    LazyLock::new(|| {
-        ast_grep::load_rules(REWRITE_VITE_RULES)
-            .expect("failed to parse vite rewrite rules")
-            .into_iter()
-            .filter(|rule| VITE_DECLARE_MODULE_RULE_IDS.contains(&rule.id.as_str()))
-            .collect()
-    });
-
 static PARSED_VITEST_RULES: LazyLock<Vec<RuleConfig<SupportLang>>> = LazyLock::new(|| {
     ast_grep::load_rules(REWRITE_VITEST_RULES).expect("failed to parse vitest rewrite rules")
 });
@@ -2289,12 +2270,14 @@ fn rewrite_import(
     // Read the file
     let content = std::fs::read_to_string(file_path)?;
 
-    // Issue #2004: `vite` value imports are rewritten only in config entry
-    // files; everything else keeps its `vite` imports (they still resolve
-    // through the core alias). `declare module 'vite'` augmentations are the
-    // exception and are rewritten everywhere — see
-    // `PARSED_VITE_DECLARE_MODULE_RULES`. This is layered ON TOP of the
-    // package-level skip (a skipped package stays skipped).
+    // Issue #2004: `vite` specifiers are rewritten only in config entry files;
+    // everything else keeps its `vite` imports (they still resolve through the
+    // core alias). This includes `declare module 'vite'` augmentations: through
+    // the alias they reach the SAME `@voidzero-dev/vite-plus-core` module whose
+    // `UserConfig` types `defineConfig` from `vite-plus`, so they keep working,
+    // whereas `vite-plus` re-exports no `UserConfig` symbol for a rewritten
+    // augmentation to merge with. This is layered ON TOP of the package-level
+    // skip (a skipped package stays skipped).
     rewrite_import_content_full(
         &content,
         skip_packages,
@@ -2359,13 +2342,12 @@ fn rewrite_import_content_full(
     let mut updated = false;
     let mut preserved_vitest = false;
 
-    // Apply vite rules if not skipped (using pre-parsed rules). Outside config
-    // entry files only the `declare module 'vite'` augmentation rules apply
-    // (Issue #2004 keeps every other `vite` specifier).
-    if !skip_packages.skip_vite {
-        let vite_rules: &[RuleConfig<SupportLang>] =
-            if vite_config_file { &PARSED_VITE_RULES } else { &PARSED_VITE_DECLARE_MODULE_RULES };
-        let vite_content = ast_grep::apply_loaded_rules(&new_content, vite_rules);
+    // Apply vite rules if not skipped (using pre-parsed rules). Issue #2004:
+    // they apply only in config entry files; every other file keeps its `vite`
+    // specifiers, including `declare module 'vite'` augmentations (see the
+    // comment in `rewrite_import`).
+    if !skip_packages.skip_vite && vite_config_file {
+        let vite_content = ast_grep::apply_loaded_rules(&new_content, &PARSED_VITE_RULES);
         if vite_content != new_content {
             new_content = vite_content;
             updated = true;
@@ -3074,11 +3056,14 @@ describe('test', () => {});"#,
     }
 
     #[test]
-    fn test_declare_module_vite_rewritten_outside_config_files() {
-        // A `declare module 'vite'` augmentation binds to the literal specifier
-        // of the import it augments. The config's own import IS rewritten to
-        // `vite-plus`, so the augmentation must follow even though it lives in
-        // a non-config .d.ts (unlike value imports, which Issue #2004 keeps).
+    fn test_declare_module_vite_preserved_outside_config_files() {
+        // A `declare module 'vite'` augmentation must stay on `vite`: through
+        // the core alias it reaches the same `@voidzero-dev/vite-plus-core`
+        // module whose `UserConfig` types `defineConfig` from `vite-plus`.
+        // `vite-plus` re-exports no `UserConfig` symbol, so rewriting the
+        // augmentation to `declare module 'vite-plus'` would orphan it (it
+        // would merge with nothing). Users extending vite-plus itself write
+        // `declare module 'vite-plus'` by hand.
         use std::fs;
 
         let temp = tempdir().unwrap();
@@ -3099,37 +3084,14 @@ describe('test', () => {});"#,
 
         let dts = fs::read_to_string(temp.path().join("types/vite.d.ts")).unwrap();
         assert!(
-            dts.contains("declare module 'vite-plus'"),
-            "augmentation must track the rewritten config import, got: {dts}"
-        );
-        assert!(
-            dts.contains("from 'vite'"),
-            "non-config `vite` value/type imports must be preserved, got: {dts}"
+            !dts.contains("vite-plus"),
+            "non-config `vite` specifiers (including augmentations) must be preserved, got: {dts}"
         );
+        assert!(dts.contains("declare module 'vite'"));
         let config = fs::read_to_string(temp.path().join("vite.config.ts")).unwrap();
         assert!(config.contains("from 'vite-plus'"));
     }
 
-    #[test]
-    fn test_declare_module_vite_skipped_in_plugin_packages() {
-        // The package-level plugin skip stays authoritative: a vite-plugin-*
-        // package keeps its `declare module 'vite'` augmentation untouched.
-        use std::fs;
-
-        let temp = tempdir().unwrap();
-        fs::write(temp.path().join("package.json"), r#"{"name":"vite-plugin-example"}"#).unwrap();
-        fs::write(
-            temp.path().join("types.d.ts"),
-            "declare module 'vite' {\n  interface UserConfig {\n    example?: object;\n  }\n}\n",
-        )
-        .unwrap();
-
-        rewrite_imports_in_directory(temp.path()).unwrap();
-
-        let dts = fs::read_to_string(temp.path().join("types.d.ts")).unwrap();
-        assert!(dts.contains("declare module 'vite'"), "plugin package must be skipped: {dts}");
-    }
-
     #[test]
     fn test_preserves_unscoped_vitest_in_nuxt_test_utils_packages() {
         use std::fs;

docs/guide/migrate-rules.md

@@ -177,12 +177,13 @@ Plugin packages (an unscoped name starting with `vite-plugin-` or
 `unplugin-`, or `vite` in `peerDependencies`/`dependencies`) skip the rewrite
 even in config files. Only the `vite` specifier is in scope for this rule.
 
-One exception goes the other way: `declare module 'vite'` augmentations are
-rewritten to `declare module 'vite-plus'` in every file, not only configs. A
-module augmentation binds to the literal specifier, so it must keep targeting
-the same module as the rewritten config import or the augmented options fail
-type-checking. (This differs from `vitest` augmentations, which are never
-rewritten; see below.)
+`declare module 'vite'` augmentations follow the same rule and are preserved
+outside config files. Through the core alias they reach the same
+`@voidzero-dev/vite-plus-core` module whose `UserConfig` types `defineConfig`
+from `vite-plus`, so they keep working after migration; `vite-plus` itself
+exports no `UserConfig` symbol, so a rewritten `declare module 'vite-plus'`
+augmentation would merge with nothing. Extensions aimed at `vite-plus`'s own
+surface are written against `vite-plus` by hand.
 
 ### `vitest` and Browser Imports
 

packages/cli/snap-tests-global/migration-rewrite-declare-module/snap.txt

@@ -1,13 +1,13 @@
 > vp migrate --no-interactive # retained vitest augmentations should keep a package-local vitest
 ◇ Migrated . to Vite+ <semver>
 • Node <semver>  pnpm <semver>
-• 2 config updates applied, 1 file had imports rewritten
+• 2 config updates applied
 
-> cat src/index.ts # declare module 'vite' follows the rewritten config import; 'vitest' augmentations keep the upstream identity
+> cat src/index.ts # declare module 'vite'/'vitest' outside config files are preserved: through the core alias a 'vite' augmentation reaches the UserConfig that types vite-plus defineConfig, while vite-plus exports no UserConfig symbol to merge a rewritten augmentation with
 import type { RuntimeEnvConfig } from './runtime.env.config.js';
 import type { RuntimeHtmlConfig } from './runtime.html.config.js';
 
-declare module 'vite-plus' {
+declare module 'vite' {
   interface UserConfig {
     /**
      * Options for vite-plugin-runtime-env

packages/cli/snap-tests-global/migration-rewrite-declare-module/steps.json

@@ -1,7 +1,7 @@
 {
   "commands": [
     "vp migrate --no-interactive # retained vitest augmentations should keep a package-local vitest",
-    "cat src/index.ts # declare module 'vite' follows the rewritten config import; 'vitest' augmentations keep the upstream identity",
+    "cat src/index.ts # declare module 'vite'/'vitest' outside config files are preserved: through the core alias a 'vite' augmentation reaches the UserConfig that types vite-plus defineConfig, while vite-plus exports no UserConfig symbol to merge a rewritten augmentation with",
     "cat package.json # check package.json",
     "cat pnpm-workspace.yaml # check pnpm-workspace.yaml has overrides and catalog"
   ]