compass-code 0.1.0__py3-none-any.whl

compass_server/routers/query.py

@@ -0,0 +1,182 @@
+"""``/api`` routes: thin HTTP adapters over the read-only query layer.
+
+Each route parses its parameters, calls one ``compass_core.query`` function and returns
+its ``compass_core.contract`` result. Status codes for failures come from
+``ERROR_MAPPINGS``, the table every adapter shares.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Annotated, Any, TypeVar
+
+from fastapi import APIRouter, Depends, Query, Response
+
+from compass_core.contract.errors import ERROR_MAPPINGS, ErrorResponse
+from compass_core.contract.models import IndexStatus
+from compass_core.contract.params import (
+    DEFAULT_IMPACT_DEPTH,
+    DEFAULT_LIMIT,
+    DEFAULT_MIN_CONFIDENCE,
+    MAX_DEPTH,
+    MAX_LIMIT,
+    MAX_TEXT_LENGTH,
+    ImpactParams,
+    SearchParams,
+)
+from compass_core.contract.results import (
+    AmbiguousReference,
+    GraphMap,
+    ImpactResult,
+    Lookup,
+    NodeDetail,
+    OverviewResult,
+    SearchResult,
+    SymbolNotFound,
+)
+from compass_core.contract.serialize import to_json
+from compass_core.errors import ErrorCode
+from compass_core.graph.db import GraphDB
+from compass_core.index.locate import IndexLocation, locate_index
+from compass_core.query.detail import describe
+from compass_core.query.graph_map import graph_map
+from compass_core.query.impact import impact
+from compass_core.query.overview import overview
+from compass_core.query.search import find_symbols
+from compass_core.query.status import index_status
+from compass_core.shared_types import SymbolKind
+
+router = APIRouter(tags=["query"])
+
+R = TypeVar("R")
+
+_AMBIGUOUS_STATUS = ERROR_MAPPINGS[ErrorCode.AMBIGUOUS].http_status
+_NOT_FOUND_STATUS = ERROR_MAPPINGS[ErrorCode.NOT_FOUND].http_status
+_ERRORS: dict[int | str, dict[str, Any]] = {
+    ERROR_MAPPINGS[ErrorCode.INVALID_ARGUMENT].http_status: {
+        "model": ErrorResponse,
+        "description": "Invalid argument",
+    },
+    ERROR_MAPPINGS[ErrorCode.INDEX_NOT_FOUND].http_status: {
+        "model": ErrorResponse,
+        "description": "Index missing, busy or incompatible",
+    },
+    ERROR_MAPPINGS[ErrorCode.QUERY_TIMEOUT].http_status: {
+        "model": ErrorResponse,
+        "description": "Query timed out",
+    },
+}
+_LOOKUP_ERRORS: dict[int | str, dict[str, Any]] = {
+    _NOT_FOUND_STATUS: {"model": SymbolNotFound, "description": "Reference matched nothing"},
+    _AMBIGUOUS_STATUS: {
+        "model": AmbiguousReference,
+        "description": "Reference matched several symbols",
+    },
+    **_ERRORS,
+}
+
+
+def get_index() -> IndexLocation:
+    """FastAPI dependency for the index; the lookup rule lives in ``locate_index``.
+
+    Returns:
+        The index location.
+
+    Raises:
+        IndexNotFoundError: If no index can be found.
+        IndexIncompatibleError: If the index must be rebuilt with ``compass ingest``.
+    """
+    return locate_index()
+
+
+def get_db(location: Annotated[IndexLocation, Depends(get_index)]) -> Iterator[GraphDB]:
+    """Yield a read-only database handle that is always closed afterwards.
+
+    Args:
+        location: The located index.
+
+    Yields:
+        A read-only ``GraphDB``.
+    """
+    with GraphDB(location.db_path, read_only=True) as db:
+        yield db
+
+
+def _lookup_response(result: Lookup[R]) -> R | Response:
+    """Return a found result as is; an ambiguous or missing reference as its status code.
+
+    Args:
+        result: What a reference-taking operation returned.
+
+    Returns:
+        ``result`` itself, or a JSON response with the status ``ERROR_MAPPINGS`` gives
+        ``AMBIGUOUS`` or ``NOT_FOUND`` and the outcome as its body.
+
+    Example:
+        ``_lookup_response(SymbolNotFound(reference="x", suggestions=()))`` is a 404 whose
+        body is ``{"outcome":"not_found","reference":"x","suggestions":[]}``.
+    """
+    if isinstance(result, AmbiguousReference):
+        status = _AMBIGUOUS_STATUS
+    elif isinstance(result, SymbolNotFound):
+        status = _NOT_FOUND_STATUS
+    else:
+        return result
+    return Response(to_json(result), status_code=status, media_type="application/json")
+
+
+Location = Annotated[IndexLocation, Depends(get_index)]
+Db = Annotated[GraphDB, Depends(get_db)]
+# Free text: 1..MAX_TEXT_LENGTH characters with at least one non-whitespace character;
+# anything else is a 422 INVALID_ARGUMENT naming the parameter.
+_TEXT = Query(min_length=1, max_length=MAX_TEXT_LENGTH, pattern=r"\S")
+
+
+@router.get("/search", response_model=SearchResult, responses=_ERRORS)
+def search(
+    db: Db,
+    location: Location,
+    q: Annotated[str, _TEXT],
+    kind: SymbolKind | None = None,
+    limit: Annotated[int, Query(ge=1, le=MAX_LIMIT)] = DEFAULT_LIMIT,
+) -> SearchResult:
+    """Search files, classes, functions and methods by name."""
+    return find_symbols(db, location, SearchParams(query=q, kind=kind, limit=limit))
+
+
+@router.get("/impact", response_model=ImpactResult, responses=_LOOKUP_ERRORS)
+def impact_of(
+    db: Db,
+    location: Location,
+    ref: Annotated[str, _TEXT],
+    depth: Annotated[int, Query(ge=1, le=MAX_DEPTH)] = DEFAULT_IMPACT_DEPTH,
+    min_confidence: Annotated[float, Query(ge=0, le=1)] = DEFAULT_MIN_CONFIDENCE,
+    limit: Annotated[int, Query(ge=1, le=MAX_LIMIT)] = DEFAULT_LIMIT,
+) -> ImpactResult | Response:
+    """List what may be affected by changing a file or symbol."""
+    params = ImpactParams(depth=depth, min_confidence=min_confidence, limit=limit)
+    return _lookup_response(impact(db, location, ref, params))
+
+
+@router.get("/status", response_model=IndexStatus, responses=_ERRORS)
+def status(db: Db, location: Location) -> IndexStatus:
+    """Describe the index: which repository, when it was built and how many files changed since."""
+    return index_status(location, db)
+
+
+@router.get("/describe", response_model=NodeDetail, responses=_LOOKUP_ERRORS)
+def describe_node(db: Db, location: Location, ref: Annotated[str, _TEXT]) -> NodeDetail | Response:
+    """Describe one file, class, function or method: docstring, source and neighbours."""
+    return _lookup_response(describe(db, location, ref))
+
+
+@router.get("/overview", response_model=OverviewResult, responses=_ERRORS)
+def repo_overview(db: Db, location: Location) -> OverviewResult:
+    """Summarise the index: totals, entry points and ranked hot spots."""
+    return overview(db, location)
+
+
+@router.get("/graph/map", response_model=GraphMap, responses=_ERRORS)
+def graph(db: Db) -> GraphMap:
+    """Every file, class, function and method, and the edges between them, for drawing."""
+    return graph_map(db)

compass_server/settings.py

@@ -0,0 +1,37 @@
+"""Settings of the HTTP server: where it binds and which frontend may call it."""
+
+from __future__ import annotations
+
+from pydantic import Field, computed_field
+
+from compass_core.settings import Settings
+
+
+class ServerSettings(Settings):
+    """Engine settings plus the server's own, from the same environment and ``.env``.
+
+    Attributes:
+        API_HOST: Host the FastAPI server binds to.
+        API_PORT: Port the FastAPI server listens on.
+        FRONTEND_HOST: Host of the frontend dev server.
+        FRONTEND_PORT: Port of the frontend dev server.
+        FRONTEND_URL: Origin allowed by CORS, built from the two fields above.
+
+    Example:
+        ``API_PORT=9000 compass serve`` gives ``ServerSettings().API_PORT == 9000``;
+        the defaults give ``FRONTEND_URL == "http://localhost:3000"``.
+    """
+
+    API_HOST: str = Field(default="127.0.0.1", description="Host the FastAPI server binds to")
+    API_PORT: int = Field(default=8000, description="Port the FastAPI server listens on")
+
+    FRONTEND_HOST: str = Field(default="localhost", description="Host of the frontend dev server")
+    FRONTEND_PORT: int = Field(default=3000, description="Port of the frontend dev server")
+
+    @computed_field  # type: ignore[prop-decorator]  # known mypy/pydantic limitation: mypy flags any decorator stacked on @property before the pydantic plugin can special-case @computed_field
+    @property
+    def FRONTEND_URL(self) -> str:
+        return f"http://{self.FRONTEND_HOST}:{self.FRONTEND_PORT}"
+
+
+server_settings = ServerSettings()

compass_server/static/404.html

@@ -0,0 +1 @@
+<!DOCTYPE html><!--ctUZeD9K7jQUgLqmBas2L--><html lang="en" class="__variable_97b0d3 __variable_c19f6d __variable_cf84ab __variable_4dc837 h-full"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="preload" href="/_next/static/media/0484562807a97172-s.p.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="preload" href="/_next/static/media/4de1fea1a954a5b6-s.p.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="preload" href="/_next/static/media/5c0c2bcbaa4149ca-s.p.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="preload" href="/_next/static/media/6d664cce900333ee-s.p.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="preload" href="/_next/static/media/8888a3826f4a3af4-s.p.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="preload" href="/_next/static/media/b957ea75a84b6ea7-s.p.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="preload" href="/_next/static/media/bb3ef058b751a6ad-s.p.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="preload" href="/_next/static/media/eafabf029ad39a43-s.p.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="stylesheet" href="/_next/static/css/1b0fbfd8dd653f37.css" data-precedence="next"/><link rel="preload" as="script" fetchPriority="low" href="/_next/static/chunks/webpack-597057bf48ce4111.js"/><script src="/_next/static/chunks/1ff282bf-bb7c483245264fc9.js" async=""></script><script src="/_next/static/chunks/937-8692224bb6d1b605.js" async=""></script><script src="/_next/static/chunks/main-app-460e8bc670818718.js" async=""></script><meta name="robots" content="noindex"/><meta name="next-size-adjust" content=""/><title>404: This page could not be found.</title><title>Code Compass</title><meta name="description" content="Visualize your codebase as a knowledge graph"/><script>(function(){try{var s=localStorage.getItem("compass-theme");var t=s==="light"||s==="dark"?s:(window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light");document.documentElement.dataset.theme=t}catch(e){document.documentElement.dataset.theme="light"}})();</script><script src="/_next/static/chunks/polyfills-42372ed130431b0a.js" noModule=""></script></head><body class="font-sans h-svh overflow-hidden flex flex-col"><div hidden=""><!--$--><!--/$--></div><div style="font-family:system-ui,&quot;Segoe UI&quot;,Roboto,Helvetica,Arial,sans-serif,&quot;Apple Color Emoji&quot;,&quot;Segoe UI Emoji&quot;;height:100vh;text-align:center;display:flex;flex-direction:column;align-items:center;justify-content:center"><div><style>body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}</style><h1 class="next-error-h1" style="display:inline-block;margin:0 20px 0 0;padding:0 23px 0 0;font-size:24px;font-weight:500;vertical-align:top;line-height:49px">404</h1><div style="display:inline-block"><h2 style="font-size:14px;font-weight:400;line-height:49px;margin:0">This page could not be found.</h2></div></div></div><!--$--><!--/$--><script src="/_next/static/chunks/webpack-597057bf48ce4111.js" id="_R_" async=""></script><script>(self.__next_f=self.__next_f||[]).push([0])</script><script>self.__next_f.push([1,"1:\"$Sreact.fragment\"\n2:I[42712,[],\"\"]\n3:I[63566,[],\"\"]\n4:I[4373,[],\"OutletBoundary\"]\n6:I[10656,[],\"AsyncMetadataOutlet\"]\n8:I[4373,[],\"ViewportBoundary\"]\na:I[4373,[],\"MetadataBoundary\"]\nb:\"$Sreact.suspense\"\nd:I[22388,[],\"\"]\n:HL[\"/_next/static/media/0484562807a97172-s.p.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/media/4de1fea1a954a5b6-s.p.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/media/5c0c2bcbaa4149ca-s.p.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/media/6d664cce900333ee-s.p.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/media/8888a3826f4a3af4-s.p.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/media/b957ea75a84b6ea7-s.p.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/media/bb3ef058b751a6ad-s.p.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/media/eafabf029ad39a43-s.p.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/css/1b0fbfd8dd653f37.css\",\"style\"]\n"])</script><script>self.__next_f.push([1,"0:{\"P\":null,\"b\":\"ctUZeD9K7jQUgLqmBas2L\",\"p\":\"\",\"c\":[\"\",\"_not-found\"],\"i\":false,\"f\":[[[\"\",{\"children\":[\"/_not-found\",{\"children\":[\"__PAGE__\",{}]}]},\"$undefined\",\"$undefined\",true],[\"\",[\"$\",\"$1\",\"c\",{\"children\":[[[\"$\",\"link\",\"0\",{\"rel\":\"stylesheet\",\"href\":\"/_next/static/css/1b0fbfd8dd653f37.css\",\"precedence\":\"next\",\"crossOrigin\":\"$undefined\",\"nonce\":\"$undefined\"}]],[\"$\",\"html\",null,{\"lang\":\"en\",\"className\":\"__variable_97b0d3 __variable_c19f6d __variable_cf84ab __variable_4dc837 h-full\",\"suppressHydrationWarning\":true,\"children\":[[\"$\",\"head\",null,{\"children\":[\"$\",\"script\",null,{\"dangerouslySetInnerHTML\":{\"__html\":\"(function(){try{var s=localStorage.getItem(\\\"compass-theme\\\");var t=s===\\\"light\\\"||s===\\\"dark\\\"?s:(window.matchMedia(\\\"(prefers-color-scheme: dark)\\\").matches?\\\"dark\\\":\\\"light\\\");document.documentElement.dataset.theme=t}catch(e){document.documentElement.dataset.theme=\\\"light\\\"}})();\"}}]}],[\"$\",\"body\",null,{\"className\":\"font-sans h-svh overflow-hidden flex flex-col\",\"children\":[\"$\",\"$L2\",null,{\"parallelRouterKey\":\"children\",\"error\":\"$undefined\",\"errorStyles\":\"$undefined\",\"errorScripts\":\"$undefined\",\"template\":[\"$\",\"$L3\",null,{}],\"templateStyles\":\"$undefined\",\"templateScripts\":\"$undefined\",\"notFound\":\"$undefined\",\"forbidden\":\"$undefined\",\"unauthorized\":\"$undefined\"}]}]]}]]}],{\"children\":[\"/_not-found\",[\"$\",\"$1\",\"c\",{\"children\":[null,[\"$\",\"$L2\",null,{\"parallelRouterKey\":\"children\",\"error\":\"$undefined\",\"errorStyles\":\"$undefined\",\"errorScripts\":\"$undefined\",\"template\":[\"$\",\"$L3\",null,{}],\"templateStyles\":\"$undefined\",\"templateScripts\":\"$undefined\",\"notFound\":\"$undefined\",\"forbidden\":\"$undefined\",\"unauthorized\":\"$undefined\"}]]}],{\"children\":[\"__PAGE__\",[\"$\",\"$1\",\"c\",{\"children\":[[[\"$\",\"title\",null,{\"children\":\"404: This page could not be found.\"}],[\"$\",\"div\",null,{\"style\":{\"fontFamily\":\"system-ui,\\\"Segoe UI\\\",Roboto,Helvetica,Arial,sans-serif,\\\"Apple Color Emoji\\\",\\\"Segoe UI Emoji\\\"\",\"height\":\"100vh\",\"textAlign\":\"center\",\"display\":\"flex\",\"flexDirection\":\"column\",\"alignItems\":\"center\",\"justifyContent\":\"center\"},\"children\":[\"$\",\"div\",null,{\"children\":[[\"$\",\"style\",null,{\"dangerouslySetInnerHTML\":{\"__html\":\"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}\"}}],[\"$\",\"h1\",null,{\"className\":\"next-error-h1\",\"style\":{\"display\":\"inline-block\",\"margin\":\"0 20px 0 0\",\"padding\":\"0 23px 0 0\",\"fontSize\":24,\"fontWeight\":500,\"verticalAlign\":\"top\",\"lineHeight\":\"49px\"},\"children\":404}],[\"$\",\"div\",null,{\"style\":{\"display\":\"inline-block\"},\"children\":[\"$\",\"h2\",null,{\"style\":{\"fontSize\":14,\"fontWeight\":400,\"lineHeight\":\"49px\",\"margin\":0},\"children\":\"This page could not be found.\"}]}]]}]}]],null,[\"$\",\"$L4\",null,{\"children\":[\"$L5\",[\"$\",\"$L6\",null,{\"promise\":\"$@7\"}]]}]]}],{},null,false]},null,false]},null,false],[\"$\",\"$1\",\"h\",{\"children\":[[\"$\",\"meta\",null,{\"name\":\"robots\",\"content\":\"noindex\"}],[[\"$\",\"$L8\",null,{\"children\":\"$L9\"}],[\"$\",\"meta\",null,{\"name\":\"next-size-adjust\",\"content\":\"\"}]],[\"$\",\"$La\",null,{\"children\":[\"$\",\"div\",null,{\"hidden\":true,\"children\":[\"$\",\"$b\",null,{\"fallback\":null,\"children\":\"$Lc\"}]}]}]]}],false]],\"m\":\"$undefined\",\"G\":[\"$d\",[]],\"s\":false,\"S\":true}\n"])</script><script>self.__next_f.push([1,"9:[[\"$\",\"meta\",\"0\",{\"charSet\":\"utf-8\"}],[\"$\",\"meta\",\"1\",{\"name\":\"viewport\",\"content\":\"width=device-width, initial-scale=1\"}]]\n5:null\n"])</script><script>self.__next_f.push([1,"7:{\"metadata\":[[\"$\",\"title\",\"0\",{\"children\":\"Code Compass\"}],[\"$\",\"meta\",\"1\",{\"name\":\"description\",\"content\":\"Visualize your codebase as a knowledge graph\"}]],\"error\":null,\"digest\":\"$undefined\"}\n"])</script><script>self.__next_f.push([1,"c:\"$7:metadata\"\n"])</script></body></html>