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

code_node/deploys/sam.py

@@ -0,0 +1,371 @@
+"""
+AWS SAM and CloudFormation templates: each AWS::Serverless::Function (and AWS::Lambda::Function) on a Python
+runtime, with Globals applied, its environment variables, and what its role allows: SAM's policy templates
+(DynamoDBCrudPolicy), the managed policies it knows, inline statements, a role in the same template, and the
+permissions its event sources add.
+"""
+
+from __future__ import annotations
+
+import json
+import posixpath
+from typing import Any
+
+from ..analysis.model import Deployment
+from . import MANAGED_POLICIES, Deploy, allowed, as_list, line_of, load_yaml, resolve_handler, statement_actions
+
+_D = "dynamodb:"
+
+POLICY_TEMPLATES: dict[str, set[str]] = {  # SAM's policy templates -> the actions they allow
+    "DynamoDBCrudPolicy": {
+        _D + a
+        for a in (
+            "GetItem",
+            "DeleteItem",
+            "PutItem",
+            "Scan",
+            "Query",
+            "UpdateItem",
+            "BatchWriteItem",
+            "BatchGetItem",
+            "DescribeTable",
+            "ConditionCheckItem",
+        )
+    },
+    "DynamoDBReadPolicy": {_D + a for a in ("GetItem", "Scan", "Query", "BatchGetItem", "DescribeTable")},
+    "DynamoDBWritePolicy": {_D + a for a in ("PutItem", "UpdateItem", "BatchWriteItem")},
+    "DynamoDBReconfigurePolicy": {_D + "DescribeTable", _D + "UpdateTable"},
+    "DynamoDBStreamReadPolicy": {_D + a for a in ("DescribeStream", "GetRecords", "GetShardIterator", "ListStreams")},
+    "S3ReadPolicy": {
+        "s3:GetObject",
+        "s3:ListBucket",
+        "s3:GetBucketLocation",
+        "s3:GetObjectVersion",
+        "s3:GetLifecycleConfiguration",
+    },
+    "S3WritePolicy": {"s3:PutObject", "s3:PutObjectAcl", "s3:PutLifecycleConfiguration"},
+    "S3CrudPolicy": {
+        "s3:GetObject",
+        "s3:ListBucket",
+        "s3:GetBucketLocation",
+        "s3:GetObjectVersion",
+        "s3:PutObject",
+        "s3:PutObjectAcl",
+        "s3:GetLifecycleConfiguration",
+        "s3:PutLifecycleConfiguration",
+        "s3:DeleteObject",
+    },
+    "S3FullAccessPolicy": {
+        "s3:GetObject",
+        "s3:GetObjectAcl",
+        "s3:GetObjectVersion",
+        "s3:PutObject",
+        "s3:PutObjectAcl",
+        "s3:DeleteObject",
+        "s3:DeleteObjectTagging",
+        "s3:DeleteObjectVersionTagging",
+        "s3:GetObjectTagging",
+        "s3:GetObjectVersionTagging",
+        "s3:PutObjectTagging",
+        "s3:PutObjectVersionTagging",
+        "s3:ListBucket",
+        "s3:GetBucketLocation",
+        "s3:GetLifecycleConfiguration",
+        "s3:PutLifecycleConfiguration",
+    },
+    "SQSSendMessagePolicy": {"sqs:SendMessage*"},
+    "SQSPollerPolicy": {
+        "sqs:ChangeMessageVisibility",
+        "sqs:ChangeMessageVisibilityBatch",
+        "sqs:DeleteMessage",
+        "sqs:DeleteMessageBatch",
+        "sqs:GetQueueAttributes",
+        "sqs:ReceiveMessage",
+    },
+    "SNSPublishMessagePolicy": {"sns:Publish"},
+    "SNSCrudPolicy": {
+        "sns:ListSubscriptionsByTopic",
+        "sns:CreateTopic",
+        "sns:SetTopicAttributes",
+        "sns:Subscribe",
+        "sns:Publish",
+    },
+    "LambdaInvokePolicy": {"lambda:InvokeFunction"},
+    "StepFunctionsExecutionPolicy": {"states:StartExecution"},
+    "StepFunctionsCallbackPolicy": {"states:SendTaskSuccess", "states:SendTaskFailure", "states:SendTaskHeartbeat"},
+    "AWSSecretsManagerGetSecretValuePolicy": {"secretsmanager:GetSecretValue"},
+    "SSMParameterReadPolicy": {
+        "ssm:DescribeParameters",
+        "ssm:GetParameters",
+        "ssm:GetParameter",
+        "ssm:GetParametersByPath",
+    },
+    "SSMParameterWithSlashPrefixReadPolicy": {
+        "ssm:DescribeParameters",
+        "ssm:GetParameters",
+        "ssm:GetParameter",
+        "ssm:GetParametersByPath",
+    },
+    "KMSDecryptPolicy": {"kms:Decrypt"},
+    "KMSEncryptPolicy": {"kms:Encrypt"},
+    "EventBridgePutEventsPolicy": {"events:PutEvents"},
+    "FirehoseWritePolicy": {"firehose:PutRecord", "firehose:PutRecordBatch"},
+    "SESCrudPolicy": {
+        "ses:GetIdentityVerificationAttributes",
+        "ses:SendEmail",
+        "ses:SendRawEmail",
+        "ses:VerifyEmailIdentity",
+    },
+    "SESSendBouncePolicy": {"ses:SendBounce"},
+    "SESBulkTemplatedCrudPolicy": {
+        "ses:GetIdentityVerificationAttributes",
+        "ses:SendEmail",
+        "ses:SendRawEmail",
+        "ses:SendTemplatedEmail",
+        "ses:SendBulkTemplatedEmail",
+        "ses:VerifyEmailIdentity",
+    },
+    "CloudWatchPutMetricPolicy": {"cloudwatch:PutMetricData"},
+    "RekognitionDetectOnlyPolicy": {
+        "rekognition:DetectFaces",
+        "rekognition:DetectLabels",
+        "rekognition:DetectModerationLabels",
+        "rekognition:DetectText",
+    },
+    "TextractDetectAnalyzePolicy": {
+        "textract:DetectDocumentText",
+        "textract:StartDocumentTextDetection",
+        "textract:StartDocumentAnalysis",
+        "textract:AnalyzeDocument",
+    },
+    "TextractGetResultPolicy": {"textract:GetDocumentTextDetection", "textract:GetDocumentAnalysis"},
+    "ComprehendBasicAccessPolicy": {
+        "comprehend:BatchDetectKeyPhrases",
+        "comprehend:DetectDominantLanguage",
+        "comprehend:DetectEntities",
+        "comprehend:BatchDetectEntities",
+        "comprehend:DetectKeyPhrases",
+        "comprehend:DetectSentiment",
+        "comprehend:BatchDetectDominantLanguage",
+        "comprehend:BatchDetectSentiment",
+    },
+    "EKSDescribePolicy": {"eks:DescribeCluster", "eks:ListClusters"},
+    "EC2DescribePolicy": {"ec2:DescribeRegions", "ec2:DescribeInstances"},
+    "AMIDescribePolicy": {"ec2:DescribeImages"},
+    "CloudFormationDescribeStacksPolicy": {"cloudformation:DescribeStacks"},
+    "ElasticsearchHttpPostPolicy": {"es:ESHttpPost", "es:ESHttpPut"},
+}
+
+_EVENT_GRANTS = {  # an event source's type -> what SAM lets the function do to read it
+    "SQS": MANAGED_POLICIES["AWSLambdaSQSQueueExecutionRole"],
+    "Kinesis": MANAGED_POLICIES["AWSLambdaKinesisExecutionRole"],
+    "DynamoDB": MANAGED_POLICIES["AWSLambdaDynamoDBExecutionRole"],
+}
+
+_PYTHON_DEFAULT_TIMEOUT = 3  # seconds: CloudFormation's (and SAM's) Lambda timeout when none is set
+
+
+def _managed(name: Any) -> set[str] | None:
+    if not isinstance(name, str):
+        return None
+    return MANAGED_POLICIES.get(name.rsplit("/", 1)[-1])
+
+
+def _sam_policies(policies: Any) -> tuple[set[str] | None, list[str]]:
+    """
+    What a function's Policies allow, and how the template names each: ({'sns:Publish'}, ['SNSPublishMessagePolicy']).
+    None for the actions when one of them can't be told.
+    """
+    actions: set[str] | None = set()
+    names: list[str] = []
+    for policy in as_list(policies):
+        found: set[str] | None = None
+        if isinstance(policy, str):
+            found = _managed(policy)
+            names.append(policy.rsplit("/", 1)[-1])
+        elif isinstance(policy, dict) and ("Statement" in policy or "PolicyDocument" in policy):
+            found = statement_actions(policy.get("PolicyDocument", policy))
+            names.append("an inline statement")
+        elif isinstance(policy, dict) and len(policy) == 1:
+            template = next(iter(policy))
+            found = POLICY_TEMPLATES.get(template)
+            names.append(template)
+        if found is None:
+            actions = None
+        elif actions is not None:
+            actions |= found
+    return actions, names
+
+
+def _role_actions(role: dict[str, Any]) -> set[str] | None:
+    """
+    What an AWS::IAM::Role in the template allows, from its inline policies and the managed ones it knows.
+    """
+    props = role.get("Properties") or {}
+    actions: set[str] = set()
+    for policy in as_list(props.get("Policies")):
+        found = statement_actions((policy or {}).get("PolicyDocument")) if isinstance(policy, dict) else None
+        if found is None:
+            return None
+        actions |= found
+    for arn in as_list(props.get("ManagedPolicyArns")):
+        found = _managed(arn) if isinstance(arn, str) else None
+        if found is None:
+            return None
+        actions |= found
+    return actions
+
+
+def _logical(ref: Any) -> str | None:
+    """
+    The resource a !Ref or !GetAtt names: {'Fn::GetAtt': ['CartRole', 'Arn']} -> 'CartRole'.
+    """
+    if isinstance(ref, dict) and "Ref" in ref and isinstance(ref["Ref"], str):
+        return ref["Ref"]
+    if isinstance(ref, dict) and "Fn::GetAtt" in ref:
+        value = ref["Fn::GetAtt"]
+        return value[0] if isinstance(value, list) and value and isinstance(value[0], str) else None
+    return None
+
+
+class SamTemplate(Deploy):
+    """
+    template.yaml (or .yml, or .json): SAM and plain CloudFormation.
+    """
+
+    name = "sam"
+    title = "AWS SAM"
+    files = ("template.yaml", "template.yml", "template.json")
+
+    def deployments(self, files: dict[str, str], code: set[str]) -> list[Deployment]:
+        found: list[Deployment] = []
+        for path, text in files.items():
+            data = json.loads(text) if path.endswith(".json") else load_yaml(text)
+            if not isinstance(data, dict) or not isinstance(data.get("Resources"), dict):
+                continue
+            found += self._functions(path, text, data, code)
+        return found
+
+    def _functions(self, path: str, text: str, data: dict[str, Any], code: set[str]) -> list[Deployment]:
+        resources: dict[str, Any] = data["Resources"]
+        base = posixpath.dirname(path)
+        defaults = (data.get("Globals") or {}).get("Function") or {}
+        connected = any(
+            isinstance(r, dict) and r.get("Type") == "AWS::Serverless::Connector" for r in resources.values()
+        )
+        found = []
+        for logical_id, resource in resources.items():
+            if not isinstance(resource, dict):
+                continue
+            kind = resource.get("Type")
+            props = resource.get("Properties") or {}
+            if (
+                kind not in ("AWS::Serverless::Function", "AWS::Lambda::Function")
+                or props.get("PackageType") == "Image"
+            ):
+                continue
+            merged = {**defaults, **props} if kind == "AWS::Serverless::Function" else dict(props)
+            runtime = merged.get("Runtime")
+            if isinstance(runtime, str) and not runtime.startswith("python"):
+                continue
+            code_dir = merged.get("CodeUri") if kind == "AWS::Serverless::Function" else merged.get("Code")
+            where = resolve_handler(
+                base, code_dir if isinstance(code_dir, str) else "", merged.get("Handler", ""), code
+            )
+            if where is None:
+                continue
+            env_names, env_error = set(), None
+            for source in ((defaults if kind == "AWS::Serverless::Function" else {}), props):
+                variables = ((source.get("Environment") or {}).get("Variables")) if isinstance(source, dict) else None
+                if isinstance(variables, dict):
+                    env_names |= {str(name) for name in variables}
+                elif variables is not None:
+                    env_error = "its Variables aren't written out"
+            actions, names = self._permissions(logical_id, props, kind, resources)
+            if connected:  # a Connector grants what it joins, which this doesn't read
+                actions = None
+            layers = [str(_logical(layer) or layer) for layer in as_list(merged.get("Layers"))]
+            timeout = merged.get("Timeout", _PYTHON_DEFAULT_TIMEOUT)
+            memory = merged.get("MemorySize", 128)
+            found.append(
+                Deployment(
+                    logical_id,
+                    path,
+                    self.name,
+                    where[0],
+                    where[1],
+                    "lambda",
+                    line_of(text, logical_id),
+                    runtime if isinstance(runtime, str) else None,
+                    timeout if isinstance(timeout, int) else None,
+                    memory if isinstance(memory, int) else None,
+                    env_names,
+                    env_error,
+                    layers,
+                    actions,
+                    names,
+                )
+            )
+        return found
+
+    def _permissions(
+        self, logical_id: str, props: dict[str, Any], kind: str, resources: dict[str, Any]
+    ) -> tuple[set[str] | None, list[str]]:
+        """
+        What a function's role allows: SAM's role from its Policies and event sources, or a role in the template,
+        plus any AWS::IAM::Policy attached to that role. None for the actions when it can't be told.
+        """
+        role_id = None
+        names: list[str] = []
+        if "Role" in props:
+            role_id = _logical(props["Role"])
+            role = resources.get(role_id) if role_id else None
+            if not isinstance(role, dict) or role.get("Type") != "AWS::IAM::Role":
+                return None, []
+            actions = _role_actions(role)
+            names.append(role_id or "")
+        elif kind == "AWS::Serverless::Function":
+            actions, names = _sam_policies(props.get("Policies"))
+            role_id = f"{logical_id}Role"
+            if actions is not None:
+                actions |= MANAGED_POLICIES["AWSLambdaBasicExecutionRole"]
+                for event in (props.get("Events") or {}).values():
+                    if isinstance(event, dict):
+                        actions |= _EVENT_GRANTS.get(event.get("Type", ""), set())
+        else:
+            return None, []
+        for resource in resources.values():
+            if not isinstance(resource, dict) or resource.get("Type") not in (
+                "AWS::IAM::Policy",
+                "AWS::IAM::ManagedPolicy",
+            ):
+                continue
+            policy = resource.get("Properties") or {}
+            if any(_logical(role) == role_id for role in as_list(policy.get("Roles"))):
+                more = statement_actions(policy.get("PolicyDocument"))
+                actions = None if more is None or actions is None else actions | more
+        return actions, names
+
+    def grant(self, deployment: Deployment, actions: list[str]) -> str:
+        """
+        The smallest SAM policy template for each service's missing actions ('add DynamoDBWritePolicy and
+        SNSPublishMessagePolicy'), and a statement for what none covers.
+        """
+        by_service: dict[str, list[str]] = {}
+        for action in actions:
+            by_service.setdefault(action.split(":")[0], []).append(action)
+        templates, rest = [], []
+        for wanted in by_service.values():
+            fits = [
+                (name, granted)
+                for name, granted in POLICY_TEMPLATES.items()
+                if all(allowed(action, granted) for action in wanted)
+            ]
+            if fits:
+                templates.append(min(fits, key=lambda fit: (len(fit[1]), fit[0]))[0])
+            else:
+                rest += wanted
+        where = f"{deployment.name}'s Policies in {deployment.source}"
+        said = [" and ".join(templates)] if templates else []
+        said += [f"a statement that allows {', '.join(rest)}"] if rest else []
+        return f"add {' and '.join(said)} to {where}"

