Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

16.8 KB
Raw Blame
"""Index-backed contract extraction: routes read at indexed handler symbols.

Three claims are under test here. The first is that anchoring a route to the
declaration directly above an indexed symbol removes a class of defect the
regex could only chase: a route-shaped string in a comment or a docstring is
not a declaration above a handler, and an empty path is just a string argument,
so neither can fabricate or lose a contract.

The second is the inherited-framework claim. Ingestion resolves Flask as well
as FastAPI, while the workspace regex layer was FastAPI-only. Flask arriving
here without a new dialect module is the evidence that the rest of the
framework list comes with the layer rather than being hand-written per
framework.

The third is that the substrate is the repo's ``wiki.db``. The parse cache this
module used to read loaded zero of three repos on a live workspace, so the
end-to-end class below writes real rows and reads them back through the real
query path.
"""

from __future__ import annotations

from pathlib import Path

import pytest

from repowise.core.ingestion.models import FileInfo, Symbol
from repowise.core.ingestion.parser import ASTParser
from repowise.core.workspace.extractors.base import ScanContext
from repowise.core.workspace.extractors.from_index import (
    EXTRACTION_LAYER_KEY,
    LAYER_INDEX,
    extract_http_providers,
    symbols_for_content,
)
from repowise.core.workspace.repo_index import IndexedSymbol

from ._repo_index import make_repo_index

REL_PATH = "app/routers/chat.py"


def _case(
    prelude: str, *handlers: tuple[str, list[str]]
) -> tuple[ScanContext, list[IndexedSymbol], list[str]]:
    """Assemble file text plus the symbol rows the index would hold for it.

    Each handler contributes its decorator lines and a two-line ``def``. The
    symbol's ``start_line`` is the ``def`` line, which is where the parser puts
    it — decorators live above the span, never inside it.
    """
    lines = prelude.split("\n")
    symbols: list[IndexedSymbol] = []
    for name, decorators in handlers:
        lines.append("")
        lines.extend(decorators)
        start = len(lines) + 1
        lines.append(f"async def {name}() -> None:")
        lines.append("    ...")
        symbols.append(
            IndexedSymbol(
                symbol_id=f"{REL_PATH}::{name}",
                name=name,
                qualified_name=name,
                kind="function",
                signature=f"def {name}()",
                file_path=REL_PATH,
                start_line=start,
                end_line=start + 1,
                visibility="public",
            )
        )
    content = "\n".join(lines)
    ctx = ScanContext("backend", REL_PATH, ".py", content)
    return ctx, symbols, lines


def _extract(prelude: str, *handlers: tuple[str, list[str]]):
    ctx, symbols, lines = _case(prelude, *handlers)
    return extract_http_providers(ctx, symbols, lines)


def _ids(contracts) -> set[str]:
    return {c.contract_id for c in contracts}


