xberg-io
diff --git a/‎CHANGELOG.md‎
Lines changed: 28 additions & 1 deletion b/‎CHANGELOG.md‎
Lines changed: 28 additions & 1 deletion
diff --git a/‎src/backends/go/trait_bridge/helpers.rs‎
Lines changed: 6 additions & 18 deletions b/‎src/backends/go/trait_bridge/helpers.rs‎
Lines changed: 6 additions & 18 deletions
diff --git a/‎src/backends/kotlin/gen_bindings/jni_emitter.rs‎
Lines changed: 3 additions & 0 deletions b/‎src/backends/kotlin/gen_bindings/jni_emitter.rs‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎src/backends/kotlin/gen_bindings/jni_emitter/bridge_object.rs‎
Lines changed: 0 additions & 26 deletions b/‎src/backends/kotlin/gen_bindings/jni_emitter/bridge_object.rs‎
Lines changed: 0 additions & 26 deletions
diff --git a/‎src/backends/kotlin/gen_bindings/jni_emitter/tests.rs‎
Lines changed: 29 additions & 0 deletions b/‎src/backends/kotlin/gen_bindings/jni_emitter/tests.rs‎
Lines changed: 29 additions & 0 deletions
diff --git a/‎src/backends/magnus/gen_stubs.rs‎
Lines changed: 40 additions & 18 deletions b/‎src/backends/magnus/gen_stubs.rs‎
Lines changed: 40 additions & 18 deletions
diff --git a/‎src/backends/napi/gen_bindings/errors.rs‎
Lines changed: 25 additions & 3 deletions b/‎src/backends/napi/gen_bindings/errors.rs‎
Lines changed: 25 additions & 3 deletions
diff --git a/‎src/backends/pyo3/gen_bindings/constructors.rs‎
Lines changed: 41 additions & 38 deletions b/‎src/backends/pyo3/gen_bindings/constructors.rs‎
Lines changed: 41 additions & 38 deletions
@@ -7,7 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Fixed
+### Added
+
+- **snippets**: `typecheck` validation level. Ordered between `compile` and `run`, it statically
+  type-checks a snippet without executing it, and for compiled languages without needing the native
+  library. Each language runs its strict static checker: `python -m mypy`, `tsc --noEmit`,
+  `cargo check`, `go vet`, `javac -Xlint:all -Werror`, `dotnet build -warnaserror`,
+  `swiftc -typecheck -warnings-as-errors`, `kotlinc -Werror`, `dart analyze --fatal-infos`, and
+  `cc -fsyntax-only -Wall -Werror`. This catches dual-representation mistakes (a config field typed
+  against a flattened union alias that rejects the documented data-enum constructor) that
+  `py_compile` and a lenient compile cannot see. A matching `snippet:typecheck-only` ceiling
+  annotation sits alongside `syntax-only` and `compile-only`. mypy is optional: when it is not
+  installed the Python snippet is reported as unavailable rather than failing.
+
+### Fixed
+
+- **pyo3**: the generated Python package now type-checks clean under `mypy`. Data-enum config fields
+  are annotated against their public class (so `EmbeddingConfig(model=EmbeddingModelType.plugin(...))`
+  is accepted) instead of a flattened union alias that shadowed the class; constructors accept the
+  public dataclass/dict for factory parameters; data-enum `__init__` signatures match the runtime
+  `#[new]`; `Json` maps to `dict[str, Any]`; and the duplicate `clear_*` registry stub is no longer
+  emitted twice.
+- **napi**: substitute binding-excluded types (e.g. `InternalDocument`) with `JsonValue` in the
+  `.d.ts` host-interface signatures. Referencing a type that is never emitted produced an undefined
+  TypeScript name; the runtime bridge marshals such values as JSON, so `JsonValue` is the faithful
+  stand-in and `tsc --strict` is clean.
+- **magnus**: apply the same excluded-type substitution (to `json_value`) in generated `.rbs`
+  interfaces and skip re-declaring a bridge `clear_*` function that is already exposed as a registry
+  function, so `rbs validate` no longer reports an undefined type or a duplicated method definition.
 
 - **go/java**: avoid callback return local-name collisions in generated trait
   bridges when a method parameter is named `result`.
 
@@ -2,24 +2,12 @@ use crate::backends::go::type_map::go_type;
 use crate::core::ir::{MethodDef, TypeRef};
 use std::collections::HashSet;
 
