@calcit/procs 0.12.20 → 0.12.21

package/editing-history/202604170520-simplify-generic-defns-via-method-dispatch.md

@@ -0,0 +1,49 @@
+# Simplify generic core defns via `.method` dispatch
+
+## 概要
+
+将 `calcit-core.cirru` 中的泛型 defn（`assoc` / `contains?` / `count` / `empty` / `empty?` / `filter` / `first` / `get` / `includes?` / `nth` / `rest` / `map`）从多分支 `if (list? x) ... if (map? x) ... if (record? x) ...` 链简化为 `list?` 快速路径 + `.method` 动态分发。
+
+## 动机
+
+- 用户要求：优先使用 `.method` 这套已有概念承担多态分发，避免每新增类型（record / tuple / set 等）都要在每个 defn 中追加分支。
+- 所有 built-in 类型已在 `&core-*-methods` 中注册了对应的 `.assoc` `.count` `.empty?` `.get` `.nth` 等方法条目，编译期 `try_inline_method_call` 已能在静态类型已知时把方法调用内联为直接 proc 调用，runtime 则由 `invoke_method` 处理。这使得 defn 自身不再需要枚举类型。
+
+## 实现
+
+以 `empty?` 为例：
+
+```cirru
+defn empty? (x)
+  if (nil? x) true $ if (list? x) (&list:empty? x) (.empty? x)
+```
+
+保留 `nil?` 与 `list?` 两个前置分支，其余类型全部交给 `.empty?`。
+
+**为什么保留 `list?` 快速路径**：
+`ensure_ns_def_compiled(CORE_NS, &init-builtin-impls!)` 在预处理期会展开 `do` 等 macro，其中 `(empty? body)` 会在 impls 还未注册到 runtime 时被调用；若此时 `empty?` 体里就走 `.empty?` → `invoke_method` → `evaluate_symbol_from_program("&core-list-impls", ...)` 会命中 quick-path 失败（循环依赖），导致 panic：
+
+```
+preprocess builtin impls: CalcitErr { kind: Var, msg: "expected symbol `&core-list-impls` from path `calcit.core`, this is a quick path, should succeed", ... }
+```
+
+`list?` 本身只用 `(&= (type-of x) :list)` 等 proc，不依赖 impl 注册，能在 bootstrap 期安全使用，打破循环；其余类型的 methods 此时已构建完毕，可顺利走方法派发。
+
+## 波及范围
+
+- `src/cirru/calcit-core.cirru`：12 个 defn 的 body 瘦身。
+- 预处理期的 `try_specialize_polymorphic_call`（已有）照常将 `(assoc x k v)` 等静态可推断调用折叠为 `&list:assoc`/`&map:assoc` 等 proc。
+- runtime 侧未变：仍由 `invoke_method` + `&core-*-impls` 完成最终派发。
+
+## 验证
+
+- `cargo fmt`
+- `cargo clippy --release -- -D warnings`
+- `cargo test --release`：179 + 67 通过
+- `yarn check-all`：全部 WASM/JS/解释执行测试通过
+- recollect (`cr --entry test` + `cr --entry test js` + `node test.mjs`) ✓
+- respo (`cr --check-only` + `cr js` + `yarn vite build`) ✓
+
+## 备注
+
+- 下一步可以考虑：把那些只剩 `list?` 单分支的 defn 再收拢到一个运行时 primitive，或在 preprocess 阶段对 macro 展开期调用的 `empty?` 等函数强制内联 proc，从而彻底去掉这条 fast path。

package/editing-history/202604172316-wasm-do-println-fixes.md

