dryv-compiler 0.0.1__tar.gz

dryv_compiler-0.0.1/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+generated/
+# Node / editors
+node_modules/
+.vscode-test/
+.idea
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Dryv local cache and materialized resources
+.dryv/

dryv_compiler-0.0.1/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: dryv-compiler
+Version: 0.0.1
+Summary: Runnable Python authoring compiler/provider for Dryv
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: dryv-author<0.1,>=0.0.1
+Requires-Dist: packaging<26,>=24
+Description-Content-Type: text/markdown
+
+# dryv-compiler
+
+`dryv-compiler` is the Python Author compiler/provider for Dryv.
+
+It captures the typed `AuthorState` snapshot from the project's `dryv.app(...)` (in the project's own Python, via `execution/bootstrap.py`), resolves author handles to canonical JSON Pointers, and lowers the states into `dryv.ir/v1alpha1`. The engine's contract models and `validate_runtime_ir` are the final authority; the compiler never accepts IR the engine rejects.
+
+## Commands
+
+```bash
+dryv-py doctor ./dryv.py
+dryv-py compile ./dryv.py
+dryv-py stdio
+```
+
+`stdio` uses the canonical Dryv Authoring Protocol.
+
+Request example:
+
+```json
+{"type":"compile-request","session_id":"build-1","entrypoint":"./dryv.py","protocol_versions":["dryv.authoring/v1alpha1"],"runtime_ir_versions":["dryv.ir/v1alpha1"],"batch_size":64}
+```
+
+Provider messages use canonical types such as:
+
+```text
+provider-hello
+begin
+batch
+diagnostic
+end
+error
+cancelled
+```
+
+## How lowering works
+
+```text
+dryv.app(...).snapshot()        typed AuthorState (dryv_author.state)
+    ↓ mapping/index.py          identities → canonical names and pointers
+    ↓ mapping/encode.py         states → canonical JSON; query "*" expansion;
+                                projection selections → canonical projection fields
+    ↓ mapping/compile.py        DryvIR.model_validate + validate_runtime_ir
+    ↓ protocol/records.py       one record per registry entry, with author origins
+```
+
+Author states mirror canonical shapes, so lowering is structural. Registry names are group-qualified (`group.Name`). The app itself is emitted as the application named by its key.
+
+Parity: `tests/test_compiler.py` compiles `tests/fixtures/faidibiz_app.py` (a port of the TypeScript faidibiz example) and, when `bun` is available, asserts the same semantic digest as the TypeScript compiler.
+
+## Canonical naming
+
+The compiler must normalize Dryv-owned wire vocabulary regardless of Python Author implementation details:
+
+```text
+Dryv-owned object keys     -> lower_snake_case
+Dryv-owned fixed values    -> lower-kebab-case
+Authored identifiers       -> preserve exactly
+Reserved/external tokens   -> preserve governing spelling
+```
+
+Canonical examples include:
+
+```text
+session_id
+runtime_ir_version
+property-primitive
+property-generic
+provider-hello
+$ref
+```
+
+The compiler must never apply a blind recursive case converter because authored names and standards-owned values are opaque.
+
+See `.docs/reference/ir/naming.md` and `.docs/reference/ir/properties.md`.
+
+## Responsibility boundary
+
+The compiler may:
+
+- validate Author/compiler compatibility;
+- inspect and execute the Python authoring environment;
+- validate Python Author state;
+- resolve symbolic relationships;
+- classify implementation-specific declarations into canonical concepts;
+- normalize canonical key/value spelling;
+- compile to Runtime-owned IR contracts;
+- stream deterministic Authoring Protocol records;
+- preserve source/provenance diagnostics.
+
+It must not:
+
+- create a competing semantic model;
+- generate application source code;
+- select template packs;
+- choose output paths;
+- write generated project files;
+- own persisted Runtime serialization.
+
+Equivalent Python and TypeScript authored meaning must converge on equivalent canonical Runtime IR.
+
+## Development
+
+```bash
+uv sync
+uv run ruff format .
+uv run ruff check --fix .
+uv run mypy
+uv run pytest
+uv build
+```

dryv_compiler-0.0.1/README.md