-/// Recursively substitute `TypeRef::Named(n)` references where `n` is explicitly excluded
-/// from the binding's public surface (collected from `ApiSurface::excluded_type_paths` and
-/// any `binding_excluded` types) with `TypeRef::Json`. This lets trait-bridge interface
-/// signatures and trampolines fall back to `json.RawMessage`, since the named Go type was
-/// never emitted into `binding.go` and would otherwise produce `undefined: <Name>` build
-/// errors.
-pub(super) fn substitute_excluded_types(ty: &TypeRef, excluded: &HashSet<&str>) -> TypeRef {
-    match ty {
-        TypeRef::Named(name) if excluded.contains(name.as_str()) => TypeRef::Json,
-        TypeRef::Optional(inner) => TypeRef::Optional(Box::new(substitute_excluded_types(inner, excluded))),
-        TypeRef::Vec(inner) => TypeRef::Vec(Box::new(substitute_excluded_types(inner, excluded))),
-        TypeRef::Map(k, v) => TypeRef::Map(
-            Box::new(substitute_excluded_types(k, excluded)),
-            Box::new(substitute_excluded_types(v, excluded)),
-        ),
-        other => other.clone(),
-    }
-}
+/// Recursively substitute `TypeRef::Named(n)` references for types excluded from the binding's
+/// public surface with `TypeRef::Json`. For Go this lets trait-bridge interface signatures and
+/// trampolines fall back to `json.RawMessage`, since the named Go type was never emitted into
+/// `binding.go` and would otherwise produce `undefined: <Name>` build errors. Shared with the
+/// other backends — see [`crate::codegen::shared::substitute_excluded_types`].
+pub(super) use crate::codegen::shared::substitute_excluded_types;
 
 /// Clone a `MethodDef`, substituting any excluded named-type references in its
 /// parameters and return type with `TypeRef::Json`. See [`substitute_excluded_types`].
 
@@ -32,3 +32,6 @@ include!("jni_emitter/constructors.rs");
 include!("jni_emitter/binary_json.rs");
 include!("jni_emitter/trait_bridge.rs");
 include!("jni_emitter/paths.rs");
+// Included last so the `#[cfg(test)]` module is the final item in this flattened module
+// (`clippy::items_after_test_module`).
+include!("jni_emitter/tests.rs");
@@ -237,29 +237,3 @@ fn trait_bridge_manages_jni_function(func_name: &str, config: &ResolvedCrateConf
                 || bridge.clear_fn.as_deref() == Some(func_name))
     })
 }
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::core::config::{KotlinAndroidConfig, TraitBridgeConfig};
-
-    #[test]
-    fn jni_bridge_object_treats_android_trait_lifecycle_functions_as_managed() {
-        let config = ResolvedCrateConfig {
-            kotlin_android: Some(KotlinAndroidConfig::default()),
-            trait_bridges: vec![TraitBridgeConfig {
-                trait_name: "Renderer".to_string(),
-                register_fn: Some("register_renderer".to_string()),
-                unregister_fn: Some("unregister_renderer".to_string()),
-                clear_fn: Some("clear_renderers".to_string()),
-                ..TraitBridgeConfig::default()
-            }],
-            ..ResolvedCrateConfig::default()
-        };
-
-        assert!(trait_bridge_manages_jni_function("register_renderer", &config));
-        assert!(trait_bridge_manages_jni_function("unregister_renderer", &config));
-        assert!(trait_bridge_manages_jni_function("clear_renderers", &config));
-        assert!(!trait_bridge_manages_jni_function("list_renderers", &config));
-    }
-}
@@ -0,0 +1,29 @@
+// Tests for the JNI emitter. Kept in a separate file `include!`d last by `jni_emitter.rs` so the
+// `#[cfg(test)]` module is the final item in the flattened module (the other `include!`d files
+// contribute production items, which must not follow a test module — `clippy::items_after_test_module`).
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::core::config::{KotlinAndroidConfig, TraitBridgeConfig};
+
+    #[test]
+    fn jni_bridge_object_treats_android_trait_lifecycle_functions_as_managed() {
+        let config = ResolvedCrateConfig {
+            kotlin_android: Some(KotlinAndroidConfig::default()),
+            trait_bridges: vec![TraitBridgeConfig {
+                trait_name: "Renderer".to_string(),
+                register_fn: Some("register_renderer".to_string()),
+                unregister_fn: Some("unregister_renderer".to_string()),
+                clear_fn: Some("clear_renderers".to_string()),
+                ..TraitBridgeConfig::default()
+            }],
+            ..ResolvedCrateConfig::default()
+        };
+
+        assert!(trait_bridge_manages_jni_function("register_renderer", &config));
+        assert!(trait_bridge_manages_jni_function("unregister_renderer", &config));
+        assert!(trait_bridge_manages_jni_function("clear_renderers", &config));
+        assert!(!trait_bridge_manages_jni_function("list_renderers", &config));
+    }
+}
@@ -1,5 +1,5 @@
 use crate::backends::magnus::type_map::rbs_type;
