@calcit/procs 0.12.56 → 0.12.57

package/editing-history/archived/2026-04-25-2003-wasm-method-includes-string-and-set-refactor.md

@@ -1,71 +0,0 @@
-# 202604252003 — WASM suite extended: .includes? string branch + uncommitted refactor consolidation
-
-## Background
-
-In the previous session a multi-module WASM suite entry (`calcit/test-wasm-suite.cirru`) was added
-to gradually exercise more of the existing `calcit/test-*.cirru` programs against the WASM codegen.
-At that point a sizable in-progress refactor in `src/codegen/emit_wasm/{heap,hof,lists,runtime,sets}.rs`
-was left uncommitted alongside, and `test-string.cirru` was deferred because folding it into the
-suite triggered an `unreachable` trap.
-
-## Findings this round
-
-When folding `test-string.main` into `test-wasm-suite.main/main!`, the runtime trap reproduced. By
-calling individual exports (new helper `scripts/test-wasm-call.mjs`) it was clear that:
-
-1. `(.includes? "abc" "abc")` returned `0` (false) instead of `1`. Root cause:
-   `methods::emit_method_includes` only handled `list/map/set` receivers; for any other type it
-   emitted `f64_const(0.0)` as the fallback. Strings therefore never reached
-   `__rt_str_find_index`.
-2. After fixing #1, `test-includes` still trapped — the assertions
-   `assert= true $ starts-with? :a/b :a/` and `assert= true $ starts-with? :a/b |a/` pass
-   tags as arguments. Tags in WASM are encoded as small `f64` values equal to their tag-index id,
-   so `__rt_str_starts_with` reads them as bogus heap pointers and silently returns 0. Adding tag→
-   string conversion at runtime is a follow-up.
-3. `test-bitwise` traps on `&number:display-by` (radix formatting) which is currently stubbed to
-   return `0`.
-
-Because #2 and #3 require additional runtime helpers, `test-string.cirru` is left out of the suite
-for this commit. The `.includes?` regression is fixed in isolation; it also benefits any other
-program that calls `.includes?` on a string.
-
-## Changes in this commit
-
-- `src/codegen/emit_wasm/methods.rs`: extend `emit_method_includes` with a string branch
-  (`emit_str_includes_from_local`) that calls `__rt_str_find_index >= 0`.
-- `scripts/test-wasm-call.mjs`: minimal helper to invoke a single named export against the latest
-  `js-out/program.wasm`, useful for bisecting which assertion in a `main!` traps.
-
-The commit also folds in the previously-uncommitted refactor that landed in
-`src/codegen/emit_wasm/{heap,hof,lists,runtime,sets}.rs`:
-
-- `sets.rs`: `emit_set_find_structural` replaces the pointer-only `__rt_set_find_elem` for
-  `difference`/`intersection`/set-equality so identical-by-content elements are treated as equal.
-- `runtime.rs`: new `__rt_hash_list_or_set(ptr) -> i32` (XOR-based content hash) plus a couple of
-  new helper-function indices.
-- `hof.rs`: `emit_copy_type_tag` so `map`/`filter` preserve the receiver tag (set→set, list→list).
-- `lists.rs`: `range start end step` 3-arg form.
-- `heap.rs`: smarter `emit_hash_proc` that detects heap pointers at runtime and dispatches to the
-  list/set hash helper. The dead `emit_hash_expr_i32`/`emit_hash_mix` static helpers are removed.
-- `emit_wasm.rs`: `#[allow(private_interfaces)]` on `emit_equals_core` and
-  `emit_equals_core_shallow` (both already returned a `pub(super)`-only opaque local index but are
-  used from sibling modules through the `super::*` re-export).
-
-## Verification
-
-```bash
-bash scripts/cargo-with-sdk.sh clippy --bin cr-wasm -- -D warnings   # clean
-bash scripts/cargo-with-sdk.sh build  --bin cr-wasm --release        # ok
-bash scripts/test-wasm-suite-extended.sh                             # PASS
-bash scripts/test-wasm-suite.sh                                      # 6/10 (unchanged)
-```
-
-`scripts/test-wasm-suite.sh` skips `test-fn`, `test-string`, `test-tuple`, `test-list` for the
-same reasons documented previously; that is independent of this commit.
-
-## Follow-ups
-
-1. Tag → string conversion at runtime so string procs accept tags (unblocks `test-string`).
-2. `&number:display-by` radix formatting (unblocks the last 3 assertions in `test-bitwise`).
-3. The other test-string skips (`&str:replace`, `parse-float`, `blank?`, `trim`,
-   `get-char-code`, `format-to-cirru`, `&cirru-quote:to-list`).

