Split out parsing stuff as well, and test it

Cargo.lock

@@ -80,6 +80,7 @@ dependencies = [
  "edera-sprout-build",
  "edera-sprout-config",
  "edera-sprout-eficore",
+ "edera-sprout-parsing",
  "hex",
  "jaarg",
  "log",
@@ -113,6 +114,14 @@ dependencies = [
  "uefi-raw",
 ]
 
+[[package]]
+name = "edera-sprout-parsing"
+version = "0.0.28"
+dependencies = [
+ "hex",
+ "sha2",
+]
+
 [[package]]
 name = "generic-array"
 version = "0.14.7"

Cargo.toml

@@ -5,6 +5,7 @@ members = [
   "crates/config",
   "crates/eficore",
   "crates/bls",
+  "crates/parsing",
 ]
 resolver = "3"
 

crates/bls/Cargo.toml

@@ -1,6 +1,9 @@
+# This crate explicitly does not have uefi/uefi-raw dependencies,
+# so that the contents can be unit-testable on non-UEFI target hosts.
+# Do not add uefi or uefi-raw as dependencies.
 [package]
 name = "edera-sprout-bls"
-description = "Sprout BLS Utilities"
+description = "Sprout BLS Utilities (UEFI-free)"
 license.workspace = true
 version.workspace = true
 homepage.workspace = true

crates/bls/src/lib.rs

@@ -213,11 +213,6 @@ pub fn sort_bls(a_bls: &BlsEntry, a_name: &str, b_bls: &BlsEntry, b_name: &str)
     }
 }
 