@@ -0,0 +1,41 @@
+# 202604172316 — WASM `do` body 与 println host import 修复
+
+## 修复内容
+
+### 1. `do` 在 defn body 中的 WASM 编译问题
+
+**现象**：`defn test-println () do (println 42) 1` 编译后生成 `f64.const 0`（函数体为空）。
+
+**根因**：Cirru 语法中 `defn f () do expr1 expr2` 解析为 `(defn f () do expr1 expr2)`，body 数组为 `[do, expr1, expr2]` 三个独立元素（不是 `[(do expr1 expr2)]`）。`do` 作为裸 Import 节点出现在 `emit_expr` 时，触发 "unsupported WASM expression" 错误，导致函数被跳过并 fallback 为 `f64.const 0`。
+
+**修复**：在 `emit_expr` 中为 `Calcit::Import { def: "do" }` 添加特例，将其视为 no-op（emit 0.0 后由 `emit_body` 的 Drop 消耗掉）。
+
+```rust
+// `do` as bare body expression is a no-op sequencer
+Calcit::Import(import) if import.def.as_ref() == "do" => {
+  ctx.emit(f64_const(0.0));
+}
+```
+
+### 2. io.log_value host import（WASM println）
+
+- WASM codegen 对 `println`/`eprintln`/`echo` 调用 host import `io.log_value`。
+- `test-wasm.mjs` 提供 `io.log_value` 实现：读取堆内存判断类型，字符串解码 UTF-8，数字直接输出。
+- 添加 `test-println` 测试用例验证功能。
+
+### 3. TypeScript 运行时 BufList 修复
+
+`_$n_buf_list_$o_concat` 中 `CalcitSliceList` 的 `items` 是方法而非属性，需调用 `xs.items()` 并手动迭代 Generator（TS 配置不支持 `for...of` Generator）。
+
+## 受影响文件
+
+- `src/codegen/emit_wasm.rs`：`emit_expr` 新增 `do` no-op 特例；`emit_call_expr` Import 分支也保留 `do` 处理（用于 `(do ...)` 调用形式）
+- `ts-src/calcit.procs.mts`：修正 `_$n_buf_list_$o_concat` 迭代逻辑
+- `calcit/test-wasm.cirru`：新增 `test-println`
+- `scripts/test-wasm.mjs`：新增 `io.log_value` 实现与 `test-println` 断言
+
+## 关键经验
+
+- `do` 在 Calcit defn body 中是语法糖/占位符，预处理后展开为多个独立 body 表达式，不是 `(do ...)` 调用形式。WASM codegen 需将其视为 no-op。
+- WASM 编译错误时 fallback 为 `f64.const 0`（静默），调试时需检查 stderr 中的 `[wasm] skipping` 日志。
+- TS 的 Generator 不能直接 `for...of`，需手动调用 `.next()`。

package/editing-history/202604181208-split-emit-wasm-and-bump-version.md

@@ -0,0 +1,15 @@
+## Summary
+
+- Split the WASM code generator so `src/codegen/emit_wasm.rs` keeps orchestration while runtime helpers, method dispatch, and record/tuple emitters live in dedicated submodules.
+- Bumped the Calcit patch version from `0.12.20` to `0.12.21` for the next release.
+
+## Module Layout
+
+- `src/codegen/emit_wasm/runtime.rs` now owns host import definitions, module assembly, and internal runtime helper builders.
+- `src/codegen/emit_wasm/methods.rs` now owns dynamic method dispatch and rest-arg call argument packing.
+- `src/codegen/emit_wasm/records.rs` now owns record and tuple emission helpers.
+
+## Notes
+
+- The split is intended to be behavior-preserving; no WASM semantics were changed as part of this refactor.
+- Version strings were updated in `Cargo.toml`, `package.json`, and `lib/package.json`, while generated JS version text will be refreshed by the validation build.

package/editing-history/202604181430-wasm-list-match-and-method-dispatch.md

@@ -0,0 +1,5 @@
+- WASM export names now stay unique by qualifying only colliding defs with `ns/def`.
+- `list-match` macro now uses `&list:empty?` after the existing list guard, avoiding the unsupported generic `empty?` invoke path in WASM.
+- Added minimal `Calcit::Method` handling in WASM for dynamic `.empty?`, `.count`, `.nth`, and `.get` calls.
+- `&tuple:nth` in WASM now accepts dynamic indices instead of literal-only indices.
+- Verified `yarn try-all` still passes in calcit after the WASM changes.

