monosmith-plugin-sdk 0.1.0__py3-none-any.whl

monosmith_plugin_sdk/codec/method_codec_algorithm.py

@@ -0,0 +1,53 @@
+"""Encoding and decoding the params and the result of each method of the protocol."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..protocol import PROTOCOL_SCHEMA
+from .encode_by_schema_algorithm import encode_by_schema
+from .encode_json_value_algorithm import encode_json_value
+from .normalize_by_schema_algorithm import normalize_by_schema
+
+
+def _side(method: str, side: str) -> dict[str, Any] | None:
+    rows = PROTOCOL_SCHEMA["x-methods"]
+    row = rows.get(method) if isinstance(method, str) else None
+    node = None if row is None else row.get(side)
+    return node if isinstance(node, dict) else None
+
+
+def _encode(method: str, side: str, value: Any) -> str:
+    node = _side(method, side)
+    return encode_json_value(value, side) if node is None else encode_by_schema(PROTOCOL_SCHEMA, node, value, side)
+
+
+def _decode(method: str, side: str, value: Any) -> Any:
+    node = _side(method, side)
+    return value if node is None else normalize_by_schema(PROTOCOL_SCHEMA, node, value, side)
+
+
+def encode_params(method: str, params: Any) -> str:
+    """The params of a request, written as the Go SDK writes them.
+
+    A method the protocol does not know is written as plain JSON.
+    """
+    return _encode(method, "params", params)
+
+
+def encode_result(method: str, result: Any) -> str:
+    """The result of a method, written as the Go SDK writes it."""
+    return _encode(method, "result", result)
+
+
+def decode_params(method: str, params: Any) -> Any:
+    """The params of a received request, shaped as the generated types promise.
+
+    Absent params are an empty object. Raises `ParamsError` for params of the wrong shape.
+    """
+    return _decode(method, "params", {} if params is None else params)
+
+
+def decode_result(method: str, result: Any) -> Any:
+    """The result of a received response, shaped as the generated types promise."""
+    return _decode(method, "result", {} if result is None else result)

monosmith_plugin_sdk/codec/normalize_by_schema_algorithm.py

@@ -0,0 +1,114 @@
+"""Shaping a received value the way the Go SDK's decoder does."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .encode_by_schema_algorithm import describe_type
+from .params_error import ParamsError
+from .schema_lookup_algorithm import SchemaNode, base_node, is_nullable, kind_of
+
+MAX_DEPTH = 64
+
+_SCALARS = {"string": "a string", "integer": "an integer", "number": "a number", "boolean": "a boolean"}
+
+
+def _is_scalar(kind: str, value: Any) -> bool:
+    if kind == "string":
+        return isinstance(value, str)
+    if kind == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if kind == "number":
+        return isinstance(value, int | float) and not isinstance(value, bool)
+    return isinstance(value, bool)
+
+
+def normalize_by_schema(schema: SchemaNode, node: SchemaNode, value: Any, path: str, depth: int = 0) -> Any:
+    """Shape a received value so that the types the generated `TypedDict`s promise hold.
+
+    - a required member that is absent or `null` is its zero value (`[]`, `{}`, `""`, `0`,
+      `False`): the Go host writes a nil slice as `null`;
+    - an optional member that is `null` is removed;
+    - members the schema does not know stay as they are.
+
+    Raises `ParamsError` where a value has the wrong JSON type. The value is edited in place
+    and returned.
+    """
+    if depth > MAX_DEPTH:
+        raise ParamsError(f"{path} is nested too deeply")
+    if value is None:
+        zero = _zero_of(schema, node, path, depth)
+        return None if zero is _NO_ZERO else zero
+    kind = kind_of(schema, node)
+    base = base_node(schema, node)
+    if kind in _SCALARS:
+        if not _is_scalar(kind, value):
+            raise _wrong_type(path, _SCALARS[kind], value)
+        return value
+    if kind == "array":
+        if not isinstance(value, list):
+            raise _wrong_type(path, "an array", value)
+        items = base.get("items") or {}
+        return [normalize_by_schema(schema, items, item, f"{path}[{i}]", depth + 1) for i, item in enumerate(value)]
+    if kind == "map":
+        return _normalize_map(schema, base, value, path, depth)
+    if kind == "struct":
+        return _normalize_struct(schema, base, value, path, depth)
+    return value
+
+
+def _normalize_map(schema: SchemaNode, base: SchemaNode, value: Any, path: str, depth: int) -> Any:
+    if not isinstance(value, dict):
+        raise _wrong_type(path, "an object", value)
+    values = base.get("additionalProperties")
+    member_schema: SchemaNode = values if isinstance(values, dict) else {}
+    keeps_null = kind_of(schema, member_schema) == "any"
+    for name in list(value):
+        member = value[name]
+        if member is not None:
+            value[name] = normalize_by_schema(schema, member_schema, member, f"{path}.{name}", depth + 1)
+        elif not keeps_null:
+            del value[name]
+    return value
+
+
+def _normalize_struct(schema: SchemaNode, base: SchemaNode, value: Any, path: str, depth: int) -> Any:
+    if not isinstance(value, dict):
+        raise _wrong_type(path, "an object", value)
+    required = set(base.get("required") or [])
+    for name, property_schema in (base.get("properties") or {}).items():
+        member = value.get(name)
+        where = f"{path}.{name}"
+        if member is not None:
+            value[name] = normalize_by_schema(schema, property_schema, member, where, depth + 1)
+        elif name in required:
+            zero = _zero_of(schema, property_schema, where, depth + 1)
+            if zero is not _NO_ZERO:
+                value[name] = zero
+        else:
+            value.pop(name, None)
+    return value
+
+
+_NO_ZERO: Any = object()
+
+
+def _zero_of(schema: SchemaNode, node: SchemaNode, path: str, depth: int) -> Any:
+    """The value Go's decoder leaves in a member the message did not carry."""
+    if is_nullable(node):
+        return None
+    kind = kind_of(schema, node)
+    zeros: dict[str, Any] = {"string": "", "integer": 0, "number": 0, "boolean": False}
+    if kind in zeros:
+        return zeros[kind]
+    if kind == "array":
+        return []
+    if kind == "map":
+        return {}
+    if kind == "struct":
+        return normalize_by_schema(schema, node, {}, path, depth + 1)
+    return _NO_ZERO
+
+
+def _wrong_type(path: str, expected: str, value: Any) -> ParamsError:
+    return ParamsError(f"{path} must be {expected}, not {describe_type(value)}")

