ifc_template_catalog/overlay/patch.rs
1//! Patch and advisory contracts.
2
3use thiserror::Error;
4
5use crate::definition::{
6 Applicability, CatalogEdition, PropertyKind, PropertyTemplate, QuantityKind,
7};
8
9/// One ledger entry correcting or annotating an official set template.
10#[derive(Debug, Clone, PartialEq, Eq)]
11pub struct Patch {
12 /// Stable identifier for this patch, e.g. `NEH-IFC4-QTO-0001`.
13 pub id: String,
14 /// Source edition this patch targets; applying it to a catalog of a
15 /// different edition fails.
16 pub edition: CatalogEdition,
17 /// `Name` of the set template this patch corrects or annotates.
18 pub target_template: String,
19 /// Why the correction is needed.
20 pub rationale: String,
21 /// Citation or reference supporting the correction.
22 pub evidence: String,
23 /// The concrete change this patch makes.
24 pub operation: PatchOperation,
25}
26
27/// The kind of change one [`Patch`] makes to a set template.
28#[derive(Debug, Clone, PartialEq, Eq)]
29#[non_exhaustive]
30pub enum PatchOperation {
31 /// Add a new applicability selector, rejected if it duplicates an
32 /// existing selector or if the target already has a
33 /// [`ReplaceApplicability`](PatchOperation::ReplaceApplicability) applied.
34 AddApplicability(Applicability),
35 /// Replace the target's entire applicability list, rejected unless the
36 /// current list equals `expected` exactly.
37 ReplaceApplicability {
38 /// Applicability list the target must currently have.
39 expected: Vec<Applicability>,
40 /// Applicability list to install in its place.
41 replacement: Vec<Applicability>,
42 },
43 /// Append a property template the edition's documentation lists but its
44 /// machine-readable PSD omits. Rejected when the target is a quantity set
45 /// or already has a member of that name.
46 AddProperty(PropertyTemplate),
47 /// Replace the kind of one quantity of a quantity set, rejected unless
48 /// the quantity currently has the `expected` kind. For a published kind
49 /// that real files cannot match.
50 ReplaceQuantityKind {
51 /// `Name` of the quantity in the target set.
52 member: String,
53 /// Kind the quantity must currently have.
54 expected: QuantityKind,
55 /// Kind to install in its place.
56 replacement: QuantityKind,
57 },
58 /// Replace the kind of one property of a property set, rejected unless
59 /// the property currently has the `expected` kind. For a published kind
60 /// that real files cannot match.
61 ReplacePropertyKind {
62 /// `Name` of the property in the target set.
63 member: String,
64 /// Kind the property must currently have.
65 expected: PropertyKind,
66 /// Kind to install in its place.
67 replacement: PropertyKind,
68 },
69 /// Attach an [`Advisory`] to the target template without changing its data.
70 AddAdvisory {
71 /// How serious the advisory is.
72 severity: AdvisorySeverity,
73 /// Advisory text shown to callers.
74 message: String,
75 },
76}
77
78/// How serious an [`Advisory`] is.
79#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
80#[non_exhaustive]
81pub enum AdvisorySeverity {
82 /// Informational note; no action implied.
83 Information,
84 /// Caution: the template is usable but has a known caveat.
85 Warning,
86 /// The template should not be used as published without the caller's own remediation.
87 Error,
88}
89
90/// A non-mutating annotation attached to a set template by a [`Patch`].
91#[derive(Debug, Clone, PartialEq, Eq)]
92#[non_exhaustive]
93pub struct Advisory {
94 /// Id of the [`Patch`] that added this advisory.
95 pub patch_id: String,
96 /// `Name` of the set template this advisory targets.
97 pub target_template: String,
98 /// How serious the advisory is.
99 pub severity: AdvisorySeverity,
100 /// Advisory text shown to callers.
101 pub message: String,
102 /// Citation or reference supporting the advisory.
103 pub evidence: String,
104}
105
106/// Record of one [`Patch`] that was successfully applied to a catalog snapshot.
107#[derive(Debug, Clone, PartialEq, Eq)]
108#[non_exhaustive]
109pub struct AppliedPatch {
110 /// Id of the applied patch.
111 pub id: String,
112 /// `Name` of the set template it was applied to.
113 pub target_template: String,
114 /// Why the correction was needed.
115 pub rationale: String,
116 /// Citation or reference supporting the correction.
117 pub evidence: String,
118 /// The change that was made.
119 pub operation: PatchOperation,
120}
121
122/// Why applying a patch ledger to a catalog failed.
123#[derive(Debug, Clone, PartialEq, Eq, Error)]
124#[non_exhaustive]
125pub enum PatchError {
126 /// The supplied patch list was empty.
127 #[error("a patch ledger must not be empty")]
128 EmptyLedger,
129 /// The requested profile transition is not allowed, e.g. patching an
130 /// `Official` catalog into `Official`, or patching into `Corrected` when
131 /// the catalog is not a clean `Official` snapshot.
132 #[error("cannot apply patches from {from:?} into {to:?}")]
133 InvalidProfileTransition {
134 /// The catalog's profile before this application.
135 from: crate::catalog::CatalogProfile,
136 /// The profile requested for the result.
137 to: crate::catalog::CatalogProfile,
138 },
139 /// Two patches in the ledger shared the same `id`.
140 #[error("duplicate patch id `{0}`")]
141 DuplicateId(String),
142 /// A patch's `edition` does not match the catalog's edition.
143 #[error("patch `{patch_id}` targets {patch_edition:?}, catalog is {catalog_edition:?}")]
144 EditionMismatch {
145 /// Id of the offending patch.
146 patch_id: String,
147 /// Edition the patch declares.
148 patch_edition: CatalogEdition,
149 /// Edition of the catalog being patched.
150 catalog_edition: CatalogEdition,
151 },
152 /// A patch's `target_template` does not match any template `Name` in the catalog.
153 #[error("patch `{patch_id}` targets unknown template `{template}`")]
154 UnknownTemplate {
155 /// Id of the offending patch.
156 patch_id: String,
157 /// The unmatched target template name.
158 template: String,
159 },
160 /// An [`PatchOperation::AddApplicability`] selector, or a
161 /// [`PatchOperation::AddProperty`] member name, already exists on the target.
162 #[error("patch `{patch_id}` is already reflected in `{template}`")]
163 AlreadyApplied {
164 /// Id of the offending patch.
165 patch_id: String,
166 /// The target template name.
167 template: String,
168 },
169 /// A [`PatchOperation::ReplaceApplicability`]'s `expected` list, or a
170 /// [`PatchOperation::ReplaceQuantityKind`] or
171 /// [`PatchOperation::ReplacePropertyKind`]'s `expected` kind, did not
172 /// match the template's current value.
173 #[error("patch `{patch_id}` expected different applicability on `{template}`")]
174 StaleTarget {
175 /// Id of the offending patch.
176 patch_id: String,
177 /// The target template name.
178 template: String,
179 },
180 /// A [`PatchOperation::AddProperty`] or
181 /// [`PatchOperation::ReplacePropertyKind`] targets a quantity set template.
182 #[error("patch `{patch_id}` changes a property of quantity set `{template}`")]
183 NotAPropertySet {
184 /// Id of the offending patch.
185 patch_id: String,
186 /// The target template name.
187 template: String,
188 },
189 /// A [`PatchOperation::ReplaceQuantityKind`] targets a property set template.
190 #[error("patch `{patch_id}` changes a quantity of property set `{template}`")]
191 NotAQuantitySet {
192 /// Id of the offending patch.
193 patch_id: String,
194 /// The target template name.
195 template: String,
196 },
197 /// A [`PatchOperation::ReplaceQuantityKind`] or
198 /// [`PatchOperation::ReplacePropertyKind`] names a member the target lacks.
199 #[error("patch `{patch_id}` names unknown member `{member}` of `{template}`")]
200 UnknownMember {
201 /// Id of the offending patch.
202 patch_id: String,
203 /// The target template name.
204 template: String,
205 /// The unmatched member name.
206 member: String,
207 },
208 /// Two patches in the ledger both attempt to change the same template's
209 /// applicability in incompatible ways (e.g. add after replace).
210 #[error("patches conflict on `{template}` applicability")]
211 ConflictingApplicability {
212 /// The target template name.
213 template: String,
214 },
215 /// Building the resulting catalog snapshot failed.
216 #[error(transparent)]
217 Catalog(#[from] crate::catalog::CatalogError),
218}