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

tpyc/sema/value_range.py

@@ -0,0 +1,181 @@
+"""
+ValueRange -- tracks provable integer value constraints.
+
+Represents a [lo, hi] interval with optional non_zero flag and symbolic
+upper bound (hi_len_of). Used for bounds check elision and division-by-zero
+check elision.
+
+Frozen dataclass so instances can be stored in FlowFacts frozensets.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# INT32 bounds (loop indices and len() return Int32)
+_INT32_MAX = 2**31 - 1
+_INT32_MIN = -(2**31)
+
+
+@dataclass(frozen=True, slots=True)
+class ValueRange:
+    """Proven integer value constraints for a variable.
+
+    lo/hi: concrete bounds (None = unbounded in that direction).
+    non_zero: True if the value is provably != 0.
+    hi_len_of: when set, hi is symbolically len(var_name) - 1.
+    """
+
+    lo: int | None = None
+    hi: int | None = None
+    non_zero: bool = False
+    hi_len_of: str | None = None
+
+    # -- Factories --
+
+    @staticmethod
+    def from_literal(value: int) -> ValueRange:
+        return ValueRange(lo=value, hi=value, non_zero=(value != 0))
+
+    @staticmethod
+    def from_len() -> ValueRange:
+        """Result of len() -- always non-negative."""
+        return ValueRange(lo=0, hi=_INT32_MAX)
+
+    @staticmethod
+    def non_negative() -> ValueRange:
+        return ValueRange(lo=0)
+
+    @staticmethod
+    def only_non_zero() -> ValueRange:
+        return ValueRange(non_zero=True)
+
+    @staticmethod
+    def for_range_index(stop_len_of: str | None = None,
+                        stop_literal: int | None = None) -> ValueRange:
+        """Range fact for a for-loop variable iterating over range().
+
+        stop_len_of: container name when stop is len(container).
+        stop_literal: concrete stop value when known.
+        """
+        if stop_len_of is not None:
+            return ValueRange(lo=0, hi_len_of=stop_len_of)
+        if stop_literal is not None:
+            if stop_literal <= 0:
+                # Empty range -- loop body never executes, but if it did
+                # the variable would have no valid value. Use [0, -1].
+                return ValueRange(lo=0, hi=-1)
+            return ValueRange(lo=0, hi=stop_literal - 1)
+        return ValueRange(lo=0)
+
+    # -- Queries --
+
+    def is_non_negative(self) -> bool:
+        return self.lo is not None and self.lo >= 0
+
+    def is_bounded_by_len(self, container: str) -> bool:
+        """True if hi is symbolically <= len(container) - 1."""
+        return self.hi_len_of is not None and self.hi_len_of == container
+
+    # -- Combinators --
+
+    @staticmethod
+    def merge(a: ValueRange, b: ValueRange) -> ValueRange:
+        """Branch join (union): widens to cover both possibilities."""
+        if a.lo is None or b.lo is None:
+            lo = None
+        else:
+            lo = min(a.lo, b.lo)
+
+        # Symbolic bounds only preserved when both agree
+        if a.hi_len_of is not None and a.hi_len_of == b.hi_len_of:
+            return ValueRange(
+                lo=lo,
+                hi_len_of=a.hi_len_of,
+                non_zero=a.non_zero and b.non_zero,
+            )
+
+        if a.hi is None or b.hi is None:
+            hi = None
+        else:
+            hi = max(a.hi, b.hi)
+
+        return ValueRange(
+            lo=lo,
+            hi=hi,
+            non_zero=a.non_zero and b.non_zero,
+        )
+
+    @staticmethod
+    def intersect(a: ValueRange, b: ValueRange) -> ValueRange:
+        """And-composition: tightens to what both prove."""
+        if a.lo is None:
+            lo = b.lo
+        elif b.lo is None:
+            lo = a.lo
+        else:
+            lo = max(a.lo, b.lo)
+
+        # Keep symbolic bound only when both sides agree (or one is absent)
+        if a.hi_len_of is not None and b.hi_len_of is not None:
+            hi_len_of = a.hi_len_of if a.hi_len_of == b.hi_len_of else None
+        else:
+            hi_len_of = a.hi_len_of or b.hi_len_of
+
+        if hi_len_of is not None:
+            return ValueRange(
+                lo=lo,
+                hi_len_of=hi_len_of,
+                non_zero=a.non_zero or b.non_zero,
+            )
+
+        if a.hi is None:
+            hi = b.hi
+        elif b.hi is None:
+            hi = a.hi
+        else:
+            hi = min(a.hi, b.hi)
+
+        return ValueRange(
+            lo=lo,
+            hi=hi,
+            non_zero=a.non_zero or b.non_zero,
+        )
+
+    def with_non_zero(self, nz: bool = True) -> ValueRange:
+        """Return a copy with non_zero set."""
+        if self.non_zero == nz:
+            return self
+        return ValueRange(
+            lo=self.lo, hi=self.hi,
+            non_zero=nz, hi_len_of=self.hi_len_of,
+        )
+
+    def with_lo(self, lo: int) -> ValueRange:
+        """Return a copy with lo tightened (only if stricter)."""
+        current_lo = self.lo
+        if current_lo is not None and current_lo >= lo:
+            return self
+        nz = self.non_zero or lo > 0
+        return ValueRange(
+            lo=lo, hi=self.hi,
+            non_zero=nz, hi_len_of=self.hi_len_of,
+        )
+
+    def with_hi(self, hi: int) -> ValueRange:
+        """Return a copy with hi tightened (only if stricter)."""
+        current_hi = self.hi
+        if current_hi is not None and current_hi <= hi:
+            return self
+        nz = self.non_zero or (self.lo is not None and self.lo > 0)
+        return ValueRange(
+            lo=self.lo, hi=hi,
+            non_zero=nz, hi_len_of=None,
+        )
+
+    def with_hi_len_of(self, container: str) -> ValueRange:
+        """Return a copy with symbolic upper bound."""
+        return ValueRange(
+            lo=self.lo, hi=None,
+            non_zero=self.non_zero, hi_len_of=container,
+        )

tpyc/symbol_binding.py

@@ -0,0 +1,259 @@
+"""Per-module attribute table.
+
+A single `dict[str, BindingCell]` per module, indexed by short local
+name. Each cell holds a `SymbolBinding` describing what the name
+refers to: kind (function / record / protocol / ...), the canonical
+Info object, and the (defining_module, canonical_name) pair the
+codegen `qualify_imported()` helper turns into a C++ qname.
+
+Cells are mutable indirections so peer references captured during
+pre-population stay live as the binding's payload Info object is
+filled in by the registration paths. The binding itself is frozen --
+identity refinement, when needed, happens by rebinding the cell's
+`.binding` slot.
+
+See docs/MUTUAL_IMPORTS_DESIGN.md "Universal re-export via per-module
+attribute table" for the full design.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class SymbolKind(Enum):
+    FUNCTION = "function"
+    RECORD = "record"
+    PROTOCOL_STATIC = "protocol_static"
+    PROTOCOL_DYNAMIC = "protocol_dynamic"
+    ENUM = "enum"
+    VARIABLE = "variable"
+    TYPE_ALIAS = "type_alias"
+    MODULE = "module"
+    SUBMODULE = "submodule"
+    CLASS_MACRO = "class_macro"
+    CALL_MACRO = "call_macro"
+    BUILDER_MACRO = "builder_macro"
+    PARSER_KEYWORD = "parser_keyword"
+    OPAQUE = "opaque"
+
+
+@dataclass(frozen=True)
+class SymbolBinding:
+    """One name in a module's attribute table.
+
+    `info` holds the canonical Info object for the binding's kind:
+      FUNCTION              -> list[FunctionInfo]
+      RECORD                -> RecordInfo
+      PROTOCOL_*            -> ProtocolInfo
+      ENUM                  -> NominalType (enum-kind)
+      VARIABLE              -> TpyType (var's declared type)
+      TYPE_ALIAS            -> TpyType (alias body)
+      MODULE / SUBMODULE    -> ModuleInfo (or None for special modules)
+      CLASS_MACRO / ...     -> macro registration object
+      PARSER_KEYWORD        -> None
+      OPAQUE                -> None
+
+    `defining_module` is None when the symbol is locally defined in the
+    module that owns this binding. For imports/re-exports it's the
+    *ultimate* defining module (chain-flattened): records use
+    `record_info.defining_module`, enums use `EnumInfo.module_name`,
+    functions use `FunctionInfo.originating_module`, variables use
+    the second pre-pop pass's chain-walk.
+
+    `canonical_name` is the symbol's name in the defining module
+    (== local_name when no aliasing).
+    """
+    local_name: str
+    kind: SymbolKind
+    info: object
+    defining_module: str | None
+    canonical_name: str
+
+
+@dataclass
+class BindingCell:
+    """Mutable indirection wrapping a `SymbolBinding`.
+
+    Cells are the stable references peers capture during
+    `bind_imports`; the cell's `.binding` slot may be rebound when
+    the same name is re-installed (e.g. a local definition shadowing
+    an earlier import in source order, or a registration path
+    refining a pre-pop'd skeleton). The binding objects themselves
+    stay frozen.
+    """
+    binding: SymbolBinding
+
+
+def make_binding(
+    local_name: str,
+    kind: SymbolKind,
+    info: object,
+    *,
+    defining_module: str | None = None,
+    canonical_name: str | None = None,
+) -> SymbolBinding:
+    return SymbolBinding(
+        local_name=local_name,
+        kind=kind,
+        info=info,
+        defining_module=defining_module,
+        canonical_name=canonical_name if canonical_name is not None else local_name,
+    )
+
+
+def install_binding(
+    table: 'dict[str, BindingCell] | None',
+    local_name: str,
+    kind: SymbolKind,
+    info: object,
+    *,
+    defining_module: str | None = None,
+    canonical_name: str | None = None,
+) -> None:
+    """Install or replace an entry in the attribute table.
+
+    No-op when `table` is None (some analyzer constructions don't have
+    one -- e.g. ad-hoc tests / REPL).
+
+    Cells are mutated in place when they already exist, preserving the
+    cell identity peer modules may have captured during `bind_imports`.
+    """
+    if table is None:
+        return
+    binding = make_binding(
+        local_name, kind, info,
+        defining_module=defining_module,
+        canonical_name=canonical_name,
+    )
+    cell = table.get(local_name)
+    if cell is None:
+        table[local_name] = BindingCell(binding=binding)
+    else:
+        cell.binding = binding
+
+
+def protocol_kind_for(is_dynamic: bool) -> SymbolKind:
+    return SymbolKind.PROTOCOL_DYNAMIC if is_dynamic else SymbolKind.PROTOCOL_STATIC
+
+
+def qualify_imported(binding: SymbolBinding, current_module: str) -> tuple[str, str]:
+    """Return the (module, canonical_name) pair to use when emitting a
+    use-site reference to `binding` from inside `current_module`.
+
+    The result is the input to `qualified_cpp_name(...)`; callers that
+    want the rendered C++ string take that extra step so this helper
+    stays free of the codegen-context import.
+    """
+    if binding.defining_module is None:
+        return (current_module, binding.canonical_name)
+    return (binding.defining_module, binding.canonical_name)
+
+
+def lookup_qualified(
+    table: 'dict[str, BindingCell] | None', name: str, current_module: str,
+) -> 'tuple[str, str] | None':
+    """Convenience for the common codegen pattern: fetch the cell from
+    `table` and pass its binding through `qualify_imported`. Returns
+    None when the table is missing or the name isn't bound, leaving
+    the caller's fallback path in charge.
+    """
+    if table is None:
+        return None
+    cell = table.get(name)
+    if cell is None:
+        return None
+    return qualify_imported(cell.binding, current_module)
+
+
+def lookup_imported(
+    table: 'dict[str, BindingCell] | None', name: str, *kinds: SymbolKind,
+) -> 'tuple[str, str] | None':
+    """Return `(defining_module, canonical_name)` when `name` is bound as
+    an *imported* symbol of one of `kinds` -- i.e. the cell exists, kind
+    matches, and the binding has a non-None `defining_module`. Returns
+    None for local definitions, kind mismatches, missing entries, and a
+    None table.
+    """
+    if table is None:
+        return None
+    cell = table.get(name)
+    if cell is None:
+        return None
+    bd = cell.binding
+    if bd.defining_module is None:
+        return None
+    if kinds and bd.kind not in kinds:
+        return None
+    return (bd.defining_module, bd.canonical_name)
+
+
+def resolve_definer(
+    registry, module_name: str, name: str, *kinds: SymbolKind,
+) -> tuple[str, str]:
+    """Return the (definer_module, definer_name) for `name` as bound in
+    `module_name`'s attribute table, or `(module_name, name)` if the
+    cell is missing / locally-defined / kind-mismatched.
+
+    `registry` only needs `get_module(name) -> object | None`; the
+    returned object only needs a `module_attributes` attribute that's
+    a `dict | None`. Works equally with the sema `TypeRegistry` and the
+    `Compiler`'s `modules` dict via a thin adapter.
+    """
+    mi = registry.get_module(module_name)
+    if mi is None:
+        return (module_name, name)
+    table = getattr(mi, "module_attributes", None)
+    imp = lookup_imported(table, name, *kinds)
+    if imp is None:
+        return (module_name, name)
+    return imp
+
+
+def walk_attribute_chain(
+    registry, module_name: str, name: str,
+    accept,  # Callable[[SymbolBinding], bool]
+) -> 'tuple[str, str, SymbolBinding] | None':
+    """Walk the `module_attributes` chain across `registry`'s modules
+    until `accept(binding)` returns True or the chain dead-ends.
+
+    Returns `(defining_module_or_current, canonical_name, binding)` for
+    the accepted cell, or None when no hop matches. `registry` only
+    needs `get_module(name) -> ModuleInfo | None` -- works equally with
+    `TypeRegistry` (sema) and `Compiler` (with a wrapper).
+    """
+    visited: set[tuple[str, str]] = set()
+    cur_mod, cur_name = module_name, name
+    while True:
+        key = (cur_mod, cur_name)
+        if key in visited:
+            return None
+        visited.add(key)
+        mi = registry.get_module(cur_mod)
+        if mi is None or mi.module_attributes is None:
+            return None
+        cell = mi.module_attributes.get(cur_name)
+        if cell is None:
+            return None
+        bd = cell.binding
+        if accept(bd):
+            return (bd.defining_module or cur_mod, bd.canonical_name, bd)
+        if bd.defining_module is None:
+            return None
+        cur_mod, cur_name = bd.defining_module, bd.canonical_name
+
+
+_MACRO_KINDS = frozenset({
+    SymbolKind.CLASS_MACRO, SymbolKind.CALL_MACRO, SymbolKind.BUILDER_MACRO,
+})
+
+
+def is_macro_kind(binding: SymbolBinding) -> bool:
+    return binding.kind in _MACRO_KINDS
+
+
+def is_kind(*kinds: SymbolKind):
+    """Return an `accept` predicate matching any of `kinds`."""
+    s = frozenset(kinds)
+    return lambda bd: bd.kind in s

