From f6c3efa849da620c68e2711dfb6695ae0783504e Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 10:43:50 +0800 Subject: [PATCH] feat(math,foreign): native formula kernel and isolated Python/Node kernels Marqdo-math: limited, documented LaTeX-subset kernel (blueprint section 5). - Exact BigRational arithmetic, structured Float only for irrational results; Int result when exact; bounds on exponents, source size, AST nodes and result bits so hostile input cannot hang or exhaust memory. - Supports numbers, Unicode identifiers, \pi/\e, + - * / ^, \frac, \sqrt, \cdot/\times, braces, parentheses, one '=' equation, and linear solving for a target variable (F=ma solved for F/m/a). - Unsupported constructs are structured errors; the kernel never claims any mathematical proof. Marqdo-foreign: explicit kernels (blueprint section 6). - run/call/detect only; reading a document never spawns a process. - Direct exec of python3/python/node with a temp program file, clear env, private cwd, JSON request envelope on stdin, captured bounded stdout/stderr, wall-clock timeout with kill, typed wire decoding for call, structured ForeignError for spawn/protocol/timeout/oversized output. - Process isolation only: crate docs state this is not a strict OS sandbox. --- crates/marqdo-foreign/src/lib.rs | 819 ++++++++++++++++++++++++ crates/marqdo-foreign/tests/kernels.rs | 374 +++++++++++ crates/marqdo-math/Cargo.toml | 2 - crates/marqdo-math/src/ast.rs | 394 ++++++++++++ crates/marqdo-math/src/error.rs | 146 +++++ crates/marqdo-math/src/eval.rs | 695 ++++++++++++++++++++ crates/marqdo-math/src/lib.rs | 171 +++++ crates/marqdo-math/src/parse.rs | 837 +++++++++++++++++++++++++ crates/marqdo-math/tests/kernel.rs | 596 ++++++++++++++++++ 9 files changed, 4032 insertions(+), 2 deletions(-) create mode 100644 crates/marqdo-foreign/src/lib.rs create mode 100644 crates/marqdo-foreign/tests/kernels.rs create mode 100644 crates/marqdo-math/src/ast.rs create mode 100644 crates/marqdo-math/src/error.rs create mode 100644 crates/marqdo-math/src/eval.rs create mode 100644 crates/marqdo-math/src/lib.rs create mode 100644 crates/marqdo-math/src/parse.rs create mode 100644 crates/marqdo-math/tests/kernel.rs diff --git a/crates/marqdo-foreign/src/lib.rs b/crates/marqdo-foreign/src/lib.rs new file mode 100644 index 0000000..08b33d6 --- /dev/null +++ b/crates/marqdo-foreign/src/lib.rs @@ -0,0 +1,819 @@ +//! Explicit foreign code kernels (Python/Node). +//! +//! A fenced `python` or `javascript` code block is an inert [`Code`] value in +//! Marqdo. Nothing in this crate is ever spawned while reading, parsing or +//! rendering a document: a process is created **only** when the host calls +//! [`run`] or [`call`] after the capability check succeeded. +//! +//! Every execution is one-shot and isolated: +//! +//! * the kernel program is written to a private, uniquely named file under +//! [`std::env::temp_dir`] (`.py` or `.js`), the child is started by direct +//! `argv` exec (no shell, no string interpolation) and its working directory +//! is a fresh private temporary directory so relative writes never touch the +//! project; modern Node performs syntax detection on `.js`, so both ESM +//! `import` and CommonJS `require` kernels are supported; +//! * stdin carries the versioned request envelope +//! `{"wire_version":1,"kind":"request","input":}`; +//! * stdout and stderr are always piped and captured, never inherited; +//! * the environment is cleared except for `PATH`, so Marqdo secrets do not +//! leak into the kernel by default; +//! * a wall-clock deadline is enforced by polling `try_wait` and killing the +//! child on expiry, and a shared byte budget aborts output flooding; +//! * the temporary program file and working directory are removed afterwards, +//! including on error paths. +//! +//! [`run`] returns captured output as data. [`call`] additionally requires +//! stdout to be exactly one versioned wire value (see +//! [`marqdo_value::from_wire`]); any stdout pollution or trailing noise is a +//! [`ForeignError::Protocol`] error rather than something silently ignored. +//! +//! This is process isolation, not a security sandbox. The `strict` sandbox +//! mode additionally needs OS-level isolation (namespaces/seccomp/cgroups or +//! platform equivalents) as described in the development blueprint; this crate +//! does not claim to provide it. +//! +//! [`Code`]: marqdo_value::CodeValue + +use std::fs; +use std::io::{self, Read, Write}; +use std::path::{Path, PathBuf}; +use std::process::{Child, Command, ExitStatus, Stdio}; +use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering}; +use std::sync::{Arc, Mutex}; +use std::thread; +use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; + +use marqdo_value::Value; +use serde_json::Value as Json; + +/// Value of the `kind` field in the stdin request envelope. +pub const REQUEST_KIND: &str = "request"; + +/// Timeout applied to `--version` probing in [`detect`]. +const DETECT_TIMEOUT: Duration = Duration::from_secs(5); + +/// Maximum bytes captured while probing a kernel version. +const DETECT_OUTPUT_LIMIT: usize = 64 * 1024; + +/// Polling interval for `try_wait` while supervising a child. +const POLL_INTERVAL: Duration = Duration::from_millis(2); + +/// How long to wait for the pipe readers after the child was reaped. A +/// misbehaving kernel that leaves a grandchild holding the pipes must not hang +/// the Marqdo host process. +const READER_GRACE: Duration = Duration::from_secs(2); + +static UNIQUE_COUNTER: AtomicU64 = AtomicU64::new(0); + +/// Canonical language names supported by this crate. +pub const SUPPORTED_LANGUAGES: [&str; 2] = ["python", "javascript"]; + +/// Normalize a language alias to its canonical kernel name. +/// +/// Recognized aliases are `python`/`python3`/`py` and +/// `javascript`/`js`/`node`/`nodejs`. The comparison is ASCII +/// case-insensitive and surrounding whitespace is ignored. Unknown languages +/// return `None`. +pub fn normalize_language(language: &str) -> Option<&'static str> { + match language.trim().to_ascii_lowercase().as_str() { + "python" | "python3" | "py" => Some("python"), + "javascript" | "js" | "node" | "nodejs" => Some("javascript"), + _ => None, + } +} + +/// What the host asks a foreign kernel to do. +#[derive(Debug, Clone, PartialEq)] +pub struct RunRequest { + /// Language name or alias (for example `"python3"` or `"js"`). + pub language: String, + /// Program source executed by the kernel. + pub source: String, + /// Optional input value delivered inside the versioned stdin envelope. + pub input: Option, + /// Wall-clock budget for the whole child execution. + pub timeout: Duration, + /// Maximum number of bytes captured across stdout and stderr combined. + pub max_output_bytes: usize, +} + +impl RunRequest { + /// Create a request with conservative defaults: 30 s timeout and 1 MiB of + /// captured output. + pub fn new(language: impl Into, source: impl Into) -> Self { + Self { + language: language.into(), + source: source.into(), + input: None, + timeout: Duration::from_secs(30), + max_output_bytes: 1024 * 1024, + } + } +} + +/// Terminal state of a foreign execution. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum RunStatus { + /// The process exited with status 0 (for [`call`]: and its output decoded). + Success, + /// The process exited non-zero or was terminated by a signal. + Failed, + /// The wall-clock deadline expired and the process was killed. + TimedOut, +} + +impl RunStatus { + /// Stable lowercase name for logging and diagnostics. + pub const fn as_str(self) -> &'static str { + match self { + RunStatus::Success => "success", + RunStatus::Failed => "failed", + RunStatus::TimedOut => "timed_out", + } + } +} + +/// Outcome of one foreign execution. +#[derive(Debug, Clone, PartialEq)] +pub struct RunResult { + /// Success/failure/timeout classification. + pub status: RunStatus, + /// Captured stdout (lossy UTF-8 for [`run`], validated for [`call`]). + pub stdout: String, + /// Captured stderr; preserved even when the kernel fails. + pub stderr: String, + /// Exit code, or `None` when the child was killed by a signal or timed out. + pub exit_code: Option, + /// Measured wall-clock duration of the child execution. + pub duration: Duration, + /// Decoded wire value; only [`call`] sets this on success. + pub value: Option, +} + +/// A detected foreign kernel. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct KernelInfo { + /// Canonical language name (`"python"` or `"javascript"`). + pub language: String, + /// Resolved absolute path of the interpreter executable. + pub program: PathBuf, + /// First line of the interpreter's `--version` output. + pub version: String, +} + +/// Failure while detecting or executing a foreign kernel. +#[derive(Debug, Clone, thiserror::Error)] +pub enum ForeignError { + /// No usable Python/Node interpreter was found on `PATH`. + #[error("foreign kernel `{language}` is unavailable: {hint}")] + KernelUnavailable { + /// Requested (normalized when known) language name. + language: String, + /// Actionable installation guidance. + hint: String, + }, + /// The child process could not be created. + #[error("failed to spawn foreign kernel: {message}")] + Spawn { + /// Operating-system error text. + message: String, + }, + /// A pipe, temporary file or wait operation failed. + #[error("foreign kernel I/O error: {message}")] + Io { + /// Operating-system error text. + message: String, + }, + /// The wall-clock deadline expired; the child was killed. + #[error("foreign kernel exceeded its wall-clock timeout of {seconds} seconds")] + Timeout { + /// Requested timeout, in seconds. + seconds: f64, + }, + /// The kernel violated the stdout wire protocol or sent invalid UTF-8. + #[error("foreign kernel protocol violation: {message}")] + Protocol { + /// What went wrong. + message: String, + }, + /// Captured stdout/stderr exceeded `max_output_bytes`; the child was + /// killed and the partial output dropped. + #[error("foreign kernel output exceeded the {limit} byte limit")] + OutputTooLarge { + /// Configured byte budget. + limit: usize, + }, +} + +/// Detect a kernel for `language` by scanning `PATH`. +/// +/// Candidates are `python3`, then `python` for Python, and `node` for +/// JavaScript. The returned [`KernelInfo::version`] is the first line of the +/// interpreter's `--version` output. Returns `None` for an unknown language or +/// when no working interpreter is installed; detection honors the same +/// cleared-environment rule as execution and is bounded by a short timeout. +pub fn detect(language: &str) -> Option { + let canonical = normalize_language(language)?; + let path_var = std::env::var_os("PATH")?; + for name in program_candidates(canonical) { + for directory in std::env::split_paths(&path_var) { + let program = directory.join(name); + if !is_executable_file(&program) { + continue; + } + if let Some(version) = probe_version(&program) { + return Some(KernelInfo { + language: canonical.to_string(), + program, + version, + }); + } + } + } + None +} + +/// One-shot isolated execution of foreign code. +/// +/// The source is run in a fresh child process. `request.input` is delivered as +/// the versioned JSON envelope on stdin, stdout/stderr are captured, and the +/// following are enforced: `request.timeout` (wall clock) and +/// `request.max_output_bytes` (stdout + stderr combined). +/// +/// A non-zero exit is reported as [`RunStatus::Failed`] with `stderr` +/// preserved, not as an `Err`. Timeouts are reported as +/// [`RunStatus::TimedOut`]. Infrastructure failures (unavailable kernel, spawn +/// failure, exceeding the output budget) are [`ForeignError`]s. +pub fn run(request: &RunRequest) -> Result { + let raw = execute(request)?; + Ok(RunResult { + status: raw.status, + stdout: String::from_utf8_lossy(&raw.stdout).into_owned(), + stderr: String::from_utf8_lossy(&raw.stderr).into_owned(), + exit_code: raw.exit_code, + duration: raw.duration, + value: None, + }) +} + +/// Typed one-shot call, like [`run`] but with a strict stdout wire protocol. +/// +/// On success, stdout must be exactly one versioned wire value object (no +/// log lines, no trailing noise); it is decoded with +/// [`marqdo_value::from_wire`] and stored in [`RunResult::value`]. Any +/// protocol violation is [`ForeignError::Protocol`]. A non-zero exit still +/// returns `Ok` with [`RunStatus::Failed`] and `stderr` preserved so the host +/// can report the kernel's own failure faithfully; a timeout returns +/// [`ForeignError::Timeout`] because no typed value can exist. +pub fn call(request: &RunRequest) -> Result { + let raw = execute(request)?; + match raw.status { + RunStatus::TimedOut => Err(ForeignError::Timeout { + seconds: request.timeout.as_secs_f64(), + }), + RunStatus::Failed => Ok(RunResult { + status: raw.status, + stdout: String::from_utf8_lossy(&raw.stdout).into_owned(), + stderr: String::from_utf8_lossy(&raw.stderr).into_owned(), + exit_code: raw.exit_code, + duration: raw.duration, + value: None, + }), + RunStatus::Success => { + let text = + std::str::from_utf8(&raw.stdout).map_err(|error| ForeignError::Protocol { + message: format!("stdout is not valid UTF-8: {error}"), + })?; + let wire: Json = + serde_json::from_str(text).map_err(|error| ForeignError::Protocol { + message: format!( + "stdout must be exactly one JSON wire value without extra output: {error}" + ), + })?; + let value = marqdo_value::from_wire(&wire).map_err(|error| ForeignError::Protocol { + message: format!("stdout is not a valid marqdo wire value: {error}"), + })?; + Ok(RunResult { + status: RunStatus::Success, + stdout: text.to_string(), + stderr: String::from_utf8_lossy(&raw.stderr).into_owned(), + exit_code: raw.exit_code, + duration: raw.duration, + value: Some(value), + }) + } + } +} + +/// Owned bytes-level result shared by [`run`] and [`call`]. +struct RawRun { + status: RunStatus, + stdout: Vec, + stderr: Vec, + exit_code: Option, + duration: Duration, +} + +fn execute(request: &RunRequest) -> Result { + let canonical = + normalize_language(&request.language).ok_or_else(|| ForeignError::KernelUnavailable { + language: request.language.clone(), + hint: format!( + "supported languages are `python` (aliases: python3, py) and \ + `javascript` (aliases: js, node); `{}` is not a foreign kernel", + request.language + ), + })?; + let program = find_program(canonical).ok_or_else(|| ForeignError::KernelUnavailable { + language: canonical.to_string(), + hint: kernel_hint(canonical).to_string(), + })?; + + let artifacts = TempArtifacts::create(canonical)?; + artifacts.write_program(&request.source)?; + let payload = request_envelope(request)?; + + let mut command = Command::new(&program); + command + .arg(&artifacts.program_path) + .current_dir(&artifacts.work_dir) + .env_clear(); + if let Some(path) = std::env::var_os("PATH") { + command.env("PATH", path); + } + + let captured = spawn_and_capture( + &mut command, + request.timeout, + request.max_output_bytes, + Some(payload), + )?; + + let (status, exit_code) = match captured.outcome { + WaitOutcome::Exited(exit) => { + let status = if exit.success() { + RunStatus::Success + } else { + RunStatus::Failed + }; + (status, exit.code()) + } + WaitOutcome::TimedOut => (RunStatus::TimedOut, None), + }; + + Ok(RawRun { + status, + stdout: captured.stdout, + stderr: captured.stderr, + exit_code, + duration: captured.duration, + }) +} + +fn program_candidates(language: &str) -> &'static [&'static str] { + match language { + "python" => &["python3", "python"], + _ => &["node"], + } +} + +fn kernel_hint(language: &str) -> &'static str { + match language { + "python" => { + "install Python 3 (for example `uv python install` or your system package manager) \ + and make sure `python3` or `python` is on PATH" + } + _ => "install Node.js and make sure `node` is on PATH", + } +} + +fn is_executable_file(path: &Path) -> bool { + match fs::metadata(path) { + Ok(metadata) if metadata.is_file() => { + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + metadata.permissions().mode() & 0o111 != 0 + } + #[cfg(not(unix))] + { + true + } + } + _ => false, + } +} + +fn find_program(language: &str) -> Option { + let path_var = std::env::var_os("PATH")?; + for name in program_candidates(language) { + for directory in std::env::split_paths(&path_var) { + let candidate = directory.join(name); + if is_executable_file(&candidate) { + return Some(candidate); + } + } + } + None +} + +fn probe_version(program: &Path) -> Option { + let mut command = Command::new(program); + command.arg("--version").env_clear(); + if let Some(path) = std::env::var_os("PATH") { + command.env("PATH", path); + } + let captured = + spawn_and_capture(&mut command, DETECT_TIMEOUT, DETECT_OUTPUT_LIMIT, None).ok()?; + let WaitOutcome::Exited(exit) = captured.outcome else { + return None; + }; + if !exit.success() { + return None; + } + let stdout = String::from_utf8_lossy(&captured.stdout); + let first = stdout.lines().next().unwrap_or("").trim(); + if !first.is_empty() { + return Some(first.to_string()); + } + let stderr = String::from_utf8_lossy(&captured.stderr); + let first = stderr.lines().next().unwrap_or("").trim(); + if first.is_empty() { + None + } else { + Some(first.to_string()) + } +} + +fn request_envelope(request: &RunRequest) -> Result, ForeignError> { + let envelope = serde_json::json!({ + "wire_version": marqdo_value::WIRE_VERSION, + "kind": REQUEST_KIND, + "input": request.input.clone().unwrap_or_default(), + }); + serde_json::to_vec(&envelope).map_err(|error| ForeignError::Io { + message: format!("cannot encode the foreign request envelope: {error}"), + }) +} + +/// Private temporary program file plus a fresh private working directory. +struct TempArtifacts { + program_path: PathBuf, + work_dir: PathBuf, +} + +impl TempArtifacts { + fn create(language: &str) -> Result { + let base = fs::canonicalize(std::env::temp_dir()).unwrap_or_else(|_| std::env::temp_dir()); + let extension = if language == "python" { "py" } else { "js" }; + let mut last_error: Option = None; + for _ in 0..16 { + let token = unique_token(); + let work_dir = base.join(format!("marqdo-foreign-work-{token}")); + match create_private_dir(&work_dir) { + Ok(()) => { + let program_path = + base.join(format!("marqdo-foreign-program-{token}.{extension}")); + return Ok(Self { + program_path, + work_dir, + }); + } + Err(error) if error.kind() == io::ErrorKind::AlreadyExists => { + last_error = Some(error); + } + Err(error) => { + return Err(ForeignError::Io { + message: format!( + "cannot create the foreign working directory `{}`: {error}", + work_dir.display() + ), + }); + } + } + } + Err(ForeignError::Io { + message: format!( + "cannot allocate a unique foreign temporary directory: {}", + last_error + .map(|error| error.to_string()) + .unwrap_or_else(|| "name collision".to_string()) + ), + }) + } + + fn write_program(&self, source: &str) -> Result<(), ForeignError> { + write_private_file(&self.program_path, source.as_bytes()).map_err(|error| { + ForeignError::Io { + message: format!( + "cannot write the foreign program `{}`: {error}", + self.program_path.display() + ), + } + }) + } +} + +impl Drop for TempArtifacts { + fn drop(&mut self) { + let _ = fs::remove_file(&self.program_path); + let _ = fs::remove_dir_all(&self.work_dir); + } +} + +fn create_private_dir(path: &Path) -> io::Result<()> { + let mut builder = fs::DirBuilder::new(); + #[cfg(unix)] + { + use std::os::unix::fs::DirBuilderExt; + builder.mode(0o700); + } + builder.create(path) +} + +fn write_private_file(path: &Path, bytes: &[u8]) -> io::Result<()> { + let mut options = fs::OpenOptions::new(); + options.write(true).create_new(true); + #[cfg(unix)] + { + use std::os::unix::fs::OpenOptionsExt; + options.mode(0o600); + } + let mut file = options.open(path)?; + file.write_all(bytes)?; + file.flush() +} + +fn unique_token() -> String { + let counter = UNIQUE_COUNTER.fetch_add(1, Ordering::Relaxed); + let nanos = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|elapsed| elapsed.as_nanos()) + .unwrap_or(0); + format!("{}-{nanos}-{counter}", std::process::id()) +} + +/// How the supervised child ended. +enum WaitOutcome { + /// The child was reaped normally (exit code or signal). + Exited(ExitStatus), + /// The deadline expired and the child was killed. + TimedOut, +} + +struct Captured { + outcome: WaitOutcome, + stdout: Vec, + stderr: Vec, + duration: Duration, +} + +struct ReaderState { + data: Arc>>, + done: Arc, + handle: Option>, +} + +fn spawn_reader( + mut stream: R, + total: Arc, + overflow: Arc, + limit: usize, +) -> Result { + let data = Arc::new(Mutex::new(Vec::new())); + let done = Arc::new(AtomicBool::new(false)); + let thread_data = Arc::clone(&data); + let thread_done = Arc::clone(&done); + let handle = thread::Builder::new() + .name("marqdo-foreign-output-reader".to_string()) + .spawn(move || { + let mut buffer = [0_u8; 8192]; + loop { + match stream.read(&mut buffer) { + Ok(0) => break, + Ok(read) => { + let previous = total.fetch_add(read, Ordering::AcqRel); + let allowed = limit.saturating_sub(previous).min(read); + if allowed > 0 { + if let Ok(mut guard) = thread_data.lock() { + guard.extend_from_slice(&buffer[..allowed]); + } + } + if allowed < read { + overflow.store(true, Ordering::Release); + break; + } + } + Err(ref error) if error.kind() == io::ErrorKind::Interrupted => continue, + Err(_) => break, + } + } + thread_done.store(true, Ordering::Release); + }) + .map_err(|error| ForeignError::Io { + message: format!("cannot start the foreign output reader: {error}"), + })?; + Ok(ReaderState { + data, + done, + handle: Some(handle), + }) +} + +/// Spawn `command`, write the optional stdin payload, capture both output +/// streams within `max_output_bytes`, and supervise the child until it exits or +/// the deadline expires. +fn spawn_and_capture( + command: &mut Command, + timeout: Duration, + max_output_bytes: usize, + stdin_payload: Option>, +) -> Result { + command + .stdin(if stdin_payload.is_some() { + Stdio::piped() + } else { + Stdio::null() + }) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()); + + let start = Instant::now(); + let mut child = command.spawn().map_err(|error| ForeignError::Spawn { + message: error.to_string(), + })?; + + let (Some(stdout), Some(stderr)) = (child.stdout.take(), child.stderr.take()) else { + kill_and_reap(&mut child); + return Err(ForeignError::Io { + message: "the child stdio pipes could not be captured".to_string(), + }); + }; + + if let Some(payload) = stdin_payload { + let Some(mut stdin) = child.stdin.take() else { + kill_and_reap(&mut child); + return Err(ForeignError::Io { + message: "the child stdin pipe could not be captured".to_string(), + }); + }; + // Writing must not block the supervisor, so it happens on its own + // thread; closing the handle at the end signals EOF to the kernel. + let writer = thread::Builder::new() + .name("marqdo-foreign-stdin-writer".to_string()) + .spawn(move || { + let _ = stdin.write_all(&payload); + let _ = stdin.flush(); + }); + if let Err(error) = writer { + kill_and_reap(&mut child); + return Err(ForeignError::Io { + message: format!("cannot start the foreign stdin writer: {error}"), + }); + } + } + + let total = Arc::new(AtomicUsize::new(0)); + let overflow = Arc::new(AtomicBool::new(false)); + let stdout_reader = match spawn_reader( + stdout, + Arc::clone(&total), + Arc::clone(&overflow), + max_output_bytes, + ) { + Ok(reader) => reader, + Err(error) => { + kill_and_reap(&mut child); + return Err(error); + } + }; + let stderr_reader = match spawn_reader( + stderr, + Arc::clone(&total), + Arc::clone(&overflow), + max_output_bytes, + ) { + Ok(reader) => reader, + Err(error) => { + kill_and_reap(&mut child); + drop(stdout_reader); + return Err(error); + } + }; + + let deadline = start.checked_add(timeout); + let mut timed_out = false; + let mut exit_status: Option = None; + loop { + if overflow.load(Ordering::Acquire) { + kill_and_reap(&mut child); + break; + } + match child.try_wait() { + Ok(Some(status)) => { + exit_status = Some(status); + break; + } + Ok(None) => {} + Err(error) => { + kill_and_reap(&mut child); + return Err(ForeignError::Io { + message: format!("waiting for the foreign kernel failed: {error}"), + }); + } + } + if let Some(deadline) = deadline { + if Instant::now() >= deadline { + kill_and_reap(&mut child); + timed_out = true; + break; + } + } + thread::sleep(POLL_INTERVAL); + } + + let stdout = collect_reader(stdout_reader); + let stderr = collect_reader(stderr_reader); + let duration = start.elapsed(); + + if overflow.load(Ordering::Acquire) { + return Err(ForeignError::OutputTooLarge { + limit: max_output_bytes, + }); + } + + let outcome = if timed_out { + WaitOutcome::TimedOut + } else if let Some(status) = exit_status { + WaitOutcome::Exited(status) + } else { + // Unreachable: the loop only exits with one of the two states above. + return Err(ForeignError::Io { + message: "the foreign kernel ended in an unknown state".to_string(), + }); + }; + + Ok(Captured { + outcome, + stdout, + stderr, + duration, + }) +} + +fn collect_reader(state: ReaderState) -> Vec { + let ReaderState { data, done, handle } = state; + let deadline = Instant::now().checked_add(READER_GRACE); + while !done.load(Ordering::Acquire) { + match deadline { + Some(deadline) if Instant::now() >= deadline => break, + _ => thread::sleep(Duration::from_millis(1)), + } + } + let bytes = data.lock().map(|guard| guard.clone()).unwrap_or_default(); + if done.load(Ordering::Acquire) { + if let Some(handle) = handle { + let _ = handle.join(); + } + } + bytes +} + +fn kill_and_reap(child: &mut Child) { + let _ = child.kill(); + let _ = child.wait(); +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn languages_are_normalized() { + assert_eq!(normalize_language("python"), Some("python")); + assert_eq!(normalize_language(" Python3 "), Some("python")); + assert_eq!(normalize_language("py"), Some("python")); + assert_eq!(normalize_language("javascript"), Some("javascript")); + assert_eq!(normalize_language("JS"), Some("javascript")); + assert_eq!(normalize_language("node"), Some("javascript")); + assert_eq!(normalize_language("cobol"), None); + assert_eq!(normalize_language(""), None); + } + + #[test] + fn request_envelope_is_versioned() { + let mut request = RunRequest::new("python", "print(1)"); + request.input = Some(serde_json::json!({"r": 2})); + let payload = request_envelope(&request).expect("encode"); + let decoded: Json = serde_json::from_slice(&payload).expect("decode"); + assert_eq!(decoded["wire_version"], marqdo_value::WIRE_VERSION); + assert_eq!(decoded["kind"], REQUEST_KIND); + assert_eq!(decoded["input"]["r"], 2); + + let request = RunRequest::new("python", ""); + let payload = request_envelope(&request).expect("encode"); + let decoded: Json = serde_json::from_slice(&payload).expect("decode"); + assert!(decoded["input"].is_null()); + } +} diff --git a/crates/marqdo-foreign/tests/kernels.rs b/crates/marqdo-foreign/tests/kernels.rs new file mode 100644 index 0000000..9782051 --- /dev/null +++ b/crates/marqdo-foreign/tests/kernels.rs @@ -0,0 +1,374 @@ +//! Integration tests against the real interpreters installed in the +//! environment (`python3` and `node`). +//! +//! The tests exercise the public contract the host layer relies on: explicit +//! execution only, the versioned stdin envelope, strict `call` protocol, +//! failure preservation, timeout killing, output limits and detection. + +use std::time::Duration; + +use marqdo_foreign::{ + call, detect, normalize_language, run, ForeignError, KernelInfo, RunRequest, RunStatus, +}; +use marqdo_value::Value; +use serde_json::json; + +fn request(language: &str, source: &str) -> RunRequest { + RunRequest { + language: language.to_string(), + source: source.to_string(), + input: None, + timeout: Duration::from_secs(30), + max_output_bytes: 1024 * 1024, + } +} + +fn python(source: &str) -> RunRequest { + request("python", source) +} + +fn node(source: &str) -> RunRequest { + request("javascript", source) +} + +fn kernel(language: &str) -> KernelInfo { + detect(language).unwrap_or_else(|| panic!("`{language}` kernel must be installed for tests")) +} + +#[test] +fn detect_finds_python_and_node_versions() { + let python = kernel("python"); + assert_eq!(python.language, "python"); + assert!(python.program.is_file()); + assert!( + python.version.to_ascii_lowercase().contains("python"), + "unexpected python version string: {:?}", + python.version + ); + + let alias = kernel("py"); + assert_eq!(alias.language, "python"); + assert!(alias.version.contains("Python")); + + let javascript = kernel("javascript"); + assert_eq!(javascript.language, "javascript"); + assert!(javascript.program.is_file()); + assert!( + javascript.version.starts_with('v') || !javascript.version.is_empty(), + "unexpected node version string: {:?}", + javascript.version + ); + + assert!(detect("node").is_some()); + assert!(detect("cobol").is_none()); + assert_eq!(normalize_language("js"), Some("javascript")); +} + +#[test] +fn run_success_captures_stdout() { + let result = run(&python("print('hello from python')")).expect("run"); + assert_eq!(result.status, RunStatus::Success); + assert_eq!(result.exit_code, Some(0)); + assert_eq!(result.stdout.trim(), "hello from python"); + assert!(result.stderr.is_empty()); + assert!(result.value.is_none()); + assert!(result.duration < Duration::from_secs(20)); +} + +#[test] +fn stdin_envelope_carries_the_input() { + let source = r#"import json, sys +req = json.load(sys.stdin) +assert req["wire_version"] == 1, req +assert req["kind"] == "request", req +print(json.dumps({"echo": req["input"]["message"]})) +"#; + let mut req = python(source); + req.input = Some(json!({"message": "ping"})); + let result = run(&req).expect("run"); + assert_eq!( + result.status, + RunStatus::Success, + "stderr: {}", + result.stderr + ); + let decoded: serde_json::Value = serde_json::from_str(&result.stdout).expect("json output"); + assert_eq!(decoded["echo"], "ping"); +} + +#[test] +fn stdin_envelope_sends_null_for_missing_input() { + let source = r#"import json, sys +req = json.load(sys.stdin) +print(json.dumps({"is_null": req["input"] is None})) +"#; + let result = run(&python(source)).expect("run"); + assert_eq!( + result.status, + RunStatus::Success, + "stderr: {}", + result.stderr + ); + let decoded: serde_json::Value = serde_json::from_str(&result.stdout).expect("json output"); + assert_eq!(decoded["is_null"], true); +} + +#[test] +fn call_decodes_a_python_wire_value() { + let source = r#"import json, sys +json.load(sys.stdin) +print(json.dumps({"type": "int", "decimal": "42"})) +"#; + let result = call(&python(source)).expect("call"); + assert_eq!(result.status, RunStatus::Success); + assert_eq!(result.exit_code, Some(0)); + assert_eq!(result.value, Some(Value::int(42))); +} + +#[test] +fn call_decodes_a_node_wire_value() { + let source = r#"import { readFileSync } from "node:fs"; +const request = JSON.parse(readFileSync(0, "utf8")); +process.stdout.write(JSON.stringify({ type: "text", value: request.input.message })); +"#; + let mut req = node(source); + req.input = Some(json!({"message": "from node"})); + let result = call(&req).expect("call"); + assert_eq!(result.status, RunStatus::Success); + assert_eq!(result.value, Some(Value::text("from node"))); +} + +#[test] +fn node_run_success_captures_stdout() { + let source = r#"import { readFileSync } from "node:fs"; +const request = JSON.parse(readFileSync(0, "utf8")); +console.log(`hello ${request.input.name}`); +"#; + let mut req = node(source); + req.input = Some(json!({"name": "node"})); + let result = run(&req).expect("run"); + assert_eq!( + result.status, + RunStatus::Success, + "stderr: {}", + result.stderr + ); + assert_eq!(result.stdout.trim(), "hello node"); +} + +#[test] +fn node_commonjs_syntax_is_supported() { + let source = r#"const fs = require("node:fs"); +const request = JSON.parse(fs.readFileSync(0, "utf8")); +console.log(`cjs ${request.input.value}`); +"#; + let mut req = node(source); + req.input = Some(json!({"value": "ok"})); + let result = run(&req).expect("run"); + assert_eq!( + result.status, + RunStatus::Success, + "stderr: {}", + result.stderr + ); + assert_eq!(result.stdout.trim(), "cjs ok"); +} + +#[test] +fn non_zero_exit_is_failed_and_keeps_stderr() { + let source = r#"import sys +print("about to fail", file=sys.stderr) +sys.exit(3) +"#; + let result = run(&python(source)).expect("run"); + assert_eq!(result.status, RunStatus::Failed); + assert_eq!(result.exit_code, Some(3)); + assert!( + result.stderr.contains("about to fail"), + "stderr was: {:?}", + result.stderr + ); + assert!(result.stdout.is_empty()); +} + +#[test] +fn non_zero_exit_is_preserved_by_call() { + let source = r#"import sys +print("call failed", file=sys.stderr) +sys.exit(7) +"#; + let result = call(&python(source)).expect("call"); + assert_eq!(result.status, RunStatus::Failed); + assert_eq!(result.exit_code, Some(7)); + assert!(result.stderr.contains("call failed")); + assert!(result.value.is_none()); +} + +#[test] +fn timeout_kills_the_kernel() { + let mut req = python("import time\ntime.sleep(10)\n"); + req.timeout = Duration::from_millis(200); + let result = run(&req).expect("run"); + assert_eq!(result.status, RunStatus::TimedOut); + assert_eq!(result.exit_code, None); + assert!( + result.duration < Duration::from_secs(5), + "timeout took {:?}", + result.duration + ); +} + +#[test] +fn call_reports_timeout_as_an_error() { + let mut req = python("import time\ntime.sleep(10)\n"); + req.timeout = Duration::from_millis(200); + match call(&req) { + Err(ForeignError::Timeout { seconds }) => assert!((seconds - 0.2).abs() < 1e-6), + other => panic!("expected Timeout, got {other:?}"), + } +} + +#[test] +fn call_rejects_stdout_noise() { + let source = r#"print("debug log line") +print('{"type": "int", "decimal": "42"}') +"#; + match call(&python(source)) { + Err(ForeignError::Protocol { .. }) => {} + other => panic!("expected Protocol error, got {other:?}"), + } +} + +#[test] +fn call_rejects_non_json_stdout() { + match call(&python("print('not a wire value')")) { + Err(ForeignError::Protocol { .. }) => {} + other => panic!("expected Protocol error, got {other:?}"), + } +} + +#[test] +fn call_rejects_unknown_wire_types() { + let source = r#"print('{"type": "mystery"}')"#; + match call(&python(source)) { + Err(ForeignError::Protocol { .. }) => {} + other => panic!("expected Protocol error, got {other:?}"), + } +} + +#[test] +fn oversized_output_is_an_error() { + let source = "print('x' * 200000)"; + let mut req = python(source); + req.max_output_bytes = 1024; + match run(&req) { + Err(ForeignError::OutputTooLarge { limit }) => assert_eq!(limit, 1024), + other => panic!("expected OutputTooLarge, got {other:?}"), + } +} + +#[test] +fn oversized_stderr_is_an_error() { + let source = r#"import sys +sys.stderr.write("y" * 200000) +"#; + let mut req = python(source); + req.max_output_bytes = 512; + match run(&req) { + Err(ForeignError::OutputTooLarge { limit }) => assert_eq!(limit, 512), + other => panic!("expected OutputTooLarge, got {other:?}"), + } +} + +#[test] +#[cfg(unix)] +fn child_environment_only_keeps_path() { + let source = r#"import json, os +print(json.dumps(sorted(os.environ))) +"#; + let result = run(&python(source)).expect("run"); + assert_eq!( + result.status, + RunStatus::Success, + "stderr: {}", + result.stderr + ); + let keys: Vec = serde_json::from_str(&result.stdout).expect("json output"); + assert!( + keys.iter().any(|key| key == "PATH"), + "PATH must be preserved for the kernel: {keys:?}" + ); + assert!( + !keys.iter().any(|key| key == "HOME"), + "the child must not inherit the parent environment: {keys:?}" + ); +} + +#[test] +fn relative_writes_happen_in_a_fresh_cleaned_directory() { + let source = r#"import os +with open("marqdo-foreign-relative-test.txt", "w", encoding="utf-8") as handle: + handle.write("x") +print(os.getcwd()) +"#; + let result = run(&python(source)).expect("run"); + assert_eq!( + result.status, + RunStatus::Success, + "stderr: {}", + result.stderr + ); + let working_directory = result.stdout.trim(); + assert!(!working_directory.is_empty()); + assert!( + !working_directory.starts_with(env!("CARGO_MANIFEST_DIR")), + "foreign cwd must not be the project: {working_directory}" + ); + assert!( + !std::path::Path::new(working_directory).exists(), + "the temporary working directory must be removed: {working_directory}" + ); + assert!( + !std::path::Path::new(env!("CARGO_MANIFEST_DIR")) + .join("marqdo-foreign-relative-test.txt") + .exists(), + "relative writes must not touch the project" + ); +} + +#[test] +fn kernel_that_ignores_stdin_does_not_hang() { + let mut req = python("print('done')"); + req.input = Some(json!({"blob": "x".repeat(4 * 1024 * 1024)})); + let result = run(&req).expect("run"); + assert_eq!( + result.status, + RunStatus::Success, + "stderr: {}", + result.stderr + ); + assert_eq!(result.stdout.trim(), "done"); +} + +#[test] +fn unknown_language_is_unavailable() { + match run(&request("cobol", "DISPLAY 'HI'.")) { + Err(ForeignError::KernelUnavailable { language, hint }) => { + assert_eq!(language, "cobol"); + assert!(!hint.is_empty()); + } + other => panic!("expected KernelUnavailable, got {other:?}"), + } +} + +#[test] +fn error_messages_are_human_readable() { + let error = ForeignError::OutputTooLarge { limit: 4096 }; + assert!(error.to_string().contains("4096")); + let error = ForeignError::KernelUnavailable { + language: "python".to_string(), + hint: "install it".to_string(), + }; + assert!(error.to_string().contains("python")); + assert!(error.to_string().contains("install it")); +} diff --git a/crates/marqdo-math/Cargo.toml b/crates/marqdo-math/Cargo.toml index 9703a70..7ff6182 100644 --- a/crates/marqdo-math/Cargo.toml +++ b/crates/marqdo-math/Cargo.toml @@ -9,11 +9,9 @@ repository.workspace = true authors.workspace = true [dependencies] -marqdo-span = { workspace = true } marqdo-value = { workspace = true } num-bigint = { workspace = true } num-rational = { workspace = true } num-traits = { workspace = true } serde = { workspace = true } -thiserror = { workspace = true } diff --git a/crates/marqdo-math/src/ast.rs b/crates/marqdo-math/src/ast.rs new file mode 100644 index 0000000..4a98653 --- /dev/null +++ b/crates/marqdo-math/src/ast.rs @@ -0,0 +1,394 @@ +//! Formula AST, exact-number representation and deterministic rendering. +//! +//! The AST is public so that `math.inspect` and tests can observe the parsed +//! structure instead of re-parsing the source string. [`Formula::source`] keeps +//! the original LaTeX exactly as supplied to [`crate::parse`]; rendering is only +//! used when an operation (currently [`crate::substitute`]) produces a new +//! formula. + +use std::collections::BTreeSet; + +use num_bigint::BigInt; +use num_rational::Ratio; +use num_traits::{One, Signed, Zero}; + +/// Exact rational number used internally by the kernel. +/// +/// This is `num-rational`'s generic `Ratio` instantiated over the same +/// `num-bigint` `BigInt` type used by [`marqdo_value::Value::Int`], so values can +/// cross the kernel boundary without a lossy or string round-trip. +pub type Rational = Ratio; + +/// Named mathematical constants supported by the subset. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum Constant { + /// The circle ratio, written `\pi` or `pi`. + Pi, + /// Euler's number, written `\e` or `e`. + E, +} + +impl Constant { + /// The approximate `f64` value of this constant. + pub fn value(self) -> f64 { + match self { + Constant::Pi => std::f64::consts::PI, + Constant::E => std::f64::consts::E, + } + } +} + +/// A node of the supported expression grammar. +#[derive(Debug, Clone, PartialEq)] +pub enum Expr { + /// An exact numeric literal. Decimal literals are reduced to exact + /// rationals (for example `0.25` becomes `1/4`). + Number(Rational), + /// A free variable resolved from the binding map at evaluation time. + Variable(String), + /// A named constant (`\pi`, `pi`, `\e`, `e`). + Constant(Constant), + /// Unary negation. + Neg(Box), + /// Addition. + Add(Box, Box), + /// Subtraction. + Sub(Box, Box), + /// Multiplication. + Mul(Box, Box), + /// Division. `\frac{a}{b}` is parsed as `Div(a, b)`. + Div(Box, Box), + /// Exponentiation. The exponent must evaluate to an integer. + Pow(Box, Box), + /// Square root. `\sqrt{x}` is a dedicated node so that perfect squares can + /// stay exact. + Sqrt(Box), +} + +impl Expr { + /// Collect every free variable name (constants are not variables). + pub fn variables(&self) -> BTreeSet { + let mut names = BTreeSet::new(); + self.collect_variables(&mut names); + names + } + + fn collect_variables(&self, names: &mut BTreeSet) { + match self { + Expr::Number(_) | Expr::Constant(_) => {} + Expr::Variable(name) => { + names.insert(name.clone()); + } + Expr::Neg(inner) | Expr::Sqrt(inner) => inner.collect_variables(names), + Expr::Add(left, right) + | Expr::Sub(left, right) + | Expr::Mul(left, right) + | Expr::Div(left, right) + | Expr::Pow(left, right) => { + left.collect_variables(names); + right.collect_variables(names); + } + } + } + + /// Number of syntactic occurrences of `name`. + pub fn occurrences(&self, name: &str) -> usize { + match self { + Expr::Number(_) | Expr::Constant(_) => 0, + Expr::Variable(variable) => usize::from(variable == name), + Expr::Neg(inner) | Expr::Sqrt(inner) => inner.occurrences(name), + Expr::Add(left, right) + | Expr::Sub(left, right) + | Expr::Mul(left, right) + | Expr::Div(left, right) + | Expr::Pow(left, right) => left.occurrences(name) + right.occurrences(name), + } + } +} + +/// Top level shape of a parsed formula: an expression or a single equation. +/// +/// A formula with one `=` is an [`FormulaKind::Equation`]; it is never an +/// assignment. More than one `=` is a parse error. +#[derive(Debug, Clone, PartialEq)] +pub enum FormulaKind { + /// A standalone arithmetic expression. + Expression(Expr), + /// `left = right`. + Equation { + /// Left-hand side. + left: Expr, + /// Right-hand side. + right: Expr, + }, +} + +/// A parsed formula plus the original source text. +#[derive(Debug, Clone, PartialEq)] +pub struct Formula { + /// Original LaTeX source exactly as supplied to [`crate::parse`], or the + /// canonical rendering produced by [`crate::substitute`]. + pub source: String, + /// Parsed structure. + pub kind: FormulaKind, +} + +impl Formula { + /// Whether this formula is an equation. + pub fn is_equation(&self) -> bool { + matches!(self.kind, FormulaKind::Equation { .. }) + } + + /// Borrow the expression when this formula is not an equation. + pub fn expression(&self) -> Option<&Expr> { + match &self.kind { + FormulaKind::Expression(expr) => Some(expr), + FormulaKind::Equation { .. } => None, + } + } + + /// Borrow both sides when this formula is an equation. + pub fn equation(&self) -> Option<(&Expr, &Expr)> { + match &self.kind { + FormulaKind::Expression(_) => None, + FormulaKind::Equation { left, right } => Some((left, right)), + } + } + + /// Every free variable appearing in the formula, in sorted order. + pub fn variables(&self) -> BTreeSet { + match &self.kind { + FormulaKind::Expression(expr) => expr.variables(), + FormulaKind::Equation { left, right } => { + let mut names = left.variables(); + names.extend(right.variables()); + names + } + } + } + + /// Render this formula back to the supported LaTeX subset deterministically. + /// + /// The result is always re-parseable by [`crate::parse`]. This is used by + /// [`crate::substitute`] to build the new [`Formula::source`]. + pub fn render(&self) -> String { + match &self.kind { + FormulaKind::Expression(expr) => render_expr(expr), + FormulaKind::Equation { left, right } => { + format!("{} = {}", render_expr(left), render_expr(right)) + } + } + } +} + +// Rendering precedence levels, from loosest to tightest. +const PREC_ADD: u8 = 1; +const PREC_MUL: u8 = 2; +const PREC_UNARY: u8 = 3; +const PREC_POW: u8 = 4; +const PREC_ATOM: u8 = 5; + +/// Fractional digits beyond which a terminating rational is rendered as +/// `\frac{..}{..}` instead of a long decimal. Chosen so that substituted +/// `f64` values that are exactly representable in a short decimal stay readable, +/// while binary-exact values with long expansions use a compact fraction. +const MAX_RENDERED_DECIMAL_DIGITS: u32 = 32; + +/// Render an expression without surrounding parentheses. +pub fn render_expr(expr: &Expr) -> String { + render(expr, 0) +} + +fn render(expr: &Expr, parent_precedence: u8) -> String { + match expr { + Expr::Number(value) => { + let (text, precedence) = render_rational(value); + parenthesize(text, precedence, parent_precedence) + } + Expr::Variable(name) => name.clone(), + Expr::Constant(constant) => match constant { + Constant::Pi => "\\pi".to_string(), + Constant::E => "\\e".to_string(), + }, + Expr::Neg(inner) => { + let text = format!("-{}", render(inner, PREC_UNARY)); + parenthesize(text, PREC_UNARY, parent_precedence) + } + Expr::Add(left, right) => { + let text = format!( + "{} + {}", + render(left, PREC_ADD), + render(right, PREC_ADD + 1) + ); + parenthesize(text, PREC_ADD, parent_precedence) + } + Expr::Sub(left, right) => { + let text = format!( + "{} - {}", + render(left, PREC_ADD), + render(right, PREC_ADD + 1) + ); + parenthesize(text, PREC_ADD, parent_precedence) + } + Expr::Mul(left, right) => { + let text = format!( + "{} * {}", + render(left, PREC_MUL), + render(right, PREC_MUL + 1) + ); + parenthesize(text, PREC_MUL, parent_precedence) + } + Expr::Div(left, right) => { + let text = format!( + "{} / {}", + render(left, PREC_MUL), + render(right, PREC_MUL + 1) + ); + parenthesize(text, PREC_MUL, parent_precedence) + } + Expr::Pow(base, exponent) => { + let text = format!( + "{} ^ {}", + render(base, PREC_POW + 1), + render(exponent, PREC_POW) + ); + parenthesize(text, PREC_POW, parent_precedence) + } + Expr::Sqrt(inner) => format!("\\sqrt{{{}}}", render(inner, 0)), + } +} + +fn parenthesize(text: String, precedence: u8, parent_precedence: u8) -> String { + if precedence < parent_precedence { + format!("({text})") + } else { + text + } +} + +/// Render an exact rational, returning the text and its rendering precedence. +/// +/// Integral values render as integers. Values with a terminating decimal +/// expansion of at most [`MAX_RENDERED_DECIMAL_DIGITS`] digits render as +/// decimals; everything else renders as `\frac{numerator}{denominator}`. +fn render_rational(value: &Rational) -> (String, u8) { + if value.is_integer() { + let integer = value.to_integer(); + let negative = integer.sign() == num_bigint::Sign::Minus; + let precedence = if negative { PREC_UNARY } else { PREC_ATOM }; + return (integer.to_string(), precedence); + } + + if let Some(places) = decimal_places(value.denom()) { + if places <= MAX_RENDERED_DECIMAL_DIGITS { + let scale = BigInt::from(10_u32).pow(places); + let scaled = value.numer() * &scale / value.denom(); + let negative = scaled.sign() == num_bigint::Sign::Minus; + let digits = scaled.abs().to_string(); + let places = places as usize; + let decimal = if digits.len() <= places { + format!("0.{}{digits}", "0".repeat(places - digits.len())) + } else { + let split = digits.len() - places; + format!("{}.{}", &digits[..split], &digits[split..]) + }; + let precedence = if negative { PREC_UNARY } else { PREC_ATOM }; + let text = if negative { + format!("-{decimal}") + } else { + decimal + }; + return (text, precedence); + } + } + + ( + format!("\\frac{{{}}}{{{}}}", value.numer(), value.denom()), + PREC_ATOM, + ) +} + +/// Number of fractional digits needed for the terminating decimal expansion of +/// `denominator`, or `None` when the expansion does not terminate or is longer +/// than [`MAX_RENDERED_DECIMAL_DIGITS`]. +fn decimal_places(denominator: &BigInt) -> Option { + let mut reduced = denominator.clone(); + let two = BigInt::from(2_u32); + let five = BigInt::from(5_u32); + let mut twos = 0_u32; + while reduced.is_positive() && (&reduced % &two).is_zero() { + reduced /= &two; + twos += 1; + if twos > MAX_RENDERED_DECIMAL_DIGITS { + return None; + } + } + let mut fives = 0_u32; + while reduced.is_positive() && (&reduced % &five).is_zero() { + reduced /= &five; + fives += 1; + if fives > MAX_RENDERED_DECIMAL_DIGITS { + return None; + } + } + if reduced.is_one() { + Some(twos.max(fives)) + } else { + None + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn number(numerator: i64, denominator: i64) -> Expr { + Expr::Number(Ratio::new( + BigInt::from(numerator), + BigInt::from(denominator), + )) + } + + #[test] + fn rendering_round_trips_through_parse() { + // The renderer must always emit text the parser accepts. + for source in [ + "1 + 2 * 3", + "(1 + 2) * 3", + "2 ^ (3 + 1)", + "\\frac{1}{3}", + "-4 ^ 2", + "2 ^ (-3)", + "\\sqrt{2}", + "a = 2 * b + 1", + "(2 ^ 3) ^ 2", + "1 - (2 - 3)", + "a / (b * c)", + ] { + let formula = crate::parse(source).expect("fixture parses"); + let rendered = formula.render(); + let reparsed = crate::parse(&rendered) + .unwrap_or_else(|err| panic!("rendered {rendered:?} does not parse: {err}")); + assert_eq!(reparsed.kind, formula.kind, "source {source:?}"); + } + } + + #[test] + fn decimal_and_fraction_rendering_is_deterministic() { + assert_eq!(render_expr(&number(5, 2)), "2.5"); + assert_eq!(render_expr(&number(-5, 2)), "-2.5"); + assert_eq!(render_expr(&number(1, 8)), "0.125"); + assert_eq!(render_expr(&number(1, 3)), "\\frac{1}{3}"); + assert_eq!(render_expr(&number(0, 1)), "0"); + } + + #[test] + fn variables_are_collected_without_constants() { + let formula = crate::parse("2 * x + y * \\pi").unwrap(); + assert_eq!( + formula.variables().into_iter().collect::>(), + vec!["x".to_string(), "y".to_string()] + ); + assert_eq!(formula.expression().unwrap().occurrences("x"), 1); + } +} diff --git a/crates/marqdo-math/src/error.rs b/crates/marqdo-math/src/error.rs new file mode 100644 index 0000000..c85ce7c --- /dev/null +++ b/crates/marqdo-math/src/error.rs @@ -0,0 +1,146 @@ +//! Structured errors returned by the native math kernel. +//! +//! The kernel never panics on untrusted LaTeX. Every failure is reported as a +//! [`MathError`] with a stable [`MathErrorKind`], a human readable message and +//! (for parse failures) the byte offset into the original LaTeX source. The +//! host layer is expected to map [`MathErrorKind::Unsupported`] to the +//! `math.unsupported` diagnostic code and the remaining kinds to the matching +//! expression diagnostics. + +use serde::{Deserialize, Serialize}; +use std::fmt; + +/// Broad category of a math kernel failure. +/// +/// The enum is deliberately small: the kernel only distinguishes "the input is +/// not in the supported grammar", "the input is in the grammar but outside the +/// supported subset", "a name is unbound" and "a value has the wrong type". +/// Resource-bound violations (exponent/result size) are reported as +/// [`MathErrorKind::Unsupported`] because they are a documented limitation of +/// the subset rather than a parse or type problem. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum MathErrorKind { + /// The input is malformed LaTeX for the supported subset. + Parse, + /// The input is well-formed but outside the deliberately limited subset, or + /// the requested operation/equation shape is not supported. + Unsupported, + /// A variable used by the formula has no binding. + UndefinedVariable, + /// A binding or operand has an incompatible type, or an operation is + /// undefined for the supplied values (for example division by zero). + Type, +} + +impl MathErrorKind { + /// Stable lowercase label used by diagnostics and tests. + pub const fn as_str(self) -> &'static str { + match self { + MathErrorKind::Parse => "parse", + MathErrorKind::Unsupported => "unsupported", + MathErrorKind::UndefinedVariable => "undefined-variable", + MathErrorKind::Type => "type", + } + } +} + +impl fmt::Display for MathErrorKind { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(self.as_str()) + } +} + +/// A structured error produced by [`crate::parse`], [`crate::evaluate`] or +/// [`crate::substitute`]. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct MathError { + /// Failure category. + pub kind: MathErrorKind, + /// Human readable explanation. Messages are diagnostic text; callers should + /// branch on [`MathError::kind`] rather than on the wording. + pub message: String, + /// Byte offset into the original LaTeX source, when the failure is tied to + /// a specific token. + pub position: Option, +} + +impl MathError { + /// Construct an error with an explicit kind and optional byte position. + pub fn new(kind: MathErrorKind, message: impl Into, position: Option) -> Self { + Self { + kind, + message: message.into(), + position, + } + } + + /// Construct a [`MathErrorKind::Parse`] error. + pub fn parse(message: impl Into, position: Option) -> Self { + Self::new(MathErrorKind::Parse, message, position) + } + + /// Construct a [`MathErrorKind::Unsupported`] error. + pub fn unsupported(message: impl Into, position: Option) -> Self { + Self::new(MathErrorKind::Unsupported, message, position) + } + + /// Construct a [`MathErrorKind::UndefinedVariable`] error. + pub fn undefined_variable(message: impl Into, position: Option) -> Self { + Self::new(MathErrorKind::UndefinedVariable, message, position) + } + + /// Construct a [`MathErrorKind::Type`] error. + pub fn type_error(message: impl Into, position: Option) -> Self { + Self::new(MathErrorKind::Type, message, position) + } + + /// The documented result-size guard was hit. Reported as `Unsupported` so + /// callers can surface a stable `math.unsupported` diagnostic instead of a + /// crash or an out-of-memory abort. + pub fn size_bound(message: impl Into) -> Self { + Self::unsupported(message, None) + } +} + +impl fmt::Display for MathError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "{}", self.kind)?; + if let Some(position) = self.position { + write!(f, " at byte {position}")?; + } + write!(f, ": {}", self.message) + } +} + +impl std::error::Error for MathError {} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn display_includes_kind_and_position() { + let err = MathError::parse("expected an expression", Some(3)); + assert_eq!(err.to_string(), "parse at byte 3: expected an expression"); + assert_eq!(err.kind.as_str(), "parse"); + } + + #[test] + fn constructors_use_stable_kinds() { + assert_eq!( + MathError::unsupported("x", None).kind, + MathErrorKind::Unsupported + ); + assert_eq!( + MathError::undefined_variable("x", None).kind, + MathErrorKind::UndefinedVariable + ); + assert_eq!(MathError::type_error("x", None).kind, MathErrorKind::Type); + assert_eq!(MathError::size_bound("x").kind, MathErrorKind::Unsupported); + assert_eq!( + MathErrorKind::UndefinedVariable.to_string(), + "undefined-variable" + ); + } +} diff --git a/crates/marqdo-math/src/eval.rs b/crates/marqdo-math/src/eval.rs new file mode 100644 index 0000000..4412119 --- /dev/null +++ b/crates/marqdo-math/src/eval.rs @@ -0,0 +1,695 @@ +//! Exact evaluation, equation solving and substitution. +//! +//! Numeric semantics are documented on the crate root. In short: literals, +//! integer/float bindings and the operators `+ - * / ^` are evaluated as exact +//! rationals; `\pi`, `\e` and non-perfect square roots introduce an `f64` +//! approximation. The final value is [`Value::Int`] exactly when the exact +//! result is an integer and [`Value::Float`] otherwise. + +use std::collections::BTreeMap; + +use num_bigint::{BigInt, Sign}; +use num_rational::Ratio; +use num_traits::{One, Signed, ToPrimitive, Zero}; + +use marqdo_value::Value; + +use crate::ast::{Expr, Formula, FormulaKind, Rational}; +use crate::error::MathError; + +/// Maximum magnitude of an integer exponent accepted by `^`. +pub const MAX_EXPONENT: u64 = 10_000; + +/// Maximum number of bits (binary digits) allowed for the numerator and for the +/// denominator of an exact intermediate or result. This bounds memory and CPU +/// for hostile formulas such as `(2^10000)^10000`. +pub const MAX_RESULT_BITS: u64 = 1_000_000; + +/// A number during evaluation: either exact or an explicit `f64` +/// approximation produced by an irrational operation. +#[derive(Debug, Clone)] +enum Numeric { + Exact(Rational), + Approx(f64), +} + +impl Numeric { + fn exact_zero() -> Self { + Numeric::Exact(Ratio::from_integer(BigInt::zero())) + } + + fn exact_one() -> Self { + Numeric::Exact(Ratio::from_integer(BigInt::one())) + } + + fn is_zero(&self) -> bool { + match self { + Numeric::Exact(value) => value.is_zero(), + Numeric::Approx(value) => *value == 0.0, + } + } + + fn neg(self) -> Result { + match self { + Numeric::Exact(value) => Ok(Numeric::Exact(-value)), + Numeric::Approx(value) => Ok(Numeric::Approx(-value)), + } + } + + fn to_approx(&self) -> Result { + match self { + Numeric::Approx(value) => Ok(*value), + Numeric::Exact(value) => ratio_to_f64(value).ok_or_else(|| { + MathError::size_bound( + "an exact intermediate result is too large to represent as a Float", + ) + }), + } + } + + fn add(self, other: Numeric) -> Result { + match (self, other) { + (Numeric::Exact(left), Numeric::Exact(right)) => { + Ok(Numeric::Exact(checked_ratio(left + right)?)) + } + (left, right) => Ok(Numeric::Approx(left.to_approx()? + right.to_approx()?)), + } + } + + fn sub(self, other: Numeric) -> Result { + match (self, other) { + (Numeric::Exact(left), Numeric::Exact(right)) => { + Ok(Numeric::Exact(checked_ratio(left - right)?)) + } + (left, right) => Ok(Numeric::Approx(left.to_approx()? - right.to_approx()?)), + } + } + + fn mul(self, other: Numeric) -> Result { + match (self, other) { + (Numeric::Exact(left), Numeric::Exact(right)) => { + Ok(Numeric::Exact(exact_mul(&left, &right)?)) + } + (left, right) => Ok(Numeric::Approx(left.to_approx()? * right.to_approx()?)), + } + } + + fn div(self, other: Numeric) -> Result { + if other.is_zero() { + return Err(division_by_zero()); + } + match (self, other) { + (Numeric::Exact(left), Numeric::Exact(right)) => { + Ok(Numeric::Exact(checked_ratio(left / right)?)) + } + (left, right) => Ok(Numeric::Approx(left.to_approx()? / right.to_approx()?)), + } + } + + fn sqrt(self) -> Result { + match self { + Numeric::Exact(value) => { + if value.is_negative() { + return Err(MathError::type_error( + "square root of a negative number is not supported by the real-valued subset", + None, + )); + } + let numerator_root = integer_sqrt(value.numer()); + let denominator_root = integer_sqrt(value.denom()); + if &(&numerator_root * &numerator_root) == value.numer() + && &(&denominator_root * &denominator_root) == value.denom() + { + Ok(Numeric::Exact(Ratio::new(numerator_root, denominator_root))) + } else { + let approximate = ratio_to_f64(&value).ok_or_else(|| { + MathError::size_bound( + "square root operands are outside the representable Float range", + ) + })?; + Ok(Numeric::Approx(approximate.sqrt())) + } + } + Numeric::Approx(value) => { + if value < 0.0 { + return Err(MathError::type_error( + "square root of a negative number is not supported by the real-valued subset", + None, + )); + } + Ok(Numeric::Approx(value.sqrt())) + } + } + } + + fn pow(self, exponent: BigInt) -> Result { + let negative_exponent = exponent.sign() == Sign::Minus; + let magnitude = exponent.magnitude(); + let bound = num_bigint::BigUint::from(MAX_EXPONENT); + if *magnitude > bound { + return Err(MathError::size_bound(format!( + "exponent magnitude exceeds the supported bound of {MAX_EXPONENT}" + ))); + } + let exponent_u32 = magnitude + .to_u32() + .ok_or_else(|| MathError::size_bound("exponent is outside the supported bound"))?; + + match self { + Numeric::Exact(base) => { + if exponent_u32 == 0 { + if base.is_zero() { + return Err(MathError::type_error( + "0 ^ 0 is undefined in the native math subset", + None, + )); + } + return Ok(Numeric::Exact(Ratio::from_integer(BigInt::one()))); + } + if base.is_zero() && negative_exponent { + return Err(division_by_zero()); + } + let max_bits = base.numer().bits().max(base.denom().bits()); + let estimated_bits = max_bits.saturating_mul(u64::from(exponent_u32)); + if estimated_bits > MAX_RESULT_BITS { + return Err(MathError::size_bound(format!( + "exponentiation result would exceed the supported size bound of {MAX_RESULT_BITS} bits" + ))); + } + let numerator = base.numer().pow(exponent_u32); + let denominator = base.denom().pow(exponent_u32); + let result = if negative_exponent { + Ratio::new(denominator, numerator) + } else { + Ratio::new(numerator, denominator) + }; + Ok(Numeric::Exact(checked_ratio(result)?)) + } + Numeric::Approx(base) => { + if base == 0.0 && negative_exponent { + return Err(division_by_zero()); + } + let exponent = exponent_u32 as i32; + Ok(Numeric::Approx(base.powi(exponent))) + } + } + } + + fn into_value(self) -> Result { + match self { + Numeric::Exact(value) => { + if value.is_integer() { + Ok(Value::Int(value.to_integer())) + } else { + Ok(Value::Float(ratio_to_f64(&value).ok_or_else(|| { + MathError::size_bound("exact result is too large to represent as a Float") + })?)) + } + } + Numeric::Approx(value) => Ok(Value::Float(value)), + } + } +} + +fn division_by_zero() -> MathError { + MathError::type_error( + "division by zero is not defined in the native math subset", + None, + ) +} + +fn checked_ratio(value: Rational) -> Result { + if value.numer().bits() > MAX_RESULT_BITS || value.denom().bits() > MAX_RESULT_BITS { + return Err(MathError::size_bound(format!( + "intermediate result exceeds the supported size bound of {MAX_RESULT_BITS} bits" + ))); + } + Ok(value) +} + +/// Convert an exact rational to `f64` without going through `Ratio`'s +/// `ToPrimitive` impl (which is bound to a different `num-bigint` version in +/// `num-rational` 0.4). Returns `None` when the value is outside the finite +/// `f64` range or would lose everything to underflow. +fn ratio_to_f64(value: &Rational) -> Option { + if value.is_zero() { + return Some(0.0); + } + let negative = value.numer().sign() == Sign::Minus; + let (numerator_mantissa, numerator_exponent) = scaled_f64_mantissa(&value.numer().abs()); + let (denominator_mantissa, denominator_exponent) = scaled_f64_mantissa(value.denom()); + let exponent = numerator_exponent - denominator_exponent; + if exponent > 1023 { + return None; + } + if exponent < -1075 { + return Some(if negative { -0.0 } else { 0.0 }); + } + let mut result = numerator_mantissa / denominator_mantissa; + result *= 2_f64.powi(exponent as i32); + if !result.is_finite() { + return None; + } + Some(if negative { -result } else { result }) +} + +/// Decompose a non-negative integer into `(mantissa, exponent)` such that the +/// value is approximately `mantissa * 2^exponent` and `mantissa` fits in `f64`. +fn scaled_f64_mantissa(value: &BigInt) -> (f64, i64) { + debug_assert!(!value.is_negative()); + let bits = value.bits(); + if bits == 0 { + return (0.0, 0); + } + // Keep the most significant 64 bits; the low bits only affect the last + // ~11 bits of the f64 mantissa, which is below the documented precision. + let shift = bits.saturating_sub(64); + let top = (value >> shift).to_u64().unwrap_or(u64::MAX); + (top as f64, shift as i64) +} + +fn exact_mul(left: &Rational, right: &Rational) -> Result { + // Pre-check before allocating so that multiplying two large operands cannot + // allocate an out-of-bound intermediate. + let numerator_bits = left.numer().bits().saturating_add(right.numer().bits()); + let denominator_bits = left.denom().bits().saturating_add(right.denom().bits()); + if numerator_bits > MAX_RESULT_BITS || denominator_bits > MAX_RESULT_BITS { + return Err(MathError::size_bound(format!( + "multiplication result would exceed the supported size bound of {MAX_RESULT_BITS} bits" + ))); + } + checked_ratio(left * right) +} + +/// Integer square root of a non-negative integer (Newton iteration). +fn integer_sqrt(value: &BigInt) -> BigInt { + debug_assert!(!value.is_negative()); + if value.is_zero() { + return BigInt::zero(); + } + let mut estimate = BigInt::one() << value.bits().div_ceil(2) as usize; + loop { + let next = (&estimate + value / &estimate) >> 1; + if next >= estimate { + return estimate; + } + estimate = next; + } +} + +/// Convert a finite `f64` into the exact binary rational it represents. +fn float_to_ratio(value: f64) -> Option { + if !value.is_finite() { + return None; + } + if value == 0.0 { + return Some(Ratio::from_integer(BigInt::zero())); + } + let bits = value.to_bits(); + let negative = (bits >> 63) == 1; + let exponent_bits = ((bits >> 52) & 0x7ff) as i32; + let fraction = bits & ((1_u64 << 52) - 1); + let (mantissa, exponent) = if exponent_bits == 0 { + (fraction, -1074_i32) + } else { + (fraction | (1_u64 << 52), exponent_bits - 1075) + }; + let mut numerator = BigInt::from(mantissa); + let mut denominator = BigInt::one(); + if exponent >= 0 { + numerator <<= exponent as usize; + } else { + denominator <<= (-exponent) as usize; + } + if negative { + numerator = -numerator; + } + Some(Ratio::new(numerator, denominator)) +} + +/// Convert a [`Value`] binding into a kernel number. +fn binding_numeric(name: &str, bindings: &BTreeMap) -> Result { + match bindings.get(name) { + None => Err(MathError::undefined_variable( + format!("variable `{name}` is not bound"), + None, + )), + Some(Value::Int(value)) => Ok(Numeric::Exact(Ratio::from_integer(value.clone()))), + Some(Value::Float(value)) => float_to_ratio(*value).map(Numeric::Exact).ok_or_else(|| { + MathError::type_error( + format!( + "binding `{name}` is a non-finite Float; the math kernel only accepts finite numeric bindings" + ), + None, + ) + }), + Some(other) => Err(MathError::type_error( + format!( + "binding `{name}` has type {} but the math kernel requires Int or Float", + other.type_name() + ), + None, + )), + } +} + +fn eval_expr(expr: &Expr, bindings: &BTreeMap) -> Result { + match expr { + Expr::Number(value) => Ok(Numeric::Exact(value.clone())), + Expr::Variable(name) => binding_numeric(name, bindings), + Expr::Constant(constant) => Ok(Numeric::Approx(constant.value())), + Expr::Neg(inner) => eval_expr(inner, bindings)?.neg(), + Expr::Add(left, right) => eval_expr(left, bindings)?.add(eval_expr(right, bindings)?), + Expr::Sub(left, right) => eval_expr(left, bindings)?.sub(eval_expr(right, bindings)?), + Expr::Mul(left, right) => eval_expr(left, bindings)?.mul(eval_expr(right, bindings)?), + Expr::Div(left, right) => eval_expr(left, bindings)?.div(eval_expr(right, bindings)?), + Expr::Pow(base, exponent) => { + let base = eval_expr(base, bindings)?; + base.pow(integer_exponent(&eval_expr(exponent, bindings)?)?) + } + Expr::Sqrt(inner) => eval_expr(inner, bindings)?.sqrt(), + } +} + +/// Require a numeric value to be an integer and return it. +fn integer_exponent(value: &Numeric) -> Result { + match value { + Numeric::Exact(value) if value.is_integer() => Ok(value.to_integer()), + _ => Err(MathError::type_error( + "exponent must be an integer in the native math subset", + None, + )), + } +} + +/// A linear/affine form `coefficient * target + constant`. +struct Affine { + coefficient: Numeric, + constant: Numeric, +} + +impl Affine { + fn constant(value: Numeric) -> Self { + Self { + coefficient: Numeric::exact_zero(), + constant: value, + } + } + + fn target() -> Self { + Self { + coefficient: Numeric::exact_one(), + constant: Numeric::exact_zero(), + } + } + + fn is_target_free(&self) -> bool { + self.coefficient.is_zero() + } + + fn neg(self) -> Result { + Ok(Self { + coefficient: self.coefficient.neg()?, + constant: self.constant.neg()?, + }) + } + + fn add(self, other: Self) -> Result { + Ok(Self { + coefficient: self.coefficient.add(other.coefficient)?, + constant: self.constant.add(other.constant)?, + }) + } + + fn sub(self, other: Self) -> Result { + Ok(Self { + coefficient: self.coefficient.sub(other.coefficient)?, + constant: self.constant.sub(other.constant)?, + }) + } + + fn scale(self, factor: Numeric) -> Result { + let coefficient = self.coefficient.mul(factor.clone())?; + let constant = self.constant.mul(factor)?; + Ok(Self { + coefficient, + constant, + }) + } +} + +/// Build the affine form of `expr` with respect to `target`. +/// +/// Variables other than `target` are resolved from `bindings`. Operations that +/// are not affine in `target` are rejected as unsupported instead of being +/// approximated or reported as a solution. +fn to_affine( + expr: &Expr, + target: &str, + bindings: &BTreeMap, +) -> Result { + match expr { + Expr::Number(value) => Ok(Affine::constant(Numeric::Exact(value.clone()))), + Expr::Constant(constant) => Ok(Affine::constant(Numeric::Approx(constant.value()))), + Expr::Variable(name) if name == target => Ok(Affine::target()), + Expr::Variable(name) => Ok(Affine::constant(binding_numeric(name, bindings)?)), + Expr::Neg(inner) => to_affine(inner, target, bindings)?.neg(), + Expr::Add(left, right) => { + let left = to_affine(left, target, bindings)?; + let right = to_affine(right, target, bindings)?; + left.add(right) + } + Expr::Sub(left, right) => { + let left = to_affine(left, target, bindings)?; + let right = to_affine(right, target, bindings)?; + left.sub(right) + } + Expr::Mul(left, right) => { + let left = to_affine(left, target, bindings)?; + let right = to_affine(right, target, bindings)?; + match (left.is_target_free(), right.is_target_free()) { + (true, true) => Ok(Affine::constant( + left.constant.mul(right.constant)?, + )), + (true, false) => right.scale(left.constant), + (false, true) => left.scale(right.constant), + (false, false) => Err(MathError::unsupported( + format!( + "cannot solve for `{target}`: the equation is not linear in the target (it appears in both factors of a product)" + ), + None, + )), + } + } + Expr::Div(left, right) => { + let left = to_affine(left, target, bindings)?; + let right = to_affine(right, target, bindings)?; + if !right.is_target_free() { + return Err(MathError::unsupported( + format!( + "cannot solve for `{target}`: the target appears in a denominator, which is outside the supported linear forms" + ), + None, + )); + } + if right.constant.is_zero() { + return Err(division_by_zero()); + } + let inverse = Numeric::exact_one().div(right.constant)?; + left.scale(inverse) + } + Expr::Pow(base, exponent) => { + if exponent.occurrences(target) > 0 { + return Err(MathError::unsupported( + format!( + "cannot solve for `{target}`: the target appears in an exponent, which is not an affine form" + ), + None, + )); + } + let exponent_value = eval_expr(exponent, bindings)?; + let exponent = integer_exponent(&exponent_value)?; + let base = to_affine(base, target, bindings)?; + if base.is_target_free() { + let value = base.constant.pow(exponent)?; + return Ok(Affine::constant(value)); + } + if exponent.is_zero() { + return Ok(Affine::constant(Numeric::exact_one())); + } + if exponent.is_one() { + return Ok(base); + } + Err(MathError::unsupported( + format!( + "cannot solve for `{target}`: the target appears in a power with exponent {exponent}, which is not an affine form" + ), + None, + )) + } + Expr::Sqrt(inner) => { + if inner.occurrences(target) > 0 { + return Err(MathError::unsupported( + format!( + "cannot solve for `{target}`: the target appears under a square root, which is not an affine form" + ), + None, + )); + } + Ok(Affine::constant(eval_expr(inner, bindings)?.sqrt()?)) + } + } +} + +/// Evaluate `formula` with `bindings`. +/// +/// For an expression the result is the exact value (or a [`Value::Float`] when +/// the exact value is not integral or an irrational operation was involved). +/// For an equation `target` selects the variable to solve for; it must occur +/// exactly once and the equation must be linear in it. +pub fn evaluate( + formula: &Formula, + bindings: &BTreeMap, + target: Option<&str>, +) -> Result { + match (&formula.kind, target) { + (FormulaKind::Expression(expr), None) => eval_expr(expr, bindings)?.into_value(), + (FormulaKind::Expression(_), Some(_)) => Err(MathError::unsupported( + "a target variable is only meaningful for an equation; the formula is a plain expression", + None, + )), + (FormulaKind::Equation { .. }, None) => Err(MathError::unsupported( + "evaluating an equation requires a target variable to solve for", + None, + )), + (FormulaKind::Equation { left, right }, Some(target)) => { + solve_equation(left, right, target, bindings) + } + } +} + +fn solve_equation( + left: &Expr, + right: &Expr, + target: &str, + bindings: &BTreeMap, +) -> Result { + if target.is_empty() { + return Err(MathError::unsupported( + "target variable name must not be empty", + None, + )); + } + if target == "pi" || target == "e" { + return Err(MathError::unsupported( + format!("`{target}` is a reserved constant, not a solvable variable"), + None, + )); + } + let occurrences = left.occurrences(target) + right.occurrences(target); + match occurrences { + 0 => { + return Err(MathError::unsupported( + format!("cannot solve for `{target}`: the variable does not occur in the equation"), + None, + )); + } + 1 => {} + count => { + return Err(MathError::unsupported( + format!( + "cannot solve for `{target}`: the variable occurs {count} times, but only a single occurrence in an affine equation is supported" + ), + None, + )); + } + } + + let left = to_affine(left, target, bindings)?; + let right = to_affine(right, target, bindings)?; + let coefficient = left.coefficient.sub(right.coefficient)?; + let constant = left.constant.sub(right.constant)?; + if coefficient.is_zero() { + return Err(MathError::unsupported( + format!( + "cannot solve for `{target}`: the equation does not uniquely determine the variable" + ), + None, + )); + } + constant.neg()?.div(coefficient)?.into_value() +} + +/// Replace every bound variable in `formula` with its exact value. +/// +/// Unbound variables stay symbolic. The returned formula gets a deterministic, +/// re-parseable [`Formula::source`] rendering; `Float` bindings are inserted as +/// the exact rational value of the `f64` (never as a rounded or lossy decimal). +pub fn substitute( + formula: &Formula, + bindings: &BTreeMap, +) -> Result { + let kind = match &formula.kind { + FormulaKind::Expression(expr) => FormulaKind::Expression(substitute_expr(expr, bindings)?), + FormulaKind::Equation { left, right } => FormulaKind::Equation { + left: substitute_expr(left, bindings)?, + right: substitute_expr(right, bindings)?, + }, + }; + let substituted = Formula { + source: String::new(), + kind, + }; + Ok(Formula { + source: substituted.render(), + kind: substituted.kind, + }) +} + +fn substitute_expr(expr: &Expr, bindings: &BTreeMap) -> Result { + match expr { + Expr::Number(_) | Expr::Constant(_) => Ok(expr.clone()), + Expr::Variable(name) => match bindings.get(name) { + None => Ok(expr.clone()), + Some(Value::Int(value)) => Ok(Expr::Number(Ratio::from_integer(value.clone()))), + Some(Value::Float(value)) => match float_to_ratio(*value) { + Some(value) => Ok(Expr::Number(value)), + None => Err(MathError::type_error( + format!( + "binding `{name}` is a non-finite Float; the math kernel only accepts finite numeric bindings" + ), + None, + )), + }, + Some(other) => Err(MathError::type_error( + format!( + "binding `{name}` has type {} but the math kernel requires Int or Float", + other.type_name() + ), + None, + )), + }, + Expr::Neg(inner) => Ok(Expr::Neg(Box::new(substitute_expr(inner, bindings)?))), + Expr::Add(left, right) => Ok(Expr::Add( + Box::new(substitute_expr(left, bindings)?), + Box::new(substitute_expr(right, bindings)?), + )), + Expr::Sub(left, right) => Ok(Expr::Sub( + Box::new(substitute_expr(left, bindings)?), + Box::new(substitute_expr(right, bindings)?), + )), + Expr::Mul(left, right) => Ok(Expr::Mul( + Box::new(substitute_expr(left, bindings)?), + Box::new(substitute_expr(right, bindings)?), + )), + Expr::Div(left, right) => Ok(Expr::Div( + Box::new(substitute_expr(left, bindings)?), + Box::new(substitute_expr(right, bindings)?), + )), + Expr::Pow(base, exponent) => Ok(Expr::Pow( + Box::new(substitute_expr(base, bindings)?), + Box::new(substitute_expr(exponent, bindings)?), + )), + Expr::Sqrt(inner) => Ok(Expr::Sqrt(Box::new(substitute_expr(inner, bindings)?))), + } +} diff --git a/crates/marqdo-math/src/lib.rs b/crates/marqdo-math/src/lib.rs new file mode 100644 index 0000000..70bb3ad --- /dev/null +++ b/crates/marqdo-math/src/lib.rs @@ -0,0 +1,171 @@ +//! Native Formula kernel for a deliberately limited, documented math subset. +//! +//! This crate is the native math kernel of the Marqdo toolchain. A Markdown math +//! node becomes an inert [`marqdo_value::FormulaValue`]; nothing is evaluated +//! implicitly. The host layer calls [`parse`], [`substitute`] and [`evaluate`] +//! explicitly, and evaluation is gated by the `math.*` capabilities. +//! +//! **The kernel never proves anything.** It computes exact or floating values +//! and solves a restricted affine equation. It does not establish a theorem, +//! does not simplify a formula into a proof obligation and must not be presented +//! as a formal verifier. See the blueprint section 5 ("原生 Math") and +//! `spec/evaluation.md`. +//! +//! # Guarantees +//! +//! * No panics on untrusted LaTeX. Malformed input, unsupported constructs, +//! unbounded work and wrong value types all become a structured [`MathError`]. +//! * Exact rational arithmetic (`num-rational` `Ratio` over `num-bigint`) is used +//! wherever possible; integers are arbitrary precision. +//! * A formula is never silently simplified, guessed or partially accepted: +//! anything outside the grammar below is an error. +//! +//! # Supported grammar +//! +//! The parser accepts exactly the following LaTeX subset (whitespace is +//! insignificant; byte offsets are reported on parse errors): +//! +//! ```text +//! formula = expr [ "=" expr ] ; single '=' only, never assignment +//! expr = term { ("+" | "-") term } ; +//! term = unary { ("*" | "/" | "·" | "×" | implicit) unary } ; +//! unary = ("+" | "-") unary | power ; +//! power = primary [ "^" unary ] ; right associative +//! primary = number +//! | identifier Unicode letter (plus digits/underscore) +//! | "\pi" | "pi" | "\e" | "e" constants +//! | "(" expr ")" | "\left(" expr "\right)" +//! | "{" expr "}" grouping +//! | "\frac{" expr "}{" expr "}" exact division +//! | "\sqrt{" expr "}" real square root +//! ; +//! number = digits [ "." digits ] | "." digits ; decimal, no exponent form +//! ``` +//! +//! Notes on the grammar: +//! +//! * `\cdot` and `\times` are accepted as synonyms for `*`. +//! * Implicit multiplication is accepted between adjacent factors where the +//! meaning is unambiguous: `2x`, `\pi r^2`, `(a)(b)` and `m a`. Concatenated +//! letters form one identifier (`ma` is the variable `ma`; write `m a` or +//! `m * a` for a product). Two adjacent number literals are a parse error. +//! * Unicode identifiers are supported (for example `面积`, `r`, `速度`). Plain +//! multi-letter identifiers are allowed as variables, but the names of common +//! elementary functions (`sin`, `cos`, `log`, `exp`, …) are reserved and +//! rejected as unsupported so that `sin(x)` is not silently read as a product. +//! * A single top-level `=` creates an equation (`F = m a`). It is **not** +//! assignment and never writes a binding. A second `=` is a parse error. +//! +//! # Unsupported constructs +//! +//! Everything outside the grammar is a structured [`MathErrorKind::Unsupported`] +//! or [`MathErrorKind::Parse`] error: matrices, sums/integrals, function calls +//! (`\sin`, `\cos`, …), multi-letter commands, `\left[`/`\right]`, mismatched or +//! missing braces, scientific notation (`1e3`), commas, arrays, subscripts, +//! superscript commands other than the `^` operator, `\frac`/`\sqrt` without +//! braced arguments, and so on. Labels, alignment characters and line breaks are +//! likewise unsupported. Underscores are ordinary identifier characters rather +//! than subscripts: `x_1` is the variable named `x_1`, not `x` subscript `1`. +//! +//! # Constants and ambiguity handling +//! +//! * `\pi` and `pi` denote the circle ratio; `\e` and `e` denote Euler's number. +//! * These spellings are **reserved**: a binding with the key `pi` or `e` never +//! overrides the constant, and they cannot be used as a solve target. Use a +//! different variable name (for example `E`, `x`, `r`). +//! * `2e` is parsed as `2 * e` (number times the constant); `2e3` is rejected as +//! scientific notation rather than silently reinterpreted. +//! +//! # Numeric semantics +//! +//! * Decimal literals are exact rationals: `0.25` is `1/4`, not a binary float. +//! * `Int` bindings become exact integers. `Float` bindings are interpreted as +//! the exact binary rational value of the `f64` (no rounding is introduced); +//! non-finite `Float` bindings are a [`MathErrorKind::Type`] error. +//! * `+ - * / ^` are exact when both operands are exact. Division keeps a +//! rational, so `\frac{1}{3} * 3` evaluates exactly to `1`. +//! * The final value is [`marqdo_value::Value::Int`] exactly when the exact result is an +//! integer, and [`marqdo_value::Value::Float`] otherwise. Consequently `1.5 + 2.5` returns +//! `Int(4)`, while `1 / 2` returns `Float(0.5)`. +//! * `\pi`, `\e` and a `\sqrt` of a non-perfect square introduce an `f64` +//! approximation; any result derived from one of them is a [`marqdo_value::Value::Float`]. +//! Precision caveats: approximations follow IEEE-754 binary64, so only about +//! 15–17 significant decimal digits are reliable and repeated operations may +//! accumulate error. The kernel never claims an approximate result is exact. +//! * `\sqrt` of a perfect square of an exact rational stays exact (`\sqrt{4}` is +//! `Int(2)`, `\sqrt{1/4}` is `Float(0.5)`); a negative radicand is a type +//! error because the subset is real-valued. +//! * The exponent of `^` must evaluate to an integer. Its magnitude is bounded by +//! [`MAX_EXPONENT`]. Integer powers with a negative exponent are exact +//! reciprocals. `0 ^ 0` is a type error. +//! * Exact intermediate/result numerators and denominators are bounded by +//! [`MAX_RESULT_BITS`]; exceeding the bound returns a structured +//! `Unsupported` error instead of hanging or exhausting memory. +//! * Parsing is bounded by [`MAX_SOURCE_BYTES`], [`MAX_PARSE_DEPTH`] and +//! [`MAX_AST_NODES`]. The node bound also bounds later recursion depth for +//! long operator chains, so hostile input cannot overflow the stack during +//! evaluation, rendering or substitution. +//! * Division by zero, `0 ^ 0` and other undefined real operations are +//! [`MathErrorKind::Type`] errors (the kernel has no dedicated division error +//! kind, so the host maps the message/kind to `runtime.division_by_zero`). +//! +//! # Equations +//! +//! [`evaluate`] of an equation requires `target`. The target must occur exactly +//! once and the equation must be affine in it. The kernel supports `+`, `-`, +//! multiplication by a target-free side, division where the target is in the +//! numerator, and inversion of those operations in either direction (`2x = 4`, +//! `4 = 2x`, `x / 2 = 3`, `3 = x / 2`). Other variables are substituted from +//! `bindings` first; missing bindings are [`MathErrorKind::UndefinedVariable`]. +//! +//! Solving a target that occurs zero times or more than once, that appears in a +//! denominator, under a root, in an exponent or in a non-affine product is a +//! structured [`MathErrorKind::Unsupported`] error. A target passed for a plain +//! expression, or an equation without a target, is likewise `Unsupported`. +//! +//! # Substitution +//! +//! [`substitute`] replaces bound variables with exact numeric literals and keeps +//! unbound variables symbolic. The returned [`Formula::source`] is a +//! deterministic canonical rendering that [`parse`] accepts again. Because the +//! rendering is canonical, it is not byte-identical to the original formatting. + +#![forbid(unsafe_code)] + +mod ast; +mod error; +mod eval; +mod parse; + +pub use ast::{render_expr, Constant, Expr, Formula, FormulaKind, Rational}; +pub use error::{MathError, MathErrorKind}; +pub use eval::{evaluate, substitute, MAX_EXPONENT, MAX_RESULT_BITS}; +pub use parse::{parse, MAX_AST_NODES, MAX_PARSE_DEPTH, MAX_SOURCE_BYTES}; + +#[cfg(test)] +mod tests { + use super::*; + use marqdo_value::Value; + use std::collections::BTreeMap; + + /// End-to-end smoke test for the API shape documented on the crate root. + #[test] + fn public_api_round_trip() { + let formula = parse("A = \\pi r^2").unwrap(); + assert!(formula.is_equation()); + assert_eq!(formula.source, "A = \\pi r^2"); + + let mut bindings = BTreeMap::new(); + bindings.insert("r".to_string(), Value::int(2)); + let area = evaluate(&formula, &bindings, Some("A")).unwrap(); + let Value::Float(area) = area else { + panic!("area should be an approximate Float"); + }; + assert!((area - std::f64::consts::PI * 4.0).abs() < 1e-12); + + let substituted = substitute(&formula, &bindings).unwrap(); + assert_eq!(substituted.source, "A = \\pi * 2 ^ 2"); + assert!(substituted.is_equation()); + assert_eq!(substituted.kind, parse("A = \\pi * 2 ^ 2").unwrap().kind); + } +} diff --git a/crates/marqdo-math/src/parse.rs b/crates/marqdo-math/src/parse.rs new file mode 100644 index 0000000..82c118a --- /dev/null +++ b/crates/marqdo-math/src/parse.rs @@ -0,0 +1,837 @@ +//! Lexer and recursive-descent parser for the documented math subset. +//! +//! The parser is intentionally strict: anything outside the subset becomes a +//! structured [`MathError`] instead of being skipped, guessed or silently +//! simplified. It never panics on untrusted input: recursion depth, source size +//! and numeric literal size are all bounded before the corresponding work +//! happens. + +use std::iter::Peekable; +use std::str::CharIndices; + +use num_bigint::BigInt; +use num_rational::Ratio; + +use crate::ast::{Constant, Expr, Formula, FormulaKind, Rational}; +use crate::error::MathError; + +/// Maximum accepted source length in bytes. Longer inputs are rejected before +/// tokenization so that a hostile formula cannot consume unbounded memory. +pub const MAX_SOURCE_BYTES: usize = 1_000_000; + +/// Maximum parser recursion depth (parentheses, groups, unary chains, fractions +/// and roots all consume one level). Deeper input is a parse error instead of a +/// stack overflow. +pub const MAX_PARSE_DEPTH: usize = 256; + +/// Maximum number of AST nodes in one formula. This bounds evaluation, +/// substitution and rendering recursion depth: a long left-associative chain +/// such as `1 + 1 + ...` would otherwise build a very deep tree even though the +/// parser loop itself is iterative. Deeper formulas are rejected with a parse +/// error instead of risking a stack overflow later. +pub const MAX_AST_NODES: usize = 512; + +/// Maximum number of digits in one numeric literal. +const MAX_LITERAL_DIGITS: usize = 100_000; + +/// Plain identifiers that name elementary functions in ordinary LaTeX. They are +/// reported as unsupported instead of being silently reinterpreted as variables +/// or implicit multiplication. +const FUNCTION_NAMES: &[&str] = &[ + "sin", "cos", "tan", "cot", "sec", "csc", "arcsin", "arccos", "arctan", "sinh", "cosh", "tanh", + "log", "ln", "lg", "exp", "abs", "min", "max", "floor", "ceil", "round", "det", "dim", "gcd", + "lcm", "lim", "sup", "inf", "arg", "Re", "Im", +]; + +#[derive(Debug, Clone, PartialEq)] +enum TokenKind { + Number(Rational), + Ident(String), + Constant(Constant), + Plus, + Minus, + Star, + Slash, + Caret, + LParen, + RParen, + LBrace, + RBrace, + Equals, + Frac, + Sqrt, + Eof, +} + +#[derive(Debug, Clone)] +struct Token { + kind: TokenKind, + /// Byte offset of the first byte of the token. + start: usize, +} + +impl Token { + fn describe(&self) -> String { + match &self.kind { + TokenKind::Number(_) => "a number".to_string(), + TokenKind::Ident(name) => format!("identifier `{name}`"), + TokenKind::Constant(constant) => match constant { + Constant::Pi => "`\\pi`".to_string(), + Constant::E => "`\\e`".to_string(), + }, + TokenKind::Plus => "`+`".to_string(), + TokenKind::Minus => "`-`".to_string(), + TokenKind::Star => "`*`".to_string(), + TokenKind::Slash => "`/`".to_string(), + TokenKind::Caret => "`^`".to_string(), + TokenKind::LParen => "`(`".to_string(), + TokenKind::RParen => "`)`".to_string(), + TokenKind::LBrace => "`{`".to_string(), + TokenKind::RBrace => "`}`".to_string(), + TokenKind::Equals => "`=`".to_string(), + TokenKind::Frac => "`\\frac`".to_string(), + TokenKind::Sqrt => "`\\sqrt`".to_string(), + TokenKind::Eof => "the end of the formula".to_string(), + } + } +} + +/// Parse `latex` into a [`Formula`]. +/// +/// The supported grammar is documented on the crate root. The returned formula +/// keeps the original source in [`Formula::source`] and exposes the parsed +/// [`FormulaKind`] for inspection. +pub fn parse(latex: &str) -> Result { + if latex.len() > MAX_SOURCE_BYTES { + return Err(MathError::parse( + format!( + "formula source is {} bytes; the supported limit is {MAX_SOURCE_BYTES} bytes", + latex.len() + ), + Some(0), + )); + } + let tokens = lex(latex)?; + Parser { + tokens, + position: 0, + depth: 0, + nodes: 0, + } + .parse_formula(latex) +} + +fn lex(source: &str) -> Result, MathError> { + Lexer { + source, + chars: source.char_indices().peekable(), + tokens: Vec::new(), + } + .run() +} + +struct Lexer<'a> { + source: &'a str, + chars: Peekable>, + tokens: Vec, +} + +impl<'a> Lexer<'a> { + fn run(mut self) -> Result, MathError> { + while let Some(&(start, ch)) = self.chars.peek() { + if ch.is_whitespace() { + self.chars.next(); + continue; + } + let kind = match ch { + '+' => { + self.chars.next(); + TokenKind::Plus + } + '-' => { + self.chars.next(); + TokenKind::Minus + } + '*' => { + self.chars.next(); + TokenKind::Star + } + '/' => { + self.chars.next(); + TokenKind::Slash + } + '^' => { + self.chars.next(); + TokenKind::Caret + } + '(' => { + self.chars.next(); + TokenKind::LParen + } + ')' => { + self.chars.next(); + TokenKind::RParen + } + '{' => { + self.chars.next(); + TokenKind::LBrace + } + '}' => { + self.chars.next(); + TokenKind::RBrace + } + '=' => { + self.chars.next(); + TokenKind::Equals + } + '\\' => self.lex_command()?, + ch if ch.is_ascii_digit() || ch == '.' => self.lex_number()?, + ch if is_ident_start(ch) => self.lex_identifier()?, + other => { + return Err(MathError::unsupported( + format!("unsupported character `{other}` in a formula"), + Some(start), + )); + } + }; + self.tokens.push(Token { kind, start }); + } + self.tokens.push(Token { + kind: TokenKind::Eof, + start: self.source.len(), + }); + Ok(self.tokens) + } + + fn lex_identifier(&mut self) -> Result { + let start = self.current_offset(); + let mut text = String::new(); + while let Some(&(_, ch)) = self.chars.peek() { + if is_ident_continue(ch) { + text.push(ch); + self.chars.next(); + } else { + break; + } + } + match text.as_str() { + "pi" => Ok(TokenKind::Constant(Constant::Pi)), + "e" => Ok(TokenKind::Constant(Constant::E)), + _ if FUNCTION_NAMES.contains(&text.as_str()) => Err(MathError::unsupported( + format!( + "function `{text}` is not supported; the native math subset has no function calls" + ), + Some(start), + )), + _ => Ok(TokenKind::Ident(text)), + } + } + + /// Byte offset of the next unconsumed character (or the source end). + fn current_offset(&mut self) -> usize { + match self.chars.peek() { + Some(&(offset, _)) => offset, + None => self.source.len(), + } + } + + fn lex_number(&mut self) -> Result { + let start = self.current_offset(); + let mut integer_digits = String::new(); + while let Some(&(_, ch)) = self.chars.peek() { + if ch.is_ascii_digit() { + integer_digits.push(ch); + self.chars.next(); + } else { + break; + } + } + + let mut fraction_digits = String::new(); + if matches!(self.chars.peek(), Some(&(_, '.'))) { + self.chars.next(); + while let Some(&(_, ch)) = self.chars.peek() { + if ch.is_ascii_digit() { + fraction_digits.push(ch); + self.chars.next(); + } else { + break; + } + } + if fraction_digits.is_empty() { + return Err(MathError::parse( + "malformed decimal literal: expected digits after `.`", + Some(start), + )); + } + } + + if integer_digits.is_empty() && fraction_digits.is_empty() { + return Err(MathError::parse("malformed numeric literal", Some(start))); + } + if integer_digits.len() + fraction_digits.len() > MAX_LITERAL_DIGITS { + return Err(MathError::parse( + format!( + "numeric literal has more than {MAX_LITERAL_DIGITS} digits, which is outside the supported resource bound" + ), + Some(start), + )); + } + + // Reject scientific notation (`1e3`) explicitly: it is outside the + // subset and would otherwise parse as `1 * e3`. + if matches!(self.chars.peek(), Some(&(_, 'e' | 'E'))) + && self.number_is_followed_by_exponent() + { + return Err(MathError::parse( + "scientific notation is not supported; write an explicit product such as `2 * 10 ^ 3`", + Some(start), + )); + } + + let integer_text = if integer_digits.is_empty() { + "0" + } else { + &integer_digits + }; + let numerator = parse_bigint(integer_text, start)?; + if fraction_digits.is_empty() { + return Ok(TokenKind::Number(Ratio::from_integer(numerator))); + } + let mut all_digits = String::with_capacity(integer_digits.len() + fraction_digits.len()); + all_digits.push_str(if integer_digits.is_empty() { + "0" + } else { + &integer_digits + }); + all_digits.push_str(&fraction_digits); + let numerator = parse_bigint(&all_digits, start)?; + let denominator = BigInt::from(10_u32).pow(fraction_digits.len() as u32); + Ok(TokenKind::Number(Ratio::new(numerator, denominator))) + } + + /// Look past the current `e`/`E` to decide whether it introduces an + /// exponent (`1e3`, `1e-3`) rather than the Euler constant (`2e`). + fn number_is_followed_by_exponent(&self) -> bool { + let mut chars = self.chars.clone(); + let _ = chars.next(); // the 'e' / 'E' + match chars.next().map(|(_, ch)| ch) { + Some(ch) if ch.is_ascii_digit() => true, + Some('+' | '-') => { + matches!(chars.next().map(|(_, ch)| ch), Some(ch) if ch.is_ascii_digit()) + } + _ => false, + } + } + + fn lex_command(&mut self) -> Result { + let start = self.current_offset(); + self.chars.next(); // consume the backslash + let mut name = String::new(); + while let Some(&(_, ch)) = self.chars.peek() { + if ch.is_ascii_alphabetic() { + name.push(ch); + self.chars.next(); + } else { + break; + } + } + match name.as_str() { + "pi" => Ok(TokenKind::Constant(Constant::Pi)), + "e" => Ok(TokenKind::Constant(Constant::E)), + "cdot" | "times" => Ok(TokenKind::Star), + "frac" => Ok(TokenKind::Frac), + "sqrt" => Ok(TokenKind::Sqrt), + "left" => self.lex_left_right(start, '('), + "right" => self.lex_left_right(start, ')'), + "" => Err(MathError::unsupported( + "unsupported LaTeX control symbol; only alphabetic commands such as `\\pi` are supported", + Some(start), + )), + other => Err(MathError::unsupported( + format!( + "unsupported LaTeX command `\\{other}`; the native math subset only supports `\\frac`, `\\sqrt`, `\\cdot`, `\\times`, `\\left(`, `\\right)`, `\\pi` and `\\e`" + ), + Some(start), + )), + } + } + + fn lex_left_right(&mut self, start: usize, expected: char) -> Result { + while let Some(&(_, ch)) = self.chars.peek() { + if ch.is_whitespace() { + self.chars.next(); + } else { + break; + } + } + match self.chars.next() { + Some((_, ch)) if ch == expected => Ok(if expected == '(' { + TokenKind::LParen + } else { + TokenKind::RParen + }), + _ => Err(MathError::unsupported( + format!( + "only the parenthesis forms `\\left(` and `\\right)` are supported, not `\\{}` followed by another delimiter", + if expected == '(' { "left" } else { "right" } + ), + Some(start), + )), + } + } +} + +fn parse_bigint(digits: &str, position: usize) -> Result { + digits + .parse::() + .map_err(|_| MathError::parse("numeric literal is too large to represent", Some(position))) +} + +fn is_ident_start(ch: char) -> bool { + ch.is_alphabetic() || ch == '_' +} + +fn is_ident_continue(ch: char) -> bool { + ch.is_alphanumeric() || ch == '_' +} + +struct Parser { + tokens: Vec, + position: usize, + depth: usize, + nodes: usize, +} + +impl Parser { + fn peek(&self) -> &Token { + // The lexer always appends an Eof token, so indexing is in bounds. + &self.tokens[self.position.min(self.tokens.len() - 1)] + } + + fn advance(&mut self) -> Token { + let token = self.peek().clone(); + if self.position < self.tokens.len() - 1 { + self.position += 1; + } + token + } + + /// Record one constructed AST node, enforcing [`MAX_AST_NODES`]. + fn node(&mut self, expr: Expr) -> Result { + self.nodes += 1; + if self.nodes > MAX_AST_NODES { + return Err(MathError::parse( + format!( + "formula contains more than the supported limit of {MAX_AST_NODES} syntax nodes" + ), + Some(self.peek().start), + )); + } + Ok(expr) + } + + fn enter_depth(&mut self) -> Result<(), MathError> { + self.depth += 1; + if self.depth > MAX_PARSE_DEPTH { + return Err(MathError::parse( + format!("formula nesting exceeds the supported limit of {MAX_PARSE_DEPTH} levels"), + Some(self.peek().start), + )); + } + Ok(()) + } + + fn parse_formula(mut self, source: &str) -> Result { + if matches!(self.peek().kind, TokenKind::Eof) { + return Err(MathError::parse("empty formula", Some(0))); + } + let left = self.parse_expr()?; + let kind = if matches!(self.peek().kind, TokenKind::Equals) { + let equals = self.advance(); + if matches!(self.peek().kind, TokenKind::Eof) { + return Err(MathError::parse( + "expected a right-hand side after `=`", + Some(equals.start + 1), + )); + } + let right = self.parse_expr()?; + if matches!(self.peek().kind, TokenKind::Equals) { + return Err(MathError::parse( + "more than one `=` in a formula; at most one equation is supported and `=` is never assignment", + Some(self.peek().start), + )); + } + FormulaKind::Equation { left, right } + } else { + FormulaKind::Expression(left) + }; + if !matches!(self.peek().kind, TokenKind::Eof) { + return Err(MathError::parse( + format!("unexpected {} after the formula", self.peek().describe()), + Some(self.peek().start), + )); + } + Ok(Formula { + source: source.to_string(), + kind, + }) + } + + fn parse_expr(&mut self) -> Result { + let mut left = self.parse_term()?; + loop { + match self.peek().kind { + TokenKind::Plus => { + self.advance(); + let right = self.parse_term()?; + left = self.node(Expr::Add(Box::new(left), Box::new(right)))?; + } + TokenKind::Minus => { + self.advance(); + let right = self.parse_term()?; + left = self.node(Expr::Sub(Box::new(left), Box::new(right)))?; + } + _ => return Ok(left), + } + } + } + + fn parse_term(&mut self) -> Result { + let mut left = self.parse_unary()?; + loop { + if matches!(self.peek().kind, TokenKind::Star) { + self.advance(); + let right = self.parse_unary()?; + left = self.node(Expr::Mul(Box::new(left), Box::new(right)))?; + } else if matches!(self.peek().kind, TokenKind::Slash) { + self.advance(); + let right = self.parse_unary()?; + left = self.node(Expr::Div(Box::new(left), Box::new(right)))?; + } else if can_start_primary(&self.peek().kind) { + if matches!(left, Expr::Number(_)) + && matches!(self.peek().kind, TokenKind::Number(_)) + { + return Err(MathError::parse( + "two adjacent number literals are ambiguous; insert an operator", + Some(self.peek().start), + )); + } + // Implicit multiplication: `2x`, `\pi r^2`, `m a`. + let right = self.parse_unary()?; + left = self.node(Expr::Mul(Box::new(left), Box::new(right)))?; + } else { + return Ok(left); + } + } + } + + fn parse_unary(&mut self) -> Result { + self.enter_depth()?; + let result = self.parse_unary_inner(); + self.depth -= 1; + result + } + + fn parse_unary_inner(&mut self) -> Result { + match self.peek().kind { + TokenKind::Minus => { + self.advance(); + let inner = self.parse_unary()?; + self.node(Expr::Neg(Box::new(inner))) + } + TokenKind::Plus => { + self.advance(); + self.parse_unary() + } + _ => self.parse_power(), + } + } + + fn parse_power(&mut self) -> Result { + let base = self.parse_primary()?; + if matches!(self.peek().kind, TokenKind::Caret) { + self.advance(); + let exponent = self.parse_unary()?; + return self.node(Expr::Pow(Box::new(base), Box::new(exponent))); + } + Ok(base) + } + + fn parse_primary(&mut self) -> Result { + self.enter_depth()?; + let result = self.parse_primary_inner(); + self.depth -= 1; + result + } + + fn parse_primary_inner(&mut self) -> Result { + let token = self.peek().clone(); + match token.kind { + TokenKind::Number(value) => { + self.advance(); + self.node(Expr::Number(value)) + } + TokenKind::Ident(name) => { + self.advance(); + self.node(Expr::Variable(name)) + } + TokenKind::Constant(constant) => { + self.advance(); + self.node(Expr::Constant(constant)) + } + TokenKind::LParen => { + self.advance(); + let inner = self.parse_expr()?; + self.expect_closing(TokenKind::RParen, "`)`", token.start)?; + Ok(inner) + } + TokenKind::LBrace => { + self.advance(); + let inner = self.parse_expr()?; + self.expect_closing(TokenKind::RBrace, "`}`", token.start)?; + Ok(inner) + } + TokenKind::Frac => { + self.advance(); + let numerator = self.parse_braced_argument("\\frac")?; + let denominator = self.parse_braced_argument("\\frac")?; + self.node(Expr::Div(Box::new(numerator), Box::new(denominator))) + } + TokenKind::Sqrt => { + self.advance(); + let inner = self.parse_braced_argument("\\sqrt")?; + self.node(Expr::Sqrt(Box::new(inner))) + } + TokenKind::Eof => Err(MathError::parse( + "expected an expression, found the end of the formula", + Some(token.start), + )), + other => Err(MathError::parse( + format!( + "expected an expression, found {}", + Token { + kind: other, + start: token.start + } + .describe() + ), + Some(token.start), + )), + } + } + + fn parse_braced_argument(&mut self, command: &str) -> Result { + if !matches!(self.peek().kind, TokenKind::LBrace) { + return Err(MathError::parse( + format!("`{command}` requires a braced argument such as `{command}{{x}}`"), + Some(self.peek().start), + )); + } + let open = self.advance(); + let inner = self.parse_expr()?; + self.expect_closing(TokenKind::RBrace, "`}`", open.start)?; + Ok(inner) + } + + fn expect_closing( + &mut self, + expected: TokenKind, + description: &str, + open_position: usize, + ) -> Result<(), MathError> { + if std::mem::discriminant(&self.peek().kind) == std::mem::discriminant(&expected) { + self.advance(); + Ok(()) + } else { + Err(MathError::parse( + format!( + "expected {description} to close the group opened at byte {open_position}, found {}", + self.peek().describe() + ), + Some(self.peek().start), + )) + } + } +} + +fn can_start_primary(kind: &TokenKind) -> bool { + matches!( + kind, + TokenKind::Number(_) + | TokenKind::Ident(_) + | TokenKind::Constant(_) + | TokenKind::LParen + | TokenKind::LBrace + | TokenKind::Frac + | TokenKind::Sqrt + ) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn parse_ok(source: &str) -> Formula { + parse(source).unwrap_or_else(|err| panic!("expected {source:?} to parse: {err}")) + } + + fn parse_err(source: &str) -> MathError { + parse(source).unwrap_err() + } + + #[test] + fn precedence_matches_standard_arithmetic() { + let formula = parse_ok("1 + 2 * 3"); + assert_eq!( + formula.kind, + FormulaKind::Expression(Expr::Add( + Box::new(Expr::Number(Ratio::from_integer(BigInt::from(1)))), + Box::new(Expr::Mul( + Box::new(Expr::Number(Ratio::from_integer(BigInt::from(2)))), + Box::new(Expr::Number(Ratio::from_integer(BigInt::from(3)))), + )), + )) + ); + } + + #[test] + fn unary_minus_binds_looser_than_power() { + // -2^2 is -(2^2), not (-2)^2. + let formula = parse_ok("-2^2"); + assert!(matches!( + formula.kind, + FormulaKind::Expression(Expr::Neg(_)) + )); + } + + #[test] + fn power_is_right_associative() { + let formula = parse_ok("2^3^2"); + let FormulaKind::Expression(Expr::Pow(_, exponent)) = formula.kind else { + panic!("expected a power"); + }; + assert!(matches!(*exponent, Expr::Pow(_, _))); + } + + #[test] + fn implicit_multiplication_joins_adjacent_factors() { + let formula = parse_ok("\\pi r^2"); + let FormulaKind::Expression(Expr::Mul(left, right)) = formula.kind else { + panic!("expected multiplication"); + }; + assert!(matches!(*left, Expr::Constant(Constant::Pi))); + assert!(matches!(*right, Expr::Pow(_, _))); + + // `F = m a` is an equation whose right side is a product. + let formula = parse_ok("F = m a"); + let FormulaKind::Equation { right, .. } = formula.kind else { + panic!("expected an equation"); + }; + assert!(matches!(right, Expr::Mul(_, _))); + } + + #[test] + fn left_and_right_parentheses_are_accepted() { + assert_eq!( + parse_ok("\\left(1 + 2\\right) * 3").kind, + parse_ok("(1 + 2) * 3").kind + ); + } + + #[test] + fn frac_and_sqrt_become_dedicated_nodes() { + let formula = parse_ok("\\frac{1}{2} + \\sqrt{4}"); + let FormulaKind::Expression(Expr::Add(left, right)) = formula.kind else { + panic!("expected addition"); + }; + assert!(matches!(*left, Expr::Div(_, _))); + assert!(matches!(*right, Expr::Sqrt(_))); + } + + #[test] + fn single_equals_is_an_equation() { + let formula = parse_ok("A = \\pi r^2"); + assert!(formula.is_equation()); + assert_eq!(formula.variables().len(), 2); + } + + #[test] + fn more_than_one_equals_is_a_parse_error() { + let err = parse_err("a = b = c"); + assert_eq!(err.kind, crate::error::MathErrorKind::Parse); + assert!(err.message.contains("more than one")); + } + + #[test] + fn empty_and_malformed_input_is_a_parse_error() { + assert_eq!(parse_err("").kind, crate::error::MathErrorKind::Parse); + for source in ["1 +", "(1 + 2", "\\frac{1}{2", "{1 + 2", "1 + 2)", "= 3"] { + let err = parse_err(source); + assert_eq!( + err.kind, + crate::error::MathErrorKind::Parse, + "source {source:?}" + ); + assert!(err.position.is_some(), "source {source:?}"); + } + } + + #[test] + fn unsupported_commands_are_structured() { + for source in [ + "\\begin{matrix}1&2\\end{matrix}", + "\\int_0^1 x dx", + "\\sin(x)", + "\\sum_{i=1}^n i", + "sin(1)", + ] { + let err = parse_err(source); + assert_eq!( + err.kind, + crate::error::MathErrorKind::Unsupported, + "source {source:?}" + ); + } + } + + #[test] + fn unknown_characters_are_structured() { + let err = parse_err("1, 2"); + assert_eq!(err.kind, crate::error::MathErrorKind::Unsupported); + assert!(err.message.contains("unsupported character")); + } + + #[test] + fn deep_nesting_is_rejected_without_stack_overflow() { + let source = format!("{}1{}", "(".repeat(10_000), ")".repeat(10_000)); + let err = parse_err(&source); + assert_eq!(err.kind, crate::error::MathErrorKind::Parse); + assert!(err.message.contains("nesting")); + } + + #[test] + fn excessive_node_count_is_rejected() { + // A long left-associative chain is cheap to parse iteratively but would + // build a very deep tree; the node budget rejects it first. + let source = format!("{}1", "1 + ".repeat(MAX_AST_NODES)); + let err = parse_err(&source); + assert_eq!(err.kind, crate::error::MathErrorKind::Parse); + assert!(err.message.contains("syntax nodes"), "{}", err.message); + } + + #[test] + fn very_long_chain_is_rejected_without_stack_overflow() { + let source = format!("{}1", "1 + ".repeat(200_000)); + let err = parse_err(&source); + assert_eq!(err.kind, crate::error::MathErrorKind::Parse); + } + + #[test] + fn numeric_literal_bounds_are_enforced() { + let source = "9".repeat(MAX_LITERAL_DIGITS + 1); + let err = parse_err(&source); + assert_eq!(err.kind, crate::error::MathErrorKind::Parse); + assert!(err.message.contains("digits")); + } +} diff --git a/crates/marqdo-math/tests/kernel.rs b/crates/marqdo-math/tests/kernel.rs new file mode 100644 index 0000000..4ce7f6a --- /dev/null +++ b/crates/marqdo-math/tests/kernel.rs @@ -0,0 +1,596 @@ +//! End-to-end tests for the native Formula kernel. +//! +//! These tests exercise the public contract used by the host layer: +//! `parse`, `evaluate` and `substitute`. They cover the documented grammar, +//! exact numeric semantics, equation solving, structured errors and resource +//! bounds. + +use std::collections::BTreeMap; + +use marqdo_math::{evaluate, parse, substitute, MathError, MathErrorKind, MAX_EXPONENT}; +use marqdo_value::Value; +use num_bigint::BigInt; + +fn empty() -> BTreeMap { + BTreeMap::new() +} + +fn bindings(entries: &[(&str, Value)]) -> BTreeMap { + entries + .iter() + .map(|(name, value)| ((*name).to_string(), value.clone())) + .collect() +} + +fn eval(source: &str, bindings: &BTreeMap) -> Result { + evaluate(&parse(source).expect("fixture must parse"), bindings, None) +} + +fn solve( + source: &str, + bindings: &BTreeMap, + target: &str, +) -> Result { + evaluate( + &parse(source).expect("fixture must parse"), + bindings, + Some(target), + ) +} + +fn assert_int(value: &Value, expected: i64) { + assert_eq!(value, &Value::int(expected), "value was {value:?}"); +} + +fn assert_float_close(value: &Value, expected: f64) { + let Value::Float(actual) = value else { + panic!("expected a Float, got {value:?}"); + }; + assert!( + (actual - expected).abs() <= 1e-12 * expected.abs().max(1.0), + "expected {expected}, got {actual}" + ); +} + +#[test] +fn precedence_and_parentheses() { + assert_int(&eval("1 + 2 * 3", &empty()).unwrap(), 7); + assert_int(&eval("(1 + 2) * 3", &empty()).unwrap(), 9); + assert_int(&eval("10 - 3 - 2", &empty()).unwrap(), 5); + assert_int(&eval("8 / 4 / 2", &empty()).unwrap(), 1); + assert_int(&eval("2 + 3 * 4 ^ 2", &empty()).unwrap(), 50); + // Power is right associative, unary minus binds looser than power. + assert_int(&eval("2 ^ 3 ^ 2", &empty()).unwrap(), 512); + assert_int(&eval("-2 ^ 2", &empty()).unwrap(), -4); + assert_int(&eval("(-2) ^ 2", &empty()).unwrap(), 4); +} + +#[test] +fn exact_big_integer_arithmetic() { + let Value::Int(power) = eval("2 ^ 100", &empty()).unwrap() else { + panic!("expected an Int"); + }; + assert_eq!(power.to_string(), "1267650600228229401496703205376"); + + let Value::Int(product) = eval( + "123456789012345678901234567890 * 987654321098765432109876543210", + &empty(), + ) + .unwrap() else { + panic!("expected an Int"); + }; + assert_eq!( + product.to_string(), + "121932631137021795226185032733622923332237463801111263526900" + ); + + let Value::Int(sum) = eval("2 ^ 200 + 1", &empty()).unwrap() else { + panic!("expected an Int"); + }; + assert_eq!( + sum.to_string(), + "1606938044258990275541962092341162602522202993782792835301377" + ); +} + +#[test] +fn division_stays_exact_when_it_reduces_to_an_integer() { + // 1/3 alone is a Float approximation, but three of them are exactly 1. + assert_int(&eval("(1 / 3) * 3", &empty()).unwrap(), 1); + assert_int(&eval("(2 / 7) * 7", &empty()).unwrap(), 2); + assert_int(&eval("100 / 4", &empty()).unwrap(), 25); + + assert_float_close(&eval("10 / 4", &empty()).unwrap(), 2.5); + assert_float_close(&eval("1 / 3", &empty()).unwrap(), 1.0 / 3.0); +} + +#[test] +fn decimal_literals_are_exact_rationals() { + // 1.5 + 2.5 is exactly 4, which is integral, so the result is an Int. + assert_int(&eval("1.5 + 2.5", &empty()).unwrap(), 4); + assert_int(&eval("0.25 * 4", &empty()).unwrap(), 1); + assert_float_close(&eval("0.1 + 0.2", &empty()).unwrap(), 0.3); + assert_float_close(&eval(".5 + 1", &empty()).unwrap(), 1.5); +} + +#[test] +fn pi_r_squared_area() { + let mut bindings = empty(); + bindings.insert("r".to_string(), Value::int(2)); + let value = solve("A = \\pi r^2", &bindings, "A").unwrap(); + assert_float_close(&value, std::f64::consts::PI * 4.0); +} + +#[test] +fn perfect_and_non_perfect_square_roots() { + assert_int(&eval("\\sqrt{16}", &empty()).unwrap(), 4); + assert_int(&eval("\\sqrt{0}", &empty()).unwrap(), 0); + // \sqrt{1/4} = 1/2: exact but not integral, so it is a Float value. + assert_float_close(&eval("\\sqrt{\\frac{1}{4}}", &empty()).unwrap(), 0.5); + // Non-perfect squares are explicitly approximate Floats. + assert_float_close( + &eval("\\sqrt{2}", &empty()).unwrap(), + std::f64::consts::SQRT_2, + ); + assert_float_close(&eval("\\sqrt{2} * \\sqrt{2}", &empty()).unwrap(), 2.0); + let err = eval("\\sqrt{-4}", &empty()).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Type); +} + +#[test] +fn frac_is_exact_division() { + assert_int(&eval("\\frac{6}{2}", &empty()).unwrap(), 3); + assert_float_close(&eval("\\frac{6}{4}", &empty()).unwrap(), 1.5); + assert_float_close( + &eval("\\frac{\\frac{1}{2}}{\\frac{3}{4}}", &empty()).unwrap(), + 2.0 / 3.0, + ); + assert_int(&eval("\\frac{1}{3} + \\frac{2}{3}", &empty()).unwrap(), 1); +} + +#[test] +fn left_right_parentheses_and_nesting() { + assert_int( + &eval( + "\\left(\\left(1 + 2\\right) * \\left(3 + 4\\right)\\right)", + &empty(), + ) + .unwrap(), + 21, + ); + assert_int(&eval("\\left(1 + 2\\right) * 3", &empty()).unwrap(), 9); + assert_int(&eval("((((1 + 2)))) * 3", &empty()).unwrap(), 9); + assert_int(&eval("2 * {3 + 4}", &empty()).unwrap(), 14); +} + +#[test] +fn unicode_identifiers() { + let bindings = bindings(&[("半径", Value::int(3))]); + assert_float_close( + &solve("面积 = \\pi 半径^2", &bindings, "面积").unwrap(), + std::f64::consts::PI * 9.0, + ); + let substituted = substitute(&parse("半径 + 1").unwrap(), &bindings).unwrap(); + assert_eq!(substituted.source, "3 + 1"); + assert_int(&eval(&substituted.source, &empty()).unwrap(), 4); +} + +#[test] +fn constants_and_their_ambiguity_rules() { + assert_float_close(&eval("\\pi", &empty()).unwrap(), std::f64::consts::PI); + assert_float_close(&eval("pi", &empty()).unwrap(), std::f64::consts::PI); + assert_float_close(&eval("\\e", &empty()).unwrap(), std::f64::consts::E); + assert_float_close(&eval("e", &empty()).unwrap(), std::f64::consts::E); + // `2e` is 2 times the constant, not scientific notation. + assert_float_close(&eval("2e", &empty()).unwrap(), 2.0 * std::f64::consts::E); + // `pi` and `e` are reserved: bindings do not shadow the constants. + let bindings = bindings(&[("pi", Value::int(3)), ("e", Value::int(3))]); + assert_float_close(&eval("pi", &bindings).unwrap(), std::f64::consts::PI); + assert_float_close(&eval("e", &bindings).unwrap(), std::f64::consts::E); + assert_eq!( + solve("pi = 3", &empty(), "pi").unwrap_err().kind, + MathErrorKind::Unsupported + ); +} + +#[test] +fn f_equals_m_a_solved_for_m() { + let bindings = bindings(&[("F", Value::int(12)), ("a", Value::int(3))]); + assert_int(&solve("F = m a", &bindings, "m").unwrap(), 4); + // F = m a is an equation, not assignment: solving for m never rebinds F. + assert_eq!(bindings.get("F"), Some(&Value::int(12))); +} + +#[test] +fn f_equals_m_a_solved_for_a() { + let bindings = bindings(&[("F", Value::int(12)), ("m", Value::int(3))]); + assert_int(&solve("F = m a", &bindings, "a").unwrap(), 4); +} + +#[test] +fn f_equals_m_a_solved_for_f() { + let bindings = bindings(&[("m", Value::int(3)), ("a", Value::int(4))]); + assert_int(&solve("F = m a", &bindings, "F").unwrap(), 12); +} + +#[test] +fn linear_equation_solving_both_directions() { + // Target on the left and on the right; multiplication and division by a + // target-free side are both inverted. + assert_int(&solve("2 x = 4", &empty(), "x").unwrap(), 2); + assert_int(&solve("4 = 2 x", &empty(), "x").unwrap(), 2); + assert_int(&solve("x / 2 = 3", &empty(), "x").unwrap(), 6); + assert_int(&solve("3 = x / 2", &empty(), "x").unwrap(), 6); + assert_int(&solve("x + 2 = 5", &empty(), "x").unwrap(), 3); + assert_int(&solve("2 + x = 5", &empty(), "x").unwrap(), 3); + assert_int(&solve("2 x + 1 = 7", &empty(), "x").unwrap(), 3); + assert_int(&solve("x = 4", &empty(), "x").unwrap(), 4); + assert_int(&solve("x / 4 = 1 / 2", &empty(), "x").unwrap(), 2); + assert_int(&solve("(x + 1) * 2 = 8", &empty(), "x").unwrap(), 3); + + // Other variables are substituted first. + let bindings = bindings(&[("y", Value::int(3))]); + assert_int(&solve("x = 2 y + 1", &bindings, "x").unwrap(), 7); +} + +#[test] +fn equation_solving_requires_exactly_one_affine_occurrence() { + assert_eq!( + solve("x + x = 4", &empty(), "x").unwrap_err().kind, + MathErrorKind::Unsupported + ); + assert_eq!( + solve("x * x = 4", &empty(), "x").unwrap_err().kind, + MathErrorKind::Unsupported + ); + assert_eq!( + solve("x ^ 2 = 4", &empty(), "x").unwrap_err().kind, + MathErrorKind::Unsupported + ); + assert_eq!( + solve("1 / x = 2", &empty(), "x").unwrap_err().kind, + MathErrorKind::Unsupported + ); + assert_eq!( + solve("\\sqrt{x} = 2", &empty(), "x").unwrap_err().kind, + MathErrorKind::Unsupported + ); + assert_eq!( + solve("2 = 4", &empty(), "x").unwrap_err().kind, + MathErrorKind::Unsupported + ); + assert_eq!( + solve("x * 0 = 1", &empty(), "x").unwrap_err().kind, + MathErrorKind::Unsupported + ); +} + +#[test] +fn target_errors_are_structured() { + let err = evaluate(&parse("A = 2").unwrap(), &empty(), None).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Unsupported); + assert!(err.message.contains("target")); + + let err = evaluate(&parse("1 + 2").unwrap(), &empty(), Some("x")).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Unsupported); + + let err = solve("A = 2", &empty(), "B").unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Unsupported); + assert!(err.message.contains("does not occur")); + + let err = solve("A = 2", &empty(), "").unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Unsupported); +} + +#[test] +fn unsupported_constructs_are_structured() { + for source in [ + "\\begin{matrix} 1 & 2 \\\\ 3 & 4 \\end{matrix}", + "\\int_0^1 x dx", + "\\sin(x)", + "\\cos(x) + 1", + "\\sum_{i=1}^{n} i", + "\\alpha + 1", + "\\frac12", + "1e3", + "\\left[ 1, 2 \\right]", + ] { + let err = parse(source).unwrap_err(); + assert!( + matches!(err.kind, MathErrorKind::Unsupported | MathErrorKind::Parse), + "source {source:?} produced {err:?}" + ); + assert!( + err.position.is_some(), + "source {source:?} lost its position" + ); + } +} + +#[test] +fn malformed_latex_is_a_parse_error_with_position() { + for source in [ + "", + "1 +", + "(1 + 2", + "\\frac{1}{2", + "\\frac{1}", + "\\sqrt 2", + "{1 + 2", + "1 + 2}", + "1 + 2)", + "1.2.3", + "1 2", + "a = b = c", + ] { + let err = parse(source).unwrap_err(); + assert_eq!( + err.kind, + MathErrorKind::Parse, + "source {source:?} produced {err:?}" + ); + assert!(err.position.is_some(), "source {source:?}"); + } +} + +#[test] +fn undefined_variables_are_reported() { + let err = eval("1 + x", &empty()).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::UndefinedVariable); + assert!(err.message.contains('x')); + + let err = solve("A = x + 1", &empty(), "A").unwrap_err(); + assert_eq!(err.kind, MathErrorKind::UndefinedVariable); +} + +#[test] +fn non_numeric_bindings_are_type_errors() { + for value in [ + Value::Bool(true), + Value::text("two"), + Value::List(vec![Value::int(2)]), + Value::None, + Value::Float(f64::NAN), + Value::Float(f64::INFINITY), + ] { + let err = eval("x + 1", &bindings(&[("x", value)])).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Type); + } + // Unused bindings of other types are irrelevant. + assert_int( + &eval("1 + 1", &bindings(&[("x", Value::text("unused"))])).unwrap(), + 2, + ); +} + +#[test] +fn float_bindings_are_exact_numeric_values() { + let bindings = bindings(&[("x", Value::Float(2.5))]); + assert_float_close(&eval("x", &bindings).unwrap(), 2.5); + // 2.5 + 0.5 is exactly 3, so the exact-result rule yields an Int. + assert_int(&eval("x + 0.5", &bindings).unwrap(), 3); + assert_float_close(&eval("x / 2", &bindings).unwrap(), 1.25); +} + +#[test] +fn division_by_zero_is_a_structured_error() { + for source in ["1 / 0", "\\frac{1}{0}", "1 / (2 - 2)"] { + let err = eval(source, &empty()).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Type, "source {source:?}"); + assert!( + err.message.contains("division by zero"), + "source {source:?} produced {err:?}" + ); + } + let err = solve("x / 0 = 1", &empty(), "x").unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Type); +} + +#[test] +fn exponent_must_be_an_integer() { + for source in ["2 ^ 0.5", "2 ^ \\frac{1}{2}", "2 ^ \\pi"] { + let err = eval(source, &empty()).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Type, "source {source:?}"); + } +} + +#[test] +fn negative_integer_exponents_are_exact_reciprocals() { + assert_float_close(&eval("2 ^ -3", &empty()).unwrap(), 0.125); + assert_int(&eval("(1 / 2) ^ -2", &empty()).unwrap(), 4); + let err = eval("0 ^ -1", &empty()).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Type); +} + +#[test] +fn huge_exponents_are_bounded_not_hung() { + let err = eval(&format!("2 ^ {}", MAX_EXPONENT + 1), &empty()).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Unsupported); + assert!(err.message.contains("exponent")); + + let err = eval("2 ^ 1000000", &empty()).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Unsupported); + + // Each factor is under the exponent bound, but the product size is not. + let err = eval("(2 ^ 10000) ^ 10000", &empty()).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Unsupported); + + // At the documented exponent bound the result is still computed exactly. + let Value::Int(bounded) = eval("2 ^ 10000", &empty()).unwrap() else { + panic!("expected an Int"); + }; + assert_eq!(bounded.bits(), 10001); +} + +#[test] +fn substitute_replaces_bindings_deterministically() { + let formula = parse("A = \\pi r^2").unwrap(); + let bindings = bindings(&[("r", Value::int(2))]); + let substituted = substitute(&formula, &bindings).unwrap(); + + // The rendering is canonical, re-parseable and deterministic. + assert_eq!(substituted.source, "A = \\pi * 2 ^ 2"); + assert_eq!(substituted.render(), substituted.source); + assert_eq!(parse(&substituted.source).unwrap().kind, substituted.kind); + + let direct = evaluate(&formula, &bindings, Some("A")).unwrap(); + let via_substitution = evaluate(&substituted, &empty(), Some("A")).unwrap(); + assert_eq!(direct, via_substitution); + + let second = substitute(&formula, &bindings).unwrap(); + assert_eq!(substituted.source, second.source); +} + +#[test] +fn substitute_leaves_unbound_variables_symbolic() { + let formula = parse("x + y * 2").unwrap(); + let substituted = substitute(&formula, &bindings(&[("x", Value::int(3))])).unwrap(); + assert_eq!(substituted.source, "3 + y * 2"); + assert!(substituted.variables().contains("y")); + assert!(!substituted.variables().contains("x")); + + let value = evaluate(&substituted, &bindings(&[("y", Value::int(4))]), None).unwrap(); + assert_int(&value, 11); +} + +#[test] +fn substitute_rejects_unsupported_binding_types() { + let formula = parse("x + 1").unwrap(); + let err = substitute(&formula, &bindings(&[("x", Value::text("two"))])).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Type); +} + +#[test] +fn scientific_notation_and_adjacent_numbers_are_rejected() { + assert_eq!(parse("1e3").unwrap_err().kind, MathErrorKind::Parse); + assert_eq!(parse("1E3").unwrap_err().kind, MathErrorKind::Parse); + assert_eq!(parse("1e-3").unwrap_err().kind, MathErrorKind::Parse); + assert_eq!(parse("1 2").unwrap_err().kind, MathErrorKind::Parse); +} + +#[test] +fn error_display_includes_kind_and_position() { + let err = parse("\\frac{1}{2").unwrap_err(); + let rendered = err.to_string(); + assert!(rendered.starts_with("parse at byte "), "{rendered}"); + assert!(rendered.contains("expected `}`"), "{rendered}"); +} + +#[test] +fn hostile_inputs_never_panic() { + // A small corpus of adversarial inputs: all must produce a structured error + // (or a value), never a panic or an unbounded computation. + let sources = [ + "\\", + "\\\\", + "\\\\\\\\", + "\\frac", + "\\frac{}{}", + "\\sqrt{}", + "{}", + "((((", + "))))", + "^^^^", + "----------------x", + "1 + + + +", + "1 // 2", + "\\left(1", + "\\right)", + "\\left[1\\right]", + "1..2", + "..", + "∞", + "1 × 2", + "1 · 2", + "2 ^ 2 ^ 2 ^ 2", + "\\pi 2 3", + "x = ", + "= x", + "x = = y", + "\\frac{1}{2} \\frac{3}{4}", + ]; + for source in sources { + match parse(source) { + Ok(formula) => { + // If it parses, evaluation must be structured as well. + let _ = evaluate(&formula, &empty(), None); + } + Err(err) => { + assert!( + !err.message.is_empty(), + "structured error must have a message for {source:?}" + ); + } + } + } +} + +#[test] +fn dot_and_times_are_multiplication_operators() { + assert_int(&eval("2 \\cdot 3", &empty()).unwrap(), 6); + assert_int(&eval("2 \\times 3", &empty()).unwrap(), 6); + assert_int(&eval("2 \\cdot 3 \\times 4", &empty()).unwrap(), 24); +} + +#[test] +fn solve_target_on_the_left_of_a_product() { + let bindings = bindings(&[("F", Value::int(20)), ("a", Value::int(5))]); + assert_int(&solve("m a = F", &bindings, "m").unwrap(), 4); + assert_int(&solve("(m + 1) a = F", &bindings, "m").unwrap(), 3); +} + +#[test] +fn substitution_with_float_and_negative_bindings_reparses() { + // A Float binding is substituted as its exact numeric value, and the + // canonical rendering must evaluate to the same value as the direct form. + let formula = parse("x * 2").unwrap(); + let x_is_float = bindings(&[("x", Value::Float(2.5))]); + let substituted = substitute(&formula, &x_is_float).unwrap(); + let direct = evaluate(&formula, &x_is_float, None).unwrap(); + let re_evaluated = evaluate(&parse(&substituted.source).unwrap(), &empty(), None).unwrap(); + assert_eq!(direct, re_evaluated); + assert_int(&direct, 5); + + // Negative substituted literals keep a parseable rendering. + let formula = parse("x + 1").unwrap(); + let x_is_negative = bindings(&[("x", Value::int(-3))]); + let substituted = substitute(&formula, &x_is_negative).unwrap(); + let value = evaluate(&parse(&substituted.source).unwrap(), &empty(), None).unwrap(); + assert_int(&value, -2); +} + +#[test] +fn large_exact_results_are_returned_as_integers() { + let Value::Int(value) = eval("2 ^ 10000", &empty()).unwrap() else { + panic!("expected an Int"); + }; + assert_eq!(value.bits(), 10001); + // A non-perfect square of the same order remains representable as Float. + assert!(matches!( + eval("\\sqrt{2}", &empty()).unwrap(), + Value::Float(_) + )); +} + +#[test] +fn long_operator_chains_within_the_node_budget_still_evaluate() { + // Each `+`/`*` needs two leaf nodes plus one operator node, so 200 + // operators stay inside the documented 512-node budget. + let source = format!("{}1", "1 + ".repeat(200)); + assert_int(&eval(&source, &empty()).unwrap(), 201); + + let source = format!("{}1", "2 * ".repeat(200)); + assert_eq!( + eval(&source, &empty()).unwrap(), + Value::Int(BigInt::from(2).pow(200)) + ); +} + +#[test] +fn oversized_formulas_are_rejected_with_a_structured_error() { + // Well over the documented node budget, but not deep enough to be caught by + // the nesting guard: this must be a parse error, not a stack overflow. + let source = format!("{}1", "1 + ".repeat(200_000)); + let err = parse(&source).unwrap_err(); + assert_eq!(err.kind, MathErrorKind::Parse); +}