diff --git a/.frontal-code/settings.json b/.frontal-code/settings.json index e36dc6ad..9c657d5d 100644 --- a/.frontal-code/settings.json +++ b/.frontal-code/settings.json @@ -284,6 +284,10 @@ "audit_logging": true, "sandbox_mode": false }, + "incremental": { + "_comment": "Incremental Compute Engine integration (see tools/incremental). When enabled, task status transitions are observed and the reconcile loop is gated by `affected` queries. Absent or false = disabled.", + "enabled": false + }, "tools": { "bash": { "enabled": true, @@ -362,6 +366,13 @@ "make_target": "generators", "description": "Scaffold crates from templates" }, + "incremental": { + "kind": "rust", + "cargo_pkg": "tools-incremental", + "bazel_label": "//tools/incremental:incremental", + "make_target": "incremental", + "description": "Incremental Compute Engine: observe, baseline, affected" + }, "remote": { "kind": "rust", "cargo_pkg": "tools-remote", diff --git a/.gitignore b/.gitignore index 2fa2822d..5826b1ad 100644 --- a/.gitignore +++ b/.gitignore @@ -32,6 +32,9 @@ Thumbs.db extensions/slack-agent/.bun-cache/ extensions/slack-agent/node_modules/ +# Incremental engine store +.incremental/ + # Bazel (Bzlmod) .bazelrc.project coverage/ diff --git a/BUILD b/BUILD index bc715f19..aed5fcc8 100644 --- a/BUILD +++ b/BUILD @@ -30,6 +30,7 @@ filegroup( "//:.cargo/config.toml", "//:rust-toolchain.toml", "//crates:all_crates", + "//third_party/incremental:rust_src", "//crates/code-plugins:bundled_plugins", "//examples:srcs", "//sdks/rust:rust_sdk_srcs", @@ -70,6 +71,7 @@ test_suite( "//crates/code-embeddings:test", "//crates/code-events:test", "//crates/code-harness:test", + "//crates/code-incremental:test", "//crates/code-integrations:test", "//crates/code-memory:test", "//crates/code-orchestrator:test", @@ -101,6 +103,7 @@ test_suite( "//crates/code-embeddings:lint", "//crates/code-events:lint", "//crates/code-harness:lint", + "//crates/code-incremental:lint", "//crates/code-integrations:lint", "//crates/code-memory:lint", "//crates/code-orchestrator:lint", @@ -132,6 +135,7 @@ test_suite( "//crates/code-embeddings:fmt", "//crates/code-events:fmt", "//crates/code-harness:fmt", + "//crates/code-incremental:fmt", "//crates/code-integrations:fmt", "//crates/code-memory:fmt", "//crates/code-orchestrator:fmt", diff --git a/Cargo.lock b/Cargo.lock index 4ea075c3..9fcada89 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -553,6 +553,16 @@ dependencies = [ "code-tools", ] +[[package]] +name = "code-incremental" +version = "0.3.0" +dependencies = [ + "incremental", + "serde", + "serde_json", + "thiserror 1.0.69", +] + [[package]] name = "code-integrations" version = "0.3.0" @@ -629,6 +639,7 @@ name = "code-runtime" version = "0.3.0" dependencies = [ "code-core", + "code-incremental", "code-integrations", "code-plugins", "code-sandbox", @@ -658,6 +669,7 @@ version = "0.3.0" dependencies = [ "axum", "code-events", + "code-incremental", "code-integrations", "code-orchestrator", "code-repo", @@ -1646,6 +1658,13 @@ dependencies = [ "icu_properties", ] +[[package]] +name = "incremental" +version = "0.1.0" +dependencies = [ + "serde_json", +] + [[package]] name = "indexmap" version = "2.14.2" @@ -2664,6 +2683,8 @@ version = "1.0.154" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" dependencies = [ + "foldhash", + "indexmap", "itoa", "memchr", "serde", @@ -3256,6 +3277,17 @@ dependencies = [ "serde_json", ] +[[package]] +name = "tools-incremental" +version = "0.3.0" +dependencies = [ + "anyhow", + "clap", + "code-incremental", + "serde", + "serde_json", +] + [[package]] name = "tools-remote" version = "0.3.0" diff --git a/Cargo.toml b/Cargo.toml index 1815c092..cd24e2a6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ [workspace] -members = ["cli", "crates/*", "sdks/rust", "tools/*", "tests/*"] +members = ["cli", "crates/*", "sdks/rust", "tools/*", "tests/*", "third_party/incremental/rust"] exclude = ["tools/fuzz/fuzz_targets/*"] resolver = "2" diff --git a/crates/BUILD.bazel b/crates/BUILD.bazel index abc098b2..9e4f40c5 100644 --- a/crates/BUILD.bazel +++ b/crates/BUILD.bazel @@ -11,6 +11,7 @@ filegroup( "//crates/code-embeddings:srcs", "//crates/code-events:srcs", "//crates/code-harness:srcs", + "//crates/code-incremental:srcs", "//crates/code-integrations:srcs", "//crates/code-memory:srcs", "//crates/code-orchestrator:srcs", diff --git a/crates/code-incremental/BUILD.bazel b/crates/code-incremental/BUILD.bazel new file mode 100644 index 00000000..2363a7e9 --- /dev/null +++ b/crates/code-incremental/BUILD.bazel @@ -0,0 +1,52 @@ +package(default_visibility = ["//visibility:public"]) + +filegroup( + name = "srcs", + srcs = glob( + ["**/*.rs"], + exclude = ["**/target/**"], + ) + ["Cargo.toml"], +) + +sh_test( + name = "test", + srcs = ["//tools:crate.sh"], + data = ["//:cargo_workspace"], + args = [ + "code-incremental", + "test", + ], + tags = [ + "rust", + "test", + ], +) + +sh_test( + name = "fmt", + size = "small", + srcs = ["//tools:crate.sh"], + data = ["//:cargo_workspace"], + args = [ + "code-incremental", + "fmt-check", + ], + tags = [ + "fmt", + "rust", + ], +) + +sh_test( + name = "lint", + srcs = ["//tools:crate.sh"], + data = ["//:cargo_workspace"], + args = [ + "code-incremental", + "clippy", + ], + tags = [ + "lint", + "rust", + ], +) diff --git a/crates/code-incremental/Cargo.toml b/crates/code-incremental/Cargo.toml new file mode 100644 index 00000000..43786fcd --- /dev/null +++ b/crates/code-incremental/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "code-incremental" +version.workspace = true +edition.workspace = true +license.workspace = true +publish = false + +[dependencies] +incremental = { path = "../../third_party/incremental/rust" } +serde = { version = "1", features = ["derive"] } +serde_json.workspace = true +thiserror = "1" + +[lints] +workspace = true diff --git a/crates/code-incremental/NOTICE.md b/crates/code-incremental/NOTICE.md new file mode 100644 index 00000000..010c8924 --- /dev/null +++ b/crates/code-incremental/NOTICE.md @@ -0,0 +1,10 @@ +// code-incremental +// +// This crate wraps the vendored Incremental Rust binding +// (third_party/incremental/rust) and provides the affected-plan and +// observation API used by the CLI runtime, code-server control plane, +// and the Bazel/dev pipeline. +// +// Vendored from: frontal-labs/incremental +// Pinned at: see third_party/manifests/incremental.json +// License: Apache-2.0 diff --git a/crates/code-incremental/src/context.rs b/crates/code-incremental/src/context.rs new file mode 100644 index 00000000..9daeb12b --- /dev/null +++ b/crates/code-incremental/src/context.rs @@ -0,0 +1,176 @@ +//! Context builder for the Incremental protocol. +//! +//! Every observation and every `affected` query carries a `context` object — +//! the set of global facts that change what a task's result means. The context +//! must be identical between observations and queries, or the engine falls back +//! to running everything (policy P2: `context_changed`). + +use serde_json::{json, Value}; +use std::path::Path; + +/// Build the context object for this repo. +/// +/// # Arguments +/// +/// * `repo_root` - The repository root directory. +/// * `runner` - The runner identifier (e.g. `frontal-code-sdk@0.3.0` or `cargo@1.85`). +/// * `node` - The runtime node version (e.g. `1.85.0` for Rust, `22.11.0` for Node). +/// +/// The context includes: +/// - `lockfile`: digest of `Cargo.lock` (Rust) or `package-lock.json` (TS), if present. +/// - `runner`: the runner identifier. +/// - `node`: the runtime version. +/// - `fmt`: the engine's format version (1). +/// - `caps`: capability flags. We only claim capabilities the adapter really records. +#[must_use] +pub fn build_context(repo_root: &Path, runner: &str, node: &str) -> Value { + let lockfile = lockfile_digest(repo_root); + let mut ctx = json!({ + "lockfile": lockfile, + "runner": runner, + "node": node, + "fmt": 1, + }); + if lockfile.is_none() { + ctx["lockfile"] = Value::Null; + } + // Capability flags: we only claim what the adapter actually records. + ctx["caps"] = json!({ + "reads": true, + "lists": false, + "probes": false, + "writes": true, + "env": false, + "config": false, + "declared_tasks": false, + }); + ctx +} + +/// Build a minimal context for tests (no real lockfile, fixed runner/node). +#[must_use] +pub fn test_context() -> Value { + build_context(Path::new("/nonexistent"), "test-runner@1.0.0", "1.0.0") +} + +/// Compute the lockfile digest. +/// +/// Reads `Cargo.lock` or `package-lock.json` from `repo_root` and returns a +/// deterministic 32-byte digest as a hex string, or `None` if no lockfile is +/// present or the read fails. +fn lockfile_digest(repo_root: &Path) -> Option { + // Try Rust lockfile first, then Node. + for name in ["Cargo.lock", "package-lock.json"] { + let path = repo_root.join(name); + if path.is_file() { + if let Ok(content) = std::fs::read(&path) { + return Some(hex(&sha256_bytes(&content))); + } + } + } + None +} + +/// Compute a deterministic 32-byte digest of a byte slice. +/// +/// This is a small inline implementation to avoid pulling in the `sha2` crate +/// as a dependency of `code-incremental`. The lockfile digest only needs to be +/// stable and collision-resistant enough for the engine to compare it — it is +/// not cryptographically secure. Uses FNV-1a 64-bit extended to 32 bytes by +/// hashing with 4 different offset mixings. +#[must_use] +fn sha256_bytes(data: &[u8]) -> [u8; 32] { + fn fnv1a_64(data: &[u8], offset: u64) -> u64 { + let mut hash: u64 = 0xcbf2_9ce4_8422_2325u64 ^ offset; + for &byte in data { + hash ^= u64::from(byte); + hash = hash.wrapping_mul(0x1000_0000_01b3u64); + } + hash + } + + let mut out = [0u8; 32]; + for (i, &offset) in [0u64, 1, 2, 3].iter().enumerate() { + out[i * 8..(i + 1) * 8].copy_from_slice(&fnv1a_64(data, offset).to_le_bytes()); + } + out +} + +/// Encode a byte slice as a lowercase hex string. +#[must_use] +fn hex(data: &[u8]) -> String { + use std::fmt::Write; + let mut s = String::with_capacity(data.len() * 2); + for &byte in data { + let _ = write!(s, "{byte:02x}"); + } + s +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_context_has_required_fields() { + let ctx = test_context(); + assert!(ctx.get("lockfile").is_some()); + assert!(ctx.get("runner").is_some()); + assert!(ctx.get("node").is_some()); + assert_eq!(ctx["fmt"], 1); + let caps = &ctx["caps"]; + assert!(caps["reads"].is_boolean()); + assert!(caps["writes"].is_boolean()); + } + + #[test] + fn build_context_in_empty_dir() { + let dir = std::env::temp_dir().join(format!( + "code-inc-ctx-empty-{}-{}", + std::process::id(), + nanos() + )); + std::fs::create_dir_all(&dir).unwrap(); + let ctx = build_context(&dir, "runner", "1.0"); + assert!(ctx["lockfile"].is_null(), "no lockfile in empty dir"); + assert_eq!(ctx["runner"], "runner"); + let _ = std::fs::remove_dir_all(&dir); + } + + #[test] + fn build_context_with_cargo_lock() { + let dir = std::env::temp_dir().join(format!( + "code-inc-ctx-lock-{}-{}", + std::process::id(), + nanos() + )); + std::fs::create_dir_all(&dir).unwrap(); + std::fs::write(dir.join("Cargo.lock"), "[package]\nname = \"x\"\n").unwrap(); + let ctx = build_context(&dir, "runner", "1.0"); + assert!( + ctx["lockfile"].is_string(), + "lockfile should be a hex string" + ); + let _ = std::fs::remove_dir_all(&dir); + } + + #[test] + fn fnv_hash_is_deterministic() { + let a = sha256_bytes(b"hello world"); + let b = sha256_bytes(b"hello world"); + assert_eq!(a, b); + } + + #[test] + fn fnv_hash_differs_for_different_input() { + let a = sha256_bytes(b"hello"); + let b = sha256_bytes(b"world"); + assert_ne!(a, b); + } + + fn nanos() -> u128 { + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map_or(0, |d| d.as_nanos()) + } +} diff --git a/crates/code-incremental/src/engine_binary.rs b/crates/code-incremental/src/engine_binary.rs new file mode 100644 index 00000000..755b374b --- /dev/null +++ b/crates/code-incremental/src/engine_binary.rs @@ -0,0 +1,149 @@ +//! Engine binary resolution and spawn. +//! +//! Resolves the `incremental` engine binary from (in order): +//! 1. `FRONTAL_CODE_INCREMENTAL_ENGINE` env var (explicit path). +//! 2. `INCREMENTAL_ENGINE` env var (the binding's own default). +//! 3. A path baked in at build time (relative to the workspace root). +//! 4. `incremental` on `PATH`. +//! +//! If no binary is found, the integration degrades to "always run everything" +//! (a safe fallback). It never returns a hard error for a missing binary. + +use std::env; +use std::path::{Path, PathBuf}; +use std::process::Command; + +/// Result of attempting to locate the engine binary. +#[derive(Debug, Clone)] +pub enum EngineBinary { + /// The binary was found at the given path. + Found(PathBuf), + /// No binary is available. The integration should degrade to "always run everything." + Missing, +} + +impl EngineBinary { + /// Whether a usable binary was found. + #[must_use] + pub fn is_available(&self) -> bool { + matches!(self, EngineBinary::Found(_)) + } + + /// The resolved path, if found. + #[must_use] + pub fn path(&self) -> Option<&Path> { + match self { + EngineBinary::Found(path) => Some(path), + EngineBinary::Missing => None, + } + } + + /// Resolve the engine binary from env vars and build-time paths. + #[must_use] + pub fn resolve() -> Self { + resolve() + } +} + +/// Resolve the engine binary from env vars and build-time paths. +#[must_use] +pub fn resolve() -> EngineBinary { + // 1. Explicit override. + if let Some(path) = env::var_os("FRONTAL_CODE_INCREMENTAL_ENGINE") { + let path = PathBuf::from(path); + if path.is_file() { + return EngineBinary::Found(path); + } + } + + // 2. The binding's own env var. + if let Some(path) = env::var_os("INCREMENTAL_ENGINE") { + let path = PathBuf::from(path); + if path.is_file() { + return EngineBinary::Found(path); + } + } + + // 3. Build-time baked path (workspace root). + if let Some(baked) = baked_path() { + if baked.is_file() { + return EngineBinary::Found(baked); + } + } + + // 4. PATH lookup. + if which_binary("incremental") { + return EngineBinary::Found(PathBuf::from("incremental")); + } + + EngineBinary::Missing +} + +/// Build-time-baked path to the engine binary, computed relative to the +/// workspace root (which is two directories above `crates/code-incremental`). +fn baked_path() -> Option { + let workspace_root = Path::new(env!("CARGO_MANIFEST_DIR")) + .parent() // code-incremental + .and_then(|p| p.parent()) // crates + .and_then(|p| p.parent()); // workspace root + + let triple = target_triple(); + workspace_root.map(|root| { + root.join(format!( + "third_party/incremental/engine-binaries/{triple}/incremental" + )) + }) +} + +/// Check whether a binary is on the PATH. +fn which_binary(name: &str) -> bool { + Command::new("which") + .arg(name) + .output() + .is_ok_and(|o| o.status.success()) +} + +/// The target triple for this platform (e.g. `darwin-arm64`, `linux-x86_64`). +#[must_use] +pub fn target_triple() -> String { + let os = env::consts::OS; + let arch = env::consts::ARCH; + // Normalize arch names to match the directory layout. + let arch = match arch { + "aarch64" => "arm64", + "x86_64" => "x86_64", + "x86" => "x86", + other => other, + }; + format!("{os}-{arch}") +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn target_triple_is_well_formed() { + let triple = target_triple(); + assert!( + triple.contains('-'), + "triple should contain a dash: {triple}" + ); + } + + #[test] + fn missing_engine_reports_unavailable() { + // We can't guarantee a missing engine in all environments, so just + // check the API shape. + let missing = EngineBinary::Missing; + assert!(!missing.is_available()); + assert!(missing.path().is_none()); + } + + #[test] + fn found_engine_reports_available() { + let found = EngineBinary::Found(PathBuf::from("/bin/true")); + assert!(found.is_available()); + assert!(found.path().is_some()); + } +} diff --git a/crates/code-incremental/src/lib.rs b/crates/code-incremental/src/lib.rs new file mode 100644 index 00000000..b1d7b7ca --- /dev/null +++ b/crates/code-incremental/src/lib.rs @@ -0,0 +1,690 @@ +//! `code-incremental` — the Incremental Compute Engine integration for frontal-code. +//! +//! This crate wraps the vendored Incremental Rust binding and provides the +//! affected-plan and observation API used by the CLI runtime, code-server +//! control plane, and the Bazel/dev pipeline. +//! +//! # Design +//! +//! - A [`Store`] manages a single engine process and its store directory. +//! - A task may be skipped **only** with a certificate: an observation at the +//! current baseline whose inputs are all unchanged. Unknown or unverifiable +//! input makes the task invalid, or makes the whole answer a fallback. +//! No silent skips. +//! - A `fallback` result means "run everything" (the safe default). It is +//! never a hard error. +//! - The store is per-worktree by default (`/.incremental/`). +//! `tg.log` is the source of truth (append-only JSONL); indexes are +//! rebuildable caches. + +pub mod context; +pub mod engine_binary; + +use std::path::{Path, PathBuf}; +use std::time::Duration; + +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +pub use context::build_context; +pub use engine_binary::{target_triple, EngineBinary}; + +// --------------------------------------------------------------------------- +// Errors +// --------------------------------------------------------------------------- + +/// Errors returned by [`Store`] methods. +#[derive(Debug, thiserror::Error)] +pub enum Error { + /// The engine binary could not be found. + #[error("incremental engine binary not found; use FRONTAL_CODE_INCREMENTAL_ENGINE or INCREMENTAL_ENGINE")] + EngineNotFound, + + /// The engine process failed to start. + #[error("engine failed to start: {0}")] + EngineStartup(String), + + /// A protocol error from the engine. + #[error("{code}: {message}")] + Protocol { code: String, message: String }, + + /// A timeout waiting for the engine to respond. + #[error("engine request timed out: {0}")] + Timeout(String), + + /// A filesystem error. + #[error("io error: {0}")] + Io(#[from] std::io::Error), + + /// A JSON serialization error. + #[error("json error: {0}")] + Json(#[from] serde_json::Error), +} + +pub type Result = std::result::Result; + +// --------------------------------------------------------------------------- +// Store +// --------------------------------------------------------------------------- + +/// A handle to one Incremental engine process and its store directory. +/// +/// The store is per-worktree by default (`/.incremental/`). Override +/// with `FRONTAL_CODE_INCREMENTAL_STORE` (passed through to +/// `INCREMENTAL_STORE`) or via [`Store::open`]. +/// +/// # Example +/// +/// ```no_run +/// use code_incremental::Store; +/// use std::path::Path; +/// +/// let mut store = Store::open(Path::new(".")).unwrap(); +/// let ctx = code_incremental::build_context(Path::new("."), "cargo@1.85", "1.85.0"); +/// let plan = store.affected( +/// &serde_json::json!({"changes": []}), +/// "abc123", +/// &ctx, +/// ).unwrap(); +/// +/// if plan.is_fallback() { +/// println!("fallback: run everything"); +/// } else { +/// for task in &plan.tasks { +/// println!("affected: {}", task.task_id); +/// } +/// } +/// ``` +pub struct Store { + client: incremental::Incremental, + path: PathBuf, + repo_root: PathBuf, +} + +impl Store { + /// Open a store rooted at `repo_root`. + /// + /// The store directory is `/.incremental/` by default. + /// The engine binary is resolved via [`EngineBinary::resolve`]. + /// + /// If no engine binary is available, returns `Err(Error::EngineNotFound)`. + /// Callers should catch this and degrade to "always run everything." + pub fn open(repo_root: &Path) -> Result { + let engine = EngineBinary::resolve(); + let binary = engine.path().ok_or(Error::EngineNotFound)?.to_path_buf(); + + let store_path = env_store_path(repo_root); + let cfg = incremental::Config { + engine: vec![binary.display().to_string()], + store: store_path.clone(), + root: repo_root.to_path_buf(), + timeout: Duration::from_secs(30), + restart: true, + }; + + let client = incremental::Incremental::connect(cfg) + .map_err(|e| Error::EngineStartup(format!("{}: {}", e.code, e.message)))?; + + Ok(Store { + client, + path: store_path, + repo_root: repo_root.to_path_buf(), + }) + } + + /// Ensure the store directory is initialized. + /// + /// Runs the engine's `init` command, which creates the store directory, + /// any missing parents, and an empty log with a header. Safe to call + /// multiple times (idempotent — the engine skips when the log exists). + /// + /// Call this before the first [`observe`](Self::observe) or + /// [`affected`](Self::affected) on a fresh worktree; a store that was + /// never initialized returns `store_missing` from the engine. + pub fn ensure_initialized(&self) { + let engine = EngineBinary::resolve(); + let Some(binary) = engine.path() else { + return; + }; + let _ = std::process::Command::new(binary) + .args([ + "init", + "--store", + &self.path.to_string_lossy(), + "--root", + &self.repo_root.to_string_lossy(), + ]) + .status(); + } + + /// The store directory path. + #[must_use] + pub fn store_path(&self) -> &Path { + &self.path + } + + /// The repo root this store is rooted at. + #[must_use] + pub fn repo_root(&self) -> &Path { + &self.repo_root + } + + // -- observation ------------------------------------------------------- + + /// Record a single observation. + /// + /// The observation JSON follows the protocol v1 schema: + /// ```json + /// { + /// "task": "src/foo.rs#test", + /// "inputs": [{"type": "file", "path": "src/foo.rs"}], + /// "outputs": [], + /// "outcome": "pass", + /// "duration_ms": 1234, + /// "dirty": false, + /// "context": { ... } + /// } + /// ``` + pub fn observe(&mut self, observation: &Value) -> Result { + self.client.observe(observation).map_err(protocol_err) + } + + /// Record multiple observations atomically. + /// + /// Either all observations are stored or none. Returns `{accepted: n}`. + pub fn observe_many(&mut self, observations: &[Value]) -> Result { + self.client.observe_many(observations).map_err(protocol_err) + } + + // -- baseline ---------------------------------------------------------- + + /// Query the current baseline. + /// + /// Returns `{baseline: | null}`. + pub fn baseline(&mut self) -> Result { + self.client.baseline().map_err(protocol_err) + } + + /// Advance the baseline to `to`. + /// + /// Fails with `baseline_conflict` unless `expected` equals the current + /// baseline (`null` before the first advance). It never overwrites. + pub fn advance(&mut self, to: &str, expected: Option<&str>) -> Result { + self.client.advance(to, expected).map_err(protocol_err) + } + + // -- affected ---------------------------------------------------------- + + /// Compute the affected plan for a changeset. + /// + /// `changes` is the changeset JSON: `{"changes": [{"path": ..., "status": ...}]}`. + /// `baseline` is the baseline to compare against (must equal the store's + /// current baseline for the engine to certify any skips — policy P0). + /// `context` is the context object; it **must** be present and must match + /// the observation contexts for the engine to certify any skips + /// (policy P0b). Use [`build_context`](crate::build_context) to build it. + /// + /// A `fallback` result means "run everything" (the safe default). + /// It is never a hard error — the plan is returned with `is_fallback == true`. + pub fn affected(&mut self, changes: &Value, baseline: &str, context: &Value) -> Result { + let mut opts = incremental::Affected::new(baseline); + opts.context = Some(context.clone()); + let raw = self.client.affected(changes, &opts).map_err(protocol_err)?; + Ok(Plan::from_json(&raw)) + } + + // -- explain / forget / stats ------------------------------------------ + + /// Explain why a task is or is not invalid. + pub fn explain(&mut self, task: &str) -> Result { + self.client.explain(task).map_err(protocol_err) + } + + /// Drop a task's observations. + pub fn forget(&mut self, task: &str) -> Result { + self.client.forget(task).map_err(protocol_err) + } + + /// Store statistics (tasks, observations, baseline). + pub fn stats(&mut self) -> Result { + self.client.stats().map_err(protocol_err) + } + + // -- hello / ping / compact -------------------------------------------- + + /// The `hello` handshake result: `{protocol, engine, capabilities, store}`. + pub fn hello(&mut self) -> Result { + self.client.hello().map_err(protocol_err) + } + + /// Ping the engine. + pub fn ping(&mut self) -> Result { + self.client.ping().map_err(protocol_err) + } + + /// Compact the store (no-op in the current build). + pub fn compact(&mut self) -> Result { + self.client.compact().map_err(protocol_err) + } +} + +// --------------------------------------------------------------------------- +// Plan +// --------------------------------------------------------------------------- + +/// The result of an `affected` query. +/// +/// A plan is never returned partially (protocol v1 §9.6). If the engine +/// cannot produce a complete plan, it returns a fallback instead. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Plan { + /// Tasks that must be re-run. + pub tasks: Vec, + /// Tasks that were skipped (have a valid certificate). + pub skipped: usize, + /// Tasks the engine knows about but has no observation for. + pub unobserved: Vec, + /// Tasks that were explicitly ignored. + pub ignored: Vec, + /// Tasks that have been deleted. + pub deleted_tasks: Vec, + /// Non-null when the engine ran everything instead of answering per task. + /// `fallback.reason` says why (e.g. `no_baseline`, `context_changed`, `dirty_observation`). + pub fallback: Option, + /// Policy confidence label (`medium`, `high`, `low`). Not a probability. + pub confidence: String, + /// The graph version at query time (e.g. `"g_a71d37aa"`). + pub graph_version: String, +} + +/// A single task in an affected plan. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Task { + /// The task ID (repo-relative path + task kind). + pub task_id: String, + /// Why the task is selected (e.g. `reads:src/math.ts`, `dirty_observation`, `fallback`). + pub reasons: Vec, +} + +/// The fallback annotation on a plan. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Fallback { + /// Why the fallback was triggered. + pub reason: String, +} + +impl Plan { + /// Whether the plan is a fallback (meaning "run everything"). + #[must_use] + pub fn is_fallback(&self) -> bool { + self.fallback.is_some() + } + + /// The number of tasks that must be re-run. + #[must_use] + pub fn task_count(&self) -> usize { + self.tasks.len() + } + + /// Deserialize a plan from the engine's raw JSON response. + #[must_use] + pub fn from_json(raw: &Value) -> Self { + let tasks = raw + .get("tasks") + .and_then(Value::as_array) + .map(|arr| { + arr.iter() + .filter_map(|t| { + Some(Task { + task_id: t["id"].as_str()?.to_string(), + reasons: t + .get("reasons") + .and_then(Value::as_array) + .map(|r| { + r.iter() + .filter_map(|v| v.as_str().map(String::from)) + .collect() + }) + .unwrap_or_default(), + }) + }) + .collect() + }) + .unwrap_or_default(); + + let skipped = raw + .get("skipped") + .and_then(Value::as_u64) + .and_then(|v| usize::try_from(v).ok()) + .unwrap_or(0); + let unobserved = string_array(raw, "unobserved"); + let ignored = string_array(raw, "ignored"); + let deleted_tasks = string_array(raw, "deleted_tasks"); + + let fallback = raw.get("fallback").and_then(|f| { + if f.is_null() { + None + } else { + Some(Fallback { + reason: f + .get("reason") + .and_then(Value::as_str) + .unwrap_or("unknown") + .to_string(), + }) + } + }); + + let confidence = raw + .get("confidence") + .and_then(Value::as_str) + .unwrap_or("unknown") + .to_string(); + + let graph_version = raw + .get("graph_version") + .and_then(Value::as_str) + .unwrap_or("unknown") + .to_string(); + + Plan { + tasks, + skipped, + unobserved, + ignored, + deleted_tasks, + fallback, + confidence, + graph_version, + } + } + + /// A plan with no tasks and no fallback (empty changeset). + #[must_use] + pub fn empty() -> Self { + Plan { + tasks: vec![], + skipped: 0, + unobserved: vec![], + ignored: vec![], + deleted_tasks: vec![], + fallback: None, + confidence: "high".to_string(), + graph_version: "unknown".to_string(), + } + } + + /// A fallback plan (run everything). + #[must_use] + pub fn fallback(reason: impl Into) -> Self { + Plan { + tasks: vec![], + skipped: 0, + unobserved: vec![], + ignored: vec![], + deleted_tasks: vec![], + fallback: Some(Fallback { + reason: reason.into(), + }), + confidence: "low".to_string(), + graph_version: "unknown".to_string(), + } + } +} + +fn string_array(raw: &Value, key: &str) -> Vec { + raw.get(key) + .and_then(Value::as_array) + .map(|arr| { + arr.iter() + .filter_map(|v| v.as_str().map(String::from)) + .collect() + }) + .unwrap_or_default() +} + +fn protocol_err(e: incremental::Error) -> Error { + match e.code.as_str() { + "timeout" => Error::Timeout(e.message), + "engine_exited" => Error::EngineStartup(e.message), + _ => Error::Protocol { + code: e.code, + message: e.message, + }, + } +} + +/// Resolve the store directory from the environment, falling back to +/// `/.incremental/`. +fn env_store_path(repo_root: &Path) -> PathBuf { + std::env::var_os("FRONTAL_CODE_INCREMENTAL_STORE") + .or_else(|| std::env::var_os("INCREMENTAL_STORE")) + .map_or_else(|| repo_root.join(".incremental"), PathBuf::from) +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + #[test] + fn plan_from_json_full() { + let raw = json!({ + "tasks": [ + {"id": "src/foo.rs#test", "reasons": ["reads:src/bar.rs"]}, + {"id": "src/baz.rs#test", "reasons": ["dirty_observation"]} + ], + "skipped": 3, + "unobserved": ["src/new.rs#test"], + "ignored": [], + "deleted_tasks": ["src/old.rs#test"], + "fallback": null, + "confidence": "medium", + "graph_version": "g_a71d37aa" + }); + let plan = Plan::from_json(&raw); + assert_eq!(plan.task_count(), 2); + assert!(!plan.is_fallback()); + assert_eq!(plan.tasks[0].task_id, "src/foo.rs#test"); + assert_eq!(plan.tasks[0].reasons, vec!["reads:src/bar.rs"]); + assert_eq!(plan.tasks[1].task_id, "src/baz.rs#test"); + assert_eq!(plan.skipped, 3); + assert_eq!(plan.unobserved, vec!["src/new.rs#test"]); + assert_eq!(plan.ignored, Vec::::new()); + assert_eq!(plan.deleted_tasks, vec!["src/old.rs#test"]); + assert_eq!(plan.confidence, "medium"); + assert_eq!(plan.graph_version, "g_a71d37aa"); + } + + #[test] + fn plan_from_json_fallback() { + let raw = json!({ + "tasks": [], + "skipped": 0, + "unobserved": [], + "ignored": [], + "deleted_tasks": [], + "fallback": {"reason": "no_baseline"}, + "confidence": "low", + "graph_version": "g_00000000" + }); + let plan = Plan::from_json(&raw); + assert!(plan.is_fallback()); + assert_eq!(plan.task_count(), 0); + assert_eq!(plan.fallback.as_ref().unwrap().reason, "no_baseline"); + } + + #[test] + fn plan_empty() { + let plan = Plan::empty(); + assert!(!plan.is_fallback()); + assert_eq!(plan.task_count(), 0); + assert_eq!(plan.confidence, "high"); + } + + #[test] + fn plan_fallback_convenience() { + let plan = Plan::fallback("context_changed"); + assert!(plan.is_fallback()); + assert_eq!(plan.fallback.as_ref().unwrap().reason, "context_changed"); + assert_eq!(plan.confidence, "low"); + } + + #[test] + fn plan_missing_fields_defaults() { + let raw = json!({}); + let plan = Plan::from_json(&raw); + assert_eq!(plan.task_count(), 0); + assert!(!plan.is_fallback()); + assert_eq!(plan.confidence, "unknown"); + assert_eq!(plan.graph_version, "unknown"); + } + + #[test] + fn env_store_path_uses_repo_root() { + // Unset the env vars to test the default. + std::env::remove_var("FRONTAL_CODE_INCREMENTAL_STORE"); + std::env::remove_var("INCREMENTAL_STORE"); + let repo = Path::new("/tmp/test-repo"); + let store = env_store_path(repo); + assert_eq!(store, Path::new("/tmp/test-repo/.incremental")); + } + + #[test] + fn task_id_roundtrip() { + let task = Task { + task_id: "crates/code-runtime/src/task_registry.rs#test".to_string(), + reasons: vec!["reads:crates/code-runtime/src/task_registry.rs".to_string()], + }; + let json_val = serde_json::to_value(&task).unwrap(); + assert_eq!(json_val["task_id"], task.task_id); + assert_eq!(json_val["reasons"][0], task.reasons[0]); + } + + // -- end-to-end against the real engine -------------------------------- + // + // These tests spawn the vendored engine binary (skipped when it is not + // available for the current platform) and drive the full observe → + // advance → affected cycle through the `Store` API, not the raw + // protocol. They mirror the protocol probe that proved the engine + // certifies skips: matching baseline + context yields a certified skip, + // while any mismatch (context, baseline) falls back. + + /// A unique, engine-free temp dir for one test process run. + fn e2e_dir(name: &str) -> PathBuf { + std::env::temp_dir().join(format!( + "code-inc-e2e-{name}-{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map_or(0, |d| d.as_nanos()) + )) + } + + /// Build a fresh store on a temp repo, initialized with a baseline. + /// Skips (returns `None`) when the engine binary is unavailable. + fn fresh_e2e_store(baseline: &str) -> Option<(Store, PathBuf)> { + let engine = EngineBinary::resolve(); + let engine_path = engine.path()?; + // Skip cleanly on platforms without a prebuilt engine binary. + if !engine_path.exists() { + return None; + } + let repo = e2e_dir("repo"); + std::fs::create_dir_all(&repo).unwrap(); + let store_dir = repo.join(".incremental"); + std::process::Command::new(engine_path) + .args([ + "init", + "--store", + &store_dir.to_string_lossy(), + "--root", + &repo.to_string_lossy(), + ]) + .status() + .ok() + .filter(std::process::ExitStatus::success)?; + let mut store = Store::open(&repo).ok()?; + // First advance: null → baseline. + store.advance(baseline, None).ok()?; + Some((store, repo)) + } + + #[test] + fn e2e_certified_skip_and_fallbacks() { + let Some((mut store, repo)) = fresh_e2e_store("abc123") else { + eprintln!("skipping: engine binary unavailable"); + return; + }; + let ctx = build_context(&repo, "test-runner@1.0.0", "1.0.0"); + + // Observe a task whose only input is a file, at the store baseline. + let observation = json!({ + "task": "src/foo.rs#test", + "baseline": "abc123", + "inputs": [{"kind": "file", "path": "src/foo.rs"}], + "outputs": [], + "outcome": "pass", + "dirty": false, + "context": ctx, + }); + store.observe(&observation).unwrap(); + + // 1. Matching baseline + context, empty changeset → certified skip. + let plan = store + .affected(&json!({"changes": []}), "abc123", &ctx) + .unwrap(); + assert!( + !plan.is_fallback(), + "expected a certified plan, got fallback {:?}", + plan.fallback + ); + assert_eq!(plan.skipped, 1, "task should be skipped"); + assert_eq!(plan.task_count(), 0); + + // 2. Context mismatch → fallback (policy P2). + let mut bad_ctx = ctx.clone(); + bad_ctx["runner"] = json!("other-runner@9.9.9"); + let plan = store + .affected(&json!({"changes": []}), "abc123", &bad_ctx) + .unwrap(); + assert!(plan.is_fallback(), "context mismatch must fall back"); + assert_eq!(plan.fallback.as_ref().unwrap().reason, "context_changed"); + + // 3. Baseline mismatch → fallback (policy P0). + let plan = store + .affected(&json!({"changes": []}), "zzz999", &ctx) + .unwrap(); + assert!(plan.is_fallback(), "baseline mismatch must fall back"); + assert_eq!(plan.fallback.as_ref().unwrap().reason, "baseline_mismatch"); + + let _ = std::fs::remove_dir_all(&repo); + } + + #[test] + fn e2e_missing_store_degrades_safely() { + // A store that was never initialized returns `store_missing` from the + // engine. `affected` must surface that as an error the caller can + // degrade on — never a certified plan, never a panic. + // No engine at all: the safe default, also acceptable. + if EngineBinary::resolve().path().is_none() { + return; + } + let repo = e2e_dir("uninit"); + std::fs::create_dir_all(&repo).unwrap(); + let Some(mut store) = Store::open(&repo).ok() else { + // Engine exists but store could not be opened. + let _ = std::fs::remove_dir_all(&repo); + return; + }; + let ctx = build_context(&repo, "test-runner@1.0.0", "1.0.0"); + // The store is missing: the engine rejects the query. We assert that + // the call does not panic and either errors or returns a fallback. + let result = store.affected(&json!({"changes": []}), "abc123", &ctx); + match result { + Err(_) => {} // expected: store_missing + Ok(plan) => assert!(plan.is_fallback()), + } + let _ = std::fs::remove_dir_all(&repo); + } +} diff --git a/crates/code-runtime/Cargo.toml b/crates/code-runtime/Cargo.toml index 6acb0238..f062d15d 100644 --- a/crates/code-runtime/Cargo.toml +++ b/crates/code-runtime/Cargo.toml @@ -7,6 +7,7 @@ publish.workspace = true [dependencies] code-core = { path = "../code-core" } +code-incremental = { path = "../code-incremental" } sha2 = "0.11" glob = "0.3" getrandom = "0.4" diff --git a/crates/code-runtime/src/incremental_observer.rs b/crates/code-runtime/src/incremental_observer.rs new file mode 100644 index 00000000..e06df97e --- /dev/null +++ b/crates/code-runtime/src/incremental_observer.rs @@ -0,0 +1,188 @@ +//! Flag-gated observation bridge between the runtime task lifecycle and the +//! Incremental engine store. +//! +//! This module is the Phase-2 hook surface: +//! - **Observe**: task status transitions are recorded as protocol-v1 +//! observations so that a future `affected` query can certify skips. +//! - **Advance**: on terminal worker transitions, the store baseline is +//! advanced so subsequent queries measure against the latest completed +//! state. +//! +//! The bridge is **flag-gated** on `incremental.enabled` in +//! `.frontal-code/settings.json` and **best-effort**: every method swallows +//! errors so a missing engine binary or store directory never disrupts task +//! execution. The safe default — run everything — is preserved because +//! `affected` falls back to a full plan when the engine is unavailable. +//! +//! Task IDs follow the convention `#` (see the +//! integration plan). Callers are responsible for building a stable ID; this +//! module provides a helper for the common case. + +use std::path::Path; + +use code_incremental::{build_context, Store}; +use serde_json::{json, Value}; + +/// The runner identifier embedded in every observation context. +const RUNNER: &str = "frontal-code-runtime"; + +/// The runtime node version embedded in the context. Bump when the +/// runtime changes in a way that affects task outcomes. +const NODE: &str = "0.3.0"; + +/// Build a stable task ID for a sub-agent task. +/// +/// `rel_path` is the repo-relative path of the primary file the task +/// operates on; `kind` is the task kind (`test`, `build`, `run`, etc.). +#[must_use] +pub fn task_id(rel_path: &str, kind: &str) -> String { + format!("{rel_path}#{kind}") +} + +/// Map a terminal task status to the protocol-v1 outcome string. +#[must_use] +pub fn outcome_for(status: &str) -> &'static str { + match status { + "completed" => "pass", + "failed" => "fail", + "stopped" => "error", + _ => "none", + } +} + +/// Lazily opened store. Re-opened on every call for now; the engine process +/// is short-lived and the cost is dominated by the JSONL append, not process +/// spawn. A process-pooling optimization is a follow-up. +/// +/// Ensures the store is initialized (idempotent) so the first observation +/// on a fresh worktree does not hit `store_missing`. +fn open_store(repo_root: &Path) -> Option { + let store = Store::open(repo_root).ok()?; + store.ensure_initialized(); + Some(store) +} + +/// Record a task status transition as a protocol-v1 observation. +/// +/// # Arguments +/// +/// * `repo_root` - repository root (used to locate the store). +/// * `id` - stable task ID (`#`). +/// * `inputs` - the protocol-v1 input list (files, dirs, probes) the task +/// consumed. Pass an empty slice when unknown; the engine will treat the +/// observation as non-certifiable but not dirty. +/// * `status` - the terminal task status (`completed`, `failed`, `stopped`). +/// * `dirty` - set true if the run crashed before inputs could be verified. +pub fn observe_task(repo_root: &Path, id: &str, inputs: &[Value], status: &str, dirty: bool) { + let Some(mut store) = open_store(repo_root) else { + return; + }; + let context = build_context(repo_root, RUNNER, NODE); + // The engine requires the observation's baseline to match the store + // baseline for the observation to count as a certificate (policy P0). + let obs_baseline = store + .baseline() + .ok() + .and_then(|v| { + v.get("baseline") + .and_then(serde_json::Value::as_str) + .map(String::from) + }) + .unwrap_or_default(); + let obs_baseline = if obs_baseline.is_empty() { + "unknown".to_string() + } else { + obs_baseline + }; + let observation = json!({ + "task": id, + "baseline": obs_baseline, + "inputs": inputs, + "outputs": [], + "outcome": outcome_for(status), + "dirty": dirty, + "context": context, + }); + let _ = store.observe(&observation); +} + +/// Record a batch of observations (e.g. all task transitions for a batch). +pub fn observe_many(repo_root: &Path, observations: &[Value]) { + let Some(mut store) = open_store(repo_root) else { + return; + }; + let _ = store.observe_many(observations); +} + +/// Advance the store baseline to `to`. Called after a worker finishes a +/// session so that the next `affected` query measures against the +/// post-completion state. +pub fn advance(repo_root: &Path, to: &str, expected: Option<&str>) { + let Some(mut store) = open_store(repo_root) else { + return; + }; + let _ = store.advance(to, expected); +} + +/// Build the observation context for this repo (useful for constructing +/// `affected` queries from the runtime). +#[must_use] +pub fn context(repo_root: &Path) -> Value { + build_context(repo_root, RUNNER, NODE) +} + +/// Query the store for tasks affected by the given changeset relative to +/// `baseline`. Returns `None` if the store is unavailable or the query +/// falls back (caller should then run everything). +#[must_use] +pub fn affected(repo_root: &Path, baseline: &str, changes: &Value) -> Option> { + let mut store = open_store(repo_root)?; + // The engine requires a context object on every `affected` query to + // certify skips (policy P0b). Build it the same way observations do. + let ctx = build_context(repo_root, RUNNER, NODE); + let plan = store.affected(changes, baseline, &ctx).ok()?; + if plan.is_fallback() { + return None; + } + Some(plan.tasks.iter().map(|t| t.task_id.clone()).collect()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn task_id_is_stable() { + assert_eq!(task_id("crates/foo.rs", "test"), "crates/foo.rs#test"); + } + + #[test] + fn outcome_mapping() { + assert_eq!(outcome_for("completed"), "pass"); + assert_eq!(outcome_for("failed"), "fail"); + assert_eq!(outcome_for("stopped"), "error"); + assert_eq!(outcome_for("created"), "none"); + } + + #[test] + fn context_is_deterministic() { + let root = Path::new(env!("CARGO_MANIFEST_DIR")); + let a = context(root); + let b = context(root); + assert_eq!(a, b); + } + + #[test] + fn observe_task_does_not_panic_without_store() { + // No store exists at this path; observe_task must swallow the error. + let root = Path::new("/nonexistent-repo-root-for-test"); + observe_task(root, "task_1", &[], "completed", false); + } + + #[test] + fn affected_returns_none_without_store() { + let root = Path::new("/nonexistent-repo-root-for-test"); + let changes = json!({"changes": []}); + assert!(affected(root, "HEAD", &changes).is_none()); + } +} diff --git a/crates/code-runtime/src/lib.rs b/crates/code-runtime/src/lib.rs index 4cc171cb..3a55b99a 100644 --- a/crates/code-runtime/src/lib.rs +++ b/crates/code-runtime/src/lib.rs @@ -15,6 +15,7 @@ pub mod core_config; mod file_ops; pub mod green_contract; mod hooks; +pub mod incremental_observer; mod json; mod lane_events; pub mod lsp_client; @@ -65,6 +66,35 @@ pub use code_integrations::mcp::stdio::{ pub use code_integrations::mcp::tool_bridge::{ McpConnectionStatus, McpServerState, McpToolRegistry, }; +/// Returns `true` when the `incremental.enabled` setting is `true` in the +/// merged runtime settings. Defaults to `false` when the setting is absent. +/// +/// This is the flag gate for all Incremental engine interactions: when +/// disabled, no observations are recorded and no baseline advances occur. +#[must_use] +pub fn incremental_enabled() -> bool { + // The config module is loaded lazily; we check the project-local + // settings file directly to avoid a full config load on every call. + let path = std::env::current_dir() + .ok() + .map(|cwd| cwd.join(".frontal-code").join("settings.json")) + .filter(|p| p.exists()); + let Some(path) = path else { + return false; + }; + let Ok(raw) = std::fs::read_to_string(path) else { + return false; + }; + let Ok(value) = serde_json::from_str::(&raw) else { + return false; + }; + value + .get("incremental") + .and_then(|v| v.get("enabled")) + .and_then(serde_json::Value::as_bool) + .unwrap_or(false) +} + pub use code_integrations::mcp::tools::{ execute_mcp_tool, mcp_tool_specs, ToolSpec as McpToolSpec, }; diff --git a/crates/code-runtime/src/task_registry.rs b/crates/code-runtime/src/task_registry.rs index adedcc10..38d876ef 100644 --- a/crates/code-runtime/src/task_registry.rs +++ b/crates/code-runtime/src/task_registry.rs @@ -31,6 +31,13 @@ impl std::fmt::Display for TaskStatus { } } +impl TaskStatus { + #[must_use] + pub fn is_terminal(self) -> bool { + matches!(self, Self::Completed | Self::Failed | Self::Stopped) + } +} + #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Task { pub task_id: String, @@ -55,6 +62,7 @@ pub struct TaskMessage { #[derive(Debug, Clone, Default)] pub struct TaskRegistry { inner: Arc>, + repo_root: Option, } #[derive(Debug, Clone, Serialize, Deserialize)] @@ -82,6 +90,18 @@ impl TaskRegistry { Self::default() } + /// Return a registry rooted at `repo_root`, so that terminal task + /// transitions are recorded as Incremental observations (flag-gated on + /// `incremental.enabled` and best-effort: a missing engine binary is a + /// no-op). + #[must_use] + pub fn with_repo_root(repo_root: impl Into) -> Self { + Self { + repo_root: Some(repo_root.into()), + ..Self::default() + } + } + pub fn create(&self, prompt: &str, description: Option<&str>) -> Task { self.create_task(prompt.to_owned(), description.map(str::to_owned), None) } @@ -203,8 +223,25 @@ impl TaskRegistry { .tasks .get_mut(task_id) .ok_or_else(|| format!("task not found: {task_id}"))?; + let was_terminal = task.status.is_terminal(); task.status = status; task.updated_at = now_secs(); + let terminal = status.is_terminal(); + drop(inner); + // Record the transition as an Incremental observation on the first + // terminal status. Best-effort: a missing engine or disabled flag is + // a no-op (the safe default is to run everything). + if terminal && !was_terminal && crate::incremental_enabled() { + if let Some(repo_root) = &self.repo_root { + crate::incremental_observer::observe_task( + repo_root, + task_id, + &[], + &status.to_string(), + false, + ); + } + } Ok(()) } @@ -235,6 +272,23 @@ impl TaskRegistry { #[must_use] pub fn from_snapshot(snapshot: TaskRegistrySnapshot) -> Self { + Self::from_snapshot_inner(snapshot, None) + } + + /// Like [`from_snapshot`], but sets a repo root so terminal task + /// transitions are recorded as Incremental observations. + #[must_use] + pub fn from_snapshot_with_repo_root( + snapshot: TaskRegistrySnapshot, + repo_root: impl Into, + ) -> Self { + Self::from_snapshot_inner(snapshot, Some(repo_root.into())) + } + + fn from_snapshot_inner( + snapshot: TaskRegistrySnapshot, + repo_root: Option, + ) -> Self { let tasks = snapshot .tasks .into_iter() @@ -245,6 +299,7 @@ impl TaskRegistry { tasks, counter: snapshot.counter, })), + repo_root, } } diff --git a/crates/code-runtime/src/worker_boot.rs b/crates/code-runtime/src/worker_boot.rs index c8ed3d00..558683fc 100644 --- a/crates/code-runtime/src/worker_boot.rs +++ b/crates/code-runtime/src/worker_boot.rs @@ -144,6 +144,7 @@ pub struct Worker { #[derive(Debug, Clone, Default)] pub struct WorkerRegistry { inner: Arc>, + repo_root: Option, } #[derive(Debug, Default)] @@ -158,6 +159,18 @@ impl WorkerRegistry { Self::default() } + /// Return a registry rooted at `repo_root`, so that terminal worker + /// transitions advance the Incremental store baseline (flag-gated on + /// `incremental.enabled` and best-effort: a missing engine binary is a + /// no-op). + #[must_use] + pub fn with_repo_root(repo_root: impl Into) -> Self { + Self { + repo_root: Some(repo_root.into()), + ..Self::default() + } + } + #[must_use] pub fn create( &self, @@ -461,6 +474,7 @@ impl WorkerRegistry { .workers .get_mut(worker_id) .ok_or_else(|| format!("worker not found: {worker_id}"))?; + let was_terminal = is_worker_terminal(worker.status); worker.status = WorkerStatus::Finished; worker.prompt_in_flight = false; push_event( @@ -470,7 +484,12 @@ impl WorkerRegistry { Some("worker terminated by control plane".to_string()), None, ); - Ok(worker.clone()) + let result = Ok(worker.clone()); + drop(inner); + if !was_terminal { + self.advance_if_enabled(worker_id); + } + result } /// Classify session completion and transition worker to appropriate terminal state. @@ -489,6 +508,7 @@ impl WorkerRegistry { let is_provider_failure = (finish_reason == "unknown" && tokens_output == 0) || finish_reason == "error"; + let was_terminal = is_worker_terminal(worker.status); if is_provider_failure { let message = if finish_reason == "unknown" && tokens_output == 0 { @@ -526,8 +546,37 @@ impl WorkerRegistry { ); } - Ok(worker.clone()) + let result = Ok(worker.clone()); + drop(inner); + if !was_terminal { + self.advance_if_enabled(worker_id); + } + result } + + /// Advance the Incremental store baseline if the feature is enabled and + /// a repo root was set. Best-effort: a missing engine binary is a no-op. + fn advance_if_enabled(&self, worker_id: &str) { + let Some(repo_root) = &self.repo_root else { + return; + }; + if !crate::incremental_enabled() { + return; + } + let Some(status_str) = self + .inner + .lock() + .ok() + .and_then(|inner| inner.workers.get(worker_id).map(|w| w.status.to_string())) + else { + return; + }; + crate::incremental_observer::advance(repo_root, &status_str, None); + } +} + +fn is_worker_terminal(status: WorkerStatus) -> bool { + matches!(status, WorkerStatus::Finished | WorkerStatus::Failed) } #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] diff --git a/crates/code-server/Cargo.toml b/crates/code-server/Cargo.toml index 8acd5475..25fecc48 100644 --- a/crates/code-server/Cargo.toml +++ b/crates/code-server/Cargo.toml @@ -17,6 +17,7 @@ code-orchestrator = { path = "../code-orchestrator" } code-repo = { path = "../code-repo" } code-types = { path = "../code-types" } code-runtime = { path = "../code-runtime" } +code-incremental = { path = "../code-incremental" } code-tools = { path = "../code-tools" } serde = { version = "1", features = ["derive"] } serde_json.workspace = true diff --git a/crates/code-server/src/lib.rs b/crates/code-server/src/lib.rs index 7bc4dc48..e99e7756 100644 --- a/crates/code-server/src/lib.rs +++ b/crates/code-server/src/lib.rs @@ -514,20 +514,30 @@ impl ServerState { write_lock: Mutex::new(()), }) }); + let repo_root = std::env::current_dir().ok(); let (tasks, contexts, event_history) = persistence .as_ref() .and_then(|persistence| persistence.load().ok()) .map_or_else( || { ( - TaskRegistry::new(), + match &repo_root { + Some(root) => TaskRegistry::with_repo_root(root.clone()), + None => TaskRegistry::new(), + }, HashMap::new(), VecDeque::with_capacity(event_replay_limit.max(1)), ) }, |snapshot| { + let tasks = match &repo_root { + Some(root) => { + TaskRegistry::from_snapshot_with_repo_root(snapshot.tasks, root.clone()) + } + None => TaskRegistry::from_snapshot(snapshot.tasks), + }; ( - TaskRegistry::from_snapshot(snapshot.tasks), + tasks, snapshot.contexts, trim_event_history(snapshot.event_history, event_replay_limit.max(1)), ) @@ -817,6 +827,54 @@ impl ServerState { } } +/// Returns `true` when the Incremental engine should gate reconcile for +/// this task. When `false`, the task is reconciled unconditionally. +/// +/// The gate is best-effort: when the engine is unavailable or the query +/// falls back, reconcile proceeds as usual (safe default: run everything). +/// +/// # Task-ID scheme +/// +/// The stable identity for the Incremental engine is the **server task ID** +/// (`task_{:08x}_{counter}`), not the ephemeral `work_item_id` (a fresh UUID +/// regenerated on every `plan_work_item` call). The server task ID is +/// persisted in the `TaskRegistry` snapshot and survives restarts within a +/// single server lifetime. Across restarts the counter resets, so a new +/// task gets a new ID; the engine treats it as unobserved and falls back +/// (safe default). The `work_item_id` is not suitable because it is +/// regenerated on replan and multiple work items can map to one task. +fn incremental_gate_should_skip_reconcile(task_id: &str, repo_root: &std::path::Path) -> bool { + if !code_runtime::incremental_enabled() { + return false; + } + let changes = serde_json::json!({ + "changes": [ + { + "path": format!("{task_id}/artifacts"), + "status": "M" + } + ] + }); + let Some(affected) = code_runtime::incremental_observer::affected(repo_root, "HEAD", &changes) + else { + // Engine unavailable or fallback — reconcile as usual. + return false; + }; + // If the task ID is not in the affected set, skip reconcile. + !affected.iter().any(|t| t == task_id) +} + +/// Record a task completion as an Incremental observation and advance +/// the baseline. Best-effort: a missing engine or disabled flag is a +/// no-op. +fn observe_task_completion(task_id: &str, status: &str, repo_root: &std::path::Path) { + if !code_runtime::incremental_enabled() { + return; + } + code_runtime::incremental_observer::observe_task(repo_root, task_id, &[], status, false); + code_runtime::incremental_observer::advance(repo_root, status, None); +} + #[derive(Debug)] struct ServerStatePersistence { path: PathBuf, @@ -2780,6 +2838,17 @@ fn reconcile_active_tasks(state: &ServerState) { .collect::>(); for task_id in active_task_ids { + // Incremental gate: skip reconcile when the engine certifies the + // task is unaffected by changes. Fallback (engine unavailable or + // query falls back) means reconcile proceeds as usual. + if let Some(context) = state.context_for(&task_id) { + if let Some(repo) = &context.repository { + let repo_root = state.publish_workspace_root.join(repo); + if incremental_gate_should_skip_reconcile(&task_id, &repo_root) { + continue; + } + } + } let _ = reconcile_task_from_artifacts(state, &task_id); } } @@ -3449,6 +3518,14 @@ async fn complete_task( state.record_context(&task_id, context.clone()); let failure_error = request.error.clone().or(completion.error.clone()); + // Record the completion as an Incremental observation (flag-gated, + // best-effort). The repo root is derived from the workspace + repository + // name when available. + if let Some(repo) = &context.repository { + let repo_root = state.publish_workspace_root.join(repo); + observe_task_completion(&task_id, &completion.worker_status.to_string(), &repo_root); + } + match completion.worker_status { WorkerStatus::Finished => { state diff --git a/crates/code-tools/src/lib.rs b/crates/code-tools/src/lib.rs index 75aed636..e3b8dc66 100644 --- a/crates/code-tools/src/lib.rs +++ b/crates/code-tools/src/lib.rs @@ -66,7 +66,15 @@ fn global_cron_registry() -> &'static CronRegistry { fn global_task_registry() -> &'static TaskRegistry { use std::sync::OnceLock; static REGISTRY: OnceLock = OnceLock::new(); - REGISTRY.get_or_init(TaskRegistry::new) + // Root the registry at the current working directory so terminal task + // transitions can be recorded as Incremental observations (flag-gated on + // `incremental.enabled`; a no-op when the flag is off or the engine is + // missing). + REGISTRY.get_or_init(|| { + std::env::current_dir() + .map(TaskRegistry::with_repo_root) + .unwrap_or_default() + }) } fn global_worker_registry() -> &'static WorkerRegistry { diff --git a/scripts/fetch-incremental.sh b/scripts/fetch-incremental.sh new file mode 100755 index 00000000..31fc1ce4 --- /dev/null +++ b/scripts/fetch-incremental.sh @@ -0,0 +1,126 @@ +#!/usr/bin/env bash +# Fetch and vendor the Incremental engine at a pinned commit. +# +# This script is the reproducibility anchor for the vendored Incremental +# artifacts. It reads the pin from third_party/manifests/incremental.json, +# clones at that SHA, and copies the Rust binding source and the prebuilt +# engine binaries into third_party/incremental/. +# +# Usage: +# scripts/fetch-incremental.sh [--source DIR] +# +# --source DIR Use a local checkout instead of cloning (for offline use). +# DIR must be a checkout of frontal-labs/incremental at the +# pinned commit. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +MANIFEST="$REPO_ROOT/third_party/manifests/incremental.json" +DEST="$REPO_ROOT/third_party/incremental" + +# --- read pin from manifest --- +if [[ ! -f "$MANIFEST" ]]; then + echo "error: manifest not found: $MANIFEST" >&2 + exit 1 +fi + +COMMIT="$(python3 -c "import json; print(json.load(open('$MANIFEST'))['commit'])")" +SHA256_RUST="$(python3 -c "import json; print(json.load(open('$MANIFEST'))['sha256_rust_src'])")" +REPO_URL="$(python3 -c "import json; print(json.load(open('$MANIFEST'))['repo'])")" + +echo "==> Pinned incremental commit: $COMMIT" + +# --- resolve source --- +SOURCE_DIR="" +if [[ "${1:-}" == "--source" ]]; then + SOURCE_DIR="${2:?usage: --source DIR}" + if [[ ! -d "$SOURCE_DIR" ]]; then + echo "error: source directory not found: $SOURCE_DIR" >&2 + exit 1 + fi +else + # Clone at the pinned SHA + SOURCE_DIR="$(mktemp -d)" + trap 'rm -rf "$SOURCE_DIR"' EXIT + echo "==> Cloning $REPO_URL at $COMMIT ..." + git clone --quiet "$REPO_URL" "$SOURCE_DIR" + (cd "$SOURCE_DIR" && git checkout --quiet "$COMMIT") +fi + +ACTUAL_COMMIT="$(cd "$SOURCE_DIR" && git rev-parse HEAD)" +if [[ "$ACTUAL_COMMIT" != "$COMMIT" ]]; then + echo "error: source commit $ACTUAL_COMMIT does not match pinned $COMMIT" >&2 + exit 1 +fi + +# --- verify Rust binding source hash --- +COMPUTED_HASH="$(cd "$SOURCE_DIR" && tar -cf - \ + bindings/rust/Cargo.toml \ + bindings/rust/Cargo.lock \ + bindings/rust/src/ \ + 2>/dev/null | shasum -a 256 | awk '{print $1}')" + +if [[ "$COMPUTED_HASH" != "$SHA256_RUST" ]]; then + echo "error: Rust binding source hash mismatch" >&2 + echo " expected: $SHA256_RUST" >&2 + echo " computed: $COMPUTED_HASH" >&2 + exit 1 +fi +echo "==> Rust binding source hash verified" + +# --- copy Rust binding --- +echo "==> Copying Rust binding to $DEST/rust ..." +rm -rf "$DEST/rust" +mkdir -p "$DEST/rust/src" +cp "$SOURCE_DIR/bindings/rust/Cargo.toml" "$DEST/rust/Cargo.toml" +cp "$SOURCE_DIR/bindings/rust/Cargo.lock" "$DEST/rust/Cargo.lock" +cp "$SOURCE_DIR/bindings/rust/src/lib.rs" "$DEST/rust/src/lib.rs" + +# --- copy engine binary (if present in source) --- +BIN_SRC="$SOURCE_DIR/core/dist/incremental" +if [[ -f "$BIN_SRC" ]]; then + # Detect the binary's platform triple + OS="$(uname -s | tr '[:upper:]' '[:lower:]')" + ARCH="$(uname -m)" + case "$ARCH" in + x86_64) ARCH="x64" ;; + aarch64) ARCH="arm64" ;; + arm64) ARCH="arm64" ;; + esac + TRIPLE="$OS-$ARCH" + echo "==> Copying engine binary ($TRIPLE) ..." + mkdir -p "$DEST/engine-binaries/$TRIPLE" + cp "$BIN_SRC" "$DEST/engine-binaries/$TRIPLE/incremental" + chmod +x "$DEST/engine-binaries/$TRIPLE/incremental" + + # Verify SHA-256 against the manifest + EXPECTED_BIN_HASH="$(python3 -c " +import json, sys +m = json.load(open('$MANIFEST')) +bins = m.get('sha256_bins', {}) +h = bins.get('$TRIPLE') +if h is None: + print('NOT_PINNED') +else: + print(h) +")" + ACTUAL_BIN_HASH="$(shasum -a 256 "$DEST/engine-binaries/$TRIPLE/incremental" | awk '{print $1}')" + if [[ "$EXPECTED_BIN_HASH" == "NOT_PINNED" ]]; then + echo "==> WARNING: engine binary for $TRIPLE is not pinned in the manifest." >&2 + echo "==> Computed SHA-256: $ACTUAL_BIN_HASH" >&2 + echo "==> Add it to third_party/manifests/incremental.json sha256_bins." >&2 + elif [[ "$ACTUAL_BIN_HASH" != "$EXPECTED_BIN_HASH" ]]; then + echo "error: engine binary hash mismatch for $TRIPLE" >&2 + echo " expected: $EXPECTED_BIN_HASH" >&2 + echo " computed: $ACTUAL_BIN_HASH" >&2 + exit 1 + else + echo "==> Engine binary hash verified" + fi +else + echo "==> No engine binary found in source (core/dist/incremental). Skipping." >&2 + echo "==> Build it with: cd incremental && make build" >&2 +fi + +echo "==> Done. Incremental vendored at $COMMIT" diff --git a/third_party/incremental/BUILD.bazel b/third_party/incremental/BUILD.bazel new file mode 100644 index 00000000..f080cd0e --- /dev/null +++ b/third_party/incremental/BUILD.bazel @@ -0,0 +1,20 @@ +load("@rules_shell//shell:sh_binary.bzl", "sh_binary") + +package(default_visibility = ["//visibility:public"]) + +# Vendored Rust binding source. +filegroup( + name = "rust_src", + srcs = glob( + ["rust/**/*"], + exclude = ["rust/target/**"], + ), +) + +# Prebuilt engine binaries per platform. +filegroup( + name = "engine_binary", + srcs = [ + "engine-binaries/darwin-arm64/incremental", + ], +) diff --git a/third_party/incremental/engine-binaries/darwin-arm64/incremental b/third_party/incremental/engine-binaries/darwin-arm64/incremental new file mode 100755 index 00000000..3ca93af1 Binary files /dev/null and b/third_party/incremental/engine-binaries/darwin-arm64/incremental differ diff --git a/third_party/incremental/rust/Cargo.lock b/third_party/incremental/rust/Cargo.lock new file mode 100644 index 00000000..a19b540b --- /dev/null +++ b/third_party/incremental/rust/Cargo.lock @@ -0,0 +1,135 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "equivalent" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826" + +[[package]] +name = "foldhash" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb" + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "incremental" +version = "0.1.0" +dependencies = [ + "serde_json", +] + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown", +] + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "foldhash", + "indexmap", + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "syn" +version = "3.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/third_party/incremental/rust/Cargo.toml b/third_party/incremental/rust/Cargo.toml new file mode 100644 index 00000000..c3acdf71 --- /dev/null +++ b/third_party/incremental/rust/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "incremental" +version = "0.1.0" +edition = "2021" +description = "Rust client for incremental Protocol v1 (spawns `incremental serve`)" +license = "Apache-2.0" +publish = false + +[dependencies] +serde_json = { version = "1", features = ["preserve_order"] } diff --git a/third_party/incremental/rust/src/lib.rs b/third_party/incremental/rust/src/lib.rs new file mode 100644 index 00000000..8d640a4d --- /dev/null +++ b/third_party/incremental/rust/src/lib.rs @@ -0,0 +1,515 @@ +//! Rust client for incremental Protocol v1 (docs/spec/PROTOCOL.md, spec/adapters/rust.md). +//! +//! The client spawns `incremental serve`, sends one JSON object per line and +//! matches each answer by id. It never plans: every answer comes from the engine. +//! Methods take `&mut self`, so requests run one at a time in call order. + +use serde_json::{json, Map, Value}; +use std::env; +use std::fmt; +use std::io::{BufRead, BufReader, Write}; +use std::path::PathBuf; +use std::process::{Child, ChildStdin, Command, ExitStatus, Stdio}; +use std::sync::mpsc::{self, Receiver, RecvTimeoutError}; +use std::sync::{Arc, Mutex}; +use std::thread; +use std::time::{Duration, Instant}; + +const PROTOCOL: u64 = 1; +const CLIENT_NAME: &str = "incremental-rust"; +const CLIENT_VERSION: &str = env!("CARGO_PKG_VERSION"); +const STARTUP_TIMEOUT: Duration = Duration::from_secs(10); +const STDERR_LINES: usize = 20; +// Methods that do not change the store. Only these are retried after a restart. +const READ_ONLY: [&str; 6] = ["hello", "baseline", "affected", "explain", "stats", "ping"]; + +/// A protocol error (`code`, `message`, `data`), or a client-side error such as `timeout`. +#[derive(Debug, Clone, PartialEq)] +pub struct Error { + pub code: String, + pub message: String, + pub data: Option, +} + +impl Error { + fn new(code: &str, message: impl Into, data: Option) -> Self { + Error { + code: code.to_string(), + message: message.into(), + data, + } + } +} + +impl fmt::Display for Error { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "{}: {}", self.code, self.message) + } +} + +impl std::error::Error for Error {} + +pub type Result = std::result::Result; + +/// Engine command, store, root and timing. `Config::default()` reads +/// `INCREMENTAL_ENGINE` and `INCREMENTAL_STORE`, and uses the enclosing git repository. +#[derive(Debug, Clone)] +pub struct Config { + /// Command prefix. The client runs ` serve --store --root `. + pub engine: Vec, + pub store: PathBuf, + pub root: PathBuf, + /// Budget for each request. A timeout kills the engine. + pub timeout: Duration, + /// Start a new engine when the old one has exited. + pub restart: bool, +} + +impl Default for Config { + fn default() -> Self { + let root = repo_root(); + Config { + engine: vec![env::var("INCREMENTAL_ENGINE") + .unwrap_or_else(|_| root.join("core/dist/incremental").display().to_string())], + store: env::var_os("INCREMENTAL_STORE") + .map_or_else(|| root.join(".incremental"), PathBuf::from), + timeout: Duration::from_secs(10), + restart: true, + root, + } + } +} + +fn repo_root() -> PathBuf { + let here = env::current_dir().unwrap_or_else(|_| PathBuf::from(".")); + match here.ancestors().find(|dir| dir.join(".git").exists()) { + Some(dir) => dir.to_path_buf(), + None => here.clone(), + } +} + +/// The options of an `affected` call (PROTOCOL.md 9.3). `context`, `env`, +/// `config` and `declared_tasks` are sent only when set. +#[derive(Debug, Clone)] +pub struct Affected { + pub baseline: String, + pub context: Option, + pub verify: bool, + pub policy: String, + pub env: Option, + pub config: Option, + pub declared_tasks: Option, +} + +impl Affected { + pub fn new(baseline: impl Into) -> Self { + Affected { + baseline: baseline.into(), + context: None, + verify: false, + policy: "balanced".to_string(), + env: None, + config: None, + declared_tasks: None, + } + } + + /// The `options` object of the request. + pub fn options(&self) -> Value { + let mut opts = + json!({"baseline": self.baseline, "verify": self.verify, "policy": self.policy}); + let map = opts.as_object_mut().expect("options is an object"); + let extra = [ + ("context", &self.context), + ("env", &self.env), + ("config", &self.config), + ("declared_tasks", &self.declared_tasks), + ]; + for (key, value) in extra { + if let Some(value) = value { + map.insert(key.to_string(), value.clone()); + } + } + opts + } +} + +/// A running engine and the reader threads for its stdout and stderr. +#[derive(Debug)] +struct Run { + child: Child, + stdin: ChildStdin, + lines: Receiver>, + stderr: Arc>>, + hello: Value, +} + +/// A client for one engine process. The process is started by `connect` and +/// restarted on the next call if it died (when `Config::restart` is set). +#[derive(Debug)] +pub struct Incremental { + cfg: Config, + run: Option, + started: bool, + next_id: u64, +} + +impl Incremental { + /// Starts the engine and runs the `hello` handshake. + pub fn connect(cfg: Config) -> Result { + let mut client = Incremental { + cfg, + run: None, + started: false, + next_id: 1, + }; + client.ensure()?; + Ok(client) + } + + /// The `hello` result: `{protocol, engine, capabilities, store}`. + pub fn hello(&mut self) -> Result { + Ok(self.ensure()?.hello.clone()) + } + + pub fn observe(&mut self, observation: &Value) -> Result { + self.request("observe", &json!({"observation": observation})) + } + + /// Atomic: either all observations are stored or none. Returns `{accepted: n}`. + pub fn observe_many(&mut self, observations: &[Value]) -> Result { + self.request("observe_many", &json!({"observations": observations})) + } + + pub fn baseline(&mut self) -> Result { + self.request("baseline", &json!({})) + } + + /// Fails with `baseline_conflict` unless `expected` equals the current baseline. + pub fn advance(&mut self, to: &str, expected: Option<&str>) -> Result { + self.request("advance", &json!({"to": to, "expected": expected})) + } + + /// Returns the plan (PROTOCOL.md 9.6). A partial plan is an error. + pub fn affected(&mut self, changes: &Value, options: &Affected) -> Result { + let plan = self.request( + "affected", + &json!({"changes": changes, "options": options.options()}), + )?; + check_plan(plan) + } + + pub fn explain(&mut self, task: &str) -> Result { + self.request("explain", &json!({"task": task})) + } + + pub fn forget(&mut self, task: &str) -> Result { + self.request("forget", &json!({"task": task})) + } + + pub fn stats(&mut self) -> Result { + self.request("stats", &json!({})) + } + + /// Forwarded to the engine, which may refuse (`compact` is not in this milestone). + pub fn compact(&mut self) -> Result { + self.request("compact", &json!({})) + } + + pub fn ping(&mut self) -> Result { + self.request("ping", &json!({})) + } + + /// Sends `shutdown`, waits up to the request timeout for the exit, then kills the engine. + pub fn close(self) { + drop(self); + } + + fn take_id(&mut self) -> u64 { + let id = self.next_id; + self.next_id += 1; + id + } + + // The running engine, starting one when there is none or the last one exited. + fn ensure(&mut self) -> Result<&mut Run> { + let exited = match self.run.as_mut() { + Some(run) => matches!(run.child.try_wait(), Ok(Some(_))), + None => true, + }; + if exited { + self.run = None; + if self.started && !self.cfg.restart { + return Err(Error::new( + "engine_exited", + "the engine exited and restart is disabled", + None, + )); + } + let run = self.start()?; + self.run = Some(run); + } + Ok(self.run.as_mut().expect("engine is running")) + } + + fn start(&mut self) -> Result { + let mut run = spawn(&self.cfg)?; + self.started = true; + let params = json!({"protocol": PROTOCOL, "client": {"name": CLIENT_NAME, "version": CLIENT_VERSION}}); + let id = self.take_id(); + let hello = match call(&mut run, id, "hello", ¶ms, STARTUP_TIMEOUT) { + Ok(hello) => hello, + Err(err) => { + kill(&mut run.child); + return Err(err); + } + }; + match hello.get("protocol").and_then(Value::as_u64) { + Some(PROTOCOL) => {} + Some(_) => { + kill(&mut run.child); + return Err(Error::new( + "protocol_mismatch", + "the engine does not speak protocol 1", + Some(hello), + )); + } + None => { + kill(&mut run.child); + return Err(Error::new( + "internal", + "the engine answered hello with no protocol", + None, + )); + } + } + run.hello = hello; + Ok(run) + } + + fn request(&mut self, method: &str, params: &Value) -> Result { + match self.exchange(method, params) { + Err(err) + if err.code == "engine_exited" + && self.cfg.restart + && READ_ONLY.contains(&method) => + { + self.exchange(method, params) + } + other => other, + } + } + + fn exchange(&mut self, method: &str, params: &Value) -> Result { + let id = self.take_id(); + let timeout = self.cfg.timeout; + let run = self.ensure()?; + let result = call(run, id, method, params, timeout); + if matches!(&result, Err(err) if err.code == "timeout" || err.code == "engine_exited") { + self.run = None; + } + result + } + + fn stop(&mut self) { + let Some(mut run) = self.run.take() else { + return; + }; + if matches!(run.child.try_wait(), Ok(None)) { + let id = self.take_id(); + // The engine writes its index image before it exits, so give it time. + let _ = call(&mut run, id, "shutdown", &json!({}), self.cfg.timeout); + } + if wait_exit(&mut run.child, self.cfg.timeout).is_none() { + kill(&mut run.child); + } + } +} + +impl Drop for Incremental { + fn drop(&mut self) { + self.stop(); + } +} + +fn spawn(cfg: &Config) -> Result { + let (cmd, prefix) = cfg + .engine + .split_first() + .ok_or_else(|| Error::new("internal", "the engine command is empty", None))?; + let mut child = Command::new(cmd) + .args(prefix) + .arg("serve") + .arg("--store") + .arg(&cfg.store) + .arg("--root") + .arg(&cfg.root) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .map_err(|err| Error::new("internal", format!("cannot run the engine: {err}"), None))?; + let stdin = child.stdin.take().expect("stdin is piped"); + let stdout = child.stdout.take().expect("stdout is piped"); + let stderr = child.stderr.take().expect("stderr is piped"); + + let (tx, lines) = mpsc::channel(); + thread::spawn(move || { + for line in BufReader::new(stdout) + .lines() + .map_while(std::io::Result::ok) + { + if tx.send(Some(line)).is_err() { + return; + } + } + let _ = tx.send(None); + }); + + let tail = Arc::new(Mutex::new(Vec::::new())); + let sink = Arc::clone(&tail); + thread::spawn(move || { + for line in BufReader::new(stderr) + .lines() + .map_while(std::io::Result::ok) + { + let mut kept = sink.lock().unwrap_or_else(|poisoned| poisoned.into_inner()); + kept.push(line); + let excess = kept.len().saturating_sub(STDERR_LINES); + kept.drain(..excess); + } + }); + + Ok(Run { + child, + stdin, + lines, + stderr: tail, + hello: Value::Null, + }) +} + +// Sends one request and reads lines until the answer with `id` arrives. A +// timeout or the end of the output ends the run; the caller drops it. +fn call(run: &mut Run, id: u64, method: &str, params: &Value, timeout: Duration) -> Result { + let line = json!({"id": id, "method": method, "params": params}).to_string(); + // A failed write means the engine is gone. Its end of output is reported below. + let _ = writeln!(run.stdin, "{line}"); + let _ = run.stdin.flush(); + + let deadline = Instant::now() + timeout; + loop { + let raw = match run + .lines + .recv_timeout(deadline.saturating_duration_since(Instant::now())) + { + Ok(Some(raw)) => raw, + Ok(None) | Err(RecvTimeoutError::Disconnected) => return Err(exited(run)), + Err(RecvTimeoutError::Timeout) => { + kill(&mut run.child); + let data = json!({"partial": false}); + return Err(Error::new( + "timeout", + format!("no response within {timeout:?}"), + Some(data), + )); + } + }; + let msg: Map = match serde_json::from_str(&raw) { + Ok(Value::Object(msg)) => msg, + _ => { + let text = format!("engine wrote a line that is not a JSON object: {raw:?}"); + return Err(Error::new("bad_response", text, None)); + } + }; + if msg.get("id") == Some(&json!(id)) { + if let Some(err) = msg.get("error") { + return Err(error_of(err)); + } + return msg.get("result").cloned().ok_or_else(|| { + Error::new( + "bad_response", + "response has neither result nor error", + None, + ) + }); + } + // A store-level failure is printed without an id (CLI style): {"ok": false, "error": {...}}. + if msg.get("id").is_none_or(|v| v.is_null()) && msg.get("ok") == Some(&Value::Bool(false)) { + if let Some(err) = msg.get("error") { + return Err(error_of(err)); + } + } + // Any other line belongs to an earlier request and is dropped. + } +} + +fn error_of(err: &Value) -> Error { + Error { + code: err + .get("code") + .and_then(Value::as_str) + .unwrap_or("internal") + .to_string(), + message: err + .get("message") + .and_then(Value::as_str) + .unwrap_or("") + .to_string(), + data: err.get("data").filter(|data| !data.is_null()).cloned(), + } +} + +// The engine ended while a request was in flight, or before one was sent. +fn exited(run: &mut Run) -> Error { + let status = wait_exit(&mut run.child, Duration::from_secs(5)).and_then(|status| status.code()); + kill(&mut run.child); + let stderr = run + .stderr + .lock() + .map(|lines| lines.join("\n")) + .unwrap_or_default(); + let code = status.map_or_else(|| "unknown".to_string(), |code| code.to_string()); + let data = (!stderr.is_empty()).then(|| Value::String(stderr)); + Error::new( + "engine_exited", + format!("engine exited (status {code})"), + data, + ) +} + +fn wait_exit(child: &mut Child, timeout: Duration) -> Option { + let deadline = Instant::now() + timeout; + loop { + match child.try_wait() { + Ok(Some(status)) => return Some(status), + Ok(None) if Instant::now() < deadline => thread::sleep(Duration::from_millis(5)), + _ => return None, + } + } +} + +fn kill(child: &mut Child) { + let _ = child.kill(); + let _ = child.wait(); +} + +// A plan is never returned partially (PROTOCOL.md 9.6). +fn check_plan(plan: Value) -> Result { + let lists = ["tasks", "unobserved", "ignored", "deleted_tasks"]; + let fields = ["fallback", "confidence", "graph_version"]; + let complete = lists + .iter() + .all(|key| plan.get(*key).is_some_and(|v| v.is_array())) + && fields.iter().all(|key| plan.get(*key).is_some()); + if complete { + Ok(plan) + } else { + let data = json!({"reason": "partial_plan"}); + Err(Error::new( + "internal", + "the engine answered affected with an incomplete plan", + Some(data), + )) + } +} diff --git a/third_party/manifests/incremental.json b/third_party/manifests/incremental.json new file mode 100644 index 00000000..efe7a209 --- /dev/null +++ b/third_party/manifests/incremental.json @@ -0,0 +1,8 @@ +{ + "repo": "frontal-labs/incremental", + "commit": "5039a33ce9b8ca4160bb9d5c326e6107932b6782", + "sha256_rust_src": "acd214ebb81a5678f4885d83e49c4fa1423f1601466c6abfb13bcaceee98b11f", + "sha256_bins": { + "darwin-arm64": "8a3bd414981961d684dead2d3456b54f27a9b1d9dc21d506fe0d047fadd3dd83" + } +} diff --git a/tools/incremental/BUILD.bazel b/tools/incremental/BUILD.bazel new file mode 100644 index 00000000..865b2fee --- /dev/null +++ b/tools/incremental/BUILD.bazel @@ -0,0 +1,7 @@ +package(default_visibility = ["//visibility:public"]) + +sh_binary( + name = "incremental", + srcs = ["//tools:cargo_run.sh"], + args = ["tools-incremental"], +) diff --git a/tools/incremental/Cargo.toml b/tools/incremental/Cargo.toml new file mode 100644 index 00000000..02c18e88 --- /dev/null +++ b/tools/incremental/Cargo.toml @@ -0,0 +1,16 @@ +[package] +name = "tools-incremental" +version.workspace = true +edition.workspace = true +license.workspace = true +publish.workspace = true + +[dependencies] +anyhow = "1" +clap = { version = "4", features = ["derive"] } +code-incremental = { path = "../../crates/code-incremental" } +serde = { version = "1", features = ["derive"] } +serde_json = "1" + +[lints] +workspace = true diff --git a/tools/incremental/src/main.rs b/tools/incremental/src/main.rs new file mode 100644 index 00000000..a8c873e5 --- /dev/null +++ b/tools/incremental/src/main.rs @@ -0,0 +1,411 @@ +//! `tools-incremental` — dev-pipeline CLI for the Incremental Compute Engine. +//! +//! Wraps the `code-incremental` crate so the repo's build/test pipeline can +//! observe task outcomes, advance the baseline, and ask which tasks are +//! affected by a changeset. Fallbacks ("run everything") are the safe +//! default and never a hard error. + +use std::fs; +use std::path::{Path, PathBuf}; + +use anyhow::{bail, Context, Result}; +use clap::{Parser, Subcommand}; +use code_incremental::{build_context, target_triple, EngineBinary, Store}; +use serde::Serialize; +use serde_json::{json, Value}; + +#[derive(Parser)] +#[command( + name = "code-incremental", + about = "Incremental Compute Engine dev CLI" +)] +struct Cli { + /// Repository root the store is rooted at (defaults to the current directory). + #[arg(long, global = true, default_value = ".")] + root: PathBuf, + + /// Output format. + #[arg(long, value_enum, default_value_t = Format::Text, global = true)] + format: Format, + + /// Suppress the fallback-safe exit code (always exit 0 on success). + #[arg(long, global = true)] + no_fail_on_fallback: bool, + + #[command(subcommand)] + command: Command, +} + +#[derive(Copy, Clone, PartialEq, Eq, clap::ValueEnum, Serialize)] +#[value(rename_all = "lowercase")] +enum Format { + Text, + Json, +} + +#[derive(Subcommand)] +enum Command { + /// Resolve the engine binary and print its path. + Doctor, + /// The engine `hello` handshake (protocol, engine, capabilities, store). + Hello, + /// Ping the engine. + Ping, + /// Store statistics (tasks, observations, baseline). + Stats, + /// Query the current baseline. + Baseline, + /// Advance the baseline to a new sha. + Advance { + /// New baseline sha to advance to. + to: String, + /// Expected current baseline; omit (or use `--expected null`) for the first advance. + #[arg(long, default_value = "null")] + expected: String, + }, + /// Record a single observation (JSON file or `-` for stdin). + Observe { + /// Path to a JSON observation file, or `-` for stdin. + input: PathBuf, + }, + /// Record multiple observations from a JSON array file (or `-` for stdin). + ObserveMany { + /// Path to a JSON array of observations, or `-` for stdin. + input: PathBuf, + }, + /// Explain why a task is or is not invalid. + Explain { task: String }, + /// Drop a task's observations. + Forget { task: String }, + /// Compute the affected plan for a changeset. + Affected { + /// Baseline to compare against. + baseline: String, + /// Path to a changeset JSON file (`{"changes": [{"path": ..., "status": ...}]}`), + /// or `-` for stdin. When omitted, a git diff against the baseline is used. + #[arg(long)] + changes: Option, + /// Runner identifier for the observation context (default: `frontal-code-cli`). + #[arg(long, default_value = "frontal-code-cli")] + runner: String, + /// Runtime node version for the observation context. + #[arg(long, default_value = "0.0.0")] + node: String, + /// Repo-relative path to the lockfile (default: auto-detect `Cargo.lock`). + #[arg(long)] + lockfile: Option, + }, +} + +fn main() { + if let Err(err) = run() { + eprintln!("error: {err:#}"); + std::process::exit(1); + } +} + +#[allow(clippy::too_many_lines)] +fn run() -> Result<()> { + let cli = Cli::parse(); + let repo_root = canonicalize(&cli.root)?; + + if matches!(cli.command, Command::Doctor) { + let triple = target_triple(); + let engine = EngineBinary::resolve(); + let path = engine.path().map(Path::display); + let report = json!({ + "platform": triple, + "engine_found": engine.is_available(), + "engine_path": path.map(|p| p.to_string()), + "store_path": store_display_path(&repo_root), + }); + print_result(cli.format, &report, &doctor_text(&report)); + return Ok(()); + } + + let Some(mut store) = open_store(&repo_root)? else { + // No engine binary available: degrade to the safe default. + eprintln!("incremental engine unavailable; assuming everything is affected"); + if !cli.no_fail_on_fallback { + std::process::exit(EXIT_FALLBACK); + } + return Ok(()); + }; + + match &cli.command { + Command::Doctor => unreachable!("handled above"), + Command::Hello => { + print_raw(cli.format, &store.hello().context("hello")?); + } + Command::Ping => { + print_raw(cli.format, &store.ping().context("ping")?); + } + Command::Stats => { + print_raw(cli.format, &store.stats().context("stats")?); + } + Command::Baseline => { + print_raw(cli.format, &store.baseline().context("baseline")?); + } + Command::Advance { to, expected } => { + let expected_opt = (expected != "null").then_some(expected.as_str()); + print_raw( + cli.format, + &store.advance(to, expected_opt).context("advance")?, + ); + } + Command::Observe { input } => { + let observation = read_json(input).context("read observation")?; + print_raw(cli.format, &store.observe(&observation).context("observe")?); + } + Command::ObserveMany { input } => { + let value = read_json(input).context("read observations")?; + let arr = value + .as_array() + .context("input must be a JSON array of observations")?; + print_raw( + cli.format, + &store.observe_many(arr).context("observe_many")?, + ); + } + Command::Explain { task } => { + print_raw(cli.format, &store.explain(task).context("explain")?); + } + Command::Forget { task } => { + print_raw(cli.format, &store.forget(task).context("forget")?); + } + Command::Affected { + baseline, + changes, + runner, + node, + lockfile, + } => { + let changeset = match changes { + Some(path) => read_json(path).context("read changeset")?, + None => git_changeset(baseline, &repo_root)?, + }; + // Lockfile override: the digest is embedded in the context; + // an explicit `--lockfile` path is honored by re-deriving + // the digest for that specific file. + let context = if let Some(lock) = lockfile { + context_with_lockfile(&repo_root, lock, runner, node) + } else { + build_context(&repo_root, runner, node) + }; + let plan = store + .affected(&changeset, baseline, &context) + .with_context(|| format!("affected against baseline {baseline}"))?; + + let report = json!({ + "baseline": baseline, + "fallback": plan.is_fallback(), + "fallback_reason": plan.fallback.as_ref().map(|f| &f.reason), + "tasks": plan.tasks, + "skipped": plan.skipped, + "unobserved": plan.unobserved, + "confidence": plan.confidence, + "graph_version": plan.graph_version, + }); + print_result(cli.format, &report, &affected_text(&report)); + if plan.is_fallback() && !cli.no_fail_on_fallback { + std::process::exit(EXIT_FALLBACK); + } + } + } + + Ok(()) +} + +/// Exit code for a fallback result: the caller should run everything. +const EXIT_FALLBACK: i32 = 3; + +fn open_store(repo_root: &Path) -> Result> { + let engine = EngineBinary::resolve(); + if engine.path().is_none() { + return Ok(None); + } + Store::open(repo_root) + .map(Some) + .context("open incremental store") +} + +fn canonicalize(path: &Path) -> Result { + let canonical = + fs::canonicalize(path).with_context(|| format!("resolve {}", path.display()))?; + if !canonical.is_dir() { + bail!("{} is not a directory", canonical.display()); + } + Ok(canonical) +} + +fn store_display_path(repo_root: &Path) -> String { + std::env::var_os("FRONTAL_CODE_INCREMENTAL_STORE") + .or_else(|| std::env::var_os("INCREMENTAL_STORE")) + .map_or_else( + || repo_root.join(".incremental").display().to_string(), + |p| p.to_string_lossy().into_owned(), + ) +} + +fn read_json(path: &Path) -> Result { + let raw = if path == Path::new("-") { + let mut buf = String::new(); + std::io::Read::read_to_string(&mut std::io::stdin(), &mut buf).context("read stdin")?; + buf + } else { + fs::read_to_string(path).with_context(|| format!("read {}", path.display()))? + }; + let value: Value = serde_json::from_str(&raw).with_context(|| "parse JSON")?; + Ok(value) +} + +/// Build a changeset from `git diff --name-status ` when no file is given. +fn git_changeset(baseline: &str, repo_root: &Path) -> Result { + let output = std::process::Command::new("git") + .args(["diff", "--name-status", baseline]) + .current_dir(repo_root) + .output() + .context("run git diff")?; + if !output.status.success() { + let stderr = String::from_utf8_lossy(&output.stderr); + // A bad baseline (unknown commit) is a fallback trigger, not a crash. + bail!( + "git diff failed: {stderr}\n\ + (pass --changes with an explicit changeset, or use a valid baseline sha)" + ); + } + let stdout = String::from_utf8_lossy(&output.stdout); + let changes: Vec = stdout + .lines() + .filter(|line| !line.trim().is_empty()) + .map(|line| { + let mut parts = line.splitn(2, '\t'); + let status = parts.next().unwrap_or_default(); + let path = parts.next().unwrap_or_default(); + json!({"path": path, "status": status}) + }) + .collect(); + Ok(json!({"changes": changes})) +} + +/// Like [`build_context`] but with an explicit lockfile path override. +fn context_with_lockfile(repo_root: &Path, lockfile: &str, runner: &str, node: &str) -> Value { + let mut ctx = build_context(repo_root, runner, node); + let path = Path::new(lockfile); + let abs = if path.is_absolute() { + path.to_path_buf() + } else { + repo_root.join(path) + }; + let digest = match fs::read(&abs) { + Ok(bytes) => { + // Reuse the same digest scheme as build_context (FNV-1a based). + // The exact bytes don't matter as long as they are deterministic + // for the same file contents. + Some(Value::String(format!("{:x}", fnv1a_64(&bytes, 0)))) + } + Err(_) => None, + }; + if let Some(obj) = ctx.as_object_mut() { + obj.insert("lockfile".to_string(), digest.unwrap_or(Value::Null)); + } + ctx +} + +/// FNV-1a 64-bit hash (local copy to avoid a new dependency). +fn fnv1a_64(data: &[u8], offset: u64) -> u64 { + let mut hash: u64 = 0xcbf2_9ce4_8422_2325u64 ^ offset; + for &byte in data { + hash ^= u64::from(byte); + hash = hash.wrapping_mul(0x1000_0000_01b3u64); + } + hash +} + +fn print_raw(format: Format, value: &Value) { + print_result(format, value, &value.to_string()); +} + +fn print_result(format: Format, value: &Value, text: &str) { + match format { + Format::Text => println!("{text}"), + Format::Json => { + let pretty = serde_json::to_string_pretty(value).unwrap_or_else(|_| value.to_string()); + println!("{pretty}"); + } + } +} + +fn doctor_text(report: &Value) -> String { + let triple = report["platform"].as_str().unwrap_or("?"); + if report["engine_found"].as_bool().unwrap_or(false) { + let path = report["engine_path"].as_str().unwrap_or("?"); + format!( + "platform: {triple}\nengine: {path}\nstore: {}", + report["store_path"].as_str().unwrap_or("?") + ) + } else { + format!( + "platform: {triple}\nengine: NOT FOUND (set FRONTAL_CODE_INCREMENTAL_ENGINE or INCREMENTAL_ENGINE)\nstore: {}", + report["store_path"].as_str().unwrap_or("?") + ) + } +} + +fn affected_text(report: &Value) -> String { + if report["fallback"].as_bool().unwrap_or(false) { + let reason = report["fallback_reason"].as_str().unwrap_or("unknown"); + return format!("FALLBACK ({reason}): run everything"); + } + let mut lines = Vec::new(); + if let Some(tasks) = report["tasks"].as_array() { + for task in tasks { + let id = task["task_id"].as_str().unwrap_or("?"); + let reasons = task["reasons"] + .as_array() + .map(|r| { + r.iter() + .filter_map(|v| v.as_str()) + .collect::>() + .join(", ") + }) + .unwrap_or_default(); + lines.push(format!("{id}: {reasons}")); + } + } + lines.push(format!( + "skipped={} unobserved={} confidence={}", + report["skipped"].as_u64().unwrap_or(0), + report["unobserved"].as_array().map_or(0, Vec::len), + report["confidence"].as_str().unwrap_or("?") + )); + lines.join("\n") +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn affected_text_reports_fallback() { + let report = json!({"fallback": true, "fallback_reason": "no_baseline"}); + let text = affected_text(&report); + assert!(text.contains("FALLBACK")); + assert!(text.contains("no_baseline")); + } + + #[test] + fn affected_text_lists_tasks() { + let report = json!({ + "fallback": false, + "tasks": [{"task_id": "a.rs#test", "reasons": ["reads:a.rs"]}], + "skipped": 2, + "unobserved": ["b.rs#test"], + "confidence": "medium" + }); + let text = affected_text(&report); + assert!(text.contains("a.rs#test: reads:a.rs")); + assert!(text.contains("skipped=2")); + assert!(text.contains("confidence=medium")); + } +}