-// ---------------------------------------------------------------------------
-// BLS version comparison
-// Reference: https://uapi-group.org/specifications/specs/version_format_specification/
-// ---------------------------------------------------------------------------
-
 /// Handles single character advancement and comparison.
 macro_rules! handle_single_char {
     ($ca: expr, $cb:expr, $a_chars:expr, $b_chars:expr, $c:expr) => {

crates/boot/Cargo.toml

@@ -12,6 +12,7 @@ anyhow.workspace = true
 edera-sprout-config.path = "../config"
 edera-sprout-eficore.path = "../eficore"
 edera-sprout-bls.path = "../bls"
+edera-sprout-parsing.path = "../parsing"
 hex.workspace = true
 jaarg.workspace = true
 sha2.workspace = true

crates/boot/src/actions/chainload.rs

@@ -1,10 +1,10 @@
 use crate::context::SproutContext;
 use crate::phases::before_handoff;
-use crate::utils;
 use alloc::boxed::Box;
 use alloc::rc::Rc;
 use anyhow::{Context, Result, bail};
 use edera_sprout_config::actions::chainload::ChainloadConfiguration;
+use edera_sprout_parsing::{combine_options, empty_is_none};
 use eficore::bootloader_interface::BootloaderInterface;
 use eficore::loader::source::ImageSource;
 use eficore::loader::{ImageLoadRequest, ImageLoader};
@@ -38,7 +38,7 @@ pub fn chainload(context: Rc<SproutContext>, configuration: &ChainloadConfigurat
             .context("unable to open loaded image protocol")?;
 
     // Stamp and combine the options to pass to the image.
-    let options = utils::combine_options(context.stamp_iter(configuration.options.iter()));
+    let options = combine_options(context.stamp_iter(configuration.options.iter()));
 
     // Pass the load options to the image.
     // If no options are provided, the resulting string will be empty.
@@ -68,7 +68,7 @@ pub fn chainload(context: Rc<SproutContext>, configuration: &ChainloadConfigurat
         .as_ref()
         .map(|item| context.stamp(item));
     // The initrd can be None or empty, so we need to collapse that into a single Option.
-    let initrd = utils::empty_is_none(initrd);
+    let initrd = empty_is_none(initrd);
 
     // If an initrd is provided, register it with the EFI stack.
     let mut initrd_handle = None;

crates/boot/src/actions/edera.rs

@@ -1,14 +1,11 @@
-use crate::{
+use crate::{actions, context::SproutContext};
-    actions,
-    context::SproutContext,
-    utils::{self},
-};
 use alloc::rc::Rc;
-use alloc::string::{String, ToString};
+use alloc::string::String;
 use alloc::{format, vec};
 use anyhow::{Context, Result};
 use edera_sprout_config::actions::chainload::ChainloadConfiguration;
 use edera_sprout_config::actions::edera::EderaConfiguration;
+use edera_sprout_parsing::{build_xen_config, combine_options, empty_is_none};
 use eficore::media_loader::{
     MediaLoaderHandle,
     constants::xen::{
@@ -18,31 +15,10 @@ use eficore::media_loader::{
 use uefi::Guid;
 
 /// Builds a configuration string for the Xen EFI stub using the specified `configuration`.
-fn build_xen_config(context: Rc<SproutContext>, configuration: &EderaConfiguration) -> String {
+fn make_xen_config(context: Rc<SproutContext>, configuration: &EderaConfiguration) -> String {
-    // Stamp xen options and combine them.
+    let xen_options = combine_options(context.stamp_iter(configuration.xen_options.iter()));
-    let xen_options = utils::combine_options(context.stamp_iter(configuration.xen_options.iter()));
+    let kernel_options = combine_options(context.stamp_iter(configuration.kernel_options.iter()));
-
+    build_xen_config(&xen_options, &kernel_options)
-    // Stamp kernel options and combine them.
-    let kernel_options =
-        utils::combine_options(context.stamp_iter(configuration.kernel_options.iter()));
-
-    // xen config file format is ini-like
-    [
-        // global section
-        "[global]".to_string(),
-        // default configuration section
-        "default=sprout".to_string(),
-        // configuration section for sprout
-        "[sprout]".to_string(),
-        // xen options
-        format!("options={}", xen_options),
-        // kernel options, stub replaces the kernel path
-        // the kernel is provided via media loader
-        format!("kernel=stub {}", kernel_options),
-        // required or else the last line will be ignored
-        "".to_string(),
-    ]
-    .join("\n")
 }
 
 /// Register a media loader for some `text` with the vendor `guid`.
@@ -80,7 +56,7 @@ fn register_media_loader_file(
 /// `configuration` and `context`. This action uses Edera-specific Xen EFI stub functionality.
 pub fn edera(context: Rc<SproutContext>, configuration: &EderaConfiguration) -> Result<()> {
     // Build the Xen config file content for this configuration.
-    let config = build_xen_config(context.clone(), configuration);
+    let config = make_xen_config(context.clone(), configuration);
 
     // Register the media loader for the config.
     let config = register_media_loader_text(XEN_EFI_CONFIG_MEDIA_GUID, "config", config)
@@ -99,7 +75,7 @@ pub fn edera(context: Rc<SproutContext>, configuration: &EderaConfiguration) ->
     let mut media_loaders = vec![config, kernel];
 
     // Register the initrd if it is provided.
-    if let Some(initrd) = utils::empty_is_none(configuration.initrd.as_ref()) {
+    if let Some(initrd) = empty_is_none(configuration.initrd.as_ref()) {
         let initrd =
             register_media_loader_file(&context, XEN_EFI_RAMDISK_MEDIA_GUID, "initrd", initrd)
                 .context("unable to register initrd media loader")?;

crates/boot/src/autoconfigure/bls.rs

@@ -1,4 +1,3 @@
-use crate::utils;
 use alloc::string::ToString;
 use alloc::{format, vec};
 use anyhow::{Context, Result};
@@ -8,6 +7,7 @@ use edera_sprout_config::actions::chainload::ChainloadConfiguration;
 use edera_sprout_config::entries::EntryDeclaration;
 use edera_sprout_config::generators::GeneratorDeclaration;
 use edera_sprout_config::generators::bls::BlsConfiguration;
+use edera_sprout_parsing::unique_hash;
 use uefi::cstr16;
 use uefi::fs::{FileSystem, Path};
 use uefi::proto::device_path::DevicePath;
@@ -37,7 +37,7 @@ pub fn scan(
     root.push('/');
 
     // Generate a unique hash of the root path.
-    let root_unique_hash = utils::unique_hash(&root);
+    let root_unique_hash = unique_hash(&root);
 
     // Whether we have a loader.conf file.
     let has_loader_conf = filesystem

crates/boot/src/autoconfigure/linux.rs

@@ -1,4 +1,3 @@
-use crate::utils;
 use alloc::collections::BTreeMap;
 use alloc::string::{String, ToString};
 use alloc::vec::Vec;
@@ -10,6 +9,10 @@ use edera_sprout_config::actions::chainload::ChainloadConfiguration;
 use edera_sprout_config::entries::EntryDeclaration;
 use edera_sprout_config::generators::GeneratorDeclaration;
 use edera_sprout_config::generators::list::ListConfiguration;
+use edera_sprout_parsing::{
+    LINUX_INITRAMFS_PREFIXES, LINUX_KERNEL_PREFIXES, initramfs_candidates, match_kernel_prefix,
+    unique_hash,
+};
 use uefi::CString16;
 use uefi::fs::{FileSystem, Path, PathBuf};
 use uefi::proto::device_path::DevicePath;
@@ -23,11 +26,6 @@ const LINUX_CHAINLOAD_ACTION_PREFIX: &str = "linux-chainload-";
 /// The empty string represents the root of the filesystem.
 const SCAN_LOCATIONS: &[&str] = &["\\boot", "\\"];
 
-/// Prefixes of kernel files to scan for.
-const KERNEL_PREFIXES: &[&str] = &["vmlinuz", "Image"];
-
-/// Prefixes of initramfs files to match to.
-const INITRAMFS_PREFIXES: &[&str] = &["initramfs", "initrd", "initrd.img"];
 
 /// This is really silly, but if what we are booting is the Canonical stubble stub,
 /// there is a chance it will assert that the load options are non-empty.
@@ -108,9 +106,7 @@ fn scan_directory(filesystem: &mut FileSystem, path: &str) -> Result<Vec<KernelP
 
         // Find a kernel prefix that matches, if any.
         // This is case-insensitive to ensure we pick up all possibilities.
-        let Some(prefix) = KERNEL_PREFIXES.iter().find(|prefix| {
+        let Some(prefix) = match_kernel_prefix(&name_for_match, LINUX_KERNEL_PREFIXES) else {
-            name_for_match == **prefix || name_for_match.starts_with(&format!("{}-", prefix))
-        }) else {
             // Skip over anything that doesn't match a kernel prefix.
             continue;
         };
@@ -118,15 +114,14 @@ fn scan_directory(filesystem: &mut FileSystem, path: &str) -> Result<Vec<KernelP
         // Acquire the suffix of the name, this will be used to match an initramfs.
         let suffix = &name[prefix.len()..];
 
-        // Find a matching initramfs, if any.
+        // Find a matching initramfs by trying each candidate name, if any.
-        let mut initramfs_prefix_iter = INITRAMFS_PREFIXES.iter();
+        let mut candidates = initramfs_candidates(suffix, LINUX_INITRAMFS_PREFIXES);
         let matched_initramfs_path = loop {
-            let Some(prefix) = initramfs_prefix_iter.next() else {
+            let Some(candidate) = candidates.next() else {
                 break None;
             };
             // Construct an initramfs path.
-            let initramfs = format!("{}{}", prefix, suffix);
+            let initramfs = CString16::try_from(candidate.as_str())
-            let initramfs = CString16::try_from(initramfs.as_str())
                 .context("unable to convert initramfs name to CString16")?;
             let mut initramfs_path = path_for_join.clone();
             initramfs_path.push(Path::new(&initramfs));
@@ -171,7 +166,7 @@ pub fn scan(
     root.push('/');
 
     // Generate a unique hash of the root path.
-    let root_unique_hash = utils::unique_hash(&root);
+    let root_unique_hash = unique_hash(&root);
 
     // Scan all locations for kernel pairs, adding them to the list.
     for location in SCAN_LOCATIONS {

crates/boot/src/autoconfigure/windows.rs

@@ -1,4 +1,3 @@
-use crate::utils;
 use alloc::string::ToString;
 use alloc::{format, vec};
 use anyhow::{Context, Result};
@@ -6,6 +5,7 @@ use edera_sprout_config::RootConfiguration;
 use edera_sprout_config::actions::ActionDeclaration;
 use edera_sprout_config::actions::chainload::ChainloadConfiguration;
 use edera_sprout_config::entries::EntryDeclaration;
+use edera_sprout_parsing::unique_hash;
 use uefi::CString16;
 use uefi::fs::{FileSystem, Path};
 use uefi::proto::device_path::DevicePath;
@@ -45,7 +45,7 @@ pub fn scan(
     root.push('/');
 
     // Generate a unique hash of the root path.
-    let root_unique_hash = utils::unique_hash(&root);
+    let root_unique_hash = unique_hash(&root);
 
     // Generate a unique name for the Windows chainload action.
     let chainload_action_name = format!("{}{}", WINDOWS_CHAINLOAD_ACTION_PREFIX, root_unique_hash,);

crates/boot/src/context.rs

@@ -1,13 +1,13 @@
 use crate::options::SproutOptions;
 use alloc::boxed::Box;
 use alloc::collections::{BTreeMap, BTreeSet};
-use alloc::format;
 use alloc::rc::Rc;
 use alloc::string::{String, ToString};
 use alloc::vec::Vec;
 use anyhow::anyhow;
 use anyhow::{Result, bail};
 use edera_sprout_config::actions::ActionDeclaration;
+use edera_sprout_parsing::stamp_values;
 use eficore::platform::timer::PlatformTimer;
 use uefi::proto::device_path::DevicePath;
 
@@ -242,44 +242,3 @@ impl SproutContext {
         Rc::into_inner(self)
     }
 }
-
-/// Stamps the `text` value with the specified `values` map. The returned value indicates
-/// whether the `text` has been changed and the value that was stamped and changed.
-///
-/// Stamping works like this:
-/// - Start with the input text.
-/// - Sort all the keys in reverse length order (longest keys first)
-/// - For each key, if the key is not empty, replace $KEY in the text.
-/// - Each follow-up iteration acts upon the last iterations result.
-/// - We keep track if the text changes during the replacement.
-/// - We return both whether the text changed during any iteration and the final result.
-fn stamp_values(values: &BTreeMap<String, String>, text: impl AsRef<str>) -> (bool, String) {
-    let mut result = text.as_ref().to_string();
-    let mut did_change = false;
-
-    // Sort the keys by length. This is to ensure that we stamp the longest keys first.
-    // If we did not do this, "$abc" could be stamped by "$a" into an invalid result.
-    let mut keys = values.keys().collect::<Vec<_>>();
-
-    // Sort by key length, reversed. This results in the longest keys appearing first.
-    keys.sort_by_key(|key| core::cmp::Reverse(key.len()));
-
-    for key in keys {
-        // Empty keys are not supported.
-        if key.is_empty() {
-            continue;
-        }
-
-        // We can fetch the value from the map. It is verifiable that the key exists.
-        let Some(value) = values.get(key) else {
-            unreachable!("keys iterated over is collected on a map that cannot be modified");
-        };
-
-        let next_result = result.replace(&format!("${key}"), value);
-        if result != next_result {
-            did_change = true;
-        }
-        result = next_result;
-    }
-    (did_change, result)
-}

crates/boot/src/generators/matrix.rs

@@ -1,46 +1,12 @@
 use crate::context::SproutContext;
 use crate::entries::BootableEntry;
 use crate::generators::list;
-use alloc::collections::BTreeMap;
 use alloc::rc::Rc;
-use alloc::string::String;
-use alloc::vec;
 use alloc::vec::Vec;
 use anyhow::Result;
 use edera_sprout_config::generators::list::ListConfiguration;
 use edera_sprout_config::generators::matrix::MatrixConfiguration;
-
+use edera_sprout_parsing::build_matrix;
-/// Builds out multiple generations of `input` based on a matrix style.
-/// For example, if input is: {"x": ["a", "b"], "y": ["c", "d"]}
-/// It will produce:
-/// x: a, y: c
-/// x: a, y: d
-/// x: b, y: c
-/// x: b, y: d
-fn build_matrix(input: &BTreeMap<String, Vec<String>>) -> Vec<BTreeMap<String, String>> {
-    // Convert the input into a vector of tuples.
-    let items: Vec<(String, Vec<String>)> = input.clone().into_iter().collect();
-
-    // The result is a vector of maps.
-    let mut result: Vec<BTreeMap<String, String>> = vec![BTreeMap::new()];
-
-    for (key, values) in items {
-        let mut new_result = Vec::new();
-
-        // Produce all the combinations of the input values.
-        for combination in &result {
-            for value in &values {
-                let mut new_combination = combination.clone();
-                new_combination.insert(key.clone(), value.clone());
-                new_result.push(new_combination);
-            }
-        }
-
-        result = new_result;
-    }
-
-    result.into_iter().filter(|item| !item.is_empty()).collect()
-}
 
 /// Generates a set of entries using the specified `matrix` configuration in the `context`.
 pub fn generate(

crates/boot/src/main.rs

@@ -61,9 +61,6 @@ pub mod phases;
 /// sbat: Secure Boot Attestation section.
 pub mod sbat;
 
-/// utils: Utility functions that are used by other parts of Sprout.
-pub mod utils;
-
 /// The delay to wait for when an error occurs in Sprout.
 const DELAY_ON_ERROR: Duration = Duration::from_secs(10);
 

crates/boot/src/utils.rs

@@ -1,23 +0,0 @@
-use alloc::string::{String, ToString};
-use alloc::vec::Vec;
-use sha2::{Digest, Sha256};
-
-/// Combine a sequence of strings into a single string, separated by spaces, ignoring empty strings.
-pub fn combine_options<T: AsRef<str>>(options: impl Iterator<Item = T>) -> String {
-    options
-        .flat_map(|item| empty_is_none(Some(item)))
-        .map(|item| item.as_ref().to_string())
-        .collect::<Vec<_>>()
-        .join(" ")
-}
-
-/// Produce a unique hash for the input.
-/// This uses SHA-256, which is unique enough but relatively short.
-pub fn unique_hash(input: &str) -> String {
-    hex::encode(Sha256::digest(input.as_bytes()))
-}
-
-/// Filter a string-like Option `input` such that an empty string is [None].
-pub fn empty_is_none<T: AsRef<str>>(input: Option<T>) -> Option<T> {
-    input.filter(|input| !input.as_ref().is_empty())
-}

crates/parsing/Cargo.toml

@@ -0,0 +1,19 @@
+# This crate explicitly does not have uefi/uefi-raw dependencies,
+# so that the contents can be unit-testable on non-UEFI target hosts.
+# Do not add uefi or uefi-raw as dependencies.
+[package]
+name = "edera-sprout-parsing"
+description = "Sprout Parsing Utilities (UEFI-free)"
+license.workspace = true
+version.workspace = true
+homepage.workspace = true
+repository.workspace = true
+edition.workspace = true
+
+[dependencies]
+hex.workspace = true
+sha2.workspace = true
+
+[lib]
+name = "edera_sprout_parsing"
+path = "src/lib.rs"

crates/parsing/src/lib.rs

@@ -0,0 +1,405 @@
+#![no_std]
+extern crate alloc;
+
+use alloc::collections::BTreeMap;
+use alloc::format;
+use alloc::string::{String, ToString};
+use alloc::vec::Vec;
+use core::cmp::Reverse;
+use sha2::{Digest, Sha256};
+
+/// Stamps the `text` value with the specified `values` map. The returned value indicates
+/// whether the `text` has been changed and the value that was stamped and changed.
+///
+/// Stamping works like this:
+/// - Start with the input text.
+/// - Sort all the keys in reverse length order (longest keys first)
+/// - For each key, if the key is not empty, replace $KEY in the text.
+/// - Each follow-up iteration acts upon the last iterations result.
+/// - We keep track if the text changes during the replacement.
+/// - We return both whether the text changed during any iteration and the final result.
+pub fn stamp_values(values: &BTreeMap<String, String>, text: impl AsRef<str>) -> (bool, String) {
+    let mut result = text.as_ref().to_string();
+    let mut did_change = false;
+
+    // Sort the keys by length. This is to ensure that we stamp the longest keys first.
+    // If we did not do this, "$abc" could be stamped by "$a" into an invalid result.
+    let mut keys = values.keys().collect::<Vec<_>>();
+
+    // Sort by key length, reversed. This results in the longest keys appearing first.
+    keys.sort_by_key(|key| Reverse(key.len()));
+
+    for key in keys {
+        // Empty keys are not supported.
+        if key.is_empty() {
+            continue;
+        }
+
+        // We can fetch the value from the map. It is verifiable that the key exists.
+        let Some(value) = values.get(key) else {
+            unreachable!("keys iterated over is collected on a map that cannot be modified");
+        };
+
+        let next_result = result.replace(&format!("${key}"), value);
+        if result != next_result {
+            did_change = true;
+        }
+        result = next_result;
+    }
+    (did_change, result)
+}
+
+/// Builds out multiple generations of `input` based on a matrix style.
+/// For example, if input is: {"x": ["a", "b"], "y": ["c", "d"]}
+/// It will produce:
+/// x: a, y: c
+/// x: a, y: d
+/// x: b, y: c
+/// x: b, y: d
+pub fn build_matrix(input: &BTreeMap<String, Vec<String>>) -> Vec<BTreeMap<String, String>> {
+    // Convert the input into a vector of tuples.
+    let items: Vec<(String, Vec<String>)> = input.clone().into_iter().collect();
+
+    // The result is a vector of maps.
+    let mut result: Vec<BTreeMap<String, String>> = alloc::vec![BTreeMap::new()];
+
+    for (key, values) in items {
+        let mut new_result = Vec::new();
+
+        // Produce all the combinations of the input values.
+        for combination in &result {
+            for value in &values {
+                let mut new_combination = combination.clone();
+                new_combination.insert(key.clone(), value.clone());
+                new_result.push(new_combination);
+            }
+        }
+
+        result = new_result;
+    }
+
+    result.into_iter().filter(|item| !item.is_empty()).collect()
+}
+
+/// Combine a sequence of strings into a single string, separated by spaces, ignoring empty strings.
+pub fn combine_options<T: AsRef<str>>(options: impl Iterator<Item = T>) -> String {
+    options
+        .flat_map(|item| empty_is_none(Some(item)))
+        .map(|item| item.as_ref().to_string())
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+/// Produce a unique hash for the input.
+/// This uses SHA-256, which is unique enough but relatively short.
+pub fn unique_hash(input: &str) -> String {
+    hex::encode(Sha256::digest(input.as_bytes()))
+}
+
+/// Filter a string-like Option `input` such that an empty string is [None].
+pub fn empty_is_none<T: AsRef<str>>(input: Option<T>) -> Option<T> {
+    input.filter(|input| !input.as_ref().is_empty())
+}
+
+/// Build a Xen EFI stub configuration file from pre-stamped `xen_options` and `kernel_options`.
+/// The returned string is in the Xen ini-like config file format.
+pub fn build_xen_config(xen_options: &str, kernel_options: &str) -> String {
+    [
+        // global section
+        "[global]",
+        // default configuration section
+        "default=sprout",
+        // configuration section for sprout
+        "[sprout]",
+        // xen options
+        &format!("options={}", xen_options),
+        // kernel options, stub replaces the kernel path
+        // the kernel is provided via media loader
+        &format!("kernel=stub {}", kernel_options),
+        // required or else the last line will be ignored
+        "",
+    ]
+    .join("\n")
+}
+
+/// Filename prefixes used to identify Linux kernel images.
+pub const LINUX_KERNEL_PREFIXES: &[&str] = &["vmlinuz", "Image"];
+
+/// Filename prefixes used to identify initramfs images paired with a kernel.
+pub const LINUX_INITRAMFS_PREFIXES: &[&str] = &["initramfs", "initrd", "initrd.img"];
+
+/// Check whether `name` (already lowercased) matches one of the `kernel_prefixes`,
+/// either exactly or as a dash-separated prefix (e.g. `"vmlinuz-6.1"`).
+/// Returns the matched prefix string if found.
+pub fn match_kernel_prefix<'a>(name: &str, kernel_prefixes: &[&'a str]) -> Option<&'a str> {
+    kernel_prefixes
+        .iter()
+        .find(|prefix| name == **prefix || name.starts_with(&format!("{}-", prefix)))
+        .copied()
+}
+
+/// Generate initramfs candidate filenames by combining each entry of `initramfs_prefixes`
+/// with `suffix`. The caller is expected to check which candidates actually exist.
+pub fn initramfs_candidates<'a>(
+    suffix: &'a str,
+    initramfs_prefixes: &'a [&'a str],
+) -> impl Iterator<Item = String> + 'a {
+    initramfs_prefixes
+        .iter()
+        .map(move |prefix| format!("{}{}", prefix, suffix))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn map(pairs: &[(&str, &str)]) -> BTreeMap<String, String> {
+        pairs
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_string()))
+            .collect()
+    }
+
+    #[test]
+    fn stamp_replaces_known_key() {
+        let values = map(&[("name", "world")]);
+        let (changed, result) = stamp_values(&values, "hello $name");
+        assert!(changed);
+        assert_eq!(result, "hello world");
+    }
+
+    #[test]
+    fn stamp_no_match_returns_unchanged() {
+        let values = map(&[("name", "world")]);
+        let (changed, result) = stamp_values(&values, "hello there");
+        assert!(!changed);
+        assert_eq!(result, "hello there");
+    }
+
+    #[test]
+    fn stamp_longer_key_takes_precedence_over_shorter() {
+        // Without longest-first ordering, "$ab" would be partially matched by "$a"
+        let values = map(&[("a", "WRONG"), ("ab", "RIGHT")]);
+        let (changed, result) = stamp_values(&values, "$ab");
+        assert!(changed);
+        assert_eq!(result, "RIGHT");
+    }
+
+    #[test]
+    fn stamp_empty_key_is_skipped() {
+        let values = map(&[("", "should-not-appear"), ("x", "val")]);
+        let (_, result) = stamp_values(&values, "$x");
+        assert_eq!(result, "val");
+        assert!(!result.contains("should-not-appear"));
+    }
+
+    #[test]
+    fn stamp_multiple_keys_replaced() {
+        let values = map(&[("a", "foo"), ("b", "bar")]);
+        let (changed, result) = stamp_values(&values, "$a and $b");
+        assert!(changed);
+        assert_eq!(result, "foo and bar");
+    }
+
+    #[test]
+    fn stamp_empty_text_returns_empty() {
+        let values = map(&[("a", "foo")]);
+        let (changed, result) = stamp_values(&values, "");
+        assert!(!changed);
+        assert_eq!(result, "");
+    }
+
+    #[test]
+    fn stamp_empty_map_returns_unchanged() {
+        let values = map(&[]);
+        let (changed, result) = stamp_values(&values, "hello $name");
+        assert!(!changed);
+        assert_eq!(result, "hello $name");
+    }
+
+    fn matrix_map(pairs: &[(&str, &[&str])]) -> BTreeMap<String, Vec<String>> {
+        pairs
+            .iter()
+            .map(|(k, vs)| (k.to_string(), vs.iter().map(|v| v.to_string()).collect()))
+            .collect()
+    }
+
+    #[test]
+    fn matrix_single_key_produces_one_entry_per_value() {
+        let input = matrix_map(&[("x", &["a", "b", "c"])]);
+        let result = build_matrix(&input);
+        assert_eq!(result.len(), 3);
+    }
+
+    #[test]
+    fn matrix_two_keys_produces_cartesian_product() {
+        let input = matrix_map(&[("x", &["a", "b"]), ("y", &["c", "d"])]);
+        let result = build_matrix(&input);
+        assert_eq!(result.len(), 4);
+        // Every combination of x and y should be present.
+        for x in &["a", "b"] {
+            for y in &["c", "d"] {
+                assert!(
+                    result
+                        .iter()
+                        .any(|m| m.get("x").map(|s| s.as_str()) == Some(x)
+                            && m.get("y").map(|s| s.as_str()) == Some(y))
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn matrix_empty_input_produces_no_entries() {
+        let input = matrix_map(&[]);
+        let result = build_matrix(&input);
+        assert!(result.is_empty());
+    }
+
+    #[test]
+    fn matrix_key_with_empty_values_produces_no_entries() {
+        let input = matrix_map(&[("x", &[])]);
+        let result = build_matrix(&input);
+        assert!(result.is_empty());
+    }
+
+    #[test]
+    fn combine_options_joins_with_space() {
+        let result = combine_options(["a", "b", "c"].iter().copied());
+        assert_eq!(result, "a b c");
+    }
+
+    #[test]
+    fn combine_options_skips_empty_strings() {
+        let result = combine_options(["a", "", "b"].iter().copied());
+        assert_eq!(result, "a b");
+    }
+
+    #[test]
+    fn combine_options_all_empty_returns_empty() {
+        let result = combine_options(["", ""].iter().copied());
+        assert_eq!(result, "");
+    }
+
+    #[test]
+    fn combine_options_empty_iterator_returns_empty() {
+        let result = combine_options(core::iter::empty::<&str>());
+        assert_eq!(result, "");
+    }
+
+    #[test]
+    fn empty_is_none_returns_none_for_empty_string() {
+        assert!(empty_is_none(Some("")).is_none());
+    }
+
+    #[test]
+    fn empty_is_none_returns_some_for_nonempty_string() {
+        assert_eq!(empty_is_none(Some("x")), Some("x"));
+    }
+
+    #[test]
+    fn empty_is_none_passthrough_on_none() {
+        assert!(empty_is_none(None::<&str>).is_none());
+    }
+
+    #[test]
+    fn unique_hash_is_deterministic() {
+        assert_eq!(unique_hash("hello"), unique_hash("hello"));
+    }
+
+    #[test]
+    fn unique_hash_differs_for_different_inputs() {
+        assert_ne!(unique_hash("hello"), unique_hash("world"));
+    }
+
+    #[test]
+    fn unique_hash_empty_string() {
+        // SHA-256 of "" is well-known; just check it produces a non-empty hex string.
+        let h = unique_hash("");
+        assert!(!h.is_empty());
+        assert!(h.chars().all(|c| c.is_ascii_hexdigit()));
+    }
+
+    #[test]
+    fn xen_config_contains_global_and_sprout_sections() {
+        let config = build_xen_config("", "");
+        assert!(config.contains("[global]"));
+        assert!(config.contains("[sprout]"));
+        assert!(config.contains("default=sprout"));
+    }
+
+    #[test]
+    fn xen_config_embeds_xen_options() {
+        let config = build_xen_config("--no-real-mode --iommu=no", "");
+        assert!(config.contains("options=--no-real-mode --iommu=no"));
+    }
+
+    #[test]
+    fn xen_config_embeds_kernel_options() {
+        let config = build_xen_config("", "quiet splash");
+        assert!(config.contains("kernel=stub quiet splash"));
+    }
+
+    #[test]
+    fn xen_config_ends_with_newline() {
+        // Required or the last line will be ignored by the Xen config parser.
+        let config = build_xen_config("", "");
+        assert!(config.ends_with('\n'));
+    }
+
+
+    #[test]
+    fn kernel_prefix_exact_match() {
+        assert_eq!(
+            match_kernel_prefix("vmlinuz", LINUX_KERNEL_PREFIXES),
+            Some("vmlinuz")
+        );
+    }
+
+    #[test]
+    fn kernel_prefix_dash_suffix_match() {
+        assert_eq!(
+            match_kernel_prefix("vmlinuz-6.1.0", LINUX_KERNEL_PREFIXES),
+            Some("vmlinuz")
+        );
+    }
+
+    #[test]
+    fn kernel_prefix_case_sensitive_no_match() {
+        // match_kernel_prefix expects the caller to lowercase first; uppercase input won't match.
+        assert!(match_kernel_prefix("VMLINUZ-6.1", LINUX_KERNEL_PREFIXES).is_none());
+    }
+
+    #[test]
+    fn kernel_prefix_no_match() {
+        assert!(match_kernel_prefix("initramfs-6.1", LINUX_KERNEL_PREFIXES).is_none());
+    }
+
+    #[test]
+    fn kernel_prefix_partial_no_match() {
+        // "vmlinuz6.1" has no dash separator — should not match.
+        assert!(match_kernel_prefix("vmlinuz6.1", LINUX_KERNEL_PREFIXES).is_none());
+    }
+
+
+    #[test]
+    fn initramfs_candidates_with_suffix() {
+        let candidates: Vec<_> = initramfs_candidates("-6.1.0", LINUX_INITRAMFS_PREFIXES).collect();
+        assert_eq!(
+            candidates,
+            &["initramfs-6.1.0", "initrd-6.1.0", "initrd.img-6.1.0"]
+        );
+    }
+
+    #[test]
+    fn initramfs_candidates_empty_suffix() {
+        let candidates: Vec<_> = initramfs_candidates("", LINUX_INITRAMFS_PREFIXES).collect();
+        assert_eq!(candidates, &["initramfs", "initrd", "initrd.img"]);
+    }
+
+    #[test]
+    fn initramfs_candidates_empty_prefixes() {
+        let candidates: Vec<_> = initramfs_candidates("-6.1.0", &[]).collect();
+        assert!(candidates.is_empty());
+    }
+}