@calcit/procs 0.12.35 → 0.12.37

package/editing-history/2026-0526-0957-match-docs-check-md.md

@@ -0,0 +1,24 @@
+# 2026-05-26 match 文档与 check-md 校验
+
+## 修改内容
+
+- 将 `match` 的文档说明统一为同时适用于 enum tuple 和 plain tuple，不再把 `tag-match` 描述成 plain tuple 的唯一入口。
+- 更新 `features/enums.md`、`features/tuples.md`、`features/common-patterns.md`、`features.md`、`quick-reference.md`、`run/agent-advanced.md` 中的推荐表述与示例。
+- 为 `agent-advanced.md` 里无法独立运行的 DOM / 事件示意片段补上 `cirru.no-check`，使 `cr docs check-md` 只校验可执行代码块。
+
+## 验证
+
+- `cargo run --bin cr -- eval $'match (:: :point 10 20)\n  (:point x y) (+ x y)\n  _ 0'`
+- `cargo run --bin cr -- docs check-md docs/features.md`
+- `cargo run --bin cr -- docs check-md docs/features/common-patterns.md`
+- `cargo run --bin cr -- docs check-md docs/features/enums.md`
+- `cargo run --bin cr -- docs check-md docs/features/error-handling.md`
+- `cargo run --bin cr -- docs check-md docs/features/traits.md`
+- `cargo run --bin cr -- docs check-md docs/features/tuples.md`
+- `cargo run --bin cr -- docs check-md docs/quick-reference.md`
+- `cargo run --bin cr -- docs check-md docs/run/agent-advanced.md`
+
+## 知识点
+
+- 原生 `match` 可以直接匹配 plain tuple；它不只适用于带 `defenum` 类型信息的 tuple。
+- 文档里的示意片段如果依赖 DOM helper、事件桥接函数或其他未加载上下文，应优先标记为 `cirru.no-check`，否则会被 `check-md` 的 `eval` 阻断。

package/editing-history/2026-0601-0003-update-callback-field-specialization.md

@@ -0,0 +1,19 @@
+# 2026-06-01 00:03 update callback field specialization
+
+## Summary
+
+- specialized `calcit.core/update` call checking so the 3rd callback arg can inherit a known record/struct field type instead of always staying at generic `fn('T) -> 'T`
+- fixed record field inference to resolve `TypeRef`-based struct annotations, not only direct `Record`/`Struct` annotations
+- aligned native `not` proc signature with calcit-core semantics by accepting dynamic input and returning `:bool`
+
+## Why
+
+- `respo` used precise type refs like `'respo.app.schema/Task`, but `infer_record_field_type` only looked through direct `Record`/`Struct` annotations, so `update task :done? not` could not see the field type
+- even after specializing `update`, Rust-side proc metadata still described `not` as `fn(:bool?) -> :bool`, which was stricter and inconsistent with the core schema/docs path
+
+## Validation
+
+- `cargo test specialize_update_uses_record_field_type_for_callback`
+- `cargo run --manifest-path /Users/chenyong/repo/calcit-lang/calcit/Cargo.toml --bin cr -- js` from `respo`
+- `yarn try-rs`
+- `cargo test`

package/editing-history/2026-0601-0005-release-0.12.36.md

@@ -0,0 +1,16 @@
+# 2026-06-01 00:05 release 0.12.36
+
+## Summary
+
+- bumped crate and npm package version from `0.12.35` to `0.12.36`
+- kept `ts-src/package.json` aligned with the root npm package metadata
+- prepared the workspace for a release lockfile refresh and tag creation
+
+## Why
+
+- this release publishes the `update` callback specialization and `not` proc typing fix after the PR checks passed
+- keeping repeated package metadata in sync avoids mismatched npm publish/version outputs during future packaging steps
+
+## Validation
+
+- `cargo update --workspace`

package/editing-history/2026-0601-2230-enum-struct-payload-docs.md

@@ -0,0 +1,4 @@
+- Documented that `defenum` payloads can reference named structs and applied generic structs.
+- Added runnable examples in `docs/features/enums.md` for plain struct payloads and generic struct payloads.
+- Clarified that `%::` validates struct payload values and generic arity at runtime when constructing enum instances.
+- Validation: `cargo run --bin cr -- demos/calcit.cirru docs check-md docs/features/enums.md`

