vue3-migration 1.0.0

package/vue3_migration/core/composable_search.py

@@ -0,0 +1,141 @@
+"""
+Composable search — find composable files matching mixin names.
+
+Generates candidate composable names from mixin filenames, searches
+Composables directories with exact then fuzzy matching.
+"""
+
+import os
+import re
+from pathlib import Path
+
+
+def generate_candidates(mixin_stem: str) -> list[str]:
+    """Generate expected composable names from a mixin filename.
+
+    selectionMixin         -> [useSelection]
+    LPiMixin               -> [useLPi, useLpi]
+    PropertiesCommonMixin  -> [usePropertiesCommon, useProperties]
+    mapHelpers             -> [useMapHelpers, useMaphelpers]
+    """
+    # Strip "Mixin" suffix (with optional _ or - prefix)
+    core_name = re.sub(r"[_-]?[Mm]ixin$", "", mixin_stem)
+    if not core_name:
+        return []
+
+    # Primary: preserve original casing after "use"
+    primary = "use" + core_name[0].upper() + core_name[1:]
+    # Secondary: capitalize-style for edge cases
+    secondary = "use" + core_name.capitalize()
+
+    candidates = [primary, secondary]
+
+    # Also try stripping "Common" if present
+    without_common = re.sub(r"[_-]?[Cc]ommon$", "", core_name)
+    if without_common and without_common != core_name:
+        candidates.append("use" + without_common[0].upper() + without_common[1:])
+        candidates.append("use" + without_common.capitalize())
+
+    return list(dict.fromkeys(candidates))
+
+
+def find_composable_dirs(project_root: Path) -> list[Path]:
+    """Find all directories named 'Composables' (case-insensitive) in the project."""
+    found = []
+    for dirpath, dirnames, _ in os.walk(project_root):
+        # Skip node_modules, dist, .git
+        rel = Path(dirpath).relative_to(project_root)
+        if any(part in {"node_modules", "dist", ".git", "__pycache__"} for part in rel.parts):
+            continue
+        for dirname in dirnames:
+            if dirname.lower() == "composables":
+                found.append(Path(dirpath) / dirname)
+    return found
+
+
+def search_for_composable(mixin_stem: str, composable_dirs: list[Path]) -> 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.
+    """
+    candidates = generate_candidates(mixin_stem)
+    matches = []
+
+    # Phase 1: Exact name match (case-insensitive)
+    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)
+
+    if matches:
+        return list(dict.fromkeys(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 []
+
+    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))
+
+
+def collect_composable_stems(composable_dirs: list[Path]) -> set[str]:
+    """Collect all composable file stems (e.g. 'useSelection') from all dirs.
+
+    Used for quick existence checks during scanning.
+    """
+    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"):
+                    stems.add(fp.stem.lower())
+    return stems
+
+
+def mixin_has_composable(mixin_stem: str, composable_stems: set[str]) -> bool:
+    """Check if a matching composable likely exists for a mixin name.
+
+    Uses the same two-phase strategy as search_for_composable:
+    Phase 1 — exact candidate match (useFilter, useFilter).
+    Phase 2 — fuzzy: any composable stem starting with 'use' that contains
+               the core word as a substring (e.g. useAdvancedFilter for filterMixin).
+    """
+    core = re.sub(r"[_-]?[Mm]ixin$", "", mixin_stem)
+    if not core:
+        return False
+
+    names_to_check = [core]
+    without_common = re.sub(r"[_-]?[Cc]ommon$", "", core)
+    if without_common != core:
+        names_to_check.append(without_common)
+
+    # Phase 1: exact candidate match
+    for name in names_to_check:
+        candidate = "use" + name[0].upper() + name[1:]
+        if candidate.lower() in composable_stems:
+            return True
+        if ("use" + name.capitalize()).lower() in composable_stems:
+            return True
+
+    # Phase 2: fuzzy — core word as substring of any use* composable
+    core_lower = core.lower()
+    for stem in composable_stems:
+        if stem.startswith("use") and core_lower in stem:
+            return True
+
+    return False

package/vue3_migration/core/file_resolver.py

@@ -0,0 +1,98 @@
+"""
+Import path resolution — resolve JS/TS import paths to actual files on disk.
+
+Handles relative paths, @/ alias (mapped to src/), and @ prefix without slash.
+"""
+
+import re
+from pathlib import Path
+from typing import Optional
+
+FILE_EXTENSIONS = (".js", ".ts")
+
+
+def find_src_directory(starting_dir: Path) -> Optional[Path]:
+    """Walk upward from starting_dir to find the nearest directory containing 'src/'."""
+    search = starting_dir.resolve()
+    while search != search.parent:
+        candidate = search / "src"
+        if candidate.is_dir():
+            return candidate
+        search = search.parent
+    return None
+
+
+def try_resolve_with_extensions(base_path: Path) -> Optional[Path]:
+    """Try to resolve a path as-is, then with .js and .ts extensions."""
+    for candidate in [base_path, base_path.with_suffix(".js"), base_path.with_suffix(".ts")]:
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def resolve_import_path(import_path: str, component_path: Path) -> Optional[Path]:
+    """Resolve an import path to an actual file on disk.
+
+    Handles three styles:
+      - Relative:     '../mixins/foo'
+      - @/ alias:     '@/components/foo'    (@ = src/)
+      - @ prefix:     '@components/foo'     (@ = src/)
+    """
+    component_dir = component_path.parent
+
+    # --- Case 1: Relative path (starts with . or /) ---
+    if import_path.startswith(".") or import_path.startswith("/"):
+        base = (component_dir / import_path).resolve()
+        return try_resolve_with_extensions(base)
+
+    # --- Case 2 & 3: @ alias (@/ or @ without /) ---
+    if import_path.startswith("@"):
+        src_dir = find_src_directory(component_dir)
+        if not src_dir:
+            return None
+
+        # "@/components/foo" -> strip "@/" -> "components/foo"
+        # "@components/foo"  -> strip "@"  -> "components/foo"
+        if import_path.startswith("@/"):
+            relative_part = import_path[2:]
+        else:
+            relative_part = import_path[1:]
+
+        base = (src_dir / relative_part).resolve()
+        return try_resolve_with_extensions(base)
+
+    # --- Fallback: treat as relative ---
+    base = (component_dir / import_path).resolve()
+    return try_resolve_with_extensions(base)
+
+
+def compute_import_path(composable_path: Path, project_root: Path) -> str:
+    """Build the import path for a composable, using @/ alias when under src/.
+
+    Resolves the actual file path relative to the project root and replaces
+    the src/ prefix with @/.
+    """
+    try:
+        relative = composable_path.resolve().relative_to(project_root.resolve())
+    except ValueError:
+        relative = composable_path
+
+    normalized = str(relative).replace("\\", "/")
+    normalized = re.sub(r"\.(js|ts)$", "", normalized)
+
+    # Replace everything up to and including "src/" with "@/"
+    src_idx = normalized.find("src/")
+    if src_idx != -1:
+        return "@/" + normalized[src_idx + 4:]
+
+    return normalized
+
+
+def resolve_mixin_stem(import_path: str) -> str:
+    """Extract the mixin filename stem from an import path.
+
+    '../mixins/selectionMixin' -> 'selectionMixin'
+    '@/mixins/LPiMixin.js'    -> 'LPiMixin'
+    """
+    basename = import_path.rsplit("/", 1)[-1]
+    return re.sub(r"\.(js|ts)$", "", basename)

package/vue3_migration/core/js_parser.py

@@ -0,0 +1,177 @@
+"""
+JavaScript parsing helpers for Vue migration tool.
+
+Provides low-level parsing of JS source code: skipping strings, comments,
+regex literals, extracting brace-delimited blocks, and extracting top-level
+property names from object literals. All functions are comment/string/regex
+aware to avoid false matches inside non-code regions.
+"""
+
+import re
+
+
+def skip_string(source: str, start: int) -> int:
+    """Skip past a quoted string (handles escaped chars).
+
+    Supports single quotes, double quotes, and template literals.
+    Returns the index after the closing quote.
+    """
+    quote = source[start]
+    pos = start + 1
+    while pos < len(source):
+        if source[pos] == "\\":
+            pos += 2
+            continue
+        if source[pos] == quote:
+            return pos + 1
+        pos += 1
+    return pos
+
+
+def skip_regex_literal(source: str, start: int) -> int:
+    """Skip past a regex literal /pattern/flags.
+
+    Handles escaped characters and character classes ([...]).
+    Returns the index after the closing / and any flags.
+    """
+    pos = start + 1  # skip opening /
+    while pos < len(source):
+        ch = source[pos]
+        if ch == "\\":
+            pos += 2  # skip escaped char
+            continue
+        if ch == "[":
+            # Character class -- skip until unescaped ]
+            pos += 1
+            while pos < len(source):
+                if source[pos] == "\\":
+                    pos += 2
+                    continue
+                if source[pos] == "]":
+                    break
+                pos += 1
+        elif ch == "/":
+            pos += 1
+            # Skip flags (g, i, m, s, u, y, d)
+            while pos < len(source) and source[pos].isalpha():
+                pos += 1
+            return pos
+        elif ch == "\n":
+            # Unterminated regex -- bail out (not a real regex)
+            return start + 1
+        pos += 1
+    return pos
+
+
+def is_regex_start(source: str, pos: int) -> bool:
+    """Determine if '/' at pos is a regex start (True) or division operator (False).
+
+    Looks at the previous non-whitespace character/word for context.
+    Division follows values: ), ], identifiers, digits.
+    Regex follows operators, keywords, punctuation, or nothing.
+    """
+    i = pos - 1
+    while i >= 0 and source[i] in " \t":
+        i -= 1
+    if i < 0:
+        return True  # start of string
+    prev = source[i]
+    # After these, '/' is division (follows a value)
+    if prev in ")]}":
+        return False
+    if prev.isalnum() or prev == "_" or prev == "$":
+        # Could be an identifier (division) or a keyword (regex).
+        end = i + 1
+        while i >= 0 and (source[i].isalnum() or source[i] in "_$"):
+            i -= 1
+        word = source[i + 1: end]
+        # After these keywords, '/' starts a regex
+        regex_keywords = {
+            "return", "typeof", "instanceof", "in", "delete",
+            "void", "throw", "new", "case", "yield", "await",
+        }
+        return word in regex_keywords
+    # After everything else (=, (, [, {, ,, ;, :, !, &, |, ?, ~, +, -, *, <, >, ^, %, newline)
+    return True
+
+
+def skip_non_code(source: str, pos: int) -> tuple[int, bool]:
+    """Skip strings, comments, and regex literals at current position.
+
+    Returns (new_pos, did_skip). If did_skip is False, the character at pos
+    is actual code and should be processed.
+    """
+    two = source[pos: pos + 2]
+    if two == "//":
+        nl = source.find("\n", pos)
+        return (nl + 1 if nl != -1 else len(source)), True
+    if two == "/*":
+        end = source.find("*/", pos + 2)
+        return (end + 2 if end != -1 else len(source)), True
+    if source[pos] in "\"'`":
+        return skip_string(source, pos), True
+    if source[pos] == "/" and is_regex_start(source, pos):
+        return skip_regex_literal(source, pos), True
+    return pos, False
+
+
+def extract_brace_block(source: str, open_brace_pos: int) -> str:
+    """Extract content between matching { } braces, skipping strings/comments/regex.
+
+    Args:
+        source: The full source text.
+        open_brace_pos: Index of the opening '{'.
+
+    Returns:
+        The text between the braces (exclusive of the braces themselves).
+    """
+    depth = 0
+    pos = open_brace_pos
+    while pos < len(source):
+        new_pos, skipped = skip_non_code(source, pos)
+        if skipped:
+            pos = new_pos
+            continue
+        if source[pos] == "{":
+            depth += 1
+        elif source[pos] == "}":
+            depth -= 1
+            if depth == 0:
+                return source[open_brace_pos + 1: pos]
+        pos += 1
+    return source[open_brace_pos + 1:]
+
+
+def extract_property_names(object_body: str) -> list[str]:
+    """Extract top-level property names from a JS object literal body.
+
+    Uses an expect_key flag: only captures identifiers right after a comma
+    or at block start. This prevents false positives from nested code
+    (e.g., function calls like clearInterval inside method bodies).
+
+    Returns deduplicated list preserving first-occurrence order.
+    """
+    names = []
+    depth = 0
+    expect_key = True
+    pos = 0
+    while pos < len(object_body):
+        new_pos, skipped = skip_non_code(object_body, pos)
+        if skipped:
+            pos = new_pos
+            continue
+        ch = object_body[pos]
+        if ch in "{[(":
+            depth += 1
+        elif ch in "}])":
+            depth -= 1
+        elif depth == 0 and ch == ",":
+            expect_key = True
+        elif depth == 0 and expect_key and (ch.isalpha() or ch in "_$"):
+            match = re.match(r"(?:async\s+)?(\w+)", object_body[pos:])
+            if match:
+                names.append(match.group(1))
+                expect_key = False
+                pos += match.end() - 1
+        pos += 1
+    return list(dict.fromkeys(names))

package/vue3_migration/core/mixin_analyzer.py

@@ -0,0 +1,54 @@
+"""
+Mixin analysis — extract members and lifecycle hooks from Vue mixin source code.
+"""
+
+import re
+
+from .js_parser import extract_brace_block, extract_property_names
+
+VUE_LIFECYCLE_HOOKS = [
+    "beforeCreate", "created", "beforeMount", "mounted",
+    "beforeUpdate", "updated", "beforeDestroy", "destroyed",
+    "beforeUnmount", "unmounted", "activated", "deactivated",
+    "errorCaptured", "renderTracked", "renderTriggered",
+    "onBeforeMount", "onMounted", "onBeforeUpdate", "onUpdated",
+    "onBeforeUnmount", "onUnmounted", "onActivated", "onDeactivated",
+    "onErrorCaptured", "onRenderTracked", "onRenderTriggered",
+]
+
+
+def extract_mixin_members(source: str) -> dict[str, list[str]]:
+    """Extract data, computed, and methods property names from a mixin.
+
+    Returns:
+        Dict with keys 'data', 'computed', 'methods', each mapping to
+        a list of property name strings.
+    """
+    members: dict[str, list[str]] = {"data": [], "computed": [], "methods": []}
+
+    # data() { return { ... } }
+    data_match = re.search(r"\bdata\s*\(\s*\)\s*\{", source)
+    if data_match:
+        body = source[data_match.end():]
+        ret = re.search(r"\breturn\s*\{", body)
+        if ret:
+            brace_pos = ret.start() + ret.group().index("{")
+            members["data"] = extract_property_names(extract_brace_block(body, brace_pos))
+
+    # computed: { ... } and methods: { ... }
+    for section in ("computed", "methods"):
+        match = re.search(rf"\b{section}\s*:\s*\{{", source)
+        if match:
+            members[section] = extract_property_names(
+                extract_brace_block(source, match.end() - 1)
+            )
+
+    return members
+
+
+def extract_lifecycle_hooks(source: str) -> list[str]:
+    """Find Vue lifecycle hooks defined in the mixin source."""
+    return [
+        hook for hook in VUE_LIFECYCLE_HOOKS
+        if re.search(rf"\b{hook}\s*(?:\(|:\s*(?:function|\())", source)
+    ]

package/vue3_migration/models.py

@@ -0,0 +1,168 @@
+"""
+Data models for the Vue mixin migration tool.
+
+Typed dataclasses replace the raw dicts used in the original scripts,
+providing clear structure and computed properties.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+
+class MigrationStatus(Enum):
+    """Status of a single mixin's migration readiness."""
+    READY = "ready"
+    BLOCKED_NO_COMPOSABLE = "blocked_no_composable"
+    BLOCKED_MISSING_MEMBERS = "blocked_missing"
+    BLOCKED_NOT_RETURNED = "blocked_not_returned"
+    FORCE_UNBLOCKED = "force_unblocked"
+
+
+@dataclass
+class MixinMembers:
+    """Members extracted from a mixin source file."""
+    data: list[str] = field(default_factory=list)
+    computed: list[str] = field(default_factory=list)
+    methods: list[str] = field(default_factory=list)
+    watch: list[str] = field(default_factory=list)
+
+    @property
+    def all_names(self) -> list[str]:
+        return self.data + self.computed + self.methods + self.watch
+
+
+@dataclass
+class MemberClassification:
+    """Classification of how mixin members relate to a composable and the component.
+
+    Given a set of used members, a composable's capabilities, and the component's
+    own members, this classifies each member into categories that determine
+    whether injection can proceed.
+    """
+    missing: list[str] = field(default_factory=list)
+    """Members not found anywhere in the composable."""
+    truly_missing: list[str] = field(default_factory=list)
+    """Missing members that the component does NOT override (blockers)."""
+    not_returned: list[str] = field(default_factory=list)
+    """Members present in composable but not in its return statement."""
+    truly_not_returned: list[str] = field(default_factory=list)
+    """Not-returned members that the component does NOT override (blockers)."""
+    overridden: list[str] = field(default_factory=list)
+    """Missing members that the component defines itself (safe to skip)."""
+    overridden_not_returned: list[str] = field(default_factory=list)
+    """Not-returned members that the component defines itself (safe to skip)."""
+    injectable: list[str] = field(default_factory=list)
+    """Members the composable should provide (used - overridden)."""
+
+    @property
+    def is_ready(self) -> bool:
+        return not self.truly_missing and not self.truly_not_returned
+
+
+@dataclass
+class ComposableCoverage:
+    """Analysis of a composable's coverage of a mixin's members."""
+    file_path: Path
+    fn_name: str
+    import_path: str
+    all_identifiers: list[str] = field(default_factory=list)
+    return_keys: list[str] = field(default_factory=list)
+
+    def classify_members(
+        self,
+        used: list[str],
+        component_own_members: set[str],
+    ) -> MemberClassification:
+        """Classify each used member by availability in the composable and component."""
+        missing = [m for m in used if m not in self.all_identifiers]
+        not_returned = [m for m in used if m in self.all_identifiers and m not in self.return_keys]
+
+        overridden = [m for m in missing if m in component_own_members]
+        truly_missing = [m for m in missing if m not in component_own_members]
+        overridden_not_returned = [m for m in not_returned if m in component_own_members]
+        truly_not_returned = [m for m in not_returned if m not in component_own_members]
+
+        injectable = [
+            m for m in used
+            if m not in overridden and m not in overridden_not_returned
+        ]
+
+        return MemberClassification(
+            missing=missing,
+            truly_missing=truly_missing,
+            not_returned=not_returned,
+            truly_not_returned=truly_not_returned,
+            overridden=overridden,
+            overridden_not_returned=overridden_not_returned,
+            injectable=injectable,
+        )
+
+
+@dataclass
+class MixinEntry:
+    """Complete analysis of a single mixin used by a component."""
+    local_name: str
+    """The local import name (e.g. 'selectionMixin')."""
+    mixin_path: Path
+    """Resolved path to the mixin file."""
+    mixin_stem: str
+    """Filename stem of the mixin (e.g. 'selectionMixin')."""
+    members: MixinMembers
+    """Extracted mixin members."""
+    lifecycle_hooks: list[str] = field(default_factory=list)
+    """Lifecycle hooks found in the mixin."""
+    used_members: list[str] = field(default_factory=list)
+    """Members actually referenced by the component."""
+    composable: Optional[ComposableCoverage] = None
+    """Matched composable, if found."""
+    classification: Optional[MemberClassification] = None
+    """Member classification against the composable."""
+    status: MigrationStatus = MigrationStatus.BLOCKED_NO_COMPOSABLE
+    """Current migration status."""
+
+    def compute_status(self) -> MigrationStatus:
+        """Determine the migration status based on analysis results."""
+        if not self.used_members:
+            self.status = MigrationStatus.READY
+        elif not self.composable or not self.classification:
+            self.status = MigrationStatus.BLOCKED_NO_COMPOSABLE
+        elif self.classification.is_ready:
+            self.status = MigrationStatus.READY
+        elif self.classification.truly_missing:
+            self.status = MigrationStatus.BLOCKED_MISSING_MEMBERS
+        else:
+            self.status = MigrationStatus.BLOCKED_NOT_RETURNED
+        return self.status
+
+
+@dataclass
+class FileChange:
+    """Represents a planned or completed file modification."""
+    file_path: Path
+    original_content: str
+    new_content: str
+    changes: list[str] = field(default_factory=list)
+    """Human-readable descriptions of each change made."""
+
+    @property
+    def has_changes(self) -> bool:
+        return self.original_content != self.new_content
+
+
+@dataclass
+class MigrationConfig:
+    """Configuration for the migration tool."""
+    project_root: Path = field(default_factory=Path.cwd)
+    skip_dirs: set[str] = field(
+        default_factory=lambda: {"node_modules", "dist", ".git", "__pycache__"}
+    )
+    file_extensions: set[str] = field(
+        default_factory=lambda: {".vue", ".js", ".ts"}
+    )
+    composable_dir_name: str = "composables"
+    backup_enabled: bool = True
+    dry_run: bool = False
+    auto_confirm: bool = False
+    indent: str = "  "