graph-dependency-analyzer 0.2.0__py3-none-any.whl

src/presentation/api/rest/routers/analysis.py

@@ -0,0 +1,980 @@
+"""
+Analysis Router (Task 9.2)
+
+REST API endpoints for impact analysis operations.
+"""
+from fastapi import APIRouter, Depends, status, HTTPException, Query
+from pydantic import BaseModel, Field
+import structlog
+
+from src.application.dtos.impact_query_request import ImpactQueryRequest
+from src.application.dtos.impact_analysis_response import ImpactAnalysisResponse
+from src.application.dtos.affected_component import AffectedComponent
+from src.infrastructure.persistence.neo4j_dependency_repository import Neo4jDependencyGraphRepository
+from src.infrastructure.persistence.qdrant_vector_repository import QdrantVectorRepository
+from src.infrastructure.external_apis.openai_embedding_provider import OpenAIEmbeddingProvider
+from src.config.container import Container
+from dependency_injector.wiring import inject, Provide
+
+logger = structlog.get_logger(__name__)
+
+router = APIRouter(prefix="/api/analysis/impact", tags=["analysis"])
+
+
+@router.post(
+    "/repo-dependents",
+    response_model=ImpactAnalysisResponse,
+    status_code=status.HTTP_200_OK,
+    responses={
+        200: {"description": "Impact analysis completed"},
+        400: {"description": "Invalid target"},
+        422: {"description": "Validation error"},
+        500: {"description": "Internal server error"}
+    }
+)
+@inject
+async def analyze_repo_dependents(
+    request: ImpactQueryRequest,
+    neo4j_repo: Neo4jDependencyGraphRepository = Depends(Provide[Container.neo4j_repository])
+) -> ImpactAnalysisResponse:
+    """
+    Analyze which components depend on a repository.
+
+    Performs impact analysis to identify all classes, methods, and other
+    repositories that depend on the specified target repository.
+
+    Args:
+        request: Impact query with target repository name and max depth
+
+    Returns:
+        ImpactAnalysisResponse with affected components
+
+    Raises:
+        HTTP 400: Invalid or unknown repository
+        HTTP 422: Request validation failed
+        HTTP 500: Internal error during analysis
+    """
+    logger.info(
+        "repo_dependents_analysis_requested",
+        target=request.target,
+        max_depth=request.max_depth
+    )
+
+    try:
+        # Query Neo4j for components that depend on the target repository
+        query = f"""
+        MATCH (dependent)-[r*1..{request.max_depth}]->(component)
+        WHERE component.repository = $target_repo
+          AND dependent.repository <> $target_repo
+          AND dependent.repository <> 'external'
+          AND dependent.repository <> 'unknown'
+        RETURN DISTINCT
+          dependent.repository AS repo,
+          labels(dependent)[0] AS type,
+          dependent.qualified_name AS qualified_name,
+          dependent.file_path AS file_path
+        ORDER BY repo, qualified_name
+        LIMIT 100
+        """
+
+        async with neo4j_repo.driver.session() as session:
+            result = await session.run(query, target_repo=request.target)
+            records = await result.data()
+
+        # Convert to AffectedComponent DTOs
+        affected_components = []
+        for record in records:
+            component_type = "class"  # Default
+            if record["type"] == "METHOD":
+                component_type = "method"
+            elif record["type"] in ("REPOSITORY", "NPM_PACKAGE"):
+                component_type = "repository"
+
+            # Extract simple name from qualified_name
+            qualified_name = record.get("qualified_name") or ""
+            name = qualified_name.split(".")[-1] if qualified_name else "Unknown"
+
+            affected_components.append(
+                AffectedComponent(
+                    type=component_type,
+                    name=name,
+                    qualified_name=qualified_name,
+                    file_path=record.get("file_path")
+                )
+            )
+
+        response = ImpactAnalysisResponse(
+            target=request.target,
+            query_type="repo-dependents",
+            affected_components=affected_components
+        )
+
+        logger.info(
+            "repo_dependents_analysis_completed",
+            target=request.target,
+            affected_count=len(response.affected_components)
+        )
+
+        return response
+
+    except Exception as e:
+        logger.error(
+            "repo_dependents_analysis_failed",
+            target=request.target,
+            error=str(e),
+            error_type=type(e).__name__
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Impact analysis failed: {str(e)}"
+        )
+
+
+@router.post(
+    "/component-impact",
+    response_model=ImpactAnalysisResponse,
+    status_code=status.HTTP_200_OK,
+    responses={
+        200: {"description": "Impact analysis completed"},
+        400: {"description": "Invalid target component"},
+        422: {"description": "Validation error"},
+        500: {"description": "Internal server error"}
+    }
+)
+@inject
+async def analyze_component_impact(
+    request: ImpactQueryRequest,
+    neo4j_repo: Neo4jDependencyGraphRepository = Depends(Provide[Container.neo4j_repository])
+) -> ImpactAnalysisResponse:
+    """
+    Analyze impact of changes to a component (class, React component, function, etc).
+
+    Performs impact analysis to identify all components that would be
+    affected by changes to the specified component. Traverses dependencies
+    up to the specified max depth.
+
+    Supports both Java classes and TypeScript/React components.
+
+    Args:
+        request: Impact query with target component name and max depth
+
+    Returns:
+        ImpactAnalysisResponse with affected components
+
+    Raises:
+        HTTP 400: Invalid or unknown component
+        HTTP 422: Request validation failed
+        HTTP 500: Internal error during analysis
+    """
+    logger.info(
+        "component_impact_analysis_requested",
+        target=request.target,
+        max_depth=request.max_depth
+    )
+
+    try:
+        # Query Neo4j for components that import/depend on the target component
+        # Support both exact match and partial match (for simple names like "Header")
+        query = f"""
+        MATCH path = (dependent)-[r:IMPORTS*1..{request.max_depth}]->(target)
+        WHERE target.qualified_name CONTAINS $target_name
+          OR target.name = $target_name
+        WITH dependent, target, length(path) AS depth
+        WHERE dependent.repository <> 'external'
+          AND dependent.repository <> 'unknown'
+        RETURN DISTINCT
+          dependent.repository AS repo,
+          labels(dependent)[0] AS type,
+          dependent.qualified_name AS qualified_name,
+          dependent.name AS name,
+          dependent.file_path AS file_path,
+          depth,
+          target.qualified_name AS target_qualified_name
+        ORDER BY depth, repo, qualified_name
+        LIMIT 100
+        """
+
+        async with neo4j_repo.driver.session() as session:
+            result = await session.run(query, target_name=request.target)
+            records = await result.data()
+
+        if not records:
+            logger.warning(
+                "component_not_found_or_no_dependents",
+                target=request.target
+            )
+
+        # Convert to AffectedComponent DTOs
+        affected_components = []
+        for record in records:
+            component_type = "class"  # Default
+            if record["type"] == "METHOD":
+                component_type = "method"
+            elif record["type"] == "Component":
+                component_type = "class"  # React components as class
+
+            name = record.get("name") or record.get("qualified_name", "Unknown").split(".")[-1]
+
+            affected_components.append(
+                AffectedComponent(
+                    type=component_type,
+                    name=name,
+                    qualified_name=record.get("qualified_name"),
+                    file_path=record.get("file_path")
+                )
+            )
+
+        response = ImpactAnalysisResponse(
+            target=request.target,
+            query_type="component-impact",
+            affected_components=affected_components
+        )
+
+        logger.info(
+            "component_impact_analysis_completed",
+            target=request.target,
+            affected_count=len(response.affected_components)
+        )
+
+        return response
+
+    except Exception as e:
+        logger.error(
+            "component_impact_analysis_failed",
+            target=request.target,
+            error=str(e),
+            error_type=type(e).__name__
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Component impact analysis failed: {str(e)}"
+        )
+
+
+@router.get(
+    "/most-imported/{repository}",
+    response_model=ImpactAnalysisResponse,
+    status_code=status.HTTP_200_OK,
+    responses={
+        200: {"description": "Analysis completed"},
+        404: {"description": "Repository not found"},
+        500: {"description": "Internal server error"}
+    }
+)
+@inject
+async def get_most_imported_components(
+    repository: str,
+    limit: int = 20,
+    neo4j_repo: Neo4jDependencyGraphRepository = Depends(Provide[Container.neo4j_repository])
+) -> ImpactAnalysisResponse:
+    """
+    Get the most imported components in a repository.
+
+    Returns a ranking of components by import count, helping identify
+    critical components that have high impact if changed.
+
+    Args:
+        repository: Repository name (e.g., "wdc-ui")
+        limit: Maximum number of components to return (default: 20)
+
+    Returns:
+        ImpactAnalysisResponse with most imported components
+    """
+    logger.info(
+        "most_imported_analysis_requested",
+        repository=repository,
+        limit=limit
+    )
+
+    try:
+        # Query Neo4j for most imported components
+        query = """
+        MATCH (component)<-[r:IMPORTS]-(importer)
+        WHERE component.repository = $repository
+          AND importer.repository = $repository
+        WITH component, count(r) AS import_count
+        ORDER BY import_count DESC
+        LIMIT $limit
+        RETURN labels(component)[0] AS type,
+               component.name AS name,
+               component.qualified_name AS qualified_name,
+               component.file_path AS file_path,
+               import_count
+        """
+
+        async with neo4j_repo.driver.session() as session:
+            result = await session.run(query, repository=repository, limit=limit)
+            records = await result.data()
+
+        if not records:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Repository '{repository}' not found or has no import relationships"
+            )
+
+        # Convert to AffectedComponent DTOs
+        affected_components = []
+        for record in records:
+            component_type = "class"
+            if record["type"] == "METHOD":
+                component_type = "method"
+
+            name = record.get("name") or record.get("qualified_name", "Unknown").split(".")[-1]
+
+            affected_components.append(
+                AffectedComponent(
+                    type=component_type,
+                    name=f"{name} (imported {record['import_count']}x)",
+                    qualified_name=record.get("qualified_name"),
+                    file_path=record.get("file_path")
+                )
+            )
+
+        response = ImpactAnalysisResponse(
+            target=repository,
+            query_type="most-imported",
+            affected_components=affected_components
+        )
+
+        logger.info(
+            "most_imported_analysis_completed",
+            repository=repository,
+            components_found=len(affected_components)
+        )
+
+        return response
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "most_imported_analysis_failed",
+            repository=repository,
+            error=str(e),
+            error_type=type(e).__name__
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Most imported analysis failed: {str(e)}"
+        )
+
+
+@router.get(
+    "/cross-repo-dependencies/{repository}",
+    response_model=ImpactAnalysisResponse,
+    status_code=status.HTTP_200_OK,
+    responses={
+        200: {"description": "Analysis completed"},
+        404: {"description": "Repository not found"},
+        500: {"description": "Internal server error"}
+    }
+)
+@inject
+async def get_cross_repo_dependencies(
+    repository: str,
+    neo4j_repo: Neo4jDependencyGraphRepository = Depends(Provide[Container.neo4j_repository])
+) -> ImpactAnalysisResponse:
+    """
+    Get cross-repository dependencies for a repository.
+
+    Shows which other repositories import components from the target repository,
+    with detailed information about what is being imported.
+
+    Args:
+        repository: Target repository name (e.g., "wdc-ui")
+
+    Returns:
+        ImpactAnalysisResponse with importing repositories and components
+    """
+    logger.info(
+        "cross_repo_dependencies_requested",
+        repository=repository
+    )
+
+    try:
+        # Query Neo4j for cross-repository imports
+        query = """
+        MATCH (source)-[r:IMPORTS]->(target)
+        WHERE target.repository = $repository
+          AND source.repository <> $repository
+          AND source.repository <> 'external'
+          AND source.repository <> 'unknown'
+        RETURN DISTINCT
+          source.repository AS source_repo,
+          source.qualified_name AS source_component,
+          source.name AS source_name,
+          source.file_path AS source_file,
+          target.qualified_name AS target_component,
+          target.name AS target_name,
+          count(r) AS import_count
+        ORDER BY source_repo, import_count DESC
+        LIMIT 100
+        """
+
+        async with neo4j_repo.driver.session() as session:
+            result = await session.run(query, repository=repository)
+            records = await result.data()
+
+        if not records:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"No cross-repository dependencies found for '{repository}'"
+            )
+
+        # Convert to AffectedComponent DTOs
+        affected_components = []
+        for record in records:
+            source_name = record.get("source_name") or record.get("source_component", "").split(".")[-1]
+            target_name = record.get("target_name") or record.get("target_component", "").split(".")[-1]
+
+            affected_components.append(
+                AffectedComponent(
+                    type="class",
+                    name=f"{source_name} → {target_name} ({record['import_count']}x from {record['source_repo']})",
+                    qualified_name=record.get("source_component"),
+                    file_path=record.get("source_file")
+                )
+            )
+
+        response = ImpactAnalysisResponse(
+            target=repository,
+            query_type="cross-repo-dependencies",
+            affected_components=affected_components
+        )
+
+        logger.info(
+            "cross_repo_dependencies_completed",
+            repository=repository,
+            dependencies_found=len(affected_components)
+        )
+
+        return response
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "cross_repo_dependencies_failed",
+            repository=repository,
+            error=str(e),
+            error_type=type(e).__name__
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Cross-repo dependency analysis failed: {str(e)}"
+        )
+
+
+@router.get(
+    "/api-calls/{repository}",
+    response_model=ImpactAnalysisResponse,
+    status_code=status.HTTP_200_OK,
+    responses={
+        200: {"description": "API calls found"},
+        404: {"description": "Repository not found or no API calls detected"},
+        500: {"description": "Internal server error"}
+    }
+)
+@inject
+async def get_api_calls(
+    repository: str,
+    neo4j_repo: Neo4jDependencyGraphRepository = Depends(Provide[Container.neo4j_repository])
+) -> ImpactAnalysisResponse:
+    """
+    Get all API calls made by components in a repository.
+
+    Shows which components are calling which HTTP APIs (fetch, axios, etc.),
+    helping identify frontend-backend connections.
+
+    Args:
+        repository: Source repository name (e.g., "wdc-ui")
+
+    Returns:
+        ImpactAnalysisResponse with API calls (component → API endpoint)
+    """
+    logger.info(
+        "api_calls_analysis_requested",
+        repository=repository
+    )
+
+    try:
+        # Query Neo4j for API calls from this repository
+        query = """
+        MATCH (component)-[r:CALLS_API]->(api)
+        WHERE component.repository = $repository
+        RETURN DISTINCT
+          component.qualified_name AS component,
+          component.name AS component_name,
+          component.file_path AS file_path,
+          api.url AS api_endpoint,
+          r.line AS line_number
+        ORDER BY component, api_endpoint
+        LIMIT 100
+        """
+
+        async with neo4j_repo.driver.session() as session:
+            result = await session.run(query, repository=repository)
+            records = await result.data()
+
+        if not records:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"No API calls detected in repository '{repository}'. Make sure components use fetch(), axios, or similar HTTP clients with string literal URLs."
+            )
+
+        # Convert to AffectedComponent DTOs
+        affected_components = []
+        for record in records:
+            component_name = record.get("component_name") or record.get("component", "").split(".")[-1]
+            api_url = record.get("api_endpoint", "")
+            line = record.get("line_number", "")
+
+            affected_components.append(
+                AffectedComponent(
+                    type="method",  # Use "method" to indicate it's a function/component calling API
+                    name=f"{component_name} → {api_url} (line {line})",
+                    qualified_name=record.get("component"),
+                    file_path=record.get("file_path")
+                )
+            )
+
+        response = ImpactAnalysisResponse(
+            target=repository,
+            query_type="api-calls",
+            affected_components=affected_components
+        )
+
+        logger.info(
+            "api_calls_analysis_completed",
+            repository=repository,
+            api_calls_found=len(affected_components)
+        )
+
+        return response
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "api_calls_analysis_failed",
+            repository=repository,
+            error=str(e),
+            error_type=type(e).__name__
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"API calls analysis failed: {str(e)}"
+        )
+
+
+@router.get(
+    "/calls-backend/{repository}",
+    response_model=ImpactAnalysisResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Show which backend repos/endpoints this frontend repo calls",
+)
+@inject
+async def get_calls_backend(
+    repository: str,
+    neo4j_repo: Neo4jDependencyGraphRepository = Depends(Provide[Container.neo4j_repository]),
+) -> ImpactAnalysisResponse:
+    """Returns all CALLS_BACKEND edges originating from this repository."""
+    try:
+        query = """
+        MATCH (src)-[r:CALLS_BACKEND]->(ep)
+        WHERE src.repository = $repository
+        RETURN DISTINCT
+            src.qualified_name  AS caller,
+            src.file_path       AS file_path,
+            r.frontend_path     AS frontend_path,
+            ep.url              AS backend_path,
+            ep.repository       AS backend_repo,
+            r.http_method       AS http_method
+        ORDER BY backend_repo, frontend_path
+        LIMIT 200
+        """
+        async with neo4j_repo.driver.session() as session:
+            result = await session.run(query, repository=repository)
+            records = await result.data()
+
+        if not records:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"No backend calls found for '{repository}'. Run POST /cross-language-link first.",
+            )
+
+        components = []
+        for r in records:
+            method = r.get("http_method") or "?"
+            backend = r.get("backend_repo") or "?"
+            path = r.get("frontend_path") or ""
+            caller = (r.get("caller") or "").split(".")[-1]
+            components.append(AffectedComponent(
+                type="method",
+                name=f"{caller} →[{method}] {path} => {backend}",
+                qualified_name=r.get("caller"),
+                file_path=r.get("file_path"),
+            ))
+
+        return ImpactAnalysisResponse(
+            target=repository,
+            query_type="calls-backend",
+            affected_components=components,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post(
+    "/cross-language-link",
+    status_code=status.HTTP_200_OK,
+    summary="Link frontend API calls to backend endpoints across all indexed repositories",
+    description=(
+        "Reads all API nodes (frontend) and ENDPOINT nodes (backend) from Neo4j "
+        "and creates CALLS_BACKEND edges using normalised path suffix matching. "
+        "Run this after indexing all repositories."
+    ),
+)
+@inject
+async def cross_language_link(
+    neo4j_repo: Neo4jDependencyGraphRepository = Depends(Provide[Container.neo4j_repository]),
+) -> dict:
+    """Generic cross-language linker — framework agnostic, works for any repos."""
+    logger.info("cross_language_link_requested")
+
+    try:
+        async with neo4j_repo.driver.session() as session:
+            # Fetch all API nodes (frontend calls)
+            api_result = await session.run(
+                "MATCH (n:API) RETURN n.id AS id, n.url AS url"
+            )
+            api_rows = await api_result.data()
+
+            # Fetch all ENDPOINT nodes (backend endpoints)
+            ep_result = await session.run(
+                "MATCH (n:ENDPOINT) RETURN n.id AS id, n.url AS url, "
+                "n.http_method AS method, n.repository AS repo"
+            )
+            ep_rows = await ep_result.data()
+
+            # Fetch existing CALLS_API edges to know who calls each API node
+            ca_result = await session.run(
+                "MATCH (src)-[r:CALLS_API]->(api) "
+                "RETURN src.id AS src_id, api.id AS api_id, src.repository AS src_repo"
+            )
+            ca_rows = await ca_result.data()
+
+        if not api_rows or not ep_rows:
+            return {"created": 0, "message": "No API or ENDPOINT nodes found — index repositories first."}
+
+        import re
+
+        def normalise(path: str) -> str:
+            p = path.strip().lstrip("/").lower().split("?")[0]
+            p = re.sub(r'(?:\{[^}]+\}|:[^/]+)', '{p}', p)
+            return p
+
+        # Build caller map: api_id -> [src_id]
+        caller_map: dict[str, list[tuple[str, str]]] = {}
+        for row in ca_rows:
+            caller_map.setdefault(row["api_id"], []).append(
+                (row["src_id"], row.get("src_repo", ""))
+            )
+
+        # Build endpoint index: normalised_path -> endpoint row
+        ep_index: dict[str, dict] = {}
+        for ep in ep_rows:
+            norm = normalise(ep["url"] or "")
+            if norm:
+                ep_index[norm] = ep
+
+        # Match and create edges
+        edges_to_create: list[dict] = []
+        for api in api_rows:
+            api_norm = normalise(api["url"] or "")
+            if not api_norm:
+                continue
+            for ep_norm, ep in ep_index.items():
+                if api_norm == ep_norm or ep_norm.endswith("/" + api_norm):
+                    callers = caller_map.get(api["id"], [(api["id"], "")])
+                    for src_id, src_repo in callers:
+                        edges_to_create.append({
+                            "src": src_id,
+                            "tgt": ep["id"],
+                            "frontend_path": api["url"],
+                            "backend_path": ep["url"],
+                            "backend_repo": ep["repo"],
+                            "http_method": ep["method"],
+                        })
+
+        if not edges_to_create:
+            return {"created": 0, "message": "No path matches found between frontend calls and backend endpoints."}
+
+        # Write edges in batches
+        async with neo4j_repo.driver.session() as session:
+            query = """
+            UNWIND $edges AS e
+            MATCH (src {id: e.src})
+            MATCH (tgt {id: e.tgt})
+            MERGE (src)-[r:CALLS_BACKEND]->(tgt)
+            SET r.frontend_path = e.frontend_path,
+                r.backend_path  = e.backend_path,
+                r.backend_repo  = e.backend_repo,
+                r.http_method   = e.http_method,
+                r.match         = 'path_suffix'
+            """
+            await session.run(query, edges=edges_to_create)
+
+        logger.info("cross_language_link_completed", edges_created=len(edges_to_create))
+        return {
+            "created": len(edges_to_create),
+            "frontend_api_nodes": len(api_rows),
+            "backend_endpoint_nodes": len(ep_rows),
+            "message": f"Created {len(edges_to_create)} CALLS_BACKEND edges.",
+        }
+
+    except Exception as e:
+        logger.error("cross_language_link_failed", error=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Cross-language linking failed: {str(e)}",
+        )
+
+
+@router.post(
+    "/resolve-db-refs",
+    status_code=status.HTTP_200_OK,
+    summary="Resolve DB cross-references for Oracle/SQL repos",
+    description=(
+        "After indexing Oracle/SQL repos, READS_TABLE edges often point to stub nodes "
+        "with warehouse-schema prefixes (e.g. DBB01USR.T_PARCEL_PROCESS) instead of "
+        "the real DDL nodes (T_PARCEL_PROCESS). This endpoint:\n"
+        "1. Strips warehouse schema prefixes and creates edges to the real DDL nodes\n"
+        "2. Resolves case-insensitive mismatches between stub and real node IDs\n"
+        "Run this after indexing any Oracle/SQL schema repository."
+    ),
+)
+@inject
+async def resolve_db_refs(
+    neo4j_repo: Neo4jDependencyGraphRepository = Depends(Provide[Container.neo4j_repository]),
+) -> dict:
+    """
+    Resolves 3 types of broken DB ref edges without re-indexing:
+    1. Warehouse prefixes:  DBB01USR.TABLE  → TABLE
+    2. Cross-schema refs:   ZMEDAPP.TABLE   → TABLE
+    3. Case mismatches:     outordhdr       → OUTORDHDR
+    All done in batches via Cypher — no regex, no APOC needed.
+    """
+    logger.info("resolve_db_refs_requested")
+
+    total_step1 = 0
+    total_step2 = 0
+    total_step3 = 0
+
+    try:
+        async with neo4j_repo.driver.session() as session:
+
+            for rel_type in ("READS_TABLE", "WRITES_TABLE", "CALLS_PROCEDURE"):
+
+                # ── Step 1: Warehouse prefixes (DBBxxUSR. / DBCxxUSR.) ────────
+                # Use split + ENDS WITH 'USR' — no regex, fast
+                r = await session.run(f"""
+                    MATCH (src)-[:{rel_type}]->(stub:DB_TABLE)
+                    WHERE stub.is_stub = 'true'
+                      AND stub.id CONTAINS '.'
+                      AND split(stub.id, '.')[0] ENDS WITH 'USR'
+                    WITH DISTINCT src,
+                         toUpper(split(stub.id, '.')[1]) AS base_name,
+                         src.repository AS repo
+                    MATCH (real:DB_TABLE)
+                    WHERE toUpper(real.id) = base_name
+                      AND real.is_stub IS NULL
+                    MERGE (src)-[nr:{rel_type}]->(real)
+                    ON CREATE SET nr.resolved = 'warehouse', nr.repository = repo
+                    RETURN count(nr) AS cnt
+                """)
+                rows = await r.data()
+                total_step1 += rows[0]["cnt"] if rows else 0
+
+                # ── Step 2: Cross-schema (ZMEDAPP.TABLE, DBO.TABLE, etc.) ─────
+                r = await session.run(f"""
+                    MATCH (src)-[:{rel_type}]->(stub:DB_TABLE)
+                    WHERE stub.is_stub = 'true'
+                      AND stub.id CONTAINS '.'
+                      AND NOT split(stub.id, '.')[0] ENDS WITH 'USR'
+                    WITH DISTINCT src,
+                         toUpper(split(stub.id, '.')[1]) AS base_name,
+                         src.repository AS repo
+                    MATCH (real:DB_TABLE)
+                    WHERE toUpper(real.id) = base_name
+                      AND real.is_stub IS NULL
+                    MERGE (src)-[nr:{rel_type}]->(real)
+                    ON CREATE SET nr.resolved = 'schema', nr.repository = repo
+                    RETURN count(nr) AS cnt
+                """)
+                rows = await r.data()
+                total_step2 += rows[0]["cnt"] if rows else 0
+
+                # ── Step 3: Unprefixed case mismatch (outordhdr → OUTORDHDR) ──
+                r = await session.run(f"""
+                    MATCH (src)-[:{rel_type}]->(stub:DB_TABLE)
+                    WHERE stub.is_stub = 'true'
+                      AND NOT stub.id CONTAINS '.'
+                    WITH DISTINCT src,
+                         toUpper(stub.id) AS base_name,
+                         src.repository AS repo
+                    MATCH (real:DB_TABLE)
+                    WHERE toUpper(real.id) = base_name
+                      AND real.is_stub IS NULL
+                    MERGE (src)-[nr:{rel_type}]->(real)
+                    ON CREATE SET nr.resolved = 'case', nr.repository = repo
+                    RETURN count(nr) AS cnt
+                """)
+                rows = await r.data()
+                total_step3 += rows[0]["cnt"] if rows else 0
+
+                # Same resolution for DB_VIEW, DB_PROCEDURE targets
+                for node_label in ("DB_VIEW", "DB_PROCEDURE", "DB_PACKAGE"):
+                    r = await session.run(f"""
+                        MATCH (src)-[:{rel_type}]->(stub:{node_label})
+                        WHERE stub.is_stub = 'true'
+                        WITH DISTINCT src,
+                             toUpper(CASE WHEN stub.id CONTAINS '.'
+                                     THEN split(stub.id, '.')[1]
+                                     ELSE stub.id END) AS base_name,
+                             src.repository AS repo
+                        MATCH (real:{node_label})
+                        WHERE toUpper(real.id) = base_name
+                          AND real.is_stub IS NULL
+                        MERGE (src)-[nr:{rel_type}]->(real)
+                        ON CREATE SET nr.resolved = 'any', nr.repository = repo
+                        RETURN count(nr) AS cnt
+                    """)
+                    rows = await r.data()
+                    total_step2 += rows[0]["cnt"] if rows else 0
+
+            # ── Final count ──────────────────────────────────────────────────
+            count_r = await session.run("""
+                MATCH (src)-[r:READS_TABLE|WRITES_TABLE|CALLS_PROCEDURE]->(tgt)
+                WHERE coalesce(tgt.is_stub, 'false') <> 'true'
+                RETURN count(r) AS cnt
+            """)
+            count_rows = await count_r.data()
+            resolved_total = count_rows[0]["cnt"] if count_rows else 0
+
+        total_new = total_step1 + total_step2 + total_step3
+        result = {
+            "warehouse_prefix_resolved": total_step1,
+            "cross_schema_resolved": total_step2,
+            "case_mismatch_resolved": total_step3,
+            "total_new_edges": total_new,
+            "total_resolved_edges_in_graph": resolved_total,
+            "message": (
+                f"Created {total_new} new edges between real DDL nodes. "
+                f"Graph now has {resolved_total} resolved DB edges."
+            ),
+        }
+        logger.info("resolve_db_refs_completed", **result)
+        return result
+
+    except Exception as e:
+        logger.error("resolve_db_refs_failed", error=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"DB ref resolution failed: {str(e)}",
+        )
+
+
+# ---------------------------------------------------------------------------
+# Semantic search
+# ---------------------------------------------------------------------------
+
+class SemanticSearchRequest(BaseModel):
+    query: str = Field(..., min_length=3, description="Natural language search query")
+    repositories: list[str] | None = Field(
+        default=None,
+        description="Filter by repository names. None = search all indexed repos."
+    )
+    max_results: int = Field(default=10, ge=1, le=50, description="Max results to return")
+    score_threshold: float = Field(
+        default=0.35, ge=0.0, le=1.0,
+        description="Minimum similarity score (0-1). Lower = more results, less precise."
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "query": "user registration and authentication flow",
+                "repositories": ["wdc-packing-list", "wdc-ui"],
+                "max_results": 10,
+                "score_threshold": 0.35
+            }
+        }
+    }
+
+
+@router.post(
+    "/search",
+    status_code=status.HTTP_200_OK,
+    summary="Semantic search across indexed code",
+    description=(
+        "Searches all indexed code chunks using vector similarity (Qdrant + OpenAI embeddings). "
+        "Accepts a natural language query and returns the most relevant code chunks "
+        "ranked by semantic similarity. Use for business impact analysis to find "
+        "which files/methods implement a given concept."
+    ),
+)
+@inject
+async def semantic_search(
+    request: SemanticSearchRequest,
+    qdrant_repo: QdrantVectorRepository = Depends(Provide[Container.qdrant_repository]),
+    embedding_provider: OpenAIEmbeddingProvider = Depends(Provide[Container.embedding_provider]),
+) -> dict:
+    logger.info(
+        "semantic_search_requested",
+        query=request.query[:100],
+        repositories=request.repositories,
+        max_results=request.max_results,
+    )
+
+    try:
+        # 1. Embed the query
+        vectors = await embedding_provider.embed_batch([request.query])
+        if not vectors:
+            raise HTTPException(status_code=500, detail="Failed to generate query embedding")
+        query_vector = vectors[0]
+
+        # 2. Search Qdrant
+        hits = await qdrant_repo.search_similar(
+            query_vector=query_vector,
+            limit=request.max_results,
+            repositories=request.repositories,
+            score_threshold=request.score_threshold,
+        )
+
+        # 3. Group by repository for readability
+        by_repo: dict[str, list] = {}
+        for hit in hits:
+            repo = hit.get("repository", "unknown")
+            by_repo.setdefault(repo, []).append(hit)
+
+        logger.info("semantic_search_completed", results=len(hits))
+
+        return {
+            "query": request.query,
+            "total_results": len(hits),
+            "repositories_found": sorted(by_repo.keys()),
+            "results": hits,
+            "results_by_repo": by_repo,
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("semantic_search_failed", error=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Semantic search failed: {str(e)}",
+        )