ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/migration_readiness_scanner.py

@@ -0,0 +1,209 @@
+"""Migration readiness assessment scanner.
+
+Aggregates per-module composite scores from health_report.json without
+re-running full discovery or activating migration mode.
+
+Usage:
+    from ref_agents.tools.migration_readiness_scanner import scan_migration_readiness
+    report = scan_migration_readiness("/path/to/project")
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import structlog
+
+from ref_agents.tools.migration_mapper import MigrationMapper, ModuleAssessment
+
+logger = structlog.get_logger(__name__)
+
+_HEALTH_REPORT_PATH = Path("ref-reports") / "platform_engineer" / "health_report.json"
+
+_RISK_ORDER: dict[str, int] = {"CRITICAL": 4, "HIGH": 3, "MEDIUM": 2, "LOW": 1}
+
+_WARNING_NO_REPORT = (
+    "⚠️ Warning: health_report.json not found.\n"
+    'Run scan(target="health", directory=".") first to generate scanner data.\n'
+    "Returning empty assessment."
+)
+
+
+def _load_health_report(directory: Path) -> dict | None:
+    """Load health_report.json from ref-reports/platform_engineer/.
+
+    Args:
+        directory: Project root directory.
+
+    Returns:
+        Parsed JSON dict or None if not found or invalid.
+    """
+    report_path = directory / _HEALTH_REPORT_PATH
+    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 _compute_overall_risk(assessments: list[ModuleAssessment]) -> str:
+    """Return worst risk level across all assessed modules.
+
+    Args:
+        assessments: Module assessments from MigrationMapper.
+
+    Returns:
+        "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" — worst risk found, or "LOW" if empty.
+    """
+    if not assessments:
+        return "LOW"
+    return max(
+        (a.risk for a in assessments if not a.unknown),
+        key=lambda r: _RISK_ORDER.get(r, 0),
+        default="LOW",
+    )
+
+
+def _write_outputs(
+    directory: Path,
+    assessments: list[ModuleAssessment],
+    overall_risk: str,
+) -> tuple[Path, Path]:
+    """Write migration_readiness.md and migration_readiness.json to ref-reports/.
+
+    Args:
+        directory: Project root directory.
+        assessments: Module assessments from MigrationMapper.
+        overall_risk: Overall project risk level string.
+
+    Returns:
+        Tuple of (md_path, json_path).
+
+    Raises:
+        OSError: If file write fails.
+    """
+    reports_dir = directory / "ref-reports"
+    reports_dir.mkdir(exist_ok=True)
+
+    md_path = reports_dir / "migration_readiness.md"
+    json_path = reports_dir / "migration_readiness.json"
+
+    timestamp = datetime.now(timezone.utc).isoformat()
+
+    # --- Markdown ---
+    action_counts: dict[str, int] = {}
+    for a in assessments:
+        action_counts[a.recommended_action] = (
+            action_counts.get(a.recommended_action, 0) + 1
+        )
+
+    lines = [
+        "# Migration Readiness Report",
+        "",
+        f"**Generated:** {timestamp}",
+        f"**Directory:** {directory}",
+        f"**Modules assessed:** {len(assessments)}",
+        "",
+        "## Module Scores",
+        "",
+        "| Module | Debt | Dead Code | Complexity | Composite | Action | Risk |",
+        "|--------|------|-----------|------------|-----------|--------|------|",
+    ]
+
+    for a in assessments:
+        if a.unknown:
+            lines.append(f"| `{a.path}` | — | — | — | — | Unknown | — |")
+        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.risk} |"
+            )
+
+    lines += [
+        "",
+        "## Summary",
+        "",
+        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"- **Overall risk:** {overall_risk}",
+        "",
+    ]
+
+    md_path.write_text("\n".join(lines), encoding="utf-8")
+
+    # --- JSON ---
+    payload = {
+        "schema_version": "1.0",
+        "generated_at": timestamp,
+        "directory": str(directory),
+        "overall_risk": overall_risk,
+        "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
+        ],
+    }
+    json_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+    logger.info(
+        "migration_readiness_written",
+        md_path=str(md_path),
+        json_path=str(json_path),
+        modules=len(assessments),
+        overall_risk=overall_risk,
+    )
+
+    return md_path, json_path
+
+
+def scan_migration_readiness(directory: str) -> str:
+    """Run migration readiness assessment for all modules in directory.
+
+    Reads ref-reports/platform_engineer/health_report.json and produces
+    per-module composite scores. Does not run scanners or set session state.
+
+    Args:
+        directory: Project root directory path.
+
+    Returns:
+        Markdown-formatted readiness report string, or warning if no health data.
+    """
+    root = Path(directory)
+
+    report = _load_health_report(root)
+    if report is None:
+        return _WARNING_NO_REPORT
+
+    mapper = MigrationMapper(directory=root, report=report)
+    assessments = mapper.assess_modules()
+    overall_risk = _compute_overall_risk(assessments)
+    md_path, _ = _write_outputs(root, assessments, overall_risk)
+
+    logger.info(
+        "scan_migration_readiness_complete",
+        directory=directory,
+        modules=len(assessments),
+        overall_risk=overall_risk,
+    )
+
+    return md_path.read_text(encoding="utf-8")