ynab-api-cli 0.1.0__py3-none-any.whl

ynab_api_cli/contract.py

@@ -0,0 +1,197 @@
+"""Load the reviewed OpenAPI contract and validate runtime JSON."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from importlib.resources import files
+
+import yaml
+from jsonschema import Draft202012Validator, FormatChecker
+
+from ynab_api_cli.exceptions import AppError
+from ynab_api_cli.types import JsonCodec, JsonValue, RequestValues
+
+
+@dataclass(frozen=True, slots=True)
+class Operation:
+    """Reviewed operation identity and its wire contract."""
+
+    identifier: str
+    alias: str
+    group: str
+    method: str
+    path: str
+    definition: dict[str, JsonValue]
+
+    @property
+    def write(self) -> bool:
+        """Classify mutations by the HTTP method."""
+        return self.method not in {"GET", "HEAD", "OPTIONS"}
+
+
+class Contract:
+    """Single source for operation metadata and JSON Schema validation."""
+
+    def __init__(self, document: dict[str, JsonValue] | None = None) -> None:
+        resource = files("ynab_api_cli.resources")
+        loaded = (
+            JsonCodec.encode(
+                yaml.safe_load(
+                    resource.joinpath("openapi.yaml").read_text(encoding="utf-8")
+                )
+            )
+            if document is None
+            else document
+        )
+        self.document = self.object(loaded)
+        self.normalized_components = self.normalize(self.document["components"])
+        self.version = str(self.object(self.document["info"])["version"])
+        self.operations = self.inventory()
+        self.catalog = self.object(
+            JsonCodec.loads(
+                resource.joinpath("catalog.json").read_text(encoding="utf-8")
+            )
+        )
+
+    @staticmethod
+    def object(value: JsonValue) -> dict[str, JsonValue]:
+        """Require a JSON object without leaking its contents in errors."""
+        if not isinstance(value, dict):
+            raise AppError("Expected a JSON object.")
+        return value
+
+    @staticmethod
+    def snake(value: str) -> str:
+        """Convert a contract operation ID into a Python-compatible name."""
+        return re.sub(r"(?<!^)(?=[A-Z])", "_", value).lower()
+
+    def inventory(self) -> dict[str, Operation]:
+        """Enumerate HTTP operations directly from the specification."""
+        result: dict[str, Operation] = {}
+        for path, raw in self.object(self.document["paths"]).items():
+            for method, entry in self.object(raw).items():
+                if method not in {
+                    "get",
+                    "post",
+                    "put",
+                    "patch",
+                    "delete",
+                    "head",
+                    "options",
+                }:
+                    continue
+                definition = self.object(entry)
+                identifier = str(definition["operationId"])
+                tags = definition["tags"]
+                if not isinstance(tags, list) or not tags:
+                    raise AppError("Operation has no resource tag.")
+                result[identifier] = Operation(
+                    identifier,
+                    self.snake(identifier),
+                    str(tags[0]).lower().replace(" ", "-"),
+                    method.upper(),
+                    path,
+                    definition,
+                )
+        return result
+
+    def get(self, name: str) -> Operation:
+        """Resolve only operations explicitly admitted by the reviewed catalog."""
+        for operation in self.operations.values():
+            if (
+                name in {operation.identifier, operation.alias}
+                and operation.identifier in self.catalog
+            ):
+                return operation
+        raise AppError("Unknown or unreviewed operation; run discover.")
+
+    def parameters(self, operation: Operation) -> list[dict[str, JsonValue]]:
+        """Return declared endpoint parameters."""
+        values = operation.definition.get("parameters", [])
+        if not isinstance(values, list):
+            raise AppError("Invalid parameter definition.")
+        return [self.object(item) for item in values]
+
+    def validate(
+        self, schema: dict[str, JsonValue], value: JsonValue, label: str
+    ) -> None:
+        """Validate constraints and formats without quoting personal values."""
+        complete = self.object(self.normalize(schema))
+        complete["components"] = self.normalized_components
+        errors = list(
+            Draft202012Validator(complete, format_checker=FormatChecker()).iter_errors(
+                value
+            )
+        )
+        if errors:
+            location = "/".join(str(part) for part in errors[0].absolute_path) or "root"
+            raise AppError(
+                f"Invalid {label} at {location}: {errors[0].validator} constraint."
+            )
+
+    @classmethod
+    def normalize(cls, value: JsonValue) -> JsonValue:
+        """Honor legacy nullable annotations in the published 3.1 document."""
+        if isinstance(value, list):
+            return [cls.normalize(item) for item in value]
+        if isinstance(value, dict):
+            result: dict[str, JsonValue] = {
+                key: cls.normalize(item)
+                for key, item in value.items()
+                if key != "nullable"
+            }
+            if value.get("nullable") is True:
+                return {"anyOf": [result, {"type": "null"}]}
+            return result
+        return value
+
+    def validate_request(self, operation: Operation, request: RequestValues) -> None:
+        """Validate path, query, body presence, and documented semantic rules."""
+        values = request.json()
+        for section in ("path", "query"):
+            parameters = [
+                item for item in self.parameters(operation) if item["in"] == section
+            ]
+            schema: dict[str, JsonValue] = {
+                "type": "object",
+                "properties": {
+                    str(item["name"]): item["schema"] for item in parameters
+                },
+                "required": [
+                    str(item["name"])
+                    for item in parameters
+                    if item.get("required") is True
+                ],
+                "additionalProperties": False,
+            }
+            self.validate(schema, values[section], section)
+        body = operation.definition.get("requestBody")
+        if body is None:
+            if "body" in values:
+                raise AppError("This operation does not accept a request body.")
+            return
+        definition = self.object(body)
+        if "body" not in values:
+            if definition.get("required") is True:
+                raise AppError("This operation requires a request body.")
+            return
+        content = self.object(self.object(definition["content"])["application/json"])
+        self.validate(self.object(content["schema"]), values["body"], "body")
+        if operation.identifier == "createTransaction":
+            payload = self.object(values["body"])
+            if ("transaction" in payload) == ("transactions" in payload):
+                raise AppError("Provide exactly one of transaction or transactions.")
+
+    def validate_response(
+        self, operation: Operation, status: int, raw: JsonValue
+    ) -> None:
+        """Validate the actual success response against its declared schema."""
+        response = self.object(operation.definition["responses"]).get(str(status))
+        if response is None:
+            raise AppError(
+                f"Unexpected HTTP {status}; bundled API contract {self.version}."
+            )
+        content = self.object(self.object(response)["content"])
+        schema = self.object(self.object(content["application/json"])["schema"])
+        self.validate(schema, raw, "response")

ynab_api_cli/contract_testing.py

@@ -0,0 +1,141 @@
+"""Enumerate contract features and synthesize supplemental schema probes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ynab_api_cli.contract import Contract
+from ynab_api_cli.types import JsonValue
+
+
+@dataclass(frozen=True, slots=True)
+class Probe:
+    """One schema feature and a candidate value to validate independently."""
+
+    identifier: str
+    schema: dict[str, JsonValue]
+    value: JsonValue
+
+
+class SchemaCases:
+    """Exercise each reachable schema node in addition to handwritten wire cases."""
+
+    UUID = "00000000-0000-4000-8000-000000000001"
+
+    def __init__(self, contract: Contract) -> None:
+        self.contract = contract
+        self.schemas = contract.object(
+            contract.object(contract.document["components"])["schemas"]
+        )
+
+    def sample(self, schema: dict[str, JsonValue]) -> JsonValue:
+        """Construct a positive witness for the schema's declared structure."""
+        reference = schema.get("$ref")
+        if isinstance(reference, str):
+            return self.sample(
+                self.contract.object(self.schemas[reference.rsplit("/", 1)[-1]])
+            )
+        enum = schema.get("enum")
+        if isinstance(enum, list):
+            return enum[0]
+        for key in ("allOf", "anyOf", "oneOf"):
+            branches = schema.get(key)
+            if isinstance(branches, list):
+                values = [self.sample(self.contract.object(item)) for item in branches]
+                if key != "allOf":
+                    return values[0]
+                if not all(isinstance(item, dict) for item in values):
+                    return values[0]
+                merged: dict[str, JsonValue] = {}
+                for item in values:
+                    merged.update(self.contract.object(item))
+                return merged
+        return self.primitive(schema)
+
+    def primitive(self, schema: dict[str, JsonValue]) -> JsonValue:
+        """Construct a witness for a primitive, array, or object schema."""
+        kind = schema.get("type")
+        if isinstance(kind, list):
+            kind = next(item for item in kind if item != "null")
+        if kind == "object" or "properties" in schema or "required" in schema:
+            result = {
+                key: self.sample(self.contract.object(value))
+                for key, value in self.contract.object(
+                    schema.get("properties", {})
+                ).items()
+            }
+            extras = schema.get("additionalProperties")
+            if isinstance(extras, dict):
+                result["2026-01-01"] = self.sample(extras)
+            return result
+        if kind == "array":
+            return [self.sample(self.contract.object(schema["items"]))]
+        if kind in {"integer", "number"}:
+            return schema.get("minimum", 0)
+        if kind == "boolean":
+            return False
+        if kind == "null":
+            return None
+        return self.string(schema)
+
+    @staticmethod
+    def string(schema: dict[str, JsonValue]) -> str:
+        """Produce format-aware deterministic string samples."""
+        values = {
+            "uuid": SchemaCases.UUID,
+            "date": "2026-01-01",
+            "date-time": "2026-01-01T00:00:00Z",
+        }
+        result = values.get(str(schema.get("format")), "fixture")
+        minimum = schema.get("minLength", 0)
+        maximum = schema.get("maxLength", len(result))
+        if isinstance(minimum, int) and isinstance(maximum, int):
+            return result.ljust(minimum, "x")[:maximum]
+        return result
+
+    def nodes(
+        self, value: JsonValue, pointer: str
+    ) -> list[tuple[str, dict[str, JsonValue]]]:
+        """Walk every schema node with stable JSON-pointer identifiers."""
+        result: list[tuple[str, dict[str, JsonValue]]] = []
+        if isinstance(value, dict):
+            if (
+                isinstance(value.get("type"), (str, list))
+                or isinstance(value.get("$ref"), str)
+                or any(
+                    isinstance(value.get(key), list)
+                    for key in ("allOf", "anyOf", "oneOf", "enum")
+                )
+            ):
+                result.append((pointer, value))
+            for key, item in value.items():
+                result.extend(self.nodes(item, pointer + "/" + key))
+        elif isinstance(value, list):
+            for index, item in enumerate(value):
+                result.extend(self.nodes(item, pointer + "/" + str(index)))
+        return result
+
+    def probes(self) -> list[Probe]:
+        """Build positive probes for each node, enum member, and nullable branch."""
+        result: list[Probe] = []
+        roots: dict[str, JsonValue] = {"components": self.schemas}
+        for operation in self.contract.operations.values():
+            roots[operation.identifier] = operation.definition
+        for pointer, schema in self.nodes(roots, ""):
+            result.append(Probe(pointer, schema, self.sample(schema)))
+            enum = schema.get("enum")
+            if isinstance(enum, list):
+                result.extend(
+                    Probe(pointer + "/enum/" + str(index), schema, item)
+                    for index, item in enumerate(enum)
+                )
+            kind = schema.get("type")
+            if schema.get("nullable") is True:
+                result.append(Probe(pointer + "/legacy-nullable", schema, None))
+            if (
+                isinstance(kind, list)
+                and "null" in kind
+                and (not isinstance(enum, list) or None in enum)
+            ):
+                result.append(Probe(pointer + "/nullable", schema, None))
+        return result

