vue3-migration 1.0.2 → 1.1.0

package/README.md

@@ -1,58 +1,222 @@
 # vue3-migration
 
-A CLI tool that migrates Vue 2 mixins to Vue 3 composables.
+**Stop rewriting mixins by hand.** Automatically migrate your Vue 2 mixins to Vue 3 composables — data, computed, methods, watchers, lifecycle hooks, and all.
 
-## Requirements
+One command. Full before/after diffs. No files changed until you say yes.
+
+## The Problem
+
+Every Vue 2 project sitting on mixins is a migration bottleneck. Rewriting them by hand means:
 
-- Node.js >= 14
-- Python >= 3.9
+- Reading every mixin, understanding every member, tracing every `this.` reference
+- Creating composable files, converting `this.x` to `x.value`, rewriting lifecycle hooks
+- Updating every component that imports the mixin — removing imports, adding `setup()`, destructuring return values
+- Doing it again for the next mixin. And the next. Across dozens (or hundreds) of components.
 
-## Installation
+**vue3-migration does all of this automatically.** It reads your mixins, generates (or patches) composables, rewrites your components, and shows you a clean diff before touching a single file.
+
+## Install
 
 ```bash
 npm install -D vue3-migration
 ```
 
-## Usage
+Requires Node.js >= 14 and Python >= 3.9 (used internally for AST analysis).
 
-Run from the root of your Vue project:
+## Quick Start
 
 ```bash
 npx vue3-migration
 ```
 
-This opens an interactive menu with four options:
+That's it. An interactive menu walks you through four options:
 
-| # | Option | Description |
-|---|--------|-------------|
-| 1 | **Full project** | Migrate every component at once. Auto-patches and generates composables as needed. Shows a per-file change summary and requires confirmation before writing. |
-| 2 | **Pick a component** | Choose one component from a list. Migrate only that file. Safe for large projects — low blast radius, easy to test and review. |
-| 3 | **Pick a mixin** | Fully retire one mixin. Patches/generates its composable and updates every component that uses it. |
-| 4 | **Project status** | Read-only. Generates a detailed markdown report of what's migrated, what's ready, and what's blocked. No files are changed. |
+| # | Mode | What it does |
+|---|------|-------------|
+| **1** | **Full project** | Migrates every component at once. Generates and patches composables, injects `setup()`, removes mixin imports. Shows a full change summary before writing. |
+| **2** | **Pick a component** | Choose one component from a list. Migrate just that file. Low blast radius — perfect for large codebases. |
+| **3** | **Pick a mixin** | Choose one mixin to fully retire. Updates the composable and every component that uses it. |
+| **4** | **Project status** | Read-only scan. Generates a detailed markdown report: what's migrated, what's ready, what's blocked and why. |
 
-### Direct commands
+### Direct Commands
 
 ```bash
-npx vue3-migration all                                # Migrate entire project
-npx vue3-migration component src/components/Foo.vue   # Migrate one component
-npx vue3-migration mixin authMixin                    # Retire one mixin
-npx vue3-migration status                             # Generate status report
+npx vue3-migration all                                # Full project migration
+npx vue3-migration component src/components/Foo.vue   # One component
+npx vue3-migration mixin authMixin                    # Retire one mixin everywhere
+npx vue3-migration status                             # Status report only
+npx vue3-migration --root /path/to/project all        # Run from outside project root
+```
+
+## What It Actually Does
+
+### Generates composables from scratch
+
+No existing composable? The tool creates one. Given a mixin like:
+
+```js
+// mixins/authMixin.js
+export default {
+  data() {
+    return { user: null, token: '' }
+  },
+  computed: {
+    isLoggedIn() { return !!this.user }
+  },
+  methods: {
+    async login(credentials) { /* ... */ }
+  },
+  mounted() {
+    this.checkSession()
+  }
+}
 ```
 
-### Output files
+It generates:
 
