Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(workspace): 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.py
index 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.schema
curr_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.py
index 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_schemas
if 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.py
index 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),
+ }
+
+
@dataclass
class 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)
@property
def 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(),
}
@classmethod
def 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.py
index 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, inclusive
end_line: int # 1-indexed, inclusive
visibility: 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.py
new file mode 100644
index 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 counts
diff --git a/tests/unit/workspace/test_signature_schema.py b/tests/unit/workspace/test_signature_schema.py
new file mode 100644
index 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.py
index 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",
}