graphlens-link 0.5.0__tar.gz

graphlens_link-0.5.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.3
+Name: graphlens-link
+Version: 0.5.0
+Summary: Cross-language boundary linker for graphlens
+Requires-Dist: graphlens
+Requires-Python: >=3.13

graphlens_link-0.5.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "graphlens-link"
+version = "0.5.0"
+description = "Cross-language boundary linker for graphlens"
+requires-python = ">=3.13"
+dependencies = [
+    "graphlens",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+graphlens = { workspace = true }
+
+[tool.bandit]
+skips = ["B101"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["graphlens_link"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "\\.\\.\\.",
+]

graphlens_link-0.5.0/src/graphlens_link/__init__.py

@@ -0,0 +1,5 @@
+"""Cross-language boundary linker for graphlens graphs."""
+
+from graphlens_link._linker import LinkResult, link_graph
+
+__all__ = ["LinkResult", "link_graph"]

graphlens_link-0.5.0/src/graphlens_link/_linker.py

@@ -0,0 +1,101 @@
+"""Cross-language boundary linker: a pure ``graph -> graph`` transform."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from graphlens import NodeKind, Relation, RelationKind
+
+if TYPE_CHECKING:
+    from graphlens import GraphLens
+
+
+@dataclass(frozen=True)
+class LinkResult:
+    """Summary of a single cross-language link pass."""
+
+    relations_added: int
+    boundaries_total: int
+    boundaries_linked: int
+    """Boundaries that had at least one provider *and* one consumer."""
+
+
+def _as_float(value: object, default: float = 1.0) -> float:
+    """Coerce a metadata value to a float, falling back to ``default``."""
+    if isinstance(value, bool):
+        return default
+    if isinstance(value, (int, float)):
+        return float(value)
+    return default
+
+
+def link_graph(graph: GraphLens, *, min_confidence: float = 0.0) -> LinkResult:
+    """
+    Add ``COMMUNICATES_WITH`` edges across cross-language boundaries.
+
+    Adapters emit a shared ``BOUNDARY`` node per contract (id derived purely
+    from mechanism + key) with ``EXPOSES`` edges from servers and
+    ``CONSUMES`` edges from clients.  This pass pairs, for every boundary,
+    each consumer with each provider and adds a directed
+    ``consumer -> provider`` edge carrying the boundary's ``mechanism`` and
+    the product of the two sides' confidences.
+
+    The graph is mutated in place.  The pass is idempotent: an edge for the
+    same ``(source, target, boundary)`` is never added twice, so it is safe
+    to run after re-analyzing part of the graph.  Two distinct boundaries
+    between the same consumer/provider pair each get their own edge.  Pairs
+    whose combined confidence is below ``min_confidence`` are skipped.
+    """
+    added = 0
+    linked = 0
+    boundaries = graph.nodes_by_kind(NodeKind.BOUNDARY)
+    existing: set[tuple[str, str, str]] = {
+        (r.source_id, r.target_id, str(r.metadata.get("boundary_id", "")))
+        for r in graph.relations
+        if r.kind == RelationKind.COMMUNICATES_WITH
+    }
+    for boundary in boundaries:
+        consumers = graph.incoming(boundary.id, RelationKind.CONSUMES)
+        providers = graph.incoming(boundary.id, RelationKind.EXPOSES)
+        if not consumers or not providers:
+            continue
+        linked += 1
+        mechanism = str(boundary.metadata.get("mechanism", ""))
+        boundary_key = str(boundary.metadata.get("key", ""))
+        for consumer in consumers:
+            for provider in providers:
+                if consumer.source_id == provider.source_id:
+                    continue
+                confidence = _as_float(
+                    consumer.metadata.get("confidence")
+                ) * _as_float(provider.metadata.get("confidence"))
+                if confidence < min_confidence:
+                    continue
+                dedupe = (
+                    consumer.source_id,
+                    provider.source_id,
+                    boundary.id,
+                )
+                if dedupe in existing:
+                    continue
+                existing.add(dedupe)
+                graph.add_relation(
+                    Relation(
+                        source_id=consumer.source_id,
+                        target_id=provider.source_id,
+                        kind=RelationKind.COMMUNICATES_WITH,
+                        metadata={
+                            "mechanism": mechanism,
+                            "boundary_id": boundary.id,
+                            "boundary_key": boundary_key,
+                            "confidence": confidence,
+                        },
+                    )
+                )
+                added += 1
+    return LinkResult(
+        relations_added=added,
+        boundaries_total=len(boundaries),
+        boundaries_linked=linked,
+    )