diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19edb5cac..d6c64e5f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,6 +51,7 @@ that directory to see how it should look like. - Make each tool description as precise as possible. Please limit the description to **500 characters**. - Add a license. If it's a proprietary tool, use `license: proprietary`. +- Add at least one category: `linter`, `formatter`, `performance`, or `meta`. - Add at least one tag, and include as many relevant tags as possible. Choose from `data/tags.yml`. If a tool does not match any existing tag, feel free to add a new tag but also add it to `data/tags.yml`. diff --git a/ci/crates/render/src/bin/main.rs b/ci/crates/render/src/bin/main.rs index c2630cb79..ccd9cc854 100644 --- a/ci/crates/render/src/bin/main.rs +++ b/ci/crates/render/src/bin/main.rs @@ -177,7 +177,7 @@ mod tests { #[test] fn cached_deprecation_never_overrides_explicit_markers() -> Result<()> { - let fixture = r#"{"name":"Example Tool","categories":[],"tags":[{"name":"Rust","value":"rust","tag_type":"language"}],"license":"MIT","types":[],"homepage":"https://example.com","description":"Example"}"#; + let fixture = r#"{"name":"Example Tool","categories":["linter"],"tags":[{"name":"Rust","value":"rust","tag_type":"language"}],"license":"MIT","types":[],"homepage":"https://example.com","description":"Example"}"#; for cached_marker in [Some(true), Some(false), None] { let cached = BTreeMap::from([( "example-tool".into(), diff --git a/ci/crates/render/src/lib.rs b/ci/crates/render/src/lib.rs index 922b27f3e..8653a688d 100644 --- a/ci/crates/render/src/lib.rs +++ b/ci/crates/render/src/lib.rs @@ -152,7 +152,7 @@ mod tests { fn entry(tags: &[Tag]) -> Result { Ok(Entry { name: String::from("Multi Tool").try_into()?, - categories: BTreeSet::new(), + categories: BTreeSet::from([crate::types::Category::Linter]).try_into()?, tags: tags.iter().cloned().collect::>().try_into()?, license: "MIT".into(), types: BTreeSet::new(), diff --git a/ci/crates/render/src/types.rs b/ci/crates/render/src/types.rs index e5909afe8..56f7d98e3 100644 --- a/ci/crates/render/src/types.rs +++ b/ci/crates/render/src/types.rs @@ -5,7 +5,7 @@ use serde::{Deserialize, Serialize, de::value::StrDeserializer}; use std::cmp::Ordering; use std::collections::{BTreeMap, BTreeSet}; -pub use crate::validated::{EntryName, EntryTags}; +pub use crate::validated::{EntryCategories, EntryName, EntryTags}; #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash, Ord, PartialOrd)] pub enum Type { @@ -62,7 +62,7 @@ pub enum Category { #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)] pub struct ParsedEntry { pub name: EntryName, - pub categories: BTreeSet, + pub categories: EntryCategories, pub tags: EntryTags, pub license: String, pub types: BTreeSet, @@ -94,7 +94,7 @@ pub enum ToolType { #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)] pub struct Entry { pub name: EntryName, - pub categories: BTreeSet, + pub categories: EntryCategories, pub tags: EntryTags, pub license: String, pub types: BTreeSet, @@ -259,7 +259,7 @@ impl Catalog { pub struct ApiEntry { /// The original entry name (not slugified) pub name: String, - pub categories: BTreeSet, + pub categories: EntryCategories, pub languages: Vec, pub other: Vec, pub licenses: Vec, diff --git a/ci/crates/render/src/validated.rs b/ci/crates/render/src/validated.rs index 4d8ace879..16478e36e 100644 --- a/ci/crates/render/src/validated.rs +++ b/ci/crates/render/src/validated.rs @@ -1,3 +1,4 @@ +use crate::types::Category; use anyhow::{Result, ensure}; use serde::{Deserialize, Serialize}; use std::collections::{BTreeSet, btree_set}; @@ -89,6 +90,23 @@ impl<'a, T: Ord> IntoIterator for &'a EntryTags { } } +/// A nonempty, sorted set of tool categories, with no mutable access to its contents. +#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)] +#[serde(try_from = "BTreeSet")] +pub struct EntryCategories(BTreeSet); + +impl TryFrom> for EntryCategories { + type Error = anyhow::Error; + + fn try_from(categories: BTreeSet) -> Result { + ensure!( + !categories.is_empty(), + "Entry must have at least one category: linter, formatter, performance, or meta." + ); + Ok(Self(categories)) + } +} + #[cfg(test)] mod tests { use super::*; @@ -125,6 +143,35 @@ mod tests { Ok(()) } + #[test] + fn categories_reject_empty_sets_in_constructors_and_serde() { + assert!(EntryCategories::try_from(BTreeSet::new()).is_err()); + for input in ["[]", "null", "\"linter\"", "[\"unknown\"]"] { + assert!(serde_json::from_str::(input).is_err()); + assert!(serde_saphyr::from_str::(input).is_err()); + } + } + + #[test] + fn categories_are_sorted_and_deduplicated_through_serde() -> Result<()> { + let categories = + EntryCategories::try_from(BTreeSet::from([Category::Formatter, Category::Linter]))?; + let encoded = r#"["formatter","linter","formatter"]"#; + assert_eq!( + serde_json::from_str::(encoded)?, + categories + ); + assert_eq!( + serde_saphyr::from_str::(encoded)?, + categories + ); + assert_eq!( + serde_json::to_value(categories)?, + json!(["linter", "formatter"]) + ); + Ok(()) + } + #[test] fn tags_reject_empty_sets_in_constructors_and_serde() { assert!(EntryTags::::try_from(BTreeSet::new()).is_err()); diff --git a/ci/crates/render/tests/regression.rs b/ci/crates/render/tests/regression.rs index 07e4dc2b5..9aa835f89 100644 --- a/ci/crates/render/tests/regression.rs +++ b/ci/crates/render/tests/regression.rs @@ -127,6 +127,56 @@ fn full_catalog_preserves_original_sources_through_api_output() -> Result<()> { Ok(()) } +#[test] +fn entries_require_nonempty_categories_in_yaml_and_json() -> Result<()> { + let parsed = serde_json::to_value(parsed()?)?; + let entry = Entry::from_parsed(self::parsed()?, &[tag("rust", Type::Language)])?; + let normalized = serde_json::to_value(&entry)?; + let api = create_api(vec![entry], &[tag("rust", Type::Language)], &[]); + let api = serde_json::to_value(api.values().next().context("Expected API entry")?)?; + + for categories in [ + None, + Some(json!([])), + Some(json!(null)), + Some(json!(["unknown"])), + ] { + for (kind, mut value) in [ + ("parsed", parsed.clone()), + ("normalized", normalized.clone()), + ("api", api.clone()), + ] { + if let Some(categories) = &categories { + value["categories"] = categories.clone(); + } else { + value + .as_object_mut() + .context("Expected object")? + .remove("categories"); + } + let encoded = serde_json::to_string(&value)?; + let (json_error, yaml_error) = match kind { + "parsed" => ( + serde_json::from_str::(&encoded).is_err(), + serde_saphyr::from_str::(&encoded).is_err(), + ), + "normalized" => ( + serde_json::from_str::(&encoded).is_err(), + serde_saphyr::from_str::(&encoded).is_err(), + ), + _ => ( + serde_json::from_str::(&encoded).is_err(), + serde_saphyr::from_str::(&encoded).is_err(), + ), + }; + assert!(json_error && yaml_error, "{kind}: {encoded}"); + } + } + let yaml = "name: Example\ncategories:\ntags: [rust]\nlicense: MIT\ntypes: [cli]\nhomepage: https://example.com\ndescription: Example\n"; + assert!(serde_saphyr::from_str::(yaml).is_err()); + Ok(()) +} + #[test] fn normalization_preserves_fields_and_uses_the_first_matching_tag() -> Result<()> { let original = parsed()?; diff --git a/data/tools/pixee.yml b/data/tools/pixee.yml index 17d652bc5..3d6f5f830 100644 --- a/data/tools/pixee.yml +++ b/data/tools/pixee.yml @@ -1,5 +1,6 @@ name: Pixee -categories: [] +categories: + - linter tags: - java - python