zlayer_builder/zimage/

parser.rs

//! `ZImagefile` parser — YAML deserialization + semantic validation.
//!
//! The entry point is [`parse_zimagefile`], which takes raw YAML content,
//! deserializes it into a [`ZImage`], and then runs validation rules that
//! cannot be expressed through serde alone.

use super::types::{ZImage, ZStep, ZWasmConfig};
use crate::error::{BuildError, Result};

/// Parse and validate a `ZImagefile` from its YAML content.
///
/// This performs two phases:
/// 1. **Deserialization** — YAML string into [`ZImage`] via `serde_yaml`.
/// 2. **Validation** — semantic rules that serde annotations cannot enforce.
///
/// # Errors
///
/// Returns [`BuildError::ZImagefileParse`] for malformed YAML and
/// [`BuildError::ZImagefileValidation`] for semantic rule violations.
pub fn parse_zimagefile(content: &str) -> Result<ZImage> {
    // Phase 1: Deserialize YAML into the ZImage struct.
    let mut image: ZImage =
        serde_yaml::from_str(content).map_err(|e| BuildError::zimagefile_parse(e.to_string()))?;

    // `runtime: wasm` is a shorthand that routes to WASM build mode. Rewrite
    // it to an explicit `wasm:` section with defaults so the rest of the
    // pipeline (validation + builder dispatch) treats it uniformly as WASM
    // mode. Keeps `runtime: wasm` distinct from language runtime templates
    // which expand into Dockerfiles.
    if image
        .runtime
        .as_deref()
        .is_some_and(|r| r.eq_ignore_ascii_case("wasm") || r.eq_ignore_ascii_case("webassembly"))
        && image.wasm.is_none()
    {
        image.runtime = None;
        image.wasm = Some(default_wasm_config());
    }

    // Stamp the resolved runtime isolation into image labels so it flows into
    // the OCI config Labels via the existing label emitters. `Auto` (and an
    // absent `isolation:`) carry no label. An explicit user-provided label is
    // never overwritten.
    if let Some(ri) = image.resolve_isolation() {
        if let Some(v) = ri.label_value() {
            image
                .labels
                .entry("com.zlayer.isolation".to_string())
                .or_insert_with(|| v.to_string());
        }
    }

    // Phase 2: Semantic validation.
    validate_version(&image)?;
    validate_mode_exclusivity(&image)?;
    validate_steps(&image)?;
    validate_wasm(&image)?;

    Ok(image)
}

/// Construct a default [`ZWasmConfig`] by routing through serde so the
/// `#[serde(default = ...)]` attributes on [`ZWasmConfig`] populate fields
/// like `target` and `opt_level`. This avoids needing a `Default` impl on
/// [`ZWasmConfig`] just for this path.
fn default_wasm_config() -> ZWasmConfig {
    serde_yaml::from_str::<ZWasmConfig>("{}")
        .expect("empty ZWasmConfig must deserialize from '{}' via serde defaults")
}

// ---------------------------------------------------------------------------
// Version validation
// ---------------------------------------------------------------------------