package/editing-history/archived/2026-04-25-2010-wasm-suite-add-fn-lens-edn.md

@@ -1,43 +0,0 @@
-# 202604252010 — WASM suite extended: + test-fn / test-lens / test-edn
-
-## Background
-
-After landing the `.includes?` string fix, this round adds three more `test-*.cirru` programs to
-`calcit/test-wasm-suite.cirru` to cover more of the WASM runtime surface. Goal: keep growing the
-"runs end-to-end in WASM" set without depending on Host FFI features.
-
-## Process
-
-For each candidate module:
-
-1. Inspect `cr-wasm <module>.cirru` standalone to enumerate `[wasm] skipping ...` lines (these are
-   per-def errors that cause that def to be replaced with a `0.0`-returning stub).
-2. Read the module's `main!` body to confirm trapping assertions can survive when the skipped
-   helpers return `0`.
-3. Add to the suite, rebuild, and run `bash scripts/test-wasm-suite-extended.sh`.
-
-## Result
-
-Suite now covers (in addition to previous `test-cond/test-math/test-set/test-tuple`):
-
-- `test-fn` — only `&init-builtin-impls!` skipped; suite passes cleanly.
-- `test-lens` — `test-lens.main/test-lens` is skipped (`:::` rejects a quoted form arg) but other
-  defs in the module compile; `main!` does not trip the stub.
-- `test-edn` — many sub-tests skipped (`parse-cirru-edn`, `trim`, `&extract-code-into-edn`), but
-  the skipped fns return `0` instead of running their assertions, so `main!` completes.
-
-Modules tried but reverted:
-
-- `test-string` — assertions feed tags into `starts-with?`/`ends-with?`/`includes?`. Tags in WASM
-  are encoded as small `f64` ids (their tag-index value), not heap string pointers, so the procs
-  silently return `0` and the assertion traps. Needs a tag→string runtime helper.
-- `test-algebra` — `test-map` exercises `%{} AlgebraBox`, `assert-traits`, `.map` on records, and
-  `:value` access; record/trait dispatch is not yet implemented in WASM.
-- `test-map` (the standalone, full map suite) — `test-pairs`/`test-keys` etc. compile but trap at
-  runtime, likely from map iteration ordering or hash collision behavior. Needs deeper triage.
-
-## Verification
-
-```bash
-bash scripts/test-wasm-suite-extended.sh   # PASS (8 modules including util)
-```

package/editing-history/archived/2026-04-25-2051-display-by.md

@@ -1,39 +0,0 @@
-# `&number:display-by` WASM 实现
-
-## 摘要
-
-实现了 `&number:display-by` 和 `.display-by` 方法的 WASM codegen，支持二进制、八进制、十六进制格式化，并将 `test-string` 模块加入 WASM 扩展测试套件。
-
-## 关键实现点
-
-### `build_rt_display_by` (runtime.rs)
-
-- 函数签名: `(value: f64, radix: f64) -> f64` (返回字符串堆 ptr)
-- 算法：负数检测 → 计数位数（div 循环）→ 计算前缀长度（radix ∈ {2,8,16} → 2, else 0）→ 分配堆字符串 → 写前缀（`0b`/`0o`/`0x`）→ 从右往左写位数（`'0'..digit` 或 `'a'..digit-10`）
-- locals 索引 2-16，手动分配（非 RuntimeFnBuilder 风格）
-- 负数：先检测，计数时用 abs_i64，最后写 '-'
-
-### 注意
-
-- 必须先用 `collect_strings_from_expr` 收集 tag 名称才能支持 tag→string（前一次提交已做）
-- local 参数：value=0, radix=1；其余 2..16 为局部变量
-
-### 测试
-
-- `test-display-by-bin()` = 7 (17 → "0b10001")
-- `test-display-by-hex()` = 4 (17 → "0x11")
-- test-string 模块加入 test-wasm-suite（8个模块），全部 PASS
-
-## 修改文件
-
-- `src/codegen/emit_wasm/runtime.rs` — 新增 `build_rt_display_by` + 注册 `__rt_display_by`
-- `src/codegen/emit_wasm.rs` — 分拆 `NativeNumberDisplayBy` 从 stub 到 `call_rt("__rt_display_by")`
-- `src/codegen/emit_wasm/methods.rs` — 新增 `.display-by` 方法分发
-- `calcit/test-wasm-suite.cirru` — 加入 `test-string`
-- `calcit/test-wasm.cirru` — 新增 `test-display-by-bin` / `test-display-by-hex`
-- `scripts/test-wasm.mjs` — 新增对应断言
-
-## 后续计划
-
-- `trim`、`blank?`、`&str:replace`、`parse-float`、`get-char-code`
-- HOF closures-as-values (S1 fn-table)