package/editing-history/2026-0601-2317-data-definition-where-bounds.md

@@ -0,0 +1,6 @@
+- added where-bound metadata to struct and enum definitions, preserving it through parsing, hashing, compare, serialization, and enum prototype reconstruction
+- enforced data-definition generic trait bounds at runtime for `%{}`, `%{}?`, and `%::` by inferring concrete type bindings from record fields and enum payloads
+- kept builtin `Show` satisfaction narrow to builtin value families so function-level missing-impl warnings still fire correctly during preprocess
+- covered the new runtime path with focused Rust tests for accepting and rejecting struct/enum payloads under generic where-bounds
+- validated the calcit side with `cargo test where_bounds --lib`, `yarn check-all`, release `cr` build, and downstream respo compilation via `../../calcit-lang/calcit/target/release/cr js`
+- downstream follow-up in respo needed one explicit `assert-type text :string` for the `Op::update` payload under the stricter enum payload check

package/editing-history/2026-0602-0114-data-definition-where-macro-followup.md

@@ -0,0 +1,21 @@
+## Summary
+
+- restored high-level `defstruct` / `defenum` where-map syntax end to end after the Rust/runtime work landed
+- aligned JS runtime parsing in `ts-src/calcit.procs.mts` so `defstruct` / `defenum` skip optional generics and where-map entries before parsing fields or variants
+- kept the smoke test in `calcit/test-enum.cirru` on the high-level syntax and reran broad validation
+
+## Knowledge Points
+
+- the JS-emitted high-level data-definition forms do not preserve where-map heads as a stable plain symbol; the first item may be a runtime function alias or even an unresolved value shape, so detecting where-map entries by exact head identity is brittle
+- a safer JS-side strategy is structural detection: after an optional generics list, treat a list as a where-map form when its head is not a tag/symbol/string and the remaining items are all 2-item pairs
+- for current JS codegen, generic parameter lists arrive as a simple list of `CalcitSymbol`s, so the runtime parser can ignore that leading entry without needing full type-variable reconstruction
+
+## Validation
+
+- `cargo fmt`
+- `cargo test where_bounds --lib`
+- `cargo run --bin cr -- calcit/test-enum.cirru`
+- `yarn compile && yarn try-js`
+- `yarn try-rs`
+- `yarn try-ir`
+- `yarn try-wasm`

package/editing-history/202605210055-tree-show-cr-config-and-edit-cleanup.md