/// The version field, if present, must be `"1"`.
fn validate_version(image: &ZImage) -> Result<()> {
    if let Some(ref v) = image.version {
        if v != "1" {
            return Err(BuildError::zimagefile_validation(format!(
                "unsupported version '{v}', only version \"1\" is supported"
            )));
        }
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// Mode exclusivity
// ---------------------------------------------------------------------------

/// Exactly one of `runtime`, `wasm`, `stages`, `base`, or `build` must be set.
/// `base` and `build` are treated as the same mode (single-stage) and are
/// mutually exclusive with each other.
fn validate_mode_exclusivity(image: &ZImage) -> Result<()> {
    let modes_present: Vec<&str> = [
        image.runtime.as_ref().map(|_| "runtime"),
        image.wasm.as_ref().map(|_| "wasm"),
        image.stages.as_ref().map(|_| "stages"),
        image.base.as_ref().map(|_| "base"),
        image.build.as_ref().map(|_| "build"),
    ]
    .into_iter()
    .flatten()
    .collect();

    match modes_present.len() {
        0 => Err(BuildError::zimagefile_validation(
            "exactly one of 'runtime', 'wasm', 'stages', 'base', or 'build' must be set, \
             but none were found"
                .to_string(),
        )),
        1 => Ok(()),
        _ => Err(BuildError::zimagefile_validation(format!(
            "exactly one of 'runtime', 'wasm', 'stages', 'base', or 'build' must be set, \
             but multiple were found: {}",
            modes_present.join(", ")
        ))),
    }
}

// ---------------------------------------------------------------------------
// Step validation
// ---------------------------------------------------------------------------

/// Validate all steps reachable from the current image configuration.
fn validate_steps(image: &ZImage) -> Result<()> {
    // Single-stage mode: validate top-level steps.
    if image.base.is_some() || image.build.is_some() {
        for (i, step) in image.steps.iter().enumerate() {
            validate_step(step, i, None)?;
        }
    }

    // Multi-stage mode: validate steps in every stage + base/build exclusivity.
    if let Some(ref stages) = image.stages {
        for (stage_name, stage) in stages {
            // Exactly one of base or build must be set per stage.
            match (&stage.base, &stage.build) {
                (None, None) => {
                    return Err(BuildError::zimagefile_validation(format!(
                        "stage '{stage_name}': exactly one of 'base' or 'build' must be set, \
                         but neither was found"
                    )));
                }
                (Some(_), Some(_)) => {
                    return Err(BuildError::zimagefile_validation(format!(
                        "stage '{stage_name}': 'base' and 'build' are mutually exclusive, \
                         but both were set"
                    )));
                }
                _ => {}
            }

            for (i, step) in stage.steps.iter().enumerate() {
                validate_step(step, i, Some(stage_name))?;
            }
        }
    }

    Ok(())
}

/// Validate a single build step.
///
/// Rules enforced:
/// - Exactly one instruction type must be set (`run`, `copy`, `add`, `env`, `workdir`, `user`),
///   with one exception: `env` may appear alongside `run`, in which case `env` acts as a
///   transient per-RUN modifier (env vars scoped to that single RUN command, not baked into
///   the image) rather than a separate persistent ENV instruction.
/// - `copy` and `add` steps must have a `to` field.
/// - `cache` is only valid on `run` steps.
/// - `from` is only valid on `copy`/`add` steps.
/// - `owner`/`chmod` are only valid on `copy`/`add` steps.
fn validate_step(step: &ZStep, index: usize, stage: Option<&str>) -> Result<()> {
    let location = match stage {
        Some(s) => format!("stage '{s}', step {}", index + 1),
        None => format!("step {}", index + 1),
    };

    // Count how many instruction fields are set.
    let mut instructions: Vec<&str> = [
        step.run.as_ref().map(|_| "run"),
        step.copy.as_ref().map(|_| "copy"),
        step.add.as_ref().map(|_| "add"),
        step.env.as_ref().map(|_| "env"),
        step.workdir.as_ref().map(|_| "workdir"),
        step.user.as_ref().map(|_| "user"),
    ]
    .into_iter()
    .flatten()
    .collect();

    // Special case: `run` + `env` is allowed. The `env` map is treated as
    // transient environment variables scoped to that single RUN command (not a
    // separate persistent ENV instruction), so it must not be counted toward
    // the mutual-exclusion check.
    if step.run.is_some() && step.env.is_some() {
        instructions.retain(|i| *i != "env");
    }

    match instructions.len() {
        0 => {
            return Err(BuildError::zimagefile_validation(format!(
                "{location}: step must have exactly one instruction type \
                 (run, copy, add, env, workdir, user), but none were found"
            )));
        }
        1 => {} // good
        _ => {
            return Err(BuildError::zimagefile_validation(format!(
                "{location}: step must have exactly one instruction type, \
                 but multiple were found: {}",
                instructions.join(", ")
            )));
        }
    }

    let instruction = instructions[0];
    let is_copy_or_add = instruction == "copy" || instruction == "add";

    // `to` is required on copy/add steps.
    if is_copy_or_add && step.to.is_none() {
        return Err(BuildError::zimagefile_validation(format!(
            "{location}: '{instruction}' step must have a 'to' field"
        )));
    }

    // `cache` is only valid on `run` steps.
    if !step.cache.is_empty() && instruction != "run" {
        return Err(BuildError::zimagefile_validation(format!(
            "{location}: 'cache' is only valid on 'run' steps, not '{instruction}'"
        )));
    }

    // `from` is only valid on `copy`/`add` steps.
    if step.from.is_some() && !is_copy_or_add {
        return Err(BuildError::zimagefile_validation(format!(
            "{location}: 'from' is only valid on 'copy'/'add' steps, not '{instruction}'"
        )));
    }

    // `owner` is only valid on `copy`/`add` steps.
    if step.owner.is_some() && !is_copy_or_add {
        return Err(BuildError::zimagefile_validation(format!(
            "{location}: 'owner' is only valid on 'copy'/'add' steps, not '{instruction}'"
        )));
    }

    // `chmod` is only valid on `copy`/`add` steps.
    if step.chmod.is_some() && !is_copy_or_add {
        return Err(BuildError::zimagefile_validation(format!(
            "{location}: 'chmod' is only valid on 'copy'/'add' steps, not '{instruction}'"
        )));
    }

    Ok(())
}

// ---------------------------------------------------------------------------
// WASM validation
// ---------------------------------------------------------------------------

/// Validate WASM-specific configuration fields when the `wasm` mode is active.
#[allow(clippy::items_after_statements)]
fn validate_wasm(image: &ZImage) -> Result<()> {
    let Some(ref wasm) = image.wasm else {
        return Ok(());
    };

    // `target` must be "preview1" or "preview2".
    const VALID_TARGETS: &[&str] = &["preview1", "preview2"];
    if !VALID_TARGETS.contains(&wasm.target.as_str()) {
        return Err(BuildError::zimagefile_validation(format!(
            "wasm.target must be one of {VALID_TARGETS:?}, got '{}'",
            wasm.target
        )));
    }

    // `world` must be a known ZLayer world name.
    if let Some(ref world) = wasm.world {
        const VALID_WORLDS: &[&str] = &[
            "zlayer-plugin",
            "zlayer-http-handler",
            "zlayer-transformer",
            "zlayer-authenticator",
            "zlayer-rate-limiter",
            "zlayer-middleware",
            "zlayer-router",
        ];
        if !VALID_WORLDS.contains(&world.as_str()) {
            return Err(BuildError::zimagefile_validation(format!(
                "wasm.world must be one of {VALID_WORLDS:?}, got '{world}'"
            )));
        }
    }

    // `opt_level` must be a valid wasm-opt optimization level.
    if let Some(ref opt_level) = wasm.opt_level {
        const VALID_OPT_LEVELS: &[&str] = &["O", "Os", "Oz", "O2", "O3"];
        if !VALID_OPT_LEVELS.contains(&opt_level.as_str()) {
            return Err(BuildError::zimagefile_validation(format!(
                "wasm.opt_level must be one of {VALID_OPT_LEVELS:?}, got '{opt_level}'"
            )));
        }
    }

    // `language` must be a supported source language.
    if let Some(ref language) = wasm.language {
        const VALID_LANGUAGES: &[&str] = &[
            "rust",
            "go",
            "python",
            "typescript",
            "assemblyscript",
            "c",
            "zig",
        ];
        if !VALID_LANGUAGES.contains(&language.as_str()) {
            return Err(BuildError::zimagefile_validation(format!(
                "wasm.language must be one of {VALID_LANGUAGES:?}, got '{language}'"
            )));
        }
    }

    Ok(())
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    // -- Happy-path tests ------------------------------------------------

    #[test]
    fn test_parse_runtime_mode() {
        let yaml = r#"
version: "1"
runtime: node22
cmd: "node server.js"
"#;
        let img = parse_zimagefile(yaml).unwrap();
        assert_eq!(img.runtime.as_deref(), Some("node22"));
    }

    #[test]
    fn test_parse_single_stage() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - run: "apk add --no-cache curl"
  - copy: "app.sh"
    to: "/usr/local/bin/app.sh"
    chmod: "755"
  - workdir: "/app"
cmd: ["./app.sh"]
"#;
        let img = parse_zimagefile(yaml).unwrap();
        assert_eq!(img.base.as_deref(), Some("alpine:3.19"));
        assert_eq!(img.steps.len(), 3);
    }

    #[test]
    fn test_parse_multi_stage() {
        let yaml = r#"
version: "1"
stages:
  builder:
    base: "node:22-alpine"
    steps:
      - copy: "package.json"
        to: "./"
      - run: "npm ci"
  runtime:
    base: "node:22-alpine"
    steps:
      - copy: "dist"
        from: builder
        to: "/app"
cmd: ["node", "dist/index.js"]
"#;
        let img = parse_zimagefile(yaml).unwrap();
        let stages = img.stages.as_ref().unwrap();
        assert_eq!(stages.len(), 2);
    }

    #[test]
    fn test_parse_wasm_mode() {
        let yaml = r#"
version: "1"
wasm:
  target: preview2
  optimize: true
"#;
        let img = parse_zimagefile(yaml).unwrap();
        assert!(img.wasm.is_some());
    }

    #[test]
    fn test_version_omitted_is_ok() {
        let yaml = r"
runtime: node22
";
        let img = parse_zimagefile(yaml).unwrap();
        assert!(img.version.is_none());
        assert_eq!(img.runtime.as_deref(), Some("node22"));
    }

    // -- Version validation -----------------------------------------------

    #[test]
    fn test_bad_version_rejected() {
        let yaml = r#"
version: "2"
runtime: node22
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("unsupported version"), "got: {msg}");
    }

    // -- Mode exclusivity -------------------------------------------------

    #[test]
    fn test_no_mode_rejected() {
        let yaml = r#"
version: "1"
cmd: "echo hi"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("none were found"), "got: {msg}");
    }

    #[test]
    fn test_multiple_modes_rejected() {
        let yaml = r#"
version: "1"
runtime: node22
base: "alpine:3.19"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("multiple were found"), "got: {msg}");
    }

    // -- Step validation --------------------------------------------------

    #[test]
    fn test_step_no_instruction_rejected() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - to: "/app"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("none were found"), "got: {msg}");
    }

    #[test]
    fn test_step_multiple_instructions_rejected() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - run: "echo hi"
    workdir: "/app"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("multiple were found"), "got: {msg}");
    }

    #[test]
    fn test_copy_missing_to_rejected() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - copy: "file.txt"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("must have a 'to' field"), "got: {msg}");
    }

    #[test]
    fn test_add_missing_to_rejected() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - add: "archive.tar.gz"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("must have a 'to' field"), "got: {msg}");
    }

    #[test]
    fn test_cache_on_non_run_rejected() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - copy: "file.txt"
    to: "/app/file.txt"
    cache:
      - target: /var/cache
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("'cache' is only valid on 'run'"), "got: {msg}");
    }

    #[test]
    fn test_from_on_non_copy_add_rejected() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - run: "echo hi"
    from: builder
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("'from' is only valid on 'copy'/'add'"),
            "got: {msg}"
        );
    }

    #[test]
    fn test_owner_on_non_copy_add_rejected() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - run: "echo hi"
    owner: "root:root"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("'owner' is only valid on 'copy'/'add'"),
            "got: {msg}"
        );
    }

    #[test]
    fn test_chmod_on_non_copy_add_rejected() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - run: "echo hi"
    chmod: "755"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("'chmod' is only valid on 'copy'/'add'"),
            "got: {msg}"
        );
    }

    #[test]
    fn test_from_on_copy_allowed() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - copy: "dist"
    from: builder
    to: "/app"
