quack_rs/validate/description_yml/mod.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//! Validation of `DuckDB` community extension `description.yml` files.
7//!
8//! Every extension submitted to the `DuckDB` community extensions repository must
9//! include a `description.yml` metadata file. This module provides:
10//!
11//! - [`DescriptionYml`] — a structured representation of the file's required fields
12//! - [`parse_description_yml`] — parse from a `description.yml` string
13//! - [`validate_description_yml_str`] — validate a `description.yml` string end-to-end
14//!
15//! # `description.yml` Format
16//!
17//! ```yaml
18//! extension:
19//! name: my_ext
20//! description: A one-line description of the extension.
21//! version: 0.1.0
22//! language: Rust
23//! build: cargo
24//! license: MIT
25//! requires_toolchains: rust;python3 # optional
26//! excluded_platforms: "wasm_mvp;wasm_eh;wasm_threads" # optional
27//! maintainers:
28//! - Jane Doe
29//!
30//! repo:
31//! github: janedoe/duckdb-my-ext
32//! ref: 4f1c2e9a7b3d5c8e1f0a2b4c6d8e0f1a3b5c7d9e
33//! ```
34//!
35//! # Required vs Optional Fields
36//!
37//! | Field | Required | Rules |
38//! |-------|----------|-------|
39//! | `extension.name` | Yes | Must pass [`validate_extension_name`] |
40//! | `extension.description` | Yes | Non-empty |
41//! | `extension.version` | No | If present, must pass [`validate_extension_version`]; the community build never reads it |
42//! | `extension.language` | Yes | Must be `"Rust"` for Rust extensions |
43//! | `extension.build` | Yes | Must be `"cargo"` for Rust extensions |
44//! | `extension.license` | Yes | Non-empty (`licence` accepted); a value [`validate_spdx_license`] rejects is a warning in [`DescriptionYml::warnings`] |
45//! | `extension.requires_toolchains` | No | Semi-colon list; [`validate_rust_extension`] additionally requires `"rust"` |
46//! | `extension.excluded_platforms` | No | Must pass [`validate_excluded_platforms_str`]; a YAML list is accepted with a warning, and so is a group name such as `wasm`, which excludes nothing |
47//! | `extension.opt_in_platforms` | No | Platforms to build that are not built by default; the parser warns about any name the build would ignore |
48//! | `extension.maintainers` | Yes | At least one maintainer |
49//! | `repo.github` | Yes | `owner/repo`, in the characters GitHub allows — not a URL |
50//! | `repo.ref` | Yes | Non-empty git ref; anything but a commit hash is a warning |
51//! | `repo.ref_next` | No | The revision built against `DuckDB` `main` before a release |
52//! | `repo.variegata`, `repo.andium` | No | Non-empty if present: the revisions built for `DuckDB` v1.5.6 and v1.4.5 instead of `ref`; anything but a commit hash is a warning |
53//!
54//! Any other `repo:` key is a warning (the community build ignores it). The
55//! whole file — `docs:` included — must be YAML that `PyYAML`'s
56//! `yaml.safe_load` accepts, since that is the community build's first step;
57//! see [`parse_description_yml`] for what is checked.
58//!
59//! # Reference
60//!
61//! - <https://duckdb.org/community_extensions/documentation>
62//! - <https://duckdb.org/community_extensions/development>
63//!
64//! # Example
65//!
66//! ```rust
67//! use quack_rs::validate::description_yml::validate_description_yml_str;
68//!
69//! let yml = r#"
70//! extension:
71//! name: my_ext
72//! description: Fast analytics for DuckDB.
73//! version: 0.1.0
74//! language: Rust
75//! build: cargo
76//! license: MIT
77//! requires_toolchains: rust;python3
78//! maintainers:
79//! - Jane Doe
80//!
81//! repo:
82//! github: janedoe/duckdb-my-ext
83//! ref: 4f1c2e9a7b3d5c8e1f0a2b4c6d8e0f1a3b5c7d9e
84//! "#;
85//!
86//! assert!(validate_description_yml_str(yml).is_ok());
87//! ```
88//!
89//! [`validate_rust_extension`]: crate::validate::description_yml::validate_rust_extension
90//! [`validate_extension_name`]: crate::validate::validate_extension_name
91//! [`validate_extension_version`]: crate::validate::validate_extension_version
92//! [`validate_spdx_license`]: crate::validate::validate_spdx_license
93//! [`validate_excluded_platforms_str`]: crate::validate::validate_excluded_platforms_str
94
95mod model;
96mod parser;
97mod validator;
98mod yaml;
99mod yaml11;
100
101pub use model::DescriptionYml;
102pub use parser::parse_description_yml;
103pub use validator::{validate_description_yml_str, validate_rust_extension};
104
105#[cfg(test)]
106mod tests;
107#[cfg(test)]
108mod tests_corpus;
109#[cfg(test)]
110mod tests_mut_block;
111#[cfg(test)]
112mod tests_mut_flow_a;
113#[cfg(test)]
114mod tests_mut_flow_b;
115#[cfg(test)]
116mod tests_mut_scalar;
117#[cfg(test)]
118mod tests_pyyaml;
119#[cfg(test)]
120mod tests_yaml;