feat(cli): add extension exclusion syntax and --baseline flag

New --extensions syntax supports `-` prefix for exclusions:
  --extensions all,-GL_EXT_direct_state_access
  --extensions GL_KHR_debug,-GL_ARB_debug_output

New --baseline flag excludes extensions fully promoted into the
specified API versions (all commands present in core via same-name
or alias). Format matches --api:
  --baseline gl:core=3.3,gles2=3.0

Both compose: explicit exclusions and baseline exclusions are
unioned into a single veto set applied after all selection passes
(explicit, dependency, promoted, predecessor).

Exclusion info flows into FeatureSet and the preamble comment now
shows what was excluded and why.

Signed-off-by: Steven Noonan <steven@uplinklabs.net>

Author: tycho

src/cli.rs

@@ -1,5 +1,7 @@
 //! Command-line interface definitions.
 
+use std::collections::HashSet;
+
 use anyhow::{Result, bail};
 use clap::{Args, Parser, Subcommand};
 
@@ -35,11 +37,22 @@ pub struct Cli {
     #[arg(long, required = true)]
     pub api: String,
 
-    /// Extension filter: path to a file (one per line) or a comma-separated
-    /// list of extension names. Omit to include all possible extensions.
+    /// Extension filter: path to a file (one per line), a comma-separated
+    /// list of extension names, or "all" (the default if omitted).  Prefix a
+    /// name with `-` to exclude it.  Examples:
+    ///   --extensions all,-GL_EXT_direct_state_access
+    ///   --extensions GL_KHR_debug,GL_ARB_sync
+    ///   --extensions ""              (include no extensions)
     #[arg(long)]
     pub extensions: Option<String>,
 
+    /// Baseline API versions.  Extensions that are fully promoted into these
+    /// versions or earlier are excluded — they're guaranteed to be present
+    /// in a context of at least the baseline version.  Format matches --api:
+    ///   --baseline gl:core=3.3,gles2=3.0
+    #[arg(long)]
+    pub baseline: Option<String>,
+
     /// Merge multiple APIs of the same spec into a single output file.
     /// Required when combining gl and gles2; behaviour is undefined otherwise.
     #[arg(long)]
@@ -86,31 +99,86 @@ impl Cli {
             .collect()
     }
 
-    /// Returns None (include all) or Some(list of extension names).
-    pub fn extension_filter(&self) -> Result<Option<Vec<String>>> {
+    /// Parse the --extensions argument into an `ExtensionFilter`.
+    pub fn extension_filter(&self) -> Result<ExtensionFilter> {
         let Some(ref spec) = self.extensions else {
-            return Ok(None);
+            return Ok(ExtensionFilter::all());
         };
 
-        if std::path::Path::new(spec).exists() {
+        // Read names from a file or inline comma-separated list.
+        let raw_names: Vec<String> = if std::path::Path::new(spec).exists() {
             let text = std::fs::read_to_string(spec)?;
-            let list = text
-                .lines()
+            text.lines()
                 .map(str::trim)
                 .filter(|l| !l.is_empty() && !l.starts_with('#'))
                 .map(str::to_string)
-                .collect();
-            return Ok(Some(list));
+                .collect()
+        } else {
+            spec.split(',')
+                .map(str::trim)
+                .filter(|s| !s.is_empty())
+                .map(str::to_string)
+                .collect()
+        };
+
+        // Split into includes and excludes based on `-` prefix.
+        let mut include_all = false;
+        let mut includes: Vec<String> = Vec::new();
+        let mut excludes: HashSet<String> = HashSet::new();
+
+        for name in raw_names {
+            if name.eq_ignore_ascii_case("all") {
+                include_all = true;
+            } else if let Some(stripped) = name.strip_prefix('-') {
+                if !stripped.is_empty() {
+                    excludes.insert(stripped.to_string());
+                }
+            } else {
+                includes.push(name);
+            }
         }
 
-        // Treat as an inline comma-separated list.
-        let list = spec
-            .split(',')
-            .map(str::trim)
-            .filter(|s| !s.is_empty())
-            .map(str::to_string)
-            .collect();
-        Ok(Some(list))
+        let include = if include_all { None } else { Some(includes) };
+        Ok(ExtensionFilter {
+            include,
+            exclude: excludes,
+        })
+    }
+
+    /// Parse the --baseline argument into API requests (same format as --api).
+    pub fn baseline_requests(&self) -> Result<Vec<ApiRequest>> {
+        let Some(ref spec) = self.baseline else {
+            return Ok(Vec::new());
+        };
+        spec.split(',')
+            .map(|s| ApiRequest::parse(s.trim()))
+            .collect()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// ExtensionFilter
+// ---------------------------------------------------------------------------
+
+/// Parsed extension filter from --extensions.
+///
+/// `include` is `None` for "all extensions" or `Some(list)` for an explicit set.
+/// `exclude` is always a set of names to unconditionally remove — applied as a
+/// final veto after all selection passes (explicit, dependency, promoted,
+/// predecessor, baseline).
+#[derive(Debug)]
+pub struct ExtensionFilter {
+    pub include: Option<Vec<String>>,
+    pub exclude: HashSet<String>,
+}
+
+impl ExtensionFilter {
+    /// No filter — include everything, exclude nothing.
+    pub fn all() -> Self {
+        Self {
+            include: None,
+            exclude: HashSet::new(),
+        }
     }
 }
 

src/preamble.rs

@@ -26,7 +26,10 @@ pub fn build_preamble(fs: &FeatureSet, command_line: &str) -> String {
     lines.push(format!(" *   {command_line}"));
 
     // ---- Extension provenance ----
-    if !fs.extensions.is_empty() {
+    if !fs.extensions.is_empty()
+        || !fs.excluded_explicit.is_empty()
+        || !fs.excluded_baseline.is_empty()
+    {
         lines.push(" *".to_string());
         lines.push(format!(" * {}", extension_summary(fs)));
 
@@ -47,6 +50,20 @@ pub fn build_preamble(fs: &FeatureSet, command_line: &str) -> String {
                 lines.push(format!(" *   {}: {}", label, names.join(", ")));
             }
         }
+
+        // List excluded extensions.
+        if !fs.excluded_baseline.is_empty() {
+            lines.push(format!(
+                " *   excluded by baseline: {} extensions",
+                fs.excluded_baseline.len()
+            ));
+        }
+        if !fs.excluded_explicit.is_empty() {
+            lines.push(format!(
+                " *   excluded explicitly: {}",
+                fs.excluded_explicit.join(", ")
+            ));
+        }
     }
 
     // ---- gloam license ----
@@ -81,11 +98,13 @@ pub fn build_preamble(fs: &FeatureSet, command_line: &str) -> String {
 /// Build a one-line summary of extension selection.
 ///
 /// Examples:
-///   "Extensions: all (451 total)"
-///   "Extensions: 5 explicit, 12 promoted, 3 predecessor (20 total)"
-///   "Extensions: 2 mandatory, 5 explicit (7 total)"
+///   "Extensions: all (451 included)"
+///   "Extensions: all, 68 excluded by baseline, 3 excluded explicitly (380 included)"
+///   "Extensions: 5 explicit, 12 promoted, 3 predecessor (20 included)"
 fn extension_summary(fs: &FeatureSet) -> String {
     let total = fs.extensions.len();
+    let n_baseline_excluded = fs.excluded_baseline.len();
+    let n_explicit_excluded = fs.excluded_explicit.len();
 
     let count = |reason: SelectionReason| -> usize {
         fs.extensions.iter().filter(|e| e.reason == reason).count()
@@ -98,29 +117,37 @@ fn extension_summary(fs: &FeatureSet) -> String {
     let n_promoted = count(SelectionReason::Promoted);
     let n_predecessor = count(SelectionReason::Predecessor);
 
+    let mut parts: Vec<String> = Vec::new();
+
     // If everything came from "all extensions" (no filter), use the short form.
     if n_all + n_mandatory == total {
-        return format!("Extensions: all ({total} total)");
+        parts.push("all".to_string());
+    } else {
+        if n_explicit > 0 {
+            parts.push(format!("{n_explicit} explicit"));
+        }
+        if n_mandatory > 0 {
+            parts.push(format!("{n_mandatory} mandatory"));
+        }
+        if n_dependency > 0 {
+            parts.push(format!("{n_dependency} dependency"));
+        }
+        if n_promoted > 0 {
+            parts.push(format!("{n_promoted} promoted"));
+        }
+        if n_predecessor > 0 {
+            parts.push(format!("{n_predecessor} predecessor"));
+        }
     }
 
-    let mut parts: Vec<String> = Vec::new();
-    if n_explicit > 0 {
-        parts.push(format!("{n_explicit} explicit"));
-    }
-    if n_mandatory > 0 {
-        parts.push(format!("{n_mandatory} mandatory"));
-    }
-    if n_dependency > 0 {
-        parts.push(format!("{n_dependency} dependency"));
+    if n_baseline_excluded > 0 {
+        parts.push(format!("{n_baseline_excluded} excluded by baseline"));
     }
-    if n_promoted > 0 {
-        parts.push(format!("{n_promoted} promoted"));
-    }
-    if n_predecessor > 0 {
-        parts.push(format!("{n_predecessor} predecessor"));
+    if n_explicit_excluded > 0 {
+        parts.push(format!("{n_explicit_excluded} excluded explicitly"));
     }
 
-    format!("Extensions: {} ({total} total)", parts.join(", "))
+    format!("Extensions: {} ({total} included)", parts.join(", "))
 }
 
 /// Returns true if this feature set includes ANGLE extension supplementals.
@@ -155,6 +182,8 @@ mod tests {
             ext_subset_indices: Default::default(),
             alias_pairs: vec![],
             required_headers: vec![],
+            excluded_explicit: vec![],
+            excluded_baseline: vec![],
         }
     }
 
@@ -255,7 +284,7 @@ mod tests {
             stub_ext("VK_KHR_swapchain", SelectionReason::AllExtensions),
             stub_ext("VK_KHR_surface", SelectionReason::AllExtensions),
         ];
-        assert_eq!(extension_summary(&fs), "Extensions: all (2 total)");
+        assert_eq!(extension_summary(&fs), "Extensions: all (2 included)");
     }
 
     #[test]
@@ -265,7 +294,7 @@ mod tests {
             stub_ext("WGL_ARB_extensions_string", SelectionReason::Mandatory),
             stub_ext("WGL_ARB_pixel_format", SelectionReason::AllExtensions),
         ];
-        assert_eq!(extension_summary(&fs), "Extensions: all (2 total)");
+        assert_eq!(extension_summary(&fs), "Extensions: all (2 included)");
     }
 
     #[test]
@@ -275,7 +304,10 @@ mod tests {
             stub_ext("VK_KHR_swapchain", SelectionReason::Explicit),
             stub_ext("VK_KHR_surface", SelectionReason::Explicit),
         ];
-        assert_eq!(extension_summary(&fs), "Extensions: 2 explicit (2 total)");
+        assert_eq!(
+            extension_summary(&fs),
+            "Extensions: 2 explicit (2 included)"
+        );
     }
 
     #[test]
@@ -292,7 +324,7 @@ mod tests {
         ];
         assert_eq!(
             extension_summary(&fs),
-            "Extensions: 1 explicit, 2 promoted, 1 predecessor (4 total)"
+            "Extensions: 1 explicit, 2 promoted, 1 predecessor (4 included)"
         );
     }
 
@@ -341,7 +373,7 @@ mod tests {
         ];
         assert_eq!(
             extension_summary(&fs),
-            "Extensions: 1 explicit, 1 dependency (2 total)"
+            "Extensions: 1 explicit, 1 dependency (2 included)"
         );
     }
 
@@ -351,4 +383,64 @@ mod tests {
         let p = build_preamble(&fs, "gloam --api vk=1.3 c");
         assert!(!p.contains("Extensions:"));
     }
+
+    // ---- Exclusion display ----
+
+    #[test]
+    fn summary_with_baseline_exclusions() {
+        let mut fs = stub_fs("gl");
+        fs.extensions = vec![stub_ext("GL_KHR_debug", SelectionReason::AllExtensions)];
+        fs.excluded_baseline = vec![
+            "GL_ARB_copy_buffer".to_string(),
+            "GL_ARB_multitexture".to_string(),
+        ];
+        assert_eq!(
+            extension_summary(&fs),
+            "Extensions: all, 2 excluded by baseline (1 included)"
+        );
+    }
+
+    #[test]
+    fn summary_with_explicit_exclusions() {
+        let mut fs = stub_fs("gl");
+        fs.extensions = vec![stub_ext("GL_KHR_debug", SelectionReason::AllExtensions)];
+        fs.excluded_explicit = vec!["GL_EXT_direct_state_access".to_string()];
+        assert_eq!(
+            extension_summary(&fs),
+            "Extensions: all, 1 excluded explicitly (1 included)"
+        );
+    }
+
+    #[test]
+    fn summary_with_both_exclusion_types() {
+        let mut fs = stub_fs("gl");
+        fs.extensions = vec![stub_ext("GL_KHR_debug", SelectionReason::AllExtensions)];
+        fs.excluded_baseline = vec!["GL_ARB_copy_buffer".to_string()];
+        fs.excluded_explicit = vec!["GL_EXT_direct_state_access".to_string()];
+        assert_eq!(
+            extension_summary(&fs),
+            "Extensions: all, 1 excluded by baseline, 1 excluded explicitly (1 included)"
+        );
+    }
+
+    #[test]
+    fn preamble_shows_baseline_exclusion_count() {
+        let mut fs = stub_fs("gl");
+        fs.extensions = vec![stub_ext("GL_KHR_debug", SelectionReason::AllExtensions)];
+        fs.excluded_baseline = vec![
+            "GL_ARB_copy_buffer".to_string(),
+            "GL_ARB_multitexture".to_string(),
+        ];
+        let p = build_preamble(&fs, "gloam --api gl:core c");
+        assert!(p.contains("excluded by baseline: 2 extensions"));
+    }
+
+    #[test]
+    fn preamble_shows_explicit_exclusion_names() {
+        let mut fs = stub_fs("gl");
+        fs.extensions = vec![stub_ext("GL_KHR_debug", SelectionReason::AllExtensions)];
+        fs.excluded_explicit = vec!["GL_EXT_direct_state_access".to_string()];
+        let p = build_preamble(&fs, "gloam --api gl:core c");
+        assert!(p.contains("excluded explicitly: GL_EXT_direct_state_access"));
+    }
 }