-Every migration writes a `migration-diff-<timestamp>.md` with a full before/after diff of every changed file.
+```js
+// composables/useAuth.js
+import { ref, computed, onMounted } from 'vue'
+
+export function useAuth() {
+  const user = ref(null)
+  const token = ref('')
+
+  const isLoggedIn = computed(() => !!user.value)
+
+  async function login(credentials) { /* ... */ }
+
+  onMounted(() => {
+    checkSession()
+  })
+
+  return { user, token, isLoggedIn, login }
+}
+```
+
+Every `this.x` reference is rewritten. Lifecycle hooks are converted. Getter/setter computed properties are handled. Watch expressions with `deep`, `immediate`, and handler options are converted.
+
+### Patches incomplete composables
+
+Already started writing composables manually? The tool detects what's missing and patches it — adds missing member declarations and updates the `return` statement. No duplicate work.
+
+### Rewrites components automatically
+
+For every component using a mixin, the tool:
+
+1. **Removes** the mixin import line
+2. **Adds** the composable import
+3. **Removes** the mixin from the `mixins: [...]` array
+4. **Injects** a `setup()` function with destructured composable calls
+5. **Converts** lifecycle hooks to their Composition API equivalents
+6. **Merges** into existing `setup()` if one already exists
+
+**Before:**
+```vue
+<script>
+import authMixin from '@/mixins/authMixin'
+
+export default {
+  mixins: [authMixin],
+  data() { return { localState: true } }
+}
+</script>
+```
+
+**After:**
+```vue
+<script>
+import { useAuth } from '@/composables/useAuth'
+
+export default {
+  setup() {
+    const { user, token, isLoggedIn, login } = useAuth()
+    return { user, token, isLoggedIn, login }
+  },
+  data() { return { localState: true } }
+}
+</script>
+```
 
