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
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.pyindex 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 annotationsimport asyncioimport jsonimport logging+import refrom collections import defaultdictfrom dataclasses import asdict, dataclass, fieldfrom datetime import datetime, timezone@@ -81,7 +82,7 @@ class ContractLink:contract_id: strcontract_type: str # "http" | "grpc" | "topic"- match_type: str # always "exact" in Phase 4+ match_type: str # "exact" | "candidate" | "manual"confidence: floatprovider_repo: strprovider_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 linksdiff --git a/packages/core/src/repowise/core/workspace/extractors/http_extractor.py b/packages/core/src/repowise/core/workspace/extractors/http_extractor.pyindex 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:continuepath = _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.pyindex 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) == 1assert 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# ---------------------------------------------------------------------------