-use crate::codegen::shared::binding_fields;
+use crate::codegen::shared::{binding_fields, substitute_excluded_types};
 use crate::core::config::TraitBridgeConfig;
 use crate::core::hash::{self, CommentStyle};
 use crate::core::ir::{ApiSurface, EnumDef, FunctionDef, MethodDef, TypeDef};
@@ -69,27 +69,39 @@ pub fn gen_stubs(
             interface_trait_names.insert(bridge.trait_name.clone());
         }
     }
+    // Names already emitted as module methods above (from `api.functions`). A bridge's `clear_fn`
+    // is often also exposed as a regular registry function (`clear_embedding_backends`), so emitting
+    // it again here would be a duplicate definition (RBS `DuplicatedMethodDefinitionError`). Skip any
+    // bridge function whose name already has a declaration; register/unregister are bridge-only.
+    let declared_function_names: std::collections::HashSet<&str> =
+        api.functions.iter().map(|f| f.name.as_str()).collect();
     for bridge in trait_bridges {
         if let Some(register_fn) = bridge.register_fn.as_deref() {
-            // Type the `backend` param against the host-implementable interface when one was
-            // emitted for this bridge's trait; otherwise fall back to `untyped`.
-            let backend_type = if interface_trait_names.contains(&bridge.trait_name) {
-                plugin_interface_name(&bridge.trait_name)
-            } else {
-                "untyped".to_string()
-            };
-            lines.push(format!(
-                "  def self.{register_fn}: ({backend_type} backend, String name) -> nil"
-            ));
-            lines.push("".to_string());
+            if !declared_function_names.contains(register_fn) {
+                // Type the `backend` param against the host-implementable interface when one was
+                // emitted for this bridge's trait; otherwise fall back to `untyped`.
+                let backend_type = if interface_trait_names.contains(&bridge.trait_name) {
+                    plugin_interface_name(&bridge.trait_name)
+                } else {
+                    "untyped".to_string()
+                };
+                lines.push(format!(
+                    "  def self.{register_fn}: ({backend_type} backend, String name) -> nil"
+                ));
+                lines.push("".to_string());
+            }
         }
         if let Some(unregister_fn) = bridge.unregister_fn.as_deref() {
-            lines.push(format!("  def self.{unregister_fn}: (String name) -> nil"));
-            lines.push("".to_string());
+            if !declared_function_names.contains(unregister_fn) {
+                lines.push(format!("  def self.{unregister_fn}: (String name) -> nil"));
+                lines.push("".to_string());
+            }
         }
         if let Some(clear_fn) = bridge.clear_fn.as_deref() {
-            lines.push(format!("  def self.{clear_fn}: () -> nil"));
-            lines.push("".to_string());
+            if !declared_function_names.contains(clear_fn) {
+                lines.push(format!("  def self.{clear_fn}: () -> nil"));
+                lines.push("".to_string());
+            }
         }
     }
 
@@ -140,6 +152,16 @@ fn gen_plugin_interface_stub(bridge: &TraitBridgeConfig, api: &ApiSurface) -> Op
     }
     api.types.iter().find(|t| t.name == bridge.trait_name)?;
 
+    // Types excluded from the binding surface (e.g. `InternalDocument`) are not emitted as RBS
+    // declarations, so an interface method referencing one would be an undefined RBS type. Substitute
+    // them with their JSON marshaling form, matching the runtime bridge (and the go/pyo3/napi backends).
+    let excluded: std::collections::HashSet<&str> = api
+        .excluded_type_paths
+        .keys()
+        .map(String::as_str)
+        .chain(api.types.iter().filter(|t| t.binding_excluded).map(|t| t.name.as_str()))
+        .collect();
+
     let interface_name = plugin_interface_name(&bridge.trait_name);
     let mut lines = vec![format!("  interface {interface_name}")];
 
