diff --git a/Cargo.lock b/Cargo.lock index ff060e0..72317f9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -504,18 +504,18 @@ dependencies = [ [[package]] name = "comline-catalog" -version = "0.10.0" -source = "git+https://github.com/ComlineProject/specification?rev=068500670debade6b004b85032924f945dbb0a2c#068500670debade6b004b85032924f945dbb0a2c" +version = "0.11.0" +source = "git+https://github.com/ComlineProject/specification?rev=69882e92971e243b6b74a539a13b534d95b3abf7#69882e92971e243b6b74a539a13b534d95b3abf7" [[package]] name = "comline-catalog" -version = "0.10.0" -source = "git+https://github.com/ComlineProject/runtime?rev=3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51#3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51" +version = "0.11.0" +source = "git+https://github.com/ComlineProject/runtime?rev=8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d#8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d" [[package]] name = "comline-codegen" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" +source = "git+https://github.com/ComlineProject/generation?rev=8e7dca84ed42f1b785fdb2470a2e94773e2fcef6#8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" dependencies = [ "comline-core", "eyre", @@ -529,7 +529,7 @@ dependencies = [ [[package]] name = "comline-codegen-rust" version = "0.1.0" -source = "git+https://github.com/ComlineProject/comline-rust?rev=349763589f16fcee43a9b8bc3e2d9af8674fef00#349763589f16fcee43a9b8bc3e2d9af8674fef00" +source = "git+https://github.com/ComlineProject/comline-rust?rev=3e6864d31fa6e933d34dde186256be6ae2ad1ff9#3e6864d31fa6e933d34dde186256be6ae2ad1ff9" dependencies = [ "comline-codegen", "comline-core", @@ -539,7 +539,7 @@ dependencies = [ [[package]] name = "comline-codegen-typescript" version = "0.1.0" -source = "git+https://github.com/ComlineProject/comline-typescript?rev=20bad456df0334b0197ddefdc1460f96c7ff33ae#20bad456df0334b0197ddefdc1460f96c7ff33ae" +source = "git+https://github.com/ComlineProject/comline-typescript?rev=b5fc2438028e6a37487993c9f86397403e4e4ff0#b5fc2438028e6a37487993c9f86397403e4e4ff0" dependencies = [ "comline-codegen", "comline-core", @@ -549,13 +549,13 @@ dependencies = [ [[package]] name = "comline-core" version = "0.1.0" -source = "git+https://github.com/ComlineProject/core?rev=263e58378bb7efcaa466542ca644228ad14e2884#263e58378bb7efcaa466542ca644228ad14e2884" +source = "git+https://github.com/ComlineProject/core?rev=e2d68a5fa4ee20bb50392c259f732e2d0f2300ba#e2d68a5fa4ee20bb50392c259f732e2d0f2300ba" dependencies = [ "ariadne", "blake3", "chumsky", "ciborium", - "comline-catalog 0.10.0 (git+https://github.com/ComlineProject/specification?rev=068500670debade6b004b85032924f945dbb0a2c)", + "comline-catalog 0.11.0 (git+https://github.com/ComlineProject/specification?rev=69882e92971e243b6b74a539a13b534d95b3abf7)", "comline-core-stdlib", "downcast-rs", "eyre", @@ -579,12 +579,12 @@ dependencies = [ [[package]] name = "comline-core-stdlib" version = "0.1.0" -source = "git+https://github.com/ComlineProject/core?rev=263e58378bb7efcaa466542ca644228ad14e2884#263e58378bb7efcaa466542ca644228ad14e2884" +source = "git+https://github.com/ComlineProject/core?rev=e2d68a5fa4ee20bb50392c259f732e2d0f2300ba#e2d68a5fa4ee20bb50392c259f732e2d0f2300ba" [[package]] name = "comline-doc-html" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" +source = "git+https://github.com/ComlineProject/generation?rev=8e7dca84ed42f1b785fdb2470a2e94773e2fcef6#8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" dependencies = [ "comline-codegen", "eyre", @@ -595,7 +595,7 @@ dependencies = [ [[package]] name = "comline-doc-markdown" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" +source = "git+https://github.com/ComlineProject/generation?rev=8e7dca84ed42f1b785fdb2470a2e94773e2fcef6#8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" dependencies = [ "comline-codegen", "eyre", @@ -606,7 +606,7 @@ dependencies = [ [[package]] name = "comline-runtime" version = "0.1.0" -source = "git+https://github.com/ComlineProject/runtime?rev=3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51#3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51" +source = "git+https://github.com/ComlineProject/runtime?rev=8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d#8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d" dependencies = [ "bytemuck", "rmp", @@ -618,9 +618,9 @@ dependencies = [ [[package]] name = "comline-runtime-conformance" version = "0.1.0" -source = "git+https://github.com/ComlineProject/runtime?rev=3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51#3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51" +source = "git+https://github.com/ComlineProject/runtime?rev=8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d#8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d" dependencies = [ - "comline-catalog 0.10.0 (git+https://github.com/ComlineProject/runtime?rev=3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51)", + "comline-catalog 0.11.0 (git+https://github.com/ComlineProject/runtime?rev=8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d)", "comline-runtime", "serde", "serde_json", diff --git a/Cargo.toml b/Cargo.toml index e918b8c..72cfdbb 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -32,23 +32,23 @@ eyre = "0.6.8" # needs real I/O (git fetch, filesystem), so it's off by default for # `comline-core`'s wasm32 consumers (the playground editor, the language # server); the CLI is the one consumer that actually runs `comline build`. -comline-core = { git = "https://github.com/ComlineProject/core", rev = "263e58378bb7efcaa466542ca644228ad14e2884", features = ["deps"] } +comline-core = { git = "https://github.com/ComlineProject/core", rev = "e2d68a5fa4ee20bb50392c259f732e2d0f2300ba", features = ["deps"] } # All three pinned to revs that agree on one `comline-codegen`, and bumped # together: comline-rust and comline-typescript's codegen crates consume # `comline-codegen`'s types, so the rev below must be byte-identical to the # one *they* pin - Cargo only unifies a git dependency across identical rev # strings, and two copies of `GenRequest` are two incompatible types. -comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" } # The official Markdown and HTML documentation renderers (`comline doc`), # linked in like the official generators. Same generation rev as # `comline-codegen`. -comline-doc-markdown = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } -comline-doc-html = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } -comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "349763589f16fcee43a9b8bc3e2d9af8674fef00", optional = true } -comline-codegen-typescript = { git = "https://github.com/ComlineProject/comline-typescript", rev = "20bad456df0334b0197ddefdc1460f96c7ff33ae", optional = true } +comline-doc-markdown = { git = "https://github.com/ComlineProject/generation", rev = "8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" } +comline-doc-html = { git = "https://github.com/ComlineProject/generation", rev = "8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" } +comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "3e6864d31fa6e933d34dde186256be6ae2ad1ff9", optional = true } +comline-codegen-typescript = { git = "https://github.com/ComlineProject/comline-typescript", rev = "b5fc2438028e6a37487993c9f86397403e4e4ff0", optional = true } # `comline conformance`: the conformance runner (corpus loading, judging, # profile proofs) and its case format, a public spec. Pinned by git rev. -comline-runtime-conformance = { git = "https://github.com/ComlineProject/runtime", rev = "3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51" } +comline-runtime-conformance = { git = "https://github.com/ComlineProject/runtime", rev = "8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d" } # `comline doc open` / `--open`: the system's default handler for a file (a # browser for HTML). Exact pin; no default features (`reveal` pulls in D-Bus). opener = { version = "=0.9.0", default-features = false } diff --git a/docs/cli.md b/docs/cli.md index 6cb8a72..5b4db67 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -321,7 +321,7 @@ resolves to, with their parameters and where each came from: | `from @framing` / `from @handshake` | the protocol's own annotation | | `from config.idp ...` | the package's `wire.format`, `wire.framing` or `handshake` | | `core's default` | nothing named one: `packed@1`, `datagram@3`, `comline@2` (`comline@1` on any framing but `datagram@3`) | -| `JSON-RPC's format` | the framing is JSON-RPC and the package names no format | +| `JSON-RPC's format` | the framing implies a format (JSON-RPC's is JSON, and the line names the framing by its title) and the package names no format | Then one row per guarantee (schema agreement, encoding agreement, encoding conformance, version honesty), held or given up. A given-up row says why, and diff --git a/src/changes.rs b/src/changes.rs index ed04f8b..693f122 100644 --- a/src/changes.rs +++ b/src/changes.rs @@ -1,5 +1,6 @@ //! Rendering for `comline_core`'s [`SchemaChanges`], shared by `build` and `diff`. +use comline_core::package::build::cas::build::UnseenConfig; use comline_core::package::build::VersionBump; use comline_core::package::config::ir::diff::{ConfigChange, ConfigChanges}; use comline_core::schema::ir::diff::{BreakingChange, Modification, NewFeature, SchemaChanges}; @@ -50,6 +51,34 @@ pub fn render_config(changes: &ConfigChanges) { } } +/// Print the configs the comparison couldn't see, if any: they count as +/// changed, so they're why a build with nothing else to show still moves +/// the version. +pub fn render_unseen(unseen: &[UnseenConfig]) { + if unseen.is_empty() { + return; + } + ui::group(heading("❔", "Configs not compared", unseen.len())); + for config in unseen { + ui::detail(unseen_line(config)); + } +} + +fn unseen_line(config: &UnseenConfig) -> String { + let whose = match config { + UnseenConfig::Own => "The package's config".to_string(), + UnseenConfig::Dependency(name) => format!("Dependency `{name}`'s config"), + }; + mark( + "❔", + "?", + format!( + "{whose} isn't stored in an older build, so it counts as changed (at least a \ + patch); `comline build` stores it from now on" + ), + ) +} + fn config_line(change: &ConfigChange) -> String { let arrow = ui::arrow(); match change { @@ -494,3 +523,20 @@ fn modification_line(modification: &Modification) -> String { ), } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn an_unseen_config_says_it_counts_as_changed_and_how_it_stops() { + let own = unseen_line(&UnseenConfig::Own); + assert!(own.contains("The package's config isn't stored in an older build")); + assert!(own.contains("counts as changed (at least a patch)")); + assert!(own.contains("`comline build` stores it from now on")); + + let dependency = unseen_line(&UnseenConfig::Dependency("shared_types".into())); + assert!(dependency.contains("Dependency `shared_types`'s config isn't stored")); + assert!(dependency.contains("`comline build` stores it from now on")); + } +} diff --git a/src/commands/build.rs b/src/commands/build.rs index 186876d..98aaf8b 100644 --- a/src/commands/build.rs +++ b/src/commands/build.rs @@ -7,6 +7,7 @@ use std::path::Path; +use comline_core::package::build::cas::object_store::StoreError; use comline_core::package::build::cas::objects::Commit; use comline_core::package::build::cas::reconcile::{self, Heads}; use comline_core::package::build::cas::{main_ref, read_ref, ref_exists, Hash, ObjectStore}; @@ -17,6 +18,7 @@ use crate::bounds_migration; use crate::changes; use crate::commands::generation::generator_registry; use crate::commands::{core_err, ensure_project}; +use crate::error; use crate::lang_targets; use crate::ui; use crate::watch; @@ -116,6 +118,11 @@ fn build_once(work_dir: &Path, offer_migration: bool) -> Result<()> { let result = match result { Ok(result) => result, + // A store core refuses (another IR format, no stamp) is a + // precondition, reported as core words it, with nothing written. + Err(e) if e.downcast_ref::().is_some() => { + return Err(error::from_core("build failed", e)); + } Err(e) => { let detail = format!("{e:#}"); let unbounded = bounds_migration::Unbounded::of(&detail); @@ -164,7 +171,8 @@ fn build_once(work_dir: &Path, offer_migration: bool) -> Result<()> { .map(|c| !c.is_empty()) .unwrap_or(false) || !result.dependency_changes.is_empty() - || !result.config_changes.is_empty(); + || !result.config_changes.is_empty() + || !result.unseen.is_empty(); if !has_changes { ui::detail(pkg(format!( @@ -186,6 +194,7 @@ fn build_once(work_dir: &Path, offer_migration: bool) -> Result<()> { changes::render(&dependency.changes); } changes::render_config(&result.config_changes); + changes::render_unseen(&result.unseen); ui::detail(changes::bump_line(result.version_bump)); next_release_line(&result); diff --git a/src/commands/diff.rs b/src/commands/diff.rs index db54c50..855517a 100644 --- a/src/commands/diff.rs +++ b/src/commands/diff.rs @@ -47,6 +47,7 @@ pub fn run(work_dir: &Path, old: &str, new: &str) -> Result<()> { changes::render(&dependency.changes); } changes::render_config(&comparison.config_changes); + changes::render_unseen(&comparison.unseen); ui::detail(changes::bump_line(comparison.bump)); Ok(()) } diff --git a/src/commands/generation.rs b/src/commands/generation.rs index 74611a9..36b09cf 100644 --- a/src/commands/generation.rs +++ b/src/commands/generation.rs @@ -615,7 +615,7 @@ fn facts_for( } FactsSource::WorkingTree => comline_core::compat::facts_of_working_tree(work_dir, context), } - .map_err(|e| miette!("working out the package's facts: {e:#}"))?; + .map_err(|e| crate::error::from_core("working out the package's facts", e))?; // The same fields under the same names: the generator protocol's mirror. let facts = serde_json::to_value(&facts) @@ -628,9 +628,10 @@ fn facts_for( /// `async = true` changes only protocols on a connection; with none, the /// output is the same as without it, which looks like the setting did nothing. -/// Every protocol is on one by default, so that's a package whose protocols -/// are all lockstep: on the `datagram` framing, or on JSON-RPC with none of -/// them client-provided. +/// A protocol is on one by default when its framing's frames go both ways and +/// name the protocol, so that's a package whose protocols are all lockstep: +/// each on a framing that keeps it off a connection +/// ([`connections::why_lockstep`]), which the warning names. fn warn_async_unused(language: &str, request: &GenerateRequest) { if !request.async_api { return; @@ -641,14 +642,65 @@ fn warn_async_unused(language: &str, request: &GenerateRequest) { return; } + let lockstep: Vec = framings_in_use(request) + .iter() + .filter_map(|framing| lockstep_description(framing)) + .collect(); + + let why = if lockstep.is_empty() { + "the package has no protocols".to_owned() + } else { + format!( + "every protocol here is lockstep: on {}", + lockstep.join(" or ") + ) + }; + ui::warn(format!( "`{language}`: `async = true`, but no protocol runs on a connection, so the output \ - is the same as without it - every protocol here is lockstep: on the `datagram` \ - framing (the default, `datagram@3`, is a connection), or on JSON-RPC with none of \ - the package's JSON-RPC protocols client-provided" + is the same as without it - {why}" )); } +/// The framings the package's protocols are on, canonical (`jsonrpc`, +/// `datagram@2`, `com.acme.lines@1`), once each. +fn framings_in_use(request: &GenerateRequest) -> std::collections::BTreeSet { + let mut framings = std::collections::BTreeSet::new(); + for (_, units) in &request.schemas { + for unit in units { + if let FrozenUnit::Protocol { parameters, .. } = unit { + framings.insert(connections::framing_name(parameters)); + } + } + } + + framings +} + +/// A framing for a message about protocols that aren't on a connection: its +/// title, and why its protocols stay off one unless the client provides +/// them. `None` for a framing that has no such reason (its frames go both +/// ways and name the protocol), where a protocol is on a connection already. +fn lockstep_description(framing: &str) -> Option { + let reason = match connections::why_lockstep(framing)? { + connections::Lockstep::OneDirection => { + "its frames go one way, so the server can't call the client" + } + connections::Lockstep::UnnamedServerProvided => { + "its frames don't name the protocol, and none of its protocols is client-provided" + } + connections::Lockstep::Unknown => { + "a framing of the package's own: a protocol on it is on a connection only when \ + the client provides it" + } + }; + + Some(format!( + "{} ({reason})", + connections::framing_title(framing) + )) +} + /// The package's `serve` / `connect` need its protocols on one connection; /// when they disagree on the framing or handshake, the generators leave them /// out, which would otherwise look like they forgot. @@ -676,27 +728,17 @@ fn note_no_connection_protocols( request: &GenerateRequest, connections_doc: Option<&str>, ) { - let mut framings = std::collections::BTreeSet::new(); - for (_, units) in &request.schemas { - for unit in units { - if let FrozenUnit::Protocol { parameters, .. } = unit { - framings.insert(connections::framing_name(parameters)); - } - } - } + let framings = framings_in_use(request); if framings.is_empty() { return; } + // Each framing's title and why it keeps its protocols off a connection; + // one with no such reason (not expected here) is just its title. let framings: Vec = framings - .into_iter() - .map(|f| match f.as_str() { - "jsonrpc" => "JSON-RPC (with none of its protocols client-provided)".to_owned(), - // Canonical, `datagram` is the lockstep `datagram@1`. - "datagram" => "`datagram@1`".to_owned(), - _ => format!("`{f}`"), - }) + .iter() + .map(|f| lockstep_description(f).unwrap_or_else(|| connections::framing_title(f))) .collect(); let page = connections_doc diff --git a/src/commands/inspect.rs b/src/commands/inspect.rs index f5942e3..59a9ef1 100644 --- a/src/commands/inspect.rs +++ b/src/commands/inspect.rs @@ -10,6 +10,7 @@ use std::io::Write as _; use std::path::Path; use anstyle::{AnsiColor, Color, Style}; +use comline_codegen::connections; use comline_core::compat::{self, PackageFacts}; use comline_core::inspect::{self, Acceptance, Choice, ProtocolSummary, Source}; use miette::{IntoDiagnostic, Result}; @@ -198,7 +199,7 @@ pub fn render(p: &ProtocolSummary, plain: bool) -> String { out += &format!( " {key:<10} {:<24} {}\n", choice_value(choice), - style(DIM, &source(choice.source, key)) + style(DIM, &source(choice.source, key, &p.framing.value)) ); } let reason = p.guarantees.iter().find_map(|g| g.reason.as_deref()); @@ -251,8 +252,9 @@ fn choice_value(choice: &Choice) -> String { format!("{} ({})", choice.value, params.join(", ")) } -/// Where a choice came from, for the header. -fn source(source: Source, key: &str) -> String { +/// Where a choice came from, for the header. `framing` is the protocol's +/// framing, which a format it implies is named after. +fn source(source: Source, key: &str, framing: &str) -> String { match source { Source::Annotation => format!("from @{key}"), Source::PackageDefault => match key { @@ -260,6 +262,6 @@ fn source(source: Source, key: &str) -> String { _ => format!("from config.idp `wire.{key}`"), }, Source::CoreDefault => "core's default".to_string(), - Source::Framing => "JSON-RPC's format".to_string(), + Source::Framing => format!("{}'s format", connections::framing_title(framing)), } } diff --git a/src/commands/release.rs b/src/commands/release.rs index 2823ca8..a3689da 100644 --- a/src/commands/release.rs +++ b/src/commands/release.rs @@ -18,8 +18,8 @@ use miette::{IntoDiagnostic, Result}; use crate::changes; use crate::cli::ReleaseLevel as Level; -use crate::commands::{core_err, ensure_project}; -use crate::error::CliError; +use crate::commands::ensure_project; +use crate::error::{self, CliError}; use crate::history; use crate::ui; @@ -39,8 +39,9 @@ pub fn run( yes: bool, ) -> Result<()> { ensure_project(work_dir)?; - // `build` below would rebuild a mismatched store, dropping its history; - // a release is made on top of that history, so refuse instead. + // A store this comline can't read is refused here, before anything is + // built: `build` below refuses it too (core never rewrites a mismatched + // store), but a release is made on top of the history, so say so first. history::ensure_readable(work_dir)?; let stable = match version { None => false, @@ -62,7 +63,7 @@ pub fn run( let spinner = ui::spinner("compiling schemas"); let built = build::build(work_dir); ui::finish_spinner(spinner); - let built = built.map_err(|e| core_err("build failed", e))?; + let built = built.map_err(|e| error::from_core("build failed", e))?; for warning in built.context.rendered_warnings() { ui::warn(warning); } @@ -90,7 +91,7 @@ pub fn run( stable, }; let released = - build::release(work_dir, &request).map_err(|e| core_err("couldn't release", e))?; + build::release(work_dir, &request).map_err(|e| error::from_core("couldn't release", e))?; ui::success(format!("Released {}", released.version)); match &released.previous_release { @@ -103,6 +104,7 @@ pub fn run( ui::group(format!("In dependency `{}`:", dependency.name)); changes::render(&dependency.changes); } + changes::render_unseen(&changes.unseen); } let record = &released.record; if record.stable { diff --git a/src/error.rs b/src/error.rs index 3a75bd9..83b10a5 100644 --- a/src/error.rs +++ b/src/error.rs @@ -12,6 +12,7 @@ use std::path::PathBuf; +use comline_core::package::build::cas::object_store::StoreError; use miette::Diagnostic; use thiserror::Error; @@ -32,12 +33,16 @@ pub enum CliError { #[error("no builds found in `{}` — run `comline build` first", .0.display())] NothingBuilt(PathBuf), - #[error( - "the version history in `.comline/` is in IR format {found}, but this comline reads \ - and writes format {expected}: run `comline build` to rebuild it in the current format \ - (that starts the version history over)" - )] - StoreFormat { found: String, expected: u32 }, + /// The store in `.comline/` can't be used by this comline: another IR + /// format, no stamp, or a stamp that isn't one. Core's own message, + /// which says nothing was changed. No command changes the store to + /// resolve it; only an explicit `comline reset` deletes it. + #[error("{0}")] + #[diagnostic(help( + "no command changes `.comline/` to get past this. If you don't need the history, \ + `comline reset` deletes it (after asking, and keeping `.comline/deps-cache/`)" + ))] + Store(StoreError), #[error("refusing to delete the version history without confirmation")] #[diagnostic(help("re-run in a terminal to confirm, or pass `--force`"))] @@ -56,12 +61,24 @@ pub enum CliError { ReleaseConfirmationRequired { what: &'static str }, } +/// A `comline-core` error as the CLI reports it: a store core refused +/// ([`StoreError`], which core carries in the `eyre` report) becomes +/// [`CliError::Store`], a precondition (exit 2) with core's message +/// as it is; anything else is `context` plus the detail, as +/// [`crate::commands::core_err`] has it. +pub fn from_core(context: &str, e: eyre::Report) -> miette::Report { + match e.downcast_ref::() { + Some(store) => CliError::Store(store.clone()).into(), + None => crate::commands::core_err(context, e), + } +} + /// Map a finished-command error to its process exit code. pub fn exit_code_for(report: &miette::Report) -> i32 { match report.downcast_ref::() { Some(CliError::NotAProject(_)) => EXIT_PRECONDITION, Some(CliError::NothingBuilt(_)) => EXIT_PRECONDITION, - Some(CliError::StoreFormat { .. }) => EXIT_PRECONDITION, + Some(CliError::Store(_)) => EXIT_PRECONDITION, Some(CliError::ConfirmationRequired) => EXIT_PRECONDITION, Some(CliError::AcceptanceRequired { .. }) => EXIT_PRECONDITION, Some(CliError::ReleaseConfirmationRequired { .. }) => EXIT_PRECONDITION, diff --git a/src/history.rs b/src/history.rs index 8b0efb9..954150f 100644 --- a/src/history.rs +++ b/src/history.rs @@ -7,7 +7,7 @@ use std::path::Path; use crate::error::CliError; -use comline_core::package::build::cas::object_store::CURRENT_IR_FORMAT_VERSION; +use comline_core::package::build::cas::object_store::{ensure_compatible_store, StoreState}; use comline_core::package::build::cas::objects::{Commit, EntryMode, Tree}; use comline_core::package::build::cas::storage::Hash; use comline_core::package::build::cas::{refs, ObjectStore}; @@ -23,34 +23,23 @@ pub struct Entry { pub commit: Commit, } -/// Refuse to read a `.comline/` store written in another IR format. +/// Refuse to use a `.comline/` store this comline can't read or write. /// -/// The stamp (`.comline/FORMAT_VERSION`) says which format the store's -/// objects are in. `build` migrates a mismatched store by rebuilding it; -/// everything else only reads, and decoding another format's objects gives -/// garbage or a confusing decode error, so each read goes through this -/// first. [`load`] and [`open_store`] call it; a command that reads the -/// store some other way calls it directly. +/// The stamp (`.comline/FORMAT_VERSION`) says which IR format the store's +/// objects are in. Decoding another format's objects gives garbage or a +/// confusing decode error, so each read goes through this first, and a +/// store of another format is refused by every command, `build` included: +/// nothing here deletes, moves or rewrites it (core's +/// [`ensure_compatible_store`] is read-only). [`load`] and [`open_store`] +/// call it; a command that reads the store some other way calls it directly. /// /// No `.comline/`, or one with no stamp and no history, is "nothing built /// yet": fine here, and the caller reports it as it always did. pub fn ensure_readable(work_dir: &Path) -> Result<()> { - let comline = work_dir.join(".comline"); - if !comline.exists() { - return Ok(()); + match ensure_compatible_store(work_dir) { + Ok(StoreState::Fresh | StoreState::Current) => Ok(()), + Err(e) => Err(CliError::Store(e).into()), } - let stamp = std::fs::read_to_string(comline.join("FORMAT_VERSION")).ok(); - let found = match stamp.as_deref().map(str::trim) { - Some(text) if text.parse() == Ok(CURRENT_IR_FORMAT_VERSION) => return Ok(()), - Some(text) => format!("`{text}`"), - None if !refs::ref_exists(work_dir, refs::main_ref()) => return Ok(()), - None => "unstamped".to_string(), - }; - Err(CliError::StoreFormat { - found, - expected: CURRENT_IR_FORMAT_VERSION, - } - .into()) } /// The object store of `work_dir`, after [`ensure_readable`]. @@ -62,7 +51,7 @@ pub fn open_store(work_dir: &Path) -> Result { /// The whole commit chain for `work_dir`, newest-first. /// /// Errors with [`CliError::NothingBuilt`] if the project has never been built, -/// and with [`CliError::StoreFormat`] if its store is in another format. +/// and with [`CliError::Store`] if its store can't be used. pub fn load(work_dir: &Path) -> Result> { ensure_readable(work_dir)?; if !refs::ref_exists(work_dir, refs::main_ref()) { diff --git a/src/main.rs b/src/main.rs index 0bbe354..97a98e8 100644 --- a/src/main.rs +++ b/src/main.rs @@ -37,6 +37,10 @@ fn main() -> ExitCode { for cause in report.chain().skip(1) { ui::error(format!(" caused by: {cause}")); } + // A diagnostic's own advice (`#[diagnostic(help(...))]`), last. + if let Some(help) = report.help() { + ui::help(help.to_string()); + } ExitCode::from(code as u8) } } diff --git a/src/ui.rs b/src/ui.rs index e91867b..f199c38 100644 --- a/src/ui.rs +++ b/src/ui.rs @@ -186,6 +186,17 @@ pub fn warn(msg: impl AsRef) { } } +/// The help a fatal error carries (a diagnostic's `help`), under the error. +/// Always printed, even under `--quiet`, like the error it belongs to. +pub fn help(msg: impl AsRef) { + let msg = msg.as_ref(); + if plain() { + anstream::eprintln!("help: {msg}"); + } else { + anstream::eprintln!("{CYAN}help{CYAN:#} {msg}"); + } +} + /// A fatal error. Always printed, even under `--quiet`. pub fn error(msg: impl AsRef) { let msg = msg.as_ref(); diff --git a/tests/cli/generation.rs b/tests/cli/generation.rs index f265846..74f888f 100644 --- a/tests/cli/generation.rs +++ b/tests/cli/generation.rs @@ -317,8 +317,9 @@ fn protocols_on_no_connection_say_why_there_is_no_package_serve() { .stderr(predicate::str::contains( "no package `Services` / `serve` / `connect`", )) + // The framing's title in the catalog, and why it's lockstep. .stderr(predicate::str::contains( - "every protocol is server-provided on `datagram@1`", + "every protocol is server-provided on datagram (its frames go one way", )) .stderr(predicate::str::contains( "(https://comlineproject.github.io/docs/languages/rust/connections/#when-theyre-generated)", @@ -326,6 +327,34 @@ fn protocols_on_no_connection_say_why_there_is_no_package_serve() { assert!(!project.join("generated/rust/connection.rs").exists()); } +/// JSON-RPC's frames go both ways but don't name the protocol, so with no +/// protocol client-provided it's lockstep too: the note names its title and +/// that reason, not the framing's spelling in the schema. +#[test] +fn the_no_connection_note_gives_json_rpc_its_title_and_reason() { + let temp = tempfile::tempdir().unwrap(); + let project = fixture_project(temp.path()); + fs::write( + project.join("src/link.ids"), + "protocol Link {\n function send(n: u32) -> u32;\n}\n", + ) + .unwrap(); + add_to_config(&project, "wire = { framing = \"jsonrpc\" }"); + + comline_cmd() + .current_dir(&project) + .args(["generation", "--target", "rust"]) + .assert() + .success() + .stderr(predicate::str::contains( + "every protocol is server-provided on JSON-RPC (its frames don't name the protocol", + )) + .stderr(predicate::str::contains( + "none of its protocols is client-provided", + )) + .stderr(predicate::str::contains("and none is on a connection")); +} + /// The TypeScript generator names its own page too: the link comes from the /// generator, not from the language's name. #[test] @@ -984,14 +1013,31 @@ fn async_without_a_connection_protocol_warns() { fs::write(project.join("comline.toml"), "[generate]\nasync = true\n").unwrap(); let config = fs::read_to_string(project.join("config.idp")).unwrap(); - // Every protocol lockstep: nothing for `async` to change. + // Every protocol lockstep: nothing for `async` to change. The warning + // names the framing's title and why it keeps a protocol off a connection. add_to_config(&project, "wire = { framing = \"datagram\" }"); comline_cmd() .current_dir(&project) .args(["generation", "--target", "rust"]) .assert() .success() - .stderr(predicate::str::contains(warning)); + .stderr(predicate::str::contains(warning)) + .stderr(predicate::str::contains( + "every protocol here is lockstep: on datagram (its frames go one way", + )); + + // The same on JSON-RPC, whose frames don't name the protocol. + fs::write(project.join("config.idp"), &config).unwrap(); + add_to_config(&project, "wire = { framing = \"jsonrpc\" }"); + comline_cmd() + .current_dir(&project) + .args(["generation", "--target", "rust"]) + .assert() + .success() + .stderr(predicate::str::contains(warning)) + .stderr(predicate::str::contains( + "every protocol here is lockstep: on JSON-RPC (its frames don't name the protocol", + )); // The default: on a connection. fs::write(project.join("config.idp"), config).unwrap(); @@ -1011,7 +1057,8 @@ const LINES_PROFILE: &str = r#"{ "calls": { "value": "by_name", "proven_by": ["lines/request"] }, "directions": { "value": "both", "proven_by": ["lines/request"] }, "errors": { "value": "by_name", "proven_by": ["lines/error"] }, - "payload": { "value": "opaque", "proven_by": ["lines/request"] } + "payload": { "value": "opaque", "proven_by": ["lines/request"] }, + "protocol": { "value": "unnamed", "proven_by": ["lines/request"] } } }"#; diff --git a/tests/cli/store_stamp.rs b/tests/cli/store_stamp.rs index 227a14b..6981eb1 100644 --- a/tests/cli/store_stamp.rs +++ b/tests/cli/store_stamp.rs @@ -50,15 +50,42 @@ fn a_wrong_stamp_is_refused_by_every_read_command() { .failure() .code(2) .stderr(predicate::str::contains( - "the version history in `.comline/` is in IR format `1`, but this comline \ + "the version history in `.comline/` is in IR format 1, but this comline \ reads and writes format", )) - .stderr(predicate::str::contains("run `comline build`")); + .stderr(predicate::str::contains("Nothing was changed")); } // Refusing changed nothing. assert_eq!(fs::read_to_string(stamp(&project)).unwrap(), "1"); } +/// The store error carries help, which is printed after the message: what +/// the refusal leaves the person to do. +#[test] +fn the_store_error_shows_its_help_after_the_message() { + let temp = tempfile::tempdir().unwrap(); + let project = built_project(temp.path()); + fs::write(stamp(&project), "1").unwrap(); + + let output = comline_cmd() + .current_dir(&project) + .args(["--plain", "inspect"]) + .assert() + .failure() + .code(2) + .get_output() + .clone(); + let stderr = String::from_utf8_lossy(&output.stderr); + let (message, help) = stderr + .split_once("\nhelp: ") + .unwrap_or_else(|| panic!("no help line in {stderr}")); + assert!( + message.starts_with("error: the version history"), + "{stderr}" + ); + assert!(help.contains("`comline reset` deletes it"), "{stderr}"); +} + #[test] fn a_missing_stamp_with_history_is_refused() { let temp = tempfile::tempdir().unwrap(); @@ -72,26 +99,37 @@ fn a_missing_stamp_with_history_is_refused() { .assert() .failure() .code(2) - .stderr(predicate::str::contains("is in IR format unstamped")); + .stderr(predicate::str::contains("no `FORMAT_VERSION` stamp")); } } #[test] -fn build_migrates_a_wrong_stamp_and_reads_work_again() { +fn build_refuses_a_wrong_stamp_and_changes_nothing() { let temp = tempfile::tempdir().unwrap(); let project = built_project(temp.path()); fs::write(stamp(&project), "1").unwrap(); + let main_ref = project.join(".comline/refs/heads/main"); + let head = fs::read(&main_ref).unwrap(); + // `build` doesn't rebuild the store in the current format (that would + // delete its history): it refuses, like the readers do. comline_cmd() .current_dir(&project) .arg("build") .assert() - .success(); + .failure() + .code(2) + .stderr(predicate::str::contains("is in IR format 1")) + .stderr(predicate::str::contains("Nothing was changed")); + + assert_eq!(fs::read_to_string(stamp(&project)).unwrap(), "1"); + assert_eq!(fs::read(&main_ref).unwrap(), head); comline_cmd() .current_dir(&project) .args(["diff", "0.1.0-dev.1", "HEAD"]) .assert() - .success(); + .failure() + .code(2); } #[test] diff --git a/tests/fixtures/conformance/Cargo.lock b/tests/fixtures/conformance/Cargo.lock index b3ff5f2..9c92724 100644 --- a/tests/fixtures/conformance/Cargo.lock +++ b/tests/fixtures/conformance/Cargo.lock @@ -30,13 +30,13 @@ dependencies = [ [[package]] name = "comline-catalog" -version = "0.10.0" -source = "git+https://github.com/ComlineProject/runtime?rev=3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51#3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51" +version = "0.11.0" +source = "git+https://github.com/ComlineProject/runtime?rev=8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d#8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d" [[package]] name = "comline-reference" version = "0.1.0" -source = "git+https://github.com/ComlineProject/runtime?rev=3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51#3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51" +source = "git+https://github.com/ComlineProject/runtime?rev=8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d#8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d" dependencies = [ "comline-runtime", "comline-runtime-conformance", @@ -47,7 +47,7 @@ dependencies = [ [[package]] name = "comline-runtime" version = "0.1.0" -source = "git+https://github.com/ComlineProject/runtime?rev=3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51#3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51" +source = "git+https://github.com/ComlineProject/runtime?rev=8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d#8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d" dependencies = [ "bytemuck", "rmp", @@ -59,7 +59,7 @@ dependencies = [ [[package]] name = "comline-runtime-conformance" version = "0.1.0" -source = "git+https://github.com/ComlineProject/runtime?rev=3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51#3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51" +source = "git+https://github.com/ComlineProject/runtime?rev=8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d#8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d" dependencies = [ "comline-catalog", "comline-runtime", diff --git a/tests/fixtures/conformance/Cargo.toml b/tests/fixtures/conformance/Cargo.toml index 321d909..07a7ba4 100644 --- a/tests/fixtures/conformance/Cargo.toml +++ b/tests/fixtures/conformance/Cargo.toml @@ -12,5 +12,5 @@ publish = false [dependencies] # The runtime rev the CLI pins `comline-runtime-conformance` at, so the # reference answers as the vectors the CLI reads were blessed. -comline-reference = { git = "https://github.com/ComlineProject/runtime", rev = "3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51" } +comline-reference = { git = "https://github.com/ComlineProject/runtime", rev = "8f8c0cb6fb0bc3a734aafbdbbf187fb9da73e00d" } serde_json = "1.0" diff --git a/tests/fixtures/conformance_package/profiles/lines.json b/tests/fixtures/conformance_package/profiles/lines.json index 34f7b25..7139ca2 100644 --- a/tests/fixtures/conformance_package/profiles/lines.json +++ b/tests/fixtures/conformance_package/profiles/lines.json @@ -5,6 +5,7 @@ "calls": { "value": "by_name", "proven_by": ["lines/request"] }, "directions": { "value": "both", "proven_by": ["lines/request", "lines/ok", "lines/reject-ok-as-request", "lines/reject-request-as-ok"] }, "errors": { "value": "by_ordinal", "proven_by": ["lines/error"] }, - "payload": { "value": "opaque", "proven_by": ["lines/request-params-msgpack"] } + "payload": { "value": "opaque", "proven_by": ["lines/request-params-msgpack"] }, + "protocol": { "value": "unnamed", "proven_by": ["lines/request"] } } } diff --git a/tests/fixtures/generators/Cargo.lock b/tests/fixtures/generators/Cargo.lock index 97faf86..cbb0609 100644 --- a/tests/fixtures/generators/Cargo.lock +++ b/tests/fixtures/generators/Cargo.lock @@ -78,13 +78,13 @@ dependencies = [ [[package]] name = "comline-catalog" -version = "0.10.0" -source = "git+https://github.com/ComlineProject/specification?rev=068500670debade6b004b85032924f945dbb0a2c#068500670debade6b004b85032924f945dbb0a2c" +version = "0.11.0" +source = "git+https://github.com/ComlineProject/specification?rev=69882e92971e243b6b74a539a13b534d95b3abf7#69882e92971e243b6b74a539a13b534d95b3abf7" [[package]] name = "comline-codegen" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" +source = "git+https://github.com/ComlineProject/generation?rev=8e7dca84ed42f1b785fdb2470a2e94773e2fcef6#8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" dependencies = [ "comline-core", "eyre", @@ -98,7 +98,7 @@ dependencies = [ [[package]] name = "comline-codegen-rust" version = "0.1.0" -source = "git+https://github.com/ComlineProject/comline-rust?rev=349763589f16fcee43a9b8bc3e2d9af8674fef00#349763589f16fcee43a9b8bc3e2d9af8674fef00" +source = "git+https://github.com/ComlineProject/comline-rust?rev=3e6864d31fa6e933d34dde186256be6ae2ad1ff9#3e6864d31fa6e933d34dde186256be6ae2ad1ff9" dependencies = [ "comline-codegen", "comline-core", @@ -108,7 +108,7 @@ dependencies = [ [[package]] name = "comline-core" version = "0.1.0" -source = "git+https://github.com/ComlineProject/core?rev=263e58378bb7efcaa466542ca644228ad14e2884#263e58378bb7efcaa466542ca644228ad14e2884" +source = "git+https://github.com/ComlineProject/core?rev=e2d68a5fa4ee20bb50392c259f732e2d0f2300ba#e2d68a5fa4ee20bb50392c259f732e2d0f2300ba" dependencies = [ "blake3", "ciborium", @@ -126,12 +126,12 @@ dependencies = [ [[package]] name = "comline-core-stdlib" version = "0.1.0" -source = "git+https://github.com/ComlineProject/core?rev=263e58378bb7efcaa466542ca644228ad14e2884#263e58378bb7efcaa466542ca644228ad14e2884" +source = "git+https://github.com/ComlineProject/core?rev=e2d68a5fa4ee20bb50392c259f732e2d0f2300ba#e2d68a5fa4ee20bb50392c259f732e2d0f2300ba" [[package]] name = "comline-doc-html" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" +source = "git+https://github.com/ComlineProject/generation?rev=8e7dca84ed42f1b785fdb2470a2e94773e2fcef6#8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" dependencies = [ "comline-codegen", "eyre", @@ -142,7 +142,7 @@ dependencies = [ [[package]] name = "comline-doc-markdown" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" +source = "git+https://github.com/ComlineProject/generation?rev=8e7dca84ed42f1b785fdb2470a2e94773e2fcef6#8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" dependencies = [ "comline-codegen", "eyre", diff --git a/tests/fixtures/generators/Cargo.toml b/tests/fixtures/generators/Cargo.toml index 8bdd403..9e8604f 100644 --- a/tests/fixtures/generators/Cargo.toml +++ b/tests/fixtures/generators/Cargo.toml @@ -12,7 +12,7 @@ publish = false [dependencies] # The same revs the CLI pins, so the real generator's output is comparable # byte for byte with the CLI's built-in one. -comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } -comline-doc-markdown = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } -comline-doc-html = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } -comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "349763589f16fcee43a9b8bc3e2d9af8674fef00" } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" } +comline-doc-markdown = { git = "https://github.com/ComlineProject/generation", rev = "8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" } +comline-doc-html = { git = "https://github.com/ComlineProject/generation", rev = "8e7dca84ed42f1b785fdb2470a2e94773e2fcef6" } +comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "3e6864d31fa6e933d34dde186256be6ae2ad1ff9" }