sourcecode 4.2.0__py3-none-any.whl → 4.3.0__py3-none-any.whl

sourcecode/client_calls.py

@@ -0,0 +1,305 @@
+"""client_calls.py — the other end of the route, when it lives in the same repository.
+
+Roadmap M10.5 item 4. A monolith's endpoint census answers *what is exposed*; it cannot
+answer *what anybody calls*, and on a 2 635-endpoint surface **deleting dead API is the
+cheapest possible reduction of exposure**. In a monorepo the answer is right there: the
+TypeScript or JavaScript client that calls the routes is checked in next to the server
+that serves them, and nobody joins the two because doing it needs an effective-route
+model on both sides.
+
+What this module extracts is deliberately narrow, and its narrowness is published rather
+than implied:
+
+* **Only a call whose verb and path are written at the call site.** `httpClient.get(...)`,
+  `axios.post(...)`, `fetch(url, {method: "PUT"})` — the shapes where the request is
+  legible without evaluating the program. A URL assembled at runtime from a variable is
+  **not** a call this module can see, and a route it never saw must never be reported as
+  uncalled: the join publishes `unmatched_client_calls` and the census states its
+  direction (`under_reports` for the client side).
+* **A template segment is a template segment.** `${bank-id}` on the client and `{bankId}`
+  on the server are the same position with different names, so the join key replaces every
+  variable segment with a placeholder — and both spellings travel with the row, because
+  that normalisation is exactly what `request_identity` refuses to do inside one tree
+  (there, `/{id:.*}` and `/{id:[^0-9].*}` are genuinely different URLs; here, one side is
+  not even the same language).
+* **A base path is a prefix nobody wrote.** `${this.configuration.basePath}/v1/x` is a
+  call to `/v1/x` plus whatever the deployment configures. The prefix is dropped and the
+  suffix is matched; a call that resolves to no leading `/` is reported unresolved rather
+  than guessed.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Optional
+
+SCHEMA_VERSION = "client-usage-v1"
+
+#: Files this module reads. A client written in something else is not covered, and the
+#: payload says so rather than reporting its routes as uncalled.
+CLIENT_SUFFIXES: "tuple[str, ...]" = (".ts", ".tsx", ".js", ".jsx", ".mjs")
+
+_SKIP_DIRS = frozenset({
+    "node_modules", "dist", "build", "out", "target", ".git", "coverage", ".angular",
+})
+
+#: `<receiver>.<verb>(<quote><url>` — the Angular/axios/jQuery shape, verb at the call.
+_VERB_CALL = re.compile(
+    r"""(?P<receiver>[\w$.]*?)\.?(?P<verb>get|post|put|patch|delete|head|options)\s*"""
+    r"""(?:<[^()]*?>\s*)?\(\s*(?P<quote>['"`])(?P<url>[^'"`]*)(?P=quote)""",
+    re.IGNORECASE,
+)
+
+#: The same shape with a non-literal first argument: `this.http.get<any>(url)`. It is a
+#: call this module cannot resolve, and it has to be *seen* to be reported: a call that
+#: matched nothing at all would silently shrink the census and could make a live route
+#: look dead — the one failure this join must not have.
+_VERB_CALL_DYNAMIC = re.compile(
+    r"""(?P<receiver>[\w$.]*?)\.(?P<verb>get|post|put|patch|delete|head|options)\s*"""
+    r"""(?:<[^()]*?>\s*)?\(\s*(?P<arg>[A-Za-z_$][\w$.\[\]()]*)""",
+    re.IGNORECASE,
+)
+
+#: `fetch("<url>", { method: "<verb>" })` — verb in the options object, GET by default.
+_FETCH_CALL = re.compile(
+    r"""fetch\s*\(\s*(?P<quote>['"`])(?P<url>[^'"`]*)(?P=quote)"""
+    r"""(?P<rest>\s*,\s*\{[^}]{0,200}\})?""",
+    re.IGNORECASE | re.DOTALL,
+)
+_METHOD_IN_OPTIONS = re.compile(r"""method\s*:\s*['"`](?P<verb>\w+)['"`]""", re.IGNORECASE)
+
+#: A template expression: `${...}`. Whatever it holds, it is one path position.
+_TEMPLATE_EXPR = re.compile(r"\$\{[^}]*\}")
+
+#: Receivers that make a verb call an HTTP call rather than a map lookup. Structural, not
+#: proprietary: the name is evidence, and the evidence required is that it looks like a
+#: client. `get(...)` on its own is a Map, a cache or a DOM query far more often than it
+#: is a request, and admitting it would fill the census with calls nobody makes.
+_HTTP_RECEIVER = re.compile(
+    r"(http|api|client|axios|request|rest|service|ajax|\$http)", re.IGNORECASE
+)
+
+
+@dataclass(frozen=True)
+class ClientCall:
+    """One HTTP call written in a client file, as written."""
+
+    method: str
+    path: str            # as written, template expressions collapsed to {}
+    source_file: str
+    line: int
+    receiver: str
+
+    @property
+    def key(self) -> str:
+        """The join key: METHOD plus the path with variable segments neutralised."""
+        return f"{self.method} {normalize_path(self.path)}"
+
+    def to_dict(self) -> dict:
+        return {
+            "method": self.method,
+            "path": self.path,
+            "join_key": self.key,
+            "source_file": self.source_file,
+            "line": self.line,
+            "receiver": self.receiver,
+        }
+
+
+def normalize_path(path: str) -> str:
+    """Path with every variable segment replaced by `{}` — the cross-language key.
+
+    Server: `/v1/pis/banks/{bank-id}/accounts`. Client: `/v1/pis/banks/${bankId}/accounts`.
+    Same request, two languages, two naming conventions. Names are dropped **only** in the
+    join key; both original spellings stay on the row that reports the match.
+    """
+    if not path:
+        return ""
+    cleaned = _TEMPLATE_EXPR.sub("{}", path.strip())
+    cleaned = cleaned.split("?", 1)[0].split("#", 1)[0]
+    segments = []
+    for segment in cleaned.split("/"):
+        if segment.startswith("{") and segment.endswith("}"):
+            segments.append("{}")
+        elif segment.startswith(":") and len(segment) > 1:   # /users/:id (express style)
+            segments.append("{}")
+        else:
+            segments.append(segment)
+    normalized = "/".join(segments)
+    while "//" in normalized:
+        normalized = normalized.replace("//", "/")
+    if len(normalized) > 1 and normalized.endswith("/"):
+        normalized = normalized[:-1]
+    return normalized
+
+
+def _iter_client_files(root: Path, extra: "Optional[Iterable[Path]]" = None) -> "list[Path]":
+    roots = [Path(root)] if extra is None else [Path(p) for p in extra]
+    found: list[Path] = []
+    for base in roots:
+        if not base.is_dir():
+            continue
+        for path in base.rglob("*"):
+            if path.suffix.lower() not in CLIENT_SUFFIXES:
+                continue
+            if any(part in _SKIP_DIRS for part in path.parts):
+                continue
+            if path.name.endswith((".spec.ts", ".test.ts", ".spec.js", ".test.js")):
+                continue
+            found.append(path)
+    return sorted(found)
+
+
+def _path_from_url(url: str) -> Optional[str]:
+    """The request path of a URL as written, or None when it is not a path at all."""
+    collapsed = _TEMPLATE_EXPR.sub("{}", url.strip())
+    if collapsed.startswith(("http://", "https://")):
+        rest = collapsed.split("://", 1)[1]
+        collapsed = "/" + rest.split("/", 1)[1] if "/" in rest else "/"
+    elif collapsed.startswith("{}"):
+        # `${basePath}/v1/x` — a configured prefix plus a written suffix.
+        collapsed = collapsed[2:]
+    if not collapsed.startswith("/"):
+        return None
+    return collapsed
+
+
+def extract_client_calls(
+    root: Path, *, client_dirs: "Optional[Iterable[Path]]" = None
+) -> "tuple[list[ClientCall], list[dict]]":
+    """(calls, unresolved) written in the client files under `root`.
+
+    `unresolved` carries the call sites this module found and could not turn into a
+    path — a URL built from a variable, an interpolation with no literal prefix. They
+    are published, never dropped: they are precisely the calls that would make a live
+    route look dead.
+    """
+    calls: list[ClientCall] = []
+    unresolved: list[dict] = []
+    base = Path(root)
+    for file_path in _iter_client_files(base, client_dirs):
+        try:
+            text = file_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        try:
+            relative = str(file_path.relative_to(base))
+        except ValueError:
+            relative = str(file_path)
+        for match in _VERB_CALL.finditer(text):
+            receiver = match.group("receiver") or ""
+            if not _HTTP_RECEIVER.search(receiver):
+                continue
+            line = text.count("\n", 0, match.start()) + 1
+            path = _path_from_url(match.group("url"))
+            if path is None:
+                unresolved.append({
+                    "source_file": relative, "line": line,
+                    "written": match.group("url")[:120],
+                    "reason": "the URL has no literal path at the call site",
+                })
+                continue
+            calls.append(ClientCall(
+                method=match.group("verb").upper(), path=path,
+                source_file=relative, line=line, receiver=receiver.strip("."),
+            ))
+        for match in _VERB_CALL_DYNAMIC.finditer(text):
+            receiver = match.group("receiver") or ""
+            if not _HTTP_RECEIVER.search(receiver):
+                continue
+            line = text.count("\n", 0, match.start()) + 1
+            unresolved.append({
+                "source_file": relative, "line": line,
+                "written": match.group(0)[:120],
+                "reason": "the URL is an expression, not a literal at the call site",
+            })
+        for match in _FETCH_CALL.finditer(text):
+            line = text.count("\n", 0, match.start()) + 1
+            path = _path_from_url(match.group("url"))
+            verb_match = _METHOD_IN_OPTIONS.search(match.group("rest") or "")
+            verb = (verb_match.group("verb") if verb_match else "GET").upper()
+            if path is None:
+                unresolved.append({
+                    "source_file": relative, "line": line,
+                    "written": match.group("url")[:120],
+                    "reason": "the URL has no literal path at the call site",
+                })
+                continue
+            calls.append(ClientCall(
+                method=verb, path=path, source_file=relative, line=line, receiver="fetch",
+            ))
+    # One call site, one row; the same route called twice is two witnesses of one usage.
+    calls.sort(key=lambda c: (c.path, c.method, c.source_file, c.line))
+    return calls, unresolved
+
+
+def build_client_usage(
+    root: Path,
+    endpoints: "Iterable[dict]",
+    *,
+    client_dirs: "Optional[Iterable[Path]]" = None,
+) -> dict:
+    """Join the client calls found under `root` against the server's own routes."""
+    from sourcecode import non_coverage
+
+    calls, unresolved = extract_client_calls(root, client_dirs=client_dirs)
+    by_key: "dict[str, list[ClientCall]]" = {}
+    for call in calls:
+        by_key.setdefault(call.key, []).append(call)
+
+    matched_keys: set[str] = set()
+    routes: list[dict] = []
+    for endpoint in endpoints:
+        method = str(endpoint.get("method") or "").upper()
+        path = str(endpoint.get("path") or endpoint.get("effective_path") or "")
+        key = f"{method} {normalize_path(path)}"
+        witnesses = by_key.get(key, [])
+        if witnesses:
+            matched_keys.add(key)
+        routes.append({
+            "method": method,
+            "path": path,
+            "join_key": key,
+            "called_by_client": bool(witnesses),
+            "call_sites": [w.to_dict() for w in witnesses],
+        })
+
+    called = [r for r in routes if r["called_by_client"]]
+    uncalled = [r for r in routes if not r["called_by_client"]]
+    unmatched = [
+        {"join_key": key, "call_sites": [c.to_dict() for c in group]}
+        for key, group in sorted(by_key.items()) if key not in matched_keys
+    ]
+    scanned = len(_iter_client_files(Path(root), client_dirs))
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "client_files_scanned": scanned,
+        "calls_found": len(calls),
+        "calls_unresolved": len(unresolved),
+        "unresolved_call_sites": unresolved[:50],
+        "summary": {
+            "routes": len(routes),
+            "called_by_a_client_in_this_repository": len(called),
+            "not_called_by_any_client_in_this_repository": len(uncalled),
+            "client_calls_matching_no_route": len(unmatched),
+        },
+        "routes": routes,
+        "unmatched_client_calls": unmatched,
+        "direction": "under_reports",
+        "reading": (
+            "A route with no call site here is a **candidate** for deletion, never a "
+            "proven-dead one: this reads only the client code in this repository, only "
+            "the call shapes whose verb and path are written at the call site, and no "
+            "other consumer of the API exists in what was read. A client call matching "
+            "no route is the more decisive direction — it is a request this repository's "
+            "own front end makes and this repository's server does not serve."
+            if scanned else
+            "No client files were found, so nothing was joined: every route below is "
+            "`called_by_client: false` because there was no client to call it. That is "
+            "an absence of evidence, published as one."
+        ),
+        "non_coverage": non_coverage.block("client_usage"),
+    }

sourcecode/context_graph.py

@@ -703,6 +703,17 @@ class ContextGraph:
             self._body_index = _BodyIndex(self._cir.body_facts)
         return self._body_index
 
+    def body_owners(self) -> tuple[str, ...]:
+        """Every owner FQN the body-fact layer carries an atom for, ordered.
+
+        The population of *bodies*, which is not the population of any one symbol
+        kind: a handler method is a `Symbol(kind="endpoint")`, not `kind="method"`,
+        so a consumer that enumerates method and constructor nodes to walk bodies
+        silently skips every controller body in the repository. Bodies are what the
+        body-fact layer is keyed by, so this is the only honest way to enumerate them.
+        """
+        return tuple(sorted(self._body().by_owner))
+
     def invocations_in(self, owner_fqn: str) -> tuple[MethodInvocation, ...]:
         """Ordered method-call atoms inside a method/constructor body. Empty tuple
         when the owner has none (never None)."""

sourcecode/data_exposure.py

@@ -0,0 +1,353 @@
+"""data_exposure.py — one declared label, and every route that can carry it.
+
+Roadmap M10.5 item 3. The question a public-sector or health system asks first is
+not *"is this endpoint authenticated?"* but *"which routes expose personal data, and
+which of those does anyone reach without authenticating?"*. Nothing here detects
+sensitive data — that is a judgement about a domain, and a tool that guessed it from
+a field name would be guessing (see `data_labels`). What this module does is take a
+label somebody declared once and answer the second half **by measurement**, over
+authorities that already exist:
+
+* reach — `spring_impact.run_impact_chain`, the same traversal `impact-chain` and
+  `ask risk` walk (`caller_reach`), so the endpoint set behind a type cannot differ
+  between commands;
+* the route's own shape — `ContextGraph.structural_references_to_type`, the class
+  type-reference atoms, which say whether a handler *itself* names the type in its
+  signature;
+* access — `security_posture.endpoint_security_surface` and, with `--profile`,
+  `posture.endpoint_access_under`: the same two authorities `risk` weighs.
+
+**The two evidence classes are published separately and never added together**,
+because they answer differently strong questions:
+
+``signature``  the handler declares the labelled type in its own parameters or
+               return type. The route carries it, as written.
+``call_reach`` the handler's call chain reaches the labelled type. It is a route
+               through which the data *can* travel — a supremum, not a proof: a
+               chain that touches `Customer` may map it to a DTO that drops every
+               labelled member, and this analyzer does not model that mapping.
+
+Both directions are stated (I-8) rather than averaged into one number nobody can
+read: `call_reach` **over-reports** exposure, and every evidence class here
+**under-reports** any flow that leaves through reflection, a serializer configured
+at runtime, an untyped `Map` payload or a native query, none of which name a type.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional
+
+from sourcecode.data_labels import DataLabel, LabelDeclaration, load_labels
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+SCHEMA_VERSION = "data-exposure-v1"
+
+#: Evidence classes, strongest first — the order rows are ranked in.
+SIGNATURE = "signature"
+CALL_REACH = "call_reach"
+_EVIDENCE_RANK = {SIGNATURE: 0, CALL_REACH: 1}
+
+_EVIDENCE_MEANING: dict[str, str] = {
+    SIGNATURE: (
+        "The handler names the labelled type in its own signature (parameter or "
+        "return type), so the route carries it as declared."
+    ),
+    CALL_REACH: (
+        "The handler's call chain reaches the labelled type. The route can carry it; "
+        "whether a mapping drops the labelled member on the way out is not modelled, "
+        "so this class over-reports."
+    ),
+}
+
+#: Class-scope type-reference contexts that put a type in a member's own signature.
+_SIGNATURE_CONTEXTS = frozenset({"param_type", "return_type"})
+
+
+@dataclass(frozen=True)
+class ExposedRoute:
+    """One endpoint, the labels it can carry, and what decides access to it."""
+
+    endpoint_id: str
+    method: str
+    path: str
+    controller_class: str
+    handler_symbol: str
+    labels: tuple[str, ...]
+    seeds: tuple[str, ...]
+    evidence: str
+    verdict: str
+    access: Optional[str] = None
+    access_decision: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        out = {
+            "endpoint_id": self.endpoint_id,
+            "method": self.method,
+            "path": self.path,
+            "controller_class": self.controller_class,
+            "handler_symbol": self.handler_symbol,
+            "labels": list(self.labels),
+            "seeds": list(self.seeds),
+            "evidence": self.evidence,
+            "evidence_meaning": _EVIDENCE_MEANING.get(self.evidence, ""),
+            "security_verdict": self.verdict,
+        }
+        if self.access is not None:
+            out["access_under_profile"] = self.access
+            out["access_decision"] = self.access_decision
+        return out
+
+
+def _endpoint_fields(endpoint: Any) -> dict:
+    """The five fields every endpoint shape in this codebase carries."""
+    get = (
+        endpoint.get if isinstance(endpoint, dict)
+        else lambda key, default=None: getattr(endpoint, key, default)
+    )
+    return {
+        "endpoint_id": str(get("endpoint_id", "") or get("id", "") or ""),
+        "method": str(get("method", "") or ""),
+        "path": str(get("path", "") or ""),
+        "controller_class": str(get("controller_class", "") or ""),
+        "handler_symbol": str(get("handler_symbol", "") or ""),
+    }
+
+
+def _simple(name: str) -> str:
+    return name.rsplit(".", 1)[-1].split("#", 1)[0]
+
+
+def build_data_exposure(
+    root: Path,
+    cir: "Optional[CanonicalRepositoryIR]" = None,
+    *,
+    model: Optional[Any] = None,
+    profiles: "Optional[set[str]]" = None,
+    declaration: Optional[LabelDeclaration] = None,
+    depth: int = 4,
+) -> dict:
+    """Every route that can carry a declared label, with what decides access to it."""
+    from sourcecode import non_coverage
+    from sourcecode.context_graph import ContextGraph
+
+    root = Path(root)
+    decl = declaration if declaration is not None else load_labels(root)
+
+    payload: dict = {
+        "schema_version": SCHEMA_VERSION,
+        "declaration": decl.to_dict(),
+        "profiles": sorted(profiles) if profiles else None,
+    }
+
+    if not decl.labels:
+        # No declaration is not "nothing is exposed" — it is a question nobody asked
+        # yet, and the counts stay null rather than reading as a clean bill (I-3/R9).
+        payload.update(
+            {
+                "answered": False,
+                "statement": (
+                    "No data labels are declared, so this run measured nothing. A "
+                    "label is a judgement about a domain and is never inferred from a "
+                    "field name: declare one under `dataLabels` in "
+                    "sourcecode.config.json and re-run."
+                ),
+                "summary": {
+                    "labels": 0,
+                    "seeds": 0,
+                    "endpoints_exposed": None,
+                    "by_evidence": {},
+                    "by_security_verdict": {},
+                },
+                "routes": [],
+                "seeds": [],
+                "non_coverage": non_coverage.block("data_exposure"),
+            }
+        )
+        return payload
+
+    if cir is None:
+        graph = ContextGraph.build_from_root(root)
+        cir = graph.cir
+    else:
+        graph = ContextGraph.from_cir(cir)
+
+    from sourcecode.security_posture import endpoint_security_surface
+    from sourcecode.spring_impact import run_impact_chain
+
+    surface = endpoint_security_surface(cir, root=root)
+    profile_access: dict[str, str] = {}
+    if profiles:
+        from sourcecode.posture import endpoint_access_under
+
+        profile_access = endpoint_access_under(root, set(profiles), cir=cir)
+
+    handlers = {
+        str(getattr(e, "handler_symbol", "") or (e.get("handler_symbol") if isinstance(e, dict) else "")): e
+        for e in (getattr(cir, "endpoints", None) or [])
+    }
+    handlers.pop("", None)
+
+    # endpoint_id → (fields, labels, seeds, best evidence)
+    rows: dict[str, dict] = {}
+    seeds_report: list[dict] = []
+
+    for label in decl.labels:
+        for seed in label.seed_types:
+            found_signature = _signature_routes(graph, seed, handlers)
+            chain = run_impact_chain(cir, seed, root=root, model=model, depth=depth)
+            resolution = str(getattr(chain, "resolution", "not_found"))
+            reached = list(getattr(chain, "endpoints_affected", []) or [])
+
+            for endpoint in reached:
+                _record(rows, _endpoint_fields(endpoint), label, seed, CALL_REACH)
+            for fields in found_signature:
+                _record(rows, fields, label, seed, SIGNATURE)
+
+            seeds_report.append(
+                {
+                    "label": label.label,
+                    "declared": seed,
+                    "resolved_symbol": str(getattr(chain, "symbol", seed)),
+                    "resolution": resolution,
+                    "routes_by_signature": len(found_signature),
+                    "routes_by_call_reach": len(reached),
+                    # A declared type the graph never resolved cannot be reported as
+                    # "exposes nothing": nothing was measured about it (R9/I-3).
+                    "measured": resolution != "not_found",
+                    "note": (
+                        "The declared type was not found in the analysed population, "
+                        "so no exposure was measured for it — this is not evidence "
+                        "that it is unexposed."
+                        if resolution == "not_found" else ""
+                    ),
+                }
+            )
+
+    routes = [
+        _finish_route(row, surface, profile_access, bool(profiles))
+        for row in rows.values()
+    ]
+    routes.sort(
+        key=lambda r: (
+            _EVIDENCE_RANK.get(r.evidence, 9), r.path, r.method, r.endpoint_id
+        )
+    )
+
+    payload.update(
+        {
+            "answered": True,
+            "summary": _summary(decl, seeds_report, routes, bool(profiles)),
+            "seeds": seeds_report,
+            "routes": [r.to_dict() for r in routes],
+            "evidence_classes": {
+                name: _EVIDENCE_MEANING[name] for name in (SIGNATURE, CALL_REACH)
+            },
+            "reading": (
+                "`signature` routes carry the labelled type as declared. "
+                "`call_reach` routes can reach it and are a supremum: a mapping that "
+                "drops the labelled member on the way out is not modelled. Neither "
+                "class sees a flow that never names the type — reflection, a runtime "
+                "serializer, an untyped payload, a native query — so a route absent "
+                "from this answer is not evidence that it carries nothing."
+            ),
+            "non_coverage": non_coverage.block("data_exposure"),
+        }
+    )
+    return payload
+
+
+def _record(
+    rows: dict[str, dict], fields: dict, label: DataLabel, seed: str, evidence: str
+) -> None:
+    endpoint_id = fields["endpoint_id"]
+    if not endpoint_id:
+        return
+    row = rows.setdefault(
+        endpoint_id, {**fields, "labels": set(), "seeds": set(), "evidence": evidence}
+    )
+    row["labels"].add(label.label)
+    row["seeds"].add(seed)
+    if _EVIDENCE_RANK[evidence] < _EVIDENCE_RANK[row["evidence"]]:
+        row["evidence"] = evidence
+
+
+def _signature_routes(graph: Any, seed: str, handlers: dict) -> list[dict]:
+    """Handlers whose own parameter/return types name the seed type.
+
+    Matched on the type as written, which is how the class type-reference atoms are
+    keyed, and on the simple name of a fully-qualified declaration — a repository
+    writes `Customer` in a signature and `com.example.Customer` in a configuration
+    file, and the label must find the route either way.
+    """
+    out: dict[str, dict] = {}
+    for name in {seed, _simple(seed)}:
+        for ref in graph.structural_references_to_type(name):
+            if ref.context not in _SIGNATURE_CONTEXTS:
+                continue
+            endpoint = handlers.get(ref.member_fqn)
+            if endpoint is None:
+                continue
+            fields = _endpoint_fields(endpoint)
+            out[fields["endpoint_id"]] = fields
+    return list(out.values())
+
+
+def _finish_route(
+    row: dict, surface: dict, profile_access: dict, with_profile: bool
+) -> ExposedRoute:
+    from sourcecode.posture import access_verdict
+
+    endpoint_id = row["endpoint_id"]
+    bound = surface.get(endpoint_id) or {}
+    verdict = str(bound.get("verdict") or "coverage_unknown")
+    access = decision = None
+    if with_profile:
+        decision = str(profile_access.get(endpoint_id, "no_rule_matched"))
+        access = access_verdict(decision)
+    return ExposedRoute(
+        endpoint_id=endpoint_id,
+        method=row["method"],
+        path=row["path"],
+        controller_class=row["controller_class"],
+        handler_symbol=row["handler_symbol"],
+        labels=tuple(sorted(row["labels"])),
+        seeds=tuple(sorted(row["seeds"])),
+        evidence=row["evidence"],
+        verdict=verdict,
+        access=access,
+        access_decision=decision,
+    )
+
+
+def _summary(
+    decl: LabelDeclaration,
+    seeds: list[dict],
+    routes: list[ExposedRoute],
+    with_profile: bool,
+) -> dict:
+    by_evidence: dict[str, int] = {}
+    by_verdict: dict[str, int] = {}
+    by_access: dict[str, int] = {}
+    for route in routes:
+        by_evidence[route.evidence] = by_evidence.get(route.evidence, 0) + 1
+        by_verdict[route.verdict] = by_verdict.get(route.verdict, 0) + 1
+        if route.access is not None:
+            by_access[route.access] = by_access.get(route.access, 0) + 1
+    unmeasured = [s for s in seeds if not s["measured"]]
+    out = {
+        "labels": len(decl.labels),
+        "seeds": len(seeds),
+        "seeds_not_resolved": len(unmeasured),
+        # Counted over the routes themselves, never over a rendered list.
+        "endpoints_exposed": len(routes),
+        "by_evidence": dict(sorted(by_evidence.items())),
+        "by_security_verdict": dict(sorted(by_verdict.items())),
+        "declaration_problems": len(decl.problems),
+    }
+    if with_profile:
+        out["by_access_under_profile"] = dict(sorted(by_access.items()))
+    return out