"#;
        parse_zimagefile(yaml).unwrap();
    }

    #[test]
    fn test_from_on_add_allowed() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - add: "https://example.com/file.tar.gz"
    from: builder
    to: "/app"
"#;
        parse_zimagefile(yaml).unwrap();
    }

    #[test]
    fn test_cache_on_run_allowed() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - run: "apt-get update"
    cache:
      - target: /var/cache/apt
        id: apt-cache
"#;
        parse_zimagefile(yaml).unwrap();
    }

    #[test]
    fn test_owner_chmod_on_copy_allowed() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - copy: "app.sh"
    to: "/usr/local/bin/app.sh"
    owner: "1000:1000"
    chmod: "755"
"#;
        parse_zimagefile(yaml).unwrap();
    }

    #[test]
    fn test_multi_stage_step_validation() {
        // Ensure validation runs on every stage, not just top-level.
        let yaml = r#"
version: "1"
stages:
  builder:
    base: "node:22"
    steps:
      - copy: "package.json"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("stage 'builder'"), "got: {msg}");
        assert!(msg.contains("must have a 'to' field"), "got: {msg}");
    }

    #[test]
    fn test_yaml_syntax_error() {
        let yaml = ":::not valid yaml:::";
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("parse error"), "got: {msg}");
    }

    #[test]
    fn test_env_step_valid() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - env:
      NODE_ENV: production
