Skip to main content

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}