tpy-lang 0.3.0.dev0__py3-none-any.whl

tpyc/test_cycle_detection.py

@@ -0,0 +1,221 @@
+"""Unit tests for cycle_detection module."""
+
+import pytest
+from .typesys import NominalType, RecordInfo, FieldInfo, PtrType, TypeParamRef, make_list
+from .type_def_registry import (
+    attach_dynamic_type_def, clear_dynamic_type_defs, TypeCategory,
+)
+from .cycle_detection import detect_type_cycles, TypeCycle
+
+
+def _named(name: str) -> NominalType:
+    return NominalType(name)
+
+
+def _box(inner: NominalType) -> NominalType:
+    # `_module_qname` mirrors what type resolution sets on real records;
+    # it's what feeds `record_info_of(typ)` through the TypeDef registry.
+    return NominalType("Box", type_args=(inner,), _module_qname="Box")
+
+
+def _list(inner) -> NominalType:
+    return make_list(element_type=inner)
+
+
+@pytest.fixture
+def _box_recordinfo():
+    """Register a minimal RecordInfo for Box mirroring tplib.Box's
+    `_ptr: Ptr[T]` storage. The cycle walker now reads indirection from
+    record fields (with type-param substitution) rather than a hardcoded
+    name list, so tests using _box() must register the record."""
+    info = RecordInfo(
+        name="Box",
+        fields=[FieldInfo(name="_ptr", type=PtrType(TypeParamRef("T")))],
+        type_params=["T"],
+    )
+    attach_dynamic_type_def("Box", TypeCategory.RECORD, record=info)
+    try:
+        yield info
+    finally:
+        clear_dynamic_type_defs()
+
+
+@pytest.fixture
+def _list_indirecting():
+    """Flip is_indirecting=True on the static `builtins.list` TypeDef for
+    the duration of one test. In production the `@builtin_type("builtins.list",
+    indirecting=True)` stub registration handles this; the unit tests skip
+    stub compilation, so we toggle the flag directly."""
+    from .type_def_registry import get_type_def
+    td = get_type_def("builtins.list")
+    assert td is not None
+    prev = td.is_indirecting
+    td.is_indirecting = True
+    try:
+        yield
+    finally:
+        td.is_indirecting = prev
+
+
+class TestCycleDetection:
+    """Tests for detect_type_cycles."""
+
+    def test_no_cycle(self) -> None:
+        """A -> B with no back-reference: no cycle."""
+        cycles = detect_type_cycles(
+            record_fields={"A": [("b", _named("B"))], "B": [("x", _named("int"))]},
+            union_aliases={},
+        )
+        assert cycles == []
+
+    def test_record_record_cycle_no_indirection(self) -> None:
+        """A has B, B has A -- infinite size cycle."""
+        cycles = detect_type_cycles(
+            record_fields={
+                "A": [("b", _named("B"))],
+                "B": [("a", _named("A"))],
+            },
+            union_aliases={},
+        )
+        assert len(cycles) == 1
+        assert cycles[0].is_fully_unindirected()
+        assert set(cycles[0].path) == {"A", "B"}
+
+    def test_record_record_cycle_with_box(self, _box_recordinfo) -> None:
+        """A has Box[B], B has A -- cycle broken by Box on one edge."""
+        cycles = detect_type_cycles(
+            record_fields={
+                "A": [("b", _box(_named("B")))],
+                "B": [("a", _named("A"))],
+            },
+            union_aliases={},
+        )
+        assert len(cycles) == 1
+        # One edge has indirection (Box), so cycle is valid
+        assert cycles[0].has_any_indirection()
+        assert not cycles[0].is_fully_unindirected()
+
+    def test_mutual_recursion_union_records(self, _box_recordinfo) -> None:
+        """type Expr = Lit | BinOp, where BinOp has Box[Expr] -- the AST pattern."""
+        cycles = detect_type_cycles(
+            record_fields={
+                "Lit": [("value", _named("int"))],
+                "BinOp": [("left", _box(_named("Expr"))), ("right", _box(_named("Expr")))],
+            },
+            union_aliases={
+                "Expr": (_named("Lit"), _named("BinOp")),
+            },
+        )
+        assert len(cycles) >= 1
+        # At least one cycle should involve Expr
+        expr_cycles = [c for c in cycles if "Expr" in c.path]
+        assert len(expr_cycles) >= 1
+        # The cycle has indirection (Box on one edge), so it's valid
+        for c in expr_cycles:
+            assert c.has_any_indirection()
+            assert not c.is_fully_unindirected()
+        # Expr should be identified as an alias in the cycle
+        for c in expr_cycles:
+            assert "Expr" in c.alias_names
+
+    def test_mutual_recursion_no_box_error(self) -> None:
+        """type Expr = Lit | BinOp, where BinOp has bare Expr -- infinite size."""
+        cycles = detect_type_cycles(
+            record_fields={
+                "Lit": [("value", _named("int"))],
+                "BinOp": [("left", _named("Expr")), ("right", _named("Expr"))],
+            },
+            union_aliases={
+                "Expr": (_named("Lit"), _named("BinOp")),
+            },
+        )
+        assert len(cycles) >= 1
+        expr_cycles = [c for c in cycles if "Expr" in c.path]
+        assert len(expr_cycles) >= 1
+        # All edges lack indirection -- infinite size
+        assert any(c.is_fully_unindirected() for c in expr_cycles)
+
+    def test_list_provides_indirection(self, _list_indirecting) -> None:
+        """type Expr = Lit | Call, where Call has list[Expr] -- OK."""
+        cycles = detect_type_cycles(
+            record_fields={
+                "Lit": [("value", _named("int"))],
+                "Call": [("args", _list(_named("Expr")))],
+            },
+            union_aliases={
+                "Expr": (_named("Lit"), _named("Call")),
+            },
+        )
+        expr_cycles = [c for c in cycles if "Expr" in c.path]
+        assert len(expr_cycles) >= 1
+        for c in expr_cycles:
+            assert c.has_any_indirection()
+            assert not c.is_fully_unindirected()
+
+    def test_deep_cycle(self, _box_recordinfo) -> None:
+        """A -> B -> C -> A through records, depth > 1."""
+        cycles = detect_type_cycles(
+            record_fields={
+                "A": [("b", _box(_named("B")))],
+                "B": [("c", _named("C"))],
+                "C": [("a", _named("A"))],
+            },
+            union_aliases={},
+        )
+        assert len(cycles) >= 1
+        deep = [c for c in cycles if len(c.path) == 3]
+        assert len(deep) >= 1
+        assert set(deep[0].path) == {"A", "B", "C"}
+
+    def test_no_false_positives_for_self_reference(self, _box_recordinfo) -> None:
+        """Self-references are skipped (handled by D19)."""
+        cycles = detect_type_cycles(
+            record_fields={"Node": [("child", _box(_named("Node")))]},
+            union_aliases={},
+        )
+        assert cycles == []
+
+    def test_empty_input(self) -> None:
+        cycles = detect_type_cycles({}, {})
+        assert cycles == []
+
+    def test_imported_record_self_loop_terminates(self) -> None:
+        """The structural field walk would loop forever on an imported,
+        non-indirecting record that references itself in its own fields
+        (e.g. `class Wrapper[T]: inner: Wrapper[T]` imported from another
+        module, where Wrapper is NOT in the current module's target_names).
+        The walker's `expanding` recursion guard must terminate.
+        """
+        # Register Wrapper with a self-referential field. No Ptr, no
+        # is_indirecting -- so the walker takes the structural-fields
+        # path and would recurse indefinitely without the guard.
+        wrapper_info = RecordInfo(
+            name="Wrapper",
+            fields=[FieldInfo(name="inner", type=NominalType(
+                "Wrapper", type_args=(TypeParamRef("T"),), _module_qname="Wrapper",
+            ))],
+            type_params=["T"],
+        )
+        attach_dynamic_type_def("Wrapper", TypeCategory.RECORD, record=wrapper_info)
+        try:
+            # The cycle check should terminate (recursion guard fires) and
+            # report no cycle: Foo's field type is Wrapper[A], which the
+            # walker expands once into `inner: Wrapper[T->A]` -- the second
+            # entry into Wrapper hits the guard and returns without finding
+            # `A` in target_names along that path.
+            cycles = detect_type_cycles(
+                record_fields={
+                    "Foo": [("w", NominalType(
+                        "Wrapper",
+                        type_args=(_named("A"),),
+                        _module_qname="Wrapper",
+                    ))],
+                    "A": [("x", _named("int"))],
+                },
+                union_aliases={},
+            )
+            # The important assertion is termination; no cycle exists in
+            # this graph (Foo -> A via Wrapper's substituted field, A -> int).
+            assert cycles == []
+        finally:
+            clear_dynamic_type_defs()