tpyc/test_c3_mro.py

@@ -0,0 +1,208 @@
+"""C3 linearization and diamond detection invariants (D22 prep).
+
+The multi-base path is still gated in sema, so these tests exercise
+`c3_linearize`, `TypeRegistry.compute_mro_ancestors`, and
+`TypeRegistry.detect_diamond` directly. Once D22 lifts the gate, the
+algorithms these tests pin down start running in production.
+"""
+from __future__ import annotations
+
+import pytest
+
+from tpyc.typesys import (
+    NominalType, RecordInfo, TypeRegistry,
+    c3_linearize, C3LinearizationError,
+    same_nominal_symbol_loose,
+)
+from tpyc.type_def_registry import (
+    attach_dynamic_type_def, TypeCategory, clear_dynamic_type_defs,
+)
+
+
+@pytest.fixture(autouse=True)
+def _cleanup():
+    yield
+    clear_dynamic_type_defs()
+
+
+def _nom(name: str) -> NominalType:
+    """NominalType with qname set so is_user_record resolves via the attached TypeDef."""
+    return NominalType(name, _module_qname=f"m.{name}")
+
+
+def _record(name: str, parents: list[NominalType], mro_ancestors: list[NominalType]) -> RecordInfo:
+    info = RecordInfo(
+        name=name, fields=[], module="m",
+        parents=list(parents),
+        mro_ancestors=list(mro_ancestors),
+    )
+    attach_dynamic_type_def(
+        info.qualified_name(),
+        TypeCategory.RECORD,
+        record=info,
+        is_value_type=False,
+    )
+    return info
+
+
+def _type_names(types: list) -> list[str]:
+    return [t.name for t in types]
+
+
+# ---------------------------------------------------------------------------
+# c3_linearize: pure algorithm
+# ---------------------------------------------------------------------------
+
+class TestC3Linearize:
+    def test_empty_bases(self) -> None:
+        assert c3_linearize([]) == []
+
+    def test_single_base_no_ancestors(self) -> None:
+        """class Child(Root): -> [Root]."""
+        root = _nom("Root")
+        assert _type_names(c3_linearize([(root, [])])) == ["Root"]
+
+    def test_single_base_with_chain(self) -> None:
+        """A <- B <- C. class D(C): -> [C, B, A]."""
+        a, b, c = _nom("A"), _nom("B"), _nom("C")
+        # C's own ancestry: [B, A]
+        result = c3_linearize([(c, [b, a])])
+        assert _type_names(result) == ["C", "B", "A"]
+
+    def test_non_diamond_two_parents(self) -> None:
+        """class D(B, C): with B(A), C: -> [B, A, C]."""
+        a, b, c = _nom("A"), _nom("B"), _nom("C")
+        result = c3_linearize([(b, [a]), (c, [])])
+        assert _type_names(result) == ["B", "A", "C"]
+
+    def test_canonical_diamond_c3(self) -> None:
+        """Canonical C3: O <- A, O <- B, A <- X(A, B), result should include A then B.
+
+        This is a 'diamond-free' compose since A and B don't share an ancestor in
+        this reduced form. Here: class D(B, C) where B(A), C(A) -- A is shared.
+        C3 linearizes this as [B, C, A], but our detect_diamond rejects it.
+        The linearization algorithm itself is permissive.
+        """
+        a, b, c = _nom("A"), _nom("B"), _nom("C")
+        # B.mro_ancestors = [A], C.mro_ancestors = [A]
+        result = c3_linearize([(b, [a]), (c, [a])])
+        assert _type_names(result) == ["B", "C", "A"]
+
+    def test_inconsistent_hierarchy_raises(self) -> None:
+        """class X(A, B) where A's MRO says [A, P, Q] and B's says [B, Q, P] -- no valid linearization."""
+        a, b, p, q = _nom("A"), _nom("B"), _nom("P"), _nom("Q")
+        with pytest.raises(C3LinearizationError):
+            c3_linearize([(a, [p, q]), (b, [q, p])])
+
+    def test_duplicate_direct_bases_raises(self) -> None:
+        """class D(B, B) -- same base listed twice is inconsistent."""
+        b = _nom("B")
+        with pytest.raises(C3LinearizationError):
+            c3_linearize([(b, []), (b, [])])
+
+
+# ---------------------------------------------------------------------------
+# TypeRegistry.compute_mro_ancestors + detect_diamond
+# ---------------------------------------------------------------------------
+
+class TestRegistryMRO:
+    def test_leaf_record_mro_empty(self) -> None:
+        reg = TypeRegistry()
+        a = _record("A", parents=[], mro_ancestors=[])
+        reg.register_record(a)
+        assert reg.compute_mro_ancestors(a) == []
+
+    def test_single_parent_linear(self) -> None:
+        reg = TypeRegistry()
+        a = _record("A", parents=[], mro_ancestors=[])
+        reg.register_record(a)
+        a_ref = _nom("A")
+        b = _record("B", parents=[a_ref], mro_ancestors=[a_ref])
+        reg.register_record(b)
+        b_ref = _nom("B")
+        c = _record("C", parents=[b_ref], mro_ancestors=[])
+        reg.register_record(c)
+        result = reg.compute_mro_ancestors(c)
+        assert _type_names(result) == ["B", "A"]
+
+    def test_multi_parent_no_diamond(self) -> None:
+        reg = TypeRegistry()
+        a = _record("A", parents=[], mro_ancestors=[])
+        reg.register_record(a)
+        b = _record("B", parents=[], mro_ancestors=[])
+        reg.register_record(b)
+        a_ref, b_ref = _nom("A"), _nom("B")
+        d = _record("D", parents=[a_ref, b_ref], mro_ancestors=[])
+        reg.register_record(d)
+        result = reg.compute_mro_ancestors(d)
+        assert _type_names(result) == ["A", "B"]
+
+
+class TestDiamondDetection:
+    def test_single_parent_no_diamond(self) -> None:
+        reg = TypeRegistry()
+        a = _record("A", parents=[], mro_ancestors=[])
+        reg.register_record(a)
+        a_ref = _nom("A")
+        b = _record("B", parents=[a_ref], mro_ancestors=[a_ref])
+        reg.register_record(b)
+        assert reg.detect_diamond(b) is None
+
+    def test_unrelated_multi_parent_no_diamond(self) -> None:
+        reg = TypeRegistry()
+        a = _record("A", parents=[], mro_ancestors=[])
+        b = _record("B", parents=[], mro_ancestors=[])
+        reg.register_record(a)
+        reg.register_record(b)
+        d = _record("D", parents=[_nom("A"), _nom("B")], mro_ancestors=[])
+        reg.register_record(d)
+        assert reg.detect_diamond(d) is None
+
+    def test_classic_diamond_detected(self) -> None:
+        """A at top; B(A), C(A); D(B, C) -- A is reachable via both B and C."""
+        reg = TypeRegistry()
+        a = _record("A", parents=[], mro_ancestors=[])
+        reg.register_record(a)
+        a_ref = _nom("A")
+        b = _record("B", parents=[a_ref], mro_ancestors=[a_ref])
+        c = _record("C", parents=[a_ref], mro_ancestors=[a_ref])
+        reg.register_record(b)
+        reg.register_record(c)
+        d = _record("D", parents=[_nom("B"), _nom("C")], mro_ancestors=[])
+        reg.register_record(d)
+
+        diamond = reg.detect_diamond(d)
+        assert diamond is not None
+        anc, p1, p2 = diamond
+        assert anc == "A"
+        assert {p1, p2} == {"B", "C"}
+
+    def test_direct_and_indirect_parent_is_diamond(self) -> None:
+        """class C(A, B) where B(A) -- A is both a direct base and an ancestor of B."""
+        reg = TypeRegistry()
+        a = _record("A", parents=[], mro_ancestors=[])
+        reg.register_record(a)
+        a_ref = _nom("A")
+        b = _record("B", parents=[a_ref], mro_ancestors=[a_ref])
+        reg.register_record(b)
+        c = _record("C", parents=[a_ref, _nom("B")], mro_ancestors=[])
+        reg.register_record(c)
+
+        diamond = reg.detect_diamond(c)
+        assert diamond is not None
+        anc, p1, p2 = diamond
+        assert anc == "A"
+        assert {p1, p2} == {"A", "B"}
+
+    def test_duplicate_direct_parent_is_diamond(self) -> None:
+        """class D(B, B) -- same parent listed twice."""
+        reg = TypeRegistry()
+        b = _record("B", parents=[], mro_ancestors=[])
+        reg.register_record(b)
+        b_ref = _nom("B")
+        d = _record("D", parents=[b_ref, b_ref], mro_ancestors=[])
+        reg.register_record(d)
+
+        diamond = reg.detect_diamond(d)
+        assert diamond is not None
+        assert diamond[0] == "B"

