emit_pybind.py

# SPDX-License-Identifier: BSD-3-Clause
"""IR -> pybind11 C++ emitter.

Consumes the same `BindModule` IR the Embind emitter does. The Python
extension is structured as one submodule per format (``whiteout.mdx``,
``whiteout.m2``, ``whiteout.m3``); each generated file defines one
``void bind<Module>(py::module_& m)`` function that the top-level
PYBIND11_MODULE entry calls.

Embind ↔ pybind11 mapping (key cases):

    enum_<E>("E").value(...)         ->  py::enum_<E>(m, "E").value(...)
    class_<C>(...).constructor<>()   ->  py::class_<C>(m, "C").def(py::init<>())
    .property("x", &C::x)            ->  .def_readwrite("x", &C::x)
    value_object<V>(...).field(...)  ->  py::class_<V>(m, "V") + .def_readwrite (no
                                          separate concept in pybind11)
    register_vector<T>("VecT")       ->  PYBIND11_MAKE_OPAQUE(std::vector<T>);
                                          py::bind_vector<...>(m, "VecT")
    constant("Name", v)              ->  m.attr("Name") = v
    typed_memory_view(...)           ->  py::memoryview::from_memory(...)

JS-side prefixes (`Mdx`, `M2`, `M3`) are stripped on the Python side: a
type already lives in ``whiteout.mdx``, so calling it ``MdxModel`` would
be redundant. The result is ``whiteout.mdx.Model``, ``whiteout.m2.Bone``,
etc.
"""

from __future__ import annotations

import re
from io import StringIO
from .ir import (
    BindClass, BindEnum, BindField, BindModule,
    TypeKind, TypeRef,
)
from .parser import _short_name, _is_span_const_u8
from .emit_embind import _WHITEOUT_PRIMITIVES, _qualify_primitives


def _is_span_const_u8_type(t):
    """Alias re-export — keeps the call-site readable in the emitter."""
    return _is_span_const_u8(t)


# ── Python naming conventions ──────────────────────────────────────────────
# Fields and methods become snake_case; enum members and module-level
# constants become UPPER_SNAKE_CASE (PEP 8). Class names stay PascalCase.

_CAMEL_BOUNDARY_1 = re.compile(r'(.)([A-Z][a-z]+)')   # fooBar -> foo_Bar
_CAMEL_BOUNDARY_2 = re.compile(r'([a-z0-9])([A-Z])')  # ABCdef -> AB_Cdef


def to_snake_case(name: str) -> str:
    """`fooBar` / `FooBar` / `_foo_Bar` -> `foo_bar`. Idempotent on
    already-snake names. Acronyms collapse: `parseBLP` -> `parse_blp`."""
    if not name:
        return name
    s = _CAMEL_BOUNDARY_1.sub(r'\1_\2', name)
    s = _CAMEL_BOUNDARY_2.sub(r'\1_\2', s)
    return s.lower().replace('__', '_').strip('_')


def to_upper_snake(name: str) -> str:
    """`NoParent` -> `NO_PARENT`. `WrapWidth` -> `WRAP_WIDTH`. Already-
    upper-snake names pass through."""
    return to_snake_case(name).upper()


def _qualified(short: str, ns: str) -> str:
    if '::' in short and short.startswith(('whiteout::', 'std::')):
        return short
    return f'{ns}::{short}'


def _cpp_type(t: TypeRef, ns: str) -> str:
    if t.kind == TypeKind.PRIMITIVE:
        short = _short_name(t.cpp_text)
        if short in _WHITEOUT_PRIMITIVES:
            return f'whiteout::{short}'
        return t.cpp_text
    if t.kind == TypeKind.STRING:
        return 'std::string'
    if t.kind in (TypeKind.NESTED, TypeKind.ENUM):
        return t.cpp_text if '::' in t.cpp_text else _qualified(t.cpp_text, ns)
    if t.kind in (TypeKind.VECTOR, TypeKind.NESTED_VEC):
        return f'std::vector<{_cpp_type(t.element, ns)}>'
    if t.kind == TypeKind.ARRAY:
        return f'std::array<{_cpp_type(t.element, ns)}, {t.array_size}>'
    if t.kind == TypeKind.OPTIONAL:
        return f'std::optional<{_cpp_type(t.element, ns)}>'
    return t.cpp_text


def _py_name(js_name: str, prefix: str) -> str:
    """Convert Embind JS class name to Python name by stripping the prefix.

    `MdxModel` -> `Model`, `MdxLayerSubTexture` -> `LayerSubTexture`.
    Shared math types (no prefix) pass through unchanged.
    """
    if prefix and js_name.startswith(prefix) and js_name != prefix:
        rest = js_name[len(prefix):]
        # Make sure we don't strip into nothing or break a real name like
        # `MdxModel` -> `Model` — that's fine, but `MdxBone` -> `Bone` is too.
        return rest
    return js_name