"#;
        parse_zimagefile(yaml).unwrap();
    }

    #[test]
    fn test_user_step_valid() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
steps:
  - user: "nobody"
"#;
        parse_zimagefile(yaml).unwrap();
    }

    // -- run + env modifier tests --------------------------------------------

    /// Helper: construct an otherwise-empty [`ZStep`] for direct `validate_step`
    /// tests. Mirrors the pattern of building literals since `ZStep` has no
    /// `Default` impl.
    fn empty_step() -> ZStep {
        ZStep {
            run: None,
            copy: None,
            add: None,
            env: None,
            workdir: None,
            user: None,
            to: None,
            from: None,
            owner: None,
            chmod: None,
            cache: Vec::new(),
        }
    }

    #[test]
    fn test_step_run_plus_env_is_valid() {
        let mut env = std::collections::HashMap::new();
        env.insert("FOO".to_string(), "bar".to_string());
        let step = ZStep {
            run: Some(super::super::types::ZCommand::Shell("echo hi".to_string())),
            env: Some(env),
            ..empty_step()
        };
        validate_step(&step, 0, None).expect("run + env must be a valid combination");
    }

    #[test]
    fn test_step_env_alone_is_valid() {
        let mut env = std::collections::HashMap::new();
        env.insert("FOO".to_string(), "bar".to_string());
        let step = ZStep {
            env: Some(env),
            ..empty_step()
        };
        validate_step(&step, 0, None).expect("env alone must remain valid");
    }

    #[test]
    fn test_step_env_plus_copy_is_rejected() {
        let mut env = std::collections::HashMap::new();
        env.insert("FOO".to_string(), "bar".to_string());
        let step = ZStep {
            copy: Some(super::super::types::ZCopySources::Single("src".to_string())),
            to: Some("/dst".to_string()),
            env: Some(env),
            ..empty_step()
        };
        let err = validate_step(&step, 0, None).expect_err("env + copy must be rejected");
        let msg = err.to_string();
        assert!(
            msg.contains("multiple") && msg.contains("instruction type"),
            "expected multiple-instruction-type error, got: {msg}"
        );
    }

    #[test]
    fn test_step_env_plus_workdir_is_rejected() {
        let mut env = std::collections::HashMap::new();
        env.insert("FOO".to_string(), "bar".to_string());
        let step = ZStep {
            workdir: Some("/app".to_string()),
            env: Some(env),
            ..empty_step()
        };
        let err = validate_step(&step, 0, None).expect_err("env + workdir must be rejected");
        let msg = err.to_string();
        assert!(
            msg.contains("multiple") && msg.contains("instruction type"),
            "expected multiple-instruction-type error, got: {msg}"
        );
    }

    // -- Build directive tests ------------------------------------------------

    #[test]
    fn test_build_short_form() {
        let yaml = r#"
version: "1"
build: "."
steps:
  - run: "echo hello"
"#;
        let img = parse_zimagefile(yaml).unwrap();
        assert!(img.build.is_some());
        assert!(img.base.is_none());
    }

    #[test]
    fn test_build_long_form() {
        let yaml = r#"
version: "1"
build:
  context: "./subdir"
  file: "ZImagefile.prod"
  args:
    RUST_VERSION: "1.90"
steps:
  - run: "echo hello"
"#;
        let img = parse_zimagefile(yaml).unwrap();
        assert!(img.build.is_some());
        assert!(img.base.is_none());
    }

    #[test]
    fn test_build_and_base_rejected() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
