From 83c4d3b313b6594229b5a6287d2019d470471c69 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Tue, 10 Nov 2026 03:45:23 +0800 Subject: [PATCH 1/2] unverified: a package says why once, for what its own settings give up config.idp takes an `unverified` key beside the settings that cause losses: handshake = "none" unverified = { schema_agreement = "the gateway pins schemas by contract" ... } or a plain reason, covering every package-scope cause. It's under the same gate as the annotation (annotations.unverified.allowed). It covers only a cause that comes from a package setting, and only for a protocol that takes that setting: one with its own @handshake or @framing isn't covered for what that gives up. A protocol is acknowledged for what its own marker covers and what the package covers for it, so an unmarked protocol whose losses are all covered compiles, and a keyed marker needn't list what the package covers. Anything else is the missing-marker and missing-guarantee errors as before. Keys are held to the catalog: a guarantee that doesn't allow package scope (bounded_size) is unverified::wrong-scope, naming the scopes it allows; unknown, repeated and reasonless entries are the protocol marker's errors; a keyed entry no protocol gives up through the package is unverified::not-given-up, a warning. The given-up set is frozen as before, and now also for a protocol the package covers without a marker. Each covered protocol also carries an `unverified_package` property: the package's reasons for the guarantees it covers for it. Nothing changes for one it covers nothing for. Reasons in diagnostics, inspect and dependency acceptance read it when the marker has none. The diff reports the property as a patch; the set decides the rest. comline-catalog moves to the specification rev with guarantee scopes. --- core/Cargo.toml | 2 +- core/src/inspect.rs | 3 +- .../package/config/ir/compiler/interpret.rs | 53 ++++- core/src/package/config/ir/frozen/mod.rs | 14 ++ .../package/config/ir/interpreter/freezing.rs | 32 +++ core/src/package/deps.rs | 30 +++ .../ir/compiler/settings/enforcement.rs | 21 ++ core/src/schema/ir/diff.rs | 6 +- core/src/schema/ir/unverified.rs | 189 +++++++++++++++- core/src/schema/ir/validation/validator.rs | 209 +++++++++++++++--- core/tests/package/unverified.rs | 208 +++++++++++++++++ schemas/doc-model.json | 2 +- 12 files changed, 716 insertions(+), 53 deletions(-) diff --git a/core/Cargo.toml b/core/Cargo.toml index 9fc037a..c013b1b 100644 --- a/core/Cargo.toml +++ b/core/Cargo.toml @@ -24,7 +24,7 @@ comline-core-stdlib = { path = "../core_stdlib", version = "0.1.0" } # The specification's catalog of shared names: guarantees, facts and their # values, the official encodings' aliases and frozen spellings. no_std and # dependency-free, so the IR-only build has it too. -comline-catalog = { git = "https://github.com/ComlineProject/specification", rev = "69d88327431275017ccce99fec43060467515a9f" } +comline-catalog = { git = "https://github.com/ComlineProject/specification", rev = "508f813c259afe07db20cf86bbe2f07028a4fbe0" } # General eyre = "0.6.8" diff --git a/core/src/inspect.rs b/core/src/inspect.rs index 7deaf3f..43e156e 100644 --- a/core/src/inspect.rs +++ b/core/src/inspect.rs @@ -118,7 +118,8 @@ pub struct GuaranteeRow { /// Empty when held. pub causes: Vec, /// The `@unverified` reason, when it's given up and the marker carries - /// one: the plain form's, or the keyed form's for this guarantee. + /// one: the plain form's, or the keyed form's for this guarantee. The + /// package's, where it acknowledges the guarantee and the marker has none. pub reason: Option, pub acceptance: Acceptance, } diff --git a/core/src/package/config/ir/compiler/interpret.rs b/core/src/package/config/ir/compiler/interpret.rs index b970b8e..fd3858e 100644 --- a/core/src/package/config/ir/compiler/interpret.rs +++ b/core/src/package/config/ir/compiler/interpret.rs @@ -55,6 +55,14 @@ pub fn interpret_context(project_context: &ProjectContext) -> Result<()> { .collect(); let wire = PackageWire::of(own_config, own_protocols.iter().map(Vec::as_slice)); check_package_encodings(project_context, own_format.as_deref(), &wire.framing, &wire.handshake)?; + // What the package says of what its own settings give up, for every + // protocol that takes them. + let package_unverified = crate::package::config::ir::frozen::unverified(own_config); + if let Some(package_unverified) = package_unverified { + check_package_unverified(package_unverified, &own_settings)?; + } + let mut package_covered = vec![]; + let mut first_own: Option>> = None; // Package-level (`.idp`) settings origins aren't span-tracked yet // (only schema-level `settings { ... }` blocks are) - a malformed // package-level value falls back to usage-site-only diagnostics, same @@ -136,11 +144,17 @@ pub fn interpret_context(project_context: &ProjectContext) -> Result<()> { // Inject Namespace unit let namespace_joined = schema_context.borrow().namespace_joined(); frozen_units.insert(0, FrozenUnit::Namespace(namespace_joined.clone())); + // What each protocol takes from the package is read before the + // package's handshake is frozen in, which makes it look its own. + let inherits = crate::schema::ir::unverified::inherits(&frozen_units); wire.freeze_handshake(&mut frozen_units); - crate::schema::ir::unverified::freeze( + crate::schema::ir::unverified::freeze_with( &mut frozen_units, &crate::schema::ir::unverified::Encodings::of(project_context), + package_unverified, + &inherits, ); + package_covered.extend(crate::schema::ir::unverified::package_covered_by(&frozen_units)); // Settings gate what the schema's author wrote; the package's // framing is the package's choice, so it's added after the snapshot // enforcement checks. @@ -248,6 +262,21 @@ pub fn interpret_context(project_context: &ProjectContext) -> Result<()> { *schema_context.borrow().frozen_schema.borrow_mut() = Some(frozen_units); schema_context.borrow().compile_state.borrow_mut().complete = true; + first_own.get_or_insert_with(|| schema_context.clone()); + } + + // The package's `unverified` lists what none of its protocols give up + // through its settings: a warning, on the first schema it compiled, as it + // has no schema of its own to be on. + if let (Some(package_unverified), Some(first), true) = (package_unverified, &first_own, schema_errors.is_empty()) { + package_covered.sort(); + package_covered.dedup(); + let unused = validation::validator::check_package_unverified_used(package_unverified, &package_covered); + let frozen = first.borrow().frozen_schema.borrow().clone().unwrap_or_default(); + let (warnings, fatal) = + resolve_diagnostic_overrides(&frozen, unused, &own_settings, &package_settings_spans); + first.borrow().warnings.borrow_mut().extend(warnings); + schema_errors.extend(fatal.iter().map(|d| crate::diagnostics::render(d, "config.idp", ""))); } if !schema_errors.is_empty() { @@ -282,6 +311,28 @@ fn check_package_encodings( Ok(()) } +/// The package's `unverified`, judged without its protocols: allowed by the +/// package's settings as `@unverified` is, and its keys and reasons sound. +fn check_package_unverified( + package_unverified: &crate::schema::ir::frozen::unit::ConfigValue, + package_settings: &crate::settings::SettingsDict, +) -> Result<()> { + let mut problems = crate::schema::ir::compiler::settings::enforcement::check_package_annotation( + "unverified", + package_settings, + &crate::settings::SettingsSpans::default(), + "config.idp's `unverified` is held to the same gate as `@unverified`", + ) + .err() + .unwrap_or_default(); + problems.extend(validation::validator::check_package_unverified(package_unverified)); + if problems.is_empty() { + return Ok(()); + } + let rendered: Vec = problems.iter().map(|d| crate::diagnostics::render(d, "config.idp", "")).collect(); + bail!("config.idp's `unverified` is invalid:\n{}", rendered.join("\n\n")) +} + /// Whether `name`, as a schema with these `declarations` uses it, is a /// type another schema declares that holds a value without a maximum /// ([`SchemaContext::unbounded`]). Every schema a `use` could bring it in diff --git a/core/src/package/config/ir/frozen/mod.rs b/core/src/package/config/ir/frozen/mod.rs index 10b9be4..8b55d5c 100644 --- a/core/src/package/config/ir/frozen/mod.rs +++ b/core/src/package/config/ir/frozen/mod.rs @@ -94,6 +94,12 @@ pub enum FrozenUnit { #[serde(default, skip_serializing_if = "Option::is_none")] directions: Option, }, + /// `unverified = ...`: why the package gives up what its own settings + /// give up, once for every protocol that takes them: a reason, or a + /// dictionary with one per guarantee, as `@unverified` takes. Frozen as + /// written, the keys unchecked; `schema::ir::unverified` and the compiler + /// judge it. Absent when the package says nothing. + Unverified(crate::schema::ir::frozen::unit::ConfigValue), } #[derive(Deserialize, Serialize)] @@ -226,6 +232,14 @@ pub fn handshake_params(units: &[FrozenUnit]) -> BTreeMap { .unwrap_or_default() } +/// The package's `unverified`, as written, if it says one. +pub fn unverified(units: &[FrozenUnit]) -> Option<&crate::schema::ir::frozen::unit::ConfigValue> { + units.iter().find_map(|unit| match unit { + FrozenUnit::Unverified(value) => Some(value), + _ => None, + }) +} + /// The package's declared `wire` entries, `(format, framing)`, as written /// (canonical). `None` for one it leaves out. /// The package's `id`, if its config declares one. diff --git a/core/src/package/config/ir/interpreter/freezing.rs b/core/src/package/config/ir/interpreter/freezing.rs index 713bd95..feb6c16 100644 --- a/core/src/package/config/ir/interpreter/freezing.rs +++ b/core/src/package/config/ir/interpreter/freezing.rs @@ -11,6 +11,7 @@ use crate::package::config::ir::frozen::{ // External Uses use comline_catalog::fact; +use crate::schema::ir::frozen::unit::ConfigValue; use crate::schema::ir::compiler::settings::conformance::check_settings_conformance; #[allow(unused)] @@ -164,6 +165,7 @@ pub fn interpret_assignment( } } } + "unverified" => vec![FrozenUnit::Unverified(interpret_assignment_unverified(&node.value)?)], "wire" => { let Value::Dictionary(items) = &node.value else { return Err("'wire' should be a dictionary, like \ @@ -226,6 +228,36 @@ fn interpret_assignment_handshake( Ok(units) } +/// `unverified = "..."` or `unverified = { schema_agreement = "..." }`: frozen +/// as `@unverified` freezes, a reason or a dictionary of them. What the keys +/// and reasons say is judged where the guarantees are known, so an entry that +/// isn't a string is kept for that to report, not refused here. +fn interpret_assignment_unverified(value: &Value) -> Result> { + use crate::package::config::dependency::strip_quotes; + + match value { + Value::String(reason) => Ok(ConfigValue::Str(strip_quotes(&reason.value))), + Value::Dictionary(items) => { + let entries = items.assignments.iter().map(|assignment| { + let assignment = &assignment.value; + let value = match &assignment.value { + Value::String(reason) => ConfigValue::Str(strip_quotes(&reason.value)), + Value::Boolean(BooleanLiteral::True) => ConfigValue::Bool(true), + Value::Boolean(BooleanLiteral::False) => ConfigValue::Bool(false), + Value::Number(n) => n.value.parse().map(ConfigValue::Integer).unwrap_or(ConfigValue::Marker), + Value::Identifier(name) => ConfigValue::Name(name.value.clone()), + _ => ConfigValue::Marker, + }; + (assignment.key.text(), value) + }); + Ok(ConfigValue::Dict(entries.collect())) + } + _ => Err("'unverified' should be a reason, like \"the gateway pins schemas by contract\", or a \ + dictionary with one for each guarantee, like { schema_agreement = \"...\" }" + .into()), + } +} + /// `wire = { format = "...", framing = "..." }`: both entries optional, /// each folded onto its canonical name. fn interpret_assignment_wire( diff --git a/core/src/package/deps.rs b/core/src/package/deps.rs index 4a36b3b..322fef1 100644 --- a/core/src/package/deps.rs +++ b/core/src/package/deps.rs @@ -770,6 +770,36 @@ mod tests { .expect("accepted for its whole set"); } + #[test] + fn the_acceptance_shows_the_reasons_the_package_gave() { + let tmp = tempfile::tempdir().unwrap(); + let dir = tmp.path().join("billing"); + std::fs::create_dir_all(dir.join("src")).unwrap(); + std::fs::write( + dir.join("config.idp"), + "congregation billing\nspecification_version = 1\nhandshake = \"none\"\n\ + unverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n \ + encoding_agreement = \"the gateway only speaks one encoding\"\n}\n\ + settings = { annotations = { unverified = { allowed = true } } }\n", + ) + .unwrap(); + // No marker of its own: the package says why. + std::fs::write(dir.join("src/api.ids"), "protocol Billing {\n function charge();\n}\n").unwrap(); + let cache = tmp.path().join("cache"); + + let err = resolve(&path_dep("billing", "billing", None), tmp.path(), &cache).map(|_| ()).unwrap_err().to_string(); + assert!(err.contains("protocol `Billing` is unverified, giving up schema agreement and encoding agreement"), "{err}"); + assert!( + err.contains( + "schema agreement \"the gateway pins schemas by contract\", \ + encoding agreement \"the gateway only speaks one encoding\"" + ), + "{err}" + ); + resolve(&accepting(&[Guarantee::SchemaAgreement, Guarantee::EncodingAgreement]), tmp.path(), &cache) + .expect("accepted for its whole set"); + } + #[test] fn a_consumer_judges_a_dependencys_schemas_by_the_dependencys_own_package() { use crate::schema::ir::frozen::unit::FrozenUnit; diff --git a/core/src/schema/ir/compiler/settings/enforcement.rs b/core/src/schema/ir/compiler/settings/enforcement.rs index fc204d1..fa9b4cb 100644 --- a/core/src/schema/ir/compiler/settings/enforcement.rs +++ b/core/src/schema/ir/compiler/settings/enforcement.rs @@ -81,6 +81,24 @@ pub fn check_settings_enforcement( if errors.is_empty() { Ok(()) } else { Err(errors) } } +/// A package-level use of an annotation's name, such as `config.idp`'s +/// `unverified`, held to the gate the annotation is under on a protocol: +/// what the package's settings say of `annotations..allowed`. `label` +/// says what's using it. +pub fn check_package_annotation( + name: &str, + package_settings: &SettingsDict, + package_spans: &SettingsSpans, + label: &str, +) -> Result<(), Vec> { + let mut errors = Vec::new(); + check_governed( + keys::annotations_allowed(), package_settings, package_spans, DeclPath::Protocol, name, + label, None, &mut errors, + ); + if errors.is_empty() { Ok(()) } else { Err(errors) } +} + fn check_field( schema_effective: &SettingsDict, schema_effective_spans: &SettingsSpans, @@ -136,6 +154,9 @@ fn check_declaration( match param { // The preset selector itself, not a policy-governed feature. FrozenUnit::Property { name, .. } if name == "settings" => {} + // Written by the compiler for what the package's `unverified` + // covers, which is gated where the package says it. + FrozenUnit::Property { name, .. } if name == crate::schema::ir::unverified::PACKAGE_KEY => {} FrozenUnit::Property { name, .. } => { check_governed( keys::annotations_allowed(), &effective, &effective_spans, decl, name, diff --git a/core/src/schema/ir/diff.rs b/core/src/schema/ir/diff.rs index 4feaf91..a054bd9 100644 --- a/core/src/schema/ir/diff.rs +++ b/core/src/schema/ir/diff.rs @@ -1856,7 +1856,11 @@ fn compare_parameters_with( // A wire number: judged by `compare_id`, which knows the framing. "id" => {} // Adding or removing the marker is judged by the set it freezes, - // below; only a reworded reason is reported here. + // below; only a reworded reason is reported here. What the + // package's `unverified` says for the protocol (`unverified_package`) + // is reported whenever it changes, and as a patch: the reason + // moving between the package and the marker, or being reworded, + // changes nothing a peer sees, and what's given up is judged below. "unverified" if old_value.is_none() || new_value.is_none() => {} // A depth limit is a bound: raising it breaks old receivers, // lowering it old senders. diff --git a/core/src/schema/ir/unverified.rs b/core/src/schema/ir/unverified.rs index 222e659..c558a75 100644 --- a/core/src/schema/ir/unverified.rs +++ b/core/src/schema/ir/unverified.rs @@ -28,6 +28,18 @@ //! which has to say every guarantee the protocol gives up. Either way the //! frozen set is the one core works out; a keyed form's reasons stay in the //! frozen annotation. +//! +//! **At package scope.** What a package's settings give up, every protocol +//! that takes them gives up too, so the package can say why once: an +//! `unverified` key in `config.idp`, a reason or, keyed, one per guarantee +//! (`unverified = { schema_agreement = "..." }`), under the same gate as the +//! annotation. It covers only a cause that comes from a package setting, and +//! only for a protocol that takes that setting rather than writing its own +//! (`@handshake`, `@framing`): [`Inherits`]. A guarantee the catalog doesn't +//! give package scope (`bounded_size`) is never covered. A protocol is +//! acknowledged for what its own marker covers and what the package covers +//! for it; the latter is frozen with it, restricted to those guarantees +//! ([`PACKAGE_KEY`]), and the given-up set is still the one core works out. use crate::encodings::{official, EncodingKind}; use crate::package::config::ir::frozen::FrozenUnit as ConfigUnit; @@ -38,6 +50,23 @@ use comline_catalog::fact; /// The annotation key. pub const KEY: &str = "unverified"; +/// The property a protocol the package's `unverified` covers carries, written +/// by the compiler beside the given-up set: the package's reasons, as a +/// dictionary from guarantee to reason, for the guarantees it covers for that +/// protocol. A protocol it covers nothing for has none. +pub const PACKAGE_KEY: &str = "unverified_package"; + +/// What a protocol takes from the package's settings rather than writing +/// itself, decided before the package's handshake and framing are frozen into +/// it ([`inherits`]): once they are, they read as the protocol's own. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct Inherits { + /// It writes no `@handshake`: the package's, or its default, applies. + pub handshake: bool, + /// It writes no `@framing`: the package's, or its default, applies. + pub framing: bool, +} + /// What the guarantee check reads besides a protocol's own parameters: the /// encoding declarations it can see (the package's own and its /// dependencies'; the official ones are always seen), and the package's @@ -201,10 +230,27 @@ pub fn framing<'a>(parameters: &'a [FrozenUnit], encodings: &Encodings<'a>) -> & .unwrap_or(IMPLICIT_FRAMING) } +/// One reason a guarantee is given up. +struct Cause { + guarantee: Guarantee, + why: String, + /// Whether it comes from a package setting the protocol takes, which the + /// package can acknowledge, and not from something the protocol writes. + package: bool, +} + /// The guarantees a protocol with these parameters gives up, whether or not /// it's marked, each with why. Sorted by guarantee; a guarantee may appear /// once per cause. pub fn causes(parameters: &[FrozenUnit], encodings: &Encodings) -> Vec<(Guarantee, String)> { + causes_from(parameters, encodings, Inherits::default()).into_iter().map(|c| (c.guarantee, c.why)).collect() +} + +/// [`causes`], each with whether it comes from a package setting +/// `inherits` says the protocol takes. The handshake's, and the same +/// handshake's policies, come from it; the format is only ever the package's; +/// the framing's, from it. +fn causes_from(parameters: &[FrozenUnit], encodings: &Encodings, inherits: Inherits) -> Vec { let mut causes = vec![]; let handshake = handshake(parameters); @@ -225,17 +271,21 @@ pub fn causes(parameters: &[FrozenUnit], encodings: &Encodings) -> Vec<(Guarante } else { format!("handshake `{handshake}` doesn't establish it") }; - causes.push((guarantee, why)); + causes.push(Cause { guarantee, why, package: inherits.handshake }); } } if annotations::HandshakeValue::of_protocol(parameters).param("same_version_differs") == Some("warn") { - causes.push((Guarantee::VersionHonesty, format!("handshake `{handshake}` with `same_version_differs = warn`"))); + let why = format!("handshake `{handshake}` with `same_version_differs = warn`"); + causes.push(Cause { guarantee: Guarantee::VersionHonesty, why, package: inherits.handshake }); } let format = encodings.format.unwrap_or(DEFAULT_FORMAT); let framing = framing(parameters, encodings); - for (kind, name) in [(EncodingKind::Format, format), (EncodingKind::Framing, framing)] { + for (kind, name, package) in [ + (EncodingKind::Format, format, true), + (EncodingKind::Framing, framing, inherits.framing), + ] { if official::resolve(kind, name).is_some() { continue; } @@ -245,14 +295,15 @@ pub fn causes(parameters: &[FrozenUnit], encodings: &Encodings) -> Vec<(Guarante Some(_) => false, }; if !has_vectors { - causes.push(( - Guarantee::EncodingConformance, - format!("{} `{name}` ships no conformance vectors", kind.as_str()), - )); + causes.push(Cause { + guarantee: Guarantee::EncodingConformance, + why: format!("{} `{name}` ships no conformance vectors", kind.as_str()), + package, + }); } } - causes.sort_by_key(|(guarantee, _)| *guarantee); + causes.sort_by_key(|cause| cause.guarantee); causes } @@ -306,9 +357,19 @@ pub fn reason(parameters: &[FrozenUnit]) -> Option<&str> { } /// Why `guarantee` is given up, as the author wrote it: the plain form's -/// reason, or the keyed form's entry for it. +/// reason, or the keyed form's entry for it. A guarantee the marker doesn't +/// say is the package's reason for it, where the package acknowledges it for +/// this protocol ([`package_reason_for`]). pub fn reason_for(parameters: &[FrozenUnit], guarantee: Guarantee) -> Option<&str> { - match marker(parameters)? { + marker(parameters) + .and_then(|marker| reason_in(marker, guarantee)) + .or_else(|| package_reason_for(parameters, guarantee)) +} + +/// `guarantee`'s reason in an acknowledgement as written: the plain form's, or +/// the keyed form's entry for it. +fn reason_in(value: &ConfigValue, guarantee: Guarantee) -> Option<&str> { + match value { ConfigValue::Str(reason) => Some(reason), ConfigValue::Dict(entries) => entries.iter().find_map(|(key, value)| match value { ConfigValue::Str(reason) if key == guarantee.name() => Some(reason.as_str()), @@ -318,6 +379,21 @@ pub fn reason_for(parameters: &[FrozenUnit], guarantee: Guarantee) -> Option<&st } } +/// What the package's `unverified` covers for this protocol, as frozen +/// ([`PACKAGE_KEY`]): a dictionary from guarantee to reason. +pub fn package_scope(parameters: &[FrozenUnit]) -> Option<&ConfigValue> { + parameters.iter().find_map(|p| match p { + FrozenUnit::Property { name, value } if name == PACKAGE_KEY => Some(value), + _ => None, + }) +} + +/// The package's reason for `guarantee` for this protocol, if its `unverified` +/// covers it there. +pub fn package_reason_for(parameters: &[FrozenUnit], guarantee: Guarantee) -> Option<&str> { + package_scope(parameters).and_then(|scope| reason_in(scope, guarantee)) +} + /// The reason for a diagnostic or an acceptance prompt about `set`: the plain /// form's, quoted, or the keyed form's, each guarantee with its own /// (`schema agreement "a", encoding agreement "b"`). @@ -344,23 +420,112 @@ pub fn frozen_set(parameters: &[FrozenUnit]) -> &[Guarantee] { .unwrap_or(&[]) } +/// For each protocol in `units`, in order, what it takes from the package +/// ([`Inherits`]). Asked of the schema's units as written, before the +/// package's handshake and framing are frozen into them +/// ([`PackageWire`](crate::schema::ir::package_wire::PackageWire)). +pub fn inherits(units: &[FrozenUnit]) -> Vec { + let writes = |parameters: &[FrozenUnit], key: &str| { + parameters.iter().any(|p| matches!(p, FrozenUnit::Property { name, .. } if name == key)) + }; + units + .iter() + .filter_map(|unit| match unit { + FrozenUnit::Protocol { parameters, .. } => Some(Inherits { + handshake: !writes(parameters, "handshake"), + framing: !writes(parameters, "framing"), + }), + _ => None, + }) + .collect() +} + +/// What the package's acknowledgement `package` covers for a protocol with +/// these parameters: each guarantee given up, every cause of which comes from +/// a package setting the protocol takes, and which `package` says a reason +/// for. Sorted by guarantee. +pub fn package_covered( + parameters: &[FrozenUnit], + encodings: &Encodings, + inherits: Inherits, + package: &ConfigValue, +) -> Vec<(Guarantee, String)> { + let causes = causes_from(parameters, encodings, inherits); + let mut covered: Vec<(Guarantee, String)> = vec![]; + for Cause { guarantee, .. } in &causes { + let from_package = causes.iter().filter(|c| c.guarantee == *guarantee).all(|c| c.package); + if !from_package || covered.iter().any(|(g, _)| g == guarantee) { + continue; + } + if let Some(reason) = reason_in(package, *guarantee) { + covered.push((*guarantee, reason.to_string())); + } + } + covered +} + +/// Every guarantee the package covers for some protocol in `units`. +pub fn package_covered_by(units: &[FrozenUnit]) -> Vec { + let mut covered = vec![]; + for unit in units { + if let FrozenUnit::Protocol { parameters, .. } = unit { + covered.extend(Guarantee::ALL.into_iter().filter(|g| package_reason_for(parameters, *g).is_some())); + } + } + covered.sort(); + covered.dedup(); + covered +} + /// Freeze the given-up set beside every marked protocol's `@unverified`. /// Run once the protocol's parameters are final (after the package's /// default handshake is applied). An unmarked protocol gets nothing: giving /// something up without the marker is a validation error, not a freeze. pub fn freeze(units: &mut [FrozenUnit], encodings: &Encodings) { + freeze_with(units, encodings, None, &[]); +} + +/// [`freeze`], for a package whose `config.idp` says `package` (its +/// `unverified`). A protocol the package covers something for is frozen like a +/// marked one, its set beside [`PACKAGE_KEY`] holding the package's reasons +/// for what it covers. `inherits` is [`inherits`] of the same units, taken +/// before the package's wire was frozen in; without it nothing is the +/// package's to cover. A `PACKAGE_KEY` the schema wrote itself is dropped: +/// only the compiler says what the package covers. +pub fn freeze_with( + units: &mut [FrozenUnit], + encodings: &Encodings, + package: Option<&ConfigValue>, + inherits: &[Inherits], +) { + let mut inherits = inherits.iter(); for unit in units { let FrozenUnit::Protocol { parameters, .. } = unit else { continue; }; - parameters.retain(|p| !matches!(p, FrozenUnit::Unverified(_))); - if marker(parameters).is_none() { + let inherited = inherits.next().copied().unwrap_or_default(); + parameters.retain(|p| { + !matches!(p, FrozenUnit::Unverified(_)) + && !matches!(p, FrozenUnit::Property { name, .. } if name == PACKAGE_KEY) + }); + let covered = match package { + Some(package) => package_covered(parameters, encodings, inherited, package), + None => vec![], + }; + if marker(parameters).is_none() && covered.is_empty() { continue; } let set = given_up(parameters, encodings); if !set.is_empty() { parameters.push(FrozenUnit::Unverified(set)); } + if !covered.is_empty() { + let reasons = covered.into_iter().map(|(g, reason)| (g.name().to_string(), ConfigValue::Str(reason))); + parameters.push(FrozenUnit::Property { + name: PACKAGE_KEY.to_string(), + value: ConfigValue::Dict(reasons.collect()), + }); + } } } diff --git a/core/src/schema/ir/validation/validator.rs b/core/src/schema/ir/validation/validator.rs index 328aeb0..d40e948 100644 --- a/core/src/schema/ir/validation/validator.rs +++ b/core/src/schema/ir/validation/validator.rs @@ -90,6 +90,8 @@ const UNVERIFIED_DUPLICATE_GUARANTEE: DiagnosticCode = DiagnosticCode::error("unverified::duplicate-guarantee"); const UNVERIFIED_MISSING_GUARANTEE: DiagnosticCode = DiagnosticCode::error("unverified::missing-guarantee"); +const UNVERIFIED_WRONG_SCOPE: DiagnosticCode = + DiagnosticCode::error("unverified::wrong-scope"); const UNVERIFIED_NOT_GIVEN_UP: DiagnosticCode = DiagnosticCode::warning("unverified::not-given-up"); const UNVERIFIED_NOTHING_GIVEN_UP: DiagnosticCode = @@ -1335,14 +1337,35 @@ fn check_unverified( given_up.push(Guarantee::BoundedSize); } let cause = unverified::cause(parameters, encodings); + let why = |guarantee: Guarantee| match guarantee { + Guarantee::BoundedSize => "a string, list or nesting it reaches has no maximum".to_string(), + _ => unverified::cause_of(parameters, encodings, guarantee), + }; + // What the package's `unverified` already says why of, for this + // protocol: frozen beside it, only for what comes from a package + // setting it takes. + let by_package = |guarantee: &Guarantee| unverified::package_reason_for(parameters, *guarantee).is_some(); let Some(marker) = unverified::marker(parameters) else { - if !given_up.is_empty() { + let uncovered: Vec = given_up.iter().copied().filter(|g| !by_package(g)).collect(); + if !uncovered.is_empty() { + let cause = if uncovered.len() == given_up.len() { + cause + } else { + let mut why_not: Vec = vec![]; + for guarantee in &uncovered { + let one = why(*guarantee); + if !why_not.contains(&one) { + why_not.push(one); + } + } + why_not.join("; ") + }; errors.push( Diagnostic::new( UNVERIFIED_MISSING_MARKER, format!( "protocol `{name}` gives up {} ({cause}) without `@unverified`", - unverified::describe(&given_up) + unverified::describe(&uncovered) ), ) .with_help( @@ -1352,6 +1375,8 @@ fn check_unverified( ) .maybe_span(Some(*span)), ); + } else { + give_up_warnings(name, *span, &given_up, &why, warnings); } continue; }; @@ -1365,26 +1390,13 @@ fn check_unverified( .maybe_span(Some(*span)), ); } - let why = |guarantee: Guarantee| match guarantee { - Guarantee::BoundedSize => "a string, list or nesting it reaches has no maximum".to_string(), - _ => unverified::cause_of(parameters, encodings, guarantee), - }; // The keyed form: a reason for every guarantee given up, and only // those, under a guarantee's id. if let ConfigValue::Dict(entries) = marker { let mut listed: Vec = vec![]; for (key, value) in entries { let Some(guarantee) = Guarantee::from_name(key) else { - let mut message = format!("`@unverified` on protocol `{name}`: `{key}` isn't a guarantee"); - if let Some(s) = closest(key, Guarantee::ALL.iter().map(|g| g.name())) { - message.push_str(&format!(" - did you mean `{s}`?")); - } - let known: Vec = Guarantee::ALL.iter().map(|g| format!("`{}`", g.name())).collect(); - errors.push( - Diagnostic::new(UNVERIFIED_UNKNOWN_GUARANTEE, message) - .with_help(format!("the guarantees are {}", known.join(", "))) - .maybe_span(Some(*span)), - ); + errors.push(unknown_guarantee(&format!("`@unverified` on protocol `{name}`"), key).maybe_span(Some(*span))); continue; }; if listed.contains(&guarantee) { @@ -1409,7 +1421,7 @@ fn check_unverified( ); } } - for guarantee in given_up.iter().filter(|g| !listed.contains(g)) { + for guarantee in given_up.iter().filter(|g| !listed.contains(g) && !by_package(g)) { errors.push( Diagnostic::new( UNVERIFIED_MISSING_GUARANTEE, @@ -1447,27 +1459,152 @@ fn check_unverified( .maybe_span(Some(*span)), ); } - for guarantee in given_up { - let code = match guarantee { - Guarantee::SchemaAgreement => UNVERIFIED_SCHEMA_AGREEMENT, - Guarantee::EncodingAgreement => UNVERIFIED_ENCODING_AGREEMENT, - Guarantee::EncodingConformance => UNVERIFIED_ENCODING_CONFORMANCE, - Guarantee::VersionHonesty => UNVERIFIED_VERSION_HONESTY, - Guarantee::BoundedSize => UNVERIFIED_BOUNDED_SIZE, - }; - warnings.push( - Diagnostic::new( - code, - format!( - "protocol `{name}` is unverified: {} isn't established ({})", - guarantee.describe(), - why(guarantee) - ), - ) - .maybe_span(Some(*span)), - ); + give_up_warnings(name, *span, &given_up, &why, warnings); + } +} + +/// One informational warning for each guarantee a protocol gives up, each +/// with a code of its own. +fn give_up_warnings( + name: &str, + span: (usize, usize), + given_up: &[crate::schema::ir::frozen::unit::Guarantee], + why: &dyn Fn(crate::schema::ir::frozen::unit::Guarantee) -> String, + warnings: &mut Vec, +) { + use crate::schema::ir::frozen::unit::Guarantee; + + for guarantee in given_up.iter().copied() { + let code = match guarantee { + Guarantee::SchemaAgreement => UNVERIFIED_SCHEMA_AGREEMENT, + Guarantee::EncodingAgreement => UNVERIFIED_ENCODING_AGREEMENT, + Guarantee::EncodingConformance => UNVERIFIED_ENCODING_CONFORMANCE, + Guarantee::VersionHonesty => UNVERIFIED_VERSION_HONESTY, + Guarantee::BoundedSize => UNVERIFIED_BOUNDED_SIZE, + }; + warnings.push( + Diagnostic::new( + code, + format!( + "protocol `{name}` is unverified: {} isn't established ({})", + guarantee.describe(), + why(guarantee) + ), + ) + .maybe_span(Some(span)), + ); + } +} + +/// `key` in an `unverified` that isn't a guarantee's id, with the nearest one +/// if there is one. `subject` says whose it is, for the message. +fn unknown_guarantee(subject: &str, key: &str) -> Diagnostic { + use crate::schema::ir::frozen::unit::Guarantee; + + let mut message = format!("{subject}: `{key}` isn't a guarantee"); + if let Some(s) = closest(key, Guarantee::ALL.iter().map(|g| g.name())) { + message.push_str(&format!(" - did you mean `{s}`?")); + } + let known: Vec = Guarantee::ALL.iter().map(|g| format!("`{}`", g.name())).collect(); + Diagnostic::new(UNVERIFIED_UNKNOWN_GUARANTEE, message).with_help(format!("the guarantees are {}", known.join(", "))) +} + +/// The package's `unverified` (`config.idp`): why the package gives up what +/// its settings give up. The errors in what it says: a reason that's missing, +/// a key that isn't a guarantee or is listed twice, and a guarantee the +/// catalog doesn't give package scope (what a type gives, such as +/// `bounded_size`, is acknowledged where it's used). Whether the protocols +/// give up what it lists is [`check_package_unverified_used`]'s. +pub fn check_package_unverified(package: &ConfigValue) -> Vec { + use crate::schema::ir::frozen::unit::Guarantee; + use comline_catalog::Scope; + + const SUBJECT: &str = "`unverified` in config.idp"; + let mut errors = vec![]; + match package { + ConfigValue::Str(reason) => { + if reason.trim().is_empty() { + errors.push( + Diagnostic::new(UNVERIFIED_MISSING_REASON, format!("{SUBJECT} needs a reason")) + .with_help("every consumer is shown it: say what replaces the check".to_string()), + ); + } } + ConfigValue::Dict(entries) => { + let mut listed: Vec = vec![]; + for (key, value) in entries { + let Some(guarantee) = Guarantee::from_name(key) else { + errors.push(unknown_guarantee(SUBJECT, key)); + continue; + }; + if listed.contains(&guarantee) { + errors.push(Diagnostic::new( + UNVERIFIED_DUPLICATE_GUARANTEE, + format!("{SUBJECT} gives a reason for `{key}` twice"), + )); + continue; + } + listed.push(guarantee); + let entry = guarantee.entry(); + if !entry.allows_scope(Scope::Package) { + let allowed: Vec<&str> = entry.scopes.iter().map(|scope| scope.as_str()).collect(); + errors.push( + Diagnostic::new( + UNVERIFIED_WRONG_SCOPE, + format!( + "{SUBJECT}: `{key}` can't be acknowledged at package scope; the scopes it allows are {}", + allowed.join(", ") + ), + ) + .with_help(format!("acknowledge `{key}` with `@unverified` where it's given up")), + ); + continue; + } + if !matches!(value, ConfigValue::Str(reason) if !reason.trim().is_empty()) { + errors.push( + Diagnostic::new( + UNVERIFIED_MISSING_REASON, + format!("{SUBJECT} needs a reason for `{key}`, as a string"), + ) + .with_help("every consumer is shown it: say what replaces the check".to_string()), + ); + } + } + } + _ => {} } + errors +} + +/// A warning for each guarantee the package's `unverified` lists that none of +/// the protocols taking its settings gives up through them (`covered`: what +/// [`unverified::package_covered_by`] says of the package's schemas), like a +/// guarantee a protocol's own marker lists and doesn't give up. +pub fn check_package_unverified_used( + package: &ConfigValue, + covered: &[crate::schema::ir::frozen::unit::Guarantee], +) -> Vec { + use crate::schema::ir::frozen::unit::Guarantee; + use comline_catalog::Scope; + + let ConfigValue::Dict(entries) = package else { + return vec![]; + }; + entries + .iter() + .filter_map(|(key, _)| Guarantee::from_name(key)) + .filter(|g| g.entry().allows_scope(Scope::Package) && !covered.contains(g)) + .map(|guarantee| { + Diagnostic::new( + UNVERIFIED_NOT_GIVEN_UP, + format!( + "`unverified` in config.idp lists `{}`, which no protocol taking the package's settings gives up through them", + guarantee.name() + ), + ) + .with_help(format!("remove `{}` from `unverified`", guarantee.name())) + }) + .collect() } /// `@provider` and `@consumer`: if both are written they have to be diff --git a/core/tests/package/unverified.rs b/core/tests/package/unverified.rs index 854577c..6225cb8 100644 --- a/core/tests/package/unverified.rs +++ b/core/tests/package/unverified.rs @@ -396,3 +396,211 @@ fn it_stays_unbounded_through_a_rename_a_struct_and_another_schema() { "{err}" ); } + +// The package's own `unverified`, in `config.idp`: why the package gives up +// what its own settings give up, once for every protocol that takes them. + +const WHY: &str = "the gateway pins schemas by contract"; + +/// A package with no handshake, its `unverified` as given. +fn without_handshake(unverified: &str) -> String { + config(&format!("handshake = \"none\"\n{unverified}{ALLOW}")) +} + +/// `unverified`, keyed, with `WHY` for what a `none` handshake gives up. +const PACKAGE_KEYED: &str = + "unverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n \ + encoding_agreement = \"the gateway pins schemas by contract\"\n}\n"; + +const BARE: &str = "protocol P {\n function f();\n}\n"; + +fn package_reasons() -> ConfigValue { + ConfigValue::Dict(vec![ + ("schema_agreement".into(), ConfigValue::Str(WHY.into())), + ("encoding_agreement".into(), ConfigValue::Str(WHY.into())), + ]) +} + +#[test] +fn a_package_acknowledgement_covers_a_protocol_that_takes_the_package_handshake() { + let (units, warnings) = compile(&without_handshake(PACKAGE_KEYED), BARE).unwrap(); + let params = protocol_params(&units, "P"); + // What's given up is what core works out, marker or not. + assert_eq!( + unverified::frozen_set(params), + [Guarantee::SchemaAgreement, Guarantee::EncodingAgreement] + ); + assert_eq!(unverified::marker(params), None); + assert_eq!(unverified::package_scope(params), Some(&package_reasons())); + assert_eq!(unverified::reason_for(params, Guarantee::SchemaAgreement), Some(WHY)); + assert_eq!(warnings, ["unverified::schema-agreement", "unverified::encoding-agreement"]); + + // Consumers are shown the package's reasons. + let set = [Guarantee::SchemaAgreement, Guarantee::EncodingAgreement]; + assert_eq!( + unverified::protocols(&units), + [( + "P", + &set[..], + Some(format!("schema agreement \"{WHY}\", encoding agreement \"{WHY}\"")) + )] + ); +} + +#[test] +fn the_plain_form_covers_every_guarantee_a_package_setting_gives_up() { + let config = without_handshake(&format!("unverified = \"{WHY}\"\n")); + let (units, _) = compile(&config, BARE).unwrap(); + let params = protocol_params(&units, "P"); + assert_eq!(unverified::frozen_set(params).len(), 2); + // Frozen as the dictionary, the plain reason for each guarantee covered. + assert_eq!(unverified::package_scope(params), Some(&package_reasons())); +} + +#[test] +fn a_protocol_with_its_own_handshake_is_not_covered() { + let own = "@handshake = \"none\"\nprotocol Q {\n function g();\n}\n"; + let schema = format!("{BARE}\n{own}"); + let err = format!("{:?}", compile(&without_handshake(PACKAGE_KEYED), &schema).unwrap_err()); + assert!(err.contains("unverified::missing-marker"), "{err}"); + assert!(err.contains("protocol `Q` gives up schema agreement and encoding agreement"), "{err}"); + assert!(!err.contains("protocol `P` gives up"), "{err}"); + + // A protocol can't write the property the compiler freezes the package's + // reasons in: only the compiler says what the package covers. + let forged = "@handshake = \"none\"\n\ + @unverified_package = {\n schema_agreement = \"mine\",\n encoding_agreement = \"mine\"\n}\n\ + protocol Q {\n function g();\n}\n"; + let err = format!("{:?}", compile(&without_handshake(PACKAGE_KEYED), forged).unwrap_err()); + assert!(err.contains("unverified::missing-marker"), "{err}"); +} + +#[test] +fn bounded_size_is_not_the_packages_to_acknowledge() { + // The handshake's losses are covered; the unbounded string isn't. + let unbounded = "protocol P {\n function put(s: string);\n}\n"; + let err = format!("{:?}", compile(&without_handshake(PACKAGE_KEYED), unbounded).unwrap_err()); + assert!(err.contains("argument `s`: `string` has no maximum"), "{err}"); + + let keyed = format!("unverified = {{ bounded_size = \"{WHY}\" }}\n"); + let err = format!("{:?}", compile(&without_handshake(&keyed), BARE).unwrap_err()); + assert!(err.contains("unverified::wrong-scope"), "{err}"); + assert!( + err.contains("`bounded_size` can't be acknowledged at package scope; the scopes it allows are protocol, function, argument, field, type"), + "{err}" + ); +} + +#[test] +fn the_package_acknowledgement_is_checked_like_a_marker() { + let err = format!("{:?}", compile(&without_handshake("unverified = { schema_agreemnt = \"x\" }\n"), BARE).unwrap_err()); + assert!(err.contains("unverified::unknown-guarantee"), "{err}"); + assert!(err.contains("`schema_agreemnt` isn't a guarantee - did you mean `schema_agreement`?"), "{err}"); + + for reason in ["\"\"", "\" \"", "true"] { + let keyed = format!("unverified = {{ schema_agreement = {reason} }}\n"); + let err = format!("{:?}", compile(&without_handshake(&keyed), BARE).unwrap_err()); + assert!(err.contains("unverified::missing-reason"), "{reason}: {err}"); + assert!(err.contains("needs a reason for `schema_agreement`"), "{reason}: {err}"); + } + let err = format!("{:?}", compile(&without_handshake("unverified = \"\"\n"), BARE).unwrap_err()); + assert!(err.contains("unverified::missing-reason"), "{err}"); + + let twice = "unverified = { schema_agreement = \"a\" schema_agreement = \"b\" }\n"; + let err = format!("{:?}", compile(&without_handshake(twice), BARE).unwrap_err()); + assert!(err.contains("unverified::duplicate-guarantee"), "{err}"); +} + +#[test] +fn a_guarantee_no_protocol_gives_up_through_the_package_is_a_warning() { + let keyed = format!( + "unverified = {{\n schema_agreement = \"{WHY}\"\n encoding_agreement = \"{WHY}\"\n \ + version_honesty = \"just in case\"\n}}\n" + ); + let (units, warnings) = compile(&without_handshake(&keyed), BARE).unwrap(); + assert!(warnings.contains(&"unverified::not-given-up".to_string()), "{warnings:?}"); + // It isn't in what the protocol is covered for. + assert_eq!(unverified::package_reason_for(protocol_params(&units, "P"), Guarantee::VersionHonesty), None); + + // The handshake is the default one: there's nothing for it to cover. + let (units, warnings) = compile(&config(&format!("{PACKAGE_KEYED}{ALLOW}")), BARE).unwrap(); + assert_eq!(warnings.iter().filter(|w| *w == "unverified::not-given-up").count(), 2, "{warnings:?}"); + assert_eq!(unverified::package_scope(protocol_params(&units, "P")), None); + assert!(unverified::frozen_set(protocol_params(&units, "P")).is_empty()); +} + +#[test] +fn a_keyed_marker_need_not_list_what_the_package_covers() { + let unbounded = |marker: &str| format!("{marker}protocol P {{\n function put(s: string);\n}}\n"); + let only_bounded = unbounded("@unverified = { bounded_size = \"the uploader streams whatever it's given\" }\n"); + let (units, _) = compile(&without_handshake(PACKAGE_KEYED), &only_bounded).unwrap(); + let params = protocol_params(&units, "P"); + assert_eq!( + unverified::frozen_set(params), + [Guarantee::SchemaAgreement, Guarantee::EncodingAgreement, Guarantee::BoundedSize] + ); + // Its own reason for one, the package's for the rest. + assert_eq!( + unverified::reason_for(params, Guarantee::BoundedSize), + Some("the uploader streams whatever it's given") + ); + assert_eq!(unverified::reason_for(params, Guarantee::EncodingAgreement), Some(WHY)); + + // Listing one the package covers is fine too, and its own reason wins. + let both = unbounded( + "@unverified = {\n schema_agreement = \"mine\",\n bounded_size = \"the uploader streams whatever it's given\"\n}\n", + ); + let (units, warnings) = compile(&without_handshake(PACKAGE_KEYED), &both).unwrap(); + assert!(!warnings.contains(&"unverified::not-given-up".to_string()), "{warnings:?}"); + assert_eq!(unverified::reason_for(protocol_params(&units, "P"), Guarantee::SchemaAgreement), Some("mine")); + + // Without the package, the same marker leaves them unsaid. + let err = format!("{:?}", compile(&config(&format!("handshake = \"none\"\n{ALLOW}")), &only_bounded).unwrap_err()); + assert!(err.contains("unverified::missing-guarantee"), "{err}"); +} + +#[test] +fn a_package_acknowledgement_is_off_without_the_gate() { + let config = config(&format!("handshake = \"none\"\n{PACKAGE_KEYED}")); + let err = format!("{:?}", compile(&config, BARE).unwrap_err()); + assert!(err.contains("annotations.unverified.allowed"), "{err}"); + assert!(err.contains("config.idp's `unverified`"), "{err}"); +} + +#[test] +fn rewording_the_package_reason_is_a_patch_and_moving_it_is_too() { + let compiled = |config: &str, schema: &str| compile(config, schema).unwrap().0; + let old = compiled(&without_handshake(PACKAGE_KEYED), BARE); + let reworded = compiled(&without_handshake(&PACKAGE_KEYED.replace("pins schemas", "fixes the schemas")), BARE); + let changes = analyze_schema_changes(&old, &reworded); + assert!(changes.breaking_changes.is_empty(), "{:?}", changes.breaking_changes); + assert!(changes.new_features.is_empty(), "{:?}", changes.new_features); + assert!(matches!( + changes.modifications.as_slice(), + [Modification::ChangedAnnotation { key, .. }] if key == "unverified_package" + )); + + // The protocol says it itself, as it could before: the same set is given + // up, so this changes what's said and no more. + let own = compiled(&without_handshake(""), NONE_MARKED.replace("@handshake = \"none\"\n", "").as_str()); + let changes = analyze_schema_changes(&old, &own); + assert!(changes.breaking_changes.is_empty(), "{:?}", changes.breaking_changes); + assert!(changes.new_features.is_empty(), "{:?}", changes.new_features); + assert!(matches!( + changes.modifications.as_slice(), + [Modification::ChangedAnnotation { key, .. }] if key == "unverified_package" + )); + + // What's given up decides major and minor, not who says why. + let plain = compiled(&config(ALLOW), BARE); + let changes = analyze_schema_changes(&plain, &old); + assert!(changes.breaking_changes.iter().any(|c| matches!( + c, + BreakingChange::GaveUpGuarantees { guarantees, .. } if guarantees.len() == 2 + ))); + let changes = analyze_schema_changes(&old, &plain); + assert!(changes.new_features.iter().any(|c| matches!( + c, + NewFeature::RestoredGuarantees { guarantees, .. } if guarantees.len() == 2 + ))); +} diff --git a/schemas/doc-model.json b/schemas/doc-model.json index 7da99ce..8b0c0a5 100644 --- a/schemas/doc-model.json +++ b/schemas/doc-model.json @@ -1012,7 +1012,7 @@ "type": "boolean" }, "reason": { - "description": "The `@unverified` reason, when it's given up and the marker carries\none: the plain form's, or the keyed form's for this guarantee.", + "description": "The `@unverified` reason, when it's given up and the marker carries\none: the plain form's, or the keyed form's for this guarantee. The\npackage's, where it acknowledges the guarantee and the marker has none.", "type": [ "string", "null" From 55bdc68e1f106c605dcd3f4a42a9f1e13b96bfd0 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Tue, 10 Nov 2026 03:54:54 +0800 Subject: [PATCH 2/2] inspect: a protocol is unverified when it gives something up, not when it's marked A protocol only the package's `unverified` covers has no marker of its own, and showed as verified while its guarantee rows said otherwise. The flag now follows what's given up (the frozen set or any cause); its doc and the doc model's description say so. --- core/src/inspect.rs | 28 ++++++++++++++++++++++++++-- schemas/doc-model.json | 2 +- 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/core/src/inspect.rs b/core/src/inspect.rs index 43e156e..fec22b0 100644 --- a/core/src/inspect.rs +++ b/core/src/inspect.rs @@ -60,7 +60,8 @@ pub struct ProtocolSummary { pub format: Choice, pub framing: Choice, pub handshake: Choice, - /// Whether it's marked `@unverified`. + /// Whether it gives something up: some guarantee isn't held, whether the + /// protocol's own `@unverified` or the package's `unverified` says why. pub unverified: bool, /// Every guarantee, in [`Guarantee::ALL`] order. pub guarantees: Vec, @@ -338,7 +339,10 @@ fn summarize(p: Protocol) -> ProtocolSummary { format, framing, handshake, - unverified: unverified::marker(p.parameters).is_some(), + // What's given up, not who says why: a protocol only the package's + // `unverified` covers has no marker. `bounded_size` is in the frozen + // set alone. + unverified: !unverified::frozen_set(p.parameters).is_empty() || !causes.is_empty(), guarantees, } } @@ -604,4 +608,24 @@ mod tests { assert_eq!(protocol(&context, "billing::api", "Billing"), Some(billing)); assert_eq!(protocol(&context, "api", "Billing"), None); } + + #[test] + fn a_protocol_only_the_package_covers_is_unverified_with_the_packages_reasons() { + let tmp = tempfile::tempdir().unwrap(); + let app = tmp.path().join("app"); + package( + &app, + "handshake = \"none\"\nunverified = {\n schema_agreement = \"pinned by contract\"\n \ + encoding_agreement = \"one encoding only\"\n}\n\ + settings = { annotations = { unverified = { allowed = true } } }\n", + "protocol Gateway {\n function ping();\n}\n", + ); + let context = crate::package::build::compile_package(&app).unwrap(); + let [gateway] = protocols(&context).try_into().unwrap(); + // No marker of its own, and still unverified. + assert!(gateway.unverified); + assert_eq!(row(&gateway, Guarantee::SchemaAgreement).reason.as_deref(), Some("pinned by contract")); + assert_eq!(row(&gateway, Guarantee::EncodingAgreement).reason.as_deref(), Some("one encoding only")); + assert!(row(&gateway, Guarantee::VersionHonesty).held); + } } diff --git a/schemas/doc-model.json b/schemas/doc-model.json index 8b0c0a5..73c9484 100644 --- a/schemas/doc-model.json +++ b/schemas/doc-model.json @@ -1623,7 +1623,7 @@ "type": "string" }, "unverified": { - "description": "Whether it's marked `@unverified`.", + "description": "Whether it gives something up: some guarantee isn't held, whether the\nprotocol's own `@unverified` or the package's `unverified` says why.", "type": "boolean" } },