blasttrace 1.2.0__py2.py3-none-any.whl

blasttrace/remediation.py

@@ -0,0 +1,220 @@
+"""
+BlastTrace Surgical Multi-File Sync Plan & Patch Generator
+Produces ordered multi-file synchronization checklists and copy-paste code patches
+across Database, Backend, API, Frontend, and Tests.
+"""
+
+from typing import Dict, Any, List, Optional
+
+
+_LAYER_ORDER = {
+    "database": 1,
+    "backend": 2,
+    "api": 3,
+    "frontend": 4,
+    "tests": 5,
+}
+
+
+def generate_surgical_sync_plan(
+    topology: Dict[str, Any],
+    classification_result: Dict[str, Any],
+    downstream_chains: List[List[str]],
+) -> Dict[str, Any]:
+    """
+    Generates an ordered checklist of files/functions to synchronize and copy-paste
+    remediation patches when a breaking change is detected.
+    """
+    gate_status = classification_result.get("gate_status", "PASS")
+    classification = classification_result.get("classification", "SAFE_INTERNAL_REFACTOR")
+    target_symbol = classification_result.get("target_symbol", "")
+    target_file = classification_result.get("target_file", "")
+    proposed_edit = classification_result.get("proposed_edit", "")
+
+    nodes_by_id = topology.get("nodes_by_id", {})
+    impacted_nodes: List[Dict[str, Any]] = []
+    seen_ids = set()
+
+    for chain in downstream_chains:
+        for idx, nid in enumerate(chain):
+            if idx == 0:
+                continue
+            if nid not in seen_ids:
+                seen_ids.add(nid)
+                nmeta = nodes_by_id.get(nid, {"id": nid, "name": nid, "layer": "backend", "file": ""})
+                impacted_nodes.append(nmeta)
+
+    impacted_nodes.sort(key=lambda n: (_LAYER_ORDER.get(n.get("layer", "backend"), 9), n.get("file", "")))
+
+    checklist: List[Dict[str, Any]] = []
+    patches: List[Dict[str, str]] = []
+
+    # 1. Origin backward-compatibility patch
+    if classification == "BREAKING_FUNCTION_SIGNATURE":
+        patches.append({
+            "layer": "backend",
+            "file": target_file or "backend_module.py",
+            "symbol": target_symbol,
+            "strategy": "Provide backward-compatible default parameter value so existing callers do not break",
+            "patch": (
+                f"# SURGICAL SAFE-COMPATIBILITY PATCH ({target_file})\n"
+                f"# Keep newly added parameters optional with a default value during rollout:\n"
+                f"{_suggest_safe_signature(target_symbol, proposed_edit)}"
+            ),
+        })
+    elif classification == "BREAKING_DATABASE_SCHEMA":
+        col_short = target_symbol.split(".")[-1]
+        patches.append({
+            "layer": "database",
+            "file": target_file or "schema.sql",
+            "symbol": target_symbol,
+            "strategy": "Use Expand-and-Contract two-phase migration instead of immediate column drop/rename",
+            "patch": (
+                f"-- PHASE 1 (EXPAND): Add new column with DEFAULT and backfill before dropping '{col_short}'\n"
+                f"ALTER TABLE {target_symbol.split('.')[0] if '.' in target_symbol else 'target_table'} "
+                f"ADD COLUMN IF NOT EXISTS {col_short}_v2 NUMERIC(12, 2) DEFAULT 0.00;\n"
+                f"-- Keep '{col_short}' readable until all ORM, API, and Frontend consumers are synced."
+            ),
+        })
+    elif classification == "BREAKING_API_CONTRACT":
+        patches.append({
+            "layer": "api",
+            "file": target_file or "api/routes.py",
+            "symbol": target_symbol,
+            "strategy": "Preserve legacy response field alias alongside the new contract field",
+            "patch": (
+                f"# SURGICAL API DUAL-EMIT PATCH ({target_file})\n"
+                f"# Emit both legacy and updated keys in the JSON payload until frontend deployment completes:\n"
+                f"return {{\n"
+                f'    "status": "ok",\n'
+                f'    # Retain legacy contract key for active frontend consumers\n'
+                f"}}"
+            ),
+        })
+
+    # 2. Ordered downstream multi-file sync checklist & per-layer patches
+    for step_idx, nmeta in enumerate(impacted_nodes, start=1):
+        layer = nmeta.get("layer", "backend")
+        rel_file = nmeta.get("file", "")
+        name = nmeta.get("name", nmeta.get("id", ""))
+        ntype = nmeta.get("type", "")
+
+        action_desc = _describe_sync_action(layer, ntype, name, target_symbol, classification)
+        checklist.append({
+            "step": step_idx,
+            "layer": layer,
+            "file": rel_file,
+            "symbol": name,
+            "node_type": ntype,
+            "required_action": action_desc,
+        })
+
+        if layer == "frontend" and rel_file:
+            prop_name = nmeta.get("property") or target_symbol.split(".")[-1]
+            patches.append({
+                "layer": "frontend",
+                "file": rel_file,
+                "symbol": name,
+                "strategy": f"Add defensive fallback on response property '{prop_name}' in {rel_file}",
+                "patch": (
+                    f"// SURGICAL FRONTEND CONSUMER PATCH ({rel_file})\n"
+                    f"const safe_{prop_name} = data?.{prop_name} ?? data?.{prop_name}_v2 ?? 0;"
+                ),
+            })
+        elif layer == "backend" and ntype in ("orm_field", "class_field") and rel_file:
+            fld = nmeta.get("field") or target_symbol.split(".")[-1]
+            patches.append({
+                "layer": "backend",
+                "file": rel_file,
+                "symbol": name,
+                "strategy": f"Synchronize ORM model attribute '{name}' with updated schema definition",
+                "patch": (
+                    f"# SURGICAL ORM SYNC PATCH ({rel_file})\n"
+                    f"# Ensure '{fld}' maps cleanly or provides a @property compatibility shim:\n"
+                    f"@property\n"
+                    f"def {fld}_compat(self):\n"
+                    f"    return getattr(self, '{fld}', None)"
+                ),
+            })
+
+    impacted_test_files = sorted({
+        n.get("file", "")
+        for n in impacted_nodes
+        if n.get("layer") == "tests" and n.get("file")
+    })
+
+    return {
+        "gate_status": gate_status,
+        "classification": classification,
+        "total_impacted_nodes": len(impacted_nodes),
+        "ordered_sync_checklist": checklist,
+        "surgical_patches": patches,
+        "recommended_test_command": (
+            f"pytest {' '.join(impacted_test_files)}"
+            if impacted_test_files
+            else "pytest"
+        ),
+    }
+
+
+def _suggest_safe_signature(symbol_name: str, proposed_edit: str) -> str:
+    clean = proposed_edit.strip()
+    if clean.startswith(("def ", "async def ")) and ")" in clean:
+        head, tail = clean.rsplit(")", 1)
+        if "=" not in head.split(",")[-1]:
+            return f"{head} = None){tail}"
+        return clean
+    return f"def {symbol_name}(*args, **kwargs): ..."
+
+
+def _describe_sync_action(layer: str, ntype: str, name: str, target_symbol: str, classification: str) -> str:
+    if layer == "database":
+        return f"Update database column/constraint reference '{name}' to match '{target_symbol}'."
+    if layer == "backend":
+        if ntype in ("orm_model", "orm_field", "class_field"):
+            return f"Sync ORM/model field '{name}' with schema change on '{target_symbol}'."
+        return f"Update call site or field access inside '{name}' to match new contract of '{target_symbol}'."
+    if layer == "api":
+        return f"Update API endpoint/serializer '{name}' payload contract and OpenAPI schema."
+    if layer == "frontend":
+        return f"Update frontend UI component/consumer '{name}' response property binding and TypeScript interface."
+    if layer == "tests":
+        return f"Re-run and update assertions in covering test '{name}'."
+    return f"Synchronize '{name}' with modified contract '{target_symbol}'."
+
+
+def generate_cycle_refactoring_plan(cycles: List[List[str]]) -> Dict[str, Any]:
+    """
+    Produces surgical refactoring recommendations to break circular import/dependency loops.
+    """
+    if not cycles:
+        return {
+            "status": "Clean",
+            "message": "Zero circular code dependencies detected.",
+            "refactoring_patches": [],
+        }
+
+    patches: List[Dict[str, str]] = []
+    for idx, cycle in enumerate(cycles):
+        mod_a = cycle[0]
+        mod_b = cycle[1] if len(cycle) > 1 else cycle[0]
+        patches.append({
+            "cycle_index": idx + 1,
+            "cycle_members": cycle,
+            "strategic_goal": f"Break circular dependency between '{mod_a}' and '{mod_b}'",
+            "recommended_pattern": "Extract shared types/interfaces into a dedicated contracts module or move runtime import inside function scope (TYPE_CHECKING guard).",
+            "surgical_patch": (
+                f"# SURGICAL CYCLE-BREAKER PATCH (in {mod_a})\n"
+                f"from typing import TYPE_CHECKING\n"
+                f"if TYPE_CHECKING:\n"
+                f"    # Keep static type-checking without runtime circular import\n"
+                f"    import {mod_b.split(':')[-1].replace('/', '.').replace('.py', '')}\n"
+            ),
+        })
+
+    return {
+        "status": "Circular Dependencies Detected",
+        "cycles_count": len(cycles),
+        "refactoring_patches": patches,
+    }
+