package/lib/calcit.procs.mjs

@@ -283,6 +283,56 @@ export function _$n_record_$o_count(x) {
         return x.fields.length;
     throw new Error(`expected a record ${x}`);
 }
+export function _$n_record_$o_field_tag(x, idx) {
+    if (!(x instanceof CalcitRecord))
+        throw new Error(`&record:field-tag expected a record, got ${x}`);
+    const i = idx;
+    if (i < 0 || i >= x.fields.length)
+        throw new Error(`&record:field-tag index ${i} out of bounds (${x.fields.length})`);
+    return x.fields[i];
+}
+// === BufList — mutable append-only list ===
+// Wrapper around a plain JS Array for O(1) push.
+export class CalcitBufList {
+    constructor(buf) {
+        this.buf = buf ?? [];
+    }
+}
+export function _$n_buf_list_$o_new() {
+    return new CalcitBufList();
+}
+export function _$n_buf_list_$o_push(buf, item) {
+    if (!(buf instanceof CalcitBufList))
+        throw new Error(`&buf-list:push expected a buf-list, got ${buf}`);
+    buf.buf.push(item);
+    return buf;
+}
+export function _$n_buf_list_$o_concat(buf, xs) {
+    if (!(buf instanceof CalcitBufList))
+        throw new Error(`&buf-list:concat expected a buf-list, got ${buf}`);
+    if (xs instanceof CalcitSliceList || xs instanceof CalcitList) {
+        const gen = xs.items();
+        let next = gen.next();
+        while (!next.done) {
+            buf.buf.push(next.value);
+            next = gen.next();
+        }
+    }
+    else {
+        throw new Error(`&buf-list:concat expected a list, got ${xs}`);
+    }
+    return buf;
+}
+export function _$n_buf_list_$o_to_list(buf) {
+    if (!(buf instanceof CalcitBufList))
+        throw new Error(`&buf-list:to-list expected a buf-list, got ${buf}`);
+    return new CalcitSliceList([...buf.buf]);
+}
+export function _$n_buf_list_$o_count(buf) {
+    if (!(buf instanceof CalcitBufList))
+        throw new Error(`&buf-list:count expected a buf-list, got ${buf}`);
+    return buf.buf.length;
+}
 export function _$n_set_$o_count(x) {
     if (x instanceof CalcitSet)
         return x.len();
@@ -1387,6 +1437,9 @@ export let nil_$q_ = (x) => {
 export let tag_$q_ = (x) => {
     return x instanceof CalcitTag;
 };
+export let symbol_$q_ = (x) => {
+    return x instanceof CalcitSymbol;
+};
 export let map_$q_ = (x) => {
     return x instanceof CalcitSliceMap || x instanceof CalcitMap;
 };

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.20",
+    "version": "0.12.21",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",
@@ -19,6 +19,7 @@
         "bench-recur-smoke": "cargo run --bin cr -- calcit/test.cirru js && node --input-type=module -e \"import { test_loop } from './js-out/test-recursion.main.mjs'; const n=3000; const t0=process.hrtime.bigint(); for(let i=0;i<n;i++) test_loop(); const dt=Number(process.hrtime.bigint()-t0)/1e6; console.log('test_loop_ms='+dt.toFixed(3));\"",
         "check-smooth": "yarn fmt-rs && yarn lint-rs && yarn test-rs && yarn check-all",
         "check-all": "yarn compile && yarn try-rs && yarn try-js && yarn try-ir && yarn try-wasm",
+        "try-all": "yarn check-all",
         "try-rs": "cargo run --bin cr -- calcit/test.cirru",
         "warn-dyn-method": "cargo run --bin cr -- calcit/test.cirru --warn-dyn-method",
         "try-js-brk": "cargo run --bin cr -- calcit/test.cirru js && node --inspect-brk js-out/main.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.20",
+  "version": "0.12.21",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",
@@ -19,6 +19,7 @@
     "bench-recur-smoke": "cargo run --bin cr -- calcit/test.cirru js && node --input-type=module -e \"import { test_loop } from './js-out/test-recursion.main.mjs'; const n=3000; const t0=process.hrtime.bigint(); for(let i=0;i<n;i++) test_loop(); const dt=Number(process.hrtime.bigint()-t0)/1e6; console.log('test_loop_ms='+dt.toFixed(3));\"",
     "check-smooth": "yarn fmt-rs && yarn lint-rs && yarn test-rs && yarn check-all",
     "check-all": "yarn compile && yarn try-rs && yarn try-js && yarn try-ir && yarn try-wasm",
+    "try-all": "yarn check-all",
     "try-rs": "cargo run --bin cr -- calcit/test.cirru",
     "warn-dyn-method": "cargo run --bin cr -- calcit/test.cirru --warn-dyn-method",
     "try-js-brk": "cargo run --bin cr -- calcit/test.cirru js && node --inspect-brk js-out/main.mjs",

package/ts-src/calcit.procs.mts

@@ -316,6 +316,57 @@ export function _$n_record_$o_count(x: CalcitValue): number {
 
   throw new Error(`expected a record ${x}`);
 }
+
+export function _$n_record_$o_field_tag(x: CalcitValue, idx: CalcitValue): CalcitTag {
+  if (!(x instanceof CalcitRecord)) throw new Error(`&record:field-tag expected a record, got ${x}`);
+  const i = idx as number;
+  if (i < 0 || i >= x.fields.length) throw new Error(`&record:field-tag index ${i} out of bounds (${x.fields.length})`);
+  return x.fields[i];
+}
+
+// === BufList — mutable append-only list ===
+// Wrapper around a plain JS Array for O(1) push.
+export class CalcitBufList {
+  buf: CalcitValue[];
+  constructor(buf?: CalcitValue[]) {
+    this.buf = buf ?? [];
+  }
+}
+
+export function _$n_buf_list_$o_new(): CalcitBufList {
+  return new CalcitBufList();
+}
+
+export function _$n_buf_list_$o_push(buf: CalcitValue, item: CalcitValue): CalcitBufList {
+  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:push expected a buf-list, got ${buf}`);
+  buf.buf.push(item);
+  return buf;
+}
+
+export function _$n_buf_list_$o_concat(buf: CalcitValue, xs: CalcitValue): CalcitBufList {
+  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:concat expected a buf-list, got ${buf}`);
+  if (xs instanceof CalcitSliceList || xs instanceof CalcitList) {
+    const gen = xs.items();
+    let next = gen.next();
+    while (!next.done) {
+      buf.buf.push(next.value);
+      next = gen.next();
+    }
+  } else {
+    throw new Error(`&buf-list:concat expected a list, got ${xs}`);
+  }
+  return buf;
+}
+
+export function _$n_buf_list_$o_to_list(buf: CalcitValue): CalcitSliceList {
+  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:to-list expected a buf-list, got ${buf}`);
+  return new CalcitSliceList([...buf.buf]);
+}
+
+export function _$n_buf_list_$o_count(buf: CalcitValue): number {
+  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:count expected a buf-list, got ${buf}`);
+  return buf.buf.length;
+}
 export function _$n_set_$o_count(x: CalcitValue): number {
   if (x instanceof CalcitSet) return x.len();
 
@@ -1504,6 +1555,9 @@ export let nil_$q_ = (x: CalcitValue): boolean => {
 export let tag_$q_ = (x: CalcitValue): boolean => {
   return x instanceof CalcitTag;
 };
+export let symbol_$q_ = (x: CalcitValue): boolean => {
+  return x instanceof CalcitSymbol;
+};
 export let map_$q_ = (x: CalcitValue): boolean => {
   return x instanceof CalcitSliceMap || x instanceof CalcitMap;
 };