@calcit/procs 0.13.7 → 0.13.8

package/editing-history/202608092000-inspect-type-path-format.md

@@ -0,0 +1,4 @@
+# `&inspect-type` 坐标输出统一
+
+- 将 `&inspect-type` 诊断中的源码坐标从 `[@3.5.1]` 调整为 `@3.5.1`。
+- 复用统一的 `@` 路径格式，并增加 Rust 回归测试，避免方括号格式再次出现。

package/history/202608092318-enum-edn-option-diagnostics.md

@@ -0,0 +1,21 @@
+# Cirru EDN enum identity and Option migration diagnostics
+
+## 背景
+
+- GitHub #326 暴露 JS `format-cirru-edn` / `parse-cirru-edn` 往返后 enum variant 从 interned `CalcitTag` 变成 `CalcitSymbol`，导致生成的 `match` 按身份比较时无法命中。
+- GitHub #325 暴露 Option migration 诊断仍使用预处理前的 source symbol，普通 `=`, `some?`, `assoc` 等调用不会触发告警，并且 `starts-with?` / `ends-with?` 的 proc metadata 比公开 schema 更宽。
+
+## 修改与边界
+
+- JS Cirru EDN parser 在匿名和具名 enum 分支统一把解析出的 symbol variant 通过 `newTag` intern；quoted nominal name 也按 tag key 恢复 options map 中的 `CalcitEnumDef`。
+- Option migration diagnostics 改用预处理后的 `head_form` / `call_head`，避免漏掉普通 source syntax，同时继续区分应用自行定义的同名函数。
+- 结构操作诊断覆盖 `assoc`, `dissoc`, `merge`, `update` 及其 nested/non-nil variants。
+- `starts-with?` / `ends-with?` proc 参数 metadata 收紧为 `String × String`，与文档和 core schema 一致；旧 Tag runtime 兼容测试用显式 `unsafe-coerce` 标明边界。
+- 合法的 nominal enum equality 继续允许，包括类型推断尚未完成时，Option/Result constructor 和已声明返回 nominal enum 的调用之间的比较。
+
+## 验证
+
+- JS runtime identity check 覆盖匿名 enum、具名 enum prototype 恢复和 identity-based match 条件。
+- Rust end-to-end snippet test 覆盖 issue 中的 `get-env`, `some?`, `update-in/assoc`, `nth/starts-with?` 普通源码写法。
+- `cargo fmt --all`, `cargo clippy -- -D warnings`, `yarn compile`, `cargo test`, `yarn check-all` 全部通过。
+- 安装当前全局 `cr` 后在 Respo 执行 `cr --check-only`，成功在真实项目中报告 3 个 Option migration warning（另有 1 个既有 JS nullable warning），未进入相关运行时失败路径。

package/history/202608100022-required-struct-field-access.md

@@ -0,0 +1,46 @@
+# Required Struct field access
+
+## Background
+
+Field syntax previously changed its contract according to inferred receiver
+type: `(:field value)` returned the declared payload for a known Struct, but
+silently lowered to Option-producing `get` when the receiver looked like a Map
+or lost type information. This made local edits unstable: adding or losing a
+type annotation changed downstream control flow without changing source syntax.
+
+Issue #325 clarified that dynamic container absence and required model fields
+are different boundaries. AI-assisted edits need those boundaries to remain
+visible so diagnostics guide code toward a declared model instead of allowing
+`Dynamic`/`Option` patches to spread.
+
+## Contract
+
+- `(:field value)` is required access. The receiver must be a statically known
+  named Struct and the field must be declared. Its result is the declared field
+  type.
+- `get` and `get-in` are explicit partial lookup APIs for Map and indexed/path
+  access. They return nominal `Option<T>`.
+- `get` on a Struct is rejected with a diagnostic pointing to required field
+  syntax; the runtime also rejects dynamically hidden Struct receivers.
+- Loose/anonymous Struct field access is rejected until an expected named
+  Struct type rewrites or narrows it.
+- Low-level `&struct:get` remains available for internal dynamic boundaries
+  such as reusable trait implementation bodies.
+
+## Type inference details
+
+- `update` preserves the receiver's collection/Struct type.
+- `&struct:from-map` preserves the Struct definition supplied as its first
+  argument.
+- Struct pattern-match expansion is exempt from source field validation because
+  all nominal branches are preprocessed before runtime guards select a variant.
+
+## Diagnostics
+
+- `W_REQUIRED_STRUCT_FIELD_TYPE`: required field syntax lacks a named Struct
+  contract.
+- `W_UNKNOWN_STRUCT_FIELD`: a named Struct does not declare the requested field.
+- `W_STRUCT_FIELD_OPTIONAL_LOOKUP`: `get` is used on a Struct.
+
+Tests cover typed access, Map fallback rejection, unknown fields, `get` misuse,
+nominal type preservation, loose Struct access, and the existing Struct suite.

