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

codegraph/process_runs.py

@@ -0,0 +1,328 @@
+"""Programs a test starts in a subprocess, in languages other than Python (#60; Python: plugins/python/subproc.py).
+
+A source scan over test code (and helpers) finds process starts whose program is the project's own entry point and
+adds CALLS (attrs.via = "subprocess", attrs.how) from the enclosing function / test to it; `isolate_tests` turns them
+into TEST_CALLS, so `cg tests` counts the test for what the program reaches:
+
+  * Rust: `env!("CARGO_BIN_EXE_x")`, `Command::cargo_bin("x")` / `cargo_bin!("x")` (assert_cmd, escargot) ->
+    the `main` of bin target `x` (Cargo.toml, auto-discovered `src/main.rs` / `src/bin/*`); `CARGO_PKG_NAME` -> the
+    bin named like the test's package;
+  * Node: `spawn / spawnSync / execFile / execFileSync / fork / exec / execSync` (child_process) and
+    `execa / execaSync / execaNode / execaCommand` running `node | tsx | ts-node | bun | process.execPath` with a
+    project script, `fork(script)`, or a `package.json` `bin` name -> that script's module node;
+  * PHP: `new Process(['php', 'artisan', 'x'])`, `Process::run('php artisan x')`, `exec / shell_exec / system /
+    passthru('php artisan x')` -> the artisan command node (`$this->artisan()` and `Artisan::call()` are modelled by
+    the Laravel plugin);
+  * Dart: `Process.run / runSync / start('dart', ['run'?, 'bin/x.dart', ...])`, `TestProcess.start(...)`
+    (`Platform.resolvedExecutable` as the program too) -> `main` of that file.
+Go has no language plugin, so `exec.Command(os.Args[0])` / `go run ./cmd/x` are not linked. Names passed in the call
+are read from their last assignment earlier in the same function (`var script = p.join(dir, '../bin/x.dart')`);
+values built in other functions or from configuration are not followed (the Python layer evaluates further).
+"""
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from bisect import bisect_right
+from collections import defaultdict
+
+from .core.model import RESOLVED
+
+JS_EXT = (".js", ".mjs", ".cjs", ".ts", ".mts", ".cts", ".jsx", ".tsx")
+SCAN_EXT = JS_EXT + (".rs", ".php", ".dart")
+LIT = re.compile(r"""(?P<q>['"`])(?P<s>(?:\\.|(?!(?P=q)).)*?)(?P=q)""", re.S)
+RUST_RX = re.compile(r'CARGO_BIN_EXE_([A-Za-z0-9_\-]+)|cargo_bin!?\s*\(\s*(?:"([^"]+)"|env!\s*\(\s*"CARGO_PKG_NAME"\s*\))')
+JS_RX = re.compile(r"\b(spawn|spawnSync|execFile|execFileSync|fork|exec|execSync|execa|execaSync|execaNode|"
+                   r"execaCommand|execaCommandSync)\s*\(")
+PHP_RX = re.compile(r"new\s+Process\s*\(|Process::(?:run|start|pipe)\s*\(|\b(?:exec|shell_exec|system|passthru)\s*\(")
+DART_RX = re.compile(r"\b(?:Process\.(?:run|runSync|start)|TestProcess\.start)\s*\(")
+JS_RUNTIMES = {"node", "nodejs", "tsx", "ts-node", "bun", "deno"}
+
+
+def _args_text(src: str, start: int, limit: int = 600) -> str:
+    """Text of the call's argument list from the `(` at `start` (balanced parentheses / brackets)."""
+    depth, i, n = 0, start, min(len(src), start + limit)
+    while i < n:
+        c = src[i]
+        if c in "([{":
+            depth += 1
+        elif c in ")]}":
+            depth -= 1
+            if depth == 0:
+                return src[start + 1:i]
+        elif c in "'\"`":
+            m = LIT.match(src, i)
+            if m:
+                i = m.end()
+                continue
+        i += 1
+    return src[start + 1:n]
+
+
+def _lits(text: str) -> list[str]:
+    return [m.group("s") for m in LIT.finditer(text)]
+
+
+class _Scan:
+    def __init__(self, project, b):
+        self.root, self.b = project.root, b
+        self.st = defaultdict(int)
+        self.samples = defaultdict(list)
+        self.by_file = defaultdict(list)          # file -> [(line, end_line, nid)] for functions / tests
+        self.modules = {}                          # file -> module node id
+        self.mains = {}                            # file -> main function id
+        self.commands = {}                         # artisan command name -> node id
+        for nid, n in b.nodes.items():
+            if not n.file:
+                continue
+            if n.kind == "module":
+                self.modules.setdefault(n.file, nid)
+            elif n.kind in ("function", "method", "test") and n.line:
+                self.by_file[n.file].append((n.line, n.end_line or n.line, nid))
+                if n.name == "main" or nid.endswith("#main") or nid.endswith("::main"):
+                    if n.kind == "function":
+                        self.mains.setdefault(n.file, nid)
+            elif n.kind == "command":
+                self.commands[n.name] = nid
+        for f in self.by_file.values():
+            f.sort()
+        self.files = sorted(self.modules) + sorted(set(self.mains) - set(self.modules))
+
+    # ---------------------------------------------------------------- shared
+    def enclosing(self, file, line):
+        best = None
+        for ln, end, nid in self.by_file.get(file, ()):
+            if ln <= line <= end and (best is None or end - ln < best[0]):
+                best = (end - ln, nid)
+        return best[1] if best else self.modules.get(file)
+
+    def assigned_lits(self, file, src, pos, args) -> list[str]:
+        """Literals assigned to the names the call passes (`var script = p.join(dir, '../bin/x.dart');` earlier in
+        the same function, else a module-level constant above it): the last assignment before the call. Values built
+        in other functions are not followed."""
+        line = src.count("\n", 0, pos) + 1
+        start = 1
+        for ln, end, _nid in self.by_file.get(file, ()):
+            if ln <= line <= end and ln > start:
+                start = ln
+        lo = 0
+        for _ in range(start - 1):
+            lo = src.find("\n", lo) + 1
+        body, out = src[lo:pos], []
+        for ident in dict.fromkeys(re.findall(r"(?<![\w.$])([A-Za-z_]\w*)\b(?!\s*[(.])", LIT.sub("", args))):
+            rx = re.compile(rf"(?<![\w.$]){re.escape(ident)}\s*=(?!=)\s*([^;]+);")
+            ms = list(rx.finditer(body)) or list(rx.finditer(src[:lo]))   # else a module-level constant above
+            if ms:
+                out += _lits(ms[-1].group(1))
+        return out
+
+    def add(self, file, line, dst, how, cmd):
+        src = self.enclosing(file, line)
+        if src is None or src == dst:
+            return
+        self.b.add_edge(src, dst, "CALLS", file, line, RESOLVED, via="subprocess", how=how, command=cmd[:120])
+        self.st["linked"] += 1
+        self.st[f"linked_{how.replace(' ', '_')}"] += 1
+
+    def miss(self, key, text):
+        self.st[key] += 1
+        if text and len(self.samples[key]) < 5 and text not in self.samples[key]:
+            self.samples[key].append(text[:80])
+
+    def resolve_path(self, file: str, text: str, pool) -> str | None:
+        """Project file a script path names: `./` / `../` paths relative to the calling file's directory
+        (`path.join(__dirname, '../bin/cli.js')`) or the root, other paths root-relative, else a unique suffix match
+        among `pool` (files with a node)."""
+        import posixpath
+        t = text.replace("\\", "/")
+        cands = []
+        if t.startswith(("./", "../")):
+            cands.append(posixpath.normpath(posixpath.join(posixpath.dirname(file), t)))
+        cands.append(posixpath.normpath(t.lstrip("/")))
+        for c in cands:
+            if not c.startswith("..") and (self.root / c).is_file():
+                return c
+        if t.startswith("../"):
+            return None                         # outside the caller's tree: not guessed by suffix
+        return self.by_suffix(t, pool)
+
+    def by_suffix(self, tail: str, pool) -> str | None:
+        tail = tail.replace("\\", "/").lstrip("./")
+        while tail.startswith("../"):
+            tail = tail[3:]
+        if not tail:
+            return None
+        hits = [f for f in pool if f == tail or f.endswith("/" + tail)]
+        return hits[0] if len(hits) == 1 else None
+
+    # ---------------------------------------------------------------- Rust
+    def rust_bins(self) -> dict:
+        try:
+            from .plugins.rust.cargo import from_toml
+            pkgs = from_toml(self.root)
+        except Exception:
+            pkgs = []
+        bins, pkg_dirs = {}, []
+        for p in pkgs:
+            pkg_dirs.append((p.dir, p.name))
+            for t in p.targets:
+                if t.kind == "bin":
+                    bins.setdefault(t.name, t.src)
+        return bins, sorted(pkg_dirs, key=lambda x: -len(x[0]))
+
+    def rust(self, file, src):
+        if not hasattr(self, "_bins"):
+            self._bins = self.rust_bins()
+        bins, pkg_dirs = self._bins
+        for m in RUST_RX.finditer(src):
+            name = m.group(1) or m.group(2)
+            if name is None:      # env!("CARGO_PKG_NAME"): the package this test belongs to
+                name = next((n for d, n in pkg_dirs if not d or file.startswith(d.rstrip("/") + "/")), None)
+            line = src.count("\n", 0, m.start()) + 1
+            path = bins.get(name or "") or bins.get((name or "").replace("-", "_"))
+            dst = self.mains.get(path) if path else None
+            if dst is None:
+                self.miss("unresolved", f"bin {name}")
+                continue
+            self.add(file, line, dst, "cargo bin", f"cargo bin {name}")
+
+    # ---------------------------------------------------------------- Node
+    def js_bins(self) -> dict:
+        out = {}
+        for pj in [self.root / "package.json"] + sorted(self.root.glob("packages/*/package.json")):
+            try:
+                d = json.loads(pj.read_text())
+            except Exception:
+                continue
+            rel = "" if pj.parent == self.root else pj.parent.relative_to(self.root).as_posix() + "/"
+            b = d.get("bin")
+            if isinstance(b, str) and d.get("name"):
+                out[d["name"].split("/")[-1]] = rel + b.lstrip("./")
+            elif isinstance(b, dict):
+                for k, v in b.items():
+                    out[k] = rel + str(v).lstrip("./")
+        return out
+
+    def js_script(self, lits, file="") -> str | None:
+        """Project script among the call's literals: the first one with a JS extension, with the plain path segments
+        before it (`path.join(__dirname, '..', 'bin', 'cli.js')`)."""
+        js_files = [f for f in self.modules if f.endswith(JS_EXT)]
+        for i, s in enumerate(lits):
+            if s.endswith(JS_EXT) and not s.startswith("-"):
+                segs = [x for x in lits[max(0, i - 3):i] if re.fullmatch(r"[\w.\-/]+", x) and not x.startswith("-")]
+                for k in range(len(segs), -1, -1):
+                    got = self.resolve_path(file, "/".join(segs[len(segs) - k:] + [s]), js_files)
+                    if got:
+                        return got
+                return None
+        return None
+
+    def js(self, file, src):
+        if not hasattr(self, "_jsbins"):
+            self._jsbins = self.js_bins()
+        for m in JS_RX.finditer(src):
+            fn = m.group(1)
+            line = src.count("\n", 0, m.start()) + 1
+            args = _args_text(src, m.end() - 1)
+            lits = _lits(args)
+            if fn in ("exec", "execSync", "execaCommand", "execaCommandSync"):
+                if not lits:
+                    continue
+                try:
+                    lits = shlex.split(lits[0]) + lits[1:]
+                except ValueError:
+                    lits = lits[0].split() + lits[1:]
+            prog = "process.execPath" if args.lstrip().startswith("process.execPath") else (lits[0] if lits else "")
+            rest = lits if fn in ("fork", "execaNode") else lits[1:] if prog != "process.execPath" else lits
+            rest = rest + self.assigned_lits(file, src, m.start(), args)
+            base = re.split(r"[/\\]", prog)[-1]
+            target = None
+            if fn in ("fork", "execaNode") or prog == "process.execPath" or base in JS_RUNTIMES or base == "npx":
+                if base == "npx" and rest and rest[0] in self._jsbins:
+                    target = self._jsbins[rest[0]]
+                else:
+                    target = self.js_script([x for x in rest if x not in ("run", "--")], file)
+            elif base in self._jsbins:
+                target = self._jsbins[base]
+            elif prog.endswith(JS_EXT):
+                target = self.js_script(lits, file)
+            else:
+                continue                      # git, docker, ...: not a project program
+            dst = self.modules.get(target) if target else None
+            if dst is None:
+                self.miss("script_without_node" if target else "unresolved",
+                          target or f"{fn}({' '.join(lits[:3])})")
+                continue
+            self.add(file, line, dst, "node script" if base not in self._jsbins else "package bin",
+                     " ".join(lits[:6]))
+
+    # ---------------------------------------------------------------- PHP
+    def php(self, file, src):
+        for m in PHP_RX.finditer(src):
+            line = src.count("\n", 0, m.start()) + 1
+            lits = _lits(_args_text(src, m.end() - 1))
+            if not lits:
+                continue
+            if len(lits) == 1 and " " in lits[0]:
+                try:
+                    lits = shlex.split(lits[0])
+                except ValueError:
+                    lits = lits[0].split()
+            words = [re.split(r"[/\\]", x)[-1] for x in lits]
+            if "artisan" not in words:
+                continue
+            i = words.index("artisan")
+            name = next((w for w in lits[i + 1:] if not w.startswith("-")), None)
+            dst = self.commands.get(name or "")
+            if dst is None:
+                self.miss("unresolved", f"artisan {name}")
+                continue
+            self.add(file, line, dst, "artisan", " ".join(lits[:6]))
+
+    # ---------------------------------------------------------------- Dart
+    def dart(self, file, src):
+        dart_files = list(self.mains)
+        for m in DART_RX.finditer(src):
+            line = src.count("\n", 0, m.start()) + 1
+            args = _args_text(src, m.end() - 1)
+            lits = _lits(args)
+            if not (args.lstrip().startswith("Platform.resolvedExecutable") or (lits and lits[0] in ("dart", "flutter"))):
+                continue
+            script = next((x for x in lits + self.assigned_lits(file, src, m.start(), args) if x.endswith(".dart")), None)
+            path = self.resolve_path(file, script, dart_files) if script else None
+            dst = self.mains.get(path) if path else None
+            if dst is None:
+                self.miss("unresolved", " ".join(lits[:4]))
+                continue
+            self.add(file, line, dst, "dart script", " ".join(lits[:6]))
+
+    def run(self) -> dict:
+        files = set(self.modules) | set(self.by_file)
+        for file in sorted(files):
+            if not file.endswith(SCAN_EXT):          # files of graph nodes: the walks already skipped presets' dirs
+                continue
+            try:
+                src = (self.root / file).read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            if file.endswith(".rs"):
+                if "cargo_bin" in src or "CARGO_BIN_EXE_" in src:
+                    self.rust(file, src)
+            elif file.endswith(".php"):
+                if "artisan" in src:
+                    self.php(file, src)
+            elif file.endswith(".dart"):
+                if "Process" in src:
+                    self.dart(file, src)
+            elif ("child_process" in src or "execa" in src) and JS_RX.search(src):
+                self.js(file, src)
+        out = {k: v for k, v in self.st.items() if v}
+        if self.samples:
+            out["samples"] = dict(self.samples)
+        return out
+
+
+def apply(project, builder) -> dict:
+    """Add the subprocess edges; returns stats (empty when nothing was found)."""
+    return _Scan(project, builder).run()

