Skip to main content

hyprstream_ts_codegen/ts_codegen/
builders.rs

1//! Generate TypeScript request builder functions.
2//!
3//! For each request union variant, generates a function that constructs
4//! a Cap'n Proto binary message with correct wire format offsets.
5//!
6//! Scoped clients get builder functions that construct the full chain:
7//! root → init inner struct → set scope fields → set discriminant → payload.
8
9use hyprstream_rpc_build::schema::types::{
10    EnumDef, FieldDef, FieldSection, ParsedSchema, ScopedClient, StructDef,
11};
12use hyprstream_rpc_build::util::{to_camel_case, to_pascal_case};
13
14use super::{bool_bit_index, capnp_to_ts_type, data_byte_offset, is_data_scalar, is_primitive};
15
16/// Generate all request builder functions for a service.
17pub fn generate_builders(out: &mut String, service_name: &str, schema: &ParsedSchema) {
18    let req_struct = match &schema.request_struct {
19        Some(s) => s,
20        None => return,
21    };
22
23    let pascal = to_pascal_case(service_name);
24
25    // Non-union fields from the root request struct (e.g., `id`)
26    let non_union_fields: Vec<&FieldDef> = req_struct.non_union_fields().collect();
27
28    // Discriminant byte offset (discriminant_offset is in u16 units)
29    let disc_byte_off = req_struct.discriminant_offset * 2;
30
31    // Filter out scoped variants (they get separate builders)
32    let scoped_names: Vec<&str> = schema
33        .scoped_clients
34        .iter()
35        .map(|sc| sc.factory_name.as_str())
36        .collect();
37
38    // Top-level (non-scoped) builder functions
39    for variant in &schema.request_variants {
40        if scoped_names.contains(&variant.name.as_str()) {
41            continue;
42        }
43
44        let variant_field = req_struct
45            .fields
46            .iter()
47            .find(|f| f.name == variant.name && f.discriminant_value != 0xFFFF);
48
49        let disc_value = variant_field.map(|f| f.discriminant_value).unwrap_or(0);
50
51        let is_void = variant.type_name == "Void";
52        let is_prim = is_primitive(&variant.type_name) && !is_void;
53        let payload_struct = if !is_void && !is_prim {
54            schema.structs.iter().find(|s| s.name == variant.type_name)
55        } else {
56            None
57        };
58
59        let fn_name = format!("build{pascal}Request_{}", variant.name);
60
61        // Parameters: non-union fields + optional payload
62        let mut params = Vec::new();
63        for f in &non_union_fields {
64            params.push(format!(
65                "{}: {}",
66                to_camel_case(&f.name),
67                capnp_to_ts_type(&f.type_name)
68            ));
69        }
70        if !is_void {
71            if let Some(ps) = payload_struct {
72                params.push(format!("p: {}", ps.name));
73            } else if is_prim {
74                params.push(format!("p: {}", capnp_to_ts_type(&variant.type_name)));
75            }
76        }
77
78        out.push_str(&format!(
79            "function {fn_name}({}): Uint8Array {{\n",
80            params.join(", ")
81        ));
82        out.push_str(&format!(
83            "  const msg = new CapnpArena({}, {});\n",
84            req_struct.data_words, req_struct.pointer_words
85        ));
86
87        // Per-function gensym counter — unique IDs for list builder variables
88        let mut counter = 0u32;
89
90        // Set non-union fields
91        for f in &non_union_fields {
92            emit_field_setter(
93                out,
94                "msg",
95                f,
96                &to_camel_case(&f.name),
97                "  ",
98                &schema.enums,
99                &schema.structs,
100                &mut counter,
101            );
102        }
103
104        // Set discriminant
105        out.push_str(&format!(
106            "  msg.setUint16({disc_byte_off}, {disc_value}); // {}\n",
107            variant.name
108        ));
109
110        // Set variant payload
111        if is_void {
112            // Nothing
113        } else if is_prim {
114            if let Some(vf) = variant_field {
115                emit_field_setter(
116                    out,
117                    "msg",
118                    vf,
119                    "p",
120                    "  ",
121                    &schema.enums,
122                    &schema.structs,
123                    &mut counter,
124                );
125            }
126        } else if let Some(ps) = payload_struct {
127            if let Some(vf) = variant_field {
128                emit_struct_init(out, vf, ps, "msg", "p", "  ", schema, &mut counter);
129            }
130        }
131
132        out.push_str("  return msg.finish();\n");
133        out.push_str("}\n\n");
134    }
135
136    // Scoped builder functions (recursive for nested clients)
137    for sc in &schema.scoped_clients {
138        generate_scoped_builders(
139            out,
140            service_name,
141            schema,
142            sc,
143            &[],
144            req_struct,
145            &non_union_fields,
146        );
147    }
148}
149
150/// Generate builder functions for a scoped client's methods.
151///
152/// `ancestors` tracks the scoped client chain from outermost to the parent of `sc`.
153/// Each ancestor's scope fields + discriminant are written into the chain.
154#[allow(clippy::too_many_arguments)]
155fn generate_scoped_builders(
156    out: &mut String,
157    service_name: &str,
158    schema: &ParsedSchema,
159    sc: &ScopedClient,
160    ancestors: &[&ScopedClient],
161    root_struct: &StructDef,
162    root_non_union_fields: &[&FieldDef],
163) {
164    let pascal = to_pascal_case(service_name);
165
166    // Build the function name prefix from the ancestor chain
167    let mut name_chain = String::new();
168    for anc in ancestors {
169        name_chain.push_str(&format!("_{}", anc.factory_name));
170    }
171    name_chain.push_str(&format!("_{}", sc.factory_name));
172
173    // Filter out nested scoped variants (they get their own builders)
174    let nested_names: Vec<&str> = sc
175        .nested_clients
176        .iter()
177        .map(|nc| nc.factory_name.as_str())
178        .collect();
179
180    // All scope fields from ancestors + current
181    let all_scope_fields: Vec<&FieldDef> = ancestors
182        .iter()
183        .flat_map(|a| a.scope_fields.iter())
184        .chain(sc.scope_fields.iter())
185        .collect();
186
187    for variant in &sc.inner_request_variants {
188        if nested_names.contains(&variant.name.as_str()) {
189            continue;
190        }
191
192        let is_void = variant.type_name == "Void";
193        let is_prim = is_primitive(&variant.type_name) && !is_void;
194        let payload_struct = if !is_void && !is_prim {
195            schema.structs.iter().find(|s| s.name == variant.type_name)
196        } else {
197            None
198        };
199
200        let fn_name = format!("build{pascal}Request{name_chain}_{}", variant.name);
201
202        // Parameters: root non-union fields + all scope fields + optional payload
203        let mut params = Vec::new();
204        for f in root_non_union_fields {
205            params.push(format!(
206                "{}: {}",
207                to_camel_case(&f.name),
208                capnp_to_ts_type(&f.type_name)
209            ));
210        }
211        for f in &all_scope_fields {
212            params.push(format!(
213                "{}: {}",
214                to_camel_case(&f.name),
215                capnp_to_ts_type(&f.type_name)
216            ));
217        }
218        if !is_void {
219            if let Some(ps) = payload_struct {
220                params.push(format!("p: {}", ps.name));
221            } else if is_prim {
222                params.push(format!("p: {}", capnp_to_ts_type(&variant.type_name)));
223            }
224        }
225
226        out.push_str(&format!(
227            "function {fn_name}({}): Uint8Array {{\n",
228            params.join(", ")
229        ));
230        out.push_str(&format!(
231            "  const msg = new CapnpArena({}, {});\n",
232            root_struct.data_words, root_struct.pointer_words
233        ));
234
235        // Per-function gensym counter — unique IDs for list builder variables
236        let mut counter = 0u32;
237
238        // Set root non-union fields
239        for f in root_non_union_fields {
240            emit_field_setter(
241                out,
242                "msg",
243                f,
244                &to_camel_case(&f.name),
245                "  ",
246                &schema.enums,
247                &schema.structs,
248                &mut counter,
249            );
250        }
251
252        // Build the chain: root → ancestors → current → method
253        // Level 0: root → first scope (sc or first ancestor)
254        let chain: Vec<&ScopedClient> = ancestors
255            .iter()
256            .copied()
257            .chain(std::iter::once(sc))
258            .collect();
259
260        let mut builder_var = "msg".to_owned();
261        for (i, level) in chain.iter().enumerate() {
262            // Find the variant field in the parent struct for this level
263            let (parent_disc_byte_off, variant_disc_value, variant_slot_offset) =
264                find_chain_variant_info(i, &chain, root_struct, schema);
265
266            // Set parent discriminant for this level's factory
267            out.push_str(&format!(
268                "  {builder_var}.setUint16({parent_disc_byte_off}, {variant_disc_value}); // {}\n",
269                level.factory_name
270            ));
271
272            // Init the inner struct at the variant's pointer slot
273            let inner_struct_name = find_inner_struct_name(i, &chain, root_struct, schema);
274            let inner_struct = schema.structs.iter().find(|s| s.name == inner_struct_name);
275
276            if let Some(is) = inner_struct {
277                let var_name = format!("_s{i}");
278                out.push_str(&format!(
279                    "  const {var_name} = {builder_var}.initStruct({variant_slot_offset}, {}, {});\n",
280                    is.data_words, is.pointer_words
281                ));
282
283                // Set scope fields on this level's struct
284                for sf in &level.scope_fields {
285                    emit_field_setter(
286                        out,
287                        &var_name,
288                        sf,
289                        &to_camel_case(&sf.name),
290                        "  ",
291                        &schema.enums,
292                        &schema.structs,
293                        &mut counter,
294                    );
295                }
296
297                builder_var = var_name;
298            }
299        }
300
301        // Now set the method discriminant on the innermost struct
302        let _innermost_sc = chain.last().expect("chain must be non-empty");
303        let inner_struct_name =
304            find_inner_struct_name(chain.len() - 1, &chain, root_struct, schema);
305        let inner_struct = schema.structs.iter().find(|s| s.name == inner_struct_name);
306
307        if let Some(is) = inner_struct {
308            let inner_disc_byte_off = is.discriminant_offset * 2;
309            let method_field = is
310                .fields
311                .iter()
312                .find(|f| f.name == variant.name && f.discriminant_value != 0xFFFF);
313
314            if let Some(mf) = method_field {
315                out.push_str(&format!(
316                    "  {builder_var}.setUint16({inner_disc_byte_off}, {}); // {}\n",
317                    mf.discriminant_value, variant.name
318                ));
319
320                // Set method payload
321                if is_void {
322                    // Nothing
323                } else if is_prim {
324                    emit_field_setter(
325                        out,
326                        &builder_var,
327                        mf,
328                        "p",
329                        "  ",
330                        &schema.enums,
331                        &schema.structs,
332                        &mut counter,
333                    );
334                } else if let Some(ps) = payload_struct {
335                    emit_struct_init(out, mf, ps, &builder_var, "p", "  ", schema, &mut counter);
336                }
337            }
338        }
339
340        out.push_str("  return msg.finish();\n");
341        out.push_str("}\n\n");
342    }
343
344    // Recurse for nested scoped clients
345    let mut new_ancestors: Vec<&ScopedClient> = ancestors.to_vec();
346    new_ancestors.push(sc);
347    for nc in &sc.nested_clients {
348        generate_scoped_builders(
349            out,
350            service_name,
351            schema,
352            nc,
353            &new_ancestors,
354            root_struct,
355            root_non_union_fields,
356        );
357    }
358}
359
360/// Find the discriminant byte offset, discriminant value, and slot offset
361/// for the variant that leads to `chain[level]` from its parent.
362fn find_chain_variant_info(
363    level: usize,
364    chain: &[&ScopedClient],
365    root_struct: &StructDef,
366    schema: &ParsedSchema,
367) -> (u32, u16, u32) {
368    if level == 0 {
369        // Parent is the root request struct
370        let disc_byte_off = root_struct.discriminant_offset * 2;
371        let variant_field = root_struct
372            .fields
373            .iter()
374            .find(|f| f.name == chain[0].factory_name && f.discriminant_value != 0xFFFF);
375        let disc_value = variant_field.map(|f| f.discriminant_value).unwrap_or(0);
376        let slot_offset = variant_field.map(|f| f.slot_offset).unwrap_or(0);
377        (disc_byte_off, disc_value, slot_offset)
378    } else {
379        // Parent is the inner struct of chain[level-1]
380        let parent_inner_name = find_inner_struct_name(level - 1, chain, root_struct, schema);
381        let parent_struct = schema.structs.iter().find(|s| s.name == parent_inner_name);
382        if let Some(ps) = parent_struct {
383            let disc_byte_off = ps.discriminant_offset * 2;
384            let variant_field = ps
385                .fields
386                .iter()
387                .find(|f| f.name == chain[level].factory_name && f.discriminant_value != 0xFFFF);
388            let disc_value = variant_field.map(|f| f.discriminant_value).unwrap_or(0);
389            let slot_offset = variant_field.map(|f| f.slot_offset).unwrap_or(0);
390            (disc_byte_off, disc_value, slot_offset)
391        } else {
392            (0, 0, 0)
393        }
394    }
395}
396
397/// Find the inner struct type name for `chain[level]`.
398///
399/// The inner struct name comes from the variant's type_name in the parent struct.
400fn find_inner_struct_name(
401    level: usize,
402    chain: &[&ScopedClient],
403    root_struct: &StructDef,
404    schema: &ParsedSchema,
405) -> String {
406    if level == 0 {
407        // Look up the variant type in the root request struct
408        let variant_field = root_struct
409            .fields
410            .iter()
411            .find(|f| f.name == chain[0].factory_name && f.discriminant_value != 0xFFFF);
412        variant_field
413            .map(|f| f.type_name.clone())
414            .unwrap_or_default()
415    } else {
416        // Look up the variant type in chain[level-1]'s inner struct
417        let parent_inner_name = find_inner_struct_name(level - 1, chain, root_struct, schema);
418        let parent_struct = schema.structs.iter().find(|s| s.name == parent_inner_name);
419        if let Some(ps) = parent_struct {
420            let variant_field = ps
421                .fields
422                .iter()
423                .find(|f| f.name == chain[level].factory_name && f.discriminant_value != 0xFFFF);
424            variant_field
425                .map(|f| f.type_name.clone())
426                .unwrap_or_default()
427        } else {
428            String::new()
429        }
430    }
431}
432
433// ---------------------------------------------------------------------------
434// Standalone struct builders
435// ---------------------------------------------------------------------------
436
437/// Generate standalone builder functions for all structs in a schema.
438///
439/// For union-bearing structs: one exported function per union variant:
440/// `build{StructName}_{variant}(nonUnionFields..., payload?): Uint8Array`.
441///
442/// For non-union structs: one exported function:
443/// `build{StructName}(p: StructName): Uint8Array`.
444///
445/// Skips Option* wrapper structs and service request/response structs.
446pub fn generate_struct_builders(out: &mut String, schema: &ParsedSchema) {
447    for sd in &schema.structs {
448        if sd.option_inner_type().is_some() {
449            continue;
450        }
451        // Skip service request/response structs (handled by generate_builders)
452        if is_service_struct(sd, schema) {
453            continue;
454        }
455
456        if !sd.has_union {
457            generate_plain_struct_builder(out, sd, schema);
458            continue;
459        }
460
461        let non_union_fields: Vec<&FieldDef> = sd.non_union_fields().collect();
462        let union_fields: Vec<&FieldDef> = sd.union_fields().collect();
463
464        let disc_byte_off = sd.discriminant_offset * 2;
465
466        for variant in &union_fields {
467            let is_void = variant.type_name == "Void";
468            let is_prim = is_primitive(&variant.type_name) && !is_void;
469            let payload_struct = if !is_void && !is_prim {
470                schema.structs.iter().find(|s| s.name == variant.type_name)
471            } else {
472                None
473            };
474            let group_leaves = super::group_arm_leaves(sd, variant);
475
476            let fn_name = format!("build{}_{}", sd.name, variant.name);
477
478            // Parameters: non-union fields + optional payload
479            let mut params = Vec::new();
480            for f in &non_union_fields {
481                params.push(format!(
482                    "{}: {}",
483                    to_camel_case(&f.name),
484                    capnp_to_ts_type(&f.type_name)
485                ));
486            }
487            if !is_void {
488                if let Some(ps) = payload_struct {
489                    params.push(format!("p: {}", ps.name));
490                } else if is_prim {
491                    params.push(format!("p: {}", capnp_to_ts_type(&variant.type_name)));
492                } else if group_leaves.is_some() {
493                    params.push(format!(
494                        "p: {}",
495                        super::group_arm_type_name(&sd.name, &variant.name)
496                    ));
497                }
498            }
499
500            out.push_str(&format!(
501                "export function {fn_name}({}): Uint8Array {{\n",
502                params.join(", ")
503            ));
504            out.push_str(&format!(
505                "  const msg = new CapnpArena({}, {});\n",
506                sd.data_words, sd.pointer_words
507            ));
508
509            // Per-function gensym counter — unique IDs for list builder variables
510            let mut counter = 0u32;
511
512            // Set non-union fields
513            for f in &non_union_fields {
514                emit_field_setter(
515                    out,
516                    "msg",
517                    f,
518                    &to_camel_case(&f.name),
519                    "  ",
520                    &schema.enums,
521                    &schema.structs,
522                    &mut counter,
523                );
524            }
525
526            // Set discriminant
527            out.push_str(&format!(
528                "  msg.setUint16({disc_byte_off}, {}); // {}\n",
529                variant.discriminant_value, variant.name
530            ));
531
532            // Set variant payload
533            if is_void {
534                // Nothing
535            } else if is_prim {
536                emit_field_setter(
537                    out,
538                    "msg",
539                    variant,
540                    "p",
541                    "  ",
542                    &schema.enums,
543                    &schema.structs,
544                    &mut counter,
545                );
546            } else if let Some(ps) = payload_struct {
547                emit_struct_init(out, variant, ps, "msg", "p", "  ", schema, &mut counter);
548            } else if let Some(leaves) = group_leaves {
549                emit_group_arm_setter(
550                    out,
551                    "msg",
552                    "p",
553                    leaves,
554                    "  ",
555                    &schema.enums,
556                    &schema.structs,
557                    &mut counter,
558                );
559            }
560
561            out.push_str("  return msg.finish();\n");
562            out.push_str("}\n\n");
563        }
564    }
565}
566
567/// Generate a single builder function for a non-union struct.
568///
569/// `export function build{StructName}(p: StructName): Uint8Array`
570fn generate_plain_struct_builder(out: &mut String, sd: &StructDef, schema: &ParsedSchema) {
571    let fn_name = format!("build{}", sd.name);
572
573    out.push_str(&format!(
574        "export function {fn_name}(p: {}): Uint8Array {{\n",
575        sd.name
576    ));
577    out.push_str(&format!(
578        "  const msg = new CapnpArena({}, {});\n",
579        sd.data_words, sd.pointer_words
580    ));
581
582    let mut counter = 0u32;
583    for f in &sd.fields {
584        let raw_expr = format!("p.{}", to_camel_case(&f.name));
585        let value_expr = value_expr_for_field(f, &raw_expr, &schema.enums);
586        emit_field_setter(
587            out,
588            "msg",
589            f,
590            &value_expr,
591            "  ",
592            &schema.enums,
593            &schema.structs,
594            &mut counter,
595        );
596    }
597
598    out.push_str("  return msg.finish();\n");
599    out.push_str("}\n\n");
600}
601
602/// Check if a struct is the service request or response struct (handled by generate_builders).
603fn is_service_struct(sd: &StructDef, schema: &ParsedSchema) -> bool {
604    schema
605        .request_struct
606        .as_ref()
607        .is_some_and(|rs| rs.name == sd.name)
608        || schema
609            .response_struct
610            .as_ref()
611            .is_some_and(|rs| rs.name == sd.name)
612}
613
614// ---------------------------------------------------------------------------
615// Field emission helpers
616// ---------------------------------------------------------------------------
617
618/// Emit a setter call for a field on a builder variable.
619///
620/// `counter` is a per-function gensym counter. Each List(Struct) field claims the
621/// next ID (`_sl{n}`, `_sv{n}`, `_si{n}`) and increments the counter, guaranteeing
622/// unique variable names across all nesting levels within a single builder function.
623fn emit_field_setter(
624    out: &mut String,
625    builder_var: &str,
626    field: &FieldDef,
627    value_expr: &str,
628    indent: &str,
629    enums: &[EnumDef],
630    structs: &[StructDef],
631    counter: &mut u32,
632) {
633    match field.section {
634        FieldSection::Data => {
635            let byte_off = data_byte_offset(field);
636            if field.type_name == "Bool" {
637                let bit = bool_bit_index(field);
638                out.push_str(&format!(
639                    "{indent}{builder_var}.setBool({byte_off}, {bit}, {value_expr});\n"
640                ));
641            } else if is_data_scalar(&field.type_name) {
642                if let Some(method) = super::setter_method(&field.type_name) {
643                    out.push_str(&format!(
644                        "{indent}{builder_var}.{method}({byte_off}, {value_expr});\n"
645                    ));
646                }
647            } else {
648                // Enum type — stored as UInt16, needs ordinal conversion
649                let enum_def = enums.iter().find(|e| e.name == field.type_name);
650                if let Some(ed) = enum_def {
651                    super::emit_enum_setter(out, indent, builder_var, byte_off, value_expr, ed);
652                } else {
653                    out.push_str(&format!(
654                        "{indent}{builder_var}.setUint16({byte_off}, {value_expr} as unknown as number);\n"
655                    ));
656                }
657            }
658        }
659        FieldSection::Pointer => {
660            if let Some(method) = super::setter_method(&field.type_name) {
661                out.push_str(&format!(
662                    "{indent}{builder_var}.{method}({}, {value_expr});\n",
663                    field.slot_offset
664                ));
665            } else if let Some(inner) = super::extract_list_inner_type(&field.type_name) {
666                if let Some(method) = super::list_setter_method(inner) {
667                    // List(<scalar/Text/Data>) — the runtime has a direct setter
668                    // that takes the whole array (see capnp.ts).
669                    out.push_str(&format!(
670                        "{indent}{builder_var}.{method}({}, {value_expr});\n",
671                        field.slot_offset
672                    ));
673                } else if let Some(nested_inner) = super::extract_list_inner_type(inner) {
674                    // List(List(<nested_inner>)) — a doubly-nested primitive list
675                    // (e.g. `embeddings: List(List(Float32))`). The runtime has a
676                    // direct setter that takes the whole nested array.
677                    if let Some(method) = super::nested_list_setter_method(nested_inner) {
678                        out.push_str(&format!(
679                            "{indent}{builder_var}.{method}({}, {value_expr});\n",
680                            field.slot_offset
681                        ));
682                    } else {
683                        panic!(
684                            "ts_codegen: field `{}: {}` is a nested list of `{nested_inner}` \
685                             — the capnp.ts runtime does not yet support this inner element \
686                             type for List(List(_)). This must be implemented in message.rs \
687                             before this field can be referenced; a silently-dropped comment \
688                             is not acceptable (#758).",
689                            field.name, field.type_name
690                        );
691                    }
692                }
693                // List(Struct) — init struct list and set each element's fields.
694                // Claim a unique ID from the per-function counter so nested lists at
695                // the same capnp pointer slot never shadow each other (TDZ collision).
696                else if let Some(sd) = structs.iter().find(|s| s.name == inner) {
697                    let id = *counter;
698                    *counter += 1;
699                    let sl = format!("_sl{id}");
700                    let sv = format!("_sv{id}");
701                    let si = format!("_si{id}");
702                    out.push_str(&format!("{indent}{{\n"));
703                    out.push_str(&format!(
704                        "{indent}  const {sl} = {builder_var}.initStructList({}, {value_expr}.length, {}, {});\n",
705                        field.slot_offset, sd.data_words, sd.pointer_words
706                    ));
707                    out.push_str(&format!(
708                        "{indent}  {value_expr}.forEach(({sv}, {si}) => {{\n"
709                    ));
710                    // Set non-union fields
711                    for sf in &sd.fields {
712                        if sf.discriminant_value != 0xFFFF {
713                            continue;
714                        }
715                        let inner_builder = format!("{sl}[{si}]");
716                        let raw_inner_value = format!("{sv}.{}", to_camel_case(&sf.name));
717                        let inner_value = value_expr_for_field(sf, &raw_inner_value, enums);
718                        emit_field_setter(
719                            out,
720                            &inner_builder,
721                            sf,
722                            &inner_value,
723                            &format!("{indent}    "),
724                            enums,
725                            structs,
726                            counter,
727                        );
728                    }
729                    // Handle union variants in list elements
730                    if sd.has_union {
731                        let inner_builder = format!("{sl}[{si}]");
732                        let inner_indent = format!("{indent}    ");
733                        emit_union_element_setter(
734                            out,
735                            sd,
736                            &inner_builder,
737                            &sv,
738                            &inner_indent,
739                            enums,
740                            structs,
741                            counter,
742                        );
743                    }
744                    out.push_str(&format!("{indent}  }});\n"));
745                    out.push_str(&format!("{indent}}}\n"));
746                } else {
747                    panic!(
748                        "ts_codegen: field `{}: {}` references struct `{inner}`, which was \
749                         not found among the parsed schema's structs. This means the \
750                         generator has a dangling struct reference — regenerate the CGR \
751                         input and investigate the parser/resolution logic; this must never \
752                         silently degrade to a comment (#725).",
753                        field.name, field.type_name
754                    );
755                }
756            } else if let Some(sd) = structs.iter().find(|s| s.name == field.type_name) {
757                if let Some(inner_name) = sd.option_inner_type() {
758                    emit_option_setter(out, field, sd, inner_name, builder_var, value_expr, indent);
759                } else {
760                    // Non-option struct pointer — init and set fields.
761                    // Use gensym counter for the local variable to avoid TDZ collisions
762                    // when the same slot_offset appears in nested or sibling struct pointers.
763                    let sp_id = *counter;
764                    *counter += 1;
765                    let sp_var = format!("_sp{sp_id}");
766                    out.push_str(&format!("{indent}if ({value_expr} != null) {{\n"));
767                    out.push_str(&format!(
768                        "{indent}  const {sp_var} = {builder_var}.initStruct({}, {}, {});\n",
769                        field.slot_offset, sd.data_words, sd.pointer_words
770                    ));
771                    for sf in &sd.fields {
772                        if sf.discriminant_value != 0xFFFF {
773                            continue;
774                        }
775                        let raw_val_expr = format!("{value_expr}.{}", to_camel_case(&sf.name));
776                        let val_expr = value_expr_for_field(sf, &raw_val_expr, enums);
777                        emit_field_setter(
778                            out,
779                            &sp_var,
780                            sf,
781                            &val_expr,
782                            &format!("{indent}  "),
783                            enums,
784                            structs,
785                            counter,
786                        );
787                    }
788                    if sd.has_union {
789                        emit_union_element_setter(
790                            out,
791                            sd,
792                            &sp_var,
793                            value_expr,
794                            &format!("{indent}  "),
795                            enums,
796                            structs,
797                            counter,
798                        );
799                    }
800                    out.push_str(&format!("{indent}}}\n"));
801                }
802            } else {
803                panic!(
804                    "ts_codegen: field `{}: {}` is an unrecognized pointer type — neither a \
805                     primitive, a List(_), nor a known struct (e.g. AnyPointer/Interface are \
806                     not supported). This must be a hard generator error, never a silently \
807                     skipped comment (#725).",
808                    field.name, field.type_name
809                );
810            }
811        }
812        FieldSection::Group => {} // groups are inlined, not handled here
813    }
814}
815
816/// Emit code to init a sub-struct and set its non-union fields.
817///
818/// For optional fields (field.optional = true), adds `?? defaultValue` coalescing
819/// so TypeScript strict mode doesn't reject `T | undefined` where `T` is expected.
820fn emit_struct_init(
821    out: &mut String,
822    ptr_field: &FieldDef,
823    struct_def: &StructDef,
824    builder_var: &str,
825    param_name: &str,
826    indent: &str,
827    schema: &ParsedSchema,
828    counter: &mut u32,
829) {
830    out.push_str(&format!(
831        "{indent}const _ps = {builder_var}.initStruct({}, {}, {});\n",
832        ptr_field.slot_offset, struct_def.data_words, struct_def.pointer_words
833    ));
834
835    for f in &struct_def.fields {
836        if f.discriminant_value != 0xFFFF {
837            continue;
838        }
839        let raw_expr = format!("{param_name}.{}", to_camel_case(&f.name));
840        let value_expr = value_expr_for_field(f, &raw_expr, &schema.enums);
841        emit_field_setter(
842            out,
843            "_ps",
844            f,
845            &value_expr,
846            indent,
847            &schema.enums,
848            &schema.structs,
849            counter,
850        );
851    }
852}
853
854/// Write an inline union `group` arm's leaf fields onto `builder_var`.
855///
856/// The leaves live in the ENCLOSING struct's sections (a group has no own
857/// pointer), so each is set directly on `builder_var` at its own slot offset —
858/// the same per-field setter path a normal field uses. `data_expr` is the
859/// arm's typed group object.
860fn emit_group_arm_setter(
861    out: &mut String,
862    builder_var: &str,
863    data_expr: &str,
864    leaves: &[FieldDef],
865    indent: &str,
866    enums: &[EnumDef],
867    structs: &[StructDef],
868    counter: &mut u32,
869) {
870    for leaf in leaves {
871        let raw = format!("{data_expr}.{}", to_camel_case(&leaf.name));
872        let val = value_expr_for_field(leaf, &raw, enums);
873        emit_field_setter(
874            out,
875            builder_var,
876            leaf,
877            &val,
878            indent,
879            enums,
880            structs,
881            counter,
882        );
883    }
884}
885
886/// Optional fields carry `T | undefined`; coalesce to the capnp default so
887/// TypeScript strict mode doesn't reject passing `T | undefined` to a setter.
888fn value_expr_for_field(field: &FieldDef, raw_expr: &str, enums: &[EnumDef]) -> String {
889    if !field.optional {
890        return raw_expr.to_owned();
891    }
892
893    let default = if field.section == FieldSection::Data
894        && !is_data_scalar(&field.type_name)
895        && field.type_name != "Bool"
896    {
897        enums
898            .iter()
899            .find(|e| e.name == field.type_name)
900            .and_then(|e| e.variants.first())
901            .map(|(name, _)| format!("'{}'", to_camel_case(name)))
902            .unwrap_or_else(|| "0".into())
903    } else {
904        super::default_value_expr(&field.type_name).to_owned()
905    };
906
907    format!("{raw_expr} ?? {default}")
908}
909
910/// Emit code to write an Option* wrapper struct at a pointer slot.
911///
912/// Generates: if value !== undefined, init the option struct and set the discriminant + inner value.
913/// Else: leave the pointer null (cap'n proto default = none).
914fn emit_option_setter(
915    out: &mut String,
916    field: &FieldDef,
917    opt_struct: &StructDef,
918    inner_type_name: &str,
919    builder_var: &str,
920    value_expr: &str,
921    indent: &str,
922) {
923    let disc_byte_off = opt_struct.discriminant_offset * 2;
924
925    out.push_str(&format!(
926        "{indent}if ({value_expr} !== undefined && {value_expr} !== null) {{\n"
927    ));
928    out.push_str(&format!(
929        "{indent}  const _opt = {builder_var}.initStruct({}, {}, {});\n",
930        field.slot_offset, opt_struct.data_words, opt_struct.pointer_words
931    ));
932    out.push_str(&format!("{indent}  _opt.setUint16({disc_byte_off}, 1);\n")); // some discriminant = 1
933
934    // For pointer-type inners (Text, Data), the 'some' field lives in the pointer section at index 0.
935    // For data-type scalars, use the slot_offset * type_size as byte offset.
936    if inner_type_name == "Text" {
937        out.push_str(&format!("{indent}  _opt.setText(0, {value_expr});\n"));
938    } else if inner_type_name == "Data" {
939        out.push_str(&format!("{indent}  _opt.setData(0, {value_expr});\n"));
940    } else if let Some(method) = super::setter_method(inner_type_name) {
941        // Find the 'some' field slot offset for computing the byte offset
942        let some_field = opt_struct.fields.iter().find(|f| f.name == "some");
943        if let Some(sf) = some_field {
944            let some_byte_off = super::data_byte_offset(sf);
945            if inner_type_name == "Bool" {
946                let bit = super::bool_bit_index(sf);
947                out.push_str(&format!(
948                    "{indent}  _opt.setBool({some_byte_off}, {bit}, {value_expr});\n"
949                ));
950            } else {
951                out.push_str(&format!(
952                    "{indent}  _opt.{method}({some_byte_off}, {value_expr});\n"
953                ));
954            }
955        }
956    }
957    // else: unsupported inner type (nested struct, etc.) — leave as-is with discriminant set
958
959    out.push_str(&format!("{indent}}}\n"));
960    out.push_str(&format!(
961        "{indent}// else: null pointer = none (cap'n proto default)\n"
962    ));
963}
964
965/// Emit a switch statement that writes union discriminant + variant payload for a list element.
966///
967/// Used when a List(Struct) field contains a union struct (e.g., `List(StreamPayload)`).
968/// The element parameter is `{ variant: string; data: unknown }`.
969fn emit_union_element_setter(
970    out: &mut String,
971    sd: &StructDef,
972    builder_var: &str,
973    value_var: &str,
974    indent: &str,
975    enums: &[EnumDef],
976    structs: &[StructDef],
977    counter: &mut u32,
978) {
979    let disc_byte_off = sd.discriminant_offset * 2;
980    let union_fields: Vec<&FieldDef> = sd.union_fields().collect();
981
982    out.push_str(&format!("{indent}switch ({value_var}.variant) {{\n"));
983    for uf in &union_fields {
984        let ci = format!("{indent}  "); // case indent
985        let bi = format!("{indent}    "); // body indent
986        out.push_str(&format!("{ci}case '{}':\n", uf.name));
987        out.push_str(&format!(
988            "{bi}{builder_var}.setUint16({disc_byte_off}, {}); // {}\n",
989            uf.discriminant_value, uf.name
990        ));
991
992        if let Some(leaves) = super::group_arm_leaves(sd, uf) {
993            // Inline group arm — write its leaves directly on this struct.
994            out.push_str(&format!("{bi}{{\n"));
995            out.push_str(&format!(
996                "{bi}  const _ugd = {value_var}.data as {};\n",
997                super::group_arm_type_name(&sd.name, &uf.name)
998            ));
999            emit_group_arm_setter(
1000                out,
1001                builder_var,
1002                "_ugd",
1003                leaves,
1004                &format!("{bi}  "),
1005                enums,
1006                structs,
1007                counter,
1008            );
1009            out.push_str(&format!("{bi}}}\n"));
1010        } else if uf.type_name == "Void" {
1011            // Nothing to set
1012        } else if uf.section == FieldSection::Data && is_data_scalar(&uf.type_name) {
1013            let byte_off = data_byte_offset(uf);
1014            if let Some(method) = super::setter_method(&uf.type_name) {
1015                out.push_str(&format!(
1016                    "{bi}{builder_var}.{method}({byte_off}, {value_var}.data as {});\n",
1017                    capnp_to_ts_type(&uf.type_name)
1018                ));
1019            }
1020        } else if uf.type_name == "Text" {
1021            out.push_str(&format!(
1022                "{bi}{builder_var}.setText({}, {value_var}.data as string);\n",
1023                uf.slot_offset
1024            ));
1025        } else if uf.type_name == "Data" {
1026            out.push_str(&format!(
1027                "{bi}{builder_var}.setData({}, {value_var}.data as Uint8Array);\n",
1028                uf.slot_offset
1029            ));
1030        } else if let Some(ps) = structs.iter().find(|s| s.name == uf.type_name) {
1031            // Struct variant — init sub-struct and set its non-union fields
1032            out.push_str(&format!("{bi}{{\n"));
1033            out.push_str(&format!(
1034                "{bi}  const _ups = {builder_var}.initStruct({}, {}, {});\n",
1035                uf.slot_offset, ps.data_words, ps.pointer_words
1036            ));
1037            out.push_str(&format!(
1038                "{bi}  const _upd = {value_var}.data as {};\n",
1039                ps.name
1040            ));
1041            for sf in &ps.fields {
1042                if sf.discriminant_value != 0xFFFF {
1043                    continue;
1044                }
1045                let raw_val_expr = format!("_upd.{}", to_camel_case(&sf.name));
1046                let val_expr = value_expr_for_field(sf, &raw_val_expr, enums);
1047                emit_field_setter(
1048                    out,
1049                    "_ups",
1050                    sf,
1051                    &val_expr,
1052                    &format!("{bi}  "),
1053                    enums,
1054                    structs,
1055                    counter,
1056                );
1057            }
1058            out.push_str(&format!("{bi}}}\n"));
1059        }
1060
1061        out.push_str(&format!("{bi}break;\n"));
1062    }
1063    out.push_str(&format!("{indent}  default: break;\n"));
1064    out.push_str(&format!("{indent}}}\n"));
1065}
1066
1067#[cfg(test)]
1068mod tests {
1069    #![allow(clippy::expect_used, clippy::unwrap_used)]
1070
1071    use std::path::Path;
1072
1073    use hyprstream_rpc_build::schema::parse_from_cgr_path;
1074    use hyprstream_rpc_build::schema::types::{FieldDef, FieldSection, ParsedSchema, StructDef};
1075
1076    /// A struct with a `List(Data)` field (mirrors #725's `certHashes: List(Data)`
1077    /// repro in `streaming.capnp`'s `QuicReach`) plus a `List(Int64)` field
1078    /// (mirrors `worker.capnp`'s `supplementalGroups`), to catch the whole
1079    /// "any other currently-unresolved shapes" class the issue calls out, not
1080    /// just the one named example.
1081    const LIST_SCHEMA: &str = r#"
1082@0xd00dfeeda00dfeed;
1083
1084struct Reach {
1085  addr @0 :Text;
1086  certHashes @1 :List(Data);
1087  supplementalGroups @2 :List(Int64);
1088}
1089"#;
1090
1091    /// Compile `schema_src` to a CGR keyed on `name` and parse it. Uses a
1092    /// per-(pid, name) temp dir so parallel tests don't collide.
1093    fn parse_schema(name: &str, schema_src: &str) -> ParsedSchema {
1094        let tmp =
1095            std::env::temp_dir().join(format!("hyprstream_ts_bld_{name}_{}", std::process::id()));
1096        std::fs::create_dir_all(&tmp).expect("create temp dir");
1097
1098        let capnp_path = tmp.join(format!("{name}.capnp"));
1099        std::fs::write(&capnp_path, schema_src).expect("write capnp");
1100
1101        let cgr_path = tmp.join(format!("{name}.cgr"));
1102        capnpc::CompilerCommand::new()
1103            .src_prefix(&tmp)
1104            .file(&capnp_path)
1105            .raw_code_generator_request_path(&cgr_path)
1106            .run()
1107            .expect("compile capnp to CGR");
1108
1109        let parsed = parse_from_cgr_path(Path::new(&cgr_path), name).expect("parse CGR");
1110        let _ = std::fs::remove_dir_all(&tmp);
1111        parsed
1112    }
1113
1114    #[test]
1115    fn list_data_and_list_scalar_fields_emit_real_setters_not_comments() {
1116        let schema = parse_schema("reach", LIST_SCHEMA);
1117        let mut out = String::new();
1118        super::generate_struct_builders(&mut out, &schema);
1119
1120        // The #725 regression: these must never degrade to a comment.
1121        assert!(
1122            !out.contains("struct definition not found"),
1123            "must never emit the silent-degrade comment:\n{out}"
1124        );
1125        assert!(
1126            !out.contains("not yet supported by runtime"),
1127            "must never emit the silent-degrade comment:\n{out}"
1128        );
1129
1130        // certHashes: List(Data) must use the real runtime setter.
1131        assert!(
1132            out.contains(".setDataList("),
1133            "expected a real setDataList call for List(Data):\n{out}"
1134        );
1135        // supplementalGroups: List(Int64) must use the real runtime setter too —
1136        // this is the "any other currently-unresolved shapes" half of the fix.
1137        assert!(
1138            out.contains(".setInt64List("),
1139            "expected a real setInt64List call for List(Int64):\n{out}"
1140        );
1141    }
1142
1143    /// A nested-list (`List(List(Float32))`) field, mirroring the
1144    /// `embeddings` field of `EmbedImagesResponse` in `inference.capnp` (the
1145    /// #758 repro — see the matching parser-side test in `parsers.rs`).
1146    const NESTED_LIST_SCHEMA: &str = r#"
1147@0xd00dfeeda00dfeec;
1148
1149struct EmbedImagesResponse {
1150  embeddings @0 :List(List(Float32));
1151  dimensions @1 :UInt32;
1152}
1153"#;
1154
1155    #[test]
1156    fn nested_list_field_builds_with_real_setter() {
1157        let schema = parse_schema("embedbuild", NESTED_LIST_SCHEMA);
1158        let mut out = String::new();
1159        super::generate_struct_builders(&mut out, &schema);
1160
1161        // Must write through the real nested-list runtime setter, never the
1162        // old #725 hard-panic ("nested list ... does not yet support double
1163        // indirection") and never a silently dropped comment.
1164        assert!(
1165            out.contains(".setFloat32ListList(0,"),
1166            "expected a real setFloat32ListList call for List(List(Float32)):\n{out}"
1167        );
1168        assert!(
1169            !out.contains("does not yet support double indirection"),
1170            "must never emit the old #725 nested-list panic path:\n{out}"
1171        );
1172        // The sibling scalar field must still build correctly alongside it.
1173        assert!(out.contains(".setUint32(0,"), "{out}");
1174    }
1175
1176    /// A field whose type references a struct that isn't in the parsed
1177    /// schema's `structs` list is a genuine generator bug (a dangling
1178    /// reference) — it must be a hard build failure, never a silently
1179    /// emitted comment.
1180    #[test]
1181    #[should_panic(expected = "dangling struct reference")]
1182    fn dangling_struct_reference_in_list_field_panics() {
1183        let field = FieldDef {
1184            name: "ghosts".to_owned(),
1185            type_name: "List(GhostStruct)".to_owned(),
1186            description: String::new(),
1187            fixed_size: None,
1188            max_len: None,
1189            optional: false,
1190            slot_offset: 0,
1191            section: FieldSection::Pointer,
1192            discriminant_value: 0xFFFF,
1193            serde_rename: None,
1194            domain_type: None,
1195        };
1196        let sd = StructDef {
1197            name: "Haunted".to_owned(),
1198            fields: vec![field],
1199            has_union: false,
1200            domain_type: None,
1201            origin_file: None,
1202            data_words: 0,
1203            pointer_words: 1,
1204            discriminant_count: 0,
1205            discriminant_offset: 0,
1206            union_arms: vec![],
1207        };
1208        let schema = ParsedSchema {
1209            request_variants: vec![],
1210            response_variants: vec![],
1211            structs: vec![sd],
1212            scoped_clients: vec![],
1213            enums: vec![],
1214            request_struct: None,
1215            response_struct: None,
1216        };
1217
1218        let mut out = String::new();
1219        super::generate_struct_builders(&mut out, &schema);
1220    }
1221}