code-node-graph 0.1.0__py3-none-any.whl

code_node/project.py

@@ -0,0 +1,402 @@
+"""
+A folder of Python code: its files, the names Python imports them by, and the entry points worth starting from.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .analysis.syntax import _parse
+from .deploys import all_deployments, deploy_file_names
+from .platforms import platforms
+
+_SKIPPED_FOLDERS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".venv",
+        "venv",
+        "env",
+        ".env",
+        "node_modules",
+        "__pycache__",
+        ".tox",
+        ".nox",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        "build",
+        "dist",
+        "site-packages",
+        ".eggs",
+        ".idea",
+        ".vscode",
+    }
+)
+
+_MAX_FILES = 5_000  # Python files read from one folder, at most
+
+_MAX_FILE_BYTES = 2 * 1024 * 1024  # a bigger .py file is generated code: skipped
+
+_MAIN_NAMES = ("main", "run", "cli", "app")
+
+_IMPORT_RE = re.compile(r"^[ \t]*(?:from[ \t]+([\w.]+)[ \t]+import|import[ \t]+([\w., \t]+))", re.M)
+
+_CLI_APPS = ("Typer",)  # web apps are a platform's (FastAPI for the web one, Chalice for Lambda's)
+
+
+@dataclass
+class EntryPoint:
+    """
+    A place to start reading the code from: 'pkg.cli.main', and why it's a good one.
+    """
+
+    name: str  # module.function, module.Class.method, or module.app (a web app object)
+    why: str  # 'a console script (code-node)', 'runs under if __name__ == "__main__"', 'a Lambda handler'
+    file: str
+    line: int
+    platform: str = ""  # the platform that found it ('lambda' for a Lambda handler): its checks run on the code
+
+
+@dataclass
+class Project:
+    """
+    The Python files under a folder, read as text: {path from the folder, with /: source}.
+    """
+
+    root: Path
+    files: dict[str, str] = field(default_factory=dict)
+    modules: dict[str, str] = field(default_factory=dict)  # file -> the module name Python imports it by
+    skipped: list[str] = field(default_factory=list)
+    limited: bool = False
+    configs: list[str] = field(default_factory=list)  # its pyproject.toml files, the root's first
+    deploy_files: dict[str, str] = field(default_factory=dict)  # files deploy plugins read (template.yaml,
+    # serverless.yml): {path from the folder: text}
+    _trees: dict[str, ast.Module] | None = None
+
+    @property
+    def trees(self) -> dict[str, ast.Module]:
+        """
+        Each file's syntax tree, parsed the first time it's asked for (files that don't parse are left out).
+        """
+        if self._trees is None:
+            self._trees = {}
+            for rel, text in self.files.items():
+                try:
+                    self._trees[rel] = _parse(text, rel)
+                except (SyntaxError, ValueError):
+                    self.skipped.append(rel)
+        return self._trees
+
+    @property
+    def own_tops(self) -> set[str]:
+        """
+        The top-level packages and modules that are this folder's own code.
+        """
+        return {module.split(".")[0] for module in self.modules.values()}
+
+    def libraries(self) -> set[str]:
+        """
+        Every top-level module the code imports that isn't its own: read as installed libraries, never as missing.
+        """
+        own = self.own_tops
+        found: set[str] = set()
+        for text in self.files.values():
+            for match in _IMPORT_RE.finditer(text):
+                names = match.group(1) or match.group(2)
+                found |= {name.strip().split(".")[0] for name in names.split(",")}
+        found = {name.split(" ")[0] for name in found if name}
+        return {name for name in found if name not in own and name not in sys.stdlib_module_names}
+
+
+def _module_name(path: Path, root: Path) -> str:
+    """
+    The name Python imports a file by: up through the folders that hold an __init__.py, the way a package is laid
+    out. 'src/pkg/sub/mod.py' (pkg and sub with __init__.py) -> 'pkg.sub.mod'.
+    """
+    parts = [path.stem] if path.name != "__init__.py" else []
+    folder = path.parent
+    while folder != root and (folder / "__init__.py").exists():
+        parts.insert(0, folder.name)
+        folder = folder.parent
+    return ".".join(parts)
+
+
+def read_project(root: str | os.PathLike[str]) -> Project:
+    """
+    Every .py file under root, skipping virtual environments, caches and build output.
+    """
+    base = Path(root).resolve()
+    project = Project(base)
+    deploy_names = deploy_file_names()
+    for folder, subfolders, names in os.walk(base):
+        subfolders[:] = sorted(d for d in subfolders if d not in _SKIPPED_FOLDERS and not d.endswith(".egg-info"))
+        for name in sorted(names):
+            if name == "pyproject.toml":
+                project.configs.append((Path(folder) / name).relative_to(base).as_posix())
+            if name in deploy_names and (Path(folder) / name).stat().st_size <= _MAX_FILE_BYTES:
+                rel = (Path(folder) / name).relative_to(base).as_posix()
+                project.deploy_files[rel] = (Path(folder) / name).read_text("utf-8", "replace")
+            if not name.endswith(".py"):
+                continue
+            path = Path(folder) / name
+            rel = path.relative_to(base).as_posix()
+            if len(project.files) >= _MAX_FILES:
+                project.limited = True
+                return project
+            if path.stat().st_size > _MAX_FILE_BYTES:
+                project.skipped.append(rel)
+                continue
+            text = path.read_text("utf-8", "replace")
+            project.files[rel] = text
+            project.modules[rel] = _module_name(path, base)
+    return project
+
+
+def _console_scripts(path: Path) -> dict[str, str]:
+    """
+    A pyproject.toml's console scripts: {'code-node': 'code_node.cli:main'}.
+    """
+    if not path.exists():
+        return {}
+    text = path.read_text("utf-8", "replace")
+    try:
+        import tomllib
+    except ImportError:  # Python 3.10: read the [project.scripts] table by hand
+        table = re.search(r"^\[(?:project\.scripts|tool\.poetry\.scripts)\]\s*$(.*?)(?=^\[|\Z)", text, re.M | re.S)
+        lines = table.group(1).splitlines() if table else []
+        pairs = (re.match(r"\s*['\"]?([\w.-]+)['\"]?\s*=\s*['\"]([\w.:]+)['\"]", line) for line in lines)
+        return {match.group(1): match.group(2) for match in pairs if match}
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError:
+        return {}
+    scripts = dict(data.get("project", {}).get("scripts", {}))
+    scripts.update(data.get("tool", {}).get("poetry", {}).get("scripts", {}))
+    return {name: str(target) for name, target in scripts.items()}
+
+
+def _main_guard_calls(tree: ast.Module) -> list[str]:
+    """
+    The functions an `if __name__ == "__main__":` block calls: ['main'].
+    """
+    called = []
+    for node in tree.body:
+        is_guard = (
+            isinstance(node, ast.If)
+            and isinstance(node.test, ast.Compare)
+            and isinstance(node.test.left, ast.Name)
+            and node.test.left.id == "__name__"
+        )
+        if not is_guard:
+            continue
+        for inner in ast.walk(node):
+            if isinstance(inner, ast.Call) and isinstance(inner.func, ast.Name):
+                called.append(inner.func.id)
+    return called
+
+
+def _module_functions(tree: ast.Module) -> dict[str, ast.FunctionDef | ast.AsyncFunctionDef]:
+    return {node.name: node for node in tree.body if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))}
+
+
+def _web_apps(tree: ast.Module) -> list[tuple[str, int, str, str]]:
+    """
+    Module-level web and CLI apps, with the platform whose app it is: `app = FastAPI()` -> [('app', 3, 'a web app:
+    each route', 'web')].
+    """
+    found = []
+    for node in tree.body:
+        if not (isinstance(node, ast.Assign) and isinstance(node.value, ast.Call)):
+            continue
+        func = node.value.func
+        made = func.attr if isinstance(func, ast.Attribute) else getattr(func, "id", "")
+        web = next((platform.name for platform in platforms() if made in platform.web_apps), None)
+        if web is not None or made in _CLI_APPS:
+            kind = "a CLI app: each command" if web is None else "a web app: each route"
+            found += [(t.id, node.lineno, kind, web or "") for t in node.targets if isinstance(t, ast.Name)]
+    return found
+
+
+def _calls(node: ast.AST) -> set[str]:
+    """
+    The plain names a function calls: {'app', 'print'}.
+    """
+    return {n.func.id for n in ast.walk(node) if isinstance(n, ast.Call) and isinstance(n.func, ast.Name)}
+
+
+def _is_test(rel: str) -> bool:
+    """
+    A test file: under tests/ or named test_*.py / *_test.py / conftest.py.
+    """
+    name = rel.rsplit("/", 1)[-1]
+    return (
+        "tests/" in f"/{rel}"
+        or "/test/" in f"/{rel}"
+        or name.startswith("test_")
+        or name.endswith("_test.py")
+        or name == "conftest.py"
+    )
+
+
+def entry_points(project: Project) -> list[EntryPoint]:
+    """
+    Where the code starts, best first: console scripts, the entry points platforms find (Lambda handlers), web apps,
+    then what runs under `if __name__ == "__main__":` and functions named main.
+    """
+    found: dict[str, EntryPoint] = {}
+    by_module = {module: rel for rel, module in project.modules.items()}
+
+    def add(entry: EntryPoint) -> None:
+        found.setdefault(entry.name, entry)
+
+    scripts = [
+        (script, target, config)
+        for config in project.configs
+        for script, target in _console_scripts(project.root / config).items()
+    ]
+    for script, target, config in scripts:
+        module, _, function = target.partition(":")
+        rel = by_module.get(module)
+        if not (rel and function and rel in project.trees):
+            continue
+        tree = project.trees[rel]
+        node = _module_functions(tree).get(function.split(".")[0])
+        apps = {name: (line, kind, runs_on) for name, line, kind, runs_on in _web_apps(tree)}
+        runs = [name for name in (_calls(node) if node is not None else set()) if name in apps]
+        command = f"the {script} command" + (f" in {config}" if "/" in config else "")
+        if runs:  # main() just runs the app: start from the app, so each command is followed
+            line, kind, runs_on = apps[runs[0]]
+            add(EntryPoint(f"{module}.{runs[0]}", f"{command} ({kind})", rel, line, runs_on))
+        add(EntryPoint(f"{module}.{function}", command, rel, getattr(node, "lineno", 0)))
+    code = {rel: tree for rel, tree in project.trees.items() if not _is_test(rel)}
+    for deployed in all_deployments(project.deploy_files, project.files):
+        tree = project.trees.get(deployed.file)
+        node = _module_functions(tree).get(deployed.function) if tree is not None else None
+        if node is not None:
+            add(
+                EntryPoint(
+                    f"{project.modules[deployed.file]}.{deployed.function}",
+                    f"{deployed.name} in {deployed.source}",
+                    deployed.file,
+                    node.lineno,
+                    deployed.platform,
+                )
+            )
+    for rel, tree in code.items():
+        module = project.modules[rel]
+        for platform in platforms():
+            for name, line, why in platform.find_entries(module, tree):
+                add(EntryPoint(f"{module}.{name}", why, rel, line, platform.name))
+        for name, line, kind, runs_on in _web_apps(tree):
+            add(EntryPoint(f"{module}.{name}", kind, rel, line, runs_on))
+    for rel, tree in code.items():
+        module = project.modules[rel]
+        functions = _module_functions(tree)
+        for name in _main_guard_calls(tree):
+            if name in functions:
+                add(EntryPoint(f"{module}.{name}", 'runs under if __name__ == "__main__"', rel, functions[name].lineno))
+    for rel, tree in code.items():
+        functions = _module_functions(tree)
+        for name in _MAIN_NAMES:
+            if name in functions:
+                add(
+                    EntryPoint(
+                        f"{project.modules[rel]}.{name}", f"a function named {name}()", rel, functions[name].lineno
+                    )
+                )
+    # one another of its kind names, as include('orders.urls') does, comes after it: the site's URLs before an app's
+    named = {
+        e.name
+        for e in found.values()
+        for other in found.values()
+        if other.why == e.why
+        and other.file != e.file
+        and re.search(rf"['\"]{re.escape(e.name.rsplit('.', 1)[0])}['\"]", project.files.get(other.file, ""))
+    }
+    return [e for e in found.values() if e.name not in named] + [e for e in found.values() if e.name in named]
+
+
+def entry_in_files(project: Project, entry: str) -> EntryPoint | None:
+    """
+    The entry point as given, when its module (or, for a method, the module before its class) is a file here.
+    """
+    by_module = {module: rel for rel, module in project.modules.items()}
+    for cut in (1, 2):
+        module = entry.rsplit(".", cut)[0]
+        if module in by_module and entry.count(".") >= cut:
+            return EntryPoint(entry, "given", by_module[module], 0)
+    return None
+
+
+def functions_matching(project: Project, text: str) -> list[EntryPoint]:
+    """
+    Functions and methods whose name contains text ('save' finds repo.Orders.save), for a partly typed entry point.
+    """
+    found = []
+    needle = text.lower()
+    for rel, tree in project.trees.items():
+        module = project.modules[rel]
+        for node in tree.body:
+            members = (
+                [(f"{module}.{node.name}", node)] if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) else []
+            )
+            if isinstance(node, ast.ClassDef):
+                members = [
+                    (f"{module}.{node.name}.{m.name}", m)
+                    for m in node.body
+                    if isinstance(m, (ast.FunctionDef, ast.AsyncFunctionDef))
+                ]
+            found += [EntryPoint(name, "matches", rel, fn.lineno) for name, fn in members if needle in name.lower()]
+    return found
+
+
+def project_root(file: Path) -> Path:
+    """
+    The folder a file's project starts at: the nearest one above it with .git, pyproject.toml, setup.py or setup.cfg,
+    else the file's own folder.
+    """
+    for folder in [file.parent, *file.parent.parents]:
+        if any((folder / marker).exists() for marker in (".git", "pyproject.toml", "setup.py", "setup.cfg")):
+            return folder
+    return file.parent
+
+
+def entries_in_file(project: Project, rel: str, function: str = "") -> list[EntryPoint]:
+    """
+    Where to start in one file, best first: the function named (function or Class.method), else what its
+    `if __name__ == "__main__":` block calls, its platforms' entry points (Lambda handlers) and apps, functions named
+    main, then every other function in it from the top.
+    """
+    module = project.modules.get(rel)
+    tree = project.trees.get(rel)
+    if module is None or tree is None:
+        return []
+    found = [e for e in entry_points(project) if e.file == rel]
+    if function:
+        known = next((e for e in found if e.name == f"{module}.{function}"), None)  # a handler keeps its platform
+        return [EntryPoint(f"{module}.{function}", "named", rel, 0, known.platform if known else "")]
+    named = {e.name for e in found}
+    functions = _module_functions(tree)
+    for name in _main_guard_calls(tree):
+        if name in functions and f"{module}.{name}" not in named:
+            found.insert(
+                0, EntryPoint(f"{module}.{name}", 'runs under if __name__ == "__main__"', rel, functions[name].lineno)
+            )
+            named.add(f"{module}.{name}")
+    for name, node in functions.items():
+        if f"{module}.{name}" not in named:
+            found.append(EntryPoint(f"{module}.{name}", "a function in this file", rel, node.lineno))
+    for cls in [node for node in tree.body if isinstance(node, ast.ClassDef)]:
+        methods = [m for m in cls.body if isinstance(m, (ast.FunctionDef, ast.AsyncFunctionDef))]
+        for method in sorted(methods, key=lambda m: m.name.startswith("_")):
+            found.append(
+                EntryPoint(f"{module}.{cls.name}.{method.name}", f"a method of {cls.name}", rel, method.lineno)
+            )
+    return found

code_node/report/__init__.py

@@ -0,0 +1,3 @@
+"""
+Drawing a CodeMap as a page: the graph, the outline and the tables.
+"""

code_node/report/brands.py

@@ -0,0 +1,244 @@
+"""
+Real logos for the graph's boxes, in two sizes, as favicons come: `full`, the detailed art, for 40 pixels and up
+(a 2x screen's 32), and, for AWS's service icons, `small`, a simple mark that stays sharp at 16 to 32 (an ordinary
+screen's badge). logo_for(name, pixels) picks one; the page's graph has both and picks by the screen's density.
+
+Real logos for the graph's boxes: an AWS service's (S3, DynamoDB, SNS...) and those of the services libraries reach
+(Redis, PostgreSQL, OpenAI...). The SVGs are gilbarbara/logos, CC0, through Iconify's @iconify-json/logos, kept as
+files in logos/: scripts/logos.py downloads the pinned version and writes the ones named here. The page embeds the
+ones it uses, so it stays one file that works offline. Each logo is its company's trademark, shown to name the
+service the code reaches.
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from importlib.resources import files
+from typing import Any
+
+from ..platforms.web import FRAMEWORK_LOGOS
+
+AWS_LOGOS = {  # boto3's service name -> its logo
+    "s3": "aws-s3",
+    "s3control": "aws-s3",
+    "dynamodb": "aws-dynamodb",
+    "dynamodbstreams": "aws-dynamodb",
+    "sns": "aws-sns",
+    "sqs": "aws-sqs",
+    "lambda": "aws-lambda",
+    "kinesis": "aws-kinesis",
+    "events": "aws-eventbridge",
+    "stepfunctions": "aws-step-functions",
+    "secretsmanager": "aws-secrets-manager",
+    "ssm": "aws-systems-manager",
+    "kms": "aws-kms",
+    "ses": "aws-ses",
+    "sesv2": "aws-ses",
+    "rds": "aws-rds",
+    "rds-data": "aws-rds",
+    "redshift": "aws-redshift",
+    "redshift-data": "aws-redshift",
+    "athena": "aws-athena",
+    "glue": "aws-glue",
+    "ecs": "aws-ecs",
+    "eks": "aws-eks",
+    "ec2": "aws-ec2",
+    "cloudwatch": "aws-cloudwatch",
+    "logs": "aws-cloudwatch",
+    "cognito-idp": "aws-cognito",
+    "cognito-identity": "aws-cognito",
+    "iam": "aws-iam",
+    "sts": "aws-iam",
+    "apigateway": "aws-api-gateway",
+    "apigatewayv2": "aws-api-gateway",
+    "apigatewaymanagementapi": "aws-api-gateway",
+    "cloudfront": "aws-cloudfront",
+    "route53": "aws-route53",
+    "elasticache": "aws-elasticache",
+    "docdb": "aws-documentdb",
+    "neptune": "aws-neptune",
+    "timestream-write": "aws-timestream",
+    "timestream-query": "aws-timestream",
+    "keyspaces": "aws-keyspaces",
+    "batch": "aws-batch",
+    "codebuild": "aws-codebuild",
+    "codepipeline": "aws-codepipeline",
+    "codedeploy": "aws-codedeploy",
+    "codecommit": "aws-codecommit",
+    "cloudformation": "aws-cloudformation",
+    "xray": "aws-xray",
+    "appsync": "aws-appsync",
+    "mq": "aws-mq",
+    "kafka": "aws-msk",
+    "opensearch": "aws-open-search",
+    "es": "aws-open-search",
+    "acm": "aws-certificate-manager",
+    "backup": "aws-backup",
+    "glacier": "aws-glacier",
+    "quicksight": "aws-quicksight",
+    "wafv2": "aws-waf",
+    "waf": "aws-waf",
+    "cloudtrail": "aws-cloudtrail",
+    "config": "aws-config",
+    "lightsail": "aws-lightsail",
+    "amplify": "aws-amplify",
+    "appflow": "aws-appflow",
+    "lakeformation": "aws-lake-formation",
+    "shield": "aws-shield",
+    "elbv2": "aws-elb",
+    "elb": "aws-elb",
+}
+
+SERVICE_LOGOS = {  # a service a library reaches, as its box names it (lower case) -> its logo
+    "redis": "redis",
+    "postgresql": "postgresql",
+    "mysql": "mysql-icon",
+    "sqlite": "sqlite",
+    "mongodb": "mongodb-icon",
+    "openai": "openai-icon",
+    "azure openai": "azure-icon",
+    "anthropic": "anthropic-icon",
+    "anthropic on bedrock": "anthropic-icon",
+    "anthropic on vertex ai": "anthropic-icon",
+    "kafka": "kafka-icon",
+    "rabbitmq": "rabbitmq-icon",
+    "snowflake": "snowflake-icon",
+    "redshift": "aws-redshift",
+    "elasticsearch": "elasticsearch",
+    "mariadb": "mariadb-icon",
+    "stripe": "stripe",
+    "slack": "slack-icon",
+    "twilio": "twilio-icon",
+    "supabase": "supabase-icon",
+    "firebase": "firebase-icon",
+    "dynamodb": "aws-dynamodb",
+    "s3": "aws-s3",
+    "google cloud": "google-cloud",
+    "google cloud storage": "google-cloud",
+}
+
+
+DEPLOY_LOGOS = {"sam": "aws-cloudformation", "serverless": "serverless"}  # a deploy plugin's name -> its logo
+
+PLATFORM_LOGOS = {"lambda": "aws-lambda", "": "python"}  # a platform's name -> its logo ('' is plain Python); the
+# web one's are by framework (platforms/web.py FRAMEWORK_LOGOS), shown on an app's box
+
+LIBRARY_LOGOS = {  # a library plugin's name -> its logo, and boto3's, which the reader knows itself
+    "boto3": "aws",
+    "redis": "redis",
+    "sql": "postgresql",
+    "mongodb": "mongodb-icon",
+    "llm": "openai-icon",
+}
+
+
+AWS_GLYPHS = {  # an AWS icon -> the symbol its small mark has, in white on the service's colour (AWS's own 16 px
+    # icons are drawn that way); one not here gets 'cloud'
+    "aws-s3": "bucket",
+    "aws-glacier": "bucket",
+    "aws-backup": "bucket",
+    "aws-dynamodb": "database",
+    "aws-rds": "database",
+    "aws-aurora": "database",
+    "aws-redshift": "database",
+    "aws-timestream": "database",
+    "aws-documentdb": "database",
+    "aws-neptune": "database",
+    "aws-elasticache": "database",
+    "aws-keyspaces": "database",
+    "aws-athena": "database",
+    "aws-sqs": "queue",
+    "aws-kinesis": "queue",
+    "aws-mq": "queue",
+    "aws-msk": "queue",
+    "aws-sns": "send",
+    "aws-eventbridge": "send",
+    "aws-ses": "send",
+    "aws-secrets-manager": "key",
+    "aws-kms": "key",
+    "aws-iam": "key",
+    "aws-cognito": "key",
+    "aws-systems-manager": "key",
+    "aws-certificate-manager": "key",
+    "aws-shield": "key",
+    "aws-waf": "key",
+    "aws-lambda": "function",
+    "aws-step-functions": "flow",
+    "aws-glue": "flow",
+    "aws-batch": "flow",
+    "aws-ecs": "flow",
+    "aws-eks": "flow",
+    "aws-codebuild": "flow",
+    "aws-codepipeline": "flow",
+    "aws-codedeploy": "flow",
+    "aws-appflow": "flow",
+    "aws-cloudformation": "flow",
+    "aws-api-gateway": "http",
+    "aws-cloudfront": "http",
+    "aws-route53": "http",
+    "aws-appsync": "http",
+    "aws-elb": "http",
+}
+
+SMALL_UNDER = 40  # pixels: a logo drawn smaller than this uses its small mark, when it has one
+
+
+def _read(path: Any) -> tuple[int, int, str] | None:
+    if not path.is_file():
+        return None
+    found = re.fullmatch(r'\s*<svg[^>]*viewBox="0 0 (\d+) (\d+)"[^>]*>(.*)</svg>\s*', path.read_text("utf-8"), re.S)
+    return (int(found.group(1)), int(found.group(2)), found.group(3)) if found else None
+
+
+@lru_cache(maxsize=None)
+def small_logo(name: str) -> tuple[int, int, str] | None:
+    """
+    A logo's small mark, from logos/small/<name>.svg: (width, height, its SVG body). None when it has none: only
+    AWS's service icons do, the others being simple enough already.
+    """
+    if not re.fullmatch(r"[a-z0-9-]+", name or ""):
+        return None
+    return _read(files(__package__).joinpath("logos", "small", f"{name}.svg"))
+
+
+def logo_for(name: str, pixels: float) -> tuple[int, int, str] | None:
+    """
+    The version of a logo for the pixels it's drawn at, as a browser picks a favicon: the small mark under
+    SMALL_UNDER, when there is one, else the full art.
+    """
+    return (small_logo(name) if pixels < SMALL_UNDER else None) or logo(name)
+
+
+@lru_cache(maxsize=None)
+def logo(name: str) -> tuple[int, int, str] | None:
+    """
+    A logo by its name ('aws-s3'), or a plugin's icon when it names one: (width, height, its SVG body), read from
+    logos/<name>.svg. None when there's no such logo.
+    """
+    if not re.fullmatch(r"[a-z0-9-]+", name or ""):
+        return None
+    return _read(files(__package__).joinpath("logos", f"{name}.svg"))
+
+
+def fills(found: tuple[int, int, str]) -> bool:
+    """
+    Whether a logo is a coloured square of its own (AWS's service icons): drawn filling its badge, not on a tile,
+    so it gets every pixel there is. Their fine lines blur together any smaller on a 1x screen.
+    """
+    width, height, body = found
+    return width == height and f'd="M0 0h{width}v{height}H0z"' in body[:600]
+
+
+def logo_names() -> set[str]:
+    """
+    Every logo the graph and the docs' figures draw: what scripts/logos.py keeps.
+    """
+    return (
+        set(AWS_LOGOS.values())
+        | set(SERVICE_LOGOS.values())
+        | set(DEPLOY_LOGOS.values())
+        | set(PLATFORM_LOGOS.values())
+        | set(LIBRARY_LOGOS.values())
+        | set(FRAMEWORK_LOGOS.values())
+    )