varar 0.5.2__tar.gz

varar-0.5.2/.gitignore

@@ -0,0 +1,32 @@
+node_modules
+dist
+.DS_Store
+*.tsbuildinfo
+coverage
+*.timestamp-*
+.superpowers
+.var/
+
+# varar.lock.json baselines written by var-cli integration tests (temp fixtures)
+typescript/packages/cli/tests/fixtures/run-basic/varar.lock.json
+typescript/packages/cli/tests/fixtures/drift-tmp-*/
+# varar.lock.json written by the Python conformance dogfood command
+python/varar.lock.json
+# varar.lock.json written into the Kotest fixture roots on every test run
+# (the drift fixture's baseline IS committed and is not listed here)
+java/kotest/src/test/resources/kotest-smoke/varar.lock.json
+java/kotest/src/test/resources/kotest-failing/varar.lock.json
+.claude/*
+!.claude/skills/
+
+# Python
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.lcov
+
+release/dist/

varar-0.5.2/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: varar
+Version: 0.5.2
+Summary: Markdown-native BDD — pure Python core (port of @varar/varar)
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: cucumber-expressions==20.0.0
+Requires-Dist: varar-core==0.5.2

varar-0.5.2/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "varar"
+version = "0.5.2"
+description = "Markdown-native BDD — pure Python core (port of @varar/varar)"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+    "cucumber-expressions==20.0.0",
+    "varar-core==0.5.2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/varar"]

varar-0.5.2/src/varar/__init__.py

@@ -0,0 +1,7 @@
+"""Author facade for var: steps over the pure var-core engine."""
+
+__version__ = "0.0.0"
+
+from varar.internal import steps
+
+__all__ = ["steps"]

varar-0.5.2/src/varar/internal.py

@@ -0,0 +1,170 @@
+"""Author-facing API for declaring step state — port of var/src/internal.ts (steps)."""
+from __future__ import annotations
+
+import sys
+from re import Pattern
+from typing import Any, Callable, Optional
+
+from varar_core.registry import Registry, add_step, create_registry, define_parameter_type
+from varar_core.step_role import StepKind
+
+# ---------------------------------------------------------------------------
+# Module-level mutable builder state (mirrors the module-scope vars in internal.ts)
+# ---------------------------------------------------------------------------
+
+_steps: list[dict[str, Any]] = []
+# One factory per step-file; keyed by the FACTORY's __code__.co_filename
+_context_factories_by_file: dict[str, Callable[[], Any]] = {}
+_custom_types: list[dict[str, Any]] = []
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def steps(
+    factory: Optional[Callable[[], Any]] = None,
+) -> tuple[
+    Callable[..., None],
+    Callable[[str], Callable[[Callable], Callable]],
+    Callable[[str], Callable[[Callable], Callable]],
+]:
+    """Register *factory* as the context-state constructor for its step file.
+
+    *factory* is optional: a step file whose steps are pure (nothing to
+    arrange, nothing to evolve) calls ``steps()`` bare and its handlers
+    receive an empty ``dict`` as state.
+
+    Returns ``(param, stimulus, sensor)``:
+
+    - ``param(name, regexp, parse=None, format=None)`` declares a custom
+      cucumber-expression parameter type. ``parse`` is a varargs function over
+      the capture groups (``parse(*groups)``); omitted, the parameter stays the
+      matched text. ``format`` is the display-only inverse.
+    - ``stimulus`` / ``sensor`` are decorator factories:
+      ``@stimulus("expression")`` registers the decorated function as a step.
+
+    Source location is captured from the decorated function's ``__code__``
+    attributes (``co_filename`` / ``co_firstlineno``).
+
+    Raises ``RuntimeError`` if called more than once for the same source file
+    (keyed by *factory*'s ``co_filename``, or the caller's file when *factory*
+    is omitted), mirroring ``internal.ts``.
+    """
+    if factory is None:
+        # No factory code object to key by — use the calling step file itself,
+        # which is where an inline factory would have been defined anyway.
+        source_file: str = sys._getframe(1).f_code.co_filename
+        factory = dict
+    else:
+        source_file = factory.__code__.co_filename
+    if source_file in _context_factories_by_file:
+        raise RuntimeError(
+            f"steps() called more than once in {source_file}"
+        )
+    _context_factories_by_file[source_file] = factory
+
+    def param(
+        name: str,
+        regexp: Any,
+        parse: Optional[Callable[..., Any]] = None,
+        format: Optional[Callable[[Any], str]] = None,
+    ) -> None:
+        _custom_types.append(
+            {"name": name, "regexp": regexp, "parse": parse, "format": format}
+        )
+
+    def _make_decorator(kind: StepKind) -> Callable[[str], Callable[[Callable], Callable]]:
+        def decorator_factory(expression: str) -> Callable[[Callable], Callable]:
+            def decorator(fn: Callable) -> Callable:
+                _steps.append(
+                    {
+                        "expression": expression,
+                        "source_file": fn.__code__.co_filename,
+                        "source_line": fn.__code__.co_firstlineno,
+                        "handler": fn,
+                        "kind": kind,
+                    }
+                )
+                return fn
+
+            return decorator
+
+        return decorator_factory
+
+    return param, _make_decorator("stimulus"), _make_decorator("sensor")
+
+
+def context_factory() -> Callable[[str], Any]:
+    """Return a callable ``(step_file: str) -> state`` that invokes the
+    registered factory for *step_file*, or ``{}`` if none is registered.
+
+    Mirrors ``contextFactory()`` in ``internal.ts``.
+    """
+    # Snapshot at call time (mirrors TS semantics where the map is closed over)
+    factories = dict(_context_factories_by_file)
+
+    def _invoke(step_file: str) -> Any:
+        f = factories.get(step_file)
+        return f() if f is not None else {}
+
+    return _invoke
+
+
+def build_registry() -> Registry:
+    """Build and return a ``Registry`` from the accumulated steps and custom types.
+
+    Mirrors ``buildRegistry()`` in ``internal.ts``: custom parameter types are
+    registered first, then steps are compiled in registration order.
+    """
+    r = create_registry()
+    for t in _custom_types:
+        kwargs: dict[str, Any] = {"name": t["name"], "regexp": t["regexp"]}
+        if t.get("parse") is not None:
+            kwargs["parse"] = t["parse"]
+        if t.get("format") is not None:
+            kwargs["format"] = t["format"]
+        r = define_parameter_type(r, **kwargs)
+    for e in _steps:
+        r = add_step(
+            r,
+            expression=e["expression"],
+            expression_source_file=e["source_file"],
+            expression_source_line=e["source_line"],
+            handler=e["handler"],
+            kind=e["kind"],
+        )
+    return r
+
+
+def _reset_builder() -> None:
+    """Clear all accumulated state.  Use in tests between isolated scenarios."""
+    global _steps, _custom_types
+    _steps = []
+    _context_factories_by_file.clear()
+    _custom_types = []
+
+
+def _custom_parameter_types() -> list[dict[str, str]]:
+    """Conformance-harness accessor: the custom parameter types accumulated by
+    ``param`` since the last ``_reset_builder``, projected to the
+    ``{"name", "regexp"}`` wire shape ``to_registry_artifact`` serializes.
+
+    ``regexp`` is the bare pattern source (``re.Pattern.pattern`` or the string
+    as authored — no flags/delimiters), the cross-port convention every
+    language's registry golden uses. Internal-only, mirrors the TS
+    ``_customParameterTypes``.
+    """
+    out: list[dict[str, str]] = []
+    for t in _custom_types:
+        rx = t["regexp"]
+        if isinstance(rx, Pattern):
+            rx = rx.pattern
+        elif not isinstance(rx, str):
+            raise TypeError(
+                f"parameter type {t['name']!r}: regexp lists are not supported by the "
+                "conformance projection yet"
+            )
+        out.append({"name": t["name"], "regexp": rx})
+    return out

varar-0.5.2/src/varar/registry.py

@@ -0,0 +1,6 @@
+"""Adapter-only glue (mirrors @varar/varar/registry): build the registry and
+context factory from the module-scope accumulator, and reset it between runs."""
+
+from varar.internal import _custom_parameter_types, _reset_builder, build_registry, context_factory
+
+__all__ = ["build_registry", "context_factory", "_reset_builder", "_custom_parameter_types"]

varar-0.5.2/tests/test_conformance.py

@@ -0,0 +1,117 @@
+"""test_conformance.py — parametrized var-doc, registry, plan, and trace conformance harness.
+
+For each bundle under conformance/bundles/, parses example.md, projects it
+to the var-doc artifact, and asserts byte-for-byte equality with the
+committed golden/var-doc.json.
+
+The registry stage imports each bundle's steps.py (after resetting the builder),
+builds the registry, projects it, and asserts byte-for-byte equality with
+golden/registry.json.
+
+The plan stage builds the execution plan and asserts equality with golden/plan.json.
+
+The trace stage runs all examples via run_conformance and asserts equality with
+golden/trace.json for all four artifacts simultaneously.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+from varar_core.canonical_json import canonical_stringify
+from varar_core.conformance import run_conformance, to_plan_artifact, to_registry_artifact, to_var_doc_artifact
+from varar.registry import _custom_parameter_types, _reset_builder, build_registry, context_factory
+from varar_core.parse import parse
+from varar_core.plan import plan as build_plan
+
+# python/packages/varar/tests/ -> parents[4] = repo root
+BUNDLES_DIR = Path(__file__).resolve().parents[4] / "conformance" / "bundles"
+BUNDLES = sorted(p for p in BUNDLES_DIR.iterdir() if p.is_dir())
+
+
+@pytest.mark.parametrize("bundle", BUNDLES, ids=lambda b: b.name)
+def test_var_doc_matches_golden(bundle: Path) -> None:
+    source = (bundle / "example.md").read_text(encoding="utf-8")
+    doc = parse("example.md", source)
+    artifact = to_var_doc_artifact(doc)
+    actual = canonical_stringify(artifact)
+    expected = (bundle / "golden" / "var-doc.json").read_text(encoding="utf-8")
+    assert actual == expected
+
+
+def _find_steps_file(bundle: Path) -> Path | None:
+    """Return the canonical step file for *bundle*.
+
+    Prefers ``<name>.steps.py`` (mirroring the TypeScript ``<name>.steps.ts``
+    convention) so the stem matches the golden ``stepFile`` values.  Falls back
+    to the legacy ``steps.py`` name so existing bundles without a renamed file
+    still work.
+    """
+    candidates = sorted(bundle.glob("*.steps.py"))
+    if candidates:
+        return candidates[0]
+    legacy = bundle / "steps.py"
+    return legacy if legacy.exists() else None
+
+
+def _import_steps(bundle: Path) -> None:
+    """Import the step file from *bundle* as a fresh module (unique name each call).
+
+    Using ``spec_from_file_location`` with a unique module name ensures
+    ``steps`` sees a different ``co_filename`` per import, and also
+    prevents Python's import cache from returning a stale module across bundles.
+    """
+    steps_py = _find_steps_file(bundle)
+    assert steps_py is not None, f"Cannot find a step file in {bundle}"
+    module_name = f"_steps_{bundle.name}"
+    spec = importlib.util.spec_from_file_location(module_name, steps_py)
+    assert spec is not None and spec.loader is not None, f"Cannot load {steps_py}"
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)  # type: ignore[union-attr]
+
+
+# Every bundle in the corpus is gated. A bundle without a Python step fixture is a
+# hole in the gate, not a bundle to skip: parametrize over all of them and let
+# _import_steps fail loudly, the way the Java/Kotlin/Rust/Go/TS harnesses do.
+
+
+@pytest.mark.parametrize("bundle", BUNDLES, ids=lambda b: b.name)
+def test_registry_matches_golden(bundle: Path) -> None:
+    _reset_builder()
+    _import_steps(bundle)
+    registry = build_registry()
+    artifact = to_registry_artifact(registry, _custom_parameter_types())
+    actual = canonical_stringify(artifact)
+    expected = (bundle / "golden" / "registry.json").read_text(encoding="utf-8")
+    assert actual == expected, f"registry.json mismatch for {bundle.name}"
+
+
+@pytest.mark.parametrize("bundle", BUNDLES, ids=lambda b: b.name)
+def test_plan_matches_golden(bundle: Path) -> None:
+    _reset_builder()
+    _import_steps(bundle)
+    registry = build_registry()
+    source = (bundle / "example.md").read_text(encoding="utf-8")
+    doc = parse("example.md", source)
+    execution = build_plan(doc, registry)
+    artifact = to_plan_artifact(execution)
+    actual = canonical_stringify(artifact)
+    expected = (bundle / "golden" / "plan.json").read_text(encoding="utf-8")
+    assert actual == expected, f"plan.json mismatch for {bundle.name}"
+
+
+@pytest.mark.parametrize("bundle", BUNDLES, ids=lambda b: b.name)
+def test_trace_matches_golden(bundle: Path) -> None:
+    _reset_builder()
+    _import_steps(bundle)
+    registry = build_registry()
+    create_ctx = context_factory()
+    source = (bundle / "example.md").read_text(encoding="utf-8")
+    doc = parse("example.md", source)
+    artifacts = run_conformance(doc, registry, create_ctx, tuple(_custom_parameter_types()))
+    actual = canonical_stringify(artifacts.trace)
+    expected = (bundle / "golden" / "trace.json").read_text(encoding="utf-8")
+    assert actual == expected, f"trace.json mismatch for {bundle.name}"

varar-0.5.2/tests/test_custom_parameter_types.py

@@ -0,0 +1,32 @@
+import re
+
+import pytest
+
+from varar import steps
+from varar.registry import _custom_parameter_types, _reset_builder
+
+
+def test_projects_name_and_pattern_source():
+    _reset_builder()
+    param, _stimulus, _sensor = steps(lambda: {})
+    param("airport", re.compile(r"[A-Z]{3}"), parse=lambda code: code.lower())
+    assert _custom_parameter_types() == [{"name": "airport", "regexp": "[A-Z]{3}"}]
+    _reset_builder()
+    assert _custom_parameter_types() == []
+
+
+def test_string_regexp_passes_through_verbatim():
+    _reset_builder()
+    param, _stimulus, _sensor = steps(lambda: {})
+    param("airport", "[A-Z]{3}")
+    assert _custom_parameter_types() == [{"name": "airport", "regexp": "[A-Z]{3}"}]
+    _reset_builder()
+
+
+def test_list_form_regexp_is_rejected():
+    _reset_builder()
+    param, _stimulus, _sensor = steps(lambda: {})
+    param("code", ["[A-Z]{3}", "[0-9]{3}"])
+    with pytest.raises(TypeError, match="not supported"):
+        _custom_parameter_types()
+    _reset_builder()

varar-0.5.2/tests/test_smoke.py

@@ -0,0 +1,5 @@
+import varar
+
+
+def test_version():
+    assert varar.__version__ == "0.0.0"

varar-0.5.2/tests/test_steps.py

@@ -0,0 +1,149 @@
+"""Tests for internal.py steps() — translated from var/src/internal.ts tests."""
+from __future__ import annotations
+
+import pytest
+
+from varar.registry import _reset_builder, build_registry, context_factory
+from varar import steps
+
+
+def test_two_decorators_register_with_correct_kinds() -> None:
+    _reset_builder()
+
+    def factory():
+        return {}
+
+    _param, stimulus, sensor = steps(factory)
+
+    @stimulus("I have set up the world")
+    def setup(state):
+        pass
+
+    @stimulus("I do something")
+    def do_something(state):
+        pass
+
+    @sensor("I check the result")
+    def check(state):
+        pass
+
+    r = build_registry()
+    assert len(r.steps) == 3
+    kinds = {s.expression: s.kind for s in r.steps}
+    assert kinds["I have set up the world"] == "stimulus"
+    assert kinds["I do something"] == "stimulus"
+    assert kinds["I check the result"] == "sensor"
+
+
+def test_decorators_capture_source_file_and_line() -> None:
+    _reset_builder()
+
+    def factory():
+        return {}
+
+    _param, stimulus, _sensor = steps(factory)
+
+    @stimulus("a step")
+    def my_step(state):
+        pass
+
+    r = build_registry()
+    step = r.steps[0]
+    assert step.expression_source_line >= 1
+    assert "test_steps" in step.expression_source_file
+
+
+def test_second_steps_in_same_module_raises() -> None:
+    _reset_builder()
+
+    def factory1():
+        return {}
+
+    def factory2():
+        return {}
+
+    steps(factory1)
+    with pytest.raises(Exception, match=r"steps.*called more than once"):
+        steps(factory2)
+
+
+def test_build_registry_returns_steps_in_registration_order() -> None:
+    _reset_builder()
+
+    def factory():
+        return {}
+
+    _param, stimulus, sensor = steps(factory)
+
+    @stimulus("step one")
+    def s1(state):
+        pass
+
+    @stimulus("step two")
+    def s2(state):
+        pass
+
+    @sensor("step three")
+    def s3(state):
+        pass
+
+    r = build_registry()
+    assert [s.expression for s in r.steps] == ["step one", "step two", "step three"]
+
+
+def test_context_factory_returns_callable_that_invokes_registered_factory() -> None:
+    _reset_builder()
+
+    def factory():
+        return {"count": 42}
+
+    _param, stimulus, _sensor = steps(factory)
+
+    @stimulus("some step")
+    def step(state):
+        pass
+
+    r = build_registry()
+    # context_factory() returns a callable(step_file) -> state
+    cf = context_factory()
+    step_file = r.steps[0].expression_source_file
+    state = cf(step_file)
+    assert state == {"count": 42}
+
+
+def test_context_factory_returns_empty_dict_for_unknown_file() -> None:
+    _reset_builder()
+
+    cf = context_factory()
+    result = cf("nonexistent_file.py")
+    assert result == {}
+
+
+def test_steps_without_factory_registers_steps_against_empty_state() -> None:
+    _reset_builder()
+
+    _param, stimulus, sensor = steps()
+
+    @stimulus("I warm up my mental math")
+    def warm_up(state):
+        pass
+
+    @sensor("the square of {int} is {int}")
+    def square(state, n, expected):
+        return [n, n * n]
+
+    r = build_registry()
+    assert len(r.steps) == 2
+    # The factory is keyed by THIS file (the caller), and produces a fresh {}.
+    cf = context_factory()
+    state = cf(r.steps[0].expression_source_file)
+    assert state == {}
+    assert cf(r.steps[0].expression_source_file) is not state
+
+
+def test_steps_without_factory_still_enforces_once_per_file() -> None:
+    _reset_builder()
+
+    steps()
+    with pytest.raises(Exception, match=r"steps.*called more than once"):
+        steps()