@shortlink-org/portolan 0.1.0

package/plugins/extract-django/auth.py

@@ -0,0 +1,302 @@
+"""Who may call an endpoint, read off DRF's permission and authentication
+classes and written into the inferred OpenAPI document as `security`.
+
+DRF decides both per view, and the reader follows the same order the
+framework does: the handler's own `@action(permission_classes=...)` or the
+function's `@permission_classes(...)`, then a `get_permissions()` that a
+`self.action` branch can decide, then the class attribute - its own or one a
+local base class declares - and past all of those `REST_FRAMEWORK` in the
+settings module, and past that DRF's own defaults, which are session or
+basic authentication and `AllowAny`. `authentication_classes` is read the
+same way.
+
+What is written is OpenAPI's, not DRF's. An authentication class becomes a
+security scheme - `SessionAuthentication` a cookie, `TokenAuthentication` an
+`Authorization` header, `JWTAuthentication` a bearer token - and the
+permission classes decide whether an operation requires one of them, accepts
+one optionally, or takes nobody's name. A permission this reader does not
+know - a project's own `IsOwner` - is not guessed at: the operation gets no
+`security` of its own, its classes are still written under
+`x-portolan-permissions`, and the diagnostic says which class it was.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+from celery_conf import follow, settings_module_name
+from serializers import resolve_symbol, selected_return
+from source import Module, Project, assigned, const_str, dotted, keyword
+
+# DRF's authentication classes and the common third-party ones, to the
+# security scheme OpenAPI writes them as. The id is what the operations refer
+# to, and it is the one drf-spectacular gives the same class, so a document a
+# project generates at runtime and this one agree on the name.
+AUTHENTICATION: Dict[str, Tuple[str, Dict[str, Any]]] = {
+    "SessionAuthentication": ("cookieAuth", {"type": "apiKey", "in": "cookie", "name": "sessionid"}),
+    "BasicAuthentication": ("basicAuth", {"type": "http", "scheme": "basic"}),
+    "TokenAuthentication": (
+        "tokenAuth",
+        {"type": "apiKey", "in": "header", "name": "Authorization", "description": "Token-based authentication with required prefix \"Token\"."},
+    ),
+    "JWTAuthentication": ("jwtAuth", {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}),
+    "JWTStatelessUserAuthentication": ("jwtAuth", {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}),
+    "JSONWebTokenAuthentication": ("jwtAuth", {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}),
+    "OAuth2Authentication": (
+        "oauth2",
+        {"type": "oauth2", "flows": {}, "description": "OAuth 2.0 bearer token; the flows are configured at runtime and are not recoverable from source."},
+    ),
+}
+
+# DRF's own permissions, by what they say about who may call.
+PUBLIC = {"AllowAny"}
+REQUIRED = {"IsAuthenticated", "IsAdminUser", "DjangoModelPermissions", "DjangoObjectPermissions"}
+READ_OPTIONAL = {"IsAuthenticatedOrReadOnly", "DjangoModelPermissionsOrAnonReadOnly"}
+SAFE_VERBS = {"GET", "HEAD", "OPTIONS"}
+
+# What DRF applies when the settings say nothing.
+DEFAULT_AUTHENTICATION = ["SessionAuthentication", "BasicAuthentication"]
+DEFAULT_PERMISSION = ["AllowAny"]
+
+
+@dataclass
+class Security:
+    """What one operation says about its caller."""
+
+    # The OpenAPI `security` requirement, or None when it could not be decided.
+    requirement: Optional[List[Dict[str, List[str]]]]
+    # The permission classes as the code names them, for `x-portolan-permissions`.
+    permissions: List[str] = field(default_factory=list)
+    # The schemes the requirement refers to, for `components.securitySchemes`.
+    schemes: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+
+
+class Registry:
+    def __init__(self, project: Project, settings: str, b) -> None:
+        self.project = project
+        self.b = b
+        self.default_authentication, self.default_permission = read_defaults(project, settings)
+        self.schemes: Dict[str, Dict[str, Any]] = {}
+        self._warned: set = set()
+
+    # --- what the document says at the top ---------------------------------
+
+    def default_security(self) -> Optional[List[Dict[str, List[str]]]]:
+        """The document-level requirement: what an operation the settings
+        alone decide would carry, for a POST."""
+        decided = self.decide(self.default_authentication, self.default_permission, "POST", "")
+        return decided.requirement
+
+    # --- what one operation says -------------------------------------------
+
+    def security_for(self, endpoint) -> Security:
+        declared = declared_security(endpoint)
+        if declared is not None:
+            return self.schemes_of(declared)
+        authentication = self.classes_for(endpoint, "authentication_classes", "get_authenticators")
+        if authentication is None:
+            authentication = list(self.default_authentication)
+        permission = self.classes_for(endpoint, "permission_classes", "get_permissions")
+        if permission is None:
+            permission = list(self.default_permission)
+        if UNRESOLVED in authentication or UNRESOLVED in permission:
+            names = [name for name in permission if name is not UNRESOLVED]
+            self.warn(endpoint.route_source or endpoint.module.rel, "%s builds its permission or authentication classes in a way this reader cannot follow; the operation carries no security of its own" % endpoint.id)
+            return Security(None, names)
+        return self.decide(authentication, permission, endpoint.verb.upper(), endpoint.route_source or endpoint.module.rel)
+
+    def decide(self, authentication: List[str], permission: List[str], verb: str, where: str) -> Security:
+        schemes: Dict[str, Dict[str, Any]] = {}
+        for name in authentication:
+            scheme_id, scheme = self.scheme_of(name, where)
+            schemes[scheme_id] = scheme
+        self.schemes.update(schemes)
+        unknown = [name for name in permission if name not in PUBLIC and name not in REQUIRED and name not in READ_OPTIONAL]
+        if unknown:
+            for name in unknown:
+                self.warn(where, "%s is not a DRF permission this reader knows, so whether the endpoint needs a caller is not said; the class is kept under x-portolan-permissions" % name)
+            return Security(None, list(permission), schemes)
+        # DRF's permission list is a conjunction, and its authentication list
+        # is tried in order until one answers, so the requirement is one
+        # alternative per scheme - and an empty one when nobody is needed.
+        required = any(name in REQUIRED for name in permission) or (verb not in SAFE_VERBS and any(name in READ_OPTIONAL for name in permission))
+        requirement = [{scheme_id: []} for scheme_id in schemes]
+        if required and not requirement:
+            self.warn(where, "the endpoint requires an authenticated caller but declares no authentication class: nobody can call it")
+        if not required and requirement:
+            requirement.append({})
+        return Security(requirement, list(permission), schemes)
+
+    def schemes_of(self, declared: List[Dict[str, List[str]]]) -> Security:
+        """A requirement the schema decorator spelled out, in OpenAPI's own
+        words; the schemes it names are the document's to declare."""
+        known = {scheme_id: scheme for _, (scheme_id, scheme) in AUTHENTICATION.items()}
+        schemes = {}
+        for alternative in declared:
+            for scheme_id in alternative:
+                if scheme_id in known:
+                    schemes[scheme_id] = known[scheme_id]
+        self.schemes.update(schemes)
+        return Security(declared, [], schemes)
+
+    def scheme_of(self, name: str, where: str) -> Tuple[str, Dict[str, Any]]:
+        if name in AUTHENTICATION:
+            scheme_id, scheme = AUTHENTICATION[name]
+            return scheme_id, dict(scheme)
+        self.warn(where, "%s is not a DRF authentication class this reader knows; it is written as a security scheme of its own, and how the credential travels is not said" % name)
+        scheme_id = name[0].lower() + name[1:] if name else "customAuth"
+        return scheme_id, {
+            "type": "http",
+            "scheme": "unknown",
+            "description": "%s: a custom authentication class. How the credential travels is not recoverable from source." % name,
+            "x-portolan-inferred": True,
+        }
+
+    # --- where the classes come from ---------------------------------------
+
+    def classes_for(self, endpoint, attribute: str, selector: str) -> Optional[List[Any]]:
+        """The classes in force for this endpoint, in DRF's order of
+        precedence, or None when nothing but the settings says."""
+        node = endpoint.node
+        module = endpoint.module
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for decorator in node.decorator_list:
+                if not isinstance(decorator, ast.Call):
+                    continue
+                last = dotted(decorator.func).split(".")[-1]
+                if last == attribute and decorator.args:
+                    return class_names(decorator.args[0], module)
+                if last == "action" and keyword(decorator, attribute) is not None:
+                    return class_names(keyword(decorator, attribute), module)
+        view = view_class(endpoint)
+        if view is None:
+            return None
+        chosen = next((m for m in view.body if isinstance(m, (ast.FunctionDef, ast.AsyncFunctionDef)) and m.name == selector), None)
+        if chosen is not None:
+            selected = selected_return(chosen.body, endpoint.action)
+            if selected is None:
+                return [UNRESOLVED]
+            return class_names(selected, module)
+        found = self.class_attribute(module, view, attribute, 0)
+        if found is None:
+            return None
+        value, owner = found
+        return class_names(value, owner)
+
+    def class_attribute(self, module: Module, node: ast.ClassDef, attribute: str, depth: int) -> Optional[Tuple[ast.AST, Module]]:
+        """The attribute as this class or a local base of it assigns it."""
+        for name, value, _ in assigned(node):
+            if name == attribute:
+                return value, module
+        if depth > 5:
+            return None
+        for base in node.bases:
+            name = dotted(base)
+            if not name:
+                continue
+            target_module, target_name = resolve_symbol(self.project, module, name)
+            target = self.project.module(target_module) if target_module else None
+            if target is None:
+                continue
+            base_node = next((c for c in target.classes() if c.name == target_name.split(".")[-1]), None)
+            if base_node is None:
+                continue
+            found = self.class_attribute(target, base_node, attribute, depth + 1)
+            if found is not None:
+                return found
+        return None
+
+    def warn(self, where: str, message: str) -> None:
+        if (where, message) in self._warned:
+            return
+        self._warned.add((where, message))
+        self.b.warn(where, message)
+
+
+# A class expression syntax does not name, kept apart from every real name.
+UNRESOLVED = object()
+
+
+def view_class(endpoint) -> Optional[ast.ClassDef]:
+    if not endpoint.view:
+        return None
+    name = endpoint.view.split(".", 1)[0]
+    return next((node for node in endpoint.module.classes() if node.name == name), None)
+
+
+def class_names(value: Optional[ast.AST], module: Module) -> List[Any]:
+    """`[IsAuthenticated, perms.IsOwner()]` as the class names it lists; an
+    element that is not a name - `IsAuthenticated | ReadOnly` - is UNRESOLVED."""
+    value = follow(value, module)
+    if not isinstance(value, (ast.List, ast.Tuple)):
+        return [UNRESOLVED]
+    out: List[Any] = []
+    for element in value.elts:
+        target = element.func if isinstance(element, ast.Call) else element
+        name = dotted(target).split(".")[-1]
+        out.append(name if name else UNRESOLVED)
+    return out
+
+
+def declared_security(endpoint) -> Optional[List[Dict[str, List[str]]]]:
+    """`extend_schema(auth=[...])` or `swagger_auto_schema(security=[...])`
+    on the handler: the requirement as the author wrote it, when it is
+    written as literals."""
+    node = endpoint.node
+    if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return None
+    for decorator in node.decorator_list:
+        if not isinstance(decorator, ast.Call):
+            continue
+        last = dotted(decorator.func).split(".")[-1]
+        value = keyword(decorator, "auth") if last == "extend_schema" else keyword(decorator, "security") if last == "swagger_auto_schema" else None
+        if value is None:
+            continue
+        if not isinstance(value, (ast.List, ast.Tuple)):
+            return None
+        out: List[Dict[str, List[str]]] = []
+        for element in value.elts:
+            if isinstance(element, ast.Dict):
+                alternative: Dict[str, List[str]] = {}
+                for key, scopes in zip(element.keys, element.values):
+                    scheme_id = const_str(key)
+                    if not scheme_id or not isinstance(scopes, (ast.List, ast.Tuple)):
+                        return None
+                    alternative[scheme_id] = [const_str(scope) for scope in scopes.elts]
+                out.append(alternative)
+            elif const_str(element):
+                out.append({const_str(element): []})
+            else:
+                return None
+        return out
+    return None
+
+
+def read_defaults(project: Project, settings: str) -> Tuple[List[str], List[str]]:
+    """`REST_FRAMEWORK["DEFAULT_AUTHENTICATION_CLASSES"]` and
+    `["DEFAULT_PERMISSION_CLASSES"]` off the settings module, as class names;
+    DRF's own defaults where the settings say nothing."""
+    authentication = list(DEFAULT_AUTHENTICATION)
+    permission = list(DEFAULT_PERMISSION)
+    module = project.module(settings or settings_module_name(project))
+    if module is None:
+        return authentication, permission
+    config: Optional[ast.AST] = None
+    for name, value, _ in assigned(module.tree):
+        if name == "REST_FRAMEWORK":
+            config = follow(value, module)
+    if not isinstance(config, ast.Dict):
+        return authentication, permission
+    for key, value in zip(config.keys, config.values):
+        setting = const_str(key) if key is not None else ""
+        value = follow(value, module)
+        if setting not in ("DEFAULT_AUTHENTICATION_CLASSES", "DEFAULT_PERMISSION_CLASSES") or not isinstance(value, (ast.List, ast.Tuple)):
+            continue
+        names = [const_str(element).split(".")[-1] for element in value.elts if const_str(element)]
+        if setting == "DEFAULT_AUTHENTICATION_CLASSES":
+            authentication = names
+        else:
+            permission = names
+    return authentication, permission