@@ -0,0 +1,110 @@
+# dryv-compiler
+
+`dryv-compiler` is the Python Author compiler/provider for Dryv.
+
+It captures the typed `AuthorState` snapshot from the project's `dryv.app(...)` (in the project's own Python, via `execution/bootstrap.py`), resolves author handles to canonical JSON Pointers, and lowers the states into `dryv.ir/v1alpha1`. The engine's contract models and `validate_runtime_ir` are the final authority; the compiler never accepts IR the engine rejects.
+
+## Commands
+
+```bash
+dryv-py doctor ./dryv.py
+dryv-py compile ./dryv.py
+dryv-py stdio
+```
+
+`stdio` uses the canonical Dryv Authoring Protocol.
+
+Request example:
+
+```json
+{"type":"compile-request","session_id":"build-1","entrypoint":"./dryv.py","protocol_versions":["dryv.authoring/v1alpha1"],"runtime_ir_versions":["dryv.ir/v1alpha1"],"batch_size":64}
+```
+
+Provider messages use canonical types such as:
+
+```text
+provider-hello
+begin
+batch
+diagnostic
+end
+error
+cancelled
+```
+
+## How lowering works
+
+```text
+dryv.app(...).snapshot()        typed AuthorState (dryv_author.state)
+    ↓ mapping/index.py          identities → canonical names and pointers
+    ↓ mapping/encode.py         states → canonical JSON; query "*" expansion;
+                                projection selections → canonical projection fields
+    ↓ mapping/compile.py        DryvIR.model_validate + validate_runtime_ir
+    ↓ protocol/records.py       one record per registry entry, with author origins
+```
+
+Author states mirror canonical shapes, so lowering is structural. Registry names are group-qualified (`group.Name`). The app itself is emitted as the application named by its key.
+
+Parity: `tests/test_compiler.py` compiles `tests/fixtures/faidibiz_app.py` (a port of the TypeScript faidibiz example) and, when `bun` is available, asserts the same semantic digest as the TypeScript compiler.
+
+## Canonical naming
+
+The compiler must normalize Dryv-owned wire vocabulary regardless of Python Author implementation details:
+
+```text
+Dryv-owned object keys     -> lower_snake_case
+Dryv-owned fixed values    -> lower-kebab-case
+Authored identifiers       -> preserve exactly
+Reserved/external tokens   -> preserve governing spelling
+```
+
+Canonical examples include:
+
+```text
+session_id
+runtime_ir_version
+property-primitive
+property-generic
+provider-hello
+$ref
+```
+
+The compiler must never apply a blind recursive case converter because authored names and standards-owned values are opaque.
+
+See `.docs/reference/ir/naming.md` and `.docs/reference/ir/properties.md`.
+
+## Responsibility boundary
+
+The compiler may:
+
+- validate Author/compiler compatibility;
+- inspect and execute the Python authoring environment;
+- validate Python Author state;
+- resolve symbolic relationships;
+- classify implementation-specific declarations into canonical concepts;
+- normalize canonical key/value spelling;
+- compile to Runtime-owned IR contracts;
+- stream deterministic Authoring Protocol records;
+- preserve source/provenance diagnostics.
+
+It must not:
+
+- create a competing semantic model;
+- generate application source code;
+- select template packs;
+- choose output paths;
+- write generated project files;
+- own persisted Runtime serialization.
+
+Equivalent Python and TypeScript authored meaning must converge on equivalent canonical Runtime IR.
+
+## Development
+
+```bash
+uv sync
+uv run ruff format .
+uv run ruff check --fix .
+uv run mypy
+uv run pytest
+uv build
+```

dryv_compiler-0.0.1/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dryv-compiler"
+version = "0.0.1"
+description = "Runnable Python authoring compiler/provider for Dryv"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+dependencies = [
+    "dryv-author>=0.0.1,<0.1",
+    "packaging>=24,<26",
+]
+
+[project.scripts]
+dryv-py = "dryv_compiler.cli:main"
+
+[dependency-groups]
+dev = [
+    # The engine validates compiled IR in tests only; the published compiler doesn't need it.
+    "dryv",
+    "mypy>=1.17",
+    "pytest>=8.4",
+    "ruff>=0.12",
+]
+
+[tool.uv.sources]
+dryv-author = { path = "../author", editable = true }
+dryv = { path = "../../../../engine/python/engine", editable = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dryv_compiler"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+docstring-code-format = true
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+plugins = ["pydantic.mypy"]
+mypy_path = "../../../../engine/python/engine/src:../author/src"
+files = ["src", "tests"]
+pretty = true
+show_error_codes = true
+warn_unreachable = true
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+warn_untyped_fields = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "../author/src", "../../../../engine/python/engine/src"]
+testpaths = ["tests"]
+addopts = ["--strict-config", "--strict-markers", "-ra"]

dryv_compiler-0.0.1/src/dryv_compiler/__init__.py

