zlayer_builder/dockerfile/

parser.rs

//! Dockerfile parser
//!
//! This module provides functionality to parse Dockerfiles into a structured representation
//! using the `dockerfile-parser` crate as the parsing backend.

use std::collections::HashMap;
use std::path::Path;
use std::str::FromStr;

use dockerfile_parser::{Dockerfile as RawDockerfile, Instruction as RawInstruction};
use serde::{Deserialize, Serialize};
use zlayer_types::ImageReference;

use crate::error::{BuildError, Result};

use super::instruction::{
    AddInstruction, ArgInstruction, CopyInstruction, EnvInstruction, ExposeInstruction,
    ExposeProtocol, HealthcheckInstruction, Instruction, RunInstruction, ShellOrExec,
};

/// A Dockerfile `FROM` target.
///
/// `FROM` references can resolve to one of three things in a Dockerfile:
/// an OCI image (the common case), a previous stage in a multi-stage
/// build (e.g. `FROM builder AS final`), or the special `scratch`
/// pseudo-image. This enum captures all three. For non-Dockerfile call
/// sites (image registry lookups, toolchain detection, etc.) use
/// [`zlayer_types::ImageReference`] directly — the bare OCI ref type
/// without the Dockerfile-only variants.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum DockerfileFromTarget {
    /// An OCI image reference (canonical OCI grammar).
    Image(ImageReference),
    /// A reference to another stage in this multi-stage build.
    Stage(String),
    /// The special `scratch` pseudo-image.
    Scratch,
}

impl DockerfileFromTarget {
    /// Parse a raw `FROM` target string.
    ///
    /// Recognizes `scratch` (case-insensitive), then attempts an OCI
    /// reference parse via [`ImageReference::from_str`]. If parsing
    /// succeeds, the result is an [`Self::Image`]; otherwise the
    /// input is treated as a [`Self::Stage`] reference.
    ///
    /// Note that the OCI grammar accepts bare names like `alpine` as
    /// valid image references, so disambiguation between an image
    /// and a multi-stage stage reference must happen post-hoc at the
    /// call site by consulting the set of known stage names.
    #[must_use]
    pub fn parse(s: &str) -> Self {
        let s = s.trim();

        if s.eq_ignore_ascii_case("scratch") {
            return Self::Scratch;
        }

        match ImageReference::from_str(s) {
            Ok(r) => Self::Image(r),
            Err(_) => Self::Stage(s.to_string()),
        }
    }

    /// Returns true if this is a stage reference.
    #[must_use]
    pub fn is_stage(&self) -> bool {
        matches!(self, Self::Stage(_))
    }

    /// Returns true if this is the `scratch` pseudo-image.
    #[must_use]
    pub fn is_scratch(&self) -> bool {
        matches!(self, Self::Scratch)
    }
}

impl std::fmt::Display for DockerfileFromTarget {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Image(r) => write!(f, "{r}"),
            Self::Stage(name) => f.write_str(name),
            Self::Scratch => f.write_str("scratch"),
        }
    }
}

/// A single stage in a multi-stage Dockerfile
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Stage {
    /// Stage index (0-based)
    pub index: usize,

    /// Optional stage name (from `AS name`)
    pub name: Option<String>,

    /// The base image for this stage
    pub base_image: DockerfileFromTarget,

    /// Optional platform specification (e.g., "linux/amd64")
    pub platform: Option<String>,

    /// Instructions in this stage (excluding the FROM)
    pub instructions: Vec<Instruction>,
}

impl Stage {
    /// Returns the stage identifier (name if present, otherwise index as string)
    #[must_use]
    pub fn identifier(&self) -> String {
        self.name.clone().unwrap_or_else(|| self.index.to_string())
    }

    /// Returns true if this stage matches the given name or index
    #[must_use]
    pub fn matches(&self, name_or_index: &str) -> bool {
        if let Some(ref name) = self.name {
            if name == name_or_index {
                return true;
            }
        }

        if let Ok(idx) = name_or_index.parse::<usize>() {
            return idx == self.index;
        }

        false
    }
}

/// Expand Docker build-arg references in a `FROM` target string.
///
/// Supports the forms Docker accepts in `FROM` lines: `${VAR}`,
/// `${VAR:-default}` (default when unset or empty), `${VAR:+alt}` (alt
/// when set and non-empty), and bare `$VAR`. Unknown variables expand to
/// the empty string, matching `docker build`.
fn expand_from_args(input: &str, vars: &HashMap<String, String>) -> String {
    let mut out = String::with_capacity(input.len());
    let mut chars = input.char_indices().peekable();
    while let Some((_, c)) = chars.next() {
        if c != '$' {
            out.push(c);
            continue;
        }
        match chars.peek() {
            Some(&(_, '{')) => {
                chars.next(); // consume '{'
                let mut body = String::new();
                let mut closed = false;
                for (_, bc) in chars.by_ref() {
                    if bc == '}' {
                        closed = true;
                        break;
                    }
                    body.push(bc);
                }
                if !closed {
                    // Unterminated `${...` — emit verbatim.
                    out.push_str("${");
                    out.push_str(&body);
                    continue;
                }
                if let Some((name, default)) = body.split_once(":-") {
                    match vars.get(name).filter(|v| !v.is_empty()) {
                        Some(v) => out.push_str(v),
                        None => out.push_str(default),
                    }
                } else if let Some((name, alt)) = body.split_once(":+") {
                    if vars.get(name).is_some_and(|v| !v.is_empty()) {
                        out.push_str(alt);
                    }
                } else {
                    out.push_str(vars.get(&body).map_or("", String::as_str));
                }
            }
            Some(&(_, next)) if next.is_ascii_alphabetic() || next == '_' => {
                let mut name = String::new();
                while let Some(&(_, nc)) = chars.peek() {
                    if nc.is_ascii_alphanumeric() || nc == '_' {
                        name.push(nc);
                        chars.next();
                    } else {
                        break;
                    }
                }
                out.push_str(vars.get(&name).map_or("", String::as_str));
            }
            // BuildKit escape: `$$` is a literal dollar sign.
            Some(&(_, '$')) => {
                chars.next();
                out.push('$');
            }
            _ => out.push('$'),
        }
    }
    out
}