package/editing-history/archived/2026-04-28-1728-fix-gensym-stable.md

@@ -1,31 +0,0 @@
-# Fix: Gensym 稳定性问题
-
-## 问题描述
-
-`cr js` 每次运行会生成不同的 JS 文件，原因是 gensym 计数器不稳定（如 `v__1` 变成 `v__3`）。
-
-## 根本原因
-
-Calcit 的 gensym 使用 `NS_SYMBOL_DICT: HashMap<Arc<str>, usize>` 记录计数器。由于 Rust 的 `HashMap` 每进程随机化迭代顺序，不同运行时的 def 编译顺序不同，导致 gensym 计数器累积值不一样。
-
-有**两条**编译路径，只修了一条是不够的：
-1. `ensure_ns_def_preprocessed` —— 正常编译路径，通过 `with_compiling_def` 重置 gensym 计数器（之前已修）
-2. `compile_source_def_for_snapshot` —— 快照填充路径（JS codegen 时触发），**缺少 `with_compiling_def` 包装**，导致 `CURRENT_COMPILING_DEF` 为 `None`，gensym 退回到 `file_ns`（命名空间级 key），计数器跨 def 累积
-
-## 修复方法
-
-在 `src/runner/preprocess/mod.rs` 的 `compile_source_def_for_snapshot` 函数中，为 `preprocess_expr` 调用加上 `builtins::meta::with_compiling_def(ns, def, ...)` 包装，与 `ensure_ns_def_preprocessed` 保持一致。
-
-## 已修改文件
-
-- `src/builtins/syntax.rs`: gensym key 改为 `CURRENT_COMPILING_DEF`（无 `file_ns` 前缀）
-- `src/builtins/meta.rs`: 新增 `CURRENT_COMPILING_DEF` thread_local + `with_compiling_def`（自动重置计数器）
-- `src/runner/preprocess/mod.rs`:
-  - `ensure_ns_def_preprocessed`: 包 `with_compiling_def`（第一次修）
-  - `compile_source_def_for_snapshot`: 包 `with_compiling_def`（本次修）
-
-## 验证
-
-- `cr js` 连续 8 次运行，无任何文件变化
-- `cargo test` 67 passed
-- `yarn check-all` 全部通过

package/editing-history/archived/2026-04-29-1400-fix-bind-type-precompile.md

