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): read a contract's request schema off its handler signature (#1839)
Raghav Chamadiyaf56d354f7615
diff --git a/packages/core/src/repowise/core/workspace/breaking_change.py b/packages/core/src/repowise/core/workspace/breaking_change.pyindex 224b25b8c..52b4b7c61 100644--- a/packages/core/src/repowise/core/workspace/breaking_change.py+++ b/packages/core/src/repowise/core/workspace/breaking_change.py@@ -545,7 +545,14 @@ def detect_breaking_changes(if prev_c is not None and curr_c is not None:prev_schema = prev_c.schemacurr_schema = curr_c.schema- if prev_schema is not None and curr_schema is not None:+ # Same source only. A parameter list and a .proto message describe+ # the same endpoint at different fidelities, so diffing one against+ # the other reports the change of parser as a change of contract.+ if (+ prev_schema is not None+ and curr_schema is not None+ and prev_schema.source == curr_schema.source+ ):raws.extend(_diff_schemas(prev_schema, curr_schema))if not raws:diff --git a/packages/core/src/repowise/core/workspace/contracts.py b/packages/core/src/repowise/core/workspace/contracts.pyindex 289209296..e649176e1 100644--- a/packages/core/src/repowise/core/workspace/contracts.py+++ b/packages/core/src/repowise/core/workspace/contracts.py@@ -27,6 +27,7 @@ from repowise.core.workspace.config import (ensure_workspace_data_dir,)from repowise.core.workspace.contract_schema import ContractSchema+from repowise.core.workspace.signature_schema import attach_signature_schemasif TYPE_CHECKING:from repowise.core.workspace.extractors.service_boundary import ServiceBoundary@@ -40,10 +41,11 @@ _log = logging.getLogger("repowise.workspace.contracts")CONTRACTS_FILENAME = "contracts.json"-#: Artifact schema version. Bumped to 2 when contracts gained ``symbol_id``.+#: Artifact schema version. Bumped to 2 when contracts gained ``symbol_id``,+#: to 3 when providers gained a signature-derived ``schema``.#: A store written under an older version is readable but not reusable: its#: rows carry no identity, and nothing short of re-extraction can give them one.-CONTRACTS_VERSION = 2+CONTRACTS_VERSION = 3# ---------------------------------------------------------------------------@@ -1019,6 +1021,7 @@ async def run_contract_extraction(contracts.extend(found)stats.update(bind_symbol_ids(contracts, repo_index))+ stats.update(attach_signature_schemas(contracts, repo_index))unresolved = stats.get("http_consumer_unresolved", 0)if unresolved:diff --git a/packages/core/src/repowise/core/workspace/diagnostics.py b/packages/core/src/repowise/core/workspace/diagnostics.pyindex 566c94a94..d6a77e31f 100644--- a/packages/core/src/repowise/core/workspace/diagnostics.py+++ b/packages/core/src/repowise/core/workspace/diagnostics.py@@ -27,6 +27,7 @@ from repowise.core.workspace.contracts import (normalize_contract_id,)from repowise.core.workspace.extractors.from_index import EXTRACTION_LAYER_KEY, LAYER_REGEX+from repowise.core.workspace.signature_schema import SCHEMA_SOURCE# ---------------------------------------------------------------------------# Constants (single source of truth)@@ -137,6 +138,47 @@ class SymbolIdentity:}+@dataclass+class SchemaCoverage:+ """How many providers recovered a request schema, and out of what.++ Two denominators, for the same reason :class:`SymbolIdentity` carries two.+ *total* is the workspace-wide share. *recovered_ratio_eligible* excludes the+ providers no mapper could reach whatever it did — one bound to nothing, to a+ route-registration site, to a symbol with no parameter list, or to a language+ with no parameter grammar — and is what says whether the mapper is working.+ """++ total: int = 0+ bound: int = 0+ recovered: int = 0+ shared_symbol: int = 0+ unsupported_language: int = 0+ non_callable: int = 0++ @property+ def eligible(self) -> int:+ return (+ self.bound - self.shared_symbol - self.unsupported_language - self.non_callable+ )++ def _ratio(self, denominator: int) -> float | None:+ return self.recovered / denominator if denominator > 0 else None++ def to_dict(self) -> dict[str, Any]:+ return {+ "total": self.total,+ "bound": self.bound,+ "recovered": self.recovered,+ "shared_symbol": self.shared_symbol,+ "unsupported_language": self.unsupported_language,+ "non_callable": self.non_callable,+ "eligible": self.eligible,+ "recovered_ratio": self._ratio(self.total),+ "recovered_ratio_eligible": self._ratio(self.eligible),+ }++@dataclassclass ExtractionDiagnostics:"""Aggregate explanation of contract extraction + matching coverage."""@@ -158,6 +200,9 @@ class ExtractionDiagnostics:#: Symbol-id binding coverage, keyed by role. Reported, never asserted: a#: contract with no symbol id still matches, it just cannot be traversed.symbol_identity: dict[str, SymbolIdentity] = field(default_factory=dict)+ #: Request-schema recovery over providers. Reported, never asserted: a+ #: provider without a schema keeps matching, it just cannot be field-diffed.+ schema_coverage: SchemaCoverage = field(default_factory=SchemaCoverage)@propertydef http_consumer_coverage(self) -> float | None:@@ -190,10 +235,12 @@ class ExtractionDiagnostics:"http_consumers_unresolved": self.http_consumers_unresolved,"http_consumer_coverage": self.http_consumer_coverage,"symbol_identity": {r: v.to_dict() for r, v in sorted(self.symbol_identity.items())},+ "schema_coverage": self.schema_coverage.to_dict(),}@classmethoddef from_dict(cls, data: dict[str, Any]) -> ExtractionDiagnostics:+ schema = data.get("schema_coverage") or {}return cls(total_providers=data.get("total_providers", 0),total_consumers=data.get("total_consumers", 0),@@ -243,6 +290,14 @@ class ExtractionDiagnostics:)for role, v in (data.get("symbol_identity") or {}).items()},+ schema_coverage=SchemaCoverage(+ total=schema.get("total", 0),+ bound=schema.get("bound", 0),+ recovered=schema.get("recovered", 0),+ shared_symbol=schema.get("shared_symbol", 0),+ unsupported_language=schema.get("unsupported_language", 0),+ non_callable=schema.get("non_callable", 0),+ ),)@@ -389,6 +444,23 @@ def build_diagnostics(for role, rows in (("provider", providers), ("consumer", consumers))}+ schema = SchemaCoverage(+ total=len(providers),+ bound=sum(1 for c in providers if c.symbol_id is not None),+ recovered=sum(+ 1 for c in providers if c.schema is not None and c.schema.source == SCHEMA_SOURCE+ ),+ shared_symbol=sum(+ s.get("schema_shared_symbol_provider", 0) for s in stats_by_repo.values()+ ),+ unsupported_language=sum(+ s.get("schema_unsupported_lang_provider", 0) for s in stats_by_repo.values()+ ),+ non_callable=sum(+ s.get("schema_non_callable_provider", 0) for s in stats_by_repo.values()+ ),+ )+return ExtractionDiagnostics(total_providers=len(providers),total_consumers=len(consumers),@@ -407,4 +479,5 @@ def build_diagnostics(s.get("http_consumer_unresolved", 0) for s in stats_by_repo.values()),symbol_identity=identity,+ schema_coverage=schema,)diff --git a/packages/core/src/repowise/core/workspace/repo_index.py b/packages/core/src/repowise/core/workspace/repo_index.pyindex cf7faf778..1897f36a0 100644--- a/packages/core/src/repowise/core/workspace/repo_index.py+++ b/packages/core/src/repowise/core/workspace/repo_index.py@@ -55,6 +55,9 @@ class IndexedSymbol:start_line: int # 1-indexed, inclusiveend_line: int # 1-indexed, inclusivevisibility: str+ #: ingestion's language key. Defaults so a caller building one by hand+ #: (the tests, and from_index) need not know about it.+ language: str = ""@dataclass(frozen=True)@@ -100,10 +103,26 @@ class RepoIndex:WikiSymbol.start_line,WikiSymbol.end_line,WikiSymbol.visibility,+ WikiSymbol.language,).where(WikiSymbol.repository_id == repo_id))for row in rows:- self._by_file.setdefault(row.file_path, []).append(IndexedSymbol(*row))+ # By keyword: eight of the ten fields are strings, so a reordered+ # or inserted column would swap values positionally without error.+ self._by_file.setdefault(row.file_path, []).append(+ IndexedSymbol(+ symbol_id=row.symbol_id,+ name=row.name,+ qualified_name=row.qualified_name,+ kind=row.kind,+ signature=row.signature,+ file_path=row.file_path,+ start_line=row.start_line,+ end_line=row.end_line,+ visibility=row.visibility,+ language=row.language or "",+ )+ )# Outermost first, so the first span containing a line is the class and# the last is the method.for symbols in self._by_file.values():diff --git a/packages/core/src/repowise/core/workspace/signature_schema.py b/packages/core/src/repowise/core/workspace/signature_schema.pynew file mode 100644index 000000000..4a9cda432--- /dev/null+++ b/packages/core/src/repowise/core/workspace/signature_schema.py@@ -0,0 +1,404 @@+"""Recover a provider's request schema from its handler's parsed signature.++A provider contract knows the symbol it was declared on+(:func:`..contracts.bind_symbol_ids`), and that handler's parameter list *is*+the request shape. Mapping one stored ``wiki_symbols.signature`` onto a+:class:`~.contract_schema.ContractSchema` is what lets the field-level+breaking-change rules — until now reachable only from ``.proto`` — apply to+every contract type that binds to a callable.++The one axis this reads is the symbol's **language**, never the framework that+declared the route: parameter order and comment syntax are language properties,+so a dialect that never heard of this module gains a schema simply by binding.+Languages absent from :data:`_GRAMMARS` yield no schema and are counted, not+guessed at.++Consumers are deliberately excluded. A consumer binds to the function that+*makes* the call, whose parameters have nothing to do with the request it sends.+"""++from __future__ import annotations++import re+from dataclasses import dataclass+from typing import TYPE_CHECKING++from repowise.core.workspace.contract_schema import ContractSchema, SchemaField++if TYPE_CHECKING:+ from repowise.core.workspace.contracts import Contract+ from repowise.core.workspace.repo_index import RepoIndex++#: ``ContractSchema.source`` for everything this module produces, so a diff+#: never compares a signature-derived shape against a ``.proto`` one.+SCHEMA_SOURCE = "signature"++#: Symbol kinds that have a parameter list at all.+_CALLABLE_KINDS = frozenset({"function", "method"})++#: Receivers the language inserts, not part of any caller-visible surface.+_RECEIVERS = frozenset({"self", "cls", "this"})++#: Types every web framework injects: the ambient request/response/context+#: object, not a field a caller supplies. Matched **exactly** on the bare type+#: name, never as a suffix — 74 of this workspace's provider parameters are a+#: request body typed `SomethingRequest`, and a suffix match would eat them all.+#: Shared vocabulary rather than framework knowledge: no entry names a+#: framework, and a framework absent from the list simply keeps its parameter.+_AMBIENT_TYPES = frozenset(+ {+ "Request",+ "Response",+ "HttpRequest",+ "HttpResponse",+ "HttpContext",+ "WebSocket",+ "BackgroundTasks",+ "CancellationToken",+ }+)++#: Parameters that widen the surface instead of naming a field — variadics and+#: rest/spread. Dropped, where an unparseable *name* refuses the whole schema.+_VARIADIC_PREFIXES = ("*", "...")++#: Bare separators in a Python parameter list: keyword-only and positional-only.+_SEPARATORS = frozenset({"*", "/"})++_IDENTIFIER = re.compile(r"^[A-Za-z_$][A-Za-z0-9_$]*$")++#: A default of ``...``/``Ellipsis``, bare or passed to a call (``Query(...)``,+#: ``Query(default=...)``, ``Field(...)``). Python's ecosystem-wide "no default"+#: placeholder — reading it as a real default is what would make a required+#: route parameter look optional. Not a framework check: it holds for any+#: library using the idiom, and the spelling of the argument does not matter.+_ELLIPSIS_DEFAULT = re.compile(r"^(?:\.\.\.|Ellipsis)$|^\w+\([^)]*(?:\.\.\.|Ellipsis)")++#: C#/Java-style attributes and annotations ahead of a parameter's type.+#: Repeated, because a parameter may carry several (``[FromQuery][Required]``).+_LEADING_ANNOTATIONS = re.compile(r"^(?:(?:\[[^\]]*\]|@\w+(?:\([^)]*\))?)\s*)+")++#: Parameter modifiers with no bearing on the field a caller supplies.+#: Per-grammar, never global: ``out``, ``params`` and ``ref`` are C# keywords+#: and ordinary Python parameter names, so one shared set eats real fields.+_CSHARP_MODIFIERS = frozenset({"ref", "out", "in", "params", "this"})+#: TypeScript constructor parameter properties: ``public readonly x: T``.+_TS_MODIFIERS = frozenset({"public", "private", "protected", "readonly"})+++@dataclass(frozen=True)+class _Grammar:+ """How one language spells a parameter list."""++ #: ``"colon"`` = ``name: Type``; ``"type_first"`` = ``Type name``.+ order: str+ comment: str+ #: ``(open, close)`` of a block comment, or ``None`` where there is none.+ #: Needed, not cosmetic: an apostrophe inside a ``/** */`` doc comment+ #: otherwise opens a string that swallows the rest of the parameter list.+ block_comment: tuple[str, str] | None+ #: Whether ``<...>`` nests. Off where the language has no generics and+ #: ``<`` can only be a comparison.+ generics: bool+ #: Whether a trailing ``?`` on a name marks the parameter optional.+ optional_marker: bool+ #: Declaration keywords to drop from the front of a parameter.+ modifiers: frozenset[str] = frozenset()+++_C_BLOCK = ("/*", "*/")++# Only languages whose parameter grammar was verified against the real parser+# output. Java is absent on purpose: its stored signature carries no parameter+# list at all (``"getReports -> List<String>"``), so there is nothing to read.+_GRAMMARS: dict[str, _Grammar] = {+ "python": _Grammar("colon", "#", None, generics=False, optional_marker=False),+ "typescript": _Grammar(+ "colon", "//", _C_BLOCK, generics=True, optional_marker=True, modifiers=_TS_MODIFIERS+ ),+ # JavaScript has no generics, so every `<` there is a comparison.+ "javascript": _Grammar(+ "colon", "//", _C_BLOCK, generics=False, optional_marker=True, modifiers=_TS_MODIFIERS+ ),+ "csharp": _Grammar(+ "type_first",+ "//",+ _C_BLOCK,+ generics=True,+ optional_marker=False,+ modifiers=_CSHARP_MODIFIERS,+ ),+}++#: Returned for a parameter that is real but carries no field (a separator, a+#: receiver, a variadic), as distinct from ``None``, which refuses the signature.+_SKIP = object()++#: Names a route template binds, e.g. ``/repos/{repo_id}``, ``/users/:id``.+_PATH_PARAM = re.compile(r"[{<:]([A-Za-z_][A-Za-z0-9_]*)")+++def _bare_type(type_text: str) -> str:+ """The type's own name: no union arm, no namespace, no nullability."""+ head = type_text.split("|")[0].strip()+ return head.rsplit(".", 1)[-1].rstrip("?").strip()++_BRACKETS = {"(": ")", "[": "]", "{": "}"}+++def _opens_generic(text: str, i: int) -> bool:+ """Whether the ``<`` at *i* opens a type argument list rather than compares.++ A generic always abuts its type name (``List<int>``); a comparison does not+ (``lo = a < b``). Without this the two ``<``/``>`` of a pair of comparisons+ balance, and every parameter between them is swallowed with no error.+ """+ return i > 0 and (text[i - 1].isalnum() or text[i - 1] == "_")+++def _split_parameters(signature: str, grammar: _Grammar) -> list[str] | None:+ """Split the top-level parameters of *signature*, or ``None`` if unreadable.++ String- and comment-aware because stored signatures keep both: a ``#`` line+ inside a multi-line parameter list, and commas inside a description string,+ are the two ways a naive split silently invents fields. An unbalanced list+ (a truncated signature) returns ``None`` rather than a shortened one.+ """+ start = signature.find("(")+ if start < 0:+ return None++ pairs = dict(_BRACKETS)+ closers: list[str] = []+ parts: list[str] = []+ buf: list[str] = []+ quote: str | None = None+ i = start + 1+ text = signature+ while i < len(text):+ ch = text[i]+ if quote is not None:+ buf.append(ch)+ if ch == "\\":+ if i + 1 < len(text):+ buf.append(text[i + 1])+ i += 2+ continue+ if ch == quote:+ quote = None+ i += 1+ continue+ if ch in "\"'":+ quote = ch+ buf.append(ch)+ i += 1+ continue+ if grammar.block_comment is not None and text.startswith(grammar.block_comment[0], i):+ end = text.find(grammar.block_comment[1], i)+ i = len(text) if end < 0 else end + len(grammar.block_comment[1])+ continue+ if text.startswith(grammar.comment, i):+ end = text.find("\n", i)+ i = len(text) if end < 0 else end+ continue+ if ch == ")" and not closers:+ parts.append("".join(buf))+ return [p.strip() for p in parts if p.strip()]+ if ch == "<" and grammar.generics and _opens_generic(text, i):+ closers.append(">")+ elif ch in pairs:+ closers.append(pairs[ch])+ elif closers and ch == closers[-1]:+ closers.pop()+ elif ch == "," and not closers:+ parts.append("".join(buf))+ buf = []+ i += 1+ continue+ buf.append(ch)+ i += 1+ return None+++def _strip_default(text: str, grammar: _Grammar) -> tuple[str, bool]:+ """Split a parameter on its top-level ``=``, returning ``(head, required)``.++ Bracket- and string-aware for the same reason the parameter split is: a+ default may itself be a call carrying ``=`` and commas.+ """+ pairs = _BRACKETS+ closers: list[str] = []+ quote: str | None = None+ for i, ch in enumerate(text):+ if quote is not None:+ if ch == quote:+ quote = None+ continue+ if ch in "\"'":+ quote = ch+ elif ch == "<" and grammar.generics and _opens_generic(text, i):+ closers.append(">")+ elif ch in pairs:+ closers.append(pairs[ch])+ elif closers and ch == closers[-1]:+ closers.pop()+ elif ch == "=" and not closers and not text.startswith("=>", i):+ default = text[i + 1 :].strip()+ required = bool(_ELLIPSIS_DEFAULT.match(default))+ return text[:i].strip(), required+ return text.strip(), True+++def _without_modifiers(text: str, grammar: _Grammar) -> list[str]:+ """Whitespace tokens of *text* with its language's leading modifiers gone."""+ tokens = text.split()+ while tokens and tokens[0] in grammar.modifiers:+ tokens.pop(0)+ return tokens+++def _parse_parameter(+ text: str, grammar: _Grammar, path_names: frozenset[str]+) -> SchemaField | object | None:+ """One parameter to a field, ``_SKIP`` for a non-field, ``None`` to refuse."""+ if text in _SEPARATORS:+ return _SKIP+ head, required = _strip_default(text, grammar)+ head = _LEADING_ANNOTATIONS.sub("", head).strip()+ if not head or head.startswith(_VARIADIC_PREFIXES):+ return _SKIP if head else None++ if grammar.order == "colon":+ name_part, _, type_text = head.partition(":")+ tokens = _without_modifiers(name_part, grammar)+ if len(tokens) != 1:+ return None+ name, type_text = tokens[0], type_text.strip()+ else:+ tokens = _without_modifiers(head, grammar)+ if len(tokens) < 2:+ return None+ name, type_text = tokens[-1], " ".join(tokens[:-1])++ # TypeScript's `name?: T` — an optional parameter, not a nullable type.+ if grammar.optional_marker and name.endswith("?"):+ name, required = name[:-1], False++ if name in _RECEIVERS:+ return _SKIP+ # The ambient request/response object. A name the route template binds is+ # caller-visible whatever it is typed as, so it is never dropped here —+ # an interlock that keeps this list safe to grow.+ if name not in path_names and _bare_type(type_text) in _AMBIENT_TYPES:+ return _SKIP+ # A name the grammar could not reduce to a plain identifier means the+ # assumption failed — a destructuring pattern, a tuple. Refuse the whole+ # signature rather than emit a field set missing one caller-visible input.+ if not _IDENTIFIER.match(name):+ return None+ return SchemaField(name=name, type=type_text, required=required)+++def schema_from_signature(+ signature: str, language: str, path_names: frozenset[str] = frozenset()+) -> ContractSchema | None:+ """The request shape *signature* declares, or ``None`` if unrecoverable.++ *path_names* are the names the route template binds; they are caller-visible+ by construction, so they are never mistaken for an injected object.++ Never returns an empty schema: a caller cannot tell "takes nothing" from+ "could not be read", and the honest answer to the second is no schema. The+ response side stays empty — a return type is one type, not a field set.+ """+ grammar = _GRAMMARS.get(language)+ if grammar is None:+ return None+ parts = _split_parameters(signature, grammar)+ if parts is None:+ return None++ fields: list[SchemaField] = []+ seen: set[str] = set()+ for part in parts:+ parsed = _parse_parameter(part, grammar, path_names)+ if parsed is None:+ return None+ if parsed is _SKIP:+ continue+ assert isinstance(parsed, SchemaField)+ if parsed.name in seen:+ return None+ seen.add(parsed.name)+ fields.append(parsed)++ return ContractSchema(source=SCHEMA_SOURCE, request_fields=fields) if fields else None+++def _route_param_names(contract: Contract) -> frozenset[str]:+ """The names this contract's route template binds, empty for non-routes.++ Read from ``symbol_name``, which keeps the *raw* path — ``contract_id``+ normalizes every parameter to ``{param}``, so the names survive only here.+ """+ if contract.contract_type != "http":+ return frozenset()+ return frozenset(_PATH_PARAM.findall(contract.symbol_name.split(" ", 1)[-1]))+++def attach_signature_schemas(+ contracts: list[Contract], index: RepoIndex | None+) -> dict[str, int]:+ """Give each bound provider in *contracts* the schema its handler declares.++ Runs after :func:`..contracts.bind_symbol_ids`, over every contract type at+ once, and leaves a contract that already carries a schema (``.proto``)+ alone. Mutates in place; returns the two structural exclusions the artifact+ cannot recover from the contracts themselves.+ """+ counts: dict[str, int] = {}+ if index is None:+ return counts++ by_symbol: dict[str, int] = {}+ for contract in contracts:+ if contract.role == "provider" and contract.symbol_id is not None:+ by_symbol[contract.symbol_id] = by_symbol.get(contract.symbol_id, 0) + 1++ for contract in contracts:+ if contract.role != "provider" or contract.schema is not None:+ continue+ symbol = next(+ (+ s+ for s in index.symbols_for_file(contract.file_path)+ if s.symbol_id == contract.symbol_id+ ),+ None,+ )+ if symbol is None:+ continue+ # An ORM model class, a table: a provider with no parameter list to read.+ if symbol.kind not in _CALLABLE_KINDS:+ counts["schema_non_callable_provider"] = (+ counts.get("schema_non_callable_provider", 0) + 1+ )+ continue+ # A symbol carrying several provider contracts is a route-registration+ # site, not a handler — `create_app()` declaring ten routes. Its+ # parameters describe none of them, so a schema here would be wrong+ # rather than merely absent.+ if by_symbol.get(symbol.symbol_id, 0) > 1:+ counts["schema_shared_symbol_provider"] = (+ counts.get("schema_shared_symbol_provider", 0) + 1+ )+ continue+ if symbol.language not in _GRAMMARS:+ counts["schema_unsupported_lang_provider"] = (+ counts.get("schema_unsupported_lang_provider", 0) + 1+ )+ continue+ contract.schema = schema_from_signature(+ symbol.signature, symbol.language, _route_param_names(contract)+ )+ return countsdiff --git a/tests/unit/workspace/test_signature_schema.py b/tests/unit/workspace/test_signature_schema.pynew file mode 100644index 000000000..d6349c918--- /dev/null+++ b/tests/unit/workspace/test_signature_schema.py@@ -0,0 +1,505 @@+"""Request schemas recovered from a handler's parsed signature.++``Contract.schema`` was proto-only, so the three field-level rules in+:mod:`~repowise.core.workspace.breaking_change` could only ever fire on gRPC.+A provider knows its handler symbol, and that handler's parameter list is the+request shape — which is what turns those rules on for every contract type that+binds to a callable.++Two claims are under test. The first is that the mapper reads a *language*, not+a framework: the same code path serves FastAPI and ASP.NET, and the headline+test drives both through the real parser rather than a hand-written signature.+The second is that it is additive and quiet where it cannot see: a handler it+cannot read keeps its contract and gains no schema, and never a schema of zero+fields, which would read as "this endpoint takes nothing".+"""++from __future__ import annotations++from pathlib import Path++import pytest++from repowise.core.ingestion import ASTParser, FileTraverser+from repowise.core.workspace.breaking_change import detect_breaking_changes+from repowise.core.workspace.config import ContractConfig, RepoEntry, WorkspaceConfig+from repowise.core.workspace.contract_schema import ContractSchema, SchemaField+from repowise.core.workspace.contracts import Contract, ContractStore, run_contract_extraction+from repowise.core.workspace.repo_index import WorkspaceIndex+from repowise.core.workspace.signature_schema import (+ SCHEMA_SOURCE,+ attach_signature_schemas,+ schema_from_signature,+)++from ._repo_index import make_repo_index++# ---------------------------------------------------------------------------+# The mapper, per language+# ---------------------------------------------------------------------------+++def _fields(+ signature: str, language: str, path_names: frozenset[str] = frozenset()+) -> list[tuple[str, str, bool]] | None:+ schema = schema_from_signature(signature, language, path_names)+ if schema is None:+ return None+ assert schema.source == SCHEMA_SOURCE+ assert not schema.response_fields, "a return type is one type, not a field set"+ return [(f.name, f.type, f.required) for f in schema.request_fields]+++class TestParameterGrammars:+ """One mapper, several parameter orders — the only axis read is language."""++ def test_python_reads_name_type_and_default(self):+ assert _fields("async def h(period: str, limit: int = 50) -> dict", "python") == [+ ("period", "str", True),+ ("limit", "int", False),+ ]++ def test_csharp_reads_the_type_first_order_past_its_attributes(self):+ assert _fields(+ "GetSummary([FromQuery] string period, [FromQuery] int limit = 50) -> IActionResult",+ "csharp",+ ) == [("period", "string", True), ("limit", "int", False)]++ def test_typescript_optional_marker_is_optional_not_a_name(self):+ assert _fields("function h(id: string, cursor?: string | null) -> void", "typescript") == [+ ("id", "string", True),+ ("cursor", "string | null", False),+ ]++ def test_an_unlisted_language_yields_nothing_rather_than_a_guess(self):+ # Java's stored signature carries no parameter list at all.+ assert _fields("getReports -> List<String>", "java") is None+ assert _fields("function F(w http.ResponseWriter) ", "go") is None++ def test_a_csharp_keyword_is_not_stripped_from_a_python_parameter(self):+ # `out`, `params` and `ref` are C# modifiers and ordinary Python names;+ # one shared modifier set would silently delete all three fields.+ assert _fields("def g(out: list, params: dict, ref: str | None = None)", "python") == [+ ("out", "list", True),+ ("params", "dict", True),+ ("ref", "str | None", False),+ ]+++class TestParametersThatAreNotFields:+ """What the parameter list carries that the caller never supplies."""++ def test_receivers_and_separators_are_dropped(self):+ assert _fields("def h(self, *, name: str, limit: int = 10)", "python") == [+ ("name", "str", True),+ ("limit", "int", False),+ ]++ def test_variadics_widen_the_surface_instead_of_naming_a_field(self):+ assert _fields("def h(a: int, *args, **kwargs)", "python") == [("a", "int", True)]++ def test_an_ellipsis_default_means_no_default(self):+ # `Query(...)` / `Field(...)` is the ecosystem-wide "required" placeholder.+ # Reading it as a real default is what makes a required parameter look+ # optional, which is the whole point of the required-tightened rule.+ assert _fields("def h(q: str = Query(...), page: int = Query(1))", "python") == [+ ("q", "str", True),+ ("page", "int", False),+ ]++ def test_the_placeholder_is_read_however_it_is_spelled(self):+ # `Query(...)` -> `Query(default=...)` is a style edit. Reading only the+ # first spelling flips `required` and reports a breaking change for it.+ assert _fields("def h(a = ..., b = Ellipsis, c = Q(default=...), d = Q(1))", "python") == [+ ("a", "", True),+ ("b", "", True),+ ("c", "", True),+ ("d", "", False),+ ]+++class TestAmbientParameters:+ """The framework's injected objects are not fields a caller supplies."""++ def test_the_request_and_response_objects_are_dropped(self):+ # Renaming one of these is a no-op on the wire; counting it as a+ # required field reports that rename as a breaking change.+ assert _fields(+ "async def h(request: Request, response: Response, q: str)", "python"+ ) == [("q", "str", True)]+ assert _fields("Get(HttpContext ctx, [FromQuery] string q)", "csharp") == [+ ("q", "string", True)+ ]++ def test_the_match_is_the_whole_type_never_a_suffix(self):+ # A request *body* is the most caller-visible field there is, and it is+ # conventionally typed `SomethingRequest`. A suffix match eats it.+ assert _fields("async def h(body: BlastRadiusRequest, q: str)", "python") == [+ ("body", "BlastRadiusRequest", True),+ ("q", "str", True),+ ]++ def test_a_name_the_route_binds_is_never_dropped(self):+ # The interlock: caller-visible by construction, whatever it is typed as.+ assert _fields("async def h(request: Request)", "python", frozenset({"request"})) == [+ ("request", "Request", True)+ ]++ def test_a_handler_taking_only_ambient_objects_yields_no_schema(self):+ assert schema_from_signature("async def h(request: Request)", "python") is None+++class TestRefusals:+ """Where the grammar's assumption fails, refuse rather than under-report."""++ def test_a_truncated_parameter_list_is_refused_whole(self):+ # A shortened field set would read as a removed field on the next diff.+ assert _fields("def h(a: int, b: str", "python") is None++ def test_a_comparison_in_a_default_is_not_a_type_argument(self):+ # Two comparisons balance as if they were `<...>`, and every parameter+ # between them is swallowed with no error — a wrong field set, which is+ # the one failure mode worse than refusing.+ assert _fields("Get(int lo = a < b, string name, int hi = c > d)", "csharp") == [+ ("lo", "int", False),+ ("name", "string", True),+ ("hi", "int", False),+ ]+ assert _fields("function h(a = x < 1, b, c = y > 2, d)", "javascript") == [+ ("a", "", False),+ ("b", "", True),+ ("c", "", False),+ ("d", "", True),+ ]++ def test_a_real_type_argument_still_nests(self):+ assert _fields("GetAll<T>(List<int> ids, Dictionary<string, int> m)", "csharp") == [+ ("ids", "List<int>", True),+ ("m", "Dictionary<string, int>", True),+ ]++ def test_a_destructured_parameter_refuses_the_whole_signature(self):+ assert _fields("function C({ children }: { children: ReactNode })", "typescript") is None++ def test_a_handler_taking_nothing_yields_no_schema(self):+ # Indistinguishable from "could not be read", and the honest answer to+ # the second is nothing at all.+ assert schema_from_signature("def create_app() -> FastAPI", "python") is None++ def test_a_comment_inside_the_list_does_not_open_a_string(self):+ signature = (+ "def h(\n"+ " a: int,\n"+ " # the caller's page size, not the server's\n"+ " b: str = 'x,y',\n"+ ") -> None"+ )+ assert _fields(signature, "python") == [("a", "int", True), ("b", "str", False)]++ def test_a_block_comment_apostrophe_does_not_swallow_the_list(self):+ signature = (+ "function h(\n"+ " a: string,\n"+ " /** Aborts the caller's read loop. */\n"+ " signal?: AbortSignal,\n"+ ") -> void"+ )+ assert _fields(signature, "typescript") == [+ ("a", "string", True),+ ("signal", "AbortSignal", False),+ ]+++# ---------------------------------------------------------------------------+# The attach pass+# ---------------------------------------------------------------------------+++def _provider(symbol_id: str | None, *, contract_id: str = "http::GET::/a") -> Contract:+ return Contract(+ repo="alpha",+ contract_id=contract_id,+ contract_type="http",+ role="provider",+ file_path="app/api.py",+ symbol_name="fastapi:GET /a",+ confidence=0.85,+ line=5,+ symbol_id=symbol_id,+ )+++async def _index_for(tmp_path: Path, symbols) -> object:+ return await make_repo_index(tmp_path / "alpha", {"app/api.py": symbols}, alias="alpha")+++def _symbol(name: str, signature: str, *, kind="function", language="python", line=6):+ from repowise.core.ingestion.models import Symbol++ return Symbol(+ id=f"app/api.py::{name}",+ name=name,+ qualified_name=name,+ kind=kind,+ signature=signature,+ start_line=line,+ end_line=line + 1,+ docstring=None,+ visibility="public",+ language=language,+ )+++class TestAttachPass:+ async def test_the_route_template_protects_its_own_parameters(self, tmp_path: Path):+ index = await _index_for(+ tmp_path, [_symbol("h", "def h(request: Request, repo_id: str)")]+ )+ contract = _provider("app/api.py::h")+ contract.symbol_name = "fastapi:GET /repos/{request}"+ try:+ attach_signature_schemas([contract], index)+ finally:+ await index.close()+ # `request` is bound by the path here, so the ambient list must not+ # reach it; `repo_id` is an ordinary field either way.+ assert [f.name for f in contract.schema.request_fields] == ["request", "repo_id"]++ async def test_a_bound_provider_gains_its_handler_schema(self, tmp_path: Path):+ index = await _index_for(tmp_path, [_symbol("h", "def h(q: str, page: int = 1)")])+ contracts = [_provider("app/api.py::h")]+ try:+ attach_signature_schemas(contracts, index)+ finally:+ await index.close()+ assert contracts[0].schema is not None+ assert [f.name for f in contracts[0].schema.request_fields] == ["q", "page"]++ async def test_a_consumer_never_gains_one(self, tmp_path: Path):+ index = await _index_for(tmp_path, [_symbol("h", "def h(q: str)")])+ consumer = _provider("app/api.py::h")+ consumer.role = "consumer"+ try:+ attach_signature_schemas([consumer], index)+ finally:+ await index.close()+ # The function making a call says nothing about the request it sends.+ assert consumer.schema is None++ async def test_a_symbol_carrying_several_providers_is_a_registration_site(+ self, tmp_path: Path+ ):+ index = await _index_for(+ tmp_path, [_symbol("create_app", "def create_app(settings: Settings) -> FastAPI")]+ )+ contracts = [+ _provider("app/api.py::create_app", contract_id="http::GET::/a"),+ _provider("app/api.py::create_app", contract_id="http::GET::/b"),+ ]+ try:+ counts = attach_signature_schemas(contracts, index)+ finally:+ await index.close()+ # `settings` describes neither route; a schema here would be wrong,+ # not merely absent.+ assert all(c.schema is None for c in contracts)+ assert counts["schema_shared_symbol_provider"] == 2++ async def test_an_unsupported_language_is_counted_not_guessed(self, tmp_path: Path):+ index = await _index_for(+ tmp_path, [_symbol("h", "h -> List<String>", language="java", kind="method")]+ )+ contracts = [_provider("app/api.py::h")]+ try:+ counts = attach_signature_schemas(contracts, index)+ finally:+ await index.close()+ assert contracts[0].schema is None+ assert counts["schema_unsupported_lang_provider"] == 1++ async def test_a_proto_schema_is_left_alone(self, tmp_path: Path):+ index = await _index_for(tmp_path, [_symbol("h", "def h(q: str)")])+ contract = _provider("app/api.py::h")+ original = ContractSchema(source="proto", request_fields=[SchemaField("id", "string")])+ contract.schema = original+ try:+ attach_signature_schemas([contract], index)+ finally:+ await index.close()+ assert contract.schema is original+ assert [f.name for f in contract.schema.request_fields] == ["id"]++ async def test_a_non_callable_symbol_is_counted_not_read(self, tmp_path: Path):+ index = await _index_for(+ tmp_path, [_symbol("Order", "class Order", kind="class", line=6)]+ )+ contracts = [_provider("app/api.py::Order")]+ try:+ counts = attach_signature_schemas(contracts, index)+ finally:+ await index.close()+ assert contracts[0].schema is None+ assert counts["schema_non_callable_provider"] == 1++ async def test_an_unbound_provider_is_untouched(self, tmp_path: Path):+ index = await _index_for(tmp_path, [_symbol("h", "def h(q: str)")])+ contracts = [_provider(None)]+ try:+ attach_signature_schemas(contracts, index)+ finally:+ await index.close()+ assert contracts[0].schema is None++ def test_no_index_is_not_an_error(self):+ contracts = [_provider("app/api.py::h")]+ assert attach_signature_schemas(contracts, None) == {}+ assert contracts[0].schema is None+++class TestFidelityIsNotMixed:+ """Two sources describe the same endpoint at different fidelities."""++ def test_a_proto_shape_is_never_diffed_against_a_signature_one(self):+ from repowise.core.workspace.breaking_change import _diff_schemas++ proto = ContractSchema(source="proto", request_fields=[SchemaField("user_id", "string")])+ signature = ContractSchema(+ source=SCHEMA_SOURCE, request_fields=[SchemaField("user_id", "int", required=True)]+ )+ # The fields differ in both type and requiredness, so a source-blind+ # diff reports two breaking changes for a change of parser.+ assert _diff_schemas(proto, signature)+ assert _report_kinds(proto, signature) == []++ def test_two_signature_shapes_are_diffed(self):+ before = ContractSchema(source=SCHEMA_SOURCE, request_fields=[SchemaField("a", "str")])+ after = ContractSchema(+ source=SCHEMA_SOURCE,+ request_fields=[SchemaField("a", "str"), SchemaField("b", "str", required=True)],+ )+ assert _report_kinds(before, after) == ["field_required"]+++def _report_kinds(prev_schema, curr_schema) -> list[str]:+ """Kinds `detect_breaking_changes` reports for one contract's two shapes."""++ def store(schema):+ contract = _provider("app/api.py::h")+ contract.schema = schema+ return ContractStore(contracts=[contract])++ return [c.kind for c in detect_breaking_changes(store(prev_schema), store(curr_schema)).changes]+++# ---------------------------------------------------------------------------+# The gate: a required parameter added to a real route, in two frameworks+# ---------------------------------------------------------------------------++FASTAPI_BEFORE = (+ "from fastapi import APIRouter\n"+ "\n"+ "router = APIRouter()\n"+ "\n"+ "\n"+ '@router.get("/reports/summary")\n'+ "async def get_summary(period: str) -> dict:\n"+ " return {}\n"+)+FASTAPI_AFTER = FASTAPI_BEFORE.replace(+ "async def get_summary(period: str)", "async def get_summary(period: str, tenant: str)"+)++ASPNET_BEFORE = (+ "using Microsoft.AspNetCore.Mvc;\n"+ "\n"+ "[ApiController]\n"+ '[Route("reports")]\n'+ "public class ReportsController : ControllerBase\n"+ "{\n"+ ' [HttpGet("summary")]\n'+ " public IActionResult GetSummary([FromQuery] string period)\n"+ " {\n"+ " return Ok();\n"+ " }\n"+ "}\n"+)+ASPNET_AFTER = ASPNET_BEFORE.replace(+ "GetSummary([FromQuery] string period)",+ "GetSummary([FromQuery] string period, [FromQuery] string tenant)",+)+++def _parse(repo: Path) -> dict[str, list]:+ """Real ingestion output for *repo*, so the test reads real signatures."""+ parser = ASTParser()+ out: dict[str, list] = {}+ for file_info in FileTraverser(repo).traverse():+ parsed = parser.parse_file(file_info, (repo / file_info.path).read_bytes())+ if parsed.symbols:+ out[file_info.path] = list(parsed.symbols)+ return out+++#: The consuming repo, so the diff has a cross-repo consumer to name. Its+#: language is irrelevant to the provider under test, which is the point.+CONSUMER = 'import axios from "axios";\n\naxios.get("/reports/summary");\n'+++async def _extract(tmp_path: Path, filename: str, source: str, monkeypatch) -> ContractStore:+ """Extract a two-repo workspace: alpha provides the route, beta calls it."""+ from repowise.core.workspace import contracts as contracts_mod++ monkeypatch.setattr(contracts_mod, "save_contract_store", lambda store, root: root)+ repo = tmp_path / "alpha"+ (repo / "src").mkdir(parents=True, exist_ok=True)+ (repo / "src" / filename).write_text(source, encoding="utf-8")+ (repo / ".repowise").mkdir(exist_ok=True)++ beta = tmp_path / "beta"+ (beta / "src").mkdir(parents=True, exist_ok=True)+ (beta / "src" / "client.ts").write_text(CONSUMER, encoding="utf-8")+ (beta / ".repowise").mkdir(exist_ok=True)++ index = await make_repo_index(repo, _parse(repo), alias="alpha")+ config = WorkspaceConfig(+ repos=[RepoEntry(path="alpha", alias="alpha"), RepoEntry(path="beta", alias="beta")],+ contracts=ContractConfig(),+ )+ try:+ return await run_contract_extraction(+ config, tmp_path, [], workspace_index=WorkspaceIndex({"alpha": index})+ )+ finally:+ await index.close()+++ ("filename", "before", "after"),+ [+ ("reports.py", FASTAPI_BEFORE, FASTAPI_AFTER),+ ("ReportsController.cs", ASPNET_BEFORE, ASPNET_AFTER),+ ],+ ids=["fastapi", "aspnet"],+)+async def test_adding_a_required_parameter_is_a_breaking_change(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, filename: str, before: str, after: str+):+ """The reported test, end to end, through the real parser and no new rule."""+ previous = await _extract(tmp_path / "a", filename, before, monkeypatch)+ current = await _extract(tmp_path / "b", filename, after, monkeypatch)++ providers = [c for c in previous.contracts if c.repo == "alpha" and c.role == "provider"]+ assert providers and all(c.schema is not None for c in providers), providers+ assert previous.contract_links, "the consumer must be matched for impact to resolve"++ report = detect_breaking_changes(previous, current)+ tightened = [c for c in report.changes if c.kind == "field_required"]+ assert [c.field_name for c in tightened] == ["tenant"], report.to_dict()+ change = tightened[0]+ assert change.severity == "breaking"+ # The identity W2 gave the contract survives onto the change itself.+ assert change.provider_symbol_id+ assert [i.repo for i in change.impacted_consumers] == ["beta"]+ # Exactly one change: adding an optional parameter or renaming an existing+ # one would show up here, and neither happened.+ assert len(report.changes) == 1, report.to_dict()diff --git a/tests/unit/workspace/test_system_graph.py b/tests/unit/workspace/test_system_graph.pyindex edfc592d8..ebc33a235 100644--- a/tests/unit/workspace/test_system_graph.py+++ b/tests/unit/workspace/test_system_graph.py@@ -312,6 +312,7 @@ def test_system_graph_json_shape_is_locked():"http_consumers_unresolved","http_consumer_coverage","symbol_identity",+ "schema_coverage",}