Skip to main content

r_description/
validation.rs

1//! General DESCRIPTION validation, separate from parsing.
2
3use std::fmt::Display;
4
5use crate::{Description, SourceSpan, SyntaxDiagnosticKind, schema};
6
7/// Validation issue severity.
8#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
9pub enum Severity {
10    /// The document does not meet a DESCRIPTION requirement.
11    Error,
12    /// Suspicious but still interpretable input.
13    Warning,
14}
15
16/// A validation issue with stable identity and source location.
17#[derive(Debug, Clone, PartialEq, Eq, Hash)]
18pub struct ValidationIssue {
19    code: &'static str,
20    severity: Severity,
21    message: String,
22    span: SourceSpan,
23}
24
25impl ValidationIssue {
26    /// Stable machine-readable code.
27    pub const fn code(&self) -> &'static str {
28        self.code
29    }
30    /// Severity.
31    pub const fn severity(&self) -> Severity {
32        self.severity
33    }
34    /// Human-readable message.
35    pub fn message(&self) -> &str {
36        &self.message
37    }
38    /// Half-open source byte span.
39    pub const fn span(&self) -> SourceSpan {
40        self.span
41    }
42}
43
44/// Complete validation result in deterministic source/check order.
45#[derive(Debug, Clone, PartialEq, Eq, Default)]
46pub struct Validation {
47    issues: Vec<ValidationIssue>,
48}
49
50impl Validation {
51    /// Returns all validation issues.
52    pub fn issues(&self) -> &[ValidationIssue] {
53        &self.issues
54    }
55    /// Returns whether no error-severity issue exists.
56    pub fn is_valid(&self) -> bool {
57        !self
58            .issues
59            .iter()
60            .any(|issue| issue.severity == Severity::Error)
61    }
62    /// Consumes the result and returns its issues.
63    pub fn into_issues(self) -> Vec<ValidationIssue> {
64        self.issues
65    }
66}
67
68impl Description {
69    /// Validates DESCRIPTION structure and documented metadata value syntax.
70    ///
71    /// This deliberately excludes CRAN policy, style, and package-directory
72    /// checks.
73    pub fn validate(&self) -> Validation {
74        let mut issues = Vec::new();
75        for diagnostic in self.diagnostics() {
76            let code = match diagnostic.kind() {
77                SyntaxDiagnosticKind::MalformedField => "syntax.malformed-field",
78                SyntaxDiagnosticKind::OrphanContinuation => "syntax.orphan-continuation",
79                SyntaxDiagnosticKind::InvalidFieldName => "syntax.invalid-field-name",
80            };
81            push(
82                &mut issues,
83                code,
84                Severity::Error,
85                diagnostic.message(),
86                diagnostic.span(),
87            );
88        }
89        let records = self.records().collect::<Vec<_>>();
90        if records.len() != 1 {
91            push(
92                &mut issues,
93                "record-count",
94                Severity::Error,
95                format!("expected exactly one record, found {}", records.len()),
96                records
97                    .first()
98                    .map_or(SourceSpan::new(0, 0), crate::Record::source_range),
99            );
100        }
101        let Some(record) = records.first() else {
102            return Validation { issues };
103        };
104
105        for name in ["Package", "Version", "Title", "Description", "License"] {
106            if record.last_field(name).is_none() {
107                push(
108                    &mut issues,
109                    "missing-field",
110                    Severity::Error,
111                    format!("required field {name} is missing"),
112                    record.source_range(),
113                );
114            }
115        }
116        if record.last_field("Authors@R").is_none() {
117            for name in ["Author", "Maintainer"] {
118                if record.last_field(name).is_none() {
119                    push(
120                        &mut issues,
121                        "missing-field",
122                        Severity::Error,
123                        format!("required field {name} is missing when Authors@R is absent"),
124                        record.source_range(),
125                    );
126                }
127            }
128        }
129
130        let mut seen = std::collections::BTreeSet::new();
131        for field in record.fields() {
132            if let Some(name) = field.name()
133                && !schema::permits_duplicate_declarations(&name)
134                && !seen.insert(name.clone())
135            {
136                push(
137                    &mut issues,
138                    "duplicate-scalar",
139                    Severity::Warning,
140                    format!("scalar field {name} is declared more than once"),
141                    field.source_range(),
142                );
143            }
144        }
145
146        if let Some(field) = record.last_field("Package") {
147            let value = field.value();
148            if !valid_package_name(value.as_str()) {
149                push(
150                    &mut issues,
151                    "invalid-package-name",
152                    Severity::Error,
153                    "package name must have at least two ASCII characters, start with a letter, contain only letters, digits, or '.', and not end with '.'",
154                    value.source_range(),
155                );
156            }
157        }
158        if let Some(Err(error)) = self.version_parsed() {
159            typed(
160                &mut issues,
161                "invalid-version",
162                error,
163                record.last_field("Version"),
164            );
165        }
166        validate_collections(self, &mut issues);
167        validate_scalars(self, record, &mut issues);
168        Validation { issues }
169    }
170}
171
172fn validate_collections(description: &Description, issues: &mut Vec<ValidationIssue>) {
173    collection_issues(
174        issues,
175        "invalid-relation",
176        description.depends_parsed().issues(),
177    );
178    collection_issues(
179        issues,
180        "invalid-relation",
181        description.imports_parsed().issues(),
182    );
183    collection_issues(
184        issues,
185        "invalid-relation",
186        description.suggests_parsed().issues(),
187    );
188    collection_issues(
189        issues,
190        "invalid-relation",
191        description.enhances_parsed().issues(),
192    );
193    collection_issues(
194        issues,
195        "invalid-relation",
196        description.linking_to_parsed().issues(),
197    );
198    collection_issues(
199        issues,
200        "invalid-relation",
201        description.vignette_builder_parsed().issues(),
202    );
203    collection_issues(issues, "invalid-url", description.urls_parsed().issues());
204    collection_issues(
205        issues,
206        "invalid-url",
207        description.additional_repositories_parsed().issues(),
208    );
209    collection_issues(
210        issues,
211        "invalid-remote",
212        description.remotes_parsed().issues(),
213    );
214}
215
216fn validate_scalars(
217    description: &Description,
218    record: &crate::Record,
219    issues: &mut Vec<ValidationIssue>,
220) {
221    macro_rules! scalar {
222        ($name:literal, $code:literal, $value:expr) => {
223            if let Some(Err(error)) = $value {
224                typed(issues, $code, error, record.last_field($name));
225            }
226        };
227    }
228    scalar!(
229        "NeedsCompilation",
230        "invalid-logical",
231        description.needs_compilation_parsed()
232    );
233    scalar!("Biarch", "invalid-logical", description.biarch_parsed());
234    scalar!(
235        "LazyData",
236        "invalid-logical",
237        description.lazy_data_parsed()
238    );
239    scalar!(
240        "LazyLoad",
241        "invalid-logical",
242        description.lazy_load_parsed()
243    );
244    scalar!(
245        "ByteCompile",
246        "invalid-logical",
247        description.byte_compile_parsed()
248    );
249    scalar!(
250        "KeepSource",
251        "invalid-logical",
252        description.keep_source_parsed()
253    );
254    scalar!("UseLTO", "invalid-logical", description.use_lto_parsed());
255    scalar!(
256        "StagedInstall",
257        "invalid-logical",
258        description.staged_install_parsed()
259    );
260    scalar!("ZipData", "invalid-logical", description.zip_data_parsed());
261    scalar!(
262        "BuildVignettes",
263        "invalid-logical",
264        description.build_vignettes_parsed()
265    );
266    scalar!(
267        "License_is_FOSS",
268        "invalid-logical",
269        description.license_is_foss_parsed()
270    );
271    scalar!(
272        "License_restricts_use",
273        "invalid-logical",
274        description.license_restricts_use_parsed()
275    );
276    scalar!("OS_type", "invalid-os-type", description.os_type_parsed());
277    scalar!(
278        "Priority",
279        "invalid-priority",
280        description.priority_parsed()
281    );
282}
283
284fn valid_package_name(name: &str) -> bool {
285    name.len() >= 2
286        && name
287            .bytes()
288            .next()
289            .is_some_and(|byte| byte.is_ascii_alphabetic())
290        && name
291            .bytes()
292            .all(|byte| byte.is_ascii_alphanumeric() || byte == b'.')
293        && !name.ends_with('.')
294}
295
296fn collection_issues<E: Display>(
297    output: &mut Vec<ValidationIssue>,
298    code: &'static str,
299    issues: &[crate::CollectionIssue<E>],
300) {
301    for issue in issues {
302        push(
303            output,
304            code,
305            Severity::Error,
306            issue.error.to_string(),
307            issue.field_span,
308        );
309    }
310}
311
312fn typed<E: Display>(
313    output: &mut Vec<ValidationIssue>,
314    code: &'static str,
315    error: E,
316    field: Option<crate::Field>,
317) {
318    push(
319        output,
320        code,
321        Severity::Error,
322        error.to_string(),
323        field.map_or(SourceSpan::new(0, 0), |value| value.value().source_range()),
324    );
325}
326
327fn push(
328    output: &mut Vec<ValidationIssue>,
329    code: &'static str,
330    severity: Severity,
331    message: impl Into<String>,
332    span: SourceSpan,
333) {
334    output.push(ValidationIssue {
335        code,
336        severity,
337        message: message.into(),
338        span,
339    });
340}