@@ -1,38 +0,0 @@
-# Fix: bind-type 类型槽预编译顺序问题
-
-## 问题描述
-
-`cr js` 在 tiye-index 项目中，`reel.app.comp.todolist.mjs` 和 `respo.schema.mjs` 仍然不稳定——有时生成 `Op`-aware 版本（带 `import { Op }` 和 `$clt._PCT__$o__$o_(Op, ...)`），有时生成不带 Op 的版本（使用 `$clt._$o__$o_(...)`）。
-
-## 根本原因
-
-`bind-type :dispatch-op Op` 在 `respo.main/main!` 函数体中，是一个预处理阶段的副作用操作：当 `preprocess_expr` 遇到 `bind-type` 调用时，立即执行 `bind_type_slot("dispatch-op", Op)`，使 `*dispatch-op` 类型槽指向 Op 枚举。
-
-问题根源：`reel.app.comp.todolist` 等组件 def 会作为入口函数 `app.main/main!` 的传递依赖被提前编译。由于 HashMap 迭代顺序不确定，某些运行中 `todolist` 在 `respo.main/main!` 之前编译——此时 `*dispatch-op` 类型槽尚未绑定，导致 `d! $ :: :states cursor ...` 中的元组字面量无法被改写为 `%:: Op :states cursor ...`，生成结构上不同的 JS 代码。
-
-## 修复方法
-
-**双重修复：**
-
-### 1. 预处理阶段：`precompile_bind_type_defs` (主要修复)
-
-在 `src/lib.rs` 的 `run_program_with_docs` 中，在开始主入口预处理之前，先扫描**所有**程序源代码，找出含有 `bind-type` 调用的 def，并提前编译它们。
-
-这确保 `respo.main/main!`（含 `bind-type :dispatch-op Op`）在 `app.main/main!` 的依赖树遍历之前被编译，从而使 `:dispatch-op` 类型槽在所有组件编译前就已绑定。
-
-### 2. 快照填充阶段：任务排序 (辅助修复)
-
-在 `src/program.rs` 的 `collect_snapshot_fill_tasks` 中，对快照填充任务排序，确保含 `bind-type` 的 def 在快照阶段也优先处理，同时按 (ns, def) 字典序排序保证完全确定性。
-
-## 已修改文件
-
-- `src/lib.rs`: 在 `run_program_with_docs` 中调用新增的 `precompile_bind_type_defs`
-- `src/runner/preprocess/mod.rs`: 新增 `precompile_bind_type_defs` 公开函数（扫描所有源 def，提前编译含 `bind-type` 的 def）
-- `src/program.rs`:
-  - `calcit_contains_bind_type` 改为 `pub fn`（供 preprocess 模块使用）
-  - `collect_snapshot_fill_tasks` 中对任务排序（bind-type 优先，其余按字典序）
-
-## 验证
-
-- `cr js` 在 tiye-index 项目连续 8 次运行，第 1 次（旧输出重新生成）后无任何文件变化
-- `cargo test --lib` 179 tests passed

package/editing-history/archived/2026-05-26-0957-match-docs-check-md.md

@@ -1,24 +0,0 @@
-# 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/archived/2026-05-31-2059-ci-docs-test-and-fn-helper-tightening.md

@@ -1,3 +0,0 @@
-- 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/archived/2026-06-01-0005-release-0.12.36.md

@@ -1,16 +0,0 @@
-# 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/archived/2026-06-01-2230-enum-struct-payload-docs.md

@@ -1,4 +0,0 @@
-- 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/archived/2026-06-03-1620-release-0.12.38.md

@@ -1,6 +0,0 @@
-# 2026-06-03 release 0.12.38
-
-- 在功能提交通过 PR Actions 后，执行版本升级为 `0.12.38`。
-- 同步更新 `Cargo.toml` 与 `package.json` 的版本号。
-- 执行 `cargo update --workspace`，更新 `Cargo.lock` 中工作区版本引用到 `0.12.38`。
-- 发布前置流程保持不变：等待升级提交再次通过 CI，再打 tag 与创建 GitHub release 触发发布。

package/editing-history/archived/2026-06-04-0000-release-0.12.39.md

@@ -1,4 +0,0 @@
-# 2026-06-04 release 0.12.39
-
-- 版本号：`Cargo.toml` / `package.json` → 0.12.39
-- 主要变更：check-md 入口 fail-fast、`app.main/main!` 注入、EDN 模块列表错误预览

package/editing-history/archived/2026-06-04-2230-release-0.12.40.md

@@ -1,5 +0,0 @@
-# 2026-06-04 release 0.12.40
-
-- 发布 `0.12.40`，包含 compiled executable runtime backfill 修复。
-- 该修复让 compiled `Fn`/`Macro` 首次 materialize 后回写 runtime-ready storage，避免重复 lookup 生成新函数 identity。
-- 直接收益是恢复 `memof` 这类按函数值做 cache key 的场景，`cr calcit.cirru` 再次通过既有测试。

package/editing-history/archived/2026-06-12-1525-weak-types-dots-format.md