HEADER = '''// SPDX-License-Identifier: BSD-3-Clause
// Copyright (c) 2026 Fernando Sahmkow
//
// AUTOGENERATED by tools/codegen — do not edit by hand.
// Regenerate via:  python -m tools.codegen.codegen {module} --backend pybind11
//
// Source headers and `@bind` annotations live under include/whiteout/.
//
// Include order matters here:
//   1. pybind11/pybind11.h   sets up the base library
//   2. project headers       define whiteout::u32 et al used inside MAKE_OPAQUE
//   3. PYBIND11_MAKE_OPAQUE  opts out of stl.h's auto-conversion for our vectors
//   4. pybind11/stl.h, stl_bind.h   honor the opaque declarations

#include <pybind11/pybind11.h>

#include <array>
#include <cstdint>
#include <optional>
#include <sstream>
#include <string>
#include <vector>

'''

INCLUDES_AND_OPAQUE_TAIL = '''
#include <pybind11/stl.h>
#include <pybind11/stl_bind.h>
#include <pybind11/operators.h>
#include <pybind11/numpy.h>

namespace py = pybind11;

'''


def _emit_buffer_vector_helper(out: StringIO):
    """Bind a std::vector<Elem> as a numpy-friendly buffer-protocol vector
    (Elem is laid out as `Components` contiguous `Scalar`s).

    Bypasses pybind11's auto-buffer-info path inside bind_vector(), which
    static-asserts on element types lacking a format_descriptor (Vector3f,
    Quaternion, ColorBGRA — none of those have one).
    """
    out.write('''
namespace {

// Buffer-protocol vector wrapper for std::vector<Elem> where Elem is laid
// out as `Components` contiguous Scalars (Vector3f, Quaternion, ColorBGRA…).
//
// pybind11's bind_vector<> wires up py::buffer_protocol() automatically,
// but stl_bind.h's auto-buffer-info path static-asserts on element types
// lacking a format_descriptor — Vector3f/Quaternion don't have one.
// We provide the same Python surface (append, extend, clear, __getitem__,
// __setitem__, __iter__, __len__, __bool__) plus a 2D buffer view.
template <typename Elem, typename Scalar, py::ssize_t Components>
auto bindBufferVector(py::module_& m, const char* name) {
    using Vec = std::vector<Elem>;
    py::class_<Vec> cls(m, name, py::buffer_protocol());
    cls.def(py::init<>());
    cls.def("__len__",  [](const Vec& v) { return v.size(); });
    cls.def("__bool__", [](const Vec& v) { return !v.empty(); });
    cls.def("__getitem__", [](const Vec& v, std::size_t i) -> Elem {
        if (i >= v.size()) throw py::index_error();
        return v[i];
    });
    cls.def("__setitem__", [](Vec& v, std::size_t i, const Elem& val) {
        if (i >= v.size()) throw py::index_error();
        v[i] = val;
    });
    cls.def("__iter__", [](Vec& v) {
        return py::make_iterator(v.begin(), v.end());
    }, py::keep_alive<0, 1>());
    cls.def("append",   [](Vec& v, const Elem& val) { v.push_back(val); });
    cls.def("extend",   [](Vec& v, const Vec& o) {
        v.insert(v.end(), o.begin(), o.end());
    });
    cls.def("clear",    &Vec::clear);
    cls.def_buffer([](Vec& v) -> py::buffer_info {
        if constexpr (Components == 1) {
            return py::buffer_info(
                v.data(),
                static_cast<py::ssize_t>(sizeof(Scalar)),
                py::format_descriptor<Scalar>::format(),
                1,
                { static_cast<py::ssize_t>(v.size()) },
                { static_cast<py::ssize_t>(sizeof(Scalar)) });
        } else {
            return py::buffer_info(
                v.data(),
                static_cast<py::ssize_t>(sizeof(Scalar)),
                py::format_descriptor<Scalar>::format(),
                2,
                { static_cast<py::ssize_t>(v.size()), Components },
                { static_cast<py::ssize_t>(sizeof(Elem)),
                  static_cast<py::ssize_t>(sizeof(Scalar)) });
        }
    });
    return cls;
}

} // namespace
''')


# Python keywords / built-ins we can't expose as bare attribute names.
_PY_RESERVED = {
    'None': 'NONE',
    'True': 'TRUE',
    'False': 'FALSE',
}


def _default_value_expr(cpp_type: str) -> str:
    """Emit a value-initialised expression for `cpp_type` usable as a
    pybind11 default arg.

    `T{}` works for single-token types (`MyStruct{}`, `int{}`,
    `std::size_t{}`) but is a parse error for multi-word primitive type
    names like `unsigned long{}` — the parser sees `(unsigned) (long{})`.
    libclang's canonical types are multi-word for `size_t`/`uintN_t` on
    LP64 systems (macOS/Linux), so we fall back to `static_cast<T>(0)`
    whenever the type name contains whitespace.
    """
    if ' ' in cpp_type:
        return f'static_cast<{cpp_type}>(0)'
    return f'{cpp_type}{{}}'


