cg-code-graph 0.10.1__py3-none-any.whl

codegraph/protocols/builtin.py

@@ -0,0 +1,67 @@
+"""Built-in protocols. Adapter protocols describe node kinds cg already emitted before #31 (ids unchanged, read by
+protocols/view.py); `endpoint` protocols are filled by plugins through protocol_send / protocol_receive."""
+from __future__ import annotations
+
+from . import Protocol, register
+from . import matchers as M
+
+A = "adapter"
+# ---- existing kinds, adapted (no new nodes or edges)
+register(Protocol("http", "tcp", "HTTP request: client endpoint http:<METHOD> <path> -> route (MATCHES_ROUTE, cg link)",
+                  matcher=M.path, ports=(80, 443), schemes=("http", "https"), source=A, kinds=("http", "route"), guards=True))
+register(Protocol("ws", "tcp", "WebSocket route (Django Channels consumer, route:WS <path>)", matcher=M.path, ports=(80, 443),
+                  schemes=("ws", "wss"), source=A, kinds=("route",), guards=True))
+register(Protocol("graphql", "tcp", "GraphQL operation resolver (route:GRAPHQL Query.x)", source=A, kinds=("route",), guards=True))
+register(Protocol("pusher", "tcp", "Pusher protocol broadcast channel (Laravel Broadcast::channel / broadcastOn -> Echo / "
+                  "pusher-js subscription; MATCHES_CHANNEL; the `cg channels` view)", matcher=M.dotted, fanout=True,
+                  source=A, kinds=("channel", "channel_sub")))
+register(Protocol("nest-rpc", "tcp", "NestJS microservice request (ClientProxy.send -> @MessagePattern)", source=A,
+                  kinds=("message",), guards=True))
+register(Protocol("nest-event", "tcp", "NestJS microservice event (ClientProxy.emit -> @EventPattern)", fanout=True, source=A,
+                  kinds=("message",), guards=True))
+register(Protocol("nest-ws", "tcp", "NestJS WebSocket gateway message (@SubscribeMessage)", source=A, kinds=("message",),
+                  guards=True))
+register(Protocol("grpc", "tcp", "gRPC method (NestJS @GrpcMethod)", source=A, kinds=("message",), guards=True))
+register(Protocol("bull", "tcp", "Bull / BullMQ job queue (Queue.add -> @Processor / @Process, WorkerHost.process)",
+                  source=A, kinds=("job",)))
+register(Protocol("laravel-queue", "tcp", "Laravel queued job (dispatch / Bus / schedule -> Job::handle)", source=A,
+                  kinds=("job",)))
+register(Protocol("celery", "tcp", "Celery / RQ / Dramatiq task (.delay / .apply_async / send_task -> task function)",
+                  source=A, kinds=("job",)))
+register(Protocol("laravel-event", "local", "Laravel application event (event() / dispatch -> listener handle())",
+                  fanout=True, entry=False, source=A, kinds=("event",)))
+register(Protocol("nest-event-emitter", "local", "NestJS EventEmitter2 event (emit -> @OnEvent)", fanout=True, entry=False,
+                  source=A, kinds=("event",)))
+register(Protocol("django-signal", "local", "Django signal (send -> @receiver)", fanout=True, entry=False, source=A,
+                  kinds=("event",), framework_senders=("django.*",)))
+
+# ---- web / native bridges and desktop process boundaries (codegraph/bridges.py: endpoint nodes with their own checks)
+for _n, _t, _d in (("capacitor", "local", "Capacitor plugin method"), ("react-native", "local", "React Native / Expo native module method"),
+                   ("flutter", "local", "Flutter MethodChannel method"), ("flutter-event", "local", "Flutter EventChannel stream"),
+                   ("pigeon", "local", "Pigeon API method"), ("electron-ipc", "ipc", "Electron IPC channel"),
+                   ("electron-preload", "local", "Electron context bridge member"), ("tauri", "ipc", "Tauri command")):
+    register(Protocol(_n, _t, _d + " (`cg bridges`)", entry=False, source="bridges"))
+
+# ---- endpoint protocols (protocol_send / protocol_receive; matchers run at index and link time)
+register(Protocol("mqtt", "tcp", "MQTT topic (publish -> subscribe, `+` / `#` wildcards)", matcher=M.mqtt, fanout=True,
+                  ports=(1883, 8883), schemes=("mqtt", "mqtts")))
+register(Protocol("nats", "tcp", "NATS subject (publish / request -> subscribe, `*` / `>` wildcards)", matcher=M.nats,
+                  fanout=True, ports=(4222,), schemes=("nats", "tls")))
+register(Protocol("amqp", "tcp", "AMQP 0-9-1 routing key on a topic exchange (`*` / `#`)", matcher=M.amqp_topic,
+                  fanout=True, ports=(5672, 5671), schemes=("amqp", "amqps")))
+register(Protocol("kafka", "tcp", "Kafka topic (produce -> consumer group subscription; regex subscriptions as globs)",
+                  matcher=M.glob, fanout=True, ports=(9092,), schemes=("kafka",)))
+register(Protocol("redis-pubsub", "tcp", "Redis PUBLISH -> SUBSCRIBE / PSUBSCRIBE (glob patterns)", matcher=M.glob,
+                  fanout=True, ports=(6379,), schemes=("redis", "rediss")))
+register(Protocol("socketio", "tcp", "Socket.IO event (<namespace>#<event>; emit -> on, both directions; python-socketio "
+                  "server and client)", matcher=M.template, ports=(80, 443), schemes=("ws", "wss", "http", "https"), guards=True,
+                  directional=True))
+
+# ---- AI harnesses (#66, codegraph/plugins/python/aitools.py): tools the model or an MCP client calls by name
+register(Protocol("llm_tool", "local", "LLM tool / function: schema offered to the model (OpenAI, Anthropic, LangChain, "
+                  "Agents SDK, LlamaIndex) -> handler (decorated function, dict registry, agent-loop branch)",
+                  entry_kind="llm_tool"))
+for _n, _d in (("mcp_tool", "MCP tool"), ("mcp_resource", "MCP resource (URI template)"), ("mcp_prompt", "MCP prompt")):
+    register(Protocol(_n, "tcp", f"{_d}: <server>/<name>; client call_tool / read_resource / get_prompt -> FastMCP / "
+                      "MCPServer handler (`*/<name>` from a client that does not name the server)", matcher=M.mcp,
+                      entry_kind="llm_tool", schemes=("stdio", "http", "https")))