@@ -151,15 +173,15 @@ fn gen_plugin_interface_stub(bridge: &TraitBridgeConfig, api: &ApiSurface) -> Op
             .params
             .iter()
             .map(|p| {
-                let param_type = rbs_type(&p.ty);
+                let param_type = rbs_type(&substitute_excluded_types(&p.ty, &excluded));
                 if p.optional {
                     format!("?{} {}", param_type, p.name)
                 } else {
                     format!("{} {}", param_type, p.name)
                 }
             })
             .collect();
-        let return_type = rbs_type(&method.return_type);
+        let return_type = rbs_type(&substitute_excluded_types(&method.return_type, &excluded));
         lines.push(format!(
             "    def {}: ({}) -> {}",
             method.name,
 
@@ -1,7 +1,7 @@
 //! TypeScript declaration file (`.d.ts`) generation for NAPI-RS bindings.
 
 use crate::codegen::naming::{to_node_name, wire_variant_value};
-use crate::codegen::shared::binding_fields;
+use crate::codegen::shared::{binding_fields, substitute_excluded_types};
 use crate::core::config::NodeCapsuleTypeConfig;
 use crate::core::hash::{self, CommentStyle};
 use crate::core::ir::{ApiSurface, EnumDef, FunctionDef, ParamDef, TypeDef, TypeRef};
@@ -268,6 +268,16 @@ pub(super) fn gen_dts(
             Decl::VisitorInterface(typ) => {
                 // Emit visitor trait as a TypeScript interface with optional callback methods.
                 // Each method becomes an optional property with a function signature.
+                //
+                // Types excluded from the binding surface (e.g. `InternalDocument`) are not emitted as
+                // `.d.ts` declarations, so substitute them with their JSON marshaling form in method
+                // signatures — otherwise the interface references an undefined TS name.
+                let excluded: std::collections::HashSet<&str> = api
+                    .excluded_type_paths
+                    .keys()
+                    .map(String::as_str)
+                    .chain(api.types.iter().filter(|t| t.binding_excluded).map(|t| t.name.as_str()))
+                    .collect();
                 lines.extend(format_jsdoc(&typ.doc, ""));
                 lines.push(format!("export interface {} {{", typ.name));
                 if trait_bridge_requires_plugin_name(typ, trait_bridges) {
@@ -278,8 +288,20 @@ pub(super) fn gen_dts(
                     if trait_bridge_requires_plugin_name(typ, trait_bridges) && method.name == "name" {
                         continue;
                     }
-                    let params = dts_params(&method.params, no_prefix, default_types);
-                    let ret = trait_bridge_dts_return_type(&method.return_type, method.is_async, no_prefix);
+                    let sub_params: Vec<ParamDef> = method
+                        .params
+                        .iter()
+                        .map(|p| ParamDef {
+                            ty: substitute_excluded_types(&p.ty, &excluded),
+                            ..p.clone()
+                        })
+                        .collect();
+                    let params = dts_params(&sub_params, no_prefix, default_types);
+                    let ret = trait_bridge_dts_return_type(
+                        &substitute_excluded_types(&method.return_type, &excluded),
+                        method.is_async,
+                        no_prefix,
+                    );
                     lines.extend(format_jsdoc(&method.doc, "  "));
                     let optional_marker = if method.has_default_impl { "?" } else { "" };
                     lines.push(format!("  {js_name}{optional_marker}({params}): {ret}"));
 
@@ -4,6 +4,31 @@ use crate::core::config::TraitBridgeConfig;
 use crate::core::ir::{ApiSurface, FieldDef, TypeDef, TypeRef};
 use std::collections::HashMap;
 
+/// Resolve the PyO3 constructor parameter identifier for a field — the single source of truth for
+/// the `#[new]` signature AND the `.pyi` `__init__` stub, so the two cannot drift apart.
+///
+/// Prefers the serde rename (the wire name, deliberately used for constructor params so the public
+/// surface matches the other language bindings — see [`replace_constructor_with_serde_rename`]),
+/// then a per-language `rename_fields` entry, then the bare field name. Only applies a resolved name
+/// when it is a syntactically valid Rust identifier (e.g. `"self-harm"` falls back to the field
+/// name); a valid name that is also a Rust keyword (e.g. `"type"`) is escaped as `r#type`.
+pub(in crate::backends::pyo3) fn resolve_param_ident<'a>(
+    field_name: &'a str,
+    serde_rename: Option<&'a String>,
+    config_renames: Option<&HashMap<String, String>>,
+) -> String {
+    use crate::core::keywords::{is_valid_rust_ident_chars, rust_raw_ident};
+    let wire_name = serde_rename
+        .map(|s| s.as_str())
+        .or_else(|| config_renames.and_then(|r| r.get(field_name)).map(|s| s.as_str()))
+        .unwrap_or(field_name);
+    if is_valid_rust_ident_chars(wire_name) {
+        rust_raw_ident(wire_name)
+    } else {
+        field_name.to_string()
+    }
+}
+
 /// Replace the constructor in an impl block with one that honors serde_rename.
 /// For has_default types, the constructor parameters should use serde_rename names
 /// (the JSON wire names) to match other language bindings' public APIs.
@@ -20,8 +45,6 @@ pub(super) fn replace_constructor_with_serde_rename(
     never_skip_cfg_field_names: &[String],
     api: &ApiSurface,
 ) -> String {
-    use crate::core::keywords::{is_valid_rust_ident_chars, rust_raw_ident};
-
     // When the type already has an explicit static `new()` method in its IR, do not
     // emit a second field-based `#[new]` constructor — the static method will be emitted
     // as `#[staticmethod] pub fn new(...)` and PyO3 forbids two `new` registrations in
@@ -41,43 +64,23 @@ pub(super) fn replace_constructor_with_serde_rename(
         if !typ.has_default || field.optional || matches!(&field.ty, TypeRef::Optional(_)) {
             return false;
         }
-        if let TypeRef::Named(ref type_name) = field.ty {
-            api.types
-                .iter()
-                .find(|t| t.name == *type_name)
-                .map(|t| t.has_default)
-                .unwrap_or(false)
-        } else {
-            false
-        }
-    }
-
-    /// Resolve the constructor parameter identifier for a field.
-    ///
-    /// Prefers the serde rename (or config rename) over the bare Rust field name, but only
-    /// when the resolved name is a syntactically valid Rust identifier (i.e. contains only
-    /// `[A-Za-z0-9_]` and does not start with a digit).  Names like `"self-harm"` or
-    /// `"self-harm/intent"` (containing hyphens or slashes) are not valid Rust identifiers
-    /// even with `r#` escaping, so the function falls back to the Rust field name in those
-    /// cases.  When the resolved name is valid but happens to be a Rust keyword (e.g. `"type"`),
-    /// it is escaped as a raw identifier (`r#type`).
-    fn resolve_param_ident<'a>(
-        field_name: &'a str,
-        serde_rename: Option<&'a String>,
-        config_renames: Option<&HashMap<String, String>>,
-    ) -> String {
-        let wire_name = serde_rename
-            .map(|s| s.as_str())
-            .or_else(|| config_renames.and_then(|r| r.get(field_name)).map(|s| s.as_str()))
-            .unwrap_or(field_name);
-        if is_valid_rust_ident_chars(wire_name) {
-            rust_raw_ident(wire_name)
-        } else {
-            // Wire name contains characters that are not valid in a Rust identifier (e.g. hyphens,
-            // slashes in serde renames like "self-harm" or "self-harm/intent").  Fall back to the
-            // Rust field name, which is guaranteed to be a valid identifier.
-            field_name.to_string()
+        let TypeRef::Named(ref type_name) = field.ty else {
+            return false;
+        };
+        // A nested struct with its own `Default`.
+        if api.types.iter().any(|t| t.name == *type_name && t.has_default) {
+            return true;
         }
+        // A data enum (tagged union — it lives in `api.enums`, not `api.types`) carried with a serde
+        // default. Such a field is None-able in the public surface, so its `#[new]` param is `Option<T>`
+        // (None falls back to the core default via `unwrap_or_else`). This lets the converter pass the
+        // coerced value or None directly rather than a conditional `**{...}` keyword-spread that no
+        // type checker can verify.
+        field.default.as_deref() == Some("/* serde(default) */")
+            && api
+                .enums
+                .iter()
+                .any(|e| e.name == *type_name && crate::codegen::generators::enum_has_data_variants(e))
     }
 
     // Check if this type has an options-field bridge (e.g., ParseOptions.visitor).