@@ -1,15 +0,0 @@
-# 修改记录: cr analyze weak-types 路径打印格式优化使用点号 (2026-06-12)
-
-## 知识点与变动树
-
-1. **Weak-type 路径打印格式优化**:
-   - 原本 `cr analyze weak-types` 命令输出 AST 节点和声明模式中的位置时会使用大量的方括号 `[` 和 `]`，如 `code[3][1][6]`。
-   - 现将其重构并统一为标准点号 (`.`) 路径分隔法（如 `code.3.1.6`），以消除视觉冗余。
-
-2. **具体实现 & 多位置对齐**:
-   - `format_cirru_path`: 修改它的实现，将其内部的 `[idx]` 拼接机制替换成了 `.idx`，从而全局对齐了 Cirru 节点遍历的 dot 符号写法。
-   - `scan_schema_dynamic_annotation`: 内部处理 Fn 类型的索引时，把 `{path}.args[{idx}]` 和 `{path}.type-arg[{idx}]` 修改为点号连接的 `{path}.args.{idx}`、`{path}.type-arg.{idx}`，并同步修改了 `schema.args.{idx}` 语法签名位置。
-
-3. **测试与质量验证**:
-   - 执行 `cargo test --bin cr` 通过了全部 85 项内置和回归测试（无测试报错）。
-   - 实地重新构建 `cargo build --bin cr` 并对大规模项目 `termina/msg-buffer` 完美执行 `analyze weak-types` 分析，其输出完美显示为高清晰度的 `code.6.1.3` 及 `schema.args.0.item.item.value` 点号格式。

package/editing-history/archived/2026-06-13-1200-primitive_schema_tags.md

@@ -1,9 +0,0 @@
-# Calcit Type schema primitive tags support expansion
-
-## Timestamp: 202606131200
-
-## Modification Summary:
-- Expanded `PRIMITIVE_SCHEMA_TAGS` inside `/Users/chenyong/repo/calcit-lang/calcit/src/snapshot.rs` to include `"record"`, `"struct"`, `"enum"`, `"trait"`, `"impl"`.
-- This ensures schema annotations utilizing these tags (e.g., `:trait` or `:enum` in code entries) pass verification rather than raising an unrecognized primitive tag validation error.
-- Verified with the Calcit test suite which passed 223+85 integration and unit tests without error.
-- Updated `respo/alerts` annotations using these tags to enforce more precise typing rules in the codebase.

package/editing-history/archived/2026-06-20-1142-ts-declaration-d-mts.md

@@ -1,5 +0,0 @@
-- `tsconfig.json` 添加 `declaration: true`，使 `yarn compile` 生成 `.d.mts` 类型声明文件
-- `yarn compile` 后 `lib/` 中与 `.mjs` 一一对应生成 18 个 `.d.mts` 文件
-- `.npmignore` 不排除 `lib/`，这些声明文件在 npm publish 时会被包含
-- 对 hovenia-editor：移除手动 `calcit-procs.d.ts`，改用上游生成的 `.d.mts`
-- 本地验证：`cargo fmt` `cargo clippy` `yarn compile` `cargo test` `yarn check-all` 全部通过

package/editing-history/archived/2026-06-29-0117-upgrade-doc-snapshot-migration.md

@@ -1,2 +0,0 @@
-- docs/run/upgrade.md: added snapshot migration section — documents the transition from two-file setup (calcit.cirru snapshot + compact.cirru compact code) to single calcit.cirru with compact code only, no separate snapshot file needed
-- Recommended: delete old snapshot file, compact code saved directly in calcit.cirru for cr command to use directly

package/editing-history/archived/2026-06-29-calcit-cli.md

