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.

fix(workspace): link HTTP contracts across base paths and mount prefixes (#428) (#437)

Raghav Chamadiya63f7c6905042
diff --git a/packages/core/src/repowise/core/workspace/contracts.py b/packages/core/src/repowise/core/workspace/contracts.py
index a1a1dd754..e756f4cad 100644
--- a/packages/core/src/repowise/core/workspace/contracts.py
+++ b/packages/core/src/repowise/core/workspace/contracts.py
@@ -12,6 +12,7 @@ from __future__ import annotations
import asyncio
import json
import logging
+import re
from collections import defaultdict
from dataclasses import asdict, dataclass, field
from datetime import datetime, timezone
@@ -81,7 +82,7 @@ class ContractLink:
contract_id: str
contract_type: str # "http" | "grpc" | "topic"
- match_type: str # always "exact" in Phase 4
+ match_type: str # "exact" | "candidate" | "manual"
confidence: float
provider_repo: str
provider_file: str
@@ -192,6 +193,32 @@ def normalize_contract_id(contract_id: str) -> str:
# Matching engine
# ---------------------------------------------------------------------------
+# Common API mount / version path prefixes. When exact matching fails, the
+# candidate pass strips these leading segments (plus unresolved base ``{param}``
+# segments) from both provider and consumer paths so a consumer that hits
+# ``/api/v1/users`` can still link to a provider mounted at ``/users`` (or vice
+# versa). Such links are emitted as lower-confidence ``candidate`` matches.
+#
+# Kept deliberately small: only segments that are almost never real resource
+# names. Words like ``internal``/``public``/``gateway`` are excluded because
+# they double as legitimate route segments and would conflate unrelated routes.
+_MOUNT_PREFIX_SEGMENTS = frozenset({"api", "rest"})
+_VERSION_SEGMENT_RE = re.compile(r"^v\d+$")
+
+# Confidence multiplier applied to candidate (non-exact) links.
+_CANDIDATE_CONFIDENCE_FACTOR = 0.6
+
+# Request paths ending in these suffixes are static assets, never API contracts.
+# They are excluded from the candidate pass so a ``fetch('/static/app.js')``
+# can't spuriously link to a provider route that shares a suffix. ``.json`` and
+# ``.xml`` are intentionally absent — real APIs serve those.
+_STATIC_ASSET_SUFFIXES = (
+ ".js", ".mjs", ".cjs", ".css", ".map", ".html", ".htm",
+ ".png", ".jpg", ".jpeg", ".gif", ".svg", ".ico", ".webp", ".avif",
+ ".woff", ".woff2", ".ttf", ".eot", ".otf",
+ ".pdf", ".txt", ".wasm",
+)
+
def _find_matching_keys(
consumer_id: str,
@@ -227,12 +254,119 @@ def _find_matching_keys(
return []
+def _split_http_id(normalized_id: str) -> tuple[str, str] | None:
+ """Return ``(method, path)`` for a normalized ``http::`` id, else ``None``."""
+ parts = normalized_id.split("::", 2)
+ if len(parts) != 3 or parts[0] != "http":
+ return None
+ return parts[1], parts[2]
+
+
+def _candidate_http_path(path: str) -> str:
+ """Reduce an HTTP path to its mount-agnostic core for candidate matching.
+
+ Strips leading unresolved base ``{param}`` segments and known mount/version
+ prefixes so routes that differ only by an API mount or version prefix
+ collapse to the same key:
+
+ - ``/api/v1/users`` → ``/users``
+ - ``/{param}/resource`` → ``/resource``
+ - ``/v1/resource`` → ``/resource``
+ """
+ segments = [s for s in path.split("/") if s]
+ while segments and (
+ segments[0] == "{param}"
+ or segments[0] in _MOUNT_PREFIX_SEGMENTS
+ or _VERSION_SEGMENT_RE.match(segments[0])
+ ):
+ segments.pop(0)
+ return "/" + "/".join(segments)
+
+
+def _is_static_asset_path(path: str) -> bool:
+ """True when *path*'s final segment looks like a static asset file."""
+ last = path.rsplit("/", 1)[-1].split("?")[0].lower()
+ return last.endswith(_STATIC_ASSET_SUFFIXES)
+
+
+def _methods_compatible(consumer_method: str, provider_method: str) -> bool:
+ """HTTP methods match if equal or either side is the ``*`` wildcard."""
+ return (
+ consumer_method == provider_method
+ or consumer_method == "*"
+ or provider_method == "*"
+ )
+
+
+def _same_repo_same_service(provider: Contract, consumer: Contract) -> bool:
+ """Skip internal calls: same repo and same service boundary (or both None)."""
+ return provider.repo == consumer.repo and provider.service == consumer.service
+
+
+def _make_link(
+ consumer: Contract,
+ provider: Contract,
+ match_type: str,
+ confidence: float,
+ seen: set[tuple[str, str, str, str, str]],
+) -> ContractLink | None:
+ """Build a deduplicated ContractLink, or ``None`` if already emitted."""
+ dedup_key = (
+ normalize_contract_id(consumer.contract_id),
+ consumer.repo,
+ consumer.file_path,
+ provider.repo,
+ provider.file_path,
+ )
+ if dedup_key in seen:
+ return None
+ seen.add(dedup_key)
+
+ return ContractLink(
+ contract_id=consumer.contract_id,
+ contract_type=consumer.contract_type,
+ match_type=match_type,
+ confidence=confidence,
+ provider_repo=provider.repo,
+ provider_file=provider.file_path,
+ provider_symbol=provider.symbol_name,
+ provider_service=provider.service,
+ consumer_repo=consumer.repo,
+ consumer_file=consumer.file_path,
+ consumer_symbol=consumer.symbol_name,
+ consumer_service=consumer.service,
+ )
+
+
+def _build_candidate_index(
+ provider_index: dict[str, list[Contract]],
+) -> dict[str, list[Contract]]:
+ """Index HTTP providers by their mount-agnostic candidate path."""
+ candidate_index: dict[str, list[Contract]] = defaultdict(list)
+ for key, providers in provider_index.items():
+ split = _split_http_id(key)
+ if split is None:
+ continue
+ core = _candidate_http_path(split[1])
+ if core in ("", "/"):
+ continue # nothing concrete left to match on
+ candidate_index[core].extend(providers)
+ return candidate_index
+
+
def match_contracts(contracts: list[Contract]) -> list[ContractLink]:
- """Match providers to consumers using exact normalized ID comparison.
+ """Match providers to consumers across repos.
+
+ Two passes:
+
+ 1. **Exact** — normalized contract IDs must be equal, with HTTP/gRPC
+ wildcard handling (``http::*::/path``, ``grpc::Service/*``).
+ 2. **Candidate** — for HTTP consumers left unmatched (including those whose
+ URL had an unresolved base prefix stripped during extraction), retry
+ after collapsing known mount/version/base prefixes on both sides. These
+ links are tagged ``match_type="candidate"`` with reduced confidence.
- - HTTP wildcard: ``http::*::/path`` matches any method on that path.
- - gRPC wildcard: ``grpc::Service/*`` matches any method on that service.
- - Same-repo same-service calls are filtered out.
+ Same-repo same-service calls are filtered out of both passes.
"""
provider_index: dict[str, list[Contract]] = defaultdict(list)
consumers: list[Contract] = []
@@ -246,44 +380,60 @@ def match_contracts(contracts: list[Contract]) -> list[ContractLink]:
links: list[ContractLink] = []
seen: set[tuple[str, str, str, str, str]] = set()
+ matched_consumers: set[int] = set()
+ # --- Pass 1: exact / wildcard ---
for consumer in consumers:
- matching_keys = _find_matching_keys(consumer.contract_id, provider_index)
+ # Consumers with an unresolved base prefix can't be matched exactly —
+ # defer them entirely to the candidate pass.
+ if consumer.meta.get("base_stripped"):
+ continue
+ matching_keys = _find_matching_keys(consumer.contract_id, provider_index)
for key in matching_keys:
for provider in provider_index[key]:
- # Same-repo same-service filter: skip internal calls
- if provider.repo == consumer.repo:
- if (
- provider.service == consumer.service # includes both-None case
- ):
- continue
-
- dedup_key = (
- normalize_contract_id(consumer.contract_id),
- consumer.repo,
- consumer.file_path,
- provider.repo,
- provider.file_path,
- )
- if dedup_key in seen:
+ if _same_repo_same_service(provider, consumer):
continue
- seen.add(dedup_key)
-
- links.append(ContractLink(
- contract_id=consumer.contract_id,
- contract_type=consumer.contract_type,
- match_type="exact",
- confidence=min(provider.confidence, consumer.confidence),
- provider_repo=provider.repo,
- provider_file=provider.file_path,
- provider_symbol=provider.symbol_name,
- provider_service=provider.service,
- consumer_repo=consumer.repo,
- consumer_file=consumer.file_path,
- consumer_symbol=consumer.symbol_name,
- consumer_service=consumer.service,
- ))
+ link = _make_link(
+ consumer,
+ provider,
+ "exact",
+ min(provider.confidence, consumer.confidence),
+ seen,
+ )
+ if link is not None:
+ links.append(link)
+ matched_consumers.add(id(consumer))
+
+ # --- Pass 2: candidate (mount/version/base prefix) for unmatched HTTP ---
+ candidate_index = _build_candidate_index(provider_index)
+ for consumer in consumers:
+ if id(consumer) in matched_consumers:
+ continue
+
+ split = _split_http_id(normalize_contract_id(consumer.contract_id))
+ if split is None:
+ continue # candidate matching is HTTP-only
+ method, path = split
+ if _is_static_asset_path(path):
+ continue
+ core = _candidate_http_path(path)
+ if core in ("", "/"):
+ continue
+
+ for provider in candidate_index.get(core, []):
+ if _same_repo_same_service(provider, consumer):
+ continue
+ psplit = _split_http_id(normalize_contract_id(provider.contract_id))
+ if psplit is None or not _methods_compatible(method, psplit[0]):
+ continue
+ confidence = round(
+ min(provider.confidence, consumer.confidence) * _CANDIDATE_CONFIDENCE_FACTOR,
+ 3,
+ )
+ link = _make_link(consumer, provider, "candidate", confidence, seen)
+ if link is not None:
+ links.append(link)
return links
diff --git a/packages/core/src/repowise/core/workspace/extractors/http_extractor.py b/packages/core/src/repowise/core/workspace/extractors/http_extractor.py
index 4f34552f3..f309a775b 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http_extractor.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http_extractor.py
@@ -225,6 +225,44 @@ def _extract_path_from_url(url: str) -> str:
return url
+# A leading base/host placeholder in a consumer URL, e.g. ``${API_BASE}/users``
+# or ``${apiUrl}/v1/users``. The value is unresolved at extraction time, so the
+# only thing we can match on is the concrete suffix. Anchored at the start so
+# interior expressions (real path params like ``/users/${id}``) are untouched.
+_LEADING_BASE_EXPR_RE = re.compile(r"^\s*\$\{[^}]+\}")
+
+
+def _strip_leading_base_expr(path: str) -> tuple[str, bool]:
+ """Strip a leading base/host placeholder from a consumer URL path.
+
+ Returns ``(path, stripped)``. ``${API_BASE}/users`` becomes ``/users`` with
+ ``stripped=True``. Treating the placeholder as an ordinary ``{param}`` path
+ segment (which is what :func:`normalize_http_path` would otherwise do)
+ prevents the route from ever lining up with a concrete provider path, so we
+ drop it and let the matcher link on the suffix as a lower-confidence
+ candidate instead.
+ """
+ new_path = _LEADING_BASE_EXPR_RE.sub("", path, count=1)
+ if new_path == path:
+ return path, False
+ if not new_path.startswith("/"):
+ new_path = "/" + new_path
+ return new_path, True
+
+
+def _consumer_meta(method: str, norm_path: str, client: str, base_stripped: bool) -> dict:
+ """Build a consumer contract's ``meta`` dict.
+
+ ``base_stripped`` is recorded only when True so the matcher knows the path
+ had an unresolved base prefix removed and should be linked as a candidate
+ rather than an exact match.
+ """
+ meta = {"method": method, "path": norm_path, "client": client}
+ if base_stripped:
+ meta["base_stripped"] = True
+ return meta
+
+
class HttpExtractor:
"""Extract HTTP route contracts from source files."""
@@ -381,6 +419,7 @@ class HttpExtractor:
url = match.group(1)
method = match.group(2).upper()
path = _extract_path_from_url(url)
+ path, base_stripped = _strip_leading_base_expr(path)
norm_path = normalize_http_path(path)
contract_id = f"http::{method}::{norm_path}"
contracts.append(
@@ -393,7 +432,7 @@ class HttpExtractor:
symbol_name=f"fetch:{method} {url}",
confidence=0.75,
service=None,
- meta={"method": method, "path": norm_path, "client": "fetch"},
+ meta=_consumer_meta(method, norm_path, "fetch", base_stripped),
)
)
@@ -404,6 +443,7 @@ class HttpExtractor:
if url in fetch_method_urls:
continue
path = _extract_path_from_url(url)
+ path, base_stripped = _strip_leading_base_expr(path)
norm_path = normalize_http_path(path)
contract_id = f"http::GET::{norm_path}"
contracts.append(
@@ -416,7 +456,7 @@ class HttpExtractor:
symbol_name=f"fetch:GET {url}",
confidence=0.75,
service=None,
- meta={"method": "GET", "path": norm_path, "client": "fetch"},
+ meta=_consumer_meta("GET", norm_path, "fetch", base_stripped),
)
)
@@ -425,6 +465,7 @@ class HttpExtractor:
method = match.group(1).upper()
url = match.group(2)
path = _extract_path_from_url(url)
+ path, base_stripped = _strip_leading_base_expr(path)
norm_path = normalize_http_path(path)
contract_id = f"http::{method}::{norm_path}"
contracts.append(
@@ -437,7 +478,7 @@ class HttpExtractor:
symbol_name=f"axios:{method} {url}",
confidence=0.75,
service=None,
- meta={"method": method, "path": norm_path, "client": "axios"},
+ meta=_consumer_meta(method, norm_path, "axios", base_stripped),
)
)
@@ -450,6 +491,7 @@ class HttpExtractor:
if "/" not in url:
continue # Avoid matching non-URL strings.
path = _extract_path_from_url(url)
+ path, base_stripped = _strip_leading_base_expr(path)
norm_path = normalize_http_path(path)
contract_id = f"http::{method}::{norm_path}"
contracts.append(
@@ -462,11 +504,7 @@ class HttpExtractor:
symbol_name=f"httpclient:{method} {url}",
confidence=0.70,
service=None,
- meta={
- "method": method,
- "path": norm_path,
- "client": "httpclient",
- },
+ meta=_consumer_meta(method, norm_path, "httpclient", base_stripped),
)
)
@@ -475,6 +513,7 @@ class HttpExtractor:
method = match.group(1).upper()
url = match.group(2)
path = _extract_path_from_url(url)
+ path, base_stripped = _strip_leading_base_expr(path)
norm_path = normalize_http_path(path)
contract_id = f"http::{method}::{norm_path}"
contracts.append(
@@ -487,7 +526,7 @@ class HttpExtractor:
symbol_name=f"requests:{method} {url}",
confidence=0.75,
service=None,
- meta={"method": method, "path": norm_path, "client": "requests"},
+ meta=_consumer_meta(method, norm_path, "requests", base_stripped),
)
)
diff --git a/tests/unit/workspace/test_contracts.py b/tests/unit/workspace/test_contracts.py
index 45e5e1fde..e2e2359d2 100644
--- a/tests/unit/workspace/test_contracts.py
+++ b/tests/unit/workspace/test_contracts.py
@@ -190,6 +190,28 @@ class TestHttpExtractor:
assert len(consumers) == 1
assert consumers[0].contract_id == "http::POST::/api/data"
+ def test_fetch_consumer_strips_leading_base_expr(self, tmp_path: Path) -> None:
+ self._write_file(tmp_path, "src/api.ts", """
+ const users = await fetch(`${API_BASE}/api/users`);
+ """)
+ contracts = HttpExtractor().extract(tmp_path, "frontend")
+ consumers = [c for c in contracts if c.role == "consumer"]
+ assert len(consumers) == 1
+ # The unresolved base placeholder is stripped, not turned into {param}.
+ assert consumers[0].contract_id == "http::GET::/api/users"
+ assert consumers[0].meta.get("base_stripped") is True
+
+ def test_fetch_consumer_keeps_interior_param(self, tmp_path: Path) -> None:
+ self._write_file(tmp_path, "src/api.ts", """
+ const u = await fetch(`/users/${id}`);
+ """)
+ contracts = HttpExtractor().extract(tmp_path, "frontend")
+ consumers = [c for c in contracts if c.role == "consumer"]
+ assert len(consumers) == 1
+ # Interior expressions are genuine path params and must remain.
+ assert consumers[0].contract_id == "http::GET::/users/{param}"
+ assert "base_stripped" not in consumers[0].meta
+
def test_empty_file(self, tmp_path: Path) -> None:
self._write_file(tmp_path, "empty.py", "")
contracts = HttpExtractor().extract(tmp_path, "svc")
@@ -592,6 +614,131 @@ class TestMatchContracts:
assert len(links) == 2
+# ---------------------------------------------------------------------------
+# Candidate matching (mount / version / base-prefix tolerant)
+# ---------------------------------------------------------------------------
+
+
+class TestCandidateMatching:
+ def _c(self, **kwargs) -> Contract:
+ defaults = {
+ "repo": "a",
+ "contract_id": "http::GET::/api",
+ "contract_type": "http",
+ "role": "provider",
+ "file_path": "f.py",
+ "symbol_name": "handler",
+ "confidence": 0.85,
+ "service": None,
+ "meta": {},
+ }
+ defaults.update(kwargs)
+ return Contract(**defaults)
+
+ def test_mount_prefix_creates_candidate_link(self) -> None:
+ # Consumer hits /api/resource/search; provider mounts /resource/search.
+ contracts = [
+ self._c(repo="backend", role="provider", contract_id="http::GET::/resource/search"),
+ self._c(repo="frontend", role="consumer", contract_id="http::GET::/api/resource/search",
+ file_path="c.ts", confidence=0.75),
+ ]
+ links = match_contracts(contracts)
+ assert len(links) == 1
+ assert links[0].match_type == "candidate"
+ # Candidate confidence is strictly lower than an exact min() would give.
+ assert links[0].confidence < 0.75
+
+ def test_version_prefix_with_base_param(self) -> None:
+ # Provider /v1/resource; consumer base resolved to a leading {param}.
+ contracts = [
+ self._c(repo="backend", role="provider", contract_id="http::POST::/v1/resource"),
+ self._c(repo="frontend", role="consumer", contract_id="http::POST::/{param}/resource",
+ file_path="c.ts"),
+ ]
+ links = match_contracts(contracts)
+ assert len(links) == 1
+ assert links[0].match_type == "candidate"
+
+ def test_base_stripped_consumer_is_candidate_not_exact(self) -> None:
+ # Even when the suffix matches exactly, a stripped base means we can't
+ # be certain of the mount point — so it is a candidate, not exact.
+ contracts = [
+ self._c(repo="backend", role="provider", contract_id="http::GET::/resource"),
+ self._c(repo="frontend", role="consumer", contract_id="http::GET::/resource",
+ file_path="c.ts", meta={"base_stripped": True}),
+ ]
+ links = match_contracts(contracts)
+ assert len(links) == 1
+ assert links[0].match_type == "candidate"
+
+ def test_exact_match_takes_precedence_over_candidate(self) -> None:
+ contracts = [
+ self._c(repo="backend", role="provider", contract_id="http::GET::/api/users"),
+ self._c(repo="frontend", role="consumer", contract_id="http::GET::/api/users", file_path="c.ts"),
+ ]
+ links = match_contracts(contracts)
+ assert len(links) == 1
+ assert links[0].match_type == "exact"
+
+ def test_static_asset_excluded_from_candidate(self) -> None:
+ # /api/app.js reduces to the same core as /app.js, but static assets
+ # must never produce contract links.
+ contracts = [
+ self._c(repo="backend", role="provider", contract_id="http::GET::/app.js"),
+ self._c(repo="frontend", role="consumer", contract_id="http::GET::/api/app.js", file_path="c.ts"),
+ ]
+ links = match_contracts(contracts)
+ assert links == []
+
+ def test_method_mismatch_no_candidate(self) -> None:
+ contracts = [
+ self._c(repo="backend", role="provider", contract_id="http::POST::/v1/resource"),
+ self._c(repo="frontend", role="consumer", contract_id="http::GET::/resource",
+ file_path="c.ts", meta={"base_stripped": True}),
+ ]
+ links = match_contracts(contracts)
+ assert links == []
+
+ def test_wildcard_provider_method_candidate(self) -> None:
+ # Go HandleFunc providers carry method "*" — compatible with any method.
+ contracts = [
+ self._c(repo="backend", role="provider", contract_id="http::*::/v1/orders"),
+ self._c(repo="frontend", role="consumer", contract_id="http::GET::/api/orders", file_path="c.ts"),
+ ]
+ links = match_contracts(contracts)
+ assert len(links) == 1
+ assert links[0].match_type == "candidate"
+
+ def test_does_not_overcollapse_to_root(self) -> None:
+ # Both sides reduce to "/" once prefixes are stripped — too generic to
+ # link safely.
+ contracts = [
+ self._c(repo="backend", role="provider", contract_id="http::GET::/api/v1"),
+ self._c(repo="frontend", role="consumer", contract_id="http::GET::/api", file_path="c.ts"),
+ ]
+ links = match_contracts(contracts)
+ assert links == []
+
+ def test_non_mount_segment_not_stripped(self) -> None:
+ # `internal` is a legitimate resource name, not a mount prefix — it must
+ # not be stripped, so /internal/users and /api/users stay distinct.
+ contracts = [
+ self._c(repo="backend", role="provider", contract_id="http::GET::/internal/users"),
+ self._c(repo="frontend", role="consumer", contract_id="http::GET::/api/users", file_path="c.ts"),
+ ]
+ links = match_contracts(contracts)
+ assert links == []
+
+ def test_same_repo_same_service_filtered_in_candidate(self) -> None:
+ contracts = [
+ self._c(repo="mono", role="provider", contract_id="http::GET::/v1/resource", service="svc-a"),
+ self._c(repo="mono", role="consumer", contract_id="http::GET::/api/resource",
+ file_path="c.py", service="svc-a"),
+ ]
+ links = match_contracts(contracts)
+ assert links == []
+
+
# ---------------------------------------------------------------------------
# ContractStore persistence
# ---------------------------------------------------------------------------