fix: validate applied struct type arg arity

Author: tiye

calcit/test-generics.cirru

@@ -21,7 +21,7 @@
         |Wrapped $ %{} :CodeEntry (:doc |) (:schema nil)
           :code $ quote
             defenum Wrapped
-              :pair $ :: Pair :number :string
+              :pair Pair
               :none
           :examples $ []
         |main! $ %{} :CodeEntry (:doc |) (:schema nil)

docs/CalcitAgent.md

@@ -662,7 +662,7 @@ let
 有两种方式标注函数返回类型：
 
 - **紧凑模式（推荐）**：紧跟在参数列表后的类型标签。
-- **正式模式**：使用 `hint-fn`（通常放在函数体开头）。
+- **正式模式**：局部 `fn` 使用 `hint-fn`（通常放在函数体开头）；顶层 `defn` / `defmacro` 使用 `:schema`。
   - 泛型变量：`hint-fn $ {} (:generics $ [] 'T 'S)`
   - 旧 clause 写法（如 `(hint-fn (return-type ...))` / `(generics ...)` / `(type-vars ...)`）已不再支持，会直接报错。
 
@@ -727,18 +727,18 @@ cr eval 'foldl (list 1 2 3) 0 &+'
 let
     ; 可选参数
     greet $ fn (name)
-      assert-type name $ :: :optional :string
+      hint-fn $ {} (:args $ [] (:: :optional :string)) (:return :string)
       str "|Hello " (or name "|Guest")
 
     ; 变长参数
     sum $ fn (& xs)
-      assert-type xs $ :: :& :number
+      hint-fn $ {} (:rest :number) (:return :number)
       reduce xs 0 &+
 
     ; Record 约束 (使用 defstruct 定义结构体)
     User $ defstruct User (:name :string)
     get-name $ fn (u)
-      assert-type u User
+      hint-fn $ {} (:args $ [] (:: :record User)) (:return :string)
       get u :name
   println $ greet |Alice
   println $ sum 1 2 3
@@ -794,6 +794,8 @@ let
 - `:return :string` 对应整个 `join-str` 的返回值
 - 内部辅助函数 `%join-str` 不是顶层定义，所以继续用 `hint-fn`
 