@@ -0,0 +1,81 @@
+# 202605210055 — tree show 可选路径 + cr config 顶级命令 + cr edit 清理
+
+## 修改概要
+
+### 1. `cr tree show` — `-p` 参数改为可选，缺失时警告而非报错
+
+**动机**: Agent 调用 `cr tree show ns/def` 时若忘记 `-p`，原来直接报错导致 token 浪费。
+
+**变更文件**:
+
+- `src/cli_args.rs`: `TreeShowCommand.path` 类型从 `String` → `Option<String>`，doc 注释更新
+- `src/bin/cli_handlers/tree.rs`: `handle_show` 中对 `None` 输出黄色 `[Warn]`，默认使用空路径（root）
+- `src/bin/cli_handlers/command_echo.rs`: `push_tree` Show 分支改用 `opt "path"` 宏处理 Option 类型
+
+**效果**:
+
+```
+$ cr calcit.cirru tree show "ns/def"
+[Warn] No path (-p) specified; showing from root. Use -p '0' to start from a child node.
+Type: list (4 items)
+...
+```
+
+---
+
+### 2. `cr config` — 顶级配置管理命令
+
+**动机**: `cr query config`、`cr query modules`、`cr edit config`、`cr edit add-module`、`cr edit rm-module` 分散在不同子命令下，操作配置需要记忆多个入口。新增统一入口 `cr config`。
+
+**新命令**:
+| 命令 | 等价旧命令 |
+|---|---|
+| `cr config show` | `cr query config` |
+| `cr config modules` | `cr query modules` |
+| `cr config version [value]` | `cr edit config version ...` |
+| `cr config set <key> <value>` | `cr edit config <key> <value>` |
+| `cr config add-module <path>` | `cr edit add-module <path>` |
+| `cr config rm-module <path>` | `cr edit rm-module <path>` |
+
+`cr config version` 可独立使用（无参数显示当前版本，传 `patch/minor/major` 递增，传 semver 直接设置）。
+
+**变更文件**:
+
+- `src/cli_args.rs`: 添加 `CalcitCommand::Config`、`ConfigCommand`、`ConfigSubcommand`（含 `ConfigVersionCommand`）及各子命令 struct
+- `src/bin/cli_handlers/config.rs`: 新建，实现 `handle_config_command` 及各子命令处理函数（含 `handle_version`）
+- `src/bin/cli_handlers/edit.rs`: `parse_semver_value`、`bump_semver_value` 改为 `pub(crate)`
+- `src/bin/cli_handlers/mod.rs`: 注册 `mod config` 并 re-export `handle_config_command`
+- `src/bin/cli_handlers/command_echo.rs`: 添加 `config_name`、`push_config`，并在 `should_echo_command` / `render_command_echo` 中处理 `Config` 变体
+- `src/bin/cr.rs`: 添加 `CalcitCommand::Config` 分支
+
+---
+
+### 3. `cr edit` 清理 — 移除已迁移至 `cr config` 的子命令
+
+**动机**: `cr edit add-module`、`cr edit rm-module`、`cr edit config` 与新增的 `cr config` 重复，保持单一职责。
+
+**删除内容**:
+
+- `EditSubcommand::AddModule / RmModule / Config` 及对应 struct（`cli_args.rs`）
+- `handle_add_module / handle_rm_module / handle_config` 函数体（`edit.rs`）
+- `command_echo.rs` 中 `edit_name` 和 `push_edit` 两处 match 的三个变体
+
+**保留**（被 `config.rs` 和单元测试引用）:
+
+- `pub(crate) fn parse_semver_value` — semver 字符串解析
+- `pub(crate) fn bump_semver_value` — patch/minor/major 递增
+
+**文档更新**:
+
+- `docs/run/agent-advanced.md` "模块和配置" 章节、快速参考示例 → 全部改为 `cr config` 命令
+- `docs/CalcitAgent.md` 第 9 节"cr 能力地图" → 新增"配置管理"条目
+
+---
+
+## 知识点
+
+- `argh` 中将 `#[argh(option)]` 字段类型改为 `Option<T>` 可使该选项变为可选
+- `pub(crate)` 可在同一 crate 内跨模块共享；被其他模块引用时，不能因删除调用方而一并删除
+- 新增顶级命令时需同步更新 `command_echo.rs` 的三处：`should_echo_command`、`render_command_echo`（名称映射和 token push）
+- 移除 enum 变体时，需同时检查 `command_echo.rs` 的两处 match（`edit_name` 和 `push_edit`）
+- 单元测试也会引用函数，删除前要 grep `tests` 模块确认

package/editing-history/202605312052-macro-schema-roundtrip-and-weak-types.md

@@ -0,0 +1,6 @@
+- refined weak-types reporting in `cr analyze weak-types` to classify schema/code hits with detail paths
+- tightened builtin proc signatures for list/map/set/buf-list helpers toward generic compound types
+- kept `field-match` / `record-match` macro schema inputs precise in `calcit-core` while preserving round-trip behavior
+- fixed macro schema serialization to keep non-dynamic returns like `:record` instead of dropping them during snapshot save/load
+- aligned bare marker tag parsing for `:record` and related special tags with schema normalization behavior
+- updated docs and parser tests to current wrapped schema / guidebook-loading behavior

package/editing-history/202605312059-ci-docs-test-and-fn-helper-tightening.md

@@ -0,0 +1,3 @@
+- fixed docs query test to be stable both with and without ~/.config/calcit/docs configured, matching CI runner behavior
+- tightened calcit.core fn helper schemas for &fn:apply / &fn:bind / &fn:map to reduce nested schema-dynamic usage
+- validated with focused docs test, full cargo test, runtime cr calcit/test.cirru, weak-types analyze, and yarn check-all