package/history/202608100102-docs-field-access-ci.md

@@ -0,0 +1,22 @@
+# Documentation validation for required Struct fields
+
+## Background
+
+The PR's local `yarn check-all` suite passed, but GitHub's Test workflow also
+runs `scripts/check-docs-md.sh`. Several executable documentation snippets
+still relied on the former context-sensitive field syntax.
+
+## Documentation migration
+
+- Map reads that branch on absence retain their `Option` value for `tag-match`
+  instead of unwrapping it first.
+- Generic enum payloads, local trait implementations, generic Struct bodies,
+  and anonymous Struct examples use explicit `&struct:get` when their receiver
+  has no statically resolvable named Struct declaration.
+- Snapshot/schema fragments now use standard `cirru.edn` fences with valid
+  EDN roots and quoted symbols, so `check-md` validates them as data instead
+  of evaluating tags such as `:entries` or `:where` as required field access.
+
+## Verification
+
+- `bash scripts/check-docs-md.sh`: 54 files, 286 blocks, all passed.

package/history/202608100145-cirru-edn-doc-fences.md

@@ -0,0 +1,17 @@
+# Standard Cirru EDN documentation fences
+
+## Background
+
+Executable documentation fences use the standard `cirru.edn` marker. The
+non-standard `cirru-edn` spelling bypassed EDN validation and hid malformed
+configuration and schema fragments.
+
+## Change
+
+- Replaced all newly introduced `cirru-edn` fences with `cirru.edn`.
+- Wrapped standalone configuration/schema fields in top-level EDN maps.
+- Quoted symbolic trait references inside EDN schema values.
+
+## Verification
+
+- `bash scripts/check-docs-md.sh`: 54 files and 290 blocks passed.

package/history/202608100339-struct-path-boundaries.md

@@ -0,0 +1,11 @@
+## Struct path API boundaries
+
+- Public collection path APIs (`get-in`, `assoc-in`, `update-in`, `dissoc-in`)
+  now stop at nominal Struct boundaries. Required fields remain visible as direct
+  `(:field value)` accesses, preserving their declared types for the checker.
+- The preprocessor diagnoses literal and dynamic paths that would enter a Struct;
+  `get-in` no longer infers a field type through such a path.
+- Runtime core implementations reject the same traversal after a Dynamic boundary,
+  so unsafe coercion cannot silently bypass the typed field-access contract.
+- Updated the type-inference fixture to use nested direct field access instead of
+  `get-in` across a Struct.

package/history/202608100348-caps-branch-checkout.md

@@ -0,0 +1,8 @@
+## caps remote branch checkout
+
+- `caps` now fetches remote branch refs as well as tags when resolving an
+  existing module clone.
+- If a requested branch exists only as `origin/<branch>`, checkout now creates
+  a local tracking branch instead of failing after the fetch succeeds.
+- This keeps branch-based module integration reproducible through `caps
+  download`, without manually editing the module cache.

package/history/202608100349-caps-remote-branch-reset.md

@@ -0,0 +1,8 @@
+## caps remote branch checkout hardening
+
+- Existing module clones can use narrow or non-standard remote refspecs, for
+  which `git checkout --track origin/<branch>` may reject an otherwise fetched
+  remote ref.
+- `caps` now creates/resets the requested local branch with `git checkout -B
+  <branch> origin/<branch>`, keeping branch-based module downloads reliable and
+  compatible with later `--pull-branch` updates.

package/history/202608100959-struct-path-review-followups.md

@@ -0,0 +1,11 @@
+## Struct path-operation review follow-ups
+
+- `contains-in?` now follows the same Struct boundary as the other collection
+  path APIs: a path may not enter a declared Struct field. Direct typed field
+  access keeps required-field diagnostics and return types precise.
+- The preprocessor reports `W_STRUCT_PATH_OPERATION` for `contains-in?`, with
+  a regression test covering all five path APIs.
+- Runtime guidance for `dissoc-in` now explains that declared Struct fields
+  cannot be removed; model optionality explicitly or convert to a map first.
+- Module ref fetching now uses `--prune`, so stale remote-tracking branches do
+  not remain selectable after an upstream branch deletion.

package/history/202608101042-release-0.13.8.md

@@ -0,0 +1,6 @@
+## Release 0.13.8
+
+- Publishes the typed Struct field-access and collection path-boundary work
+  merged through PR #327.
+- Keeps module branch resolution robust by fetching and pruning remote branch
+  refs before checkout.

