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

tpyc/test_parse_type_ref.py

@@ -0,0 +1,506 @@
+"""Tests for the syntactic type-ref walker (Phase F.3b.1).
+
+Verifies that `Parser._parse_type_ref` produces the expected TypeRefNode
+shape for representative Python type annotations. The resolver
+(F.3b.2+) is out of scope for this test -- here we only pin the
+syntactic output.
+"""
+
+from __future__ import annotations
+import ast
+
+import pytest
+
+from .parse import (
+    Parser, ParseError,
+    TpyTypeRef, TpyUnionRef, TpyCallableRef, TpyLiteralRef,
+)
+from .typesys import LiteralValue, LiteralTag
+
+
+def _make_parser() -> Parser:
+    """Create a parser with imports that enable all structural-wrapper
+    recognition paths plus primitive names."""
+    parser = Parser()
+    parser.parse(
+        "from tpy import Ptr, Own, readonly, auto_readonly, auto_own, Fn\n"
+        "from tpy import (Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64,\n"
+        "                 Char, Float32, String, StrView, BytesView,\n"
+        "                 basic_slice, slice, Array, Span)\n"
+        "from typing import Optional, Final, Callable, Literal, Self\n"
+        "pass\n",
+        module_name="test_module",
+    )
+    return parser
+
+
+def _parse_ann(parser: Parser, annotation_src: str):
+    """Parse a type annotation source fragment into a TypeRefNode."""
+    tree = ast.parse(f"x: {annotation_src}\n")
+    ann_node = tree.body[0].annotation
+    return parser._parse_type_ref(ann_node)
+
+
+class TestLeafNames:
+    def test_bare_name(self):
+        ref = _parse_ann(_make_parser(), "Int32")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "Int32"
+        assert ref.args == ()
+
+    def test_user_record_name(self):
+        ref = _parse_ann(_make_parser(), "MyRecord")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "MyRecord"
+        assert ref.args == ()
+
+    def test_none_constant(self):
+        ref = _parse_ann(_make_parser(), "None")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "None"
+
+    def test_dotted_attribute(self):
+        ref = _parse_ann(_make_parser(), "Outer.Inner")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "Outer.Inner"
+        assert ref.args == ()
+
+    def test_deep_dotted(self):
+        ref = _parse_ann(_make_parser(), "a.b.c.D")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "a.b.c.D"
+
+
+class TestGenerics:
+    def test_list_of_int(self):
+        ref = _parse_ann(_make_parser(), "list[Int32]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "list"
+        assert len(ref.args) == 1
+        inner = ref.args[0]
+        assert isinstance(inner, TpyTypeRef) and inner.name == "Int32"
+
+    def test_dict_of_str_int(self):
+        ref = _parse_ann(_make_parser(), "dict[str, Int32]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "dict"
+        assert len(ref.args) == 2
+        k, v = ref.args
+        assert isinstance(k, TpyTypeRef) and k.name == "str"
+        assert isinstance(v, TpyTypeRef) and v.name == "Int32"
+
+    def test_array_with_int_size(self):
+        ref = _parse_ann(_make_parser(), "Array[Int32, 8]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "Array"
+        assert len(ref.args) == 2
+        elem, size = ref.args
+        assert isinstance(elem, TpyTypeRef) and elem.name == "Int32"
+        assert size == 8
+
+    def test_nested_generic(self):
+        ref = _parse_ann(_make_parser(), "list[dict[str, Int32]]")
+        assert isinstance(ref, TpyTypeRef) and ref.name == "list"
+        outer_arg = ref.args[0]
+        assert isinstance(outer_arg, TpyTypeRef) and outer_arg.name == "dict"
+        k, v = outer_arg.args
+        assert isinstance(k, TpyTypeRef) and k.name == "str"
+        assert isinstance(v, TpyTypeRef) and v.name == "Int32"
+
+    def test_user_generic_record(self):
+        ref = _parse_ann(_make_parser(), "Stack[Int32]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "Stack"
+        assert len(ref.args) == 1
+        assert isinstance(ref.args[0], TpyTypeRef) and ref.args[0].name == "Int32"
+
+
+class TestStructuralWrappers:
+    # Canonical structural wrappers use qualified names ("tpy:Ptr",
+    # "typing:Optional", ...) so they don't collide with raw user-source
+    # names like "Ptr" or "Optional" (the resolver's wrapper dispatch must
+    # only fire when the walker confirmed module resolution).
+
+    def test_ptr(self):
+        ref = _parse_ann(_make_parser(), "Ptr[Int32]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "tpy:Ptr"
+        assert len(ref.args) == 1
+        assert isinstance(ref.args[0], TpyTypeRef) and ref.args[0].name == "Int32"
+
+    def test_own(self):
+        ref = _parse_ann(_make_parser(), "Own[MyRecord]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "tpy:Own"
+
+    def test_readonly(self):
+        ref = _parse_ann(_make_parser(), "readonly[Int32]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "tpy:readonly"
+
+    def test_auto_readonly(self):
+        ref = _parse_ann(_make_parser(), "auto_readonly[Int32]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "tpy:auto_readonly"
+
+    def test_auto_own(self):
+        ref = _parse_ann(_make_parser(), "auto_own[MyRecord]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "tpy:auto_own"
+
+    def test_optional(self):
+        ref = _parse_ann(_make_parser(), "Optional[Int32]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "typing:Optional"
+
+    def test_final(self):
+        ref = _parse_ann(_make_parser(), "Final[Int32]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "typing:Final"
+
+    def test_ptr_of_readonly(self):
+        # Ptr[readonly[Int32]] -- readonly nested under Ptr.
+        # The resolver applies Ptr.is_readonly; walker just records structure.
+        ref = _parse_ann(_make_parser(), "Ptr[readonly[Int32]]")
+        assert isinstance(ref, TpyTypeRef) and ref.name == "tpy:Ptr"
+        inner = ref.args[0]
+        assert isinstance(inner, TpyTypeRef) and inner.name == "tpy:readonly"
+        leaf = inner.args[0]
+        assert isinstance(leaf, TpyTypeRef) and leaf.name == "Int32"
+
+
+class TestTuple:
+    def test_empty_tuple_allowed_syntactically(self):
+        # Parser-level: tuple with no args is syntactically valid here; the
+        # resolver raises.
+        ref = _parse_ann(_make_parser(), "tuple[Int32]")
+        assert isinstance(ref, TpyTypeRef) and ref.name == "builtins:tuple"
+        assert len(ref.args) == 1
+
+    def test_tuple_multiple(self):
+        ref = _parse_ann(_make_parser(), "tuple[Int32, str, bool]")
+        assert isinstance(ref, TpyTypeRef) and ref.name == "builtins:tuple"
+        assert len(ref.args) == 3
+        assert all(isinstance(a, TpyTypeRef) for a in ref.args)
+
+
+class TestUnion:
+    def test_simple_union(self):
+        ref = _parse_ann(_make_parser(), "Int32 | str")
+        assert isinstance(ref, TpyUnionRef)
+        assert len(ref.members) == 2
+        a, b = ref.members
+        assert isinstance(a, TpyTypeRef) and a.name == "Int32"
+        assert isinstance(b, TpyTypeRef) and b.name == "str"
+
+    def test_union_with_none(self):
+        ref = _parse_ann(_make_parser(), "Int32 | None")
+        assert isinstance(ref, TpyUnionRef)
+        assert len(ref.members) == 2
+
+    def test_three_way_union(self):
+        ref = _parse_ann(_make_parser(), "Int32 | str | bool")
+        assert isinstance(ref, TpyUnionRef)
+        assert len(ref.members) == 3
+
+
+class TestCallable:
+    def test_callable(self):
+        ref = _parse_ann(_make_parser(), "Callable[[Int32, str], bool]")
+        assert isinstance(ref, TpyCallableRef)
+        assert ref.kind == "Callable"
+        assert len(ref.params) == 2
+        assert isinstance(ref.params[0], TpyTypeRef) and ref.params[0].name == "Int32"
+        assert isinstance(ref.params[1], TpyTypeRef) and ref.params[1].name == "str"
+        assert isinstance(ref.return_type, TpyTypeRef)
+        assert ref.return_type.name == "bool"
+
+    def test_fn(self):
+        ref = _parse_ann(_make_parser(), "Fn[[Int32], bool]")
+        assert isinstance(ref, TpyCallableRef)
+        assert ref.kind == "Fn"
+        assert len(ref.params) == 1
+
+    def test_callable_no_params(self):
+        ref = _parse_ann(_make_parser(), "Callable[[], None]")
+        assert isinstance(ref, TpyCallableRef)
+        assert ref.kind == "Callable"
+        assert ref.params == ()
+
+    def test_callable_malformed_missing_list(self):
+        with pytest.raises(ParseError, match="parameter types must be a list"):
+            _parse_ann(_make_parser(), "Callable[Int32, bool]")
+
+
+class TestLiteral:
+    def test_str_literal(self):
+        ref = _parse_ann(_make_parser(), 'Literal["a", "b"]')
+        assert isinstance(ref, TpyLiteralRef)
+        assert ref.values == (LiteralValue(LiteralTag.STR, "a"), LiteralValue(LiteralTag.STR, "b"))
+
+    def test_int_literal(self):
+        ref = _parse_ann(_make_parser(), "Literal[1, 2, 3]")
+        assert isinstance(ref, TpyLiteralRef)
+        assert ref.values == (
+            LiteralValue(LiteralTag.INT, 1), LiteralValue(LiteralTag.INT, 2), LiteralValue(LiteralTag.INT, 3),
+        )
+
+    def test_bool_literal(self):
+        ref = _parse_ann(_make_parser(), "Literal[True, False]")
+        assert isinstance(ref, TpyLiteralRef)
+        assert ref.values == (LiteralValue(LiteralTag.BOOL, True), LiteralValue(LiteralTag.BOOL, False))
+
+    def test_negative_int_literal(self):
+        ref = _parse_ann(_make_parser(), "Literal[-5]")
+        assert isinstance(ref, TpyLiteralRef)
+        assert ref.values == (LiteralValue(LiteralTag.INT, -5),)
+
+    def test_mixed_types_rejected(self):
+        with pytest.raises(ParseError, match="Literal cannot mix value types"):
+            _parse_ann(_make_parser(), 'Literal["a", 1]')
+
+
+class TestUnknownName:
+    def test_unknown_name_does_not_raise(self):
+        # The resolver is what raises "Unknown type". The walker is permissive.
+        ref = _parse_ann(_make_parser(), "TotallyUnknownName")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "TotallyUnknownName"
+
+    def test_unknown_generic_does_not_raise(self):
+        ref = _parse_ann(_make_parser(), "UnknownGeneric[Int32]")
+        assert isinstance(ref, TpyTypeRef)
+        assert ref.name == "UnknownGeneric"
+
+
+class TestLoc:
+    def test_loc_populated(self):
+        ref = _parse_ann(_make_parser(), "Int32")
+        assert ref.loc is not None
+        assert ref.loc.line == 1
+
+
+# --- F.3b.2: equivalence of _resolve_type_ref_impl with _parse_type_annotation
+# For every case below, walking + resolving a TypeRefNode must produce the
+# same TpyType as the direct parse. The resolver is dead code at this point
+# (no call sites), but this test pins equivalence before F.3b.3 flips the
+# entry point.
+
+def _ann_tree(annotation_src: str):
+    tree = ast.parse(f"x: {annotation_src}\n")
+    return tree.body[0].annotation
+
+
+def _equiv(parser: Parser, annotation_src: str, type_param_scope=None):
+    """Assert _parse_type_annotation == _resolve_type_ref_impl(_parse_type_ref)."""
+    node = _ann_tree(annotation_src)
+    expected = parser._parse_type_annotation(node, type_param_scope)
+    ref = parser._parse_type_ref(node, type_param_scope)
+    actual = parser._resolve_type_ref_impl(ref, type_param_scope)
+    assert expected == actual, (
+        f"Mismatch for {annotation_src!r}:\n  expected: {expected}\n  actual:   {actual}"
+    )
+    return expected
+
+
+class TestResolverEquivalence:
+    @pytest.mark.parametrize("src", [
+        # Primitives
+        "Int32", "Int8", "Int16", "Int64",
+        "UInt8", "UInt16", "UInt32", "UInt64",
+        "int", "float", "Float32", "bool",
+        "str", "bytes", "bytearray", "String", "StrView", "BytesView",
+        "Char", "None",
+        # Slice types
+        "basic_slice", "slice",
+    ])
+    def test_primitives(self, src):
+        _equiv(_make_parser(), src)
+
+    @pytest.mark.parametrize("src", [
+        "list[Int32]",
+        "list[str]",
+        "dict[str, Int32]",
+        "dict[Int32, str]",
+        "set[Int32]",
+        "tuple[Int32]",
+        "tuple[Int32, str]",
+        "tuple[Int32, str, bool]",
+        "Array[Int32, 8]",
+        "Array[str, 16]",
+        "Span[Int32]",
+        "Span[readonly[Int32]]",
+    ])
+    def test_generics(self, src):
+        _equiv(_make_parser(), src)
+
+    @pytest.mark.parametrize("src", [
+        "Ptr[Int32]",
+        "Ptr[readonly[Int32]]",
+        "Own[list[Int32]]",
+        "readonly[Int32]",
+        "auto_readonly[Int32]",
+        "auto_own[list[Int32]]",
+        "Optional[Int32]",
+        "Optional[Ptr[Int32]]",
+        "Final[Int32]",
+    ])
+    def test_structural_wrappers(self, src):
+        _equiv(_make_parser(), src)
+
+    @pytest.mark.parametrize("src", [
+        "Int32 | str",
+        "Int32 | None",
+        "Int32 | str | bool",
+        "Ptr[Int32] | None",
+        "Optional[Int32]",
+        "list[Int32] | None",
+    ])
+    def test_unions(self, src):
+        _equiv(_make_parser(), src)
+
+    @pytest.mark.parametrize("src", [
+        "Callable[[Int32], bool]",
+        "Callable[[Int32, str], bool]",
+        "Callable[[], None]",
+        "Fn[[Int32], bool]",
+        "Fn[[], None]",
+    ])
+    def test_callable(self, src):
+        _equiv(_make_parser(), src)
+
+    @pytest.mark.parametrize("src", [
+        'Literal["a", "b"]',
+        "Literal[1, 2, 3]",
+        "Literal[-5]",
+        "Literal[True, False]",
+    ])
+    def test_literal(self, src):
+        _equiv(_make_parser(), src)
+
+    @pytest.mark.parametrize("src", [
+        # Nested generics + wrappers
+        "list[Ptr[Int32]]",
+        "dict[str, list[Int32]]",
+        "Optional[list[Int32]]",
+        "list[tuple[Int32, str]]",
+        "Callable[[list[Int32]], Optional[str]]",
+    ])
+    def test_nested(self, src):
+        _equiv(_make_parser(), src)
+
+    def test_type_param_ref(self):
+        parser = _make_parser()
+        from .typesys import TypeParamKind
+        scope = {"T": TypeParamKind.TYPE}
+        _equiv(parser, "T", scope)
+        _equiv(parser, "list[T]", scope)
+        _equiv(parser, "Ptr[T]", scope)
+        _equiv(parser, "T | None", scope)
+        # Type params in nested / variable-arity forms
+        _equiv(parser, "dict[str, T]", scope)
+        _equiv(parser, "Optional[T]", scope)
+        _equiv(parser, "Fn[[T], bool]", scope)
+        _equiv(parser, "auto_readonly[T]", scope)
+        _equiv(parser, "Own[T]", scope)
+
+    def test_int_type_param_ref(self):
+        parser = _make_parser()
+        from .typesys import TypeParamKind
+        scope = {"T": TypeParamKind.TYPE, "N": TypeParamKind.INT}
+        _equiv(parser, "Array[T, N]", scope)
+
+    @pytest.mark.parametrize("src", [
+        "Self",
+        "Ptr[Self]",
+        "Optional[Self]",
+        "list[Self]",
+    ])
+    def test_self_type(self, src):
+        _equiv(_make_parser(), src)
+
+
+class TestResolverErrors:
+    def test_unknown_type_raises(self):
+        from .typesys import TypeParamKind
+        parser = _make_parser()
+        node = _ann_tree("TotallyUnknownName")
+        ref = parser._parse_type_ref(node)
+        with pytest.raises(ParseError, match="Unknown type"):
+            parser._resolve_type_ref_impl(ref)
+
+    def test_unknown_generic_raises(self):
+        parser = _make_parser()
+        node = _ann_tree("UnknownGeneric[Int32]")
+        ref = parser._parse_type_ref(node)
+        with pytest.raises(ParseError, match="Unknown generic type"):
+            parser._resolve_type_ref_impl(ref)
+
+    def test_error_lineno_preserved(self):
+        """Errors raised from the resolver use ref.loc to set lineno, matching
+        the ast-based path."""
+        parser = _make_parser()
+        # Build annotation on line 3
+        tree = ast.parse("pass\npass\nx: UnknownName\n")
+        node = tree.body[2].annotation
+        # Direct parse raises with lineno=3
+        try:
+            parser._parse_type_annotation(node)
+            assert False, "should have raised"
+        except ParseError as e:
+            expected_lineno = e.lineno
+        # Resolver path raises with same lineno
+        ref = parser._parse_type_ref(node)
+        try:
+            parser._resolve_type_ref_impl(ref)
+            assert False, "should have raised"
+        except ParseError as e:
+            assert e.lineno == expected_lineno
+
+
+class TestResolverLenient:
+    """Pin `TypeResolver.resolve_lenient` message-pattern fallback.
+
+    The lenient resolver catches three specific error message patterns
+    ("Unknown type", "Unknown generic type", "Unsupported qualified type")
+    and falls back to a NominalType placeholder. The error sites carry
+    LOAD-BEARING-MESSAGE markers; this test enforces the contract.
+    """
+
+    def test_lenient_unknown_bare_name(self):
+        from .typesys import NominalType
+        parser = _make_parser()
+        node = _ann_tree("TotallyUnknownName")
+        ref = parser._parse_type_ref(node)
+        # Strict resolver raises.
+        with pytest.raises(ParseError, match="Unknown type"):
+            parser._resolve_type_ref_impl(ref)
+        # Lenient resolver returns a NominalType placeholder.
+        result = parser._resolver.resolve_lenient(ref)
+        assert isinstance(result, NominalType)
+        assert result.name == "TotallyUnknownName"
+        assert result.type_args == ()
+
+    def test_lenient_unknown_generic_with_args(self):
+        from .typesys import NominalType, INT32
+        parser = _make_parser()
+        node = _ann_tree("UnknownGeneric[Int32]")
+        ref = parser._parse_type_ref(node)
+        with pytest.raises(ParseError, match="Unknown generic type"):
+            parser._resolve_type_ref_impl(ref)
+        result = parser._resolver.resolve_lenient(ref)
+        assert isinstance(result, NominalType)
+        assert result.name == "UnknownGeneric"
+        # Inner Int32 resolves normally through strict path inside the
+        # lenient recursion, so type_args carries the real singleton.
+        assert result.type_args == (INT32,)
+
+    def test_lenient_still_raises_structural_errors(self):
+        """Structural errors (not name-resolution) still propagate."""
+        parser = _make_parser()
+        # Fn with wrong arity is a structural error raised by the walker,
+        # not the resolver. The walker runs first, so it raises before
+        # the lenient resolver even sees it.
+        with pytest.raises(ParseError):
+            node = _ann_tree("Fn[[Int32]]")  # Fn requires [[params], return]
+            parser._parse_type_ref(node)

tpyc/test_parse_version_info.py

@@ -0,0 +1,58 @@
+"""Unit tests for _parse_version_info in tpyc/__init__.py."""
+
+import pytest
+
+from tpyc import _parse_version_info
+
+
+def test_final_release():
+    assert _parse_version_info("0.1.0") == (0, 1, 0, "final", 0)
+    assert _parse_version_info("1.2.3") == (1, 2, 3, "final", 0)
+    assert _parse_version_info("12.34.56") == (12, 34, 56, "final", 0)
+
+
+def test_alpha():
+    assert _parse_version_info("0.1.0a1") == (0, 1, 0, "alpha", 1)
+    assert _parse_version_info("2.0.0a12") == (2, 0, 0, "alpha", 12)
+
+
+def test_beta():
+    assert _parse_version_info("0.1.0b2") == (0, 1, 0, "beta", 2)
+
+
+def test_release_candidate():
+    assert _parse_version_info("0.1.0rc1") == (0, 1, 0, "candidate", 1)
+
+
+def test_dev():
+    assert _parse_version_info("0.1.0.dev0") == (0, 1, 0, "dev", 0)
+    assert _parse_version_info("0.1.0.dev42") == (0, 1, 0, "dev", 42)
+
+
+def test_invalid_raises():
+    with pytest.raises(ValueError):
+        _parse_version_info("")
+    with pytest.raises(ValueError):
+        _parse_version_info("1.2")                  # not enough components
+    with pytest.raises(ValueError):
+        _parse_version_info("1.2.3.4")              # too many components
+    with pytest.raises(ValueError):
+        _parse_version_info("1.2.3dev0")            # missing dot before dev
+    with pytest.raises(ValueError):
+        _parse_version_info("1.2.3.a1")             # spurious dot before alpha
+    with pytest.raises(ValueError):
+        _parse_version_info("1.2.3x1")              # unknown suffix
+    with pytest.raises(ValueError):
+        _parse_version_info("v1.2.3")               # leading junk
+
+
+def test_unsupported_pep440_forms_raise():
+    # Valid PEP 440 that tpyc doesn't ship today. If tpyc ever adopts one
+    # of these forms, version_info needs a new releaselevel mapping and
+    # this test should update accordingly.
+    with pytest.raises(ValueError):
+        _parse_version_info("1.2.3.post1")          # post-release
+    with pytest.raises(ValueError):
+        _parse_version_info("1!1.2.3")              # epoch
+    with pytest.raises(ValueError):
+        _parse_version_info("1.2.3+local")          # local identifier

tpyc/test_reach_analysis.py

@@ -0,0 +1,72 @@
+"""Tests for `tpyc.module_names.module_from_qname`.
+
+Drives `#include` emission via the reached-modules set in
+`tpyc/sema/reach_analysis.py` and SCC peer detection in
+`tpyc/compiler.py`. Must not prefix-walk the qname of a record whose
+defining file diverges from its qname (e.g. `Poll` -- qname
+`tpy.coro.Poll`, body in `tpy/_core/_types.py`).
+"""
+
+from __future__ import annotations
+
+from tpyc import qnames, typesys as ts
+from tpyc.module_names import module_from_qname
+
+
+def _registry_with_modules(names: list[str], builtin: list[str] | None = None) -> ts.TypeRegistry:
+    registry = ts.TypeRegistry()
+    builtin_set = set(builtin or [])
+    for name in names:
+        registry.register_module(
+            ts.ModuleInfo(name=name, is_builtin=name in builtin_set)
+        )
+    return registry
+
+
+def test_record_with_divergent_qname_uses_record_module():
+    registry = _registry_with_modules(["tpy", "tpy.coro", "tpy._core._types"])
+    record = ts.RecordInfo(
+        name="Poll",
+        module="tpy",
+        defining_module="tpy._core._types",
+        builtin_type_key=qnames.POLL,
+        fields=[],
+        methods={},
+    )
+    registry.register_record(record)
+
+    assert module_from_qname(qnames.POLL, registry) == "tpy"
+
+
+def test_record_with_aligned_qname_still_returns_module():
+    registry = _registry_with_modules(["pkg", "pkg.sub"])
+    record = ts.RecordInfo(
+        name="Widget",
+        module="pkg.sub",
+        defining_module="pkg.sub",
+        builtin_type_key="pkg.sub.Widget",
+        fields=[],
+        methods={},
+    )
+    registry.register_record(record)
+
+    assert module_from_qname("pkg.sub.Widget", registry) == "pkg.sub"
+
+
+def test_unregistered_qname_falls_back_to_prefix_walk():
+    registry = _registry_with_modules(["pkg", "pkg.sub"])
+
+    assert module_from_qname("pkg.sub.Outer.Inner", registry) == "pkg.sub"
+    assert module_from_qname("pkg.Foo", registry) == "pkg"
+
+
+def test_unregistered_qname_with_no_module_ancestor_falls_to_first_component():
+    registry = _registry_with_modules([])
+
+    assert module_from_qname("foo.Bar", registry) == "foo"
+
+
+def test_single_component_qname_returns_none():
+    registry = _registry_with_modules([])
+
+    assert module_from_qname("BareName", registry) is None