sphinx-mkdocs-migrate 0.0.1.dev0__tar.gz → 0.0.1.dev1__tar.gz

{sphinx_mkdocs_migrate-0.0.1.dev0 → sphinx_mkdocs_migrate-0.0.1.dev1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: sphinx-mkdocs-migrate
-Version: 0.0.1.dev0
+Version: 0.0.1.dev1
 Summary: Deterministic, evidence-driven analyzer and migration engine from MkDocs to Sphinx + MyST
 Project-URL: Homepage, https://github.com/prateek-dagar/sphinx-mkdocs-migrate
-Project-URL: Documentation, https://github.com/prateek-dagar/sphinx-mkdocs-migrate#readme
+Project-URL: Documentation, https://sphinx-mkdocs-migrate.readthedocs.io/en/latest/
 Project-URL: Repository, https://github.com/prateek-dagar/sphinx-mkdocs-migrate.git
 Project-URL: Issues, https://github.com/prateek-dagar/sphinx-mkdocs-migrate/issues
 Project-URL: Changelog, https://github.com/prateek-dagar/sphinx-mkdocs-migrate/blob/main/CHANGELOG.md
@@ -74,6 +74,7 @@ Description-Content-Type: text/markdown
 # sphinx_mkdocs_migrate
 
 [![PyPI version](https://img.shields.io/badge/pypi-0.0.1.dev0-blue.svg)](https://pypi.org/project/sphinx-mkdocs-migrate/)
+[![Documentation Status](https://readthedocs.org/projects/sphinx-mkdocs-migrate/badge/?version=latest)](https://sphinx-mkdocs-migrate.readthedocs.io/en/latest/?badge=latest)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 **`sphinx-mkdocs-migrate`** (`sphinx-migrate`) is a deterministic, evidence-driven analyzer and migration engine that safely converts MkDocs and Material for MkDocs documentation projects to Sphinx + MyST Parser.
@@ -111,11 +112,11 @@ The migration lifecycle consists of 4 distinct commands:
 
 ```text
 sphinx-migrate analyze   # 1. Factual project & subsystem inspection
-       ↑
+       ↓
 sphinx-migrate plan      # 2. Deterministic, read-only MigrationPlan generation
-       ⊑
+       ↓
 sphinx-migrate migrate   # 3. Dry-run diffing or atomic disk transformation
-       ⊑
+       ↓
 sphinx-migrate validate  # 4. AST validation & isolated sandbox Sphinx build
 ```
 

{sphinx_mkdocs_migrate-0.0.1.dev0 → sphinx_mkdocs_migrate-0.0.1.dev1}/README.md

@@ -1,6 +1,7 @@
 # sphinx_mkdocs_migrate
 
 [![PyPI version](https://img.shields.io/badge/pypi-0.0.1.dev0-blue.svg)](https://pypi.org/project/sphinx-mkdocs-migrate/)
+[![Documentation Status](https://readthedocs.org/projects/sphinx-mkdocs-migrate/badge/?version=latest)](https://sphinx-mkdocs-migrate.readthedocs.io/en/latest/?badge=latest)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 **`sphinx-mkdocs-migrate`** (`sphinx-migrate`) is a deterministic, evidence-driven analyzer and migration engine that safely converts MkDocs and Material for MkDocs documentation projects to Sphinx + MyST Parser.
@@ -38,11 +39,11 @@ The migration lifecycle consists of 4 distinct commands:
 
 ```text
 sphinx-migrate analyze   # 1. Factual project & subsystem inspection
-       ↑
+       ↓
 sphinx-migrate plan      # 2. Deterministic, read-only MigrationPlan generation
-       ⊑
+       ↓
 sphinx-migrate migrate   # 3. Dry-run diffing or atomic disk transformation
-       ⊑
+       ↓
 sphinx-migrate validate  # 4. AST validation & isolated sandbox Sphinx build
 ```
 

{sphinx_mkdocs_migrate-0.0.1.dev0 → sphinx_mkdocs_migrate-0.0.1.dev1}/pyproject.toml

@@ -56,7 +56,7 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://github.com/prateek-dagar/sphinx-mkdocs-migrate"
-Documentation = "https://github.com/prateek-dagar/sphinx-mkdocs-migrate#readme"
+Documentation = "https://sphinx-mkdocs-migrate.readthedocs.io/en/latest/"
 Repository = "https://github.com/prateek-dagar/sphinx-mkdocs-migrate.git"
 Issues = "https://github.com/prateek-dagar/sphinx-mkdocs-migrate/issues"
 Changelog = "https://github.com/prateek-dagar/sphinx-mkdocs-migrate/blob/main/CHANGELOG.md"

{sphinx_mkdocs_migrate-0.0.1.dev0 → sphinx_mkdocs_migrate-0.0.1.dev1}/src/sphinx_mkdocs_migrate/__init__.py

@@ -4,5 +4,5 @@ Deterministic, evidence-driven analyzer and migration engine from MkDocs to Sphi
 """
 
 # PEP 440 developmental release version
-__version__ = "0.0.1.dev0"
+__version__ = "0.0.1.dev1"
 __all__ = ["__version__"]

{sphinx_mkdocs_migrate-0.0.1.dev0 → sphinx_mkdocs_migrate-0.0.1.dev1}/src/sphinx_mkdocs_migrate/analyzer/mkdocs.py

@@ -59,6 +59,11 @@ class MkDocsConfigAnalyzer:
         if not mkdocs_file or not mkdocs_file.exists():
             return ConfigAnalysis()
 
+        try:
+            rel_config_path = str(mkdocs_file.relative_to(self.project_root))
+        except ValueError:
+            rel_config_path = str(mkdocs_file)
+
         try:
             content = mkdocs_file.read_text(encoding="utf-8")
             data = yaml.load(content, Loader=SafeMkDocsLoader) or {}
@@ -67,13 +72,14 @@ class MkDocsConfigAnalyzer:
                 # Fallback simple load
                 data = yaml.safe_load(mkdocs_file.read_text(encoding="utf-8")) or {}
             except Exception:
-                return ConfigAnalysis()
+                return ConfigAnalysis(config_file_path=rel_config_path)
 
         theme_data = data.get("theme", {})
         theme_logo = None
         theme_icon = None
         theme_favicon = None
         theme_language = None
+        theme_custom_dir = None
         theme_font = None
         theme_palette: List[ThemePalette] = []
 
@@ -91,6 +97,7 @@ class MkDocsConfigAnalyzer:
             )
             theme_favicon = theme_data.get("favicon")
             theme_language = theme_data.get("language")
+            theme_custom_dir = theme_data.get("custom_dir")
 
             # Palette parsing (can be a dict or list of dicts in Material for MkDocs)
             pal = theme_data.get("palette")
@@ -185,7 +192,19 @@ class MkDocsConfigAnalyzer:
             extra_js = [extra_js]
         extra = data.get("extra", {}) if isinstance(data.get("extra"), dict) else {}
 
+        raw_exclude = data.get("exclude_docs", [])
+        if isinstance(raw_exclude, str):
+            exclude_docs = [s.strip() for s in raw_exclude.splitlines() if s.strip()]
+        elif isinstance(raw_exclude, list):
+            exclude_docs = [str(s) for s in raw_exclude]
+        else:
+            exclude_docs = []
+
+        raw_use_dir = data.get("use_directory_urls")
+        use_dir_urls = bool(raw_use_dir) if raw_use_dir is not None else None
+
         return ConfigAnalysis(
+            config_file_path=rel_config_path,
             site_name=site_name,
             site_description=data.get("site_description"),
             site_author=data.get("site_author"),
@@ -200,6 +219,7 @@ class MkDocsConfigAnalyzer:
             theme_icon=theme_icon,
             theme_favicon=theme_favicon,
             theme_language=theme_language,
+            theme_custom_dir=theme_custom_dir,
             theme_palette=theme_palette,
             theme_font=theme_font,
             theme_features=features,
@@ -211,24 +231,42 @@ class MkDocsConfigAnalyzer:
             extra_css=extra_css,
             extra_javascript=extra_js,
             extra=extra,
+            exclude_docs=exclude_docs,
+            use_directory_urls=use_dir_urls,
             raw_config_keys=list(data.keys()) if isinstance(data, dict) else [],
         )
 
 
-def detect_obsolete_generator_scripts(
+def detect_obsolete_mkdocs_files(
     project_root: Path,
     mkdocs_config: Optional[ConfigAnalysis],
     additional_scripts: Optional[List[str]] = None,
 ) -> List[str]:
-    """Detect obsolete MkDocs generator scripts and hooks (e.g. scripts/gen_ref_nav.py) that should be removed.
+    """Detect obsolete MkDocs configuration files, generator scripts, and hooks that should be removed upon migration.
 
-    These scripts run at build time under MkDocs (e.g., mkdocs-gen-files) to generate virtual stubs.
-    Once Sphinx autodoc/autosummary is configured and MkDocs dependencies are removed, these scripts
-    become obsolete, broken, and trigger repo lint failures.
+    1. MkDocs configuration files (e.g. mkdocs.yml, mkdocs.yaml) which are superseded by Sphinx conf.py.
+    2. Generator scripts and hooks (e.g. scripts/gen_ref_nav.py) that run at build time under MkDocs
+       (e.g., mkdocs-gen-files) to generate virtual stubs. Once Sphinx autodoc/autosummary is configured
+       and MkDocs dependencies are removed, these scripts become obsolete, broken, and trigger repo lint failures.
     """
+    obsolete: List[str] = []
+
+    # 1. MkDocs configuration files
+    if mkdocs_config and mkdocs_config.config_file_path:
+        cfg_path = project_root / mkdocs_config.config_file_path
+        if cfg_path.is_file() and mkdocs_config.config_file_path not in obsolete:
+            obsolete.append(mkdocs_config.config_file_path)
+
+    # Check common root configuration candidates if not already detected
+    for candidate in ["mkdocs.yml", "mkdocs.yaml", ".mkdocs.yml", ".mkdocs.yaml"]:
+        cand_path = project_root / candidate
+        if cand_path.is_file() and candidate not in obsolete:
+            obsolete.append(candidate)
+
     if not mkdocs_config:
-        return []
+        return sorted(obsolete)
 
+    # 2. Generator scripts and hooks
     candidate_scripts: set[str] = set()
     gen_cfg = mkdocs_config.plugins_config.get("gen-files", {})
     if isinstance(gen_cfg, dict):
@@ -245,7 +283,6 @@ def detect_obsolete_generator_scripts(
         if isinstance(hook, str):
             candidate_scripts.add(hook)
 
-    obsolete: List[str] = []
     for s_rel in sorted(candidate_scripts):
         s_path = project_root / s_rel
         if s_path.is_file():
@@ -258,6 +295,10 @@ def detect_obsolete_generator_scripts(
                 or "mkdocstrings" in content
                 or (isinstance(gen_cfg, dict) and s_rel in gen_cfg.get("scripts", []))
             ):
-                obsolete.append(s_rel)
+                if s_rel not in obsolete:
+                    obsolete.append(s_rel)
+
+    return sorted(obsolete)
+
 
-    return obsolete
+detect_obsolete_generator_scripts = detect_obsolete_mkdocs_files

{sphinx_mkdocs_migrate-0.0.1.dev0 → sphinx_mkdocs_migrate-0.0.1.dev1}/src/sphinx_mkdocs_migrate/analyzer/models.py

@@ -163,6 +163,7 @@ class ThemeFont(BaseModel):
 
 
 class ConfigAnalysis(BaseModel):
+    config_file_path: Optional[str] = None
     site_name: Optional[str] = None
     site_description: Optional[str] = None
     site_author: Optional[str] = None
@@ -185,9 +186,12 @@ class ConfigAnalysis(BaseModel):
     markdown_extensions: List[str] = Field(default_factory=list)
     nav_raw: Optional[Any] = None
     custom_hooks: List[str] = Field(default_factory=list)
+    theme_custom_dir: Optional[str] = None
     extra_css: List[str] = Field(default_factory=list)
     extra_javascript: List[str] = Field(default_factory=list)
     extra: Dict[str, Any] = Field(default_factory=dict)
+    exclude_docs: List[str] = Field(default_factory=list)
+    use_directory_urls: Optional[bool] = None
     raw_config_keys: List[str] = Field(default_factory=list)
 
 

{sphinx_mkdocs_migrate-0.0.1.dev0 → sphinx_mkdocs_migrate-0.0.1.dev1}/src/sphinx_mkdocs_migrate/analyzer/navigation.py

@@ -1,10 +1,18 @@
 """Subsystem analyzer for MkDocs declarative navigation trees with path normalization and missing file detection."""
 
+import fnmatch
 from pathlib import Path, PurePosixPath
 from typing import List, Any, Optional, Set
+from ..constants import ROOT_DOC_CANDIDATE_STEMS
 from .models import NavigationItem, NavigationAnalysis
 
 
+def is_root_document_path(rel_path: str) -> bool:
+    """Returns True if the relative path represents a top-level root document."""
+    p = Path(rel_path)
+    return len(p.parts) == 1 and p.stem.lower() in ROOT_DOC_CANDIDATE_STEMS
+
+
 def _normalize_nav_path(raw_path: str) -> str:
     """Normalizes relative navigation paths (e.g. './guide/index.md#sec' -> 'guide/index.md')."""
     clean = raw_path.strip()
@@ -91,10 +99,30 @@ class NavigationAnalyzer:
                 else:
                     missing_refs.append(ref)
 
-        # Detect orphan documents (on disk, but not in nav, excluding index.md)
+        def is_covered_by_wildcard(disc_path: str) -> bool:
+            for w_ref in generated_wildcard_refs:
+                pat = w_ref.split("|", 1)[1].strip() if "|" in w_ref else w_ref.strip()
+                pat = pat.replace("...", "").strip().lstrip("./").lstrip("/")
+                if not pat:
+                    continue
+                if fnmatch.fnmatch(disc_path, pat):
+                    return True
+                if fnmatch.fnmatch(disc_path, f"{pat}.md"):
+                    return True
+                if pat.endswith("/*"):
+                    base_prefix = pat[:-2]
+                    if disc_path.startswith(f"{base_prefix}/"):
+                        return True
+            return False
+
+        # Detect orphan documents (on disk, but not in nav, excluding root landing documents)
         orphans: List[str] = []
         for disc in discovered_rel_paths:
-            if disc not in referenced_paths and disc != "index.md":
+            if (
+                disc not in referenced_paths
+                and not is_root_document_path(disc)
+                and not is_covered_by_wildcard(disc)
+            ):
                 orphans.append(disc)
 
         return NavigationAnalysis(

{sphinx_mkdocs_migrate-0.0.1.dev0 → sphinx_mkdocs_migrate-0.0.1.dev1}/src/sphinx_mkdocs_migrate/cli.py

@@ -1,14 +1,20 @@
 """Command-line interface for deterministic MkDocs-to-Sphinx migration."""
 
-import sys
+import importlib.util
 import json
 from pathlib import Path
-from typing import Optional
+import re
+import subprocess
+import sys
+from typing import Dict, List, Optional
+
 import click
 from rich.console import Console
-from rich.table import Table
+from rich.prompt import Confirm, Prompt
 from rich.syntax import Syntax
+from rich.table import Table
 
+from .analyzer.models import Classification
 from .analyzer.project import ProjectAnalyzer
 from .planner.planner import MigrationPlanner
 from .transformer.engine import TransformationEngine
@@ -18,6 +24,170 @@ from . import __version__
 console = Console()
 
 
+def _normalize_module_name(pkg_name: str) -> str:
+    """Normalize a Python package name to its top-level importable module name."""
+    mapping = {
+        "myst-parser": "myst_parser",
+        "sphinx-immaterial": "sphinx_immaterial",
+        "sphinx-design": "sphinx_design",
+        "sphinx-copybutton": "sphinx_copybutton",
+        "sphinx-rtd-theme": "sphinx_rtd_theme",
+        "sphinxcontrib-mermaid": "sphinxcontrib.mermaid",
+        "mkdocs-material": "material",
+    }
+    m = re.match(r"^([a-zA-Z0-9_\-\.]+)", pkg_name)
+    base = (
+        m.group(1).lower().replace("_", "-")
+        if m
+        else pkg_name.lower().replace("_", "-")
+    )
+    return mapping.get(base, base.replace("-", "_"))
+
+
+def _get_missing_sphinx_packages(candidates: List[str]) -> List[str]:
+    """Return candidates that are not found in the current Python environment."""
+    missing: List[str] = []
+    for pkg in candidates:
+        mod = _normalize_module_name(pkg)
+        try:
+            if importlib.util.find_spec(mod) is None:
+                missing.append(pkg)
+        except (ModuleNotFoundError, ValueError):
+            missing.append(pkg)
+    return missing
+
+
+def _get_installed_mkdocs_packages(candidates: List[str]) -> List[str]:
+    """Return MkDocs packages that are currently installed in the environment."""
+    installed: List[str] = []
+    for pkg in candidates:
+        mod = _normalize_module_name(pkg)
+        try:
+            if importlib.util.find_spec(mod) is not None:
+                installed.append(pkg)
+        except (ModuleNotFoundError, ValueError):
+            pass
+    return installed
+
+
+def _is_interactive() -> bool:
+    """Return whether the current session is running in an interactive terminal."""
+    return sys.stdin.isatty()
+
+
+def _collect_manual_review_resolutions(
+    plan,
+    project_root: Path,
+) -> Dict[str, str]:
+    """Interactively prompt user to resolve constructs requiring manual review.
+
+    Returns:
+        Dict mapping action_id -> custom replacement text.
+    """
+    manual_actions = [
+        act
+        for act in plan.document_actions
+        if act.classification == Classification.MANUAL
+    ]
+    if not manual_actions:
+        return {}
+
+    manual_actions.sort(key=lambda a: (a.source_file, a.start_line))
+    total = len(manual_actions)
+
+    console.print(
+        f"\n[bold yellow]Constructs Requiring Manual Review ({total}):[/bold yellow]"
+    )
+    console.print(
+        "[dim]You can review each construct to keep it as-is, comment it out, or enter a custom MyST replacement.[/dim]\n"
+    )
+
+    overrides: Dict[str, str] = {}
+    for idx, act in enumerate(manual_actions, 1):
+        src_path = project_root / act.source_file
+        snippet = ""
+        if src_path.exists():
+            try:
+                lines = src_path.read_text(encoding="utf-8").splitlines(keepends=True)
+                start_idx = max(0, act.start_line - 1)
+                end_idx = min(len(lines), act.end_line)
+                snippet = "".join(lines[start_idx:end_idx])
+            except Exception:
+                snippet = act.description
+        else:
+            snippet = act.description
+
+        console.print(
+            f"[bold cyan]Item {idx}/{total}:[/bold cyan] [bold]{act.source_file}:{act.start_line}-{act.end_line}[/bold]"
+        )
+        console.print(
+            f"  • Construct: [magenta]{act.source_kind.value}[/magenta] ([dim]{act.rule_id}[/dim])"
+        )
+        if act.manual_instruction:
+            console.print(f"  • Instruction: [yellow]{act.manual_instruction}[/yellow]")
+        console.print()
+
+        if snippet.strip():
+            console.print(
+                Syntax(
+                    snippet.strip(),
+                    "markdown",
+                    line_numbers=True,
+                    start_line=act.start_line,
+                )
+            )
+            console.print()
+
+        console.print("  [1] Keep original content (safe, default)")
+        console.print(
+            f"  [2] Comment out block (<!-- MANUAL_REVIEW: {act.source_kind.value} -->)"
+        )
+        console.print("  [3] Enter custom replacement text")
+        console.print("  [s] Skip remaining and keep original for all")
+        console.print()
+
+        choice = Prompt.ask(
+            "Choose action",
+            choices=["1", "2", "3", "s"],
+            default="1",
+        )
+
+        if choice == "1":
+            console.print("[dim]Kept original content.[/dim]\n")
+        elif choice == "2":
+            comment_text = (
+                f"<!-- MANUAL_REVIEW: {act.source_kind.value}\n"
+                f"{snippet.rstrip()}\n"
+                f"-->\n"
+            )
+            overrides[act.action_id] = comment_text
+            console.print("[green]Marked block as commented out.[/green]\n")
+        elif choice == "3":
+            custom_text = Prompt.ask(
+                "Enter custom replacement text (use \\n for newlines)",
+                default="",
+            )
+            if not custom_text.strip():
+                if Confirm.ask("Empty replacement: delete block?", default=False):
+                    overrides[act.action_id] = ""
+                    console.print("[green]Block marked for deletion.[/green]\n")
+                else:
+                    console.print("[dim]Kept original content.[/dim]\n")
+            else:
+                custom_text = custom_text.replace(r"\n", "\n")
+                if not custom_text.endswith("\n"):
+                    custom_text += "\n"
+                overrides[act.action_id] = custom_text
+                console.print("[green]Custom replacement saved.[/green]\n")
+        elif choice == "s":
+            console.print(
+                "[dim]Skipping remaining items; keeping original content.[/dim]\n"
+            )
+            break
+
+    return overrides
+
+
 @click.group()
 @click.version_option(version=__version__, prog_name="sphinx-migrate")
 def main():
@@ -259,6 +429,33 @@ def plan(project_path: Path, output_json_path: Optional[Path], json_stdout: bool
     default=False,
     help="Write transformed files and conf.py to disk.",
 )
+@click.option(
+    "--yes",
+    "-y",
+    "auto_approve",
+    is_flag=True,
+    default=False,
+    help="Automatically confirm prompts and apply migration without interactive confirmation.",
+)
+@click.option(
+    "--interactive/--no-interactive",
+    "-i",
+    "interactive",
+    default=None,
+    help="Prompt interactively to resolve constructs requiring manual review.",
+)
+@click.option(
+    "--install-deps/--no-install-deps",
+    "install_deps",
+    default=None,
+    help="Automatically install (or skip installing) missing Sphinx dependencies in current environment.",
+)
+@click.option(
+    "--uninstall-mkdocs/--no-uninstall-mkdocs",
+    "uninstall_mkdocs",
+    default=None,
+    help="Automatically uninstall (or skip uninstalling) obsolete MkDocs dependencies from current environment.",
+)
 @click.option(
     "--force-conf",
     "overwrite_conf",
@@ -295,6 +492,10 @@ def plan(project_path: Path, output_json_path: Optional[Path], json_stdout: bool
 def migrate(
     project_path: Path,
     write_to_disk: bool,
+    auto_approve: bool,
+    interactive: Optional[bool],
+    install_deps: Optional[bool],
+    uninstall_mkdocs: Optional[bool],
     overwrite_conf: bool,
     show_diff: bool,
     run_validation: bool,
@@ -314,8 +515,64 @@ def migrate(
     planner = MigrationPlanner(project_path)
     plan = planner.create_plan()
 
-    # 2. Execute Transformation
-    engine = TransformationEngine(plan)
+    # Pre-flight check & interactive confirmation
+    to_add: List[str] = (
+        list(plan.dependency_analysis.suggested_packages_to_add)
+        if plan.dependency_analysis
+        else []
+    )
+    if plan.documentation_plan:
+        for req_pkg in plan.documentation_plan.required_packages or []:
+            to_add.append(req_pkg)
+        if "sphinx_copybutton" in (plan.documentation_plan.required_extensions or []):
+            to_add.append("sphinx-copybutton")
+    to_add = sorted(list(dict.fromkeys(to_add)))
+
+    to_remove: List[str] = list(plan.packages_to_remove or [])
+    if plan.dependency_analysis:
+        to_remove.extend(plan.dependency_analysis.detected_packages_to_remove)
+    to_remove = sorted(list(dict.fromkeys(to_remove)))
+
+    if write_to_disk:
+        console.print("[bold]Migration Pre-flight Check:[/bold]")
+        console.print(f"  • Planned transformations: {len(plan.document_actions)}")
+        if to_add:
+            console.print(
+                f"  • Sphinx dependencies to add: [green]{', '.join(to_add)}[/green]"
+            )
+        if to_remove:
+            console.print(
+                f"  • MkDocs dependencies to remove: [yellow]{', '.join(to_remove)}[/yellow]"
+            )
+        if plan.obsolete_files:
+            console.print(
+                f"  • Obsolete MkDocs files to remove: [yellow]{', '.join(plan.obsolete_files)}[/yellow]"
+            )
+        console.print()
+
+        if not auto_approve and _is_interactive():
+            if not Confirm.ask("Apply migration changes to disk?", default=True):
+                console.print("[yellow]Migration cancelled by user.[/yellow]")
+                return
+
+    # 2. Collect manual review resolutions if interactive
+    manual_overrides: Dict[str, str] = {}
+    has_manual = any(
+        act.classification == Classification.MANUAL for act in plan.document_actions
+    )
+    should_prompt_manual = (
+        has_manual
+        and not auto_approve
+        and (
+            interactive is True
+            or (interactive is None and write_to_disk and _is_interactive())
+        )
+    )
+    if should_prompt_manual:
+        manual_overrides = _collect_manual_review_resolutions(plan, project_path)
+
+    # 3. Execute Transformation
+    engine = TransformationEngine(plan, manual_overrides=manual_overrides)
     report = engine.execute(write_to_disk=write_to_disk, overwrite_conf=overwrite_conf)
 
     res_table = Table(
@@ -423,7 +680,86 @@ def migrate(
         for cf in report.cleaned_files:
             console.print(f"      - [yellow]{cf}[/yellow]")
     console.print()
-    if not write_to_disk:
+
+    if write_to_disk:
+        # Check missing Sphinx packages in current environment
+        missing_sphinx = _get_missing_sphinx_packages(to_add)
+        if missing_sphinx:
+            console.print(
+                "[bold yellow]Notice: Missing Sphinx dependencies in current environment:[/bold yellow]"
+            )
+            for p in missing_sphinx:
+                console.print(f"  • [yellow]{p}[/yellow]")
+            console.print()
+
+            do_install = False
+            if install_deps is True:
+                do_install = True
+            elif install_deps is None and not auto_approve and _is_interactive():
+                do_install = Confirm.ask(
+                    f"Install {len(missing_sphinx)} missing Sphinx dependencies into current environment?",
+                    default=True,
+                )
+
+            if do_install:
+                console.print(
+                    f"[bold cyan]Installing {', '.join(missing_sphinx)}...[/bold cyan]"
+                )
+                res = subprocess.run(
+                    [sys.executable, "-m", "pip", "install", *missing_sphinx]
+                )
+                if res.returncode == 0:
+                    console.print(
+                        "[bold green]✔ Dependencies installed successfully.[/bold green]\n"
+                    )
+                else:
+                    console.print(
+                        "[bold red]✖ Failed to install dependencies via pip.[/bold red]\n"
+                    )
+            else:
+                console.print(
+                    f"[dim]To install manually: [bold]pip install {' '.join(missing_sphinx)}[/bold][/dim]\n"
+                )
+
+        # Check installed obsolete MkDocs packages in current environment
+        installed_mkdocs = _get_installed_mkdocs_packages(to_remove)
+        if installed_mkdocs:
+            console.print(
+                "[bold yellow]Notice: Found obsolete MkDocs dependencies in current environment:[/bold yellow]"
+            )
+            for p in installed_mkdocs:
+                console.print(f"  • [yellow]{p}[/yellow]")
+            console.print()
+
+            do_uninstall = False
+            if uninstall_mkdocs is True:
+                do_uninstall = True
+            elif uninstall_mkdocs is None and not auto_approve and _is_interactive():
+                do_uninstall = Confirm.ask(
+                    f"Uninstall {len(installed_mkdocs)} obsolete MkDocs dependencies from current environment?",
+                    default=False,
+                )
+
+            if do_uninstall:
+                console.print(
+                    f"[bold cyan]Uninstalling {', '.join(installed_mkdocs)}...[/bold cyan]"
+                )
+                res = subprocess.run(
+                    [sys.executable, "-m", "pip", "uninstall", "-y", *installed_mkdocs]
+                )
+                if res.returncode == 0:
+                    console.print(
+                        "[bold green]✔ Obsolete MkDocs dependencies uninstalled.[/bold green]\n"
+                    )
+                else:
+                    console.print(
+                        "[bold red]✖ Failed to uninstall dependencies via pip.[/bold red]\n"
+                    )
+            else:
+                console.print(
+                    f"[dim]To uninstall manually: [bold]pip uninstall -y {' '.join(installed_mkdocs)}[/bold][/dim]\n"
+                )
+    else:
         console.print(
             "[dim]Dry-run mode: files were not modified. Pass --apply to write changes to disk.[/dim]"
         )

sphinx_mkdocs_migrate-0.0.1.dev1/src/sphinx_mkdocs_migrate/constants.py

@@ -0,0 +1,5 @@
+"""Universal constants, defaults, and configuration keys for sphinx-mkdocs-migrate."""
+
+DEFAULT_ROOT_DOC = "index"
+ROOT_DOC_CANDIDATE_STEMS = ("index", "readme")
+DEFAULT_ROOT_DOC_FILENAME = f"{DEFAULT_ROOT_DOC}.md"