@calcit/procs 0.12.11 → 0.12.13

package/editing-history/2026-0225-1234-watch-mode-default-once.md

@@ -2,5 +2,4 @@
 
 - Unified run mode behavior for `cr`, `cr js`, and `cr ir`: default to once.
 - Added explicit `-w/--watch` switches for top-level direct run and `ir` subcommand.
-- Kept `-1/--once` for backward compatibility.
 - Updated watch-mode related docs in `Agents.md` and `docs/CalcitAgent.md`.

package/editing-history/2026-0320-0116-json-builtins-and-runtime-docs.md

@@ -3,17 +3,20 @@
 This commit moves JSON parsing and serialization into Calcit builtins and aligns the surrounding runtime/docs/tooling updates needed to ship it cleanly.
 
 1. Added builtin JSON runtime functions
+
 - Introduced `json-parse`, `json-stringify`, and `json-pretty` in Rust builtin dispatch and JS runtime exports.
 - Added fast arity/type checks on exposed runtime entry points.
 - Normalized integer-valued numbers to encode as JSON integers in Rust, matching JS output.
 - Added native tests and Calcit-level coverage for parse/stringify/pretty behavior and error paths.
 
 2. Updated core docs and runtime placeholder naming
+
 - Added `calcit.core` docs/examples for the JSON runtime functions.
 - Renamed the runtime placeholder spelling from `runtime-inplementation` to `runtime-implementation` across core snapshot metadata and Rust handling.
 - Preserved an explicit `cr <snapshot-file> edit format` example in `docs/CalcitAgent.md`.
 
 3. Snapshot formatting workflow
+
 - Re-ran `cr edit format` against the touched Cirru snapshot files:
   - `src/cirru/calcit-core.cirru`
   - `calcit/test.cirru`

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