class TestFastApiFromDecorators:
    PRELUDE = 'router = APIRouter(prefix="/snapshots/{snapshot_id}/chat")'

    def test_empty_path_route_resolves_to_the_prefix(self) -> None:
        ids = _ids(_extract(self.PRELUDE, ("chat_message", ['@router.post("")'])))
        assert ids == {"http::POST::/snapshots/{param}/chat"}

    def test_provenance_is_recorded(self) -> None:
        contract = _extract(self.PRELUDE, ("chat_message", ['@router.post("")']))[0]
        assert contract.meta[EXTRACTION_LAYER_KEY] == LAYER_INDEX
        assert contract.meta["handler"] == "chat_message"

    def test_layer_key_does_not_collide_with_grpc_dialect_provenance(self) -> None:
        # The gRPC dialects already own meta["source"] for dialect provenance
        # ("py_servicer", "go_client", "proto"); the layer must not overwrite
        # it or the coverage metric mis-partitions every gRPC contract.
        assert EXTRACTION_LAYER_KEY != "source"
        contract = _extract(self.PRELUDE, ("chat", ['@router.post("")']))[0]
        assert "source" not in contract.meta

    def test_a_multi_line_decorator_is_read_whole(self) -> None:
        ids = _ids(
            _extract(
                self.PRELUDE,
                (
                    "chat",
                    ["@router.post(", '    "/messages",', "    status_code=201,", ")"],
                ),
            )
        )
        assert ids == {"http::POST::/snapshots/{param}/chat/messages"}

    def test_a_stacked_decorator_does_not_hide_the_route(self) -> None:
        ids = _ids(
            _extract(
                self.PRELUDE,
                ("chat", ['@limiter.limit("120/minute")', '@router.get("/history")']),
            )
        )
        assert ids == {"http::GET::/snapshots/{param}/chat/history"}

    def test_a_comment_inside_a_multi_line_decorator_keeps_the_route(self) -> None:
        decorator = [
            "@router.get(",
            '    "/conversations",',
            "    # Tight on purpose (one call per load).",
            "",
            "    dependencies=[Depends(limit())],",
            ")",
        ]
        ids = _ids(_extract(self.PRELUDE, ("chat", decorator)))
        assert ids == {"http::GET::/snapshots/{param}/chat/conversations"}

    def test_a_comment_between_stacked_decorators_keeps_the_route(self) -> None:
        stack = ['@router.post("/fork")', "# Per-IP as well.", '@limiter.limit("10/hour")']
        ids = _ids(_extract(self.PRELUDE, ("chat", stack)))
        assert ids == {"http::POST::/snapshots/{param}/chat/fork"}

    def test_a_comment_in_the_arguments_is_not_read_as_one(self) -> None:
        decorator = ['@router.route("/items",', '    # methods=["POST"]', ")"]
        ids = _ids(_extract(self.PRELUDE, ("items", decorator)))
        assert ids == {"http::GET::/snapshots/{param}/chat/items"}

    def test_a_commented_out_decorator_in_a_stack_is_not_a_route(self) -> None:
        stack =['# @router.delete("/old")', '@limiter.limit("10/hour")']
        assert _extract(self.PRELUDE, ("chat", stack)) == []

    def test_non_route_decorators_are_ignored(self) -> None:
        assert (
            _extract(
                self.PRELUDE,
                ("chat", ['@limiter.limit("240/minute")', "@dataclass", "@classmethod"]),
            )
            == []
        )

    def test_unknown_router_variable_is_not_a_route(self) -> None:
        assert _extract(self.PRELUDE, ("cached", ['@cache.get("/x")'])) == []

    def test_the_same_route_twice_yields_one_contract(self) -> None:
        contracts = _extract(
            self.PRELUDE,
            ("chat", ['@router.post("")']),
            ("chat_again", ['@router.post("")']),
        )
        assert len(contracts) == 1

    def test_a_decorated_class_does_not_lend_its_route_to_a_method(self) -> None:
        # PEP 8 asks for a blank line here and nothing enforces one. Without a
        # stop at ordinary code the walk climbs past ``class Foo:`` and binds
        # the class's route to the first method under it.
        content = '\n'.join(
            [
                'app = Flask(__name__)',
                '@app.route("/items")',
                "class Foo:",
                "    def get(self) -> None:",
                "        ...",
            ]
        )
        ctx = ScanContext("backend", REL_PATH, ".py", content)
        method = IndexedSymbol(
            symbol_id=f"{REL_PATH}::Foo::get",
            name="get",
            qualified_name="Foo.get",
            kind="method",
            signature="def get(self)",
            file_path=REL_PATH,
            start_line=4,
            end_line=5,
            visibility="public",
        )
        assert extract_http_providers(ctx, [method], content.split("\n")) == []

    def test_a_neighbouring_handler_does_not_lend_its_route(self) -> None:
        content = '\n'.join(
            [
                'router = APIRouter()',
                '@router.get("/first")',
                "async def first() -> None:",
                "    ...",
                "async def second() -> None:",
                "    ...",
            ]
        )
        ctx = ScanContext("backend", REL_PATH, ".py", content)
        second = IndexedSymbol(
            symbol_id=f"{REL_PATH}::second",
            name="second",
            qualified_name="second",
            kind="function",
            signature="def second()",
            file_path=REL_PATH,
            start_line=5,
            end_line=6,
            visibility="public",
        )
        assert extract_http_providers(ctx, [second], content.split("\n")) == []

    def test_a_non_handler_symbol_carries_no_route(self) -> None:
        # A route decorator can only sit above a callable; a module constant
        # that happens to follow one must not become a contract.
        ctx, symbols, lines = _case(self.PRELUDE, ("chat", ['@router.post("/x")']))
        constants = [
            IndexedSymbol(
                symbol_id=f"{REL_PATH}::EXAMPLE",
                name="EXAMPLE",
                qualified_name="EXAMPLE",
                kind="constant",
                signature="",
                file_path=REL_PATH,
                start_line=symbols[0].start_line,
                end_line=symbols[0].start_line,
                visibility="public",
            )
        ]
        assert extract_http_providers(ctx, constants, lines) == []


