blasttrace 1.0.2__py3-none-any.whl

blasttrace/visualizer.py

@@ -0,0 +1,165 @@
+"""
+BlastTrace Mermaid Blast-Radius Visualizer
+Generates render-ready Mermaid.js flowcharts for Full-Stack Contract Blast Radius,
+Cross-Stack Dependency Chains, and Circular Code Dependency Loops.
+"""
+
+from typing import List, Dict, Any, Optional
+
+
+def sanitize_id(node_id: str, prefix: str = "N") -> str:
+    cleaned = "".join(c if c.isalnum() or c == "_" else "_" for c in node_id)
+    return f"{prefix}_{cleaned}"
+
+
+def sanitize_label(text: str) -> str:
+    return text.replace('"', "'").replace("\n", " ").replace("[", "(").replace("]", ")")
+
+
+def _layer_style_for_node(node_id: str) -> str:
+    if node_id.startswith("db:"):
+        return "dbNode"
+    if node_id.startswith(("orm:", "py:")):
+        return "backendNode"
+    if node_id.startswith("api"):
+        return "apiNode"
+    if node_id.startswith("fe:"):
+        return "frontendNode"
+    if node_id.startswith("test:"):
+        return "testNode"
+    return "backendNode"
+
+
+def _layer_icon_for_node(node_id: str) -> str:
+    if node_id.startswith("db:"):
+        return "🗄️ DB:"
+    if node_id.startswith("orm:"):
+        return "🧩 ORM:"
+    if node_id.startswith("py:"):
+        return "⚙️ Backend:"
+    if node_id.startswith("api"):
+        return "🔌 API:"
+    if node_id.startswith("fe:"):
+        return "🖥️ UI:"
+    if node_id.startswith("test:"):
+        return "🧪 Test:"
+    return "📦 Symbol:"
+
+
+def generate_mermaid_blast_radius(
+    chains: List[List[str]],
+    title: str = "Full-Stack Blast Radius",
+    gate_status: str = "BLOCK",
+    topology: Optional[Dict[str, Any]] = None,
+) -> str:
+    """
+    Generates a left-to-right Mermaid diagram visualizing all downstream consumers
+    across Database, Backend, API, Frontend, and Tests.
+    """
+    if not chains or len(chains) == 0:
+        return (
+            "```mermaid\n"
+            "flowchart LR\n"
+            "    classDef safe fill:#059669,stroke:#047857,stroke-width:2px,color:#ffffff,font-weight:bold;\n"
+            "    SAFE[\"✅ Zero Downstream Breaking Impact Detected (PASS)\"]:::safe\n"
+            "```"
+        )
+
+    nodes_by_id = (topology or {}).get("nodes_by_id", {})
+    lines = [
+        "```mermaid",
+        "flowchart LR",
+        "    classDef origin fill:#dc2626,stroke:#7f1d1d,stroke-width:3px,color:#ffffff,font-weight:bold;",
+        "    classDef dbNode fill:#d97706,stroke:#92400e,stroke-width:2px,color:#ffffff;",
+        "    classDef backendNode fill:#2563eb,stroke:#1e40af,stroke-width:2px,color:#ffffff;",
+        "    classDef apiNode fill:#7c3aed,stroke:#5b21b6,stroke-width:2px,color:#ffffff;",
+        "    classDef frontendNode fill:#db2777,stroke:#9d174d,stroke-width:2px,color:#ffffff;",
+        "    classDef testNode fill:#0d9488,stroke:#115e59,stroke-width:2px,color:#ffffff;",
+        f'    subgraph BlastRadius ["{sanitize_label(title)} [{gate_status}]"]',
+        "        direction LR",
+    ]
+
+    declared_nodes: Dict[str, str] = {}
+    declared_edges = set()
+    counter = 0
+
+    for chain in chains:
+        for idx, nid in enumerate(chain):
+            if nid not in declared_nodes:
+                counter += 1
+                var_name = f"B{counter}"
+                declared_nodes[nid] = var_name
+                nmeta = nodes_by_id.get(nid, {})
+                display_name = nmeta.get("name") or nid.split(":", 1)[-1]
+                rel_file = nmeta.get("file", "")
+                icon = "💥 Edited:" if idx == 0 else _layer_icon_for_node(nid)
+                style_cls = "origin" if idx == 0 else _layer_style_for_node(nid)
+                label_str = f"{icon} {display_name}"
+                if rel_file and rel_file not in display_name:
+                    label_str += f" ({rel_file})"
+                lines.append(f'        {var_name}["{sanitize_label(label_str)}"]:::{style_cls}')
+
+        for idx in range(len(chain) - 1):
+            u, v = chain[idx], chain[idx + 1]
+            if u == v:
+                continue
+            edge_key = (declared_nodes[u], declared_nodes[v])
+            if edge_key not in declared_edges:
+                declared_edges.add(edge_key)
+                lines.append(f"        {edge_key[0]} -->|impacts| {edge_key[1]}")
+
+    lines.append("    end")
+    lines.append("```")
+    return "\n".join(lines)
+
+
+def generate_mermaid_contract_chain(
+    path: List[str],
+    title: str = "Cross-Stack Contract Chain",
+    topology: Optional[Dict[str, Any]] = None,
+) -> str:
+    if not path:
+        return generate_mermaid_blast_radius([], title=title, gate_status="PASS", topology=topology)
+    return generate_mermaid_blast_radius([path], title=title, gate_status="TRACED", topology=topology)
+
+
+def generate_mermaid_cycles(cycles: List[List[str]]) -> str:
+    """
+    Generates Mermaid flowchart syntax for circular code dependency loops.
+    """
+    if not cycles or len(cycles) == 0:
+        return (
+            "```mermaid\n"
+            "flowchart TD\n"
+            "    classDef clean fill:#059669,stroke:#047857,stroke-width:2px,color:#ffffff;\n"
+            "    CLEAN[\"✅ Zero Circular Code Dependencies Detected\"]:::clean\n"
+            "```"
+        )
+
+    lines = [
+        "```mermaid",
+        "flowchart TD",
+        "    classDef cycleNode fill:#dc2626,stroke:#7f1d1d,stroke-width:2px,color:#ffffff,font-weight:bold;",
+    ]
+
+    for c_idx, cycle in enumerate(cycles):
+        lines.append(f'    subgraph Cycle{c_idx} ["🔁 Circular Dependency Loop #{c_idx + 1}"]')
+        lines.append("        direction TB")
+        c_vars: List[str] = []
+        for n_idx, node in enumerate(cycle):
+            var_name = f"C{c_idx}_{n_idx}"
+            c_vars.append(var_name)
+            lines.append(f'        {var_name}["{sanitize_label(node)}"]:::cycleNode')
+
+        if len(c_vars) == 2:
+            lines.append(f"        {c_vars[0]} <-->|circular_import| {c_vars[1]}")
+        else:
+            for idx in range(len(c_vars)):
+                src = c_vars[idx]
+                dst = c_vars[(idx + 1) % len(c_vars)]
+                lines.append(f"        {src} -->|imports| {dst}")
+        lines.append("    end")
+
+    lines.append("```")
+    return "\n".join(lines)
+