@@ -0,0 +1,72 @@
+# Query 搜索结果分层、降噪与路径/预览优化（合并记录）
+
+## 变更概述
+
+- 初始实现：为 `cr query` 搜索类命令引入结果分层展示（详情窗口 + 压缩输出）。
+- 参数命名收敛：将 `--prefer` 直接改为 `--detail-offset`（不保留兼容别名）。
+- 输出降噪：删除冗长提示，保留定位核心信息（定义、路径、命中片段）。
+- 路径统一：搜索输出与 `--start-path` 示例统一为点号分隔；解析层仅接受点号输入。
+- 详情窗口进一步从 5 缩小为 3，并在窗口内增加“所在表达式 + 父表达式”预览（可省略复杂父表达式）。
+
+## 覆盖命令
+
+- `cr query find`
+- `cr query usages`
+- `cr query search`
+- `cr query search-expr`
+
+## 关键实现
+
+- `src/cli_args.rs`
+  - 参数字段统一为 `detail_offset`。
+  - 参数统一为 `#[argh(option, long = "detail-offset", default = "0")]`。
+  - 参数说明更新为“3 detailed items”。
+  - `query search --start-path` 示例更新为点号格式 `2.1.0`。
+
+- `src/bin/cli_handlers/query.rs`
+  - 结果窗口逻辑：
+    - `DETAILED_RESULTS_WINDOW = 3`
+    - `detailed_window(detail_offset, total)`
+    - `in_detail_window(index, total, detail_offset)`
+    - `print_detail_window_hint(...)`
+  - 搜索结果降噪：
+    - `search/search-expr` 按命中数排序定义（高命中优先）。
+    - 详情行输出为 `[path] <preview>`；窗口外仅输出压缩条数（`N matches compressed outside window`）。
+    - 移除 `Next steps`/批量替换等长提示块。
+  - 预览增强：
+    - 新增 `preview_node_oneline(...)` 并修复叶子节点空预览问题。
+    - 新增 `path_parent(...)`、`get_node_at_path(...)`、`count_nodes_limited(...)`、`can_show_parent_preview(...)`、`expression_and_parent_preview(...)`。
+    - 最终形态改为“单行预览”：优先显示父节点预览；无父节点时回退到当前表达式（避免重复展示两遍）。
+
+  - Tips 与 exact 语义修正：
+    - `--exact` 高优先级提示文案统一为英文：`Many matches (N); add --exact to show exact matches only`。
+    - 仅在 contains 模式且命中数 `> 10` 时展示该提示；`--exact` 模式不再显示冗余提示。
+    - 修复 exact 模式下的误导性高亮：只在 token 边界高亮，避免将 `states` 中的 `state` 误标为命中。
+
+  - 命名收敛：将旧命名 `prefer` 在函数参数/调用链/提示文案中统一改为 `detail_offset` / `detail-offset`。
+
+- `src/bin/cli_handlers/common.rs`
+  - `parse_path(...)` 改为仅接受点号分隔；逗号输入报错并提示改用点号。
+
+## 降噪策略
+
+- 深度嵌套（路径过深）或分支复杂（节点过大）时，父表达式预览自动省略。
+- 详细窗口外仍然输出压缩占位，不展开上下文。
+
+## 验证
+
+- `cargo check --bin cr` 通过。
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query find --help`
+  - 可见 `--detail-offset` 参数。
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.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/compact.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`
+  - 精确命中不再把 `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/compact.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

@@ -0,0 +1,71 @@
+# Command Echo 主导的工具输出收敛与 tree replace 差异摘要
+
+## 变更概述
+
+- 将 `cr` 的命令回显进一步固定为工具主语境：前置、单行、语义化参数展示。
+- 为工具型命令引入更安静的 runtime 输出模式，避免版本、模块目录、模块加载、平台 API 注册等噪音干扰结果读取。
+- 大范围清理 `docs/query/tree` 正文里对 `target/path/pattern/entry/deps` 的重复回显，统一交给 command echo 表达。
+- 修正 `docs/CalcitAgent.md` 中示意性 Cirru 代码块的检查模式，避免 `check-md` 将结构示例误判为 runnable 程序。
+- 单独重构 `tree replace` 输出：从“Preview + From/To”双份重复，改成“Changed node + Containing expression”的单次差异摘要。
+
+## 关键实现
+
+- `src/bin/cr.rs`
+  - 在启用 command echo 时同步启用 `calcit::set_quiet_tool_output(true)`。
+  - 屏蔽工具模式下的运行环境提示：
+    - `calcit version`
+    - `module folder`
+    - `stack trace disabled`
+    - `running entry`
+
+- `src/lib.rs`
+  - 新增全局 quiet flag：
+    - `set_quiet_tool_output(...)`
+    - `quiet_tool_output()`
+  - `load_module(...)` 在工具模式下不再打印 `loading: ...`。
+
+- `src/bin/injection/mod.rs`
+  - `inject_platform_apis()` 在工具模式下不再打印 `registered platform APIs`。
+
+- `src/bin/cli_handlers/docs.rs`
+  - `docs check-md` 不再重复回显 `entry/deps`。
+  - 移除只服务旧回显的路径展示 helper。
+
+- `src/bin/cli_handlers/query.rs`
+  - 删除 `query def/peek/schema/examples/usages` 中重复的 target 标题。
+  - 删除 `query search/search-expr` 中重复的 pattern/filter/entry/start-path 摘要。
+  - `query find` 摘要从“重复 symbol”收敛为纯结果计数。
+
+- `src/bin/cli_handlers/tree.rs`
+  - 删除 `tree show` 与多类 tree 写操作中的冗余 follow-up 命令提示。
+  - 删除成功文案里重复的 `path/target/pattern` 回显。
+  - `tree replace` 改为：
+    - `✓ Replaced node`
+    - `Changed node` 下单次展示 `Before/After`
+    - 非 root path 额外展示 `Containing expression`，帮助快速看出修改落点。
+
+- `docs/CalcitAgent.md`
+  - 将示意性代码块改成 `cirru.no-check`，避免 `docs check-md` 因不存在的符号或非独立程序片段失败。
+
+## 输出策略结论
+
+- 输入参数语境：由 `Command: ...` 统一承担。
+- 正文输出：只保留结果、差异、结构上下文、或真正新增的信息。
+- 不再在正文里重复打印 command echo 已经覆盖的 target/path/pattern/entry/deps。
+
+## 验证摘要
+
+- `cargo fmt`
+- `cargo run --bin cr -- calcit/test.cirru analyze js-escape 'demo?'`
+- `cargo run --bin cr -- calcit/test.cirru analyze js-unescape 'demo_$q_'`
+- `cargo run --bin cr -- calcit/test.cirru query ns app.main`
+- `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 输出形态
+
+## 经验
+
+- command echo 一旦语义化，就应把正文里的“参数再描述一遍”系统性删掉，否则会让工具输出看起来像教程而不是结果。
+- tree 类命令相比简单成功提示，更需要“差异摘要 + 所在表达式”，这样既不冗余，也能快速判断改动是否落在预期结构。