tpyc/test_dump_types.py

@@ -0,0 +1,225 @@
+"""Tests for builtin type dump output (walks lib/tpy/ .py stubs)."""
+
+import ast as pyast
+import io
+import re
+from contextlib import redirect_stdout
+
+from .dump_types import (
+    _extract_all_whitelist,
+    _format_function_signature,
+    _get_docstring,
+    _gfm_anchor,
+    _indent,
+    _is_public,
+    _path_to_module,
+    _render_module,
+    dump_builtin_types,
+)
+
+
+def _parse(src: str) -> pyast.Module:
+    return pyast.parse(src)
+
+
+def test_path_to_module():
+    assert _path_to_module("tpy/__init__.py") == "tpy"
+    assert _path_to_module("tpy/_core/_types.py") == "tpy._core._types"
+    assert _path_to_module("typing.py") == "typing"
+    assert _path_to_module("tplib/json/parser.py") == "tplib.json.parser"
+
+
+def test_is_public():
+    assert _is_public("Foo", None)
+    assert not _is_public("_hidden", None)
+    # Dunder names are public-by-convention module metadata.
+    assert _is_public("__version__", None)
+    assert _is_public("__all__", None)
+    # With an __all__ whitelist, only listed names are public.
+    allow = frozenset({"Foo"})
+    assert _is_public("Foo", allow)
+    assert not _is_public("Bar", allow)
+    assert not _is_public("_hidden", allow)
+    # __all__ whitelist takes precedence even for dunders.
+    assert not _is_public("__version__", allow)
+
+
+def test_extract_all_whitelist():
+    tree = _parse('__all__ = ["A", "B"]\nclass C: ...')
+    assert _extract_all_whitelist(tree) == {"A", "B"}
+
+    tree_no_all = _parse("class C: ...")
+    assert _extract_all_whitelist(tree_no_all) is None
+
+    tree_tuple = _parse('__all__ = ("A", "B")')
+    assert _extract_all_whitelist(tree_tuple) == {"A", "B"}
+
+
+def test_format_function_signature_basic():
+    tree = _parse("def f(x: int, y: str) -> bool: ...")
+    fn = tree.body[0]
+    assert _format_function_signature("f", fn) == "f(x: int, y: str) -> bool"
+
+
+def test_format_function_signature_skips_self_for_constructors():
+    tree = _parse("class C:\n    def __init__(self, x: int) -> None: ...")
+    init = tree.body[0].body[0]
+    sig = _format_function_signature("C", init, is_method=True, skip_self=True)
+    assert sig == "C(x: int) -> None"
+
+
+def test_format_function_signature_keeps_self_for_methods():
+    tree = _parse("class C:\n    def f(self, x: int) -> int: ...")
+    method = tree.body[0].body[0]
+    sig = _format_function_signature("f", method, is_method=True)
+    assert sig == "f(self, x: int) -> int"
+
+
+def test_format_function_signature_varargs_and_kwonly():
+    tree = _parse("def f(*args: int, flag: bool = True, **kw: str) -> None: ...")
+    fn = tree.body[0]
+    sig = _format_function_signature("f", fn)
+    assert "*args: int" in sig
+    assert "flag: bool" in sig
+    assert "**kw: str" in sig
+
+
+def test_format_function_signature_bare_kwonly_separator():
+    """A bare `*` separator must be emitted when kwonlyargs exist without *args."""
+    tree = _parse("def f(x: int, *, flag: bool) -> None: ...")
+    fn = tree.body[0]
+    sig = _format_function_signature("f", fn)
+    assert sig == "f(x: int, *, flag: bool) -> None"
+
+
+def test_get_docstring_module_class_function():
+    tree = _parse('"""Module doc."""\n'
+                  'class C:\n'
+                  '    """Class doc."""\n'
+                  '    def m(self):\n'
+                  '        """Method doc."""\n'
+                  '        ...\n'
+                  'def f():\n'
+                  '    """Function doc."""\n'
+                  '    ...\n')
+    assert _get_docstring(tree) == "Module doc."
+    cls = tree.body[1]
+    assert _get_docstring(cls) == "Class doc."
+    # cls.body[0] is the docstring expression; cls.body[1] is the method.
+    method = cls.body[1]
+    assert _get_docstring(method) == "Method doc."
+    fn = tree.body[2]
+    assert _get_docstring(fn) == "Function doc."
+
+
+def test_get_docstring_absent_returns_none():
+    tree = _parse("class C: ...\ndef f(): ...\n")
+    assert _get_docstring(tree) is None
+    assert _get_docstring(tree.body[0]) is None
+    assert _get_docstring(tree.body[1]) is None
+
+
+def test_get_docstring_dedents_and_strips():
+    tree = _parse('def f():\n    """First line.\n\n    Second line.\n    """\n    ...\n')
+    # pyast.get_docstring(clean=True) already handles dedent, but our
+    # normalisation strips trailing whitespace too.
+    doc = _get_docstring(tree.body[0])
+    assert doc == "First line.\n\nSecond line."
+
+
+def test_indent_preserves_blank_lines():
+    assert _indent("a\n\nb", "  ") == "  a\n\n  b"
+
+
+def test_render_module_end_to_end(tmp_path):
+    """End-to-end: synthetic stub rendered through _render_module should
+    include class header, constructor overloads, methods, docstring, and a
+    trailing blank line after docstrings so the next item isn't swallowed."""
+    lib = tmp_path / "lib"
+    pkg = lib / "pkg"
+    pkg.mkdir(parents=True)
+    (pkg / "mod.py").write_text('"""Module doc."""\n'
+                                 "class Foo:\n"
+                                 '    """Class doc."""\n'
+                                 "    def __init__(self, x: int) -> None: ...\n"
+                                 "    def __init__(self, x: str) -> None: ...\n"
+                                 "    def method(self, y: int) -> int:\n"
+                                 '        """Method doc."""\n'
+                                 "        ...\n"
+                                 "    def another(self) -> None: ...\n"
+                                 "VERSION: str = '1.0'\n")
+
+    result = _render_module(pkg / "mod.py", lib)
+    assert result is not None
+    module_name, body = result
+    assert module_name == "pkg.mod"
+
+    # Module docstring appears.
+    assert "Module doc." in body
+    # Class header + class docstring.
+    assert "### Foo" in body
+    assert "Class doc." in body
+    # Both __init__ overloads are under Constructor, not Methods.
+    assert "**Constructor:**" in body
+    assert body.count("Foo(x: int)") == 1
+    assert body.count("Foo(x: str)") == 1
+    # Methods section exists and contains visible methods.
+    assert "**Methods:**" in body
+    assert "method(self, y: int) -> int" in body
+    assert "another(self) -> None" in body
+    # Method docstring appears.
+    assert "Method doc." in body
+    # Module-level typed constant rendered.
+    assert "`VERSION: str`" in body
+
+
+def test_render_module_skips_when_nothing_to_document(tmp_path):
+    """A module with only imports/private helpers produces no section."""
+    lib = tmp_path / "lib"
+    lib.mkdir()
+    (lib / "empty.py").write_text("from os import path\n"
+                                   "_private = 1\n"
+                                   "def _helper(): ...\n")
+    assert _render_module(lib / "empty.py", lib) is None
+
+
+def test_render_module_handles_syntax_error(tmp_path):
+    lib = tmp_path / "lib"
+    lib.mkdir()
+    (lib / "broken.py").write_text("this is not ::: valid python\n")
+    assert _render_module(lib / "broken.py", lib) is None
+
+
+def test_dump_builtin_types_emits_toc_and_modules():
+    """Smoke test: run the real dump against lib/tpy/ and verify structure."""
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        dump_builtin_types()
+    out = buf.getvalue()
+    # Header + TOC markers.
+    assert out.startswith("# TurboPython API Reference")
+    assert "## Modules" in out
+    # A few well-known modules appear both in the TOC and as sections.
+    for mod in ("math", "dataclasses", "tpy.version"):
+        assert f"[`{mod}`]" in out, f"missing TOC entry for {mod}"
+        assert f"## `{mod}`" in out, f"missing section for {mod}"
+    # tpy.version surfaces its typed constants (AnnAssign handling).
+    assert "`__version__: Final[str]`" in out
+    assert "`is_compiled: Final[bool]`" in out
+    # Internal _bindings.* layers are filtered out (no TOC entry, no section
+    # header). Their names may still appear in body text of other modules
+    # that reference them (e.g. `re` docstring), so check only structural
+    # positions, not raw substrings. Regex catches any future _bindings.*
+    # module without needing per-name updates.
+    assert not re.search(r"\[`_bindings\.[^`]+`\]", out)
+    assert not re.search(r"^## `_bindings\.[^`]+`", out, re.MULTILINE)
+
+
+def test_gfm_anchor():
+    # Backticks and dots stripped, underscores preserved, lowercased.
+    assert _gfm_anchor("`bisect`") == "bisect"
+    assert _gfm_anchor("`tpy._core._types`") == "tpy_core_types"
+    assert _gfm_anchor("`tplib.json.parser`") == "tplibjsonparser"
+    assert _gfm_anchor("`tplib.array_list`") == "tplibarray_list"
+    # Spaces become hyphens.
+    assert _gfm_anchor("Hello World") == "hello-world"

