From 1520244923ee99d2f46c93113f49b02162468e04 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 10:24:13 +0800 Subject: [PATCH] feat(value): value model, structured diagnostics and wire format Implements the shared data contract from blueprint sections 3.4, 7.2 and 10.3: - Value: Unit/None/Bool/Int(BigInt)/Float/Text/List/Map/Table/Formula/Code/ FunctionRef/PluginHandle; Unit and None stay distinct and there is no implicit string/number coercion. - Diagnostic with stable machine-readable codes (markdown.invalid_construct, expr.parse, symbol.unknown, permission.denied, ...) and span/related/hints. - RuntimeError with category codes and call frames; renders to a Diagnostic. - Versioned, type-tagged JSON wire format (wire_version = 1) that keeps arbitrary-precision integers as decimal strings, tags NaN/Infinity, enforces depth/size limits on untrusted input and never trusts JSON numbers for Int. - Byte spans and line/column mapping live in the new marqdo-span crate. --- Cargo.lock | 822 ++++++++++++++++++++++++++ crates/marqdo-value/src/diagnostic.rs | 187 ++++++ crates/marqdo-value/src/error.rs | 175 ++++++ crates/marqdo-value/src/lib.rs | 17 + crates/marqdo-value/src/value.rs | 352 +++++++++++ crates/marqdo-value/src/wire.rs | 415 +++++++++++++ 6 files changed, 1968 insertions(+) create mode 100644 Cargo.lock create mode 100644 crates/marqdo-value/src/diagnostic.rs create mode 100644 crates/marqdo-value/src/error.rs create mode 100644 crates/marqdo-value/src/lib.rs create mode 100644 crates/marqdo-value/src/value.rs create mode 100644 crates/marqdo-value/src/wire.rs diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..944ea91 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,822 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 3 + +[[package]] +name = "anstream" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d" +dependencies = [ + "anstyle", + "anstyle-parse", + "anstyle-query", + "anstyle-wincon", + "colorchoice", + "is_terminal_polyfill", + "utf8parse", +] + +[[package]] +name = "anstyle" +version = "1.0.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000" + +[[package]] +name = "anstyle-parse" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e" +dependencies = [ + "utf8parse", +] + +[[package]] +name = "anstyle-query" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "anstyle-wincon" +version = "3.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d" +dependencies = [ + "anstyle", + "once_cell_polyfill", + "windows-sys", +] + +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + +[[package]] +name = "caseless" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8b6fd507454086c8edfd769ca6ada439193cdb209c7681712ef6275cccbfe5d8" +dependencies = [ + "unicode-normalization", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "clap" +version = "4.6.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "844c5c0b65be192cb68d570cca1b21a6444431d24e39c084dc0336177015337c" +dependencies = [ + "clap_builder", + "clap_derive", +] + +[[package]] +name = "clap_builder" +version = "4.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec0797fb7aeb1406c84efac526901f7ec3ead2124f946b494e72879d4b54704d" +dependencies = [ + "anstream", + "anstyle", + "clap_lex", + "strsim", +] + +[[package]] +name = "clap_derive" +version = "4.6.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b4c174f11f949b9ca8c60580925e282b9cbd5454750e506f08648b2038080cd7" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "clap_lex" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e0921b3876b3a1df8a1c9f912e7f94342458022c2e84288015893d83c4d62a79" + +[[package]] +name = "colorchoice" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" + +[[package]] +name = "comrak" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d981d666dca19afb3cc090dc7c381560cb8ba76582dda6e2c14686ff39fd547f" +dependencies = [ + "caseless", + "entities", + "finl_unicode", + "memchr-n", + "phf", + "phf_codegen", + "rustc-hash", + "smallvec", + "typed-arena", +] + +[[package]] +name = "cpufeatures" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +dependencies = [ + "libc", +] + +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "typenum", +] + +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer", + "crypto-common", +] + +[[package]] +name = "entities" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b5320ae4c3782150d900b79807611a59a99fc9a1d61d686faafc24b93fc8d7ca" + +[[package]] +name = "equivalent" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826" + +[[package]] +name = "fastrand" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223" + +[[package]] +name = "fearless_simd" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "629c9d6b6f30b5604089e0980f4d924a013aacb1654a6cdf5d3d852224f68651" + +[[package]] +name = "fearless_simd_macros" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3e91d94c6885390b81782d7ee60fd6583b33907333a8b340de25ccf468353315" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "finl_unicode" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ded33109e99472f809cb7495544506eea45e366725dacf2a383e184f660456" + +[[package]] +name = "generic-array" +version = "0.14.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" +dependencies = [ + "typenum", + "version_check", +] + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "hex" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown", +] + +[[package]] +name = "is_terminal_polyfill" +version = "1.70.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695" + +[[package]] +name = "itoa" +version = "1.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3bd1574e617a9a6c1f8f8181bd7e841e1f20e4277607ef28945765188d6284d4" + +[[package]] +name = "libc" +version = "0.2.191" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" + +[[package]] +name = "libloading" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55" +dependencies = [ + "cfg-if", + "windows-link", +] + +[[package]] +name = "marqdo-cli" +version = "0.1.0" +dependencies = [ + "clap", + "marqdo-expression", + "marqdo-foreign", + "marqdo-frontend", + "marqdo-host", + "marqdo-ir", + "marqdo-markdown", + "marqdo-math", + "marqdo-package", + "marqdo-plugin-abi", + "marqdo-runtime", + "marqdo-sandbox", + "marqdo-span", + "marqdo-value", + "serde", + "serde_json", + "thiserror", +] + +[[package]] +name = "marqdo-expression" +version = "0.1.0" +dependencies = [ + "marqdo-span", + "serde", + "thiserror", +] + +[[package]] +name = "marqdo-foreign" +version = "0.1.0" +dependencies = [ + "marqdo-span", + "marqdo-value", + "serde_json", + "thiserror", +] + +[[package]] +name = "marqdo-frontend" +version = "0.1.0" +dependencies = [ + "marqdo-expression", + "marqdo-ir", + "marqdo-markdown", + "marqdo-span", + "marqdo-value", + "serde", + "serde_json", + "thiserror", + "unicode-normalization", +] + +[[package]] +name = "marqdo-host" +version = "0.1.0" +dependencies = [ + "marqdo-foreign", + "marqdo-math", + "marqdo-plugin-abi", + "marqdo-sandbox", + "marqdo-span", + "marqdo-value", + "serde", + "serde_json", + "thiserror", +] + +[[package]] +name = "marqdo-ir" +version = "0.1.0" +dependencies = [ + "marqdo-expression", + "marqdo-span", + "marqdo-value", + "serde", + "serde_json", +] + +[[package]] +name = "marqdo-markdown" +version = "0.1.0" +dependencies = [ + "comrak", + "marqdo-span", + "serde", + "serde_yaml", + "unicode-normalization", +] + +[[package]] +name = "marqdo-math" +version = "0.1.0" +dependencies = [ + "marqdo-span", + "marqdo-value", + "num-bigint 0.5.1", + "num-rational", + "num-traits", + "serde", + "thiserror", +] + +[[package]] +name = "marqdo-package" +version = "0.1.0" +dependencies = [ + "hex", + "marqdo-span", + "serde", + "serde_json", + "serde_yaml", + "sha2", + "thiserror", + "walkdir", +] + +[[package]] +name = "marqdo-plugin-abi" +version = "0.1.0" +dependencies = [ + "libloading", + "marqdo-span", + "marqdo-value", + "serde", + "serde_json", + "serde_yaml", + "thiserror", +] + +[[package]] +name = "marqdo-plugin-sdk" +version = "0.1.0" +dependencies = [ + "marqdo-plugin-abi", + "serde", + "serde_json", +] + +[[package]] +name = "marqdo-runtime" +version = "0.1.0" +dependencies = [ + "marqdo-expression", + "marqdo-host", + "marqdo-ir", + "marqdo-span", + "marqdo-value", + "thiserror", +] + +[[package]] +name = "marqdo-sandbox" +version = "0.1.0" +dependencies = [ + "marqdo-span", + "serde", + "thiserror", +] + +[[package]] +name = "marqdo-span" +version = "0.1.0" +dependencies = [ + "serde", +] + +[[package]] +name = "marqdo-value" +version = "0.1.0" +dependencies = [ + "marqdo-span", + "num-bigint 0.5.1", + "num-traits", + "serde", + "serde_json", +] + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "memchr-n" +version = "0.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f48c6352cc1185740af256ccc396af598d2366bfd90a34f5afe48744bf06a5b5" +dependencies = [ + "fearless_simd", + "fearless_simd_macros", +] + +[[package]] +name = "num-bigint" +version = "0.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367" +dependencies = [ + "num-integer", + "num-traits", +] + +[[package]] +name = "num-bigint" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93e7820bc0a80a0238e650327316f929ba18d5be054b647490a3a6a339f3e7c0" +dependencies = [ + "num-integer", + "num-traits", + "serde", +] + +[[package]] +name = "num-integer" +version = "0.1.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b" +dependencies = [ + "num-traits", +] + +[[package]] +name = "num-rational" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824" +dependencies = [ + "num-bigint 0.4.8", + "num-integer", + "num-traits", + "serde", +] + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "once_cell_polyfill" +version = "1.70.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" + +[[package]] +name = "phf" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "010378780309880b08997fae13be7834dba947d36393bd372f2b1556deb2a2f6" +dependencies = [ + "phf_shared", + "serde", +] + +[[package]] +name = "phf_codegen" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41b585a510fb76fdebead6897982ef2a03a21d8e6cbcca904999742a4afc6ffe" +dependencies = [ + "phf_generator", + "phf_shared", +] + +[[package]] +name = "phf_generator" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aeb62e0959d5a1bebc965f4d15d9e2b7cea002b6b0f5ba8cde6cc26738467100" +dependencies = [ + "fastrand", + "phf_shared", +] + +[[package]] +name = "phf_shared" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6fd9027e2d9319be6349febd1db4e8d02aa544921200c9b777720ac34a3aa89" +dependencies = [ + "siphasher", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "rustc-hash" +version = "2.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d" + +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "same-file" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_yaml" +version = "0.9.34+deprecated" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47" +dependencies = [ + "indexmap", + "itoa", + "ryu", + "serde", + "unsafe-libyaml", +] + +[[package]] +name = "sha2" +version = "0.10.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283" +dependencies = [ + "cfg-if", + "cpufeatures", + "digest", +] + +[[package]] +name = "siphasher" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33f4fe9184a62d842c9ef383018f3306d8ba224fd9d836f56d7288308847c256" + +[[package]] +name = "smallvec" +version = "1.16.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3244542535d5de959d90ec55d1b5ff0fd2bb7b1310223907d5f11932847f7b59" + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "syn" +version = "3.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "tinyvec" +version = "1.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee" + +[[package]] +name = "typed-arena" +version = "2.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6af6ae20167a9ece4bcb41af5b80f8a1f1df981f6391189ce00fd257af04126a" + +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "unicode-normalization" +version = "0.1.26" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "75cd3fb03d5288b3ba9a1ee103ac7e9cbb59f0b03d64f8ddfcc04dd42758a85d" +dependencies = [ + "tinyvec", +] + +[[package]] +name = "unsafe-libyaml" +version = "0.2.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861" + +[[package]] +name = "utf8parse" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + +[[package]] +name = "walkdir" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b" +dependencies = [ + "same-file", + "winapi-util", +] + +[[package]] +name = "winapi-util" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/crates/marqdo-value/src/diagnostic.rs b/crates/marqdo-value/src/diagnostic.rs new file mode 100644 index 0000000..105824b --- /dev/null +++ b/crates/marqdo-value/src/diagnostic.rs @@ -0,0 +1,187 @@ +//! Machine readable diagnostics shared by `check`, `inspect` and `run`. + +use marqdo_span::Span; +use serde::{Deserialize, Serialize}; + +/// Stable diagnostic codes. CI may depend on these strings; they must not be +/// renamed without an ADR because they are part of the CLI contract. +pub mod codes { + /// A Markdown AST node occupies an executable position but has an invalid shape. + pub const MARKDOWN_INVALID_CONSTRUCT: &str = "markdown.invalid_construct"; + /// Front matter is malformed or appears somewhere other than the document start. + pub const FRONTMATTER_INVALID: &str = "frontmatter.invalid"; + /// An executable payload failed to parse as an expression or statement. + pub const EXPR_PARSE: &str = "expr.parse"; + /// A function name is referenced but no such function exists. + pub const SYMBOL_UNKNOWN: &str = "symbol.unknown"; + /// A variable is read before any binding is guaranteed to exist. + pub const SYMBOL_UNINITIALIZED: &str = "symbol.uninitialized"; + /// A call supplies the wrong number of arguments. + pub const CALL_ARITY: &str = "call.arity"; + /// A call supplies an argument of the wrong type. + pub const CALL_TYPE: &str = "call.type"; + /// An imported module cannot be resolved or loaded. + pub const MODULE_UNRESOLVED: &str = "module.unresolved"; + /// A module import cycle was detected. + pub const MODULE_CYCLE: &str = "module.cycle"; + /// A Markdown reference or link target cannot be resolved. + pub const REF_UNRESOLVED: &str = "ref.unresolved"; + /// The requested math operation is outside the supported subset. + pub const MATH_UNSUPPORTED: &str = "math.unsupported"; + /// A foreign language kernel is not available on this machine. + pub const KERNEL_UNAVAILABLE: &str = "kernel.unavailable"; + /// A capability check rejected the requested operation. + pub const PERMISSION_DENIED: &str = "permission.denied"; + /// A plugin artifact does not match the supported ABI version. + pub const PLUGIN_ABI_MISMATCH: &str = "plugin.abi_mismatch"; + /// A resource budget (fuel, stack, memory, time) was exhausted. + pub const RESOURCE_EXHAUSTED: &str = "resource.exhausted"; + /// A runtime type error that is not better described by a more specific code. + pub const RUNTIME_TYPE: &str = "runtime.type"; + /// A runtime index or key error. + pub const RUNTIME_INDEX: &str = "runtime.index"; + /// Invalid project manifest. + pub const PROJECT_MANIFEST: &str = "project.manifest"; + /// Invalid project lockfile. + pub const PROJECT_LOCK: &str = "project.lock"; + /// Dependency resolution failed. + pub const PROJECT_DEPENDENCY: &str = "project.dependency"; + /// Internal invariant violation; never expected in normal operation. + pub const INTERNAL: &str = "internal.error"; +} + +/// Severity level of a [`Diagnostic`]. +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Severity { + /// The input is invalid and execution/checking cannot proceed. + Error, + /// The input is valid but suspicious or potentially non-portable. + Warning, + /// Informational note attached to another diagnostic. + Info, +} + +impl Severity { + /// Lowercase name used in JSON output. + pub const fn as_str(self) -> &'static str { + match self { + Severity::Error => "error", + Severity::Warning => "warning", + Severity::Info => "info", + } + } +} + +impl std::fmt::Display for Severity { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(self.as_str()) + } +} + +/// Secondary source location attached to a diagnostic. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct Related { + /// Optional span of the related location. + #[serde(skip_serializing_if = "Option::is_none")] + pub span: Option, + /// Why this location is relevant. + pub message: String, +} + +/// A structured, machine readable diagnostic. +/// +/// The JSON shape is part of the CLI contract: +/// `{ code, severity, span, message, related, hints }`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct Diagnostic { + /// Stable code from [`codes`]. + pub code: String, + /// Severity of the diagnostic. + pub severity: Severity, + /// Source span (byte offsets into the file), if known. + #[serde(skip_serializing_if = "Option::is_none")] + pub span: Option, + /// Human readable message. Not part of the compatibility contract. + pub message: String, + /// Related locations, e.g. a conflicting declaration. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub related: Vec, + /// Suggested fixes or authoring hints. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub hints: Vec, +} + +impl Diagnostic { + /// Create an error diagnostic. + pub fn error(code: impl Into, span: Option, message: impl Into) -> Self { + Self { + code: code.into(), + severity: Severity::Error, + span, + message: message.into(), + related: Vec::new(), + hints: Vec::new(), + } + } + + /// Create a warning diagnostic. + pub fn warning( + code: impl Into, + span: Option, + message: impl Into, + ) -> Self { + Self { + severity: Severity::Warning, + ..Self::error(code, span, message) + } + } + + /// Add an authoring hint. + pub fn with_hint(mut self, hint: impl Into) -> Self { + self.hints.push(hint.into()); + self + } + + /// Add a related source location. + pub fn with_related(mut self, span: Option, message: impl Into) -> Self { + self.related.push(Related { + span, + message: message.into(), + }); + self + } + + /// Add a related span that is a suitable fix location. + pub fn with_help_span(self, span: Span, message: impl Into) -> Self { + self.with_related(Some(span), message) + } + + /// Whether this diagnostic is fatal. + pub fn is_error(&self) -> bool { + self.severity == Severity::Error + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn diagnostic_json_shape_is_stable() { + let diag = Diagnostic::error(codes::EXPR_PARSE, Some(Span::new(3, 9)), "bad expression") + .with_hint("use a code span") + .with_related(None, "declared here"); + let json = serde_json::to_value(&diag).unwrap(); + assert_eq!(json["code"], "expr.parse"); + assert_eq!(json["severity"], "error"); + assert_eq!(json["span"]["start"], 3); + assert_eq!(json["hints"][0], "use a code span"); + assert_eq!(json["related"][0]["message"], "declared here"); + // Absent optional fields are omitted rather than null. + let minimal = Diagnostic::error(codes::INTERNAL, None, "oops"); + let json = serde_json::to_value(&minimal).unwrap(); + assert!(json.get("span").is_none()); + assert!(json.get("related").is_none()); + } +} diff --git a/crates/marqdo-value/src/error.rs b/crates/marqdo-value/src/error.rs new file mode 100644 index 0000000..b48335f --- /dev/null +++ b/crates/marqdo-value/src/error.rs @@ -0,0 +1,175 @@ +//! Structured runtime errors with source spans and call frames. + +use crate::codes; +use crate::diagnostic::Diagnostic; +use marqdo_span::Span; + +/// Category of a runtime failure. Each category maps to a stable diagnostic +/// code so that CI and agents can branch on codes instead of message wording. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ErrorCategory { + /// A value had the wrong type for the operation. + Type, + /// A call supplied the wrong number of arguments. + Arity, + /// A name is not bound in any reachable scope. + UnknownSymbol, + /// A name is bound but may be read before assignment. + Uninitialized, + /// Division or modulo by zero. + DivisionByZero, + /// A value was used as a function but is not callable. + NotCallable, + /// A map key or record field does not exist. + UnknownField, + /// A list/map index is out of bounds. + IndexOutOfBounds, + /// A resource budget was exhausted (fuel, stack, output size). + ResourceExhausted, + /// A capability check denied the operation. + PermissionDenied, + /// A foreign language kernel is unavailable. + KernelUnavailable, + /// The requested math operation is unsupported. + MathUnsupported, + /// Plugin ABI negotiation failed. + PluginAbi, + /// A plugin reported an execution failure. + PluginFailure, + /// A foreign kernel failed (non-zero exit, protocol violation). + ForeignFailure, + /// A host operation failed for an environmental reason. + HostError, + /// Internal invariant violation. + Internal, +} + +impl ErrorCategory { + /// Stable diagnostic code for this category. + pub const fn code(self) -> &'static str { + match self { + ErrorCategory::Type => codes::RUNTIME_TYPE, + ErrorCategory::Arity => codes::CALL_ARITY, + ErrorCategory::UnknownSymbol => codes::SYMBOL_UNKNOWN, + ErrorCategory::Uninitialized => codes::SYMBOL_UNINITIALIZED, + ErrorCategory::DivisionByZero => "runtime.division_by_zero", + ErrorCategory::NotCallable => "call.not_callable", + ErrorCategory::UnknownField => "runtime.unknown_field", + ErrorCategory::IndexOutOfBounds => codes::RUNTIME_INDEX, + ErrorCategory::ResourceExhausted => codes::RESOURCE_EXHAUSTED, + ErrorCategory::PermissionDenied => codes::PERMISSION_DENIED, + ErrorCategory::KernelUnavailable => codes::KERNEL_UNAVAILABLE, + ErrorCategory::MathUnsupported => codes::MATH_UNSUPPORTED, + ErrorCategory::PluginAbi => codes::PLUGIN_ABI_MISMATCH, + ErrorCategory::PluginFailure => "plugin.failure", + ErrorCategory::ForeignFailure => "foreign.failure", + ErrorCategory::HostError => "host.error", + ErrorCategory::Internal => codes::INTERNAL, + } + } +} + +/// One entry of the Marqdo call stack. +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +pub struct CallFrame { + /// Canonical function name (or `
` for the entry function). + pub function: String, + /// Source location of the call site in the caller. + #[serde(skip_serializing_if = "Option::is_none")] + pub span: Option, +} + +/// A structured runtime failure. +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +pub struct RuntimeError { + /// Failure category. + pub category: ErrorCategory, + /// Location in the source that caused the failure. + #[serde(skip_serializing_if = "Option::is_none")] + pub span: Option, + /// Human readable message. + pub message: String, + /// Call frames from innermost to outermost. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub frames: Vec, + /// Underlying cause (e.g. a host or foreign kernel error). + #[serde(skip_serializing_if = "Option::is_none")] + pub cause: Option>, + /// Effect trace recorded by the host, when available. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub effect_trace: Vec, +} + +impl RuntimeError { + /// Create a new runtime error. + pub fn new(category: ErrorCategory, span: Option, message: impl Into) -> Self { + Self { + category, + span, + message: message.into(), + frames: Vec::new(), + cause: None, + effect_trace: Vec::new(), + } + } + + /// Convenience constructor for type errors. + pub fn type_error(span: Option, message: impl Into) -> Self { + Self::new(ErrorCategory::Type, span, message) + } + + /// Record a call frame (called while unwinding). + pub fn push_frame(&mut self, function: impl Into, span: Option) { + self.frames.push(CallFrame { + function: function.into(), + span, + }); + } + + /// Add a cause. + pub fn with_cause(mut self, cause: RuntimeError) -> Self { + self.cause = Some(Box::new(cause)); + self + } + + /// The stable diagnostic code for this failure. + pub fn code(&self) -> &'static str { + self.category.code() + } + + /// Render as a user facing diagnostic. + pub fn to_diagnostic(&self) -> Diagnostic { + let mut diag = Diagnostic::error(self.code(), self.span, self.message.clone()); + for frame in &self.frames { + diag = diag.with_related(frame.span, format!("in function `{}`", frame.function)); + } + if let Some(cause) = &self.cause { + diag = diag.with_related(cause.span, format!("caused by: {}", cause.message)); + } + diag + } +} + +impl std::fmt::Display for RuntimeError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "{}: {}", self.code(), self.message) + } +} + +impl std::error::Error for RuntimeError {} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn frames_are_rendered_as_related_diagnostics() { + let mut err = RuntimeError::type_error(Some(Span::new(1, 2)), "expected Bool"); + err.push_frame("阶乘", None); + let diag = err.to_diagnostic(); + assert_eq!(diag.code, "runtime.type"); + assert_eq!(diag.related.len(), 1); + assert_eq!(diag.related[0].message, "in function `阶乘`"); + } +} diff --git a/crates/marqdo-value/src/lib.rs b/crates/marqdo-value/src/lib.rs new file mode 100644 index 0000000..33712e3 --- /dev/null +++ b/crates/marqdo-value/src/lib.rs @@ -0,0 +1,17 @@ +//! Marqdo language values, diagnostics and errors. +//! +//! This crate is the shared data contract between the frontend, the IR, the +//! runtime and the host boundary. It has no dependency on Markdown parsing, +//! process execution or the CLI so that every layer can agree on values and +//! structured failures without creating dependency cycles. + +pub mod diagnostic; +pub mod error; +pub mod value; +pub mod wire; + +pub use diagnostic::{codes, Diagnostic, Related, Severity}; +pub use error::{CallFrame, ErrorCategory, RuntimeError}; +pub use marqdo_span::{LineCol, Span}; +pub use value::{CodeValue, FormulaValue, FunctionRef, Table, Value}; +pub use wire::{from_wire, to_wire, WireError, WIRE_VERSION}; diff --git a/crates/marqdo-value/src/value.rs b/crates/marqdo-value/src/value.rs new file mode 100644 index 0000000..0f28ef5 --- /dev/null +++ b/crates/marqdo-value/src/value.rs @@ -0,0 +1,352 @@ +//! The Marqdo value model. +//! +//! Values are deliberately explicit: there is no truthiness and no implicit +//! string/number conversion. `Unit` (no result) and `None` (explicit empty +//! value) are distinct, as required by the language specification. + +use std::collections::BTreeMap; + +use num_bigint::BigInt; +use num_traits::ToPrimitive; +use serde::{Deserialize, Serialize}; + +use marqdo_span::Span; + +/// A structured GFM table value. +#[derive(Debug, Clone, PartialEq)] +pub struct Table { + /// Column headers in order. + pub header: Vec, + /// Data rows; every row has exactly `header.len()` cells. + pub rows: Vec>, +} + +/// An inert `Formula` value: LaTeX source plus provenance. Parsing and +/// evaluation are separate, explicit operations performed by the math kernel. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct FormulaValue { + /// Raw LaTeX (or math extension) source, without delimiters. + pub latex: String, + /// Canonical owning unit, when the formula came from a document heading range. + #[serde(skip_serializing_if = "Option::is_none")] + pub unit: Option, + /// Whether the formula was display math (`$$...$$`). + pub display: bool, + /// Source location of the formula node. + #[serde(skip_serializing_if = "Option::is_none")] + pub span: Option, +} + +/// An inert `Code` value: a fenced code block plus provenance. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct CodeValue { + /// Fence info string language (empty for plain fences). + pub language: String, + /// Raw source inside the fence. + pub source: String, + /// Canonical owning unit, when the fence came from a document heading range. + #[serde(skip_serializing_if = "Option::is_none")] + pub unit: Option, + /// Lowercase hex SHA-256 of `source`. + pub content_hash: String, + /// Source location of the code block. + #[serde(skip_serializing_if = "Option::is_none")] + pub span: Option, +} + +/// A reference to a named function in a module. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct FunctionRef { + /// Canonical module identity (project relative path or imported alias). + pub module: String, + /// Canonical function name within the module. + pub name: String, +} + +/// A host-owned handle to a loaded plugin export. Handles are opaque; they +/// cannot be forged from wire data. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct PluginHandle { + /// Plugin identifier from its manifest. + pub plugin: String, + /// Export name within the plugin. + pub export: String, + /// Host-assigned generation number. + pub id: u64, +} + +/// A Marqdo runtime value. +#[derive(Debug, Clone, PartialEq)] +pub enum Value { + /// No result (a function that fell through its body). + Unit, + /// Explicit empty value. + None, + /// Boolean. + Bool(bool), + /// Arbitrary precision integer. + Int(BigInt), + /// IEEE-754 double. + Float(f64), + /// Unicode text. + Text(String), + /// Ordered sequence. + List(Vec), + /// String-keyed record with deterministic key order. + Map(BTreeMap), + /// Structured table. + Table(Table), + /// Inert formula. + Formula(FormulaValue), + /// Inert code fence. + Code(CodeValue), + /// Reference to a named function. + FunctionRef(FunctionRef), + /// Host-owned plugin handle. + PluginHandle(PluginHandle), +} + +impl Value { + /// Stable type name used by diagnostics and wire messages. + pub const fn type_name(&self) -> &'static str { + match self { + Value::Unit => "Unit", + Value::None => "None", + Value::Bool(_) => "Bool", + Value::Int(_) => "Int", + Value::Float(_) => "Float", + Value::Text(_) => "Text", + Value::List(_) => "List", + Value::Map(_) => "Map", + Value::Table(_) => "Table", + Value::Formula(_) => "Formula", + Value::Code(_) => "Code", + Value::FunctionRef(_) => "FunctionRef", + Value::PluginHandle(_) => "PluginHandle", + } + } + + /// Construct an integer from an `i64`. + pub fn int(value: i64) -> Self { + Value::Int(BigInt::from(value)) + } + + /// Construct a text value. + pub fn text(value: impl Into) -> Self { + Value::Text(value.into()) + } + + /// Whether the value is the boolean `true`. + pub fn is_true(&self) -> Option { + match self { + Value::Bool(b) => Some(*b), + _ => None, + } + } + + /// User-facing rendering used by the host `print` operation. + /// + /// Strings print unquoted (like a scripting language), collections use a + /// deterministic Rust-like representation so that output is reproducible. + pub fn display(&self) -> String { + match self { + Value::Unit => "Unit".to_string(), + Value::None => "None".to_string(), + Value::Bool(b) => b.to_string(), + Value::Int(i) => i.to_string(), + Value::Float(f) => format_float(*f), + Value::Text(t) => t.clone(), + other => other.repr(), + } + } + + /// Debug-style rendering with type-faithful literals. + pub fn repr(&self) -> String { + match self { + Value::Unit => "Unit".to_string(), + Value::None => "None".to_string(), + Value::Bool(b) => b.to_string(), + Value::Int(i) => i.to_string(), + Value::Float(f) => format_float(*f), + Value::Text(t) => format!("{t:?}"), + Value::List(items) => { + let inner = items.iter().map(Value::repr).collect::>().join(", "); + format!("[{inner}]") + } + Value::Map(map) => { + let inner = map + .iter() + .map(|(k, v)| format!("{}: {}", k, v.repr())) + .collect::>() + .join(", "); + format!("{{{inner}}}") + } + Value::Table(table) => { + let header = table.header.join(" | "); + let rows = table + .rows + .iter() + .map(|row| { + row.iter() + .map(Value::display) + .collect::>() + .join(" | ") + }) + .collect::>() + .join("; "); + format!("Table[{header}]{{{rows}}}") + } + Value::Formula(f) => format!("Formula({:?})", f.latex), + Value::Code(c) => format!("Code({:?}, {} bytes)", c.language, c.source.len()), + Value::FunctionRef(r) => format!("FunctionRef({}::{})", r.module, r.name), + Value::PluginHandle(h) => format!("PluginHandle({}::{})", h.plugin, h.export), + } + } + + /// Structural equality that treats `Float` NaN as unequal to itself while + /// keeping `Int`/`Float` distinct. + pub fn same_value(&self, other: &Value) -> bool { + self == other + } +} + +/// Format a float without exposing the internal `f64` Debug formatting +/// (`1.0` vs `1`); NaN and infinities get explicit spellings. +pub fn format_float(f: f64) -> String { + if f.is_nan() { + "NaN".to_string() + } else if f.is_infinite() { + if f.is_sign_negative() { + "-Infinity".to_string() + } else { + "Infinity".to_string() + } + } else if f == 0.0 && f.is_sign_negative() { + "-0.0".to_string() + } else { + // Rust's Display for f64 produces the shortest representation that + // round-trips, and always keeps a decimal point for integral values + // when using `{:?}`; we use `{}` to keep the common case short but + // preserve `.0` so that the value still reads as a Float. + let s = format!("{f}"); + if s.contains('.') || s.contains('e') || s.contains('E') { + s + } else { + format!("{s}.0") + } + } +} + +impl std::fmt::Display for Value { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(&self.display()) + } +} + +impl From for Value { + fn from(value: bool) -> Self { + Value::Bool(value) + } +} + +impl From<&str> for Value { + fn from(value: &str) -> Self { + Value::Text(value.to_string()) + } +} + +impl From for Value { + fn from(value: String) -> Self { + Value::Text(value) + } +} + +impl From for Value { + fn from(value: i64) -> Self { + Value::int(value) + } +} + +impl From> for Value { + fn from(value: Vec) -> Self { + Value::List(value) + } +} + +impl FromIterator for Value { + fn from_iter>(iter: T) -> Self { + Value::List(iter.into_iter().collect()) + } +} + +/// Convert a float to an exact integer when it is integral; used by explicit +/// math coercions, never implicitly by the evaluator. +pub fn float_to_bigint(f: f64) -> Option { + if f.is_finite() && f.fract() == 0.0 { + // Route through the decimal string so that values beyond i64 range do + // not lose precision. + let s = format!("{f:.0}"); + s.parse().ok() + } else { + None + } +} + +/// Convert an integer to `f64` when it round-trips exactly. +pub fn bigint_to_exact_f64(i: &BigInt) -> Option { + let f = i.to_f64()?; + if float_to_bigint(f).as_ref() == Some(i) { + Some(f) + } else { + None + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn unit_and_none_are_distinct() { + assert_ne!(Value::Unit, Value::None); + assert_eq!(Value::Unit.type_name(), "Unit"); + assert_eq!(Value::None.type_name(), "None"); + } + + #[test] + fn display_is_stable() { + assert_eq!(Value::int(42).display(), "42"); + assert_eq!(Value::Float(2.0).display(), "2.0"); + assert_eq!(Value::Text("hi".into()).display(), "hi"); + assert_eq!(Value::Text("hi".into()).repr(), "\"hi\""); + assert_eq!( + Value::List(vec![Value::int(1), Value::Unit]).display(), + "[1, Unit]" + ); + } + + #[test] + fn big_integers_are_arbitrary_precision() { + let big: BigInt = "123456789012345678901234567890".parse().unwrap(); + let value = Value::Int(big.clone()); + assert_eq!(value.display(), "123456789012345678901234567890"); + assert_eq!( + big + BigInt::from(1), + "123456789012345678901234567891".parse().unwrap() + ); + } + + #[test] + fn float_to_bigint_requires_integral_value() { + assert_eq!(float_to_bigint(2.0), Some(BigInt::from(2))); + assert_eq!(float_to_bigint(2.5), None); + assert_eq!( + bigint_to_exact_f64(&BigInt::from(9007199254740992i64)), + Some(9007199254740992.0) + ); + assert_eq!( + bigint_to_exact_f64(&BigInt::from(9007199254740993i64)), + None + ); + } +} diff --git a/crates/marqdo-value/src/wire.rs b/crates/marqdo-value/src/wire.rs new file mode 100644 index 0000000..e53f4e8 --- /dev/null +++ b/crates/marqdo-value/src/wire.rs @@ -0,0 +1,415 @@ +//! Versioned, type-tagged JSON wire format for values crossing ABI, worker IPC +//! and foreign-kernel boundaries. +//! +//! JSON numbers cannot represent arbitrary precision integers or special +//! floats faithfully, so every value carries an explicit `type` tag and +//! integers are encoded as decimal strings. This is the single canonical +//! exchange format required by the specification (`spec/value-wire.md`). + +use std::collections::BTreeMap; + +use num_bigint::BigInt; +use serde_json::{json, Map, Value as Json}; + +use crate::value::{CodeValue, FormulaValue, FunctionRef, PluginHandle, Table, Value}; +use marqdo_span::Span; + +/// Current wire protocol version. +pub const WIRE_VERSION: u32 = 1; + +/// Limits applied while decoding untrusted wire data. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct WireLimits { + /// Maximum nesting depth. + pub max_depth: usize, + /// Maximum number of elements in a list. + pub max_items: usize, + /// Maximum number of bytes in a single string. + pub max_string_bytes: usize, +} + +impl Default for WireLimits { + fn default() -> Self { + Self { + max_depth: 64, + max_items: 1_000_000, + max_string_bytes: 16 * 1024 * 1024, + } + } +} + +/// Failure while decoding or encoding wire data. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum WireError { + /// The `type` tag is missing or unknown. + UnknownType(String), + /// A required field is missing. + MissingField(&'static str), + /// A field has the wrong JSON type or an invalid value. + Invalid(String), + /// Nesting or size limits were exceeded. + LimitExceeded(&'static str), +} + +impl std::fmt::Display for WireError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + WireError::UnknownType(t) => write!(f, "unknown wire value type `{t}`"), + WireError::MissingField(field) => write!(f, "missing wire field `{field}`"), + WireError::Invalid(msg) => write!(f, "invalid wire value: {msg}"), + WireError::LimitExceeded(what) => write!(f, "wire limit exceeded: {what}"), + } + } +} + +impl std::error::Error for WireError {} + +/// Encode a value as the canonical wire representation. +pub fn to_wire(value: &Value) -> Json { + encode(value) +} + +fn encode(value: &Value) -> Json { + match value { + Value::Unit => json!({"type": "unit"}), + Value::None => json!({"type": "none"}), + Value::Bool(b) => json!({"type": "bool", "value": b}), + Value::Int(i) => json!({"type": "int", "decimal": i.to_string()}), + Value::Float(f) => { + if f.is_nan() { + json!({"type": "float", "special": "nan"}) + } else if f.is_infinite() { + json!({"type": "float", "special": if f.is_sign_negative() { "-infinity" } else { "infinity" }}) + } else { + json!({"type": "float", "value": f}) + } + } + Value::Text(t) => json!({"type": "text", "value": t}), + Value::List(items) => json!({ + "type": "list", + "items": items.iter().map(encode).collect::>(), + }), + Value::Map(entries) => { + let mut map = Map::new(); + for (key, val) in entries { + map.insert(key.clone(), encode(val)); + } + json!({"type": "map", "entries": Json::Object(map)}) + } + Value::Table(table) => json!({ + "type": "table", + "header": table.header, + "rows": table + .rows + .iter() + .map(|row| row.iter().map(encode).collect::>()) + .collect::>(), + }), + Value::Formula(formula) => { + let mut obj = json!({ + "type": "formula", + "latex": formula.latex, + "display": formula.display, + }); + if let Some(unit) = &formula.unit { + obj["unit"] = Json::String(unit.clone()); + } + if let Some(span) = formula.span { + obj["span"] = encode_span(span); + } + obj + } + Value::Code(code) => { + let mut obj = json!({ + "type": "code", + "language": code.language, + "source": code.source, + "content_hash": code.content_hash, + }); + if let Some(unit) = &code.unit { + obj["unit"] = Json::String(unit.clone()); + } + if let Some(span) = code.span { + obj["span"] = encode_span(span); + } + obj + } + Value::FunctionRef(func) => json!({ + "type": "function_ref", + "module": func.module, + "name": func.name, + }), + Value::PluginHandle(handle) => json!({ + "type": "plugin_handle", + "plugin": handle.plugin, + "export": handle.export, + "id": handle.id, + }), + } +} + +fn encode_span(span: Span) -> Json { + json!({"start": span.start, "end": span.end}) +} + +/// Decode a value from wire data using default limits. +pub fn from_wire(json: &Json) -> Result { + from_wire_with_limits(json, WireLimits::default()) +} + +/// Decode a value from wire data with explicit limits. +pub fn from_wire_with_limits(json: &Json, limits: WireLimits) -> Result { + decode(json, 0, &limits) +} + +fn decode(json: &Json, depth: usize, limits: &WireLimits) -> Result { + if depth > limits.max_depth { + return Err(WireError::LimitExceeded("nesting depth")); + } + let obj = json + .as_object() + .ok_or_else(|| WireError::Invalid("value must be a JSON object".into()))?; + let type_tag = obj + .get("type") + .and_then(Json::as_str) + .ok_or_else(|| WireError::MissingField("type"))?; + let require = |field: &'static str| obj.get(field).ok_or(WireError::MissingField(field)); + match type_tag { + "unit" => Ok(Value::Unit), + "none" => Ok(Value::None), + "bool" => require("value")? + .as_bool() + .map(Value::Bool) + .ok_or_else(|| WireError::Invalid("bool.value must be a boolean".into())), + "int" => { + let decimal = require("decimal")? + .as_str() + .ok_or_else(|| WireError::Invalid("int.decimal must be a string".into()))?; + decimal + .parse::() + .map(Value::Int) + .map_err(|_| WireError::Invalid(format!("invalid integer `{decimal}`"))) + } + "float" => { + if let Some(special) = obj.get("special").and_then(Json::as_str) { + let f = match special { + "nan" => f64::NAN, + "infinity" => f64::INFINITY, + "-infinity" => f64::NEG_INFINITY, + other => { + return Err(WireError::Invalid(format!( + "unknown float special `{other}`" + ))) + } + }; + return Ok(Value::Float(f)); + } + require("value")? + .as_f64() + .map(Value::Float) + .ok_or_else(|| WireError::Invalid("float.value must be a number".into())) + } + "text" => { + let text = require("value")? + .as_str() + .ok_or_else(|| WireError::Invalid("text.value must be a string".into()))?; + if text.len() > limits.max_string_bytes { + return Err(WireError::LimitExceeded("text length")); + } + Ok(Value::Text(text.to_string())) + } + "list" => { + let items = require("items")? + .as_array() + .ok_or_else(|| WireError::Invalid("list.items must be an array".into()))?; + if items.len() > limits.max_items { + return Err(WireError::LimitExceeded("list length")); + } + let decoded = items + .iter() + .map(|item| decode(item, depth + 1, limits)) + .collect::, _>>()?; + Ok(Value::List(decoded)) + } + "map" => { + let entries = require("entries")? + .as_object() + .ok_or_else(|| WireError::Invalid("map.entries must be an object".into()))?; + if entries.len() > limits.max_items { + return Err(WireError::LimitExceeded("map length")); + } + let mut map = BTreeMap::new(); + for (key, val) in entries { + if key.len() > limits.max_string_bytes { + return Err(WireError::LimitExceeded("map key length")); + } + map.insert(key.clone(), decode(val, depth + 1, limits)?); + } + Ok(Value::Map(map)) + } + "table" => { + let header = require("header")? + .as_array() + .ok_or_else(|| WireError::Invalid("table.header must be an array".into()))? + .iter() + .map(|cell| { + cell.as_str().map(str::to_string).ok_or_else(|| { + WireError::Invalid("table.header cells must be strings".into()) + }) + }) + .collect::, _>>()?; + let rows = require("rows")? + .as_array() + .ok_or_else(|| WireError::Invalid("table.rows must be an array".into()))? + .iter() + .map(|row| { + let cells = row + .as_array() + .ok_or_else(|| WireError::Invalid("table rows must be arrays".into()))?; + if cells.len() != header.len() { + return Err(WireError::Invalid( + "table row length does not match header".into(), + )); + } + cells + .iter() + .map(|cell| decode(cell, depth + 1, limits)) + .collect::, _>>() + }) + .collect::, _>>()?; + Ok(Value::Table(Table { header, rows })) + } + "formula" => Ok(Value::Formula(FormulaValue { + latex: require("latex")? + .as_str() + .ok_or_else(|| WireError::Invalid("formula.latex must be a string".into()))? + .to_string(), + display: obj.get("display").and_then(Json::as_bool).unwrap_or(false), + unit: optional_string(obj, "unit")?, + span: optional_span(obj)?, + })), + "code" => Ok(Value::Code(CodeValue { + language: optional_string(obj, "language")?.unwrap_or_default(), + source: require("source")? + .as_str() + .ok_or_else(|| WireError::Invalid("code.source must be a string".into()))? + .to_string(), + unit: optional_string(obj, "unit")?, + content_hash: optional_string(obj, "content_hash")?.unwrap_or_default(), + span: optional_span(obj)?, + })), + "function_ref" => Ok(Value::FunctionRef(FunctionRef { + module: require("module")? + .as_str() + .ok_or_else(|| WireError::Invalid("function_ref.module must be a string".into()))? + .to_string(), + name: require("name")? + .as_str() + .ok_or_else(|| WireError::Invalid("function_ref.name must be a string".into()))? + .to_string(), + })), + "plugin_handle" => Ok(Value::PluginHandle(PluginHandle { + plugin: require("plugin")? + .as_str() + .ok_or_else(|| WireError::Invalid("plugin_handle.plugin must be a string".into()))? + .to_string(), + export: require("export")? + .as_str() + .ok_or_else(|| WireError::Invalid("plugin_handle.export must be a string".into()))? + .to_string(), + id: require("id")? + .as_u64() + .ok_or_else(|| WireError::Invalid("plugin_handle.id must be an integer".into()))?, + })), + other => Err(WireError::UnknownType(other.to_string())), + } +} + +fn optional_string(obj: &Map, field: &str) -> Result, WireError> { + match obj.get(field) { + None | Some(Json::Null) => Ok(None), + Some(Json::String(s)) => Ok(Some(s.clone())), + Some(_) => Err(WireError::Invalid(format!("{field} must be a string"))), + } +} + +fn optional_span(obj: &Map) -> Result, WireError> { + let Some(span) = obj.get("span") else { + return Ok(None); + }; + let start = span + .get("start") + .and_then(Json::as_u64) + .ok_or_else(|| WireError::Invalid("span.start must be an integer".into()))?; + let end = span + .get("end") + .and_then(Json::as_u64) + .ok_or_else(|| WireError::Invalid("span.end must be an integer".into()))?; + Ok(Some(Span::new(start as usize, end as usize))) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn roundtrip(value: Value) { + let wire = to_wire(&value); + let decoded = from_wire(&wire).expect("decode"); + assert_eq!(decoded, value); + } + + #[test] + fn scalar_roundtrip() { + roundtrip(Value::Unit); + roundtrip(Value::None); + roundtrip(Value::Bool(true)); + roundtrip(Value::int(-7)); + roundtrip(Value::Float(1.5)); + roundtrip(Value::Float(-0.0)); + roundtrip(Value::Text("你好\n".into())); + roundtrip(Value::List(vec![Value::int(1), Value::text("x")])); + let mut map = BTreeMap::new(); + map.insert("a".to_string(), Value::Bool(false)); + roundtrip(Value::Map(map)); + roundtrip(Value::Table(Table { + header: vec!["x".into()], + rows: vec![vec![Value::int(1)]], + })); + } + + #[test] + fn big_integers_keep_all_digits() { + let big: BigInt = "123456789012345678901234567890123456789".parse().unwrap(); + let wire = to_wire(&Value::Int(big)); + assert_eq!(wire["decimal"], "123456789012345678901234567890123456789"); + assert!(matches!(from_wire(&wire), Ok(Value::Int(_)))); + } + + #[test] + fn special_floats_are_tagged() { + assert_eq!(to_wire(&Value::Float(f64::NAN))["special"], "nan"); + assert_eq!(to_wire(&Value::Float(f64::INFINITY))["special"], "infinity"); + let decoded = from_wire(&to_wire(&Value::Float(f64::NEG_INFINITY))).unwrap(); + assert!(matches!(decoded, Value::Float(f) if f == f64::NEG_INFINITY)); + } + + #[test] + fn untrusted_wire_is_validated() { + assert_eq!( + from_wire(&json!({"type": "int", "decimal": "not-a-number"})), + Err(WireError::Invalid("invalid integer `not-a-number`".into())) + ); + assert_eq!( + from_wire(&json!({"type": "mystery"})), + Err(WireError::UnknownType("mystery".into())) + ); + let deep = (0..100).fold( + json!({"type": "unit"}), + |acc, _| json!({"type": "list", "items": [acc]}), + ); + assert_eq!( + from_wire(&deep), + Err(WireError::LimitExceeded("nesting depth")) + ); + } +}