quack_rs/validate/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 utilities for `DuckDB` community extension compliance.
7//!
8//! This module provides compile-time and runtime validators that enforce the
9//! [`DuckDB` Community Extension](https://duckdb.org/community_extensions/development)
10//! requirements. Extensions that pass these checks are ready for submission to the
11//! `DuckDB` community extensions repository.
12//!
13//! # What is validated
14//!
15//! - **Extension name**: A lowercase letter, then lowercase letters, digits and underscores
16//! (no hyphens: `DuckDB` derives the `<name>_init_c_api` symbol from it); for a
17//! community extension, also not a `DuckDB` alias (`s3`) or core extension name (`json`)
18//! - **Function name**: Letters, digits and underscores, and not a reserved SQL keyword —
19//! anything needing quotes in SQL is rejected
20//! - **Semantic versioning**: `validate_semver` for strict semver; extension
21//! versions are checked far more loosely, because `DuckDB` specifies no format
22//! - **SPDX license**: Must be a recognized SPDX license identifier
23//! - **Platform targets**: Exclusions must name real `DuckDB` build targets,
24//! kept in sync with `extension-ci-tools`' distribution matrix by CI
25//! - **Platform exclusion list**: Semicolon-separated string from `description.yml`
26//! - **Cargo.toml**: Release profile settings for loadable extensions
27//!
28//! # Example
29//!
30//! ```rust
31//! use quack_rs::validate::{
32//! validate_extension_name, validate_extension_version,
33//! validate_function_name, validate_semver, validate_spdx_license,
34//! validate_platform, validate_excluded_platforms_str,
35//! };
36//!
37//! assert!(validate_extension_name("my_extension").is_ok());
38//! assert!(validate_extension_name("MyExt").is_err()); // uppercase not allowed
39//!
40//! assert!(validate_function_name("word_count").is_ok());
41//! // Mixed case is fine — DuckDB ships `formatReadableSize`.
42//! assert!(validate_function_name("wordCount").is_ok());
43//! assert!(validate_function_name("word-count").is_err()); // would need quoting in SQL
44//!
45//! assert!(validate_semver("1.0.0").is_ok());
46//! assert!(validate_semver("not-a-version").is_err());
47//!
48//! // Extension versions accept both semver and git hashes (unstable)
49//! assert!(validate_extension_version("0.1.0").is_ok());
50//! assert!(validate_extension_version("690bfc5").is_ok());
51//!
52//! assert!(validate_spdx_license("MIT").is_ok());
53//! assert!(validate_spdx_license("FAKE-LICENSE").is_err());
54//!
55//! assert!(validate_platform("linux_amd64").is_ok());
56//! assert!(validate_platform("freebsd_amd64").is_err());
57//!
58//! // Validate the semicolon-separated excluded_platforms field from description.yml
59//! assert!(validate_excluded_platforms_str("wasm_mvp;wasm_eh;wasm_threads").is_ok());
60//! assert!(validate_excluded_platforms_str("invalid_platform").is_err());
61//! assert!(validate_excluded_platforms_str("").is_ok()); // empty means no exclusions
62//! ```
63
64pub mod description_yml;
65pub mod extension_name;
66pub mod function_name;
67pub mod platform;
68pub mod release_profile;
69pub mod semver;
70pub mod spdx;
71mod spdx_exceptions;
72
73pub use extension_name::{
74 validate_community_extension_name, validate_extension_name, DUCKDB_CORE_EXTENSION_NAMES,
75 DUCKDB_EXTENSION_ALIASES, DUCKDB_RESERVED_EXTENSION_NAMES,
76};
77pub use function_name::{
78 validate_function_name, validate_parameter_name, DUCKDB_RESERVED_KEYWORDS,
79 DUCKDB_UNCALLABLE_KEYWORDS, DUCKDB_UNREFERENCEABLE_PARAMETER_KEYWORDS,
80};
81pub use platform::{
82 is_opt_in_platform, validate_excluded_platforms, validate_platform, DUCKDB_CI_PLATFORMS,
83 DUCKDB_OPT_IN_PLATFORMS, DUCKDB_PLATFORMS, DUCKDB_PLATFORM_GROUPS, DUCKDB_RETIRED_PLATFORMS,
84};
85pub use release_profile::{validate_release_profile, ReleaseProfileCheck};
86pub use semver::{validate_extension_version, validate_semver};
87pub use spdx::validate_spdx_license;
88
89/// Validates the `excluded_platforms` field from `description.yml` as a semicolon-separated string.
90///
91/// `DuckDB`'s `description.yml` stores excluded platforms as a semicolon-delimited string:
92/// `"wasm_mvp;wasm_eh;wasm_threads"`. This function splits on `;` and validates each token.
93///
94/// An empty string is valid and means no platforms are excluded.
95///
96/// # Errors
97///
98/// Returns [`crate::error::ExtensionError`] if any token is not a known `DuckDB` build target,
99/// or if the same platform appears more than once.
100///
101/// # Example
102///
103/// ```rust
104/// use quack_rs::validate::validate_excluded_platforms_str;
105///
106/// assert!(validate_excluded_platforms_str("").is_ok());
107/// assert!(validate_excluded_platforms_str("wasm_mvp;wasm_eh").is_ok());
108/// assert!(validate_excluded_platforms_str("wasm_mvp;wasm_threads;wasm_eh").is_ok());
109/// assert!(validate_excluded_platforms_str("invalid_platform").is_err());
110/// assert!(validate_excluded_platforms_str("linux_amd64;linux_amd64").is_err()); // duplicate
111/// ```
112pub fn validate_excluded_platforms_str(s: &str) -> Result<(), crate::error::ExtensionError> {
113 if s.is_empty() {
114 return Ok(());
115 }
116 let tokens: Vec<&str> = s.split(';').collect();
117 validate_excluded_platforms(&tokens)
118}
119
120/// Whether `repo` is a GitHub repository path, `owner/repo`, in the
121/// characters GitHub allows: letters, digits and `-` in the owner (not first),
122/// and letters, digits, `-`, `_` and `.` in the name (not `.` or `..`).
123///
124/// `repo.github` in `description.yml` is handed to `actions/checkout` as its
125/// `repository`, which takes exactly this — not a URL, and not a path with
126/// more segments. The scaffold writes the same value.
127pub(crate) fn is_github_repo(repo: &str) -> bool {
128 repo.split_once('/').is_some_and(|(owner, name)| {
129 !owner.is_empty()
130 && !owner.starts_with('-')
131 && owner
132 .bytes()
133 .all(|b| b.is_ascii_alphanumeric() || b == b'-')
134 && !name.is_empty()
135 && name != "."
136 && name != ".."
137 && name
138 .bytes()
139 .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.'))
140 })
141}
142
143#[cfg(test)]
144mod tests {
145 use super::*;
146
147 #[test]
148 fn empty_excluded_platforms_str_is_ok() {
149 assert!(validate_excluded_platforms_str("").is_ok());
150 }
151
152 #[test]
153 fn single_platform_str_valid() {
154 assert!(validate_excluded_platforms_str("wasm_mvp").is_ok());
155 }
156
157 #[test]
158 fn multiple_platforms_str_valid() {
159 assert!(validate_excluded_platforms_str("wasm_mvp;wasm_eh;wasm_threads").is_ok());
160 }
161
162 #[test]
163 fn invalid_platform_str_rejected() {
164 let err = validate_excluded_platforms_str("invalid_platform").unwrap_err();
165 assert!(err.as_str().contains("not a recognized"));
166 }
167
168 #[test]
169 fn duplicate_platform_str_rejected() {
170 let err = validate_excluded_platforms_str("linux_amd64;linux_amd64").unwrap_err();
171 assert!(err.as_str().contains("duplicate"));
172 }
173
174 #[test]
175 fn all_wasm_platforms_excluded_is_ok() {
176 assert!(validate_excluded_platforms_str("wasm_mvp;wasm_eh;wasm_threads").is_ok());
177 }
178}