tpyc/test_install_docs.py

@@ -0,0 +1,65 @@
+"""Smoke tests for install_docs."""
+
+from pathlib import Path
+
+from .install_docs import install_agent_docs, agents_md_snippet
+
+
+def test_install_creates_both_files(tmp_path: Path) -> None:
+    target = tmp_path / "mydocs"
+    written = install_agent_docs(target)
+
+    names = {p.name for p in written}
+    assert names == {
+        "TPY_FOR_AGENTS.md",
+        "TPY_LANGUAGE_FEATURES.md",
+        "TPY_STDLIB_ROADMAP.md",
+        "TPY_API_REFERENCE.md",
+    }
+    for p in written:
+        assert p.is_file()
+        assert p.read_text().startswith("#")
+
+
+def test_install_creates_missing_dir(tmp_path: Path) -> None:
+    target = tmp_path / "a" / "b" / "c"
+    install_agent_docs(target)
+    assert target.is_dir()
+
+
+def test_install_overwrites(tmp_path: Path) -> None:
+    target = tmp_path / "docs"
+    target.mkdir()
+    stale = target / "TPY_FOR_AGENTS.md"
+    stale.write_text("old content")
+
+    install_agent_docs(target)
+
+    assert stale.read_text() != "old content"
+
+
+def test_install_rejects_existing_file(tmp_path: Path) -> None:
+    target = tmp_path / "not_a_dir"
+    target.write_text("I am a regular file")
+
+    try:
+        install_agent_docs(target)
+    except NotADirectoryError as e:
+        assert "not a directory" in str(e)
+    else:
+        raise AssertionError("expected NotADirectoryError")
+
+
+def test_snippet_uses_provided_path() -> None:
+    snippet = agents_md_snippet(Path("mydocs"))
+    assert "mydocs/TPY_FOR_AGENTS.md" in snippet
+    assert "mydocs/TPY_LANGUAGE_FEATURES.md" in snippet
+    assert "mydocs/TPY_STDLIB_ROADMAP.md" in snippet
+    assert "mydocs/TPY_API_REFERENCE.md" in snippet
+    assert "tpyc --install-agent-docs mydocs" in snippet
+
+
+def test_snippet_strips_trailing_slash() -> None:
+    snippet = agents_md_snippet(Path("docs/"))
+    assert "docs/TPY_FOR_AGENTS.md" in snippet
+    assert "docs//TPY_FOR_AGENTS.md" not in snippet