monosmith_plugin_sdk/codec/params_error.py

@@ -0,0 +1,10 @@
+"""The error of received params, or a received result, of the wrong shape."""
+
+from __future__ import annotations
+
+
+class ParamsError(Exception):
+    """A received message whose params (or result) do not have the shape the schema describes.
+
+    The serve loop answers it with the code `INVALID_PARAMS`.
+    """

monosmith_plugin_sdk/codec/received_message_contract.py

@@ -0,0 +1,38 @@
+"""The messages as they were read from a frame."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ReceivedRequest:
+    """A request or notification as it was received."""
+
+    id: int | None
+    """The request id; `None` for a notification, which gets no response."""
+    method: str
+    """The method name; empty when the message carried none."""
+    params: Any
+    """The params as the JSON parser returned them; `None` when absent."""
+
+
+@dataclass(frozen=True)
+class ReceivedError:
+    """The error object of a response."""
+
+    code: int
+    message: str
+
+
+@dataclass(frozen=True)
+class ReceivedResponse:
+    """A response as it was received."""
+
+    id: int | None
+    """The id of the request answered; `None` when the request could not be read."""
+    result: Any
+    """The result, when the response is not an error."""
+    error: ReceivedError | None
+    """The error, when the response is one."""

monosmith_plugin_sdk/codec/schema_lookup_algorithm.py

@@ -0,0 +1,62 @@
+"""Reading a schema node: what it holds, with `$ref` followed and `null` set aside."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+SchemaNode = dict[str, Any]
+"""A node of the JSON Schema, as the JSON parser returns it."""
+
+NodeKind = Literal["string", "integer", "number", "boolean", "array", "struct", "map", "any"]
+"""What a schema node holds, as far as the codec cares."""
+
+REF_PREFIX = "#/$defs/"
+MAX_REF_HOPS = 16
+
+
+def resolve_node(schema: SchemaNode, node: SchemaNode) -> SchemaNode:
+    """Follow `$ref` to the definition it names."""
+    current = node
+    hops = 0
+    while "$ref" in current:
+        name = str(current["$ref"])[len(REF_PREFIX) :]
+        target = schema["$defs"].get(name)
+        if target is None or hops > MAX_REF_HOPS:
+            raise ValueError(f"the schema has no definition {current['$ref']}")
+        current = target
+        hops += 1
+    return current
+
+
+def is_nullable(node: SchemaNode) -> bool:
+    """Whether `null` is a value of the node: `["integer", "null"]`, or an `anyOf` with null."""
+    kind = node.get("type")
+    if isinstance(kind, list):
+        return "null" in kind
+    return any(branch.get("type") == "null" for branch in node.get("anyOf") or [])
+
+
+def without_null(schema: SchemaNode, node: SchemaNode) -> SchemaNode:
+    """The node without its `null` alternative."""
+    kind = node.get("type")
+    if isinstance(kind, list):
+        types = [t for t in kind if t != "null"]
+        return {**node, "type": types[0] if len(types) == 1 else types}
+    branches = [branch for branch in node.get("anyOf") or [] if branch.get("type") != "null"]
+    return resolve_node(schema, branches[0]) if len(branches) == 1 else node
+
+
+def base_node(schema: SchemaNode, node: SchemaNode) -> SchemaNode:
+    """The node as the codec walks it: nullability removed, references followed."""
+    return resolve_node(schema, without_null(schema, node))
+
+
+def kind_of(schema: SchemaNode, node: SchemaNode) -> NodeKind:
+    """The kind of value a node describes, after `$ref` and null are set aside."""
+    base = base_node(schema, node)
+    kind = base.get("type")
+    if kind in ("string", "integer", "number", "boolean", "array"):
+        return kind  # type: ignore[no-any-return]
+    if kind == "object":
+        return "map" if "properties" not in base else "struct"
+    return "any"

