1use std::collections::{BTreeMap, BTreeSet};
27
28use ridl_ir::v2;
29
30use crate::{Category, Change, Verdict, frozen};
31
32#[cfg(test)]
33mod classify_tests;
34
35pub fn classify(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
54 classify_in(change, old, new, &[], &[])
55}
56
57#[deny(
71 clippy::wildcard_enum_match_arm,
72 clippy::match_wildcard_for_single_variants
73)]
74pub(crate) fn classify_in(
75 change: &Change,
76 old: &v2::Package,
77 new: &v2::Package,
78 scope: &[&v2::Package],
79 encodings: &[&str],
80) -> Verdict {
81 match change.category {
82 Category::InteractionInserted
85 | Category::InteractionReordered
86 | Category::MemberReordered
87 | Category::InteractionRemoved
88 | Category::ReservedNameRedeclared
89 | Category::KindChanged
90 | Category::PayloadChanged
91 | Category::ReturnChanged
92 | Category::ParamsChanged
93 | Category::WidthChanged
94 | Category::ServiceChanged
95 | Category::DeclRemoved => Verdict::Breaking,
96
97 Category::InitChanged => Verdict::Breaking,
101
102 Category::DocOnly | Category::InteractionRetired => Verdict::Compatible,
109
110 Category::InterfaceRenamed | Category::InterfaceRetired => Verdict::Compatible,
117
118 Category::InterfaceFrozen => Verdict::Compatible,
124 Category::InterfaceNumberChanged => Verdict::Breaking,
125
126 Category::LimitChanged => Verdict::Breaking,
130
131 Category::EnumReordered => Verdict::Compatible,
137
138 Category::StrictEnumAppend | Category::EnumClosed => Verdict::Breaking,
143 Category::EnumOpened => Verdict::Compatible,
144
145 Category::ServiceInterfaceAdded | Category::ServiceInterfaceRemoved => Verdict::Compatible,
153
154 Category::VisibilityChanged => visibility(change, old, new),
155 Category::InteractionAppended => appended(change, old, new),
156 Category::DeclAdded => added(change, old, new, scope),
157 Category::ConstraintChanged => constraint(change, old, new, scope),
158 Category::TimingChanged => timing(change, old, new),
159 Category::RpcBoundChanged => rpc_bound(change, old, new),
160 Category::ContractChanged => contract(change, old, new),
161 Category::InteractionClassChanged => Verdict::Breaking,
165
166 Category::PodbufInlineAppend
174 | Category::PodbufRemoteInlineGrowth
175 | Category::PodbufWidthChange
176 | Category::PodbufStrictEnumAppend => {
177 if encodings.contains(&"podbuf") {
178 Verdict::Breaking
179 } else {
180 Verdict::Compatible
181 }
182 }
183 Category::FlatbuffersWidthChange => {
184 if encodings.contains(&"flatbuffers") {
185 Verdict::Breaking
186 } else {
187 Verdict::Compatible
188 }
189 }
190 Category::Proto3WidthChange => {
191 if encodings.contains(&"proto3") {
192 Verdict::Breaking
193 } else {
194 Verdict::Compatible
195 }
196 }
197 }
198}
199
200fn visibility(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
218 let (Some(old_visibility), Some(new_visibility)) = (
219 find_visibility(old, &change.path, |name| find_old_shape(old, new, name)),
220 find_visibility(new, &change.path, |name| find_shape(new, name)),
221 ) else {
222 return Verdict::Breaking;
223 };
224
225 match (
226 v2::Visibility::try_from(old_visibility),
227 v2::Visibility::try_from(new_visibility),
228 ) {
229 (Ok(v2::Visibility::Internal), Ok(v2::Visibility::Public)) => Verdict::Compatible,
230 _ => Verdict::Breaking,
231 }
232}
233
234fn find_visibility<'a>(
241 package: &'a v2::Package,
242 path: &str,
243 shape_of: impl Fn(&str) -> Option<v2::InterfaceShape<'a>>,
244) -> Option<i32> {
245 let mut segments = path.split('/').skip(1);
246 let name = segments.next()?;
247
248 if let Some(member) = segments.next() {
249 return shape_of(name)?
250 .interface
251 .interactions
252 .iter()
253 .find(|decl| decl.name == member)
254 .map(|decl| decl.visibility);
255 }
256 if let Some(decl) = find_decl(package, name) {
257 return Some(decl.visibility);
258 }
259 if let Some(shape) = shape_of(name) {
264 return Some(shape.visibility());
265 }
266 package
269 .services
270 .iter()
271 .find(|service| service.name == name)
272 .map(|service| service.visibility)
273}
274
275fn appended(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
290 let Some((container, member)) = member_path(change) else {
291 return Verdict::Breaking;
292 };
293 let (Some(old_iface), Some(new_iface)) = (
294 find_old_interface(old, new, container),
295 find_interface(new, container),
296 ) else {
297 return Verdict::Breaking;
298 };
299 let Some(ordinal) = slot_ordinal(new_iface, member) else {
300 return Verdict::Breaking;
301 };
302
303 for (name, old_ordinal) in slots(old_iface) {
304 if old_ordinal == ordinal && name != member {
305 return Verdict::Breaking;
306 }
307 }
308 Verdict::Compatible
309}
310
311fn added(change: &Change, old: &v2::Package, new: &v2::Package, scope: &[&v2::Package]) -> Verdict {
327 let Some((container, member)) = member_path(change) else {
328 return Verdict::Compatible;
331 };
332 let (Some(old_decl), Some(new_decl)) = (find_decl(old, container), find_decl(new, container))
333 else {
334 return Verdict::Breaking;
335 };
336
337 use v2::decl::Kind;
342 let appended = match (&old_decl.kind, &new_decl.kind) {
343 (Some(Kind::StructDef(old_def)), Some(Kind::StructDef(new_def))) => {
344 appended_slot(
345 &struct_slots(old_def),
346 &struct_reserved(old_def),
347 &struct_slots(new_def),
348 ) && absence_reads_as_legal(new_def, member, new, scope)
349 }
350 (Some(Kind::UnionDef(old_def)), Some(Kind::UnionDef(new_def))) => {
351 !old_def.is_result
354 && !new_def.is_result
355 && appended_slot(
356 &union_slots(old_def),
357 &union_reserved(old_def),
358 &union_slots(new_def),
359 )
360 }
361 (Some(Kind::EnumDef(old_def)), Some(Kind::EnumDef(new_def))) => {
366 new_def.open
367 && appended_slot(
368 &value_slots(&old_def.values),
369 &reserved_values(&old_def.reserved),
370 &value_slots(&new_def.values),
371 )
372 }
373 (Some(Kind::EnumSetDef(old_def)), Some(Kind::EnumSetDef(new_def))) => {
374 new_def.open
375 && appended_slot(
376 &value_slots(&old_def.bits),
377 &[],
378 &value_slots(&new_def.bits),
379 )
380 }
381 _ => false,
383 };
384
385 if appended {
386 Verdict::Compatible
387 } else {
388 Verdict::Breaking
389 }
390}
391
392pub(crate) fn is_strict_enum_append(old_decl: &v2::Decl, new_decl: &v2::Decl) -> bool {
397 use v2::decl::Kind;
398 match (&old_decl.kind, &new_decl.kind) {
399 (Some(Kind::EnumDef(old_def)), Some(Kind::EnumDef(new_def))) => {
400 !new_def.open
401 && appended_slot(
402 &value_slots(&old_def.values),
403 &reserved_values(&old_def.reserved),
404 &value_slots(&new_def.values),
405 )
406 }
407 (Some(Kind::EnumSetDef(old_def)), Some(Kind::EnumSetDef(new_def))) => {
408 !new_def.open
409 && appended_slot(
410 &value_slots(&old_def.bits),
411 &[],
412 &value_slots(&new_def.bits),
413 )
414 }
415 _ => false,
416 }
417}
418
419pub fn absence_refused(
428 new_set: &[v2::Package],
429 context: &[v2::Package],
430 package: &str,
431 container: &str,
432 member: &str,
433) -> bool {
434 let scope: Vec<&v2::Package> = new_set.iter().chain(context).collect();
435 let Some(home) = new_set.iter().find(|candidate| candidate.name == package) else {
436 return false;
437 };
438 match find_decl(home, container).and_then(|decl| decl.kind.as_ref()) {
439 Some(v2::decl::Kind::StructDef(def)) => !absence_reads_as_legal(def, member, home, &scope),
440 _ => false,
441 }
442}
443
444fn absence_reads_as_legal(
464 def: &v2::StructDef,
465 member: &str,
466 home: &v2::Package,
467 scope: &[&v2::Package],
468) -> bool {
469 let Some(r#type) = def.members.iter().find_map(|slot| match &slot.member {
470 Some(v2::struct_member::Member::Field(field)) if field.name == member => {
471 field.r#type.as_ref()
472 }
473 _ => None,
474 }) else {
475 return false;
476 };
477 ridl_ir::zero::field_type_holds_zero(r#type, |reference| resolve(home, scope, reference))
478}
479
480fn resolve<'a>(
484 home: &'a v2::Package,
485 scope: &[&'a v2::Package],
486 reference: &str,
487) -> Option<&'a v2::Decl> {
488 match reference.rsplit_once('.') {
489 Some((package, name)) => std::iter::once(home)
490 .chain(scope.iter().copied())
491 .find(|candidate| candidate.name == package)
492 .and_then(|candidate| find_decl(candidate, name)),
493 None => find_decl(home, reference),
494 }
495}
496
497fn appended_slot(old: &[(String, i64)], old_retired: &[i64], new: &[(String, i64)]) -> bool {
508 let mut new_slots: BTreeMap<&str, i64> = BTreeMap::new();
510 for (name, slot) in new {
511 new_slots.entry(name.as_str()).or_insert(*slot);
512 }
513 for (name, old_slot) in old {
514 match new_slots.get(name.as_str()) {
515 Some(new_slot) if new_slot == old_slot => {}
516 _ => return false,
518 }
519 }
520
521 let mark = old
524 .iter()
525 .map(|(_, slot)| *slot)
526 .chain(old_retired.iter().copied())
527 .max();
528 let old_names: BTreeSet<&str> = old.iter().map(|(name, _)| name.as_str()).collect();
529 for (name, slot) in new {
530 if old_names.contains(name.as_str()) {
531 continue;
532 }
533 if !is_above_high_water(*slot, mark) {
534 return false;
535 }
536 }
537 true
538}
539
540pub fn is_above_high_water(slot: i64, held: impl IntoIterator<Item = i64>) -> bool {
549 held.into_iter().max().is_none_or(|mark| slot > mark)
550}
551
552fn constraint(
565 change: &Change,
566 old: &v2::Package,
567 new: &v2::Package,
568 scope: &[&v2::Package],
569) -> Verdict {
570 let mut segments = change.path.split('/').skip(1);
571 let (Some(name), None) = (segments.next(), segments.next()) else {
572 return Verdict::Breaking;
573 };
574 let (Some(old_decl), Some(new_decl)) = (find_decl(old, name), find_decl(new, name)) else {
575 return Verdict::Breaking;
576 };
577
578 use v2::decl::Kind;
579 let (Some(Kind::TypeDef(old_def)), Some(Kind::TypeDef(new_def))) =
580 (&old_decl.kind, &new_decl.kind)
581 else {
582 return Verdict::Breaking;
583 };
584
585 if narrows(old_def.constraint.as_ref(), new_def.constraint.as_ref()) {
586 Verdict::Breaking
587 } else {
588 crate::direction::widening_verdict(new, scope, &format!("{}.{}", new.name, name))
589 }
590}
591
592pub(crate) fn narrows(old: Option<&v2::Constraint>, new: Option<&v2::Constraint>) -> bool {
599 let (Some(old), Some(new)) = (old, new) else {
600 return old.is_none() && new.is_some();
603 };
604
605 if raised(old.min.as_deref(), new.min.as_deref())
607 || lowered(old.max.as_deref(), new.max.as_deref())
608 {
609 return true;
610 }
611 if raised_u64(old.len_min, new.len_min) || lowered_u64(old.len_max, new.len_max) {
613 return true;
614 }
615 if new.step.is_some() && old.step != new.step {
618 return true;
619 }
620 if let Some(step) = new.step.as_deref()
623 && old.min != new.min
624 && !same_grid(old.min.as_deref(), new.min.as_deref(), step)
625 {
626 return true;
627 }
628 if (new.pattern.is_some() && old.pattern != new.pattern)
631 || (new.pattern_const.is_some() && old.pattern_const != new.pattern_const)
632 {
633 return true;
634 }
635 false
636}
637
638fn same_grid(old: Option<&str>, new: Option<&str>, step: &str) -> bool {
642 use num_bigint::BigInt;
643
644 let read = |text: &str| -> Option<(BigInt, usize)> {
645 let (negative, digits) = split_sign(text)?;
646 let (whole, fraction) = digits.split_once('.').unwrap_or((&digits, ""));
647 if whole.is_empty() || (digits.contains('.') && fraction.is_empty()) {
648 return None;
649 }
650 let coefficient = BigInt::parse_bytes(format!("{whole}{fraction}").as_bytes(), 10)?;
651 Some((
652 if negative { -coefficient } else { coefficient },
653 fraction.len(),
654 ))
655 };
656 let (Some(old), Some(new), Some(step)) = (
657 read(old.unwrap_or("0")),
658 read(new.unwrap_or("0")),
659 read(step),
660 ) else {
661 return false;
662 };
663 let scale = old.1.max(new.1).max(step.1);
664 let rescale = |(coefficient, places): (BigInt, usize)| -> Option<BigInt> {
665 Some(coefficient * BigInt::from(10).pow(u32::try_from(scale - places).ok()?))
666 };
667 let (Some(old), Some(new), Some(step)) = (rescale(old), rescale(new), rescale(step)) else {
668 return false;
669 };
670 step > BigInt::from(0) && (old - new) % step == BigInt::from(0)
671}
672
673fn raised(old: Option<&str>, new: Option<&str>) -> bool {
675 match (old, new) {
676 (None, Some(_)) => true,
677 (Some(old), Some(new)) => cmp_decimal(new, old).is_none_or(std::cmp::Ordering::is_gt),
678 _ => false,
679 }
680}
681
682fn lowered(old: Option<&str>, new: Option<&str>) -> bool {
684 match (old, new) {
685 (None, Some(_)) => true,
686 (Some(old), Some(new)) => cmp_decimal(new, old).is_none_or(std::cmp::Ordering::is_lt),
687 _ => false,
688 }
689}
690
691fn raised_u64(old: Option<u64>, new: Option<u64>) -> bool {
692 match (old, new) {
693 (None, Some(_)) => true,
694 (Some(old), Some(new)) => new > old,
695 _ => false,
696 }
697}
698
699fn lowered_u64(old: Option<u64>, new: Option<u64>) -> bool {
700 match (old, new) {
701 (None, Some(_)) => true,
702 (Some(old), Some(new)) => new < old,
703 _ => false,
704 }
705}
706
707fn cmp_decimal(left: &str, right: &str) -> Option<std::cmp::Ordering> {
717 use std::cmp::Ordering;
718
719 let (left_negative, left_digits) = split_sign(left)?;
720 let (right_negative, right_digits) = split_sign(right)?;
721 if left_negative != right_negative {
722 return Some(if left_negative {
725 Ordering::Less
726 } else {
727 Ordering::Greater
728 });
729 }
730
731 let magnitude = cmp_magnitude(&left_digits, &right_digits)?;
732 Some(if left_negative {
733 magnitude.reverse()
734 } else {
735 magnitude
736 })
737}
738
739fn split_sign(text: &str) -> Option<(bool, String)> {
742 let (negative, rest) = match text.strip_prefix('-') {
743 Some(rest) => (true, rest),
744 None => (false, text.strip_prefix('+').unwrap_or(text)),
745 };
746 if rest.is_empty() || !rest.chars().all(|c| c.is_ascii_digit() || c == '.') {
747 return None;
748 }
749 if rest.matches('.').count() > 1 {
750 return None;
751 }
752 Some((negative, rest.to_string()))
753}
754
755fn cmp_magnitude(left: &str, right: &str) -> Option<std::cmp::Ordering> {
758 use std::cmp::Ordering;
759
760 let (left_int, left_frac) = left.split_once('.').unwrap_or((left, ""));
761 let (right_int, right_frac) = right.split_once('.').unwrap_or((right, ""));
762
763 let left_int = left_int.trim_start_matches('0');
764 let right_int = right_int.trim_start_matches('0');
765 let by_length = left_int.len().cmp(&right_int.len());
766 if by_length != Ordering::Equal {
767 return Some(by_length);
768 }
769 let by_int = left_int.cmp(right_int);
770 if by_int != Ordering::Equal {
771 return Some(by_int);
772 }
773
774 let width = left_frac.len().max(right_frac.len());
776 let pad = |frac: &str| format!("{frac:0<width$}");
777 Some(pad(left_frac).cmp(&pad(right_frac)))
778}
779
780fn timing(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
792 let Some((container, member)) = member_path(change) else {
793 return Verdict::Breaking;
794 };
795 let (Some(old_decl), Some(new_decl)) = (
796 find_old_interaction(old, new, container, member),
797 find_interaction(new, container, member),
798 ) else {
799 return Verdict::Breaking;
800 };
801 let (Some(old_timing), Some(new_timing)) =
802 (interaction_timing(old_decl), interaction_timing(new_decl))
803 else {
804 return Verdict::Breaking;
814 };
815
816 let (Some(old_timing), Some(new_timing)) = (old_timing, new_timing) else {
817 return Verdict::Breaking;
820 };
821
822 if old_timing.mode != new_timing.mode {
823 return Verdict::Breaking;
824 }
825 if lowered(old_timing.min_us.as_deref(), new_timing.min_us.as_deref())
827 || dropped(old_timing.min_us.as_deref(), new_timing.min_us.as_deref())
828 || raised(old_timing.max_us.as_deref(), new_timing.max_us.as_deref())
829 || dropped(old_timing.max_us.as_deref(), new_timing.max_us.as_deref())
830 {
831 return Verdict::Breaking;
832 }
833 Verdict::Compatible
836}
837
838fn rpc_bound(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
857 let Some((container, member)) = member_path(change) else {
858 return Verdict::Breaking;
859 };
860 let (Some(old_decl), Some(new_decl)) = (
861 find_old_interaction(old, new, container, member),
862 find_interaction(new, container, member),
863 ) else {
864 return Verdict::Breaking;
865 };
866 let (Some(old_timing), Some(new_timing)) = (rpc_timing(old_decl), rpc_timing(new_decl)) else {
867 return Verdict::Breaking;
874 };
875
876 let (Some(old_timing), Some(new_timing)) = (old_timing, new_timing) else {
877 return Verdict::Breaking;
880 };
881
882 if old_timing.mode != new_timing.mode {
885 return Verdict::Breaking;
886 }
887 if raised(old_timing.min_us.as_deref(), new_timing.min_us.as_deref())
892 || dropped(old_timing.min_us.as_deref(), new_timing.min_us.as_deref())
893 || raised(old_timing.max_us.as_deref(), new_timing.max_us.as_deref())
894 || dropped(old_timing.max_us.as_deref(), new_timing.max_us.as_deref())
895 {
896 return Verdict::Breaking;
897 }
898 Verdict::Compatible
904}
905
906fn dropped(old: Option<&str>, new: Option<&str>) -> bool {
908 old.is_some() && new.is_none()
909}
910
911fn interaction_timing(decl: &v2::Decl) -> Option<Option<&v2::Timing>> {
914 use v2::decl::Kind;
915 match &decl.kind {
916 Some(Kind::SignalDef(def)) => Some(def.timing.as_ref()),
917 Some(Kind::EventDef(def)) => Some(def.timing.as_ref()),
918 _ => None,
919 }
920}
921
922fn rpc_timing(decl: &v2::Decl) -> Option<Option<&v2::Timing>> {
926 use v2::decl::Kind;
927 match &decl.kind {
928 Some(Kind::CommandDef(def)) => Some(def.timing.as_ref()),
929 Some(Kind::QueryDef(def)) => Some(def.timing.as_ref()),
930 _ => None,
931 }
932}
933
934fn contract(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
948 let Some((container, member)) = member_path(change) else {
949 return Verdict::Breaking;
950 };
951 let (Some(old_decl), Some(new_decl)) = (
952 find_old_interaction(old, new, container, member),
953 find_interaction(new, container, member),
954 ) else {
955 return Verdict::Breaking;
956 };
957 let (Some(old_clauses), Some(new_clauses)) = (contracts(old_decl), contracts(new_decl)) else {
958 return Verdict::Breaking;
959 };
960
961 let kind = |want: v2::ContractKind| {
962 move |clause: &&v2::Contract| v2::ContractKind::try_from(clause.kind) == Ok(want)
963 };
964 let sources = |clauses: &[v2::Contract], want: v2::ContractKind| -> Vec<String> {
965 let mut out: Vec<String> = clauses
966 .iter()
967 .filter(kind(want))
968 .map(|clause| clause.source.clone())
969 .collect();
970 out.sort();
971 out
972 };
973
974 let old_require = sources(old_clauses, v2::ContractKind::Require);
975 let new_require = sources(new_clauses, v2::ContractKind::Require);
976 let old_ensure = sources(old_clauses, v2::ContractKind::Ensure);
977 let new_ensure = sources(new_clauses, v2::ContractKind::Ensure);
978
979 if !covers(&old_require, &new_require) || !covers(&new_ensure, &old_ensure) {
980 return Verdict::Breaking;
981 }
982 Verdict::Compatible
983}
984
985fn covers(superset: &[String], subset: &[String]) -> bool {
987 let mut remaining: Vec<&String> = superset.iter().collect();
988 for clause in subset {
989 match remaining.iter().position(|held| *held == clause) {
990 Some(index) => {
991 remaining.swap_remove(index);
992 }
993 None => return false,
994 }
995 }
996 true
997}
998
999fn contracts(decl: &v2::Decl) -> Option<&[v2::Contract]> {
1001 use v2::decl::Kind;
1002 match &decl.kind {
1003 Some(Kind::CommandDef(def)) => Some(&def.contracts),
1004 Some(Kind::QueryDef(def)) => Some(&def.contracts),
1005 _ => None,
1006 }
1007}
1008
1009fn member_path(change: &Change) -> Option<(&str, &str)> {
1016 let mut segments = change.path.split('/').skip(1);
1017 let container = segments.next()?;
1018 let member = segments.next()?;
1019 if segments.next().is_some() {
1020 return None;
1021 }
1022 Some((container, member))
1023}
1024
1025pub(crate) fn find_decl<'a>(package: &'a v2::Package, name: &str) -> Option<&'a v2::Decl> {
1026 package.decls.iter().find(|decl| decl.name == name)
1027}
1028
1029fn find_shape<'a>(package: &'a v2::Package, name: &str) -> Option<v2::InterfaceShape<'a>> {
1034 package.shapes().find(|shape| shape.name == name)
1035}
1036
1037fn find_old_shape<'a>(
1044 old: &'a v2::Package,
1045 new: &v2::Package,
1046 name: &str,
1047) -> Option<v2::InterfaceShape<'a>> {
1048 let by_number = find_shape(new, name)
1049 .filter(|shape| frozen(shape.interface))
1050 .and_then(|shape| {
1051 old.shapes().find(|candidate| {
1052 frozen(candidate.interface) && candidate.interface.number == shape.interface.number
1053 })
1054 });
1055 by_number.or_else(|| find_shape(old, name))
1056}
1057
1058fn find_interface<'a>(package: &'a v2::Package, name: &str) -> Option<&'a v2::Interface> {
1059 find_shape(package, name).map(|shape| shape.interface)
1060}
1061
1062fn find_old_interface<'a>(
1063 old: &'a v2::Package,
1064 new: &v2::Package,
1065 name: &str,
1066) -> Option<&'a v2::Interface> {
1067 find_old_shape(old, new, name).map(|shape| shape.interface)
1068}
1069
1070fn find_interaction<'a>(
1071 package: &'a v2::Package,
1072 container: &str,
1073 member: &str,
1074) -> Option<&'a v2::Decl> {
1075 find_interface(package, container)?
1076 .interactions
1077 .iter()
1078 .find(|decl| decl.name == member)
1079}
1080
1081fn find_old_interaction<'a>(
1084 old: &'a v2::Package,
1085 new: &v2::Package,
1086 container: &str,
1087 member: &str,
1088) -> Option<&'a v2::Decl> {
1089 find_old_interface(old, new, container)?
1090 .interactions
1091 .iter()
1092 .find(|decl| decl.name == member)
1093}
1094
1095fn slots(interface: &v2::Interface) -> Vec<(&str, u32)> {
1107 interface
1108 .interactions
1109 .iter()
1110 .filter_map(|decl| match &decl.kind {
1111 Some(v2::decl::Kind::ReservedSlot(reserved)) => {
1112 Some((reserved.name.as_deref().unwrap_or(""), decl.ordinal))
1113 }
1114 Some(_) => Some((decl.name.as_str(), decl.ordinal)),
1115 None => None,
1116 })
1117 .collect()
1118}
1119
1120fn slot_ordinal(interface: &v2::Interface, member: &str) -> Option<u32> {
1121 slots(interface)
1122 .into_iter()
1123 .find(|(name, _)| *name == member)
1124 .map(|(_, ordinal)| ordinal)
1125}
1126
1127pub(crate) fn struct_slots(def: &v2::StructDef) -> Vec<(String, i64)> {
1131 def.members
1132 .iter()
1133 .filter_map(|member| match &member.member {
1134 Some(v2::struct_member::Member::Field(field)) => {
1135 Some((field.name.clone(), i64::from(field.ordinal)))
1136 }
1137 _ => None,
1138 })
1139 .collect()
1140}
1141
1142fn struct_reserved(def: &v2::StructDef) -> Vec<i64> {
1143 def.members
1144 .iter()
1145 .filter_map(|member| match &member.member {
1146 Some(v2::struct_member::Member::Reserved(reserved)) => {
1147 Some(i64::from(reserved.ordinal))
1148 }
1149 _ => None,
1150 })
1151 .collect()
1152}
1153
1154pub(crate) fn union_slots(def: &v2::UnionDef) -> Vec<(String, i64)> {
1156 def.arms
1157 .iter()
1158 .map(|arm| (arm.name.clone(), i64::from(arm.ordinal)))
1159 .collect()
1160}
1161
1162fn union_reserved(def: &v2::UnionDef) -> Vec<i64> {
1163 def.reserved
1164 .iter()
1165 .map(|reserved| i64::from(reserved.ordinal))
1166 .collect()
1167}
1168
1169pub(crate) fn value_slots(values: &[v2::EnumValue]) -> Vec<(String, i64)> {
1172 values
1173 .iter()
1174 .map(|value| (value.name.clone(), value.value))
1175 .collect()
1176}
1177
1178fn reserved_values(reserved: &[v2::Reserved]) -> Vec<i64> {
1179 reserved.iter().filter_map(|entry| entry.value).collect()
1180}
1181
1182pub fn category_from_word(word: &str) -> Option<Category> {
1189 crate::CATEGORIES
1190 .into_iter()
1191 .find(|category| crate::category_word(*category) == word)
1192}
1193
1194#[deny(
1204 clippy::wildcard_enum_match_arm,
1205 clippy::match_wildcard_for_single_variants
1206)]
1207pub fn explain(category: Category) -> &'static str {
1208 match category {
1209 Category::DeclAdded => concat!(
1210 "A declaration, interface, or service present only in the new snapshot.\n",
1211 " compatible a new package-level decl, interface, or service; an enum\n",
1212 " value appended above every live and retired number; a\n",
1213 " union arm appended at the end of the body (typl 7.4,\n",
1214 " append-only); a struct field appended at the end of the body\n",
1215 " when it is optional, or when it is a scalar, enum, or enum set\n",
1216 " whose type allows the value 0\n",
1217 " breaking a member inserted below the highest slot ever used, a member\n",
1218 " taking a retired number, any addition that moves a surviving\n",
1219 " member's slot, or any arm of a result union (ADR-0008 d4); a\n",
1220 " non-optional struct field appended whose type does not allow\n",
1221 " 0 — a string, bytes, struct, union, tuple, array, or map, a\n",
1222 " scalar whose range or step excludes 0, an enum with no zero\n",
1223 " member, or a type the diff cannot resolve (ridl diff\n",
1224 " resolves ridl.std types). A reader of the new version\n",
1225 " refuses every payload of the old one, which does not carry\n",
1226 " the field (typl 7.4). Declare the new field optional instead\n",
1227 " (`field : T?`): an absent optional field reads as absent\n",
1228 " note an interface is matched by its interfaces.lock number (lock\n",
1229 " design 7): a frozen number the old side never held is a new\n",
1230 " interface, and so is every provisional one — a declaration\n",
1231 " with no lock entry carries no identity, and a rename keeps its\n",
1232 " number, so it is never a renamed interface (interface_renamed)"
1233 ),
1234 Category::DeclRemoved => concat!(
1235 "A declaration, interface, or service present only in the old snapshot.\n",
1236 " breaking a removed service, interface, decl, enum value, struct\n",
1237 " field, or union arm withdraws something a consumer compiled\n",
1238 " against\n",
1239 " note an interface is matched by its interfaces.lock number (lock\n",
1240 " design 7), so an interface here is one whose number is gone\n",
1241 " from the new side and not retired there — a lock line deleted\n",
1242 " by hand, or a number changed by hand, which is this row plus\n",
1243 " decl_added. A number the new side's lock retires is\n",
1244 " interface_retired instead, and `ridl baseline` refuses to\n",
1245 " publish the removal of a number it does not find retired\n",
1246 " (RIDL-412). A removed unit, whose\n",
1247 " packages are gone from the new set, is also decl_removed.\n",
1248 " For its allocated interface numbers, `ridl baseline` refuses\n",
1249 " publication with RIDL-412. To remove the unit on purpose,\n",
1250 " run ridl baseline CURRENT_SOURCE --reset-history --out BASELINE\n",
1251 " (see the CLI reference, Baseline publication and recovery)\n",
1252 " caveat a composite member retired the sanctioned way — replaced by\n",
1253 " a `reserved` tombstone in its own slot (typl 7.4) — is also\n",
1254 " reported breaking today. The body comparison is keyed on\n",
1255 " member names and does not read the `reserved` list, so it\n",
1256 " cannot yet tell that retirement from a bare deletion. This\n",
1257 " errs on the safe side; carried as debt, see the note on\n",
1258 " `diff_composite`. The interaction-level tombstone IS\n",
1259 " recognised — see interaction_retired"
1260 ),
1261 Category::InterfaceRenamed => concat!(
1262 "An interface whose interfaces.lock number is the same on both sides and\n",
1263 "whose name changed.\n",
1264 " compatible always — the number is the interface's identity and its\n",
1265 " routing key (lock design 7, rsdl decision D-7), so nothing\n",
1266 " moves on the wire. Visible in source: a rename changes the\n",
1267 " generated identity-table names in both wire backends, which\n",
1268 " is why the text report lists it under the heading\n",
1269 " \"compatible on the wire, visible in source\". The path\n",
1270 " carries the new name and the detail old -> new; changes\n",
1271 " inside the interface are reported under the new name and\n",
1272 " classified as any other interface's\n",
1273 " note a provisional number is no identity: a declaration with no\n",
1274 " lock entry is never matched, so a rename the lock does not\n",
1275 " record is decl_removed plus decl_added, breaking, until\n",
1276 " `ridl lock <pkg> --rename Old=New` records it"
1277 ),
1278 Category::InterfaceRetired => concat!(
1279 "An interface whose number the old snapshot held is gone from the new\n",
1280 "snapshot, whose interfaces.lock retires it.\n",
1281 " compatible always — the sanctioned removal of an interface: the entry\n",
1282 " keeps its number forever with the word `retired`, so the\n",
1283 " number is never allocated again (lock design 4 and 7, rsdl\n",
1284 " decision D-7). A number gone with no retired entry is\n",
1285 " decl_removed, breaking, and `ridl baseline` refuses to publish\n",
1286 " it (RIDL-412)"
1287 ),
1288 Category::InterfaceFrozen => concat!(
1289 "An interface matched by name whose number is the same on both sides and\n",
1290 "whose provisional flag went from true to false: `ridl lock` froze the\n",
1291 "number in place.\n",
1292 " compatible always — the number is the routing key and it did not\n",
1293 " change, so nothing moves on the wire. The catalog hash\n",
1294 " changes, because it covers each interface's number and its\n",
1295 " provisional flag, and a generated face refuses a port whose\n",
1296 " catalog hash is another one (ADR-0023 decision 8): a peer\n",
1297 " built before the lock and a peer built after it refuse each\n",
1298 " other. This is why the text report lists it under the\n",
1299 " heading \"compatible on the wire, may change the catalog\n",
1300 " hash\".\n",
1301 " The detail carries the number before and after, marked\n",
1302 " (provisional) on the old side\n",
1303 " note a baseline never holds a provisional number (`ridl baseline`\n",
1304 " refuses one, RIDL-411), so this change is seen between two\n",
1305 " builds, or in a reversed comparison whose old side is a\n",
1306 " build. A number 0 on either side, from a snapshot written\n",
1307 " before the lock existed, is not compared"
1308 ),
1309 Category::InterfaceNumberChanged => concat!(
1310 "An interface matched across the two sides whose number differs.\n",
1311 " breaking always — the number is the interface's routing key, so a\n",
1312 " peer built against the old number cannot reach the\n",
1313 " interface at the new one. Seen between two provisional\n",
1314 " builds when a sibling interface added before this one in\n",
1315 " byte order moves its provisional number, and when `ridl\n",
1316 " lock` freezes a provisional number as another number. The\n",
1317 " detail carries the old and the new number, each marked\n",
1318 " (provisional) when it is\n",
1319 " note two frozen numbers are matched by number, so they never\n",
1320 " differ here: a frozen number changed by hand is\n",
1321 " decl_removed plus decl_added. A number 0 on either side,\n",
1322 " from a snapshot written before the lock existed, is not\n",
1323 " compared.\n",
1324 " Run `ridl lock` to freeze the numbers, so that a later\n",
1325 " sibling cannot move them"
1326 ),
1327 Category::MemberReordered => concat!(
1328 "A surviving composite member whose slot in the body changed.\n",
1329 " breaking always — a struct field or union arm takes its wire\n",
1330 " identity from its ordinal, its 1-based place in the body\n",
1331 " counting tombstones (typl 7.4), so a member whose ordinal\n",
1332 " changed has a new wire identity; the detail carries the old\n",
1333 " and new ordinal. An enum value or enum-set bit takes its\n",
1334 " identity from the explicit number it declares (typl 8, 9),\n",
1335 " so one whose number changed has a new wire identity; the\n",
1336 " detail carries the old and new value or bit. An enum or\n",
1337 " enum-set body reordered with no number changed is\n",
1338 " enum_reordered, compatible, instead\n",
1339 " note reported only when both bodies hold the same member names:\n",
1340 " a reorder in the same edit as an addition or a removal is\n",
1341 " reported through decl_added or decl_removed alone. A reorder\n",
1342 " in the same edit as an in-place change to the body is\n",
1343 " reported with constraint_changed on the container as well.\n",
1344 " An enum or enum-set body whose only differences are changed\n",
1345 " numbers, in any order, reports member_reordered alone"
1346 ),
1347 Category::EnumReordered => concat!(
1348 "An enum or enum-set body whose difference is only order: its values or\n",
1349 "bits reordered with no number changed, the enum's reserved list\n",
1350 "reordered with no entry added, removed or changed, or both.\n",
1351 " compatible always — a value or bit takes its identity from the\n",
1352 " explicit number it declares (typl 8, 9), so nothing moves\n",
1353 " on the wire. The catalog hash covers only the declarations\n",
1354 " an interface reaches. When an interface reaches the enum or\n",
1355 " enum set, the order of its values or bits, and of an enum's\n",
1356 " reserved list, is part of the hash, so the hash changes\n",
1357 " then, and a generated face refuses a port whose catalog hash\n",
1358 " is another one (ADR-0023 decision 8). This is why the text\n",
1359 " report lists it under the heading \"compatible on the wire,\n",
1360 " may change the catalog hash\". The path is the container's;\n",
1361 " there is no detail\n",
1362 " note a value or bit whose number changed is member_reordered,\n",
1363 " breaking, not enum_reordered"
1364 ),
1365 Category::InteractionAppended => concat!(
1366 "An interaction added after every slot that existed before.\n",
1367 " compatible the slot it takes was never occupied\n",
1368 " breaking the slot was freed by an untombstoned removal and is now\n",
1369 " reused by a new name — a reused wire identity (ADR-0008 d14)"
1370 ),
1371 Category::InteractionInserted => concat!(
1372 "An interaction added before the end of the interface body.\n",
1373 " breaking always — every later ordinal shifts, and the ordinal is the\n",
1374 " transport identity (ridl 11)"
1375 ),
1376 Category::InteractionReordered => concat!(
1377 "A surviving interaction whose relative order in the body changed.\n",
1378 " breaking always — a reorder shifts wire identities (ridl 11)"
1379 ),
1380 Category::InteractionRemoved => concat!(
1381 "An interaction removed without a `reserved` tombstone holding its slot.\n",
1382 " breaking always — the freed ordinal is reusable, so the wire identity\n",
1383 " is no longer permanent (ridl 11)"
1384 ),
1385 Category::InteractionRetired => concat!(
1386 "An interaction retired to a `reserved` tombstone in its own ordinal slot.\n",
1387 " compatible always — the sanctioned retirement: the slot stays occupied\n",
1388 " and every later ordinal holds (ridl 11)"
1389 ),
1390 Category::KindChanged => concat!(
1391 "An interaction whose kind changed (signal, event, command, query, fixed).\n",
1392 " breaking any direction — the kind selects the transport shape"
1393 ),
1394 Category::PayloadChanged => concat!(
1395 "A signal, event, or fixed payload type changed.\n",
1396 " breaking any direction, a stream added or removed included"
1397 ),
1398 Category::ReturnChanged => concat!(
1399 "A query return shape changed.\n",
1400 " breaking any direction — an ok-arm change, an error arm added, removed,\n",
1401 " or retyped, a stream added or removed, or any other change to\n",
1402 " the synthesized inline `T | E` transport identity (ADR-0008 d4:\n",
1403 " interface + interaction ordinal + ordered arm types)"
1404 ),
1405 Category::ParamsChanged => concat!(
1406 "A command or query parameter list changed.\n",
1407 " breaking any direction — a parameter added, removed, renamed, retyped,\n",
1408 " or a stream added or removed on one"
1409 ),
1410 Category::TimingChanged => concat!(
1411 "A signal or event resolved timing changed (ADR-0008 d12).\n",
1412 " compatible min raised (a higher rate floor) or max lowered (a tighter\n",
1413 " staleness bound) with the mode unchanged; default_applied\n",
1414 " flipped over identical resolved bounds — a default made\n",
1415 " explicit\n",
1416 " breaking min lowered, max raised, a bound added where none was, a bound\n",
1417 " removed, or the strict-periodic/range mode flipped\n",
1418 " note editing `[defaults].timing` needs no special rule: diff\n",
1419 " compares resolved bounds, so it surfaces here on every\n",
1420 " defaulted interaction (ridl 9.1)"
1421 ),
1422 Category::RpcBoundChanged => concat!(
1423 "A command or query declared RPC bound changed (ADR-0015 d8).\n",
1424 " compatible min lowered (the caller may call more often) or max lowered\n",
1425 " (a stronger provider promise), with the mode unchanged;\n",
1426 " default_applied flipped over identical resolved bounds — a\n",
1427 " default made explicit\n",
1428 " breaking min raised — on an RPC, min is the call throttle and\n",
1429 " constrains the caller, so raising it withdraws a call rate\n",
1430 " the caller was entitled to use; max raised (a weaker provider\n",
1431 " promise); a bound added or removed, the whole annotation\n",
1432 " included\n",
1433 " note the min direction is the inverse of timing_changed's, which\n",
1434 " is why this is a category of its own rather than a branch:\n",
1435 " a missed branch would inherit the signal rule and call a\n",
1436 " raised RPC min compatible (ADR-0012 d9, fail closed).\n",
1437 " an RPC bound may come from a default, and diff compares\n",
1438 " resolved bounds, so editing a default surfaces here on\n",
1439 " every defaulted command or query (ridl 9.1)"
1440 ),
1441 Category::LimitChanged => concat!(
1442 "The payload limit of the interaction changed; every change of a limit is\n",
1443 "breaking, ADR-0030 decision 13.\n",
1444 " breaking a limit raised, lowered, added where none was, or removed"
1445 ),
1446 Category::ContractChanged => concat!(
1447 "A command or query require/ensure clause set changed (ridl 13).\n",
1448 " compatible a require removed, or an ensure added\n",
1449 " breaking a require added or its text changed, or an ensure removed or\n",
1450 " its text changed. Clause text is compared verbatim: the\n",
1451 " classifier does not prove that one clause implies another\n",
1452 " (ADR-0008 d14)"
1453 ),
1454 Category::InteractionClassChanged => concat!(
1455 "A name-paired interaction's family or operation shape changed\n",
1456 "(ADR-0012 d6).\n",
1457 " breaking any change, in either direction: the family selects the\n",
1458 " obligations a consumer compiled against, and the shape\n",
1459 " the gesture an intent command is. No source writes a\n",
1460 " family other than dispatch yet; the walk compares the\n",
1461 " fields from the start so the diff fails closed (ADR-0012 d9)"
1462 ),
1463 Category::WidthChanged => concat!(
1464 "A derived wire width or scalar backing changed.\n",
1465 " breaking any IntWidth or FloatWidth change, uint64 versus int64\n",
1466 " included — the resolved width is part of the contract\n",
1467 " (typl 4.2, 5.6)"
1468 ),
1469 Category::ConstraintChanged => concat!(
1470 "A scalar constraint changed, or a composite body changed in place.\n",
1471 " compatible widened only on a type reached by at least one interaction\n",
1472 " and exclusively sent by the consumer (command or query\n",
1473 " parameters, including streams). Widened means min lowered\n",
1474 " without shifting a stepped grid, max\n",
1475 " raised, a length bound loosened,\n",
1476 " a step removed, a match pattern removed (by literal or by\n",
1477 " named constant), or the whole constraint dropped so the\n",
1478 " value is unbounded again\n",
1479 " breaking widened on a received value (signal, event, fixed or query\n",
1480 " reply, both fallible arms and stream elements included),\n",
1481 " on a type reached in both directions, or on an unreached\n",
1482 " type. Reachability follows nested types across packages.\n",
1483 " Narrowed — min raised, max lowered, a length bound\n",
1484 " tightened, a stepped grid shifted, a step added or changed\n",
1485 " (divisibility between different steps is never\n",
1486 " proved), a match pattern added or rewritten (by literal or\n",
1487 " by named constant), or a constraint appearing where there\n",
1488 " was none, which bounds a previously unbounded value. A\n",
1489 " composite body changed in place is breaking: the walk\n",
1490 " does not say which member changed inside it\n",
1491 " note each facet is judged on its own and any one narrowing\n",
1492 " decides the change, so a mixed edit is breaking on the half\n",
1493 " that narrows. A widening that flips the resolved wire width\n",
1494 " is separately reported as width_changed, which is always\n",
1495 " breaking (typl 5.6). Per-side remote contexts report a changed\n",
1496 " scalar constraint at each surviving consumer interaction path,\n",
1497 " once per path and remote declaration, with the same rule.\n",
1498 " Missing per-side context supplies no comparison."
1499 ),
1500 Category::InitChanged => concat!(
1501 "A declared or resolved init value changed.\n",
1502 " breaking any direction — the init is the value a consumer reads before\n",
1503 " the first publish, so it is part of the contract (ridl 9.1)"
1504 ),
1505 Category::ReservedNameRedeclared => concat!(
1506 "A name retired by a `reserved` tombstone is live again — an interaction\n",
1507 "inside an interface body.\n",
1508 " breaking always — a retired identity is never reused (ridl 11,\n",
1509 " RIDL-401)"
1510 ),
1511 Category::ServiceChanged => concat!(
1512 "A service switched between the named list and an inline shape.\n",
1513 " breaking always — extraction rewrites the transport identity of every\n",
1514 " fallible query in the shape: an inline shape derives it from\n",
1515 " the service's dotted name, a named interface from its own name\n",
1516 " (ADR-0008 d4, ADR-0015 d15). A changed list is not this\n",
1517 " category: it is read as a set by the service_interface_*\n",
1518 " rows (ADR-0015 d19, as amended 2026-09-15)"
1519 ),
1520 Category::ServiceInterfaceAdded => concat!(
1521 "An interface joined a service's set of interfaces.\n",
1522 " compatible always — nothing that existed moved: an interface's number\n",
1523 " comes from its unit's interfaces.lock, not from its place\n",
1524 " in the list, and the routing key does not contain the service\n",
1525 " (ADR-0015 d19, as amended 2026-09-15)"
1526 ),
1527 Category::ServiceInterfaceRemoved => concat!(
1528 "An interface left a service's set of interfaces.\n",
1529 " compatible always — on the wire: the routing key does not contain the\n",
1530 " service, so no identity moves, and a split into two services\n",
1531 " is a removal plus an addition. Visible in source: the\n",
1532 " service.member addresses of that interface stop resolving\n",
1533 " under this service, which is why the text report lists it\n",
1534 " under the heading \"compatible on the wire, visible in\n",
1535 " source\". A consumer that loses its only provider is a\n",
1536 " wiring error for rsdl, not a package diff (ADR-0015 d19, as\n",
1537 " amended 2026-09-15)"
1538 ),
1539 Category::DocOnly => concat!(
1540 "Only doc comment, labels, or deprecation metadata changed.\n",
1541 " compatible always — none of it reaches a consumer's build.\n",
1542 " Visibility is NOT in this category: see\n",
1543 " visibility_changed"
1544 ),
1545 Category::VisibilityChanged => concat!(
1546 "The visibility a declaration is published at changed.\n",
1547 " compatible internal -> public: the declaration is offered to more\n",
1548 " consumers than before\n",
1549 " breaking public -> internal: `internal` maps to the target's\n",
1550 " package-private mechanism — Rust `pub(crate)`, a\n",
1551 " non-exported TypeScript member (ADR-0002 8) — so the\n",
1552 " declaration disappears from every out-of-package\n",
1553 " consumer's build. The wire layout does not move, but the\n",
1554 " consumer-visible guarantee narrows (ADR-0008 d14). Any\n",
1555 " direction involving an unset visibility is breaking"
1556 ),
1557 Category::PodbufRemoteInlineGrowth => concat!(
1558 "A remote declaration held inline by an old consumer has a larger podbuf size.\n",
1559 "The path belongs to the consumer; the values name the remote declaration\n",
1560 "and its old and new inline sizes. An inline member has no nested producer-size\n",
1561 "boundary, so its growth can move the fields after it even when only a remote\n",
1562 "pin changes and the local consumer declaration is unchanged. Producer-sized\n",
1563 "roots, array elements, map entries and union arms may grow, but their inline\n",
1564 "members may not. An append that fits entirely in the old head's pad bytes\n",
1565 "keeps the head size and draws no line; verify does not check pads.\n",
1566 "Shrinkage, other equal-size layout changes and general dependency semantic\n",
1567 "changes are deferred; this category judges only remote inline growth.\n",
1568 " breaking with `--encoding podbuf`\n",
1569 " compatible otherwise; listed under the heading \"breaking under podbuf\""
1570 ),
1571 Category::PodbufInlineAppend => concat!(
1572 "A struct field appended, compatible under the generic rule, to a\n",
1573 "struct another head holds inline on the old side — as a struct field,\n",
1574 "a tuple member, or an element of an exact-length array, in a struct,\n",
1575 "in the argument struct a call with several parameters induces, or in\n",
1576 "a tuple reply — when the field does not fit entirely inside the old\n",
1577 "head: the first-fit law places any of its bytes past the old head's\n",
1578 "size, so that the head grows. A field the law places entirely inside\n",
1579 "the old head, in its pad bytes, draws no line, because `verify` does\n",
1580 "not check pads; a field that starts in the pads and ends past the\n",
1581 "old size draws it. When several fields are appended at once, each is\n",
1582 "judged by its own bytes. Only a holder of the old side counts, because\n",
1583 "a holder new on the new side has no published copy;\n",
1584 "the detail names each inline use of the old side. The search mirrors\n",
1585 "the heads the encoder lays out, a declaration and a named induced\n",
1586 "tuple: a struct that is a root of its own (a single named parameter, a\n",
1587 "named reply, a signal, event or fixed payload), that is used only\n",
1588 "behind a descriptor (the element of a bounded array, the key or value\n",
1589 "of a map entry, a union arm), or only inside an exact-length array\n",
1590 "that is itself a root (a fixed payload `[S; 2..2]`, which has no head)\n",
1591 "is not reported: the root or the stride gives the producer's size, and\n",
1592 "the fields past it read as 0. A tuple inside such a root is a head,\n",
1593 "and a struct inside that tuple is a use.\n",
1594 " breaking with `--encoding podbuf`: the inline copy cannot grow\n",
1595 " without moving the fields after it\n",
1596 " compatible otherwise; listed under the heading \"breaking under\n",
1597 " podbuf\", so that a workspace that builds podbuf sees it"
1598 ),
1599 Category::PodbufWidthChange => concat!(
1600 "An enum value, an enum-set flag or a union arm appended, compatible\n",
1601 "under the generic rule, after which the podbuf integer of the enum or\n",
1602 "the enum set or the tag of the union is a different integer, by width\n",
1603 "or by signedness. podbuf lays an enum out as the narrowest integer\n",
1604 "that holds every declared value, signed when a value is negative\n",
1605 "(ADR-0031 decision 5), an enum set as its width, the narrowest\n",
1606 "unsigned integer that holds its highest bit, and a union's tag as the\n",
1607 "narrowest unsigned integer that holds the largest arm ordinal: a value\n",
1608 "above 255, a flag at bit 8 or an arm past ordinal 255 widens a `u8` to\n",
1609 "a `u16`, a value above 65535 or a flag at bit 16 a `u16` to a `u32`,\n",
1610 "and a flag at bit 32 widens a `u32` to a `u64`.\n",
1611 "A negative value appended to an enum that has values is below its\n",
1612 "highest value, an insert, which the generic rule reports as a breaking\n",
1613 "`decl_added` line and not as a width line; the integer turns signed\n",
1614 "only when an enum with no value gains values (`-1` gives an `i8`,\n",
1615 "`-1` and `200` an `i16`). The line is reported once per declaration\n",
1616 "and carries the old and the new integer. An append that keeps the\n",
1617 "integer draws no such line.\n",
1618 " breaking with `--encoding podbuf`: every head that holds the enum,\n",
1619 " the enum set or the union lays out a different integer,\n",
1620 " and an older reader misreads the value\n",
1621 " compatible otherwise; listed under the\n",
1622 " heading \"breaking under podbuf\", so that a workspace\n",
1623 " that builds podbuf sees it. An enum-set flag that widens\n",
1624 " the integer also widens the enum set's FlatBuffers\n",
1625 " scalar, which `flatbuffers_width_change` reports, and a\n",
1626 " flag at bit 32 also widens the proto3 field, which\n",
1627 " `proto3_width_change` reports"
1628 ),
1629 Category::PodbufStrictEnumAppend => concat!(
1630 "Superseded by `strict_enum_append`, which is breaking for every\n",
1631 "encoding. `ridl diff` no longer reports this category; the word stays\n",
1632 "so that a report or a script that names it still reads.\n",
1633 " breaking with `--encoding podbuf`\n",
1634 " compatible otherwise"
1635 ),
1636 Category::StrictEnumAppend => concat!(
1637 "An enum value or an enum-set flag appended to an enum or an enum set\n",
1638 "that is not declared `open`. A reader built from the old declaration\n",
1639 "refuses a value or a flag it does not name: the `verify` of podbuf\n",
1640 "does, and so does the codec of every encoding that checks the\n",
1641 "declaration, so the append is breaking whatever encodings the\n",
1642 "comparison is judged for. To let readers accept values a later\n",
1643 "version adds, declare an open enum or an open enum set (the `open`\n",
1644 "keyword) before the first release that readers depend on: an append\n",
1645 "to an open enum or an open enum set is compatible. For a compared\n",
1646 "declaration, the line is reported once at `<package>/<decl>`, with\n",
1647 "the appended names. With per-side remote contexts, a surviving old\n",
1648 "consumer use reports the line at its consumer path, once per path\n",
1649 "and remote declaration, with `<remote declaration>: <names>` values\n",
1650 "before and after (ADR-0031 decision 13). A side without remote\n",
1651 "context draws no remote strict-append line.\n",
1652 " breaking always, for every encoding\n",
1653 " note for a compared declaration, a value or flag that is\n",
1654 " not an append (an insert below the highest number, or a\n",
1655 " reused number) is decl_added, breaking, instead"
1656 ),
1657 Category::EnumOpened => concat!(
1658 "An enum or an enum set that gained the `open` keyword. A reader built\n",
1659 "from the old declaration already refuses nothing that the new one\n",
1660 "names, and a reader built from the new declaration accepts any\n",
1661 "integer, so no producer or reader of either side is refused by the\n",
1662 "other. The path is the declaration's; there is no detail.\n",
1663 " compatible always"
1664 ),
1665 Category::EnumClosed => concat!(
1666 "An enum or an enum set that lost the `open` keyword. A reader built\n",
1667 "from the new declaration refuses a value that a producer of the old\n",
1668 "declaration may still send, because the old declaration accepted any\n",
1669 "integer. The path is the declaration's; there is no detail.\n",
1670 " breaking always"
1671 ),
1672 Category::FlatbuffersWidthChange => concat!(
1673 "An enum-set flag appended, compatible under the\n",
1674 "generic rule, after which the FlatBuffers integer of the\n",
1675 "enum set is a different integer. FlatBuffers stores an enum set as the\n",
1676 "unsigned scalar of its width, the narrowest that holds its highest\n",
1677 "bit: a flag at bit 8 widens a `u8` (`ubyte`) to a `u16` (`ushort`),\n",
1678 "a flag at bit 16 a `u16` to a `u32` (`uint`), and a flag at bit 32 a\n",
1679 "`u32` to a `u64` (`ulong`). Every enum is stored as fixed `int` whatever\n",
1680 "its values, so an appended enum value keeps the integer; a union's\n",
1681 "type field is always `ubyte`. The line is reported once per\n",
1682 "declaration and carries the old and the new integer. An append that\n",
1683 "keeps the integer draws no such line.\n",
1684 "Only per-side context entry points report a remote declaration reached\n",
1685 "by a surviving old consumer use once per consumer path and remote\n",
1686 "declaration, at the consumer path with `<remote declaration>: <integer>`\n",
1687 "values; a side without remote context draws no such line.\n",
1688 " breaking with `--encoding flatbuffers`: every table field and\n",
1689 " vector element of the type changes its scalar, so a\n",
1690 " reader of the new schema rejects or misreads an old\n",
1691 " buffer and a reader of the old schema drops the flag\n",
1692 " compatible otherwise; listed under the heading \"breaking under\n",
1693 " flatbuffers\", so that a workspace that builds\n",
1694 " FlatBuffers sees it"
1695 ),
1696 Category::Proto3WidthChange => concat!(
1697 "An enum-set flag appended, compatible under the generic rule, after\n",
1698 "which the proto3 scalar of the enum set is a different scalar. proto3\n",
1699 "has no 8-bit or 16-bit integer, so an enum set of width `u8`, `u16`\n",
1700 "or `u32` is a `uint32` field and one of width `u64` is a `uint64`\n",
1701 "field: a flag at bit 32 above a highest bit of 31 or below widens\n",
1702 "`uint32` to `uint64`, and a flag at bit 8 or 16 keeps `uint32`. Every\n",
1703 "enum is a proto3 `enum`, an `int32`, and the proto3 backend refuses a\n",
1704 "value outside `int32`, so an appended enum value never changes it.\n",
1705 "The line is reported once per declaration and carries the old and the\n",
1706 "new scalar. An append that keeps the scalar draws no such line.\n",
1707 "Only per-side context entry points report a remote declaration reached\n",
1708 "by a surviving old consumer use once per consumer path and remote\n",
1709 "declaration, at the consumer path with `<remote declaration>: <integer>`\n",
1710 "values; a side without remote context draws no such line.\n",
1711 " breaking with `--encoding proto3`: a reader of the old schema\n",
1712 " refuses the value (the generated Rust codec) or truncates\n",
1713 " it to 32 bits and drops the flag\n",
1714 " compatible otherwise; listed under the heading \"breaking under\n",
1715 " proto3\", so that a workspace that builds proto3 sees it"
1716 ),
1717 }
1718}