@calcit/procs 0.12.14 → 0.12.17

package/editing-history/202504121453-map-to-record-rewrite.md

@@ -0,0 +1,33 @@
+# 202504121453 - Automatic map-to-record rewrite in preprocessing
+
+## Summary
+
+When a function parameter is typed as a struct type in its schema, but the caller passes a hashmap literal `{}`, the preprocessor now automatically rewrites the hashmap to a record construction `%{}` so that runtime gets a proper record with full type checking.
+
+## Key implementation details
+
+### type_annotation.rs
+- Added `CalcitTypeAnnotation::resolve_to_struct()` — resolves `Struct`, `Record`, `TypeRef("ns/def")`, and `Optional(inner)` variants to concrete `CalcitStruct` definitions
+- Added `resolve_struct_from_program(ns, def)` helper — looks up struct definitions from the program registry via `lookup_runtime_ready_registered` with fallback to `lookup_def_code_registered`
+
+### preprocess.rs
+- Added `try_rewrite_map_args_to_records()` — iterates processed args, checks each against `fn_info.arg_types[idx]`, calls `try_rewrite_single_map_to_record()` for potential rewrites
+- Added `try_rewrite_single_map_to_record()` — validates arg is `List` with `Proc(NativeMap)` head, resolves expected type to struct, validates all keys are tags, builds `[Proc(NativeRecord), Struct(def), k1, v1, ...]`
+- Integration point: `preprocess_list_call()` → `Calcit::Fn` match arm, between arg preprocessing and type checking
+
+### AST transformation
+- Input (hashmap literal): `[Proc(NativeMap), Tag(:x), 10, Tag(:y), 20]`
+- Output (record literal): `[Proc(NativeRecord), Struct(Point2D), Tag(:x), 10, Tag(:y), 20]`
+
+### Rewrite conditions
+- Function has schema with `:args` referencing a struct type (TypeRef, Struct, or Record)
+- Argument is a hashmap literal (`{}`) with tag keys
+- Struct definition is resolvable at preprocess time
+- If any condition fails, argument is left unchanged (safe fallback)
+
+## Test
+- Added `Point2D`, `sum-point`, `check-point-type`, `test-map-to-record` to `calcit/test-record.cirru`
+- `check-point-type` uses `record?` to verify the rewrite produces actual records, not just maps
+
+## Gotcha
+- `cr tree insert-after` can create doubly-nested nodes — always verify with `tree show` after insertion

package/editing-history/2026-0326-2013-docs-frontmatter-and-module-search.md

@@ -55,4 +55,4 @@
 ## 后续经验
 
 - docs 元数据一旦进入 CLI 行为，就应该配套规范页与验证页，否则后续加字段很容易出现“文档能写、检索却不稳定”的分叉。
-- 模块文档检索要尽量和 core docs 走同一套 resolver，这样使用者不需要记两套命令心智模型。
+- 模块文档检索要尽量和 core docs 走同一套 resolver，这样使用者不需要记两套命令心智模型。

package/editing-history/2026-0410-0011-snapshot-empty-version-pipe-marker.md

@@ -0,0 +1,23 @@
+# 2026-0410-0011 — 修复 snapshot `configs.version` 对 `||` 空字符串的漏判
+
+## 背景
+
+PR `snapshot-format` 新增了空 `configs.version` 的回归测试，但 GitHub Actions 上加载 `compact.cirru` 时，`(:version ||)` 会解析成字符串 `"|"`，没有命中原先仅检查空白字符串的校验。
+
+## 知识点
+
+- Cirru 的空字符串字面量 `||` 在这条解析路径里会落成 `"|"`，不能只靠 `trim().is_empty()` 判断是否为空。
+- `configs.version` 的校验要同时覆盖真正空串和这个 pipe marker，才能在加载阶段稳定报出 `configs.version cannot be empty`。
+
+## 修改
+
+- `src/snapshot.rs`
+  - 将 `parse_snapshot_config_string_field` 中 `version` 的空值判断扩展为：`text.trim().is_empty() || text == "|"`。
+
+## 验证
+
+```bash
+cargo fmt -- src/snapshot.rs
+```
+
+本地 `cargo test` 在当前机器仍受 macOS 链接器环境影响（`ld: library 'System' not found`），实际正确性改由 GitHub Actions 复核。

package/editing-history/202604121524-js-codegen-map-to-record.md

