blasttrace 1.0.2__py3-none-any.whl

blasttrace/parsers/ts_react_parser.py

@@ -0,0 +1,299 @@
+"""
+BlastTrace TypeScript & React Frontend Parser
+Parses TypeScript/JavaScript functions, React components, interfaces/types, ES imports,
+API consumer calls (fetch, axios, useSWR, useQuery), and response property accesses.
+"""
+
+import os
+import re
+from typing import Dict, Any, List
+
+
+def _normalize_url_to_route_path(raw_url: str) -> str:
+    cleaned = raw_url.strip().strip("\"'`")
+    cleaned = re.sub(r"^https?://[^/]+", "", cleaned)
+    cleaned = cleaned.split("?")[0]
+    cleaned = re.sub(r"\$\{[^}]+\}", ":param", cleaned)
+    cleaned = re.sub(r"\{[^}]+\}", ":param", cleaned)
+    if not cleaned.startswith("/"):
+        cleaned = "/" + cleaned
+    if len(cleaned) > 1 and cleaned.endswith("/"):
+        cleaned = cleaned.rstrip("/")
+    return cleaned
+
+
+def _parse_ts_params(param_str: str) -> List[Dict[str, Any]]:
+    params: List[Dict[str, Any]] = []
+    raw = param_str.strip()
+    if not raw:
+        return params
+    # Handle destructured props like `{ userId, amount = 0 }: CheckoutProps`
+    if raw.startswith("{"):
+        destruct_match = re.match(r"\{([^}]*)\}(?:\s*:\s*([A-Za-z0-9_<>[\]|&]+))?", raw)
+        if destruct_match:
+            inner = destruct_match.group(1)
+            prop_type = (destruct_match.group(2) or "").strip()
+            for part in inner.split(","):
+                p = part.strip()
+                if not p:
+                    continue
+                has_def = "=" in p
+                p_name = p.split("=")[0].split(":")[0].strip()
+                def_val = p.split("=", 1)[1].strip() if has_def else None
+                params.append({
+                    "name": p_name,
+                    "annotation": prop_type,
+                    "required": not has_def,
+                    "default": def_val,
+                })
+            return params
+
+    for part in raw.split(","):
+        p = part.strip()
+        if not p:
+            continue
+        has_def = "=" in p
+        left = p.split("=", 1)[0].strip()
+        def_val = p.split("=", 1)[1].strip() if has_def else None
+        optional_q = "?" in left.split(":")[0]
+        if ":" in left:
+            p_name, p_ann = left.split(":", 1)
+            p_name = p_name.strip().rstrip("?")
+            p_ann = p_ann.strip()
+        else:
+            p_name = left.rstrip("?")
+            p_ann = ""
+        params.append({
+            "name": p_name,
+            "annotation": p_ann,
+            "required": not (has_def or optional_q),
+            "default": def_val,
+        })
+    return params
+
+
+def parse_ts_react_content(content: str, rel_file: str) -> Dict[str, Any]:
+    symbols: Dict[str, Dict[str, Any]] = {}
+    interfaces: Dict[str, Dict[str, Any]] = {}
+    imports: List[Dict[str, str]] = []
+    api_calls: List[Dict[str, Any]] = []
+    property_accesses: List[str] = []
+    nodes: List[Dict[str, Any]] = []
+    edges: List[Dict[str, str]] = []
+
+    module_id = f"fe:{rel_file}"
+    nodes.append({
+        "id": module_id,
+        "type": "frontend_module",
+        "name": rel_file,
+        "file": rel_file,
+        "layer": "frontend",
+    })
+
+    # 1. ES Imports
+    import_pattern = re.compile(
+        r"import\s+(?:type\s+)?(?:\{([^}]+)\}|([A-Za-z0-9_$]+))\s+from\s+[`\"']([^`\"']+)[`\"']",
+        re.MULTILINE,
+    )
+    for match in import_pattern.finditer(content):
+        named_group = match.group(1)
+        default_imp = match.group(2)
+        src_mod = match.group(3)
+        if named_group:
+            for item in named_group.split(","):
+                sym = item.strip().split(" as ")[0].strip()
+                if sym:
+                    imports.append({"module": src_mod, "symbol": sym})
+        elif default_imp:
+            imports.append({"module": src_mod, "symbol": default_imp.strip()})
+
+    # 2. Interfaces & Type Aliases
+    iface_pattern = re.compile(r"(?:export\s+)?interface\s+([A-Za-z0-9_]+)\s*\{([^}]*)\}", re.DOTALL)
+    for match in iface_pattern.finditer(content):
+        iname = match.group(1).strip()
+        ibody = match.group(2)
+        fields: Dict[str, Dict[str, Any]] = {}
+        for line in ibody.splitlines():
+            line_clean = line.strip().rstrip(";,")
+            if not line_clean or line_clean.startswith("//"):
+                continue
+            if ":" in line_clean:
+                fname, ftype = line_clean.split(":", 1)
+                fname_clean = fname.strip().rstrip("?")
+                fields[fname_clean] = {
+                    "name": fname_clean,
+                    "type": ftype.strip(),
+                    "required": not fname.strip().endswith("?"),
+                }
+        iface_id = f"fe:{rel_file}:{iname}"
+        interfaces[iname] = {"name": iname, "fields": fields, "file": rel_file}
+        nodes.append({
+            "id": iface_id,
+            "type": "ts_interface",
+            "name": iname,
+            "fields": list(fields.keys()),
+            "file": rel_file,
+            "layer": "frontend",
+        })
+        edges.append({"source": module_id, "target": iface_id, "relation": "defines_interface"})
+
+    # 3. Functions, Arrow Functions, and React Components
+    fn_pattern = re.compile(
+        r"(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+([A-Za-z0-9_]+)\s*\(([^)]*)\)(?:\s*:\s*([A-Za-z0-9_<>[\]|&]+))?",
+    )
+    for match in fn_pattern.finditer(content):
+        fname = match.group(1).strip()
+        raw_params = match.group(2)
+        ret_type = (match.group(3) or "").strip()
+        params = _parse_ts_params(raw_params)
+        is_component = fname[0].isupper()
+        sym_id = f"fe:{rel_file}:{fname}"
+        symbols[fname] = {
+            "name": fname,
+            "kind": "react_component" if is_component else "ts_function",
+            "params": params,
+            "return_type": ret_type,
+            "signature_string": f"function {fname}({raw_params})" + (f": {ret_type}" if ret_type else ""),
+            "file": rel_file,
+        }
+        nodes.append({
+            "id": sym_id,
+            "type": "react_component" if is_component else "ts_function",
+            "name": fname,
+            "params": params,
+            "return_type": ret_type,
+            "file": rel_file,
+            "layer": "frontend",
+        })
+        edges.append({"source": module_id, "target": sym_id, "relation": "defines_symbol"})
+
+    arrow_pattern = re.compile(
+        r"(?:export\s+)?const\s+([A-Za-z0-9_]+)\s*(?::\s*[^=]+)?=\s*(?:async\s*)?\(([^)]*)\)\s*(?::\s*([A-Za-z0-9_<>[\]|&]+))?\s*=>",
+    )
+    for match in arrow_pattern.finditer(content):
+        fname = match.group(1).strip()
+        if fname in symbols:
+            continue
+        raw_params = match.group(2)
+        ret_type = (match.group(3) or "").strip()
+        params = _parse_ts_params(raw_params)
+        is_component = fname[0].isupper()
+        sym_id = f"fe:{rel_file}:{fname}"
+        symbols[fname] = {
+            "name": fname,
+            "kind": "react_component" if is_component else "ts_function",
+            "params": params,
+            "return_type": ret_type,
+            "signature_string": f"const {fname} = ({raw_params}) =>",
+            "file": rel_file,
+        }
+        nodes.append({
+            "id": sym_id,
+            "type": "react_component" if is_component else "ts_function",
+            "name": fname,
+            "params": params,
+            "return_type": ret_type,
+            "file": rel_file,
+            "layer": "frontend",
+        })
+        edges.append({"source": module_id, "target": sym_id, "relation": "defines_symbol"})
+
+    # 4. Property accesses on response/state objects (e.g. data.balance, user.balance, profile.email)
+    prop_pattern = re.compile(r"\b(?:data|user|res|response|payload|item|account|profile)\.([a-zA-Z_][a-zA-Z0-9_]*)\b")
+    for p_match in prop_pattern.finditer(content):
+        prop_name = p_match.group(1)
+        if prop_name not in ("json", "status", "ok", "headers", "then", "catch", "map", "filter", "length"):
+            if prop_name not in property_accesses:
+                property_accesses.append(prop_name)
+
+    # 5. API calls: fetch('/api/...'), axios.get('/api/...'), useSWR('/api/...')
+    fetch_pattern = re.compile(
+        r"\bfetch\s*\(\s*[`\"']([^`\"']+)[`\"'](?:\s*,\s*\{([^}]*)\})?",
+        re.DOTALL,
+    )
+    for match in fetch_pattern.finditer(content):
+        raw_url = match.group(1)
+        opts = match.group(2) or ""
+        m_match = re.search(r"method\s*:\s*[`\"']([A-Za-z]+)[`\"']", opts, re.IGNORECASE)
+        method = m_match.group(1).upper() if m_match else "GET"
+        norm_path = _normalize_url_to_route_path(raw_url)
+        api_calls.append({
+            "client": "fetch",
+            "method": method,
+            "raw_url": raw_url,
+            "normalized_path": norm_path,
+            "accessed_fields": property_accesses,
+            "file": rel_file,
+        })
+
+    axios_pattern = re.compile(
+        r"\baxios\.(get|post|put|delete|patch)\s*(?:<[^>]+>)?\s*\(\s*[`\"']([^`\"']+)[`\"']",
+        re.IGNORECASE,
+    )
+    for match in axios_pattern.finditer(content):
+        method = match.group(1).upper()
+        raw_url = match.group(2)
+        norm_path = _normalize_url_to_route_path(raw_url)
+        api_calls.append({
+            "client": "axios",
+            "method": method,
+            "raw_url": raw_url,
+            "normalized_path": norm_path,
+            "accessed_fields": property_accesses,
+            "file": rel_file,
+        })
+
+    swr_pattern = re.compile(r"\b(?:useSWR|useQuery)\s*(?:<[^>]+>)?\s*\(\s*[`\"'](/[^`\"']+)[`\"']")
+    for match in swr_pattern.finditer(content):
+        raw_url = match.group(1)
+        norm_path = _normalize_url_to_route_path(raw_url)
+        api_calls.append({
+            "client": "hook",
+            "method": "GET",
+            "raw_url": raw_url,
+            "normalized_path": norm_path,
+            "accessed_fields": property_accesses,
+            "file": rel_file,
+        })
+
+    return {
+        "file": rel_file,
+        "symbols": symbols,
+        "interfaces": interfaces,
+        "imports": imports,
+        "api_calls": api_calls,
+        "property_accesses": property_accesses,
+        "nodes": nodes,
+        "edges": edges,
+    }
+
+
+def parse_ts_react_file(file_path: str, repo_root: str = "") -> Dict[str, Any]:
+    if not os.path.exists(file_path):
+        return {
+            "error": f"Frontend file not found: {file_path}",
+            "symbols": {},
+            "interfaces": {},
+            "imports": [],
+            "api_calls": [],
+            "property_accesses": [],
+            "nodes": [],
+            "edges": [],
+        }
+    rel_file = os.path.relpath(file_path, repo_root).replace("\\", "/") if repo_root else os.path.basename(file_path)
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+            content = f.read()
+    except Exception as exc:
+        return {
+            "error": str(exc),
+            "symbols": {},
+            "interfaces": {},
+            "imports": [],
+            "api_calls": [],
+            "property_accesses": [],
+            "nodes": [],
+            "edges": [],
+        }
+    return parse_ts_react_content(content, rel_file)
+

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,
+    }
+