monosmith_plugin_sdk/codec/wire_message_mapper.py

@@ -0,0 +1,90 @@
+"""The JSON-RPC 2.0 envelopes: written the way the Go SDK writes them, and read."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .encode_json_value_algorithm import encode_json_string
+from .message_parse_error import MessageParseError
+from .received_message_contract import ReceivedError, ReceivedRequest, ReceivedResponse
+
+_INT64_MIN = -(2**63)
+_INT64_MAX = 2**63 - 1
+
+
+def write_request(request_id: int, method: str, params_json: str | None) -> str:
+    """A request as the Go SDK writes it: `jsonrpc`, `id`, `method`, `params` (left out when there are none)."""
+    params = "" if params_json is None else f',"params":{params_json}'
+    return f'{{"jsonrpc":"2.0","id":{request_id},"method":{encode_json_string(method)}{params}}}'
+
+
+def write_notification(method: str, params_json: str) -> str:
+    """A notification as the Go SDK writes it: a request with no `id`, which gets no response."""
+    return f'{{"jsonrpc":"2.0","method":{encode_json_string(method)},"params":{params_json}}}'
+
+
+def write_result(request_id: int | None, result_json: str) -> str:
+    """A successful response; `id` is `None` only when the request could not be read."""
+    return f'{{"jsonrpc":"2.0","id":{_id(request_id)},"result":{result_json}}}'
+
+
+def write_failure(request_id: int | None, code: int, message: str) -> str:
+    """An error response."""
+    return (
+        f'{{"jsonrpc":"2.0","id":{_id(request_id)},"error":{{"code":{code},"message":{encode_json_string(message)}}}}}'
+    )
+
+
+def _id(request_id: int | None) -> str:
+    return "null" if request_id is None else str(request_id)
+
+
+def _reject_constant(name: str) -> Any:
+    raise ValueError(f"{name} is not JSON")
+
+
+def _parse_object(body: str) -> dict[str, Any]:
+    try:
+        value = json.loads(body, parse_constant=_reject_constant)
+    except ValueError as error:
+        raise MessageParseError(str(error)) from error
+    if not isinstance(value, dict):
+        raise MessageParseError("a message is a JSON object")
+    return value
+
+
+def _read_id(message: dict[str, Any]) -> int | None:
+    value = message.get("id")
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or not _INT64_MIN <= value <= _INT64_MAX:
+        raise MessageParseError("id must be an integer")
+    return value
+
+
+def parse_request(body: str) -> ReceivedRequest:
+    """Read a request frame. A `null` or missing id makes it a notification."""
+    message = _parse_object(body)
+    request_id = _read_id(message)
+    method = message.get("method")
+    if method is None:
+        method = ""
+    if not isinstance(method, str):
+        raise MessageParseError("method must be a string")
+    return ReceivedRequest(request_id, method, message.get("params"))
+
+
+def parse_response(body: str) -> ReceivedResponse:
+    """Read a response frame."""
+    message = _parse_object(body)
+    request_id = _read_id(message)
+    error = message.get("error")
+    if error is None:
+        return ReceivedResponse(request_id, message.get("result"), None)
+    if not isinstance(error, dict):
+        raise MessageParseError("error must be an object")
+    code, text = error.get("code"), error.get("message")
+    if isinstance(code, bool) or not isinstance(code, int) or not isinstance(text, str):
+        raise MessageParseError("error needs a numeric code and a message")
+    return ReceivedResponse(request_id, None, ReceivedError(code, text))

monosmith_plugin_sdk/concurrency/__init__.py

@@ -0,0 +1,21 @@
+"""What a declared `concurrency` means: one at a time by default, a count, or unlimited."""
+
+from .concurrency_policy import (
+    CONCURRENCY_UNLIMITED,
+    UNLIMITED_IN_FLIGHT,
+    UNLIMITED_WORKERS,
+    concurrency_limit,
+    in_flight_limit,
+    is_valid_concurrency,
+    worker_limit,
+)
+
+__all__ = [
+    "CONCURRENCY_UNLIMITED",
+    "UNLIMITED_IN_FLIGHT",
+    "UNLIMITED_WORKERS",
+    "concurrency_limit",
+    "in_flight_limit",
+    "is_valid_concurrency",
+    "worker_limit",
+]

monosmith_plugin_sdk/concurrency/concurrency_policy.py

@@ -0,0 +1,44 @@
+"""What a declared `concurrency` means."""
+
+from __future__ import annotations
+
+CONCURRENCY_UNLIMITED = -1
+"""The `concurrency` value that leaves the number of simultaneous requests to the host."""
+
+UNLIMITED_IN_FLIGHT = 32
+"""How many requests the host keeps in flight to a plugin that declared unlimited concurrency."""
+
+UNLIMITED_WORKERS = 1024
+"""The most workers a plugin that declared unlimited concurrency runs: the pool stays bounded."""
+
+
+def is_valid_concurrency(declared: int) -> bool:
+    """Whether a declared concurrency is one the protocol defines.
+
+    Absent (0), a count (1 and above) or unlimited (-1).
+    """
+    return declared >= CONCURRENCY_UNLIMITED
+
+
+def concurrency_limit(declared: int | None) -> tuple[int, bool]:
+    """Read a declared concurrency: `(limit, unlimited)`.
+
+    An absent, zero or invalid value is 1, the default of every plugin that says nothing.
+    """
+    if declared == CONCURRENCY_UNLIMITED:
+        return 0, True
+    if declared is None or isinstance(declared, bool) or declared < 1:
+        return 1, False
+    return declared, False
+
+
+def in_flight_limit(declared: int | None) -> int:
+    """How many requests the host keeps in flight to a plugin that declared `declared`."""
+    limit, unlimited = concurrency_limit(declared)
+    return UNLIMITED_IN_FLIGHT if unlimited else limit
+
+
+def worker_limit(declared: int | None) -> int:
+    """How many requests a plugin that declared `declared` works on at once (its pool size)."""
+    limit, unlimited = concurrency_limit(declared)
+    return UNLIMITED_WORKERS if unlimited else limit

monosmith_plugin_sdk/conformance/__init__.py

@@ -0,0 +1,7 @@
+"""The checks of `smith plugin check`, to run in a plugin's own tests."""
+
+from .check_generation_use_case import CONFORMANCE_STACK
+from .check_plugin_use_case import check_plugin
+from .conformance_report_model import CheckResult, ConformanceReport
+
+__all__ = ["CONFORMANCE_STACK", "CheckResult", "ConformanceReport", "check_plugin"]