def _cpp_string_lit(s: str) -> str:
    """Render `s` as a C++ raw string literal, suitable as a docstring arg."""
    if not s:
        return '""'
    # R"doc(...)doc" can carry any byte except the literal sequence )doc"
    # (which our extracted comments will never contain).
    return f'R"doc({s})doc"'


def _py_enum_value_name(name: str) -> str:
    """Enum members follow PEP 8: UPPER_SNAKE_CASE. Reserved word collisions
    (None/True/False) are also handled here as a side-effect of upper-casing."""
    upper = to_upper_snake(name)
    return _PY_RESERVED.get(name, upper)


def _emit_enum(out: StringIO, e: BindEnum, ns: str, prefix: str):
    py_name = _py_name(e.js_name, prefix)
    use_ns = e.cpp_namespace or ns
    if e.doc:
        out.write(f'    py::enum_<{_qualified(e.cpp_qualifier, use_ns)}>'
                  f'(m, "{py_name}", {_cpp_string_lit(e.doc)})\n')
    else:
        out.write(f'    py::enum_<{_qualified(e.cpp_qualifier, use_ns)}>'
                  f'(m, "{py_name}")\n')
    seen = set()
    for v in e.values:
        py = _py_enum_value_name(v.js_name)
        if py in seen:
            # An alias maps to the same Python name as a primary value (e.g.
            # ShadingFlag has SortPrimitives + SortPrimsFarZ both 0x10000).
            # pybind11 errors on duplicates, so keep the first one.
            continue
        seen.add(py)
        if v.doc:
            out.write(f'        .value("{py}", '
                      f'{_qualified(v.cpp_qualifier, use_ns)}, '
                      f'{_cpp_string_lit(v.doc)})\n')
        else:
            out.write(f'        .value("{py}", '
                      f'{_qualified(v.cpp_qualifier, use_ns)})\n')
    out.write('    ;\n\n')