package/plugins/extract-django/auth_test.py

@@ -0,0 +1,188 @@
+import json
+import os
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(1, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "pyplugin"))
+
+import apps  # noqa: E402
+import auth  # noqa: E402
+import routing  # noqa: E402
+import serializers  # noqa: E402
+import transport  # noqa: E402
+from extract import openapi_document, routed_applications  # noqa: E402
+from protocol import Builder  # noqa: E402
+from source import Project  # noqa: E402
+
+
+class WhoMayCall(unittest.TestCase):
+    """Each way DRF says who may call, once, and what OpenAPI it becomes."""
+
+    def setUp(self):
+        self.holder = tempfile.TemporaryDirectory(prefix="portolan-django-auth-")
+        root = self.holder.name
+        files = {
+            "manage.py": 'os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")\n',
+            "config/settings.py": '''
+ROOT_URLCONF = "config.urls"
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": ("rest_framework.authentication.TokenAuthentication",),
+    "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.AllowAny"],
+}
+''',
+            "config/urls.py": '''
+from django.urls import include, path
+urlpatterns = [path("", include("api.urls"))]
+''',
+            "api/base.py": '''
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.views import APIView
+class Protected(APIView):
+    permission_classes = [IsAuthenticated]
+''',
+            "api/views.py": '''
+from drf_spectacular.utils import extend_schema
+from rest_framework import viewsets
+from rest_framework.decorators import api_view, authentication_classes, permission_classes
+from rest_framework.permissions import AllowAny, IsAuthenticated
+from rest_framework.views import APIView
+from .base import Protected
+from .perms import IsOwner
+
+class Public(APIView):
+    def get(self, request):
+        return None
+
+class Admin(Protected):
+    def post(self, request):
+        return None
+
+class Mixed(viewsets.ViewSet):
+    def get_permissions(self):
+        if self.action == "list":
+            return [AllowAny()]
+        return [IsAuthenticated()]
+    def list(self, request):
+        return None
+    def create(self, request):
+        return None
+
+class Owned(APIView):
+    permission_classes = [IsOwner]
+    def get(self, request):
+        return None
+
+class Spelled(APIView):
+    @extend_schema(auth=[{"basicAuth": []}])
+    def get(self, request):
+        return None
+
+@api_view(["POST"])
+@authentication_classes([])
+@permission_classes([IsAuthenticated])
+def hook(request):
+    return None
+''',
+            "api/perms.py": '''
+from rest_framework.permissions import BasePermission
+class IsOwner(BasePermission):
+    pass
+''',
+            "api/urls.py": '''
+from django.urls import path
+from rest_framework.routers import DefaultRouter
+from .views import Admin, Owned, Public, Spelled, hook, Mixed
+
+router = DefaultRouter()
+router.register("mixed", Mixed, basename="mixed")
+urlpatterns = [
+    path("public/", Public.as_view()),
+    path("admin/", Admin.as_view()),
+    path("owned/", Owned.as_view()),
+    path("spelled/", Spelled.as_view()),
+    path("hook/", hook),
+] + router.urls
+''',
+        }
+        for name, contents in files.items():
+            path = os.path.join(root, name)
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "w", encoding="utf-8") as handle:
+                handle.write(contents)
+        self.project = Project(root, root, lambda path: os.path.relpath(path, root).replace(os.sep, "/"))
+        self.b = Builder()
+        routes = routing.read(self.project)
+        endpoint_apps = routed_applications(self.project, apps.discover(self.project, []), routes)
+        endpoints = []
+        for app in endpoint_apps:
+            endpoints += [(app, endpoint) for endpoint in transport.read_endpoints(app, self.b, routes)]
+        registry = serializers.read(self.project, endpoint_apps)
+        self.registry = auth.Registry(self.project, "", self.b)
+        self.spec = openapi_document(endpoints, "Api", self.b, registry, "", self.registry)
+
+    def tearDown(self):
+        self.holder.cleanup()
+
+    def operation(self, path, verb):
+        return self.spec["paths"][path][verb]
+
+    def test_the_settings_decide_the_document_and_a_view_that_says_nothing(self):
+        self.assertEqual(self.registry.default_authentication, ["TokenAuthentication"])
+        self.assertEqual(self.spec["security"], [{"tokenAuth": []}, {}])
+        self.assertEqual(self.operation("/public/", "get")["security"], [{"tokenAuth": []}, {}])
+        self.assertEqual(self.operation("/public/", "get")["x-portolan-permissions"], ["AllowAny"])
+        self.assertEqual(self.spec["components"]["securitySchemes"]["tokenAuth"]["in"], "header")
+
+    def test_a_local_base_class_lends_its_permissions(self):
+        self.assertEqual(self.operation("/admin/", "post")["security"], [{"tokenAuth": []}])
+        self.assertEqual(self.operation("/admin/", "post")["x-portolan-permissions"], ["IsAuthenticated"])
+
+    def test_get_permissions_is_decided_per_action(self):
+        self.assertEqual(self.operation("/mixed/", "get")["security"], [{"tokenAuth": []}, {}])
+        self.assertEqual(self.operation("/mixed/", "post")["security"], [{"tokenAuth": []}])
+
+    def test_a_permission_the_reader_does_not_know_is_named_and_not_guessed(self):
+        owned = self.operation("/owned/", "get")
+        self.assertNotIn("security", owned)
+        self.assertEqual(owned["x-portolan-permissions"], ["IsOwner"])
+        self.assertTrue(any("IsOwner is not a DRF permission" in w.message for w in self.b.warnings))
+
+    def test_the_schema_decorator_spells_the_requirement_itself(self):
+        self.assertEqual(self.operation("/spelled/", "get")["security"], [{"basicAuth": []}])
+        self.assertEqual(self.spec["components"]["securitySchemes"]["basicAuth"], {"type": "http", "scheme": "basic"})
+
+    def test_a_function_view_reads_its_decorators_and_an_empty_list_is_a_fact(self):
+        hook = self.operation("/hook/", "post")
+        self.assertEqual(hook["security"], [])
+        self.assertEqual(hook["x-portolan-permissions"], ["IsAuthenticated"])
+        self.assertTrue(any("nobody can call it" in w.message for w in self.b.warnings))
+
+    def test_the_document_is_still_json(self):
+        json.dumps(self.spec)
+
+
+class ReadOnly(unittest.TestCase):
+    def test_read_only_permissions_relax_safe_verbs_only(self):
+        registry = auth.Registry.__new__(auth.Registry)
+        registry.schemes = {}
+        registry._warned = set()
+        registry.b = Builder()
+        for verb, expected in (("GET", [{"cookieAuth": []}, {}]), ("POST", [{"cookieAuth": []}])):
+            decided = registry.decide(["SessionAuthentication"], ["IsAuthenticatedOrReadOnly"], verb, "")
+            self.assertEqual(decided.requirement, expected)
+
+    def test_a_custom_authentication_class_is_a_scheme_whose_transport_is_unknown(self):
+        registry = auth.Registry.__new__(auth.Registry)
+        registry.schemes = {}
+        registry._warned = set()
+        registry.b = Builder()
+        decided = registry.decide(["HmacAuthentication"], ["IsAuthenticated"], "POST", "api/views.py")
+        self.assertEqual(decided.requirement, [{"hmacAuthentication": []}])
+        self.assertEqual(decided.schemes["hmacAuthentication"]["scheme"], "unknown")
+        self.assertEqual(len(registry.b.warnings), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/plugins/extract-django/clients.py

@@ -0,0 +1,121 @@
+"""A call to another service, read off the client that makes it.
+
+`<app>/clients/<peer>/` holds the vendored document and the class that calls
+it. The code names the verb and the route - `self._http.post("/v1/quotes")` -
+and the document beside it says which operation answers there, so the call is
+recorded under the id the callee's own extractor would give it. Without a
+document there is no id to share: the call is still recorded, against the route
+it names, and left unresolved.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+from dataclasses import dataclass, field as dc_field
+from typing import Dict, List, Optional, Tuple
+
+import openapi
+from apps import App
+from source import Module, const_str, dotted
+
+VERBS = {"get", "post", "put", "patch", "delete", "head", "options", "request"}
+
+
+@dataclass
+class Call:
+    """One method of a client, and what it reaches."""
+
+    id: str  # "shop.v1.Pricing/GetQuote", or "POST /v1/quotes" when nothing names it
+    pkg: str  # what the manifest's peers map is keyed by: the api id
+    source: str  # the document, or the client module
+    label: str  # what the arrow says: the operation, or the route
+    resolved: bool
+
+
+@dataclass
+class Client:
+    name: str  # the class
+    module: Module
+    directory: str
+    spec: Optional[openapi.Spec] = None
+    calls: Dict[str, Call] = dc_field(default_factory=dict)  # method -> call
+
+
+def path_of(node: ast.AST) -> str:
+    """The route as the code writes it, with every hole spelled the same."""
+    literal = const_str(node)
+    if literal:
+        return literal
+    if isinstance(node, ast.JoinedStr):
+        out = ""
+        for part in node.values:
+            if isinstance(part, ast.Constant) and isinstance(part.value, str):
+                out += part.value
+            else:
+                out += "{}"
+        return out
+    return ""
+
+
+def http_call(node: ast.Call) -> Optional[Tuple[str, str]]:
+    """(verb, route) for a call that goes out over HTTP.
+
+    The route has to look like one. `get` is the name of an HTTP verb and also
+    the name of the method every mapping in Python has, and what tells the two
+    apart is that only one of them is handed a path."""
+    name = dotted(node.func)
+    verb = name.split(".")[-1]
+    if verb not in VERBS or not node.args:
+        return None
+    if verb == "request":
+        if len(node.args) < 2:
+            return None
+        route = path_of(node.args[1])
+        return (const_str(node.args[0]).upper(), route) if is_route(route) else None
+    route = path_of(node.args[0])
+    return (verb.upper(), route) if is_route(route) else None
+
+
+def is_route(route: str) -> bool:
+    return route.startswith("/") or route.startswith("http://") or route.startswith("https://")
+
+
+def read_clients(app: App, peers: Dict[str, str], rel, b) -> List[Client]:
+    out: List[Client] = []
+    for module in app.package("clients"):
+        directory = os.path.dirname(module.path)
+        spec_path = openapi.beside(directory)
+        spec = openapi.read(spec_path) if spec_path else None
+        for node in module.classes():
+            client = Client(name=node.name, module=module, directory=directory, spec=spec)
+            for method in node.body:
+                if not isinstance(method, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    continue
+                for child in ast.walk(method):
+                    if not isinstance(child, ast.Call):
+                        continue
+                    found = http_call(child)
+                    if found is None:
+                        continue
+                    verb, route = found
+                    client.calls[method.name] = resolve(verb, route, spec, module, os.path.basename(directory), rel, b)
+                    break
+            if client.calls:
+                out.append(client)
+        if spec is None and any(module.classes()):
+            b.warn(module.rel, "no OpenAPI document beside this client: its calls name a route, and nothing says which operation answers there")
+    for client in out:
+        for call in client.calls.values():
+            if call.resolved and call.pkg not in peers:
+                b.warn(call.id, "%s answers this call and the manifest names no peer for it: the step stays unresolved" % call.pkg)
+    return out
+
+
+def resolve(verb: str, route: str, spec: Optional[openapi.Spec], module: Module, fallback: str, rel, b) -> Call:
+    if spec is not None:
+        operation = spec.find(verb, route)
+        if operation is not None:
+            return Call(id=operation.call_id(spec.api), pkg=spec.api, source=rel(spec.path), label=operation.id, resolved=True)
+        b.warn(module.rel, "%s %s is not a route %s declares" % (verb, route, rel(spec.path)))
+    return Call(id="%s %s" % (verb, route), pkg=fallback, source=module.rel, label="%s %s" % (verb, route), resolved=False)