codegraph/protocols/__init__.py

@@ -0,0 +1,299 @@
+"""Protocol links (#31, epic #29): one model for every way two pieces of code talk through a named endpoint.
+
+    sender code  -SENDS_TO->  endpoint:<protocol>:<name>  -RECEIVED_BY->  handler
+                              endpoint (send side)  -MATCHES_ENDPOINT->  endpoint (receive side)   names differ but match
+
+* Registry: one `Protocol` per protocol (name, transport, default ports, URL schemes, name normaliser, matcher,
+  fan-out, whether receivers are entry points and whether guards are recorded). Plugins register theirs with
+  `register(Protocol(...))`; the shared matchers live in protocols/matchers.py (path, MQTT / NATS / AMQP topics, glob,
+  exact, `{param}` templates).
+* Builder helpers: `protocol_send(builder, protocol, name, src, ...)` / `protocol_receive(builder, protocol, name,
+  handler, ...)`: a plugin reports facts, the name is normalised here and matching happens once, at the end of
+  `cg index` (`apply`) and over the combined graph of `cg link` (`link_db`). Identical ids need no edge: the combined
+  DB keeps one node per id.
+* Existing node kinds keep their ids and are adapted by the query (protocols/view.py): `http` / `route` (protocol
+  http; `route:WS ...` ws, `route:GRAPHQL ...` graphql), `channel_sub` / `channel` (pusher), Nest `message:`
+  (nest-rpc / nest-event / nest-ws / grpc), `job:` (bull, laravel-queue, celery), `event:` (laravel-event,
+  nest-event-emitter, django-signal) and the bridge endpoints of codegraph/bridges.py (capacitor, react-native,
+  flutter, electron-ipc, tauri, ...).
+* `cg protocols` / MCP `protocol_links`: summary per protocol and one block per endpoint with senders, receivers,
+  guards, matches and checks (no_receiver, no_sender, ambiguous, schema_mismatch, unguarded, test_sender_only).
+"""
+from __future__ import annotations
+
+import fnmatch
+import re
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Callable
+
+from . import matchers as M
+
+
+@dataclass
+class Protocol:
+    name: str
+    transport: str                       # tcp | udp | quic | local (in-process / same machine) | ipc
+    description: str
+    matcher: Callable[[str, str], dict | None] = M.exact
+    normalise: Callable[[str], str] | None = None
+    ports: tuple = ()
+    schemes: tuple = ()
+    fanout: bool = False                 # pub/sub: every matching receiver gets the message (never ambiguous)
+    entry: bool = True                   # receivers can be reached from outside the process (message_handler entry)
+    guards: bool = False                 # receivers record guards: `unguarded` is checked
+    source: str = "endpoint"             # endpoint (protocol_send / protocol_receive) | the adapter of an existing kind
+    kinds: tuple = ("endpoint",)         # node kinds holding its endpoints
+    aliases: tuple = field(default_factory=tuple)
+    entry_kind: str = "message_handler"  # entry kind of a receiving endpoint (llm_tool: called by a model / MCP client)
+    framework_senders: tuple = ()        # name globs the framework itself sends (Django's post_save, ...): never no_sender
+    directional: bool = False            # both processes send and receive on one name (Socket.IO): a sender's
+                                         # `process` (server / client) reaches only receivers of the other one (#69)
+
+
+REGISTRY: dict[str, Protocol] = {}
+
+
+def register(p: Protocol) -> Protocol:
+    REGISTRY[p.name] = p
+    return p
+
+
+def get(name: str) -> Protocol | None:
+    return REGISTRY.get(name)
+
+
+_TEMPLATE = re.compile(r"\$\{\s*([A-Za-z_$][\w$.]*)?[^{}]*\}|(?<![\w}])\{\{\s*(\w*)[^{}]*\}\}|(?<=[/.:])\:([A-Za-z_]\w*)")
+
+
+def normalise(name: str) -> str:
+    """Default name normaliser: template parts become `{param}` (`${id}` / `{{id}}` -> `{id}`, `/:id` -> `/{id}`);
+    surrounding blanks dropped."""
+    def rep(m):
+        n = m.group(1) or m.group(2) or m.group(3) or ""
+        return "{" + n.rsplit(".", 1)[-1] + "}"
+    return _TEMPLATE.sub(rep, (name or "").strip())
+
+
+def norm_name(protocol: str, name: str) -> str:
+    p = REGISTRY.get(protocol)
+    return (p.normalise if p and p.normalise else normalise)(name)
+
+
+def is_pattern(name: str) -> bool:
+    return bool(re.search(r"\{[^{}]*\}|[*?#>+]", name or ""))
+
+
+# ------------------------------------------------------------------ builder helpers
+def _endpoint(builder, protocol: str, name: str, node_attrs: dict | None) -> str:
+    p = REGISTRY.get(protocol)
+    key = f"{protocol}:{name}"
+    nid = builder.add_node("endpoint", key, name, fqn=name,
+                           attrs={"protocol": protocol, "transport": p.transport if p else "tcp"})
+    n = builder.nodes[nid]
+    if is_pattern(name):
+        n.attrs["pattern"] = name
+    for k, v in (node_attrs or {}).items():
+        if v not in (None, [], ""):
+            n.attrs[k] = v
+    return nid
+
+
+def protocol_send(builder, protocol: str, name: str, src: str, file: str | None, line: int | None,
+                  confidence: str, test: bool = False, role: str = "send", node_attrs: dict | None = None,
+                  **attrs) -> str:
+    """Code `src` sends to `endpoint:<protocol>:<name>` (SENDS_TO; from test code: TEST_CALLS with orig SENDS_TO).
+    role: send | publish | emit | request | invoke | enqueue; attrs: library, payload, schema, room, ..."""
+    nid = _endpoint(builder, protocol, norm_name(protocol, name), node_attrs)
+    n = builder.nodes[nid]
+    if test:
+        n.attrs.setdefault("test_only", True)
+    else:
+        n.attrs["test_only"] = False
+    a = {k: v for k, v in attrs.items() if v not in (None, [], "")}
+    if test:
+        builder.add_edge(src, nid, "TEST_CALLS", file=file, line=line, confidence=confidence, orig="SENDS_TO", role=role, **a)
+    else:
+        builder.add_edge(src, nid, "SENDS_TO", file=file, line=line, confidence=confidence, role=role, **a)
+    return nid
+
+
+def protocol_receive(builder, protocol: str, name: str, handler: str, file: str | None, line: int | None,
+                     confidence: str, guards: list | None = None, node_attrs: dict | None = None, **attrs) -> str:
+    """`endpoint:<protocol>:<name>` is handled by `handler` (RECEIVED_BY). guards: names of the guards / middleware /
+    signature checks protecting the receiver ([] = known to have none); the endpoint becomes a message_handler entry
+    point when the protocol's senders can sit outside the process."""
+    nid = _endpoint(builder, protocol, norm_name(protocol, name), node_attrs)
+    n = builder.nodes[nid]
+    p = REGISTRY.get(protocol)
+    if guards is not None:
+        n.attrs["guards"] = sorted(set(n.attrs.get("guards") or []) | set(guards))
+    if (p is None or p.entry) and not n.entry_kind:
+        n.entry_kind = p.entry_kind if p else "message_handler"
+    builder.add_edge(nid, handler, "RECEIVED_BY", file=file, line=line, confidence=confidence,
+                     **{k: v for k, v in attrs.items() if v not in (None, [], "")})
+    return nid
+
+
+# ------------------------------------------------------------------ matching (cg index and cg link)
+def compatible(p, sprocs, rprocs) -> bool:
+    """A sender process set can reach a receiver process set: always, unless the protocol is directional and both
+    sides name their processes (server -> client, client -> server)."""
+    if p is None or not p.directional or not sprocs or not rprocs:
+        return True
+    return any(a != b for a in sprocs for b in rprocs)
+
+
+def match_rows(eps: dict[str, tuple[str, str]], senders: set, receivers: set, existing: set = frozenset(),
+               externals: list | tuple = (), procs: dict | None = None) -> tuple[list, dict]:
+    """eps: endpoint id -> (protocol, name) of the generic endpoints in a graph; senders / receivers: ids with a
+    SENDS_TO (or test send) / RECEIVED_BY. Returns ([(src, dst, confidence, attrs)], stats per protocol) for
+    MATCHES_ENDPOINT send-side -> receive-side endpoints whose names differ but match by the protocol's matcher.
+    Fan-out protocols link every matching receiver; the others the most specific ones (ties: ambiguous, heuristic)."""
+    by_proto: dict[str, dict] = {}
+    for nid, (proto, name) in eps.items():
+        d = by_proto.setdefault(proto, {"send": [], "recv": []})
+        if nid in senders:
+            d["send"].append((nid, name))
+        if nid in receivers:
+            d["recv"].append((nid, name))
+    rows, stats = [], {}
+    for proto, d in sorted(by_proto.items()):
+        p = REGISTRY.get(proto)
+        if p is None or p.source != "endpoint":
+            continue
+        s = stats.setdefault(proto, {"endpoints": 0, "send": 0, "receive": 0, "matched": 0, "match_edges": 0,
+                                     "no_receiver": 0, "no_sender": 0, "ambiguous": 0, "external": 0})
+        ids = {nid for nid, (pp, _) in eps.items() if pp == proto}
+        s["endpoints"] = len(ids)
+        s["send"], s["receive"] = len(d["send"]), len(d["recv"])
+        got_recv = set()
+        pr = procs or {}
+
+        def ok(a, b):
+            return compatible(p, pr.get(("send", a)), pr.get(("recv", b)))
+        for sid, sname in d["send"]:
+            hits = []
+            for rid, rname in d["recv"]:
+                if rid == sid or p.matcher is M.exact or not ok(sid, rid):
+                    continue
+                info = p.matcher(sname, rname)
+                if info is not None:
+                    hits.append((rid, rname, info))
+            direct = sid in receivers and ok(sid, sid)
+            if direct:
+                got_recv.add(sid)
+            if hits and not p.fanout:
+                if direct:
+                    hits = []              # the exact name is received: the most specific receiver
+                else:
+                    top = max(M.rank(h[2]) for h in hits)
+                    hits = [h for h in hits if M.rank(h[2]) == top]
+            tied = len(hits) > 1 and not p.fanout
+            for rid, rname, info in hits:
+                got_recv.add(rid)
+                if (sid, rid) in existing:
+                    continue
+                a = {"sender_name": sname, "pattern": rname, "segments": info}
+                if tied:
+                    a["ambiguous"] = len(hits)
+                rows.append((sid, rid, M.confidence(info, tied), a))
+                s["match_edges"] += 1
+            if hits or direct:
+                s["matched"] += 1
+            elif externals and external_match(externals, proto, sname):
+                s["external"] += 1        # .cg.yaml protocols.external: received outside these repos (#69)
+            else:
+                s["no_receiver"] += 1 if d["recv"] else 0
+            if tied:
+                s["ambiguous"] += 1
+        unsent = [rname for rid, rname in d["recv"] if (rid not in senders or not ok(rid, rid)) and rid not in got_recv] \
+            if d["send"] else []
+        ext = [r for r in unsent if externals and external_match(externals, proto, r)]
+        s["no_sender"] = len(unsent) - len(ext)
+        s["external"] += len(ext)
+    return rows, stats
+
+
+def apply(builder, externals: list | tuple = ()) -> dict:
+    """End of `cg index`: MATCHES_ENDPOINT between the generic endpoints of one graph; stats per protocol (only
+    when the graph has endpoints of registered non-bridge protocols)."""
+    eps = {nid: (n.attrs.get("protocol"), n.name) for nid, n in builder.nodes.items()
+           if n.kind == "endpoint" and (REGISTRY.get(n.attrs.get("protocol")) or Protocol("", "", "", source="?")).source == "endpoint"}
+    if not eps:
+        return {}
+    senders, receivers, loc, procs = set(), set(), {}, defaultdict(set)
+    for e in builder.edges.values():
+        if e.kind == "SENDS_TO" and e.dst in eps:
+            senders.add(e.dst)
+            if e.attrs.get("process"):
+                procs[("send", e.dst)].add(e.attrs["process"])
+        elif e.kind == "TEST_CALLS" and e.dst in eps and e.attrs.get("orig") == "SENDS_TO":
+            senders.add(e.dst)
+        elif e.kind == "RECEIVED_BY" and e.src in eps:
+            receivers.add(e.src)
+            if e.attrs.get("process"):
+                procs[("recv", e.src)].add(e.attrs["process"])
+            loc.setdefault(e.src, (e.file, e.line))      # the match is evidenced where the receiver registers
+    for nid in eps:
+        a = builder.nodes[nid].attrs
+        a["side"] = "both" if nid in senders and nid in receivers else "send" if nid in senders else "receive" if nid in receivers else "none"
+    rows, st = match_rows(eps, senders, receivers, externals=externals, procs=procs)
+    for s, d, conf, a in rows:
+        f, ln = loc.get(d, (None, None))
+        builder.add_edge(s, d, "MATCHES_ENDPOINT", file=f, line=ln, confidence=conf, **a)
+    return st
+
+
+def link_db(db) -> dict:
+    """`cg link`: MATCHES_ENDPOINT over the combined graph (senders in one repo, receivers in the other)."""
+    import json
+    from ..core.model import CONFIDENCE_RANK
+    names = [p.name for p in REGISTRY.values() if p.source == "endpoint"]
+    if not names:
+        return {}
+    q = ",".join("?" * len(names))
+    eps = {r[0]: (r[1], r[2]) for r in db.execute(
+        f"SELECT id, json_extract(attrs,'$.protocol'), name FROM nodes WHERE kind='endpoint' AND json_extract(attrs,'$.protocol') IN ({q})", names)}
+    if not eps:
+        return {}
+    senders = {r[0] for r in db.execute("SELECT DISTINCT dst FROM edges WHERE kind='SENDS_TO' OR (kind='TEST_CALLS' AND "
+                                        "json_extract(attrs,'$.orig')='SENDS_TO')") if r[0] in eps}
+    receivers = {r[0] for r in db.execute("SELECT DISTINCT src FROM edges WHERE kind='RECEIVED_BY'") if r[0] in eps}
+    existing = {(r[0], r[1]) for r in db.execute("SELECT src, dst FROM edges WHERE kind='MATCHES_ENDPOINT'")}
+    externals = []
+    for alias in ("b", "f"):          # protocols.external of both repos (.cg.yaml, in their index stats)
+        try:
+            r = db.execute(f"SELECT value FROM {alias}.meta WHERE key='stats'").fetchone()
+        except Exception:  # noqa: BLE001  (not attached: a graph linked on its own)
+            r = None
+        if r:
+            externals += ((json.loads(r[0]).get("config") or {}).get("protocols") or {}).get("external") or []
+    procs = defaultdict(set)
+    for kind, col, side in (("SENDS_TO", "dst", "send"), ("RECEIVED_BY", "src", "recv")):
+        for nid, pr in db.execute(f"SELECT {col}, json_extract(attrs,'$.process') FROM edges WHERE kind=? AND "
+                                  "json_extract(attrs,'$.process') IS NOT NULL", (kind,)):
+            if nid in eps:
+                procs[(side, nid)].add(pr)
+    rows, st = match_rows(eps, senders, receivers, existing, externals=list(dict.fromkeys(externals)), procs=procs)
+    loc = {}
+    for r in db.execute("SELECT src, file, line FROM edges WHERE kind='RECEIVED_BY' ORDER BY rowid"):
+        loc.setdefault(r[0], (r[1], r[2]))
+    db.executemany("INSERT INTO edges(src,dst,kind,file,line,confidence,conf_rank,attrs,gate) VALUES (?,?,?,?,?,?,?,?,?)",
+                   [(s, d, "MATCHES_ENDPOINT", *loc.get(d, (None, None)), c, CONFIDENCE_RANK[c], json.dumps(a), None)
+                    for s, d, c, a in rows])
+    db.commit()
+    return st
+
+
+def external_match(patterns: list[str], protocol: str, name: str) -> str | None:
+    """`.cg.yaml` protocols.external entries (`kafka:audit.*`, `http:GET /v1/*`, `socketio:*`): the first one
+    matching `<protocol>:<name>` (glob)."""
+    for p in patterns or []:
+        pp, _, nn = p.partition(":")
+        if fnmatch.fnmatchcase(protocol, pp) and fnmatch.fnmatchcase(name, nn or "*"):
+            return p
+    return None
+
+
+from . import builtin  # noqa: E402,F401  (registers the built-in protocols)