diff --git a/catalog/gen/catalog.json b/catalog/gen/catalog.json index 6c6a477..2fe64cc 100644 --- a/catalog/gen/catalog.json +++ b/catalog/gen/catalog.json @@ -4,31 +4,54 @@ "status": "stable", "title": "schema agreement", "description": "Both ends were built from compatible schemas, which the handshake checks.", - "comes_from": "handshake" + "comes_from": "handshake", + "scopes": [ + "package", + "protocol" + ] }, "encoding_agreement": { "status": "stable", "title": "encoding agreement", "description": "Both ends use the same format and framing, which the handshake checks.", - "comes_from": "handshake" + "comes_from": "handshake", + "scopes": [ + "package", + "protocol" + ] }, "encoding_conformance": { "status": "stable", "title": "encoding conformance", "description": "An implementation encodes what its name promises, proven by conformance vectors.", - "comes_from": "encoding" + "comes_from": "encoding", + "scopes": [ + "package", + "protocol" + ] }, "version_honesty": { "status": "stable", "title": "version honesty", "description": "A version bump says what the change breaks, as the version comparison works it out.", - "comes_from": "policy" + "comes_from": "policy", + "scopes": [ + "package", + "protocol" + ] }, "bounded_size": { "status": "stable", "title": "bounded size", "description": "Every value has a maximum size, so a decoder refuses an oversized one before allocating it.", - "comes_from": "type" + "comes_from": "type", + "scopes": [ + "protocol", + "function", + "argument", + "field", + "type" + ] } }, "facts": { @@ -375,6 +398,14 @@ "version_honesty", "bounded_size" ], + "scopes": [ + "package", + "protocol", + "function", + "argument", + "field", + "type" + ], "formats": [ "packed@1", "json@1", diff --git a/catalog/guarantees.cue b/catalog/guarantees.cue index c9af68f..5b1bb6c 100644 --- a/catalog/guarantees.cue +++ b/catalog/guarantees.cue @@ -5,25 +5,30 @@ guarantees: { title: "schema agreement" description: "Both ends were built from compatible schemas, which the handshake checks." comes_from: "handshake" + scopes: ["package", "protocol"] } encoding_agreement: { title: "encoding agreement" description: "Both ends use the same format and framing, which the handshake checks." comes_from: "handshake" + scopes: ["package", "protocol"] } encoding_conformance: { title: "encoding conformance" description: "An implementation encodes what its name promises, proven by conformance vectors." comes_from: "encoding" + scopes: ["package", "protocol"] } version_honesty: { title: "version honesty" description: "A version bump says what the change breaks, as the version comparison works it out." comes_from: "policy" + scopes: ["package", "protocol"] } bounded_size: { title: "bounded size" description: "Every value has a maximum size, so a decoder refuses an oversized one before allocating it." comes_from: "type" + scopes: ["protocol", "function", "argument", "field", "type"] } } diff --git a/catalog/readme.md b/catalog/readme.md index 245b52a..9dd7d64 100644 --- a/catalog/readme.md +++ b/catalog/readme.md @@ -23,6 +23,15 @@ What an entry may say, and the rules across entries, are in (`frozen_as`: `jsonrpc`, `datagram`), that spelling is an alias too. - A reference (`establishes`, `feature`) names an entry that exists. - A handshake's facts are booleans. +- A guarantee's `scopes` say where an `@unverified` marker acknowledging it + may sit: any of `package`, `protocol`, `function`, `argument`, `field` and + `type`, outermost to innermost, each at most once. They follow from where + its cause is: what the handshake, a policy or the encoding gives up + (`schema_agreement`, `version_honesty`, `encoding_conformance`, ...) is + settled for a package or a protocol, so those are its scopes; what a type + gives up (`bounded_size`) can also be acknowledged on a function, an + argument, a field or the type itself, and must include `type`. The schema + checks both, and `sets.scopes` lists the vocabulary. - `since` is the spec version that introduced an entry, where the changelog names one. diff --git a/catalog/rust.cue b/catalog/rust.cue index 6289daa..d2f498b 100644 --- a/catalog/rust.cue +++ b/catalog/rust.cue @@ -34,6 +34,14 @@ _rust: { #in: "format" | "framing" | "handshake" out: {format: "Kind::Format", framing: "Kind::Framing", handshake: "Kind::Handshake"}[#in] } + scope: { + #in: #Scope + out: {package: "Scope::Package", protocol: "Scope::Protocol", function: "Scope::Function", argument: "Scope::Argument", field: "Scope::Field", type: "Scope::Type"}[#in] + } + scopes: { + #in: [...#Scope] + out: "&[" + strings.Join([for s in #in {(scope & {#in: s}).out}], ", ") + "]" + } status: { #in: "stable" | "experimental" | "deprecated" out: {stable: "Status::Stable", experimental: "Status::Experimental", deprecated: "Status::Deprecated"}[#in] @@ -80,7 +88,7 @@ _set: { rust_catalog: """ // Generated from the catalog's CUE by `specs/check.sh`: don't edit by hand. - use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Status, Value}; + use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Scope, Status, Value}; pub const SPEC_VERSION: &str = \((_rust.str & {#in: _spec_version}).out); @@ -92,6 +100,7 @@ rust_catalog: """ title: \((_rust.str & {#in: g.title}).out), description: \((_rust.str & {#in: g.description}).out), comes_from: \({handshake: "Origin::Handshake", encoding: "Origin::Encoding", policy: "Origin::Policy", type: "Origin::Type"}[g.comes_from]), + scopes: \((_rust.scopes & {#in: g.scopes}).out), \((_rust.lifecycle & {#in: g}).out) }, """}], "\n")) @@ -165,6 +174,7 @@ rust_catalog: """ /// The catalog's sets. pub mod sets { \((_set & {#name: "GUARANTEES", #in: sets.guarantees}).out) + \((_set & {#name: "SCOPES", #in: sets.scopes}).out) \((_set & {#name: "FORMATS", #in: sets.formats}).out) \((_set & {#name: "FRAMINGS", #in: sets.framings}).out) \((_set & {#name: "HANDSHAKES", #in: sets.handshakes}).out) diff --git a/catalog/schema.cue b/catalog/schema.cue index ac9282c..34de17a 100644 --- a/catalog/schema.cue +++ b/catalog/schema.cue @@ -13,6 +13,12 @@ import "list" } } +// Where an `@unverified` marker may sit, outermost to innermost: the +// package, a protocol in it, a function of the protocol, one of its +// arguments, a field of a type, a type. +#Scopes: ["package", "protocol", "function", "argument", "field", "type"] +#Scope: or(#Scopes) + // A guarantee Comline gives between peers, which a protocol can give up // with `@unverified`. Its id is the name written in `accept_unverified`, // diagnostics and generated docs. @@ -23,6 +29,9 @@ import "list" // What gives it up: the handshake, the format and framing, a handshake // policy, or a type. comes_from!: "handshake" | "encoding" | "policy" | "type" + // Where an `@unverified` marker acknowledging it may sit, which follows + // from where its cause is. In `#Scopes` order, each at most once. + scopes!: [#Scope, ...#Scope] }) // A fact an encoding's profile states, with every value it may take and @@ -74,6 +83,18 @@ facts: {[=~#SnakeId]: #Fact, [!~#SnakeId]: _|_} encodings: {[=~#EncodingId]: #Encoding, [!~#EncodingId]: _|_} features: {[=~#FeatureId]: #Feature, [!~#FeatureId]: _|_} +// A guarantee's scopes follow from where it comes from: what a type gives +// up can be acknowledged on the type, or on whatever uses it, down from the +// protocol; what the handshake, the policies and the encoding give up is +// settled by the package and its protocols, never below a protocol. +_scope_rank: {for i, s in #Scopes {(s): i}} +_scopes_are_ordered: [for id, g in guarantees + let ranks = [for s in g.scopes {_scope_rank[s]}] + if len([for i, r in ranks if i > 0 if r <= ranks[i-1] {i}]) > 0 {id}] & [] +_scopes_follow_origin: [for id, g in guarantees + let inner = [for s in g.scopes if _scope_rank[s] >= _scope_rank["function"] {s}] + if (g.comes_from == "type" && !list.Contains(g.scopes, "type")) || (g.comes_from != "type" && len(inner) > 0) {id}] & [] + // A handshake's facts are booleans. _boolean_handshake_facts: [for id, f in facts if f.applies_to == "handshake" if [for v, _ in f.values {v}] != ["true", "false"] {id}] & [] diff --git a/catalog/sets.cue b/catalog/sets.cue index 6932211..07b2b64 100644 --- a/catalog/sets.cue +++ b/catalog/sets.cue @@ -4,6 +4,8 @@ package catalog // label that names a top-level field is quoted, so it doesn't shadow it. sets: { "guarantees": [for id, _ in guarantees {id}] + // Where an `@unverified` marker may sit, outermost to innermost. + scopes: #Scopes formats: [for id, e in encodings if e.kind == "format" {id}] framings: [for id, e in encodings if e.kind == "framing" {id}] handshakes: [for id, e in encodings if e.kind == "handshake" {id}] diff --git a/rust/src/catalog.rs b/rust/src/catalog.rs index 69f777b..7dd334a 100644 --- a/rust/src/catalog.rs +++ b/rust/src/catalog.rs @@ -1,6 +1,6 @@ // Generated from the catalog's CUE by `specs/check.sh`: don't edit by hand. -use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Status, Value}; +use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Scope, Status, Value}; pub const SPEC_VERSION: &str = r#"0.10"#; @@ -11,6 +11,7 @@ pub const GUARANTEES: &[Guarantee] = &[ title: r#"schema agreement"#, description: r#"Both ends were built from compatible schemas, which the handshake checks."#, comes_from: Origin::Handshake, + scopes: &[Scope::Package, Scope::Protocol], status: Status::Stable, replaced_by: None, since: None, @@ -20,6 +21,7 @@ pub const GUARANTEES: &[Guarantee] = &[ title: r#"encoding agreement"#, description: r#"Both ends use the same format and framing, which the handshake checks."#, comes_from: Origin::Handshake, + scopes: &[Scope::Package, Scope::Protocol], status: Status::Stable, replaced_by: None, since: None, @@ -29,6 +31,7 @@ pub const GUARANTEES: &[Guarantee] = &[ title: r#"encoding conformance"#, description: r#"An implementation encodes what its name promises, proven by conformance vectors."#, comes_from: Origin::Encoding, + scopes: &[Scope::Package, Scope::Protocol], status: Status::Stable, replaced_by: None, since: None, @@ -38,6 +41,7 @@ pub const GUARANTEES: &[Guarantee] = &[ title: r#"version honesty"#, description: r#"A version bump says what the change breaks, as the version comparison works it out."#, comes_from: Origin::Policy, + scopes: &[Scope::Package, Scope::Protocol], status: Status::Stable, replaced_by: None, since: None, @@ -47,6 +51,7 @@ pub const GUARANTEES: &[Guarantee] = &[ title: r#"bounded size"#, description: r#"Every value has a maximum size, so a decoder refuses an oversized one before allocating it."#, comes_from: Origin::Type, + scopes: &[Scope::Protocol, Scope::Function, Scope::Argument, Scope::Field, Scope::Type], status: Status::Stable, replaced_by: None, since: None, @@ -503,6 +508,7 @@ pub mod feature { /// The catalog's sets. pub mod sets { pub const GUARANTEES: &[&str] = &[r#"schema_agreement"#, r#"encoding_agreement"#, r#"encoding_conformance"#, r#"version_honesty"#, r#"bounded_size"#]; + pub const SCOPES: &[&str] = &[r#"package"#, r#"protocol"#, r#"function"#, r#"argument"#, r#"field"#, r#"type"#]; pub const FORMATS: &[&str] = &[r#"packed@1"#, r#"json@1"#, r#"msgpack@1"#]; pub const FRAMINGS: &[&str] = &[r#"jsonrpc@1"#, r#"datagram@1"#, r#"datagram@2"#, r#"datagram@3"#]; pub const HANDSHAKES: &[&str] = &[r#"comline@1"#, r#"comline@2"#, r#"none"#]; diff --git a/rust/src/lib.rs b/rust/src/lib.rs index cd3531b..375ddf1 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -52,6 +52,38 @@ pub enum Origin { Type, } +/// Where an `@unverified` marker may sit, outermost to innermost. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum Scope { + /// The whole package. + Package, + /// A protocol in it. + Protocol, + /// A function of a protocol. + Function, + /// An argument of a function. + Argument, + /// A field of a type. + Field, + /// A type. + Type, +} + +impl Scope { + /// As the catalog writes it: `package`, `protocol`, `function`, + /// `argument`, `field`, `type`. + pub const fn as_str(self) -> &'static str { + match self { + Scope::Package => "package", + Scope::Protocol => "protocol", + Scope::Function => "function", + Scope::Argument => "argument", + Scope::Field => "field", + Scope::Type => "type", + } + } +} + /// Where an entry stands. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Status { @@ -69,12 +101,23 @@ pub struct Guarantee { pub title: &'static str, pub description: &'static str, pub comes_from: Origin, + /// Where an `@unverified` marker acknowledging it may sit, outermost to + /// innermost. + pub scopes: &'static [Scope], pub status: Status, pub replaced_by: Option<&'static str>, /// The spec version that introduced it, where the changelog names one. pub since: Option<&'static str>, } +impl Guarantee { + /// Whether an `@unverified` marker acknowledging this guarantee may sit + /// at `scope`. + pub fn allows_scope(&self, scope: Scope) -> bool { + self.scopes.contains(&scope) + } +} + /// One value a fact may take, and what it means. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct Value { @@ -226,6 +269,39 @@ mod tests { } } + #[test] + fn every_guarantee_has_scopes_in_order() { + let rank = |s: &Scope| sets::SCOPES.iter().position(|id| *id == s.as_str()).unwrap(); + for g in GUARANTEES { + assert!(!g.scopes.is_empty(), "{}", g.id); + assert!(g.scopes.windows(2).all(|w| rank(&w[0]) < rank(&w[1])), "{}", g.id); + assert_eq!(g.comes_from == Origin::Type, g.allows_scope(Scope::Type), "{}", g.id); + } + } + + #[test] + fn a_type_guarantee_reaches_below_the_protocol() { + let bounded = guarantee(guarantee::BOUNDED_SIZE).unwrap(); + assert!(bounded.allows_scope(Scope::Field)); + assert!(!bounded.allows_scope(Scope::Package)); + let agreement = guarantee(guarantee::SCHEMA_AGREEMENT).unwrap(); + assert!(agreement.allows_scope(Scope::Package) && agreement.allows_scope(Scope::Protocol)); + assert!(!agreement.allows_scope(Scope::Field)); + } + + #[test] + fn scopes_match_their_set() { + let all = [ + Scope::Package, + Scope::Protocol, + Scope::Function, + Scope::Argument, + Scope::Field, + Scope::Type, + ]; + assert!(all.iter().map(|s| s.as_str()).eq(sets::SCOPES.iter().copied())); + } + #[test] fn the_spec_version_is_a_version() { let (major, minor) = SPEC_VERSION.split_once('.').unwrap();