package/editing-history/202605312105-map-generic-weak-types-followup.md

@@ -0,0 +1,15 @@
+- tightened multiple calcit.core snapshot schemas that safely remove weak composite internals without narrowing runtime behavior: typed path lists for `assoc-in`/`get-in`/`dissoc-in`/`update-in`/`contains-in?`, typed collection helpers like `apply`, `join-str`, `foldr-shortcut`, and explicit output map generics for `map-kv` and `pairs-map`
+- corrected one weak-types false lead by changing `keys` from returning `:list` to `:set`, matching runtime/tests and moving that hit out of the list family
+- extended `cr analyze weak-types` to classify nested schema-dynamic shapes/families, include per-definition summaries, split family/shape counts by `arg`/`return` position, and show per-definition `shape@position` contributors for the remaining hotspots
+- confirmed the current lower-bound weak hits under the existing type system: `&record:to-map` for heterogeneous record values; `&tuple:params`, `&cirru-quote:to-list`, `parse-cirru-list`, `&format-ternary-tree`, `&list:flatten`, `format-cirru`, and `format-cirru-one-liner` for mixed list payloads that cannot be soundly collapsed to `list<'T>`
+- verified the final baseline at schema-dynamic=290 with `cargo test --bin cr analyze_weak_types -- --nocapture`, repeated `cargo run --bin cr -- calcit/test.cirru analyze weak-types --ns calcit.core --only schema-dynamic`, and runtime suite checks via `cargo run --bin cr -- calcit/test.cirru`
+- aligned `parse-float` runtime behavior with the existing optional-number schema across Rust and JS: invalid input now yields `nil`/`null` instead of throwing or leaking `NaN`, and added inference coverage in `calcit/test-types-inference.cirru`
+- aligned JS record missing-field behavior with Rust/eval by making `CalcitRecord.get` return `undefined` on absent fields, which keeps top-level `get` and `get-in` optional semantics consistent across runtimes
+- refined preprocess return inference for `calcit.core/get` and `calcit.core/get-in`, so list/string/map/record accesses produce precise `optional<...>` results for literal paths instead of collapsing to broad `dynamic` in the common safe cases
+- tightened the generic matching path so `Struct` annotations and bare `TypeRef` names bind declared type variables consistently when only one side carries applied type arguments, reducing a gap that previously skipped bindings needed by later generic specialization and `:where` checks
+- validated the follow-up with `cargo run --bin cr -- calcit/test-types-inference.cirru`, `cargo test binds_generic_args_from`, `cargo fmt && cargo test binds_generic_args_from`, and `yarn try-rs`
+- added RFC `RFCs/06-01-generic-binding-unification-rfc.md` to document the next step for Rust-like generic binding unification across `Struct` / `Enum` / `TypeRef`, including concrete examples, rollout stages, and the tradeoff that enum support needs deeper metadata changes than the struct-side fix
+- extended the enum-generic foundation end to end: runtime enum metadata now preserves declared generics, `&enum::new` accepts generic parameter lists, and applied named enum annotations like `(:: 'ResultX :number :string)` validate against payload creation instead of being rejected as "enum cannot be generic"
+- fixed the remaining struct declaration gap in the core macros/runtime boundary: `defstruct Box ([] 'T) (:value 'T)` now lowers to a real generics list for `&struct::new`, and generic field annotations are preserved as type forms instead of being evaluated away before runtime parsing
+- documented the current runnable generic data-structure entry points in `docs/features/records.md` and `docs/features/enums.md`, including a high-level generic `defstruct` example and the current stable generic-enum constructor form via `&enum::new`
+- validated the new docs/examples with direct eval smoke checks for the struct and enum snippets, `cargo run --bin cr -- demos/calcit.cirru docs check-md docs/features/records.md`, `cargo run --bin cr -- demos/calcit.cirru docs check-md docs/features/enums.md`, and `cargo run --bin cr -- calcit/test-generics.cirru`

package/lib/calcit.procs.mjs

@@ -103,6 +103,57 @@ const list_items = (item) => {
     }
     throw new Error(`Expected list entry, got: ${item}`);
 };
