Skip to main content

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}