From 92e01551342d8980a0446d52c6bc2c1cb4495155 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 17:32:19 -0800 Subject: [PATCH 1/9] chore(quest): claim quest/m1/ffi-export/api-lock.md Quest-Claim: 7212b0b336da742c From 2c7d8226df7f2e675b4d662496c4d948a17c7777 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 18:00:07 -0800 Subject: [PATCH 2/9] feat(ffi): an API lock, --baseline, that fails the export on a break Co-Authored-By: Claude Opus 5.5 --- ffi/Cargo.lock | 4 + ffi/README.md | 34 +- ffi/fixtures/lock/Cargo.toml | 21 ++ ffi/fixtures/lock/expected.txt | 10 + ffi/fixtures/lock/ffi.toml | 2 + ffi/fixtures/lock/src/lib.rs | 138 ++++++++ ffi/src/cli.rs | 28 +- ffi/src/config.rs | 2 + ffi/src/driver.rs | 65 +++- ffi/src/lock.rs | 507 ++++++++++++++++++++++++++++++ ffi/src/main.rs | 1 + ffi/src/merge.rs | 38 ++- ffi/tests/fixtures.rs | 74 ++++- quest/m1/ffi-export/README.md | 5 +- quest/m1/ffi-export/api-lock.md | 44 --- quest/m1/ffi-export/lock-names.md | 25 ++ quest/m1/ffi-export/ship.md | 1 - 17 files changed, 907 insertions(+), 92 deletions(-) create mode 100644 ffi/fixtures/lock/Cargo.toml create mode 100644 ffi/fixtures/lock/expected.txt create mode 100644 ffi/fixtures/lock/ffi.toml create mode 100644 ffi/fixtures/lock/src/lib.rs create mode 100644 ffi/src/lock.rs delete mode 100644 quest/m1/ffi-export/api-lock.md create mode 100644 quest/m1/ffi-export/lock-names.md diff --git a/ffi/Cargo.lock b/ffi/Cargo.lock index e53575e96..1cb9dbf51 100644 --- a/ffi/Cargo.lock +++ b/ffi/Cargo.lock @@ -183,6 +183,10 @@ version = "0.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae" +[[package]] +name = "lock-fixture" +version = "0.0.0" + [[package]] name = "memchr" version = "2.8.3" diff --git a/ffi/README.md b/ffi/README.md index 60386f2f6..5f7410431 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -5,7 +5,7 @@ attributes in the Rust source. Every language's generator but Python's builds on the C ABI. ```bash -rust2-ffi --config ffi.toml (--out dir | --census dir | --api file) [--manifest-path Cargo.toml] [--target triple]... [--with file]... [-- cargo args] +rust2-ffi --config ffi.toml (--out dir | --census dir | --api file) [--manifest-path Cargo.toml] [--target triple]... [--with file]... [--baseline api.json] [-- cargo args] ``` It runs `cargo check` on the package with itself as `RUSTC_WRAPPER`, for each `--target` @@ -184,6 +184,34 @@ package, features, and `exclude`, from the same sources: a staged span's file is to the workspace's root or cargo's home, so a checkout at another path keeps it, and is dropped for the other target's span where the file differs. +## The API lock + +Each export writes its API, merged across every target it serves, to `api.json` in `--out`, +in the format `--api` writes. `--baseline file` fails the export, writing nothing, where its +API breaks the one in `file`, with an error at each item that names how: + +- an item removed, or no longer on one of the baseline's targets, and a target the baseline + serves that the export does not; +- a function's receiver, parameter, return, error, or asyncness changed, a constant's type + changed, a trait method added or changed, or a trait impl such as `Clone` dropped; +- a record's or variant's field added, removed, moved, or of another type, a variant + removed or of another value, or one added to an enum another crate matches exhaustively; +- a C name that now names another item: since a name depends on every item exported + ([The C ABI](#the-c-abi)), adding `audio::encoder_finish` renames `audio_encoder::finish` + to `moq_audio_encoder_finish_`, and a C caller of the old name would call the new item. + +An item is known by its kind and Rust path, as `exclude` names it. An addition passes: a new +item, method, trait impl, or a variant of a `#[non_exhaustive]` enum. A constant's value and +an item's docs may change. The check runs once, on the API every language is generated from; +it covers C's names, while a language's own names for a clash its generator renames are not +compared. + +The baseline is a lockfile, not config: the consumer commits it beside `Cargo.lock`, the +export reads it only to compare, and the export is the same with or without it. To accept a +break, export without `--baseline` and commit the `api.json` it writes. Its spans are relative +to the workspace and cargo's home, as a staged API's are, so a removed item's error points +where it was while its file is unchanged. + ## The C ABI - **Handles** are `Arc`s, and a call borrows the value as Rust's receiver or parameter @@ -940,6 +968,10 @@ build must fail its contract check. The `target` test exports a package for the binding, which builds for each, and staged with `--api` and `--with`; a build for a target not exported fails, and items that differ between the two are refused, naming both. The `reject` fixture's expected errors, each with its notes, are `fixtures/reject/expected.txt`. +The `lock` test exports the `lock` fixture for wasm32, staged, and the host, then again +against that export's `api.json`: its `added` feature only adds and must pass, and its `next` +feature breaks the API twice for each kind of break, once in an item only wasm32 has, each +error matching `fixtures/lock/expected.txt`. moq's crates export through `target/moq-ffi`, an empty library on each that `just ffi moq` writes in place of moq-ffi's remainder. `moq/moq.c` publishes and subscribes to a moq-net track in one process, polling each read, scopes an origin to moq-pattern's patterns and diff --git a/ffi/fixtures/lock/Cargo.toml b/ffi/fixtures/lock/Cargo.toml new file mode 100644 index 000000000..b7d05e18d --- /dev/null +++ b/ffi/fixtures/lock/Cargo.toml @@ -0,0 +1,21 @@ +[package] +name = "lock-fixture" +description = "An API whose features break it, or add to it, against the baseline exported without them" +version = "0.0.0" +edition = "2024" +license = "MIT OR Apache-2.0" +publish = false + +# The export's prefix. +[lib] +name = "lock" + +[features] +# Breaks the API twice for each kind of break: a C name another item takes, an item +# removed, a signature changed, a field changed, and a variant changed. +next = [] +# Adds to the API, which the baseline lets pass. +added = [] + +[lints] +workspace = true diff --git a/ffi/fixtures/lock/expected.txt b/ffi/fixtures/lock/expected.txt new file mode 100644 index 000000000..f7b58e9b5 --- /dev/null +++ b/ffi/fixtures/lock/expected.txt @@ -0,0 +1,10 @@ +fixtures/lock/src/lib.rs:106:1: rust2-ffi: the API breaks the baseline at enum `lock::Mode`: variant `Idle` is added to an exhaustive enum +fixtures/lock/src/lib.rs:113:1: rust2-ffi: the API breaks the baseline at enum `lock::Shape`: variant `Circle`'s field `0`'s type changed +fixtures/lock/src/lib.rs:21:2: rust2-ffi: the API breaks the baseline at const `lock::limits_max::RATE`: its C name `LOCK_LIMITS_MAX_RATE` is now `LOCK_LIMITS_MAX_RATE_`, and `LOCK_LIMITS_MAX_RATE` names const `lock::limits::MAX_RATE` +fixtures/lock/src/lib.rs:30:1: rust2-ffi: the API breaks the baseline at fn `lock::removed`: it is removed +fixtures/lock/src/lib.rs:36:1: rust2-ffi: the API breaks the baseline at fn `lock::portable`: it is no longer on wasm32-unknown-unknown +fixtures/lock/src/lib.rs:46:1: rust2-ffi: the API breaks the baseline at fn `lock::scale`: its parameter `x`'s type; its return type +fixtures/lock/src/lib.rs:66:2: rust2-ffi: the API breaks the baseline at fn `lock::Meter::add`: its parameter `n`'s type +fixtures/lock/src/lib.rs:7:2: rust2-ffi: the API breaks the baseline at fn `lock::audio_encoder::finish`: its C name `lock_audio_encoder_finish` is now `lock_audio_encoder_finish_`, and `lock_audio_encoder_finish` names fn `lock::audio::encoder_finish` +fixtures/lock/src/lib.rs:86:1: rust2-ffi: the API breaks the baseline at struct `lock::Size`: field `depth` is added, which every value must now give +fixtures/lock/src/lib.rs:94:1: rust2-ffi: the API breaks the baseline at struct `lock::Canvas`: field `width`'s type changed diff --git a/ffi/fixtures/lock/ffi.toml b/ffi/fixtures/lock/ffi.toml new file mode 100644 index 000000000..fd1aea94b --- /dev/null +++ b/ffi/fixtures/lock/ffi.toml @@ -0,0 +1,2 @@ +# Nothing left out. +exclude = [] diff --git a/ffi/fixtures/lock/src/lib.rs b/ffi/fixtures/lock/src/lib.rs new file mode 100644 index 000000000..6c98f6047 --- /dev/null +++ b/ffi/fixtures/lock/src/lib.rs @@ -0,0 +1,138 @@ +//! An API exported for the host and wasm32, whose `next` feature breaks it in pairs and +//! whose `added` feature only adds to it. + +/// Its C name, `lock_audio_encoder_finish`, is taken by `audio::encoder_finish` in `next`, +/// which comes first by path. +pub mod audio_encoder { + pub fn finish(level: u32) -> u32 { + level + } +} + +#[cfg(feature = "next")] +pub mod audio { + pub fn encoder_finish(level: u32) -> u32 { + level + 1 + } +} + +/// `LOCK_LIMITS_MAX_RATE`, which `limits::MAX_RATE` takes in `next`. +pub mod limits_max { + pub const RATE: u32 = 60; +} + +#[cfg(feature = "next")] +pub mod limits { + pub const MAX_RATE: u32 = 30; +} + +#[cfg(not(feature = "next"))] +pub fn removed() -> u32 { + 1 +} + +/// Not on wasm32 in `next`. +#[cfg(any(not(feature = "next"), not(target_arch = "wasm32")))] +pub fn portable() -> u32 { + 2 +} + +#[cfg(not(feature = "next"))] +pub fn scale(x: u32) -> u32 { + x * 2 +} + +#[cfg(feature = "next")] +pub fn scale(x: u64) -> u64 { + x * 2 +} + +#[cfg_attr(feature = "added", derive(Clone))] +pub struct Meter { + total: u64, +} + +impl Meter { + pub fn new() -> Self { + Self { total: 0 } + } + + #[cfg(not(feature = "next"))] + pub fn add(&mut self, n: u32) { + self.total += u64::from(n); + } + + #[cfg(feature = "next")] + pub fn add(&mut self, n: u16) { + self.total += u64::from(n); + } + + #[cfg(feature = "added")] + pub fn reset(&mut self) { + self.total = 0; + } + + pub fn total(&self) -> u64 { + self.total + } +} + +impl Default for Meter { + fn default() -> Self { + Self::new() + } +} + +pub struct Size { + pub width: u32, + #[cfg(feature = "next")] + pub depth: u32, +} + +/// Only wasm32's API has it, so only the staged target's API breaks. +#[cfg(target_arch = "wasm32")] +pub struct Canvas { + #[cfg(not(feature = "next"))] + pub width: u32, + #[cfg(feature = "next")] + pub width: u64, +} + +#[cfg(target_arch = "wasm32")] +pub fn canvas(width: u32) -> Canvas { + Canvas { width: width.into() } +} + +pub enum Mode { + Fast, + Slow, + #[cfg(feature = "next")] + Idle, +} + +pub enum Shape { + #[cfg(not(feature = "next"))] + Circle(u32), + #[cfg(feature = "next")] + Circle(f64), +} + +#[non_exhaustive] +pub enum Level { + Low, + #[cfg(feature = "added")] + High, +} + +pub fn pick(mode: Mode, shape: Shape, size: Size, level: Level) -> u32 { + let _ = (shape, size, level); + match mode { + Mode::Fast => 1, + _ => 0, + } +} + +#[cfg(feature = "added")] +pub fn extra() -> u32 { + 3 +} diff --git a/ffi/src/cli.rs b/ffi/src/cli.rs index 36b119d12..1e86cd90c 100644 --- a/ffi/src/cli.rs +++ b/ffi/src/cli.rs @@ -8,7 +8,7 @@ use rust2_driver::cargo::{Args, Check, Output}; use crate::config::{self, Config}; -const USAGE: &str = "usage: rust2-ffi --config (--out | --census | --api ) [--manifest-path ] [--target ]... [--with ]... [-- ] +const USAGE: &str = "usage: rust2-ffi --config (--out | --census | --api ) [--manifest-path ] [--target ]... [--with ]... [--baseline ] [-- ] Exports the pub API of the package's library, following its `pub use` re-exports into other crates, as one library: a crate in that builds the C ABI, with its C header @@ -25,6 +25,12 @@ alone. --api writes one target's API to instead of exporting, for an export on another host, whose C toolchain the check of a target may need, to add with --with . +Each export writes its API, of every target it serves, to /api.json. --baseline +fails the export where its API breaks the one an earlier export wrote there: an item +removed, or no longer on a target; a signature, field, or variant changed; or a C name +that now names another item. Commit api.json beside Cargo.lock as the baseline, and +replace it to accept a break. + --census writes a Markdown report, /.md, of what exports and of every construct the export refuses, instead of exporting."; @@ -55,6 +61,9 @@ fn try_run(args: &[String]) -> Result { (Output::Dir(_), Some(api)) => (config::env::API, api), (Output::Census(_), Some(_)) => return Err(format!("--api and --census are each an output\n\n{USAGE}")), }; + if output.0 != config::env::OUT && own.baseline.is_some() { + return Err(format!("--baseline checks an export: give it with --out\n\n{USAGE}")); + } if output.0 != config::env::OUT && (targets.len() > 1 || !own.with.is_empty()) { return Err(format!( "--census and --api write one target's: give at most one --target and no --with\n\n{USAGE}" @@ -72,7 +81,8 @@ fn try_run(args: &[String]) -> Result { let workspace = rust2_driver::cargo::workspace_root(Some(&args.manifest))?; let roots = std::env::join_paths(std::iter::once(workspace).chain(cargo_home)) .map_err(|err| format!("joining the roots of spans: {err}"))?; - let check = |target: &str, output: (&str, &std::ffi::OsStr), merge: &std::ffi::OsStr| { + let baseline = own.baseline.unwrap_or_default(); + let check = |target: &str, output: (&str, &std::ffi::OsStr), merge: &std::ffi::OsStr, baseline: &Path| { Check { tool: "rust2-ffi", manifest: &args.manifest, @@ -86,6 +96,7 @@ fn try_run(args: &[String]) -> Result { (config::env::PACKAGE, line.as_ref()), (config::env::PATCH, patch.as_ref()), (config::env::MERGE, merge), + (config::env::BASELINE, baseline.as_os_str()), (config::env::ROOTS, roots.as_ref()), output, ], @@ -100,14 +111,14 @@ fn try_run(args: &[String]) -> Result { let mut merge = own.with.clone(); for target in rest { let staged = crate::merge::staged(&stage, target); - let code = check(target, (config::env::API, staged.as_os_str()), "".as_ref())?; + let code = check(target, (config::env::API, staged.as_os_str()), "".as_ref(), "".as_ref())?; if code != ExitCode::SUCCESS { return Ok(code); } merge.push(staged); } let merge = std::env::join_paths(&merge).map_err(|err| format!("joining the paths to merge: {err}"))?; - check(last, (output.0, output.1.as_os_str()), &merge) + check(last, (output.0, output.1.as_os_str()), &merge, &baseline) }; let code = run(); if stage.exists() { @@ -193,6 +204,8 @@ struct Own { with: Vec, /// `--api`: write the target's API here instead of exporting. api: Option, + /// `--baseline`: the API an earlier export wrote, which this one's must not break. + baseline: Option, } impl Own { @@ -203,12 +216,13 @@ impl Own { targets: Vec::new(), with: Vec::new(), api: None, + baseline: None, }; let mut rest = Vec::new(); let mut args = args.iter(); while let Some(arg) = args.next() { let flag = arg.as_str(); - if !matches!(flag, "--target" | "--with" | "--api") { + if !matches!(flag, "--target" | "--with" | "--api" | "--baseline") { // The cargo args, and the rest after them, are cargo's. if flag == "--" { rest.push(arg.clone()); @@ -227,6 +241,10 @@ impl Own { } "--target" => own.targets.push(value.clone()), "--with" => own.with.push(absolute(value)?), + "--baseline" if own.baseline.is_some() => { + return Err(format!("--baseline is given twice\n\n{USAGE}")); + } + "--baseline" => own.baseline = Some(absolute(value)?), _ if own.api.is_some() => return Err(format!("--api is given twice\n\n{USAGE}")), _ => { let api = absolute(value)?; diff --git a/ffi/src/config.rs b/ffi/src/config.rs index bc274c43a..0363f3452 100644 --- a/ffi/src/config.rs +++ b/ffi/src/config.rs @@ -83,6 +83,8 @@ pub mod env { /// The file to write the target's API into instead of exporting, absolute, for the /// export of several targets to merge. pub const API: &str = "RUST2_FFI_API"; + /// The API an earlier export wrote, absolute, which the export's must not break. + pub const BASELINE: &str = "RUST2_FFI_BASELINE"; /// The other targets' APIs the export merges with its own, as a list of paths. pub const MERGE: &str = "RUST2_FFI_MERGE"; /// The directories a staged API's spans are relative to, as a list of paths: the diff --git a/ffi/src/driver.rs b/ffi/src/driver.rs index 27c89442d..0dd5a665b 100644 --- a/ffi/src/driver.rs +++ b/ffi/src/driver.rs @@ -19,7 +19,6 @@ use rustc_span::{FileName, Span, sym}; use crate::abi::Abi; use crate::config::{self, Config}; -use crate::ir::Api; use crate::{census, collect, glue, merge}; /// Run as rustc, with `args` as cargo passed them: the wrapped rustc's path first. @@ -42,6 +41,9 @@ pub fn run(args: Vec) -> ExitCode { }) } +/// The file in the export that holds its API, which `--baseline` reads back. +pub const API_FILE: &str = "api.json"; + /// Compiles the facade, exporting its API after analysis. struct Export { config: Config, @@ -55,6 +57,8 @@ struct Export { merge: Vec, /// The directories a staged API's spans are relative to. roots: Vec, + /// The API an earlier export wrote, which this one's must not break. + baseline: Option, } /// What the job writes. @@ -112,6 +116,9 @@ impl Export { .map(str::to_string) .collect(); let patch = std::env::var(config::env::PATCH).map_err(|_| format!("{} is unset", config::env::PATCH))?; + let baseline = std::env::var_os(config::env::BASELINE) + .filter(|p| !p.is_empty()) + .map(PathBuf::from); Ok(Some(Self { config, output, @@ -119,6 +126,7 @@ impl Export { patch, merge, roots, + baseline, })) } } @@ -175,8 +183,8 @@ impl Callbacks for Export { Output::Api(_) if tcx.dcx().has_errors().is_some() => Ok(()), Output::Api(path) => target.write(path, tcx.sess.source_map(), &self.roots), Output::Dir(out) => match self.merged(tcx, target) { - Some(api) => self.export(tcx, &api, out), - None => Ok(()), + Some(api) if self.locked(tcx, &api) => self.export(tcx, api, out), + _ => Ok(()), }, }; if let Err(err) = written { @@ -189,11 +197,11 @@ impl Callbacks for Export { impl Export { /// This target's API merged with the other targets', or none once a difference /// between two of them is an error. - fn merged(&self, tcx: TyCtxt<'_>, ours: merge::Target) -> Option { + fn merged(&self, tcx: TyCtxt<'_>, ours: merge::Target) -> Option { if self.merge.is_empty() { - return Some(ours.api); + return Some(ours); } - let mut apis = vec![ours.api]; + let mut apis = vec![ours.api.clone()]; let mut unmergeable = false; for path in &self.merge { let theirs = match merge::Target::read(path, tcx.sess.source_map(), &self.roots) { @@ -260,11 +268,49 @@ impl Export { }; err.emit(); } - differs.is_empty().then_some(api) + differs.is_empty().then_some(merge::Target { api, ..ours }) + } + + /// Whether `ours` keeps the baseline's API, if there is one, emitting each break of it. + fn locked(&self, tcx: TyCtxt<'_>, ours: &merge::Target) -> bool { + let Some(path) = &self.baseline else { + return true; + }; + let base = match merge::Target::read(path, tcx.sess.source_map(), &self.roots) { + Ok(base) => base, + Err(err) => { + tcx.dcx().err(format!("rust2-ffi: the baseline: {err}")); + return false; + } + }; + if base.package != ours.package { + tcx.dcx().err(format!( + "rust2-ffi: the baseline {} is package `{}`'s API, not `{}`'s", + path.display(), + base.package, + ours.package + )); + return false; + } + let breaks = crate::lock::breaks(&base.api, &ours.api, &self.facade.lib); + let help = format!( + "to accept the break, export without --baseline and replace {} with the export's {API_FILE}", + path.display() + ); + for b in &breaks { + let what = format!("rust2-ffi: the API breaks the baseline at {}", b.what); + let err = match b.span.is_dummy() { + true => tcx.dcx().struct_err(what), + false => tcx.dcx().struct_span_err(b.span, what), + }; + err.with_help(help.clone()).emit(); + } + breaks.is_empty() } /// Write the export of `api` into `out`, or fail on two items that share a C name. - fn export(&self, tcx: TyCtxt<'_>, api: &Api, out: &Path) -> Result<(), String> { + fn export(&self, tcx: TyCtxt<'_>, target: merge::Target, out: &Path) -> Result<(), String> { + let api = &target.api; let abi = Abi::new(api, &self.facade.lib); for (name, (first, first_span), (second, second_span)) in &abi.clashes { tcx.dcx() @@ -289,7 +335,8 @@ impl Export { facade: &self.facade, patch: &self.patch, }; - glue.write(out) + glue.write(out)?; + target.write(&out.join(API_FILE), tcx.sess.source_map(), &self.roots) } } diff --git a/ffi/src/lock.rs b/ffi/src/lock.rs new file mode 100644 index 000000000..00c53ca17 --- /dev/null +++ b/ffi/src/lock.rs @@ -0,0 +1,507 @@ +//! The API lock: the export's API checked against a baseline an earlier export wrote, so a +//! break of it fails the export once, in the API every binding is generated from, rather +//! than once per language. +//! +//! An item is known by its kind and Rust path, as the config names it. One the baseline has +//! that the export lacks, or has on fewer of the baseline's targets, is removed; one whose +//! signature, fields, or variants differ is changed; and one whose C name differs is renamed, +//! as an item added beside it makes it when their names clash, since a C caller of the old +//! name then calls the new item. An addition passes: a new item, method, trait impl, or a +//! variant of an enum another crate cannot match exhaustively. + +use std::collections::BTreeMap; + +use rustc_span::{DUMMY_SP, Span}; + +use crate::abi::{Abi, Ty}; +use crate::ir::{Access, Api, Constant, Function, Literal, On, Traits}; +use crate::merge::{self, Maps}; + +/// An item the export's API breaks the baseline's at: where, and how. +pub struct Break { + /// The item's span in the export, or the baseline's if the export lacks it, or none. + pub span: Span, + /// The item, then each way it breaks. + pub what: String, +} + +/// Every break of `base`, the baseline, by `now`, the export's API, both prefixed `prefix`. +pub fn breaks(base: &Api, now: &Api, prefix: &str) -> Vec { + let base = Index::new(base, prefix); + let now = Index::new(now, prefix); + let mut breaks = Vec::new(); + let dropped: Vec<&String> = base + .api + .targets + .iter() + .filter(|t| !now.api.targets.contains(t)) + .collect(); + for target in &dropped { + breaks.push(Break { + span: DUMMY_SP, + what: format!("target `{target}`: the export no longer serves it; give it as a --target"), + }); + } + let maps = base.maps(&now); + for (key, ours) in &base.entries { + let Some(theirs) = now.entries.get(key) else { + let mut what = format!("{}: it is removed", ours.what); + if let Some(other) = now.named(&ours.c) { + what += &format!(", and its C name `{}` names {}", ours.c, other.what); + } + // Where it was, else the type it was a member of. + let span = match ours.span.is_dummy() { + false => ours.span, + true => (ours.owner.as_ref().and_then(|owner| now.entries.get(owner))).map_or(DUMMY_SP, |o| o.span), + }; + breaks.push(Break { span, what }); + continue; + }; + let mut changes = Vec::new(); + let lost: Vec<&str> = (base.api.named(ours.on).into_iter()) + .filter(|t| now.api.targets.iter().any(|n| n == t)) + .filter(|t| !now.api.named(theirs.on).contains(t)) + .collect(); + if !lost.is_empty() { + changes.push(format!("it is no longer on {}", lost.join(", "))); + } + changes.extend(changed(&base, &now, &maps, &ours.item, &theirs.item)); + if ours.c != theirs.c { + let mut renamed = format!("its C name `{}` is now `{}`", ours.c, theirs.c); + if let Some(other) = now.named(&ours.c) { + renamed += &format!(", and `{}` names {}", ours.c, other.what); + } + changes.push(renamed); + } + if !changes.is_empty() { + breaks.push(Break { + span: theirs.span, + what: format!("{}: {}", ours.what, changes.join("; ")), + }); + } + } + breaks +} + +/// An item of an API. +#[derive(Clone, Copy)] +enum Item<'a> { + Record(usize), + Enum(usize), + Object(usize), + Callback(usize), + Function(&'a Function), + Constant(&'a Constant), +} + +struct Entry<'a> { + item: Item<'a>, + /// How an error names it, such as ``fn `moq::track::Producer::append` ``. + what: String, + /// Its C name, the one every other is made from. + c: String, + span: Span, + on: On, + /// A method's type's key. + owner: Option, +} + +/// An API's items, each by its key: its kind and Rust path with its instance's arguments. +struct Index<'a> { + api: &'a Api, + entries: BTreeMap>, +} + +impl<'a> Index<'a> { + fn new(api: &'a Api, prefix: &str) -> Self { + let abi = Abi::new(api, prefix); + let mut entries = BTreeMap::new(); + let shown = |shown: &[String]| shown.join("::"); + let mut types = Vec::new(); + for (i, r) in api.records.iter().enumerate() { + types.push(( + Item::Record(i), + "struct", + &r.shown, + abi.record(i), + r.span, + r.on, + &r.methods, + )); + } + for (i, e) in api.enums.iter().enumerate() { + types.push(( + Item::Enum(i), + "enum", + &e.shown, + abi.enumeration(i), + e.span, + e.on, + &e.methods, + )); + } + for (i, o) in api.objects.iter().enumerate() { + types.push(( + Item::Object(i), + "type", + &o.shown, + abi.object(i), + o.span, + o.on, + &o.methods, + )); + } + for (item, kind, path, c, span, on, methods) in types { + let key = type_key(path); + // A method's C name goes through its type's, as the C header declares it. + let owner = match item { + Item::Record(_) => Ty::Struct(c.clone()), + Item::Enum(i) if api.enums[i].plain() => Ty::Enum(c.clone()), + Item::Enum(_) => Ty::Struct(c.clone()), + _ => Ty::Handle { + name: c.clone(), + constant: false, + }, + }; + for method in methods { + let c = abi.export(method, Some(&owner)).call.name; + entries.insert(function_key(method), Entry::function(method, c, Some(key.clone()))); + } + let what = format!("{kind} `{}`", shown(path)); + entries.insert( + key, + Entry { + item, + what, + c, + span, + on, + owner: None, + }, + ); + } + for (i, callback) in api.callbacks.iter().enumerate() { + let entry = Entry { + item: Item::Callback(i), + what: format!("trait `{}`", shown(&callback.path)), + c: abi.callback(i), + span: callback.span, + on: callback.on, + owner: None, + }; + entries.insert(type_key(&callback.path), entry); + } + for function in &api.functions { + let c = abi.export(function, None).call.name; + entries.insert(function_key(function), Entry::function(function, c, None)); + } + for constant in &api.constants { + let entry = Entry { + item: Item::Constant(constant), + what: format!("const `{}`", shown(&constant.path)), + c: abi.constant(&constant.path), + span: constant.span, + on: constant.on, + owner: None, + }; + entries.insert(format!("const {}", shown(&constant.path)), entry); + } + Self { api, entries } + } + + /// The item whose C name is `c`. + fn named(&self, c: &str) -> Option<&Entry<'a>> { + self.entries.values().find(|entry| entry.c == c) + } + + /// Where each of this API's types lands among `now`'s, by key, or past every index + /// `now` has, each apart, for one it lacks or has as another kind. + fn maps(&self, now: &Index<'_>) -> Maps { + let mut missing = usize::MAX; + let mut at = |key: String, kind: fn(&Item<'_>) -> Option| { + (now.entries.get(&key).and_then(|entry| kind(&entry.item))).unwrap_or_else(|| { + missing -= 1; + missing + }) + }; + let api = self.api; + let record = |item: &Item<'_>| match item { + Item::Record(i) => Some(*i), + _ => None, + }; + let enumeration = |item: &Item<'_>| match item { + Item::Enum(i) => Some(*i), + _ => None, + }; + let object = |item: &Item<'_>| match item { + Item::Object(i) => Some(*i), + _ => None, + }; + let callback = |item: &Item<'_>| match item { + Item::Callback(i) => Some(*i), + _ => None, + }; + Maps { + records: api.records.iter().map(|r| at(type_key(&r.shown), record)).collect(), + enums: api.enums.iter().map(|e| at(type_key(&e.shown), enumeration)).collect(), + objects: api.objects.iter().map(|o| at(type_key(&o.shown), object)).collect(), + callbacks: api.callbacks.iter().map(|c| at(type_key(&c.path), callback)).collect(), + } + } +} + +impl<'a> Entry<'a> { + fn function(function: &'a Function, c: String, owner: Option) -> Self { + let what = match function.access { + Access::Field { set: false, .. } => "field", + Access::Field { set: true, .. } => "setter of field", + _ => "fn", + }; + Self { + item: Item::Function(function), + what: format!("{what} `{}`", function.shown.join("::")), + c, + span: function.span, + on: function.on, + owner, + } + } +} + +/// A type's key: one for every kind, so a type that becomes another kind is changed. +fn type_key(path: &[String]) -> String { + format!("type {}", path.join("::")) +} + +fn function_key(function: &Function) -> String { + let kind = match function.access { + Access::Field { set: false, .. } => "get", + Access::Field { set: true, .. } => "set", + _ => "fn", + }; + format!("{kind} {}", function.shown.join("::")) +} + +/// How `ours`, of the baseline, and `theirs`, of the export, both of one key, differ, with +/// the baseline's types mapped by `maps` to the export's. +fn changed(base: &Index<'_>, now: &Index<'_>, maps: &Maps, ours: &Item<'_>, theirs: &Item<'_>) -> Vec { + let (b, n) = (base.api, now.api); + let mut changes = Vec::new(); + let mut traits = |ours: Traits, theirs: Traits| { + let lost: Vec<&str> = [ + ("Clone", ours.clone && !theirs.clone), + ("PartialEq", ours.eq && !theirs.eq), + ("Display", ours.display && !theirs.display), + ("Debug", ours.debug && !theirs.debug), + ("Default", ours.default && !theirs.default), + ] + .into_iter() + .filter_map(|(name, lost)| lost.then_some(name)) + .collect(); + if !lost.is_empty() { + changes.push(format!("it no longer implements {}", lost.join(", "))); + } + }; + match (*ours, *theirs) { + (Item::Record(i), Item::Record(j)) => { + traits(b.records[i].traits, n.records[j].traits); + let mut ours = merge::bare_record(&b.records[i]); + maps.fields(&mut ours.fields); + maps.types(&mut ours.args); + let mut theirs = merge::bare_record(&n.records[j]); + (ours.traits, theirs.traits) = (Traits::default(), Traits::default()); + if ours.fields != theirs.fields { + changes.extend(fields("field", &ours.fields, &theirs.fields)); + } + (ours.fields, theirs.fields) = (Vec::new(), Vec::new()); + if ours != theirs { + changes.push("how it exports".to_string()); + } + } + (Item::Enum(i), Item::Enum(j)) => { + let (e, f) = (&b.enums[i], &n.enums[j]); + traits(e.traits, f.traits); + if e.exhaustive && !f.exhaustive { + changes.push("it is now `#[non_exhaustive]`".to_string()); + } + for variant in &e.variants { + let Some(other) = f.variants.iter().find(|v| v.name == variant.name) else { + changes.push(format!("variant `{}` is removed", variant.name)); + continue; + }; + let mut ours = merge::bare_variant(variant); + maps.fields(&mut ours.fields); + let theirs = merge::bare_variant(other); + if ours.fields != theirs.fields { + let what = format!("variant `{}`'s field", variant.name); + changes.extend(fields(&what, &ours.fields, &theirs.fields)); + } else if ours != theirs { + changes.push(format!("variant `{}` changed", variant.name)); + } + if e.plain() && f.plain() && variant.discriminant != other.discriminant { + changes.push(format!( + "variant `{}`'s value {} is now {}", + variant.name, variant.discriminant, other.discriminant + )); + } + let lost: Vec<&str> = (b.named(variant.on).into_iter()) + .filter(|t| n.targets.iter().any(|n| n == t) && !n.named(other.on).contains(t)) + .collect(); + if !lost.is_empty() { + changes.push(format!( + "variant `{}` is no longer on {}", + variant.name, + lost.join(", ") + )); + } + } + // Another crate matching an exhaustive enum has no arm for a new variant. + if e.exhaustive { + for variant in f + .variants + .iter() + .filter(|v| !e.variants.iter().any(|o| o.name == v.name)) + { + changes.push(format!("variant `{}` is added to an exhaustive enum", variant.name)); + } + } + let mut ours = merge::bare_enum(e); + maps.types(&mut ours.args); + let mut theirs = merge::bare_enum(f); + for e in [&mut ours, &mut theirs] { + e.traits = Traits::default(); + e.exhaustive = false; + } + if ours != theirs { + changes.push("how it exports".to_string()); + } + } + (Item::Object(i), Item::Object(j)) => { + traits(b.objects[i].traits, n.objects[j].traits); + let mut ours = merge::bare_object(&b.objects[i]); + maps.types(&mut ours.args); + let mut theirs = merge::bare_object(&n.objects[j]); + (ours.traits, theirs.traits) = (Traits::default(), Traits::default()); + if ours != theirs { + changes.push("how it exports".to_string()); + } + } + (Item::Callback(i), Item::Callback(j)) => { + let mut ours = merge::bare_callback(&b.callbacks[i]); + maps.functions(&mut ours.methods); + let theirs = merge::bare_callback(&n.callbacks[j]); + let names = |methods: &[Function]| methods.iter().map(|m| m.name().to_string()).collect::>(); + for method in &ours.methods { + match theirs.methods.iter().find(|m| m.name() == method.name()) { + None => changes.push(format!("method `{}` is removed", method.name())), + Some(other) if other != method => { + changes.extend( + signature(method, other) + .into_iter() + .map(|c| format!("method `{}`'s {c}", method.name())), + ); + } + Some(_) => {} + } + } + // A foreign implementation lacks a method the trait now requires. + for name in names(&theirs.methods) + .iter() + .filter(|m| !names(&ours.methods).contains(m)) + { + changes.push(format!( + "method `{name}` is added, which every implementation must have" + )); + } + if changes.is_empty() && ours != theirs { + changes.push("how it exports".to_string()); + } + } + (Item::Function(f), Item::Function(g)) => { + let mut ours = merge::bare_function(f); + maps.function(&mut ours); + let theirs = merge::bare_function(g); + changes.extend(signature(&ours, &theirs).into_iter().map(|c| format!("its {c}"))); + } + (Item::Constant(c), Item::Constant(d)) => { + // Its value may change: what a constant is called and its type are its API. + let ty = |c: &Constant| { + let mut c = merge::bare_constant(c); + c.value = match c.value { + Literal::Bool(_) => Literal::Bool(false), + Literal::Int(int, _) => Literal::Int(int, 0), + }; + c + }; + if ty(c) != ty(d) { + changes.push(format!("its type: it was `{}`, and is now `{}`", c.value, d.value)); + } + } + _ => changes.push("it is another kind of item".to_string()), + } + changes +} + +/// How the fields `ours` became `theirs`, each named as `what`. +fn fields(what: &str, ours: &[crate::ir::Field], theirs: &[crate::ir::Field]) -> Vec { + let mut changes = Vec::new(); + for (i, field) in ours.iter().enumerate() { + match theirs.iter().position(|f| f.name == field.name) { + None => changes.push(format!("{what} `{}` is removed", field.name)), + Some(j) if theirs[j].ty != field.ty => changes.push(format!("{what} `{}`'s type changed", field.name)), + // A value's fields are laid out in order, in C as in every binding's struct. + Some(j) if j != i => changes.push(format!("{what} `{}` moved", field.name)), + Some(_) => {} + } + } + for field in theirs.iter().filter(|f| !ours.iter().any(|o| o.name == f.name)) { + changes.push(format!( + "{what} `{}` is added, which every value must now give", + field.name + )); + } + changes +} + +/// What of the function `ours` changed in `theirs`, both bare and of one key. +fn signature(ours: &Function, theirs: &Function) -> Vec { + let (mut ours, mut theirs) = (ours.clone(), theirs.clone()); + // Which name the config gives a field: no binding names it otherwise. + for f in [&mut ours, &mut theirs] { + if let Access::Field { shared, .. } = &mut f.access { + *shared = false; + } + } + let mut changes = Vec::new(); + if ours.receiver != theirs.receiver { + changes.push("receiver".to_string()); + } + if ours.params.len() != theirs.params.len() { + changes.push(format!( + "parameters: it took {}, and now takes {}", + ours.params.len(), + theirs.params.len() + )); + } else { + for (p, q) in ours.params.iter().zip(&theirs.params) { + if p.name != q.name { + changes.push(format!("parameter `{}`, now `{}`", p.name, q.name)); + } else if p != q { + changes.push(format!("parameter `{}`'s type", p.name)); + } + } + } + if ours.ok != theirs.ok { + changes.push("return type".to_string()); + } + if ours.err != theirs.err { + changes.push("error type".to_string()); + } + if ours.future != theirs.future { + changes.push("whether it is async".to_string()); + } + if changes.is_empty() && ours != theirs { + changes.push("how it exports".to_string()); + } + changes +} diff --git a/ffi/src/main.rs b/ffi/src/main.rs index 95e2938f4..45224949d 100644 --- a/ffi/src/main.rs +++ b/ffi/src/main.rs @@ -35,6 +35,7 @@ mod glue; mod go; mod ir; mod kotlin; +mod lock; mod merge; mod python; mod swift; diff --git a/ffi/src/merge.rs b/ffi/src/merge.rs index dbda04f10..c212d19d4 100644 --- a/ffi/src/merge.rs +++ b/ffi/src/merge.rs @@ -108,11 +108,11 @@ struct Merged { /// Where each type of the API being added lands among the merged API's. #[derive(Default)] -struct Maps { - records: Vec, - enums: Vec, - objects: Vec, - callbacks: Vec, +pub struct Maps { + pub records: Vec, + pub enums: Vec, + pub objects: Vec, + pub callbacks: Vec, } impl Maps { @@ -129,7 +129,7 @@ impl Maps { .collect() } - fn ty(&self, ty: &mut Type) { + pub fn ty(&self, ty: &mut Type) { match ty { Type::Record(i) => *i = self.records[*i], Type::Enum(i) => *i = self.enums[*i], @@ -148,15 +148,15 @@ impl Maps { } } - fn types(&self, types: &mut [Type]) { + pub fn types(&self, types: &mut [Type]) { types.iter_mut().for_each(|ty| self.ty(ty)); } - fn fields(&self, fields: &mut [Field]) { + pub fn fields(&self, fields: &mut [Field]) { fields.iter_mut().for_each(|f| self.ty(&mut f.ty)); } - fn function(&self, f: &mut Function) { + pub fn function(&self, f: &mut Function) { f.params.iter_mut().for_each(|p| self.ty(&mut p.ty)); self.ty(&mut f.ok); if let Some(err) = &mut f.err { @@ -171,7 +171,7 @@ impl Maps { } } - fn functions(&self, functions: &mut [Function]) { + pub fn functions(&self, functions: &mut [Function]) { functions.iter_mut().for_each(|f| self.function(f)); } } @@ -184,7 +184,7 @@ fn bare(item: &T, clear: impl Fn(&mut T)) -> T { item } -fn bare_function(f: &Function) -> Function { +pub fn bare_function(f: &Function) -> Function { bare(f, |f| { f.span = DUMMY_SP; f.docs.clear(); @@ -192,7 +192,7 @@ fn bare_function(f: &Function) -> Function { }) } -fn bare_record(r: &Record) -> Record { +pub fn bare_record(r: &Record) -> Record { bare(r, |r| { r.span = DUMMY_SP; r.docs.clear(); @@ -202,7 +202,7 @@ fn bare_record(r: &Record) -> Record { }) } -fn bare_enum(e: &Enum) -> Enum { +pub fn bare_enum(e: &Enum) -> Enum { bare(e, |e| { e.span = DUMMY_SP; e.docs.clear(); @@ -212,7 +212,7 @@ fn bare_enum(e: &Enum) -> Enum { }) } -fn bare_variant(v: &Variant) -> Variant { +pub fn bare_variant(v: &Variant) -> Variant { bare(v, |v| { v.on = On::ALL; // Compared apart, as only a plain enum's matter. @@ -221,7 +221,7 @@ fn bare_variant(v: &Variant) -> Variant { }) } -fn bare_object(o: &Object) -> Object { +pub fn bare_object(o: &Object) -> Object { bare(o, |o| { o.span = DUMMY_SP; o.docs.clear(); @@ -230,7 +230,7 @@ fn bare_object(o: &Object) -> Object { }) } -fn bare_callback(c: &Callback) -> Callback { +pub fn bare_callback(c: &Callback) -> Callback { bare(c, |c| { c.span = DUMMY_SP; c.docs.clear(); @@ -239,7 +239,7 @@ fn bare_callback(c: &Callback) -> Callback { }) } -fn bare_constant(c: &Constant) -> Constant { +pub fn bare_constant(c: &Constant) -> Constant { bare(c, |c| { c.span = DUMMY_SP; c.docs.clear(); @@ -626,6 +626,10 @@ pub mod span { pub fn serialize(span: &Span, s: S) -> Result { let located = context(|map, roots| { + // A staged span whose file was not on this host as it was: no file names it. + if span.is_dummy() { + return None; + } let span = span.source_callsite(); let file = map.lookup_source_file(span.lo()); let FileName::Real(real) = &file.name else { diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index a348ea731..5453b04eb 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -52,18 +52,24 @@ fn run(cmd: &mut Command) -> Output { /// Export the fixture `name` into `out` for `targets` into one binding, else the host, /// with these cargo args, returning what the exporter printed. fn export(name: &str, out: &Path, targets: &[&str], cargo: &[&str]) -> Output { + exporter(name, out, targets, &[], cargo).output().expect("running rust2-ffi") +} + +/// The export of the fixture `name`, with `args` for rust2-ffi besides. +fn exporter(name: &str, out: &Path, targets: &[&str], args: &[&std::ffi::OsStr], cargo: &[&str]) -> Command { let fixture = manifest_dir().join("fixtures").join(name); - Command::new(env!("CARGO_BIN_EXE_rust2-ffi")) + let mut command = Command::new(env!("CARGO_BIN_EXE_rust2-ffi")); + command .arg("--config") .arg(fixture.join("ffi.toml")) .arg("--out") .arg(out) .args(targets.iter().flat_map(|target| ["--target", target])) + .args(args) .arg("--") .args(cargo) - .env("CARGO_TARGET_DIR", scratch().join(name).join("build")) - .output() - .expect("running rust2-ffi") + .env("CARGO_TARGET_DIR", scratch().join(name).join("build")); + command } /// The api fixture, exported and built once for each language's test. @@ -1312,8 +1318,23 @@ fn reject() { let out = scratch().join("reject").join("out"); let output = export("reject", &out, &[], &[]); assert!(!output.status.success(), "exporting reject succeeded"); + let errors = errors(&output); + let expected = std::fs::read_to_string(manifest_dir().join("fixtures/reject/expected.txt")).unwrap(); + if std::env::var_os("UPDATE_EXPECT").is_some() { + std::fs::write( + manifest_dir().join("fixtures/reject/expected.txt"), + errors.join("\n") + "\n", + ) + .unwrap(); + return; + } + assert_eq!(errors.join("\n") + "\n", expected); +} + +/// Each of rust2-ffi's errors the export printed, sorted: at its span, then each of its +/// notes at its own. +fn errors(output: &Output) -> Vec { let stderr = String::from_utf8_lossy(&output.stderr); - // Each error at its span, then each of its notes at its own. let lines: Vec<&str> = stderr.lines().collect(); let at = |i: usize| { lines[i + 1..] @@ -1338,16 +1359,45 @@ fn reject() { } } errors.sort(); - let expected = std::fs::read_to_string(manifest_dir().join("fixtures/reject/expected.txt")).unwrap(); + errors +} + +/// The lock fixture exported for wasm32, staged, and the host, then again against that +/// export's API as the baseline: with `next`, which must fail at each break, and with +/// `added`, which must pass. +#[test] +fn lock() { + let dir = scratch().join("lock"); + let targets = [WASM, host()]; + let output = export("lock", &dir.join("base"), &targets, &[]); + assert!( + output.status.success(), + "exporting failed:\n{}", + String::from_utf8_lossy(&output.stderr) + ); + let baseline = dir.join("base").join("api.json"); + let locked = |feature: &str| { + let args = ["--baseline".as_ref(), baseline.as_os_str()]; + exporter("lock", &dir.join(feature), &targets, &args, &["--features", feature]) + .output() + .expect("running rust2-ffi") + }; + let added = locked("added"); + assert!( + added.status.success(), + "an addition broke the baseline:\n{}", + String::from_utf8_lossy(&added.stderr) + ); + let next = locked("next"); + assert!(!next.status.success(), "breaking the baseline passed"); + assert!(!dir.join("next").join("api.json").exists(), "a broken export wrote its API"); + let errors = errors(&next).join("\n") + "\n"; + let expected = manifest_dir().join("fixtures/lock/expected.txt"); if std::env::var_os("UPDATE_EXPECT").is_some() { - std::fs::write( - manifest_dir().join("fixtures/reject/expected.txt"), - errors.join("\n") + "\n", - ) - .unwrap(); + std::fs::write(&expected, errors).unwrap(); return; } - assert_eq!(errors.join("\n") + "\n", expected); + assert_eq!(errors, std::fs::read_to_string(expected).unwrap()); } /// The C library builds the facade's dependencies with what the facade enables in them, diff --git a/quest/m1/ffi-export/README.md b/quest/m1/ffi-export/README.md index 95937ca12..2427942ba 100644 --- a/quest/m1/ffi-export/README.md +++ b/quest/m1/ffi-export/README.md @@ -83,9 +83,8 @@ Decided with the maintainer on 2026-11-12, in the quest audit: which waits on a rind release the maintainer holds. - ✅ Every change that breaks the C ABI or a generated API is a child here, so it lands before moq pins: [the fused async start](/quest/m1/ffi-export/async-start.md), - [owned buffers](/quest/m1/ffi-export/owned-bufs.md), - [numeric slices](/quest/m1/ffi-export/numeric-slices.md), and - [the API lock](/quest/m1/ffi-export/api-lock.md). Work that changes no generated API is + [owned buffers](/quest/m1/ffi-export/owned-bufs.md), and + [numeric slices](/quest/m1/ffi-export/numeric-slices.md). Work that changes no generated API is [its own epic](/quest/m1/ffi-speed/README.md), which does not hold the pin. - Not planned: one walker emitting lift and lower instructions every generator implements, as wit-bindgen's `Bindgen` does. A new rule touches 19 to 38 files today, diff --git a/quest/m1/ffi-export/api-lock.md b/quest/m1/ffi-export/api-lock.md deleted file mode 100644 index 10e551b86..000000000 --- a/quest/m1/ffi-export/api-lock.md +++ /dev/null @@ -1,44 +0,0 @@ -# [M] An API lock that fails the export on a break - -## Goal - -`rust2-ffi --baseline ` fails the export when the crate's exported API breaks -the one the file records: an exported name that now means another item, an item removed, -or a signature, field, or variant changed. Each failure has the span of the item and says -what changed, once for every language rather than once per binding. moq's release check -runs it in place of the half of its -[`api-diff`](https://github.com/moq-dev/moq/blob/main/sh/api-diff/ffi.sh) that reads -UniFFI metadata, which goes when moq switches. - -## Plan - -Decided with the maintainer on 2026-11-12, in the quest audit: ✅ a child of the exporter -epic, so moq's first pinned release already has a baseline. - -The hole today: a C name depends on every item exported. Among names that clash, the -first by kind and Rust path keeps the name and each later one takes a trailing `_` -(`ffi/src/abi.rs`'s `rename`). So adding `audio::encoder_finish` beside an existing -`audio_encoder::finish` gives the new function `moq_audio_encoder_finish` and renames the -old one, as `ffi/README.md` describes. With equal signatures a C caller compiles and calls -the wrong function, and the contract hash only catches a header and library from -different builds. Stable mangling was rejected when the naming rule was decided -([#599](https://github.com/moq-dev/rust2/pull/599)); this catches the break instead. - -- The baseline covers every target the binding serves. `--api` writes one target's API - and refuses `--with` or a second `--target` (`ffi/src/cli.rs`), so a host-written file - would miss a break in an item only Android or only unix has, such as - `tokio::tls::init_android`. The export that merges the staged targets writes the merged - API as the baseline, in the same format, and `--baseline` compares against the merge. -- The consumer commits it beside its lockfile. It is a lockfile, not config: the exporter - reads it only to compare, and the export is the same with or without it. Record that in - `ffi/README.md`. -- An addition passes. A rebound name, a removal, and a changed signature fail, each - listed, and the consumer accepts a break by writing the file again. -- Not planned: compiling the last release's generated glue against the new facade as a - witness. It would catch a break the two files' diff cannot name, but old glue may fail - on the runtime's internals instead; try it only if the diff misses a real break. - -Prove it on the api fixture with a pair of edits per kind of break, one of them in an -item only a staged target has, and by replaying two moq commits a known break apart. - -Public API: the `--baseline` flag and its errors, and the merged API file an export writes. diff --git a/quest/m1/ffi-export/lock-names.md b/quest/m1/ffi-export/lock-names.md new file mode 100644 index 000000000..f9111897e --- /dev/null +++ b/quest/m1/ffi-export/lock-names.md @@ -0,0 +1,25 @@ +# [M] The API lock compares every language's names + +## Goal + +`rust2-ffi --baseline` also fails the export where a binding's own name for a kept item +changes: a Kotlin, Swift, Go, Dart, Python, or C++ class, function, or member name that a +clash rule renames because another item was added. Each failure names the language, the +item, and the old and new name, at the item's span. + +## Plan + +The lock ([ffi/README.md](/ffi/README.md#the-api-lock)) compares the IR and C's names, so a +C caller never calls a renamed item. The languages rename on their own: `abi::apart` names +`audio::encoder::Finish` `AudioEncoderFinish` alone, but `AudioEncoder_Finish` once +`audio::EncoderFinish` is added beside it, in every language over `abi::classes`, and each +generator's `claim` gives a later member a trailing `_`. Neither reaches C, so the lock passes while a Kotlin or Swift caller stops compiling, +or, with equal signatures, calls the new item. + +- Each generator returns its name table, item key to name, beside its output, and the + lock writes each into `api.json` and compares it as it compares C's. +- A generator renames through `abi::apart`, `abi::claim`, `abi::unique`, or + `abi::distinct`, so the table can come from those calls rather than a second walk. + +Prove it on the lock fixture with a pair of edits that rename a class and a member in one +language and no C name. diff --git a/quest/m1/ffi-export/ship.md b/quest/m1/ffi-export/ship.md index fd08c0ad2..fbda1e8f2 100644 --- a/quest/m1/ffi-export/ship.md +++ b/quest/m1/ffi-export/ship.md @@ -29,4 +29,3 @@ then see change. A sibling planned later adds itself to `Required` here. - [Fused async start](/quest/m1/ffi-export/async-start.md) - every future's C signature - [Owned buffers](/quest/m1/ffi-export/owned-bufs.md) - what a buffer's owner means on the way in - [Numeric slices](/quest/m1/ffi-export/numeric-slices.md) - the types of numeric slices and vectors -- [API lock](/quest/m1/ffi-export/api-lock.md) - the check moq's releases run on the exported names From 6a34db0067745f8a2aa11910e45bc9c22bcd156e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 18:03:40 -0800 Subject: [PATCH 3/9] style(ffi): format the lock test Co-Authored-By: Claude Opus 5.5 --- ffi/tests/fixtures.rs | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index 5453b04eb..5dc3ef1f6 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -52,7 +52,9 @@ fn run(cmd: &mut Command) -> Output { /// Export the fixture `name` into `out` for `targets` into one binding, else the host, /// with these cargo args, returning what the exporter printed. fn export(name: &str, out: &Path, targets: &[&str], cargo: &[&str]) -> Output { - exporter(name, out, targets, &[], cargo).output().expect("running rust2-ffi") + exporter(name, out, targets, &[], cargo) + .output() + .expect("running rust2-ffi") } /// The export of the fixture `name`, with `args` for rust2-ffi besides. @@ -1390,7 +1392,10 @@ fn lock() { ); let next = locked("next"); assert!(!next.status.success(), "breaking the baseline passed"); - assert!(!dir.join("next").join("api.json").exists(), "a broken export wrote its API"); + assert!( + !dir.join("next").join("api.json").exists(), + "a broken export wrote its API" + ); let errors = errors(&next).join("\n") + "\n"; let expected = manifest_dir().join("fixtures/lock/expected.txt"); if std::env::var_os("UPDATE_EXPECT").is_some() { From 7ff2a42a037517b3f60d51233542358c1eab0c1d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 19:43:04 -0800 Subject: [PATCH 4/9] fix(ffi): the lock catches a data enum's reordered tags, a plain enum gaining fields, and a renamed library Co-Authored-By: Claude Opus 5.5 --- ffi/README.md | 6 +++++- ffi/fixtures/lock/expected.txt | 2 ++ ffi/fixtures/lock/src/lib.rs | 36 ++++++++++++++++++++++++++++++++-- ffi/src/lock.rs | 31 +++++++++++++++++++++++++++-- 4 files changed, 70 insertions(+), 5 deletions(-) diff --git a/ffi/README.md b/ffi/README.md index 5f7410431..4a437fd91 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -195,7 +195,11 @@ API breaks the one in `file`, with an error at each item that names how: - a function's receiver, parameter, return, error, or asyncness changed, a constant's type changed, a trait method added or changed, or a trait impl such as `Clone` dropped; - a record's or variant's field added, removed, moved, or of another type, a variant - removed or of another value, or one added to an enum another crate matches exhaustively; + removed or of another value or, in an enum with fields, at another place, which is its C + tag, one added to an enum another crate matches exhaustively, and an enum gaining its + first variant with fields or losing its last, which changes it between a C enum and a + struct; +- the library's name, which every C name starts with; - a C name that now names another item: since a name depends on every item exported ([The C ABI](#the-c-abi)), adding `audio::encoder_finish` renames `audio_encoder::finish` to `moq_audio_encoder_finish_`, and a C caller of the old name would call the new item. diff --git a/ffi/fixtures/lock/expected.txt b/ffi/fixtures/lock/expected.txt index f7b58e9b5..dfc7798ec 100644 --- a/ffi/fixtures/lock/expected.txt +++ b/ffi/fixtures/lock/expected.txt @@ -1,5 +1,7 @@ fixtures/lock/src/lib.rs:106:1: rust2-ffi: the API breaks the baseline at enum `lock::Mode`: variant `Idle` is added to an exhaustive enum fixtures/lock/src/lib.rs:113:1: rust2-ffi: the API breaks the baseline at enum `lock::Shape`: variant `Circle`'s field `0`'s type changed +fixtures/lock/src/lib.rs:123:1: rust2-ffi: the API breaks the baseline at enum `lock::Stroke`: variant `Solid`'s tag 0 is now 1; variant `Dashed`'s tag 1 is now 0 +fixtures/lock/src/lib.rs:135:1: rust2-ffi: the API breaks the baseline at enum `lock::Level`: a variant with fields makes it a struct in C fixtures/lock/src/lib.rs:21:2: rust2-ffi: the API breaks the baseline at const `lock::limits_max::RATE`: its C name `LOCK_LIMITS_MAX_RATE` is now `LOCK_LIMITS_MAX_RATE_`, and `LOCK_LIMITS_MAX_RATE` names const `lock::limits::MAX_RATE` fixtures/lock/src/lib.rs:30:1: rust2-ffi: the API breaks the baseline at fn `lock::removed`: it is removed fixtures/lock/src/lib.rs:36:1: rust2-ffi: the API breaks the baseline at fn `lock::portable`: it is no longer on wasm32-unknown-unknown diff --git a/ffi/fixtures/lock/src/lib.rs b/ffi/fixtures/lock/src/lib.rs index 6c98f6047..0eeeb1357 100644 --- a/ffi/fixtures/lock/src/lib.rs +++ b/ffi/fixtures/lock/src/lib.rs @@ -115,17 +115,49 @@ pub enum Shape { Circle(u32), #[cfg(feature = "next")] Circle(f64), + Square(u32), } +/// Its tags are its variants' places, which `next` swaps. +#[non_exhaustive] +pub enum Stroke { + #[cfg(feature = "next")] + Dashed(u32), + Solid(u32), + #[cfg(not(feature = "next"))] + Dashed(u32), + #[cfg(feature = "added")] + Dotted(u32), +} + +/// A C enum, which a variant with fields in `next` makes a struct. #[non_exhaustive] pub enum Level { Low, #[cfg(feature = "added")] High, + #[cfg(feature = "next")] + Custom(u8), +} + +/// A handle `added` makes `Clone`, so copies of it may share one value. +#[cfg_attr(feature = "added", derive(Clone))] +pub struct Token { + id: u32, +} + +impl Token { + pub fn new(id: u32) -> Self { + Self { id } + } + + pub fn id(&self) -> u32 { + self.id + } } -pub fn pick(mode: Mode, shape: Shape, size: Size, level: Level) -> u32 { - let _ = (shape, size, level); +pub fn pick(mode: Mode, shape: Shape, stroke: Stroke, size: Size, level: Level) -> u32 { + let _ = (shape, stroke, size, level); match mode { Mode::Fast => 1, _ => 0, diff --git a/ffi/src/lock.rs b/ffi/src/lock.rs index 00c53ca17..13b62a32e 100644 --- a/ffi/src/lock.rs +++ b/ffi/src/lock.rs @@ -27,6 +27,19 @@ pub struct Break { /// Every break of `base`, the baseline, by `now`, the export's API, both prefixed `prefix`. pub fn breaks(base: &Api, now: &Api, prefix: &str) -> Vec { + // Every path starts with the facade's root, which prefixes every C name. + let root = (base.records.iter().map(|r| &r.shown)) + .chain(base.enums.iter().map(|e| &e.shown)) + .chain(base.objects.iter().map(|o| &o.shown)) + .chain(base.functions.iter().map(|f| &f.shown)) + .chain(base.constants.iter().map(|c| &c.path)) + .find_map(|path| path.first()); + if let Some(root) = root.filter(|root| *root != prefix) { + return vec![Break { + span: DUMMY_SP, + what: format!("library `{root}`: it is now `{prefix}`, which every path and C name starts with"), + }]; + } let base = Index::new(base, prefix); let now = Index::new(now, prefix); let mut breaks = Vec::new(); @@ -324,11 +337,21 @@ fn changed(base: &Index<'_>, now: &Index<'_>, maps: &Maps, ours: &Item<'_>, thei if e.exhaustive && !f.exhaustive { changes.push("it is now `#[non_exhaustive]`".to_string()); } - for variant in &e.variants { - let Some(other) = f.variants.iter().find(|v| v.name == variant.name) else { + // A plain enum is a C enum, and one with fields a struct of a tag and a payload. + match (e.plain(), f.plain()) { + (true, false) => changes.push("a variant with fields makes it a struct in C".to_string()), + (false, true) => changes.push("no variant has fields, which makes it an enum in C".to_string()), + _ => {} + } + for (at, variant) in e.variants.iter().enumerate() { + let Some((to, other)) = f.variants.iter().enumerate().find(|(_, v)| v.name == variant.name) else { changes.push(format!("variant `{}` is removed", variant.name)); continue; }; + // The tag of an enum with fields is the variant's place. + if !e.plain() && !f.plain() && at != to { + changes.push(format!("variant `{}`'s tag {at} is now {to}", variant.name)); + } let mut ours = merge::bare_variant(variant); maps.fields(&mut ours.fields); let theirs = merge::bare_variant(other); @@ -381,6 +404,10 @@ fn changed(base: &Index<'_>, now: &Index<'_>, maps: &Maps, ours: &Item<'_>, thei let mut ours = merge::bare_object(&b.objects[i]); maps.types(&mut ours.args); let mut theirs = merge::bare_object(&n.objects[j]); + // An added `Clone` may let copies of a handle share one value: what it adds. + if !ours.traits.clone && theirs.traits.clone && !ours.shared { + theirs.shared = false; + } (ours.traits, theirs.traits) = (Traits::default(), Traits::default()); if ours != theirs { changes.push("how it exports".to_string()); From 4d28bcd330da8b7cca576718ee06dd6be317ca69 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 20:22:38 -0800 Subject: [PATCH 5/9] quest(m0): plan the Swift async-closure timeout flake Co-Authored-By: Claude Opus 5.5 --- quest/m0/swift-giveup-flake.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 quest/m0/swift-giveup-flake.md diff --git a/quest/m0/swift-giveup-flake.md b/quest/m0/swift-giveup-flake.md new file mode 100644 index 000000000..77bc93e09 --- /dev/null +++ b/quest/m0/swift-giveup-flake.md @@ -0,0 +1,15 @@ +# [S] Swift's async-closure timeout test races under load + +## Goal + +`api_swift`'s futures run never fails "Rust gives up on an async closure" because of host +load: the check waits for the timeout to fire rather than for one drain to happen to see it. + +## Plan + +`tests/api.swift` launches `within(0) {}` and checks `threw` after a single `q.drain()` +(added in [#705](https://github.com/kixel-ai/rust2/pull/705)). The timer behind a zero +deadline can fire after that drain on a loaded host. It failed once in `just ci` on +[#739](https://github.com/kixel-ai/rust2/pull/739) and passed three reruns. Reproduce it by +loading the host (or delaying the timer's wake) first, then wait with `until` as the +sibling checks do, or drive the deadline from a mocked clock if the runtime takes one. From ea52753a8c6c98ce7d539a62acd31e02bafb7696 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 21:17:17 -0800 Subject: [PATCH 6/9] fix(ffi): a callback-only baseline names its library too Co-Authored-By: Claude Opus 5.5 --- ffi/src/lock.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/ffi/src/lock.rs b/ffi/src/lock.rs index 13b62a32e..4faad6b3b 100644 --- a/ffi/src/lock.rs +++ b/ffi/src/lock.rs @@ -33,6 +33,7 @@ pub fn breaks(base: &Api, now: &Api, prefix: &str) -> Vec { .chain(base.objects.iter().map(|o| &o.shown)) .chain(base.functions.iter().map(|f| &f.shown)) .chain(base.constants.iter().map(|c| &c.path)) + .chain(base.callbacks.iter().map(|c| &c.path)) .find_map(|path| path.first()); if let Some(root) = root.filter(|root| *root != prefix) { return vec![Break { From f9095fd89acb055d7811789549b7f7efb2434339 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 21:31:16 -0800 Subject: [PATCH 7/9] fix(ffi): a constant's type break names its types; record the pick round's follow-up answers A constant whose type changed printed its values (`60` -> `60`). The lock fixture now widens one constant on the host and one on wasm32 under `next`, and changes a value under `added`, which passes. lock-names is kept and ship requires it; the Swift flake folds into quest/m0/swift-gives-up.md, which main added for the same race. Co-Authored-By: Claude Opus 5.5 --- ffi/fixtures/lock/expected.txt | 2 ++ ffi/fixtures/lock/src/lib.rs | 18 ++++++++++++++++++ ffi/src/lock.rs | 10 ++++++++-- quest/m0/swift-gives-up.md | 3 ++- quest/m0/swift-giveup-flake.md | 15 --------------- quest/m1/ffi-export/lock-names.md | 5 +++++ quest/m1/ffi-export/ship.md | 1 + 7 files changed, 36 insertions(+), 18 deletions(-) delete mode 100644 quest/m0/swift-giveup-flake.md diff --git a/ffi/fixtures/lock/expected.txt b/ffi/fixtures/lock/expected.txt index dfc7798ec..094167a63 100644 --- a/ffi/fixtures/lock/expected.txt +++ b/ffi/fixtures/lock/expected.txt @@ -2,6 +2,8 @@ fixtures/lock/src/lib.rs:106:1: rust2-ffi: the API breaks the baseline at enum ` fixtures/lock/src/lib.rs:113:1: rust2-ffi: the API breaks the baseline at enum `lock::Shape`: variant `Circle`'s field `0`'s type changed fixtures/lock/src/lib.rs:123:1: rust2-ffi: the API breaks the baseline at enum `lock::Stroke`: variant `Solid`'s tag 0 is now 1; variant `Dashed`'s tag 1 is now 0 fixtures/lock/src/lib.rs:135:1: rust2-ffi: the API breaks the baseline at enum `lock::Level`: a variant with fields makes it a struct in C +fixtures/lock/src/lib.rs:176:1: rust2-ffi: the API breaks the baseline at const `lock::DEPTH`: its type: it was `u32`, and is now `u64` +fixtures/lock/src/lib.rs:182:1: rust2-ffi: the API breaks the baseline at const `lock::PAGES`: its type: it was `u16`, and is now `i16` fixtures/lock/src/lib.rs:21:2: rust2-ffi: the API breaks the baseline at const `lock::limits_max::RATE`: its C name `LOCK_LIMITS_MAX_RATE` is now `LOCK_LIMITS_MAX_RATE_`, and `LOCK_LIMITS_MAX_RATE` names const `lock::limits::MAX_RATE` fixtures/lock/src/lib.rs:30:1: rust2-ffi: the API breaks the baseline at fn `lock::removed`: it is removed fixtures/lock/src/lib.rs:36:1: rust2-ffi: the API breaks the baseline at fn `lock::portable`: it is no longer on wasm32-unknown-unknown diff --git a/ffi/fixtures/lock/src/lib.rs b/ffi/fixtures/lock/src/lib.rs index 0eeeb1357..ad0399fe4 100644 --- a/ffi/fixtures/lock/src/lib.rs +++ b/ffi/fixtures/lock/src/lib.rs @@ -168,3 +168,21 @@ pub fn pick(mode: Mode, shape: Shape, stroke: Stroke, size: Size, level: Level) pub fn extra() -> u32 { 3 } + +/// A constant `next` widens, on the host alone. +#[cfg(all(not(feature = "next"), not(target_arch = "wasm32")))] +pub const DEPTH: u32 = 8; +#[cfg(all(feature = "next", not(target_arch = "wasm32")))] +pub const DEPTH: u64 = 8; + +/// A constant `next` makes signed, on wasm32 alone. +#[cfg(all(not(feature = "next"), target_arch = "wasm32"))] +pub const PAGES: u16 = 4; +#[cfg(all(feature = "next", target_arch = "wasm32"))] +pub const PAGES: i16 = 4; + +/// A constant whose value `added` changes, which is no break. +#[cfg(not(feature = "added"))] +pub const LIMIT: u32 = 10; +#[cfg(feature = "added")] +pub const LIMIT: u32 = 20; diff --git a/ffi/src/lock.rs b/ffi/src/lock.rs index 4faad6b3b..c87e85b9c 100644 --- a/ffi/src/lock.rs +++ b/ffi/src/lock.rs @@ -453,7 +453,7 @@ fn changed(base: &Index<'_>, now: &Index<'_>, maps: &Maps, ours: &Item<'_>, thei } (Item::Constant(c), Item::Constant(d)) => { // Its value may change: what a constant is called and its type are its API. - let ty = |c: &Constant| { + let bare = |c: &Constant| { let mut c = merge::bare_constant(c); c.value = match c.value { Literal::Bool(_) => Literal::Bool(false), @@ -461,8 +461,14 @@ fn changed(base: &Index<'_>, now: &Index<'_>, maps: &Maps, ours: &Item<'_>, thei }; c }; + let ty = |c: &Constant| match c.value { + Literal::Bool(_) => "bool", + Literal::Int(int, _) => int.rust(), + }; if ty(c) != ty(d) { - changes.push(format!("its type: it was `{}`, and is now `{}`", c.value, d.value)); + changes.push(format!("its type: it was `{}`, and is now `{}`", ty(c), ty(d))); + } else if bare(c) != bare(d) { + changes.push("how it exports".to_string()); } } _ => changes.push("it is another kind of item".to_string()), diff --git a/quest/m0/swift-gives-up.md b/quest/m0/swift-gives-up.md index dd5650f5a..873f72785 100644 --- a/quest/m0/swift-gives-up.md +++ b/quest/m0/swift-gives-up.md @@ -10,7 +10,8 @@ closure" check in `ffi/tests/api.swift` no longer fails intermittently. Found while validating [#740](https://github.com/kixel-ai/rust2/pull/740) on 2026-11-13: `just ffi test --test fixtures` failed `api_swift` there in 2 of 4 runs, and at `main` `7008d1d3` in 1 of 5, each time with `"futures" failed: Rust gives up on an async closure`. -The test passes alone. +The test passes alone. It also failed once in `just ci` on +[#739](https://github.com/kixel-ai/rust2/pull/739) and passed three reruns alone. Two races fit, and the fix covers both: diff --git a/quest/m0/swift-giveup-flake.md b/quest/m0/swift-giveup-flake.md deleted file mode 100644 index 77bc93e09..000000000 --- a/quest/m0/swift-giveup-flake.md +++ /dev/null @@ -1,15 +0,0 @@ -# [S] Swift's async-closure timeout test races under load - -## Goal - -`api_swift`'s futures run never fails "Rust gives up on an async closure" because of host -load: the check waits for the timeout to fire rather than for one drain to happen to see it. - -## Plan - -`tests/api.swift` launches `within(0) {}` and checks `threw` after a single `q.drain()` -(added in [#705](https://github.com/kixel-ai/rust2/pull/705)). The timer behind a zero -deadline can fire after that drain on a loaded host. It failed once in `just ci` on -[#739](https://github.com/kixel-ai/rust2/pull/739) and passed three reruns. Reproduce it by -loading the host (or delaying the timer's wake) first, then wait with `until` as the -sibling checks do, or drive the deadline from a mocked clock if the runtime takes one. diff --git a/quest/m1/ffi-export/lock-names.md b/quest/m1/ffi-export/lock-names.md index f9111897e..d7977fbe5 100644 --- a/quest/m1/ffi-export/lock-names.md +++ b/quest/m1/ffi-export/lock-names.md @@ -9,6 +9,11 @@ item, and the old and new name, at the item's span. ## Plan +Decided with the maintainer on 2026-11-12, in the pick round of +[#739](https://github.com/kixel-ai/rust2/pull/739): ✅ kept. ✅ [ship](/quest/m1/ffi-export/ship.md) +requires it (rejected: independent), so moq drops its own api-diff only once every +binding's names are locked. + The lock ([ffi/README.md](/ffi/README.md#the-api-lock)) compares the IR and C's names, so a C caller never calls a renamed item. The languages rename on their own: `abi::apart` names `audio::encoder::Finish` `AudioEncoderFinish` alone, but `AudioEncoder_Finish` once diff --git a/quest/m1/ffi-export/ship.md b/quest/m1/ffi-export/ship.md index fbda1e8f2..939024d59 100644 --- a/quest/m1/ffi-export/ship.md +++ b/quest/m1/ffi-export/ship.md @@ -29,3 +29,4 @@ then see change. A sibling planned later adds itself to `Required` here. - [Fused async start](/quest/m1/ffi-export/async-start.md) - every future's C signature - [Owned buffers](/quest/m1/ffi-export/owned-bufs.md) - what a buffer's owner means on the way in - [Numeric slices](/quest/m1/ffi-export/numeric-slices.md) - the types of numeric slices and vectors +- [Lock every language's names](/quest/m1/ffi-export/lock-names.md) - `--baseline` catches a binding's own rename, so moq can drop its api-diff From f3d6293a2a5fef4c7de18ad9984330537f21b08e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 22:15:50 -0800 Subject: [PATCH 8/9] fix(ffi): the lock catches a renamed tuple struct, and refuses a baseline the export overwrites A tuple's C name runs its elements' together, so adding `((u32, u64), u8)` renamed `((u32,), u64, u8)`'s struct with no break reported. The lock now keys each tuple struct by its Rust spelling and reports one whose C name changed, at a function that uses it. `--baseline /api.json` would have replaced the baseline on every passing export; it is now refused up front. Co-Authored-By: Claude Opus 5.5 --- ffi/README.md | 5 +++- ffi/fixtures/lock/expected.txt | 1 + ffi/fixtures/lock/src/lib.rs | 10 +++++++ ffi/src/abi.rs | 2 +- ffi/src/cli.rs | 12 +++++++++ ffi/src/lock.rs | 48 +++++++++++++++++++++++++++++++--- ffi/tests/fixtures.rs | 11 ++++++++ 7 files changed, 84 insertions(+), 5 deletions(-) diff --git a/ffi/README.md b/ffi/README.md index 4a437fd91..a661732dd 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -203,6 +203,8 @@ API breaks the one in `file`, with an error at each item that names how: - a C name that now names another item: since a name depends on every item exported ([The C ABI](#the-c-abi)), adding `audio::encoder_finish` renames `audio_encoder::finish` to `moq_audio_encoder_finish_`, and a C caller of the old name would call the new item. + A tuple's struct, known by its Rust spelling, is renamed the same way when another + tuple's elements run together into its name. An item is known by its kind and Rust path, as `exclude` names it. An addition passes: a new item, method, trait impl, or a variant of a `#[non_exhaustive]` enum. A constant's value and @@ -211,7 +213,8 @@ it covers C's names, while a language's own names for a clash its generator rena compared. The baseline is a lockfile, not config: the consumer commits it beside `Cargo.lock`, the -export reads it only to compare, and the export is the same with or without it. To accept a +export reads it only to compare, and the export is the same with or without it. It refuses a +baseline that is the `api.json` it would write. To accept a break, export without `--baseline` and commit the `api.json` it writes. Its spans are relative to the workspace and cargo's home, as a staged API's are, so a removed item's error points where it was while its file is unchanged. diff --git a/ffi/fixtures/lock/expected.txt b/ffi/fixtures/lock/expected.txt index 094167a63..433c9a80e 100644 --- a/ffi/fixtures/lock/expected.txt +++ b/ffi/fixtures/lock/expected.txt @@ -4,6 +4,7 @@ fixtures/lock/src/lib.rs:123:1: rust2-ffi: the API breaks the baseline at enum ` fixtures/lock/src/lib.rs:135:1: rust2-ffi: the API breaks the baseline at enum `lock::Level`: a variant with fields makes it a struct in C fixtures/lock/src/lib.rs:176:1: rust2-ffi: the API breaks the baseline at const `lock::DEPTH`: its type: it was `u32`, and is now `u64` fixtures/lock/src/lib.rs:182:1: rust2-ffi: the API breaks the baseline at const `lock::PAGES`: its type: it was `u16`, and is now `i16` +fixtures/lock/src/lib.rs:191:1: rust2-ffi: the API breaks the baseline at tuple `((u32,), u64, u8)`: its C name `lock_tuple_tuple_u32_u64_u8` is now `lock_tuple_tuple_u32_u64_u8_`, and `lock_tuple_tuple_u32_u64_u8` names tuple `((u32, u64), u8)` fixtures/lock/src/lib.rs:21:2: rust2-ffi: the API breaks the baseline at const `lock::limits_max::RATE`: its C name `LOCK_LIMITS_MAX_RATE` is now `LOCK_LIMITS_MAX_RATE_`, and `LOCK_LIMITS_MAX_RATE` names const `lock::limits::MAX_RATE` fixtures/lock/src/lib.rs:30:1: rust2-ffi: the API breaks the baseline at fn `lock::removed`: it is removed fixtures/lock/src/lib.rs:36:1: rust2-ffi: the API breaks the baseline at fn `lock::portable`: it is no longer on wasm32-unknown-unknown diff --git a/ffi/fixtures/lock/src/lib.rs b/ffi/fixtures/lock/src/lib.rs index ad0399fe4..beb7104af 100644 --- a/ffi/fixtures/lock/src/lib.rs +++ b/ffi/fixtures/lock/src/lib.rs @@ -186,3 +186,13 @@ pub const PAGES: i16 = 4; pub const LIMIT: u32 = 10; #[cfg(feature = "added")] pub const LIMIT: u32 = 20; + +/// A tuple whose C name, `lock_tuple_tuple_u32_u64_u8`, `next` gives another tuple too. +pub fn nested(x: ((u32,), u64, u8)) -> u32 { + x.0.0 +} + +#[cfg(feature = "next")] +pub fn flat(x: ((u32, u64), u8)) -> u32 { + x.0.0 +} diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index f522ffd59..d53d7da9d 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -589,7 +589,7 @@ impl<'a> Abi<'a> { /// A type by its key, with each tuple spelled as Rust spells it, which tells apart /// tuples that share a C name. - fn spell(&self, ty: &Type) -> String { + pub fn spell(&self, ty: &Type) -> String { match ty { Type::Tuple(elements) => { let elements: Vec = elements.iter().map(|e| self.spell(e)).collect(); diff --git a/ffi/src/cli.rs b/ffi/src/cli.rs index 1e86cd90c..d78cf0220 100644 --- a/ffi/src/cli.rs +++ b/ffi/src/cli.rs @@ -64,6 +64,18 @@ fn try_run(args: &[String]) -> Result { if output.0 != config::env::OUT && own.baseline.is_some() { return Err(format!("--baseline checks an export: give it with --out\n\n{USAGE}")); } + if let Some(baseline) = &own.baseline { + // The export's own api.json would silently replace the baseline it passed. + let api = output.1.join(crate::driver::API_FILE); + if let (Ok(a), Ok(b)) = (std::fs::canonicalize(baseline), std::fs::canonicalize(&api)) + && a == b + { + return Err(format!( + "--baseline {} is the api.json the export writes: commit the baseline outside --out\n\n{USAGE}", + baseline.display() + )); + } + } if output.0 != config::env::OUT && (targets.len() > 1 || !own.with.is_empty()) { return Err(format!( "--census and --api write one target's: give at most one --target and no --with\n\n{USAGE}" diff --git a/ffi/src/lock.rs b/ffi/src/lock.rs index c87e85b9c..4adcc56dc 100644 --- a/ffi/src/lock.rs +++ b/ffi/src/lock.rs @@ -6,7 +6,8 @@ //! that the export lacks, or has on fewer of the baseline's targets, is removed; one whose //! signature, fields, or variants differ is changed; and one whose C name differs is renamed, //! as an item added beside it makes it when their names clash, since a C caller of the old -//! name then calls the new item. An addition passes: a new item, method, trait impl, or a +//! name then calls the new item. A tuple's struct is known by its Rust spelling, and is +//! renamed the same way. An addition passes: a new item, method, trait impl, or a //! variant of an enum another crate cannot match exhaustively. use std::collections::BTreeMap; @@ -14,7 +15,7 @@ use std::collections::BTreeMap; use rustc_span::{DUMMY_SP, Span}; use crate::abi::{Abi, Ty}; -use crate::ir::{Access, Api, Constant, Function, Literal, On, Traits}; +use crate::ir::{Access, Api, Constant, Function, Literal, On, Traits, Type}; use crate::merge::{self, Maps}; /// An item the export's API breaks the baseline's at: where, and how. @@ -94,6 +95,19 @@ pub fn breaks(base: &Api, now: &Api, prefix: &str) -> Vec { }); } } + // A tuple the export no longer uses is no break: what used it reports its own change. + for (spelled, (c, _)) in &base.tuples { + let Some((theirs, span)) = now.tuples.get(spelled) else { + continue; + }; + if c != theirs { + let mut what = format!("tuple `{spelled}`: its C name `{c}` is now `{theirs}`"); + if let Some((other, _)) = now.tuples.iter().find(|(_, (n, _))| n == c) { + what += &format!(", and `{c}` names tuple `{other}`"); + } + breaks.push(Break { span: *span, what }); + } + } breaks } @@ -124,6 +138,9 @@ struct Entry<'a> { struct Index<'a> { api: &'a Api, entries: BTreeMap>, + /// Each tuple's struct by its Rust spelling: its C name, and a function that takes or + /// returns it. + tuples: BTreeMap, } impl<'a> Index<'a> { @@ -220,7 +237,32 @@ impl<'a> Index<'a> { }; entries.insert(format!("const {}", shown(&constant.path)), entry); } - Self { api, entries } + let mut tuples: BTreeMap = (abi.tuples.iter()) + .map(|(c, elements)| (abi.spell(&Type::Tuple(elements.clone())), (c.clone(), DUMMY_SP))) + .collect(); + let functions = (api.functions.iter()) + .chain(api.records.iter().flat_map(|r| &r.methods)) + .chain(api.enums.iter().flat_map(|e| &e.methods)) + .chain(api.objects.iter().flat_map(|o| &o.methods)); + for function in functions { + let types = function + .params + .iter() + .map(|p| &p.ty) + .chain([&function.ok]) + .chain(&function.err); + for ty in types { + crate::ir::each(ty, &mut |ty| { + if let Type::Tuple(elements) = ty { + let name = abi.tuple(elements); + if let Some((_, span)) = tuples.values_mut().find(|(c, span)| *c == name && span.is_dummy()) { + *span = function.span; + } + } + }); + } + } + Self { api, entries, tuples } } /// The item whose C name is `c`. diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index 5dc3ef1f6..85022c888 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -1378,6 +1378,17 @@ fn lock() { String::from_utf8_lossy(&output.stderr) ); let baseline = dir.join("base").join("api.json"); + let before = std::fs::read(&baseline).unwrap(); + let args = ["--baseline".as_ref(), baseline.as_os_str()]; + let itself = exporter("lock", &dir.join("base"), &targets, &args, &[]) + .output() + .expect("running rust2-ffi"); + assert!(!itself.status.success(), "a baseline the export would overwrite passed"); + assert_eq!( + std::fs::read(&baseline).unwrap(), + before, + "the export overwrote its baseline" + ); let locked = |feature: &str| { let args = ["--baseline".as_ref(), baseline.as_os_str()]; exporter("lock", &dir.join(feature), &targets, &args, &["--features", feature]) From 6680e1c18013acd490a982ed3ce383f036f019e8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 13 Nov 2026 00:33:58 -0800 Subject: [PATCH 9/9] fix(ffi): a tuple break points at a field or trait method too; refuse a hard-linked baseline Leave quest/m0/swift-gives-up.md as main has it: #730 finishes it. Test the lock's library-name guard and the hard-linked baseline. Co-Authored-By: Claude Opus 5.5 --- ffi/src/cli.rs | 17 ++++++++++++++--- ffi/src/lock.rs | 26 +++++++++++++++++--------- ffi/tests/fixtures.rs | 36 ++++++++++++++++++++++++++++++++++++ quest/m0/swift-gives-up.md | 3 +-- 4 files changed, 68 insertions(+), 14 deletions(-) diff --git a/ffi/src/cli.rs b/ffi/src/cli.rs index d78cf0220..c8da50144 100644 --- a/ffi/src/cli.rs +++ b/ffi/src/cli.rs @@ -67,9 +67,7 @@ fn try_run(args: &[String]) -> Result { if let Some(baseline) = &own.baseline { // The export's own api.json would silently replace the baseline it passed. let api = output.1.join(crate::driver::API_FILE); - if let (Ok(a), Ok(b)) = (std::fs::canonicalize(baseline), std::fs::canonicalize(&api)) - && a == b - { + if same_file(baseline, &api) { return Err(format!( "--baseline {} is the api.json the export writes: commit the baseline outside --out\n\n{USAGE}", baseline.display() @@ -611,6 +609,19 @@ struct Target { kind: Vec, } +/// Whether `a` and `b` are one file, through a symlink or a hard link. +fn same_file(a: &Path, b: &Path) -> bool { + #[cfg(unix)] + { + use std::os::unix::fs::MetadataExt; + matches!((std::fs::metadata(a), std::fs::metadata(b)), (Ok(a), Ok(b)) if (a.dev(), a.ino()) == (b.dev(), b.ino())) + } + #[cfg(not(unix))] + { + matches!((std::fs::canonicalize(a), std::fs::canonicalize(b)), (Ok(a), Ok(b)) if a == b) + } +} + #[cfg(test)] mod tests { use super::*; diff --git a/ffi/src/lock.rs b/ffi/src/lock.rs index 4adcc56dc..0d2f62c36 100644 --- a/ffi/src/lock.rs +++ b/ffi/src/lock.rs @@ -240,23 +240,31 @@ impl<'a> Index<'a> { let mut tuples: BTreeMap = (abi.tuples.iter()) .map(|(c, elements)| (abi.spell(&Type::Tuple(elements.clone())), (c.clone(), DUMMY_SP))) .collect(); + // Each item that names a type, with its span: a function by its signature, a + // record or enum by its fields. let functions = (api.functions.iter()) .chain(api.records.iter().flat_map(|r| &r.methods)) .chain(api.enums.iter().flat_map(|e| &e.methods)) - .chain(api.objects.iter().flat_map(|o| &o.methods)); - for function in functions { - let types = function - .params - .iter() - .map(|p| &p.ty) - .chain([&function.ok]) - .chain(&function.err); + .chain(api.objects.iter().flat_map(|o| &o.methods)) + .chain(api.callbacks.iter().flat_map(|c| &c.methods)) + .map(|f| { + let types: Vec<&Type> = f.params.iter().map(|p| &p.ty).chain([&f.ok]).chain(&f.err).collect(); + (f.span, types) + }); + let records = (api.records.iter()).map(|r| (r.span, r.fields.iter().map(|f| &f.ty).collect())); + let enums = (api.enums.iter()).map(|e| { + ( + e.span, + e.variants.iter().flat_map(|v| &v.fields).map(|f| &f.ty).collect(), + ) + }); + for (at, types) in functions.chain(records).chain(enums) { for ty in types { crate::ir::each(ty, &mut |ty| { if let Type::Tuple(elements) = ty { let name = abi.tuple(elements); if let Some((_, span)) = tuples.values_mut().find(|(c, span)| *c == name && span.is_dummy()) { - *span = function.span; + *span = at; } } }); diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index 85022c888..6492689bd 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -1389,6 +1389,42 @@ fn lock() { before, "the export overwrote its baseline" ); + let linked = dir.join("linked"); + let _ = std::fs::remove_dir_all(&linked); + std::fs::create_dir_all(&linked).unwrap(); + std::fs::hard_link(&baseline, linked.join("api.json")).unwrap(); + let args = ["--baseline".as_ref(), baseline.as_os_str()]; + let link = exporter("lock", &linked, &targets, &args, &[]) + .output() + .expect("running rust2-ffi"); + assert!( + !link.status.success(), + "a hard-linked baseline the export would overwrite passed" + ); + assert_eq!( + std::fs::read(&baseline).unwrap(), + before, + "the export overwrote its hard-linked baseline" + ); + // Every path starts with the library's name, so a baseline of another library breaks. + let renamed = dir.join("renamed.json"); + std::fs::write( + &renamed, + String::from_utf8(before.clone()) + .unwrap() + .replace("\"lock\"", "\"other\""), + ) + .unwrap(); + let args = ["--baseline".as_ref(), renamed.as_os_str()]; + let other = exporter("lock", &dir.join("renamed"), &targets, &args, &[]) + .output() + .expect("running rust2-ffi"); + assert!(!other.status.success(), "a baseline of another library passed"); + let stderr = String::from_utf8_lossy(&other.stderr); + assert!( + stderr.contains("library `other`: it is now `lock`"), + "no library error:\n{stderr}" + ); let locked = |feature: &str| { let args = ["--baseline".as_ref(), baseline.as_os_str()]; exporter("lock", &dir.join(feature), &targets, &args, &["--features", feature]) diff --git a/quest/m0/swift-gives-up.md b/quest/m0/swift-gives-up.md index 873f72785..dd5650f5a 100644 --- a/quest/m0/swift-gives-up.md +++ b/quest/m0/swift-gives-up.md @@ -10,8 +10,7 @@ closure" check in `ffi/tests/api.swift` no longer fails intermittently. Found while validating [#740](https://github.com/kixel-ai/rust2/pull/740) on 2026-11-13: `just ffi test --test fixtures` failed `api_swift` there in 2 of 4 runs, and at `main` `7008d1d3` in 1 of 5, each time with `"futures" failed: Rust gives up on an async closure`. -The test passes alone. It also failed once in `just ci` on -[#739](https://github.com/kixel-ai/rust2/pull/739) and passed three reruns alone. +The test passes alone. Two races fit, and the fix covers both: