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..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, @@ -118,7 +119,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, } @@ -337,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, } } @@ -603,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/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..73c9484 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" @@ -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" } },