chore(vdev): add deprecation fragment commands (#25638)

Author: pront

vdev/src/commands/deprecation/check.rs

@@ -0,0 +1,98 @@
+#![allow(clippy::print_stdout)]
+#![allow(clippy::print_stderr)]
+
+use anyhow::{Result, bail};
+use semver::Version;
+
+use crate::utils::{deprecation, git, paths};
+
+/// Check deprecation.d fragments are valid and that generated/deprecations.json is up to date
+#[derive(clap::Args, Debug)]
+#[command()]
+pub struct Cli {}
+
+impl Cli {
+    pub fn exec(self) -> Result<()> {
+        let repo_root = paths::find_repo_root()?;
+        let dir = repo_root.join(deprecation::DEPRECATION_DIR);
+
+        let json_path = repo_root.join(deprecation::DEPRECATIONS_JSON);
+        let entries = if dir.is_dir() {
+            deprecation::read_deprecation_fragments(&dir)?
+        } else if json_path.is_file() {
+            println!(
+                "{} not found; validating generated JSON only.",
+                dir.display()
+            );
+            Vec::new()
+        } else {
+            bail!(
+                "Neither {} nor {} found; the deprecation fragment system is not installed in this repo.",
+                dir.display(),
+                json_path.display()
+            );
+        };
+
+        if entries.is_empty() {
+            println!("No deprecation fragments found.");
+        } else {
+            for entry in &entries {
+                println!("  ok  {}", entry.filename);
+            }
+            println!("{} deprecation fragment(s) are valid.", entries.len());
+        }
+
+        // Reject any fragment with a deprecated_since newer than the next
+        // minor release. Skipped (with a warning) when the checkout has no
+        // release tags so shallow CI/source checkouts can still validate
+        // fragment frontmatter + generated JSON.
+        match git::latest_release_version() {
+            Ok(latest) => {
+                let next_minor = Version::new(latest.major, latest.minor + 1, 0);
+                let future: Vec<_> = entries
+                    .iter()
+                    .filter(|e| e.deprecated_since.0 > next_minor)
+                    .collect();
+                if !future.is_empty() {
+                    for e in &future {
+                        eprintln!(
+                            "  future  {} (deprecated_since: {}, next release: {}.{})",
+                            e.filename, e.deprecated_since, next_minor.major, next_minor.minor
+                        );
+                    }
+                    bail!(
+                        "{} fragment(s) have a deprecated_since version newer than the next release ({}.{}). \
+                         Update deprecated_since to {} or earlier.",
+                        future.len(),
+                        next_minor.major,
+                        next_minor.minor,
+                        next_minor
+                    );
+                }
+            }
+            Err(e) => {
+                eprintln!(
+                    "Warning: skipping future-version validation; could not determine latest release version: {e}"
+                );
+            }
+        }
+
+        let on_disk = std::fs::read_to_string(&json_path).unwrap_or_default();
+        let expected = deprecation::rendered_json(&repo_root)?;
+        if on_disk != expected {
+            bail!(
+                "{} is out of date. Run `cargo vdev deprecation generate` and commit the result.",
+                json_path.display()
+            );
+        }
+
+        let enacted_count = deprecation::validate_enacted(&repo_root)?;
+        println!(
+            "{} is up to date ({} enacted entries valid).",
+            json_path.display(),
+            enacted_count
+        );
+
+        Ok(())
+    }
+}

vdev/src/commands/deprecation/enact.rs

@@ -0,0 +1,97 @@
+#![allow(clippy::print_stdout)]
+
+use anyhow::{Result, bail};
+use semver::Version;
+
+use crate::utils::{deprecation, git, paths};
+
+/// Enact a deprecation: record it as removed and delete the deprecation.d fragment
+#[derive(clap::Args, Debug)]
+#[command()]
+pub struct Cli {
+    /// Filename (slug) in deprecation.d/ to enact, e.g. "azure-monitor-logs-sink"
+    slug: String,
+
+    /// The Vector version in which this feature was removed, e.g. "0.58.0".
+    /// Defaults to the next minor after the latest git tag.
+    #[arg(long)]
+    version: Option<Version>,
+}
+
+impl Cli {
+    pub fn exec(self) -> Result<()> {
+        let repo_root = paths::find_repo_root()?;
+        let dir = repo_root.join(deprecation::DEPRECATION_DIR);
+
+        // Accept "slug" or "slug.md"; reject path-like inputs to keep the
+        // identifier unambiguous (and the file lookup safe).
+        if self.slug.contains('/') || self.slug.contains('\\') {
+            bail!(
+                "expected a deprecation slug (e.g. \"azure-monitor-logs-sink\"), not a path: {}",
+                self.slug
+            );
+        }
+        let stem = self.slug.strip_suffix(".md").unwrap_or(&self.slug);
+        let filename = format!("{stem}.md");
+
+        let path = dir.join(&filename);
+        if !path.exists() {
+            bail!("No deprecation fragment found at {}", path.display());
+        }
+
+        // Parse the fragment to get entry data.
+        let entries = deprecation::read_deprecation_fragments(&dir)?;
+        let entry = entries
+            .into_iter()
+            .find(|e| e.filename == filename)
+            .ok_or_else(|| anyhow::anyhow!("Could not parse {filename}"))?;
+
+        let version = if let Some(v) = self.version {
+            // Reject `--version 0.58.0-alpha` and friends: only release-shaped
+            // semver is valid here.
+            if !v.pre.is_empty() || !v.build.is_empty() {
+                bail!(
+                    "--version {v} has prerelease or build metadata; only plain X.Y.Z is allowed"
+                );
+            }
+            v
+        } else {
+            let latest = git::latest_release_version()?;
+            Version::new(latest.major, latest.minor + 1, 0)
+        };
+
+        if !deprecation::later_minor(&version, &entry.deprecated_since.0) {
+            bail!(
+                "removed_in ({version}) must be in a later minor release than deprecated_since ({}); \
+                 the deprecation policy requires at least one minor release between \
+                 the announcement and removal. \
+                 Check --version or the fragment's `deprecated_since` field.",
+                entry.deprecated_since
+            );
+        }
+
+        let enacted = deprecation::EnactedEntry {
+            what: entry.what.clone(),
+            deprecated_since: entry.deprecated_since.to_string(),
+            removed_in: version.to_string(),
+            description: entry.description.clone(),
+        };
+
+        // Append to enacted JSON.
+        deprecation::append_enacted(&repo_root, enacted)?;
+        println!("Recorded enacted entry for: {}", entry.what);
+
+        // Delete the deprecation.d fragment.
+        std::fs::remove_file(&path)?;
+        println!("Deleted {}", path.display());
+
+        // Regenerate deprecations.cue.
+        deprecation::sync_deprecations_cue(&repo_root)?;
+        println!(
+            "Updated {}",
+            repo_root.join(deprecation::DEPRECATIONS_JSON).display()
+        );
+
+        Ok(())
+    }
+}

vdev/src/commands/deprecation/generate.rs

@@ -0,0 +1,31 @@
+#![allow(clippy::print_stdout)]
+
+use anyhow::{Result, bail};
+
+use crate::utils::{deprecation, paths};
+
+/// Regenerate generated/deprecations.json from deprecation.d/ fragments
+#[derive(clap::Args, Debug)]
+#[command()]
+pub struct Cli {}
+
+impl Cli {
+    pub fn exec(self) -> Result<()> {
+        let repo_root = paths::find_repo_root()?;
+        let dir = repo_root.join(deprecation::DEPRECATION_DIR);
+        let json_path = repo_root.join(deprecation::DEPRECATIONS_JSON);
+        // If neither input exists, the fragment system isn't installed. With
+        // either present, we can still produce or refresh the JSON (an empty
+        // pending list is valid once all fragments have been enacted).
+        if !dir.is_dir() && !json_path.is_file() {
+            bail!(
+                "Neither {} nor {} found; the deprecation fragment system is not installed in this repo.",
+                dir.display(),
+                json_path.display()
+            );
+        }
+        deprecation::sync_deprecations_cue(&repo_root)?;
+        println!("Updated {}", json_path.display());
+        Ok(())
+    }
+}

vdev/src/commands/deprecation/mod.rs

@@ -0,0 +1,12 @@
+mod check;
+mod enact;
+mod generate;
+mod show;
+
+crate::cli_subcommands! {
+    "Manage and inspect deprecation notices..."
+    check,
+    enact,
+    generate,
+    show,
+}