def _emit_method(out: StringIO, m, cls_qual: str, ns: str):
    """Emit one pybind11 .def(...) line for a class method.

    Handles four orthogonal cases for the return value:
      - plain T            → return T directly
      - std::vector<u8>    → wrap in py::bytes  (bytes_out)
      - std::optional<T>   → return None when empty
      - std::optional<std::vector<u8>> → bytes or None  (bytes_out + optional)
    """
    # Python method name: use cpp_name so overloads collapse onto the
    # original C++ name and pybind11's overload dispatch picks the right
    # one via signature matching. m.name carries the disambiguating
    # suffix needed by the C symbol layer only (not Python). The rename
    # annotation still takes precedence so `@bind rename=foo` works.
    py_method_name = m.annotations.get('rename') if m.annotations else None
    if not py_method_name:
        py_method_name = m.cpp_name
    py_name = to_snake_case(py_method_name)
    doc_arg = f', {_cpp_string_lit(m.doc)}' if m.doc else ''
    binder = 'def_static' if m.is_static else 'def'

    ret = m.return_type
    is_optional = ret.kind.value == 'optional'

    # Fast path: no marshalling needed. Pybind11 handles std::optional<T>
    # natively (auto-converts to T|None), and primitives/strings round-trip
    # without help. Overloaded methods need py::overload_cast to pin which
    # overload we're binding.
    if not (m.bytes_in or m.bytes_out or m.needs_wrapper):
        target = f'&{cls_qual}::{m.cpp_name}'
        if m.is_overloaded:
            # pybind11 overload_cast: the param types go in the template
            # args; `py::const_` is a *second runtime arg* to overload_cast
            # (not a template arg) that pins the const-qualified overload.
            # Build the param spelling from the canonical fully-qualified
            # type (so `interfaces::Foo` / bare `Model` get the right
            # namespace) and restore const/ref qualifiers from cpp_raw,
            # which preserves the original signature decoration.
            def _qual_param(p) -> str:
                raw = p.cpp_raw or ''
                # Identify the core type (strip const + ref/ptr) to special-
                # case platform-dependent global typedefs.
                core = raw.strip()
                if core.startswith('const '):
                    core = core[6:].strip()
                while core.endswith(('&', '*', ' ')):
                    core = core[:-1].strip()
                # `size_t` must survive verbatim — canonicalising to
                # `whiteout::u64` (which is `uint64_t`) breaks py::overload_cast
                # template deduction on macOS arm64, where `size_t` is
                # `unsigned long` but `uint64_t` is `unsigned long long`
                # (distinct types despite identical size). Linux happens to
                # alias them so the bug only fires on macOS.
                if core == 'size_t':
                    return raw.replace(' &', '&').replace(' *', '*')
                base = _cpp_type(p.type, ns)
                if '*' in raw:
                    base += '*'
                elif '&' in raw:
                    base += '&'
                if raw.lstrip().startswith('const '):
                    base = 'const ' + base
                return base
            param_sig = ', '.join(_qual_param(p) for p in m.params)
            cast = f'py::overload_cast<{param_sig}>({target}'
            if m.is_const and not m.is_static:
                cast += ', py::const_'
            cast += ')'
            target = cast
        # py::arg(...) for every parameter — supplies names AND, when the
        # original C++ signature defaulted a param, the matching default.
        # Without this pybind11 reports "incompatible function arguments"
        # for any call that omits a defaulted tail param.
        arg_clauses: list[str] = []
        for p in m.params:
            if p.has_default:
                raw = p.cpp_raw or ''
                # Pointer params default to nullptr — `Pointee{}` is wrong
                # AND fails for abstract bases (`WorkerPool* pool = nullptr`
                # would try to default-construct the abstract type).
                if '*' in raw:
                    arg_clauses.append(f'py::arg("{p.name}") = nullptr')
                else:
                    arg_clauses.append(
                        f'py::arg("{p.name}") = {_default_value_expr(_cpp_type(p.type, ns))}')
            else:
                arg_clauses.append(f'py::arg("{p.name}")')
        args_tail = ', ' + ', '.join(arg_clauses) if arg_clauses else ''
        out.write(f'        .{binder}("{py_name}", {target}{args_tail}{doc_arg})\n')
        return

    # Slow path: we wrap in a lambda to convert std::span ⇄ bytes etc.
    # Span params can appear anywhere in the signature (the only API that
    # has one mid-signature is `writeFile(name, data, opts)`).
    #
    # Two flavours of span marshalling:
    #   - `std::span<const u8>` → `py::bytes` (the established idiom for
    #     parser bytes_in handlers).
    #   - `std::span<const T>` for any other primitive T → `py::array_t<T>`
    #     with `c_style | forcecast`, giving zero-copy access to numpy
    #     buffers (and accepting Python list / typed iterable inputs too).
    span_params = [(i, p) for i, p in enumerate(m.params)
                   if p.span_scalar is not None]

    # Match _qual_param above: build the param's C++ type from
    # _cpp_type (canonical, fully qualified) and restore the const/
    # ref/pointer decoration the original signature had. Without
    # this, pointer-to-abstract params (WorkerPool*) lose the `*`
    # and pybind tries to default-construct the abstract.
    def _qual_param_lambda(p) -> str:
        raw = p.cpp_raw or ''
        base = _cpp_type(p.type, ns)
        if '*' in raw:
            base += '*'
        elif '&' in raw:
            base += '&'
        if raw.lstrip().startswith('const '):
            base = 'const ' + base
        return base

    out.write(f'        .{binder}("{py_name}",\n')
    out.write(f'            [](')
    if not m.is_static:
        out.write(f'{cls_qual}& self')
    sep = ', ' if not m.is_static else ''
    for i, p in enumerate(m.params):
        out.write(sep)
        sep = ', '
        if p.span_scalar is not None:
            short, _ = p.span_scalar
            if short == 'u8':
                out.write(f'py::bytes __py_bytes_{i}')
            else:
                # numpy-aware: forcecast allows Python list inputs too.
                out.write(
                    f'py::array_t<whiteout::{short}, '
                    f'py::array::c_style | py::array::forcecast> __py_arr_{i}'
                )
        else:
            out.write(f'{_qual_param_lambda(p)} {p.name}')
    out.write(') {\n')
    for i, p in span_params:
        short, _ = p.span_scalar
        pname = p.name
        if short == 'u8':
            out.write(f'                std::string __s_{i} = __py_bytes_{i};\n')
            out.write(f'                std::span<const whiteout::u8> {pname}('
                      f'reinterpret_cast<const whiteout::u8*>(__s_{i}.data()), __s_{i}.size());\n')
        else:
            # Zero-copy: span points straight at the numpy buffer.
            out.write(f'                auto __buf_{i} = __py_arr_{i}.request();\n')
            out.write(f'                std::span<const whiteout::{short}> {pname}(\n'
                      f'                    static_cast<const whiteout::{short}*>(__buf_{i}.ptr),\n'
                      f'                    static_cast<std::size_t>(__buf_{i}.size));\n')
    qualified_call = (
        f'{cls_qual}::{m.cpp_name}' if m.is_static else f'self.{m.cpp_name}'
    )
    args = ', '.join(p.name for p in m.params)
    call = f'{qualified_call}({args})'

    if m.bytes_out and is_optional:
        # std::optional<std::vector<u8>> → py::bytes or py::none
        out.write(f'                auto __r = {call};\n')
        out.write('                if (!__r) return py::object(py::none());\n')
        out.write('                return py::object(py::bytes(\n')
        out.write('                    reinterpret_cast<const char*>(__r->data()), __r->size()));\n')
    elif m.bytes_out:
        out.write(f'                auto __v = {call};\n')
        out.write('                return py::bytes(\n')
        out.write('                    reinterpret_cast<const char*>(__v.data()), __v.size());\n')
    elif is_optional:
        # Let pybind11 auto-convert std::optional<T> to T|None.
        out.write(f'                return {call};\n')
    elif ret.cpp_text == 'void':
        out.write(f'                {call};\n')
    elif m.return_is_reference:
        # Builder-pattern reference return — discard inside the lambda
        # so the deduced return type is `void` (preventing pybind11 from
        # trying to copy-construct a move-only class at the wire boundary).
        # The JS/Python caller already has the object; chaining via the
        # return value is unavailable but the operation still applies.
        out.write(f'                {call};\n')
    else:
        out.write(f'                return {call};\n')

    # Trailing py::arg(...) overrides — gives names + defaults to the
    # wrapped lambda signature. The arg count MUST match the lambda's
    # argument count, so emit one entry per m.params slot (span positions
    # get a no-default py::arg too).
    arg_clauses: list[str] = []
    span_idx_set = {i for i, _ in span_params}
    for i, p in enumerate(m.params):
        if i not in span_idx_set and p.has_default:
            raw = p.cpp_raw or ''
            # Pointer defaults → nullptr (see fast-path arm above).
            if '*' in raw:
                arg_clauses.append(f'py::arg("{p.name}") = nullptr')
            else:
                arg_clauses.append(
                    f'py::arg("{p.name}") = {_default_value_expr(_cpp_type(p.type, ns))}')
        else:
            arg_clauses.append(f'py::arg("{p.name}")')
    if arg_clauses:
        out.write(f'            }}, {", ".join(arg_clauses)}{doc_arg})\n')
    else:
        out.write(f'            }}{doc_arg})\n')


