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}