/// Quote-tracking state while scanning an ARG/ENV instruction, carried
/// across line continuations (quoted values may span lines).
#[derive(Debug, Clone, Copy, Default)]
struct QuoteState {
    in_double: bool,
    in_single: bool,
}

impl QuoteState {
    fn in_quotes(self) -> bool {
        self.in_double || self.in_single
    }
}

/// Which multi-line construct the normalizer is currently inside.
enum LineState {
    /// Start of a fresh logical instruction.
    Top,
    /// Continuation of an ARG/ENV instruction (with carried quote state).
    ArgEnv(QuoteState),
    /// Continuation of any other instruction (e.g. RUN) — copied verbatim.
    Other,
}

/// True if `body` (a line without its terminator) ends in a Dockerfile
/// line continuation: a `\` followed only by spaces/tabs.
fn ends_with_continuation(body: &str) -> bool {
    body.trim_end_matches([' ', '\t']).ends_with('\\')
}

/// Rewrite unquoted-empty assignments (`KEY=` followed by whitespace or
/// end-of-line) on one line of an ARG/ENV instruction to the quoted-empty
/// spelling `KEY=""`, appending the result to `out`.
///
/// Returns `true` if the instruction continues on the next line (trailing
/// `\` outside quotes, an escaped newline inside a quoted string, or a
/// still-open quoted string).
fn rewrite_empty_assignments_in_line(
    body: &str,
    quotes: &mut QuoteState,
    out: &mut String,
    changed: &mut bool,
) -> bool {
    let mut continues = false;
    let mut prev_is_key_char = false;
    let mut chars = body.char_indices().peekable();

    while let Some((idx, c)) = chars.next() {
        if quotes.in_quotes() {
            match c {
                '\\' => {
                    out.push(c);
                    if let Some((_, esc)) = chars.next() {
                        out.push(esc);
                    } else {
                        // `\` at end of line inside a string: the grammar's
                        // `escape` rule consumes the newline, so the string
                        // (and the instruction) continues on the next line.
                        continues = true;
                    }
                }
                '"' if quotes.in_double => {
                    quotes.in_double = false;
                    out.push(c);
                }
                '\'' if quotes.in_single => {
                    quotes.in_single = false;
                    out.push(c);
                }
                _ => out.push(c),
            }
            prev_is_key_char = false;
            continue;
        }

        match c {
            '"' => {
                quotes.in_double = true;
                out.push(c);
                prev_is_key_char = false;
            }
            '\'' => {
                quotes.in_single = true;
                out.push(c);
                prev_is_key_char = false;
            }
            // Line continuation: `\` followed only by trailing whitespace.
            '\\' if body[idx + 1..].chars().all(|w| w == ' ' || w == '\t') => {
                continues = true;
                out.push_str(&body[idx..]);
                break;
            }
            '=' if prev_is_key_char => {
                out.push(c);
                // Empty value only when the `=` is followed by whitespace or
                // end-of-line. `KEY=\` (line continuation directly after the
                // `=`) is left alone: the value may continue on the next line.
                if matches!(chars.peek(), None | Some(&(_, ' ' | '\t'))) {
                    out.push_str("\"\"");
                    *changed = true;
                }
                prev_is_key_char = false;
            }
            _ => {
                out.push(c);
                prev_is_key_char = c.is_ascii_alphanumeric() || c == '_';
            }
        }
    }

    // An unterminated quoted string spans the raw newline in the upstream
    // grammar (`inner` matches ANY except `"`/`\`/two control chars), so the
    // instruction continues either way.
    continues || quotes.in_quotes()
}

