Skip to main content

r_description/
description.rs

1use deb822_lossless::{Deb822, Entry, Parse, PositionedParseError, TextRange};
2use rowan::TextSize;
3
4/// Error validating caller-provided field mutation input.
5#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
6pub enum FieldMutationError {
7    /// The field name is not valid DCF syntax.
8    #[error("invalid DESCRIPTION field name {name:?}")]
9    InvalidFieldName {
10        /// The rejected field name.
11        name: String,
12    },
13
14    /// A named scalar setter received a multiline value.
15    #[error("{field} scalar setter does not accept multiline values")]
16    MultilineScalar {
17        /// The field whose setter rejected the value.
18        field: &'static str,
19    },
20
21    /// A multiline value contains an empty continuation line.
22    #[error("field value contains an empty continuation line at line {line}")]
23    EmptyContinuationLine {
24        /// One-based line number in the supplied logical value.
25        line: usize,
26    },
27
28    /// A logical value line begins with whitespace consumed as DCF indentation.
29    #[error("field value line {line} begins with unrepresentable DCF indentation")]
30    LeadingWhitespace {
31        /// One-based line number in the supplied logical value.
32        line: usize,
33    },
34}
35
36/// A logical value paired with its absolute range in a `DESCRIPTION` document.
37///
38/// The range refers to the document rendering current when this value was
39/// obtained. Mutation may shift it.
40///
41/// `Debug` includes the wrapped value and may expose credentials or other
42/// sensitive field content.
43#[derive(Debug, Clone, PartialEq, Eq, Hash)]
44pub struct Spanned<T> {
45    value: T,
46    range: TextRange,
47}
48
49impl<T> Spanned<T> {
50    pub(crate) fn new(value: T, range: TextRange) -> Self {
51        Self { value, range }
52    }
53
54    /// Returns the value.
55    pub fn value(&self) -> &T {
56        &self.value
57    }
58
59    /// Returns the absolute, half-open UTF-8 byte range of the value.
60    pub fn range(&self) -> TextRange {
61        self.range
62    }
63
64    /// Consumes the wrapper and returns its value.
65    pub fn into_inner(self) -> T {
66        self.value
67    }
68}
69
70/// A losslessly parsed R `DESCRIPTION` document.
71///
72/// The document retains structural parser errors without rejecting the
73/// recovered syntax tree. Use [`RDescription::syntax_issues`] to inspect them.
74/// Typed field validation is performed on demand by named accessors.
75///
76/// Absolute ranges returned directly by the document or a [`Spanned`] value
77/// refer to the rendering current when they were obtained. Nested parser errors
78/// may instead use relative ranges, as documented by their types. Any mutation
79/// may shift document-relative ranges, so reacquire structural issues, typed
80/// errors, and spanned values after changing the document.
81///
82/// `Debug` may include the complete source document, including credentials or
83/// other sensitive values. Do not log untrusted documents without review.
84#[derive(Debug, Clone, PartialEq, Eq)]
85pub struct RDescription {
86    parse: Parse<Deb822>,
87}
88
89impl RDescription {
90    pub(crate) fn tree(&self) -> Deb822 {
91        self.parse.tree()
92    }
93
94    /// Parses an R `DESCRIPTION` document with structural error recovery.
95    ///
96    /// Before mutation, rendering the resulting document reproduces the input,
97    /// including when the DCF parser reports syntax issues.
98    pub fn parse(input: &str) -> Self {
99        Self {
100            parse: Deb822::parse(input),
101        }
102    }
103
104    /// Returns structural DCF issues in source order.
105    ///
106    /// Issue ranges are absolute, half-open UTF-8 byte ranges into the current
107    /// rendered document. A consumer can combine these ranges with that source
108    /// using a diagnostic renderer such as miette:
109    ///
110    /// ```rust,ignore
111    /// use miette::{Diagnostic, NamedSource, SourceSpan};
112    /// use r_description::{PositionedParseError, RDescription};
113    /// use thiserror::Error;
114    ///
115    /// #[derive(Debug, Error, Diagnostic)]
116    /// #[error("DESCRIPTION contains {count} syntax errors")]
117    /// struct DescriptionDiagnostics {
118    ///     count: usize,
119    ///
120    ///     #[source_code]
121    ///     source: NamedSource<String>,
122    ///
123    ///     #[related]
124    ///     issues: Vec<DescriptionSyntaxDiagnostic>,
125    /// }
126    ///
127    /// #[derive(Debug, Error, Diagnostic)]
128    /// #[error("{issue}")]
129    /// struct DescriptionSyntaxDiagnostic {
130    ///     issue: PositionedParseError,
131    ///
132    ///     #[label("{issue}")]
133    ///     span: SourceSpan,
134    /// }
135    ///
136    /// fn validate(source: String) -> Result<(), DescriptionDiagnostics> {
137    ///     let description = RDescription::parse(&source);
138    ///     let issues = description
139    ///         .syntax_issues()
140    ///         .iter()
141    ///         .cloned()
142    ///         .map(|issue| {
143    ///             let start = usize::from(issue.range.start());
144    ///             let end = usize::from(issue.range.end());
145    ///             DescriptionSyntaxDiagnostic {
146    ///                 issue,
147    ///                 span: (start..end).into(),
148    ///             }
149    ///         })
150    ///         .collect::<Vec<_>>();
151    ///
152    ///     if issues.is_empty() {
153    ///         return Ok(());
154    ///     }
155    ///
156    ///     Err(DescriptionDiagnostics {
157    ///         count: issues.len(),
158    ///         source: NamedSource::new("DESCRIPTION", source),
159    ///         issues,
160    ///     })
161    /// }
162    /// ```
163    pub fn syntax_issues(&self) -> &[PositionedParseError] {
164        self.parse.positioned_errors()
165    }
166
167    /// Returns all values for a field across all recovered paragraphs.
168    ///
169    /// Field names are matched ASCII case-insensitively. Values are returned in
170    /// source order without applying a duplicate-field policy. Each range
171    /// covers the field value and excludes its key and colon.
172    ///
173    /// [`Spanned::value`] is the logical DCF value with continuation syntax
174    /// removed. Its range bounds the source representation; for multiline
175    /// fields, slicing that range is not guaranteed to equal the logical value
176    /// byte-for-byte because continuation indentation remains in the source.
177    pub fn field_values(&self, name: &str) -> Vec<Spanned<String>> {
178        self.parse
179            .tree()
180            .paragraphs()
181            .flat_map(|paragraph| paragraph.entries().collect::<Vec<_>>())
182            .filter_map(|entry| {
183                if !entry
184                    .key()
185                    .is_some_and(|key| key.eq_ignore_ascii_case(name))
186                {
187                    return None;
188                }
189
190                let range = entry.value_range().unwrap_or_else(|| {
191                    let offset = entry
192                        .colon_range()
193                        .map_or_else(|| entry.text_range().end(), |range| range.end());
194                    TextRange::new(offset, offset)
195                });
196
197                Some(Spanned::new(entry.value(), range))
198            })
199            .collect()
200    }
201
202    /// Sets a known or custom field using canonical DCF formatting.
203    ///
204    /// Existing occurrences are matched ASCII case-insensitively. The first is
205    /// replaced in place and every later occurrence is removed. An absent field
206    /// is appended to the first recovered paragraph.
207    ///
208    /// Single-line values are written inline. For multiline values, the first
209    /// line remains inline and subsequent lines use four-space continuation
210    /// indentation. CRLF and lone carriage returns are normalized to LF.
211    /// Empty continuation lines and lines beginning with spaces or tabs are
212    /// rejected because DCF parsing would consume or reinterpret them.
213    ///
214    /// ```rust
215    /// use r_description::RDescription;
216    ///
217    /// let mut description = RDescription::parse("X-Custom: old\n\nX-Custom: duplicate\n");
218    /// description.set_field("X-Custom", "first\nsecond")?;
219    /// assert_eq!(
220    ///     description.to_string(),
221    ///     "X-Custom: first\n    second\n\n",
222    /// );
223    /// # Ok::<(), r_description::FieldMutationError>(())
224    /// ```
225    pub fn set_field(&mut self, name: &str, value: &str) -> Result<(), FieldMutationError> {
226        if !valid_field_name(name) {
227            return Err(FieldMutationError::InvalidFieldName {
228                name: name.to_string(),
229            });
230        }
231
232        let value = value.replace("\r\n", "\n").replace('\r', "\n");
233        let lines = value.split('\n').collect::<Vec<_>>();
234        if lines.len() > 1 && lines[0].trim().is_empty() {
235            return Err(FieldMutationError::EmptyContinuationLine { line: 1 });
236        }
237        if let Some((index, _)) = lines
238            .iter()
239            .enumerate()
240            .skip(1)
241            .find(|(_, line)| line.trim().is_empty())
242        {
243            return Err(FieldMutationError::EmptyContinuationLine { line: index + 1 });
244        }
245        if let Some((index, _)) = lines
246            .iter()
247            .enumerate()
248            .find(|(_, line)| line.starts_with([' ', '\t']))
249        {
250            return Err(FieldMutationError::LeadingWhitespace { line: index + 1 });
251        }
252
253        let rendered = render_field(name, &lines);
254        self.replace_field_rendered(name, Some(&rendered));
255        Ok(())
256    }
257
258    /// Removes every case-insensitive occurrence of a field.
259    pub fn remove_field(&mut self, name: &str) {
260        self.replace_field_rendered(name, None);
261    }
262
263    pub(crate) fn set_scalar_field(
264        &mut self,
265        field: &'static str,
266        value: &str,
267    ) -> Result<(), FieldMutationError> {
268        if value.contains(['\n', '\r']) {
269            return Err(FieldMutationError::MultilineScalar { field });
270        }
271        if value.starts_with([' ', '\t']) {
272            return Err(FieldMutationError::LeadingWhitespace { line: 1 });
273        }
274
275        self.set_known_single_line_field(field, value);
276        Ok(())
277    }
278
279    pub(crate) fn set_known_single_line_field(&mut self, field: &str, value: &str) {
280        let rendered = render_field(field, &[value]);
281        self.replace_field_rendered(field, Some(&rendered));
282    }
283
284    pub(crate) fn replace_field_rendered(&mut self, field: &str, rendered: Option<&str>) {
285        let tree = self.tree();
286        let paragraphs = tree.paragraphs().collect::<Vec<_>>();
287        let occurrences = paragraphs
288            .iter()
289            .flat_map(|paragraph| paragraph.entries().collect::<Vec<_>>())
290            .filter(|entry| {
291                entry
292                    .key()
293                    .is_some_and(|key| key.eq_ignore_ascii_case(field))
294            })
295            .map(|entry| entry.text_range())
296            .collect::<Vec<_>>();
297
298        if rendered.is_none() && occurrences.is_empty() {
299            return;
300        }
301
302        let mut source = self.to_string();
303        match (occurrences.first().copied(), rendered) {
304            (Some(first), Some(rendered)) => {
305                for range in occurrences.iter().skip(1).rev() {
306                    source.replace_range(usize::from(range.start())..usize::from(range.end()), "");
307                }
308                source.replace_range(
309                    usize::from(first.start())..usize::from(first.end()),
310                    rendered,
311                );
312            }
313            (Some(_), None) => {
314                for range in occurrences.iter().rev() {
315                    source.replace_range(usize::from(range.start())..usize::from(range.end()), "");
316                }
317            }
318            (None, Some(rendered)) => {
319                let insertion = paragraphs.first().map_or(source.len(), |paragraph| {
320                    usize::from(paragraph.text_range().end())
321                });
322                let prefix =
323                    if insertion > 0 && source.as_bytes().get(insertion - 1) != Some(&b'\n') {
324                        "\n"
325                    } else {
326                        ""
327                    };
328                source.insert_str(insertion, &format!("{prefix}{rendered}"));
329            }
330            (None, None) => return,
331        }
332
333        *self = Self::parse(&source);
334    }
335}
336
337fn valid_field_name(name: &str) -> bool {
338    let mut characters = name.chars();
339    characters.next().is_some_and(|character| {
340        character != '-'
341            && character != '#'
342            && character.is_ascii_graphic()
343            && character != ':'
344            && characters.all(|character| character.is_ascii_graphic() && character != ':')
345    })
346}
347
348fn render_field(name: &str, lines: &[&str]) -> String {
349    let first = lines.first().copied().unwrap_or_default();
350    let mut rendered = if first.is_empty() {
351        format!("{name}:\n")
352    } else {
353        format!("{name}: {first}\n")
354    };
355    for line in lines.iter().skip(1) {
356        rendered.push_str("    ");
357        rendered.push_str(line);
358        rendered.push('\n');
359    }
360    rendered
361}
362
363impl std::fmt::Display for RDescription {
364    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
365        std::fmt::Display::fmt(self.parse.green(), formatter)
366    }
367}
368
369#[derive(Debug)]
370struct ValueLine {
371    logical_start: usize,
372    logical_end: usize,
373    source: TextRange,
374}
375
376#[derive(Debug)]
377struct EntryValueMap {
378    lines: Vec<ValueLine>,
379    logical_len: usize,
380    empty_anchor: TextSize,
381    fallback: TextRange,
382}
383
384impl EntryValueMap {
385    fn new(entry: &Entry, value: &str) -> Self {
386        let mut logical_start = 0;
387        let lines = entry
388            .value_line_ranges()
389            .into_iter()
390            .enumerate()
391            .map(|(index, source)| {
392                if index > 0 {
393                    logical_start += 1;
394                }
395                let logical_end = logical_start + usize::from(source.len());
396                let line = ValueLine {
397                    logical_start,
398                    logical_end,
399                    source,
400                };
401                logical_start = logical_end;
402                line
403            })
404            .collect();
405        let empty_anchor = entry
406            .colon_range()
407            .map_or_else(|| entry.text_range().end(), |range| range.end());
408        let fallback = entry
409            .value_range()
410            .unwrap_or_else(|| TextRange::empty(empty_anchor));
411
412        Self {
413            lines,
414            logical_len: value.len(),
415            empty_anchor,
416            fallback,
417        }
418    }
419
420    fn map_range(&self, range: TextRange) -> TextRange {
421        let start = usize::from(range.start());
422        let end = usize::from(range.end());
423        if end > self.logical_len {
424            return self.fallback;
425        }
426
427        self.map_point(start)
428            .zip(self.map_point(end))
429            .map_or(self.fallback, |(start, end)| TextRange::new(start, end))
430    }
431
432    fn map_point(&self, point: usize) -> Option<TextSize> {
433        if self.lines.is_empty() {
434            return (point == 0).then_some(self.empty_anchor);
435        }
436
437        for (index, line) in self.lines.iter().enumerate() {
438            if point >= line.logical_start && point <= line.logical_end {
439                return Some(
440                    line.source.start() + TextSize::from((point - line.logical_start) as u32),
441                );
442            }
443            if index + 1 < self.lines.len() && point == line.logical_end + 1 {
444                return Some(self.lines[index + 1].source.start());
445            }
446        }
447
448        (point == self.logical_len).then(|| {
449            self.lines
450                .last()
451                .map_or(self.empty_anchor, |line| line.source.end())
452        })
453    }
454}
455
456pub(crate) fn map_entry_value_range(entry: &Entry, value: &str, range: TextRange) -> TextRange {
457    EntryValueMap::new(entry, value).map_range(range)
458}
459
460#[cfg(test)]
461mod tests {
462    use super::*;
463
464    #[test]
465    fn r_description_is_send_and_sync() {
466        fn assert_send_sync<T: Send + Sync>() {}
467        assert_send_sync::<RDescription>();
468    }
469
470    #[test]
471    fn valid_input_round_trips_losslessly() {
472        let input = "Package: example\n Description continuation\n";
473        assert_eq!(RDescription::parse(input).to_string(), input);
474    }
475
476    #[test]
477    fn malformed_input_round_trips_losslessly() {
478        let input = "Package example\nBroken: value\n";
479        assert_eq!(RDescription::parse(input).to_string(), input);
480    }
481
482    #[test]
483    fn malformed_input_exposes_positioned_issues() {
484        let input = "Package example\nBroken: value\n";
485        let description = RDescription::parse(input);
486        let issues = description.syntax_issues();
487
488        assert!(!issues.is_empty());
489        assert!(issues.iter().all(|issue| {
490            let start = usize::from(issue.range.start());
491            let end = usize::from(issue.range.end());
492            start <= end && end <= input.len()
493        }));
494        assert!(issues.iter().all(|issue| !issue.message.is_empty()));
495    }
496
497    #[test]
498    fn field_values_include_all_paragraphs_and_ranges() {
499        let input = "X-Custom: first\n\nx-custom: second\n";
500        let description = RDescription::parse(input);
501        let values = description.field_values("X-CUSTOM");
502
503        assert_eq!(values.len(), 2);
504        assert_eq!(values[0].value(), "first");
505        assert_eq!(values[1].value(), "second");
506        assert_eq!(
507            &input[usize::from(values[0].range().start())..usize::from(values[0].range().end())],
508            "first"
509        );
510        assert_eq!(
511            &input[usize::from(values[1].range().start())..usize::from(values[1].range().end())],
512            "second"
513        );
514    }
515
516    #[test]
517    fn empty_field_value_has_empty_range_after_colon() {
518        let input = "X-Custom:\n";
519        let value = RDescription::parse(input)
520            .field_values("X-Custom")
521            .into_iter()
522            .next()
523            .expect("field should be present");
524
525        assert_eq!(value.value(), "");
526        assert!(value.range().is_empty());
527        assert_eq!(usize::from(value.range().start()), "X-Custom:".len());
528    }
529
530    #[test]
531    fn generic_set_coalesces_duplicates_and_formats_multiline_values() {
532        let mut description =
533            RDescription::parse("X-Custom: old\nKeep: exact\n\nx-custom: duplicate\n");
534
535        description
536            .set_field("X-Custom", "first\r\nsecond")
537            .unwrap();
538
539        assert_eq!(
540            description.to_string(),
541            "X-Custom: first\n    second\nKeep: exact\n\n"
542        );
543        assert_eq!(
544            description.field_values("X-Custom")[0].value(),
545            "first\nsecond"
546        );
547    }
548
549    #[test]
550    fn generic_set_supports_empty_values_and_remove_clears_all_occurrences() {
551        let mut description = RDescription::parse("");
552        description.set_field("X-Custom", "").unwrap();
553        assert_eq!(description.to_string(), "X-Custom:\n");
554
555        description.set_field("x-custom", "again").unwrap();
556        description.remove_field("X-CUSTOM");
557        assert_eq!(description.to_string(), "");
558    }
559
560    #[test]
561    fn generic_set_validation_is_transactional() {
562        let input = "Package: example\n";
563        let mut description = RDescription::parse(input);
564
565        assert!(matches!(
566            description.set_field("-Invalid", "value"),
567            Err(FieldMutationError::InvalidFieldName { .. })
568        ));
569        assert_eq!(description.to_string(), input);
570
571        assert!(matches!(
572            description.set_field("#Comment", "value"),
573            Err(FieldMutationError::InvalidFieldName { .. })
574        ));
575        assert_eq!(description.to_string(), input);
576
577        assert_eq!(
578            description.set_field("X-Custom", "first\n \nthird"),
579            Err(FieldMutationError::EmptyContinuationLine { line: 2 })
580        );
581        assert_eq!(description.to_string(), input);
582
583        assert_eq!(
584            description.set_field("X-Custom", "first\n  second"),
585            Err(FieldMutationError::LeadingWhitespace { line: 2 })
586        );
587        assert_eq!(description.to_string(), input);
588    }
589}