blasttrace-1.0.2.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: blasttrace
+Version: 1.0.2
+Summary: Pre-Edit Full-Stack Breaking-Change & Contract Blast-Radius Engine
+Home-page: https://blasttrace.dev
+Author: Moin Hasan
+Author-email: Moin Hasan <moin_hasan@live.com>
+License: Proprietary
+Project-URL: Homepage, https://blasttrace.dev
+Project-URL: Documentation, https://blasttrace.dev
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Quality Assurance
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: requests>=2.28.0
+Dynamic: author
+Dynamic: home-page
+
+# BlastTrace
+
+> **Pre-Edit Full-Stack Breaking-Change & Contract Blast-Radius Engine**  
+> `Database` $\leftrightarrow$ `Backend ORM` $\leftrightarrow$ `API Route` $\leftrightarrow$ `Frontend UI` $\leftrightarrow$ `Tests`
+
+[![PyPI Version](https://img.shields.io/badge/pypi-v1.0.0-orange.svg)](https://pypi.org/project/blasttrace/)
+[![Engine](https://img.shields.io/badge/engine-BlastTrace%20Native%20Core-blue.svg)](https://blasttrace.dev)
+[![License](https://img.shields.io/badge/license-Commercial%20%2F%20Community-green.svg)](https://blasttrace.dev)
+
+---
+
+## ⚡ What is BlastTrace?
+
+BlastTrace is a high-performance **Model Context Protocol (MCP)** server and standalone CLI that prevents AI coding agents (and human developers) from silently breaking full-stack web applications.
+
+Existing AST tools only trace single-language file imports (`File A -> File B`). They go **100% blind** when a schema edit crosses boundaries:
+```text
+[Database Column: users.billing_balance]
+        ↓
+[Backend ORM Model: User.billing_balance]
+        ↓
+[API Endpoint: GET /api/v1/user/summary]
+        ↓
+[Frontend UI Component: CheckoutModal.tsx (data.billing_balance)]
+        ↓
+[Unit & E2E Tests: test_checkout.py, checkout.spec.ts]
+```
+
+BlastTrace deterministically bridges this gap using the **BlastTrace Native Core**, catching breaking changes **before** the file is saved, before `git commit`, and before pull requests merge.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation
+```bash
+pip install blasttrace
+```
+*Or run zero-install via uvx:*
+```bash
+uvx blasttrace
+```
+
+### 2. Standalone CLI Usage (Zero AI Required)
+```bash
+# Check if a proposed edit or signature change breaks downstream consumers
+blasttrace check src/api/routes.py --symbol get_user_profile
+
+# Inspect current git diff for breaking full-stack changes
+blasttrace diff
+
+# Install git pre-commit safety gate across your repo
+blasttrace pre-commit --install
+```
+
+### 3. Connect to AI Agents & IDEs (Cursor, Claude Code, Windsurf, VS Code)
+Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "blasttrace": {
+      "command": "blasttrace"
+    }
+  }
+}
+```
+
+---
+
+## 🛡️ Supported Technology Stacks
+
+- **Database & Schemas:** PostgreSQL, MySQL, SQLite migrations (`.sql`), Prisma (`schema.prisma`), Drizzle ORM, SQLAlchemy & Django ORM (`models.py`).
+- **Backend & APIs:** Python (FastAPI, Flask, Django REST, async functions, classes), Node.js / TypeScript (Express, Next.js App Router `app/api/.../route.ts`, NestJS, OpenAPI / Swagger specs).
+- **Frontend Consumers:** React, Next.js, Vue, TypeScript (`.tsx`, `.ts`) calling `fetch()`, `axios`, `useSWR()`, `useQuery()`, and property destructuring.
+- **Test Discovery:** Pytest, Unittest, Jest, Vitest, Playwright, Cypress.
+
+---
+
+## 🔑 Licensing & Tiers
+
+| Tier | Price | Features |
+| :--- | :--- | :--- |
+| **Community** | **$0** (Free) | Index topology, basic single-file symbol reachability, community support |
+| **Pro** | **$19/mo** (or $180/yr) | Pre-Edit Breaking-Change Gate (PASS/WARN/BLOCK), full-stack contract chains, circular dependency interceptor, 2 seats |
+| **Team / CI Gate** | **$99/mo** (or $990/yr) | Everything in Pro, 5 seats, git pre-commit hook enforcement, GitHub Actions / GitLab CI PR Gate integration |
+
+Activate your Pro license:
+```bash
+blasttrace activate YOUR-LICENSE-KEY
+```
+
+---
+
+## 🔒 Security & Privacy
+
+BlastTrace runs **100% locally and air-gapped** on your machine.
+- Zero telemetry.
+- Zero remote code scanning.
+- Zero cloud database uploads.
+- Your code never leaves your workstation.
+
+---
+
+© 2026 BlastTrace Inc. All rights reserved. Official website: [blasttrace.dev](https://blasttrace.dev)

blasttrace-1.0.2.dist-info/RECORD

@@ -0,0 +1,18 @@
+blasttrace/__init__.py,sha256=btjn2g5b-X3amyPdt7iYmLh8e9XJPZWPPy8idM7NDOY,160
+blasttrace/classifier.py,sha256=Aj_wc3bFe1j5mPfl9tUe9W5cBgY5I2y42NMaOiuENrc,18932
+blasttrace/license.py,sha256=p1q3mRUFvGWgJ3rX4P2DJhNDwyXAyaFFsc2IDEc6dT4,10663
+blasttrace/remediation.py,sha256=wBswHi6EsWBsawU2jhvcKl-N-x9vAUtQgO37PEWuIOI,9436
+blasttrace/server.py,sha256=CHgf7wj-uEC9o1wLWx8vIrIg3QLURHZMLb_PGMy7yaI,32398
+blasttrace/visualizer.py,sha256=uMl5-NWfVPm4gOIAPLCN2oEM7tRVgyAY-dgXYhcj2Uw,6301
+blasttrace/parsers/__init__.py,sha256=YZz8WFIdpQ31f4w_ldnp6YONucgrcwDO-gOtc1SpzEw,74
+blasttrace/parsers/api_route_parser.py,sha256=LUtsG5LcCeRiRuC2OYEFI4FZBaFWuFkyS-65i0IehsU,12964
+blasttrace/parsers/contract_linker.py,sha256=F5VfQ1z5t95UI2L3PoEfDd8DjjDhlMwJf_WkjeMca_8,22458
+blasttrace/parsers/python_ast_parser.py,sha256=4vc87EuBgDDnjF_zxsfi45S8ypM4N9WRM8tTrgSU9Io,13201
+blasttrace/parsers/sql_schema_parser.py,sha256=3KdBynO1acEyGxgVgvRt78hDKTetRmMlZzR2tGfkuCI,14770
+blasttrace/parsers/test_mapper.py,sha256=DJoI1P0dpcYQIqyxhc6oQy5pSzUAVfTfdke0aT4AruI,6956
+blasttrace/parsers/ts_react_parser.py,sha256=rtJFPp8G2MQvuOaa57j9oTY6neA2x-C6MToF6h0a5-c,11440
+blasttrace-1.0.2.dist-info/METADATA,sha256=qC8FY3hCHNfzcvv7lhkZFHB-FtcxuJDxh5xKcPShxi4,4449
+blasttrace-1.0.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+blasttrace-1.0.2.dist-info/entry_points.txt,sha256=YqImtXzrUYt4ugt24ZrSX8OhCzEsLAJbtl1izOx9dq0,94
+blasttrace-1.0.2.dist-info/top_level.txt,sha256=HvYxGntDu3K7Rrw8WER3ilnqDicEiO7ptEhx_sNq9vo,11
+blasttrace-1.0.2.dist-info/RECORD,,

blasttrace-1.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

blasttrace-1.0.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+blasttrace = blasttrace.server:main
+blasttrace-mcp = blasttrace.server:main

blasttrace-1.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+blasttrace