Skip to main content

r_description/
normalization.rs

1//! Deterministic whole-document DESCRIPTION normalization.
2
3use std::{collections::BTreeSet, error::Error, fmt};
4
5use r_dcf_syntax::{FieldName, FormatStyle, LineEnding, LogicalValue, SourceSpan};
6use r_metadata::{AdditionalRepositories, RelationList, RemoteList, UrlList};
7
8use crate::{Description, Field, SyntaxDiagnosticKind, schema};
9
10const WIDTH: usize = 80;
11
12/// One reason a DESCRIPTION document could not be normalized safely.
13#[derive(Debug, Clone, PartialEq, Eq, Hash)]
14pub struct NormalizationDiagnostic {
15    code: &'static str,
16    message: String,
17    span: SourceSpan,
18}
19
20impl NormalizationDiagnostic {
21    /// Stable machine-readable diagnostic code.
22    pub const fn code(&self) -> &'static str {
23        self.code
24    }
25
26    /// Human-readable explanation.
27    pub fn message(&self) -> &str {
28        &self.message
29    }
30
31    /// Half-open source byte span.
32    pub const fn span(&self) -> SourceSpan {
33        self.span
34    }
35}
36
37/// Atomic whole-document normalization failure.
38#[derive(Debug, Clone, PartialEq, Eq)]
39pub struct NormalizationError {
40    diagnostics: Vec<NormalizationDiagnostic>,
41}
42
43impl NormalizationError {
44    /// Returns all blocking diagnostics in deterministic order.
45    pub fn diagnostics(&self) -> &[NormalizationDiagnostic] {
46        &self.diagnostics
47    }
48
49    /// Consumes the error and returns all blocking diagnostics.
50    pub fn into_diagnostics(self) -> Vec<NormalizationDiagnostic> {
51        self.diagnostics
52    }
53}
54
55impl fmt::Display for NormalizationError {
56    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
57        write!(
58            formatter,
59            "DESCRIPTION cannot be normalized safely ({} diagnostic{})",
60            self.diagnostics.len(),
61            if self.diagnostics.len() == 1 { "" } else { "s" }
62        )
63    }
64}
65
66impl Error for NormalizationError {}
67
68#[derive(Debug)]
69struct InputField {
70    name: String,
71    value: String,
72    span: SourceSpan,
73    source_index: usize,
74}
75
76#[derive(Debug)]
77struct OutputField {
78    name: String,
79    value: String,
80    span: SourceSpan,
81    source_index: usize,
82}
83
84impl Description {
85    /// Normalizes the complete DESCRIPTION document into one canonical form.
86    ///
87    /// The operation is atomic. It returns diagnostics instead of output when
88    /// malformed syntax, multiple records, or invalid structured collections
89    /// make a semantics-preserving transformation unsafe.
90    ///
91    /// # Errors
92    ///
93    /// Returns every normalization blocker found in deterministic order.
94    pub fn normalize(&self) -> Result<Self, NormalizationError> {
95        let mut diagnostics = syntax_diagnostics(self);
96        let records = self.records().collect::<Vec<_>>();
97        if records.len() != 1 {
98            diagnostics.push(NormalizationDiagnostic {
99                code: "record-count",
100                message: format!("expected exactly one record, found {}", records.len()),
101                span: records
102                    .first()
103                    .map_or(SourceSpan::new(0, 0), crate::Record::source_range),
104            });
105        }
106
107        let Some(record) = records.first() else {
108            return Err(NormalizationError { diagnostics });
109        };
110        let fields = record
111            .fields()
112            .enumerate()
113            .filter_map(|(source_index, field)| input_field(&field, source_index))
114            .collect::<Vec<_>>();
115
116        validate_values(&fields, &mut diagnostics);
117        if !diagnostics.is_empty() {
118            return Err(NormalizationError { diagnostics });
119        }
120
121        let mut output = normalize_fields(&fields);
122        if output.is_empty() {
123            return Err(NormalizationError {
124                diagnostics: vec![NormalizationDiagnostic {
125                    code: "empty-record",
126                    message: "normalization would remove every field from the record".to_owned(),
127                    span: record.source_range(),
128                }],
129            });
130        }
131        output.sort_by(|left, right| {
132            schema::order(&left.name)
133                .cmp(&schema::order(&right.name))
134                .then_with(|| left.source_index.cmp(&right.source_index))
135        });
136
137        let style = FormatStyle {
138            line_ending: LineEnding::Lf,
139            continuation_indent: "    ".to_owned(),
140            space_after_colon: true,
141        };
142        let mut rendered = Vec::with_capacity(output.len());
143        for field in output {
144            let Ok(name) = FieldName::new(&field.name) else {
145                return Err(generated_value_error(
146                    "invalid-normalized-field-name",
147                    "normalized field name is not valid DCF syntax",
148                    field.span,
149                ));
150            };
151            let Ok(value) = LogicalValue::new(field.value) else {
152                return Err(generated_value_error(
153                    "invalid-normalized-value",
154                    "normalized field value cannot be represented in DCF syntax",
155                    field.span,
156                ));
157            };
158            rendered.push(r_dcf_syntax::field(&name, &value, &style));
159        }
160        let mut source = r_dcf_syntax::record(&rendered, &style);
161        source.push('\n');
162        Ok(Self::parse(&source))
163    }
164}
165
166fn syntax_diagnostics(description: &Description) -> Vec<NormalizationDiagnostic> {
167    description
168        .diagnostics()
169        .iter()
170        .map(|diagnostic| NormalizationDiagnostic {
171            code: match diagnostic.kind() {
172                SyntaxDiagnosticKind::MalformedField => "syntax.malformed-field",
173                SyntaxDiagnosticKind::OrphanContinuation => "syntax.orphan-continuation",
174                SyntaxDiagnosticKind::InvalidFieldName => "syntax.invalid-field-name",
175            },
176            message: diagnostic.message().to_owned(),
177            span: diagnostic.span(),
178        })
179        .collect()
180}
181
182fn generated_value_error(
183    code: &'static str,
184    message: &'static str,
185    span: SourceSpan,
186) -> NormalizationError {
187    NormalizationError {
188        diagnostics: vec![NormalizationDiagnostic {
189            code,
190            message: message.to_owned(),
191            span,
192        }],
193    }
194}
195
196fn input_field(field: &Field, source_index: usize) -> Option<InputField> {
197    Some(InputField {
198        name: field.name()?,
199        value: field.value().into_string(),
200        span: field.source_range(),
201        source_index,
202    })
203}
204
205fn validate_values(fields: &[InputField], diagnostics: &mut Vec<NormalizationDiagnostic>) {
206    for field in fields {
207        if LogicalValue::new(&field.value).is_err() {
208            push_invalid(
209                diagnostics,
210                "invalid-logical-value",
211                "field value cannot be represented canonically",
212                field,
213            );
214            continue;
215        }
216        match schema::field_kind(&field.name) {
217            Some(schema::FieldKind::Relations) => {
218                for issue in RelationList::parse(&field.value).issues() {
219                    push_invalid(diagnostics, "invalid-collection", issue.to_string(), field);
220                }
221            }
222            Some(schema::FieldKind::Urls) => {
223                for issue in UrlList::parse(&field.value).issues() {
224                    push_invalid(diagnostics, "invalid-collection", issue.to_string(), field);
225                }
226            }
227            Some(schema::FieldKind::Repositories) => {
228                for issue in AdditionalRepositories::parse(&field.value).issues() {
229                    push_invalid(diagnostics, "invalid-collection", issue.to_string(), field);
230                }
231            }
232            Some(schema::FieldKind::Remotes) => {
233                for issue in RemoteList::parse(&field.value).issues() {
234                    push_invalid(diagnostics, "invalid-collection", issue.to_string(), field);
235                }
236            }
237            Some(schema::FieldKind::Scalar | schema::FieldKind::Ordered) | None => {}
238        }
239    }
240}
241
242fn push_invalid(
243    diagnostics: &mut Vec<NormalizationDiagnostic>,
244    code: &'static str,
245    message: impl Into<String>,
246    field: &InputField,
247) {
248    diagnostics.push(NormalizationDiagnostic {
249        code,
250        message: format!("{}: {}", field.name, message.into()),
251        span: field.span,
252    });
253}
254
255fn normalize_fields(fields: &[InputField]) -> Vec<OutputField> {
256    let mut output = Vec::new();
257    let names = fields
258        .iter()
259        .map(|field| field.name.as_str())
260        .collect::<BTreeSet<_>>();
261    for name in names {
262        let declarations = fields
263            .iter()
264            .filter(|field| field.name == name)
265            .collect::<Vec<_>>();
266        match schema::field_kind(name) {
267            Some(schema::FieldKind::Relations) => {
268                let values = declarations
269                    .iter()
270                    .flat_map(|field| RelationList::parse(&field.value).into_parts().0)
271                    .map(|entry| entry.value)
272                    .collect::<BTreeSet<_>>()
273                    .into_iter()
274                    .map(|value| value.to_string())
275                    .collect::<Vec<_>>();
276                push_collection(&mut output, name, &values, &declarations);
277            }
278            Some(schema::FieldKind::Urls) => {
279                let values = declarations
280                    .iter()
281                    .flat_map(|field| UrlList::parse(&field.value).into_parts().0)
282                    .map(|entry| entry.value.to_string())
283                    .collect::<BTreeSet<_>>()
284                    .into_iter()
285                    .collect::<Vec<_>>();
286                push_collection(&mut output, name, &values, &declarations);
287            }
288            Some(schema::FieldKind::Repositories) => {
289                let values = stable_unique(
290                    declarations
291                        .iter()
292                        .flat_map(|field| {
293                            AdditionalRepositories::parse(&field.value).into_parts().0
294                        })
295                        .map(|entry| entry.value.to_string()),
296                );
297                push_collection(&mut output, name, &values, &declarations);
298            }
299            Some(schema::FieldKind::Remotes) => {
300                let values = stable_unique(
301                    declarations
302                        .iter()
303                        .flat_map(|field| RemoteList::parse(&field.value).into_parts().0)
304                        .map(|entry| entry.value.to_string()),
305                );
306                push_collection(&mut output, name, &values, &declarations);
307            }
308            Some(schema::FieldKind::Scalar | schema::FieldKind::Ordered) => {
309                if let Some(field) = declarations.last() {
310                    push_scalar(&mut output, field);
311                }
312            }
313            None => {
314                for field in declarations {
315                    push_scalar(&mut output, field);
316                }
317            }
318        }
319    }
320    output
321}
322
323fn stable_unique(values: impl IntoIterator<Item = String>) -> Vec<String> {
324    let mut seen = BTreeSet::new();
325    values
326        .into_iter()
327        .filter(|value| seen.insert(value.clone()))
328        .collect()
329}
330
331fn push_collection(
332    output: &mut Vec<OutputField>,
333    name: &str,
334    values: &[String],
335    declarations: &[&InputField],
336) {
337    if values.is_empty() {
338        return;
339    }
340    let Some(declaration) = declarations.last() else {
341        return;
342    };
343    output.push(OutputField {
344        name: name.to_owned(),
345        value: format!("\n{}", values.join(",\n")),
346        span: declaration.span,
347        source_index: declaration.source_index,
348    });
349}
350
351fn push_scalar(output: &mut Vec<OutputField>, field: &InputField) {
352    if field.value.is_empty() && schema::remove_when_empty(&field.name) {
353        return;
354    }
355    output.push(OutputField {
356        name: field.name.clone(),
357        value: if schema::is_prose(&field.name) {
358            wrap(&field.name, &field.value)
359        } else {
360            field.value.clone()
361        },
362        span: field.span,
363        source_index: field.source_index,
364    });
365}
366
367fn wrap(name: &str, value: &str) -> String {
368    let words = value.split_whitespace().collect::<Vec<_>>();
369    if words.is_empty() {
370        return String::new();
371    }
372    let first_width = WIDTH.saturating_sub(name.len() + 2).max(1);
373    let continued_width = WIDTH.saturating_sub(4).max(1);
374    let mut lines = Vec::new();
375    let mut line = String::new();
376    let mut width = first_width;
377    for word in words {
378        if word != "."
379            && !line.is_empty()
380            && line.chars().count() + 1 + word.chars().count() > width
381        {
382            lines.push(std::mem::take(&mut line));
383            width = continued_width;
384        }
385        if !line.is_empty() {
386            line.push(' ');
387        }
388        line.push_str(word);
389    }
390    lines.push(line);
391    lines.join("\n")
392}