/// Rewrite Docker-valid unquoted-empty assignments in ARG and ENV
/// instructions to their quoted-empty spelling before upstream parsing.
///
/// The `dockerfile-parser` pest grammar rejects `ARG NAME=` / `ENV NAME=` /
/// `ENV A= B=c`: its value rules (`arg_value` and `env_pair_value`, both
/// `any_whitespace`) require at least one character after `=`, while real
/// Docker (legacy builder and `BuildKit`) accepts an explicitly empty value —
/// `cross` 0.2.5 generates `ARG CROSS_DEB_ARCH=`. The grammar DOES accept
/// the quoted-empty form (`NAME=""`, parsed to an empty-string value), so
/// this pass rewrites `KEY=` → `KEY=""` inside ARG/ENV instructions only:
/// quoted regions are skipped, non-ARG/ENV instructions (and their
/// continuation lines) are copied verbatim, and line structure is preserved
/// so parse-error line numbers stay meaningful.
fn normalize_empty_assignments(content: &str) -> std::borrow::Cow<'_, str> {
    let mut out = String::with_capacity(content.len() + 8);
    let mut changed = false;
    let mut state = LineState::Top;

    for raw_line in content.split_inclusive('\n') {
        // Split the body from its terminator (`\n` or `\r\n`; the final line
        // may have none).
        let (body, terminator) = match raw_line.strip_suffix('\n') {
            Some(rest) => match rest.strip_suffix('\r') {
                Some(rest) => (rest, "\r\n"),
                None => (rest, "\n"),
            },
            None => (raw_line, ""),
        };

        state = match state {
            LineState::Top => {
                let trimmed = body.trim_start();
                let keyword_len = trimmed
                    .chars()
                    .take_while(char::is_ascii_alphabetic)
                    .count();
                let keyword = &trimmed[..keyword_len];
                let after_keyword = trimmed[keyword_len..].chars().next();
                let is_arg_env = (keyword.eq_ignore_ascii_case("arg")
                    || keyword.eq_ignore_ascii_case("env")
                    || keyword.eq_ignore_ascii_case("label"))
                    && matches!(after_keyword, Some(' ' | '\t' | '\\'));

                if is_arg_env {
                    let prefix_len = body.len() - trimmed.len() + keyword_len;
                    out.push_str(&body[..prefix_len]);
                    let mut quotes = QuoteState::default();
                    if rewrite_empty_assignments_in_line(
                        &trimmed[keyword_len..],
                        &mut quotes,
                        &mut out,
                        &mut changed,
                    ) {
                        LineState::ArgEnv(quotes)
                    } else {
                        LineState::Top
                    }
                } else {
                    out.push_str(body);
                    let is_blank_or_comment = trimmed.is_empty() || trimmed.starts_with('#');
                    if !is_blank_or_comment && ends_with_continuation(body) {
                        LineState::Other
                    } else {
                        LineState::Top
                    }
                }
            }
            LineState::ArgEnv(mut quotes) => {
                let trimmed = body.trim_start();
                if !quotes.in_quotes() && (trimmed.is_empty() || trimmed.starts_with('#')) {
                    // Comment and empty lines may follow a line continuation
                    // (grammar `arg_ws`); the instruction resumes after them.
                    out.push_str(body);
                    LineState::ArgEnv(quotes)
                } else if rewrite_empty_assignments_in_line(
                    body,
                    &mut quotes,
                    &mut out,
                    &mut changed,
                ) {
                    LineState::ArgEnv(quotes)
                } else {
                    LineState::Top
                }
            }
            LineState::Other => {
                out.push_str(body);
                let trimmed = body.trim_start();
                let is_blank_or_comment = trimmed.is_empty() || trimmed.starts_with('#');
                if is_blank_or_comment || ends_with_continuation(body) {
                    LineState::Other
                } else {
                    LineState::Top
                }
            }
        };

        out.push_str(terminator);
    }

    if changed {
        std::borrow::Cow::Owned(out)
    } else {
        std::borrow::Cow::Borrowed(content)
    }
}

/// A parsed Dockerfile
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Dockerfile {
    /// Global ARG instructions that appear before the first FROM
    pub global_args: Vec<ArgInstruction>,

    /// Build stages
    pub stages: Vec<Stage>,
}

impl Dockerfile {
    /// Expand pre-FROM `ARG`s in every stage's `FROM` target.
    ///
    /// Docker semantics: only ARGs declared BEFORE the first `FROM`
    /// participate in `FROM`-line expansion (`FROM ${BASE_IMAGE}` /
    /// `FROM img:${TAG:-latest}`), with `--build-arg` values overriding
    /// their defaults. The parser can't do this (it has no build args), so
    /// targets containing `$` end up classified as [`DockerfileFromTarget::Stage`]
    /// — and struct-consuming backends then fail with `Stage '${BASE_IMAGE}'
    /// not found`. Call this with the effective build args before handing
    /// the Dockerfile to a backend.
    ///
    /// Expanded targets are re-classified: `scratch`, a previously declared
    /// stage name, an OCI image reference, or (still) a stage string. A
    /// target that expands to an empty string is left untouched so the
    /// eventual error names the unexpanded variable instead of a blank.
    pub fn resolve_from_args(&mut self, build_args: &HashMap<String, String>) {
        // Effective FROM-scope variables: declared global ARGs only,
        // defaults overridden by matching build args (an undeclared build
        // arg does NOT leak into FROM lines, per Docker).
        let mut vars: HashMap<String, String> = HashMap::new();
        for arg in &self.global_args {
            let value = build_args
                .get(&arg.name)
                .cloned()
                .or_else(|| arg.default.clone())
                .unwrap_or_default();
            vars.insert(arg.name.clone(), value);
        }

        let mut known_stage_names: std::collections::HashSet<String> =
            std::collections::HashSet::new();
        for stage in &mut self.stages {
            if let DockerfileFromTarget::Stage(raw) = &stage.base_image {
                if raw.contains('$') {
                    let expanded = expand_from_args(raw, &vars);
                    if !expanded.trim().is_empty() {
                        let mut target = DockerfileFromTarget::parse(&expanded);
                        // Same post-hoc stage promotion as `from_raw`: a bare
                        // name that matches an earlier stage alias is a stage
                        // reference even though it parses as an OCI ref.
                        if matches!(target, DockerfileFromTarget::Image(_))
                            && known_stage_names.contains(expanded.trim())
                        {
                            target = DockerfileFromTarget::Stage(expanded.trim().to_string());
                        }
                        stage.base_image = target;
                    }
                }
            }
            if let Some(name) = &stage.name {
                known_stage_names.insert(name.clone());
            }
        }
    }

    /// Parse a Dockerfile from a string
    ///
    /// # Errors
    ///
    /// Returns an error if the Dockerfile content is malformed or contains invalid instructions.
    pub fn parse(content: &str) -> Result<Self> {
        // The upstream grammar rejects Docker-valid unquoted-empty
        // assignments (`ARG NAME=` / `ENV NAME=`); rewrite them to the
        // quoted-empty spelling it accepts. See `normalize_empty_assignments`.
        let content = normalize_empty_assignments(content);
        let raw = RawDockerfile::parse(&content).map_err(|e| BuildError::DockerfileParse {
            message: e.to_string(),
            line: 1,
        })?;

        Self::from_raw(raw)
    }

    /// Parse a Dockerfile from a file
    ///
    /// # Errors
    ///
    /// Returns an error if the file cannot be read or the Dockerfile is malformed.
    pub fn from_file(path: impl AsRef<Path>) -> Result<Self> {
        let content =
            std::fs::read_to_string(path.as_ref()).map_err(|e| BuildError::ContextRead {
                path: path.as_ref().to_path_buf(),
                source: e,
            })?;

        Self::parse(&content)
    }

