quack_rs/validate/description_yml/
parser.rs1use crate::error::ExtensionError;
7use crate::validate::platform::{
8 is_opt_in_platform, platforms_in_group, DUCKDB_OPT_IN_PLATFORMS, DUCKDB_PLATFORM_GROUPS,
9 DUCKDB_RETIRED_PLATFORMS,
10};
11use crate::validate::{
12 validate_community_extension_name, validate_excluded_platforms_str, validate_extension_version,
13 validate_platform, validate_spdx_license,
14};
15
16use super::model::DescriptionYml;
17use super::yaml::{read_sections, Entry, Section, Value};
18use super::yaml11;
19
20pub fn parse_description_yml(content: &str) -> Result<DescriptionYml, ExtensionError> {
110 let sections = read_sections(content, &["extension", "repo"])
111 .map_err(|e| ExtensionError::new(format!("description.yml: {e}")))?;
112 let extension = Fields::new(§ions, "extension");
113 let repo = Fields::new(§ions, "repo");
114 let mut warnings = Vec::new();
115
116 let name = extension.scalar("name")?;
117 if name.is_empty() {
118 return Err(missing("extension.name"));
119 }
120 validate_community_extension_name(&name)
121 .map_err(|e| ExtensionError::new(format!("description.yml: extension.name: {e}")))?;
122
123 let description = extension.required("description")?;
124
125 let version = extension.scalar("version")?;
126 let version = if version.is_empty() {
127 None
128 } else {
129 validate_extension_version(&version)
130 .map_err(|e| ExtensionError::new(format!("description.yml: extension.version: {e}")))?;
131 Some(version)
132 };
133
134 let language = extension.required("language")?;
135 let build = extension.required("build")?;
136
137 let license = match (extension.get("license"), extension.get("licence")) {
138 (Some(first), Some(second)) => {
139 return Err(ExtensionError::new(format!(
140 "description.yml: both 'extension.license' (line {}) and \
141 'extension.licence' (line {}) are set",
142 first.line, second.line
143 )))
144 }
145 (None, Some(_)) => {
146 warnings.push(
147 "'extension.licence' is the British spelling; DuckDB's documentation and \
148 tooling use 'license'"
149 .to_string(),
150 );
151 extension.scalar("licence")?
152 }
153 _ => extension.scalar("license")?,
154 };
155 if license.is_empty() {
156 return Err(missing("extension.license"));
157 }
158 if let Err(e) = validate_spdx_license(&license) {
159 warnings.push(format!("extension.license: {e}"));
160 }
161
162 let requires_toolchains = extension.semicolon_list("requires_toolchains", &mut warnings)?;
166
167 let (excluded_platforms, opt_in_platforms) = extension.platforms(&mut warnings)?;
168
169 let maintainers = extension.maintainers(&mut warnings)?;
170 if maintainers.is_empty() {
171 return Err(ExtensionError::new(
172 "description.yml: 'extension.maintainers' must list at least one maintainer",
173 ));
174 }
175
176 let github = repo.scalar("github")?;
177 if github.is_empty() {
178 return Err(missing("repo.github"));
179 }
180 if !crate::validate::is_github_repo(&github) {
181 return Err(ExtensionError::new(format!(
182 "description.yml: 'repo.github' must be in 'owner/repo' format — the repository, \
183 not its URL or a path inside it, in the characters GitHub allows (the community \
184 build passes it to actions/checkout as `repository`), got '{github}'"
185 )));
186 }
187
188 let git_ref = repo.scalar("ref")?;
189 if git_ref.is_empty() {
190 return Err(missing("repo.ref"));
191 }
192 warn_unless_commit_hash("repo.ref", &git_ref, &mut warnings);
193 let git_ref_next = repo.scalar("ref_next")?;
194 let git_ref_variegata = repo.release_ref("variegata", "v1.5.6", &mut warnings)?;
195 let git_ref_andium = repo.release_ref("andium", "v1.4.5", &mut warnings)?;
196 warn_about_unknown_repo_keys(&repo, &mut warnings);
197
198 warn_about_yaml_1_1_retyping(&[&extension, &repo], &mut warnings);
199
200 Ok(DescriptionYml {
201 name,
202 description,
203 version,
204 language,
205 build,
206 license,
207 requires_toolchains,
208 excluded_platforms,
209 opt_in_platforms,
210 maintainers,
211 github,
212 git_ref,
213 git_ref_next,
214 git_ref_variegata,
215 git_ref_andium,
216 warnings,
217 })
218}
219
220const REPO_KEYS: [&str; 6] = [
223 "github",
224 "ref",
225 "ref_next",
226 "variegata",
227 "andium",
228 "canonical_name",
229];
230
231fn warn_about_unknown_repo_keys(repo: &Fields<'_>, warnings: &mut Vec<String>) {
234 for entry in repo.entries {
235 if !REPO_KEYS.contains(&entry.key.as_str()) {
236 warnings.push(format!(
237 "repo.{}: the community build does not read this key (it reads {}), so it has \
238 no effect",
239 entry.key,
240 REPO_KEYS.join(", ")
241 ));
242 }
243 }
244}
245
246fn warn_about_platform_groups(field: &str, list: &str, warnings: &mut Vec<String>) {
256 for group in list
257 .split(';')
258 .filter(|p| DUCKDB_PLATFORM_GROUPS.contains(p))
259 {
260 warnings.push(format!(
261 "extension.{field}: '{group}' is a platform group, not a platform. The community \
262 build compares exact platform names, so it matches nothing here; list the \
263 platforms instead: \"{}\"",
264 platforms_in_group(group).join(";")
265 ));
266 }
267}
268
269fn warn_about_ignored_opt_ins(list: &str, warnings: &mut Vec<String>) {
275 warn_about_platform_groups("opt_in_platforms", list, warnings);
276 for platform in list.split(';').filter(|p| !p.is_empty()) {
277 if DUCKDB_PLATFORM_GROUPS.contains(&platform) || is_opt_in_platform(platform) {
278 continue;
279 }
280 let why = if validate_platform(platform).is_ok() {
281 "is not an opt-in platform, so the community build ignores it here"
282 } else {
283 "is not a recognized DuckDB build target, so the community build ignores it"
284 };
285 warnings.push(format!(
286 "extension.opt_in_platforms: '{platform}' {why} (the opt-in platforms are {})",
287 DUCKDB_OPT_IN_PLATFORMS.join(", ")
288 ));
289 }
290}
291
292fn warn_about_yaml_1_1_retyping(sections: &[&Fields<'_>], warnings: &mut Vec<String>) {
298 const READ_AS_TEXT: [&str; 15] = [
299 "name",
300 "description",
301 "version",
302 "language",
303 "build",
304 "license",
305 "licence",
306 "requires_toolchains",
307 "excluded_platforms",
308 "opt_in_platforms",
309 "github",
310 "ref",
311 "ref_next",
312 "variegata",
313 "andium",
314 ];
315 for fields in sections {
316 for entry in fields.entries {
317 let Value::Scalar(ref text) = entry.value else {
318 continue;
319 };
320 if !entry.plain || !READ_AS_TEXT.contains(&entry.key.as_str()) {
321 continue;
322 }
323 if let Some(kind) = yaml11::implicit_type(text) {
324 warnings.push(format!(
325 "{}.{}: the unquoted value '{text}' is {kind}, not text, to YAML 1.1 \
326 readers such as PyYAML, which the community-extensions build uses; quote \
327 it",
328 fields.section, entry.key
329 ));
330 }
331 }
332 }
333}
334
335fn missing(field: &str) -> ExtensionError {
336 ExtensionError::new(format!("description.yml: missing required field '{field}'"))
337}
338
339struct Fields<'a> {
342 section: &'static str,
343 entries: &'a [Entry],
344}
345
346impl<'a> Fields<'a> {
347 fn new(sections: &'a [Section], section: &'static str) -> Self {
348 let entries = sections
349 .iter()
350 .find(|s| s.name == section)
351 .map_or(&[][..], |s| s.entries.as_slice());
352 Self { section, entries }
353 }
354
355 fn get(&self, key: &str) -> Option<&'a Entry> {
356 self.entries.iter().find(|e| e.key == key)
357 }
358
359 fn scalar(&self, key: &str) -> Result<String, ExtensionError> {
361 match self.get(key).map(|e| (&e.value, e.line)) {
362 None | Some((Value::Null, _)) => Ok(String::new()),
363 Some((Value::Scalar(s), _)) => Ok(s.clone()),
367 Some((_, line)) => Err(ExtensionError::new(format!(
368 "description.yml: line {line}: '{}.{key}' must be a single value, not a list \
369 or mapping",
370 self.section
371 ))),
372 }
373 }
374
375 fn release_ref(
381 &self,
382 key: &str,
383 release: &str,
384 warnings: &mut Vec<String>,
385 ) -> Result<String, ExtensionError> {
386 let Some(entry) = self.get(key) else {
387 return Ok(String::new());
388 };
389 let value = self.scalar(key)?;
390 if value.is_empty() {
391 return Err(ExtensionError::new(format!(
392 "description.yml: line {}: 'repo.{key}' is present but empty: the community \
393 build then checks out no revision when it builds for DuckDB {release}; give \
394 a commit hash or remove the key",
395 entry.line
396 )));
397 }
398 warn_unless_commit_hash(&format!("repo.{key}"), &value, warnings);
399 Ok(value)
400 }
401
402 fn required(&self, key: &str) -> Result<String, ExtensionError> {
404 let value = self.scalar(key)?;
405 if value.is_empty() {
406 return Err(missing(&format!("{}.{key}", self.section)));
407 }
408 Ok(value)
409 }
410
411 fn semicolon_list(
417 &self,
418 key: &str,
419 warnings: &mut Vec<String>,
420 ) -> Result<String, ExtensionError> {
421 let Some(Entry {
422 value: Value::Seq(items),
423 line,
424 ..
425 }) = self.get(key)
426 else {
427 return self.scalar(key);
428 };
429 let mut joined = Vec::with_capacity(items.len());
430 for item in items {
431 match item {
432 Value::Scalar(s) => joined.push(s.trim().to_string()),
433 Value::Null => {}
434 _ => {
435 return Err(ExtensionError::new(format!(
436 "description.yml: line {line}: '{}.{key}' entries must be plain values",
437 self.section
438 )))
439 }
440 }
441 }
442 let joined = joined.join(";");
443 warnings.push(format!(
444 "{}.{key} is a YAML list; the community build copies the value into its \
445 environment as-is, so a list arrives as Python's ['a', 'b'] rather than the \
446 ';'-separated string it splits — write \"{joined}\"",
447 self.section
448 ));
449 Ok(joined)
450 }
451
452 fn platforms(&self, warnings: &mut Vec<String>) -> Result<(String, String), ExtensionError> {
455 let excluded = self.semicolon_list("excluded_platforms", warnings)?;
456 validate_excluded_platforms_str(&excluded).map_err(|e| {
457 ExtensionError::new(format!(
458 "description.yml: extension.excluded_platforms: {e}"
459 ))
460 })?;
461 for retired in excluded
462 .split(';')
463 .filter(|p| DUCKDB_RETIRED_PLATFORMS.contains(p))
464 {
465 warnings.push(format!(
466 "extension.excluded_platforms: '{retired}' is no longer built by DuckDB, so \
467 excluding it has no effect"
468 ));
469 }
470 warn_about_platform_groups("excluded_platforms", &excluded, warnings);
471
472 let opt_in = self.semicolon_list("opt_in_platforms", warnings)?;
473 warn_about_ignored_opt_ins(&opt_in, warnings);
474 Ok((excluded, opt_in))
475 }
476
477 fn maintainers(&self, warnings: &mut Vec<String>) -> Result<Vec<String>, ExtensionError> {
479 let Some(entry) = self.get("maintainers") else {
480 return Ok(Vec::new());
481 };
482 match &entry.value {
483 Value::Null => Ok(Vec::new()),
484 Value::Scalar(name) => {
485 warnings.push(format!(
486 "extension.maintainers should be a list; read '{name}' as its only entry"
487 ));
488 Ok(vec![name.trim().to_string()])
489 }
490 Value::Seq(items) => {
491 let mut names = Vec::with_capacity(items.len());
492 for item in items {
493 match item {
494 Value::Scalar(name) if !name.trim().is_empty() => {
495 names.push(name.trim().to_string());
496 }
497 Value::Scalar(_) | Value::Null => {}
498 _ => {
499 return Err(ExtensionError::new(format!(
500 "description.yml: line {}: 'extension.maintainers' entries must \
501 be names, not lists or mappings",
502 entry.line
503 )))
504 }
505 }
506 }
507 Ok(names)
508 }
509 Value::Mapping => Err(ExtensionError::new(format!(
510 "description.yml: line {}: 'extension.maintainers' must be a list of names",
511 entry.line
512 ))),
513 }
514 }
515}
516
517fn warn_unless_commit_hash(field: &str, git_ref: &str, warnings: &mut Vec<String>) {
522 if !is_commit_hash(git_ref) {
523 warnings.push(format!(
524 "{field} '{git_ref}' is not a commit hash: the community build checks out \
525 exactly this revision, and a branch or tag can be moved to another commit, so \
526 the build is not pinned; DuckDB's documentation asks for the hash of the commit \
527 to build"
528 ));
529 }
530}
531
532fn is_commit_hash(git_ref: &str) -> bool {
535 (7..=64).contains(&git_ref.len()) && git_ref.bytes().all(|b| b.is_ascii_hexdigit())
536}