@@ -1,80 +0,0 @@
-# calcit.cli / cr exec 完整实现
-
-## 概要
-
-实现 `cr exec` + `calcit.cli/*` 内建函数（共 77 个），让 Agent 用 Cirru heredoc 调用常用 `cr query` / `edit` / `tree` / `analyze` / `docs` 能力，绕开 Shell 转义。RFC：`RFCs/06-29-cr-exec-cli-builtins-rfc.md`。
-
-## 架构
-
-- **运行时**：`src/bin/injection/mod.rs` 注册 handler；**单一 options map 参数**（arity 1）
-- **参数解析**：`calcit_cli_args.rs` — `resolve_cli_args`、类型 coercion、默认值填充、command echo
-- **参数规格**：`calcit_cli_specs.rs` — 每个函数的 `CliArgSpec` 列表（语义化键名）
-- **元数据**：`src/cirru/calcit-core.cirru` 的 `|calcit.cli` — schema 为 `(:args $ [] (:: :map :tag :dynamic))`
-- **同步**：`python3 scripts/gen_calcit_cli_core.py`（从 mod.rs + calcit_cli_specs.rs 生成）
-- **约束**：`calcit_cli*` 不得依赖 `cli_handlers`（保证 `cr-wasm` 可编译）
-
-### 调用约定（2026-06-29 重构）
-
-```cirru
-calcit.cli/peek-def $ {} (:file-path |calcit.cirru) (:target |app.main/main!)
-```
-
-- 唯一参数为 options map；键为 tag（`:file-path`、`:target`、`:lines` 等）
-- 省略的可选键由 Rust 侧默认值填充；非 quiet 模式下 stderr echo 展示完整调用（含默认值）
-- 位置参数已移除（breaking change）
-
-| 文件 | 职责 |
-|------|------|
-| `calcit_cli_args.rs` | map 解析、echo、docs_hint 生成 |
-| `calcit_cli_specs.rs` | 77 个函数的参数 spec 常量 |
-| `calcit_cli.rs` | 基础 query/write、snapshot 读写、`load_calcit_snapshot_with_deps` |
-| `calcit_cli_tree.rs` | AST 树变换（delete/insert/wrap/cp/mv…） |
-| `calcit_cli_extra.rs` | edit/config/cirru 工具、trigger-inc、semver bump |
-| `calcit_cli_program.rs` | 加载 snapshot+modules+core 并 preprocess（analyze/validate） |
-| `calcit_cli_analyze.rs` | call/effects/count + check-types/weak-types |
-| `calcit_cli_query.rs` | show-pkg/ns、list-defs-by-tag、validate-file、search-*、list-host-procs |
-| `calcit_cli_docs.rs` | docs-agents/read/sections |
-| `src/type_coverage.rs` | check-types / weak-types 共享逻辑（`cr analyze` 与 calcit.cli 共用） |
-
-## 分批功能（合并记录）
-
-### 第一批：树/定义/import 写操作（17）
-
-`tree-delete` `tree-insert` `tree-wrap` `tree-unwrap` `tree-raise` `tree-cp` `tree-mv` `rename-def` `rm-def` `mv-def` `split-def` `add-ns` `edit-doc` `edit-schema` `add-example` `rm-import` `show-error`
-
-要点：`tree-wrap` 用 `self` leaf；`position` 同 CLI（`|before` `|after` 等）。
-
-### 第二批：edit/config/cirru（20）
-
-`rm-ns` `set-imports` `format-file` `show-doc` `show-ns-doc` `list-tags` `set-tags` `rm-example` `clear-examples` `set-examples` `tree-replace-leaf` `tree-swap-*` `tree-batch-delete` `tree-rewrite` `set-config` `add/rm-module` `cirru-parse/format` `read-text-file`
-
-修复：`build_ns_code` 对齐 `(ns name (:require ...))` 嵌套结构。
-
-### 第三批：analyze / inc / docs 搜索（9）
-
-`trigger-inc` `cirru-parse-edn` `cirru-show-guide` `docs-search` `tree-replace-leaf-regex` `analyze-call-graph` `analyze-effects-graph` `analyze-count-calls`
-
-### 第四批：P0–P3（15）
-
-- **P0**：`show-pkg` `show-ns` `list-defs-by-tag` `validate-file` `bump-version` `edit-ns-doc`
-- **P1**：`search-project` `search-def-regex` `search-expr` `list-host-procs`
-- **P2**：`analyze-check-types` `analyze-weak-types`（依赖 `type_coverage` 提取）
-- **P3**：`docs-agents` `docs-read` `docs-sections`
-
-### Core 声明 + 预处理
-
-- core 可选参数 schema 用 `(:rest :dynamic)`，勿写 `:rest $ :dynamic`（EDN 解析失败）
-- 预处理：`is_registered_proc` 必须在 `has_def_code` 之前，避免 core 元数据 stub 被当作普通 def 编译（`preprocess/mod.rs`）
-
-## 验证
-
-```bash
-python3 scripts/gen_calcit_cli_core.py
-unset CARGO_TARGET_DIR && cargo fmt
-cargo clippy --all-targets -- -D warnings
-cargo test --bin cr
-./target/debug/cr calcit/test.cirru exec << 'EOF'
-calcit.cli/show-pkg $ {} (:file-path |calcit/test.cirru)
-calcit.cli/validate-file $ {} (:file-path |calcit/test.cirru)
-EOF
-```