    /// Convert from the raw dockerfile-parser types to our internal representation
    fn from_raw(raw: RawDockerfile) -> Result<Self> {
        let mut global_args = Vec::new();
        let mut stages = Vec::new();
        let mut current_stage: Option<Stage> = None;
        let mut stage_index = 0;
        // Track stage names declared so far so subsequent FROM lines can
        // resolve `FROM <name>` to a stage reference even when the name
        // is also a syntactically-valid OCI reference (e.g. `FROM builder`).
        let mut known_stage_names: std::collections::HashSet<String> =
            std::collections::HashSet::new();

        for instruction in raw.instructions {
            match &instruction {
                RawInstruction::From(from) => {
                    // Save previous stage if any
                    if let Some(stage) = current_stage.take() {
                        stages.push(stage);
                    }

                    // Parse base image
                    let raw_from = from.image.content.trim().to_string();
                    let mut base_image = DockerfileFromTarget::parse(&raw_from);

                    // Post-hoc stage promotion: `DockerfileFromTarget::parse`
                    // delegates to the OCI grammar, which accepts bare names
                    // like `builder` as valid image refs. If the raw FROM
                    // text matches a previously-declared stage name, swap
                    // the parsed `Image` for a `Stage` reference.
                    if matches!(base_image, DockerfileFromTarget::Image(_))
                        && known_stage_names.contains(&raw_from)
                    {
                        base_image = DockerfileFromTarget::Stage(raw_from.clone());
                    }

                    // Get alias (stage name) - the field is `alias` not `image_alias`
                    let name = from.alias.as_ref().map(|a| a.content.clone());

                    if let Some(ref n) = name {
                        known_stage_names.insert(n.clone());
                    }

                    // Get platform flag
                    let platform = from
                        .flags
                        .iter()
                        .find(|f| f.name.content.as_str() == "platform")
                        .map(|f| f.value.to_string());

                    current_stage = Some(Stage {
                        index: stage_index,
                        name,
                        base_image,
                        platform,
                        instructions: Vec::new(),
                    });

                    stage_index += 1;
                }

                RawInstruction::Arg(arg) => {
                    let arg_inst = ArgInstruction {
                        name: arg.name.to_string(),
                        default: arg.value.as_ref().map(std::string::ToString::to_string),
                    };

                    if current_stage.is_none() {
                        global_args.push(arg_inst);
                    } else if let Some(ref mut stage) = current_stage {
                        stage.instructions.push(Instruction::Arg(arg_inst));
                    }
                }

                _ => {
                    if let Some(ref mut stage) = current_stage {
                        if let Some(inst) = Self::convert_instruction(&instruction)? {
                            stage.instructions.push(inst);
                        }
                    }
                }
            }
        }

        // Don't forget the last stage
        if let Some(stage) = current_stage {
            stages.push(stage);
        }

        // Resolve stage references in COPY --from
        // (This is currently a no-op as stage references are already correct,
        // but kept for future validation/resolution logic)
        let _stage_names: HashMap<String, usize> = stages
            .iter()
            .filter_map(|s| s.name.as_ref().map(|n| (n.clone(), s.index)))
            .collect();
        let _num_stages = stages.len();

        Ok(Self {
            global_args,
            stages,
        })
    }