ynab_api_cli/development.py

@@ -0,0 +1,269 @@
+"""Deterministic code generation and release verification commands."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import tomllib
+from datetime import UTC, datetime
+from importlib.metadata import version
+from pathlib import Path
+
+import yaml
+
+
+class Development:
+    """Run the pinned generator with reviewed templates and transformations."""
+
+    def __init__(self, root: Path | None = None) -> None:
+        self.root = root if root is not None else Path(__file__).resolve().parents[2]
+
+    @classmethod
+    def main(cls) -> None:
+        """Dispatch development tasks through the project entry point."""
+        parser = argparse.ArgumentParser()
+        parser.add_argument(
+            "command", choices=["generate", "codegen-check", "initialize"]
+        )
+        args = parser.parse_args()
+        if args.command == "initialize":
+            cls().initialize()
+            return
+        cls().generate(check=args.command == "codegen-check")
+
+    def initialize(self) -> None:
+        """Record the initial reviewed baseline exactly once."""
+        resource = self.root / "src/ynab_api_cli/resources"
+        path = resource / "openapi.yaml"
+        spec = yaml.safe_load(path.read_text(encoding="utf-8"))
+        catalog = {
+            op["operationId"]: {"method": verb.upper(), "path": route}
+            for route, item in spec["paths"].items()
+            for verb, op in item.items()
+            if verb in {"get", "post", "put", "patch", "delete"}
+        }
+        provenance = {
+            "source_url": "https://api.ynab.com/papi/open_api_spec.yaml",
+            "retrieved_at": datetime.now(UTC).isoformat(),
+            "spec_sha256": hashlib.sha256(path.read_bytes()).hexdigest(),
+            "api_version": spec["info"]["version"],
+            "generator": "openapi-python-client",
+            "generator_version": version("openapi-python-client"),
+            "operation_count": len(catalog),
+        }
+        for name, value in (("catalog.json", catalog), ("provenance.json", provenance)):
+            with (resource / name).open("x", encoding="utf-8") as stream:
+                stream.write(json.dumps(value, indent=2) + "\n")
+
+    def generate(self, *, check: bool) -> None:
+        """Generate into a temporary directory and compare or install source."""
+        root = self.root
+        config = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))[
+            "tool"
+        ]["ynab_api_cli"]["codegen"]
+        with tempfile.TemporaryDirectory() as temporary:
+            workspace = Path(temporary)
+            config_path = workspace / "config.json"
+            config_path.write_text(json.dumps(config), encoding="utf-8")
+            output = workspace / "generated"
+            result = subprocess.run(  # noqa: S603 - fixed installed module and local paths, no shell.
+                [
+                    sys.executable,
+                    "-m",
+                    "openapi_python_client",
+                    "generate",
+                    "--path",
+                    str(root / "src/ynab_api_cli/resources/openapi.yaml"),
+                    "--meta",
+                    "none",
+                    "--config",
+                    str(config_path),
+                    "--custom-template-path",
+                    str(root / "templates"),
+                    "--output-path",
+                    str(output),
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if (
+                result.returncode
+                or "warning" in (result.stdout + result.stderr).lower()
+            ):
+                sys.stderr.write(result.stdout + result.stderr)
+                raise SystemExit(1)
+            for name in ("client.py", "types.py", "errors.py"):
+                (output / name).unlink()
+            for path in output.rglob("*.py"):
+                self.transform(path, output)
+            self.bindings(output)
+            subprocess.run(  # noqa: S603 - fixed installed ruff module, no shell.
+                [
+                    sys.executable,
+                    "-m",
+                    "ruff",
+                    "format",
+                    str(output),
+                    "--config",
+                    str(root / "pyproject.toml"),
+                ],
+                check=True,
+            )
+            subprocess.run(  # noqa: S603 - fixed installed ruff module, no shell.
+                [
+                    sys.executable,
+                    "-m",
+                    "ruff",
+                    "check",
+                    str(output),
+                    "--fix",
+                    "--config",
+                    str(root / "pyproject.toml"),
+                ],
+                check=True,
+            )
+            subprocess.run(  # noqa: S603 - fixed installed ruff module, no shell.
+                [
+                    sys.executable,
+                    "-m",
+                    "ruff",
+                    "format",
+                    str(output),
+                    "--config",
+                    str(root / "pyproject.toml"),
+                ],
+                check=True,
+            )
+            destination = (root / "src/ynab_api_cli/generated").resolve()
+            if not destination.is_relative_to((root / "src/ynab_api_cli").resolve()):
+                raise SystemExit("Generated destination escapes the project.")
+            if check:
+                if self.fingerprints(output) != self.fingerprints(destination):
+                    raise SystemExit(
+                        "Generated source differs; run poe generate and review."
+                    )
+            else:
+                if destination.exists():
+                    shutil.rmtree(destination)
+                shutil.copytree(
+                    output, destination, ignore=shutil.ignore_patterns(".ruff_cache")
+                )
+
+    @staticmethod
+    def transform(path: Path, root: Path) -> None:
+        """Use absolute package imports and complete generated file headers."""
+        text = path.read_text(encoding="utf-8")
+        if path.name == "__init__.py":
+            if path.parent == root:
+                text = '"""Generated REST client declarations."""\n'
+            elif path.parent.name != "models":
+                text = '"""Generated endpoint declarations."""\n'
+            else:
+                text = text.replace(
+                    '""" Contains all the data models used in inputs/outputs """',
+                    '"""Generated request and response models."""',
+                )
+        package = ["ynab_api_cli", "generated", *path.relative_to(root).parts[:-1]]
+        for match in list(re.finditer(r"from (\.+)([\w.]*) import", text)):
+            prefix = ".".join(package[: len(package) - len(match[1]) + 1])
+            suffix = "." + match[2] if match[2] else ""
+            text = text.replace(match[0], f"from {prefix}{suffix} import")
+        text = re.sub(r"from ynab_api_cli.generated.types import .*\n", "", text)
+        text = text.replace("from enum import Enum", "from enum import StrEnum")
+        text = re.sub(
+            r"class (\w+)\(str, Enum\):",
+            r'class \1(StrEnum):\n    """Generated contract enumeration."""',
+            text,
+        )
+        text = re.sub(
+            r"    def __str__\(self\) -> str:\n        return str\(self.value\)\n",
+            "",
+            text,
+        )
+        if not text.startswith('"""'):
+            text = (
+                '"""Generated declarations; regenerate rather than editing."""\n' + text
+            )
+        if "from __future__ import annotations" not in text:
+            closing = text.index('"""', 3) + 3
+            text = (
+                text[:closing]
+                + "\nfrom __future__ import annotations\n"
+                + text[closing:]
+            )
+        if path.name == "__init__.py" and path.parent.name == "models":
+            text += '''
+from pydantic import BaseModel
+
+class ModelRegistry:
+    """Resolve forward references after all models have loaded."""
+    @classmethod
+    def rebuild(cls) -> None:
+        """Resolve generated models against the complete namespace."""
+        namespace = globals()
+        for value in tuple(namespace.values()):
+            if (
+                isinstance(value, type) and value is not BaseModel
+                and issubclass(value, BaseModel)
+            ):
+                value.model_rebuild(_types_namespace=namespace)
+
+ModelRegistry.rebuild()
+'''
+        path.write_text(text, encoding="utf-8")
+
+    @staticmethod
+    def fingerprints(root: Path) -> dict[str, str]:
+        """Hash generated Python files independently of cache artifacts."""
+        return {
+            str(path.relative_to(root)): hashlib.sha256(path.read_bytes()).hexdigest()
+            for path in root.rglob("*.py")
+        }
+
+    @staticmethod
+    def bindings(root: Path) -> None:
+        """Generate static class bindings without reflective endpoint invocation."""
+        imports: list[str] = []
+        entries: list[str] = []
+        for index, path in enumerate(sorted((root / "api").glob("*/*.py"))):
+            if path.name == "__init__.py":
+                continue
+            module = ".".join(path.parent.relative_to(root).parts)
+            alias = f"operation{index}"
+            imports.append(
+                f"from ynab_api_cli.generated.{module} import {path.stem} as {alias}"
+            )
+            entries.append(f'        "{path.stem}": {alias}.Endpoint.dispatch,')
+        text = "\n".join(
+            [
+                '"""Generated static endpoint dispatch; regenerate to change."""',
+                "from __future__ import annotations",
+                "from collections.abc import Callable, Mapping",
+                "from types import MappingProxyType",
+                "from typing import ClassVar",
+                "from ynab_api_cli.transport import Transport",
+                "from ynab_api_cli.types import RequestValues, Response",
+                *imports,
+                "",
+                "class Bindings:",
+                '    """Statically reference every generated typed operation."""',
+                "    operations: ClassVar[Mapping[str,",
+                "        Callable[[Transport, RequestValues], Response[object]]",
+                "    ]] = MappingProxyType({",
+                *entries,
+                "    })",
+                "",
+            ]
+        )
+        (root / "bindings.py").write_text(text, encoding="utf-8")
+
+
+if __name__ == "__main__":
+    Development.main()