tpyc/test_local_cpp_form.py

@@ -0,0 +1,135 @@
+"""Tests for `CodeGenContext.local_cpp_form` and the lift-helper predicates.
+
+The classifier reads several parallel `set[str]` fields plus
+`current_func_params`. These tests stub those attributes directly to
+exercise priority order and helper-method dispatch without spinning up
+a full analyzer.
+"""
+
+from types import SimpleNamespace
+
+from .codegen_cpp.context import (
+    CodeGenContext,
+    LocalCppForm,
+)
+from .typesys import (
+    OwnType,
+    UnionType,
+    NominalType,
+)
+
+
+def _make_ctx(**overrides) -> SimpleNamespace:
+    """Build a stub with just the attrs/methods `local_cpp_form` reads."""
+    base = SimpleNamespace(
+        pointer_locals=set(),
+        optional_locals=set(),
+        ptr_variant_locals=set(),
+        storage_form_tuple_locals=set(),
+        storage_form_optional_locals=set(),
+        current_func_params={},
+    )
+    for k, v in overrides.items():
+        setattr(base, k, v)
+    # Bind the real classifier methods to the stub so the lift helpers
+    # (which call `self.local_cpp_form(...)` etc.) work.
+    base.is_own_ptr_variant_param = (
+        lambda name: CodeGenContext.is_own_ptr_variant_param(base, name)
+    )
+    base.is_ptr_variant_union = (
+        lambda u: CodeGenContext.is_ptr_variant_union(base, u)
+    )
+    base.local_cpp_form = (
+        lambda name: CodeGenContext.local_cpp_form(base, name)
+    )
+    return base
+
+
+def _form(ctx, name: str) -> LocalCppForm:
+    return CodeGenContext.local_cpp_form(ctx, name)
+
+
+class TestLocalCppFormClassification:
+    def test_default_is_value(self):
+        ctx = _make_ctx()
+        assert _form(ctx, "x") is LocalCppForm.VALUE
+
+    def test_pointer_only(self):
+        ctx = _make_ctx(pointer_locals={"p"})
+        assert _form(ctx, "p") is LocalCppForm.POINTER
+
+    def test_ptr_variant(self):
+        ctx = _make_ctx(ptr_variant_locals={"u"})
+        assert _form(ctx, "u") is LocalCppForm.PTR_VARIANT
+
+    def test_storage_tuple(self):
+        ctx = _make_ctx(storage_form_tuple_locals={"t"})
+        assert _form(ctx, "t") is LocalCppForm.STORAGE_TUPLE
+
+    def test_storage_optional(self):
+        # Loop var iterating `list[P|None]` / `dict[K, P|None]`, or
+        # comp/genexpr unpack var bound from a storage-form tuple slot.
+        ctx = _make_ctx(storage_form_optional_locals={"it"})
+        assert _form(ctx, "it") is LocalCppForm.STORAGE_OPTIONAL
+
+    def test_optional_storage_priority_over_storage_optional(self):
+        # The two sets are producer-disjoint today, but a same-name
+        # shadow (Own[Opt[T_ref]] param + a loop var that reuses the
+        # name) could put both populations on one name. Both lift via
+        # `optional_to_ptr`; the classifier resolves to OPTIONAL_STORAGE
+        # so the existing OPTIONAL_STORAGE consumer paths fire.
+        ctx = _make_ctx(
+            pointer_locals={"p"},
+            optional_locals={"p"},
+            storage_form_optional_locals={"p"},
+        )
+        assert _form(ctx, "p") is LocalCppForm.OPTIONAL_STORAGE
+
+    def test_optional_storage_in_both_sets(self):
+        # Own[Opt[T_ref]] params land in BOTH pointer_locals and
+        # optional_locals; the classifier must return OPTIONAL_STORAGE,
+        # not POINTER.
+        ctx = _make_ctx(pointer_locals={"p"}, optional_locals={"p"})
+        assert _form(ctx, "p") is LocalCppForm.OPTIONAL_STORAGE
+
+    def test_value_variant_via_own_union_param(self):
+        # Own[Union(Dog, Cat)] with both non-value records -> ptr-variant
+        # union -> classifier returns VALUE_VARIANT for the param name.
+        union = UnionType((NominalType("Dog"), NominalType("Cat")))
+        own = OwnType(union)
+        ctx = _make_ctx(current_func_params={"animal": own})
+        # Force the union to be ptr-variant: stub `is_ptr_variant_union`
+        # to return True. (The real predicate consults the record
+        # registry; we bypass it here.)
+        ctx.is_ptr_variant_union = lambda u: u is union
+        assert _form(ctx, "animal") is LocalCppForm.VALUE_VARIANT
+
+    def test_value_variant_takes_priority_over_ptr_variant_locals(self):
+        # If a single name somehow appears in both populations, the param
+        # ABI form (VALUE_VARIANT) wins -- it reflects the storage shape
+        # the caller produced, not the local-decl shape.
+        union = UnionType((NominalType("Dog"), NominalType("Cat")))
+        own = OwnType(union)
+        ctx = _make_ctx(
+            ptr_variant_locals={"animal"},
+            current_func_params={"animal": own},
+        )
+        ctx.is_ptr_variant_union = lambda u: u is union
+        assert _form(ctx, "animal") is LocalCppForm.VALUE_VARIANT
+
+
+class TestLiftHelpers:
+    def test_needs_optional_to_ptr_lift(self):
+        ctx = _make_ctx(pointer_locals={"p"}, optional_locals={"p"})
+        assert CodeGenContext.needs_optional_to_ptr_lift(ctx, "p") is True
+        # Plain POINTER name -- pointer_locals only, no optional_locals.
+        ctx2 = _make_ctx(pointer_locals={"q"})
+        assert CodeGenContext.needs_optional_to_ptr_lift(ctx2, "q") is False
+        assert CodeGenContext.needs_optional_to_ptr_lift(ctx, "missing") is False
+
+    def test_needs_to_ptr_variant_lift(self):
+        union = UnionType((NominalType("Dog"), NominalType("Cat")))
+        ctx = _make_ctx(current_func_params={"animal": OwnType(union)})
+        ctx.is_ptr_variant_union = lambda u: u is union
+        assert CodeGenContext.needs_to_ptr_variant_lift(ctx, "animal") is True
+        assert CodeGenContext.needs_to_ptr_variant_lift(ctx, "x") is False