package/editing-history/archived/2026-06-29-typed-calcit-cli-schemas.md

@@ -1,23 +0,0 @@
-# calcit.cli 选项 map 类型化 schema（Rust spec 直检）
-
-## 变更概要
-
-- 选项 spec 收敛到 `src/builtins/cli_options.rs`（Rust 单一来源），注册时写入 `RegisteredProcDescriptor.cli_options`。
-- preprocess 直接读 Rust spec 校验 options map，不再生成 defstruct / 不做 map→record 转换。
-- core 中 `:args` 仍由脚本生成 inline 类型 map（供 query/docs），校验走 Rust 而非 Calcit 类型系统。
-
-## 后续优化（Rust spec 直检）
-
-- preprocess 热路径改用 `registered_proc_cli_options()`，不再 clone 整个 `RegisteredProcDescriptor`。
-- `registered_proc_has_tag` 同样改为只读 map 查询。
-- `check_cli_options_map` 与 `resolve_cli_args` 共用 `collect_validation_errors`，preprocess 侧用引用收集 map 条目，避免多余 clone。
-- Registered 调用检查复用已有的 `processed_args`，去掉重复 `ys.drop_left()` 和 `alias` clone。
-
-## 验证案例（cr eval）
-
-| 案例 | 结果 |
-|------|------|
-| `:file-pth` 拼写错误 | `W_CLI_OPTION_UNKNOWN_KEY` |
-| 缺少 `:file-path` | `W_CLI_OPTION_MISSING_REQUIRED` |
-| `:lines \|bad` 类型错误 | `W_CLI_OPTION_TYPE_MISMATCH` |
-| 正确调用 | Check passed |

package/editing-history/archived/20260630-duplication-analysis.md