+可以简单记忆为：**namespace 上的定义看 `:schema`，函数体内部的辅助函数看 `hint-fn`。**
+
 推荐工作流：
 
 ```bash
@@ -1456,20 +1458,20 @@ cr eval 'let ((x 1)) (+ x 2)'
 
 ### 错误信息对照表
 
-| 错误信息                                         | 原因                                              | 解决方法                                                       |
-| ------------------------------------------------ | ------------------------------------------------- | -------------------------------------------------------------- |
-| `Path index X out of bounds`                     | 路径索引已过期（操作后变化）                      | 重新运行 `cr query search` 获取最新路径                        |
-| `tag-match expected tuple`                       | 传入 vector 而非 tuple                            | 改用 `::` 语法，如 `:: :event-name data`                       |
-| `unknown symbol: xxx`                            | 符号未定义或未 import                             | `cr query find xxx` 确认位置，`cr edit add-import` 引入        |
-| `expects pairs in list for let`                  | `let` 绑定语法错误                                | 改为 `let ((x val)) body`（双层括号）                          |
-| `cannot be used as operator`                     | 末尾符号被当作函数调用                            | 改用 `, acc` 前缀传递值，或用函数包裹                          |
-| `unknown data for foldl-shortcut`                | 参数顺序错误（Calcit vs Clojure 差异）            | Calcit 集合在第一位：`map data fn`                             |
-| `Do not include ':require' as prefix`            | `cr edit imports` 格式错误                        | 去掉 `:require` 前缀，直接传 `src-ns :refer $ sym`             |
-| `Namespace name mismatch`                        | `add-ns -e` 名称不一致                            | ns 表达式名称必须与位置参数完全一致                            |
-| 字符串被拆分成多个 token                         | 没有用 `\|` 或 `"` 包裹                           | 使用 `\|complete string` 或 `"complete string`                 |
-| `unexpected format`                              | Cirru 语法错误                                    | 用 `cr cirru parse '<code>'` 验证语法                          |
-| `Type warning` 导致 eval 失败                    | 类型不匹配（阻断执行）                            | 检查参数类型标注，或用 `assert-type` 确认预期类型              |
-| `schema mismatch while preprocessing definition` | `:schema` 与 `defn` / `defmacro` / 参数个数不一致 | 修正 `:kind`、`:args`、`:rest`，或让代码定义与 schema 保持一致 |
+| 错误信息                                         | 原因                                              | 解决方法                                                                 |
+| ------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------ |
+| `Path index X out of bounds`                     | 路径索引已过期（操作后变化）                      | 重新运行 `cr query search` 获取最新路径                                  |
+| `tag-match expected tuple`                       | 传入 vector 而非 tuple                            | 改用 `::` 语法，如 `:: :event-name data`                                 |
+| `unknown symbol: xxx`                            | 符号未定义或未 import                             | `cr query find xxx` 确认位置，`cr edit add-import` 引入                  |
+| `expects pairs in list for let`                  | `let` 绑定语法错误                                | 改为 `let ((x val)) body`（双层括号）                                    |
+| `cannot be used as operator`                     | 末尾符号被当作函数调用                            | 改用 `, acc` 前缀传递值，或用函数包裹                                    |
+| `unknown data for foldl-shortcut`                | 参数顺序错误（Calcit vs Clojure 差异）            | Calcit 集合在第一位：`map data fn`                                       |
+| `Do not include ':require' as prefix`            | `cr edit imports` 格式错误                        | 去掉 `:require` 前缀，直接传 `src-ns :refer $ sym`                       |
+| `Namespace name mismatch`                        | `add-ns -e` 名称不一致                            | ns 表达式名称必须与位置参数完全一致                                      |
+| 字符串被拆分成多个 token                         | 没有用 `\|` 或 `"` 包裹                           | 使用 `\|complete string` 或 `"complete string`                           |
+| `unexpected format`                              | Cirru 语法错误                                    | 用 `cr cirru parse '<code>'` 验证语法                                    |
+| `Type warning` 导致 eval 失败                    | 类型不匹配（阻断执行）                            | 优先检查 `:schema` / `hint-fn` 的参数标注；局部值再用 `assert-type` 复核 |
+| `schema mismatch while preprocessing definition` | `:schema` 与 `defn` / `defmacro` / 参数个数不一致 | 修正 `:kind`、`:args`、`:rest`，或让代码定义与 schema 保持一致           |
 
 ### 调试常用命令
 

editing-history/2026-0313-2216-validate-struct-type-arg-arity.md

@@ -87,6 +87,7 @@ fn type_fail_schema_mismatch_fixtures_report_error_code() {
   }
 }
 
+
 #[test]
 fn type_fail_call_arg_fixture_reports_warning_code() {
   let _guard = lock_fixture_tests();

src/bin/cr_tests/type_fail.rs

@@ -190,6 +190,14 @@ pub fn new_struct(xs: &[Calcit]) -> Result<Calcit, CalcitErr> {
             }
           };
           let field_type = CalcitTypeAnnotation::parse_type_annotation_form_with_generics(type_expr, generics.as_slice());
+          if let Err(e) = field_type.validate_applied_type_args() {
+            let hint = format_proc_examples_hint(&CalcitProc::NativeStructNew).unwrap_or_default();
+            return CalcitErr::err_str_with_hint(
+              CalcitErrKind::Type,
+              format!("&struct::new field `{field_name}` has invalid type annotation: {e}"),
+              hint,
+            );
+          }
           fields.push((field_name, field_type));
         }
         (Some(_), None, _) => {

src/builtins/records.rs

@@ -137,7 +137,11 @@ impl CalcitEnum {
       Calcit::List(items) => {
         let mut payloads: Vec<Arc<CalcitTypeAnnotation>> = Vec::with_capacity(items.len());
         for item in items.iter() {
-          payloads.push(CalcitTypeAnnotation::parse_type_annotation_form(item));
+          let parsed = CalcitTypeAnnotation::parse_type_annotation_form(item);
+          parsed
+            .validate_applied_type_args()
+            .map_err(|e| format!("enum variant `{tag}` has invalid payload type annotation: {e}"))?;
+          payloads.push(parsed);
         }
         Ok(payloads)
       }
@@ -152,7 +156,7 @@ impl CalcitEnum {
 #[cfg(test)]
 mod tests {
   use super::*;
-  use crate::calcit::{CalcitList, CalcitStruct, CalcitTypeAnnotation};
+  use crate::calcit::{CalcitList, CalcitStruct, CalcitTuple, CalcitTypeAnnotation};
 
   fn empty_list() -> Calcit {
     Calcit::List(Arc::new(CalcitList::Vector(vec![])))
@@ -186,4 +190,25 @@ mod tests {
     }
     assert_eq!(enum_proto.find_variant_by_name("ok").unwrap().arity(), 0);
   }
+
+  #[test]
+  fn rejects_non_generic_struct_type_args_in_payloads() {
+    let pair = CalcitStruct::from_fields(EdnTag::new("Pair"), vec![EdnTag::new("left"), EdnTag::new("right")]);
+    let applied_pair = Calcit::Tuple(CalcitTuple {
+      tag: Arc::new(Calcit::Struct(pair)),
+      extra: vec![Calcit::tag("number"), Calcit::tag("string")],
+      sum_type: None,
+    });
+    let record = CalcitRecord {
+      struct_ref: Arc::new(CalcitStruct::from_fields(EdnTag::new("Wrapped"), vec![EdnTag::new("pair")])),
+      values: Arc::new(vec![list_from(vec![applied_pair])]),
+    };
+
+    let err = CalcitEnum::from_record(record).expect_err("non-generic struct should reject type args in enum payloads");
+    assert!(
+      err.contains("enum variant `pair` has invalid payload type annotation")
+        && err.contains("struct `Pair` is not generic but received 2 type argument(s)"),
+      "unexpected error: {err}"
+    );
+  }
 }

src/calcit/sum_type.rs

@@ -143,6 +143,76 @@ pub enum CalcitTypeAnnotation {
 }
 
 impl CalcitTypeAnnotation {
+  pub(crate) fn validate_applied_type_args(&self) -> Result<(), String> {
+    match self {
+      Self::List(inner) | Self::Set(inner) | Self::Ref(inner) | Self::Variadic(inner) | Self::Optional(inner) => {
+        inner.validate_applied_type_args()
+      }
+      Self::Map(key, value) => {
+        key.validate_applied_type_args()?;
+        value.validate_applied_type_args()
+      }
+      Self::Fn(signature) => signature.validate_applied_type_args(),
+      Self::Struct(base, args) => {
+        for arg in args.iter() {
+          arg.validate_applied_type_args()?;
+        }
+
+        let expected = base.generics.len();
+        let actual = args.len();
+        if expected == 0 {
+          if actual > 0 {
+            return Err(format!(
+              "struct `{}` is not generic but received {actual} type argument(s)",
+              base.name
+            ));
+          }
+        } else if actual != expected {
+          return Err(format!(
+            "struct `{}` expects {expected} type argument(s), but received {actual}",
+            base.name
+          ));
+        }
+
+        Ok(())
+      }
+      Self::Enum(enum_def, args) => {
+        for arg in args.iter() {
+          arg.validate_applied_type_args()?;
+        }
+
+        if !args.is_empty() {
+          return Err(format!(
+            "enum `{}` is not generic but received {} type argument(s)",
+            enum_def.name(),
+            args.len()
+          ));
+        }
+
+        Ok(())
+      }
+      Self::TypeRef(_, args) => {
+        for arg in args.iter() {
+          arg.validate_applied_type_args()?;
+        }
+        Ok(())
+      }
+      Self::Record(_) | Self::Tuple(_) | Self::Trait(_) | Self::TraitSet(_) | Self::Custom(_) => Ok(()),
+      Self::Bool
+      | Self::Number
+      | Self::String
+      | Self::Symbol
+      | Self::Tag
+      | Self::DynTuple
+      | Self::DynFn
+      | Self::Buffer
+      | Self::CirruQuote
+      | Self::Dynamic
+      | Self::TypeVar(_)
+      | Self::Unit => Ok(()),
+    }
+  }
+
   fn custom_keyword_matches(custom: &Calcit, keyword: &str) -> bool {
     match custom {
       Calcit::Tag(tag) => tag.ref_str().trim_start_matches(':') == keyword,
@@ -2545,6 +2615,46 @@ mod tests {
       CalcitTypeAnnotation::Dynamic
     ));
   }
+
+  #[test]
+  fn rejects_type_args_on_non_generic_struct_annotation() {
+    let pair = CalcitStruct {
+      name: EdnTag::new("Pair"),
+      fields: Arc::new(vec![]),
+      field_types: Arc::new(vec![]),
+      generics: Arc::new(vec![]),
+      impls: vec![],
+    };
+    let annotation = CalcitTypeAnnotation::Struct(
+      Arc::new(pair),
+      Arc::new(vec![Arc::new(CalcitTypeAnnotation::Number), Arc::new(CalcitTypeAnnotation::String)]),
+    );
+
+    let err = annotation
+      .validate_applied_type_args()
+      .expect_err("non-generic struct should reject type args");
+    assert!(err.contains("struct `Pair` is not generic"), "unexpected error: {err}");
+  }
+
+  #[test]
+  fn rejects_wrong_arity_on_generic_struct_annotation() {
+    let pair = CalcitStruct {
+      name: EdnTag::new("Pair"),
+      fields: Arc::new(vec![]),
+      field_types: Arc::new(vec![]),
+      generics: Arc::new(vec![Arc::from("A"), Arc::from("B")]),
+      impls: vec![],
+    };
+    let annotation = CalcitTypeAnnotation::Struct(Arc::new(pair), Arc::new(vec![Arc::new(CalcitTypeAnnotation::Number)]));
+
+    let err = annotation
+      .validate_applied_type_args()
+      .expect_err("generic struct should enforce arity");
+    assert!(
+      err.contains("expects 2 type argument(s), but received 1"),
+      "unexpected error: {err}"
+    );
+  }
 }
 
 impl fmt::Display for CalcitTypeAnnotation {
@@ -2715,6 +2825,17 @@ pub struct CalcitFnTypeAnnotation {
 }
 
 impl CalcitFnTypeAnnotation {
+  pub(crate) fn validate_applied_type_args(&self) -> Result<(), String> {
+    for arg in &self.arg_types {
+      arg.validate_applied_type_args()?;
+    }
+    self.return_type.validate_applied_type_args()?;
+    if let Some(rest) = &self.rest_type {
+      rest.validate_applied_type_args()?;
+    }
+    Ok(())
+  }
+
   fn to_inline_type_schema_edn(&self) -> Edn {
     let args: Vec<Edn> = self.arg_types.iter().map(|t| t.to_type_edn()).collect();
     let mut map = EdnMapView::default();