class TestCommentsCannotFabricateRoutes:
    """The self-extraction defect, structurally: prose is not a declaration."""

    PRELUDE = '''router = APIRouter(prefix="/api")

# Recognises @app.get('/path') and @router.post('/orders') declarations.
EXAMPLE = "@router.delete('/fabricated')"'''

    def test_route_shaped_text_above_no_handler_yields_nothing(self) -> None:
        assert _extract(self.PRELUDE, ("documented", [])) == []

    def test_a_real_decorator_in_the_same_file_still_counts(self) -> None:
        ids = _ids(_extract(self.PRELUDE, ("real", ['@router.get("/real")'])))
        assert ids == {"http::GET::/api/real"}

    def test_a_commented_out_decorator_is_not_a_route(self) -> None:
        # A comment never joins the decorator text, so a commented-out
        # decorator is inert; the first code line above ends the walk.
        ids = _ids(_extract(self.PRELUDE, ("plain", ['# @router.get("/commented")'])))
        assert ids == set()


class TestFlaskIsInherited:
    """Flask providers via the index path, for a file that names no framework.

    A file that imports Flask is left to the Flask dialect, which owns the
    ``register_blueprint`` prefix rule this path cannot apply. What is inherited
    here is the decorator shape: a ``@x.route`` above an indexed handler is read
    as a route wherever the framework is not spelled out.
    """

    PRELUDE = 'app = Flask(__name__)\nbp = Blueprint("api", __name__)'

    def test_route_decorator_defaults_to_get(self) -> None:
        ids = _ids(_extract(self.PRELUDE, ("index", ['@app.route("/health")'])))
        assert ids == {"http::GET::/health"}

    def test_methods_kwarg_yields_one_contract_per_verb(self) -> None:
        ids = _ids(
            _extract(
                self.PRELUDE,
                ("users", ['@app.route("/users", methods=["POST", "PUT"])']),
            )
        )
        assert ids == {"http::POST::/users", "http::PUT::/users"}

    def test_framework_is_labelled_flask(self) -> None:
        contract = _extract(self.PRELUDE, ("index", ['@app.route("/health")']))[0]
        assert contract.meta["framework"] == "flask"
        assert contract.meta[EXTRACTION_LAYER_KEY] == LAYER_INDEX

    def test_blueprint_url_prefix_is_stitched_on(self) -> None:
        # Flask spells it ``url_prefix=``, and the shared prefix pattern is not
        # left-anchored to a word boundary, so it matches that too and the
        # blueprint's mount lands on the route. Incidental, but correct — this
        # test pins the behaviour so a later tightening of the pattern has to
        # keep Flask working deliberately.
        prelude = 'bp = Blueprint("api", __name__, url_prefix="/api")'
        ids = _ids(_extract(prelude, ("listing", ['@bp.route("/items")'])))
        assert ids == {"http::GET::/api/items"}

    def test_a_flask_file_is_left_to_the_flask_dialect(self) -> None:
        # One layer per file: this one cannot read a `register_blueprint`
        # prefix, so a route it published would be served somewhere else.
        prelude = "from flask import Flask\n\n" + self.PRELUDE
        assert _extract(prelude, ("index", ['@app.route("/health")'])) == []


def test_no_index_on_the_context_means_no_symbols() -> None:
    ctx = ScanContext("backend", REL_PATH, ".py", "x = 1\n")
    assert symbols_for_content(ctx, 1) == []