+const isQuotedTypeVar = (item) => {
+    if (item instanceof CalcitSymbol) {
+        return true;
+    }
+    if (item instanceof CalcitList || item instanceof CalcitSliceList) {
+        const items = Array.from(item.items());
+        return items.length === 2 && items[0] instanceof CalcitSymbol && items[0].value === "quote" && items[1] instanceof CalcitSymbol;
+    }
+    return false;
+};
+const isGenericsEntry = (entry) => {
+    if (!(entry instanceof CalcitList || entry instanceof CalcitSliceList)) {
+        return false;
+    }
+    const items = Array.from(entry.items());
+    return items.length > 0 && items.every(isQuotedTypeVar);
+};
+const isWhereMapEntry = (entry) => {
+    // where-bound can be emitted as a CalcitMap (from _$n__$M_) or as a list-of-pairs
+    if (entry instanceof CalcitMap || entry instanceof CalcitSliceMap) {
+        return true;
+    }
+    if (!(entry instanceof CalcitList || entry instanceof CalcitSliceList)) {
+        return false;
+    }
+    const items = Array.from(entry.items());
+    if (items.length < 2) {
+        return false;
+    }
+    const head = items[0];
+    if (head instanceof CalcitTag || head instanceof CalcitSymbol || typeof head === "string") {
+        return false;
+    }
+    return items.slice(1).every((item) => {
+        if (!(item instanceof CalcitList || item instanceof CalcitSliceList)) {
+            return false;
+        }
+        const pair = Array.from(item.items());
+        return pair.length === 2;
+    });
+};
+const trimDataDefinitionEntries = (entries) => {
+    let start = 0;
+    if (entries[start] != null && isGenericsEntry(entries[start])) {
+        start += 1;
+    }
+    if (entries[start] != null && isWhereMapEntry(entries[start])) {
+        start += 1;
+    }
+    return entries.slice(start);
+};
 export let _$n_trait_$o__$o_new = function (name, methods) {
     if (arguments.length !== 2)
         throw new Error("&trait::new expected 2 arguments");
@@ -172,7 +223,8 @@ export let _$n_assert_traits = function (value, traitDef) {
 export let defstruct = (name, ...entries) => {
     const structName = castTag(name);
     const fields = [];
-    for (let entry of entries) {
+    const fieldEntries = trimDataDefinitionEntries(entries);
+    for (let entry of fieldEntries) {
         const items = list_items(entry);
         if (items.length !== 2) {
             throw new Error(`defstruct expects (field type) pairs, got: ${toString(entry, true)}`);
@@ -194,7 +246,8 @@ export let defstruct = (name, ...entries) => {
 export let defenum = (name, ...variants) => {
     const enumName = castTag(name);
     const entries = [];
-    for (let variant of variants) {
+    const variantEntries = trimDataDefinitionEntries(variants);
+    for (let variant of variantEntries) {
         const items = list_items(variant);
         if (items.length === 0) {
             throw new Error("defenum expects variant tag and payload types, got empty list");
@@ -1183,7 +1236,11 @@ export let _$n_str_$o_find_index = (x, y) => {
     return x.indexOf(y);
 };
 export let parse_float = (x) => {
-    return parseFloat(x);
+    const value = parseFloat(x);
+    if (Number.isNaN(value)) {
+        return null;
+    }
+    return value;
 };
 export let trim = (x, c) => {
     if (c != null) {

package/lib/js-record.mjs

@@ -26,7 +26,7 @@ export class CalcitRecord {
             return this.values[idx];
         }
         else {
-            throw new Error(`Cannot find :${field} among (${this.fields.join(",")})`);
+            return undefined;
         }
     }
     getOrNil(k) {

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.35",
+    "version": "0.12.37",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.7.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.35",
+  "version": "0.12.37",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.7.0",

package/ts-src/calcit.procs.mts

@@ -126,6 +126,61 @@ const list_items = (item: CalcitValue): CalcitValue[] => {
   throw new Error(`Expected list entry, got: ${item}`);
 };
 
+const isQuotedTypeVar = (item: CalcitValue): boolean => {
+  if (item instanceof CalcitSymbol) {
+    return true;
+  }
+  if (item instanceof CalcitList || item instanceof CalcitSliceList) {
+    const items = Array.from(item.items());
+    return items.length === 2 && items[0] instanceof CalcitSymbol && items[0].value === "quote" && items[1] instanceof CalcitSymbol;
+  }
+  return false;
+};
+
+const isGenericsEntry = (entry: CalcitValue): boolean => {
+  if (!(entry instanceof CalcitList || entry instanceof CalcitSliceList)) {
+    return false;
+  }
+  const items = Array.from(entry.items());
+  return items.length > 0 && items.every(isQuotedTypeVar);
+};
+
+const isWhereMapEntry = (entry: CalcitValue): boolean => {
+  // where-bound can be emitted as a CalcitMap (from _$n__$M_) or as a list-of-pairs
+  if (entry instanceof CalcitMap || entry instanceof CalcitSliceMap) {
+    return true;
+  }
+  if (!(entry instanceof CalcitList || entry instanceof CalcitSliceList)) {
+    return false;
+  }
+  const items = Array.from(entry.items());
+  if (items.length < 2) {
+    return false;
+  }
+  const head = items[0];
+  if (head instanceof CalcitTag || head instanceof CalcitSymbol || typeof head === "string") {
+    return false;
+  }
+  return items.slice(1).every((item) => {
+    if (!(item instanceof CalcitList || item instanceof CalcitSliceList)) {
+      return false;
+    }
+    const pair = Array.from(item.items());
+    return pair.length === 2;
+  });
+};
+
+const trimDataDefinitionEntries = (entries: CalcitValue[]): CalcitValue[] => {
+  let start = 0;
+  if (entries[start] != null && isGenericsEntry(entries[start])) {
+    start += 1;
+  }
+  if (entries[start] != null && isWhereMapEntry(entries[start])) {
+    start += 1;
+  }
+  return entries.slice(start);
+};
+
 export let _$n_trait_$o__$o_new = function (name: CalcitValue, methods: CalcitValue): CalcitTrait {
   if (arguments.length !== 2) throw new Error("&trait::new expected 2 arguments");
   const items = list_items(methods);
@@ -195,8 +250,9 @@ export let _$n_assert_traits = function (value: CalcitValue, traitDef: CalcitVal
 export let defstruct = (name: CalcitValue, ...entries: CalcitValue[]): CalcitStruct => {
   const structName = castTag(name);
   const fields: Array<{ tag: CalcitTag; type: CalcitValue }> = [];
+  const fieldEntries = trimDataDefinitionEntries(entries);
 
-  for (let entry of entries) {
+  for (let entry of fieldEntries) {
     const items = list_items(entry);
     if (items.length !== 2) {
       throw new Error(`defstruct expects (field type) pairs, got: ${toString(entry, true)}`);
@@ -221,8 +277,9 @@ export let defstruct = (name: CalcitValue, ...entries: CalcitValue[]): CalcitStr
 export let defenum = (name: CalcitValue, ...variants: CalcitValue[]): CalcitEnum => {
   const enumName = castTag(name);
   const entries: Array<{ tag: CalcitTag; payload: CalcitSliceList }> = [];
+  const variantEntries = trimDataDefinitionEntries(variants);
 
-  for (let variant of variants) {
+  for (let variant of variantEntries) {
     const items = list_items(variant);
     if (items.length === 0) {
       throw new Error("defenum expects variant tag and payload types, got empty list");
@@ -1283,8 +1340,12 @@ export let _$n_str_$o_find_index = (x: string, y: string): number => {
   return x.indexOf(y);
 };
 
-export let parse_float = (x: string): number => {
-  return parseFloat(x);
+export let parse_float = (x: string): number | null => {
+  const value = parseFloat(x);
+  if (Number.isNaN(value)) {
+    return null;
+  }
+  return value;
 };
 export let trim = (x: string, c: string): string => {
   if (c != null) {

package/ts-src/js-record.mts

@@ -34,7 +34,7 @@ export class CalcitRecord {
     if (idx >= 0) {
       return this.values[idx];
     } else {
-      throw new Error(`Cannot find :${field} among (${this.fields.join(",")})`);
+      return undefined;
     }
   }
   getOrNil(k: CalcitValue) {