diff --git a/codegen/Cargo.toml b/codegen/Cargo.toml index 8ac82dd..870920d 100644 --- a/codegen/Cargo.toml +++ b/codegen/Cargo.toml @@ -8,8 +8,8 @@ license = "GPL-3.0-only" # Consumed by git rev (see ComlineProject/docs → Design → Runtime & generation # repository structure — no crates.io publishing at this stage). Local # iteration: add a `[patch]` onto a sibling checkout. -comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "0977d7a339e92ced0ebaac477a0f6b3c1104c680" } -comline-core = { git = "https://github.com/ComlineProject/core", rev = "35ab4b801c9b35af591fb48972407468c8e8af24", default-features = false } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "cd63473e7029542ef1358accbc5fc61059824577" } +comline-core = { git = "https://github.com/ComlineProject/core", rev = "263e58378bb7efcaa466542ca644228ad14e2884", default-features = false } eyre = "0.6.8" @@ -21,6 +21,6 @@ path = "src/bin/comline-gen-typescript.rs" # The conformance corpus: every fixture is a whole package. Same generation # rev as `comline-codegen` above, so the corpus and the generator share one # `comline-codegen`. -comline-conformance = { git = "https://github.com/ComlineProject/generation", rev = "0977d7a339e92ced0ebaac477a0f6b3c1104c680" } +comline-conformance = { git = "https://github.com/ComlineProject/generation", rev = "cd63473e7029542ef1358accbc5fc61059824577" } # The tests compile schemas, so they need core's compiler. -comline-core = { git = "https://github.com/ComlineProject/core", rev = "35ab4b801c9b35af591fb48972407468c8e8af24" } +comline-core = { git = "https://github.com/ComlineProject/core", rev = "263e58378bb7efcaa466542ca644228ad14e2884" } diff --git a/codegen/src/generator.rs b/codegen/src/generator.rs index b935750..14c9bdd 100644 --- a/codegen/src/generator.rs +++ b/codegen/src/generator.rs @@ -42,7 +42,7 @@ use std::path::PathBuf; use comline_core::schema::ir::frozen::types::{Literal, PrimitiveType, TypeRef}; use comline_core::schema::ir::frozen::schema_ir_hash; use comline_core::schema::idl::annotations::{MethodNames, IMPLICIT_HANDSHAKE, FORMAT_JSON, FRAMING_JSONRPC, HANDSHAKE_NONE}; -use comline_core::schema::ir::frozen::unit::FrozenUnit; +use comline_core::schema::ir::frozen::unit::{FrozenUnit, Guarantee}; use comline_core::schema::ir::unverified; use eyre::Result; @@ -1385,20 +1385,33 @@ fn no_handshake(parameters: &[FrozenUnit]) -> bool { /// A doc comment naming what an `@unverified` protocol gives up, and why, /// for its dispatcher and client. Empty for one that gives nothing up. +/// +/// The reasons are the ones the protocol was frozen with +/// ([`unverified::frozen_reasons`]); nothing is recomputed from the +/// encodings, which a request doesn't carry. fn unverified_doc(parameters: &[FrozenUnit]) -> String { let set = unverified::frozen_set(parameters); if set.is_empty() { return String::new(); } - let mut doc = format!( - "/**\n * **Unverified:** gives up {} ({}).\n", - unverified::describe(set), - // The request carries no encoding declarations, so this sees the - // official ones only: the handshake's cause, as the IR records it. - unverified::cause(parameters, &unverified::Encodings::default()) - ); - if let Some(reason) = unverified::reason(parameters) { - doc.push_str(&format!(" * Reason given: {reason}\n")); + let mut doc = format!("/**\n * **Unverified:** gives up {}.\n", unverified::describe(set)); + // One reason for everything given up reads once; a keyed one, per + // guarantee that says something different. + let mut groups: Vec<(Vec, String)> = vec![]; + for (guarantee, reason) in unverified::frozen_reasons(parameters) { + let Some(reason) = reason else { continue }; + match groups.iter_mut().find(|(_, r)| *r == reason) { + Some((guarantees, _)) => guarantees.push(guarantee), + None => groups.push((vec![guarantee], reason)), + } + } + let several = groups.len() > 1 || groups.iter().any(|(guarantees, _)| guarantees.len() < set.len()); + for (guarantees, reason) in groups { + if several { + doc.push_str(&format!(" * Reason given for {}: {reason}\n", unverified::describe(&guarantees))); + } else { + doc.push_str(&format!(" * Reason given: {reason}\n")); + } } doc.push_str(" */\n"); doc diff --git a/codegen/tests/generate.rs b/codegen/tests/generate.rs index 92ba349..72da257 100644 --- a/codegen/tests/generate.rs +++ b/codegen/tests/generate.rs @@ -1539,12 +1539,63 @@ fn handshake_none_passes_no_handshake_and_documents_what_is_given_up() { assert!(out.contains(" NoHandshake,\n"), "{out}"); assert!(out.contains("await Client.connect(transport, codec, IR_HASH, framing, new NoHandshake())")); assert!(out.contains(".serve(transport, IR_HASH, new NoHandshake())")); - let doc = "/**\n * **Unverified:** gives up schema agreement and encoding agreement (handshake `none`).\n \ + let doc = "/**\n * **Unverified:** gives up schema agreement and encoding agreement.\n \ * Reason given: the 2009 gateway\n */\n"; assert!(out.contains(&format!("{doc}export class GateDispatcher")), "{out}"); assert!(out.contains(&format!("{doc}export class GateClient")), "{out}"); } +/// A lockstep `Gate` protocol with these `@unverified` parameters. +fn unverified_gate(marker: ConfigValue, set: Vec) -> String { + one(vec![FrozenUnit::Protocol { + docstring: String::new(), + parameters: vec![ + FrozenUnit::Property { name: "unverified".into(), value: marker }, + FrozenUnit::Unverified(set), + FrozenUnit::Property { name: "framing".into(), value: ConfigValue::Str("datagram".into()) }, + ], + name: "Gate".into(), + functions: vec![function("ping", vec![], None, vec![])], + span: (0, 0), + }]) +} + +/// core#253: the cause was recomputed from the official encodings, so a +/// protocol given up only for its size read as `(handshake ...)`. +#[test] +fn unverified_docs_render_the_frozen_reasons_not_a_handshake() { + use comline_core::schema::ir::frozen::unit::Guarantee; + let reason = "the uploader streams whatever it's given"; + + let out = unverified_gate(ConfigValue::Str(reason.into()), vec![Guarantee::BoundedSize]); + let doc = format!("/**\n * **Unverified:** gives up bounded size.\n * Reason given: {reason}\n */\n"); + assert!(out.contains(&format!("{doc}export class GateClient")), "{out}"); + assert!(!out.contains("(handshake"), "{out}"); + + let out = unverified_gate(ConfigValue::Str("lines has no vectors".into()), vec![Guarantee::EncodingConformance]); + assert!(out.contains(" * **Unverified:** gives up encoding conformance.\n * Reason given: lines has no vectors\n"), "{out}"); + assert!(!out.contains("(handshake"), "{out}"); + + // Nothing recorded beside a bounded size: what the build shows for it. + let out = unverified_gate(ConfigValue::Dict(vec![]), vec![Guarantee::BoundedSize]); + assert!(out.contains(" * Reason given: a string, list or nesting it reaches has no maximum\n"), "{out}"); +} + +/// A keyed `@unverified` says each guarantee's own reason. +#[test] +fn a_keyed_unverified_renders_each_guarantees_reason() { + use comline_core::schema::ir::frozen::unit::Guarantee; + let keyed = ConfigValue::Dict(vec![ + ("schema_agreement".into(), ConfigValue::Str("the gateway predates Comline".into())), + ("bounded_size".into(), ConfigValue::Str("the uploader streams".into())), + ]); + let out = unverified_gate(keyed, vec![Guarantee::SchemaAgreement, Guarantee::BoundedSize]); + let doc = "/**\n * **Unverified:** gives up schema agreement and bounded size.\n \ + * Reason given for schema agreement: the gateway predates Comline\n \ + * Reason given for bounded size: the uploader streams\n */\n"; + assert!(out.contains(&format!("{doc}export class GateClient")), "{out}"); +} + #[test] fn a_protocol_with_the_default_handshake_imports_no_no_handshake() { let out = one(vec![FrozenUnit::Protocol { diff --git a/xtask/Cargo.toml b/xtask/Cargo.toml index 201f080..601d7c3 100644 --- a/xtask/Cargo.toml +++ b/xtask/Cargo.toml @@ -7,8 +7,8 @@ publish = false [dependencies] # Same revs `codegen` pins, so this tool and the generator it drives agree on # one `comline-core` - see codegen/Cargo.toml's own comment. -comline-core = { git = "https://github.com/ComlineProject/core", rev = "35ab4b801c9b35af591fb48972407468c8e8af24" } -comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "0977d7a339e92ced0ebaac477a0f6b3c1104c680" } +comline-core = { git = "https://github.com/ComlineProject/core", rev = "263e58378bb7efcaa466542ca644228ad14e2884" } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "cd63473e7029542ef1358accbc5fc61059824577" } comline-codegen-typescript = { path = "../codegen" } eyre = "0.6.8"