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): name how every contract and link was made, and read the system graph through one adjacency (#4486)

Raghav Chamadiya4d685baa0b11
diff --git a/docs/reference/WORKSPACE_CONTRACTS.md b/docs/reference/WORKSPACE_CONTRACTS.md
index 17999a331..e8dcf83e4 100644
--- a/docs/reference/WORKSPACE_CONTRACTS.md
+++ b/docs/reference/WORKSPACE_CONTRACTS.md
@@ -6,6 +6,44 @@ contracts, for when you need to know why a link did or did not form. Start from
names the reason for each unmatched consumer. The support matrix of frameworks
and libraries is in [API Contract Extraction](../scale/WORKSPACES.md#api-contract-extraction).
+## How a contract and a link were made
+
+Every contract carries an `origin` and every link a `strategy`, each from a closed
+vocabulary with exactly one confidence per value, the rule
+[GRAPH.md](../layers/GRAPH.md#every-edge-says-how-it-got-there) applies to call edges. A
+link's confidence is its weaker end's times its strategy's factor, and its `match_type`
+follows from the strategy.
+
+| Confidence | Contract `origin` | What was established |
+|:---:|---|---|
+| 0.90 | `idl` | An OpenAPI or proto document declares the operation |
+| 0.90 | `package_export` | A published package exports the symbol another repo imports |
+| 0.85 | `route_registration` | A framework registers the route, handler, server or hub in code |
+| 0.85 | `typed_client` | The parsed index types the receiver as an HTTP client |
+| 0.85 | `ddl` | SQL DDL or a migration creates or alters the table |
+| 0.85 | `explicit_table` | An ORM model names its table explicitly |
+| 0.75 | `client_call` | A known client, broker, socket or query-builder call names the destination |
+| 0.75 | `instance_base` | A call on a client instance whose base URL the file reads |
+| 0.70 | `dataflow` | The destination was traced across statements to the call |
+| 0.70 | `sql_string` | A table named inside SQL text in a string |
+| 0.65 | `name_heuristic` | Only a callee or receiver name says it is a client call |
+| 0.60 | `name_convention` | A naming convention: an ORM's default table name, a unique short type name |
+
+| Factor | Link `strategy` | `match_type` | What joined the two ends |
+|:---:|---|---|---|
+| 1.0 | `exact_id` | exact | Both name the same normalized id, method and service wildcards included |
+| 1.0 | `pattern_matched` | exact | The consumer's subscription pattern matches the provider's name |
+| 1.0 | `binding_routed` | exact | A queue bound to the provider's exchange, with a routing key it receives |
+| 1.0 | `shared_table` | exact | A service that only models a table, to the one service defining its schema |
+| 1.0 | `service_mapped` | exact | The consumer's host or base token maps to the providing service |
+| 1.0 | `unique_path` | exact | The consumer's base is unread and one service serves the path |
+| 0.6 | `ambiguous_path` | candidate | The base is unread and several services serve the path; linked to each |
+| 0.6 | `prefix_stripped` | candidate | Matched only after stripping mount, version or base prefixes |
+| 1.0 | `manual` | manual | Declared in the workspace config |
+
+A new dialect picks an existing origin, not a number. A system-graph edge carries the
+strategy of the link that gave it its confidence, and `manifest` for a package dependency.
+
## Sockets
An endpoint is identified by its path (`socket::/hubs/game`); a message by its
@@ -31,7 +69,10 @@ topic ARN by its last field. A subscription by pattern (NATS `orders.*` /
whose name it matches. A Laravel job dispatched without a queue runs on the
queue its class declares (`public $queue`, `$this->onQueue()`, `viaQueue()`),
found by the class's fully qualified name; one left on the connection's
-default queue is not recorded, since every app has one. RabbitMQ
+default queue is not recorded, since every app has one. A Laravel job class
+links only to a Laravel dispatch of that class: a raw publish (amqplib
+`sendToQueue`) on a queue of the same name is not the job envelope its worker
+reads. RabbitMQ
publishers name an exchange and a routing key while consumers name a queue, so
a queue binding found anywhere in the workspace connects the two: each consumer
of the bound queue links to the exchange's publishers whose routing key the
@@ -62,7 +103,8 @@ or injected as `HttpClient`, with `environment.apiUrl` folded from `src/environm
fields built on it; a base an interceptor prepends is not read. A client call
whose base URL is an unresolved placeholder (`fetch(\`${API_BASE}/users\`)`) matches
on the host-relative path; the link is **exact** when exactly one workspace service
-provides that path and a lower-confidence **candidate** when the target is ambiguous.
+provides that path (`unique_path`) and a lower-confidence **candidate** when the target
+is ambiguous (`ambiguous_path`).
## Contracts over REST
diff --git a/docs/scale/WORKSPACES.md b/docs/scale/WORKSPACES.md
index b283bc01c..36a661526 100644
--- a/docs/scale/WORKSPACES.md
+++ b/docs/scale/WORKSPACES.md
@@ -302,6 +302,7 @@ The contracts, package dependencies, and co-changes above are each a flat list.
- a `kind`, `http`, `grpc`, `event`, `package`, `co_change`, or `db`;
- a `match_type`, `exact`, `candidate`, `manual`, or `inferred`;
+- a `strategy`, the [matching rule](../reference/WORKSPACE_CONTRACTS.md#how-a-contract-and-a-link-were-made) of the link that gave the edge its confidence (`manifest` for a package dependency, none for co-change);
- a `confidence` and a `weight` (how many underlying contracts / deps / co-changes it aggregates);
- `contract_refs` back-pointers so any view can drill from an edge to its evidence.
@@ -497,7 +498,7 @@ A rule with `allow: false` (the default) is a **deny** rule: a structural depend
### Dependency cycles
-Independently of any rules, conformance detects **circular dependencies** among services over structural edges (`A -> B -> ... -> A`). A cycle means the services cannot be built, deployed, or reasoned about independently. Cycle detection runs even with zero rules declared, so every workspace gets it.
+Independently of any rules, conformance detects **circular dependencies** among services over structural edges (`A -> B -> ... -> A`). A cycle means the services cannot be built, deployed, or reasoned about independently. Cycle detection runs even with zero rules declared, so every workspace gets it. A cycle that closes only through an event edge still counts, since it couples message schemas and deploy order; each cycle lists the edge kinds on every leg (`leg_kinds`) and how many legs are asynchronous (`async_legs`).
### Using it
diff --git a/packages/api-client/src/types/workspace.ts b/packages/api-client/src/types/workspace.ts
index 52552a9ba..732962d37 100644
--- a/packages/api-client/src/types/workspace.ts
+++ b/packages/api-client/src/types/workspace.ts
@@ -88,6 +88,8 @@ export interface WorkspaceContractEntry {
* just cannot be traversed into the call graph.
*/
symbol_id: string | null;
+ /** What established the contract (`route_registration`, `client_call`, ...). */
+ origin?: string | null;
/**
* Extractor-supplied detail (`extraction_layer`, `framework`, `method`,
* `path`, `table`, `package`...). Keys vary by contract type.
@@ -99,6 +101,8 @@ export interface WorkspaceContractLinkEntry {
contract_id: string;
contract_type: string;
match_type: string;
+ /** The matching rule that made the link (`exact_id`, `binding_routed`, ...); `match_type` derives from it. */
+ strategy?: string | null;
confidence: number;
provider_repo: string;
provider_file: string;
diff --git a/packages/core/src/repowise/core/workspace/architecture_metrics.py b/packages/core/src/repowise/core/workspace/architecture_metrics.py
index e56c3d1ba..1fddeda73 100644
--- a/packages/core/src/repowise/core/workspace/architecture_metrics.py
+++ b/packages/core/src/repowise/core/workspace/architecture_metrics.py
@@ -41,7 +41,7 @@ from statistics import median
from typing import Any
from repowise.core.workspace.cycles import detect_cycles
-from repowise.core.workspace.system_graph import SystemEdge, SystemGraph
+from repowise.core.workspace.system_graph import SystemGraph
_log = logging.getLogger("repowise.workspace.architecture_metrics")
@@ -203,19 +203,14 @@ class ArchitectureMetrics:
# ---------------------------------------------------------------------------
-def _structural_adjacency(edges: list[SystemEdge]) -> dict[str, set[str]]:
+def _structural_adjacency(graph: SystemGraph) -> dict[str, set[str]]:
"""Forward dependency adjacency over structural edges: ``source -> {targets}``.
- Direction is the system graph's own: ``source`` depends on / calls
- ``target``. Behavioral co-change edges are excluded — they assert correlated
- change, not a dependency, so they never contribute to reachability.
+ The graph's own :meth:`SystemGraph.adjacency`, so reachability here and the
+ cycles reported beside it walk the same edges. Behavioral co-change edges
+ are excluded: they assert correlated change, not a dependency.
"""
- adj: dict[str, set[str]] = {}
- for edge in edges:
- if not edge.structural:
- continue
- adj.setdefault(edge.source, set()).add(edge.target)
- return adj
+ return {src: set(targets) for src, targets in graph.adjacency().items()}
def _reachable(start: str, adj: dict[str, set[str]], node_ids: set[str]) -> set[str]:
@@ -372,7 +367,7 @@ def compute_architecture_metrics(
node_ids = [n.id for n in graph.nodes]
n = len(node_ids)
- adj = _structural_adjacency(graph.edges)
+ adj = _structural_adjacency(graph)
structural_edge_count = sum(len(t) for t in adj.values())
# Empty / single-service workspaces are vacuously decoupled — no coupling is
diff --git a/packages/core/src/repowise/core/workspace/blast_radius.py b/packages/core/src/repowise/core/workspace/blast_radius.py
index bff5db819..ac27a7904 100644
--- a/packages/core/src/repowise/core/workspace/blast_radius.py
+++ b/packages/core/src/repowise/core/workspace/blast_radius.py
@@ -30,7 +30,7 @@ from collections import defaultdict
from dataclasses import dataclass, field
from typing import Any
-from repowise.core.workspace.system_graph import SystemEdge, SystemGraph
+from repowise.core.workspace.system_graph import SystemGraph
# ---------------------------------------------------------------------------
# Constants (single source of truth)
@@ -165,25 +165,6 @@ class _Accum:
edge_kinds: set[str]
-def _build_impact_adjacency(
- edges: list[SystemEdge],
-) -> dict[str, list[tuple[str, SystemEdge]]]:
- """Adjacency in *impact* direction: changed-node id → (dependent id, edge).
-
- Structural edge ``source → target`` (source depends on target): changing
- ``target`` impacts ``source``, so we add ``target → source``. Behavioral
- co-change edges are symmetric, so both endpoints impact each other.
- """
- adj: dict[str, list[tuple[str, SystemEdge]]] = defaultdict(list)
- for e in edges:
- if e.structural:
- adj[e.target].append((e.source, e))
- else:
- adj[e.source].append((e.target, e))
- adj[e.target].append((e.source, e))
- return adj
-
-
def cross_repo_blast_radius(
graph: SystemGraph,
targets: list[str],
@@ -218,10 +199,9 @@ def cross_repo_blast_radius(
unresolved_targets=unresolved,
)
- edges = graph.edges
- if not include_behavioral:
- edges = [e for e in edges if e.structural]
- adj = _build_impact_adjacency(edges)
+ # Impact direction: a change to a node reaches whatever depends on it, and
+ # co-change edges are symmetric, so both endpoints reach each other.
+ adj = graph.adjacency(behavioral=include_behavioral, impact=True)
best: dict[str, _Accum] = {}
# Frontier value per node: (propagated score, path-is-all-structural).
@@ -230,7 +210,7 @@ def cross_repo_blast_radius(
for hop in range(1, depth + 1):
next_frontier: dict[str, tuple[float, bool]] = {}
for src, (src_score, src_structural) in frontier.items():
- for dst, edge in adj.get(src, []):
+ for dst, edge in ((d, e) for d, es in adj.get(src, {}).items() for e in es):
if dst in target_set:
continue # never impact a changed node back onto itself
factor = 1.0 if edge.structural else BEHAVIORAL_EDGE_WEIGHT
diff --git a/packages/core/src/repowise/core/workspace/code_api.py b/packages/core/src/repowise/core/workspace/code_api.py
index 499c7f4ff..38604bdaa 100644
--- a/packages/core/src/repowise/core/workspace/code_api.py
+++ b/packages/core/src/repowise/core/workspace/code_api.py
@@ -40,6 +40,7 @@ from typing import TYPE_CHECKING, Any
from repowise.core.fsutils import repo_relative
from repowise.core.pyparse import parse_python
+from repowise.core.workspace.origins import ContractOrigin, origin_confidence
if TYPE_CHECKING:
from collections.abc import Callable, Collection
@@ -54,7 +55,7 @@ CODE_CONTRACT_TYPE = "code"
#: Both sides are index-resolved, not regex-matched — the manifest and the
#: import edge each name their half outright.
-_CONFIDENCE = 0.9
+_ORIGIN = ContractOrigin.PACKAGE_EXPORT
#: Manifest basenames handled here, mapped to the ecosystem they declare.
_MANIFESTS: dict[str, str] = {
@@ -514,7 +515,8 @@ def build_code_surface(
role="provider",
file_path=symbol.file_path,
symbol_name=exported,
- confidence=_CONFIDENCE,
+ confidence=origin_confidence(_ORIGIN),
+ origin=_ORIGIN,
line=symbol.start_line,
# Known at emission, so bind_symbol_ids is a no-op here and
# attach_signature_schemas reaches the parameter list.
@@ -558,7 +560,8 @@ def build_code_surface(
role="consumer",
file_path=edge.source_file,
symbol_name=f"{package.name}:{exported}",
- confidence=_CONFIDENCE,
+ confidence=origin_confidence(_ORIGIN),
+ origin=_ORIGIN,
meta={
"package": package.name,
"ecosystem": package.ecosystem,
diff --git a/packages/core/src/repowise/core/workspace/contracts.py b/packages/core/src/repowise/core/workspace/contracts.py
index 29985047b..eaba2e88a 100644
--- a/packages/core/src/repowise/core/workspace/contracts.py
+++ b/packages/core/src/repowise/core/workspace/contracts.py
@@ -26,6 +26,7 @@ from repowise.core.workspace.config import (
ensure_workspace_data_dir,
)
from repowise.core.workspace.contract_schema import ContractSchema
+from repowise.core.workspace.origins import LinkStrategy, legacy_strategy
from repowise.core.workspace.signature_schema import attach_signature_schemas
if TYPE_CHECKING:
@@ -65,7 +66,10 @@ CONTRACTS_FILENAME = "contracts.json"
# Version 13 adds Angular HttpClient calls, with bases folded from environment
# files and class fields.
# Version 14 adds MassTransit message-type topic contracts (C# and VB.NET).
-CONTRACTS_VERSION = 14
+# Version 15 stamps each contract with its origin and each link with its
+# strategy (see :mod:`.origins`), and stops linking a Laravel job class to a
+# publisher that is not Laravel.
+CONTRACTS_VERSION = 15
#: ``meta["kind"]`` of a topic contract: the destination a broker call names.
#: A queue is read by one consumer group; a topic, subject or channel fans
@@ -104,7 +108,7 @@ class Contract:
role: str # "provider" | "consumer"
file_path: str # relative to repo root
symbol_name: str # handler name, service.method, etc. — display only
- confidence: float # 0.7–0.9 based on extraction strategy
+ confidence: float # the origin's confidence, see :data:`.origins.ORIGIN_CONFIDENCE`
service: str | None = None # service boundary path (monorepo)
#: 1-indexed line of the declaration or call this contract was read from.
#: The key :func:`bind_symbol_ids` binds against, and what says *where* a
@@ -119,12 +123,15 @@ class Contract:
# Optional request/response shape — populated by dialects that can recover
# it (proto message fields today). Drives schema-level breaking-change diffs.
schema: ContractSchema | None = None
+ #: What established this contract, a :class:`.origins.ContractOrigin`. None
+ #: on a row stored before origins existed.
+ origin: str | None = None
def to_dict(self) -> dict[str, Any]:
d = asdict(self)
if d["service"] is None:
del d["service"]
- for optional in ("line", "symbol_id"):
+ for optional in ("line", "symbol_id", "origin"):
if d[optional] is None:
del d[optional]
if not d["meta"]:
@@ -152,6 +159,7 @@ class Contract:
symbol_id=data.get("symbol_id"),
meta=data.get("meta", {}),
schema=ContractSchema.from_dict(raw_schema) if raw_schema else None,
+ origin=data.get("origin"),
)
@@ -161,7 +169,7 @@ class ContractLink:
contract_id: str
contract_type: str # "http" | "grpc" | "socket" | "topic" | "data" | "code"
- match_type: str # "exact" | "candidate" | "manual"
+ match_type: str # "exact" | "candidate" | "manual", derived from ``strategy``
confidence: float
provider_repo: str
provider_file: str
@@ -181,6 +189,8 @@ class ContractLink:
#: or a path matched across case, a wildcard method or a mount prefix.
#: None when both ends share ``contract_id``.
consumer_contract_id: str | None = None
+ #: The matching rule that made this link, a :class:`.origins.LinkStrategy`.
+ strategy: str | None = None
def to_dict(self) -> dict[str, Any]:
d = asdict(self)
@@ -188,17 +198,23 @@ class ContractLink:
del d["provider_service"]
if d["consumer_service"] is None:
del d["consumer_service"]
- for optional in ("provider_symbol_id", "consumer_symbol_id", "consumer_contract_id"):
+ for optional in (
+ "provider_symbol_id",
+ "consumer_symbol_id",
+ "consumer_contract_id",
+ "strategy",
+ ):
if d[optional] is None:
del d[optional]
return d
@classmethod
def from_dict(cls, data: dict[str, Any]) -> ContractLink:
+ match_type = data.get("match_type", "exact")
return cls(
contract_id=data["contract_id"],
contract_type=data["contract_type"],
- match_type=data.get("match_type", "exact"),
+ match_type=match_type,
confidence=data.get("confidence", 1.0),
provider_repo=data["provider_repo"],
provider_file=data["provider_file"],
@@ -211,6 +227,8 @@ class ContractLink:
provider_symbol_id=data.get("provider_symbol_id"),
consumer_symbol_id=data.get("consumer_symbol_id"),
consumer_contract_id=data.get("consumer_contract_id"),
+ # A store written before strategies existed: read its match_type.
+ strategy=data.get("strategy") or legacy_strategy(match_type),
)
@@ -407,6 +425,7 @@ def _build_manual_links(
contract_type=ml.contract_type,
match_type="manual",
confidence=1.0,
+ strategy=LinkStrategy.MANUAL,
provider_repo=ml.to_repo,
provider_file="",
provider_symbol="",
@@ -424,6 +443,7 @@ def _build_manual_links(
contract_type=ml.contract_type,
match_type="manual",
confidence=1.0,
+ strategy=LinkStrategy.MANUAL,
provider_repo=ml.from_repo,
provider_file="",
provider_symbol="",
diff --git a/packages/core/src/repowise/core/workspace/cycles.py b/packages/core/src/repowise/core/workspace/cycles.py
index 2996873bb..815ed3213 100644
--- a/packages/core/src/repowise/core/workspace/cycles.py
+++ b/packages/core/src/repowise/core/workspace/cycles.py
@@ -8,8 +8,13 @@ other workspace view reads.
**Structural edges only.** Co-change is *behavioral* — two files changing
together does not assert a dependency, so a co-change "loop" is not a cycle. We
-walk only ``edge.structural`` edges (http / grpc / event / package / db), exactly
-the distinction the system graph already encodes.
+walk :meth:`SystemGraph.adjacency`, the structural view every workspace metric
+reads (http / grpc / socket / event / package / db).
+
+**An async leg still closes a cycle.** A loop that only closes through an event
+edge couples message schemas and deploy order all the same, so it counts. Each
+cycle carries ``leg_kinds``, the edge kinds on every leg, so a view can say
+which legs are asynchronous (:data:`ASYNC_EDGE_KINDS`) instead of hiding them.
**Reuse, not reinvention.** Cycle finding is delegated to NetworkX
(``simple_cycles`` / ``strongly_connected_components``) — the same library the
@@ -24,10 +29,10 @@ Pure and I/O-free: it consumes a ``SystemGraph`` and returns dataclasses.
from __future__ import annotations
import logging
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from typing import Any
-from repowise.core.workspace.system_graph import SystemEdge, SystemGraph
+from repowise.core.workspace.system_graph import ASYNC_EDGE_KINDS, SystemEdge, SystemGraph
_log = logging.getLogger("repowise.workspace.cycles")
@@ -55,20 +60,30 @@ class DependencyCycle:
goes ``nodes[i] -> nodes[i+1]``, and the last wraps back to the first).
``edge_ids`` are the system-graph edges that form the loop, so a view can
highlight exactly those seams. ``length`` is the number of services.
+ ``leg_kinds[i]`` lists the edge kinds joining ``nodes[i]`` to the next node,
+ sorted: more than one when, say, an http and an event edge both do.
"""
nodes: list[str]
edge_ids: list[str]
+ leg_kinds: list[list[str]] = field(default_factory=list)
@property
def length(self) -> int:
return len(self.nodes)
+ @property
+ def async_legs(self) -> int:
+ """How many legs only an asynchronous edge (an event) joins."""
+ return sum(1 for kinds in self.leg_kinds if kinds and set(kinds) <= ASYNC_EDGE_KINDS)
+
def to_dict(self) -> dict[str, Any]:
return {
"nodes": self.nodes,
"edge_ids": self.edge_ids,
"length": self.length,
+ "leg_kinds": self.leg_kinds,
+ "async_legs": self.async_legs,
}
@classmethod
@@ -76,6 +91,7 @@ class DependencyCycle:
return cls(
nodes=list(data.get("nodes", [])),
edge_ids=list(data.get("edge_ids", [])),
+ leg_kinds=[list(kinds) for kinds in data.get("leg_kinds", [])],
)
@@ -84,32 +100,23 @@ class DependencyCycle:
# ---------------------------------------------------------------------------
-def _structural_adjacency(edges: list[SystemEdge]) -> dict[tuple[str, str], str]:
- """Map each structural ``(source, target)`` pair to a representative edge id.
+def _cycle(
+ nodes: list[str], adjacency: dict[str, dict[str, list[SystemEdge]]]
+) -> DependencyCycle:
+ """The loop ``nodes[0] -> … -> nodes[0]`` with each leg's edges.
Parallel structural edges (e.g. http + package between the same services)
- collapse onto one entry — a cycle highlights the seam, not every transport.
- Self-loops (``source == target``) are kept: a service depending on itself is
- a degenerate 1-cycle worth reporting.
+ are one leg: the first names it in ``edge_ids`` (a cycle highlights the
+ seam, not every transport) and all of them name its ``leg_kinds``.
"""
- adjacency: dict[tuple[str, str], str] = {}
- for edge in edges:
- if not edge.structural:
- continue
- key = (edge.source, edge.target)
- adjacency.setdefault(key, edge.id)
- return adjacency
-
-
-def _cycle_edges(nodes: list[str], adjacency: dict[tuple[str, str], str]) -> list[str]:
- """Resolve the edge ids for the loop ``nodes[0] -> … -> nodes[0]``."""
edge_ids: list[str] = []
+ leg_kinds: list[list[str]] = []
for i, src in enumerate(nodes):
- tgt = nodes[(i + 1) % len(nodes)]
- eid = adjacency.get((src, tgt))
- if eid is not None:
- edge_ids.append(eid)
- return edge_ids
+ edges = adjacency.get(src, {}).get(nodes[(i + 1) % len(nodes)], [])
+ if edges:
+ edge_ids.append(edges[0].id)
+ leg_kinds.append(sorted({e.kind for e in edges}))
+ return DependencyCycle(nodes=list(nodes), edge_ids=edge_ids, leg_kinds=leg_kinds)
def detect_cycles(graph: SystemGraph) -> tuple[list[DependencyCycle], int]:
@@ -122,7 +129,7 @@ def detect_cycles(graph: SystemGraph) -> tuple[list[DependencyCycle], int]:
cap instead. Returns ``([], 0)`` when the structural subgraph is acyclic or
NetworkX is unavailable.
"""
- adjacency = _structural_adjacency(graph.edges)
+ adjacency = graph.adjacency()
if not adjacency:
return [], 0
@@ -134,14 +141,14 @@ def detect_cycles(graph: SystemGraph) -> tuple[list[DependencyCycle], int]:
digraph = nx.DiGraph()
digraph.add_nodes_from(n.id for n in graph.nodes)
- digraph.add_edges_from(adjacency.keys())
+ digraph.add_edges_from((src, tgt) for src, targets in adjacency.items() for tgt in targets)
cycles: list[DependencyCycle] = []
try:
for raw in nx.simple_cycles(digraph):
- edge_ids = _cycle_edges(raw, adjacency)
- if edge_ids:
- cycles.append(DependencyCycle(nodes=list(raw), edge_ids=edge_ids))
+ cycle = _cycle(raw, adjacency)
+ if cycle.edge_ids:
+ cycles.append(cycle)
except Exception: # pragma: no cover - defensive
_log.warning("cycle enumeration failed", exc_info=True)
return [], 0
diff --git a/packages/core/src/repowise/core/workspace/extractors/data/ddl.py b/packages/core/src/repowise/core/workspace/extractors/data/ddl.py
index 8032e3de5..2a48be54d 100644
--- a/packages/core/src/repowise/core/workspace/extractors/data/ddl.py
+++ b/packages/core/src/repowise/core/workspace/extractors/data/ddl.py
@@ -4,7 +4,7 @@ A ``CREATE TABLE`` / ``CREATE VIEW`` in a repo's schema files or migrations is
the strongest ownership signal there is. Parsed with sqlglot in permissive
mode (same engine as the ingestion SQL handler): a statement that fails to
parse contributes nothing, never a guess. ``ALTER TABLE`` in migrations also
-asserts ownership (the repo evolves that table) at slightly lower confidence.
+asserts ownership (the repo evolves that table), marked ``schema: alter``.
"""
from __future__ import annotations
@@ -12,8 +12,10 @@ from __future__ import annotations
import logging
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import ScanContext
-from .dialect import ALTER_CONFIDENCE, build_table_provider
+from .dialect import build_table_provider
if TYPE_CHECKING:
from repowise.core.workspace.contracts import Contract
@@ -57,7 +59,6 @@ class DdlDialect:
if stmt is None:
continue
raw: str | None = None
- confidence = 0.85
schema = "create"
if isinstance(stmt, exp.Create) and (stmt.kind or "").upper() in _CREATE_KINDS:
target = stmt.this
@@ -66,13 +67,12 @@ class DdlDialect:
raw = _qualified_name(target)
elif isinstance(stmt, exp.Alter) and (stmt.args.get("kind") or "").upper() == "TABLE":
raw = _qualified_name(stmt.this)
- confidence = ALTER_CONFIDENCE
schema = "alter"
if raw is None or raw in seen:
continue
seen.add(raw)
contract = build_table_provider(
- ctx, table_raw=raw, framework="sql-ddl", confidence=confidence, schema=schema
+ ctx, table_raw=raw, framework="sql-ddl", origin=ContractOrigin.DDL, schema=schema
)
if contract is not None:
out.append(contract)
diff --git a/packages/core/src/repowise/core/workspace/extractors/data/dialect.py b/packages/core/src/repowise/core/workspace/extractors/data/dialect.py
index 4438b4394..64fd8c450 100644
--- a/packages/core/src/repowise/core/workspace/extractors/data/dialect.py
+++ b/packages/core/src/repowise/core/workspace/extractors/data/dialect.py
@@ -13,6 +13,8 @@ import re
from collections.abc import Callable
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import line_at
from ..dialect import build_contract
from .names import normalize_table_name
@@ -29,7 +31,7 @@ def build_table_provider(
table_raw: str,
framework: str,
line: int | None = None,
- confidence: float = 0.85,
+ origin: ContractOrigin = ContractOrigin.EXPLICIT_TABLE,
schema: str | None = None,
) -> Contract | None:
"""Build a provider contract for a declared table, or ``None``.
@@ -49,7 +51,7 @@ def build_table_provider(
contract_type="data",
role="provider",
symbol_name=f"{framework}:{table_raw}",
- confidence=confidence,
+ origin=origin,
line=line,
meta={"table": table, "framework": framework, **({"schema": schema} if schema else {})},
)
@@ -62,7 +64,7 @@ def build_table_consumer(
verb: str,
client: str,
line: int | None = None,
- confidence: float = 0.7,
+ origin: ContractOrigin = ContractOrigin.CLIENT_CALL,
) -> Contract | None:
"""Build a consumer contract for a table referenced from app code.
@@ -79,7 +81,7 @@ def build_table_consumer(
contract_type="data",
role="consumer",
symbol_name=f"{client}:{verb} {table}",
- confidence=confidence,
+ origin=origin,
line=line,
meta={"table": table, "verb": verb, "client": client},
)
@@ -102,20 +104,14 @@ def dedup_consumers(
return out
-EXPLICIT_CONFIDENCE = 0.85
-CONVENTION_CONFIDENCE = 0.6
-# A declaration that evolves a table (``ALTER TABLE``, ``Schema::table``).
-ALTER_CONFIDENCE = 0.8
-
-
-#: One table declaration: ``(raw_name, confidence, line)``.
-_Found = tuple[str, float, int]
+#: One table declaration: ``(raw_name, origin, line)``.
+_Found = tuple[str, ContractOrigin, int]
def found_names(
pattern: re.Pattern[str],
content: str,
- confidence: float,
+ origin: ContractOrigin,
transform: Callable[[str], str] = str,
) -> list[_Found]:
r"""Every match of *pattern*'s first group, with the line it sits on.
@@ -126,7 +122,7 @@ def found_names(
declaration.
"""
return [
- (transform(m.group(1)), confidence, line_at(content, m.start(1)))
+ (transform(m.group(1)), origin, line_at(content, m.start(1)))
for m in pattern.finditer(content)
]
@@ -142,7 +138,7 @@ def dedup_emit(
"""One provider per raw name in *found*, skipping names already in *seen*."""
out: list[Contract] = []
seen = set() if seen is None else seen
- for raw, confidence, line in found:
+ for raw, origin, line in found:
if raw in seen:
continue
seen.add(raw)
@@ -151,7 +147,7 @@ def dedup_emit(
table_raw=raw,
framework=framework,
line=line,
- confidence=confidence,
+ origin=origin,
schema=schema,
)
if contract is not None:
diff --git a/packages/core/src/repowise/core/workspace/extractors/data/drizzle.py b/packages/core/src/repowise/core/workspace/extractors/data/drizzle.py
index 53376d79b..b1475ff26 100644
--- a/packages/core/src/repowise/core/workspace/extractors/data/drizzle.py
+++ b/packages/core/src/repowise/core/workspace/extractors/data/drizzle.py
@@ -12,11 +12,13 @@ import re
from functools import lru_cache
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import ScanContext, line_at
from ..calls import Call, call_sites, receiver_at
from ..langs import JS_TS
from ..strings import Arg
-from .dialect import EXPLICIT_CONFIDENCE, dedup_emit
+from .dialect import dedup_emit
if TYPE_CHECKING:
from repowise.core.workspace.contracts import Contract
@@ -56,11 +58,11 @@ class DrizzleDialect:
if bound is not None:
schemas[bound.group("name")] = names[0]
else:
- found.append((names[0], EXPLICIT_CONFIDENCE, line_at(content, m.start())))
+ found.append((names[0], ContractOrigin.EXPLICIT_TABLE, line_at(content, m.start())))
if schemas:
for _call, args, m, strings in call_sites(ctx, _schema_tables(tuple(sorted(schemas)))):
names, refused = strings.resolve(args[:1], _FIRST)
if names and not refused and receiver_at(content, m.start()):
table = f"{schemas[m.group('schema')]}.{names[0]}"
- found.append((table, EXPLICIT_CONFIDENCE, line_at(content, m.start())))
+ found.append((table, ContractOrigin.EXPLICIT_TABLE, line_at(content, m.start())))
return dedup_emit(ctx, self.name, found)
diff --git a/packages/core/src/repowise/core/workspace/extractors/data/knex.py b/packages/core/src/repowise/core/workspace/extractors/data/knex.py
index c77c07a57..1003a11a4 100644
--- a/packages/core/src/repowise/core/workspace/extractors/data/knex.py
+++ b/packages/core/src/repowise/core/workspace/extractors/data/knex.py
@@ -19,11 +19,13 @@ import re
from functools import lru_cache
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import ScanContext, line_at
from ..calls import Call, call_chain, call_sites, receiver_at
from ..langs import JS_TS
from ..strings import Arg, match_paren
-from .dialect import ALTER_CONFIDENCE, EXPLICIT_CONFIDENCE, dedup_consumers, dedup_emit
+from .dialect import dedup_consumers, dedup_emit
if TYPE_CHECKING:
from repowise.core.workspace.contracts import Contract
@@ -99,8 +101,7 @@ class KnexDialect:
continue
table = f"{schemas[0]}.{table}"
kind = _SCHEMA_OPS[m.group("op")]
- confidence = EXPLICIT_CONFIDENCE if kind == "create" else ALTER_CONFIDENCE
- found[kind].append((table, confidence, line_at(ctx.content, m.start())))
+ found[kind].append((table, ContractOrigin.DDL, line_at(ctx.content, m.start())))
return dedup_emit(ctx, self.name, found["create"], schema="create") + dedup_emit(
ctx, self.name, found["alter"], schema="alter"
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/data/laravel.py b/packages/core/src/repowise/core/workspace/extractors/data/laravel.py
index d5c3ea778..9f7c744a3 100644
--- a/packages/core/src/repowise/core/workspace/extractors/data/laravel.py
+++ b/packages/core/src/repowise/core/workspace/extractors/data/laravel.py
@@ -17,13 +17,11 @@ import re
from typing import TYPE_CHECKING
from repowise.core.ingestion.framework_routes import scan_code
+from repowise.core.workspace.origins import ContractOrigin
from ..base import ScanContext, line_at
from ..langs import PHP
from .dialect import (
- ALTER_CONFIDENCE,
- CONVENTION_CONFIDENCE,
- EXPLICIT_CONFIDENCE,
dedup_consumers,
dedup_emit,
found_names,
@@ -58,12 +56,12 @@ class EloquentDialect:
_ELOQUENT_IMPORT = ("Illuminate\\Database\\Eloquent", "Illuminate\\Foundation\\Auth")
def extract(self, ctx: ScanContext) -> list[Contract]:
- found = found_names(self._TABLE_RE, ctx.content, EXPLICIT_CONFIDENCE)
+ found = found_names(self._TABLE_RE, ctx.content, ContractOrigin.EXPLICIT_TABLE)
if not found and any(i in ctx.content for i in self._ELOQUENT_IMPORT):
found = found_names(
self._MODEL_CLASS_RE,
ctx.content,
- CONVENTION_CONFIDENCE,
+ ContractOrigin.NAME_CONVENTION,
lambda cls: pluralize(snake_case(cls)),
)
return dedup_emit(ctx, self.name, found)
@@ -82,8 +80,8 @@ class LaravelMigrationDialect:
def extract(self, ctx: ScanContext) -> list[Contract]:
if "Schema::" not in ctx.content:
return [] # far cheaper than the regexes, which have no literal prefix
- created = found_names(self._CREATE_RE, ctx.content, EXPLICIT_CONFIDENCE)
- altered = found_names(self._ALTER_RE, ctx.content, ALTER_CONFIDENCE)
+ created = found_names(self._CREATE_RE, ctx.content, ContractOrigin.DDL)
+ altered = found_names(self._ALTER_RE, ctx.content, ContractOrigin.DDL)
return dedup_emit(ctx, self.name, created, schema="create") + dedup_emit(
ctx, self.name, altered, schema="alter"
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/data/orm_models.py b/packages/core/src/repowise/core/workspace/extractors/data/orm_models.py
index 701b3cffa..00c507172 100644
--- a/packages/core/src/repowise/core/workspace/extractors/data/orm_models.py
+++ b/packages/core/src/repowise/core/workspace/extractors/data/orm_models.py
@@ -17,9 +17,11 @@ from __future__ import annotations
import re
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import ScanContext
from ..langs import CSHARP, JAVA, KOTLIN, PYTHON, RUBY
-from .dialect import CONVENTION_CONFIDENCE, EXPLICIT_CONFIDENCE, dedup_emit, found_names
+from .dialect import dedup_emit, found_names
from .names import pluralize, snake_case
if TYPE_CHECKING:
@@ -41,11 +43,11 @@ class SqlAlchemyDjangoDialect:
def extract(self, ctx: ScanContext) -> list[Contract]:
# A migration's `create_table` defines the schema; the rest model it.
seen: set[str] = set()
- created = found_names(self._CREATE_TABLE_RE, ctx.content, EXPLICIT_CONFIDENCE)
+ created = found_names(self._CREATE_TABLE_RE, ctx.content, ContractOrigin.DDL)
out = dedup_emit(ctx, self.name, created, schema="create", seen=seen)
- found = found_names(self._TABLENAME_RE, ctx.content, EXPLICIT_CONFIDENCE)
- found += found_names(self._DB_TABLE_RE, ctx.content, EXPLICIT_CONFIDENCE)
- found += found_names(self._SQLMODEL_RE, ctx.content, CONVENTION_CONFIDENCE, str.lower)
+ found = found_names(self._TABLENAME_RE, ctx.content, ContractOrigin.EXPLICIT_TABLE)
+ found += found_names(self._DB_TABLE_RE, ctx.content, ContractOrigin.EXPLICIT_TABLE)
+ found += found_names(self._SQLMODEL_RE, ctx.content, ContractOrigin.NAME_CONVENTION, str.lower)
return out + dedup_emit(ctx, self.name, found, seen=seen)
@@ -62,12 +64,12 @@ class JpaDialect:
)
def extract(self, ctx: ScanContext) -> list[Contract]:
- found = found_names(self._TABLE_RE, ctx.content, EXPLICIT_CONFIDENCE)
+ found = found_names(self._TABLE_RE, ctx.content, ContractOrigin.EXPLICIT_TABLE)
if not found:
# Only fall back to the class-name convention when no explicit
# @Table names the table (one entity per file is the JPA norm).
found = found_names(
- self._ENTITY_CLASS_RE, ctx.content, CONVENTION_CONFIDENCE, snake_case
+ self._ENTITY_CLASS_RE, ctx.content, ContractOrigin.NAME_CONVENTION, snake_case
)
return dedup_emit(ctx, self.name, found)
@@ -82,8 +84,8 @@ class EfCoreDialect:
_DBSET_RE = re.compile(r"\bDbSet<\s*\w+\s*>\s+(\w+)")
def extract(self, ctx: ScanContext) -> list[Contract]:
- found = found_names(self._TABLE_ATTR_RE, ctx.content, EXPLICIT_CONFIDENCE)
- found += found_names(self._DBSET_RE, ctx.content, CONVENTION_CONFIDENCE)
+ found = found_names(self._TABLE_ATTR_RE, ctx.content, ContractOrigin.EXPLICIT_TABLE)
+ found += found_names(self._DBSET_RE, ctx.content, ContractOrigin.NAME_CONVENTION)
return dedup_emit(ctx, self.name, found)
@@ -99,12 +101,12 @@ class ActiveRecordDialect:
)
def extract(self, ctx: ScanContext) -> list[Contract]:
- found = found_names(self._TABLE_NAME_RE, ctx.content, EXPLICIT_CONFIDENCE)
+ found = found_names(self._TABLE_NAME_RE, ctx.content, ContractOrigin.EXPLICIT_TABLE)
if not found:
found = found_names(
self._MODEL_CLASS_RE,
ctx.content,
- CONVENTION_CONFIDENCE,
+ ContractOrigin.NAME_CONVENTION,
lambda m: pluralize(snake_case(m)),
)
return dedup_emit(ctx, self.name, found)
diff --git a/packages/core/src/repowise/core/workspace/extractors/data/prisma.py b/packages/core/src/repowise/core/workspace/extractors/data/prisma.py
index 0126efc4c..4bb37a9d1 100644
--- a/packages/core/src/repowise/core/workspace/extractors/data/prisma.py
+++ b/packages/core/src/repowise/core/workspace/extractors/data/prisma.py
@@ -13,8 +13,10 @@ from __future__ import annotations
import re
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import ScanContext, line_at
-from .dialect import EXPLICIT_CONFIDENCE, dedup_emit
+from .dialect import dedup_emit
if TYPE_CHECKING:
from repowise.core.workspace.contracts import Contract
@@ -42,5 +44,5 @@ class PrismaDialect:
table = mapped.group(1) if mapped else m.group(1)
if schema:
table = f"{schema.group(1)}.{table}"
- found.append((table, EXPLICIT_CONFIDENCE, line_at(content, m.start(1))))
+ found.append((table, ContractOrigin.EXPLICIT_TABLE, line_at(content, m.start(1))))
return dedup_emit(ctx, self.name, found)
diff --git a/packages/core/src/repowise/core/workspace/extractors/data/sequelize.py b/packages/core/src/repowise/core/workspace/extractors/data/sequelize.py
index 6d44a06e7..ea87612da 100644
--- a/packages/core/src/repowise/core/workspace/extractors/data/sequelize.py
+++ b/packages/core/src/repowise/core/workspace/extractors/data/sequelize.py
@@ -16,11 +16,13 @@ from __future__ import annotations
import re
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import ScanContext, line_at
from ..calls import Call, call_sites, decorated_member, file_strings, receiver_name
from ..langs import JS_TS
from ..strings import Arg, call_arguments, match_paren, on_comment_line, select_argument
-from .dialect import CONVENTION_CONFIDENCE, EXPLICIT_CONFIDENCE, dedup_emit
+from .dialect import dedup_emit
from .names import pluralize, snake_case
if TYPE_CHECKING:
@@ -50,7 +52,7 @@ def _table(model: str, options: list[str], strings: FileStrings) -> tuple[str, f
if refused:
return None
if names:
- return names[0], EXPLICIT_CONFIDENCE
+ return names[0], ContractOrigin.EXPLICIT_TABLE
modelled, refused = strings.resolve(options, Arg(keys=("modelName",)))
if refused:
return None
@@ -60,7 +62,7 @@ def _table(model: str, options: list[str], strings: FileStrings) -> tuple[str, f
name = pluralize(name)
if _flag(options, "underscored"):
name = snake_case(name)
- return name, CONVENTION_CONFIDENCE
+ return name, ContractOrigin.NAME_CONVENTION
class SequelizeDialect:
diff --git a/packages/core/src/repowise/core/workspace/extractors/data/sql_strings.py b/packages/core/src/repowise/core/workspace/extractors/data/sql_strings.py
index d9d9ce111..8c50c5668 100644
--- a/packages/core/src/repowise/core/workspace/extractors/data/sql_strings.py
+++ b/packages/core/src/repowise/core/workspace/extractors/data/sql_strings.py
@@ -19,6 +19,8 @@ import logging
import re
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import ScanContext, line_at
from ..langs import CSHARP, GO, JAVA, JS_TS, KOTLIN, PHP, PYTHON, RUBY
from .dialect import build_table_consumer
@@ -135,7 +137,12 @@ class SqlStringsDialect:
continue
seen.add(key)
contract = build_table_consumer(
- ctx, table_raw=table_raw, verb=verb, client=self.name, line=line
+ ctx,
+ table_raw=table_raw,
+ verb=verb,
+ client=self.name,
+ line=line,
+ origin=ContractOrigin.SQL_STRING,
)
if contract is not None:
out.append(contract)
diff --git a/packages/core/src/repowise/core/workspace/extractors/data/typeorm.py b/packages/core/src/repowise/core/workspace/extractors/data/typeorm.py
index 67826cc16..6ab9197c0 100644
--- a/packages/core/src/repowise/core/workspace/extractors/data/typeorm.py
+++ b/packages/core/src/repowise/core/workspace/extractors/data/typeorm.py
@@ -12,11 +12,13 @@ from __future__ import annotations
import re
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import ScanContext, line_at
from ..calls import Call, call_sites, decorated_member
from ..langs import JS_TS
from ..strings import Arg, on_comment_line
-from .dialect import CONVENTION_CONFIDENCE, EXPLICIT_CONFIDENCE, dedup_emit
+from .dialect import dedup_emit
from .names import snake_case
if TYPE_CHECKING:
@@ -56,6 +58,6 @@ class TypeOrmDialect:
table = names[0] if names else _default_table(member.group("name"))
if schemas:
table = f"{schemas[0]}.{table}"
- confidence = EXPLICIT_CONFIDENCE if names else CONVENTION_CONFIDENCE
- found.append((table, confidence, line_at(content, m.start())))
+ origin = ContractOrigin.EXPLICIT_TABLE if names else ContractOrigin.NAME_CONVENTION
+ found.append((table, origin, line_at(content, m.start())))
return dedup_emit(ctx, self.name, found)
diff --git a/packages/core/src/repowise/core/workspace/extractors/dialect.py b/packages/core/src/repowise/core/workspace/extractors/dialect.py
index 93494fbba..50fbc1333 100644
--- a/packages/core/src/repowise/core/workspace/extractors/dialect.py
+++ b/packages/core/src/repowise/core/workspace/extractors/dialect.py
@@ -11,6 +11,8 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Protocol
+from repowise.core.workspace.origins import ContractOrigin, origin_confidence
+
from .base import ScanContext, select_files
if TYPE_CHECKING:
@@ -55,11 +57,16 @@ def build_contract(
contract_id: str,
role: str,
symbol_name: str,
- confidence: float,
+ origin: ContractOrigin,
line: int | None,
meta: dict,
) -> Contract:
- """A :class:`Contract` read from *ctx*'s file. The service is assigned later."""
+ """A :class:`Contract` read from *ctx*'s file. The service is assigned later.
+
+ A dialect declares *origin*, what established the contract, from the closed
+ vocabulary in :mod:`..origins`; the confidence is the origin's, never a
+ number of the dialect's own.
+ """
from repowise.core.workspace.contracts import Contract
return Contract(
@@ -69,10 +76,11 @@ def build_contract(
role=role,
file_path=ctx.rel_path,
symbol_name=symbol_name,
- confidence=confidence,
+ confidence=origin_confidence(origin),
service=None,
line=line,
meta=meta,
+ origin=origin,
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/grpc/languages.py b/packages/core/src/repowise/core/workspace/extractors/grpc/languages.py
index 340525b63..b66d205fe 100644
--- a/packages/core/src/repowise/core/workspace/extractors/grpc/languages.py
+++ b/packages/core/src/repowise/core/workspace/extractors/grpc/languages.py
@@ -1,7 +1,7 @@
"""The generated-stub shapes gRPC produces, one table row per language.
Every language dialect was the same loop over a provider regex and a consumer
-regex, differing only in the pattern, the display wording and the confidence.
+regex, differing only in the pattern, the display wording and the origin.
The three real per-language facts are declared instead of coded: C# has two
provider shapes, TypeScript has no consumer shape and is the only one whose
match names a method, and a bare ``new XxxClient(...)`` needs a gRPC marker in
@@ -16,6 +16,8 @@ import re
from dataclasses import dataclass, field
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import line_at
from ..dialect import build_contract
from ..langs import CSHARP, GO, JAVA, JS_TS, PYTHON
@@ -26,6 +28,11 @@ if TYPE_CHECKING:
from ..base import ScanContext
+_ROUTE_REGISTRATION = ContractOrigin.ROUTE_REGISTRATION
+_CLIENT_CALL = ContractOrigin.CLIENT_CALL
+# `new XClient(` names any class so; nothing confirms it is a gRPC stub.
+_NAME_HEURISTIC = ContractOrigin.NAME_HEURISTIC
+
@dataclass(frozen=True)
class _Rule:
"""One recognisable shape. Group 1 is always the service name."""
@@ -34,7 +41,7 @@ class _Rule:
pattern: re.Pattern[str]
symbol: str # display template over {service} and {method}
source: str # meta["source"], the tag that says which shape matched
- confidence: float
+ origin: ContractOrigin
method_group: int | None = None # only a shape that names a method sets this
@@ -56,10 +63,10 @@ LANGUAGES: tuple[_Language, ...] = (
rules=(
# pb.RegisterAuthServiceServer(grpcServer, &impl{})
_Rule("provider", re.compile(r"\.Register(\w+)Server\s*\("),
- "go:Register{service}Server", "go_register", 0.8),
+ "go:Register{service}Server", "go_register", _ROUTE_REGISTRATION),
# pb.NewAuthServiceClient(conn)
_Rule("consumer", re.compile(r"\.New(\w+)Client\s*\("),
- "go:New{service}Client", "go_client", 0.7),
+ "go:New{service}Client", "go_client", _CLIENT_CALL),
),
),
_Language(
@@ -68,10 +75,10 @@ LANGUAGES: tuple[_Language, ...] = (
rules=(
# extends AuthServiceGrpc.AuthServiceImplBase
_Rule("provider", re.compile(r"extends\s+(\w+)Grpc\.(\w+)ImplBase"),
- "java:extends {service}Grpc.ImplBase", "java_extends", 0.8),
+ "java:extends {service}Grpc.ImplBase", "java_extends", _ROUTE_REGISTRATION),
# AuthServiceGrpc.newBlockingStub(channel)
_Rule("consumer", re.compile(r"(\w+)Grpc\.new(?:Blocking|Future)?Stub\s*\("),
- "java:{service}Grpc.newStub", "java_stub", 0.7),
+ "java:{service}Grpc.newStub", "java_stub", _CLIENT_CALL),
),
),
_Language(
@@ -80,10 +87,10 @@ LANGUAGES: tuple[_Language, ...] = (
rules=(
# add_AuthServiceServicer_to_server(servicer, server)
_Rule("provider", re.compile(r"add_(\w+?)Servicer_to_server\s*\("),
- "py:add_{service}Servicer_to_server", "py_servicer", 0.8),
+ "py:add_{service}Servicer_to_server", "py_servicer", _ROUTE_REGISTRATION),
# AuthServiceStub(channel)
_Rule("consumer", re.compile(r"(\w+)Stub\s*\("),
- "py:{service}Stub", "py_stub", 0.7),
+ "py:{service}Stub", "py_stub", _CLIENT_CALL),
),
false_prefixes=("mock", "test", "fake"),
),
@@ -93,7 +100,7 @@ LANGUAGES: tuple[_Language, ...] = (
rules=(
# @GrpcMethod('AuthService', 'Login') — the one shape naming a method.
_Rule("provider", re.compile(r"@GrpcMethod\s*\(\s*'(\w+)'\s*,\s*'(\w+)'\s*\)"),
- "ts:@GrpcMethod('{service}', '{method}')", "ts_decorator", 0.8,
+ "ts:@GrpcMethod('{service}', '{method}')", "ts_decorator", _ROUTE_REGISTRATION,
method_group=2),
),
),
@@ -103,14 +110,14 @@ LANGUAGES: tuple[_Language, ...] = (
rules=(
# app.MapGrpcService<GreeterService>()
_Rule("provider", re.compile(r"\.\s*MapGrpcService\s*<\s*(\w+)\s*>"),
- "cs:MapGrpcService<{service}>", "csharp_mapgrpc", 0.8),
+ "cs:MapGrpcService<{service}>", "csharp_mapgrpc", _ROUTE_REGISTRATION),
# class Impl : ServiceName.ServiceNameBase
_Rule("provider",
re.compile(r"class\s+\w+\s*:\s*(?:[\w.]+\.)?(\w+?)\s*\.\s*\1Base\b"),
- "cs:extends {service}.{service}ServiceBase", "csharp_base", 0.8),
+ "cs:extends {service}.{service}ServiceBase", "csharp_base", _ROUTE_REGISTRATION),
# new AuthServiceClient(channel)
_Rule("consumer", re.compile(r"\bnew\s+(\w+)Client\s*\("),
- "cs:new {service}Client", "csharp_client", 0.65),
+ "cs:new {service}Client", "csharp_client", _NAME_HEURISTIC),
),
consumer_gate=re.compile(
r"\bGrpcChannel\b|\bGrpc\.(?:Net|Core)\b|\bCallInvoker\b|\bChannelBase\b"
@@ -148,7 +155,7 @@ class LanguageGrpcDialect:
contract_id=f"grpc::{service}/{method or '*'}",
role=rule.role,
symbol_name=rule.symbol.format(service=service, method=method),
- confidence=rule.confidence,
+ origin=rule.origin,
meta={
"service": service,
**({"method": method} if method else {}),
diff --git a/packages/core/src/repowise/core/workspace/extractors/grpc/proto.py b/packages/core/src/repowise/core/workspace/extractors/grpc/proto.py
index 543da0816..7bfd0d3d3 100644
--- a/packages/core/src/repowise/core/workspace/extractors/grpc/proto.py
+++ b/packages/core/src/repowise/core/workspace/extractors/grpc/proto.py
@@ -18,6 +18,7 @@ import re
from typing import TYPE_CHECKING, NamedTuple
from repowise.core.workspace.contract_schema import ContractSchema, SchemaField
+from repowise.core.workspace.origins import ContractOrigin
from ..dialect import build_contract
from ..langs import PROTO
@@ -225,7 +226,7 @@ class ProtoDialect:
contract_id=f"grpc::{svc.full_path}/{method.name}",
role="provider",
symbol_name=f"{svc.full_path}/{method.name}",
- confidence=0.85,
+ origin=ContractOrigin.IDL,
meta={
"package": package,
"service": svc.name,
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/apex_callouts.py b/packages/core/src/repowise/core/workspace/extractors/http/apex_callouts.py
index 9b04d0b1f..bd9c271eb 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/apex_callouts.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/apex_callouts.py
@@ -24,6 +24,7 @@ import re
from typing import TYPE_CHECKING
from repowise.core.ingestion.framework_routes import apex_code
+from repowise.core.workspace.origins import ContractOrigin
from ..base import line_at
from ..langs import APEX
@@ -57,8 +58,6 @@ _CALLOUT_RE = re.compile(
)
_ABSOLUTE_RE = re.compile(r"https?://[^/$?]+(?:[/?]|$)", re.IGNORECASE)
-_CONFIDENCE = 0.75
-
def _blocks(code: str) -> list[tuple[int, int, bool]]:
"""``(open, close, is_type_body)`` per brace block of comment- and string-blanked *code*."""
@@ -221,7 +220,7 @@ class ApexCalloutsDialect:
url=endpoint,
client="apex-callout",
line=line_at(content, m.start()),
- confidence=_CONFIDENCE,
+ origin=ContractOrigin.CLIENT_CALL,
)
if c is not None:
c.symbol_name = f"apex-callout:{method} {url}" # as written, not rewritten
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/client_calls.py b/packages/core/src/repowise/core/workspace/extractors/http/client_calls.py
index 66574d450..77116fb14 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/client_calls.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/client_calls.py
@@ -19,6 +19,8 @@ from collections.abc import Iterable, Iterator
from dataclasses import dataclass
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import line_at
from ..strings import StringSyntax, literal_span, resolve_string
from .dialect import build_consumer_contract, method_from_callee
@@ -49,7 +51,7 @@ class ClientCallMatch:
offset: int
callee: str = ""
method: str | None = None
- confidence: float = 0.75
+ origin: ContractOrigin = ContractOrigin.CLIENT_CALL
# ---------------------------------------------------------------------------
@@ -128,7 +130,7 @@ def consumer_contracts(
url=url,
client=m.client,
line=line_at(ctx.content, m.offset),
- confidence=m.confidence,
+ origin=m.origin,
)
if c is not None:
out.append(c)
@@ -143,7 +145,7 @@ def matches_in(
url_group: int,
method_group: int | None = None,
callee_group: int | None = None,
- confidence: float = 0.75,
+ origin: ContractOrigin = ContractOrigin.CLIENT_CALL,
prefix_group: int | None = None,
) -> Iterator[ClientCallMatch]:
"""Rows for every match of *pattern* whose *url_group* captured a literal body.
@@ -163,7 +165,7 @@ def matches_in(
offset=m.start(),
callee=m.group(callee_group) if callee_group is not None else "",
method=m.group(method_group).upper() if method_group is not None else None,
- confidence=confidence,
+ origin=origin,
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/csharp_http.py b/packages/core/src/repowise/core/workspace/extractors/http/csharp_http.py
index c304048cd..240156777 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/csharp_http.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/csharp_http.py
@@ -18,6 +18,8 @@ import re
from collections.abc import Iterator
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..langs import CSHARP
from ..strings import CSHARP_SYNTAX
from .client_calls import ClientCallMatch, consumer_contracts, matches_in
@@ -48,7 +50,8 @@ _BESTHTTP_RE = re.compile(
re.IGNORECASE,
)
-_CONFIDENCE = 0.70
+# HttpClient calls are read off any receiver; its type is not confirmed.
+_ORIGIN = ContractOrigin.NAME_HEURISTIC
def httpclient_calls(content: str) -> Iterator[ClientCallMatch]:
@@ -59,7 +62,7 @@ def httpclient_calls(content: str) -> Iterator[ClientCallMatch]:
url_group=3,
prefix_group=2,
method_group=1,
- confidence=_CONFIDENCE,
+ origin=_ORIGIN,
)
@@ -71,7 +74,7 @@ def unitywebrequest_calls(content: str) -> Iterator[ClientCallMatch]:
url_group=3,
prefix_group=2,
method_group=1,
- confidence=_CONFIDENCE,
+ origin=_ORIGIN,
)
@@ -83,7 +86,7 @@ def besthttp_calls(content: str) -> Iterator[ClientCallMatch]:
url_group=2,
prefix_group=1,
method_group=3,
- confidence=_CONFIDENCE,
+ origin=_ORIGIN,
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/dialect.py b/packages/core/src/repowise/core/workspace/extractors/http/dialect.py
index ba284f267..ebe031850 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/dialect.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/dialect.py
@@ -11,6 +11,8 @@ from __future__ import annotations
import re
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..dialect import build_contract
from .paths import (
absolute_host,
@@ -77,7 +79,7 @@ def build_provider_contract(
path_raw: str,
framework: str,
line: int | None = None,
- confidence: float = 0.85,
+ origin: ContractOrigin = ContractOrigin.ROUTE_REGISTRATION,
handler: str | None = None,
) -> Contract | None:
"""Build a provider contract, or ``None`` if the path is unusable.
@@ -101,7 +103,7 @@ def build_provider_contract(
contract_type="http",
role="provider",
symbol_name=f"{framework}:{method} {path_raw}",
- confidence=confidence,
+ origin=origin,
line=line,
meta={
"method": method,
@@ -119,7 +121,7 @@ def build_consumer_contract(
url: str,
client: str,
line: int | None = None,
- confidence: float = 0.75,
+ origin: ContractOrigin = ContractOrigin.CLIENT_CALL,
) -> Contract | None:
"""Build a consumer contract from a raw client-call URL.
@@ -142,7 +144,7 @@ def build_consumer_contract(
contract_type="http",
role="consumer",
symbol_name=f"{client}:{method} {url}",
- confidence=confidence,
+ origin=origin,
line=line,
meta=consumer_meta(method, norm_path, client, base_token, host),
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/index_clients.py b/packages/core/src/repowise/core/workspace/extractors/http/index_clients.py
index 439a6ef98..c1b04277f 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/index_clients.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/index_clients.py
@@ -30,6 +30,8 @@ from __future__ import annotations
import re
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import line_at
from ..calls import FileStrings
from ..langs import PYTHON
@@ -271,7 +273,7 @@ def extract_consumers(
# sink-reaching wrapper and the URL is a whole literal argument, not a
# string that happened to sit next to a parenthesis.
contract = build_consumer_contract(
- ctx, method=method, url=url, client=callee, line=line, confidence=0.85
+ ctx, method=method, url=url, client=callee, line=line, origin=ContractOrigin.TYPED_CLIENT
)
if contract is not None:
contract.meta[EXTRACTION_LAYER_KEY] = LAYER_INDEX
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/java_clients.py b/packages/core/src/repowise/core/workspace/extractors/http/java_clients.py
index b41574758..d80a7a1a8 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/java_clients.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/java_clients.py
@@ -25,6 +25,8 @@ import re
from collections.abc import Iterator
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..langs import JAVA
from ..strings import JAVA_SYNTAX, call_arguments, match_paren, string_constants
from .client_calls import VERBS, ClientCallMatch, consumer_contracts, method_from_argument
@@ -57,9 +59,6 @@ _REST_TEMPLATE_RE = re.compile(
r"\s*\("
)
-_FEIGN_CONFIDENCE = 0.75
-_BUILDER_CONFIDENCE = 0.75
-_REST_TEMPLATE_CONFIDENCE = 0.65
def feign_calls(content: str) -> Iterator[ClientCallMatch]:
@@ -74,7 +73,7 @@ def feign_calls(content: str) -> Iterator[ClientCallMatch]:
url=f'"{m.group(2).strip()}"',
offset=m.start(),
method=verb.upper(),
- confidence=_FEIGN_CONFIDENCE,
+ origin=ContractOrigin.CLIENT_CALL,
)
@@ -131,7 +130,7 @@ def java_net_http_calls(content: str) -> Iterator[ClientCallMatch]:
url=url,
offset=m.start(),
method=method,
- confidence=_BUILDER_CONFIDENCE,
+ origin=ContractOrigin.CLIENT_CALL,
)
@@ -157,7 +156,7 @@ def resttemplate_calls(content: str) -> Iterator[ClientCallMatch]:
offset=m.start(),
callee=callee,
method=method,
- confidence=_REST_TEMPLATE_CONFIDENCE,
+ origin=ContractOrigin.NAME_HEURISTIC,
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/js_clients.py b/packages/core/src/repowise/core/workspace/extractors/http/js_clients.py
index 39d1612a6..20f446e1d 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/js_clients.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/js_clients.py
@@ -14,6 +14,8 @@ import re
from collections.abc import Iterator
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..calls import receiver_name
from ..langs import JS_TS
from ..strings import JS_SYNTAX, literal_span, string_constants
@@ -107,7 +109,7 @@ def wrapper_calls(content: str, clients: frozenset[str]) -> Iterator[ClientCallM
offset=m.start(),
callee=callee,
method=method_opt.group(1).upper() if method_opt else None,
- confidence=0.65,
+ origin=ContractOrigin.NAME_HEURISTIC,
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/kotlin_clients.py b/packages/core/src/repowise/core/workspace/extractors/http/kotlin_clients.py
index ebc063718..cfab3d1c2 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/kotlin_clients.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/kotlin_clients.py
@@ -29,6 +29,8 @@ import re
from collections.abc import Iterator
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..langs import KOTLIN
from ..strings import KOTLIN_SYNTAX, call_arguments, match_paren, string_constants
from .client_calls import ClientCallMatch, consumer_contracts, method_from_argument
@@ -64,7 +66,7 @@ _NAMED_ARG_RE = re.compile(r"([A-Za-z_]\w*)\s*=(?!=)\s*(.*)", re.DOTALL)
# The identifier a call hangs off, when the receiver is a plain name.
_RECEIVER_RE = re.compile(r"[A-Za-z_]\w*$")
-_CONFIDENCE = 0.65
+_ORIGIN = ContractOrigin.NAME_HEURISTIC # the receiver's type is unknown
def _block_end(content: str, open_idx: int) -> int:
@@ -149,7 +151,7 @@ def ktor_calls(content: str) -> Iterator[ClientCallMatch]:
url=args[0],
offset=m.start(),
method=m.group(1).upper(),
- confidence=_CONFIDENCE,
+ origin=_ORIGIN,
)
for m in _VERB_BLOCK_RE.finditer(content):
@@ -166,7 +168,7 @@ def ktor_calls(content: str) -> Iterator[ClientCallMatch]:
url=url,
offset=m.start(),
method=m.group(1).upper(),
- confidence=_CONFIDENCE,
+ origin=_ORIGIN,
)
for m in _REQUEST_RE.finditer(content):
@@ -199,7 +201,7 @@ def ktor_calls(content: str) -> Iterator[ClientCallMatch]:
url=url,
offset=m.start(),
method=method,
- confidence=_CONFIDENCE,
+ origin=_ORIGIN,
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/node_clients.py b/packages/core/src/repowise/core/workspace/extractors/http/node_clients.py
index 691c1f6c5..64029e1ff 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/node_clients.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/node_clients.py
@@ -30,6 +30,8 @@ from dataclasses import dataclass
from functools import lru_cache
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import line_at
from ..calls import Call, call_sites, file_strings, receiver_at
from ..langs import JS_EXTENSION_RE, JS_TS
@@ -420,7 +422,12 @@ def client_calls(ctx: ScanContext) -> tuple[list[Contract], frozenset[str]]:
if not is_rooted_url(url):
continue # relative to a base this cannot see
c = build_consumer_contract(
- ctx, method=method, url=url, client=client.library.name, line=line_at(content, m.start())
+ ctx,
+ method=method,
+ url=url,
+ client=client.library.name,
+ line=line_at(content, m.start()),
+ origin=ContractOrigin.INSTANCE_BASE if client.base else ContractOrigin.CLIENT_CALL,
)
if c is not None:
out.append(c)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/php_clients.py b/packages/core/src/repowise/core/workspace/extractors/http/php_clients.py
index dcfd34ea8..6103d1a04 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/php_clients.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/php_clients.py
@@ -23,6 +23,8 @@ import re
from collections.abc import Iterator
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..langs import PHP
from ..strings import PHP_SYNTAX, call_arguments, match_paren, string_constants
from .client_calls import VERBS, ClientCallMatch, consumer_contracts, method_from_argument
@@ -51,8 +53,6 @@ _CHAIN_ARROW_RE = re.compile(r"\s*->\s*")
# How far along a builder chain the verb call is looked for.
_MAX_CHAIN_LINKS = 8
-_AMBIGUOUS_RECEIVER_CONFIDENCE = 0.65
-
def _names_a_client(content: str) -> bool:
return "Client" in content and _GUZZLE_GATE_RE.search(content) is not None
@@ -92,7 +92,7 @@ def guzzle_verb_calls(content: str) -> Iterator[ClientCallMatch]:
url=args[0],
offset=m.start(),
method=m.group(1).upper(),
- confidence=_AMBIGUOUS_RECEIVER_CONFIDENCE,
+ origin=ContractOrigin.NAME_HEURISTIC,
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/ruby_clients.py b/packages/core/src/repowise/core/workspace/extractors/http/ruby_clients.py
index bc4aa1678..3cb27f55a 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/ruby_clients.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/ruby_clients.py
@@ -27,6 +27,8 @@ import re
from collections.abc import Iterator
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..langs import RUBY
from ..strings import RUBY_SYNTAX, call_arguments, match_paren, split_first_arg, string_constants
from .client_calls import ClientCallMatch, consumer_contracts, method_from_argument
@@ -51,8 +53,6 @@ _REQUEST_OBJECT_RE = re.compile(r"\.request\s*\(\s*(Net::HTTP::\w+)\.new\s*\(")
_FARADAY_NEW_RE = re.compile(r"(?<![.\w])(@?[a-z_]\w*)\s*=\s*Faraday\.new\b")
-_CONNECTION_CONFIDENCE = 0.65
-
def _first_argument(content: str, end: int) -> str | None:
"""The URL argument of the call whose callee ends at *end*.
@@ -135,7 +135,7 @@ def faraday_connection_calls(content: str) -> Iterator[ClientCallMatch]:
url=args[0],
offset=m.start(),
method=m.group(2).upper(),
- confidence=_CONNECTION_CONFIDENCE,
+ origin=ContractOrigin.NAME_HEURISTIC, # read off a connection whose base is unread
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/rust_clients.py b/packages/core/src/repowise/core/workspace/extractors/http/rust_clients.py
index 6c0e92dda..62e4d0230 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/rust_clients.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/rust_clients.py
@@ -17,6 +17,8 @@ import re
from collections.abc import Iterator
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..langs import RUST
from ..strings import RUST_SYNTAX
from .client_calls import ClientCallMatch, consumer_contracts, matches_in
@@ -37,13 +39,13 @@ _METHOD_FMT_RE = re.compile(rf"""\.({_VERBS})\s*\(\s*&?\s*(format!\s*\(\s*"[^"]*
# reqwest::get(format!("...", ...))
_FREE_FMT_RE = re.compile(rf"""\breqwest::({_VERBS})\s*\(\s*&?\s*(format!\s*\(\s*"[^"]*")""")
-_CONFIDENCE = 0.65
+_ORIGIN = ContractOrigin.NAME_HEURISTIC # `.get(` on any receiver
def reqwest_calls(content: str) -> Iterator[ClientCallMatch]:
for rx in (_METHOD_LIT_RE, _FREE_LIT_RE):
yield from matches_in(
- content, rx, client="reqwest", url_group=2, method_group=1, confidence=_CONFIDENCE
+ content, rx, client="reqwest", url_group=2, method_group=1, origin=_ORIGIN
)
for rx in (_METHOD_FMT_RE, _FREE_FMT_RE):
for m in rx.finditer(content):
@@ -54,7 +56,7 @@ def reqwest_calls(content: str) -> Iterator[ClientCallMatch]:
url=m.group(2) + ")",
offset=m.start(),
method=m.group(1).upper(),
- confidence=_CONFIDENCE,
+ origin=_ORIGIN,
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/masstransit.py b/packages/core/src/repowise/core/workspace/extractors/masstransit.py
index 67a0c06ea..c8778e667 100644
--- a/packages/core/src/repowise/core/workspace/extractors/masstransit.py
+++ b/packages/core/src/repowise/core/workspace/extractors/masstransit.py
@@ -23,6 +23,7 @@ from repowise.core.ingestion.resolvers.dotnet.namespace_map import (
declared_namespaces,
scan_type_declarations,
)
+from repowise.core.workspace.origins import ContractOrigin, origin_confidence
from ..config import DEFAULT_CONTRACT_PROJECT_PATTERN
from .base import line_at, select_files
@@ -39,9 +40,10 @@ _TEST_DIR_RE = re.compile(
r"^.+\.(?:tests?|unittests?|integrationtests?|specs?|testing|testhelpers?)$", re.IGNORECASE
)
-_TIER_DECLARED = 0.8
-_TIER_UNIQUE_NAME = 0.6
-_TIER_DATAFLOW = 0.7
+# A type named through a using or its namespace is the library call's own
+# argument; one found by its short name alone is a naming convention.
+_TIER_DECLARED = ContractOrigin.CLIENT_CALL
+_TIER_UNIQUE_NAME = ContractOrigin.NAME_CONVENTION
# ---------------------------------------------------------------------------
@@ -164,7 +166,7 @@ def _file_context(masked: str, vb: bool) -> _FileContext:
@dataclass(frozen=True)
class _Resolved:
fqn: str
- confidence: float
+ origin: ContractOrigin
resolution: str
@@ -1191,7 +1193,10 @@ class MassTransitExtractor:
}
if f.receiver is not None:
meta["receiver"] = f.receiver
- confidence = min(res.confidence, _TIER_DATAFLOW) if f.dataflow else res.confidence
+ # A type traced across statements is no stronger than the trace.
+ origin = res.origin
+ if f.dataflow:
+ origin = min(res.origin, ContractOrigin.DATAFLOW, key=origin_confidence)
contracts.append(
Contract(
repo=repo_alias,
@@ -1200,7 +1205,8 @@ class MassTransitExtractor:
role=f.role,
file_path=rel_path,
symbol_name=f.symbol,
- confidence=confidence,
+ confidence=origin_confidence(origin),
+ origin=origin,
service=None,
line=f.line if f.line is not None else line_at(content, f.offset),
meta=meta,
diff --git a/packages/core/src/repowise/core/workspace/extractors/openapi.py b/packages/core/src/repowise/core/workspace/extractors/openapi.py
index 05f3f9d6d..60003739f 100644
--- a/packages/core/src/repowise/core/workspace/extractors/openapi.py
+++ b/packages/core/src/repowise/core/workspace/extractors/openapi.py
@@ -23,6 +23,7 @@ from repowise.core.workspace.contract_schema import (
SchemaField,
SchemaIssue,
)
+from repowise.core.workspace.origins import ContractOrigin, origin_confidence
from .base import SourceFile, select_files
from .from_index import EXTRACTION_LAYER_KEY
@@ -573,7 +574,8 @@ def _operation_contract(
role="provider",
file_path=rel_path,
symbol_name=f"openapi:{method.upper()} {path}",
- confidence=0.98,
+ confidence=origin_confidence(ContractOrigin.IDL),
+ origin=ContractOrigin.IDL,
meta={
EXTRACTION_LAYER_KEY: OPENAPI_EXTRACTION_LAYER,
"openapi_version": version,
diff --git a/packages/core/src/repowise/core/workspace/extractors/socket/dialect.py b/packages/core/src/repowise/core/workspace/extractors/socket/dialect.py
index f90fa9271..0f17da410 100644
--- a/packages/core/src/repowise/core/workspace/extractors/socket/dialect.py
+++ b/packages/core/src/repowise/core/workspace/extractors/socket/dialect.py
@@ -21,6 +21,8 @@ import re
from dataclasses import dataclass
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..base import line_at
from ..calls import call_sites
from ..dialect import build_contract
@@ -75,7 +77,7 @@ class SocketCall:
label: str
extensions: frozenset[str]
name: Arg
- confidence: float = 0.8
+ origin: ContractOrigin = ContractOrigin.CLIENT_CALL
requires: tuple[str, ...] = ()
normalize: Callable[[str], str | None] = path_identity
@@ -86,7 +88,7 @@ def _socket_contract(
contract_id: str,
role: str,
symbol: str,
- confidence: float,
+ origin: ContractOrigin,
offset: int,
meta: dict[str, str],
) -> Contract:
@@ -96,7 +98,7 @@ def _socket_contract(
contract_id=f"socket::{contract_id}",
role=role,
symbol_name=symbol,
- confidence=confidence,
+ origin=origin,
line=line_at(ctx.content, offset),
meta=meta,
)
@@ -110,7 +112,7 @@ def event_contract(
role: str,
transport: str,
label: str,
- confidence: float,
+ origin: ContractOrigin,
offset: int,
) -> Contract:
"""One message: *event* within *scope*, emitted by a provider, received by a consumer."""
@@ -119,7 +121,7 @@ def event_contract(
contract_id=f"{scope}#{event}",
role=role,
symbol=f"{label}('{event}')",
- confidence=confidence,
+ origin=origin,
offset=offset,
meta={"scope": scope, "event": event, "transport": transport},
)
@@ -142,7 +144,7 @@ def event_contracts(
role=call.role,
transport=call.transport,
label=label or call.label,
- confidence=call.confidence,
+ origin=call.origin,
offset=offset,
)
for scope in scopes
@@ -168,7 +170,7 @@ class SocketDialect:
contract_id=path,
role=call.role,
symbol=f"{call.label}('{path}')",
- confidence=call.confidence,
+ origin=call.origin,
offset=m.start(),
meta={"path": path, "transport": call.transport},
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/socket/dotnet.py b/packages/core/src/repowise/core/workspace/extractors/socket/dotnet.py
index 32f2e257d..8c9ec825b 100644
--- a/packages/core/src/repowise/core/workspace/extractors/socket/dotnet.py
+++ b/packages/core/src/repowise/core/workspace/extractors/socket/dotnet.py
@@ -8,6 +8,8 @@ from __future__ import annotations
import re
+from repowise.core.workspace.origins import ContractOrigin
+
from ..langs import CSHARP
from ..strings import Arg
from .dialect import SocketCall, SocketDialect
@@ -24,7 +26,6 @@ DOTNET = SocketDialect(
label="ClientWebSocket.ConnectAsync",
extensions=CSHARP,
name=_URL,
- confidence=0.75,
),
SocketCall(
head=re.compile(r"\bWithUrl\s*\(", re.IGNORECASE),
@@ -42,7 +43,6 @@ DOTNET = SocketDialect(
label="NativeWebSocket.WebSocket",
extensions=CSHARP,
name=_URL,
- confidence=0.75,
requires=("NativeWebSocket",),
),
SocketCall(
@@ -52,7 +52,6 @@ DOTNET = SocketDialect(
label="WebSocketSharp.WebSocket",
extensions=CSHARP,
name=_URL,
- confidence=0.75,
requires=("WebSocketSharp",),
),
SocketCall(
@@ -62,7 +61,7 @@ DOTNET = SocketDialect(
label="MapHub",
extensions=CSHARP,
name=_URL,
- confidence=0.85,
+ origin=ContractOrigin.ROUTE_REGISTRATION,
),
),
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/socket/socketio.py b/packages/core/src/repowise/core/workspace/extractors/socket/socketio.py
index f906aefcf..dcd268804 100644
--- a/packages/core/src/repowise/core/workspace/extractors/socket/socketio.py
+++ b/packages/core/src/repowise/core/workspace/extractors/socket/socketio.py
@@ -23,6 +23,8 @@ from __future__ import annotations
import re
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import ContractOrigin
+
from ..calls import call_chain, call_sites, file_strings
from ..langs import JS_TS
from ..strings import Arg, call_arguments, match_paren
@@ -186,7 +188,7 @@ class SocketIoDialect:
role=_VERBS[verb],
transport=_TRANSPORT,
label=f"{recv}.{verb}",
- confidence=0.75,
+ origin=ContractOrigin.CLIENT_CALL,
offset=offset,
)
for event in events
@@ -254,7 +256,6 @@ WEBSOCKETS = SocketDialect(
label="new WebSocket",
extensions=JS_TS,
name=_FIRST,
- confidence=0.75,
requires=("WebSocket",),
),
),
diff --git a/packages/core/src/repowise/core/workspace/extractors/topic/dialect.py b/packages/core/src/repowise/core/workspace/extractors/topic/dialect.py
index 2589fd355..ea9101b59 100644
--- a/packages/core/src/repowise/core/workspace/extractors/topic/dialect.py
+++ b/packages/core/src/repowise/core/workspace/extractors/topic/dialect.py
@@ -23,6 +23,7 @@ from repowise.core.workspace.contracts import (
TOPIC_PREFIX,
TOPIC_ROUTING_KEY_UNRESOLVED,
)
+from repowise.core.workspace.origins import ContractOrigin
from ..base import line_at
from ..calls import call_sites
@@ -62,7 +63,7 @@ class TopicCall:
extensions: frozenset[str]
name: Arg
kind: str = TOPIC_KIND_TOPIC
- confidence: float = 0.8
+ origin: ContractOrigin = ContractOrigin.CLIENT_CALL
routing_key: Arg | None = None
queue: Arg | None = None
default_exchange: bool = False
@@ -79,7 +80,7 @@ def topic_contract(
kind: str,
role: str,
label: str,
- confidence: float,
+ origin: ContractOrigin,
offset: int,
**extra: str | bool,
) -> Contract:
@@ -91,7 +92,7 @@ def topic_contract(
contract_id=f"{TOPIC_PREFIX}{name.lower()}",
role=role,
symbol_name=f"{label}('{name}')",
- confidence=confidence,
+ origin=origin,
line=line_at(ctx.content, offset),
meta=meta,
)
@@ -145,7 +146,7 @@ def call_contracts(
kind=kind,
role=call.role,
label=call.label,
- confidence=call.confidence,
+ origin=call.origin,
offset=offset,
**extra,
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/topic/kafka.py b/packages/core/src/repowise/core/workspace/extractors/topic/kafka.py
index ae9353ab2..49d5d0f2e 100644
--- a/packages/core/src/repowise/core/workspace/extractors/topic/kafka.py
+++ b/packages/core/src/repowise/core/workspace/extractors/topic/kafka.py
@@ -5,6 +5,7 @@ from __future__ import annotations
import re
from repowise.core.workspace.contracts import TOPIC_PATTERN_REGEX
+from repowise.core.workspace.origins import ContractOrigin
from ..langs import GO, JAVA, JS_TS, PYTHON
from ..strings import Arg, unescape_backslashes
@@ -59,7 +60,6 @@ KAFKA = TopicDialect(
label="KafkaConsumer",
extensions=PYTHON,
name=_FIRST,
- confidence=0.7,
),
TopicCall(
head=re.compile(r"producer\.produce\s*\("),
@@ -67,7 +67,7 @@ KAFKA = TopicDialect(
label="producer.produce",
extensions=PYTHON | JS_TS,
name=Arg(keys=("topic",), pos=0),
- confidence=0.7,
+ origin=ContractOrigin.NAME_HEURISTIC, # read off a variable named `producer`
),
TopicCall(
head=re.compile(r"ConsumePartition\s*\("),
@@ -75,7 +75,6 @@ KAFKA = TopicDialect(
label="ConsumePartition",
extensions=GO,
name=_FIRST,
- confidence=0.7,
),
),
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/topic/laravel.py b/packages/core/src/repowise/core/workspace/extractors/topic/laravel.py
index 8a185bac1..54549efa7 100644
--- a/packages/core/src/repowise/core/workspace/extractors/topic/laravel.py
+++ b/packages/core/src/repowise/core/workspace/extractors/topic/laravel.py
@@ -33,6 +33,7 @@ from repowise.core.ingestion.languages.php_same_namespace import (
qualify_php_name,
)
from repowise.core.workspace.contracts import TOPIC_KIND_QUEUE
+from repowise.core.workspace.origins import ContractOrigin
from ..calls import FileStrings, call_chain
from ..langs import PHP
@@ -282,7 +283,7 @@ class _LaravelQueuePass:
kind=TOPIC_KIND_QUEUE,
role=role,
label=label,
- confidence=0.8,
+ origin=ContractOrigin.CLIENT_CALL,
offset=offset,
**extra,
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/topic/nestjs.py b/packages/core/src/repowise/core/workspace/extractors/topic/nestjs.py
index 0e4e786fc..99c40f77b 100644
--- a/packages/core/src/repowise/core/workspace/extractors/topic/nestjs.py
+++ b/packages/core/src/repowise/core/workspace/extractors/topic/nestjs.py
@@ -116,7 +116,7 @@ class NestMicroservicesDialect:
kind=call.kind,
role=call.role,
label=call.label,
- confidence=call.confidence,
+ origin=call.origin,
offset=m.start(),
)
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/topic/rabbitmq.py b/packages/core/src/repowise/core/workspace/extractors/topic/rabbitmq.py
index d6c044294..b5366f283 100644
--- a/packages/core/src/repowise/core/workspace/extractors/topic/rabbitmq.py
+++ b/packages/core/src/repowise/core/workspace/extractors/topic/rabbitmq.py
@@ -19,6 +19,7 @@ from repowise.core.workspace.contracts import (
TOPIC_KIND_EXCHANGE,
TOPIC_KIND_QUEUE,
)
+from repowise.core.workspace.origins import ContractOrigin
from ..langs import JAVA, JS_TS, PHP, PYTHON
from ..strings import Arg
@@ -96,7 +97,7 @@ RABBITMQ = TopicDialect(
extensions=PYTHON,
name=Arg(keys=("queue",), pos=0),
kind=TOPIC_KIND_QUEUE,
- confidence=0.7,
+ origin=ContractOrigin.NAME_HEURISTIC, # a variable named `channel`
),
TopicCall(
head=re.compile(r"channel\.basic_publish\s*\("),
@@ -105,7 +106,7 @@ RABBITMQ = TopicDialect(
extensions=PYTHON,
name=Arg(keys=("exchange",)),
kind=TOPIC_KIND_EXCHANGE,
- confidence=0.7,
+ origin=ContractOrigin.NAME_HEURISTIC, # a variable named `channel`
routing_key=Arg(keys=("routing_key",)),
default_exchange=True,
),
@@ -116,7 +117,7 @@ RABBITMQ = TopicDialect(
extensions=PYTHON,
name=Arg(keys=("exchange",), pos=1),
kind=TOPIC_KIND_BINDING,
- confidence=0.7,
+ origin=ContractOrigin.NAME_HEURISTIC, # a variable named `channel`
routing_key=Arg(keys=("routing_key",), pos=2),
queue=Arg(keys=("queue",), pos=0),
),
diff --git a/packages/core/src/repowise/core/workspace/matching/__init__.py b/packages/core/src/repowise/core/workspace/matching/__init__.py
index 55a015c5e..099394d19 100644
--- a/packages/core/src/repowise/core/workspace/matching/__init__.py
+++ b/packages/core/src/repowise/core/workspace/matching/__init__.py
@@ -17,6 +17,7 @@ from dataclasses import dataclass
from typing import TYPE_CHECKING
from repowise.core.workspace.contracts import normalize_contract_id
+from repowise.core.workspace.origins import LinkStrategy
from . import data, http, topic
from .common import MatchState, find_matching_keys, internal, prefer_target_repo
@@ -75,16 +76,13 @@ def _exact_pass(state: MatchState) -> None:
continue
if rules.accepts is not None and not rules.accepts(provider, consumer):
continue
- state.add(
- consumer,
- provider,
- "exact",
- min(provider.confidence, consumer.confidence),
- # A key the type's own rule reached under another name (a
- # pattern subscription) links under the provider's name.
- via_alias=rules.keys is not None
- and normalize_contract_id(provider.contract_id) != own,
- )
+ # A key the type's own rule reached under another name (a pattern
+ # subscription, the only `keys` rule today) links under the
+ # provider's name. A new `keys` rule with another meaning names its
+ # own strategy here.
+ aliased = rules.keys is not None and normalize_contract_id(provider.contract_id) != own
+ strategy = LinkStrategy.PATTERN_MATCHED if aliased else LinkStrategy.EXACT_ID
+ state.add(consumer, provider, strategy, via_alias=aliased)
def match_contracts(contracts: list[Contract]) -> list[ContractLink]:
diff --git a/packages/core/src/repowise/core/workspace/matching/common.py b/packages/core/src/repowise/core/workspace/matching/common.py
index 13b2c3d12..6c9dc6128 100644
--- a/packages/core/src/repowise/core/workspace/matching/common.py
+++ b/packages/core/src/repowise/core/workspace/matching/common.py
@@ -11,6 +11,7 @@ from repowise.core.workspace.contracts import (
normalize_contract_id,
same_service,
)
+from repowise.core.workspace.origins import LinkStrategy, link_confidence, match_type_for
def internal(provider: Contract, consumer: Contract) -> bool:
@@ -60,12 +61,16 @@ class MatchState:
self,
consumer: Contract,
provider: Contract,
- match_type: str,
- confidence: float,
+ strategy: LinkStrategy,
*,
+ via: Contract | None = None,
via_alias: bool = False,
) -> bool:
- """Record one link unless an identical one exists; True when it was added.
+ """Record one link made by *strategy* unless an identical one exists; True when added.
+
+ Its confidence is the weakest of the two ends (and *via*, the binding a
+ queue was reached through) scaled by the strategy's, and its
+ ``match_type`` is the strategy's (see :mod:`..origins`).
A link's ``contract_id`` is the provider's id, and ``consumer_contract_id``
the consumer's whenever it is spelled differently (another case, a
@@ -90,8 +95,13 @@ class MatchState:
ContractLink(
contract_id=provider.contract_id,
contract_type=consumer.contract_type,
- match_type=match_type,
- confidence=confidence,
+ match_type=match_type_for(strategy),
+ confidence=link_confidence(
+ strategy,
+ provider.confidence,
+ consumer.confidence,
+ *((via.confidence,) if via is not None else ()),
+ ),
provider_repo=provider.repo,
provider_file=provider.file_path,
provider_symbol=provider.symbol_name,
@@ -105,6 +115,7 @@ class MatchState:
consumer_contract_id=(
consumer.contract_id if consumer.contract_id != provider.contract_id else None
),
+ strategy=strategy,
)
)
self.matched.add(id(consumer))
diff --git a/packages/core/src/repowise/core/workspace/matching/data.py b/packages/core/src/repowise/core/workspace/matching/data.py
index 13241a6cb..438506377 100644
--- a/packages/core/src/repowise/core/workspace/matching/data.py
+++ b/packages/core/src/repowise/core/workspace/matching/data.py
@@ -11,6 +11,8 @@ from __future__ import annotations
from collections import defaultdict
from typing import TYPE_CHECKING
+from repowise.core.workspace.origins import LinkStrategy
+
from .common import internal
if TYPE_CHECKING:
@@ -53,4 +55,4 @@ def shared_table_pass(state: MatchState) -> None:
owner = owners[0]
for other in best:
if other is not owner and not internal(owner, other):
- state.add(other, owner, "exact", min(owner.confidence, other.confidence))
+ state.add(other, owner, LinkStrategy.SHARED_TABLE)
diff --git a/packages/core/src/repowise/core/workspace/matching/http.py b/packages/core/src/repowise/core/workspace/matching/http.py
index b7c075322..875471181 100644
--- a/packages/core/src/repowise/core/workspace/matching/http.py
+++ b/packages/core/src/repowise/core/workspace/matching/http.py
@@ -13,6 +13,7 @@ from collections import defaultdict
from typing import TYPE_CHECKING
from repowise.core.workspace.contracts import normalize_contract_id
+from repowise.core.workspace.origins import LinkStrategy
from .common import find_matching_keys, internal, prefer_target_repo
@@ -25,7 +26,8 @@ if TYPE_CHECKING:
# 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.
+# versa). Such links are emitted as lower-confidence ``candidate`` matches
+# (:attr:`LinkStrategy.PREFIX_STRIPPED`).
#
# Kept deliberately small: only segments that are almost never real resource
# names. Words like ``internal``/``public``/``gateway`` are excluded because
@@ -33,9 +35,6 @@ if TYPE_CHECKING:
_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
@@ -204,9 +203,10 @@ def is_deferred(consumer: Contract) -> bool:
def base_resolved_pass(state: MatchState) -> None:
"""Match consumers whose unresolved base was stripped, on their host-relative path.
- The link is ``exact`` when the target service is unambiguous (one matching
- service, or a configured ``service_bases`` target that narrows to a
- provider) and ``candidate`` otherwise.
+ The strategy names how the target service was settled: a host or
+ ``service_bases`` target that narrows to a provider (``service_mapped``),
+ the only service serving the path (``unique_path``), or neither, linking
+ every service that serves it (``ambiguous_path``, a candidate).
"""
for consumer in state.unmatched("http"):
if not is_deferred(consumer):
@@ -227,13 +227,14 @@ def base_resolved_pass(state: MatchState) -> None:
narrowed = [p for p in providers if p.repo == target] if target else []
if narrowed:
providers = narrowed
- resolved = bool(narrowed) or len({(p.repo, p.service) for p in providers}) == 1
- match_type = "exact" if resolved else "candidate"
+ if narrowed:
+ strategy = LinkStrategy.SERVICE_MAPPED
+ elif len({(p.repo, p.service) for p in providers}) == 1:
+ strategy = LinkStrategy.UNIQUE_PATH
+ else:
+ strategy = LinkStrategy.AMBIGUOUS_PATH
for provider in providers:
- confidence = min(provider.confidence, consumer.confidence)
- if not resolved:
- confidence = round(confidence * CANDIDATE_CONFIDENCE_FACTOR, 3)
- state.add(consumer, provider, match_type, confidence)
+ state.add(consumer, provider, strategy)
def candidate_pass(state: MatchState) -> None:
@@ -265,15 +266,10 @@ def candidate_pass(state: MatchState) -> None:
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,
- )
- state.add(consumer, provider, "candidate", confidence)
+ state.add(consumer, provider, LinkStrategy.PREFIX_STRIPPED)
__all__ = [
- "CANDIDATE_CONFIDENCE_FACTOR",
"annotate_consumer_targets",
"base_resolved_pass",
"candidate_pass",
diff --git a/packages/core/src/repowise/core/workspace/matching/topic.py b/packages/core/src/repowise/core/workspace/matching/topic.py
index 6d19e8e82..517ab1d8d 100644
--- a/packages/core/src/repowise/core/workspace/matching/topic.py
+++ b/packages/core/src/repowise/core/workspace/matching/topic.py
@@ -31,6 +31,7 @@ from repowise.core.workspace.contracts import (
TOPIC_ROUTING_KEY_UNRESOLVED,
normalize_contract_id,
)
+from repowise.core.workspace.origins import LinkStrategy
from .common import find_matching_keys, internal
@@ -144,7 +145,10 @@ def accepts(provider: Contract, consumer: Contract) -> bool:
A key the source did not settle routes nowhere: reading it as match-all
would link every binding on the exchange. The two ends must be able to be
one broker's destination (:func:`same_transport`), and a Laravel job is
- read by a Laravel worker only if it is the worker's own class.
+ read by a Laravel worker only if it is the worker's own class. A job class
+ consumer therefore takes only a Laravel dispatch of that class: a raw
+ publish on a queue of the same name (amqplib ``sendToQueue``) is not the
+ serialized job envelope its worker reads.
"""
if provider.meta.get(TOPIC_ROUTING_KEY_UNRESOLVED) or consumer.meta.get(
TOPIC_ROUTING_KEY_UNRESOLVED
@@ -152,10 +156,9 @@ def accepts(provider: Contract, consumer: Contract) -> bool:
return False
if not same_transport(provider, consumer):
return False
- if (
- provider.meta.get("broker") == consumer.meta.get("broker") == "laravel"
- and provider.meta.get("job") != consumer.meta.get("job")
- ):
+ job = consumer.meta.get("job")
+ both_laravel = provider.meta.get("broker") == consumer.meta.get("broker") == "laravel"
+ if (job or both_laravel) and provider.meta.get("job") != job:
return False
return routing_matches(
consumer.meta.get("routing_key", ""), provider.meta.get("routing_key", "")
@@ -184,19 +187,15 @@ def binding_pass(state: MatchState) -> None:
for provider in publishers:
if not readers:
if not internal(provider, binding):
- state.add(
- binding, provider, "exact", min(provider.confidence, binding.confidence)
- )
+ state.add(binding, provider, LinkStrategy.BINDING_ROUTED)
continue
for consumer in readers:
- if internal(provider, consumer):
+ # The reader is held to the same rule: a job class behind a
+ # binding still takes only its own Laravel dispatch.
+ if internal(provider, consumer) or not accepts(provider, consumer):
continue
state.add(
- consumer,
- provider,
- "exact",
- min(provider.confidence, consumer.confidence, binding.confidence),
- via_alias=True,
+ consumer, provider, LinkStrategy.BINDING_ROUTED, via=binding, via_alias=True
)
diff --git a/packages/core/src/repowise/core/workspace/origins.py b/packages/core/src/repowise/core/workspace/origins.py
new file mode 100644
index 000000000..309b3f37f
--- /dev/null
+++ b/packages/core/src/repowise/core/workspace/origins.py
@@ -0,0 +1,152 @@
+"""How a workspace contract was read and how a cross-repo link was made.
+
+Two closed vocabularies, each value carrying exactly one confidence, the same
+rule ``docs/layers/GRAPH.md`` applies to call edges:
+
+* :class:`ContractOrigin` names what established a contract: a framework
+ registration, a schema document, a client call, a naming convention. Every
+ dialect declares one of these as data and :func:`.extractors.dialect.build_contract`
+ turns it into the contract's ``confidence``. A new dialect picks an existing
+ origin; a genuinely new way of establishing a contract adds one row here.
+* :class:`LinkStrategy` names the matching rule that joined a consumer to a
+ provider. A link's confidence is the weaker end's confidence times its
+ strategy's, so the strategy distribution and the confidence histogram are
+ two views of the same data.
+
+``match_type`` (exact / candidate / manual), which the system graph, the API
+and the web views read, is derived from the strategy and never set on its own.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class ContractOrigin(StrEnum):
+ """What established a contract. Confidence per value: :data:`ORIGIN_CONFIDENCE`."""
+
+ #: An OpenAPI or proto document declares the operation.
+ IDL = "idl"
+ #: A published package exports the symbol another repo imports.
+ PACKAGE_EXPORT = "package_export"
+ #: A framework registers the route, handler, server or hub in code.
+ ROUTE_REGISTRATION = "route_registration"
+ #: The parsed index types the receiver as an HTTP client.
+ TYPED_CLIENT = "typed_client"
+ #: SQL DDL or a migration creates or alters the table.
+ DDL = "ddl"
+ #: An ORM model names its table explicitly.
+ EXPLICIT_TABLE = "explicit_table"
+ #: A known client, broker, socket or query-builder call names the destination.
+ CLIENT_CALL = "client_call"
+ #: A call on a client instance whose base URL the file reads.
+ INSTANCE_BASE = "instance_base"
+ #: The destination was traced across statements to the call.
+ DATAFLOW = "dataflow"
+ #: A table named inside SQL text in a string.
+ SQL_STRING = "sql_string"
+ #: The call shape matches, but only a callee or receiver name says it is a client.
+ NAME_HEURISTIC = "name_heuristic"
+ #: Derived from a naming convention: an ORM's default table name, a unique short type name.
+ NAME_CONVENTION = "name_convention"
+
+
+ORIGIN_CONFIDENCE: dict[ContractOrigin, float] = {
+ ContractOrigin.IDL: 0.90,
+ ContractOrigin.PACKAGE_EXPORT: 0.90,
+ ContractOrigin.ROUTE_REGISTRATION: 0.85,
+ ContractOrigin.TYPED_CLIENT: 0.85,
+ ContractOrigin.DDL: 0.85,
+ ContractOrigin.EXPLICIT_TABLE: 0.85,
+ ContractOrigin.CLIENT_CALL: 0.75,
+ ContractOrigin.INSTANCE_BASE: 0.75,
+ ContractOrigin.DATAFLOW: 0.70,
+ ContractOrigin.SQL_STRING: 0.70,
+ ContractOrigin.NAME_HEURISTIC: 0.65,
+ ContractOrigin.NAME_CONVENTION: 0.60,
+}
+
+
+class LinkStrategy(StrEnum):
+ """The rule that joined a consumer to a provider. Confidence: :data:`STRATEGY_CONFIDENCE`."""
+
+ #: Both ends name the same normalized id (HTTP method and gRPC service wildcards included).
+ EXACT_ID = "exact_id"
+ #: The consumer's subscription pattern (``orders.*``) matches the provider's name.
+ PATTERN_MATCHED = "pattern_matched"
+ #: A queue bound to the exchange the provider publishes to, with a routing key it receives.
+ BINDING_ROUTED = "binding_routed"
+ #: A service that only models a table, linked to the one service whose schema defines it.
+ SHARED_TABLE = "shared_table"
+ #: The consumer's host or base token maps to the providing service.
+ SERVICE_MAPPED = "service_mapped"
+ #: The consumer's base is unread and exactly one service serves the path.
+ UNIQUE_PATH = "unique_path"
+ #: The consumer's base is unread and several services serve the path; linked to each.
+ AMBIGUOUS_PATH = "ambiguous_path"
+ #: Matched only after stripping mount, version or base prefixes from both paths.
+ PREFIX_STRIPPED = "prefix_stripped"
+ #: Declared in the workspace config.
+ MANUAL = "manual"
+ #: A manifest declares the package dependency (system-graph package edges only).
+ MANIFEST = "manifest"
+
+
+STRATEGY_CONFIDENCE: dict[LinkStrategy, float] = {
+ LinkStrategy.EXACT_ID: 1.0,
+ LinkStrategy.PATTERN_MATCHED: 1.0,
+ LinkStrategy.BINDING_ROUTED: 1.0,
+ LinkStrategy.SHARED_TABLE: 1.0,
+ LinkStrategy.SERVICE_MAPPED: 1.0,
+ LinkStrategy.UNIQUE_PATH: 1.0,
+ LinkStrategy.AMBIGUOUS_PATH: 0.6,
+ LinkStrategy.PREFIX_STRIPPED: 0.6,
+ LinkStrategy.MANUAL: 1.0,
+ LinkStrategy.MANIFEST: 1.0,
+}
+
+_CANDIDATE = frozenset({LinkStrategy.AMBIGUOUS_PATH, LinkStrategy.PREFIX_STRIPPED})
+
+
+def origin_confidence(origin: str) -> float:
+ """The one confidence *origin* carries. Raises ``ValueError`` outside the vocabulary."""
+ return ORIGIN_CONFIDENCE[ContractOrigin(origin)]
+
+
+def match_type_for(strategy: str) -> str:
+ """The ``match_type`` a link made by *strategy* is shown as: exact, candidate or manual."""
+ s = LinkStrategy(strategy)
+ if s is LinkStrategy.MANUAL:
+ return "manual"
+ return "candidate" if s in _CANDIDATE else "exact"
+
+
+def link_confidence(strategy: str, *end_confidences: float) -> float:
+ """The weakest end's confidence scaled by *strategy*'s, rounded as links store it."""
+ return round(min(end_confidences) * STRATEGY_CONFIDENCE[LinkStrategy(strategy)], 3)
+
+
+def legacy_strategy(match_type: str) -> str | None:
+ """The strategy a link stored before strategies existed most likely had.
+
+ A guess: a stored ``candidate`` may have been an ambiguous path rather than
+ a stripped prefix. A compatibility read only: such a store is re-extracted on the next update
+ (its version is older), and until then the reads it serves name a strategy.
+ """
+ return {
+ "exact": LinkStrategy.EXACT_ID,
+ "candidate": LinkStrategy.PREFIX_STRIPPED,
+ "manual": LinkStrategy.MANUAL,
+ }.get(match_type)
+
+
+__all__ = [
+ "ORIGIN_CONFIDENCE",
+ "STRATEGY_CONFIDENCE",
+ "ContractOrigin",
+ "LinkStrategy",
+ "legacy_strategy",
+ "link_confidence",
+ "match_type_for",
+ "origin_confidence",
+]
diff --git a/packages/core/src/repowise/core/workspace/reads.py b/packages/core/src/repowise/core/workspace/reads.py
index d7bea2ecb..30d00a4e3 100644
--- a/packages/core/src/repowise/core/workspace/reads.py
+++ b/packages/core/src/repowise/core/workspace/reads.py
@@ -16,6 +16,7 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Any
from repowise.core.workspace.cross_repo import MAX_EDGES, MAX_EDGES_PER_REPO_PAIR
+from repowise.core.workspace.origins import legacy_strategy
if TYPE_CHECKING:
from collections.abc import Iterable, Sequence
@@ -51,6 +52,7 @@ def contract_row(c: dict) -> dict[str, Any]:
"service": c.get("service"),
"line": c.get("line"),
"symbol_id": c.get("symbol_id"),
+ "origin": c.get("origin"),
"meta": c.get("meta") or {},
}
@@ -61,6 +63,7 @@ def link_row(lk: dict) -> dict[str, Any]:
"contract_id": lk.get("contract_id", ""),
"contract_type": lk.get("contract_type", ""),
"match_type": lk.get("match_type", "exact"),
+ "strategy": lk.get("strategy") or legacy_strategy(lk.get("match_type", "exact")),
"confidence": lk.get("confidence", 0.0),
"provider_repo": lk.get("provider_repo", ""),
"provider_file": lk.get("provider_file", ""),
diff --git a/packages/core/src/repowise/core/workspace/system_graph.py b/packages/core/src/repowise/core/workspace/system_graph.py
index 7661cacd1..f7965f88f 100644
--- a/packages/core/src/repowise/core/workspace/system_graph.py
+++ b/packages/core/src/repowise/core/workspace/system_graph.py
@@ -9,7 +9,8 @@ service-granular graph:
no detected sub-boundary collapses to one repo-root node.
* **Edges are typed and honest.** Every edge carries its ``kind`` (http / grpc /
event / package / co_change / db), ``match_type`` (exact / candidate / manual /
- inferred), a ``confidence``, a ``weight`` (how many underlying contracts /
+ inferred), the ``strategy`` that made its strongest link (see :mod:`.origins`;
+ None on a co-change edge), a ``confidence``, a ``weight`` (how many underlying contracts /
co-changes / deps it aggregates), and ``contract_refs`` back-pointers so any
consumer can drill from an edge to its evidence. Structural edges (contracts,
package deps) are flagged distinctly from behavioral co-change edges.
@@ -21,7 +22,8 @@ The graph is built once during ``repowise update --workspace`` (where contracts,
the cross-repo overlay, and service boundaries are all in hand) and persisted to
``.repowise-workspace/system_graph.json``. The map (Phase 2), blast radius, the
DSM, and the MCP/CLI surfaces are all *views* over this one artifact — none of
-them re-derives the graph.
+them re-derives the graph. Each reads it through :meth:`SystemGraph.adjacency`,
+the one place that decides which edges a dependency walk follows.
Pure and I/O-free except for the thin ``save_system_graph`` / ``load_system_graph``
helpers and the ``run_system_graph_build`` orchestrator at the bottom.
@@ -51,6 +53,7 @@ from repowise.core.workspace.extractors.service_boundary import (
assign_service,
detect_service_boundaries,
)
+from repowise.core.workspace.origins import LinkStrategy, legacy_strategy
_log = logging.getLogger("repowise.workspace.system_graph")
@@ -96,6 +99,12 @@ MAX_EDGE_REFS = 50
#: conflate "call each other" with "change together".
_STRUCTURAL_KINDS: frozenset[str] = frozenset({"http", "grpc", "socket", "event", "package", "db"})
+#: Structural kinds whose dependency is asynchronous: the subscriber depends on
+#: the message shape, not on the publisher answering. Still a dependency (a
+#: cycle through one couples schemas and deploy order), so every view walks it;
+#: this set is what lets a view say which legs of a path are async.
+ASYNC_EDGE_KINDS: frozenset[str] = frozenset({"event"})
+
def edge_kind_for_contract_type(contract_type: str) -> str:
"""Map a contract type to its edge kind, falling back to the type itself."""
@@ -168,6 +177,9 @@ class SystemEdge:
weight: int # number of underlying contracts / co-changes / deps
structural: bool # True for contract/package, False for co-change
contract_refs: list[str] = field(default_factory=list)
+ #: The :class:`.origins.LinkStrategy` of the link that gave the edge its
+ #: confidence. None on a co-change edge, which no link made.
+ strategy: str | None = None
def to_dict(self) -> dict[str, Any]:
return {
@@ -180,20 +192,28 @@ class SystemEdge:
"weight": self.weight,
"structural": self.structural,
"contract_refs": self.contract_refs,
+ "strategy": self.strategy,
}
@classmethod
def from_dict(cls, data: dict[str, Any]) -> SystemEdge:
+ match_type = data.get("match_type", "exact")
+ strategy = data.get("strategy")
+ if strategy is None and data.get("kind") == "package":
+ strategy = LinkStrategy.MANIFEST # a graph written before strategies existed
+ elif strategy is None and data.get("kind") != "co_change":
+ strategy = legacy_strategy(match_type)
return cls(
id=data["id"],
source=data["source"],
target=data["target"],
kind=data["kind"],
- match_type=data.get("match_type", "exact"),
+ match_type=match_type,
confidence=data.get("confidence", 0.0),
weight=data.get("weight", 1),
structural=data.get("structural", True),
contract_refs=data.get("contract_refs", []),
+ strategy=strategy,
)
@@ -229,6 +249,37 @@ class SystemGraph:
diagnostics=ExtractionDiagnostics.from_dict(data.get("diagnostics", {})),
)
+ def adjacency(
+ self, *, behavioral: bool = False, impact: bool = False
+ ) -> dict[str, dict[str, list[SystemEdge]]]:
+ """The graph as ``node -> {neighbour: [edges]}``: the one view every walk reads.
+
+ Default: dependency direction (``source`` depends on ``target``) over
+ structural edges, which is what cycles, the architecture metrics and
+ reachability walk. *impact* flips it to "a change to the key reaches
+ the neighbour" (``target -> source``), the blast-radius direction.
+ *behavioral* adds co-change edges, both ways, since they are symmetric.
+
+ Parallel edges between one pair (an http and an event edge, say) stay
+ separate in the list, in graph order, so a caller can tell a sync leg
+ from an async one by each edge's ``kind`` (:data:`ASYNC_EDGE_KINDS`).
+ """
+ adj: dict[str, dict[str, list[SystemEdge]]] = {}
+
+ def link(a: str, b: str, edge: SystemEdge) -> None:
+ adj.setdefault(a, {}).setdefault(b, []).append(edge)
+
+ for edge in self.edges:
+ if edge.structural:
+ if impact:
+ link(edge.target, edge.source, edge)
+ else:
+ link(edge.source, edge.target, edge)
+ elif behavioral:
+ link(edge.source, edge.target, edge)
+ link(edge.target, edge.source, edge)
+ return adj
+
# ---------------------------------------------------------------------------
# Graph assembly (pure)
@@ -295,6 +346,7 @@ class _GraphBuilder:
match_type: str,
confidence: float,
ref: str,
+ strategy: str | None,
) -> None:
if source == target:
return # intra-node calls aren't system-level edges
@@ -316,9 +368,12 @@ class _GraphBuilder:
weight=1,
structural=structural,
contract_refs=[ref] if ref else [],
+ strategy=strategy,
)
return
existing.weight += 1
+ if round(confidence, 3) > existing.confidence:
+ existing.strategy = strategy
existing.confidence = round(max(existing.confidence, confidence), 3)
if _MATCH_TYPE_RANK.get(match_type, 0) > _MATCH_TYPE_RANK.get(existing.match_type, 0):
existing.match_type = match_type
@@ -393,6 +448,7 @@ def build_system_graph(
match_type=lk.match_type,
confidence=lk.confidence,
ref=lk.contract_id,
+ strategy=lk.strategy,
)
# 3. Package-dependency edges — the dependent repo imports the dependency.
@@ -409,6 +465,7 @@ def build_system_graph(
match_type="exact",
confidence=1.0,
ref=reference,
+ strategy=LinkStrategy.MANIFEST,
)
# 4. Co-change edges — behavioral, undirected, lower trust.
@@ -422,6 +479,7 @@ def build_system_graph(
match_type="inferred",
confidence=cc.strength,
ref=f"{cc.source_file}~{cc.target_file}",
+ strategy=None,
)
nodes, edges = builder.finalize(diagnostics)
diff --git a/packages/server/src/repowise/server/schemas/workspace.py b/packages/server/src/repowise/server/schemas/workspace.py
index c31d62593..d5482cd7d 100644
--- a/packages/server/src/repowise/server/schemas/workspace.py
+++ b/packages/server/src/repowise/server/schemas/workspace.py
@@ -107,6 +107,10 @@ class WorkspaceContractEntry(BaseModel):
#: index or nothing is declared at ``line`` — the contract still matches, it
#: just cannot be traversed into the call graph.
symbol_id: str | None = None
+ #: What established the contract (``route_registration``, ``client_call``,
+ #: ``sql_string``...), one of the closed origins in
+ #: ``repowise.core.workspace.origins``. None on a row stored before origins.
+ origin: str | None = None
#: Extractor-supplied detail (``extraction_layer``, ``framework``, ``method``,
#: ``path``, ``table``, ``package``...). Keys vary by contract type.
meta: dict = {}
@@ -116,6 +120,10 @@ class WorkspaceContractLinkEntry(BaseModel):
contract_id: str
contract_type: str
match_type: str
+ #: The matching rule that made the link (``exact_id``, ``binding_routed``,
+ #: ``prefix_stripped``...), one of ``repowise.core.workspace.origins``.
+ #: ``match_type`` is derived from it.
+ strategy: str | None = None
confidence: float
provider_repo: str
provider_file: str
@@ -265,6 +273,9 @@ class WorkspaceSystemEdge(BaseModel):
weight: int = 1
structural: bool = True
contract_refs: list[str] = []
+ #: Strategy of the link that gave the edge its confidence (``manifest`` on
+ #: a package edge); None on a co-change edge.
+ strategy: str | None = None
class WorkspaceRepoDiagnostics(BaseModel):
@@ -474,6 +485,10 @@ class WorkspaceDependencyCycle(BaseModel):
nodes: list[str] = []
edge_ids: list[str] = []
length: int = 0
+ #: Edge kinds on each leg (``leg_kinds[i]`` joins ``nodes[i]`` to the next).
+ leg_kinds: list[list[str]] = []
+ #: Legs only an asynchronous (event) edge joins.
+ async_legs: int = 0
class WorkspaceConformanceResponse(BaseModel):
diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.ts
index 52aba6f45..d88c903cc 100644
--- a/packages/types/src/generated/http.ts
+++ b/packages/types/src/generated/http.ts
@@ -4581,6 +4581,7 @@ export interface WorkspaceContractEntry {
service?: string | null;
line?: number | null;
symbol_id?: string | null;
+ origin?: string | null;
meta?: Record<string, unknown>;
}
@@ -4588,6 +4589,7 @@ export interface WorkspaceContractLinkEntry {
contract_id: string;
contract_type: string;
match_type: string;
+ strategy?: string | null;
confidence: number;
provider_repo: string;
provider_file: string;
@@ -4637,6 +4639,8 @@ export interface WorkspaceDependencyCycle {
nodes?: string[];
edge_ids?: string[];
length?: number;
+ leg_kinds?: string[][];
+ async_legs?: number;
}
export interface WorkspaceExtractionDiagnostics {
@@ -4831,6 +4835,7 @@ export interface WorkspaceSystemEdge {
weight?: number;
structural?: boolean;
contract_refs?: string[];
+ strategy?: string | null;
}
export interface WorkspaceSystemGraphResponse {
diff --git a/packages/types/src/workspace.ts b/packages/types/src/workspace.ts
index ade058bfa..a8ea9e28d 100644
--- a/packages/types/src/workspace.ts
+++ b/packages/types/src/workspace.ts
@@ -36,6 +36,8 @@ export interface WorkspaceContractLinkEntry {
contract_id: string;
contract_type: string;
match_type: string;
+ /** The matching rule that made the link (`exact_id`, `binding_routed`, ...); `match_type` derives from it. */
+ strategy?: string | null;
confidence: number;
provider_repo: string;
provider_file: string;
@@ -144,6 +146,8 @@ export interface SystemEdge {
structural: boolean;
/** Back-pointers to the underlying evidence, for drill-down (bounded). */
contract_refs: string[];
+ /** Strategy of the link that gave the edge its confidence; null on a co-change edge. */
+ strategy?: string | null;
}
export interface SystemGraph {
@@ -422,6 +426,10 @@ export interface DependencyCycle {
edge_ids: string[];
/** Number of services in the cycle. */
length: number;
+ /** Edge kinds on each leg: `leg_kinds[i]` joins `nodes[i]` to the next node. */
+ leg_kinds?: string[][];
+ /** Legs only an asynchronous (event) edge joins. */
+ async_legs?: number;
}
export interface ConformanceReport {
diff --git a/tests/unit/workspace/test_conformance.py b/tests/unit/workspace/test_conformance.py
index d0a3f1a18..726b134e8 100644
--- a/tests/unit/workspace/test_conformance.py
+++ b/tests/unit/workspace/test_conformance.py
@@ -205,6 +205,20 @@ def test_acyclic_graph_has_no_cycles():
assert detect_cycles(g) == ([], 0)
+def test_a_cycle_closed_by_an_event_counts_and_names_each_legs_kinds():
+ g = _graph(
+ [_node("a"), _node("b")],
+ [_edge("a", "b", kind="event"), _edge("b", "a"), _edge("b", "a", kind="db")],
+ )
+ [cycle], total = detect_cycles(g)
+ assert total == 1
+ legs = dict(zip(cycle.nodes, cycle.leg_kinds, strict=True))
+ assert legs == {"a": ["event"], "b": ["db", "http"]}
+ assert cycle.async_legs == 1
+ assert cycle.to_dict()["async_legs"] == 1
+ assert type(cycle).from_dict(cycle.to_dict()).leg_kinds == cycle.leg_kinds
+
+
def test_cycles_ignore_behavioral_edges():
# a->b structural, b->a only via co-change → not a real cycle
g = _graph(
diff --git a/tests/unit/workspace/test_grpc_languages.py b/tests/unit/workspace/test_grpc_languages.py
index dd36d1310..7faf9db97 100644
--- a/tests/unit/workspace/test_grpc_languages.py
+++ b/tests/unit/workspace/test_grpc_languages.py
@@ -42,7 +42,7 @@ class TestCSharp:
"grpc::GreeterService/*",
"provider",
"cs:MapGrpcService<GreeterService>",
- 0.8,
+ 0.85,
(("service", "GreeterService"), ("source", "csharp_mapgrpc")),
),
(
@@ -51,7 +51,7 @@ class TestCSharp:
# The template says ServiceBase while the regex matched `GreeterBase`.
# Preserved verbatim from the module this replaced, quirk included.
"cs:extends Greeter.GreeterServiceBase",
- 0.8,
+ 0.85,
(("service", "Greeter"), ("source", "csharp_base")),
),
(
@@ -92,7 +92,7 @@ class TestTypeScript:
"grpc::AuthService/Login",
"provider",
"ts:@GrpcMethod('AuthService', 'Login')",
- 0.8,
+ 0.85,
(
("service", "AuthService"),
("method", "Login"),
@@ -125,4 +125,4 @@ class TestPythonAndGoKeepTheirOwnRules:
".go",
"pb.RegisterAuthServiceServer(s, &impl{})\nc := pb.NewAuthServiceClient(conn)\n",
)
- assert [(r[1], r[3]) for r in rows] == [("provider", 0.8), ("consumer", 0.7)]
+ assert [(r[1], r[3]) for r in rows] == [("provider", 0.85), ("consumer", 0.75)]
diff --git a/tests/unit/workspace/test_masstransit_extractor.py b/tests/unit/workspace/test_masstransit_extractor.py
index 3e492d54e..41e1ce2f5 100644
--- a/tests/unit/workspace/test_masstransit_extractor.py
+++ b/tests/unit/workspace/test_masstransit_extractor.py
@@ -192,7 +192,7 @@ class TestConsumers:
assert submitted.meta["broker"] == "masstransit"
assert submitted.meta["fault"] is False
assert submitted.meta["resolution"] == "using"
- assert submitted.confidence == 0.8
+ assert submitted.origin == "client_call"
def test_fault_consumer_is_keyed_on_the_inner_message(
self, contracts: Path, tmp_path: Path
@@ -662,7 +662,7 @@ class TestResolution:
(row,) = _rows(rows, "provider")
assert row.meta["resolution"] == "qualified"
- assert row.confidence == 0.8
+ assert row.origin == "client_call"
def test_unknown_qualified_name_does_not_fall_back_to_the_short_name(
self, contracts: Path, tmp_path: Path
diff --git a/tests/unit/workspace/test_origins.py b/tests/unit/workspace/test_origins.py
new file mode 100644
index 000000000..9991238ea
--- /dev/null
+++ b/tests/unit/workspace/test_origins.py
@@ -0,0 +1,211 @@
+"""Contract origins and link strategies: one closed vocabulary, one confidence per value."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from repowise.core.workspace.config import ContractConfig, ManualContractLink
+from repowise.core.workspace.contracts import (
+ Contract,
+ ContractLink,
+ _build_manual_links,
+ _enabled_extractors,
+)
+from repowise.core.workspace.extractors import grpc, socket, topic
+from repowise.core.workspace.extractors.base import ScanContext
+from repowise.core.workspace.extractors.dialect import build_contract
+from repowise.core.workspace.extractors.topic.nestjs import _HANDLERS
+from repowise.core.workspace.matching import annotate_consumer_targets, match_contracts
+from repowise.core.workspace.origins import (
+ ORIGIN_CONFIDENCE,
+ STRATEGY_CONFIDENCE,
+ ContractOrigin,
+ LinkStrategy,
+ link_confidence,
+ match_type_for,
+)
+from repowise.core.workspace.system_graph import SystemEdge
+
+
+def test_every_value_carries_exactly_one_confidence() -> None:
+ assert set(ORIGIN_CONFIDENCE) == set(ContractOrigin)
+ assert set(STRATEGY_CONFIDENCE) == set(LinkStrategy)
+ assert all(0 < v <= 1 for v in [*ORIGIN_CONFIDENCE.values(), *STRATEGY_CONFIDENCE.values()])
+
+
+def _declared_rows() -> list[object]:
+ rows: list[object] = list(_HANDLERS)
+ for dialect in (*topic.DIALECTS, *socket.DIALECTS):
+ rows.extend(getattr(dialect, "calls", ()))
+ for lang in grpc.LANGUAGES:
+ rows.extend(lang.rules)
+ return rows
+
+
+def test_every_registered_row_declares_an_origin_from_the_vocabulary() -> None:
+ rows = _declared_rows()
+ assert len(rows) > 40 # the registries were actually walked
+ for row in rows:
+ assert isinstance(row.origin, ContractOrigin), row
+
+
+def test_a_contract_outside_the_vocabulary_cannot_be_built() -> None:
+ ctx = ScanContext("a", "x.py", ".py", "")
+ with pytest.raises(ValueError):
+ build_contract(
+ ctx,
+ contract_type="http",
+ contract_id="http::GET::/x",
+ role="consumer",
+ symbol_name="x",
+ origin="guessed", # type: ignore[arg-type]
+ line=1,
+ meta={},
+ )
+
+
+_FILES = {
+ "server.js": "const app = require('express')();\napp.get('/users', (req, res) => {});\n",
+ "client.js": "fetch('/orders');\n",
+ "api.ts": (
+ "import axios from 'axios';\n"
+ "const api = axios.create({ baseURL: 'http://billing/api' });\n"
+ "api.get('/invoices');\n"
+ ),
+ "schema.sql": "CREATE TABLE orders (id int);\n",
+ "repo.py": 'cur.execute("SELECT * FROM orders")\n',
+ "worker.py": "from kafka import KafkaConsumer\nKafkaConsumer('orders')\n",
+ "svc.proto": (
+ "syntax = \"proto3\";\npackage shop;\n"
+ "service Cart { rpc Add (Req) returns (Res); }\n"
+ "message Req {}\nmessage Res {}\n"
+ ),
+}
+
+
+def test_every_extracted_contract_is_stamped_with_its_origin(tmp_path: Path) -> None:
+ for name, text in _FILES.items():
+ (tmp_path / name).write_text(text, encoding="utf-8")
+ contracts: list[Contract] = []
+ for extractor in _enabled_extractors(ContractConfig()):
+ contracts.extend(extractor.extract(tmp_path, "svc"))
+ origins = {c.origin for c in contracts}
+ assert {
+ ContractOrigin.ROUTE_REGISTRATION,
+ ContractOrigin.CLIENT_CALL,
+ ContractOrigin.INSTANCE_BASE,
+ ContractOrigin.DDL,
+ ContractOrigin.SQL_STRING,
+ ContractOrigin.IDL,
+ } <= origins
+ for c in contracts:
+ assert c.confidence == ORIGIN_CONFIDENCE[ContractOrigin(c.origin)], c
+ assert Contract.from_dict(c.to_dict()).origin == c.origin
+
+
+def _http(repo: str, role: str, path: str, origin: ContractOrigin, **meta) -> Contract:
+ return Contract(
+ repo=repo,
+ contract_id=f"http::GET::{path}",
+ contract_type="http",
+ role=role,
+ file_path=f"{repo}.ts",
+ symbol_name=path,
+ confidence=ORIGIN_CONFIDENCE[origin],
+ meta={"method": "GET", "path": path, **meta},
+ origin=origin,
+ )
+
+
+def _provider(repo: str, path: str) -> Contract:
+ return _http(repo, "provider", path, ContractOrigin.ROUTE_REGISTRATION)
+
+
+def _consumer(path: str, **meta) -> Contract:
+ return _http("web", "consumer", path, ContractOrigin.NAME_HEURISTIC, **meta)
+
+
+ ("contracts", "service_bases", "strategy"),
+ [
+ ([_provider("users", "/users"), _consumer("/users")], {}, LinkStrategy.EXACT_ID),
+ ([_provider("users", "/api/v1/users"), _consumer("/users")], {}, LinkStrategy.PREFIX_STRIPPED),
+ (
+ [_provider("users", "/users"), _consumer("/users", base_stripped=True)],
+ {},
+ LinkStrategy.UNIQUE_PATH,
+ ),
+ (
+ [
+ _provider("users", "/users"),
+ _provider("admin", "/users"),
+ _consumer("/users", base_stripped=True, base_token="users_api"),
+ ],
+ {"USERS_API": "users"},
+ LinkStrategy.SERVICE_MAPPED,
+ ),
+ (
+ [
+ _provider("users", "/users"),
+ _provider("admin", "/users"),
+ _consumer("/users", base_stripped=True),
+ ],
+ {},
+ LinkStrategy.AMBIGUOUS_PATH,
+ ),
+ ],
+)
+def test_each_http_link_names_the_rule_that_made_it(
+ contracts: list[Contract], service_bases: dict[str, str], strategy: LinkStrategy
+) -> None:
+ annotate_consumer_targets(contracts, service_bases)
+ links = match_contracts(contracts)
+ assert links
+ for link in links:
+ assert link.strategy == strategy
+ assert link.match_type == match_type_for(strategy)
+ # The weaker end (the 0.65 consumer) scaled by the strategy's factor.
+ assert link.confidence == link_confidence(strategy, 0.85, 0.65)
+ assert ContractLink.from_dict(link.to_dict()).strategy == strategy
+
+
+def test_a_manual_link_is_its_own_strategy() -> None:
+ manual = ManualContractLink(
+ from_repo="web", to_repo="users", contract_id="http::GET::/x", contract_type="http"
+ )
+ [link] = _build_manual_links([manual])
+ assert (link.strategy, link.match_type) == (LinkStrategy.MANUAL, "manual")
+
+
+ ("match_type", "kind", "strategy"),
+ [
+ ("exact", "http", LinkStrategy.EXACT_ID),
+ ("candidate", "http", LinkStrategy.PREFIX_STRIPPED),
+ ("manual", "grpc", LinkStrategy.MANUAL),
+ ("exact", "package", LinkStrategy.MANIFEST),
+ ("inferred", "co_change", None),
+ ],
+)
+def test_a_stored_artifact_without_strategies_still_reads_one(
+ match_type: str, kind: str, strategy: LinkStrategy | None
+) -> None:
+ edge = SystemEdge.from_dict(
+ {"id": "a->b", "source": "a", "target": "b", "kind": kind, "match_type": match_type}
+ )
+ assert edge.strategy == strategy
+ if kind != "co_change":
+ link = ContractLink.from_dict(
+ {
+ "contract_id": "x",
+ "contract_type": "http",
+ "match_type": match_type,
+ "provider_repo": "b",
+ "provider_file": "b.ts",
+ "consumer_repo": "a",
+ "consumer_file": "a.ts",
+ }
+ )
+ assert link.strategy == (strategy if kind != "package" else LinkStrategy.EXACT_ID)
diff --git a/tests/unit/workspace/test_php_clients.py b/tests/unit/workspace/test_php_clients.py
index 2dbee3ec0..0a7c3890c 100644
--- a/tests/unit/workspace/test_php_clients.py
+++ b/tests/unit/workspace/test_php_clients.py
@@ -20,6 +20,7 @@ from repowise.core.workspace.extractors.http.php_clients import (
laravel_http_calls,
)
from repowise.core.workspace.matching import match_contracts
+from repowise.core.workspace.origins import ContractOrigin
GUZZLE_REQUEST = """<?php
@@ -160,7 +161,7 @@ class TestPhpClientsRecognition:
def test_verb_form_reads_the_callee_name(self):
rows = list(guzzle_verb_calls(GUZZLE_VERBS))
assert [r.method for r in rows] == ["GET", "DELETE"]
- assert all(r.confidence == 0.65 for r in rows)
+ assert all(r.origin == ContractOrigin.NAME_HEURISTIC for r in rows)
def test_facade_reads_the_direct_and_the_chained_call(self):
rows = list(laravel_http_calls(LARAVEL_HTTP))
diff --git a/tests/unit/workspace/test_ruby_clients.py b/tests/unit/workspace/test_ruby_clients.py
index 62e5456d6..b1ecdf9a1 100644
--- a/tests/unit/workspace/test_ruby_clients.py
+++ b/tests/unit/workspace/test_ruby_clients.py
@@ -23,6 +23,7 @@ from repowise.core.workspace.extractors.http.ruby_clients import (
net_http_calls,
)
from repowise.core.workspace.matching import match_contracts
+from repowise.core.workspace.origins import ContractOrigin
HTTPARTY_RB = """\
class Dyte
@@ -184,7 +185,7 @@ class TestRubyClientsRecognition:
def test_connection_receiver_comes_from_faraday_new(self) -> None:
rows = list(faraday_connection_calls(FARADAY_RB))
- assert [(r.method, r.confidence) for r in rows] == [("GET", 0.65)]
+ assert [(r.method, r.origin) for r in rows] == [("GET", ContractOrigin.NAME_HEURISTIC)]
class TestRubyClientsContracts:
diff --git a/tests/unit/workspace/test_system_graph.py b/tests/unit/workspace/test_system_graph.py
index cf835875d..8259f01f1 100644
--- a/tests/unit/workspace/test_system_graph.py
+++ b/tests/unit/workspace/test_system_graph.py
@@ -46,7 +46,7 @@ def _consumer(repo, cid, ctype="http", file="src/client.py") -> Contract:
def _link(
- cid, p_repo, p_file, c_repo, c_file, ctype="http", match="exact", conf=0.72
+ cid, p_repo, p_file, c_repo, c_file, ctype="http", match="exact", conf=0.72, strategy=None
) -> ContractLink:
return ContractLink(
contract_id=cid,
@@ -61,6 +61,7 @@ def _link(
consumer_file=c_file,
consumer_symbol="call",
consumer_service=None,
+ strategy=strategy,
)
@@ -173,8 +174,10 @@ def test_parallel_links_aggregate_into_one_weighted_edge():
_consumer("web", "http::GET::/b", file="web/c.py"),
]
links = [
- _link("http::GET::/a", "api", "api/h.py", "web", "web/c.py", match="exact", conf=0.9),
- _link("http::GET::/b", "api", "api/h.py", "web", "web/c.py", match="candidate", conf=0.5),
+ _link("http::GET::/b", "api", "api/h.py", "web", "web/c.py", match="candidate", conf=0.5,
+ strategy="prefix_stripped"),
+ _link("http::GET::/a", "api", "api/h.py", "web", "web/c.py", match="exact", conf=0.9,
+ strategy="exact_id"),
]
graph = build_system_graph(contracts, links, CrossRepoOverlay(), {})
edges = _edges_by_key(graph)
@@ -182,6 +185,7 @@ def test_parallel_links_aggregate_into_one_weighted_edge():
assert edge.weight == 2
assert edge.confidence == 0.9 # max of contributors
assert edge.match_type == "exact" # most authoritative wins
+ assert edge.strategy == "exact_id" # the strategy behind the edge's confidence
assert set(edge.contract_refs) == {"http::GET::/a", "http::GET::/b"}
@@ -329,6 +333,7 @@ def test_system_graph_json_shape_is_locked():
"weight",
"structural",
"contract_refs",
+ "strategy",
}
assert set(data["diagnostics"]) == {
"total_providers",
@@ -370,3 +375,22 @@ def test_save_and_load(tmp_path: Path):
def test_load_missing_returns_none(tmp_path: Path):
assert load_system_graph(tmp_path) is None
+
+
+def test_adjacency_is_the_one_view_every_walk_reads():
+ from repowise.core.workspace.system_graph import SystemEdge
+
+ def edge(src, tgt, kind, structural=True):
+ return SystemEdge(
+ id=f"{src}->{tgt}:{kind}", source=src, target=tgt, kind=kind,
+ match_type="exact", confidence=1.0, weight=1, structural=structural,
+ )
+
+ http, event, co = edge("a", "b", "http"), edge("a", "b", "event"), edge("b", "c", "co_change", False)
+ graph = SystemGraph(edges=[http, event, co])
+ assert graph.adjacency() == {"a": {"b": [http, event]}}
+ assert graph.adjacency(impact=True) == {"b": {"a": [http, event]}}
+ assert graph.adjacency(behavioral=True, impact=True) == {
+ "b": {"a": [http, event], "c": [co]},
+ "c": {"b": [co]},
+ }
diff --git a/tests/unit/workspace/test_topic_matching.py b/tests/unit/workspace/test_topic_matching.py
index bab3b9cf5..3ebe8daec 100644
--- a/tests/unit/workspace/test_topic_matching.py
+++ b/tests/unit/workspace/test_topic_matching.py
@@ -290,6 +290,20 @@ class TestTransports:
assert len(match_contracts(same)) == 1
assert match_contracts(other) == []
+ def test_a_laravel_job_class_reads_only_a_laravel_dispatch(self) -> None:
+ job = _on("laravel", "consumer", "api", job="App\\Jobs\\NotifyTicketSold")
+ dispatch = _on("laravel", "provider", "web", job="App\\Jobs\\NotifyTicketSold")
+ # amqplib sendToQueue on a queue of the same name is not the job's envelope.
+ assert match_contracts([_on("rabbitmq", "provider", "events"), job]) == []
+ assert len(match_contracts([dispatch, job])) == 1
+ # Nor through an exchange binding onto the job's queue.
+ reader = _queue_consumer("api", "emails")
+ reader.meta.update(broker="laravel", job="App\\Jobs\\NotifyTicketSold")
+ bound = [_publisher(), _binding("api", "emails", "#", file="bind.ts"), reader]
+ assert [lk.consumer_file for lk in match_contracts(bound)] == []
+ # A Laravel dispatch still reaches a raw consumer of its queue.
+ assert len(match_contracts([dispatch, _on("rabbitmq", "consumer", "events")])) == 1
+
def test_a_name_that_only_looks_like_a_pattern_is_exact(self) -> None:
contracts = [
_topic("orders", "provider", "orders.created", "a.go", kind="subject"),