build: "."
steps:
  - run: "echo hi"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("multiple were found"), "got: {msg}");
    }

    #[test]
    fn test_stage_build_directive() {
        let yaml = r#"
version: "1"
stages:
  builder:
    build: "."
    steps:
      - run: "make build"
  runtime:
    base: "debian:bookworm-slim"
    steps:
      - copy: "target/release/app"
        from: builder
        to: "/usr/local/bin/app"
"#;
        let img = parse_zimagefile(yaml).unwrap();
        let stages = img.stages.as_ref().unwrap();
        assert!(stages["builder"].build.is_some());
        assert!(stages["builder"].base.is_none());
        assert!(stages["runtime"].base.is_some());
        assert!(stages["runtime"].build.is_none());
    }

    #[test]
    fn test_stage_build_and_base_rejected() {
        let yaml = r#"
version: "1"
stages:
  builder:
    base: "rust:1.90"
    build: "."
    steps:
      - run: "cargo build"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("mutually exclusive"), "got: {msg}");
    }

    #[test]
    fn test_stage_neither_base_nor_build_rejected() {
        let yaml = r#"
version: "1"
stages:
  builder:
    steps:
      - run: "echo hi"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("neither was found"), "got: {msg}");
    }

    // -- WASM validation tests ------------------------------------------------

    #[test]
    fn test_wasm_valid_full_config() {
        let yaml = r#"
version: "1"
wasm:
  target: "preview2"
  optimize: true
  opt_level: "Oz"
  language: "rust"
  world: "zlayer-http-handler"
  wit: "./wit"
  output: "./output.wasm"
  features: [json, metrics]
  build_args:
    CARGO_PROFILE_RELEASE_LTO: "true"
  pre_build:
    - "wit-bindgen tiny-go --world zlayer-http-handler --out-dir bindings/"
  post_build:
    - "wasm-tools component embed --world zlayer-http-handler wit/ output.wasm -o output.wasm"
  adapter: "./wasi_snapshot_preview1.reactor.wasm"
"#;
        parse_zimagefile(yaml).unwrap();
    }

    #[test]
    fn test_wasm_preview1_target_valid() {
        let yaml = r#"
version: "1"
wasm:
  target: "preview1"
"#;
        parse_zimagefile(yaml).unwrap();
    }

    #[test]
    fn test_wasm_invalid_target_rejected() {
        let yaml = r#"
version: "1"
wasm:
  target: "preview3"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("wasm.target"), "got: {msg}");
        assert!(msg.contains("preview3"), "got: {msg}");
    }

    #[test]
    fn test_wasm_invalid_world_rejected() {
        let yaml = r#"
version: "1"
wasm:
  world: "unknown-world"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("wasm.world"), "got: {msg}");
        assert!(msg.contains("unknown-world"), "got: {msg}");
    }

    #[test]
    fn test_wasm_all_valid_worlds() {
        for world in &[
            "zlayer-plugin",
            "zlayer-http-handler",
            "zlayer-transformer",
            "zlayer-authenticator",
            "zlayer-rate-limiter",
            "zlayer-middleware",
            "zlayer-router",
        ] {
            let yaml = format!(
                r#"
version: "1"
wasm:
  world: "{world}"
"#
            );
            parse_zimagefile(&yaml).unwrap_or_else(|e| {
                panic!("world '{world}' should be valid, got: {e}");
            });
        }
    }

    #[test]
    fn test_wasm_invalid_opt_level_rejected() {
        let yaml = r#"
version: "1"
wasm:
  opt_level: "O4"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("wasm.opt_level"), "got: {msg}");
        assert!(msg.contains("O4"), "got: {msg}");
    }

    #[test]
    fn test_wasm_all_valid_opt_levels() {
        for level in &["O", "Os", "Oz", "O2", "O3"] {
            let yaml = format!(
                r#"
version: "1"
wasm:
  opt_level: "{level}"
"#
            );
            parse_zimagefile(&yaml).unwrap_or_else(|e| {
                panic!("opt_level '{level}' should be valid, got: {e}");
            });
        }
    }

    #[test]
    fn test_wasm_invalid_language_rejected() {
        let yaml = r#"
version: "1"
wasm:
  language: "java"
"#;
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("wasm.language"), "got: {msg}");
        assert!(msg.contains("java"), "got: {msg}");
    }

    #[test]
    fn test_runtime_wasm_rewrites_to_wasm_mode() {
        // `runtime: wasm` is shorthand: it should be transparently rewritten
        // to the `wasm:` mode with serde-default values so the rest of the
        // pipeline dispatches it through the WASM build path.
        let yaml = r#"
version: "1"
runtime: wasm
"#;
        let img = parse_zimagefile(yaml).unwrap();
        assert!(img.runtime.is_none(), "runtime should be cleared");
        let wasm = img.wasm.expect("wasm mode should be set");
        assert_eq!(wasm.target, "preview2");
        assert_eq!(wasm.opt_level.as_deref(), Some("Oz"));
    }

    #[test]
    fn test_runtime_webassembly_alias_rewrites_to_wasm_mode() {
        let yaml = r#"
version: "1"
runtime: WebAssembly
"#;
        let img = parse_zimagefile(yaml).unwrap();
        assert!(img.runtime.is_none());
        assert!(img.wasm.is_some());
    }

    #[test]
    fn test_runtime_wasm_does_not_override_explicit_wasm_mode() {
        // If the user sets both `runtime: wasm` and an explicit `wasm:`
        // block... actually, the mode exclusivity check should reject that.
        let yaml = r#"
version: "1"
runtime: wasm
wasm:
  target: preview1
"#;
        // Since we only rewrite when `image.wasm.is_none()`, both fields
        // remain set and mode exclusivity rejects the combination.
        let err = parse_zimagefile(yaml).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("multiple were found"), "got: {msg}");
    }

    // -- isolation label stamping ---------------------------------------------

    #[test]
    fn test_isolation_native_stamps_sandbox_label() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