def _is_pod_value_object(c: BindClass) -> bool:
    """A value_object whose fields are all primitive-or-enum — eligible for
    a positional-args ctor and a clean `__repr__`. (Strings are excluded
    because they need pass-by-const-ref handling in the lambda init.)"""
    if not c.is_value_object or not c.fields:
        return False
    return all(f.type.kind in (TypeKind.PRIMITIVE, TypeKind.ENUM)
               for f in c.fields)


def _emit_class(out: StringIO, c: BindClass, ns: str, prefix: str):
    short = c.cpp_qualifier
    use_ns = c.cpp_namespace or ns
    if short in ('Vector2f', 'Vector3f', 'Vector4f', 'Quaternion'):
        cpp_qual = f'whiteout::{short}'
    else:
        cpp_qual = _qualified(short, use_ns)

    py_name = _py_name(c.js_name, prefix)

    # `py::class_<C, Base>` when @bind extends= sets a base class.
    base_part = f', {c.base_class}' if c.base_class else ''
    if c.doc:
        out.write(f'    py::class_<{cpp_qual}{base_part}>(m, "{py_name}", '
                  f'{_cpp_string_lit(c.doc)})\n')
    else:
        out.write(f'    py::class_<{cpp_qual}{base_part}>(m, "{py_name}")\n')
    if not c.no_default_ctor:
        out.write('        .def(py::init<>())\n')

    # Helper: render ctor parameter types using the fully-qualified
    # canonical type (so the binding TU resolves names correctly), while
    # preserving any reference qualifier from the original spelling.
    def _ctor_param_type(p, ns):
        # Preserve const/ref/pointer qualifiers from the original
        # signature spelling — needed for abstract-base pointer params
        # (e.g. `WorkerPool* pool`) where dropping the `*` makes pybind11
        # try to instantiate the abstract base.
        base = _cpp_type(p.type, ns)
        raw = p.cpp_raw or ''
        if '*' in raw:
            base += '*'
        elif '&' in raw:
            base += '&'
        if raw.lstrip().startswith('const '):
            base = 'const ' + base
        return base

    # POD value_objects: positional + keyword constructor and `__repr__`.
    # Use aggregate init through a lambda so this works whether or not the
    # underlying C++ type has a matching numeric constructor.
    if _is_pod_value_object(c):
        params = ', '.join(
            f'{_cpp_type(f.type, ns)} {to_snake_case(f.name)}'
            for f in c.fields
        )
        body = ', '.join(to_snake_case(f.name) for f in c.fields)
        py_args = ', '.join(
            f'py::arg("{to_snake_case(f.name)}")' for f in c.fields
        )
        out.write(f'        .def(py::init([]({params}) {{\n')
        out.write(f'            return {cpp_qual}{{{body}}};\n')
        out.write(f'        }}), {py_args})\n')

        # __repr__: ClassName(field1=val1, field2=val2, ...)
        out.write(f'        .def("__repr__", [](const {cpp_qual}& self) {{\n')
        out.write(f'            std::ostringstream oss;\n')
        out.write(f'            oss << "{py_name}(";\n')
        for i, f in enumerate(c.fields):
            sep = '", "' if i < len(c.fields) - 1 else '")"'
            py_field = to_snake_case(f.name)
            # u8/i8 stream as characters; enum class types don't stream at
            # all without a cast. Route both through `static_cast<int>`.
            short_t = _short_name(f.type.cpp_text)
            needs_int_cast = (
                short_t in ('u8', 'i8') or f.type.kind == TypeKind.ENUM
            )
            if needs_int_cast:
                out.write(f'            oss << "{py_field}=" '
                          f'<< static_cast<int>(self.{f.cpp_name}) << {sep};\n')
            else:
                out.write(f'            oss << "{py_field}=" '
                          f'<< self.{f.cpp_name} << {sep};\n')
        out.write(f'            return oss.str();\n')
        out.write(f'        }})\n')

    for ctor in c.constructors:
        sig = ', '.join(_ctor_param_type(p, ns) for p in ctor.params)
        # Emit py::arg("name") for every parameter so Python callers can
        # use keyword args: `Cls(name=value)`. The libclang-spelled names
        # are captured by the parser at make_param time.
        py_args = ', '.join(f'py::arg("{to_snake_case(p.name)}")'
                            for p in ctor.params)
        if py_args:
            out.write(f'        .def(py::init<{sig}>(), {py_args})\n')
        else:
            out.write(f'        .def(py::init<{sig}>())\n')

    array_helpers = []
    for f in c.fields:
        if f.type.kind == TypeKind.ARRAY:
            array_helpers.append(f)
            continue
        py_field = to_snake_case(f.name)
        if f.doc:
            out.write(f'        .def_readwrite("{py_field}", '
                      f'&{cpp_qual}::{f.cpp_name}, '
                      f'{_cpp_string_lit(f.doc)})\n')
        else:
            out.write(f'        .def_readwrite("{py_field}", '
                      f'&{cpp_qual}::{f.cpp_name})\n')
        if f.array_with_view:
            # For vector<u8> fields, expose a memoryview accessor that
            # zero-copies the underlying buffer. The user must copy out
            # before any subsequent operation that could grow the heap.
            out.write(f'        .def("{py_field}_view",\n')
            out.write(f'            [](const {cpp_qual}& self) {{\n')
            out.write(f'                return py::memoryview::from_memory(\n')
            out.write(f'                    static_cast<const void*>(self.{f.cpp_name}.data()),\n')
            out.write(f'                    static_cast<py::ssize_t>(self.{f.cpp_name}.size()));\n')
            out.write(f'            }})\n')

    # std::array fields: getter/setter pairs that round-trip via std::vector
    # (pybind11 has automatic conversion via stl.h).
    for f in array_helpers:
        elem_t = _cpp_type(f.type.element, ns)
        py_field = to_snake_case(f.name)
        out.write(f'        .def("get_{py_field}",\n')
        out.write(f'            [](const {cpp_qual}& self) {{\n')
        out.write(f'                return std::vector<{elem_t}>(self.{f.cpp_name}.begin(), self.{f.cpp_name}.end());\n')
        out.write(f'            }})\n')
        out.write(f'        .def("set_{py_field}",\n')
        out.write(f'            []({cpp_qual}& self, const std::vector<{elem_t}>& v) {{\n')
        out.write(f'                if (v.size() != self.{f.cpp_name}.size())\n')
        out.write(f'                    throw std::runtime_error("setter expected exactly "\n')
        out.write(f'                        + std::to_string(self.{f.cpp_name}.size()) + " elements");\n')
        out.write(f'                for (std::size_t i = 0; i < v.size(); ++i) self.{f.cpp_name}[i] = v[i];\n')
        out.write(f'            }})\n')

    # Methods.
    for m in c.methods:
        _emit_method(out, m, cpp_qual, ns)

    out.write('    ;\n\n')


