Skip to main content

quack_rs/validate/description_yml/
model.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6/// A validated representation of a `DuckDB` community extension `description.yml`.
7///
8/// Construct via [`parse_description_yml`] or [`validate_description_yml_str`].
9///
10/// Every field was validated during construction. Things the community build
11/// accepts but that are probably not what the author meant — a licence outside
12/// quack-rs's SPDX shortlist, a list-form `excluded_platforms`, the British
13/// spelling `licence:` — do not fail the parse; they are reported in
14/// [`warnings`][Self::warnings].
15///
16/// `#[non_exhaustive]`: new fields can be added without a breaking release, so
17/// read fields by name rather than destructuring.
18///
19/// [`parse_description_yml`]: super::parse_description_yml
20/// [`validate_description_yml_str`]: super::validate_description_yml_str
21#[derive(Debug, Clone, PartialEq, Eq)]
22#[non_exhaustive]
23pub struct DescriptionYml {
24    // extension section
25    /// Extension name (validated: a lowercase letter, then lowercase letters,
26    /// digits and underscores).
27    pub name: String,
28    /// One-line description of the extension.
29    pub description: String,
30    /// Extension version, when the file declares one (validated: see
31    /// [`validate_extension_version`][crate::validate::validate_extension_version]).
32    ///
33    /// Optional: the community build never reads it (`scripts/build.py` in
34    /// `duckdb/community-extensions` takes the version from the extension's
35    /// own repository), and 12 of the 346 published files omit it.
36    pub version: Option<String>,
37    /// Implementation language (for Rust extensions: `"Rust"`).
38    pub language: String,
39    /// Build system (for Rust extensions: `"cargo"`).
40    pub build: String,
41    /// The declared license — an SPDX identifier or expression when the file
42    /// follows the convention. Only presence is enforced; see
43    /// [`warnings`][Self::warnings].
44    pub license: String,
45    /// Semicolon-separated required toolchains (must include `"rust"` for Rust extensions).
46    pub requires_toolchains: String,
47    /// Platforms to exclude from CI builds, semicolon-separated. Empty means no
48    /// exclusions. A YAML list in the file is joined with `;` here (and warned
49    /// about: the community build passes a list through unsplit).
50    pub excluded_platforms: String,
51    /// Opt-in platforms to build, semicolon-separated (`extension.opt_in_platforms`).
52    /// Empty when absent.
53    ///
54    /// The community build only builds the platforms in
55    /// [`DUCKDB_OPT_IN_PLATFORMS`][crate::validate::DUCKDB_OPT_IN_PLATFORMS] when
56    /// they are listed here. A name that is not one of them, or that is not a
57    /// platform at all, is ignored by the build and reported in
58    /// [`warnings`][Self::warnings].
59    pub opt_in_platforms: String,
60    /// List of maintainer names (at least one required).
61    pub maintainers: Vec<String>,
62    // repo section
63    /// GitHub repository in `owner/repo` format.
64    pub github: String,
65    /// The git ref the community build checks out: a commit hash. A branch or
66    /// tag is accepted with a warning in [`DescriptionYml::warnings`].
67    pub git_ref: String,
68    /// `repo.ref_next` — a revision compatible with `DuckDB`'s `main` branch,
69    /// empty when absent.
70    ///
71    /// Optional, and documented by `DuckDB` for the window while a new release
72    /// is being prepared: the community repository tests an extension against
73    /// both the latest stable release and `main`, and once the release hash is
74    /// set `ref_next` is swapped in for `ref`.
75    pub git_ref_next: String,
76    /// `repo.variegata` — the revision the community build checks out when it
77    /// builds for `DuckDB` v1.5.6 (the `v1.5-variegata` release line) instead
78    /// of [`git_ref`][Self::git_ref]; empty when absent. 133 of the 395
79    /// published descriptors set it.
80    ///
81    /// `ref` is built for the newest release (v2.0.0). An extension stamped
82    /// for one exact `DuckDB` 1.x release (`C_STRUCT_UNSTABLE`) needs its
83    /// v1.5.6 build here, from a revision whose `Makefile` targets v1.5.6.
84    pub git_ref_variegata: String,
85    /// `repo.andium` — as [`git_ref_variegata`][Self::git_ref_variegata], for
86    /// `DuckDB` v1.4.5 (the `v1.4-andium` line); empty when absent.
87    pub git_ref_andium: String,
88    /// Non-fatal findings, one human-readable sentence each: the file is
89    /// accepted, but something in it is unusual enough to be worth a look.
90    pub warnings: Vec<String>,
91}