isolation: native
"#;
        let img = parse_zimagefile(yaml).unwrap();
        assert_eq!(
            img.labels.get("com.zlayer.isolation").map(String::as_str),
            Some("sandbox"),
            "`isolation: native` must stamp com.zlayer.isolation=sandbox"
        );
    }

    #[test]
    fn test_isolation_absent_stamps_no_label() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
"#;
        let img = parse_zimagefile(yaml).unwrap();
        assert!(
            !img.labels.contains_key("com.zlayer.isolation"),
            "no isolation: must leave the label unset"
        );
    }

    #[test]
    fn test_isolation_explicit_label_not_overwritten() {
        let yaml = r#"
version: "1"
base: "alpine:3.19"
isolation: native
labels:
  com.zlayer.isolation: vm
"#;
        let img = parse_zimagefile(yaml).unwrap();
        assert_eq!(
            img.labels.get("com.zlayer.isolation").map(String::as_str),
            Some("vm"),
            "an explicit user label must win over the resolved isolation"
        );
    }

    #[test]
    fn test_wasm_all_valid_languages() {
        for lang in &[
            "rust",
            "go",
            "python",
            "typescript",
            "assemblyscript",
            "c",
            "zig",
        ] {
            let yaml = format!(
                r#"
version: "1"
wasm:
  language: "{lang}"
"#
            );
            parse_zimagefile(&yaml).unwrap_or_else(|e| {
                panic!("language '{lang}' should be valid, got: {e}");
            });
        }
    }
}