@calcit/procs 0.12.55 → 0.12.57

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 行  ← 工具函数
-```