tpyc/test_cli_argv.py

@@ -0,0 +1,52 @@
+"""Unit tests for tpyc argv pre-split helper."""
+
+import pytest
+
+from .cli import _split_tpyc_argv
+
+
+def test_no_separator_returns_empty_script_args():
+    assert _split_tpyc_argv(["foo.py", "-o", "out/"]) == (["foo.py", "-o", "out/"], [])
+
+
+def test_empty_argv():
+    assert _split_tpyc_argv([]) == ([], [])
+
+
+def test_separator_at_end_yields_empty_script_args():
+    assert _split_tpyc_argv(["foo.py", "-x", "--"]) == (["foo.py", "-x"], [])
+
+
+def test_separator_splits_compiler_and_program_args():
+    before, after = _split_tpyc_argv(["foo.py", "-x", "--", "a", "b"])
+    assert before == ["foo.py", "-x"]
+    assert after == ["a", "b"]
+
+
+def test_tpyc_flags_preserved_before_separator():
+    before, after = _split_tpyc_argv(["foo.py", "-o", "out/", "--pcre2=none", "-x", "--", "arg"])
+    assert before == ["foo.py", "-o", "out/", "--pcre2=none", "-x"]
+    assert after == ["arg"]
+
+
+def test_multiple_dash_dash_only_first_is_separator():
+    before, after = _split_tpyc_argv(["foo.py", "-x", "--", "a", "--", "b"])
+    assert before == ["foo.py", "-x"]
+    assert after == ["a", "--", "b"]
+
+
+def test_leading_separator_with_trailing_tokens_rejected():
+    with pytest.raises(ValueError, match="input file must appear before"):
+        _split_tpyc_argv(["--", "foo.py"])
+
+
+def test_only_separator_passes_through():
+    # `tpyc --` alone: no trailing tokens, so nothing to reject. argparse will
+    # then fail with "required: input" which is the right error for this shape.
+    assert _split_tpyc_argv(["--"]) == ([], [])
+
+
+def test_flag_like_program_args_preserved():
+    before, after = _split_tpyc_argv(["foo.py", "-x", "--", "-O", "--help", "-"])
+    assert before == ["foo.py", "-x"]
+    assert after == ["-O", "--help", "-"]