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.

feat(workspace): resolve router mount prefixes in HTTP contract extraction (#567)

Raghav Chamadiya455ccb3def30
diff --git a/packages/core/src/repowise/core/workspace/extractors/base.py b/packages/core/src/repowise/core/workspace/extractors/base.py
index bcbc04dad..c5da5fc1b 100644
--- a/packages/core/src/repowise/core/workspace/extractors/base.py
+++ b/packages/core/src/repowise/core/workspace/extractors/base.py
@@ -12,8 +12,8 @@ descend into sibling/vendored repos rooted under the workspace.
from __future__ import annotations
import os
-from collections.abc import Iterator
-from dataclasses import dataclass
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass, field
from pathlib import Path
@@ -23,13 +23,16 @@ class ScanContext:
``rel_path`` is POSIX-relative to the repo root; ``suffix`` is the
lower-cased file extension (including the dot); ``content`` is the decoded
- file text.
+ file text. ``mounts`` is the repo-wide ``router-variable -> mount-prefix``
+ map a provider dialect uses to recover cross-file route prefixes (see
+ :mod:`.http.mounts`); empty for single-file extraction.
"""
repo_alias: str
rel_path: str
suffix: str
content: str
+ mounts: Mapping[str, str] = field(default_factory=dict)
def iter_source_files(
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/__init__.py b/packages/core/src/repowise/core/workspace/extractors/http/__init__.py
index 6700eed47..a92e6e627 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/__init__.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/__init__.py
@@ -21,6 +21,7 @@ from .fastapi import FastApiDialect
from .go import GoDialect
from .js_clients import JsClientsDialect
from .laravel import LaravelDialect
+from .mounts import merge_mount_maps
from .paths import normalize_http_path
from .python_clients import PythonClientsDialect
from .rust_axum import RustAxumDialect
@@ -66,14 +67,22 @@ class HttpExtractor:
consumer_dialects: tuple[HttpDialect, ...] = CONSUMER_DIALECTS
def extract(self, repo_path: Path, repo_alias: str = "") -> list[Contract]:
- """Scan all source files in *repo_path* and return Contract instances."""
+ """Scan all source files in *repo_path* and return Contract instances.
+
+ Files are read once into memory so a first pass can collect repo-wide
+ router mounts (``include_router(prefix=...)`` / ``app.use('/x', router)``)
+ before the extraction pass stitches them onto each provider route.
+ """
all_exts = _union_extensions(self.provider_dialects) | _union_extensions(
self.consumer_dialects
)
+ files = list(iter_source_files(repo_path, all_exts))
+ mounts = self._collect_mounts(files)
+
contracts: list[Contract] = []
- for rel_path, suffix, content in iter_source_files(repo_path, all_exts):
- ctx = ScanContext(repo_alias, rel_path, suffix, content)
+ for rel_path, suffix, content in files:
+ ctx = ScanContext(repo_alias, rel_path, suffix, content, mounts)
for dialect in self.provider_dialects:
if suffix in dialect.extensions:
contracts.extend(dialect.extract(ctx))
@@ -82,5 +91,22 @@ class HttpExtractor:
contracts.extend(dialect.extract(ctx))
return contracts
+ def _collect_mounts(self, files: list[tuple[str, str, str]]) -> dict[str, str]:
+ """Build the unambiguous repo-wide ``router-var -> mount-prefix`` map.
+
+ Each provider dialect may expose ``collect_mounts(content)``; results are
+ merged across every file, dropping any router name mounted at conflicting
+ prefixes (see :func:`merge_mount_maps`).
+ """
+ per_file: list[dict[str, str]] = []
+ for _rel, suffix, content in files:
+ for dialect in self.provider_dialects:
+ collect = getattr(dialect, "collect_mounts", None)
+ if collect is not None and suffix in dialect.extensions:
+ found = collect(content)
+ if found:
+ per_file.append(found)
+ return merge_mount_maps(per_file)
+
__all__ = ["CONSUMER_DIALECTS", "PROVIDER_DIALECTS", "HttpExtractor", "normalize_http_path"]
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/express.py b/packages/core/src/repowise/core/workspace/extractors/http/express.py
index 38a3175c4..501c2bda8 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/express.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/express.py
@@ -1,4 +1,9 @@
-"""Express / Node.js HTTP provider dialect — ``router.get('/path', ...)``."""
+"""Express / Node.js HTTP provider dialect — ``router.get('/path', ...)``.
+
+Express routers carry no in-file prefix; the mount lives in a separate
+``app.use('/prefix', router)`` call, so the real path is recovered by stitching
+the cross-file mount prefix (collected by the orchestrator) onto the route.
+"""
from __future__ import annotations
@@ -7,29 +12,54 @@ from typing import TYPE_CHECKING
from ..langs import JS_TS
from .dialect import METHODS, build_provider_contract
+from .mounts import compose_prefix
if TYPE_CHECKING:
from repowise.core.workspace.contracts import Contract
from ..base import ScanContext
-# router.get('/path', ...) or app.post('/path', ...). The negative lookbehind for
-# ``@`` keeps FastAPI decorators (``@app.get``) from matching here.
+# router.get('/path', ...) / app.post('/path', ...). The receiver variable is
+# captured so its mount prefix can be resolved; the negative lookbehind for ``@``
+# keeps decorator frameworks (FastAPI ``@app.get``, NestJS ``@Get``) out.
_EXPRESS_RE = re.compile(
- rf"""(?<!@)(?:router|app)\.({METHODS})\s*\(\s*['"]([^'"]+)['"]""",
+ rf"""(?<!@)(\w+)\.({METHODS})\s*\(\s*['"]([^'"]+)['"]""",
re.IGNORECASE,
)
+# Variables bound to an Express app / router: ``r = express.Router()``,
+# ``app = express()``, ``router = require('express').Router()``.
+_ROUTER_BIND_RE = re.compile(r"""(\w+)\s*=\s*(?:[\w.]*\.Router\s*\(|express\s*\(|Router\s*\()""")
+
+# app.use('/prefix', router) — a cross-file (or in-file) router mount.
+_APP_USE_RE = re.compile(r"""\.use\s*\(\s*['"]([^'"]+)['"]\s*,\s*([\w.]+)""")
+
+_DEFAULT_ROUTER_NAMES = frozenset({"app", "router"})
+
class ExpressDialect:
name = "express"
extensions = JS_TS
+ def collect_mounts(self, content: str) -> dict[str, str]:
+ """Find ``app.use('/prefix', router)`` mounts declared in *content*."""
+ out: dict[str, str] = {}
+ for m in _APP_USE_RE.finditer(content):
+ out[m.group(2).split(".")[-1]] = m.group(1)
+ return out
+
def extract(self, ctx: ScanContext) -> list[Contract]:
+ known = {m.group(1) for m in _ROUTER_BIND_RE.finditer(ctx.content)}
+ known |= _DEFAULT_ROUTER_NAMES
+
out: list[Contract] = []
for m in _EXPRESS_RE.finditer(ctx.content):
+ var, method, path_raw = m.group(1), m.group(2), m.group(3)
+ if var not in known:
+ continue
+ path = compose_prefix(ctx.mounts.get(var, ""), path_raw)
c = build_provider_contract(
- ctx, method=m.group(1).upper(), path_raw=m.group(2), framework="express"
+ ctx, method=method.upper(), path_raw=path, framework="express"
)
if c is not None:
out.append(c)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/fastapi.py b/packages/core/src/repowise/core/workspace/extractors/http/fastapi.py
index e7d00f14c..d4acb6255 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/fastapi.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/fastapi.py
@@ -1,4 +1,9 @@
-"""FastAPI / Python HTTP provider dialect — ``@app.get('/path')``."""
+"""FastAPI / Python HTTP provider dialect — ``@app.get('/path')``.
+
+Resolves the real route path by stitching three segments where present:
+a cross-file ``include_router(prefix=...)`` mount, the in-file
+``APIRouter(prefix=...)`` binding, and the decorator path itself.
+"""
from __future__ import annotations
@@ -7,28 +12,63 @@ from typing import TYPE_CHECKING
from ..langs import PYTHON
from .dialect import METHODS, build_provider_contract
+from .mounts import balanced_args, compose_prefix, router_prefixes
if TYPE_CHECKING:
from repowise.core.workspace.contracts import Contract
from ..base import ScanContext
-# @app.get('/path') or @router.post('/path')
+# @<var>.get('/path') / @<var>.post('/path'). The variable is captured so its
+# router prefix can be resolved; only known routers (those bound to APIRouter /
+# FastAPI in-file, plus the conventional ``app`` / ``router`` names) are kept, so
+# an unrelated ``@cache.get(...)`` decorator is not mistaken for a route.
_FASTAPI_RE = re.compile(
- rf"""@(?:app|router)\.({METHODS})\s*\(\s*['"]([^'"]+)['"]""",
+ rf"""@(\w+)\.({METHODS})\s*\(\s*['"]([^'"]+)['"]""",
re.IGNORECASE,
)
+# include_router(...) — a cross-file mount of a router.
+_INCLUDE_ROUTER_RE = re.compile(r"""include_router\s*\(""")
+_FIRST_ARG_RE = re.compile(r"""\s*([\w.]+)""")
+_PREFIX_KW_RE = re.compile(r"""prefix\s*=\s*['"]([^'"]+)['"]""")
+
+_DEFAULT_ROUTER_NAMES = frozenset({"app", "router"})
+
class FastApiDialect:
name = "fastapi"
extensions = PYTHON
+ def collect_mounts(self, content: str) -> dict[str, str]:
+ """Find ``include_router(var, prefix=...)`` mounts declared in *content*.
+
+ Keyed by the router variable's final name segment (``pkg.router`` ->
+ ``router``); only mounts that carry an explicit ``prefix=`` are recorded.
+ """
+ out: dict[str, str] = {}
+ for m in _INCLUDE_ROUTER_RE.finditer(content):
+ args = balanced_args(content, m.end() - 1) # m.end()-1 is the '('
+ var_m = _FIRST_ARG_RE.match(args)
+ pm = _PREFIX_KW_RE.search(args)
+ if var_m and pm:
+ out[var_m.group(1).split(".")[-1]] = pm.group(1)
+ return out
+
def extract(self, ctx: ScanContext) -> list[Contract]:
+ prefixes = router_prefixes(ctx.content, "APIRouter|FastAPI")
+ known = set(prefixes) | _DEFAULT_ROUTER_NAMES
+
out: list[Contract] = []
for m in _FASTAPI_RE.finditer(ctx.content):
+ var, method, path_raw = m.group(1), m.group(2), m.group(3)
+ if var not in known:
+ continue
+ # In-file APIRouter(prefix=...) then any cross-file mount of this var.
+ path = compose_prefix(prefixes.get(var, ""), path_raw)
+ path = compose_prefix(ctx.mounts.get(var, ""), path)
c = build_provider_contract(
- ctx, method=m.group(1).upper(), path_raw=m.group(2), framework="fastapi"
+ ctx, method=method.upper(), path_raw=path, framework="fastapi"
)
if c is not None:
out.append(c)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/go.py b/packages/core/src/repowise/core/workspace/extractors/http/go.py
index af81ae757..304bae987 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/go.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/go.py
@@ -1,6 +1,10 @@
"""Go HTTP provider dialect — gin/echo/chi ``r.GET("/path", ...)`` and
stdlib ``.HandleFunc("/path", ...)`` (which carries no method, recorded as
-``*``)."""
+``*``).
+
+Route groups (``api := r.Group("/api"); v1 := api.Group("/v1")``) are resolved
+transitively so a handler on ``v1`` records its full ``/api/v1/...`` path.
+"""
from __future__ import annotations
@@ -9,29 +13,62 @@ from typing import TYPE_CHECKING
from ..langs import GO
from .dialect import METHODS_UPPER, build_provider_contract
+from .mounts import compose_prefix
if TYPE_CHECKING:
from repowise.core.workspace.contracts import Contract
from ..base import ScanContext
-# r.GET("/path", ...) or .HandleFunc("/path", ...)
+# group := parent.Group("/segment") — a nested router group.
+_GROUP_RE = re.compile(r"""(\w+)\s*:?=\s*(\w+)\.Group\s*\(\s*['"]([^'"]+)['"]""")
+
+# r.GET("/path", ...) or .HandleFunc("/path", ...). The receiver variable is
+# captured (when it is a bare identifier) so its group prefix can be resolved; an
+# empty capture (e.g. an inline-chained ``Group("/x").GET(...)``) falls back to no
+# prefix, preserving the pre-group-resolution behaviour.
_GO_ROUTE_RE = re.compile(
- rf"""\.({METHODS_UPPER}|Handle|HandleFunc)\s*\(\s*['"]([^'"]+)['"]""",
+ rf"""(\w*)\.({METHODS_UPPER}|Handle|HandleFunc)\s*\(\s*['"]([^'"]+)['"]""",
)
+def _group_prefixes(content: str) -> dict[str, str]:
+ """Resolve each group variable to its full, transitively-composed prefix."""
+ # child -> (parent, segment)
+ edges: dict[str, tuple[str, str]] = {}
+ for m in _GROUP_RE.finditer(content):
+ edges[m.group(1)] = (m.group(2), m.group(3))
+
+ resolved: dict[str, str] = {}
+
+ def resolve(var: str, seen: frozenset[str]) -> str:
+ if var in resolved:
+ return resolved[var]
+ if var not in edges or var in seen:
+ return "" # base router (gin.Default()/echo.New()) or a cycle
+ parent, segment = edges[var]
+ prefix = compose_prefix(resolve(parent, seen | {var}), segment)
+ resolved[var] = prefix
+ return prefix
+
+ for var in edges:
+ resolve(var, frozenset())
+ return resolved
+
+
class GoDialect:
name = "go"
extensions = GO
def extract(self, ctx: ScanContext) -> list[Contract]:
+ prefixes = _group_prefixes(ctx.content)
out: list[Contract] = []
for m in _GO_ROUTE_RE.finditer(ctx.content):
- method_raw = m.group(1)
+ var, method_raw, path_raw = m.group(1), m.group(2), m.group(3)
# Handle/HandleFunc don't carry a method verb.
method = "*" if method_raw in ("Handle", "HandleFunc") else method_raw.upper()
- c = build_provider_contract(ctx, method=method, path_raw=m.group(2), framework="go")
+ path = compose_prefix(prefixes.get(var, ""), path_raw)
+ c = build_provider_contract(ctx, method=method, path_raw=path, framework="go")
if c is not None:
out.append(c)
return out
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/mounts.py b/packages/core/src/repowise/core/workspace/extractors/http/mounts.py
new file mode 100644
index 000000000..97208b07c
--- /dev/null
+++ b/packages/core/src/repowise/core/workspace/extractors/http/mounts.py
@@ -0,0 +1,88 @@
+"""Router mount-prefix resolution shared by the HTTP provider dialects.
+
+A framework's real route path is rarely the string in the decorator alone. It is
+that string stitched onto the prefix of the *router object* it hangs off:
+
+ router = APIRouter(prefix="/snapshots") # in-file binding
+ @router.get("/{id}/c4") # real path: /snapshots/{id}/c4
+
+and, one level up, the mount the router is attached at in a different file:
+
+ include_router(snapshots_router, prefix="/api") # real: /api/snapshots/{id}/c4
+
+Recovering both is the single highest-leverage recall fix for cross-repo contract
+matching: without it a provider stores ``/{param}/c4`` and never lines up with the
+consumer that calls ``/api/snapshots/{id}/c4``. The helpers here find the in-file
+``var -> prefix`` bindings and compose the segments; cross-file mounts are
+collected per dialect and merged by the orchestrator.
+"""
+
+from __future__ import annotations
+
+import re
+
+# A ``prefix="..."`` / ``prefix='...'`` keyword argument inside a constructor call.
+_PREFIX_KW_RE = re.compile(r"""prefix\s*=\s*['"]([^'"]+)['"]""")
+
+
+def balanced_args(content: str, open_paren: int) -> str:
+ """Return the text inside the parentheses opened at *open_paren*.
+
+ Scans to the matching close paren so nested calls in the argument list
+ (``dependencies=[Depends(x)]``) don't truncate the span the way a
+ ``[^)]*`` regex would.
+ """
+ depth = 0
+ for i in range(open_paren, len(content)):
+ ch = content[i]
+ if ch == "(":
+ depth += 1
+ elif ch == ")":
+ depth -= 1
+ if depth == 0:
+ return content[open_paren + 1 : i]
+ return content[open_paren + 1 :]
+
+
+def router_prefixes(content: str, ctor_pattern: str) -> dict[str, str]:
+ """Map ``var -> prefix`` for in-file ``var = Ctor(...)`` router bindings.
+
+ *ctor_pattern* is a regex alternation of constructor names (e.g.
+ ``APIRouter|FastAPI``). A constructor with no ``prefix=`` keyword maps to the
+ empty string, which still records the variable as a *known* router so its
+ routes are extracted.
+ """
+ out: dict[str, str] = {}
+ for m in re.finditer(rf"(\w+)\s*=\s*(?:{ctor_pattern})\s*\(", content):
+ var = m.group(1)
+ args = balanced_args(content, m.end() - 1) # m.end()-1 is the '('
+ pm = _PREFIX_KW_RE.search(args)
+ out[var] = pm.group(1) if pm else ""
+ return out
+
+
+def compose_prefix(prefix: str, path: str) -> str:
+ """Stitch a router *prefix* onto a method-level *path*.
+
+ ``("/snapshots", "/{id}/c4")`` -> ``"/snapshots/{id}/c4"``. An empty prefix
+ returns the path unchanged. Normalization (case, trailing slash, param
+ unification) is left to :func:`normalize_http_path` downstream.
+ """
+ if not prefix:
+ return path
+ return "/" + prefix.strip("/") + "/" + path.lstrip("/")
+
+
+def merge_mount_maps(maps: list[dict[str, str]]) -> dict[str, str]:
+ """Merge per-file cross-file mount maps into one unambiguous ``var -> prefix``.
+
+ A router variable mounted at two *different* prefixes anywhere in the repo is
+ ambiguous (the common case being a generic name like ``router`` reused across
+ files), so it is dropped rather than guessed. Only names with a single
+ distinct prefix survive.
+ """
+ collected: dict[str, set[str]] = {}
+ for m in maps:
+ for var, prefix in m.items():
+ collected.setdefault(var, set()).add(prefix)
+ return {var: next(iter(prefixes)) for var, prefixes in collected.items() if len(prefixes) == 1}
diff --git a/tests/unit/workspace/test_contracts.py b/tests/unit/workspace/test_contracts.py
index 177377e30..b38e4b094 100644
--- a/tests/unit/workspace/test_contracts.py
+++ b/tests/unit/workspace/test_contracts.py
@@ -154,6 +154,99 @@ class TestHttpExtractor:
assert len(providers) == 1
assert providers[0].contract_id == "http::GET::/health"
+ def test_fastapi_router_prefix_infile(self, tmp_path: Path) -> None:
+ # APIRouter(prefix=...) must be stitched onto each decorator path.
+ self._write_file(tmp_path, "routers/snapshots.py", """
+ router = APIRouter(prefix="/snapshots", tags=["snap"])
+
+ @router.get("/{snapshot_id}/symbols")
+ async def symbols(snapshot_id: str): ...
+
+ @router.post("/{snapshot_id}/chat")
+ async def chat(snapshot_id: str): ...
+ """)
+ contracts = HttpExtractor().extract(tmp_path, "backend")
+ ids = {c.contract_id for c in contracts if c.role == "provider"}
+ assert "http::GET::/snapshots/{param}/symbols" in ids
+ assert "http::POST::/snapshots/{param}/chat" in ids
+
+ def test_fastapi_multiple_routers_distinct_prefixes(self, tmp_path: Path) -> None:
+ # Each route uses its own router's prefix, not the first one in the file.
+ self._write_file(tmp_path, "routers/multi.py", """
+ repos_router = APIRouter(prefix="/repos")
+ users_router = APIRouter(prefix="/users")
+
+ @repos_router.get("/{repo_id}")
+ async def repo(repo_id: str): ...
+
+ @users_router.get("/me")
+ async def me(): ...
+ """)
+ ids = {c.contract_id for c in HttpExtractor().extract(tmp_path, "backend") if c.role == "provider"}
+ assert "http::GET::/repos/{param}" in ids
+ assert "http::GET::/users/me" in ids
+
+ def test_fastapi_dependency_paren_in_args(self, tmp_path: Path) -> None:
+ # A nested call in the constructor args must not truncate the prefix scan.
+ self._write_file(tmp_path, "routers/secure.py", """
+ router = APIRouter(prefix="/admin", dependencies=[Depends(require_admin)])
+
+ @router.get("/stats")
+ async def stats(): ...
+ """)
+ ids = {c.contract_id for c in HttpExtractor().extract(tmp_path, "backend") if c.role == "provider"}
+ assert "http::GET::/admin/stats" in ids
+
+ def test_fastapi_unknown_decorator_not_a_route(self, tmp_path: Path) -> None:
+ # @cache.get(...) on a non-router object must not become a contract.
+ self._write_file(tmp_path, "service.py", """
+ @cache.get("/some-key")
+ def cached(): ...
+ """)
+ providers = [c for c in HttpExtractor().extract(tmp_path, "api") if c.role == "provider"]
+ assert providers == []
+
+ def test_fastapi_cross_file_include_router_prefix(self, tmp_path: Path) -> None:
+ # include_router(items_router, prefix="/api") in main.py mounts a router
+ # defined in another file under that prefix.
+ self._write_file(tmp_path, "app/main.py", """
+ from .items import items_router
+ app = FastAPI()
+ app.include_router(items_router, prefix="/api")
+ """)
+ self._write_file(tmp_path, "app/items.py", """
+ items_router = APIRouter(prefix="/items")
+
+ @items_router.get("/{item_id}")
+ async def get_item(item_id: int): ...
+ """)
+ ids = {c.contract_id for c in HttpExtractor().extract(tmp_path, "backend") if c.role == "provider"}
+ assert "http::GET::/api/items/{param}" in ids
+
+ def test_express_cross_file_app_use_prefix(self, tmp_path: Path) -> None:
+ # app.use('/api/users', userRouter) mounts a uniquely-named router.
+ self._write_file(tmp_path, "src/app.js", """
+ const userRouter = require('./users');
+ app.use('/api/users', userRouter);
+ """)
+ self._write_file(tmp_path, "src/users.js", """
+ const userRouter = express.Router();
+ userRouter.get('/:id', handler);
+ """)
+ ids = {c.contract_id for c in HttpExtractor().extract(tmp_path, "backend") if c.role == "provider"}
+ assert "http::GET::/api/users/{param}" in ids
+
+ def test_go_route_group_nested(self, tmp_path: Path) -> None:
+ # Nested groups compose: v1 := api.Group("/v1") under api := r.Group("/api").
+ self._write_file(tmp_path, "main.go", """
+ r := gin.Default()
+ api := r.Group("/api")
+ v1 := api.Group("/v1")
+ v1.GET("/users", listUsers)
+ """)
+ ids = {c.contract_id for c in HttpExtractor().extract(tmp_path, "svc") if c.role == "provider"}
+ assert "http::GET::/api/v1/users" in ids
+
def test_fetch_consumer(self, tmp_path: Path) -> None:
self._write_file(tmp_path, "src/api.ts", """
const users = await fetch('/api/users');