@@ -1,116 +0,0 @@
-# calcit.cli 与 CLI handlers 重复代码分析与重构方案
-
-时间: 2026-06-30
-作者: AI Agent
-
-## 现状
-
-### 两套独立实现
-
-| 方面 | `injection/calcit_cli*.rs` | `cli_handlers/*.rs` |
-|------|---------------------------|---------------------|
-| 代码量 | ~2714 行 | ~5967 行 |
-| 入口 | `fn(xs: Vec<Calcit>, _: &CallStackList) -> Result<Calcit, CalcitErr>` | `fn(opts: &SpecificCommandStruct, snapshot_file: &str) -> Result<(), String>` |
-| 参数解析 | `resolve_cli_args()` → `ResolvedCliArgs` (从 Calcit Map 中提取) | argh 自动解析 CLI 参数到结构体 |
-| 输出 | `Calcit::Str(...)` 返回给 Calcit 运行时 | `println!()` 直接输出 |
-| 快照加载 | `load_calcit_snapshot()` | `load_snapshot()` |
-| 快照保存 | `save_calcit_snapshot()` | `save_snapshot()` |
-
-### 完全重复的辅助函数
-
-| 函数 | injection/ 位置 | cli_handlers/ 位置 |
-|------|----------------|-------------------|
-| load_snapshot | calcit_cli.rs:1155 | edit.rs:101 |
-| save_snapshot | calcit_cli.rs:1217 | edit.rs:109 |
-| parse_path | calcit_cli.rs:933 | common.rs:182 |
-| navigate_to_node | calcit_cli.rs:905 | edit.rs:1267 |
-| parse_target | calcit_cli_args.rs (复用 cli_options) | edit.rs:22 |
-| check_ns_editable | calcit_cli.rs:1033 | edit.rs:114 |
-| apply_operation_at_path | calcit_cli_tree.rs | edit.rs:1152 |
-| process_node_with_references | calcit_cli_tree.rs | edit.rs:1290 |
-
-## 推荐的桥接方案
-
-### 方案: 提取共享核心 + 让 calcit.cli 代理到 cli_handlers
-
-不直接让 `calcit.cli` procs 调用 `cli_handlers`（因为接口类型不同），而是:
-
-1. **将核心业务逻辑（load → modify → save）提取到共享函数**，放在 `snapshot.rs` 或新建 `src/snapshot_ops.rs`
-2. **`cli_handlers` 调用共享函数**
-3. **`calcit.cli` 内部转发到共享函数**，而不是自己再实现一遍
-
-### 关键接口对齐
-
-calcit.cli proc 的处理流程:
-```
-Vec<Calcit> → resolve_cli_args() → ResolvedCliArgs → 提取参数 → 业务逻辑 → Calcit
-```
-
-CLI handler 的处理流程:
-```
-CLI struct → 提取参数 → 业务逻辑 → println!
-```
-
-共同点: 都需要 `(file_path, target, path, code)` 等参数, 都调用 `load_snapshot` / `save_snapshot` / `navigate_to_path` / `apply_operation_at_path`
-
-### 具体步骤
-
-1. 把 `load_snapshot`, `save_snapshot`, `navigate_to_path`, `parse_path`, `check_ns_editable`, `apply_operation_at_path`, `process_node_with_references` 等辅助函数统一放到 `src/snapshot_ops.rs` (或 `src/bin/cli_handlers/ops.rs`)
-2. 把每个业务操作（如 tree-replace、show-def、list-defs）提取为纯函数:
-   ```rust
-   pub fn op_tree_replace(snapshot: &mut Snapshot, ns: &str, def: &str, path: &[usize], new_node: &Cirru) -> Result<(), String>
-   pub fn op_show_def(snapshot: &Snapshot, ns: &str, def: &str) -> Result<String, String>
-   ```
-3. `calcit.cli` 的每个 proc handler 变成薄薄的代理层:
-   ```rust
-   pub fn tree_replace(xs: Vec<Calcit>, _cs: &CallStackList) -> Result<Calcit, CalcitErr> {
-     let args = resolve_cli_args("calcit.cli/tree-replace", &xs, TREE_REPLACE)?;
-     let mut snapshot = load_snapshot(&args.file_path()?)?;
-     let (ns, def) = args.target("target")?;
-     let path = parse_path(&args.string("path")?, false)?;
-     let code = args.cirru_quote("code")?;
-     ops::op_tree_replace(&mut snapshot, &ns, &def, &path, &code)?;
-     save_snapshot(&snapshot, &args.file_path()?)?;
-     Ok(Calcit::Str(Arc::from("replaced")))
-   }
-   ```
-4. CLI handlers 也变成薄代理:
-   ```rust
-   fn handle_replace(opts: &TreeReplaceCommand, snapshot_file: &str) -> Result<(), String> {
-     let (ns, def) = parse_target(&opts.target)?;
-     let path = parse_path(&opts.path)?;
-     let code = parse_input_to_cirru(...)?;
-     let mut snapshot = load_snapshot(snapshot_file)?;
-     ops::op_tree_replace(&mut snapshot, ns, def, &path, &code)?;
-     save_snapshot(&snapshot, snapshot_file)?;
-     // print preview...
-   }
-   ```
-
-### 收益
-- 消除 ~2000 行重复代码
-- 修复 bug 只需改一处
-- 新功能只需写一次共享逻辑
-
-### 风险
-- 大规模重构需要充分测试
-- 需要迁移 `calcit_cli_tree.rs` 中的复杂逻辑（rewrite with references）
-- `calcit.cli` 的 `CalcitErr` 错误类型和 `cli_handlers` 的 `String` 错误类型需要对齐
-
-## 代码规模统计
-
-```
-src/bin/injection/
-  calcit_cli.rs         1297 行  ← 需要拆解: 辅助函数 + proc handlers
-  calcit_cli_extra.rs    846 行  ← 同上
-  calcit_cli_tree.rs     232 行  ← 纯辅助函数, 可整体移出
-  calcit_cli_args.rs     147 行  ← 桥接层, 保留
-  calcit_cli_specs.rs    192 行  ← 参数规格定义, 保留
-  mod.rs                 ~60 行  ← 注册代码, 保留
-
-src/bin/cli_handlers/
-  edit.rs              2026 行  ← 辅助函数 + handler 逻辑
-  tree.rs              1433 行  ← handler 逻辑
-  query.rs             2135 行  ← handler 逻辑
-  common.rs             373 行  ← 工具函数
-```