@@ -0,0 +1,21 @@
+from .compatibility import AuthorCompatibilityError, validate_author_compatibility
+from .mapping import compile_app, compile_ir
+from .version import (
+    AUTHOR_COMPATIBILITY,
+    COMPILER_VERSION,
+    SUPPORTED_AUTHORING_PROTOCOLS,
+    SUPPORTED_RUNTIME_IR_VERSIONS,
+    __version__,
+)
+
+__all__ = [
+    "AUTHOR_COMPATIBILITY",
+    "COMPILER_VERSION",
+    "SUPPORTED_AUTHORING_PROTOCOLS",
+    "SUPPORTED_RUNTIME_IR_VERSIONS",
+    "AuthorCompatibilityError",
+    "__version__",
+    "compile_app",
+    "compile_ir",
+    "validate_author_compatibility",
+]

dryv_compiler-0.0.1/src/dryv_compiler/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

dryv_compiler-0.0.1/src/dryv_compiler/cli.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import argparse
+import json
+import signal
+import sys
+from collections.abc import Sequence
+from threading import Thread
+
+from .execution import inspect_python_environment
+from .protocol import (
+    AuthoringServerMessage,
+    CancellationToken,
+    CancelRequest,
+    CompileRequest,
+    ErrorMessage,
+    encode_message,
+    parse_client_message_text,
+    stream_compile,
+)
+from .version import (
+    COMPILER_VERSION,
+    SUPPORTED_AUTHORING_PROTOCOLS,
+    SUPPORTED_RUNTIME_IR_VERSIONS,
+)
+
+
+def _emit(message: AuthoringServerMessage) -> None:
+    sys.stdout.write(encode_message(message))
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+
+
+def _install_signal_cancellation(token: CancellationToken) -> None:
+    def cancel(_signum: int, _frame: object) -> None:
+        token.cancel()
+
+    signal.signal(signal.SIGINT, cancel)
+    signal.signal(signal.SIGTERM, cancel)
+
+
+def _watch_stdin_cancellation(session_id: str, token: CancellationToken) -> None:
+    for raw in sys.stdin:
+        if not raw.strip():
+            continue
+        try:
+            message = parse_client_message_text(raw)
+        except ValueError:
+            continue
+        if isinstance(message, CancelRequest) and message.session_id == session_id:
+            token.cancel()
+            return
+
+
+def _run_request(request: CompileRequest, *, watch_stdin: bool) -> int:
+    token = CancellationToken()
+    _install_signal_cancellation(token)
+    if watch_stdin:
+        Thread(
+            target=_watch_stdin_cancellation,
+            args=(request.session_id, token),
+            daemon=True,
+        ).start()
+    return 0 if stream_compile(request, _emit, cancellation=token) else 1
+
+
+def _stdio() -> int:
+    first = sys.stdin.readline()
+    if not first:
+        sys.stderr.write("dryv-py stdio expected a compile.request JSONL message\n")
+        return 2
+    try:
+        message = parse_client_message_text(first)
+    except ValueError as exc:
+        _emit(ErrorMessage(session_id="unknown", code="PROTOCOL_ERROR", message=str(exc)))
+        return 2
+    if not isinstance(message, CompileRequest):
+        _emit(
+            ErrorMessage(
+                session_id=message.session_id,
+                code="PROTOCOL_ERROR",
+                message="first stdio message must be compile.request",
+            )
+        )
+        return 2
+    return _run_request(message, watch_stdin=True)
+
+
+def _compile(
+    *,
+    entrypoint: str,
+    session_id: str,
+    batch_size: int,
+    protocol: str,
+    runtime_ir: str,
+) -> int:
+    request = CompileRequest(
+        session_id=session_id,
+        entrypoint=entrypoint,
+        protocol_versions=(protocol,),
+        runtime_ir_versions=(runtime_ir,),
+        batch_size=batch_size,
+    )
+    return _run_request(request, watch_stdin=False)
+
+
+def _doctor(entrypoint: str) -> int:
+    report = inspect_python_environment(entrypoint)
+    value: dict[str, object] = {
+        "status": report.status.value,
+        "pythonExecutable": report.python_executable,
+        "pythonVersion": report.python_version,
+        "projectRoot": report.project_root,
+        "entrypoint": report.entrypoint,
+        "virtualEnvironment": report.virtual_environment,
+        "authorVersion": report.author_version,
+    }
+    if report.message is not None:
+        value["message"] = report.message
+    sys.stdout.write(json.dumps(value, sort_keys=True, separators=(",", ":")))
+    sys.stdout.write("\n")
+    return 0 if report.status.value == "READY" else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="dryv-py")
+    parser.add_argument("--version", action="version", version=COMPILER_VERSION)
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    compile_parser = commands.add_parser("compile", help="compile one Python authoring entrypoint")
+    compile_parser.add_argument("entrypoint")
+    compile_parser.add_argument("--session-id", default="standalone")
+    compile_parser.add_argument("--batch-size", type=int, default=64)
+    compile_parser.add_argument("--protocol", default=SUPPORTED_AUTHORING_PROTOCOLS[0])
+    compile_parser.add_argument("--runtime-ir", default=SUPPORTED_RUNTIME_IR_VERSIONS[0])
+
+    commands.add_parser("stdio", help="serve one machine-readable JSONL compile session on stdio")
+    doctor_parser = commands.add_parser("doctor", help="inspect the Python authoring environment")
+    doctor_parser.add_argument("entrypoint")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    command = str(args.command)
+    if command == "compile":
+        return _compile(
+            entrypoint=str(args.entrypoint),
+            session_id=str(args.session_id),
+            batch_size=int(args.batch_size),
+            protocol=str(args.protocol),
+            runtime_ir=str(args.runtime_ir),
+        )
+    if command == "stdio":
+        return _stdio()
+    if command == "doctor":
+        return _doctor(str(args.entrypoint))
+    parser.error(f"unsupported command: {command}")