package/lib/js-cirru.mjs

@@ -225,13 +225,17 @@ let recordFieldOrder = (a, b) => {
 };
 /** makes sure we got string */
 let extractFieldTag = (x) => {
-    if (x[0] === ":") {
+    if (x[0] === ":" || x[0] === "'") {
         return newTag(x.slice(1));
     }
     else {
         return newTag(x);
     }
 };
+let extractEnumTag = (x, options, preserveSourceEntries) => {
+    const parsedTag = extract_cirru_edn_inner(x, options, preserveSourceEntries);
+    return parsedTag instanceof CalcitSymbol ? newTag(parsedTag.value) : parsedTag;
+};
 let resolveEnumPrototype = (enumName, options) => {
     if (options instanceof CalcitMap || options instanceof CalcitSliceMap) {
         let value = options.get(extractFieldTag(enumName));
@@ -412,7 +416,7 @@ const extract_cirru_edn_inner = (x, options, preserveSourceEntries) => {
             if (x.length < 2) {
                 throw new Error(`anonymous enum expects at least 1 value, got: ${x}`);
             }
-            return new CalcitEnumValue(extract_cirru_edn_inner(x[1], options, preserveSourceEntries), x
+            return new CalcitEnumValue(extractEnumTag(x[1], options, preserveSourceEntries), x
                 .slice(2)
                 .filter(notComment)
                 .map((x) => extract_cirru_edn_inner(x, options, preserveSourceEntries)));
@@ -426,10 +430,7 @@ const extract_cirru_edn_inner = (x, options, preserveSourceEntries) => {
                 throw new Error(`Expected string for enum name, got: ${enumName}`);
             }
             let enumPrototype = resolveEnumPrototype(enumName, options);
-            // unwrap prototype to record then extract name
-            const proto = enumPrototype != null ? unwrap_enum_prototype_local(enumPrototype) : null;
-            const enumTag = proto != null ? proto.name.toString() : enumName;
-            return new CalcitEnumValue(extract_cirru_edn_inner(x[2], options, preserveSourceEntries), x
+            return new CalcitEnumValue(extractEnumTag(x[2], options, preserveSourceEntries), x
                 .slice(3)
                 .filter(notComment)
                 .map((x) => extract_cirru_edn_inner(x, options, preserveSourceEntries)), enumPrototype);

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.13.7",
+    "version": "0.13.8",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.7.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.13.7",
+  "version": "0.13.8",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.7.0",

package/ts-src/js-cirru.mts

@@ -220,13 +220,18 @@ let recordFieldOrder = (a: [string, CirruEdnFormat], b: [string, CirruEdnFormat]
 
 /** makes sure we got string */
 let extractFieldTag = (x: string) => {
-  if (x[0] === ":") {
+  if (x[0] === ":" || x[0] === "'") {
     return newTag(x.slice(1));
   } else {
     return newTag(x);
   }
 };
 
+let extractEnumTag = (x: CirruEdnFormat, options: CalcitValue, preserveSourceEntries: boolean): CalcitValue => {
+  const parsedTag = extract_cirru_edn_inner(x, options, preserveSourceEntries);
+  return parsedTag instanceof CalcitSymbol ? newTag(parsedTag.value) : parsedTag;
+};
+
 let resolveEnumPrototype = (enumName: string, options: CalcitValue) => {
   if (options instanceof CalcitMap || options instanceof CalcitSliceMap) {
     let value = options.get(extractFieldTag(enumName));
@@ -405,7 +410,7 @@ const extract_cirru_edn_inner = (x: CirruEdnFormat, options: CalcitValue, preser
         throw new Error(`anonymous enum expects at least 1 value, got: ${x}`);
       }
       return new CalcitEnumValue(
-        extract_cirru_edn_inner(x[1], options, preserveSourceEntries),
+        extractEnumTag(x[1], options, preserveSourceEntries),
         x
           .slice(2)
           .filter(notComment)
@@ -421,11 +426,8 @@ const extract_cirru_edn_inner = (x: CirruEdnFormat, options: CalcitValue, preser
         throw new Error(`Expected string for enum name, got: ${enumName}`);
       }
       let enumPrototype = resolveEnumPrototype(enumName, options);
-      // unwrap prototype to record then extract name
-      const proto = enumPrototype != null ? unwrap_enum_prototype_local(enumPrototype) : null;
-      const enumTag = proto != null ? proto.name.toString() : enumName;
       return new CalcitEnumValue(
-        extract_cirru_edn_inner(x[2], options, preserveSourceEntries),
+        extractEnumTag(x[2], options, preserveSourceEntries),
         x
           .slice(3)
           .filter(notComment)