package/editing-history/2026-0326-2013-docs-frontmatter-and-module-search.md

@@ -0,0 +1,58 @@
+# Docs frontmatter 与模块检索整理
+
+## 变更概述
+
+- 为 `cr docs search/read/read-lines` 增加 `scope/module` 维度，支持核心文档、模块文档和跨域检索。
+- 为 core docs 建立统一的 frontmatter 规范，并补充 `title/scope/kind/category/aliases/entry_for` 元数据。
+- 将 `docs` 检索逻辑从纯文件名匹配升级为结合 frontmatter、路径、标题与条目词的综合解析与排序。
+- 给文档系统补充规范页与验证页，方便后续扩展 `cr docs` 时保持行为稳定。
+- 调整 Cirru 校验错误提示，让“其实是字符串”的场景给出更直接的修复建议。
+
+## 关键实现
+
+- `src/cli_args.rs`
+  - 为 `docs search`、`docs read`、`docs read-lines` 增加 `--scope`、`--module` 参数。
+
+- `src/bin/cli_handlers/command_echo.rs`
+  - 同步回显新增 docs 参数，确保工具模式下能看到完整检索上下文。
+
+- `src/bin/cli_handlers/docs.rs`
+  - 引入 `GuideDocFrontmatter`、`GuideDocScope`、`DocsSearchScope`。
+  - 支持解析 Markdown frontmatter，并在加载时校验 `category`。
+  - 支持从 core docs 与 `~/.config/calcit/modules/<module>/docs/` 同时加载文档。
+  - 统一 `search/read/read-lines` 的查询解析逻辑，允许通过文件名、路径片段、标题、`aliases`、`entry_for` 命中目标。
+  - 增加更偏向 guide/reference 页的排序策略，减少 spec/索引页抢占结果。
+  - 抽出 `match_score`、`accumulate_match_score`、`parse_guide_doc` 等辅助函数，压缩主文件重复逻辑。
+
+- `src/bin/cli_handlers/docs_tests.rs`
+  - 将 docs 相关测试从 `docs.rs` 拆出，单独维护解析、排序、模块加载与校验场景。
+
+- `docs/docs-indexing.md`
+  - 固化 frontmatter 字段、分类注册表、scope 布局与 authoring 约束。
+
+- `docs/docs-validation.md`
+  - 记录 `cr docs` 的可执行回归命令，覆盖 `search/read/read-lines` 与 module scope。
+
+- `src/bin/cli_handlers/cirru_validator.rs`
+  - 当 token 更像“应写成字符串的文本”时，提示使用 `|text` 或 `"|text with spaces"`，减少样式值与括号文本误写的排查成本。
+
+## 文档整理原则
+
+- `category` 只允许稳定注册值，避免搜索元数据失控膨胀。
+- `aliases` 主要承接用户会直接输入的别名或术语，`entry_for` 主要承接命令/API/任务入口。
+- `Agents.md` 与普通 docs 页复用同一套 frontmatter 机制，但渲染时默认隐藏元数据正文。
+- 模块领域知识保留在模块 docs 中，Calcit core 只提供通用索引与加载能力，不内置 Respo 特殊语义。
+
+## 验证
+
+- `cargo fmt`
+- `cargo test docs --bin cr`
+- 手动验证：
+  - `cargo run --bin cr -- docs search target-replace`
+  - `cargo run --bin cr -- docs search 'cr eval'`
+  - `cargo run --bin cr -- docs read polymorphism.md`
+
+## 后续经验
+
+- docs 元数据一旦进入 CLI 行为，就应该配套规范页与验证页，否则后续加字段很容易出现“文档能写、检索却不稳定”的分叉。
+- 模块文档检索要尽量和 core docs 走同一套 resolver，这样使用者不需要记两套命令心智模型。

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.11",
+    "version": "0.12.13",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.11",
+  "version": "0.12.13",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",