blasttrace 1.2.0__py2.py3-none-any.whl

blasttrace/parsers/contract_linker.py

@@ -0,0 +1,815 @@
+"""
+BlastTrace Cross-Stack Contract Linker
+Deterministically connects Database Tables/Columns <-> ORM Models <-> Backend Functions <->
+API Routes/Payloads <-> Frontend React/TS Consumers <-> Covering Test Suites.
+"""
+
+import os
+import re
+from typing import Dict, Any, List, Optional, Tuple
+
+from blasttrace.parsers.sql_schema_parser import (
+    parse_sql_content,
+    parse_prisma_content,
+    parse_orm_python_content,
+    _pluralize,
+    _singularize,
+)
+from blasttrace.parsers.python_ast_parser import parse_python_content
+from blasttrace.parsers.api_route_parser import (
+    parse_python_api_routes,
+    parse_ts_js_api_routes,
+    parse_openapi_spec,
+    _normalize_route_path,
+)
+from blasttrace.parsers.ts_react_parser import parse_ts_react_content
+from blasttrace.parsers.dart_flutter_parser import parse_dart_content
+from blasttrace.parsers.swift_ios_parser import parse_swift_content
+from blasttrace.parsers.kotlin_android_parser import parse_kotlin_content
+from blasttrace.parsers.vue_nuxt_parser import parse_vue_content
+from blasttrace.parsers.go_parser import parse_go_content
+from blasttrace.parsers.test_mapper import (
+    is_test_file,
+    parse_python_test_content,
+    parse_ts_test_content,
+)
+
+
+_IGNORED_DIRS = {
+    ".git", "__pycache__", "node_modules", ".venv", "venv", "env",
+    "build", "dist", ".pytest_cache", ".mypy_cache", ".next", ".turbo",
+    ".dart_tool", ".flutter-plugins", "Pods", ".gradle", ".build", ".swiftpm", "DerivedData", "website", "website_v3", "egg-info",
+}
+
+
+def build_fullstack_topology(repo_path: str) -> Dict[str, Any]:
+    """
+    Scans a repository and builds the complete cross-stack contract topology
+    spanning Database, Backend, API, Frontend, and Tests.
+    """
+    if not os.path.exists(repo_path):
+        return {"error": f"Repository path not found: {repo_path}"}
+
+    root = os.path.abspath(repo_path)
+    if os.path.isfile(root):
+        root = os.path.dirname(root)
+
+    nodes_by_id: Dict[str, Dict[str, Any]] = {}
+    edges: List[Dict[str, str]] = []
+    edge_set = set()
+
+    # Collected layer registries
+    db_tables: Dict[str, Dict[str, Any]] = {}
+    orm_models: Dict[str, Dict[str, Any]] = {}
+    py_modules: Dict[str, Dict[str, Any]] = {}
+    api_routes: List[Dict[str, Any]] = []
+    fe_modules: Dict[str, Dict[str, Any]] = {}
+    flutter_modules: Dict[str, Dict[str, Any]] = {}
+    swift_modules: Dict[str, Dict[str, Any]] = {}
+    kotlin_modules: Dict[str, Dict[str, Any]] = {}
+    vue_modules: Dict[str, Any] = {}
+    go_modules: Dict[str, Any] = {}
+    test_suites: Dict[str, Dict[str, Any]] = {}
+    module_import_edges: List[Dict[str, str]] = []
+
+    def _add_node(n: Dict[str, Any]) -> None:
+        nid = n["id"]
+        if nid not in nodes_by_id:
+            nodes_by_id[nid] = n
+        else:
+            nodes_by_id[nid].update(n)
+
+    def _add_edge(src: str, dst: str, relation: str = "impacts") -> None:
+        if not src or not dst or src == dst:
+            return
+        key = (src, dst)
+        if key not in edge_set:
+            edge_set.add(key)
+            edges.append({"source": src, "target": dst, "relation": relation})
+
+    # Walk repository files
+    all_files: List[Tuple[str, str]] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [
+            d for d in dirnames
+            if d not in _IGNORED_DIRS and not d.endswith(".egg-info")
+        ]
+        for fn in sorted(filenames):
+            abs_p = os.path.join(dirpath, fn)
+            rel_p = os.path.relpath(abs_p, root).replace("\\", "/")
+            all_files.append((abs_p, rel_p))
+
+    for abs_p, rel_p in all_files:
+        lower = rel_p.lower()
+        try:
+            with open(abs_p, "r", encoding="utf-8", errors="ignore") as f:
+                content = f.read()
+        except Exception:
+            continue
+
+        # 1. SQL / Prisma schemas
+        if lower.endswith(".sql"):
+            sql_res = parse_sql_content(content, rel_p)
+            for tname, tinfo in sql_res["tables"].items():
+                if tname in db_tables:
+                    db_tables[tname]["columns"].update(tinfo.get("columns", {}))
+                else:
+                    db_tables[tname] = tinfo
+            for n in sql_res["nodes"]:
+                _add_node(n)
+            for e in sql_res["edges"]:
+                _add_edge(e["source"], e["target"], e.get("relation", "schema"))
+
+        elif lower.endswith(".prisma"):
+            pr_res = parse_prisma_content(content, rel_p)
+            for tname, tinfo in pr_res["tables"].items():
+                if tname in db_tables:
+                    db_tables[tname]["columns"].update(tinfo.get("columns", {}))
+                else:
+                    db_tables[tname] = tinfo
+            for n in pr_res["nodes"]:
+                _add_node(n)
+            for e in pr_res["edges"]:
+                _add_edge(e["source"], e["target"], e.get("relation", "schema"))
+
+        # 2. Test files (Python or TS/JS)
+        elif is_test_file(rel_p):
+            if lower.endswith(".py"):
+                t_res = parse_python_test_content(content, rel_p)
+            else:
+                t_res = parse_ts_test_content(content, rel_p)
+            test_suites[rel_p] = t_res
+            for n in t_res["nodes"]:
+                _add_node(n)
+            for e in t_res["edges"]:
+                _add_edge(e["source"], e["target"], e.get("relation", "test"))
+
+        # 3. Python Backend / ORM / API files
+        elif lower.endswith(".py"):
+            py_res = parse_python_content(content, rel_p)
+            py_modules[rel_p] = py_res
+            for n in py_res["nodes"]:
+                _add_node(n)
+            for e in py_res["edges"]:
+                _add_edge(e["source"], e["target"], e.get("relation", "python"))
+
+            orm_res = parse_orm_python_content(content, rel_p)
+            for cls_name, minfo in orm_res["orm_models"].items():
+                orm_models[cls_name] = minfo
+                tbl = minfo["table"]
+                db_tables.setdefault(tbl, {"name": tbl, "file": rel_p, "columns": {}})
+                for fname, finfo in minfo["fields"].items():
+                    db_tables[tbl]["columns"].setdefault(fname.lower(), {
+                        "name": fname.lower(),
+                        "table": tbl,
+                        "type": finfo.get("args", "ORM"),
+                        "nullable": "nullable=False" not in finfo.get("args", ""),
+                        "has_default": "default=" in finfo.get("args", ""),
+                        "file": rel_p,
+                    })
+            for n in orm_res["nodes"]:
+                _add_node(n)
+            for e in orm_res["edges"]:
+                _add_edge(e["source"], e["target"], e.get("relation", "orm"))
+
+            api_res = parse_python_api_routes(content, rel_p)
+            api_routes.extend(api_res["routes"])
+            for n in api_res["nodes"]:
+                _add_node(n)
+            for e in api_res["edges"]:
+                _add_edge(e["source"], e["target"], e.get("relation", "api"))
+
+        # 4. TypeScript / React / JS files
+        elif lower.endswith((".ts", ".tsx", ".js", ".jsx")):
+            fe_res = parse_ts_react_content(content, rel_p)
+            fe_modules[rel_p] = fe_res
+            for n in fe_res["nodes"]:
+                _add_node(n)
+            for e in fe_res["edges"]:
+                _add_edge(e["source"], e["target"], e.get("relation", "frontend"))
+
+            ts_api = parse_ts_js_api_routes(content, rel_p)
+            api_routes.extend(ts_api["routes"])
+            for n in ts_api["nodes"]:
+                _add_node(n)
+            for e in ts_api["edges"]:
+                _add_edge(e["source"], e["target"], e.get("relation", "api"))
+
+        # 4B. Dart / Flutter Mobile & POS files
+        elif lower.endswith(".dart"):
+            dart_res = parse_dart_content(content, rel_p)
+            flutter_modules[rel_p] = dart_res
+            dart_mod_id = f"dart:{rel_p}"
+            _add_node({
+                "id": dart_mod_id,
+                "type": "flutter_module",
+                "name": os.path.basename(rel_p),
+                "file": rel_p,
+                "layer": "flutter_client",
+            })
+            for cls_info in dart_res.get("classes", []):
+                cid = f"dart:{rel_p}:{cls_info['name']}"
+                _add_node({
+                    "id": cid,
+                    "type": "flutter_model",
+                    "name": cls_info["name"],
+                    "file": rel_p,
+                    "layer": "flutter_client",
+                })
+                _add_edge(dart_mod_id, cid, "contains_model")
+
+        # 4C. Swift / iOS Client files
+        elif lower.endswith(".swift"):
+            sw_res = parse_swift_content(content, rel_p)
+            swift_modules[rel_p] = sw_res
+            sw_mod_id = f"swift:{rel_p}"
+            _add_node({
+                "id": sw_mod_id,
+                "type": "swift_module",
+                "name": os.path.basename(rel_p),
+                "file": rel_p,
+                "layer": "ios_client",
+            })
+            for cls_info in sw_res.get("classes", []):
+                cid = f"swift:{rel_p}:{cls_info['name']}"
+                _add_node({
+                    "id": cid,
+                    "type": "swift_model",
+                    "name": cls_info["name"],
+                    "file": rel_p,
+                    "layer": "ios_client",
+                })
+                _add_edge(sw_mod_id, cid, "contains_model")
+
+        # 4D. Kotlin / Android Client files
+        elif lower.endswith((".kt", ".kts")):
+            kt_res = parse_kotlin_content(content, rel_p)
+            kotlin_modules[rel_p] = kt_res
+            kt_mod_id = f"kotlin:{rel_p}"
+            _add_node({
+                "id": kt_mod_id,
+                "type": "kotlin_module",
+                "name": os.path.basename(rel_p),
+                "file": rel_p,
+                "layer": "android_client",
+            })
+            for cls_info in kt_res.get("classes", []):
+                cid = f"kotlin:{rel_p}:{cls_info['name']}"
+                _add_node({
+                    "id": cid,
+                    "type": "kotlin_model",
+                    "name": cls_info["name"],
+                    "file": rel_p,
+                    "layer": "android_client",
+                })
+                _add_edge(kt_mod_id, cid, "contains_model")
+
+        # 4E. Vue.js / Nuxt 3 Frontend files
+        elif lower.endswith(".vue"):
+            vue_res = parse_vue_content(content, rel_p)
+            vue_modules[rel_p] = vue_res
+            vue_mod_id = f"vue:{rel_p}"
+            _add_node({
+                "id": vue_mod_id,
+                "type": "vue_module",
+                "name": os.path.basename(rel_p),
+                "file": rel_p,
+                "layer": "web_frontend",
+            })
+            for comp in vue_res.components:
+                cid = f"vue:{rel_p}:{comp.name}"
+                _add_node({
+                    "id": cid,
+                    "type": "vue_component",
+                    "name": comp.name,
+                    "file": rel_p,
+                    "layer": "web_frontend",
+                })
+                _add_edge(vue_mod_id, cid, "contains_component")
+
+        # 4F. Go (Golang) Microservice & Backend files
+        elif lower.endswith(".go") and not lower.endswith("_test.go"):
+            go_res = parse_go_content(content, rel_p)
+            go_modules[rel_p] = go_res
+            go_mod_id = f"go:{rel_p}"
+            _add_node({
+                "id": go_mod_id,
+                "type": "go_module",
+                "name": os.path.basename(rel_p),
+                "file": rel_p,
+                "layer": "backend",
+            })
+            for st in go_res.structs:
+                sid = f"go:{rel_p}:{st.name}"
+                _add_node({
+                    "id": sid,
+                    "type": "go_struct",
+                    "name": st.name,
+                    "file": rel_p,
+                    "layer": "backend",
+                })
+                _add_edge(go_mod_id, sid, "contains_struct")
+                for f in st.fields:
+                    fid = f"go:{rel_p}:{st.name}.{f.name}"
+                    _add_node({
+                        "id": fid,
+                        "type": "go_field",
+                        "name": f.name,
+                        "file": rel_p,
+                        "layer": "backend",
+                    })
+                    _add_edge(sid, fid, "has_field")
+            for r in go_res.routes:
+                r_id = f"api:{r.method} {r.path}"
+                _add_node({
+                    "id": r_id,
+                    "type": "api_route",
+                    "name": f"{r.method} {r.path}",
+                    "file": rel_p,
+                    "layer": "api",
+                })
+                _add_edge(go_mod_id, r_id, "exposes_route")
+                api_routes.append({
+                    "id": r_id,
+                    "method": r.method,
+                    "path": r.path,
+                    "normalized_path": _normalize_route_path(r.path),
+                    "file": rel_p,
+                    "function_name": r.handler_name,
+                    "handler": r.handler_name,
+                })
+
+        # 5. OpenAPI specs
+        elif os.path.basename(lower) in ("openapi.json", "openapi.yaml", "openapi.yml", "swagger.json", "swagger.yaml"):
+            oa_res = parse_openapi_spec(content, rel_p)
+            api_routes.extend(oa_res["routes"])
+            for n in oa_res["nodes"]:
+                _add_node(n)
+            for e in oa_res["edges"]:
+                _add_edge(e["source"], e["target"], e.get("relation", "api"))
+
+    # =========================================================================
+    # CROSS-STACK LINKING PASS 1: DB Table/Column <-> ORM Model <-> Python Class/Function
+    # =========================================================================
+    # Map class names & table names
+    class_to_py_id: Dict[str, str] = {}
+    func_to_py_ids: Dict[str, List[str]] = {}
+    module_stem_to_rel: Dict[str, str] = {}
+
+    for rel_p, py_info in py_modules.items():
+        stem = os.path.splitext(rel_p)[0].replace("/", ".")
+        short_stem = os.path.splitext(os.path.basename(rel_p))[0]
+        module_stem_to_rel[stem] = rel_p
+        module_stem_to_rel[short_stem] = rel_p
+
+        for cname, cinfo in py_info["classes"].items():
+            cls_id = f"py:{rel_p}:{cname}"
+            class_to_py_id[cname] = cls_id
+            tbl_guess = (cinfo.get("tablename") or _pluralize(cname)).lower()
+            if tbl_guess in db_tables:
+                _add_edge(f"db:{tbl_guess}", cls_id, "maps_table_to_class")
+                if cname in orm_models:
+                    _add_edge(f"orm:{cname}", cls_id, "orm_to_py_class")
+                for fname in cinfo["fields"]:
+                    col_id = f"db:{tbl_guess}.{fname.lower()}"
+                    py_field_id = f"py:{rel_p}:{cname}.{fname}"
+                    if fname.lower() in db_tables[tbl_guess]["columns"]:
+                        _add_edge(col_id, py_field_id, "maps_column_to_field")
+                    if cname in orm_models and fname in orm_models[cname]["fields"]:
+                        _add_edge(f"orm:{cname}.{fname}", py_field_id, "orm_field_to_py_field")
+
+        for fname in py_info["functions"]:
+            func_to_py_ids.setdefault(fname, []).append(f"py:{rel_p}:{fname}")
+
+    # Link Python imports & cross-module function calls + SQL/ORM references inside functions
+    for rel_p, py_info in py_modules.items():
+        mod_id = f"py:{rel_p}"
+        for imp in py_info["imports"]:
+            target_mod = imp.get("module", "")
+            target_sym = imp.get("symbol", "")
+            resolved_rel = (
+                module_stem_to_rel.get(target_mod)
+                or module_stem_to_rel.get(target_mod.split(".")[-1])
+                or module_stem_to_rel.get(target_sym)
+            )
+            if resolved_rel and resolved_rel != rel_p:
+                # Module import edge for circular dependency detection & module blast radius
+                _add_edge(f"py:{resolved_rel}", mod_id, "imported_by")
+                module_import_edges.append({"source": mod_id, "target": f"py:{resolved_rel}"})
+
+        for fn_name, fn_meta in py_info["functions"].items():
+            fn_id = f"py:{rel_p}:{fn_name}"
+
+            # Cross-module function calls
+            for called in fn_meta.get("calls", []):
+                short_called = called.split(".")[-1]
+                for target_fn_id in func_to_py_ids.get(short_called, []):
+                    if target_fn_id != fn_id:
+                        _add_edge(target_fn_id, fn_id, "called_by")
+                if called in class_to_py_id:
+                    _add_edge(class_to_py_id[called], fn_id, "instantiates_class")
+
+            # Attribute accesses (e.g. user.balance, User.balance) -> link from ORM/DB column to function
+            for attr in fn_meta.get("attributes", []):
+                attr_short = attr.split(".")[-1].lower()
+                for tbl_name, tbl_info in db_tables.items():
+                    if attr_short in tbl_info["columns"]:
+                        col_id = f"db:{tbl_name}.{attr_short}"
+                        _add_edge(col_id, fn_id, "column_read_by_function")
+                for cls_name, minfo in orm_models.items():
+                    for orm_f in minfo["fields"]:
+                        if orm_f.lower() == attr_short:
+                            _add_edge(f"orm:{cls_name}.{orm_f}", fn_id, "orm_field_read_by_function")
+                            if cls_name in class_to_py_id:
+                                py_cls_file = py_modules_file_for_class(py_modules, cls_name)
+                                if py_cls_file:
+                                    _add_edge(f"py:{py_cls_file}:{cls_name}.{orm_f}", fn_id, "field_read_by_function")
+
+            # Raw SQL string literals inside function bodies (e.g. "SELECT id, balance FROM users")
+            for s_lit in fn_meta.get("string_literals", []):
+                s_low = s_lit.lower()
+                for tbl_name, tbl_info in db_tables.items():
+                    if re.search(rf"\b{re.escape(tbl_name)}\b", s_low):
+                        _add_edge(f"db:{tbl_name}", fn_id, "queries_table")
+                        for col_name in tbl_info["columns"]:
+                            if re.search(rf"\b{re.escape(col_name)}\b", s_low):
+                                _add_edge(f"db:{tbl_name}.{col_name}", fn_id, "queries_column")
+
+    # =========================================================================
+    # CROSS-STACK LINKING PASS 2: Backend/ORM <-> API Route & Payload Fields
+    # =========================================================================
+    routes_by_norm_path: Dict[str, List[Dict[str, Any]]] = {}
+    for route in api_routes:
+        norm_p = route["normalized_path"]
+        routes_by_norm_path.setdefault(norm_p, []).append(route)
+        route_id = route["id"]
+        handler_id = route.get("handler_id")
+
+        # Connect DB/ORM fields referenced or returned by handler directly to API payload fields
+        for rf in route.get("response_fields", []):
+            rf_low = rf.lower()
+            field_node = f"api_field:{norm_p}.{rf}"
+            if handler_id:
+                _add_edge(handler_id, field_node, "populates_api_field")
+            for tbl_name, tbl_info in db_tables.items():
+                if rf_low in tbl_info["columns"]:
+                    _add_edge(f"db:{tbl_name}.{rf_low}", route_id, "exposes_db_column")
+                    _add_edge(f"db:{tbl_name}.{rf_low}", field_node, "maps_to_api_field")
+            for cls_name, minfo in orm_models.items():
+                for orm_f in minfo["fields"]:
+                    if orm_f.lower() == rf_low:
+                        _add_edge(f"orm:{cls_name}.{orm_f}", route_id, "exposes_orm_field")
+                        _add_edge(f"orm:{cls_name}.{orm_f}", field_node, "maps_orm_to_api_field")
+
+    # =========================================================================
+    # CROSS-STACK LINKING PASS 3: API Route/Payload <-> Frontend TS/React Consumers
+    # =========================================================================
+    fe_symbol_to_id: Dict[str, str] = {}
+    for rel_p, fe_info in fe_modules.items():
+        for sym_name in fe_info["symbols"]:
+            fe_symbol_to_id[sym_name] = f"fe:{rel_p}:{sym_name}"
+
+    for rel_p, fe_info in fe_modules.items():
+        fe_mod_id = f"fe:{rel_p}"
+        fe_syms = [f"fe:{rel_p}:{s}" for s in fe_info["symbols"]]
+        target_fe_nodes = fe_syms if fe_syms else [fe_mod_id]
+
+        # Link frontend cross-file imports
+        for imp in fe_info["imports"]:
+            sym = imp.get("symbol", "")
+            if sym in fe_symbol_to_id and fe_symbol_to_id[sym] not in target_fe_nodes:
+                for t_node in target_fe_nodes:
+                    _add_edge(fe_symbol_to_id[sym], t_node, "imported_by_component")
+
+        # Link API calls (fetch, axios, useSWR, useQuery) to API routes & payload fields
+        for call in fe_info["api_calls"]:
+            c_path = call["normalized_path"]
+            c_method = call["method"]
+            matched_routes = routes_by_norm_path.get(c_path, [])
+            if not matched_routes:
+                # Try prefix / parameter matching (e.g. /api/v1/users/123 vs /api/v1/users/:param)
+                for cand_path, r_list in routes_by_norm_path.items():
+                    if _paths_match(cand_path, c_path):
+                        matched_routes.extend(r_list)
+
+            for route in matched_routes:
+                route_id = route["id"]
+                _add_edge(route_id, fe_mod_id, "consumed_by_frontend_module")
+                for t_node in target_fe_nodes:
+                    _add_edge(route_id, t_node, "consumed_by_component")
+
+                # Connect accessed properties (e.g. data.balance) to api_field nodes
+                for prop in call.get("accessed_fields", []):
+                    field_node = f"api_field:{route['normalized_path']}.{prop}"
+                    if field_node in nodes_by_id:
+                        _add_edge(field_node, fe_mod_id, "field_read_by_frontend")
+                        for t_node in target_fe_nodes:
+                            _add_edge(field_node, t_node, "field_read_by_component")
+                            prop_node_id = f"{t_node}.{prop}"
+                            _add_node({
+                                "id": prop_node_id,
+                                "type": "frontend_property_access",
+                                "name": f"{os.path.basename(rel_p)} ({prop})",
+                                "property": prop,
+                                "file": rel_p,
+                                "layer": "frontend",
+                            })
+                            _add_edge(field_node, prop_node_id, "renders_field")
+                            _add_edge(t_node, prop_node_id, "accesses_property")
+
+    # =========================================================================
+    # CROSS-STACK LINKING PASS 3B: API Route/Payload <-> Flutter Dart Mobile/POS Consumers
+    # =========================================================================
+    for rel_p, d_info in flutter_modules.items():
+        dart_mod_id = f"dart:{rel_p}"
+        dart_classes = [f"dart:{rel_p}:{c['name']}" for c in d_info.get("classes", [])]
+        target_dart_nodes = dart_classes if dart_classes else [dart_mod_id]
+
+        for call in d_info.get("api_calls", []):
+            c_path = call["path"]
+            matched_routes = routes_by_norm_path.get(c_path, [])
+            if not matched_routes:
+                for cand_path, r_list in routes_by_norm_path.items():
+                    if _paths_match(cand_path, c_path) or c_path.rstrip("/") in cand_path or cand_path.rstrip("/") in c_path:
+                        matched_routes.extend(r_list)
+
+            for route in matched_routes:
+                route_id = route["id"]
+                _add_edge(route_id, dart_mod_id, "consumed_by_flutter_app")
+                for t_node in target_dart_nodes:
+                    _add_edge(route_id, t_node, "consumed_by_flutter_model")
+
+                for prop in d_info.get("accessed_properties", []):
+                    field_node = f"api_field:{route['normalized_path']}.{prop}"
+                    if field_node in nodes_by_id:
+                        _add_edge(field_node, dart_mod_id, "field_read_by_flutter")
+                        for t_node in target_dart_nodes:
+                            _add_edge(field_node, t_node, "field_read_by_flutter_model")
+
+        for prop in d_info.get("accessed_properties", []):
+            for cls_name, minfo in orm_models.items():
+                if prop in minfo.get("fields", {}):
+                    for t_node in target_dart_nodes:
+                        _add_edge(f"orm:{cls_name}.{prop}", t_node, "orm_field_to_flutter")
+                        _add_edge(f"orm:{cls_name}", t_node, "orm_model_to_flutter")
+
+    # =========================================================================
+    # CROSS-STACK LINKING PASS 3C: API Route/Payload <-> Swift iOS Client Consumers
+    # =========================================================================
+    for rel_p, s_info in swift_modules.items():
+        sw_mod_id = f"swift:{rel_p}"
+        sw_classes = [f"swift:{rel_p}:{c['name']}" for c in s_info.get("classes", [])]
+        target_sw_nodes = sw_classes if sw_classes else [sw_mod_id]
+
+        for call in s_info.get("api_calls", []):
+            c_path = call["path"]
+            matched_routes = routes_by_norm_path.get(c_path, [])
+            if not matched_routes:
+                for cand_path, r_list in routes_by_norm_path.items():
+                    if _paths_match(cand_path, c_path) or c_path.rstrip("/") in cand_path or cand_path.rstrip("/") in c_path:
+                        matched_routes.extend(r_list)
+
+            for route in matched_routes:
+                route_id = route["id"]
+                _add_edge(route_id, sw_mod_id, "consumed_by_ios_app")
+                for t_node in target_sw_nodes:
+                    _add_edge(route_id, t_node, "consumed_by_ios_model")
+
+                for prop in s_info.get("accessed_properties", []):
+                    field_node = f"api_field:{route['normalized_path']}.{prop}"
+                    if field_node in nodes_by_id:
+                        _add_edge(field_node, sw_mod_id, "field_read_by_ios")
+                        for t_node in target_sw_nodes:
+                            _add_edge(field_node, t_node, "field_read_by_ios_model")
+
+        for prop in s_info.get("accessed_properties", []):
+            for cls_name, minfo in orm_models.items():
+                if prop in minfo.get("fields", {}):
+                    for t_node in target_sw_nodes:
+                        _add_edge(f"orm:{cls_name}.{prop}", t_node, "orm_field_to_ios")
+                        _add_edge(f"orm:{cls_name}", t_node, "orm_model_to_ios")
+
+    # =========================================================================
+    # CROSS-STACK LINKING PASS 3D: API Route/Payload <-> Kotlin Android Client Consumers
+    # =========================================================================
+    for rel_p, k_info in kotlin_modules.items():
+        kt_mod_id = f"kotlin:{rel_p}"
+        kt_classes = [f"kotlin:{rel_p}:{c['name']}" for c in k_info.get("classes", [])]
+        target_kt_nodes = kt_classes if kt_classes else [kt_mod_id]
+
+        for call in k_info.get("api_calls", []):
+            c_path = call["path"]
+            matched_routes = routes_by_norm_path.get(c_path, [])
+            if not matched_routes:
+                for cand_path, r_list in routes_by_norm_path.items():
+                    if _paths_match(cand_path, c_path) or c_path.rstrip("/") in cand_path or cand_path.rstrip("/") in c_path:
+                        matched_routes.extend(r_list)
+
+            for route in matched_routes:
+                route_id = route["id"]
+                _add_edge(route_id, kt_mod_id, "consumed_by_android_app")
+                for t_node in target_kt_nodes:
+                    _add_edge(route_id, t_node, "consumed_by_android_model")
+
+                for prop in k_info.get("accessed_properties", []):
+                    field_node = f"api_field:{route['normalized_path']}.{prop}"
+                    if field_node in nodes_by_id:
+                        _add_edge(field_node, kt_mod_id, "field_read_by_android")
+                        for t_node in target_kt_nodes:
+                            _add_edge(field_node, t_node, "field_read_by_android_model")
+
+        for prop in k_info.get("accessed_properties", []):
+            for cls_name, minfo in orm_models.items():
+                if prop in minfo.get("fields", {}):
+                    for t_node in target_kt_nodes:
+                        _add_edge(f"orm:{cls_name}.{prop}", t_node, "orm_field_to_android")
+                        _add_edge(f"orm:{cls_name}", t_node, "orm_model_to_android")
+
+    # =========================================================================
+    # CROSS-STACK LINKING PASS 3E: API Route/Payload <-> Vue.js / Nuxt 3 Consumers
+    # =========================================================================
+    for rel_p, v_parse_res in vue_modules.items():
+        vue_mod_id = f"vue:{rel_p}"
+        comp_nodes = [f"vue:{rel_p}:{c.name}" for c in v_parse_res.components]
+        target_vue_nodes = comp_nodes if comp_nodes else [vue_mod_id]
+
+        for call in v_parse_res.api_calls:
+            c_path = _normalize_route_path(call.endpoint)
+            matched_routes = routes_by_norm_path.get(c_path, [])
+            if not matched_routes:
+                for cand_path, r_list in routes_by_norm_path.items():
+                    if _paths_match(cand_path, c_path) or c_path.rstrip("/") in cand_path or cand_path.rstrip("/") in c_path:
+                        matched_routes.extend(r_list)
+
+            for route in matched_routes:
+                route_id = route["id"]
+                _add_edge(route_id, vue_mod_id, "consumed_by_vue_storefront")
+                for t_node in target_vue_nodes:
+                    _add_edge(route_id, t_node, "consumed_by_vue_component")
+
+                for prop in v_parse_res.all_accessed_properties:
+                    field_node = f"api_field:{route['normalized_path']}.{prop}"
+                    if field_node in nodes_by_id:
+                        _add_edge(field_node, vue_mod_id, "field_read_by_vue")
+                        for t_node in target_vue_nodes:
+                            _add_edge(field_node, t_node, "field_read_by_vue_component")
+
+        for prop in v_parse_res.all_accessed_properties:
+            for cls_name, minfo in orm_models.items():
+                if prop in minfo.get("fields", {}):
+                    for t_node in target_vue_nodes:
+                        _add_edge(f"orm:{cls_name}.{prop}", t_node, "orm_field_to_vue")
+                        _add_edge(f"orm:{cls_name}", t_node, "orm_model_to_vue")
+
+    # =========================================================================
+    # CROSS-STACK LINKING PASS 3F: Go Microservice Structs & Outbound Calls
+    # =========================================================================
+    for rel_p, g_parse_res in go_modules.items():
+        go_mod_id = f"go:{rel_p}"
+        for st in g_parse_res.structs:
+            sid = f"go:{rel_p}:{st.name}"
+            # Match Go struct to DB table
+            norm_st = st.name.lower()
+            matching_tbls = [t for t in db_tables if t.lower() in (norm_st, _pluralize(norm_st), _singularize(norm_st))]
+            for tbl in matching_tbls:
+                _add_edge(f"db:{tbl}", sid, "table_backed_by_go_struct")
+                for gf in st.fields:
+                    fname = gf.json_name or gf.name.lower()
+                    if fname in db_tables[tbl]["columns"]:
+                        _add_edge(f"db:{tbl}.{fname}", f"go:{rel_p}:{st.name}.{gf.name}", "column_to_go_field")
+
+        for call in g_parse_res.api_calls:
+            c_path = _normalize_route_path(call.endpoint)
+            matched_routes = routes_by_norm_path.get(c_path, [])
+            if not matched_routes:
+                for cand_path, r_list in routes_by_norm_path.items():
+                    if _paths_match(cand_path, c_path) or c_path.rstrip("/") in cand_path or cand_path.rstrip("/") in c_path:
+                        matched_routes.extend(r_list)
+            for route in matched_routes:
+                _add_edge(go_mod_id, route["id"], "go_calls_api_route")
+
+    # =========================================================================
+    # CROSS-STACK LINKING PASS 4: Backend/API/Frontend <-> Covering Test Suites
+    # =========================================================================
+    for test_rel, t_info in test_suites.items():
+        suite_id = f"test:{test_rel}"
+        for sym in t_info.get("imported_symbols", []):
+            for fn_id in func_to_py_ids.get(sym, []):
+                _add_edge(fn_id, suite_id, "covered_by_test_suite")
+            if sym in class_to_py_id:
+                _add_edge(class_to_py_id[sym], suite_id, "covered_by_test_suite")
+            if sym in fe_symbol_to_id:
+                _add_edge(fe_symbol_to_id[sym], suite_id, "covered_by_test_suite")
+
+        for tc in t_info.get("test_cases", []):
+            tc_id = tc["id"]
+            for called in tc.get("called_symbols", []):
+                for fn_id in func_to_py_ids.get(called, []):
+                    _add_edge(fn_id, tc_id, "verified_by_test")
+                if called in class_to_py_id:
+                    _add_edge(class_to_py_id[called], tc_id, "verified_by_test")
+                if called in fe_symbol_to_id:
+                    _add_edge(fe_symbol_to_id[called], tc_id, "verified_by_test")
+
+            for ep in tc.get("tested_endpoints", []):
+                parts = ep.split(" ", 1)
+                if len(parts) == 2:
+                    m, raw_p = parts[0], parts[1]
+                    norm_p = _normalize_route_path(raw_p)
+                    for r in routes_by_norm_path.get(norm_p, []):
+                        _add_edge(r["id"], tc_id, "endpoint_tested_by")
+                        _add_edge(r["id"], suite_id, "endpoint_covered_by_suite")
+
+    return {
+        "repo_root": root,
+        "nodes": list(nodes_by_id.values()),
+        "nodes_by_id": nodes_by_id,
+        "edges": edges,
+        "db_tables": db_tables,
+        "orm_models": orm_models,
+        "py_modules": py_modules,
+        "api_routes": api_routes,
+        "fe_modules": fe_modules,
+        "test_suites": test_suites,
+        "module_import_edges": module_import_edges,
+    }
+
+
+def py_modules_file_for_class(py_modules: Dict[str, Dict[str, Any]], cls_name: str) -> Optional[str]:
+    for rel_p, info in py_modules.items():
+        if cls_name in info.get("classes", {}):
+            return rel_p
+    return None
+
+
+def _paths_match(route_norm: str, call_norm: str) -> bool:
+    if route_norm == call_norm:
+        return True
+    r_parts = [p for p in route_norm.split("/") if p]
+    c_parts = [p for p in call_norm.split("/") if p]
+    if len(r_parts) != len(c_parts):
+        return False
+    for rp, cp in zip(r_parts, c_parts):
+        if rp == ":param" or cp == ":param" or rp.startswith(":") or cp.startswith(":"):
+            continue
+        if rp != cp:
+            return False
+    return True
+
+
+def resolve_entity_id(topology: Dict[str, Any], query: str) -> List[str]:
+    """
+    Resolves a user or AI agent symbol/table/route/component query string
+    into matching canonical node IDs inside the Full-Stack Contract Topology Engine.
+    """
+    if not query:
+        return []
+    q = query.strip()
+    nodes_by_id: Dict[str, Dict[str, Any]] = topology.get("nodes_by_id", {})
+    if q in nodes_by_id:
+        return [q]
+
+    q_low = q.lower()
+    exact_matches: List[str] = []
+    suffix_matches: List[str] = []
+    substring_matches: List[str] = []
+
+    # Direct prefix candidates
+    for prefix in ("db:", "orm:", "py:", "api:", "api_field:", "fe:", "test:"):
+        cand = f"{prefix}{q}"
+        if cand in nodes_by_id:
+            exact_matches.append(cand)
+        cand_low = f"{prefix}{q_low}"
+        if cand_low in nodes_by_id and cand_low not in exact_matches:
+            exact_matches.append(cand_low)
+
+    # Check API route path normalization if query looks like a URL path
+    if q.startswith("/") or q_low.startswith(("get ", "post ", "put ", "delete ", "patch ")):
+        if " " in q:
+            m_part, p_part = q.split(" ", 1)
+            norm_cand = f"api:{m_part.upper()} {_normalize_route_path(p_part)}"
+            if norm_cand in nodes_by_id:
+                exact_matches.append(norm_cand)
+        else:
+            norm_p = _normalize_route_path(q)
+            for m in ("GET", "POST", "PUT", "DELETE", "PATCH"):
+                cand = f"api:{m} {norm_p}"
+                if cand in nodes_by_id:
+                    exact_matches.append(cand)
+
+    if exact_matches:
+        return exact_matches
+
+    for nid, nmeta in nodes_by_id.items():
+        nid_low = nid.lower()
+        name_low = str(nmeta.get("name", "")).lower()
+        file_low = str(nmeta.get("file", "")).lower()
+        if name_low == q_low or file_low == q_low or os.path.basename(file_low) == q_low:
+            suffix_matches.append(nid)
+        elif nid_low.endswith(f":{q_low}") or nid_low.endswith(f".{q_low}") or nid_low.endswith(f"/{q_low}"):
+            suffix_matches.append(nid)
+        elif q_low in nid_low or q_low in name_low:
+            substring_matches.append(nid)
+
+    return suffix_matches if suffix_matches else substring_matches
+