@calcit/procs 0.12.10 → 0.12.11

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

@@ -0,0 +1,45 @@
+## Summary
+
+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`
+
+## Files touched (high level)
+
+- Rust builtin registration and implementation for JSON runtime support.
+- JS runtime proc exports for JSON behavior and validation.
+- Calcit core snapshot docs/examples and test snapshot updates.
+- CLI/codegen placeholder spelling cleanup.
+- Agent guide example for `edit format`.
+
+## Validation notes
+
+- `cargo test json_`
+- `cargo test validate_runtime_impl_is_skipped -- --nocapture`
+- `cargo test runtime_placeholder -- --nocapture`
+- `cargo run --bin cr -- calcit/test.cirru -1`
+- `yarn check-all`
+
+## Release size check
+
+Measured `target/release/cr` against `HEAD` using a detached worktree build:
+
+- Current: `5192960` bytes (`5.0M`)
+- Base: `5174400` bytes (`4.9M`)
+- Delta: `+18560` bytes (about `+18.1 KiB`)
+
+Conclusion: the builtin JSON work increases the release binary size slightly, but the delta is small relative to the ~5 MB target.

package/lib/calcit.procs.mjs

@@ -1438,6 +1438,103 @@ export let parse_cirru_edn = (code, options) => {
         throw new Error(`Expected EDN in a single node, got ${nodes.length}`);
     }
 };
+const json_to_calcit = (value) => {
+    if (value == null)
+        return null;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "boolean")
+        return value;
+    if (Array.isArray(value)) {
+        return new CalcitSliceList(value.map(json_to_calcit));
+    }
+    if (typeof value === "object") {
+        const entries = [];
+        for (const key of Object.keys(value)) {
+            entries.push(newTag(key), json_to_calcit(value[key]));
+        }
+        return new CalcitSliceMap(entries);
+    }
+    throw new Error(`Unsupported JSON value: ${value}`);
+};
+const calcit_json_key = (value) => {
+    if (value instanceof CalcitTag)
+        return value.value;
+    if (typeof value === "string")
+        return value;
+    throw new Error(`json-stringify expected object keys to be tags or strings, got: ${toString(value, true)}`);
+};
+const cirru_quote_to_json = (value) => {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value.map(cirru_quote_to_json);
+    throw new Error(`Unsupported cirru quote node: ${value}`);
+};
+const calcit_to_json = (value) => {
+    if (value == null)
+        return null;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return value;
+        throw new Error(`json-stringify cannot encode number: ${value}`);
+    }
+    if (typeof value === "boolean")
+        return value;
+    if (value instanceof CalcitTag)
+        return value.value;
+    if (value instanceof CalcitSymbol)
+        return value.value;
+    if (value instanceof CalcitList || value instanceof CalcitSliceList) {
+        return Array.from(value.items()).map(calcit_to_json);
+    }
+    if (value instanceof CalcitSet) {
+        return value.values().map(calcit_to_json);
+    }
+    if (value instanceof CalcitMap || value instanceof CalcitSliceMap) {
+        const result = {};
+        for (const [key, item] of value.pairs()) {
+            result[calcit_json_key(key)] = calcit_to_json(item);
+        }
+        return result;
+    }
+    if (value instanceof CalcitTuple) {
+        return [calcit_to_json(value.tag), ...value.extra.map(calcit_to_json)];
+    }
+    if (value instanceof CalcitCirruQuote) {
+        return cirru_quote_to_json(value.value);
+    }
+    if (value instanceof CalcitRecord) {
+        const result = {};
+        for (let idx = 0; idx < value.fields.length; idx++) {
+            result[value.fields[idx].value] = calcit_to_json(value.values[idx]);
+        }
+        return result;
+    }
+    throw new Error(`json-stringify cannot encode value: ${toString(value, true)}`);
+};
+export let json_parse = function (code) {
+    if (arguments.length !== 1)
+        throw new Error("json-parse expected 1 argument");
+    if (typeof code !== "string") {
+        throw new Error(`json-parse expected a string, got: ${toString(code, true)}`);
+    }
+    return json_to_calcit(JSON.parse(code));
+};
+export let json_stringify = function (value) {
+    if (arguments.length !== 1)
+        throw new Error("json-stringify expected 1 argument");
+    return JSON.stringify(calcit_to_json(value));
+};
+export let json_pretty = function (value) {
+    if (arguments.length !== 1)
+        throw new Error("json-pretty expected 1 argument");
+    return JSON.stringify(calcit_to_json(value), null, 2);
+};
 export let format_to_lisp = (x) => {
     if (x == null) {
         return "nil";

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.10",
+    "version": "0.12.11",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",
@@ -16,14 +16,14 @@
         "test-rs": "cargo test -q",
         "test-fail": "cargo test -q --bin cr type_fail_",
         "test-snippets": "cargo test -q snippets::tests",
-        "bench-recur-smoke": "cargo run --bin cr -- calcit/test.cirru -1 js && node --input-type=module -e \"import { test_loop } from './js-out/test-recursion.main.mjs'; const n=3000; const t0=process.hrtime.bigint(); for(let i=0;i<n;i++) test_loop(); const dt=Number(process.hrtime.bigint()-t0)/1e6; console.log('test_loop_ms='+dt.toFixed(3));\"",
+        "bench-recur-smoke": "cargo run --bin cr -- calcit/test.cirru js && node --input-type=module -e \"import { test_loop } from './js-out/test-recursion.main.mjs'; const n=3000; const t0=process.hrtime.bigint(); for(let i=0;i<n;i++) test_loop(); const dt=Number(process.hrtime.bigint()-t0)/1e6; console.log('test_loop_ms='+dt.toFixed(3));\"",
         "check-smooth": "yarn fmt-rs && yarn lint-rs && yarn test-rs && yarn check-all",
         "check-all": "yarn compile && yarn try-rs && yarn try-js && yarn try-ir",
-        "try-rs": "cargo run --bin cr -- calcit/test.cirru -1",
-        "warn-dyn-method": "cargo run --bin cr -- calcit/test.cirru -1 --warn-dyn-method",
-        "try-js-brk": "cargo run --bin cr -- calcit/test.cirru -1 js && node --inspect-brk js-out/main.mjs",
-        "try-js": "cargo run --bin cr -- calcit/test.cirru -1 js && node js-out/main.mjs",
-        "try-ir": "cargo run --bin cr -- calcit/test.cirru -1 js"
+        "try-rs": "cargo run --bin cr -- calcit/test.cirru",
+        "warn-dyn-method": "cargo run --bin cr -- calcit/test.cirru --warn-dyn-method",
+        "try-js-brk": "cargo run --bin cr -- calcit/test.cirru js && node --inspect-brk js-out/main.mjs",
+        "try-js": "cargo run --bin cr -- calcit/test.cirru js && node js-out/main.mjs",
+        "try-ir": "cargo run --bin cr -- calcit/test.cirru js"
     },
     "repository": {
         "type": "git",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.10",
+  "version": "0.12.11",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",
@@ -16,14 +16,14 @@
     "test-rs": "cargo test -q",
     "test-fail": "cargo test -q --bin cr type_fail_",
     "test-snippets": "cargo test -q snippets::tests",
-    "bench-recur-smoke": "cargo run --bin cr -- calcit/test.cirru -1 js && node --input-type=module -e \"import { test_loop } from './js-out/test-recursion.main.mjs'; const n=3000; const t0=process.hrtime.bigint(); for(let i=0;i<n;i++) test_loop(); const dt=Number(process.hrtime.bigint()-t0)/1e6; console.log('test_loop_ms='+dt.toFixed(3));\"",
+    "bench-recur-smoke": "cargo run --bin cr -- calcit/test.cirru js && node --input-type=module -e \"import { test_loop } from './js-out/test-recursion.main.mjs'; const n=3000; const t0=process.hrtime.bigint(); for(let i=0;i<n;i++) test_loop(); const dt=Number(process.hrtime.bigint()-t0)/1e6; console.log('test_loop_ms='+dt.toFixed(3));\"",
     "check-smooth": "yarn fmt-rs && yarn lint-rs && yarn test-rs && yarn check-all",
     "check-all": "yarn compile && yarn try-rs && yarn try-js && yarn try-ir",
-    "try-rs": "cargo run --bin cr -- calcit/test.cirru -1",
-    "warn-dyn-method": "cargo run --bin cr -- calcit/test.cirru -1 --warn-dyn-method",
-    "try-js-brk": "cargo run --bin cr -- calcit/test.cirru -1 js && node --inspect-brk js-out/main.mjs",
-    "try-js": "cargo run --bin cr -- calcit/test.cirru -1 js && node js-out/main.mjs",
-    "try-ir": "cargo run --bin cr -- calcit/test.cirru -1 js"
+    "try-rs": "cargo run --bin cr -- calcit/test.cirru",
+    "warn-dyn-method": "cargo run --bin cr -- calcit/test.cirru --warn-dyn-method",
+    "try-js-brk": "cargo run --bin cr -- calcit/test.cirru js && node --inspect-brk js-out/main.mjs",
+    "try-js": "cargo run --bin cr -- calcit/test.cirru js && node js-out/main.mjs",
+    "try-ir": "cargo run --bin cr -- calcit/test.cirru js"
   },
   "repository": {
     "type": "git",

package/ts-src/calcit.procs.mts

@@ -1560,6 +1560,93 @@ export let parse_cirru_edn = (code: string, options: CalcitValue) => {
   }
 };
 
+const json_to_calcit = (value: any): CalcitValue => {
+  if (value == null) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return value;
+  if (typeof value === "boolean") return value;
+  if (Array.isArray(value)) {
+    return new CalcitSliceList(value.map(json_to_calcit));
+  }
+  if (typeof value === "object") {
+    const entries: CalcitValue[] = [];
+    for (const key of Object.keys(value)) {
+      entries.push(newTag(key), json_to_calcit(value[key]));
+    }
+    return new CalcitSliceMap(entries);
+  }
+  throw new Error(`Unsupported JSON value: ${value}`);
+};
+
+const calcit_json_key = (value: CalcitValue): string => {
+  if (value instanceof CalcitTag) return value.value;
+  if (typeof value === "string") return value;
+  throw new Error(`json-stringify expected object keys to be tags or strings, got: ${toString(value, true)}`);
+};
+
+const cirru_quote_to_json = (value: ICirruNode): any => {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.map(cirru_quote_to_json);
+  throw new Error(`Unsupported cirru quote node: ${value}`);
+};
+
+const calcit_to_json = (value: CalcitValue): any => {
+  if (value == null) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) return value;
+    throw new Error(`json-stringify cannot encode number: ${value}`);
+  }
+  if (typeof value === "boolean") return value;
+  if (value instanceof CalcitTag) return value.value;
+  if (value instanceof CalcitSymbol) return value.value;
+  if (value instanceof CalcitList || value instanceof CalcitSliceList) {
+    return Array.from(value.items()).map(calcit_to_json);
+  }
+  if (value instanceof CalcitSet) {
+    return value.values().map(calcit_to_json);
+  }
+  if (value instanceof CalcitMap || value instanceof CalcitSliceMap) {
+    const result: Record<string, any> = {};
+    for (const [key, item] of value.pairs()) {
+      result[calcit_json_key(key)] = calcit_to_json(item);
+    }
+    return result;
+  }
+  if (value instanceof CalcitTuple) {
+    return [calcit_to_json(value.tag), ...value.extra.map(calcit_to_json)];
+  }
+  if (value instanceof CalcitCirruQuote) {
+    return cirru_quote_to_json(value.value as ICirruNode);
+  }
+  if (value instanceof CalcitRecord) {
+    const result: Record<string, any> = {};
+    for (let idx = 0; idx < value.fields.length; idx++) {
+      result[value.fields[idx].value] = calcit_to_json(value.values[idx]);
+    }
+    return result;
+  }
+  throw new Error(`json-stringify cannot encode value: ${toString(value, true)}`);
+};
+
+export let json_parse = function (code: CalcitValue): CalcitValue {
+  if (arguments.length !== 1) throw new Error("json-parse expected 1 argument");
+  if (typeof code !== "string") {
+    throw new Error(`json-parse expected a string, got: ${toString(code, true)}`);
+  }
+  return json_to_calcit(JSON.parse(code));
+};
+
+export let json_stringify = function (value: CalcitValue): string {
+  if (arguments.length !== 1) throw new Error("json-stringify expected 1 argument");
+  return JSON.stringify(calcit_to_json(value));
+};
+
+export let json_pretty = function (value: CalcitValue): string {
+  if (arguments.length !== 1) throw new Error("json-pretty expected 1 argument");
+  return JSON.stringify(calcit_to_json(value), null, 2);
+};
+
 export let format_to_lisp = (x: CalcitValue): string => {
   if (x == null) {
     return "nil";