Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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 annotationsimport os-from collections.abc import Iterator-from dataclasses import dataclass+from collections.abc import Iterator, Mapping+from dataclasses import dataclass, fieldfrom pathlib import Path@@ -23,13 +23,16 @@ class ScanContext:``rel_path`` is POSIX-relative to the repo root; ``suffix`` is thelower-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: strrel_path: strsuffix: strcontent: 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__.pyindex 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 FastApiDialectfrom .go import GoDialectfrom .js_clients import JsClientsDialectfrom .laravel import LaravelDialect+from .mounts import merge_mount_mapsfrom .paths import normalize_http_pathfrom .python_clients import PythonClientsDialectfrom .rust_axum import RustAxumDialect@@ -66,14 +67,22 @@ class HttpExtractor:consumer_dialects: tuple[HttpDialect, ...] = CONSUMER_DIALECTSdef 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.pyindex 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_CHECKINGfrom ..langs import JS_TSfrom .dialect import METHODS, build_provider_contract+from .mounts import compose_prefixif TYPE_CHECKING:from repowise.core.workspace.contracts import Contractfrom ..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.pyindex 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_CHECKINGfrom ..langs import PYTHONfrom .dialect import METHODS, build_provider_contract+from .mounts import balanced_args, compose_prefix, router_prefixesif TYPE_CHECKING:from repowise.core.workspace.contracts import Contractfrom ..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.pyindex 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", ...)`` andstdlib ``.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_CHECKINGfrom ..langs import GOfrom .dialect import METHODS_UPPER, build_provider_contract+from .mounts import compose_prefixif TYPE_CHECKING:from repowise.core.workspace.contracts import Contractfrom ..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 = GOdef 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 outdiff --git a/packages/core/src/repowise/core/workspace/extractors/http/mounts.py b/packages/core/src/repowise/core/workspace/extractors/http/mounts.pynew file mode 100644index 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.pyindex 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) == 1assert 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');