-`npx vue3-migration status` writes a `migration-status-<timestamp>.md` with:
-- Summary counts (total, ready, blocked)
-- Mixin overview table
-- Per-component status and blocking reason
+### Handles `this.$` patterns
+
+- `this.$nextTick(cb)` &rarr; `nextTick(cb)` (auto-imports from `'vue'`)
+- `this.$set(obj, key, val)` &rarr; `obj[key] = val`
+- `this.$delete(obj, key)` &rarr; `delete obj[key]`
+- `this.$emit`, `this.$router`, `this.$store`, `this.$refs`, and 15+ more patterns are detected and flagged with actionable migration guidance
+
+### Smart about what it can't automate
+
+Some patterns need human judgment. The tool doesn't silently skip them — it flags them clearly:
+
+- **`this.$emit`** &rarr; "Use `defineEmits` or pass `emit` from `setup()`"
+- **`this.$router` / `this.$route`** &rarr; "Import `useRouter()` / `useRoute()` from `vue-router`"
+- **`this.$store`** &rarr; "Import store directly from Pinia/Vuex"
+- **`this.$refs`** &rarr; "Use template refs with `ref()`"
+- **Mixin `props`, `inject`, `provide`** &rarr; "Must use `defineProps()` / `inject()` manually"
+- **Nested mixins** &rarr; "Transitive members may be missed"
+- **`filters`** &rarr; "Removed in Vue 3 — convert to methods"
+- **This-aliasing** (`const self = this`) &rarr; "Manual replacement needed"
+
+Each warning is injected as a comment directly in the generated code, so nothing gets lost.
+
+## Safety Features
+
+**Nothing changes until you confirm.** Every migration mode shows a complete change summary and asks for explicit `y/n` confirmation before writing any file.
+
+**Full diff report.** Every migration writes a `migration-diff-<timestamp>.md` with unified diffs of every changed file — composables and components.
+
+**Override-aware.** If a component defines its own `data`, `computed`, or `methods` that overlap with a mixin, the tool knows the component's version takes precedence and won't inject duplicates.
+
+**Confidence scoring.** Generated composables include a confidence header:
+- **HIGH** — Clean conversion, no remaining issues
+- **MEDIUM** — Has TODOs or warnings that need review
+- **LOW** — Remaining `this.` references or structural issues
+
+**Blocked status.** If a mixin can't be safely migrated (e.g., missing composable, incomplete coverage), the tool marks it as blocked and tells you exactly why — it never partially migrates and leaves broken code.
+
+## What It Supports
+
+| Mixin feature | Auto-converted |
+|--------------|---------------|
+| `data()` properties | ref() with default values |
+| `computed` (simple) | computed(() => ...) |
+| `computed` (get/set) | computed({ get, set }) |
+| `methods` (sync & async) | Plain functions |
+| `watch` (handler + options) | watch() with deep/immediate |
+| `mounted`, `created`, etc. | onMounted(), inlined, etc. |
+| `beforeDestroy` / `destroyed` | onBeforeUnmount() / onUnmounted() |
+| `this.x` references | x.value or x (context-aware) |
+| `this.$nextTick` | nextTick() |
+| `this.$set` / `this.$delete` | Direct assignment / delete |
+| Multiple mixins per component | Multiple composable calls |
+| Existing `setup()` function | Merges (doesn't overwrite) |
+| `@/` and relative imports | Resolved and rewritten |
+
+## Recommended Workflow for Large Projects
+
+1. **Run `npx vue3-migration status`** to see the full picture — which mixins are used where, what's ready, what's blocked.
+2. **Start with "Pick a component"** (option 2). Migrate one component, test it, commit.
+3. **When a mixin is fully covered**, use "Pick a mixin" (option 3) to retire it across all components at once.
+4. **Repeat** until the status report shows zero remaining mixins.
+
+For smaller projects, "Full project" (option 1) handles everything in one pass.
+
+## How It Finds Your Files
+
+The tool searches recursively from your project root (or `--root` if specified):
+
+- **Components:** Every `.vue` file in the project tree
+- **Mixin files:** Resolved from import paths (`@/`, relative, bare imports)
+- **Composables:** First checks directories named `composables/` (case-insensitive), then falls back to searching the entire project for any `use*.js` / `use*.ts` file
+
+Skips `node_modules/`, `dist/`, `.git/`, and `__pycache__/` automatically.
+
+## Requirements
 
-## Workflow for large projects
+- **Node.js** >= 14 (for the CLI wrapper)
+- **Python** >= 3.9 (for the migration engine — auto-detected on your PATH)
 
-For large codebases where each change is critical:
+## License
 
-1. Run `npx vue3-migration status` to see the full picture.
-2. Use **Pick a component** (option 2) to migrate one component at a time.
-3. Test after each migration, then move on to the next.
-4. When a mixin is fully covered and you're ready to retire it, use **Pick a mixin** (option 3).
+MIT

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "vue3-migration",
-  "version": "1.0.2",
-  "description": "Vue 2 mixin to Vue 3 composable migration tool",
+  "version": "1.1.0",
+  "description": "Automatically migrate Vue 2 mixins to Vue 3 composables — data, computed, methods, watchers, lifecycle hooks, and all",
   "bin": {
     "vue3-migration": "./bin/cli.js"
   },
   "files": [
     "bin/",
-    "vue3_migration/"
+    "vue3_migration/**/*.py",
+    "!**/__pycache__/"
   ],
   "engines": {
     "node": ">=14"

package/vue3_migration/cli.py

@@ -173,7 +173,7 @@ def _scan_components_with_mixins(project_root: Path, config: MigrationConfig) ->
     from .core.composable_search import collect_composable_stems, find_composable_dirs, mixin_has_composable
 
     composable_dirs = find_composable_dirs(project_root)
-    composable_stems = collect_composable_stems(composable_dirs)
+    composable_stems = collect_composable_stems(composable_dirs, project_root=project_root)
     results: list[dict] = []
 
     for dirpath, _, filenames in os.walk(project_root):
@@ -216,7 +216,7 @@ def _scan_mixin_usage(project_root: Path, config: MigrationConfig) -> list[dict]
     from .core.composable_search import collect_composable_stems, find_composable_dirs, mixin_has_composable
 
     composable_dirs = find_composable_dirs(project_root)
-    composable_stems = collect_composable_stems(composable_dirs)
+    composable_stems = collect_composable_stems(composable_dirs, project_root=project_root)
     mixin_counter: Counter[str] = Counter()
 
     for dirpath, _, filenames in os.walk(project_root):
@@ -511,9 +511,15 @@ def project_status(config: MigrationConfig) -> None:
 # =============================================================================
 
 def main(argv: list[str] | None = None):
+    import argparse
     import sys
     args = argv if argv is not None else sys.argv[1:]
-    config = MigrationConfig()
+
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--root", default=None)
+    known, args = parser.parse_known_args(args)
+    project_root = Path(known.root).resolve() if known.root else Path.cwd()
+    config = MigrationConfig(project_root=project_root)
 
     if not args:
         interactive_menu(config)

package/vue3_migration/core/composable_search.py

@@ -53,57 +53,109 @@ def find_composable_dirs(project_root: Path) -> list[Path]:
     return found
 
 
-def search_for_composable(mixin_stem: str, composable_dirs: list[Path]) -> list[Path]:
+_SKIP_DIRS = {"node_modules", "dist", ".git", "__pycache__"}
+
+
+def find_all_composable_files(project_root: Path) -> list[Path]:
+    """Find every .js/.ts file whose stem starts with 'use' anywhere in the project.
+
+    Skips node_modules, dist, .git, __pycache__.
+    """
+    files: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(project_root):
+        rel = Path(dirpath).relative_to(project_root)
+        if any(part in _SKIP_DIRS for part in rel.parts):
+            dirnames[:] = []
+            continue
+        # Prune skipped dirs in-place so os.walk won't descend into them
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+        for fn in filenames:
+            fp = Path(dirpath) / fn
+            if fp.suffix in (".js", ".ts") and fp.stem.lower().startswith("use"):
+                files.append(fp)
+    return files
+
+
+def search_for_composable(
+    mixin_stem: str,
+    composable_dirs: list[Path],
+    project_root: "Path | None" = None,
+) -> list[Path]:
     """Search for composable files matching a mixin name.
 
     Phase 1: Exact stem match against generated candidate names (case-insensitive).
     Phase 2: Fuzzy -- any 'use' file whose name contains the mixin's core word.
+
+    If no matches found in composable_dirs and project_root is provided,
+    repeats both phases across all use*.js/ts files found project-wide.
     """
     candidates = generate_candidates(mixin_stem)
     matches = []
 
-    # Phase 1: Exact name match (case-insensitive)
+    def _search_files(files: list[Path]) -> list[Path]:
+        found = []
+        # Phase 1: exact
+        for fp in files:
+            if any(fp.stem.lower() == c.lower() for c in candidates):
+                found.append(fp)
+        if found:
+            return list(dict.fromkeys(found))
+        # Phase 2: fuzzy
+        core_word = re.sub(r"[_-]?[Mm]ixin$", "", mixin_stem).lower()
+        if not core_word:
+            return []
+        for fp in files:
+            if fp.stem.lower().startswith("use") and core_word in fp.stem.lower():
+                found.append(fp)
+        return list(dict.fromkeys(found))
+
+    # Collect files from named composable directories
+    dir_files: list[Path] = []
     for comp_dir in composable_dirs:
         for dirpath, _, filenames in os.walk(comp_dir):
             for filename in filenames:
-                filepath = Path(dirpath) / filename
-                if filepath.suffix not in (".js", ".ts"):
-                    continue
-                if any(filepath.stem.lower() == c.lower() for c in candidates):
-                    matches.append(filepath)
+                fp = Path(dirpath) / filename
+                if fp.suffix in (".js", ".ts"):
+                    dir_files.append(fp)
 
+    matches = _search_files(dir_files)
     if matches:
-        return list(dict.fromkeys(matches))
+        return matches
 
-    # Phase 2: Fuzzy fallback -- "use" prefix + core word substring
-    core_word = re.sub(r"[_-]?[Mm]ixin$", "", mixin_stem).lower()
-    if not core_word:
-        return []
+    # Fallback: project-wide search
+    if project_root is not None:
+        all_files = find_all_composable_files(project_root)
+        # Exclude files already covered by composable_dirs to avoid duplicates
+        dir_file_set = set(dir_files)
+        extra_files = [f for f in all_files if f not in dir_file_set]
+        matches = _search_files(extra_files)
 
-    for comp_dir in composable_dirs:
-        for dirpath, _, filenames in os.walk(comp_dir):
-            for filename in filenames:
-                filepath = Path(dirpath) / filename
-                if filepath.suffix not in (".js", ".ts"):
-                    continue
-                if filepath.stem.lower().startswith("use") and core_word in filepath.stem.lower():
-                    matches.append(filepath)
-
-    return list(dict.fromkeys(matches))
+    return matches
 
 
-def collect_composable_stems(composable_dirs: list[Path]) -> set[str]:
+def collect_composable_stems(
+    composable_dirs: list[Path],
+    project_root: "Path | None" = None,
+) -> set[str]:
     """Collect all composable file stems (e.g. 'useSelection') from all dirs.
 
     Used for quick existence checks during scanning.
+
+    If composable_dirs yields no stems and project_root is provided,
+    falls back to a project-wide search via find_all_composable_files.
     """
     stems: set[str] = set()
     for comp_dir in composable_dirs:
         for dirpath, _, filenames in os.walk(comp_dir):
             for fn in filenames:
                 fp = Path(dirpath) / fn
-                if fp.suffix in (".js", ".ts") and fp.stem.startswith("use"):
+                if fp.suffix in (".js", ".ts") and fp.stem.lower().startswith("use"):
                     stems.add(fp.stem.lower())
+
+    if not stems and project_root is not None:
+        for fp in find_all_composable_files(project_root):
+            stems.add(fp.stem.lower())
+
     return stems
 
 

package/vue3_migration/reporting/markdown.py

@@ -148,7 +148,7 @@ def generate_status_report(project_root: Path, config) -> str:
     from ..core.file_resolver import resolve_mixin_stem
 
     composable_dirs = find_composable_dirs(project_root)
-    composable_stems = collect_composable_stems(composable_dirs)
+    composable_stems = collect_composable_stems(composable_dirs, project_root=project_root)
 
     # Detect composables that need manual migration (reactive() or variable return)
     manual_stems: set[str] = set()

package/vue3_migration/workflows/auto_migrate_workflow.py

@@ -67,7 +67,7 @@ def _analyze_mixin_silent(
         entry.compute_status()
         return entry
 
-    matches = search_for_composable(mixin_file.stem, composable_dirs)
+    matches = search_for_composable(mixin_file.stem, composable_dirs, project_root=project_root)
     composable_file = matches[0] if matches else None
 
     if composable_file:
@@ -204,9 +204,11 @@ def plan_new_composables(
     Returns FileChange objects with original_content="" (new files).
     """
     composable_dirs = find_composable_dirs(project_root)
-    if not composable_dirs:
-        return []
-    target_dir = composable_dirs[0]
+    if composable_dirs:
+        target_dir = composable_dirs[0]
+    else:
+        src_dir = project_root / "src"
+        target_dir = (src_dir / "composables") if src_dir.is_dir() else (project_root / "composables")
 
     seen_stems: set[str] = set()
     changes = []

package/vue3_migration/workflows/mixin_workflow.py

@@ -296,7 +296,7 @@ def run(mixin_arg: str, composable_arg: Optional[str] = None, config: MigrationC
         candidates = generate_candidates(mixin_path.stem)
         print(f"  Looking for: {cyan(', '.join(candidates))}")
         comp_dirs = find_composable_dirs(project_root)
-        matches = search_for_composable(mixin_path.stem, comp_dirs)
+        matches = search_for_composable(mixin_path.stem, comp_dirs, project_root=project_root)
 
         if len(matches) == 1:
             found_path = matches[0]