@calcit/procs 0.12.33 → 0.12.35

package/README.md

@@ -54,23 +54,24 @@ cr eval 'range 100'
 cr eval 'thread-first 100 range (map $ \ * % %)'
 ```
 
-Run with a [compact.cirru](https://github.com/calcit-lang/lilac/blob/main/compact.cirru):
+Run with a runtime snapshot such as [calcit.cirru](https://github.com/calcit-lang/lilac/blob/main/compact.cirru) (legacy filename: `compact.cirru`):
 
 ```bash
-cr compact.cirru # run once (default)
+cr calcit.cirru # run once (default)
+cr compact.cirru # legacy filename still works
 
-cr # by default, it picks `compact.cirru`
+cr # by default, it picks `calcit.cirru`, then falls back to `compact.cirru`
 
 cr -w # watch mode (explicit flag required)
 ```
 
-By default Calcit reads `:init-fn` and `:reload-fn` inside `compact.cirru` configs. You may also specify functions,
+By default Calcit reads `:init-fn` and `:reload-fn` inside `calcit.cirru` configs (falling back to `compact.cirru`). You may also specify functions,
 
 ```bash
 cr --init-fn='app.main/main!' --reload-fn='app.main/reload!'
 ```
 
-and even configure `:entries` in `compact.cirru`:
+and even configure `:entries` in `calcit.cirru`:
 
 ```bash
 cr --entry server
@@ -81,7 +82,7 @@ cr --entry server
 It compiles to JavaScript and runs in consistet semantics. However it might require a lot of JavaScript interop.
 
 ```bash
-cr js # compile to js, also picks `compact.cirru` by default
+cr js # compile to js, also picks `calcit.cirru` by default
 cr js --emit-path=out/ # compile to js and save in `out/`
 ```
 