ROUTES_PY = '''\
from fastapi import APIRouter

router = APIRouter(prefix="/snapshots/{snapshot_id}/chat")


# Documents the @router.get("/fabricated") shape this module handles.
EXAMPLE = "@router.delete('/also-fabricated')"


@router.post("")
async def chat_message() -> None:
    """Sends a message. See @router.put("/not-a-route") for the old shape."""


@router.get("/conversations")
async def list_conversations() -> None:
    ...
'''


def _parse_symbols(rel_path: str, source: str) -> list[Symbol]:
    """Symbols for *source* from the real parser, as ingestion records them."""
    info = FileInfo(
        path=rel_path,
        abs_path=f"/repo/{rel_path}",
        language="python",
        size_bytes=len(source),
        git_hash="",
        last_modified=0.0,
        is_test=False,
        is_config=False,
        is_api_contract=True,
        is_entry_point=False,
    )
    return ASTParser().parse_file(info, source.encode()).symbols


class TestAgainstARealIndex:
    """The plumbing, end to end: real parser, real wiki.db, real query path.

    Everything above builds symbol rows by hand, which cannot catch the two
    agreements this path depends on — that the parser's line numbers leave a
    decorator above the span, and that the rows survive the database round trip
    keyed by the same relative path the walk yields.
    """

    @pytest.fixture
    async def repo(self, tmp_path: Path):
        (tmp_path / "routers").mkdir()
        (tmp_path / "routers" / "chat.py").write_text(ROUTES_PY, encoding="utf-8")
        rel = "routers/chat.py"
        index = await make_repo_index(tmp_path, {rel: _parse_symbols(rel, ROUTES_PY)})
        yield tmp_path, index
        await index.close()

    def _extract_all(self, repo: Path, index):
        from repowise.core.workspace.extractors import HttpExtractor
        from repowise.core.workspace.extractors.base import make_exclude_predicate

        return HttpExtractor().extract(
            repo, "backend", make_exclude_predicate(), None, index
        )

    async def test_the_rows_round_trip(self, repo) -> None:
        _path, index = repo
        assert index.symbols_for_file("routers/chat.py")

    async def test_routes_come_from_the_index(self, repo) -> None:
        path, index = repo
        providers = [c for c in self._extract_all(path, index) if c.role == "provider"]
        assert providers, "index path produced nothing"
        assert {c.meta[EXTRACTION_LAYER_KEY] for c in providers} == {LAYER_INDEX}

    async def test_the_empty_path_route_survives_the_whole_path(self, repo) -> None:
        path, index = repo
        ids = _ids(self._extract_all(path, index))
        assert "http::POST::/snapshots/{param}/chat" in ids

    async def test_routes_in_comments_and_docstrings_are_not_extracted(
        self, repo
    ) -> None:
        path, index = repo
        ids = _ids(self._extract_all(path, index))
        for fabricated in (
            "http::GET::/snapshots/{param}/chat/fabricated",
            "http::DELETE::/snapshots/{param}/chat/also-fabricated",
            "http::PUT::/snapshots/{param}/chat/not-a-route",
        ):
            assert fabricated not in ids

    async def test_a_truncated_file_falls_back_to_the_regex(self, repo) -> None:
        path, index = repo
        # Cut the file down after it was indexed: the spans now overrun it, so
        # they must be refused rather than used to slice the wrong lines.
        (path / "routers" / "chat.py").write_text(
            'from fastapi import APIRouter\n\nrouter = APIRouter(prefix="/api")\n',
            encoding="utf-8",
        )
        contracts = self._extract_all(path, index)
        layers = {
            c.meta.get(EXTRACTION_LAYER_KEY) for c in contracts if c.role == "provider"
        }
        assert LAYER_INDEX not in layers

    async def test_a_route_added_after_indexing_is_still_found(self, repo) -> None:
        path, index = repo
        (path / "routers" / "chat.py").write_text(
            ROUTES_PY + '\n\n@router.get("/added")\nasync def added() -> None: ...\n',
            encoding="utf-8",
        )
        # The appended route sits outside every indexed span, so the index
        # cannot see it; the regex dialect still can, and both run for a file
        # the index pass produced no routes for.
        ids = _ids(self._extract_all(path, index))
        assert "http::GET::/snapshots/{param}/chat/added" in ids