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.
This commit is contained in:
cflmy committed 2026-11-20 10:24:13 +08:00
1 parent df878b434a
commit 1520244923
6 files changed
+1968

No files matched your search

Generated
+822
View File
@@ -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"
+187
View File
@@ -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<Span>,
/// 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<Span>,
/// 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<Related>,
/// Suggested fixes or authoring hints.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub hints: Vec<String>,
}
impl Diagnostic {
/// Create an error diagnostic.
pub fn error(code: impl Into<String>, span: Option<Span>, message: impl Into<String>) -> 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<String>,
span: Option<Span>,
message: impl Into<String>,
) -> Self {
Self {
severity: Severity::Warning,
..Self::error(code, span, message)
}
}
/// Add an authoring hint.
pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
self.hints.push(hint.into());
self
}
/// Add a related source location.
pub fn with_related(mut self, span: Option<Span>, message: impl Into<String>) -> 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<String>) -> 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());
}
}
+175
View File
@@ -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 `<main>` 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<Span>,
}
/// 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<Span>,
/// Human readable message.
pub message: String,
/// Call frames from innermost to outermost.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub frames: Vec<CallFrame>,
/// Underlying cause (e.g. a host or foreign kernel error).
#[serde(skip_serializing_if = "Option::is_none")]
pub cause: Option<Box<RuntimeError>>,
/// Effect trace recorded by the host, when available.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub effect_trace: Vec<String>,
}
impl RuntimeError {
/// Create a new runtime error.
pub fn new(category: ErrorCategory, span: Option<Span>, message: impl Into<String>) -> 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<Span>, message: impl Into<String>) -> Self {
Self::new(ErrorCategory::Type, span, message)
}
/// Record a call frame (called while unwinding).
pub fn push_frame(&mut self, function: impl Into<String>, span: Option<Span>) {
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 `阶乘`");
}
}
+17
View File
@@ -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};
+352
View File
@@ -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<String>,
/// Data rows; every row has exactly `header.len()` cells.
pub rows: Vec<Vec<Value>>,
}
/// 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<String>,
/// 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<Span>,
}
/// 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<String>,
/// 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<Span>,
}
/// 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<Value>),
/// String-keyed record with deterministic key order.
Map(BTreeMap<String, Value>),
/// 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<String>) -> Self {
Value::Text(value.into())
}
/// Whether the value is the boolean `true`.
pub fn is_true(&self) -> Option<bool> {
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::<Vec<_>>().join(", ");
format!("[{inner}]")
}
Value::Map(map) => {
let inner = map
.iter()
.map(|(k, v)| format!("{}: {}", k, v.repr()))
.collect::<Vec<_>>()
.join(", ");
format!("{{{inner}}}")
}
Value::Table(table) => {
let header = table.header.join(" | ");
let rows = table
.rows
.iter()
.map(|row| {
row.iter()
.map(Value::display)
.collect::<Vec<_>>()
.join(" | ")
})
.collect::<Vec<_>>()
.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<bool> 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<String> for Value {
fn from(value: String) -> Self {
Value::Text(value)
}
}
impl From<i64> for Value {
fn from(value: i64) -> Self {
Value::int(value)
}
}
impl From<Vec<Value>> for Value {
fn from(value: Vec<Value>) -> Self {
Value::List(value)
}
}
impl FromIterator<Value> for Value {
fn from_iter<T: IntoIterator<Item = Value>>(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<BigInt> {
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<f64> {
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
);
}
}
+415
View File
@@ -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::<Vec<_>>(),
}),
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::<Vec<_>>())
.collect::<Vec<_>>(),
}),
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<Value, WireError> {
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<Value, WireError> {
decode(json, 0, &limits)
}
fn decode(json: &Json, depth: usize, limits: &WireLimits) -> Result<Value, WireError> {
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::<BigInt>()
.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::<Result<Vec<_>, _>>()?;
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::<Result<Vec<_>, _>>()?;
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::<Result<Vec<_>, _>>()
})
.collect::<Result<Vec<_>, _>>()?;
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<String, Json>, field: &str) -> Result<Option<String>, 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<String, Json>) -> Result<Option<Span>, 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"))
);
}
}