codegraph/protocols/matchers.py

@@ -0,0 +1,144 @@
+"""Shared name matchers of the protocol registry (codegraph/protocols/__init__.py).
+
+A matcher takes the name a sender uses and the name a receiver declares and returns None (no match) or a dict of
+segment counts, used to rank candidates and to set the confidence of the MATCHES_ENDPOINT edge:
+
+    lit          literal segment == literal segment
+    wild         a receiver wildcard / {param} took one segment (`orders.*` / `orders.{id}` ~ `orders.42`)
+    multi        a receiver multi-level wildcard took zero or more segments (MQTT `#`, NATS `>`, AMQP `#`, glob `**`)
+    ph_into_lit  a sender placeholder (`orders.{id}` built from a template) fitted a receiver literal (heuristic)
+
+Names use `{param}` for parameters on both sides (the builder normalises `${x}` / `:x` to it).
+"""
+from __future__ import annotations
+
+import fnmatch
+import re
+
+PARAM = re.compile(r"^\{[^{}]*\}$")
+
+
+def _info(**kw) -> dict:
+    d = {"lit": 0, "wild": 0, "multi": 0, "ph_into_lit": 0}
+    d.update(kw)
+    return d
+
+
+def exact(send: str, recv: str) -> dict | None:
+    """Same name (case-sensitive)."""
+    return _info(lit=1) if send == recv else None
+
+
+def glob(send: str, recv: str) -> dict | None:
+    """Receiver name as a shell-style glob (`*`, `?`, `[...]`) over the whole name; literal characters rank."""
+    if send == recv:
+        return _info(lit=1)
+    if not any(c in recv for c in "*?["):
+        return None
+    if not fnmatch.fnmatchcase(send, recv):
+        return None
+    return _info(lit=len(re.sub(r"[*?]|\[[^\]]*\]", "", recv)), wild=1)
+
+
+def path(send: str, recv: str) -> dict | None:
+    """URL-style paths split on `/`: the HTTP route matcher of cg link (`{param}`, `{rest*}` catch-alls, embedded
+    params), at least one literal segment in common."""
+    from ..link import match_path
+    ok, info = match_path(send, recv)
+    if not ok or (info["lit"] == 0 and (send.strip("/") or recv.strip("/"))):
+        return None
+    return _info(lit=info["lit"], wild=info["param"] + info["lit_into_param"], ph_into_lit=info["ph_into_lit"])
+
+
+def topic(sep: str, one: str | None, many: str | None, many_min: int = 0, many_last: bool = True):
+    """Dotted / slashed topic names with single- and multi-level wildcards in the receiver's subscription:
+    MQTT topic('/', '+', '#') (`#` last, also matches the parent level), NATS topic('.', '*', '>', many_min=1),
+    AMQP topic exchange topic('.', '*', '#', many_last=False) (`#` anywhere, zero or more words).
+    `{param}` segments act as single-level wildcards on the receiver side and as placeholders on the sender side."""
+
+    def match(send: str, recv: str) -> dict | None:
+        s, r = send.split(sep), recv.split(sep)
+        if many_last and many in r[:-1]:
+            return None                    # `#` / `>` only as the last level
+        best: list[dict | None] = [None]
+
+        def go(i: int, j: int, acc: dict):
+            if j == len(r):
+                if i == len(s):
+                    rank = (acc["lit"], -acc["multi"], -acc["ph_into_lit"])
+                    if best[0] is None or rank > (best[0]["lit"], -best[0]["multi"], -best[0]["ph_into_lit"]):
+                        best[0] = dict(acc)
+                return
+            rs = r[j]
+            if many is not None and rs == many:
+                for k in range(i + many_min, len(s) + 1):
+                    go(k, j + 1, dict(acc, multi=acc["multi"] + 1))
+                return
+            if i >= len(s):
+                return
+            ss = s[i]
+            s_ph = bool(PARAM.match(ss))
+            if (one is not None and rs == one) or PARAM.match(rs):
+                go(i + 1, j + 1, dict(acc, wild=acc["wild"] + 1))
+            elif ss == rs:
+                go(i + 1, j + 1, dict(acc, lit=acc["lit"] + 1))
+            elif s_ph:
+                go(i + 1, j + 1, dict(acc, ph_into_lit=acc["ph_into_lit"] + 1))
+
+        go(0, 0, _info())
+        return best[0]
+
+    match.__doc__ = f"topic matcher sep={sep!r} one={one!r} many={many!r}"
+    return match
+
+
+def _tpl_rx(name: str) -> re.Pattern:
+    return re.compile("^" + "".join(".+?" if PARAM.match(part) else re.escape(part)
+                                    for part in re.split(r"(\{[^{}]*\})", name)) + "$", re.S)
+
+
+def template(send: str, recv: str) -> dict | None:
+    """Whole-name `{param}` templates (`order:{id}` ~ `order:42`, Socket.IO `<namespace>#<event>`): a receiver
+    template takes any non-empty text per parameter; a sender template fitting a receiver literal is a placeholder fit."""
+    if send == recv:
+        return _info(lit=1)
+    if "{" in recv and _tpl_rx(recv).match(send):
+        return _info(lit=len(re.sub(r"\{[^{}]*\}", "", recv)), wild=len(re.findall(r"\{[^{}]*\}", recv)))
+    if "{" in send and "{" not in recv and _tpl_rx(send).match(recv):
+        return _info(lit=len(re.sub(r"\{[^{}]*\}", "", send)), ph_into_lit=1)
+    return None
+
+
+def mcp(send: str, recv: str) -> dict | None:
+    """MCP primitives `<server>/<name or uri template>`: a client that does not know the server sends `*/<name>`; the
+    rest matches exactly or by `{param}` URI template (`notes://{id}` ~ `notes://42`)."""
+    ss, _, sr = send.partition("/")
+    rs, _, rr = recv.partition("/")
+    if ss not in ("*", rs):
+        return None
+    i = template(sr, rr)
+    if i is None:
+        return None
+    if ss == "*":
+        i["wild"] += 1
+    return i
+
+
+mqtt = topic("/", "+", "#")
+nats = topic(".", "*", ">", many_min=1)
+amqp_topic = topic(".", "*", "#", many_last=False)
+dotted = topic(".", None, None)          # `{param}` templates only (Laravel channel names, Socket.IO rooms)
+
+MATCHERS = {"exact": exact, "glob": glob, "path": path, "template": template, "mqtt": mqtt, "nats": nats, "amqp_topic": amqp_topic,
+            "dotted": dotted, "mcp": mcp}
+
+
+def rank(info: dict) -> tuple:
+    """Higher is more specific: fewer placeholder-into-literal fits, more literal segments, fewer wildcards."""
+    return (-info["ph_into_lit"], info["lit"], -info["multi"], -info["wild"])
+
+
+def confidence(info: dict, tied: bool) -> str:
+    if info["ph_into_lit"] or tied:
+        return "heuristic"
+    return "resolved" if (info["wild"] or info["multi"]) else "exact"