def _vector_py_name(v: TypeRef, prefix: str) -> str:
    """Vector container name for pybind11; mirror the JS naming for now so
    the same C++ type gets the same Python class name across formats."""
    from .parser import js_name_for_type
    js = 'Vector' + js_name_for_type(v.element, prefix)
    return _py_name(js, prefix)


# GCC 15.2 peak RSS (GB) of a binding TU at the CI flags (-O3 -flto), fitted
# over whole and split m2/m3/wem/mdx TUs. bind_vector dominates: each one
# instantiates pybind11's full list interface.
_TU_BASE_GB = 0.41
_STMT_COST_GB = (
    (re.compile(r'\.def_read(?:write|only)\('), 0.0015),
    (re.compile(r'\.def(?:_static|_property|_property_readonly)?\('), 0.0033),
    (re.compile(r'\.value\('), 0.0010),
    (re.compile(r'py::bind_vector<|bindBufferVector<'), 0.0446),
)

# AppVeyor's Linux worker (~7 GB) compiles two TUs at once; a part above
# this gets the runner OOM-killed, which AppVeyor reports as a green job.
PART_BUDGET_GB = 1.75


def _stmt_cost(text: str) -> float:
    return sum(len(rx.findall(text)) * gb for rx, gb in _STMT_COST_GB)


