blasttrace 1.0.2__py3-none-any.whl

blasttrace/__init__.py

@@ -0,0 +1,7 @@
+"""
+BlastTrace — Pre-Edit Full-Stack Breaking-Change & Contract Blast-Radius Engine.
+"""
+
+__version__ = "1.0.2"
+__engine__ = "BlastTrace Native Core"
+

blasttrace/classifier.py

@@ -0,0 +1,415 @@
+"""
+BlastTrace Evidence-Based Breaking-Change Classifier
+Evaluates proposed code, schema, and API contract edits for the Pre-Edit Breaking-Change Gate.
+"""
+
+import ast
+import os
+import re
+from typing import Dict, Any, List, Optional
+
+from blasttrace.parsers.python_ast_parser import _extract_function_signature
+from blasttrace.parsers.ts_react_parser import _parse_ts_params
+
+
+def classify_proposed_edit(
+    topology: Dict[str, Any],
+    file_path: str,
+    symbol_name: str,
+    proposed_signature_or_diff: str,
+    downstream_chains: List[List[str]],
+) -> Dict[str, Any]:
+    """
+    Compares the existing symbol, database column, or API route contract against
+    the proposed signature or diff, returning the breaking classification, gate status
+    (PASS / WARN / BLOCK), detailed reasons, and formatted hop-by-hop evidence chains.
+    """
+    rel_file = _normalize_rel_path(file_path, topology.get("repo_root", ""))
+    lower_file = rel_file.lower()
+    prop_text = proposed_signature_or_diff.strip()
+    has_consumers = len(downstream_chains) > 0
+
+    # 1. Database Schema / Migration Classification
+    if lower_file.endswith((".sql", ".prisma")) or symbol_name.lower().startswith("db:") or "." in symbol_name and symbol_name.split(".")[0].lower() in topology.get("db_tables", {}):
+        return _classify_db_edit(topology, rel_file, symbol_name, prop_text, downstream_chains)
+
+    # 2. API Contract Classification
+    if symbol_name.upper().startswith(("GET ", "POST ", "PUT ", "DELETE ", "PATCH ", "API:")) or symbol_name.startswith("/api"):
+        return _classify_api_edit(topology, rel_file, symbol_name, prop_text, downstream_chains)
+
+    # 3. Python Function / Method / Class / ORM Classification
+    if lower_file.endswith(".py"):
+        # Check if proposed edit modifies an API decorator or response payload field
+        if any(tok in prop_text for tok in ("@app.", "@router.", "route(", "response_model")):
+            return _classify_api_edit(topology, rel_file, symbol_name, prop_text, downstream_chains)
+        return _classify_python_signature_edit(topology, rel_file, symbol_name, prop_text, downstream_chains)
+
+    # 4. TypeScript / React Component / Function Classification
+    if lower_file.endswith((".ts", ".tsx", ".js", ".jsx")):
+        return _classify_ts_signature_edit(topology, rel_file, symbol_name, prop_text, downstream_chains)
+
+    # Default fallback inspection
+    return _classify_generic_edit(topology, rel_file, symbol_name, prop_text, downstream_chains)
+
+
+def _normalize_rel_path(file_path: str, repo_root: str) -> str:
+    if not file_path:
+        return ""
+    norm = file_path.replace("\\", "/")
+    if repo_root and os.path.isabs(file_path):
+        try:
+            return os.path.relpath(file_path, repo_root).replace("\\", "/")
+        except ValueError:
+            return norm
+    return norm
+
+
+def _classify_db_edit(
+    topology: Dict[str, Any],
+    rel_file: str,
+    symbol_name: str,
+    prop_text: str,
+    downstream_chains: List[List[str]],
+) -> Dict[str, Any]:
+    upper_prop = prop_text.upper()
+    reasons: List[str] = []
+    classification = "SAFE_INTERNAL_REFACTOR"
+
+    if any(k in upper_prop for k in ("DROP COLUMN", "DROP TABLE", "RENAME COLUMN", "RENAME TO", "REMOVED")):
+        classification = "BREAKING_DATABASE_SCHEMA"
+        reasons.append(f"Column or table '{symbol_name}' is being dropped or renamed, breaking active ORM and query bindings.")
+    elif "NOT NULL" in upper_prop and "DEFAULT" not in upper_prop:
+        classification = "BREAKING_DATABASE_SCHEMA"
+        reasons.append(f"Adding NOT NULL constraint on '{symbol_name}' without a DEFAULT value breaks existing INSERT/ORM writes.")
+    elif any(k in upper_prop for k in ("ALTER COLUMN", "TYPE VARCHAR(", "TYPE INT", "NARROW")):
+        classification = "BREAKING_DATABASE_SCHEMA"
+        reasons.append(f"Column type alteration on '{symbol_name}' risks data truncation or serializer type mismatch across consumers.")
+    elif "-" in prop_text and "+" in prop_text:
+        classification = "BREAKING_DATABASE_SCHEMA"
+        reasons.append(f"Schema definition diff on '{symbol_name}' modifies column contract consumed downstream.")
+
+    gate_status = _compute_gate_status(classification, downstream_chains)
+    return {
+        "gate_status": gate_status,
+        "classification": classification,
+        "target_file": rel_file,
+        "target_symbol": symbol_name,
+        "proposed_edit": prop_text,
+        "reasons": reasons or ["Schema modification is backward-compatible with existing table contracts."],
+        "evidence_chains": format_evidence_chains(topology, downstream_chains),
+    }
+
+
+def _classify_api_edit(
+    topology: Dict[str, Any],
+    rel_file: str,
+    symbol_name: str,
+    prop_text: str,
+    downstream_chains: List[List[str]],
+) -> Dict[str, Any]:
+    reasons: List[str] = []
+    classification = "SAFE_INTERNAL_REFACTOR"
+    upper_prop = prop_text.upper()
+
+    # Check against existing route metadata if available
+    matched_route = None
+    for r in topology.get("api_routes", []):
+        if symbol_name in (r["id"], r["path"], r["normalized_path"], r["handler"]):
+            matched_route = r
+            break
+
+    if matched_route:
+        old_path = matched_route["path"]
+        old_method = matched_route["method"]
+        # Check if new route path or method differs
+        path_match = re.search(r'[`"\'](/[^`"\']+)[`"\']', prop_text)
+        if path_match and path_match.group(1).rstrip("/") != old_path.rstrip("/"):
+            classification = "BREAKING_API_CONTRACT"
+            reasons.append(f"API route path changed from '{old_path}' to '{path_match.group(1)}', breaking frontend callers.")
+
+        method_match = re.search(r"\b(GET|POST|PUT|DELETE|PATCH)\b", upper_prop)
+        if method_match and method_match.group(1) != old_method:
+            classification = "BREAKING_API_CONTRACT"
+            reasons.append(f"HTTP method changed from '{old_method}' to '{method_match.group(1)}'.")
+
+        for rf in matched_route.get("response_fields", []):
+            if f"-{rf}" in prop_text or f"removed {rf}" in prop_text.lower() or (
+                "return {" in prop_text and f'"{rf}"' not in prop_text and f"'{rf}'" not in prop_text
+            ):
+                classification = "BREAKING_API_CONTRACT"
+                reasons.append(f"Response payload field '{rf}' was removed or renamed from '{old_method} {old_path}'.")
+
+    if classification == "SAFE_INTERNAL_REFACTOR":
+        if any(w in prop_text.lower() for w in ("remove", "rename", "drop", "v2", "breaking")):
+            classification = "BREAKING_API_CONTRACT"
+            reasons.append(f"Proposed API contract change on '{symbol_name}' alters endpoint path, method, or response payload shape.")
+
+    gate_status = _compute_gate_status(classification, downstream_chains)
+    return {
+        "gate_status": gate_status,
+        "classification": classification,
+        "target_file": rel_file,
+        "target_symbol": symbol_name,
+        "proposed_edit": prop_text,
+        "reasons": reasons or ["API endpoint contract remains backward-compatible."],
+        "evidence_chains": format_evidence_chains(topology, downstream_chains),
+    }
+
+
+def _classify_python_signature_edit(
+    topology: Dict[str, Any],
+    rel_file: str,
+    symbol_name: str,
+    prop_text: str,
+    downstream_chains: List[List[str]],
+) -> Dict[str, Any]:
+    reasons: List[str] = []
+    classification = "SAFE_INTERNAL_REFACTOR"
+
+    # Lookup existing function or class field in topology
+    py_mod = topology.get("py_modules", {}).get(rel_file)
+    if not py_mod:
+        for k, v in topology.get("py_modules", {}).items():
+            if k.endswith(rel_file) or os.path.basename(k) == os.path.basename(rel_file):
+                py_mod = v
+                rel_file = k
+                break
+
+    existing_fn = py_mod.get("functions", {}).get(symbol_name) if py_mod else None
+    if not existing_fn and py_mod:
+        # Check if symbol_name is Class.field or Class
+        if "." in symbol_name:
+            cls_n, fld_n = symbol_name.split(".", 1)
+            cls_meta = py_mod.get("classes", {}).get(cls_n)
+            if cls_meta and fld_n in cls_meta.get("fields", {}):
+                if any(tok in prop_text.lower() for tok in ("remove", "drop", "rename", "-")) or fld_n not in prop_text:
+                    classification = "BREAKING_DATABASE_SCHEMA" if cls_meta.get("tablename") else "BREAKING_API_CONTRACT"
+                    reasons.append(f"Model/schema field '{symbol_name}' is being renamed, removed, or re-typed.")
+                    return {
+                        "gate_status": _compute_gate_status(classification, downstream_chains),
+                        "classification": classification,
+                        "target_file": rel_file,
+                        "target_symbol": symbol_name,
+                        "proposed_edit": prop_text,
+                        "reasons": reasons,
+                        "evidence_chains": format_evidence_chains(topology, downstream_chains),
+                    }
+
+    # Parse proposed Python function signature if it starts with def / async def
+    prop_sig = _try_parse_python_def(prop_text, symbol_name)
+    if existing_fn and prop_sig:
+        old_params = existing_fn.get("params", [])
+        new_params = prop_sig.get("params", [])
+        old_by_name = {p["name"]: p for p in old_params}
+        new_by_name = {p["name"]: p for p in new_params}
+
+        # 1. Removed parameters
+        for op in old_params:
+            if op["name"] not in new_by_name:
+                classification = "BREAKING_FUNCTION_SIGNATURE"
+                reasons.append(f"Parameter '{op['name']}' was removed from '{symbol_name}()'.")
+
+        # 2. Added required parameters (without default)
+        for np in new_params:
+            if np["name"] not in old_by_name:
+                if np["required"]:
+                    classification = "BREAKING_FUNCTION_SIGNATURE"
+                    reasons.append(
+                        f"Added required parameter '{np['name']}' without a default value to '{symbol_name}()', breaking existing call sites."
+                    )
+            else:
+                op = old_by_name[np["name"]]
+                if not op["required"] and np["required"]:
+                    classification = "BREAKING_FUNCTION_SIGNATURE"
+                    reasons.append(
+                        f"Optional parameter '{np['name']}' was made required (default value removed) in '{symbol_name}()'."
+                    )
+                if op["annotation"] and np["annotation"] and op["annotation"] != np["annotation"]:
+                    classification = "BREAKING_FUNCTION_SIGNATURE"
+                    reasons.append(
+                        f"Parameter '{np['name']}' type annotation changed from '{op['annotation']}' to '{np['annotation']}'."
+                    )
+
+        # 3. Reordered positional parameters
+        common_old_order = [p["name"] for p in old_params if p["name"] in new_by_name]
+        common_new_order = [p["name"] for p in new_params if p["name"] in old_by_name]
+        if common_old_order != common_new_order:
+            classification = "BREAKING_FUNCTION_SIGNATURE"
+            reasons.append(
+                f"Positional parameter order changed from ({', '.join(common_old_order)}) to ({', '.join(common_new_order)})."
+            )
+
+        # 4. Return type change
+        old_ret = existing_fn.get("return_type", "")
+        new_ret = prop_sig.get("return_type", "")
+        if old_ret and new_ret and old_ret != new_ret:
+            classification = "BREAKING_FUNCTION_SIGNATURE"
+            reasons.append(f"Return type annotation changed from '{old_ret}' to '{new_ret}'.")
+
+    elif prop_sig and not existing_fn:
+        # Even if existing function wasn't indexed yet, check if proposed edit has required params or breaking hints
+        req_params = [p["name"] for p in prop_sig.get("params", []) if p["required"]]
+        if req_params and "-" in prop_text:
+            classification = "BREAKING_FUNCTION_SIGNATURE"
+            reasons.append(f"Modified signature on '{symbol_name}' introduces required parameters: {', '.join(req_params)}.")
+
+    gate_status = _compute_gate_status(classification, downstream_chains)
+    return {
+        "gate_status": gate_status,
+        "classification": classification,
+        "target_file": rel_file,
+        "target_symbol": symbol_name,
+        "existing_signature": existing_fn.get("signature_string") if existing_fn else None,
+        "proposed_edit": prop_text,
+        "reasons": reasons or ["Proposed function change preserves existing call-site signature compatibility."],
+        "evidence_chains": format_evidence_chains(topology, downstream_chains),
+    }
+
+
+def _classify_ts_signature_edit(
+    topology: Dict[str, Any],
+    rel_file: str,
+    symbol_name: str,
+    prop_text: str,
+    downstream_chains: List[List[str]],
+) -> Dict[str, Any]:
+    reasons: List[str] = []
+    classification = "SAFE_INTERNAL_REFACTOR"
+
+    fe_mod = topology.get("fe_modules", {}).get(rel_file)
+    if not fe_mod:
+        for k, v in topology.get("fe_modules", {}).items():
+            if k.endswith(rel_file) or os.path.basename(k) == os.path.basename(rel_file):
+                fe_mod = v
+                rel_file = k
+                break
+
+    existing_sym = fe_mod.get("symbols", {}).get(symbol_name) if fe_mod else None
+    paren_match = re.search(r"\(([^)]*)\)", prop_text)
+    if existing_sym and paren_match:
+        old_params = existing_sym.get("params", [])
+        new_params = _parse_ts_params(paren_match.group(1))
+        old_names = {p["name"]: p for p in old_params}
+        new_names = {p["name"]: p for p in new_params}
+
+        for op in old_params:
+            if op["name"] not in new_names:
+                classification = "BREAKING_FUNCTION_SIGNATURE"
+                reasons.append(f"Prop/parameter '{op['name']}' was removed from '{symbol_name}'.")
+        for np in new_params:
+            if np["name"] not in old_names and np["required"]:
+                classification = "BREAKING_FUNCTION_SIGNATURE"
+                reasons.append(f"Added required prop/parameter '{np['name']}' without default to '{symbol_name}'.")
+
+    gate_status = _compute_gate_status(classification, downstream_chains)
+    return {
+        "gate_status": gate_status,
+        "classification": classification,
+        "target_file": rel_file,
+        "target_symbol": symbol_name,
+        "proposed_edit": prop_text,
+        "reasons": reasons or ["Frontend component/function signature remains backward-compatible."],
+        "evidence_chains": format_evidence_chains(topology, downstream_chains),
+    }
+
+
+def _classify_generic_edit(
+    topology: Dict[str, Any],
+    rel_file: str,
+    symbol_name: str,
+    prop_text: str,
+    downstream_chains: List[List[str]],
+) -> Dict[str, Any]:
+    classification = "SAFE_INTERNAL_REFACTOR"
+    reasons: List[str] = []
+    if any(k in prop_text.upper() for k in ("DROP ", "REMOVE", "RENAME", "BREAKING")):
+        classification = "BREAKING_FUNCTION_SIGNATURE"
+        reasons.append(f"Breaking modification detected on '{symbol_name}'.")
+
+    gate_status = _compute_gate_status(classification, downstream_chains)
+    return {
+        "gate_status": gate_status,
+        "classification": classification,
+        "target_file": rel_file,
+        "target_symbol": symbol_name,
+        "proposed_edit": prop_text,
+        "reasons": reasons or ["Internal refactor with no contract breakage detected."],
+        "evidence_chains": format_evidence_chains(topology, downstream_chains),
+    }
+
+
+def _try_parse_python_def(prop_text: str, symbol_name: str) -> Optional[Dict[str, Any]]:
+    cleaned = prop_text.strip()
+    # If diff lines are passed, extract the '+' line with def
+    for line in cleaned.splitlines():
+        l_strip = line.lstrip("+").strip()
+        if l_strip.startswith(("def ", "async def ")):
+            cleaned = l_strip
+            break
+    if not cleaned.startswith(("def ", "async def ")):
+        if cleaned.startswith("(") and cleaned.endswith(")"):
+            cleaned = f"def {symbol_name}{cleaned}: pass"
+        else:
+            return None
+    if not cleaned.endswith("pass") and ":" not in cleaned.split(")")[-1]:
+        cleaned = cleaned + ":\n    pass"
+    elif cleaned.endswith(":"):
+        cleaned = cleaned + "\n    pass"
+    try:
+        tree = ast.parse(cleaned)
+        for node in tree.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                return _extract_function_signature(node)
+    except Exception:
+        return None
+    return None
+
+
+def _compute_gate_status(classification: str, downstream_chains: List[List[str]]) -> str:
+    if classification == "SAFE_INTERNAL_REFACTOR":
+        return "PASS"
+    if len(downstream_chains) > 0:
+        return "BLOCK"
+    return "WARN"
+
+
+def format_node_evidence_label(topology: Dict[str, Any], node_id: str) -> str:
+    nodes_by_id = topology.get("nodes_by_id", {})
+    n = nodes_by_id.get(node_id)
+    if not n:
+        return node_id
+    rel_file = n.get("file", "")
+    name = n.get("name", node_id)
+    ntype = n.get("type", "")
+    if ntype == "db_column":
+        return f"{rel_file} ({n.get('table')}.{n.get('column')})"
+    if ntype == "db_table":
+        return f"{rel_file} ({name})"
+    if ntype in ("orm_field", "class_field", "python_function", "python_method", "python_class"):
+        return f"{rel_file} ({name})"
+    if ntype == "api_route":
+        return f"{rel_file} ({n.get('method')} {n.get('path')})"
+    if ntype == "api_payload_field":
+        return f"{rel_file} ({name})"
+    if ntype in ("react_component", "ts_function", "frontend_property_access"):
+        return f"{rel_file} ({name})"
+    if ntype in ("test_suite", "test_case"):
+        return f"{rel_file} ({n.get('function', 'test_suite')})"
+    return f"{rel_file} ({name})" if rel_file else name
+
+
+def format_evidence_chains(topology: Dict[str, Any], chains: List[List[str]]) -> List[str]:
+    formatted: List[str] = []
+    for chain in chains:
+        if not chain:
+            continue
+        hops = [format_node_evidence_label(topology, nid) for nid in chain]
+        dedup_hops: List[str] = []
+        for h in hops:
+            if not dedup_hops or dedup_hops[-1] != h:
+                dedup_hops.append(h)
+        chain_str = " -> ".join(dedup_hops)
+        if chain_str not in formatted:
+            formatted.append(chain_str)
+    return formatted
+