wunderspec 0.129.1__tar.gz → 0.129.2__tar.gz

{wunderspec-0.129.1 → wunderspec-0.129.2}/.flake8

@@ -2,5 +2,6 @@
 max-line-length = 88
 extend-ignore = E203, E501
 per-file-ignores = 
+    examples/*:E266,F403,F405
     tests/*:F401,F841
     wunderspec/lang.py:E721

wunderspec-0.129.2/.github/workflows/build.yml

@@ -0,0 +1,34 @@
+name: Build
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        enable-cache: true
+        cache-suffix: build
+
+    - name: Build package
+      run: uv build
+
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/

wunderspec-0.129.2/.github/workflows/convert-to-tla.yml

@@ -0,0 +1,78 @@
+name: Convert to TLA+
+
+env:
+  APALACHE_VERSION: "0.57.0"
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  convert-to-tla:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        enable-cache: true
+        cache-suffix: convert-to-tla
+
+    - name: Install project
+      run: uv sync --locked
+
+    - name: Set up Java
+      uses: actions/setup-java@v5
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+
+    - name: Cache tla2tools.jar
+      id: cache-tla2tools
+      uses: actions/cache@v5
+      with:
+        path: tla2tools.jar
+        key: tla2tools-v1.8.0
+
+    - name: Download tla2tools.jar
+      if: steps.cache-tla2tools.outputs.cache-hit != 'true'
+      run: wget -q https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tla2tools.jar
+
+    - name: Cache Apalache
+      id: cache-apalache
+      uses: actions/cache@v5
+      with:
+        path: apalache-${{ env.APALACHE_VERSION }}
+        key: apalache-v${{ env.APALACHE_VERSION }}
+
+    - name: Download Apalache
+      if: steps.cache-apalache.outputs.cache-hit != 'true'
+      run: |
+        curl -fsSL "https://github.com/apalache-mc/apalache/releases/download/v${APALACHE_VERSION}/apalache-${APALACHE_VERSION}.tgz" -o apalache.tgz
+        tar -xzf apalache.tgz
+        rm apalache.tgz
+
+    - name: Add Apalache to PATH
+      run: echo "$PWD/apalache-${APALACHE_VERSION}/bin" >> "$GITHUB_PATH"
+
+    - name: Convert examples to TLA+
+      run: uv run python scripts/convert_examples_to_tla.py
+
+    - name: Run Apalache typecheck on generated specs
+      run: |
+        set -euo pipefail
+        mkdir -p .apalache-out/build
+        cd .build
+        for f in *.tla; do
+          echo "=== Typechecking $f ==="
+          apalache-mc typecheck --out-dir="../.apalache-out/build/$(basename "${f%.tla}")" "$f"
+        done

wunderspec-0.129.2/.github/workflows/lint.yml

@@ -0,0 +1,40 @@
+name: Lint
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        enable-cache: true
+        cache-suffix: lint
+
+    - name: Install project
+      run: uv sync --locked --group dev
+
+    - name: Check code formatting with Black
+      run: uv run black --check --diff .
+
+    - name: Check import sorting with isort
+      run: uv run isort --check-only --diff .
+
+    - name: Lint with flake8
+      run: uv run flake8 wunderspec examples scripts
+
+    - name: Type check with mypy
+      run: uv run mypy wunderspec

wunderspec-0.129.2/.github/workflows/run-examples.yml

@@ -0,0 +1,31 @@
+name: Run Examples
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  run-examples:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        enable-cache: true
+        cache-suffix: run-examples
+
+    - name: Install project
+      run: uv sync --locked
+
+    - name: Run examples
+      run: uv run python scripts/run_examples.py

{wunderspec-0.129.1 → wunderspec-0.129.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wunderspec
-Version: 0.129.1
+Version: 0.129.2
 Summary: Protocol specifications as Python code
 Author: Igor Konnov, Thomas Pani
 License-File: LICENSE
@@ -74,8 +74,8 @@ commands are not included in this package.
 
 ## 4. Release Provenance
 
-- Release tag: `v0.129.1`
-- Source commit: `604d6a23a444006bb67b14e0728df07711d3facb`
+- Release tag: `v0.129.2`
+- Source commit: `f60e52f632281f5cbb2d1a382ea49b10750d2f4d`
 
 See [tests/README.md](https://github.com/wunderspec/wunderspec/blob/main/tests/README.md)
 for the development test log captured at release time.

{wunderspec-0.129.1 → wunderspec-0.129.2}/README.md

@@ -58,8 +58,8 @@ commands are not included in this package.
 
 ## 4. Release Provenance
 
-- Release tag: `v0.129.1`
-- Source commit: `604d6a23a444006bb67b14e0728df07711d3facb`
+- Release tag: `v0.129.2`
+- Source commit: `f60e52f632281f5cbb2d1a382ea49b10750d2f4d`
 
 See [tests/README.md](https://github.com/wunderspec/wunderspec/blob/main/tests/README.md)
 for the development test log captured at release time.

{wunderspec-0.129.1 → wunderspec-0.129.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wunderspec"
-version = "0.129.1"
+version = "0.129.2"
 description = "Protocol specifications as Python code"
 authors = [
     {name = "Igor Konnov"},

wunderspec-0.129.2/scripts/__init__.py

@@ -0,0 +1 @@
+"""Repository maintenance scripts."""

wunderspec-0.129.2/scripts/_spec_utils.py

@@ -0,0 +1,190 @@
+"""Shared AST helpers for wunderspec example scripts."""
+
+import ast
+import re
+from pathlib import Path
+from typing import Any, TypedDict
+
+import yaml  # type: ignore[import-untyped]
+
+
+class ExampleConfigRow(TypedDict):
+    file: str
+    instances: list[str]
+    invariants_auto: bool
+    invariants: list[str]
+    examples_auto: bool
+    examples: list[str]
+    example_run_seeds: dict[str, int]
+    example_run_max_samples: dict[str, int]
+    timeout: int | None
+
+
+def _find_decorated_names(spec_path: Path, decorator_id: str) -> list[str]:
+    """Return names of functions decorated with ``@decorator_id`` in *spec_path*.
+
+    Uses AST inspection so the module is never imported (avoids dependency
+    issues with spec-local imports such as ``from simple_ponzi import *``).
+    """
+    tree = ast.parse(spec_path.read_text())
+    names: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for decorator in node.decorator_list:
+                if isinstance(decorator, ast.Name) and decorator.id == decorator_id:
+                    names.append(node.name)
+    return names
+
+
+def find_invariant_names(spec_path: Path) -> set[str]:
+    """Return the names of functions decorated with ``@invariant`` in *spec_path*."""
+    return set(_find_decorated_names(spec_path, "invariant"))
+
+
+def find_example_names(spec_path: Path) -> set[str]:
+    """Return the names of functions decorated with ``@example`` in *spec_path*."""
+    return set(_find_decorated_names(spec_path, "example"))
+
+
+def find_coverage_names(spec_path: Path) -> set[str]:
+    """Return the names of functions decorated with ``@coverage`` in *spec_path*."""
+    return set(_find_decorated_names(spec_path, "coverage"))
+
+
+def find_init_action_name(spec_path: Path) -> str:
+    """Return the name of the ``@action(init=True)`` function, or ``"init"``."""
+    tree = ast.parse(spec_path.read_text())
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for decorator in node.decorator_list:
+                if isinstance(decorator, ast.Call):
+                    func = decorator.func
+                    if isinstance(func, ast.Name) and func.id == "action":
+                        for kw in decorator.keywords:
+                            if (
+                                kw.arg == "init"
+                                and isinstance(kw.value, ast.Constant)
+                                and kw.value.value is True
+                            ):
+                                return node.name
+    return "init"
+
+
+_STEP_NAME_RE = re.compile(r"^(Next|step|Step|.*_next|.*Next)$")
+
+
+def find_step_action_name(spec_path: Path, init_name: str) -> str:
+    """Return the name of the bare ``@action`` (non-init, single-param) function.
+
+    Only considers names matching: Next, step, Step, *_next, *Next.
+    Falls back to ``"step"`` if none is found.
+    """
+    tree = ast.parse(spec_path.read_text())
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if node.name == init_name:
+            continue
+        if not _STEP_NAME_RE.match(node.name):
+            continue
+        if len(node.args.args) != 1:
+            continue
+        for decorator in node.decorator_list:
+            if isinstance(decorator, ast.Name) and decorator.id == "action":
+                return node.name
+    return "step"
+
+
+def load_examples_config(config_path: Path) -> list[ExampleConfigRow]:
+    """Load examples YAML config.
+
+    Expected shape:
+
+    examples:
+      - file: spec.py
+        instances: inst_a inst_b   # or a YAML list
+        invariants: inv_x inv_y    # or a YAML list; omit for auto-discovery
+        examples: ex_a ex_b        # or a YAML list; omit for auto-discovery
+        example_run_seeds:         # optional mapping example -> integer seed
+          ex_b: 123
+        example_run_max_samples:   # optional mapping example -> integer
+          ex_b: 300
+        timeout: 30                # optional wall-clock cap (seconds) per run
+    """
+
+    def _to_tokens(raw: Any, key: str, file_label: str) -> list[str]:
+        if raw is None:
+            return []
+        if isinstance(raw, str):
+            return raw.split()
+        if isinstance(raw, list) and all(isinstance(x, str) for x in raw):
+            return raw
+        raise ValueError(
+            f"{config_path}: '{key}' in '{file_label}' must be a string or list[str]"
+        )
+
+    def _to_optional_int(raw: Any, key: str, file_label: str) -> int | None:
+        if raw is None:
+            return None
+        if isinstance(raw, int) and not isinstance(raw, bool):
+            return raw
+        raise ValueError(f"{config_path}: '{key}' in '{file_label}' must be an integer")
+
+    def _to_str_int_map(raw: Any, key: str, file_label: str) -> dict[str, int]:
+        if raw is None:
+            return {}
+        if not isinstance(raw, dict):
+            raise ValueError(
+                f"{config_path}: '{key}' in '{file_label}' must be a mapping[str, int]"
+            )
+        out: dict[str, int] = {}
+        for k, v in raw.items():
+            if not isinstance(k, str) or not isinstance(v, int):
+                raise ValueError(
+                    f"{config_path}: '{key}' in '{file_label}' must be a mapping[str, int]"
+                )
+            out[k] = v
+        return out
+
+    data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"{config_path}: root must be a mapping")
+    examples = data.get("examples")
+    if not isinstance(examples, list) or not examples:
+        raise ValueError(f"{config_path}: 'examples' must be a non-empty list")
+
+    rows: list[ExampleConfigRow] = []
+    for entry in examples:
+        if not isinstance(entry, dict):
+            raise ValueError(f"{config_path}: each example entry must be a mapping")
+        spec_file = entry.get("file")
+        if not isinstance(spec_file, str) or not spec_file.strip():
+            raise ValueError(
+                f"{config_path}: each example must define non-empty 'file'"
+            )
+        spec_file = spec_file.strip()
+        rows.append(
+            {
+                "file": spec_file,
+                "instances": _to_tokens(entry.get("instances"), "instances", spec_file),
+                "invariants_auto": "invariants" not in entry,
+                "invariants": _to_tokens(
+                    entry.get("invariants"), "invariants", spec_file
+                ),
+                "examples_auto": "examples" not in entry,
+                "examples": _to_tokens(entry.get("examples"), "examples", spec_file),
+                "example_run_seeds": _to_str_int_map(
+                    entry.get("example_run_seeds"),
+                    "example_run_seeds",
+                    spec_file,
+                ),
+                "example_run_max_samples": _to_str_int_map(
+                    entry.get("example_run_max_samples"),
+                    "example_run_max_samples",
+                    spec_file,
+                ),
+                "timeout": _to_optional_int(entry.get("timeout"), "timeout", spec_file),
+            }
+        )
+
+    return rows

wunderspec-0.129.2/scripts/convert_examples_to_tla.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Convert examples from examples/examples.yaml to TLA+ and validate with SANY.
+
+For each file listed in the YAML config, this script:
+1. Converts the base spec to ``<build_dir>/<stem>.tla``
+2. Converts each listed ``@instance`` to ``<build_dir>/MC_<instance>_<stem>.tla``
+3. Downloads Apalache support modules into ``build_dir`` if they are missing
+4. Runs SANY on every generated ``.tla`` file with ``build_dir`` on the classpath
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+from typing import cast
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from scripts._spec_utils import load_examples_config  # noqa: E402
+
+ROOT = Path(__file__).parent.parent
+EXAMPLES_DIR = ROOT / "examples"
+CONFIG_PATH = EXAMPLES_DIR / "examples.yaml"
+BUILD_DIR = ROOT / ".build"
+TLA2TOOLS_JAR = ROOT / "tla2tools.jar"
+SUPPORT_MODULES = {
+    "Variants.tla": "https://raw.githubusercontent.com/apalache-mc/apalache/main/src/tla/Variants.tla",
+    "Apalache.tla": "https://raw.githubusercontent.com/apalache-mc/apalache/main/src/tla/Apalache.tla",
+}
+
+
+def clear_build_dir(build_dir: Path) -> None:
+    """Remove the generated build directory if it matches the expected location."""
+    resolved_root = ROOT.resolve()
+    resolved_build_dir = build_dir.resolve(strict=False)
+    expected_build_dir = (resolved_root / ".build").resolve(strict=False)
+
+    if resolved_build_dir != expected_build_dir:
+        raise SystemExit(
+            f"Refusing to remove unexpected build directory: {resolved_build_dir}"
+        )
+    if resolved_build_dir.parent != resolved_root:
+        raise SystemExit(
+            f"Refusing to remove build directory outside project root: {resolved_build_dir}"
+        )
+    if resolved_build_dir.name != ".build":
+        raise SystemExit(
+            f"Refusing to remove directory with unexpected name: {resolved_build_dir}"
+        )
+
+    if build_dir.exists():
+        shutil.rmtree(build_dir)
+
+
+def ensure_support_modules(build_dir: Path) -> None:
+    build_dir.mkdir(parents=True, exist_ok=True)
+    for filename, url in SUPPORT_MODULES.items():
+        dst = build_dir / filename
+        if dst.exists():
+            continue
+        src = ROOT / filename
+        if src.exists():
+            shutil.copy(src, dst)
+            continue
+        print(f"Downloading {filename}...", flush=True)
+        urllib.request.urlretrieve(url, dst)
+
+
+def run_cmd(cmd: list[str], *, env: dict[str, str], cwd: Path = ROOT) -> None:
+    result = subprocess.run(cmd, cwd=cwd, env=env)
+    if result.returncode != 0:
+        raise SystemExit(result.returncode)
+
+
+def main() -> int:
+    if not TLA2TOOLS_JAR.exists():
+        print("Error: tla2tools.jar not found", file=sys.stderr)
+        return 1
+
+    clear_build_dir(BUILD_DIR)
+    ensure_support_modules(BUILD_DIR)
+
+    env = {**os.environ, "PYTHONPATH": str(EXAMPLES_DIR)}
+    generated: list[Path] = []
+
+    for row in load_examples_config(CONFIG_PATH):
+        spec_file = str(row["file"]).strip()
+        if not spec_file:
+            continue
+
+        stem = Path(spec_file).stem
+        instances = cast(list[str], row["instances"])
+        base_out = BUILD_DIR / f"{stem}.tla"
+        print(f"=== Converting {spec_file} ===", flush=True)
+        run_cmd(
+            [
+                sys.executable,
+                "-m",
+                "wunderspec.cli",
+                "convert",
+                "--from",
+                f"examples/{spec_file}",
+                "--to",
+                str(base_out),
+            ],
+            env=env,
+        )
+        generated.append(base_out)
+
+        for instance in instances:
+            wrapper_out = BUILD_DIR / f"MC_{instance}_{stem}.tla"
+            print(
+                f"=== Converting {spec_file} instance {instance} ===",
+                flush=True,
+            )
+            run_cmd(
+                [
+                    sys.executable,
+                    "-m",
+                    "wunderspec.cli",
+                    "convert",
+                    "--from",
+                    f"examples/{spec_file}",
+                    "--to",
+                    str(wrapper_out),
+                    "--instance",
+                    str(instance),
+                ],
+                env=env,
+            )
+            generated.append(wrapper_out)
+
+    classpath = f"{TLA2TOOLS_JAR}{os.pathsep}{BUILD_DIR}"
+    for tla_file in generated:
+        print(f"=== Checking {tla_file.relative_to(ROOT)} ===", flush=True)
+        run_cmd(
+            ["java", "-cp", classpath, "tla2sany.SANY", tla_file.name],
+            env=env,
+            cwd=BUILD_DIR,
+        )
+
+    print("All examples and listed instances converted and passed SANY")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())