@@ -95,7 +96,7 @@ main_$x_(); // which corresponds to `main!` function in calcit
 ### Calcit Editor & Bundler
 
 Install [Calcit Editor](https://github.com/calcit-lang/editor) and run `ct` to launch editor server,
-which writes `compact.cirru` and `.compact-inc.cirru` on saving. Try launching example by cloning [Calcit Workflow](https://github.com/calcit-lang/calcit-workflow).
+which writes `calcit.cirru` and `.compact-inc.cirru` on saving. Legacy `compact.cirru` remains compatible. Try launching example by cloning [Calcit Workflow](https://github.com/calcit-lang/calcit-workflow).
 
 Read more in [Minimal Calcit](https://github.com/calcit-lang/minimal-calcit/blob/main/README.md) to learn how to code Calcit with a plain text editor.
 
@@ -116,10 +117,10 @@ When using the Calcit Runner through MCP:
 
 1. **Start Runner**: Use `start_calcit_runner` to launch the background process. This automatically:
    - Creates a `.calcit-tmp/` directory
-   - Copies the current `compact.cirru` as a temporary baseline
+   - Copies the current runtime snapshot (`calcit.cirru`, or legacy `compact.cirru`) as a temporary baseline
 
 2. **Generate Incremental Updates**: After making changes to your code, use `generate_calcit_incremental` to:
-   - Compare current `compact.cirru` with the temporary baseline
+   - Compare current runtime snapshot with the temporary baseline
    - Generate a `.compact-inc.cirru` file with only the changes
    - Apply incremental updates to the running process
 
@@ -143,17 +144,17 @@ Run `caps` to download. Sources are downloaded into `~/.config/calcit/modules/`.
 
 `:calcit-version` helps in check version, and provides hints in [CI](https://github.com/calcit-lang/setup-cr) environment.
 
-To load modules, use `:modules` configuration and `compact.cirru`(which normally generated from `calcit.cirru`):
+To load modules, use `:modules` configuration and the runtime snapshot file `calcit.cirru` (legacy: `compact.cirru`):
 
 ```cirru
 :configs $ {}
-  :modules $ [] |memof/compact.cirru |lilac/
+  :modules $ [] |memof/calcit.cirru |lilac/
 ```
 
 Paths defined in `:modules` field are just loaded as files from `~/.config/calcit/modules/`,
-i.e. `~/.config/calcit/modules/memof/compact.cirru`.
+i.e. `~/.config/calcit/modules/memof/calcit.cirru`.
 
-Modules that ends with `/`s are automatically suffixed `compact.cirru` since it's the default entry.
+Modules that ends with `/`s are automatically suffixed `calcit.cirru`, and still fall back to `compact.cirru` for compatibility.
 
 ### Development
 
@@ -169,13 +170,13 @@ cargo run --bin cr -- calcit/test.cirru js && yarn try-js
 # run snippet
 cargo run --bin cr -- eval 'range 100'
 
-cr compact.cirru ir # compiles intermediate representation into program-ir.cirru
+cr calcit.cirru ir # compiles intermediate representation into program-ir.cirru
 
 cr-wasm calcit/test-wasm.cirru # compile standalone wasm target to js-out/program.wasm
 ```
 
 - [Cirru Parser](https://github.com/Cirru/parser.rs) for indentation-based syntax parsing.
-- [Cirru EDN](https://github.com/Cirru/cirru-edn.rs) for `compact.cirru` file parsing.
+- [Cirru EDN](https://github.com/Cirru/cirru-edn.rs) for runtime snapshot file parsing (`calcit.cirru` / legacy `compact.cirru`).
 - [Ternary Tree](https://github.com/calcit-lang/ternary-tree.rs) for immutable list data structure.
 
 Other tools:

package/editing-history/2026-0223-2321-ns-imports-code-fixes.md

@@ -2,7 +2,7 @@
 
 ## 背景
 
-通过在 `demos/compact.cirru` 上逐一测试 `cr edit` 的 namespace 相关子命令，发现三处导致 Agent 频繁用错的根本原因。
+通过在 `demos/calcit.cirru` 上逐一测试 `cr edit` 的 namespace 相关子命令，发现三处导致 Agent 频繁用错的根本原因。
 
 ## 发现的 Bug
 

package/editing-history/2026-0227-1958-tree-rewrite-command-and-reference-model.md

@@ -12,7 +12,7 @@
 - `tree` handler：将 `handle_structural` 更名为 `handle_rewrite`，并更新输出提示与错误信息。
 - 结构引用处理：在 `tree` 中统一使用 `parse_with_references` + `process_node_with_references`。
 - 文档更新：`docs/CalcitAgent.md` 与 `Agents.md` 全部改用 `tree rewrite` 与 `--with` 示例。
-- 真实命令验证（基于 `demos/compact.cirru`）：
+- 真实命令验证（基于 `demos/calcit.cirru`）：
   - `tree replace` 可执行普通替换；
   - `tree rewrite` 无 `--with` 会按预期报错；
   - `tree rewrite` 携带 `--with` 可按预期执行。

package/editing-history/2026-0304-1548-impl-new-dot-method-input-and-doc-hints.md

@@ -27,7 +27,7 @@
 - `yarn compile`
 - `cargo test`
 - `yarn check-all`
-- `cargo run --bin cr -- demos/compact.cirru query examples 'calcit.core/&impl::new'`
-- `cargo run --bin cr -- demos/compact.cirru query examples 'calcit.core/&impl:get'`
+- `cargo run --bin cr -- demos/calcit.cirru query examples 'calcit.core/&impl::new'`
+- `cargo run --bin cr -- demos/calcit.cirru query examples 'calcit.core/&impl:get'`
 
 以上在本次改动后均通过。

package/editing-history/2026-0306-1552-core-schema-and-hintfn-migration.md

@@ -36,7 +36,7 @@
 
 每批次均执行：
 
-- `cargo run --bin cr -- demos/compact.cirru edit format`
+- `cargo run --bin cr -- demos/calcit.cirru edit format`
 - `yarn check-all`
 
 结果均通过（尾部稳定为 `... and 24 files not changed.`）。

package/editing-history/2026-0307-1302-calcit-agent-docs-update.md

@@ -8,7 +8,7 @@
 
 ```
 - `cr --no-tips <subcommand> ...` - 隐藏所有编辑/查询命令输出的 "Tips:" 提示行（适合脚本/Agent 使用）
-  - 示例：`cr --no-tips demos/compact.cirru query def calcit.core/foldl`
+  - 示例：`cr --no-tips demos/calcit.cirru query def calcit.core/foldl`
 ```
 
 **背景**：`aa21b3a` 提交新增了 `--no-tips` 全局开关（`TIPS_SUPPRESSED: AtomicBool`，通过 `suppress_tips()` 设置），文档中缺少记录。

package/editing-history/2026-0320-1229-query-window-3-with-parent-preview.md

@@ -56,17 +56,17 @@
 ## 验证
 
 - `cargo check --bin cr` 通过。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query find --help`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query find --help`
   - 可见 `--detail-offset` 参数。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search --help`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search --help`
   - `--start-path` 示例为点号格式。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 5`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 5`
   - 输出降噪，路径为点号，窗口外压缩。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 0`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 0`
   - 详情窗口为 `[0, 3)`，每条命中仅展示一行（优先父节点预览）。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
   - 精确命中不再把 `states` 视觉误判为 `state`；且不显示“add --exact”提示。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search-expr state -f respo.app.comp.todolist/comp-todolist --detail-offset 0`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search-expr state -f respo.app.comp.todolist/comp-todolist --detail-offset 0`
   - 输出样式一致（单行预览）。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search-expr state -f respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search-expr state -f respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
   - 结果为 `No matches found`，符合结构精确匹配预期。

package/editing-history/2026-0323-1137-command-echo-tool-output-cleanup.md

@@ -62,8 +62,8 @@
 - `cargo run --bin cr -- calcit/test.cirru query find render`
 - `cargo run --bin cr -- calcit/test.cirru tree show app.main/test-json -p ''`
 - `cargo run --bin cr -- calcit/test.cirru docs search chunk -f agent-advanced.md`
-- `cargo run --bin cr -- demos/compact.cirru docs check-md docs/CalcitAgent.md`
-- `cargo run --bin cr -- /tmp/calcit-cli-demo/compact.cirru tree replace ...` 多次人工检查 replace 输出形态
+- `cargo run --bin cr -- demos/calcit.cirru docs check-md docs/CalcitAgent.md`
+- `cargo run --bin cr -- /tmp/calcit-cli-demo/calcit.cirru tree replace ...` 多次人工检查 replace 输出形态
 
 ## 经验
 

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

@@ -2,7 +2,7 @@
 
 ## 背景
 
-PR `snapshot-format` 新增了空 `configs.version` 的回归测试，但 GitHub Actions 上加载 `compact.cirru` 时，`(:version ||)` 会解析成字符串 `"|"`，没有命中原先仅检查空白字符串的校验。
+PR `snapshot-format` 新增了空 `configs.version` 的回归测试，但 GitHub Actions 上加载运行时快照文件（`calcit.cirru` / legacy `compact.cirru`）时，`(:version ||)` 会解析成字符串 `"|"`，没有命中原先仅检查空白字符串的校验。
 
 ## 知识点
 

package/editing-history/202604182041-cr-wasm-split-and-runtime-stability.md

@@ -11,7 +11,7 @@
 
 ## 经验与注意事项
 
-- 对 `compact.cirru` 的修改必须通过 `cr edit`/`cr tree` 完成，避免文本直接编辑破坏结构。
+- 对运行时快照文件（`calcit.cirru` / legacy `compact.cirru`）的修改必须通过 `cr edit`/`cr tree` 完成，避免文本直接编辑破坏结构。
 - 在多项目联动（calcit + recollect）场景下，发布前验证至少应覆盖：
   - calcit: `yarn check-all`
   - recollect: `yarn test:cr`、`yarn test:js`、`yarn test:wasm`

package/lib/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.33",
+    "version": "0.12.35",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
-        "@types/node": "^25.0.9",
-        "typescript": "^6.0.2"
+        "@types/node": "^25.7.0",
+        "typescript": "^6.0.3"
     },
     "scripts": {
         "compile": "rm -rf lib && tsc",

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.33",
+  "version": "0.12.35",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
-    "@types/node": "^25.0.9",
-    "typescript": "^6.0.2"
+    "@types/node": "^25.7.0",
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "compile": "rm -rf lib && tsc",

package/rfc/03-05-function-schema-dual-track-rfc.md

@@ -105,13 +105,13 @@
 主示例：
 
 ```bash
-cr demos/compact.cirru cirru parse-edn "(:: :fn ({} (:generics ([] 'T 'U)) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U)) (:where ([] (:: 'Eq 'T)))))"
+cr demos/calcit.cirru cirru parse-edn "(:: :fn ({} (:generics ([] 'T 'U)) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U)) (:where ([] (:: 'Eq 'T)))))"
 ```
 
 运行时数据验证：
 
 ```bash
-cr demos/compact.cirru eval "let ((schema (:: :fn ({} (:generics ([] 'T 'U)) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U)) (:where ([] (:: 'Eq 'T))))))) (println schema) (println (type-of schema)) , schema"
+cr demos/calcit.cirru eval "let ((schema (:: :fn ({} (:generics ([] 'T 'U)) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U)) (:where ([] (:: 'Eq 'T))))))) (println schema) (println (type-of schema)) , schema"
 ```
 
 ## 顶层定义与局部定义的分工

package/rfcs/05-12-program-diff-rfc.md

@@ -0,0 +1,204 @@
+# RFC: `cr analyze program-diff <GIT REF>`
+
+状态：Draft
+日期：2026-05-12
+
+---
+
+## 1. 概要
+
+新增命令：
+
+- `cr analyze program-diff <GIT REF>`
+
+该命令从 Git 中读取指定版本的完整运行时快照文件（默认沿用当前 `cr` 的输入文件路径，优先 `calcit.cirru`，兼容旧文件名 `compact.cirru`），确保**历史版本**与**当前工作区版本**都能被正确解析为 Calcit snapshot，然后做**结构化 diff**。
+
+输出目标不是纯文本行 diff，而是面向程序结构的树形 diff：
+
+- 顶层展示 `package/configs/entries/files` 等结构；
+- 文件层展示 `ns/defs`；
+- definition 层展示 `doc/schema/examples/code`；
+- `code/examples/ns.code` 内部继续深入到 Cirru 表达式节点级别；
+- 无变化分支允许灰色折叠；
+- 变更分支默认展开；
+- 增加、删除、修改分别用不同符号和颜色表示。
+
+## 2. 动机
+
+当前针对运行时快照文件的版本对比主要依赖 Git 行 diff，但它有几个明显问题：
+
+1. **对结构不友好**：`calcit.cirru`（兼容旧文件名 `compact.cirru`）是机器生成的 snapshot，行 diff 容易受格式、字段顺序和长表达式影响；
+2. **对表达式内部变化不友好**：definition 代码改动往往是局部子树变化，行 diff 很难快速看出 AST 层面的增删改；
+3. **对 LLM / CLI 阅读不友好**：调用 `git diff` 后很难一眼区分“只是某个 def 变了”还是“整个 namespace 被搬动了”；
+4. **缺少 parse guard**：历史版本文件如果本身损坏，应该先明确报解析失败，而不是直接进入错误 diff。
+
+因此需要一个基于 Calcit 自身 snapshot/Cirru 结构的 diff 命令。
+
+## 3. 命令定义
+
+```/dev/null/rfc.txt#L1-2
+cr analyze program-diff <GIT REF>
+```
+
+语义：
+
+- `<GIT REF>` 可以是 `HEAD~1`、tag、branch、commit SHA 等；
+- 当前侧使用 `cr` 输入路径（默认优先 `calcit.cirru`，兼容旧文件名 `compact.cirru`）；
+- 历史侧使用 `git show <ref>:<repo-relative-input-path>` 读取文件内容；
+- 两边都必须先经过：
+  1. `cirru_edn::parse`
+  2. `snapshot::load_snapshot_data`
+- 任一侧失败都直接返回错误并停止 diff。
+
+## 4. 输出设计
+
+### 4.1 总体结构
+
+输出分 2 段：
+
+1. Summary
+2. Tree Diff
+
+Summary 示例：
+
+```/dev/null/rfc.txt#L1-6
+# Program Diff
+- ref: HEAD~1
+- file: calcit.cirru
+- parsed: ok / ok
+- changes: ~12 +3 -1
+```
+
+### 4.2 树形 diff 约定
+
+参考 `cr analyze call-graph` 的树形展示风格，继续使用：
+
+- `├──`
+- `└──`
+- `│`
+
+在此基础上增加状态符号：
+
+- `=` unchanged（灰色）
+- `~` modified（黄色）
+- `+` added（绿色）
+- `-` removed（红色）
+
+### 4.3 折叠策略
+
+- `Unchanged` 子树默认只显示一行概要，并灰色折叠；
+- `Modified` / `Added` / `Removed` 子树默认展开；
+- root 总是展开；
+- 叶子节点直接显示 old/new 摘要。
+
+### 4.4 表达式内部 diff
+
+对于 `code/examples/ns.code` 内部的 `Cirru`：
+
+- 叶子变更显示 old/new；
+- list 节点按子节点序列做结构化比对；
+- 插入/删除节点要保留索引位置和节点摘要；
+- 同位置替换优先显示为 `modified`，而不是简单拆成 delete+add；
+- 整棵新增/删除表达式应继续展开其子结构。
+
+## 5. 范围
+
+本次只在 `calcit` 当前仓库内实现，不先抽到 `cirru_parser`：
+
+- 先满足 CLI 工作流；
+- diff 数据结构先放在当前项目中，便于快速迭代；
+- 后续如果算法稳定，再考虑抽取成 Cirru parser / edn 侧通用模块。
+
+## 6. 实现方案
+
+### 6.1 新模块
+
+新增库模块：
+
+- `src/program_diff.rs`
+
+职责：
+
+1. 读取当前 snapshot 文件；
+2. 从 git ref 读取历史 snapshot 文件；
+3. 校验两边都能 parse/load；
+4. 构建结构化 diff tree；
+5. 生成适合终端的彩色树形输出。
+
+### 6.2 CLI 接入
+
+- `src/cli_args.rs`
+  - 为 `AnalyzeSubcommand` 增加 `ProgramDiff`；
+- `src/bin/cr.rs`
+  - 将该命令作为 standalone analyze 命令优先处理；
+- `src/bin/cli_handlers/command_echo.rs`
+  - 增加 command echo 渲染；
+- `src/bin/cli_handlers/mod.rs`
+  - 导出 handler。
+
+### 6.3 Git 文件读取
+
+流程：
+
+1. 用 `git rev-parse --show-toplevel` 找 repo root；
+2. 将当前 `input` 解析成 repo-relative path；
+3. 用 `git show <ref>:<relative-path>` 读取历史内容；
+4. 若文件不存在、ref 不存在、或命令失败，则直接返回错误。
+
+### 6.4 Diff 层级
+
+优先按 snapshot 语义层比较：
+
+1. `package`
+2. `about`
+3. `configs`
+4. `entries`
+5. `files`
+6. `file.ns`
+7. `file.defs`
+8. `def.doc`
+9. `def.schema`
+10. `def.examples`
+11. `def.code`
+12. `Cirru` 子树
+
+这样可以避免直接把整个运行时快照文件当作匿名 EDN 树来比，输出会更稳定、更可读。
+
+### 6.5 Cirru 序列 diff
+
+list 内部子节点对比采用“带替换代价的序列对齐”策略：
+
+- 完全相等 => `match`
+- 不相等但对位更合理 => `replace`
+- 仅旧侧存在 => `remove`
+- 仅新侧存在 => `insert`
+
+这比单纯按索引逐位比较更适合表达式中间插入/删除节点的场景。
+
+## 7. 预期收益
+
+- 更适合 review `calcit.cirru`（兼容旧文件名 `compact.cirru`）的语义变化；
+- 更容易理解大型 definition 的局部 AST 改动；
+- 对 agent/LLM 更友好，能直接拿到层级化变化；
+- 为后续抽象成 Cirru diff 模块提供实现样本。
+
+## 8. 暂不处理
+
+本 RFC 本轮不覆盖：
+
+- 三方 merge；
+- patch 应用；
+- HTML/TUI 交互界面；
+- 抽取到 `cirru_parser` crate；
+- 和 `cr tree show` / `cr query def` 的统一 chunk/diff UI。
+
+## 9. 后续可能扩展
+
+后续可考虑继续增加：
+
+- `--format json`
+- `--no-color`
+- `--expand-all`
+- `--only <path-prefix>`
+- `--git-path <path>`（脱离当前 input）
+- 将 Cirru diff 算法下沉到 parser 层