global: snapshot

2026-07-19 06:58:11 -07:00 · 2026-01-11 17:19:00 +01:00
parent 6f45ec13f3
commit ea70c381de
419 changed files with 38059 additions and 7653 deletions
@@ -21,24 +21,29 @@ pub fn generate_api_methods(output: &mut String, endpoints: &[Endpoint]) {
        if let Some(desc) = &endpoint.description
            && endpoint.summary.as_ref() != Some(desc)
        {
-            writeln!(output, "   * @description {}", desc).unwrap();
+            writeln!(output, "   *").unwrap();
+            writeln!(output, "   * {}", desc).unwrap();
+        }
+
+        if !endpoint.path_params.is_empty() || !endpoint.query_params.is_empty() {
+            writeln!(output, "   *").unwrap();
        }

        for param in &endpoint.path_params {
-            let desc = param.description.as_deref().unwrap_or("");
+            let desc = format_param_desc(param.description.as_deref());
            writeln!(
                output,
-                "   * @param {{{}}} {} {}",
+                "   * @param {{{}}} {}{}",
                param.param_type, param.name, desc
            )
            .unwrap();
        }
        for param in &endpoint.query_params {
            let optional = if param.required { "" } else { "=" };
-            let desc = param.description.as_deref().unwrap_or("");
+            let desc = format_param_desc(param.description.as_deref());
            writeln!(
                output,
-                "   * @param {{{}{}}} [{}] {}",
+                "   * @param {{{}{}}} [{}]{}",
                param.param_type, optional, param.name, desc
            )
            .unwrap();
@@ -119,3 +124,11 @@ fn normalize_return_type(return_type: &str) -> String {
    }
    result
 }
+
+/// Format param description with dash prefix, or empty string if no description.
+fn format_param_desc(desc: Option<&str>) -> String {
+    match desc {
+        Some(d) if !d.is_empty() => format!(" - {}", d),
+        _ => String::new(),
+    }
+}
@@ -6,9 +6,8 @@ use std::fmt::Write;
 use brk_types::TreeNode;

 use crate::{
-    ClientMetadata, Endpoint, PatternField, child_type_name, get_fields_with_child_info,
-    get_first_leaf_name, get_node_fields, get_pattern_instance_base, infer_accumulated_name,
-    to_camel_case,
+    ClientMetadata, Endpoint, PatternField, child_type_name, get_first_leaf_name, get_node_fields,
+    get_pattern_instance_base, infer_accumulated_name, prepare_tree_node, to_camel_case,
 };

 use super::api::generate_api_methods;
@@ -38,36 +37,23 @@ fn generate_tree_typedef(
    metadata: &ClientMetadata,
    generated: &mut HashSet<String>,
 ) {
-    let TreeNode::Branch(children) = node else {
+    let Some(ctx) = prepare_tree_node(node, name, pattern_lookup, metadata, generated) else {
        return;
    };

-    let fields_with_child_info = get_fields_with_child_info(children, name, pattern_lookup);
-    let fields: Vec<PatternField> = fields_with_child_info
-        .iter()
-        .map(|(f, _)| f.clone())
-        .collect();
-
-    if pattern_lookup.contains_key(&fields)
-        && pattern_lookup.get(&fields) != Some(&name.to_string())
-    {
-        return;
-    }
-
-    if generated.contains(name) {
-        return;
-    }
-    generated.insert(name.to_string());
-
    writeln!(output, "/**").unwrap();
    writeln!(output, " * @typedef {{Object}} {}", name).unwrap();

-    for (field, child_fields) in &fields_with_child_info {
-        let generic_value_type = child_fields
-            .as_ref()
-            .and_then(|cf| metadata.get_type_param(cf))
-            .map(String::as_str);
-        let js_type = field_type_with_generic(field, metadata, false, generic_value_type);
+    for ((field, child_fields), (child_name, _)) in
+        ctx.fields_with_child_info.iter().zip(ctx.children.iter())
+    {
+        let js_type = metadata.resolve_tree_field_type(
+            child_fields.as_deref(),
+            name,
+            child_name,
+            |generic| field_type_with_generic(field, metadata, false, generic),
+        );
+
        writeln!(
            output,
            " * @property {{{}}} {}",
@@ -79,10 +65,11 @@ fn generate_tree_typedef(

    writeln!(output, " */\n").unwrap();

-    for (child_name, child_node) in children {
+    for (child_name, child_node) in ctx.children {
        if let TreeNode::Branch(grandchildren) = child_node {
            let child_fields = get_node_fields(grandchildren, pattern_lookup);
-            if !pattern_lookup.contains_key(&child_fields) {
+            // Generate typedef if no pattern match OR pattern is not parameterizable
+            if !metadata.is_parameterizable_fields(&child_fields) {
                let child_type = child_type_name(name, child_name);
                generate_tree_typedef(
                    output,
@@ -183,22 +170,13 @@ fn generate_tree_initializer(
                }
                TreeNode::Branch(grandchildren) => {
                    let child_fields = get_node_fields(grandchildren, pattern_lookup);
-                    if let Some(pattern_name) = pattern_lookup.get(&child_fields) {
-                        let pattern = metadata
-                            .structural_patterns
-                            .iter()
-                            .find(|p| &p.name == pattern_name);
-                        let is_parameterizable =
-                            pattern.map(|p| p.is_parameterizable()).unwrap_or(false);
-
-                        let arg = if is_parameterizable {
-                            get_pattern_instance_base(child_node)
-                        } else if accumulated_name.is_empty() {
-                            format!("/{}", child_name)
-                        } else {
-                            format!("{}/{}", accumulated_name, child_name)
-                        };
+                    // Only use pattern factory if pattern is parameterizable
+                    let pattern_name = pattern_lookup
+                        .get(&child_fields)
+                        .filter(|name| metadata.is_parameterizable(name));

+                    if let Some(pattern_name) = pattern_name {
+                        let arg = get_pattern_instance_base(child_node);
                        writeln!(
                            output,
                            "{}{}: create{}(this, '{}'){}",
@@ -21,10 +21,24 @@ pub fn generate_type_definitions(output: &mut String, schemas: &TypeSchemas) {

        let js_type = schema_to_js_type(schema, Some(name));

+        let type_desc = schema.get("description").and_then(|d| d.as_str());
+
        if is_primitive_alias(schema) {
-            writeln!(output, "/** @typedef {{{}}} {} */", js_type, name).unwrap();
+            if let Some(desc) = type_desc {
+                writeln!(output, "/**").unwrap();
+                write_jsdoc_description(output, desc);
+                writeln!(output, " *").unwrap();
+                writeln!(output, " * @typedef {{{}}} {}", js_type, name).unwrap();
+                writeln!(output, " */").unwrap();
+            } else {
+                writeln!(output, "/** @typedef {{{}}} {} */", js_type, name).unwrap();
+            }
        } else if let Some(props) = schema.get("properties").and_then(|p| p.as_object()) {
            writeln!(output, "/**").unwrap();
+            if let Some(desc) = type_desc {
+                write_jsdoc_description(output, desc);
+                writeln!(output, " *").unwrap();
+            }
            writeln!(output, " * @typedef {{Object}} {}", name).unwrap();
            for (prop_name, prop_schema) in props {
                let prop_type = schema_to_js_type(prop_schema, Some(name));
@@ -35,14 +49,25 @@ pub fn generate_type_definitions(output: &mut String, schemas: &TypeSchemas) {
                    .unwrap_or(false);
                let optional = if required { "" } else { "=" };
                let safe_name = to_camel_case(prop_name);
+                let prop_desc = prop_schema
+                    .get("description")
+                    .and_then(|d| d.as_str())
+                    .map(|d| format!(" - {}", d))
+                    .unwrap_or_default();
                writeln!(
                    output,
-                    " * @property {{{}{}}} {}",
-                    prop_type, optional, safe_name
+                    " * @property {{{}{}}} {}{}",
+                    prop_type, optional, safe_name, prop_desc
                )
                .unwrap();
            }
            writeln!(output, " */").unwrap();
+        } else if let Some(desc) = type_desc {
+            writeln!(output, "/**").unwrap();
+            write_jsdoc_description(output, desc);
+            writeln!(output, " *").unwrap();
+            writeln!(output, " * @typedef {{{}}} {}", js_type, name).unwrap();
+            writeln!(output, " */").unwrap();
        } else {
            writeln!(output, "/** @typedef {{{}}} {} */", js_type, name).unwrap();
        }
@@ -50,6 +75,17 @@ pub fn generate_type_definitions(output: &mut String, schemas: &TypeSchemas) {
    writeln!(output).unwrap();
 }

+/// Write a multi-line description with proper JSDoc formatting.
+fn write_jsdoc_description(output: &mut String, desc: &str) {
+    for line in desc.lines() {
+        if line.is_empty() {
+            writeln!(output, " *").unwrap();
+        } else {
+            writeln!(output, " * {}", line).unwrap();
+        }
+    }
+}
+
 fn is_primitive_alias(schema: &Value) -> bool {
    schema.get("properties").is_none()
        && schema.get("items").is_none()
@@ -27,7 +27,7 @@ pub fn generate_python_client(
    writeln!(output, "from __future__ import annotations").unwrap();
    writeln!(
        output,
-        "from typing import TypeVar, Generic, Any, Optional, List, Literal, TypedDict, Final, Union, Protocol"
+        "from typing import TypeVar, Generic, Any, Optional, List, Literal, TypedDict, Union, Protocol"
    )
    .unwrap();
    writeln!(output, "import httpx\n").unwrap();
@@ -6,8 +6,8 @@ use std::fmt::Write;
 use brk_types::TreeNode;

 use crate::{
-    ClientMetadata, PatternField, child_type_name, get_fields_with_child_info, get_node_fields,
-    get_pattern_instance_base, to_snake_case,
+    ClientMetadata, PatternField, child_type_name, get_node_fields, get_pattern_instance_base,
+    prepare_tree_node, to_snake_case,
 };

 use super::client::field_type_with_generic;
@@ -37,28 +37,10 @@ fn generate_tree_class(
    metadata: &ClientMetadata,
    generated: &mut HashSet<String>,
 ) {
-    let TreeNode::Branch(children) = node else {
+    let Some(ctx) = prepare_tree_node(node, name, pattern_lookup, metadata, generated) else {
        return;
    };

-    let fields_with_child_info = get_fields_with_child_info(children, name, pattern_lookup);
-    let fields: Vec<PatternField> = fields_with_child_info
-        .iter()
-        .map(|(f, _)| f.clone())
-        .collect();
-
-    // Skip if this matches a pattern (already generated)
-    if pattern_lookup.contains_key(&fields)
-        && pattern_lookup.get(&fields) != Some(&name.to_string())
-    {
-        return;
-    }
-
-    if generated.contains(name) {
-        return;
-    }
-    generated.insert(name.to_string());
-
    writeln!(output, "class {}:", name).unwrap();
    writeln!(output, "    \"\"\"Catalog tree node.\"\"\"").unwrap();
    writeln!(output, "    ").unwrap();
@@ -69,7 +51,7 @@ fn generate_tree_class(
    .unwrap();

    for ((field, child_fields_opt), (_child_name, child_node)) in
-        fields_with_child_info.iter().zip(children.iter())
+        ctx.fields_with_child_info.iter().zip(ctx.children.iter())
    {
        // Look up type parameter for generic patterns
        let generic_value_type = child_fields_opt
@@ -79,44 +61,35 @@ fn generate_tree_class(
        let py_type = field_type_with_generic(field, metadata, false, generic_value_type);
        let field_name_py = to_snake_case(&field.name);

-        if metadata.is_pattern_type(&field.rust_type) {
-            let pattern = metadata.find_pattern(&field.rust_type);
-            let is_parameterizable = pattern.is_some_and(|p| p.is_parameterizable());
-
-            if is_parameterizable {
-                let metric_base = get_pattern_instance_base(child_node);
-                writeln!(
-                    output,
-                    "        self.{}: {} = {}(client, '{}')",
-                    field_name_py, py_type, field.rust_type, metric_base
-                )
-                .unwrap();
-            } else {
-                writeln!(
-                    output,
-                    "        self.{}: {} = {}(client, f'{{base_path}}_{}')",
-                    field_name_py, py_type, field.rust_type, field.name
-                )
-                .unwrap();
-            }
-        } else if metadata.field_uses_accessor(field) {
+        if metadata.is_pattern_type(&field.rust_type) && metadata.is_parameterizable(&field.rust_type)
+        {
+            // Parameterizable pattern: use pattern class with metric base
+            let metric_base = get_pattern_instance_base(child_node);
+            writeln!(
+                output,
+                "        self.{}: {} = {}(client, '{}')",
+                field_name_py, py_type, field.rust_type, metric_base
+            )
+            .unwrap();
+        } else if let TreeNode::Leaf(leaf) = child_node {
+            // Leaf node: use actual metric name
            let accessor = metadata.find_index_set_pattern(&field.indexes).unwrap();
            writeln!(
                output,
-                "        self.{}: {} = {}(client, f'{{base_path}}_{}')",
-                field_name_py, py_type, accessor.name, field.name
+                "        self.{}: {} = {}(client, '{}')",
+                field_name_py, py_type, accessor.name, leaf.name()
            )
            .unwrap();
        } else if field.is_branch() {
-            // Non-pattern branch - instantiate the nested class
+            // Non-parameterizable pattern or regular branch: generate inline class
+            let inline_class = child_type_name(name, &field.name);
            writeln!(
                output,
-                "        self.{}: {} = {}(client, f'{{base_path}}_{}')",
-                field_name_py, py_type, field.rust_type, field.name
+                "        self.{}: {} = {}(client)",
+                field_name_py, inline_class, inline_class
            )
            .unwrap();
        } else {
-            // All metrics must be indexed - this should not be reached
            panic!(
                "Field '{}' has no matching index pattern. All metrics must be indexed.",
                field.name
@@ -127,10 +100,12 @@ fn generate_tree_class(
    writeln!(output).unwrap();

    // Generate child classes
-    for (child_name, child_node) in children {
+    for (child_name, child_node) in ctx.children {
        if let TreeNode::Branch(grandchildren) = child_node {
            let child_fields = get_node_fields(grandchildren, pattern_lookup);
-            if !pattern_lookup.contains_key(&child_fields) {
+
+            // Generate inline class if no pattern match OR pattern is not parameterizable
+            if !metadata.is_parameterizable_fields(&child_fields) {
                let child_class = child_type_name(name, child_name);
                generate_tree_class(
                    output,
@@ -25,8 +25,44 @@ pub fn generate_type_definitions(output: &mut String, schemas: &TypeSchemas) {
        let Some(schema) = schemas.get(&name) else {
            continue;
        };
+        let type_desc = schema.get("description").and_then(|d| d.as_str());
+
        if let Some(props) = schema.get("properties").and_then(|p| p.as_object()) {
            writeln!(output, "class {}(TypedDict):", name).unwrap();
+
+            // Collect field descriptions for Attributes section
+            let field_docs: Vec<(String, Option<&str>)> = props
+                .iter()
+                .map(|(prop_name, prop_schema)| {
+                    let safe_name = escape_python_keyword(prop_name);
+                    let desc = prop_schema.get("description").and_then(|d| d.as_str());
+                    (safe_name, desc)
+                })
+                .collect();
+            let has_field_docs = field_docs.iter().any(|(_, d)| d.is_some());
+
+            // Generate docstring if we have type description or field descriptions
+            if type_desc.is_some() || has_field_docs {
+                writeln!(output, "    \"\"\"").unwrap();
+                if let Some(desc) = type_desc {
+                    for line in desc.lines() {
+                        writeln!(output, "    {}", line).unwrap();
+                    }
+                }
+                if has_field_docs {
+                    if type_desc.is_some() {
+                        writeln!(output).unwrap();
+                    }
+                    writeln!(output, "    Attributes:").unwrap();
+                    for (field_name, desc) in &field_docs {
+                        if let Some(d) = desc {
+                            writeln!(output, "        {}: {}", field_name, d).unwrap();
+                        }
+                    }
+                }
+                writeln!(output, "    \"\"\"").unwrap();
+            }
+
            for (prop_name, prop_schema) in props {
                let prop_type = schema_to_python_type_ctx(prop_schema, Some(&name));
                let safe_name = escape_python_keyword(prop_name);
@@ -35,6 +71,11 @@ pub fn generate_type_definitions(output: &mut String, schemas: &TypeSchemas) {
            writeln!(output).unwrap();
        } else {
            let py_type = schema_to_python_type_ctx(schema, Some(&name));
+            if let Some(desc) = type_desc {
+                for line in desc.lines() {
+                    writeln!(output, "# {}", line).unwrap();
+                }
+            }
            writeln!(output, "{} = {}", name, py_type).unwrap();
        }
    }
@@ -6,8 +6,9 @@ use std::fmt::Write;
 use brk_types::TreeNode;

 use crate::{
-    ClientMetadata, PatternField, RustSyntax, child_type_name, generate_tree_node_field,
-    get_fields_with_child_info, get_node_fields, get_pattern_instance_base, to_snake_case,
+    ClientMetadata, LanguageSyntax, PatternField, RustSyntax, child_type_name,
+    generate_tree_node_field, get_node_fields, get_pattern_instance_base, prepare_tree_node,
+    to_snake_case,
 };

 use super::client::field_type_with_generic;
@@ -36,38 +37,23 @@ fn generate_tree_node(
    metadata: &ClientMetadata,
    generated: &mut HashSet<String>,
 ) {
-    let TreeNode::Branch(children) = node else {
+    let Some(ctx) = prepare_tree_node(node, name, pattern_lookup, metadata, generated) else {
        return;
    };

-    let fields_with_child_info = get_fields_with_child_info(children, name, pattern_lookup);
-    let fields: Vec<PatternField> = fields_with_child_info
-        .iter()
-        .map(|(f, _)| f.clone())
-        .collect();
-
-    if let Some(pattern_name) = pattern_lookup.get(&fields)
-        && pattern_name != name
-    {
-        return;
-    }
-
-    if generated.contains(name) {
-        return;
-    }
-    generated.insert(name.to_string());
-
    writeln!(output, "/// Catalog tree node.").unwrap();
    writeln!(output, "pub struct {} {{", name).unwrap();

-    for (field, child_fields) in &fields_with_child_info {
+    for ((field, child_fields), (child_name, _)) in
+        ctx.fields_with_child_info.iter().zip(ctx.children.iter())
+    {
        let field_name = to_snake_case(&field.name);
-        // Look up type parameter for generic patterns
-        let generic_value_type = child_fields
-            .as_ref()
-            .and_then(|cf| metadata.get_type_param(cf))
-            .map(String::as_str);
-        let type_annotation = field_type_with_generic(field, metadata, false, generic_value_type);
+        let type_annotation = metadata.resolve_tree_field_type(
+            child_fields.as_deref(),
+            name,
+            child_name,
+            |generic| field_type_with_generic(field, metadata, false, generic),
+        );
        writeln!(output, "    pub {}: {},", field_name, type_annotation).unwrap();
    }

@@ -82,29 +68,61 @@ fn generate_tree_node(
    writeln!(output, "        Self {{").unwrap();

    let syntax = RustSyntax;
-    for (field, (child_name, child_node)) in fields.iter().zip(children.iter()) {
-        // Detect pattern base for parameterizable patterns
-        let pattern_base = if metadata.is_pattern_type(&field.rust_type) {
-            let pattern = metadata.find_pattern(&field.rust_type);
-            if pattern.is_some_and(|p| p.is_parameterizable()) {
-                Some(get_pattern_instance_base(child_node))
-            } else {
-                None
-            }
+    for ((field_info, child_fields), (child_name, child_node)) in
+        ctx.fields_with_child_info.iter().zip(ctx.children.iter())
+    {
+        let field_name = to_snake_case(&field_info.name);
+
+        // Check if this is a pattern type and if it's parameterizable
+        let is_parameterizable = child_fields
+            .as_ref()
+            .is_some_and(|cf| metadata.is_parameterizable_fields(cf));
+
+        if metadata.is_pattern_type(&field_info.rust_type) && is_parameterizable {
+            // Parameterizable pattern: use pattern constructor with metric base
+            let pattern_base = get_pattern_instance_base(child_node);
+            generate_tree_node_field(
+                output,
+                &syntax,
+                field_info,
+                metadata,
+                "            ",
+                child_name,
+                Some(&pattern_base),
+            );
+        } else if child_fields.is_some() {
+            // Non-parameterizable pattern or regular branch: use inline struct
+            let child_struct = child_type_name(name, child_name);
+            let path_expr = syntax.path_expr("base_path", &format!("_{}", child_name));
+            writeln!(
+                output,
+                "            {}: {}::new(client.clone(), {}),",
+                field_name, child_struct, path_expr
+            )
+            .unwrap();
        } else {
-            None
-        };
-        generate_tree_node_field(output, &syntax, field, metadata, "            ", child_name, pattern_base.as_deref());
+            // Leaf field
+            generate_tree_node_field(
+                output,
+                &syntax,
+                field_info,
+                metadata,
+                "            ",
+                child_name,
+                None,
+            );
+        }
    }

    writeln!(output, "        }}").unwrap();
    writeln!(output, "    }}").unwrap();
    writeln!(output, "}}\n").unwrap();

-    for (child_name, child_node) in children {
+    for (child_name, child_node) in ctx.children {
        if let TreeNode::Branch(grandchildren) = child_node {
            let child_fields = get_node_fields(grandchildren, pattern_lookup);
-            if !pattern_lookup.contains_key(&child_fields) {
+            // Generate child struct if no pattern match OR pattern is not parameterizable
+            if !metadata.is_parameterizable_fields(&child_fields) {
                let child_struct = child_type_name(name, child_name);
                generate_tree_node(
                    output,