    /// Convert a raw instruction to our internal representation
    #[allow(clippy::too_many_lines)]
    fn convert_instruction(raw: &RawInstruction) -> Result<Option<Instruction>> {
        let instruction = match raw {
            RawInstruction::From(_) => {
                return Ok(None);
            }

            RawInstruction::Run(run) => {
                let command = match &run.expr {
                    dockerfile_parser::ShellOrExecExpr::Shell(s) => {
                        ShellOrExec::Shell(s.to_string())
                    }
                    dockerfile_parser::ShellOrExecExpr::Exec(args) => {
                        ShellOrExec::Exec(args.elements.iter().map(|s| s.content.clone()).collect())
                    }
                };

                Instruction::Run(RunInstruction {
                    command,
                    mounts: Vec::new(),
                    network: None,
                    security: None,
                    env: HashMap::new(),
                })
            }

            RawInstruction::Copy(copy) => {
                let from = copy
                    .flags
                    .iter()
                    .find(|f| f.name.content.as_str() == "from")
                    .map(|f| f.value.to_string());

                let chown = copy
                    .flags
                    .iter()
                    .find(|f| f.name.content.as_str() == "chown")
                    .map(|f| f.value.to_string());

                let chmod = copy
                    .flags
                    .iter()
                    .find(|f| f.name.content.as_str() == "chmod")
                    .map(|f| f.value.to_string());

                let link = copy.flags.iter().any(|f| f.name.content.as_str() == "link");

                // The external parser separates sources and destination already.
                let sources: Vec<String> = copy
                    .sources
                    .iter()
                    .map(std::string::ToString::to_string)
                    .collect();
                let destination = copy.destination.to_string();

                Instruction::Copy(CopyInstruction {
                    sources,
                    destination,
                    from,
                    chown,
                    chmod,
                    link,
                    exclude: Vec::new(),
                })
            }

            RawInstruction::Entrypoint(ep) => {
                let command = match &ep.expr {
                    dockerfile_parser::ShellOrExecExpr::Shell(s) => {
                        ShellOrExec::Shell(s.to_string())
                    }
                    dockerfile_parser::ShellOrExecExpr::Exec(args) => {
                        ShellOrExec::Exec(args.elements.iter().map(|s| s.content.clone()).collect())
                    }
                };
                Instruction::Entrypoint(command)
            }

            RawInstruction::Cmd(cmd) => {
                let command = match &cmd.expr {
                    dockerfile_parser::ShellOrExecExpr::Shell(s) => {
                        ShellOrExec::Shell(s.to_string())
                    }
                    dockerfile_parser::ShellOrExecExpr::Exec(args) => {
                        ShellOrExec::Exec(args.elements.iter().map(|s| s.content.clone()).collect())
                    }
                };
                Instruction::Cmd(command)
            }

            RawInstruction::Env(env) => {
                let mut vars = HashMap::new();
                for var in &env.vars {
                    vars.insert(var.key.to_string(), var.value.to_string());
                }
                Instruction::Env(EnvInstruction { vars })
            }

            RawInstruction::Label(label) => {
                let mut labels = HashMap::new();
                for l in &label.labels {
                    labels.insert(l.name.to_string(), l.value.to_string());
                }
                Instruction::Label(labels)
            }

            RawInstruction::Arg(arg) => Instruction::Arg(ArgInstruction {
                name: arg.name.to_string(),
                default: arg.value.as_ref().map(std::string::ToString::to_string),
            }),

            RawInstruction::Misc(misc) => {
                let instruction_upper = misc.instruction.content.to_uppercase();
                match instruction_upper.as_str() {
                    "WORKDIR" => Instruction::Workdir(misc.arguments.to_string()),

                    "USER" => Instruction::User(misc.arguments.to_string()),

                    "VOLUME" => {
                        let args = misc.arguments.to_string();
                        let volumes = if args.trim().starts_with('[') {
                            serde_json::from_str(&args).unwrap_or_else(|_| vec![args])
                        } else {
                            args.split_whitespace().map(String::from).collect()
                        };
                        Instruction::Volume(volumes)
                    }

                    "EXPOSE" => {
                        let args = misc.arguments.to_string();
                        let (port_str, protocol) = if let Some((p, proto)) = args.split_once('/') {
                            let proto = match proto.to_lowercase().as_str() {
                                "udp" => ExposeProtocol::Udp,
                                _ => ExposeProtocol::Tcp,
                            };
                            (p, proto)
                        } else {
                            (args.as_str(), ExposeProtocol::Tcp)
                        };

                        let port: u16 = port_str.trim().parse().map_err(|_| {
                            BuildError::InvalidInstruction {
                                instruction: "EXPOSE".to_string(),
                                reason: format!("Invalid port number: {port_str}"),
                            }
                        })?;

                        Instruction::Expose(ExposeInstruction { port, protocol })
                    }

                    "SHELL" => {
                        let args = misc.arguments.to_string();
                        let shell: Vec<String> = serde_json::from_str(&args).map_err(|_| {
                            BuildError::InvalidInstruction {
                                instruction: "SHELL".to_string(),
                                reason: "SHELL requires a JSON array".to_string(),
                            }
                        })?;
                        Instruction::Shell(shell)
                    }

                    "STOPSIGNAL" => Instruction::Stopsignal(misc.arguments.to_string()),

                    "HEALTHCHECK" => {
                        let args = misc.arguments.to_string().trim().to_string();
                        if args.eq_ignore_ascii_case("NONE") {
                            Instruction::Healthcheck(HealthcheckInstruction::None)
                        } else {
                            let command = if let Some(stripped) = args.strip_prefix("CMD ") {
                                ShellOrExec::Shell(stripped.to_string())
                            } else {
                                ShellOrExec::Shell(args)
                            };
                            Instruction::Healthcheck(HealthcheckInstruction::cmd(command))
                        }
                    }

                    "ONBUILD" => {
                        tracing::warn!("ONBUILD instruction parsing not fully implemented");
                        return Ok(None);
                    }

                    "MAINTAINER" => {
                        let mut labels = HashMap::new();
                        labels.insert("maintainer".to_string(), misc.arguments.to_string());
                        Instruction::Label(labels)
                    }

                    "ADD" => {
                        let args = misc.arguments.to_string();
                        let parts: Vec<String> =
                            args.split_whitespace().map(String::from).collect();

                        if parts.len() < 2 {
                            return Err(BuildError::InvalidInstruction {
                                instruction: "ADD".to_string(),
                                reason: "ADD requires at least one source and a destination"
                                    .to_string(),
                            });
                        }

                        let (sources, dest) = parts.split_at(parts.len() - 1);
                        let destination = dest.first().cloned().unwrap_or_default();

                        Instruction::Add(AddInstruction {
                            sources: sources.to_vec(),
                            destination,
                            chown: None,
                            chmod: None,
                            link: false,
                            checksum: None,
                            keep_git_dir: false,
                        })
                    }

                    other => {
                        tracing::warn!("Unknown Dockerfile instruction: {}", other);
                        return Ok(None);
                    }
                }
            }
        };

        Ok(Some(instruction))
    }

    /// Get a stage by name or index
    #[must_use]
    pub fn get_stage(&self, name_or_index: &str) -> Option<&Stage> {
        self.stages.iter().find(|s| s.matches(name_or_index))
    }

    /// Get the final stage (last one in the Dockerfile)
    #[must_use]
    pub fn final_stage(&self) -> Option<&Stage> {
        self.stages.last()
    }

    /// Get all stage names/identifiers
    #[must_use]
    pub fn stage_names(&self) -> Vec<String> {
        self.stages.iter().map(Stage::identifier).collect()
    }

    /// Check if a stage exists
    #[must_use]
    pub fn has_stage(&self, name_or_index: &str) -> bool {
        self.get_stage(name_or_index).is_some()
    }

