@calcit/procs 0.12.14 → 0.12.15

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/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.14",
+    "version": "0.12.15",
     "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.15",
   "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";