Conversation
There was a problem hiding this comment.
Pull request overview
This pull request updates the Calcit language runtime and toolchain from version 0.10 to 0.11 (alpha 5). The update encompasses several major changes including package manager migration from Yarn 1 to Yarn 4, Node.js version upgrade, breaking API changes in the Calcit code, and significant documentation restructuring.
Changes:
- Upgrades Calcit runtime from 0.10.4 to 0.11.0-a5 and updates related dependencies (Respo, memof)
- Migrates package manager from Yarn 1 to Yarn 4 with new lockfile format and configuration
- Updates CI workflow to Node.js 24 with Corepack/Yarn 4 support
- Replaces
%::syntax withwith-classfunction calls across all plugin hooks (breaking change) - Restructures documentation by moving comprehensive guide to llms/Calcit.md
Reviewed changes
Copilot reviewed 7 out of 10 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| package.json | Updates @calcit/procs to 0.11.0-a5; removes version field |
| deps.cirru | Updates calcit-version to 0.11.0-a5 and dependency versions (respo.calcit, memof) |
| compact.cirru | Increments version to 0.10.5; replaces %:: with with-class syntax; whitespace cleanup |
| yarn.lock | Complete lockfile regeneration from Yarn v1 to Yarn v4 format (862 lines added) |
| .yarnrc.yml | New file configuring node-modules linker for Yarn 4 |
| .gitignore | Adds .yarn directory exclusion |
| .github/workflows/upload.yaml | Updates to Node.js 24, actions/setup-node@v6, adds Corepack setup |
| Agents.md | Drastically shortened (683→30 lines) to redirect to llms/ directory |
| llms/Calcit.md | New comprehensive 928-line developer guide for Calcit tooling |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Developer runs `cr js` to watch build JavaScript, and `yarn vite` to start a local server. LLMs edits program by running `cr` commands, and then triggers re-compiling. | ||
|
|
||
| - make sure reading `llms/Calcit.md` for Calcit language tools, aka `cr` command. | ||
| - read `llms/Respo.md` for UI library usages. | ||
|
|
||
| ## LLM 执行效率优化（不重复 llms/Calcit.md） | ||
|
|
||
| - **先定位再修改**：先读结构/需求，再做最小变更，避免“改一处→报错→补救”式迭代。 | ||
| - **缓存上下文**：记录你已经确认的定义位置与修改点，避免重复搜索相同目标。 | ||
| - **优先局部替换**：只替换目标节点或小段结构，避免整段重写导致结构漂移。 | ||
| - **拆分复杂改动**：把 UI 改动与逻辑改动拆开，减少单次变更影响面。 | ||
| - **尽量复用已有组件/样式**：优先扩展已有样式/组件，而不是新增并重复实现。 | ||
| - **检查生成代码风险点**：处理 `let`、map 结构、属性 map 的键值对等高风险结构时，先确认结构是否符合预期，再替换。 | ||
| - **利用 diff 控制范围**：在多次修改后随时对比 diff，避免无关变更积累。 | ||
| - **编译前自检**：对于复杂变更，先手动检查节点结构（比如嵌套列表、属性 map、函数参数形态）再编译。 | ||
| - **输出稳定性优先**：避免频繁调整格式或样式细节，优先保证逻辑稳定与可读性。 | ||
|
|
||
| ## 常见错误与正确做法（结合本项目实践） | ||
|
|
||
| - **`let` 只保留最后一个表达式**：多个表达式需要包一层 `div`/`do`，否则前面的节点会被丢掉。 | ||
| - **属性 map 必须是成对键值**：避免把 `:style` 与 `:inner-text` 写在同一个 pair 内；每个属性单独成对。 | ||
| - **避免生成“可调用字符串”**：形如 `(<> ((str ...)))` 会变成调用结果，正确写法为 `<> $ str ...`。 | ||
| - **列表 vs set**：`keys` 返回 set，拼接前先 `.to-list`，再 `concat`。 | ||
| - **pairs 列表转 map**：不要用 `.to-map` 处理 list，改用 `pairs-map`。 | ||
| - **函数调用与变量区分**：`week-start` 这类变量必须 is-leaf，避免成为单元素 list 导致被当做“函数调用”。 | ||
| - **数值与单位风险**：CSS 属性如 `flex`, `font-weight`, `line-height`, `z-index` 若使用单纯数字，Respo 会自动拼接 `px` 单位。必须改为字符串形式，例如 `:flex "\"1"` 或 `:font-weight "\"300"`。 | ||
| - **结构化编辑优先**：严禁直接编辑 `compact.cirru`，必须使用 `cr tree replace` 或 `cr edit def` 等命令。建议先通过 `cr query search 'keyword' -f 'ns/def'` 精确获得 node 路径。 | ||
| - **性能优化准则**：对于动态生成的列表（如任务项），应将静态样式从内联 `:style` 提取到 `defstyle` 中，通过 `:class-name` 引用以提升虚拟 DOM 性能。 | ||
| - **排序逻辑翻转**：翻转列表排序应直接修改 `sort` 函数所用比较器的返回分支（如将 `if ret 1 -1` 翻转为 `if ret -1 1`）。 |
There was a problem hiding this comment.
The Agents.md file content has been almost entirely replaced with a reference to llms/Calcit.md. While the new llms/Calcit.md file contains comprehensive documentation (928 lines added), this represents a major documentation restructuring that should be explained in the PR description. The file is now much shorter (30 lines vs 683 lines) and primarily serves as a redirection document. Consider whether Agents.md should be kept at all or if it should be removed in favor of having users directly reference the llms/ directory files.
| corepack enable | ||
| corepack prepare yarn@4.12.0 --activate | ||
| yarn --version | ||
|
|
There was a problem hiding this comment.
Yarn 4 migration detected with Corepack setup. The workflow now explicitly enables Corepack and pins Yarn to version 4.12.0, which aligns with the yarn.lock format change from Yarn v1 to Yarn v4 (Berry). The actions/setup-node@v6 also removes the cache: yarn option. However, consider adding cache configuration for Yarn 4, as it uses a different cache structure. You can use the Yarn cache action or configure caching manually for the .yarn/cache directory to speed up CI builds.
| - name: Cache Yarn 4 dependencies | |
| uses: actions/cache@v4 | |
| with: | |
| path: .yarn/cache | |
| key: ${{ runner.os }}-yarn4-${{ hashFiles('yarn.lock') }} | |
| restore-keys: | | |
| ${{ runner.os }}-yarn4- |
| with: | ||
| node-version: 20 | ||
| cache: yarn | ||
| node-version: 24 |
There was a problem hiding this comment.
The CI workflow is being updated from Node.js 20 to Node.js 24, which is a reasonable upgrade. However, Node.js 24 does not exist as a stable release as of January 2025 (the latest LTS is Node.js 22, and 23 is the current version). This appears to be specifying a future version that may not be available when the CI runs. The version should be changed to an existing Node.js version such as 22 (current LTS) or 23 (latest stable).
| node-version: 24 | |
| node-version: 22 |
| @@ -0,0 +1 @@ | |||
| nodeLinker: node-modules | |||
There was a problem hiding this comment.
The .yarnrc.yml configuration sets nodeLinker: node-modules, which configures Yarn 4 to use the traditional node_modules structure instead of Plug'n'Play (PnP). While this is a valid choice for compatibility, it bypasses Yarn 4's performance benefits. Consider documenting the reason for this choice in the PR description - whether it's for compatibility with specific tooling, build systems, or other requirements. If compatibility isn't an issue, consider using PnP for better performance and disk space efficiency.
| nodeLinker: node-modules | |
| nodeLinker: pnp |
No description provided.