@@ -0,0 +1,26 @@
+# JS Codegen Fix for Map-to-Record Rewrite
+
+## Problem
+The map-to-record rewrite (from previous commit) inserted `Calcit::Struct` directly into the AST. The interpreter handles this, but JS codegen (`emit_js.rs` line 319) has no arm for `Calcit::Struct` → panics with `unreachable!`.
+
+## Key Insight
+The `%{}` macro normally expands to `&%{}` with a **symbol/import reference** as the first arg (not a literal `Calcit::Struct`). JS codegen relies on this — it emits the symbol as a variable reference (e.g., `Element`), and the JS runtime `_$n__PCT__$M_` function accepts the struct object at runtime.
+
+## Solution
+1. Added `resolve_to_struct_with_ref()` to `CalcitTypeAnnotation` — returns `Option<(CalcitStruct, Option<(Arc<str>, Arc<str>)>)>` with ns/def path from TypeRef annotations.
+2. Modified `try_rewrite_single_map_to_record()` to emit `Calcit::Import(CalcitImport { ... })` instead of `Calcit::Struct`:
+   - `ImportInfo::SameFile` when struct is in same namespace (avoids self-import duplicate declaration)
+   - `ImportInfo::NsReferDef` when struct is in a different namespace (generates proper cross-ns import)
+   - Falls back to `Calcit::Struct` only when no ns/def path is available
+
+## Pitfall: Self-Import Duplicate Declaration
+First attempt used `NsReferDef` for all imports — caused `SyntaxError: Identifier 'Point2D' has already been declared` because a self-import was generated when struct is in same namespace. Fix: detect `ns == file_ns` and use `SameFile`.
+
+## Verification in Respo
+- Typed `element->string` as `'respo.schema/Element`, `make-string` as `'respo.schema/Component`
+- Test passes `{}` map to `element->string` → auto-rewritten to `%{} Element ...` record construction
+- Generated JS: `import { Element } from "./respo.schema.mjs"` + `$clt._$n__PCT__$M_(Element, ...)`
+
+## Files Changed
+- `src/calcit/type_annotation.rs`: Added `resolve_to_struct_with_ref()`
+- `src/runner/preprocess.rs`: Emit Import reference in `try_rewrite_single_map_to_record()`

package/editing-history/202604121549-map-to-record-field-validation.md

@@ -0,0 +1,29 @@
+# Map-to-Record Field Validation and Nil Fill
+
+## Problem
+Map-to-record rewrite was passing through ALL map keys without validation, and emitting only
+the keys present in the map. This caused:
+1. Maps with keys not in the struct (e.g., `:x`) being incorrectly rewritten to records
+2. "fields size does not match" runtime error when the map has fewer keys than struct fields
+
+## Fix (preprocess.rs)
+1. **Field validation**: Check each map key against `struct_def.fields`. If any key is not a
+   valid struct field, skip the rewrite entirely (stay as map).
+2. **Nil fill**: Emit ALL struct fields in definition order. For fields not present in the map,
+   emit `Calcit::Nil`. This ensures the record always has the correct field count.
+3. **HashMap tracking**: Build a `HashMap<EdnTag, &Calcit>` of provided fields for O(1) lookup
+   during emission.
+
+## Key Types
+- `struct_def.fields` is `Vec<EdnTag>` — compare with `EdnTag` directly, not `Arc<str>`
+- `provided_fields` is `HashMap<EdnTag, &Calcit>` — avoids the `Arc<str>: Borrow<EdnTag>` issue
+
+## Respo DomProps Design
+- 29 fields with `(:: :optional <type>)` annotations
+- Strings: class-name, id, type, href, src, placeholder, name, title, data-name, data-comp, target
+- Dynamic: style (map), value, inner-text
+- Bools: disabled, checked, spell-check, read-only, selected
+- Number: tab-index
+- Fns: on-click, on-input, on-focus, on-blur, on-keydown, on-keyup, on-change
+- Maps: on, event
+- `create-element`/`create-list-element` convert record props to map via `&record:to-map`

package/editing-history/202604131600-tuple-to-enum-rewrite.md

@@ -0,0 +1,13 @@
+## 概要
+
+为 tuple-to-enum 自动改写实现预处理阶段支持。当函数参数 schema 标注为 enum 类型时,
+调用者传递的 untyped tuple `:: :tag payload` 自动改写为 `%:: Enum :tag payload`。
+
+## 知识点
+
+- `CalcitTypeAnnotation::resolve_to_enum_with_ref()` 对应 struct 端已有的 `resolve_to_struct_with_ref()`
+- `resolve_enum_from_program()` 通过 `lookup_runtime_ready_registered` + `lookup_def_code_registered` 两级缓存查找
+- tuple 改写只替换 head proc (`NativeTuple` → `NativeEnumTupleNew`) 并插入 enum 引用，不对 tag/payload 做验证（由 `check_enum_tuple_construction` 兜底）
+- JS codegen 需要 `Calcit::Import` 而非 `Calcit::Enum` 内联值，通过 TypeRef 路径判断走 SameFile 还是 NsReferDef
+- map-to-record 改写验证 key 合法性，tuple-to-enum 改写不验证（差异源于 struct field 是封闭集合，enum tag 验证已有独立检查）
+- Cirru tag-match 零载荷变体的 pattern 是 `(:ok)` 而非 `:ok`（后者在 pair 中被当作 body）

