diff --git a/README.md b/README.md index 4efcf07..321a3be 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,12 @@ wasm/ comline-playground-wasm — the editor's Rust crate, wasm-bindgen surf encode_describe / check_description — the Describe call first, checked as the CLI checks it (protocol, IR format, language and version) - describe_project(files) -> the schema shape the sim runs on + describe_project(files) -> the schema shape the sim runs on, + with wire numbers and the comline@2 Hello + The package takes core's defaults (datagram@3, comline@2) and + has the fixed id 706c617967726f756e64000000000000; its facts are + a first version's (comline_core::compat::facts_of_context), so + wire numbers and lines are provisional. semantic_tokens / hover / completions — the LSP handlers verbatim deps: comline-core, comline-codegen, comline-codegen-rust, comline-codegen-typescript, comline-language-server (git rev) diff --git a/app/package.json b/app/package.json index d97832e..144d032 100644 --- a/app/package.json +++ b/app/package.json @@ -24,7 +24,7 @@ "@codemirror/view": "^6.34.0", "@lezer/highlight": "^1.2.3", "comline-examples": "git+https://github.com/ComlineProject/examples.git#f63894988ea2cc5db98ff97cc0fbdfceb5af6bb7", - "comline-simulator": "git+https://github.com/ComlineProject/simulator.git#1eab1f84f1ae7760135ca4a7a519c78091001a44" + "comline-simulator": "git+https://github.com/ComlineProject/simulator.git#564851a8fa00709cd94db8ce8ab1c4325a691fc4" }, "devDependencies": { "@types/node": "^20.19.43", diff --git a/app/src/sim/shape.ts b/app/src/sim/shape.ts index e0de842..8a8c381 100644 --- a/app/src/sim/shape.ts +++ b/app/src/sim/shape.ts @@ -4,6 +4,24 @@ export interface ProjectShape { schemas: SchemaShape[]; + /** The package's connection, when its protocols run on one. */ + connection?: ConnectionShape; +} + +/** The package connection: what every protocol on it shares. */ +export interface ConnectionShape { + /** Canonical: `datagram@3` (core's default), `datagram@2`, ... */ + framing: string; + /** Canonical: `comline@2` (core's default), `comline@1` or `none`. */ + handshake: string; + /** `comline@2`'s four parameters, each as written or its default. */ + params?: Record; + /** + * Under `comline@2`: the encoded `Hello` each end sends, hex. A playground + * package has no history, so its numbers and lines are a first version's: + * provisional, as a first build's are until `comline release`. + */ + hello?: string; } export interface SchemaShape { @@ -19,14 +37,18 @@ export interface SchemaShape { export interface ProtocolShape { name: string; - framing: "datagram" | "datagram@2" | "jsonrpc"; + framing: "datagram" | "datagram@2" | "datagram@3" | "jsonrpc"; + /** The number its frames carry on the connection (its wire number under `datagram@3`). */ + number?: number; functions: FnShape[]; } export interface FnShape { name: string; - /** 0-based position in the protocol — the `Call` id `resolveKind` matches. */ + /** 0-based position in the protocol. */ index: number; + /** What its call carries on the wire: its wire number under `datagram@3`, else its position. */ + call?: number; /** No return at all — a fire-and-forget `notify`. */ oneway: boolean; args: ArgShape[]; diff --git a/app/src/sim/sim-wasm.test.ts b/app/src/sim/sim-wasm.test.ts index a77a2b1..e647b22 100644 --- a/app/src/sim/sim-wasm.test.ts +++ b/app/src/sim/sim-wasm.test.ts @@ -47,10 +47,16 @@ test("the sim wasm instantiates and round-trips a call", () => { assert.equal(result.status, "ok"); assert.deepEqual(result.value, { body: "", seq: 0 }); // default seeded reply = zero value + // Core's defaults: `datagram@3` and `comline@2`, whose `offer` exchange is + // three messages (hello, answer, verdict). const frames = JSON.parse(sim.frames(conn)); - assert.equal(frames.length, 4, "two handshake frames, then request + response"); - assert.equal(frames[2].kind, "request"); - assert.equal(frames[3].kind, "response"); + assert.equal(frames.length, 5, "three comline@2 handshake frames, then request + response"); + assert.deepEqual( + frames.slice(0, 3).map((f: { kind: string }) => f.kind), + ["handshake", "handshake", "handshake"], + ); + assert.equal(frames[3].kind, "request"); + assert.equal(frames[4].kind, "response"); }); test("a behaviour swap and a shareable link work through the facade", () => { diff --git a/app/src/sim/ui/framelog.ts b/app/src/sim/ui/framelog.ts index 9550698..4ee261c 100644 --- a/app/src/sim/ui/framelog.ts +++ b/app/src/sim/ui/framelog.ts @@ -41,6 +41,8 @@ export interface FrameDetail { /** Why it faulted, when the simulator knows. */ note?: string; handshake?: { irHash: string; wireFormat: string; framing: string; caps: number }; + /** A `comline@2` message, as the runtime decodes it. */ + comline2?: { type: "hello" | "answer" | "verdict"; message: unknown }; } export interface LogSource { @@ -338,6 +340,7 @@ export function frameLog(): FrameLog { kv("framing_name", detail.handshake.framing), ); } + if (detail.comline2) body.append(json(`comline@2 ${detail.comline2.type}`, detail.comline2.message)); if (detail.requestId !== undefined) body.append(kv("request_id", detail.requestId)); if ("params" in detail) body.append(json("params", detail.params)); if ("ok" in detail) body.append(json("ok", detail.ok)); diff --git a/app/src/sim/ui/view.ts b/app/src/sim/ui/view.ts index 4a409ac..3c9ce60 100644 --- a/app/src/sim/ui/view.ts +++ b/app/src/sim/ui/view.ts @@ -59,7 +59,7 @@ interface ModelConn { clientId: string; serverId: string; faults: Faults; - framing: "auto" | "datagram" | "datagram@2" | "jsonrpc"; + framing: "auto" | "datagram" | "datagram@2" | "datagram@3" | "jsonrpc"; wireFormat: "packed" | "json" | "msgpack"; } interface Model { @@ -842,6 +842,7 @@ export function createSim(opts: SimOpts = {}): SimView { ["protocol", sel.protocol], ["role", sel.role], ["framing", found.protocol.framing], + ...(shape?.connection ? [["handshake", handshakeLabel(shape.connection)] as [string, string]] : []), ]), ); const hash = document.createElement("button"); @@ -1100,7 +1101,7 @@ export function createSim(opts: SimOpts = {}): SimView { inspectorEl.append(section("transport")); const framingSel = document.createElement("select"); framingSel.title = "auto follows the protocol's declared framing"; - for (const v of ["auto", "datagram@2", "datagram", "jsonrpc"] as const) { + for (const v of ["auto", "datagram@3", "datagram@2", "datagram", "jsonrpc"] as const) { framingSel.append(opt(v, v, v === conn.framing)); } const wireSel = document.createElement("select"); @@ -1128,6 +1129,11 @@ export function createSim(opts: SimOpts = {}): SimView { if (conn.framing === "auto") { inspectorEl.append(muted(`auto → ${resolvedFraming} for this protocol`)); } + const handshake = shape?.connection; + if (handshake) { + inspectorEl.append(facts([["handshake", handshakeLabel(handshake)]])); + if (handshake.hello) inspectorEl.append(muted(PROVISIONAL)); + } inspectorEl.append(section("faults")); inspectorEl.append(faultControls(conn)); @@ -1699,3 +1705,13 @@ function opt(value: string, text: string, selected = false): HTMLOptionElement { if (selected) o.selected = true; return o; } + +/** A playground package has no history: its wire numbers and lines are a first version's. */ +const PROVISIONAL = + "wire numbers and lines are a first version's — provisional, as a first build's are until `comline release`"; + +/** `comline@2 (exchange = offer, ...)`, or the handshake's name alone. */ +function handshakeLabel(c: { handshake: string; params?: Record }): string { + const params = Object.entries(c.params ?? {}); + return params.length ? `${c.handshake} (${params.map(([k, v]) => `${k} = ${v}`).join(", ")})` : c.handshake; +} diff --git a/app/src/sim/view.test.ts b/app/src/sim/view.test.ts index 61ca512..6facd1f 100644 --- a/app/src/sim/view.test.ts +++ b/app/src/sim/view.test.ts @@ -122,7 +122,8 @@ test("1d — place, connect, call, and see the reply and frames", async () => { (reqRow as HTMLDetailsElement).open = true; fire(reqRow, "toggle"); assert.match(reqRow.querySelector(".frame-body")!.textContent!, /"text": "hello"/); - assert.match(reqRow.querySelector(".frame-body")!.textContent!, /datagram@2/); + // Core's default framing, addressing the call by its wire number. + assert.match(reqRow.querySelector(".frame-body")!.textContent!, /datagram@3/); sim.destroy(); }); @@ -844,13 +845,16 @@ test("2g — `compare` runs the call over every framing/codec combo", async () = "datagram@2/json", "datagram@2/msgpack", "datagram@2/packed", + "datagram@3/json", + "datagram@3/msgpack", + "datagram@3/packed", "jsonrpc/json", ], "every combo Chat's framing supports", ); assert.match( blk.querySelector(".compare-note")!.textContent!, - /same reply on all 7 framing\/codec combinations/, + /same reply on all 10 framing\/codec combinations/, "the decoded reply is identical across encodings", ); assert.equal(blk.querySelectorAll(".compare-table tr.mismatch").length, 0); @@ -872,7 +876,14 @@ test("2g — the connection inspector edits framing / wire format", async () => const wireSel = () => selects().find((s) => [...s.options].some((o) => o.value === "msgpack"))!; assert.equal(framingSel().value, "auto", "starts on auto"); - assert.match(sim.el.querySelector(".sim-inspector")!.textContent!, /auto → datagram@2/); + assert.match(sim.el.querySelector(".sim-inspector")!.textContent!, /auto → datagram@3/); + // Core's default handshake, with its parameters, and the numbers labelled + // provisional: a playground package has no history. + assert.match( + sim.el.querySelector(".sim-inspector")!.textContent!, + /comline@2 \(scope = protocol, newer_consumer = degrade, same_version_differs = refuse, exchange = offer\)/, + ); + assert.match(sim.el.querySelector(".sim-inspector")!.textContent!, /provisional/); assert.deepEqual( [...wireSel().options].map((o) => o.value), ["packed", "json", "msgpack"], diff --git a/app/yarn.lock b/app/yarn.lock index a72e74f..a16a8a1 100644 --- a/app/yarn.lock +++ b/app/yarn.lock @@ -787,7 +787,7 @@ __metadata: "@lezer/highlight": "npm:^1.2.3" "@types/node": "npm:^20.19.43" comline-examples: "git+https://github.com/ComlineProject/examples.git#f63894988ea2cc5db98ff97cc0fbdfceb5af6bb7" - comline-simulator: "git+https://github.com/ComlineProject/simulator.git#1eab1f84f1ae7760135ca4a7a519c78091001a44" + comline-simulator: "git+https://github.com/ComlineProject/simulator.git#564851a8fa00709cd94db8ce8ab1c4325a691fc4" linkedom: "npm:^0.18.13" tsx: "npm:^4.23.13" typescript: "npm:^5.6.0" @@ -795,10 +795,10 @@ __metadata: languageName: unknown linkType: soft -"comline-simulator@git+https://github.com/ComlineProject/simulator.git#1eab1f84f1ae7760135ca4a7a519c78091001a44": +"comline-simulator@git+https://github.com/ComlineProject/simulator.git#564851a8fa00709cd94db8ce8ab1c4325a691fc4": version: 0.0.0 - resolution: "comline-simulator@https://github.com/ComlineProject/simulator.git#commit=1eab1f84f1ae7760135ca4a7a519c78091001a44" - checksum: 10c0/1c06f13064ca40fbf183d154d6849c429b6f89b91664fe6ca5afdb304637069a6443a9a1f925662c6308ed80d7c3c6eb500616d9593c5cc5cf8227a393b2274c + resolution: "comline-simulator@https://github.com/ComlineProject/simulator.git#commit=564851a8fa00709cd94db8ce8ab1c4325a691fc4" + checksum: 10c0/0238c841ab44ef23e1224473c61631b0424ab9d470474921d43fdb7a5d9f4792c0902374964773298f28fcd91913c6447edb57a9643a5f2cee1052ffc0dbb396 languageName: node linkType: hard diff --git a/wasm/Cargo.toml b/wasm/Cargo.toml index 1bf31dd..30eb8f5 100644 --- a/wasm/Cargo.toml +++ b/wasm/Cargo.toml @@ -12,13 +12,13 @@ crate-type = ["cdylib", "rlib"] # The same crates the CLI and the language server compose — by git rev, so the # playground runs *that* code, not a re-implementation. Keep the `comline-core` # rev identical across all of them (one `comline-core` in the tree). -comline-core = { git = "https://github.com/ComlineProject/core", rev = "8f5dc91f1c1c91e192585c3e4b80128621047499" } -comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "c303722c447ded28d50d7cf32b3164916fa76e5f" } -comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "2d50fbff670d883c92c363793e888158bb15b7a0" } -comline-codegen-typescript = { git = "https://github.com/ComlineProject/comline-typescript", rev = "ea9b9e2c70bbd87d99cc028543f73c8ee7749e1c" } +comline-core = { git = "https://github.com/ComlineProject/core", rev = "1dc294ae97cc3649311e9f78c7eeac8c6f969c31" } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "83162eac46c3689a4d4a681e3e4dc1be8bdbd856" } +comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "addca268903503f997a8f099e30261c2fff0c720" } +comline-codegen-typescript = { git = "https://github.com/ComlineProject/comline-typescript", rev = "40cab74beb727e293d1445cd3e9afa98e1ec380b" } # The LSP's analysis layer (diagnostics / hover / completion / semantic tokens), # without its `tower-lsp` server — builds for wasm32. -comline-language-server = { git = "https://github.com/ComlineProject/language-server", rev = "91189530cdcb72dacb96eff6e2a67c3f14da8282", default-features = false } +comline-language-server = { git = "https://github.com/ComlineProject/language-server", rev = "0764367be56f18a6715cf7c385259debdbd9b6d2", default-features = false } lsp-types = "0.94" rust-sitter = "0.4.5" # parse-error types @@ -26,10 +26,11 @@ wasm-bindgen = "0.2" serde = { version = "1", features = ["derive"] } serde-wasm-bindgen = "0.6" console_error_panic_hook = "0.1" - -[dev-dependencies] +# `comline_core::compat::PackageFacts` into the generator protocol's mirror, +# as the CLI converts it. serde_json = "1" + [profile.release] opt-level = "s" lto = true diff --git a/wasm/src/lib.rs b/wasm/src/lib.rs index 0e2ca82..81b3507 100644 --- a/wasm/src/lib.rs +++ b/wasm/src/lib.rs @@ -25,9 +25,10 @@ use std::rc::Rc; use serde::{Deserialize, Serialize}; use wasm_bindgen::prelude::*; +use comline_core::package::config::ir::context::ProjectContext; use comline_core::package::config::ir::frozen::FrozenUnit as ConfigUnit; use comline_core::package::config::ir::interpreter::ProjectInterpreter; -use comline_core::schema::idl::annotations::{FramingValue, DEFAULT_FORMAT, DEFAULT_FRAMING}; +use comline_core::schema::idl::annotations::{FramingValue, DEFAULT_FORMAT, IMPLICIT_FRAMING}; use comline_core::schema::idl::grammar::Declaration; use comline_core::schema::ir::compiler::interpreter::incremental::IncrementalInterpreter; use comline_core::schema::ir::context::SchemaContext; @@ -44,6 +45,7 @@ use comline_codegen::versions::LangVersion; use comline_codegen::{GenerateRequest, Mode, PackageMeta}; use comline_language_server::analysis::diagnostics::generate_diagnostics; +use comline_language_server::analysis::source::{apply_package_wire, declared_wire}; use comline_language_server::handlers::{completion, hover as hover_h, semantic_tokens}; use comline_language_server::parser; use comline_language_server::util::byte_range_to_lsp_range; @@ -53,7 +55,27 @@ use lsp_types::{Diagnostic, DiagnosticSeverity, Position, Range, Url}; /// Minimal package config — enough for `ProjectInterpreter` to hand back a /// `ProjectContext` we can push schema contexts onto. Generation targets are /// chosen in the UI, not here. -const CONGREGATION: &str = "congregation playground\nspecification_version = 1\n"; +/// +/// It states no `wire` or `handshake`, so the playground's package takes +/// core's defaults, `datagram@3` and `comline@2`. `comline@2` identifies a +/// package by its `id`, which `comline build` writes into a real package's +/// config.idp; the playground has no disk to write one to, so every +/// playground package shares this fixed one ([`PACKAGE_ID`]). A fixed id +/// keeps the generated code the same from one visit to the next. +const CONGREGATION: &str = concat!( + "congregation playground\nid = \"", + "706c617967726f756e64000000000000", + "\"\nspecification_version = 1\n" +); + +/// The id every playground package has: "playground" in ASCII, as hex, +/// padded to the 32 hex digits a package id takes. See [`CONGREGATION`]. +pub const PACKAGE_ID: &str = "706c617967726f756e64000000000000"; + +/// The version a playground package's facts are of: a first version's, as +/// it has no history. Its numbers are provisional, as a first build's are +/// until `comline release`. +const PACKAGE_VERSION: &str = "0.1.0"; /// Schema file extension (`comline-core`'s `SCHEMA_EXTENSION`), stripped when /// turning a virtual file name into a namespace. @@ -123,7 +145,7 @@ pub fn compile_project(files: JsValue) -> JsValue { }) } }; - to_js(&interpret_project(&files).0) + to_js(&interpret_project(&files).report) } #[derive(Serialize)] @@ -469,7 +491,17 @@ fn check_path(path: &str) -> Result<(), &'static str> { fn generate_request(files: JsValue, target: &str, mode: &str) -> Result { let files: Vec = serde_wasm_bindgen::from_value(files).map_err(|e| format!("bad file list: {e}"))?; - let (_, schemas, declared) = interpret_project(&files); + request_for(&files, target, mode) +} + +/// [`generate_request`], over files already read. +fn request_for(files: &[FileInput], target: &str, mode: &str) -> Result { + let Interpreted { + schemas, + declared, + context, + .. + } = interpret_project(files); if schemas.is_empty() { return Err("no schema parses".to_string()); } @@ -484,7 +516,7 @@ fn generate_request(files: JsValue, target: &str, mode: &str) -> Result Result Result Result { + let facts = comline_core::compat::facts_of_context(context, PACKAGE_VERSION); + // The same fields under the same names: the generator protocol's mirror, + // as the CLI converts it. + serde_json::to_value(&facts) + .and_then(serde_json::from_value) + .map_err(|e| format!("the package's facts: {e}")) +} + /// The shared pipeline behind [`compile_project`] and [`generate_project`]: /// build a `ProjectContext` from the cleanly-parsing files, then interpret each /// one with full project context (so `use` across files resolves) and validate /// it. /// -/// Returns the per-file reports and, separately, `(namespace-path, units)` for -/// every file that froze — the shape `comline-codegen` wants. -fn interpret_project( - files: &[FileInput], -) -> ( - CompileProjectResult, - Vec<(String, Vec)>, - Vec, -) { +/// The package's framing and handshake (its own, or core's defaults) are +/// frozen into every protocol that doesn't write one, as `comline build` +/// does, so the IR, the description and the generated code all show what +/// the wire runs. +fn interpret_project(files: &[FileInput]) -> Interpreted { let mut context = ProjectInterpreter::from_config_source(CONGREGATION).expect("static congregation parses"); + // Frozen as a build freezes it: its `id` is in the facts. + context.config_frozen = Some( + comline_core::package::config::ir::interpreter::interpret::interpret_context( + &context, None, + ) + .expect("static congregation interprets"), + ); // The encodings the package declares, for `encodings::fill`. The // congregation is in memory, so it declares none: core reads an // encoding's profile from the package directory. @@ -552,6 +607,8 @@ fn interpret_project( // First pass: parse everything, register the good ones on the context so // later files' `use` statements can see them. let mut parsed: Vec = Vec::with_capacity(files.len()); + // Where this package's own schema contexts start. + let own_contexts = context.schema_contexts.len(); for f in files { let segments = namespace_segments(&f.path); let pr = parser::parse(&f.source).expect("parser never errors internally"); @@ -574,13 +631,50 @@ fn interpret_project( }); } - // Second pass: interpret + validate each file against the whole context. + // Second pass: interpret each file against the whole context. + let frozen: Vec>> = parsed + .iter() + .map(|p| { + let decls = p.decls.clone()?; + let mut units = IncrementalInterpreter::from_declarations_with_context( + decls, + &p.segments, + &context, + ); + // Match `comline build`: a leading `Namespace` unit before validation. + units.insert(0, FrozenUnit::Namespace(p.segments.join("::"))); + Some(units) + }) + .collect(); + // The package's framing and handshake, into every protocol that doesn't + // write one: the handshake is one for the package, so all the files at + // once. + let mut frozen: Vec<(usize, (String, Vec))> = frozen + .into_iter() + .enumerate() + .filter_map(|(i, units)| Some((i, (String::new(), units?)))) + .collect(); + { + let mut all: Vec<(String, Vec)> = + frozen.iter_mut().map(|(_, s)| std::mem::take(s)).collect(); + apply_package_wire(&mut all, &declared_wire(CONGREGATION)); + for ((_, slot), schema) in frozen.iter_mut().zip(all) { + *slot = schema; + } + } + let mut frozen = frozen.into_iter().peekable(); + + // Third pass: validate each file, and report it. let mut reports = Vec::with_capacity(files.len()); let mut schemas = Vec::new(); - for (f, p) in files.iter().zip(parsed) { + for (i, (f, p)) in files.iter().zip(parsed).enumerate() { let namespace = p.segments.join("::"); - let Some(decls) = p.decls else { + let units = match frozen.peek() { + Some((at, _)) if *at == i => frozen.next().map(|(_, (_, units))| units), + _ => None, + }; + let Some(units) = units else { reports.push(FileReport { path: f.path.clone(), namespace, @@ -592,11 +686,6 @@ fn interpret_project( continue; }; - let mut units = - IncrementalInterpreter::from_declarations_with_context(decls, &p.segments, &context); - // Match `comline build`: a leading `Namespace` unit before validation. - units.insert(0, FrozenUnit::Namespace(namespace.clone())); - // `validate` reports warnings through its `Ok` arm now - a // deprecation, say. Showing those too matches what `comline build` // prints; only the `Err` arm means the schema would fail to build. @@ -628,7 +717,35 @@ fn interpret_project( schemas.push((p.segments.join("/"), units)); } - (CompileProjectResult { files: reports }, schemas, declared) + // Each parsed file's schema context holds what it froze, as a build's + // does, for the facts. + let mut parsed_contexts = context.schema_contexts[own_contexts..].iter(); + for (_, units) in &schemas { + if let Some(schema) = parsed_contexts.next() { + *schema.borrow().frozen_schema.borrow_mut() = Some(units.clone()); + } + } + + Interpreted { + report: CompileProjectResult { files: reports }, + schemas, + declared, + context, + } +} + +/// What [`interpret_project`] makes of the file set. +struct Interpreted { + /// Per file: diagnostics and IR. + report: CompileProjectResult, + /// `(namespace-path, units)` for every file that froze — the shape + /// `comline-codegen` wants. + schemas: Vec<(String, Vec)>, + /// The encodings the package declares. + declared: Vec, + /// The package as a build would hold it, each parsed file's schema + /// context with its frozen units. + context: ProjectContext, } /// `chat.ids` → `["chat"]`, `wire/frame.ids` → `["wire", "frame"]`. Falls back @@ -696,6 +813,36 @@ fn plain_error(message: String) -> Diagnostic { #[derive(Serialize)] struct ProjectShape { schemas: Vec, + /// The package's connection, when its protocols run on one. + #[serde(skip_serializing_if = "Option::is_none")] + connection: Option, +} + +/// `comline@2`'s parameters. A struct, not a map, so it crosses into JS as a +/// plain object. +#[derive(Serialize)] +struct Comline2ParamsShape { + scope: String, + newer_consumer: String, + same_version_differs: String, + exchange: String, +} + +/// The package's connection: what every protocol on it shares. +#[derive(Serialize)] +struct ConnectionShape { + /// Canonical: `datagram@3`, `datagram@2`, ... + framing: String, + /// Canonical: `comline@2`, `comline@1` or `none`. + handshake: String, + /// `comline@2`'s four parameters, each as written or its default. + #[serde(skip_serializing_if = "Option::is_none")] + params: Option, + /// Under `comline@2`: the `Hello` this package's ends send, hex, as the + /// generators embed it. Built from the facts of a first version, so its + /// numbers and lines are provisional, as a first build's are. + #[serde(skip_serializing_if = "Option::is_none")] + hello: Option, } #[derive(Serialize)] @@ -716,9 +863,15 @@ struct SchemaShape { #[derive(Serialize)] struct ProtocolShape { name: String, - /// `"datagram"` | `"jsonrpc"` — from the protocol's `@framing`, else the - /// datagram default. + /// `"datagram"` | `"datagram@2"` | `"datagram@3"` | `"jsonrpc"` — from the + /// protocol's `@framing`, else the package's (core's default, + /// `datagram@3`). framing: String, + /// The number its frames carry on the package connection: its wire + /// number from the facts under a framing that calls by number, else its + /// position in the package. + #[serde(skip_serializing_if = "Option::is_none")] + number: Option, functions: Vec, } @@ -727,6 +880,10 @@ struct FnShape { name: String, /// 0-based position in the protocol — the `Call` id `resolveKind` matches. index: u32, + /// What its call carries on the wire: its wire number under a framing + /// that calls by number (`datagram@3`), else its position. + #[serde(skip_serializing_if = "Option::is_none")] + call: Option, /// No `_return` at all — a fire-and-forget `notify`, not `Some(Unit)`. oneway: bool, args: Vec, @@ -813,9 +970,17 @@ enum TypeRef { pub fn describe_project(files: JsValue) -> JsValue { let files: Vec = match serde_wasm_bindgen::from_value(files) { Ok(f) => f, - Err(_) => return to_js(&ProjectShape { schemas: vec![] }), + Err(_) => { + return to_js(&ProjectShape { + schemas: vec![], + connection: None, + }) + } }; - let frozen = interpret_project(&files).1; + let frozen = interpret_project(&files).schemas; + // The request `comline generate` would build, for the facts and the + // connection; `None` while nothing parses. + let request = request_for(&files, "rust", "code").ok(); // Struct / enum names across the whole project, so a cross-file type // reference still classifies as `ref` (not an opaque scalar). @@ -830,11 +995,87 @@ pub fn describe_project(files: JsValue) -> JsValue { }) .collect(); - let schemas = frozen + let mut schemas: Vec = frozen .iter() .map(|(ns_path, units)| describe_schema(ns_path, units, &known)) .collect(); - to_js(&ProjectShape { schemas }) + let connection = request + .as_ref() + .and_then(|req| describe_connection(req, &mut schemas)); + to_js(&ProjectShape { + schemas, + connection, + }) +} + +/// The package connection of `req`, and each protocol's and call's numbers +/// on it in `schemas`, as the generators address them. +fn describe_connection( + req: &GenerateRequest, + schemas: &mut [SchemaShape], +) -> Option { + use comline_codegen::connections; + use comline_codegen::facts; + + for (ns_path, units) in &req.schemas { + let namespace = ns_path.replace('/', "::"); + for unit in units { + let FrozenUnit::Protocol { + name, + parameters, + functions, + .. + } = unit + else { + continue; + }; + let Ok(addressing) = facts::addressing( + req.facts.as_ref(), + &req.schemas, + &req.encodings, + ns_path, + name, + parameters, + functions, + ) else { + continue; + }; + let Some(shape) = schemas + .iter_mut() + .filter(|s| s.namespace == namespace) + .flat_map(|s| s.protocols.iter_mut()) + .find(|p| &p.name == name) + else { + continue; + }; + shape.number = Some(addressing.protocol); + for (f, call) in shape.functions.iter_mut().zip(addressing.calls) { + f.call = Some(call); + } + } + } + + let connection = connections::package_connection(&req.schemas).ok()??; + let comline2 = connection.handshake == "comline@2"; + let params = comline2.then(|| { + let p = facts::Comline2Params::of(&connection.handshake_value); + Comline2ParamsShape { + scope: p.scope, + newer_consumer: p.newer_consumer, + same_version_differs: p.same_version_differs, + exchange: p.exchange, + } + }); + let hello = comline2 + .then(|| facts::hello(req, &connection).ok()) + .flatten() + .map(|(bytes, _)| bytes.iter().map(|b| format!("{b:02x}")).collect()); + Some(ConnectionShape { + framing: connection.framing, + handshake: connection.handshake, + params, + hello, + }) } fn describe_schema(ns_path: &str, units: &[FrozenUnit], known: &HashSet<&str>) -> SchemaShape { @@ -893,6 +1134,7 @@ fn describe_schema(ns_path: &str, units: &[FrozenUnit], known: &HashSet<&str>) - } => Some(ProtocolShape { name: name.clone(), framing: framing_of(parameters), + number: None, functions: functions .iter() .enumerate() @@ -923,12 +1165,12 @@ fn describe_schema(ns_path: &str, units: &[FrozenUnit], known: &HashSet<&str>) - /// Read through core's `FramingValue`, so `"jsonrpc"` and /// `{ name = "jsonrpc", ... }` are the same framing here as everywhere. /// -/// A protocol that names none gets the package's framing, which core has -/// already written into it when the package declares one, else the -/// built-in default, `datagram@2`. +/// The package's framing, or core's default (`datagram@3`), is frozen into +/// every protocol that names none ([`interpret_project`]); an absent one is +/// what it has always meant, `datagram@2` (`IMPLICIT_FRAMING`). fn framing_of(params: &[FrozenUnit]) -> String { FramingValue::of_protocol(params) - .map_or(DEFAULT_FRAMING, |f| f.name) + .map_or(IMPLICIT_FRAMING, |f| f.name) .to_string() } @@ -968,6 +1210,7 @@ fn fn_shape( } => Some(FnShape { name: name.clone(), index, + call: None, oneway: _return.is_none(), args: arguments .iter() @@ -1336,7 +1579,7 @@ mod tests { path: "alias.ids".to_string(), source: "type Handle = string\n\nstruct Account {\n owner: Handle\n}\n".to_string(), }]; - let (_, frozen, _) = interpret_project(&files); + let frozen = interpret_project(&files).schemas; let known: HashSet<&str> = frozen .iter() .flat_map(|(_, units)| units.iter()) @@ -1370,8 +1613,122 @@ mod tests { } #[test] - fn no_framing_is_the_default_datagram2() { + fn no_framing_reads_as_the_implicit_datagram2() { assert_eq!(framing_of(&[]), "datagram@2"); assert_eq!(framing_of(&framing_param("datagram@2")), "datagram@2"); } + + fn chat() -> Vec { + vec![FileInput { + path: "chat.ids".to_string(), + source: "protocol Chat {\n function send(text: string) -> bool;\n function leave();\n}\n\n\ + protocol Presence {\n function ping();\n}\n" + .to_string(), + }] + } + + #[test] + fn a_package_taking_the_defaults_runs_datagram3_and_comline2() { + let interpreted = interpret_project(&chat()); + assert!( + interpreted.report.files[0].ok, + "{:?}", + interpreted.report.files[0].diagnostics + ); + let (_, units) = &interpreted.schemas[0]; + for unit in units { + if let FrozenUnit::Protocol { + name, parameters, .. + } = unit + { + assert_eq!(framing_of(parameters), "datagram@3", "{name}"); + assert_eq!( + comline_codegen::connections::handshake_name(parameters), + "comline@2", + "{name}" + ); + } + } + } + + #[test] + fn generating_a_default_package_carries_first_version_facts() { + for target in ["rust", "typescript"] { + let req = request_for(&chat(), target, "code").unwrap(); + let facts = req.facts.as_ref().expect("the default package needs facts"); + assert_eq!(facts.id.as_deref(), Some(PACKAGE_ID)); + assert_eq!(facts.version, PACKAGE_VERSION); + let numbers: Vec<(String, u16, Vec)> = facts + .protocols + .iter() + .map(|p| { + ( + p.name.clone(), + p.number, + p.functions.iter().map(|f| f.number).collect(), + ) + }) + .collect(); + assert_eq!( + numbers, + vec![ + ("Chat".to_string(), 0, vec![0, 1]), + ("Presence".to_string(), 1, vec![0]) + ], + "{facts:?}" + ); + let generated = match target { + "rust" => comline_codegen_rust::generate_rust(&req), + _ => comline_codegen_typescript::generate_typescript(&req), + }; + let files = generated.unwrap_or_else(|e| panic!("{target}: {e:#}")); + assert!(!files.is_empty(), "{target}"); + } + } + + #[test] + fn a_package_off_the_defaults_needs_no_facts() { + let files = vec![FileInput { + path: "rpc.ids".to_string(), + source: "@framing = \"jsonrpc\"\nprotocol Rpc {\n function ping();\n}\n".to_string(), + }]; + let req = request_for(&files, "rust", "code").unwrap(); + assert!(req.facts.is_none()); + comline_codegen_rust::generate_rust(&req).unwrap(); + } + + #[test] + fn the_description_carries_wire_numbers_and_the_comline2_hello() { + let req = request_for(&chat(), "rust", "code").unwrap(); + let frozen = interpret_project(&chat()).schemas; + let known = HashSet::new(); + let mut schemas: Vec = frozen + .iter() + .map(|(ns, units)| describe_schema(ns, units, &known)) + .collect(); + let connection = describe_connection(&req, &mut schemas).expect("a package connection"); + assert_eq!( + (connection.framing.as_str(), connection.handshake.as_str()), + ("datagram@3", "comline@2") + ); + assert_eq!(connection.params.as_ref().unwrap().exchange, "offer"); + let hello = connection.hello.expect("a comline@2 hello"); + assert!( + hello.starts_with("434f0201"), + "the Hello message's magic, version and type: {hello}" + ); + assert!(hello.contains(PACKAGE_ID), "{hello}"); + + let shape = serde_json::to_value(&schemas[0]).unwrap(); + assert_eq!(shape["protocols"][0]["framing"], "datagram@3"); + assert_eq!(shape["protocols"][0]["number"], 0); + assert_eq!(shape["protocols"][1]["number"], 1); + let calls: Vec<_> = shape["protocols"][0]["functions"] + .as_array() + .unwrap() + .iter() + .map(|f| f["call"].clone()) + .collect(); + assert_eq!(calls, vec![serde_json::json!(0), serde_json::json!(1)]); + } }