    /// Returns the number of stages
    #[must_use]
    pub fn stage_count(&self) -> usize {
        self.stages.len()
    }
}

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

    #[test]
    fn test_parse_simple_dockerfile() {
        let content = r#"
FROM alpine:3.18
RUN apk add --no-cache curl
COPY . /app
WORKDIR /app
CMD ["./app"]
"#;

        let dockerfile = Dockerfile::parse(content).unwrap();
        assert_eq!(dockerfile.stages.len(), 1);

        let stage = &dockerfile.stages[0];
        assert_eq!(stage.index, 0);
        assert!(stage.name.is_none());
        assert_eq!(stage.instructions.len(), 4);
    }

    #[test]
    fn test_parse_multistage_dockerfile() {
        let content = r#"
FROM golang:1.21 AS builder
WORKDIR /src
COPY . .
RUN go build -o /app

FROM alpine:3.18
COPY --from=builder /app /app
CMD ["/app"]
"#;

        let dockerfile = Dockerfile::parse(content).unwrap();
        assert_eq!(dockerfile.stages.len(), 2);

        let builder = &dockerfile.stages[0];
        assert_eq!(builder.name, Some("builder".to_string()));

        let runtime = &dockerfile.stages[1];
        assert!(runtime.name.is_none());

        let copy = runtime
            .instructions
            .iter()
            .find(|i| matches!(i, Instruction::Copy(_)));
        assert!(copy.is_some());
        if let Some(Instruction::Copy(c)) = copy {
            assert_eq!(c.from, Some("builder".to_string()));
        }
    }

    #[test]
    fn test_parse_copy_from_external_image_reference() {
        // `COPY --from=<external-image>` must capture the full registry-
        // qualified reference in `CopyInstruction.from` so the buildah
        // backend can pull and forward it to `buildah copy --from=...`.
        let content = r"
FROM alpine:3.18
COPY --from=ghcr.io/astral-sh/uv:0.5.0 /uv /usr/local/bin/uv
RUN /usr/local/bin/uv --version
";

        let dockerfile = Dockerfile::parse(content).unwrap();
        assert_eq!(dockerfile.stages.len(), 1);

        let copy = dockerfile.stages[0]
            .instructions
            .iter()
            .find_map(|i| {
                if let Instruction::Copy(c) = i {
                    Some(c)
                } else {
                    None
                }
            })
            .expect("COPY instruction present");

        assert_eq!(
            copy.from,
            Some("ghcr.io/astral-sh/uv:0.5.0".to_string()),
            "external image ref must be preserved verbatim in CopyInstruction.from",
        );
        assert_eq!(copy.sources, vec!["/uv".to_string()]);
        assert_eq!(copy.destination, "/usr/local/bin/uv".to_string());

        // The parser must NOT treat the external ref as a stage; only the
        // top-level `FROM alpine:3.18` should appear in the stage list.
        assert!(dockerfile.get_stage("ghcr.io/astral-sh/uv:0.5.0").is_none());
    }

    #[test]
    fn expand_from_args_all_forms() {
        let vars: HashMap<String, String> = [
            ("BASE".to_string(), "ghcr.io/org/img".to_string()),
            ("TAG".to_string(), "1.2".to_string()),
            ("EMPTY".to_string(), String::new()),
        ]
        .into_iter()
        .collect();

        assert_eq!(
            expand_from_args("${BASE}:${TAG}", &vars),
            "ghcr.io/org/img:1.2"
        );
        assert_eq!(expand_from_args("$BASE", &vars), "ghcr.io/org/img");
        assert_eq!(
            expand_from_args("img:${MISSING:-latest}", &vars),
            "img:latest"
        );
        assert_eq!(
            expand_from_args("img:${EMPTY:-fallback}", &vars),
            "img:fallback"
        );
        assert_eq!(expand_from_args("img:${TAG:+pinned}", &vars), "img:pinned");
        assert_eq!(expand_from_args("img:${MISSING:+pinned}", &vars), "img:");
        assert_eq!(expand_from_args("${MISSING}", &vars), "");
        // BuildKit `$$` escape yields a literal dollar; a trailing `$`
        // passes through.
        assert_eq!(expand_from_args("a$$b", &vars), "a$b");
        assert_eq!(expand_from_args("price$", &vars), "price$");
    }

    #[test]
    fn resolve_from_args_expands_from_lines() {
        let content = r"
ARG BASE_IMAGE=ghcr.io/org/alpine:latest
ARG BASE_TAG=latest
FROM ${BASE_IMAGE} AS builder
RUN echo hi
FROM ghcr.io/org/alpine:${BASE_TAG}
COPY --from=builder /x /x
";
        let mut dockerfile = Dockerfile::parse(content).unwrap();
        // Pre-resolution both FROM targets are (mis)classified as stages.
        assert!(dockerfile.stages[0].base_image.is_stage());
        assert!(dockerfile.stages[1].base_image.is_stage());

        let build_args: HashMap<String, String> = [("BASE_TAG".to_string(), "3.20".to_string())]
            .into_iter()
            .collect();
        dockerfile.resolve_from_args(&build_args);

        match &dockerfile.stages[0].base_image {
            DockerfileFromTarget::Image(r) => {
                assert_eq!(r.to_string(), "ghcr.io/org/alpine:latest");
            }
            other => panic!("stage 0 not resolved to an image: {other:?}"),
        }
        match &dockerfile.stages[1].base_image {
            DockerfileFromTarget::Image(r) => {
                // The build arg overrides the declared default.
                assert_eq!(r.to_string(), "ghcr.io/org/alpine:3.20");
            }
            other => panic!("stage 1 not resolved to an image: {other:?}"),
        }
    }

    #[test]
    fn resolve_from_args_keeps_stage_references() {
        let content = r"
ARG BASE=ghcr.io/org/alpine:latest
FROM ${BASE} AS builder
RUN echo hi
FROM builder
RUN echo again
";
        let mut dockerfile = Dockerfile::parse(content).unwrap();
        dockerfile.resolve_from_args(&HashMap::new());
        assert!(matches!(
            &dockerfile.stages[0].base_image,
            DockerfileFromTarget::Image(_)
        ));
        // `FROM builder` must stay a stage reference.
        assert_eq!(
            dockerfile.stages[1].base_image,
            DockerfileFromTarget::Stage("builder".to_string())
        );
    }

    #[test]
    fn test_parse_global_args() {
        let content = r#"
ARG BASE_IMAGE=alpine:3.18
FROM ${BASE_IMAGE}
RUN echo "hello"
"#;

        let dockerfile = Dockerfile::parse(content).unwrap();
        assert_eq!(dockerfile.global_args.len(), 1);
        assert_eq!(dockerfile.global_args[0].name, "BASE_IMAGE");
        assert_eq!(
            dockerfile.global_args[0].default,
            Some("alpine:3.18".to_string())
        );
    }

    #[test]
    fn test_get_stage_by_name() {
        let content = r#"
FROM alpine:3.18 AS base
RUN echo "base"

FROM base AS builder
RUN echo "builder"
"#;

        let dockerfile = Dockerfile::parse(content).unwrap();

        let base = dockerfile.get_stage("base");
        assert!(base.is_some());
        assert_eq!(base.unwrap().index, 0);

        let builder = dockerfile.get_stage("builder");
        assert!(builder.is_some());
        assert_eq!(builder.unwrap().index, 1);

        let stage_0 = dockerfile.get_stage("0");
        assert!(stage_0.is_some());
        assert_eq!(stage_0.unwrap().name, Some("base".to_string()));
    }

    #[test]
    fn test_final_stage() {
        let content = r#"
FROM alpine:3.18 AS builder
RUN echo "builder"

FROM scratch
COPY --from=builder /app /app
"#;

        let dockerfile = Dockerfile::parse(content).unwrap();
        let final_stage = dockerfile.final_stage().unwrap();

        assert_eq!(final_stage.index, 1);
        assert!(matches!(
            final_stage.base_image,
            DockerfileFromTarget::Scratch
        ));
    }

    #[test]
    fn test_parse_env_instruction() {
        let content = r"
FROM alpine
ENV FOO=bar BAZ=qux
";

        let dockerfile = Dockerfile::parse(content).unwrap();
        let stage = &dockerfile.stages[0];

        let env = stage
            .instructions
            .iter()
            .find(|i| matches!(i, Instruction::Env(_)));
        assert!(env.is_some());

        if let Some(Instruction::Env(e)) = env {
            assert_eq!(e.vars.get("FOO"), Some(&"bar".to_string()));
            assert_eq!(e.vars.get("BAZ"), Some(&"qux".to_string()));
        }
    }

    /// Extract the ARG instructions of a stage as (name, default) pairs.
    fn stage_args(stage: &Stage) -> Vec<(String, Option<String>)> {
        stage
            .instructions
            .iter()
            .filter_map(|i| {
                if let Instruction::Arg(a) = i {
                    Some((a.name.clone(), a.default.clone()))
                } else {
                    None
                }
            })
            .collect()
    }

    #[test]
    fn arg_empty_unquoted_default_parses_as_defined_empty() {
        // `cross` 0.2.5 generates `ARG CROSS_DEB_ARCH=` — Docker-valid
        // (defined, empty default), distinct from `ARG NAME` (no default).
        let content = "FROM alpine:3.18\nARG CROSS_DEB_ARCH=\n";
        let dockerfile = Dockerfile::parse(content).unwrap();
        assert_eq!(
            stage_args(&dockerfile.stages[0]),
            vec![("CROSS_DEB_ARCH".to_string(), Some(String::new()))],
        );
    }

    #[test]
    fn arg_empty_unquoted_default_parses_as_global_arg() {
        // Pre-FROM position: must land in `global_args` with a defined-empty
        // default so `resolve_from_args` sees "" rather than unset.
        let content = "ARG EMPTYDEFAULT=\nFROM alpine:3.18\n";
        let dockerfile = Dockerfile::parse(content).unwrap();
        assert_eq!(dockerfile.global_args.len(), 1);
        assert_eq!(dockerfile.global_args[0].name, "EMPTYDEFAULT");
        assert_eq!(dockerfile.global_args[0].default, Some(String::new()));
    }

    #[test]
    fn label_empty_unquoted_value_parses() {
        // Same upstream-grammar defect class as ARG/ENV (`label_value` needs
        // ≥1 char after `=`); the normalizer rewrites `LABEL k=` → `LABEL k=""`.
        let content = "FROM alpine:3.18\nLABEL emptyone= other=\"x\"\n";
        let dockerfile = Dockerfile::parse(content).unwrap();
        assert_eq!(dockerfile.stages.len(), 1);
    }

    #[test]
    fn arg_quoted_empty_default_parses_as_defined_empty() {
        let content = "FROM alpine:3.18\nARG NAME=\"\"\n";
        let dockerfile = Dockerfile::parse(content).unwrap();
        assert_eq!(
            stage_args(&dockerfile.stages[0]),
            vec![("NAME".to_string(), Some(String::new()))],
        );
    }

    #[test]
    fn arg_no_default_and_plain_default_still_parse() {
        let content = "FROM alpine:3.18\nARG X\nARG Y=z\n";
        let dockerfile = Dockerfile::parse(content).unwrap();
        assert_eq!(
            stage_args(&dockerfile.stages[0]),
            vec![
                ("X".to_string(), None),
                ("Y".to_string(), Some("z".to_string())),
            ],
        );
    }

    #[test]
    fn env_empty_values_parse() {
        // `ENV NAME=` and a trailing empty pair in a multi-pair ENV are both
        // Docker-valid (defined, empty).
        let content = "FROM alpine:3.18\nENV EMPTYONE=\nENV A= B=c\n";
        let dockerfile = Dockerfile::parse(content).unwrap();
        let stage = &dockerfile.stages[0];

        let envs: Vec<&EnvInstruction> = stage
            .instructions
            .iter()
            .filter_map(|i| {
                if let Instruction::Env(e) = i {
                    Some(e)
                } else {
                    None
                }
            })
            .collect();
        assert_eq!(envs.len(), 2);
        assert_eq!(envs[0].vars.get("EMPTYONE"), Some(&String::new()));
        assert_eq!(envs[1].vars.get("A"), Some(&String::new()));
        assert_eq!(envs[1].vars.get("B"), Some(&"c".to_string()));
    }

    #[test]
    fn env_quoted_value_containing_equals_is_untouched() {
        // The quoted `x= ` must not be rewritten by empty-assignment
        // normalization; only the trailing bare `B=` is.
        let content = "FROM alpine:3.18\nENV A=\"x= \" B=\n";
        let dockerfile = Dockerfile::parse(content).unwrap();
        let stage = &dockerfile.stages[0];
        if let Some(Instruction::Env(e)) = stage
            .instructions
            .iter()
            .find(|i| matches!(i, Instruction::Env(_)))
        {
            assert_eq!(e.vars.get("A"), Some(&"x= ".to_string()));
            assert_eq!(e.vars.get("B"), Some(&String::new()));
        } else {
            panic!("ENV instruction missing");
        }
    }

    #[test]
    fn run_shell_content_with_trailing_equals_is_untouched() {
        // A `KEY=` token inside RUN shell content (including on a
        // continuation line) is shell text — normalization must not
        // rewrite it into `KEY=""`.
        let content = "FROM alpine:3.18\nRUN export FOO= && \\\n    BAR= true\n";
        let dockerfile = Dockerfile::parse(content).unwrap();
        let stage = &dockerfile.stages[0];
        if let Some(Instruction::Run(run)) = stage
            .instructions
            .iter()
            .find(|i| matches!(i, Instruction::Run(_)))
        {
            let ShellOrExec::Shell(cmd) = &run.command else {
                panic!("expected shell-form RUN");
            };
            assert!(cmd.contains("FOO="), "cmd: {cmd}");
            assert!(!cmd.contains("FOO=\"\""), "cmd: {cmd}");
            assert!(cmd.contains("BAR="), "cmd: {cmd}");
            assert!(!cmd.contains("BAR=\"\""), "cmd: {cmd}");
        } else {
            panic!("RUN instruction missing");
        }
    }

    #[test]
    fn env_empty_value_on_continuation_line_parses() {
        let content = "FROM alpine:3.18\nENV A=1 \\\n    B=\n";
        let dockerfile = Dockerfile::parse(content).unwrap();
        let stage = &dockerfile.stages[0];
        if let Some(Instruction::Env(e)) = stage
            .instructions
            .iter()
            .find(|i| matches!(i, Instruction::Env(_)))
        {
            assert_eq!(e.vars.get("A"), Some(&"1".to_string()));
            assert_eq!(e.vars.get("B"), Some(&String::new()));
        } else {
            panic!("ENV instruction missing");
        }
    }

    #[test]
    fn normalize_empty_assignments_rewrites_only_arg_env() {
        // ARG / ENV empty assignments get the quoted-empty spelling.
        assert_eq!(normalize_empty_assignments("ARG A=\n"), "ARG A=\"\"\n");
        assert_eq!(
            normalize_empty_assignments("ENV A= B=c\n"),
            "ENV A=\"\" B=c\n"
        );
        // Quoted regions are skipped; only the bare trailing `B=` rewritten.
        assert_eq!(
            normalize_empty_assignments("ENV A=\"x= \" B=\n"),
            "ENV A=\"x= \" B=\"\"\n"
        );
        // Continuation lines of an ENV instruction are rewritten too.
        assert_eq!(
            normalize_empty_assignments("ENV A=1 \\\n    B=\n"),
            "ENV A=1 \\\n    B=\"\"\n"
        );
        // `KEY=\` (continuation directly after `=`) is left for the parser —
        // the value may continue on the next line.
        assert_eq!(
            normalize_empty_assignments("ARG A=\\\nx\n"),
            "ARG A=\\\nx\n"
        );
        // Non-ARG/ENV instructions and their continuation lines are verbatim.
        assert_eq!(
            normalize_empty_assignments("RUN export FOO= && \\\n    BAR= true\n"),
            "RUN export FOO= && \\\n    BAR= true\n"
        );
        // A keyword prefix is not enough — `ENVIRONMENT=` is not ENV.
        assert_eq!(
            normalize_empty_assignments("ENVIRONMENT= foo\n"),
            "ENVIRONMENT= foo\n"
        );
        // Untouched content comes back borrowed (no reallocation).
        assert!(matches!(
            normalize_empty_assignments("FROM alpine\nRUN echo hi\n"),
            std::borrow::Cow::Borrowed(_)
        ));
        // CRLF and a missing final newline are preserved.
        assert_eq!(
            normalize_empty_assignments("ARG A=\r\nARG B="),
            "ARG A=\"\"\r\nARG B=\"\""
        );
    }

    #[test]
    fn cross_generated_dockerfile_parses_end_to_end() {
        // Minimal mirror of the preamble `cross` 0.2.5 generates
        // (live failure: ZLayer build.yml run 19200 job 105756).
        let content = "FROM cross/x86_64-unknown-linux-musl:0.2.5\n\
                       ARG CROSS_DEB_ARCH=\n\
                       ARG CROSS_CMD\n\
                       RUN eval \"${CROSS_CMD}\"\n";
        let dockerfile = Dockerfile::parse(content).unwrap();
        assert_eq!(dockerfile.stages.len(), 1);

        let stage = &dockerfile.stages[0];
        assert_eq!(
            stage_args(stage),
            vec![
                ("CROSS_DEB_ARCH".to_string(), Some(String::new())),
                ("CROSS_CMD".to_string(), None),
            ],
        );
        assert!(stage
            .instructions
            .iter()
            .any(|i| matches!(i, Instruction::Run(_))));
    }
}