ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/migration_mapper.py

@@ -0,0 +1,946 @@
+"""Migration intent detection and MIGRATION_MAP.md generation.
+
+Detects legacy codebase signals, scores each module by composite risk,
+and produces MIGRATION_MAP.md + ref-reports/migration_map.json.
+
+Reads from ref-reports/platform_engineer/health_report.json (written by
+scan_health) — no additional filesystem scan passes.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+# --- Thresholds -----------------------------------------------------------
+
+_STRONG_SIGNAL_DEAD_CODE_PCT = 30.0  # SIG-S4: whole-codebase dead code %
+_WEAK_SIGNAL_DEAD_CODE_PCT = 20.0  # SIG-W2: single-module dead code %
+_WEAK_SIGNAL_COMPLEXITY_FUNCS = 3  # SIG-W3: min functions with HIGH/CRITICAL complexity
+_WEAK_SIGNAL_MONOLITH_LOC = 1000  # SIG-W4: LOC threshold
+_WEAK_SIGNAL_MARKER_FILES = 5  # SIG-W1: min files with legacy markers
+
+_LEGACY_MARKERS = re.compile(
+    r"\b(DEPRECATED|TODO:\s*migrate|TODO:\s*rewrite|FIXME:\s*legacy)\b",
+    re.IGNORECASE,
+)
+
+_SOAP_PATTERNS = re.compile(
+    r"\b(zeep|suds|SOAPpy|pysimplesoap|xmlrpclib|node-soap|soap-client)\b",
+    re.IGNORECASE,
+)
+
+_DB_CONTROLLER_DIRS = re.compile(
+    r"(view|controller|route|handler|endpoint)", re.IGNORECASE
+)
+
+_DB_IMPORTS = re.compile(
+    r"\b(psycopg2|cx_Oracle|pymysql|sqlite3|pyodbc|MySQLdb)\.connect\b",
+    re.IGNORECASE,
+)
+
+# Composite score weights (must sum to 1.0)
+_W_DEBT = 0.35
+_W_DEAD = 0.20
+_W_COMPLEXITY = 0.25
+_W_COVERAGE = 0.20
+
+# Recommended action thresholds by composite score
+_ACTION_THRESHOLDS: list[tuple[float, str]] = [
+    (3.0, "Keep"),
+    (5.5, "Refactor"),
+    (7.5, "Migrate"),
+    (9.0, "Rewrite"),
+    (10.1, "Delete"),
+]
+
+_RISK_THRESHOLDS: list[tuple[float, str]] = [
+    (3.0, "LOW"),
+    (5.5, "MEDIUM"),
+    (7.5, "HIGH"),
+    (10.1, "CRITICAL"),
+]
+
+
+# --- Data classes ---------------------------------------------------------
+
+
+@dataclass
+class DetectedSignal:
+    """A single migration intent signal found in the codebase."""
+
+    id: str
+    category: Literal["strong", "weak"]
+    description: str
+    files_affected: list[str] = field(default_factory=list)
+
+
+@dataclass
+class MigrationIntentResult:
+    """Result of migration intent evaluation."""
+
+    is_migration: bool
+    signals: list[DetectedSignal]
+    trigger_reason: str
+    mode_source: Literal["auto_detected", "explicit_param", "explicit_env"]
+
+
+@dataclass
+class ModuleAssessment:
+    """Risk assessment for a single module (directory)."""
+
+    path: str
+    debt_score: float | None
+    dead_code_score: float | None
+    complexity_score: float | None
+    composite_score: float | None
+    recommended_action: Literal[
+        "Keep", "Refactor", "Migrate", "Rewrite", "Delete", "Unknown"
+    ]
+    batch: int
+    risk: Literal["LOW", "MEDIUM", "HIGH", "CRITICAL"]
+    unknown: bool = False
+
+
+# --- Signal detection -----------------------------------------------------
+
+
+def _load_health_report(directory: Path) -> dict | None:
+    """Load cached health report JSON if available.
+
+    Args:
+        directory: Project root directory.
+
+    Returns:
+        Parsed JSON dict or None if not found / invalid.
+    """
+    report_path = directory / "ref-reports" / "platform_engineer" / "health_report.json"
+    if not report_path.exists():
+        logger.debug("health_report_not_found", path=str(report_path))
+        return None
+    try:
+        return json.loads(report_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.warning(
+            "health_report_load_failed", path=str(report_path), error=str(exc)
+        )
+        return None
+
+
+def _detect_soap_patterns(directory: Path) -> DetectedSignal | None:
+    """SIG-S1: Detect SOAP/XML-RPC usage.
+
+    Args:
+        directory: Project root directory.
+
+    Returns:
+        DetectedSignal if found, else None.
+    """
+    affected: list[str] = []
+    source_exts = {".py", ".ts", ".js", ".java", ".cs", ".xml"}
+
+    for path in directory.rglob("*"):
+        if not path.is_file() or path.suffix not in source_exts:
+            continue
+        if any(
+            skip in path.parts
+            for skip in ("node_modules", "__pycache__", ".git", "dist")
+        ):
+            continue
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+            if _SOAP_PATTERNS.search(text):
+                affected.append(str(path.relative_to(directory)))
+        except OSError:
+            continue
+
+    # Also check package manifests
+    for manifest in ("requirements.txt", "setup.cfg", "pyproject.toml"):
+        manifest_path = directory / manifest
+        if manifest_path.exists():
+            try:
+                text = manifest_path.read_text(encoding="utf-8", errors="ignore")
+                if _SOAP_PATTERNS.search(text) and str(manifest) not in affected:
+                    affected.append(manifest)
+            except OSError:
+                continue
+
+    if not affected:
+        return None
+
+    return DetectedSignal(
+        id="SIG-S1",
+        category="strong",
+        description=f"SOAP/XML-RPC patterns detected in {len(affected)} file(s)",
+        files_affected=affected,
+    )
+
+
+def _detect_db_in_controller(directory: Path) -> DetectedSignal | None:
+    """SIG-S2: Direct DB access in UI/controller layer (3+ files).
+
+    Args:
+        directory: Project root directory.
+
+    Returns:
+        DetectedSignal if found, else None.
+    """
+    affected: list[str] = []
+    source_exts = {".py", ".ts", ".js"}
+
+    for path in directory.rglob("*"):
+        if not path.is_file() or path.suffix not in source_exts:
+            continue
+        if any(skip in path.parts for skip in ("node_modules", "__pycache__", ".git")):
+            continue
+        if not _DB_CONTROLLER_DIRS.search(path.stem) and not _DB_CONTROLLER_DIRS.search(
+            str(path.parent.name)
+        ):
+            continue
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+            if _DB_IMPORTS.search(text):
+                affected.append(str(path.relative_to(directory)))
+        except OSError:
+            continue
+
+    if len(affected) < 3:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+        return None
+
+    return DetectedSignal(
+        id="SIG-S2",
+        category="strong",
+        description=f"Direct DB access in controller/view layer ({len(affected)} files)",
+        files_affected=affected,
+    )
+
+
+def _detect_old_framework_version(directory: Path) -> DetectedSignal | None:
+    """SIG-S3: Framework version >3 major releases behind current.
+
+    Checks pyproject.toml, requirements.txt, package.json.
+
+    Args:
+        directory: Project root directory.
+
+    Returns:
+        DetectedSignal if found, else None.
+    """
+    # Current major versions (update as ecosystem evolves)
+    _PYTHON_FRAMEWORK_CURRENT: dict[str, int] = {
+        "django": 5,
+        "flask": 3,
+        "fastapi": 0,
+        "sqlalchemy": 2,
+        "celery": 5,
+    }
+    _NODE_FRAMEWORK_CURRENT: dict[str, int] = {
+        "react": 18,
+        "angular": 17,
+        "vue": 3,
+        "express": 4,
+        "next": 14,
+    }
+
+    version_re = re.compile(r"[=><~^]*(\d+)\.")
+    affected: list[str] = []
+
+    # Check Python manifests
+    for manifest_name in ("requirements.txt", "pyproject.toml", "Pipfile"):
+        manifest = directory / manifest_name
+        if not manifest.exists():
+            continue
+        try:
+            text = manifest.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        for pkg, current_major in _PYTHON_FRAMEWORK_CURRENT.items():
+            pattern = re.compile(
+                rf"^\s*{re.escape(pkg)}\s*[=><~^]*\s*(\d+)\.",
+                re.IGNORECASE | re.MULTILINE,
+            )
+            match = pattern.search(text)
+            if match:
+                detected_major = int(match.group(1))
+                if current_major - detected_major >= 3:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+                    affected.append(
+                        f"{manifest_name}: {pkg}=={detected_major}.x (current: {current_major}.x)"
+                    )
+
+    # Check package.json
+    pkg_json = directory / "package.json"
+    if pkg_json.exists():
+        try:
+            data = json.loads(pkg_json.read_text(encoding="utf-8"))
+            deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+            for pkg, current_major in _NODE_FRAMEWORK_CURRENT.items():
+                version_str = deps.get(pkg, "")
+                m = version_re.search(version_str)
+                if m:
+                    detected_major = int(m.group(1))
+                    if current_major - detected_major >= 3:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+                        affected.append(
+                            f"package.json: {pkg}@{detected_major}.x (current: {current_major}.x)"
+                        )
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    if not affected:
+        return None
+
+    return DetectedSignal(
+        id="SIG-S3",
+        category="strong",
+        description=f"Framework version >3 major releases behind: {', '.join(affected)}",
+        files_affected=affected,
+    )
+
+
+def _detect_high_dead_code_codebase(report: dict | None) -> DetectedSignal | None:
+    """SIG-S4: Dead code density >30% across whole codebase.
+
+    Args:
+        report: Parsed health_report.json or None.
+
+    Returns:
+        DetectedSignal if found, else None.
+    """
+    if not report:
+        return None
+
+    findings = report.get("findings", [])
+    total_files = max(1, report.get("files_scanned", 1))
+    dead_code_files = {f["file"] for f in findings if f.get("scanner") == "dead_code"}
+    pct = len(dead_code_files) / total_files * 100
+
+    if pct < _STRONG_SIGNAL_DEAD_CODE_PCT:
+        return None
+
+    return DetectedSignal(
+        id="SIG-S4",
+        category="strong",
+        description=f"Dead code density {pct:.1f}% across codebase (threshold: {_STRONG_SIGNAL_DEAD_CODE_PCT}%)",
+        files_affected=list(dead_code_files)[:20],  # cap for readability
+    )
+
+
+def _detect_legacy_markers(directory: Path) -> DetectedSignal | None:
+    """SIG-W1: DEPRECATED/TODO: migrate markers in 5+ files.
+
+    Args:
+        directory: Project root directory.
+
+    Returns:
+        DetectedSignal if found, else None.
+    """
+    affected: list[str] = []
+    source_exts = {".py", ".ts", ".tsx", ".js", ".java", ".cs", ".go", ".rb"}
+
+    for path in directory.rglob("*"):
+        if not path.is_file() or path.suffix not in source_exts:
+            continue
+        if any(
+            skip in path.parts
+            for skip in ("node_modules", "__pycache__", ".git", "dist")
+        ):
+            continue
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+            if _LEGACY_MARKERS.search(text):
+                affected.append(str(path.relative_to(directory)))
+        except OSError:
+            continue
+
+    if len(affected) < _WEAK_SIGNAL_MARKER_FILES:
+        return None
+
+    return DetectedSignal(
+        id="SIG-W1",
+        category="weak",
+        description=f"Legacy markers (DEPRECATED/TODO: migrate) in {len(affected)} files",
+        files_affected=affected,
+    )
+
+
+def _detect_module_dead_code(report: dict | None) -> DetectedSignal | None:
+    """SIG-W2: Dead code density >20% in any single module.
+
+    Args:
+        report: Parsed health_report.json or None.
+
+    Returns:
+        DetectedSignal if found, else None.
+    """
+    if not report:
+        return None
+
+    findings = report.get("findings", [])
+    # Group dead_code findings by module (parent dir)
+    module_dead: dict[str, set[str]] = {}
+    module_files: dict[str, set[str]] = {}
+
+    for f in findings:
+        file_path = f.get("file", "")
+        if not file_path:
+            continue
+        module = str(Path(file_path).parent)
+        module_files.setdefault(module, set()).add(file_path)
+        if f.get("scanner") == "dead_code":
+            module_dead.setdefault(module, set()).add(file_path)
+
+    hot_modules: list[str] = []
+    for module, files in module_files.items():
+        dead_pct = len(module_dead.get(module, set())) / max(1, len(files)) * 100
+        if dead_pct > _WEAK_SIGNAL_DEAD_CODE_PCT:
+            hot_modules.append(f"{module} ({dead_pct:.1f}%)")
+
+    if not hot_modules:
+        return None
+
+    return DetectedSignal(
+        id="SIG-W2",
+        category="weak",
+        description=f"Dead code >20% in modules: {', '.join(hot_modules[:5])}",
+        files_affected=hot_modules,
+    )
+
+
+def _detect_high_complexity(report: dict | None) -> DetectedSignal | None:
+    """SIG-W3: Cyclomatic complexity >30 in 3+ functions.
+
+    Args:
+        report: Parsed health_report.json or None.
+
+    Returns:
+        DetectedSignal if found, else None.
+    """
+    if not report:
+        return None
+
+    findings = report.get("findings", [])
+    complex_funcs = [
+        f
+        for f in findings
+        if f.get("scanner") == "complexity"
+        and f.get("severity") in ("CRITICAL", "HIGH")
+    ]
+
+    if len(complex_funcs) < _WEAK_SIGNAL_COMPLEXITY_FUNCS:
+        return None
+
+    affected = [f.get("file", "") for f in complex_funcs[:20]]
+    return DetectedSignal(
+        id="SIG-W3",
+        category="weak",
+        description=f"High cyclomatic complexity in {len(complex_funcs)} functions",
+        files_affected=affected,
+    )
+
+
+def _detect_monolithic_files(directory: Path) -> DetectedSignal | None:
+    """SIG-W4: Files >1000 LOC with no separation of concerns.
+
+    Args:
+        directory: Project root directory.
+
+    Returns:
+        DetectedSignal if found, else None.
+    """
+    source_exts = {".py", ".ts", ".tsx", ".js", ".java", ".cs"}
+    affected: list[str] = []
+
+    for path in directory.rglob("*"):
+        if not path.is_file() or path.suffix not in source_exts:
+            continue
+        if any(
+            skip in path.parts
+            for skip in ("node_modules", "__pycache__", ".git", "dist")
+        ):
+            continue
+        try:
+            loc = sum(1 for _ in path.open(encoding="utf-8", errors="ignore"))
+            if loc > _WEAK_SIGNAL_MONOLITH_LOC:
+                affected.append(str(path.relative_to(directory)))
+        except OSError:
+            continue
+
+    if not affected:
+        return None
+
+    return DetectedSignal(
+        id="SIG-W4",
+        category="weak",
+        description=f"Monolithic files (>{_WEAK_SIGNAL_MONOLITH_LOC} LOC): {len(affected)} found",
+        files_affected=affected,
+    )
+
+
+def detect_migration_intent(
+    directory: Path,
+    explicit: bool = False,
+) -> MigrationIntentResult:
+    """Evaluate codebase signals against migration thresholds.
+
+    Reads ref-reports/platform_engineer/health_report.json for scanner-based
+    signals (dead code, complexity). Performs lightweight filesystem checks
+    for structural signals (SOAP, framework version, legacy markers).
+
+    Args:
+        directory: Project root directory.
+        explicit: If True, migration mode activates regardless of signals.
+
+    Returns:
+        MigrationIntentResult with detection outcome and signals found.
+    """
+    # Determine mode source
+    env_explicit = os.environ.get("REF_MIGRATION_MODE") == "1"
+    if env_explicit:
+        mode_source: Literal["auto_detected", "explicit_param", "explicit_env"] = (
+            "explicit_env"
+        )
+    elif explicit:
+        mode_source = "explicit_param"
+    else:
+        mode_source = "auto_detected"
+
+    report = _load_health_report(directory)
+
+    # Evaluate all signals
+    signal_checks = [
+        _detect_soap_patterns(directory),
+        _detect_db_in_controller(directory),
+        _detect_old_framework_version(directory),
+        _detect_high_dead_code_codebase(report),
+        _detect_legacy_markers(directory),
+        _detect_module_dead_code(report),
+        _detect_high_complexity(report),
+        _detect_monolithic_files(directory),
+    ]
+
+    signals = [s for s in signal_checks if s is not None]
+    strong = [s for s in signals if s.category == "strong"]
+    weak = [s for s in signals if s.category == "weak"]
+
+    auto_trigger = len(strong) >= 1 or len(weak) >= 2  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+    is_migration = explicit or env_explicit or auto_trigger
+
+    if is_migration:
+        if explicit or env_explicit:
+            trigger_reason = f"Migration mode: explicitly enabled ({mode_source})"
+        elif strong:
+            trigger_reason = (
+                f"1 strong signal: {strong[0].id} ({strong[0].description[:60]})"
+            )
+        else:
+            trigger_reason = (
+                f"{len(weak)} weak signals: {', '.join(s.id for s in weak[:3])}"
+            )
+    else:
+        weak_count = len(weak)
+        strong_count = len(strong)
+        trigger_reason = (
+            f"Insufficient signals: {strong_count} strong, {weak_count} weak "
+            f"(need 1 strong OR 2+ weak)"
+        )
+        if signals:
+            trigger_reason += f" — advisory: {signals[0].id} detected"
+
+    logger.info(
+        "migration_intent_evaluated",
+        is_migration=is_migration,
+        strong_signals=len(strong),
+        weak_signals=len(weak),
+        trigger_reason=trigger_reason,
+    )
+
+    return MigrationIntentResult(
+        is_migration=is_migration,
+        signals=signals,
+        trigger_reason=trigger_reason,
+        mode_source=mode_source,
+    )
+
+
+# --- Module assessment ----------------------------------------------------
+
+
+def _classify_action(score: float) -> str:
+    """Map composite score to recommended action.
+
+    Args:
+        score: Composite risk score 0.0–10.0.
+
+    Returns:
+        Recommended action string.
+    """
+    for threshold, action in _ACTION_THRESHOLDS:
+        if score <= threshold:
+            return action
+    return "Delete"
+
+
+def _classify_risk(score: float) -> str:
+    """Map composite score to risk level.
+
+    Args:
+        score: Composite risk score 0.0–10.0.
+
+    Returns:
+        Risk level string.
+    """
+    for threshold, risk in _RISK_THRESHOLDS:
+        if score <= threshold:
+            return risk
+    return "CRITICAL"
+
+
+class MigrationMapper:
+    """Aggregates scanner findings into per-module assessments and produces artifacts.
+
+    Args:
+        directory: Project root directory.
+        report: Parsed health_report.json dict, or None to load from disk.
+    """
+
+    def __init__(self, directory: Path, report: dict | None = None) -> None:
+        self._directory = directory
+        self._report = report or _load_health_report(directory) or {}
+
+    def _compute_composite_score(
+        self,
+        debt_score: float,
+        dead_code_score: float,
+        complexity_score: float,
+        coverage_score: float,
+    ) -> float:
+        """Compute weighted composite risk score.
+
+        Args:
+            debt_score: Debt density 0.0–10.0.
+            dead_code_score: Dead code density 0.0–10.0.
+            complexity_score: Complexity risk 0.0–10.0.
+            coverage_score: Inverse coverage 0.0–10.0 (high = low coverage = high risk).
+
+        Returns:
+            Composite score 0.0–10.0.
+        """
+        raw = (
+            debt_score * _W_DEBT
+            + dead_code_score * _W_DEAD
+            + complexity_score * _W_COMPLEXITY
+            + coverage_score * _W_COVERAGE
+        )
+        return round(min(10.0, max(0.0, raw)), 2)
+
+    def assess_modules(self) -> list[ModuleAssessment]:
+        """Build per-module risk assessments from health report findings.
+
+        Groups findings by parent directory (= module). Normalises counts
+        to 0–10 scores. Assigns batch order by risk (CRITICAL=0, HIGH=1, ...).
+
+        Returns:
+            Sorted list of ModuleAssessment (highest composite score first).
+        """
+        findings = self._report.get("findings", [])
+        if not findings:
+            return []
+
+        # Group by module (parent dir of each finding's file)
+        module_debt: dict[str, int] = {}
+        module_dead: dict[str, set[str]] = {}
+        module_complexity_sev: dict[str, list[str]] = {}
+        module_file_count: dict[str, set[str]] = {}
+
+        sev_weight = {"CRITICAL": 10.0, "HIGH": 7.5, "MEDIUM": 5.0, "LOW": 2.5}
+
+        for f in findings:
+            file_path = f.get("file", "")
+            if not file_path:
+                continue
+            module = str(Path(file_path).parent)
+            scanner = f.get("scanner", "")
+            severity = f.get("severity", "LOW")
+            module_file_count.setdefault(module, set()).add(file_path)
+
+            if scanner == "debt":
+                module_debt[module] = module_debt.get(module, 0) + 1
+            elif scanner == "dead_code":
+                module_dead.setdefault(module, set()).add(file_path)
+            elif scanner == "complexity":
+                module_complexity_sev.setdefault(module, []).append(severity)
+
+        if not module_file_count:
+            return []
+
+        assessments: list[ModuleAssessment] = []
+
+        for module, files in module_file_count.items():
+            file_count = max(1, len(files))
+
+            # Debt: findings per file, normalised 0–10
+            debt_raw = module_debt.get(module, 0)
+            debt_score = min(10.0, (debt_raw / file_count) * 2.5)
+
+            # Dead code: affected files / total files, normalised 0–10
+            dead_files = len(module_dead.get(module, set()))
+            dead_code_score = min(10.0, (dead_files / file_count) * 10.0)
+
+            # Complexity: average severity weight of complexity findings
+            sev_list = module_complexity_sev.get(module, [])
+            if sev_list:
+                complexity_score = min(
+                    10.0,
+                    sum(sev_weight.get(s, 2.5) for s in sev_list) / len(sev_list),
+                )
+            else:
+                complexity_score = 0.0
+
+            # Coverage: no coverage data available from health scanner — use neutral 5.0
+            coverage_score = 5.0
+
+            all_none = debt_raw == 0 and dead_files == 0 and not sev_list
+            if all_none:
+                assessment = ModuleAssessment(
+                    path=module,
+                    debt_score=None,
+                    dead_code_score=None,
+                    complexity_score=None,
+                    composite_score=None,
+                    recommended_action="Unknown",
+                    batch=99,
+                    risk="LOW",
+                    unknown=True,
+                )
+            else:
+                composite = self._compute_composite_score(
+                    debt_score, dead_code_score, complexity_score, coverage_score
+                )
+                action = _classify_action(composite)
+                risk = _classify_risk(composite)
+                # Batch: CRITICAL→0, HIGH→1, MEDIUM→2, LOW→3
+                batch_map = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}
+                assessment = ModuleAssessment(
+                    path=module,
+                    debt_score=round(debt_score, 2),
+                    dead_code_score=round(dead_code_score, 2),
+                    complexity_score=round(complexity_score, 2),
+                    composite_score=composite,
+                    recommended_action=action,  # type: ignore[arg-type]
+                    batch=batch_map.get(risk, 3),
+                    risk=risk,  # type: ignore[arg-type]
+                    unknown=False,
+                )
+            assessments.append(assessment)
+
+        assessments.sort(key=lambda a: (a.composite_score or 0.0), reverse=True)
+        return assessments
+
+    def generate_map(
+        self,
+        intent: MigrationIntentResult,
+        assessments: list[ModuleAssessment],
+    ) -> tuple[Path, Path]:
+        """Generate MIGRATION_MAP.md and ref-reports/migration_map.json.
+
+        Args:
+            intent: Migration intent detection result.
+            assessments: Per-module risk assessments from assess_modules().
+
+        Returns:
+            Tuple of (markdown_path, json_path).
+
+        Raises:
+            OSError: If artifact write fails.
+        """
+        md_path = self._write_markdown(intent, assessments)
+        json_path = self._write_json(intent, assessments)
+        logger.info(
+            "migration_map_generated",
+            md_path=str(md_path),
+            json_path=str(json_path),
+            modules=len(assessments),
+        )
+        return md_path, json_path
+
+    def _write_markdown(
+        self,
+        intent: MigrationIntentResult,
+        assessments: list[ModuleAssessment],
+    ) -> Path:
+        """Write docs/MIGRATION_MAP.md.
+
+        Args:
+            intent: Migration intent result.
+            assessments: Module assessments.
+
+        Returns:
+            Path to written file.
+        """
+        action_counts: dict[str, int] = {}
+        for a in assessments:
+            action_counts[a.recommended_action] = (
+                action_counts.get(a.recommended_action, 0) + 1
+            )
+
+        scores = [
+            a.composite_score for a in assessments if a.composite_score is not None
+        ]
+        overall_score = sum(scores) / max(1, len(scores)) if scores else 0.0
+        overall_risk = _classify_risk(overall_score)
+
+        batches = {a.batch for a in assessments if not a.unknown}
+        estimated_batches = len(batches - {99})
+
+        lines = [
+            "# Migration Map",
+            "",
+            "<!-- REF:AUTO -->",
+            "## Summary",
+            "",
+            f"- **Total modules assessed:** {len(assessments)}",
+            f"- **Migrate:** {action_counts.get('Migrate', 0)} | "
+            f"**Rewrite:** {action_counts.get('Rewrite', 0)} | "
+            f"**Delete:** {action_counts.get('Delete', 0)} | "
+            f"**Keep:** {action_counts.get('Keep', 0)} | "
+            f"**Refactor:** {action_counts.get('Refactor', 0)}",
+            f"- **Estimated migration batches:** {estimated_batches}",
+            f"- **Overall migration risk:** {overall_risk}",
+            f"- **Migration mode trigger:** {intent.trigger_reason}",
+            "",
+            "---",
+            "",
+            "## Intent Signals Detected",
+            "",
+        ]
+
+        if intent.signals:
+            lines.append("| Signal ID | Category | Description | Files Affected |")
+            lines.append("|-----------|----------|-------------|----------------|")
+            for sig in intent.signals:
+                files_str = str(len(sig.files_affected))
+                lines.append(
+                    f"| `{sig.id}` | {sig.category} | {sig.description[:70]} | {files_str} |"
+                )
+        else:
+            lines.append("_No signals detected. Migration mode explicitly enabled._")
+
+        lines += [
+            "",
+            "---",
+            "",
+            "## Module Assessment",
+            "",
+            "| Module | Debt Score | Dead Code Score | Complexity Score | Composite | Action | Batch | Risk |",
+            "|--------|-----------|-----------------|-----------------|-----------|--------|-------|------|",
+        ]
+
+        for a in assessments:
+            if a.unknown:
+                lines.append(
+                    f"| `{a.path}` | — | — | — | — | Unknown (manual review) | — | — |"
+                )
+            else:
+                lines.append(
+                    f"| `{a.path}` | {a.debt_score:.1f} | {a.dead_code_score:.1f} | "
+                    f"{a.complexity_score:.1f} | **{a.composite_score:.1f}** | "
+                    f"**{a.recommended_action}** | {a.batch} | {a.risk} |"
+                )
+
+        lines += [
+            "",
+            "---",
+            "",
+            "## Dependency Order",
+            "",
+            "```mermaid",
+            "graph TD",
+        ]
+
+        batch_modules: dict[int, list[str]] = {}
+        for a in assessments:
+            if not a.unknown:
+                batch_modules.setdefault(a.batch, []).append(a.path)
+
+        for batch_num in sorted(batch_modules.keys()):
+            prev_batch = batch_num - 1
+            for module in batch_modules[batch_num]:
+                safe_id = re.sub(r"[^a-zA-Z0-9_]", "_", module)
+                lines.append(f"  {safe_id}[{module}]")
+                if prev_batch in batch_modules:
+                    for prev_mod in batch_modules[prev_batch]:
+                        prev_id = re.sub(r"[^a-zA-Z0-9_]", "_", prev_mod)
+                        lines.append(f"  {prev_id} --> {safe_id}")
+
+        lines.append("```")
+        lines.append("")
+
+        docs_dir = self._directory / "docs"
+        docs_dir.mkdir(exist_ok=True)
+        md_path = docs_dir / "MIGRATION_MAP.md"
+        md_path.write_text("\n".join(lines), encoding="utf-8")
+        return md_path
+
+    def _write_json(
+        self,
+        intent: MigrationIntentResult,
+        assessments: list[ModuleAssessment],
+    ) -> Path:
+        """Write ref-reports/migration_map.json.
+
+        Args:
+            intent: Migration intent result.
+            assessments: Module assessments.
+
+        Returns:
+            Path to written file.
+        """
+        scores = [
+            a.composite_score for a in assessments if a.composite_score is not None
+        ]
+        overall_score = sum(scores) / max(1, len(scores)) if scores else 0.0
+
+        payload = {
+            "schema_version": "1.0",
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "migration_mode": intent.mode_source,
+            "overall_risk": _classify_risk(overall_score),
+            "trigger_reason": intent.trigger_reason,
+            "signals": [
+                {
+                    "id": s.id,
+                    "category": s.category,
+                    "description": s.description,
+                    "files_affected": s.files_affected,
+                }
+                for s in intent.signals
+            ],
+            "modules": [
+                {
+                    "path": a.path,
+                    "debt_score": a.debt_score,
+                    "dead_code_score": a.dead_code_score,
+                    "complexity_score": a.complexity_score,
+                    "composite_score": a.composite_score,
+                    "recommended_action": a.recommended_action,
+                    "batch": a.batch,
+                    "risk": a.risk,
+                    "unknown": a.unknown,
+                }
+                for a in assessments
+            ],
+        }
+
+        reports_dir = self._directory / "ref-reports"
+        reports_dir.mkdir(exist_ok=True)
+        json_path = reports_dir / "migration_map.json"
+        json_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+        return json_path