codegraph/protocols/view.py

@@ -0,0 +1,334 @@
+"""`cg protocols` / MCP `protocol_links`: every protocol endpoint of a graph in one view.
+
+Endpoints come from the generic model (`endpoint:<protocol>:<name>` with SENDS_TO / RECEIVED_BY / MATCHES_ENDPOINT)
+and from the node kinds cg emitted before it, read through adapters with their ids unchanged:
+
+  kind          protocol                         senders (into the node)            receivers                 matches
+  http          http (ws for http:WS ...)        HTTP_CALLS                         -                         MATCHES_ROUTE ->
+  route         http / ws / graphql              (test: TEST_HTTP)                  ROUTES_TO                 <- MATCHES_ROUTE
+  channel       pusher                           BROADCASTS_ON (events)             -                         <- MATCHES_CHANNEL
+  channel_sub   pusher                           -                                  SUBSCRIBES_CHANNEL (code) MATCHES_CHANNEL ->
+  message       nest-rpc / nest-event / nest-ws / grpc   DISPATCHES                 HANDLED_BY
+  job           bull / laravel-queue / celery    DISPATCHES (also to the handler,   HANDLED_BY
+                                                 via=job), SCHEDULES
+  event         laravel-event / nest-event-emitter / django-signal   DISPATCHES     LISTENED_BY / HANDLED_BY
+  endpoint      attrs.protocol (bridges, MQTT, Socket.IO, ...)   SENDS_TO           RECEIVED_BY               MATCHES_ENDPOINT
+
+Checks (per endpoint; a side is judged only when the graph holds some endpoint of that protocol on the other side, so
+a single backend graph does not call every route `no_sender`):
+  no_receiver      sent, nothing receives it here (directly or through a match)
+  no_sender        received, nothing sends it (dead handler, or the producer is outside the analysed repos)
+  test_sender_only received, sent from tests only
+  ambiguous        one sender matched several receivers equally well
+  schema_mismatch  senders and receivers name different message types
+  unguarded        a receiver reachable from outside (http / ws / graphql routes, Socket.IO handlers, ...) with no
+                   auth guard recorded (the same classification as `cg routes --unguarded`)
+  external         declared external in .cg.yaml (protocols.external: ["kafka:audit.*"]), a third-party HTTP origin,
+                   or a bridge module implemented outside the repo
+Bridge endpoints (Capacitor, React Native, Flutter, Electron, Tauri) keep the checks codegraph/bridges.py computed.
+"""
+from __future__ import annotations
+
+import fnmatch
+import json
+from collections import defaultdict
+
+from . import REGISTRY, compatible, external_match
+
+KINDS = ("http", "route", "channel", "channel_sub", "message", "job", "event", "endpoint")
+EDGE_ROLE_KINDS = ("HTTP_CALLS", "MATCHES_ROUTE", "ROUTES_TO", "USES_MIDDLEWARE", "TEST_HTTP", "BROADCASTS_ON",
+                   "SUBSCRIBES_CHANNEL", "MATCHES_CHANNEL", "DISPATCHES", "HANDLED_BY", "LISTENED_BY", "SCHEDULES",
+                   "SENDS_TO", "RECEIVED_BY", "MATCHES_ENDPOINT", "TEST_CALLS")
+NEST = {"rpc": "nest-rpc", "event": "nest-event", "ws": "nest-ws", "grpc": "grpc"}
+SEND_IN = {"http": ("HTTP_CALLS",), "channel": ("BROADCASTS_ON",), "message": ("DISPATCHES",),
+           "job": ("DISPATCHES", "SCHEDULES"), "event": ("DISPATCHES",), "endpoint": ("SENDS_TO",)}
+RECV_OUT = {"route": ("ROUTES_TO",), "message": ("HANDLED_BY",), "job": ("HANDLED_BY",),
+            "event": ("LISTENED_BY", "HANDLED_BY"), "endpoint": ("RECEIVED_BY",)}
+RECV_IN = {"channel_sub": ("SUBSCRIBES_CHANNEL",)}
+MATCH = ("MATCHES_ROUTE", "MATCHES_CHANNEL", "MATCHES_ENDPOINT")
+TEST_ORIG = ("HTTP_CALLS", "DISPATCHES", "SENDS_TO", "SUBSCRIBES_CHANNEL")
+
+
+def protocol_of(kind: str, nid: str, a: dict, lang: str | None) -> str | None:
+    if kind == "endpoint":
+        return a.get("protocol")
+    if kind == "http":
+        return "ws" if a.get("method") == "WS" else "http"
+    if kind == "route":
+        m = (a.get("method") or "").upper()
+        return "ws" if m == "WS" else "graphql" if m == "GRAPHQL" else "http"
+    if kind in ("channel", "channel_sub"):
+        return "pusher"
+    if kind == "message":
+        return NEST.get(a.get("transport") or nid.split(":")[1], "nest-" + (a.get("transport") or "message"))
+    if kind == "job":
+        fw = a.get("framework") or ""
+        return "bull" if fw.startswith("bull") or lang == "ts" else "laravel-queue" if lang == "php" else "celery"
+    if kind == "event":
+        fw = a.get("framework") or ""
+        if fw == "nest-event-emitter" or lang == "ts":
+            return "nest-event-emitter"
+        return "django-signal" if a.get("signal") or lang == "python" else "laravel-event"
+    return None
+
+
+def name_of(kind: str, nid: str, name: str, a: dict) -> str:
+    key = nid.split(":", 1)[1]
+    if kind == "channel":
+        return a.get("pattern") or key
+    if kind == "channel_sub":
+        return a.get("name") or key
+    if kind == "message":
+        return key.split(":", 1)[1] if ":" in key else key
+    if kind == "endpoint":
+        return name or key.split(":", 1)[-1]
+    return key
+
+
+def _externals(st) -> list[str]:
+    """protocols.external of the indexed repo(s) (.cg.yaml, recorded in the index stats)."""
+    from ..routes import _meta_of
+    try:
+        m = st.meta()
+    except Exception:  # noqa: BLE001
+        return []
+    metas = [_meta_of((m.get("sources") or {}).get(r)) for r in m.get("repos") or []] or [m]
+    out = []
+    for mm in metas:
+        out += (((mm.get("stats") or {}).get("config") or {}).get("protocols") or {}).get("external") or []
+    return list(dict.fromkeys(out))
+
+
+def _load(st):
+    nodes = {}
+    q = ",".join("?" * len(KINDS))
+    for r in st.q(f"SELECT id, kind, name, file, line, lang, attrs, entry_kind FROM nodes WHERE kind IN ({q})", KINDS):
+        a = json.loads(r["attrs"] or "{}") if r["attrs"] else {}
+        proto = protocol_of(r["kind"], r["id"], a, r["lang"])
+        if not proto:
+            continue
+        nodes[r["id"]] = {"id": r["id"], "kind": r["kind"], "protocol": proto, "name": name_of(r["kind"], r["id"], r["name"], a),
+                          "file": r["file"], "line": r["line"], "attrs": a, "entry_kind": r["entry_kind"]}
+    q2 = ",".join("?" * len(EDGE_ROLE_KINDS))
+    edges = [dict(r) for r in st.q(f"SELECT src, dst, kind, file, line, confidence, attrs FROM edges WHERE kind IN ({q2})",
+                                   EDGE_ROLE_KINDS)]
+    return nodes, edges
+
+
+def collect(st) -> dict:
+    """Every endpoint with senders / receivers / matches / guards / checks (no per-endpoint queries)."""
+    from ..routes import AuthMatcher, guard_setup, route_guards
+    nodes, edges = _load(st)
+    ep = {nid: dict(n, senders=[], test_senders=[], receivers=[], matches=[], mw=[]) for nid, n in nodes.items()}
+    job_of_handler = {}
+    for e in edges:
+        if e["kind"] == "HANDLED_BY" and e["src"] in ep and ep[e["src"]]["kind"] == "job":
+            job_of_handler.setdefault(e["dst"], e["src"])
+    for e in edges:
+        k, s, d = e["kind"], e["src"], e["dst"]
+        a = json.loads(e["attrs"] or "{}") if e["attrs"] else {}
+        at = f"{e['file']}:{e['line']}"
+        if k in MATCH:
+            if s in ep and d in ep:
+                ep[s]["matches"].append({"endpoint": d, "confidence": e["confidence"], "dir": "out", "kind": k,
+                                         "ambiguous": a.get("ambiguous")})
+                ep[d]["matches"].append({"endpoint": s, "confidence": e["confidence"], "dir": "in", "kind": k})
+            continue
+        if k == "USES_MIDDLEWARE":
+            if s in ep:
+                ep[s]["mw"].append(e)
+            continue
+        if k in ("TEST_CALLS", "TEST_HTTP"):
+            if d in ep and (k == "TEST_HTTP" or a.get("orig") in TEST_ORIG):
+                ep[d]["test_senders"].append({"fn": s, "at": at, "confidence": e["confidence"]})
+            continue
+        if d in ep and k in SEND_IN.get(ep[d]["kind"], ()):
+            ep[d]["senders"].append({"fn": s, "at": at, "confidence": e["confidence"], "via": a.get("via") or a.get("role"),
+                                     **({k2: a[k2] for k2 in ("schema", "process") if a.get(k2)})})
+        elif k == "DISPATCHES" and a.get("via") == "job" and d in job_of_handler:
+            ep[job_of_handler[d]]["senders"].append({"fn": s, "at": at, "confidence": e["confidence"], "via": "dispatch"})
+        if s in ep and k in RECV_OUT.get(ep[s]["kind"], ()):
+            ep[s]["receivers"].append({"handler": d, "at": at, "confidence": e["confidence"],
+                                       **({k2: a[k2] for k2 in ("platform", "process", "schema") if a.get(k2)})})
+        if d in ep and k in RECV_IN.get(ep[d]["kind"], ()):
+            ep[d]["receivers"].append({"handler": s, "at": at, "confidence": e["confidence"]})
+    # sides per protocol
+    psend, precv = defaultdict(bool), defaultdict(bool)
+    for n in ep.values():
+        psend[n["protocol"]] |= bool(n["senders"])
+        precv[n["protocol"]] |= bool(n["receivers"])
+    gs = guard_setup(st)
+    is_auth = AuthMatcher(None, gs["applied"], gs["auth_patterns"], gs["secret_patterns"])
+    ext = _externals(st)
+    for n in ep.values():
+        a, p = n["attrs"], REGISTRY.get(n["protocol"])
+        peers = [ep[m["endpoint"]] for m in n["matches"]]
+        # a directional protocol (Socket.IO): this endpoint's own senders and receivers pair up only across processes
+        own = compatible(p, {x["process"] for x in n["senders"] if x.get("process")},
+                         {x["process"] for x in n["receivers"] if x.get("process")})
+        psent = any(x["senders"] for x in peers)
+        precv_ = any(x["receivers"] or x["kind"] == "route" for x in peers)   # a matched route receives
+        if own:
+            sent = bool(n["senders"]) or psent
+            recv = bool(n["receivers"]) or precv_
+        else:                      # e.g. a client emits `x` and a client handles `x`: neither reaches the other
+            sent = psent or (bool(n["senders"]) and not n["receivers"])
+            recv = precv_ or (bool(n["receivers"]) and not n["senders"])
+        n["side"] = "both" if n["senders"] and n["receivers"] else "send" if n["senders"] or (n["kind"] == "http") \
+            else "receive" if n["receivers"] or n["kind"] in ("route",) else ("send" if n["test_senders"] else "none")
+        n["linked"] = sent and recv
+        if not own:
+            n["linked"] = bool((n["senders"] and precv_) or (n["receivers"] and psent))
+        ck = []
+        n["external"] = None
+        if p and p.source == "bridges":
+            ck = list(a.get("checks") or [])
+            n["external"] = a.get("package") or ("implemented outside this repo" if a.get("external") else None)
+        else:
+            hit = external_match(ext, n["protocol"], n["name"])
+            if hit:
+                n["external"] = f".cg.yaml protocols.external {hit}"
+            elif p and not sent and any(fnmatch.fnmatchcase(n["name"], g) for g in p.framework_senders):
+                n["external"] = "sent by the framework"
+            elif n["kind"] == "http" and a.get("origin_kind") == "other":
+                n["external"] = f"other origin {a.get('origin')}"
+            test_only = bool(a.get("test_only"))
+            skip_route = n["kind"] == "route" and (a.get("mounted", True) is False or a.get("framework") == "django-admin")
+            if (sent and not recv or not own and n["senders"] and not precv_) and precv[n["protocol"]] \
+                    and not n["external"] and not test_only:
+                ck.append("no_receiver")
+            if (recv and not sent or not own and n["receivers"] and not psent) and psend[n["protocol"]] \
+                    and not n["external"] and not skip_route:
+                ck.append("test_sender_only" if n["test_senders"] or any(x["test_senders"] for x in peers) else "no_sender")
+            outs = [m for m in n["matches"] if m["dir"] == "out"]
+            amb = any(m.get("ambiguous") for m in outs)
+            if not amb and len(outs) > 1:
+                if n["kind"] == "http":
+                    amb = True                 # several routes equally specific (cg link keeps the ties, heuristic)
+                elif n["kind"] == "channel_sub":
+                    amb = any(m["confidence"] == "heuristic" for m in outs)
+                elif n["kind"] == "endpoint":
+                    amb = not (p and p.fanout)
+            if amb:
+                ck.append("ambiguous")
+            ss = {x["schema"] for x in n["senders"] + [y for q in peers for y in q["senders"]] if x.get("schema")}
+            rs = {x["schema"] for x in n["receivers"] + [y for q in peers for y in q["receivers"]] if x.get("schema")}
+            if a.get("schema"):
+                (rs if n["receivers"] else ss).add(a["schema"])
+            if ss and rs and not (ss & rs):
+                ck.append("schema_mismatch")
+                n["schemas"] = {"sent": sorted(ss), "received": sorted(rs)}
+        # guards: routes as in `cg routes`, generic receivers from attrs.guards
+        if n["kind"] == "route" or (n["kind"] in ("endpoint", "message") and "guards" in a):
+            if n["kind"] == "route":
+                g = route_guards(a, n["mw"], is_auth)
+            elif n["kind"] == "message":   # Nest @UseGuards / APP_GUARD class names: classified like route guards (#69)
+                g = [{"name": x, "auth": is_auth(x), "secret": is_auth.secret(x)} for x in a.get("guards") or []]
+            else:   # recorded by the plugin as a check that rejects (connect handler, io.use, interceptor): auth
+                g = [{"name": x if isinstance(x, str) else x.get("name"), "auth": True} for x in a.get("guards") or []]
+            n["guards"] = [x["name"] for x in g]
+            has_auth = any(x["auth"] for x in g)
+            secret = any(x.get("secret") for x in g)
+            if (p and p.guards) and (n["receivers"] or n["kind"] == "route") and not has_auth and not secret and not n["external"] \
+                    and not (n["kind"] == "route" and (a.get("mounted", True) is False or a.get("framework") == "django-admin")):
+                ck.append("unguarded")
+        else:
+            n["guards"] = None
+        n["checks"] = ck
+    return ep
+
+
+def protocols(st, pattern: str | None = None, protocol: str | None = None, side: str | None = None,
+              unmatched: bool = False, max_items: int = 200) -> dict:
+    ep = collect(st)
+    summ = defaultdict(lambda: defaultdict(int))
+    for n in ep.values():
+        s = summ[n["protocol"]]
+        s["endpoints"] += 1
+        s["send"] += n["side"] in ("send", "both")
+        s["receive"] += n["side"] in ("receive", "both")
+        s["linked"] += n["linked"]
+        for c in n["checks"]:
+            s[c] += 1
+        s["external"] += bool(n["external"])
+    sel = []
+    listing = bool(pattern or protocol or side or unmatched)
+    if listing:
+        p = pattern[len("endpoint:"):] if pattern and pattern.startswith("endpoint:") else pattern
+        for nid in sorted(ep):
+            n = ep[nid]
+            if protocol and n["protocol"] != protocol:
+                continue
+            if side and n["side"] not in (side, "both"):
+                continue
+            if unmatched and not (n["checks"] or n["external"]):
+                continue
+            if p and not (n["id"] == p or fnmatch.fnmatchcase(n["name"], p) or fnmatch.fnmatchcase(n["id"].split(":", 1)[1], p)
+                          or fnmatch.fnmatchcase(f"{n['protocol']}:{n['name']}", p) or p.lower() in n["name"].lower()):
+                continue
+            sel.append(n)
+    detail = 0 < len(sel) <= 6
+    out = []
+    for n in sel[:max_items]:
+        item = {k: n[k] for k in ("id", "kind", "protocol", "name", "side", "linked", "checks", "external", "guards", "senders",
+                                  "test_senders", "receivers", "matches")}
+        item["at"] = f"{n['file']}:{n['line']}" if n["file"] else None
+        item["transport"] = (REGISTRY.get(n["protocol"]).transport if REGISTRY.get(n["protocol"]) else None)
+        if n.get("schemas"):
+            item["schemas"] = n["schemas"]
+        if n["attrs"].get("test_only"):
+            item["test_only"] = True
+        if detail:
+            for s in item["senders"]:
+                s["entry_kinds"] = {e["entry_kind"]: e["entry_count"] for e in
+                                    st.q("SELECT entry_kind, entry_count FROM node_entry WHERE node_id=?", (s["fn"],))}
+        out.append(item)
+    reg = [{"name": p.name, "transport": p.transport, "matcher": getattr(p.matcher, "__name__", "custom"), "fanout": p.fanout,
+            "source": p.source, "description": p.description} for p in REGISTRY.values()]
+    return {"pattern": pattern, "protocol": protocol, "side": side, "unmatched": unmatched,
+            "summary": {k: dict(v) for k, v in sorted(summ.items())}, "endpoints": out, "selected": len(sel),
+            "listing": listing, "registry": reg}
+
+
+def render_protocols(res: dict, max_items: int = 60) -> str:
+    from ..query import short_id
+    L = []
+    if not res["summary"]:
+        return "no protocol endpoints in this graph (HTTP calls / routes, channels, messages, jobs, events, bridges)"
+    if not res["listing"]:
+        L.append("protocol            endpoints  send  receive  linked  checks")
+        for p, s in res["summary"].items():
+            ck = ", ".join(f"{k} {v}" for k, v in s.items() if k not in ("endpoints", "send", "receive", "linked") and v)
+            L.append(f"{p:<19} {s['endpoints']:>9}  {s.get('send', 0):>4}  {s.get('receive', 0):>7}  {s.get('linked', 0):>6}  {ck or '-'}")
+        L.append("(cg protocols --protocol P | PATTERN | --unmatched for endpoints; cg link / channels / bridges for the "
+                 "HTTP, Pusher and bridge views)")
+        return "\n".join(L)
+    eps = res["endpoints"]
+    if not eps:
+        return "no protocol endpoint matches " + ", ".join(
+            f"{k}={res[k]!r}" for k in ("pattern", "protocol", "side") if res.get(k)) + (" (unmatched only)" if res["unmatched"] else "")
+    detail = len(eps) <= 6
+    for i in eps[:max_items]:
+        flags = list(i["checks"]) + ([f"external ({i['external']})"] if i["external"] else [])
+        L.append(f"[{i['protocol']}] {i['name']}  ({i['side']}{', linked' if i['linked'] else ''})"
+                 + (f"  guards: {', '.join(i['guards']) or 'none'}" if i["guards"] is not None else "")
+                 + (f"  ! {'; '.join(flags)}" if flags else ""))
+        if detail:
+            L.append(f"    node {i['id']}" + (f" @ {i['at']}" if i.get("at") else ""))
+            for s in i["senders"][:8]:
+                ek = ", ".join(f"{k}({v})" for k, v in sorted((s.get("entry_kinds") or {}).items()))
+                L.append(f"    sent by {short_id(s['fn'])} @ {s['at']} [{s['confidence']}]" + (f"  entries: {ek}" if ek else ""))
+            for s in i["test_senders"][:4]:
+                L.append(f"    test {short_id(s['fn'])} @ {s['at']}")
+            for r in i["receivers"][:8]:
+                L.append(f"    received by {short_id(r['handler'])} @ {r['at']} [{r['confidence']}]")
+            for m in i["matches"][:8]:
+                L.append(f"    {'matches' if m['dir'] == 'out' else 'matched by'} {m['endpoint']} [{m['confidence']}]")
+            if i.get("schemas"):
+                L.append(f"    schemas: sent {i['schemas']['sent']} / received {i['schemas']['received']}")
+        else:
+            L.append(f"    senders {len(i['senders'])}" + (f" (+{len(i['test_senders'])} test)" if i["test_senders"] else "")
+                     + f", receivers {len(i['receivers'])}, matches {len(i['matches'])}")
+    if res["selected"] > min(len(eps), max_items):
+        L.append(f"... {res['selected'] - min(len(eps), max_items)} more")
+    return "\n".join(L)