code_node/deploys/serverless.py

@@ -0,0 +1,117 @@
+"""
+The Serverless Framework's serverless.yml: each function on a Python runtime, with the provider's settings applied,
+its environment variables (names only), and what its role's statements allow.
+"""
+
+from __future__ import annotations
+
+import posixpath
+from typing import Any
+
+from ..analysis.model import Deployment
+from . import MANAGED_POLICIES, Deploy, as_list, line_of, load_yaml, resolve_handler, statement_actions
+
+_DEFAULT_TIMEOUT = 6  # seconds: the Serverless Framework's default
+
+_DEFAULT_MEMORY = 1024
+
+
+def _statements(provider: dict[str, Any]) -> tuple[Any, Any]:
+    """
+    The provider's role statements and managed policies, from v3's iam.role or v2's iamRoleStatements. ('string',
+    None) when the role is one made elsewhere (an ARN or a name).
+    """
+    iam = provider.get("iam") or {}
+    role = iam.get("role") if isinstance(iam, dict) else None
+    if isinstance(role, str):
+        return "elsewhere", None
+    if isinstance(role, dict):
+        return role.get("statements") or [], role.get("managedPolicies")
+    return provider.get("iamRoleStatements") or [], provider.get("iamManagedPolicies")
+
+
+class ServerlessFile(Deploy):
+    """
+    serverless.yml (or .yaml) with provider.name aws.
+    """
+
+    name = "serverless"
+    title = "Serverless Framework"
+    files = ("serverless.yml", "serverless.yaml")
+
+    def deployments(self, files: dict[str, str], code: set[str]) -> list[Deployment]:
+        found: list[Deployment] = []
+        for path, text in files.items():
+            data = load_yaml(text)
+            if not isinstance(data, dict) or not isinstance(data.get("provider"), dict):
+                continue
+            provider = data["provider"]
+            if provider.get("name", "aws") != "aws":
+                continue
+            functions = data.get("functions") or {}
+            if isinstance(functions, list):  # an old file: a list of {name: function}
+                functions = {k: v for item in functions if isinstance(item, dict) for k, v in item.items()}
+            if not isinstance(functions, dict):
+                continue
+            statements, managed = _statements(provider)
+            for name, function in functions.items():
+                if not isinstance(function, dict) or "image" in function:
+                    continue
+                runtime = function.get("runtime", provider.get("runtime"))
+                if isinstance(runtime, str) and not runtime.startswith("python"):
+                    continue
+                where = resolve_handler(posixpath.dirname(path), "", function.get("handler", ""), code)
+                if where is None:
+                    continue
+                env_names, env_error = set(), None
+                for source in (provider.get("environment"), function.get("environment")):
+                    if isinstance(source, dict):
+                        env_names |= {str(key) for key in source}
+                    elif source is not None:
+                        env_error = "its environment comes from a file or a variable"
+                actions = None
+                if statements != "elsewhere":
+                    actions = statement_actions(as_list(statements) + as_list(function.get("iamRoleStatements")))
+                    for policy in as_list(managed):
+                        granted = (
+                            MANAGED_POLICIES.get(str(policy).rsplit("/", 1)[-1]) if isinstance(policy, str) else None
+                        )
+                        actions = None if granted is None or actions is None else actions | granted
+                    if actions is not None:
+                        actions |= MANAGED_POLICIES["AWSLambdaBasicExecutionRole"]
+                        for event in as_list(function.get("events")):
+                            if isinstance(event, dict) and "sqs" in event:
+                                actions |= MANAGED_POLICIES["AWSLambdaSQSQueueExecutionRole"]
+                            if isinstance(event, dict) and "stream" in event:
+                                actions |= (
+                                    MANAGED_POLICIES["AWSLambdaDynamoDBExecutionRole"]
+                                    | MANAGED_POLICIES["AWSLambdaKinesisExecutionRole"]
+                                )
+                timeout = function.get("timeout", provider.get("timeout", _DEFAULT_TIMEOUT))
+                memory = function.get("memorySize", provider.get("memorySize", _DEFAULT_MEMORY))
+                layers = [str(layer) for layer in as_list(function.get("layers", provider.get("layers")))]
+                found.append(
+                    Deployment(
+                        str(name),
+                        path,
+                        self.name,
+                        where[0],
+                        where[1],
+                        "lambda",
+                        line_of(text, str(name), 2),
+                        runtime if isinstance(runtime, str) else None,
+                        timeout if isinstance(timeout, int) else None,
+                        memory if isinstance(memory, int) else None,
+                        env_names,
+                        env_error,
+                        layers,
+                        actions,
+                        ["provider.iam.role.statements"],
+                    )
+                )
+        return found
+
+    def grant(self, deployment: Deployment, actions: list[str]) -> str:
+        return (
+            f"add a statement that allows {', '.join(actions)} to provider.iam.role.statements in {deployment.source}"
+        )

