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