monosmith_plugin_sdk/conformance/check_generation_use_case.py

@@ -0,0 +1,128 @@
+"""The checks of a plugin that generates projects."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from ..host import PluginClient
+from ..plugin_roles import effective_roles
+from ..projects import project_kind_directory
+from ..protocol import GenerateParams, Project, ProjectKind
+from .conformance_report_model import ConformanceReport
+from .find_manifests_algorithm import find_manifests
+from .go_list_mapper import go_list, go_quote
+
+CONFORMANCE_STACK = "conformance"
+"""The stack name generated projects are asked to record."""
+
+LONG = 20 * 60.0
+
+
+def _article(kind: ProjectKind) -> str:
+    return "an app" if kind == "app" else f"a {kind}"
+
+
+def check_generation(client: PluginClient, workspace: str | Path, report: ConformanceReport) -> None:
+    """Ask the plugin for one project of each kind and check the files it reports exist.
+
+    For a language plugin, also that its own `discover` returns what it made, with the kind and the
+    stack it was asked for, tasks with commands, and that the dry runs of `version/write`, `remove`,
+    `publish` and `published` answer.
+    """
+    language = "language" in effective_roles(client.info)
+    made: list[GenerateParams] = []
+    kinds: tuple[ProjectKind, ...] = ("app", "lib", "package")
+    for kind in kinds:
+        name = f"c{kind}"
+        params: GenerateParams = {
+            "kind": kind,
+            "name": name,
+            "directory": f"{project_kind_directory(kind)}/{name}",
+            "stack": CONFORMANCE_STACK,
+            "workspace": {"name": "conformance", "scope": "@conformance", "modulePrefix": "example.com/conformance"},
+        }
+        try:
+            files = client.call("generate", params, timeout=LONG)["files"]
+        except Exception as error:
+            report.add(f"generates {_article(kind)}", False, str(error))
+            continue
+        missing = [file for file in files if not Path(workspace, *file.split("/")).exists()]
+        report.add(
+            f"generates {_article(kind)}",
+            len(files) > 0 and not missing,
+            f"files reported but not written: {go_list(missing)} (of {go_list(files)})",
+        )
+        made.append(params)
+    if not language or not made:
+        return
+
+    try:
+        manifests = find_manifests(workspace, client.info.get("manifests") or [])
+        projects: list[Project] = client.call("discover", {"manifests": manifests}, timeout=LONG)["projects"]
+    except Exception as error:
+        report.add("discovers what it generated", False, str(error))
+        return
+    found = {project["root"]: project for project in projects}
+    for params in made:
+        kind = params["kind"]
+        project = found.get(params["directory"])
+        report.add(
+            f"discovers the generated {kind}",
+            project is not None,
+            f"no project at {params['directory']} among {len(projects)} discovered",
+        )
+        if project is None:
+            continue
+        report.add(
+            f"the generated {kind} keeps its kind",
+            project["kind"] == kind,
+            f"discovered as {go_quote(project['kind'])}",
+        )
+        report.add(
+            f"the generated {kind} records its stack",
+            project.get("stack") == CONFORMANCE_STACK,
+            f"discovered with stack {go_quote(project.get('stack', ''))}; "
+            "generate must record params.stack in the manifest",
+        )
+        empty = sorted(name for name, task in (project.get("tasks") or {}).items() if not task["command"])
+        report.add(
+            f"the generated {kind}'s tasks have commands", not empty, f"tasks without a command: {go_list(empty)}"
+        )
+        call = functools.partial(client.call, timeout=60.0)
+        if client.supports("version/write"):
+            _attempt(
+                report,
+                f"writes the {kind}'s version (dry run)",
+                functools.partial(call, "version/write", {"project": project, "version": "1.2.3", "dryRun": True}),
+            )
+        if client.supports("remove"):
+            _attempt(
+                report,
+                f"would remove the {kind} (dry run)",
+                functools.partial(call, "remove", {"project": project, "dryRun": True}),
+            )
+        if kind == "package" and client.supports("publish"):
+            publish = functools.partial(client.call, timeout=300.0)
+            _attempt(
+                report,
+                "publishes the package (dry run)",
+                functools.partial(publish, "publish", {"project": project, "version": "1.2.3", "dryRun": True}),
+            )
+        if kind == "package" and client.supports("published"):
+            _attempt(
+                report,
+                "says what the registry has of the package",
+                functools.partial(call, "published", {"project": project}),
+                " (an unreachable registry is a result, not an error)",
+            )
+
+
+def _attempt(report: ConformanceReport, check: str, call: Callable[[], Any], hint: str = "") -> None:
+    try:
+        call()
+        report.add(check, True, "")
+    except Exception as error:
+        report.add(check, False, f"{error}{hint}")