def _partition(costs: list[float], parts: int) -> list[int]:
    """Contiguous split into `parts` non-empty runs minimising the largest
    run; returns the start index of each run."""
    n = len(costs)
    parts = max(1, min(parts, n))
    prefix = [0.0]
    for c in costs:
        prefix.append(prefix[-1] + c)
    inf = float('inf')
    best = [[inf] * (n + 1) for _ in range(parts + 1)]
    cut = [[0] * (n + 1) for _ in range(parts + 1)]
    best[0][0] = 0.0
    for k in range(1, parts + 1):
        for i in range(k, n + 1):
            for j in range(k - 1, i):
                v = max(best[k - 1][j], prefix[i] - prefix[j])
                if v < best[k][i]:
                    best[k][i], cut[k][i] = v, j
    starts, i = [], n
    for k in range(parts, 0, -1):
        i = cut[k][i]
        starts.append(i)
    return starts[::-1]


def emit(module: BindModule) -> str:
    return emit_parts(module)[0][0]


def emit_parts(module: BindModule, parts: int = 1) -> list[tuple[str, float]]:
    """One (source, estimated peak GB) per translation unit. Part 0 defines
    `bind_<module>` and calls `bind_<module>_<k>` for the rest in order, so
    registration order — which base classes and default args rely on — is
    unchanged by the split."""
    ns = module.cpp_namespace
    prefix = module.js_prefix
    skip = set(module.skip_class_js_names)
    skip_vec = set(module.skip_vector_js_names)

    buf = StringIO()
    buf.write(HEADER.format(module=module.name))

    # Source headers FIRST — needed so whiteout::u32 et al resolve inside
    # the PYBIND11_MAKE_OPAQUE template arguments below.
    for h in module.headers:
        buf.write(f'#include <{h.replace("include/", "")}>\n')
    # whiteout/interfaces.h is needed whenever a bound method takes an
    # `interfaces::X` reference/pointer (m2::Parser, m2::Writer, etc.).
    # Module configs that already include it skip — duplicate #includes
    # are harmless because of header guards, but we keep the check
    # explicit so the emitted output stays minimal.
    interfaces_already = any('interfaces.h' in h for h in module.headers)
    if not interfaces_already:
        buf.write('#include <whiteout/interfaces.h>\n')
    buf.write('\n')

    # MAKE_OPAQUE block — every vector we bind. Must come before stl.h.
    seen_opaque = set()
    def _opaque(cpp: str):
        if cpp in seen_opaque:
            return
        seen_opaque.add(cpp)
        buf.write(f'PYBIND11_MAKE_OPAQUE({cpp});\n')
    for v in sorted(module.vector_types, key=lambda x: x.cpp_text):
        _opaque(f'std::vector<{_cpp_type(v.element, ns)}>')
    if 'VectorU8' in skip_vec:
        _opaque('std::vector<whiteout::u8>')
    if 'VectorString' in skip_vec:
        _opaque('std::vector<std::string>')

    buf.write(INCLUDES_AND_OPAQUE_TAIL)

    # Buffer-protocol vector helper if any vector element is one of the
    # known math structs. Primitive vectors use bind_vector's built-in
    # buffer support directly.
    needs_buffer_vector = any(
        _buffer_descriptor(v.element) is not None
        and v.element.kind != TypeKind.PRIMITIVE
        for v in module.vector_types
    )
    if needs_buffer_vector:
        _emit_buffer_vector_helper(buf)

    preamble = buf.getvalue()
    stmts: list[str] = []

    def _stmt(emit_fn, *args):
        out = StringIO()
        emit_fn(out, *args)
        stmts.append(out.getvalue())

    # Constants.
    if module.constants:
        for c in module.constants:
            expr = c.cpp_expr if 'whiteout::' in c.cpp_expr else _qualified(c.cpp_expr, ns)
            cast_t = f'whiteout::{c.cpp_type}' if c.cpp_type in _WHITEOUT_PRIMITIVES else c.cpp_type
            # Drop the module prefix and rewrite as PEP 8 UPPER_SNAKE_CASE
            # (Python convention for module-level constants).
            py_const = to_upper_snake(_py_name(c.js_name, prefix))
            doc = f'    // {c.doc}\n' if c.doc else ''
            stmts.append(f'{doc}    m.attr("{py_const}") = static_cast<{cast_t}>({expr});\n')
        stmts[-1] += '\n'

    # Enums.
    enums = [e for e in module.enums if e.js_name not in skip]
    for e in enums:
        _stmt(_emit_enum, e, ns, prefix)

    # Value-object math types first.
    value_classes = [c for c in module.classes if c.is_value_object and c.js_name not in skip]
    other_classes = [c for c in module.classes if not c.is_value_object and c.js_name not in skip]
    for c in value_classes:
        _stmt(_emit_class, c, ns, prefix)

    # Class types.
    for c in other_classes:
        _stmt(_emit_class, c, ns, prefix)

    # Vector containers.
    #
    # For "buffer-friendly" element types (primitives + the standard math
    # structs) we wire up py::buffer_protocol() so `np.asarray(vec)` is a
    # zero-copy view sharing memory with the underlying C++ std::vector.
    # Mutations to the numpy array propagate; resizing the vector
    # invalidates outstanding views (standard numpy aliasing caveat).
    seen = set(skip_vec)
    for v in sorted(module.vector_types, key=lambda x: x.cpp_text):
        from .parser import js_name_for_type
        js = 'Vector' + js_name_for_type(v.element, prefix)
        if js in seen:
            continue
        seen.add(js)
        py = _py_name(js, prefix)
        elem_cpp = _cpp_type(v.element, ns)
        info = _buffer_descriptor(v.element)
        if info is not None and v.element.kind == TypeKind.PRIMITIVE:
            # Primitive scalar vector: pybind11's bind_vector already wires
            # up a 1D buffer protocol when given py::buffer_protocol().
            stmts.append(
                f'    py::bind_vector<std::vector<{elem_cpp}>>'
                f'(m, "{py}", py::buffer_protocol());\n'
            )
        elif info is not None:
            # Vector of math struct (Vector*, Quaternion, ColorBGRA): use
            # the bindBufferVector helper which builds a 2D shape with the
            # right (rows=N, cols=Components) layout.
            scalar_cpp, _scalar_fmt, components = info
            stmts.append(
                f'    bindBufferVector<{elem_cpp}, {scalar_cpp}, {components}>'
                f'(m, "{py}");\n'
            )
        else:
            stmts.append(f'    py::bind_vector<std::vector<{elem_cpp}>>(m, "{py}");\n')

    # Every part repeats the full preamble: the PYBIND11_MAKE_OPAQUE set must
    # be identical in every TU that sees these vector types (ODR).
    fn = f'bind_{module.name}'
    starts = _partition([_stmt_cost(s) for s in stmts], parts)
    ends = starts[1:] + [len(stmts)]
    last = len(starts) - 1
    result = []
    for k, (lo, hi) in enumerate(zip(starts, ends)):
        body = ''.join(stmts[lo:hi]) + ('\n' if k == last else '')
        if k == 0:
            decls = ''.join(f'void {fn}_{j}(py::module_& m);\n' for j in range(1, last + 1))
            calls = ''.join(f'    {fn}_{j}(m);\n' for j in range(1, last + 1))
            text = (preamble + (decls + '\n' if decls else '')
                    + f'void {fn}(py::module_& m) {{\n' + body + calls + '}\n')
        else:
            text = (preamble
                    + f'// Part {k} of {fn}(), which calls the parts in order.\n'
                    + f'void {fn}_{k}(py::module_& m) {{\n' + body + '}\n')
        result.append((text, _TU_BASE_GB + sum(_stmt_cost(s) for s in stmts[lo:hi])))
    return result