code_node/kit/__init__.py

@@ -0,0 +1,4 @@
+"""
+Shared rendering helpers, copied from aws-analyzer's _kit: the report blocks, their HTML and text drawings,
+formatting and code highlighting.
+"""

code_node/kit/blocks.py

@@ -0,0 +1,184 @@
+"""
+The blocks a report is made of, and what draws each kind of block.
+
+A View command builds a list of blocks (a _Title, _Cards, a _Table, ...) and hands it to the renderer, which draws
+each block by what's registered for its type: its HTML, or its lines of text. These are the blocks every service
+uses (render.py draws them); a service's own blocks (_Passage, _Steps, _Wiring, ...) are defined in its module and
+register how they're drawn with @_draws when it's imported.
+
+The registries @_draws fills: _HTML (block type -> its HTML), _TEXT (block type -> its lines in text mode) and
+_CELLS (table cell type -> its HTML, given the cell's text).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class _Title:
+    """
+    The report's title, with a line under it (sub).
+    """
+
+    text: str
+    sub: str = ""
+
+
+@dataclass
+class _Cards:
+    """
+    The few numbers that matter, as cards. Each item is (label, value), or (label, value, tone) with tone 'warn',
+    'bad' or 'ok'.
+    """
+
+    items: list[tuple[str, ...]]
+
+
+@dataclass
+class _Table:
+    """
+    A table of rows under its headers.
+
+        rows        cells are text, or _Tone for a coloured status (or another type registered as a cell)
+        bars        0..1 per row, drawn as an extra column headed bar_label
+        tree        the first column holds indented tree labels
+        max_rows    None for the view's default, 0 for no cap
+        code_cols   columns holding calls to copy, shown as code
+        prose_cols  columns of sentences this tool wrote (findings): the calls in them shown as code
+        collapsed   a secondary view: folded under its title in HTML
+        path_cols   columns of keys and paths: the file name always shows, a long folder is shortened
+        sortable    in HTML a click on a column's header sorts by it (tree tables never sort)
+    """
+
+    headers: list[str]
+    rows: list[list[Any]]
+    title: str = ""
+    bars: list[float] | None = None
+    bar_label: str = "Share"
+    tree: bool = False
+    max_rows: int | None = None
+    code_cols: tuple[int, ...] = ()
+    prose_cols: tuple[int, ...] = ()
+    collapsed: bool = False
+    path_cols: tuple[int, ...] = ()
+    sortable: bool = True
+
+
+@dataclass
+class _Note:
+    """
+    A sentence on its own, at a level: 'info', 'warn' or 'ok'.
+    """
+
+    text: str
+    level: str = "info"
+
+
+@dataclass
+class _Text:
+    """
+    Text shown as it is.
+
+        wrap       prose: wrap long lines instead of scrolling sideways
+        code       a snippet to copy: in HTML one click selects all of it
+        collapsed  a secondary view (raw JSON): folded under its title in HTML
+    """
+
+    text: str
+    title: str = ""
+    wrap: bool = False
+    code: bool = False
+    collapsed: bool = False
+
+
+@dataclass
+class _Findings:
+    """
+    The (level, message) pairs from a *_findings function, and what to say (as an ok note) when there are none;
+    nothing when `empty` is blank.
+    """
+
+    items: list[tuple[str, str]]
+    empty: str = ""
+
+
+@dataclass
+class _Next:
+    """
+    The commands worth running next, as (call, what it shows), with their arguments filled in.
+    """
+
+    items: list[tuple[str, str]]
+    title: str = "Next"
+
+
+@dataclass
+class _Tone:
+    """
+    A table cell with a status colour (tone: 'warn', 'bad' or 'ok'): a pill in HTML, plain text elsewhere.
+    """
+
+    text: str
+    tone: str = "warn"
+
+    def __str__(self) -> str:
+        return self.text
+
+
+@dataclass(frozen=True)
+class _Report:
+    """
+    One report being drawn: what each block's drawing function gets besides the block.
+
+        max_rows  the view's cap on table rows; 0 for no cap
+        badge     the chip before each title (HTML), so reports from different services are easy to tell apart
+        root      the service's root class, which scopes the CSS rules
+        blocks    the whole report, for a block that needs to know what else is in it
+        rules     CSS rules the blocks need beyond the stylesheet (a table's filters and columns): a <style> after it
+        parts     what blocks share while the report is drawn (see shared)
+    """
+
+    max_rows: int
+    badge: str = ""
+    root: str = ""
+    blocks: tuple[Any, ...] = ()
+    rules: set[str] = field(default_factory=set)
+    parts: dict[Any, Any] = field(default_factory=dict)
+
+    def shared(self, key: Any, make: Callable[[], Any]) -> Any:
+        """
+        What the report's blocks share while it's drawn, made by make() the first time one asks for it: S3's PDF
+        pages share one full-size view, so its ‹ › step through every page in the report.
+        """
+        if key not in self.parts:
+            self.parts[key] = make()
+        return self.parts[key]
+
+
+_HTML: dict[type, Callable[[Any, _Report], str]] = {}
+_TEXT: dict[type, Callable[[Any, _Report], list[str]]] = {}
+_CELLS: dict[type, Callable[[Any, str], str]] = {}
+
+
+def _draws(kind: type, mode: str) -> Callable[[Callable], Callable]:
+    """
+    @_draws(_Passage, "html") makes the function under it the way a _Passage block is drawn in HTML:
+    f(block, report) -> str. "text" registers its lines in text mode, f(block, report) -> list[str], and "cell" how
+    a table cell of that type shows in HTML, f(cell, text) -> str (text mode shows str(cell)).
+    """
+    registry: dict[type, Callable] = {"html": _HTML, "text": _TEXT, "cell": _CELLS}[mode]
+
+    def register(draw: Callable) -> Callable:
+        registry[kind] = draw
+        return draw
+
+    return register
+
+
+def _drawer(registry: dict[type, Callable], value: Any) -> Callable | None:
+    """
+    What draws value: the function registered for its type, or for the closest type it's made from.
+    """
+    return next((registry[cls] for cls in type(value).__mro__ if cls in registry), None)