package/editing-history/202604132309-typeslot-enum-compile-safety.md

@@ -0,0 +1,40 @@
+# TypeSlot + Enum 编译期安全增强
+
+## 概要
+
+让 `deftype-slot` / `bind-type` 机制真正实现编译期 enum variant 校验。此前 TypeSlot 绑定的 enum 在自动推导 (`:: → %::`) 路径上缺乏变体验证，导致拼写错误或不存在的 variant 无法在 `cr js` / `--check-only` 时报出。
+
+## 修改的文件
+
+### `src/calcit/type_annotation.rs`
+- `resolve_to_enum_with_ref()`: 新增 `TypeSlot` 分支，通过 `resolve_type_slot()` 解析绑定类型后委托
+- `matches_with_bindings()`: 双向 `Tuple/Enum` 匹配 — 原先只有 `(Tuple, Enum)` 方向，TypeSlot 解析后顺序会翻转，新增 `(Enum, Tuple)` 方向
+
+### `src/calcit.rs`
+- 将 `resolve_type_slot` 加入 `pub use` 导出列表
+
+### `src/runner/preprocess.rs`
+- `resolve_enum_value()`: 在 `as_struct()` 调用前增加 TypeSlot 解析（避免 `&CalcitStruct` 生命周期问题）
+- 新增 `try_rewrite_local_fn_tuple_args_to_enum_tuples()`: 对本地函数调用（如回调 `d!`）也执行 tuple→enum 自动重写
+- 主预处理 `Calcit::Local` 分支: 增加 local fn 调用的重写+类型检查（clone 避免借用冲突）
+- `try_rewrite_single_tuple_to_enum_tuple()`: 增加变体验证 — 重写后立即检查 tag 是否是 enum 的合法 variant，不合法则发出警告
+
+### `src/bin/cr_tests/type_fail.rs`
+- 新增 `type_fail_type_slot_enum_invalid_variant` 测试，验证 TypeSlot 绑定的 enum 在自动重写路径下能正确检测不存在的 variant
+
+### `calcit/type-fail/type-slot-enum-invalid-variant.cirru`
+- 新增测试 fixture：声明 `defenum Action`、通过 TypeSlot 绑定、调用 `takes-action $ :: :nonexistent |hello`，期望产生 variant 不存在警告
+
+## 知识点
+
+1. **TypeSlot 解析链**: `TypeSlot(name) → resolve_type_slot(name) → CalcitTypeAnnotation (通常是 TypeRef)` → 再通过 `resolve_to_enum_with_ref()` 得到 enum 定义。这是一个两步间接过程。
+
+2. **`matches_with_bindings` 双向性**: TypeSlot 被解析后会调 `bound.matches_with_bindings(other, bindings)`，此时 self/other 顺序可能翻转。所有组合型匹配（如 Tuple/Enum）都需要双向 pattern。
+
+3. **`as_struct()` 返回引用**: `CalcitTypeAnnotation::as_struct()` 返回 `Option<&CalcitStruct>`，无法从临时解析结果中返回引用。修复方案是在调用点先解析 TypeSlot 再调 `as_struct()`。
+
+4. **自动重写的 `%::` 不经过 `preprocess_expr`**: `try_rewrite_single_tuple_to_enum_tuple` 构造的 `[NativeEnumTupleNew, ...]` 列表是在预处理完参数后生成的，不会经过 `check_proc_arg_types` 中的 `check_enum_tuple_construction`。因此变体验证必须在重写函数内部完成。
+
+5. **Local fn 调用缺少自动重写**: 原先只有 `CalcitFn` 调用走 `try_rewrite_tuple_args_to_enum_tuples`。`Calcit::Local` 调用（如回调参数 `d!`）需要单独处理。新函数接受 `CalcitFnTypeAnnotation` 而非 `CalcitFn`。
+
+6. **Lambda-in-map 的 EXPECTED_FN_TYPE 盲区**: `fn (e d!)` 在 hashmap 值（如 `:on-click`）中时，`d!` 不会获得 `EXPECTED_FN_TYPE` 注入的类型信息。目前通过显式 `%:: Op :variant` 写法绕过，属于已知架构限制。

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.14",
+    "version": "0.12.17",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.14",
+  "version": "0.12.17",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",

package/ts-src/calcit.procs.mts

@@ -22,7 +22,7 @@ import {
 } from "./calcit-data.mjs";
 
 import { CalcitRef } from "./js-ref.mjs";
-import { fieldsEqual, CalcitRecord } from "./js-record.mjs";
+import { CalcitRecord } from "./js-record.mjs";
 import { CalcitImpl } from "./js-impl.mjs";
 import { CalcitStruct } from "./js-struct.mjs";
 import { CalcitEnum } from "./js-enum.mjs";