# ── Buffer-protocol element descriptors ────────────────────────────────────
#
# For each element type we know is laid out as a contiguous array of one
# scalar type, return (scalar_cpp, format_descriptor_T, components).
# The components field decides whether to emit a 1D buffer (primitives)
# or a 2D buffer (Vector*, Quaternion, ColorBGRA).
def _buffer_descriptor(t: TypeRef) -> tuple[str, str, int] | None:
    """Returns (scalar_cpp_type, format_T, components) if `t` can be
    exposed via the numpy buffer protocol, otherwise None.
    """
    if t.kind == TypeKind.PRIMITIVE:
        short = _short_name(t.cpp_text)
        if short in ('u8', 'u16', 'u32', 'u64', 'i8', 'i16', 'i32', 'i64',
                     'f32', 'f64'):
            return f'whiteout::{short}', f'whiteout::{short}', 1
    if t.kind == TypeKind.NESTED:
        short = _short_name(t.cpp_text).replace('::', '')
        if short == 'Vector2f':
            return 'float', 'float', 2
        if short == 'Vector3f':
            return 'float', 'float', 3
        if short in ('Vector4f', 'Quaternion'):
            return 'float', 'float', 4
        if short == 'ColorBGRA':
            return 'whiteout::u8', 'whiteout::u8', 4
    return None