dryv_compiler-0.0.1/src/dryv_compiler/compatibility.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from dryv_author import AUTHOR_REPRESENTATION_VERSION
+from dryv_author import __version__ as author_version
+from packaging.specifiers import SpecifierSet
+from packaging.version import InvalidVersion, Version
+
+from .version import AUTHOR_COMPATIBILITY, AUTHOR_REPRESENTATION
+
+
+class AuthorCompatibilityError(RuntimeError):
+    """Raised when an author SDK cannot be consumed by this compiler."""
+
+
+@dataclass(frozen=True, slots=True)
+class AuthorCompatibility:
+    author_version: str
+    supported_versions: str
+    representation: str
+
+
+def current_author_compatibility() -> AuthorCompatibility:
+    return AuthorCompatibility(
+        author_version=author_version,
+        supported_versions=AUTHOR_COMPATIBILITY,
+        representation=AUTHOR_REPRESENTATION_VERSION,
+    )
+
+
+def validate_author_details(author_version_value: str, representation: str) -> AuthorCompatibility:
+    compatibility = AuthorCompatibility(
+        author_version=author_version_value,
+        supported_versions=AUTHOR_COMPATIBILITY,
+        representation=representation,
+    )
+    try:
+        parsed = Version(compatibility.author_version)
+    except InvalidVersion as exc:
+        raise AuthorCompatibilityError(
+            f"installed dryv-author version {compatibility.author_version!r} is invalid"
+        ) from exc
+
+    if parsed not in SpecifierSet(compatibility.supported_versions):
+        raise AuthorCompatibilityError(
+            "installed dryv-author version "
+            f"{compatibility.author_version!r} is incompatible with compiler requirement "
+            f"{compatibility.supported_versions!r}"
+        )
+    if compatibility.representation != AUTHOR_REPRESENTATION:
+        raise AuthorCompatibilityError(
+            "installed dryv-author compiler-facing representation "
+            f"{compatibility.representation!r} is incompatible with {AUTHOR_REPRESENTATION!r}"
+        )
+    return compatibility
+
+
+def validate_author_compatibility() -> AuthorCompatibility:
+    compatibility = current_author_compatibility()
+    return validate_author_details(
+        compatibility.author_version,
+        compatibility.representation,
+    )

dryv_compiler-0.0.1/src/dryv_compiler/execution/__init__.py

@@ -0,0 +1,23 @@
+from .entrypoint import AuthorEntrypointError, LoadedAuthor, load_author_entrypoint
+from .environment import EnvironmentStatus, PythonEnvironmentReport, inspect_python_environment
+from .project import (
+    CapturedAuthor,
+    ProjectPythonError,
+    capture_author_entrypoint,
+    discover_project_python,
+    inspect_project_python,
+)
+
+__all__ = [
+    "AuthorEntrypointError",
+    "CapturedAuthor",
+    "EnvironmentStatus",
+    "LoadedAuthor",
+    "ProjectPythonError",
+    "PythonEnvironmentReport",
+    "capture_author_entrypoint",
+    "discover_project_python",
+    "inspect_project_python",
+    "inspect_python_environment",
+    "load_author_entrypoint",
+]