dockerfile-analyzer 0.3.25__tar.gz → 0.4.0__tar.gz

{dockerfile_analyzer-0.3.25 → dockerfile_analyzer-0.4.0}/Cargo.lock

@@ -14,7 +14,7 @@ dependencies = [
 
 [[package]]
 name = "dockerfile-analyzer"
-version = "0.3.25"
+version = "0.4.0"
 dependencies = [
  "docker-image",
  "parse-dockerfile",

{dockerfile_analyzer-0.3.25 → dockerfile_analyzer-0.4.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "dockerfile-analyzer"
-version = "0.3.25"
+version = "0.4.0"
 edition = "2024"
 readme = "README.md"
 

{dockerfile_analyzer-0.3.25 → dockerfile_analyzer-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dockerfile-analyzer
-Version: 0.3.25
+Version: 0.4.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 License-File: LICENSE

{dockerfile_analyzer-0.3.25 → dockerfile_analyzer-0.4.0}/README.md

@@ -10,9 +10,28 @@ This Python package analyzes a Dockerfile and returns detailed analysis informat
 - Instructions statistics
 - Environment variables, labels, and arguments
 - Exposed ports
+- A per-stage breakdown (`stages`, `final_stage_info`): each stage's base image, parent stage, `--platform`, and its own `ARG`, `ENV`, `LABEL`, `EXPOSE`, `USER`, and `WORKDIR` values
 
 Image references that contain `$` are not expanded. Other image references are lowercased. `EXPOSE` values are returned as written, including protocol suffixes and ranges. A later `ARG NAME` without a default keeps an earlier default.
 
+The top-level `args`, `env_vars`, `labels`, and `exposed_ports` are merged across all stages (and `args` also includes global `ARG`s declared before the first `FROM`), so a later stage's value for a key replaces an earlier one. To see which stage set what, use the per-stage breakdown described below.
+
+## Per-stage breakdown
+
+`analysis.stages` is a list of `Stage` objects in Dockerfile order. Each `Stage` has:
+
+| Attribute | Description |
+| --- | --- |
+| `index` | Zero-based position of the stage. |
+| `name` | The lowercased `AS` name, or `None` when the stage is unnamed. |
+| `base_image` | The `FROM` reference, normalized like `images` (lowercased unless it contains `$`). |
+| `parent_stage` | The name of the earlier stage this `FROM` builds on, or `None`. Docker only resolves earlier stages, so a name defined later, or an unknown name, is treated as an image and has no parent. |
+| `platform` | The `FROM --platform` value as written, or `None`. |
+| `args`, `env_vars`, `labels`, `exposed_ports` | Values set by this stage's own instructions. Global `ARG`s before the first `FROM` are not attributed to any stage, and nothing is inherited from a parent stage. |
+| `user`, `workdir` | The last `USER` and `WORKDIR` in this stage, or `None`. |
+
+`Stage` has `to_dict()` and a readable `repr()`. `analysis.final_stage_info` returns the last `Stage`, or `None` when there are no stages. The existing `analysis.final_stage` is unchanged and still returns only the last stage's name (or `None` when it is unnamed). `analysis.to_dict()` includes the stages under a `stages` key.
+
 The code leverages the highly useful Rust crates `parse-dockerfile` and `docker-image`.
 
 ## Example
@@ -88,6 +107,12 @@ print(analysis.final_stage)  # None
 # The second ARG VERSION has no default, so 1.0.0 is kept.
 print(analysis.args["VERSION"])  # 1.0.0
 
+# Per-stage values. Global ARGs before the first FROM belong to no stage.
+print(analysis.stages[0].args)  # {}
+print(analysis.stages[2].parent_stage)  # build
+final = analysis.final_stage_info
+print(final.index, final.user, final.exposed_ports)  # 4 nonroot ['8080/tcp', '9090/udp']
+
 print(json.dumps(analysis.to_dict(), indent=2))
 ```
 
@@ -99,6 +124,9 @@ ghcr.io
 ['debug']
 None
 1.0.0
+{}
+build
+4 nonroot ['8080/tcp', '9090/udp']
 
 ```json
 {
@@ -205,7 +233,84 @@ None
   },
   "env_vars": {
     "APP_VERSION": "$VERSION"
-  }
+  },
+  "stages": [
+    {
+      "index": 0,
+      "name": "tools",
+      "base_image": "alpine:${ALPINE_VERSION}",
+      "parent_stage": null,
+      "platform": null,
+      "args": {},
+      "env_vars": {},
+      "labels": {},
+      "exposed_ports": [],
+      "user": null,
+      "workdir": null
+    },
+    {
+      "index": 1,
+      "name": "build",
+      "base_image": "golang:${GO_VERSION}-alpine",
+      "parent_stage": null,
+      "platform": null,
+      "args": {},
+      "env_vars": {},
+      "labels": {},
+      "exposed_ports": [],
+      "user": null,
+      "workdir": "/src"
+    },
+    {
+      "index": 2,
+      "name": "assets",
+      "base_image": "build",
+      "parent_stage": "build",
+      "platform": null,
+      "args": {},
+      "env_vars": {},
+      "labels": {},
+      "exposed_ports": [],
+      "user": null,
+      "workdir": null
+    },
+    {
+      "index": 3,
+      "name": "debug",
+      "base_image": "alpine:${ALPINE_VERSION}",
+      "parent_stage": null,
+      "platform": null,
+      "args": {},
+      "env_vars": {},
+      "labels": {},
+      "exposed_ports": [],
+      "user": null,
+      "workdir": null
+    },
+    {
+      "index": 4,
+      "name": null,
+      "base_image": "gcr.io/distroless/static-debian12:nonroot@sha256:2c8e1f5d9a3b7e6c4d1f0a8b5e2c9d7f3a6b1c4e8d2f5a9b3c7e1d4f6a8b0c2e",
+      "parent_stage": null,
+      "platform": null,
+      "args": {
+        "VERSION": null
+      },
+      "env_vars": {
+        "APP_VERSION": "$VERSION"
+      },
+      "labels": {
+        "org.opencontainers.image.title": "app",
+        "org.opencontainers.image.version": "${VERSION}"
+      },
+      "exposed_ports": [
+        "8080/tcp",
+        "9090/udp"
+      ],
+      "user": "nonroot",
+      "workdir": null
+    }
+  ]
 }
 ```
 

{dockerfile_analyzer-0.3.25 → dockerfile_analyzer-0.4.0}/dockerfile_analyzer.pyi

@@ -19,6 +19,11 @@ def analyze_dockerfile(body: str) -> Analysis:
         when it is unnamed. A later ``ARG NAME`` without a value keeps an
         earlier default.
 
+        ``args``, ``labels``, ``env_vars``, and ``exposed_ports`` are merged
+        across all stages. ``stages`` lists each stage with the values it sets
+        itself, and ``final_stage_info`` is the last ``Stage`` (None when
+        there are no stages).
+
     Raises:
         ValueError: If the dockerfile content is empty or invalid
 
@@ -32,6 +37,16 @@ def analyze_dockerfile(body: str) -> Analysis:
 from typing import Dict, List, Optional, Any
 
 class Analysis:
+    """Analysis of one Dockerfile.
+
+    ``args``, ``labels``, ``env_vars``, and ``exposed_ports`` are merged across
+    all stages (``args`` also includes global ``ARG``s before the first
+    ``FROM``); a later stage's value for a key replaces an earlier one. Use
+    ``stages`` for the values each stage sets. ``final_stage`` is the last
+    stage's name (None when unnamed); ``final_stage_info`` is the last
+    ``Stage`` object, or None when there are no stages.
+    """
+
     num_stages: int
     images: List[Image]
     stage_names: List[str]
@@ -46,6 +61,33 @@ class Analysis:
     args: Dict[str, Optional[str]]
     labels: Dict[str, str]
     env_vars: Dict[str, str]
+    stages: List[Stage]
+
+    @property
+    def final_stage_info(self) -> Optional[Stage]: ...
+    def to_dict(self) -> Dict[str, Any]: ...
+    def __repr__(self) -> str: ...
+
+class Stage:
+    """One build stage, from its ``FROM`` line to the next ``FROM``.
+
+    Values are the stage's own. Nothing is inherited from a parent stage, and
+    global ``ARG``s declared before the first ``FROM`` are not attributed to
+    any stage. ``parent_stage`` is set only when ``FROM`` names an earlier
+    stage; a later or unknown name is treated as an image.
+    """
+
+    index: int
+    name: Optional[str]
+    base_image: str
+    parent_stage: Optional[str]
+    platform: Optional[str]
+    args: Dict[str, Optional[str]]
+    env_vars: Dict[str, str]
+    labels: Dict[str, str]
+    exposed_ports: List[str]
+    user: Optional[str]
+    workdir: Optional[str]
 
     def to_dict(self) -> Dict[str, Any]: ...
     def __repr__(self) -> str: ...

{dockerfile_analyzer-0.3.25 → dockerfile_analyzer-0.4.0}/src/analyzer.rs

@@ -24,6 +24,8 @@ struct InstructionFacts {
     args: BTreeMap<String, Option<String>>,
     labels: BTreeMap<String, String>,
     env_vars: BTreeMap<String, String>,
+    user: Option<String>,
+    workdir: Option<String>,
 }
 
 enum FromTarget {
@@ -35,7 +37,12 @@ pub fn analyze_dockerfile(body: &str) -> Result<models::Analysis, Box<dyn Error>
     let dockerfile = parse(body)?;
     let stages: Vec<_> = dockerfile.stages().collect();
     let stage_info = extract_stage_info(&stages);
-    let facts = collect_instructions(&dockerfile.instructions, &stage_info.ordered_names);
+    let facts = collect_instructions(&dockerfile.instructions, &stage_info.ordered_names, true);
+    let stage_details = stages
+        .iter()
+        .enumerate()
+        .map(|(index, stage)| build_stage(index, stage, &stage_info.ordered_names))
+        .collect();
     let multistage_analysis = analyze_multistage(
         stages.len(),
         &stage_info.images,
@@ -62,9 +69,43 @@ pub fn analyze_dockerfile(body: &str) -> Result<models::Analysis, Box<dyn Error>
         args: facts.args,
         labels: facts.labels,
         env_vars: facts.env_vars,
+        stages: stage_details,
     })
 }
 
+/// Describe one stage using only the instructions inside it.
+///
+/// The `FROM` instruction is not part of `stage.instructions`, so global
+/// `ARG`s before the first `FROM` never land in stage 0.
+fn build_stage(index: usize, stage: &Stage, ordered_names: &[Option<String>]) -> models::Stage {
+    let facts = collect_instructions(stage.instructions, ordered_names, false);
+    let base_image = normalize_image_ref(&stage.from.image.value);
+    let parent_stage = earlier_stage_named(&base_image, &ordered_names[..index]);
+    models::Stage {
+        index,
+        name: ordered_names[index].clone(),
+        base_image,
+        parent_stage,
+        platform: flag_value(&stage.from.options, constants::PLATFORM),
+        args: facts.args,
+        env_vars: facts.env_vars,
+        labels: facts.labels,
+        exposed_ports: facts.exposed_ports.into_iter().collect(),
+        user: facts.user,
+        workdir: facts.workdir,
+    }
+}
+
+/// Docker resolves a `FROM` name against earlier stages only. A name defined
+/// later, or not at all, is an image reference.
+fn earlier_stage_named(image: &str, earlier_names: &[Option<String>]) -> Option<String> {
+    earlier_names
+        .iter()
+        .flatten()
+        .find(|name| name.as_str() == image)
+        .cloned()
+}
+
 fn analyze_multistage(
     num_stages: usize,
     images: &BTreeSet<String>,
@@ -125,6 +166,7 @@ fn extract_stage_info(stages: &[Stage]) -> StageInfo {
 fn collect_instructions(
     instructions: &[Instruction],
     ordered_stage_names: &[Option<String>],
+    preserve_arg_defaults: bool,
 ) -> InstructionFacts {
     let mut facts = InstructionFacts {
         copy_from_stages: BTreeSet::new(),
@@ -137,6 +179,8 @@ fn collect_instructions(
         args: BTreeMap::new(),
         labels: BTreeMap::new(),
         env_vars: BTreeMap::new(),
+        user: None,
+        workdir: None,
     };
 
     for instruction in instructions {
@@ -146,10 +190,14 @@ fn collect_instructions(
 
         match instruction {
             Instruction::Arg(arg) => {
-                parse_utils::merge_kv_pairs(
-                    &mut facts.args,
-                    parse_utils::parse_kv_pairs(arg.arguments.value.as_ref(), false),
-                );
+                let pairs = parse_utils::parse_kv_pairs(arg.arguments.value.as_ref(), false);
+                if preserve_arg_defaults {
+                    // A later stage's bare `ARG NAME` redeclares a global default.
+                    parse_utils::merge_kv_pairs(&mut facts.args, pairs);
+                } else {
+                    // Inside one stage, a later bare `ARG NAME` clears the default.
+                    facts.args.extend(pairs);
+                }
             }
             Instruction::Env(env) => {
                 insert_required_values(
@@ -168,6 +216,12 @@ fn collect_instructions(
                     .exposed_ports
                     .extend(expose.arguments.iter().map(|port| port.value.to_string()));
             }
+            Instruction::User(user) => {
+                facts.user = Some(user.arguments.value.to_string());
+            }
+            Instruction::Workdir(workdir) => {
+                facts.workdir = Some(workdir.arguments.value.to_string());
+            }
             Instruction::Copy(copy) => {
                 record_from_flag(
                     &copy.options,
@@ -206,7 +260,7 @@ fn record_from_flag(
     stages: &mut BTreeSet<String>,
     images: &mut BTreeMap<String, models::Image>,
 ) {
-    let Some(raw) = from_flag_value(options) else {
+    let Some(raw) = flag_value(options, constants::FROM) else {
         return;
     };
     match resolve_from_target(&raw, ordered_stage_names) {
@@ -221,11 +275,11 @@ fn record_from_flag(
     }
 }
 
-fn from_flag_value(options: &[Flag]) -> Option<String> {
+fn flag_value(options: &[Flag], name: &str) -> Option<String> {
     options.iter().find_map(|flag| {
         flag.name
             .value
-            .eq_ignore_ascii_case(constants::FROM)
+            .eq_ignore_ascii_case(name)
             .then(|| flag.value.as_ref().map(|value| value.value.to_string()))
             .flatten()
     })
@@ -446,6 +500,31 @@ mod tests {
         }
     }
 
+    fn stage(
+        index: usize,
+        name: Option<&str>,
+        base_image: &str,
+        parent_stage: Option<&str>,
+    ) -> models::Stage {
+        models::Stage {
+            index,
+            name: name.map(str::to_string),
+            base_image: base_image.to_string(),
+            parent_stage: parent_stage.map(str::to_string),
+            platform: None,
+            args: BTreeMap::new(),
+            env_vars: BTreeMap::new(),
+            labels: BTreeMap::new(),
+            exposed_ports: vec![],
+            user: None,
+            workdir: None,
+        }
+    }
+
+    fn strings(values: &[&str]) -> Vec<String> {
+        values.iter().map(|value| value.to_string()).collect()
+    }
+
     #[test]
     fn test_multistage() {
         let dockerfile = r#"
@@ -557,6 +636,46 @@ CMD ["uvicorn", "--host", "0.0.0.0", "--port", "5000", "app.main:app"]"#;
             args,
             labels,
             env_vars,
+            stages: vec![
+                models::Stage {
+                    labels: BTreeMap::from([
+                        ("org.opencontainers.image.title".into(), "My App".into()),
+                        ("org.opencontainers.image.version".into(), "1.0".into()),
+                        (
+                            "org.opencontainers.image.authors".into(),
+                            "john@example.com".into(),
+                        ),
+                    ]),
+                    env_vars: BTreeMap::from([
+                        ("PYTHONPATH".into(), "/src".into()),
+                        ("PYTHONUNBUFFERED".into(), "1".into()),
+                        (
+                            "REQUESTS_CA_BUNDLE".into(),
+                            "/etc/ssl/certs/ca-certificates.crt".into(),
+                        ),
+                        ("PATH".into(), "/home/appuser/.local/bin:$PATH".into()),
+                    ]),
+                    workdir: Some("/src".into()),
+                    user: Some("root:root".into()),
+                    ..stage(
+                        0,
+                        Some("base"),
+                        "docker.abc.com/base-images/python:3.13-debian@sha256:55f1d15ef4c37870e23c03e89ad238940b55c8ede9f13fac4b7d71c7955f1053",
+                        None,
+                    )
+                },
+                models::Stage {
+                    user: Some("1000:1000".into()),
+                    ..stage(1, Some("test"), "base", Some("base"))
+                },
+                models::Stage {
+                    user: Some("1000:1000".into()),
+                    args: BTreeMap::from([("GIT_COMMIT".into(), None)]),
+                    env_vars: BTreeMap::from([("GIT_COMMIT".into(), "$GIT_COMMIT".into())]),
+                    exposed_ports: strings(&["5000"]),
+                    ..stage(2, None, "base", Some("base"))
+                },
+            ],
         };
 
         let res = analyze_dockerfile(dockerfile);
@@ -645,6 +764,13 @@ CMD ["npm", "start"]
             args: BTreeMap::new(),
             labels: BTreeMap::new(),
             env_vars: BTreeMap::from([("NODE_ENV".into(), "production".into())]),
+            stages: vec![models::Stage {
+                workdir: Some("/app".into()),
+                user: Some("nextjs".into()),
+                exposed_ports: strings(&["3000"]),
+                env_vars: BTreeMap::from([("NODE_ENV".into(), "production".into())]),
+                ..stage(0, None, "node:20-alpine", None)
+            }],
         };
         let res = analyze_dockerfile(dockerfile);
         assert!(res.is_ok());
@@ -765,6 +891,26 @@ CMD ["node", "server.js"]
             args: BTreeMap::new(),
             labels: BTreeMap::new(),
             env_vars: BTreeMap::new(),
+            stages: vec![
+                models::Stage {
+                    workdir: Some("/app".into()),
+                    ..stage(0, Some("dependencies"), "node:20-alpine", None)
+                },
+                models::Stage {
+                    workdir: Some("/app".into()),
+                    ..stage(1, Some("builder"), "node:20-alpine", None)
+                },
+                models::Stage {
+                    workdir: Some("/configs".into()),
+                    ..stage(2, Some("config-builder"), "alpine:3.18", None)
+                },
+                models::Stage {
+                    workdir: Some("/app".into()),
+                    user: Some("nextjs".into()),
+                    exposed_ports: strings(&["8080"]),
+                    ..stage(3, Some("production"), "node:20-alpine", None)
+                },
+            ],
         };
         let res = analyze_dockerfile(dockerfile);
         assert!(res.is_ok());
@@ -868,6 +1014,26 @@ CMD ["./app"]
             args: BTreeMap::new(),
             labels: BTreeMap::new(),
             env_vars: BTreeMap::new(),
+            stages: vec![
+                models::Stage {
+                    workdir: Some("/downloads".into()),
+                    ..stage(0, Some("downloader"), "alpine:3.18", None)
+                },
+                models::Stage {
+                    workdir: Some("/src".into()),
+                    ..stage(1, Some("go-builder"), "golang:1.21-alpine", None)
+                },
+                models::Stage {
+                    workdir: Some("/certs".into()),
+                    ..stage(2, Some("cert-generator"), "alpine:3.18", None)
+                },
+                models::Stage {
+                    workdir: Some("/app".into()),
+                    user: Some("appuser".into()),
+                    exposed_ports: strings(&["8080", "8443"]),
+                    ..stage(3, None, "alpine:3.18", None)
+                },
+            ],
         };
         let res = analyze_dockerfile(dockerfile);
         assert!(res.is_ok());
@@ -1115,4 +1281,223 @@ FROM ${REG}/library/ubuntu:${TAG:-22.04} AS build
         assert!(!rendered.contains("components=\"ImageComponents"));
         assert!(!rendered.contains("Some("));
     }
+
+    #[test]
+    fn test_stage_parent_resolves_only_earlier_stages() {
+        let dockerfile = r#"
+FROM alpine:3.20 AS Base
+FROM base AS child
+FROM later AS early
+FROM node:20 AS later
+FROM unknown-image
+FROM child
+"#;
+        let analysis = analyze_dockerfile(dockerfile).unwrap();
+        assert_eq!(
+            analysis.stages,
+            vec![
+                stage(0, Some("base"), "alpine:3.20", None),
+                stage(1, Some("child"), "base", Some("base")),
+                // `later` is defined after this stage, so it is an image.
+                stage(2, Some("early"), "later", None),
+                stage(3, Some("later"), "node:20", None),
+                stage(4, None, "unknown-image", None),
+                stage(5, None, "child", Some("child")),
+            ]
+        );
+        assert_eq!(analysis.num_stages, analysis.stages.len());
+    }
+
+    #[test]
+    fn test_stage_platform() {
+        let dockerfile = r#"
+FROM --platform=$BUILDPLATFORM golang:1.22 AS build
+FROM --platform=linux/amd64 alpine:3.20 AS runtime
+FROM scratch
+"#;
+        let analysis = analyze_dockerfile(dockerfile).unwrap();
+        let platforms: Vec<_> = analysis
+            .stages
+            .iter()
+            .map(|stage| stage.platform.clone())
+            .collect();
+        assert_eq!(
+            platforms,
+            vec![
+                Some("$BUILDPLATFORM".to_string()),
+                Some("linux/amd64".to_string()),
+                None
+            ]
+        );
+    }
+
+    #[test]
+    fn test_stage_scoped_values_and_merged_top_level() {
+        let dockerfile = r#"
+FROM golang:1.22 AS build
+ARG TARGETOS=linux
+ENV CGO_ENABLED=0 MODE=build
+LABEL stage="build"
+EXPOSE 6060
+WORKDIR /src
+USER builder
+WORKDIR /src/cmd
+
+FROM alpine:3.20
+ARG TARGETOS
+ENV MODE=runtime
+LABEL stage="runtime" org.opencontainers.image.title="app"
+EXPOSE 8080/tcp 9090/udp
+USER root
+USER 65532:65532
+"#;
+        let analysis = analyze_dockerfile(dockerfile).unwrap();
+        let build = &analysis.stages[0];
+        let runtime = &analysis.stages[1];
+
+        assert_eq!(
+            build.args,
+            BTreeMap::from([("TARGETOS".into(), Some("linux".into()))])
+        );
+        assert_eq!(
+            build.env_vars,
+            BTreeMap::from([
+                ("CGO_ENABLED".into(), "0".into()),
+                ("MODE".into(), "build".into()),
+            ])
+        );
+        assert_eq!(
+            build.labels,
+            BTreeMap::from([("stage".into(), "build".into())])
+        );
+        assert_eq!(build.exposed_ports, strings(&["6060"]));
+        assert_eq!(build.user.as_deref(), Some("builder"));
+        assert_eq!(build.workdir.as_deref(), Some("/src/cmd"));
+
+        assert_eq!(runtime.args, BTreeMap::from([("TARGETOS".into(), None)]));
+        assert_eq!(
+            runtime.env_vars,
+            BTreeMap::from([("MODE".into(), "runtime".into())])
+        );
+        assert_eq!(
+            runtime.labels,
+            BTreeMap::from([
+                ("org.opencontainers.image.title".into(), "app".into()),
+                ("stage".into(), "runtime".into()),
+            ])
+        );
+        assert_eq!(runtime.exposed_ports, strings(&["8080/tcp", "9090/udp"]));
+        assert_eq!(runtime.user.as_deref(), Some("65532:65532"));
+        assert_eq!(runtime.workdir, None);
+
+        // Top-level values stay merged across stages.
+        assert_eq!(
+            analysis.args,
+            BTreeMap::from([("TARGETOS".into(), Some("linux".into()))])
+        );
+        assert_eq!(
+            analysis.env_vars,
+            BTreeMap::from([
+                ("CGO_ENABLED".into(), "0".into()),
+                ("MODE".into(), "runtime".into()),
+            ])
+        );
+        assert_eq!(
+            analysis.labels,
+            BTreeMap::from([
+                ("org.opencontainers.image.title".into(), "app".into()),
+                ("stage".into(), "runtime".into()),
+            ])
+        );
+        assert_eq!(
+            analysis.exposed_ports,
+            strings(&["6060", "8080/tcp", "9090/udp"])
+        );
+    }
+
+    #[test]
+    fn test_global_args_are_not_attributed_to_first_stage() {
+        let dockerfile = r#"
+ARG VERSION=1
+ARG REGISTRY=docker.io
+FROM ${REGISTRY}/alpine:${VERSION} AS base
+RUN true
+
+FROM base
+ARG VERSION
+"#;
+        let analysis = analyze_dockerfile(dockerfile).unwrap();
+        assert!(analysis.stages[0].args.is_empty());
+        assert_eq!(
+            analysis.stages[0].base_image,
+            "${REGISTRY}/alpine:${VERSION}"
+        );
+        assert_eq!(
+            analysis.stages[1].args,
+            BTreeMap::from([("VERSION".into(), None)])
+        );
+        assert_eq!(
+            analysis.args,
+            BTreeMap::from([
+                ("REGISTRY".into(), Some("docker.io".into())),
+                ("VERSION".into(), Some("1".into())),
+            ])
+        );
+    }
+
+    #[test]
+    fn test_final_stage_info_is_last_stage() {
+        let dockerfile = r#"
+FROM golang:1.22 AS build
+FROM build AS release
+USER app
+"#;
+        let analysis = analyze_dockerfile(dockerfile).unwrap();
+        assert_eq!(analysis.final_stage, Some("release".to_string()));
+        assert_eq!(
+            analysis.final_stage_info(),
+            Some(models::Stage {
+                user: Some("app".into()),
+                ..stage(1, Some("release"), "build", Some("build"))
+            })
+        );
+
+        let unnamed = analyze_dockerfile("FROM alpine AS a\nFROM scratch\n").unwrap();
+        assert_eq!(unnamed.final_stage, None);
+        assert_eq!(
+            unnamed.final_stage_info(),
+            Some(stage(1, None, "scratch", None))
+        );
+    }
+
+    #[test]
+    fn test_final_stage_info_without_stages_is_none() {
+        let mut analysis = analyze_dockerfile("FROM alpine\n").unwrap();
+        analysis.stages.clear();
+        assert_eq!(analysis.final_stage_info(), None);
+    }
+
+    #[test]
+    fn test_bare_arg_in_same_stage_clears_default() {
+        let dockerfile = "FROM alpine\nARG VERSION=1\nARG VERSION\n";
+        let analysis = analyze_dockerfile(dockerfile).unwrap();
+        assert_eq!(
+            analysis.stages[0].args,
+            BTreeMap::from([("VERSION".into(), None)])
+        );
+        assert_eq!(
+            analysis.args,
+            BTreeMap::from([("VERSION".into(), Some("1".into()))])
+        );
+    }
+
+    #[test]
+    fn test_stage_repr_uses_python_none() {
+        let analysis = analyze_dockerfile("FROM alpine\nARG VERSION\n").unwrap();
+        assert_eq!(
+            analysis.stages[0].repr(),
+            "Stage(index=0, name=None, base_image=\"alpine\", parent_stage=None, platform=None, args={\"VERSION\": None}, env_vars={}, labels={}, exposed_ports=[], user=None, workdir=None)"
+        );
+        assert!(!analysis.repr().contains("Stage("));
+    }
 }

{dockerfile_analyzer-0.3.25 → dockerfile_analyzer-0.4.0}/src/constants.rs

@@ -11,6 +11,7 @@ pub const HEALTHCHECK: &str = "HEALTHCHECK";
 pub const LABEL: &str = "LABEL";
 pub const MAINTAINER: &str = "MAINTAINER";
 pub const ONBUILD: &str = "ONBUILD";
+pub const PLATFORM: &str = "platform";
 pub const RUN: &str = "RUN";
 pub const SHELL: &str = "SHELL";
 pub const STOPSIGNAL: &str = "STOPSIGNAL";

{dockerfile_analyzer-0.3.25 → dockerfile_analyzer-0.4.0}/src/lib.rs

@@ -22,6 +22,10 @@ Returns:
     only; `final_stage` is the last stage name, or None when it is unnamed.
     A later `ARG NAME` without a value keeps an earlier default.
 
+    `args`, `labels`, `env_vars`, and `exposed_ports` are merged across all
+    stages. `stages` lists each stage with the values it sets itself, and
+    `final_stage_info` is the last `Stage` (None when there are no stages).
+
 Raises:
     ValueError: If the dockerfile content is empty or invalid
 
@@ -47,5 +51,6 @@ fn dockerfile_analyzer(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<models::Image>()?;
     m.add_class::<models::ImageComponents>()?;
     m.add_class::<models::InstructionStats>()?;
+    m.add_class::<models::Stage>()?;
     Ok(())
 }

{dockerfile_analyzer-0.3.25 → dockerfile_analyzer-0.4.0}/src/models.rs

@@ -181,6 +181,98 @@ impl MultistageAnalysis {
     }
 }
 
+#[pyclass(skip_from_py_object)]
+#[doc = "One build stage, from its `FROM` line to the next `FROM`.
+
+Values are the stage's own, as written in that stage. Nothing is inherited
+from a parent stage, and global `ARG`s declared before the first `FROM` are
+not attributed to any stage.
+
+Attributes:
+    index (int): Zero-based position of the stage in the Dockerfile.
+    name (str | None): The lowercased `AS` name, or None when unnamed.
+    base_image (str): The `FROM` reference. It is lowercased unless it
+        contains `$`, matching `Analysis.images`.
+    parent_stage (str | None): The name of the earlier stage this `FROM`
+        builds on, or None. Only earlier stages are matched, as in Docker; a
+        name defined later, or any other name, is treated as an image.
+    platform (str | None): The `--platform` value as written, or None.
+    args (dict[str, str | None]): `ARG`s declared in this stage. A
+        redeclaration without a default is None here.
+    env_vars (dict[str, str]): `ENV` values set in this stage.
+    labels (dict[str, str]): `LABEL` values set in this stage.
+    exposed_ports (list[str]): `EXPOSE` tokens in this stage, sorted.
+    user (str | None): The last `USER` in this stage, or None.
+    workdir (str | None): The last `WORKDIR` in this stage, or None.
+"]
+#[derive(Debug, PartialEq, Clone)]
+pub struct Stage {
+    #[pyo3(get)]
+    pub index: usize,
+    #[pyo3(get)]
+    pub name: Option<String>,
+    #[pyo3(get)]
+    pub base_image: String,
+    #[pyo3(get)]
+    pub parent_stage: Option<String>,
+    #[pyo3(get)]
+    pub platform: Option<String>,
+    #[pyo3(get)]
+    pub args: BTreeMap<String, Option<String>>,
+    #[pyo3(get)]
+    pub env_vars: BTreeMap<String, String>,
+    #[pyo3(get)]
+    pub labels: BTreeMap<String, String>,
+    #[pyo3(get)]
+    pub exposed_ports: Vec<String>,
+    #[pyo3(get)]
+    pub user: Option<String>,
+    #[pyo3(get)]
+    pub workdir: Option<String>,
+}
+
+impl Stage {
+    pub fn repr(&self) -> String {
+        self.__repr__()
+    }
+}
+
+#[pymethods]
+impl Stage {
+    fn __repr__(&self) -> String {
+        format!(
+            "Stage(index={}, name={}, base_image={:?}, parent_stage={}, platform={}, args={}, env_vars={:?}, labels={:?}, exposed_ports={:?}, user={}, workdir={})",
+            self.index,
+            fmt_opt(&self.name),
+            self.base_image,
+            fmt_opt(&self.parent_stage),
+            fmt_opt(&self.platform),
+            fmt_opt_map(&self.args),
+            self.env_vars,
+            self.labels,
+            self.exposed_ports,
+            fmt_opt(&self.user),
+            fmt_opt(&self.workdir)
+        )
+    }
+
+    fn to_dict(&self, py: Python) -> PyResult<Py<PyAny>> {
+        let dict = PyDict::new(py);
+        dict.set_item("index", self.index)?;
+        dict.set_item("name", &self.name)?;
+        dict.set_item("base_image", &self.base_image)?;
+        dict.set_item("parent_stage", &self.parent_stage)?;
+        dict.set_item("platform", &self.platform)?;
+        dict.set_item("args", &self.args)?;
+        dict.set_item("env_vars", &self.env_vars)?;
+        dict.set_item("labels", &self.labels)?;
+        dict.set_item("exposed_ports", &self.exposed_ports)?;
+        dict.set_item("user", &self.user)?;
+        dict.set_item("workdir", &self.workdir)?;
+        Ok(dict.into())
+    }
+}
+
 #[pyclass(skip_from_py_object)]
 #[doc = "Analysis of one Dockerfile.
 
@@ -199,6 +291,13 @@ in-range index of an unnamed stage, the index is reported in place of a name.
 images are `copy_from_images` and `add_from_images`. A `--from` value that
 names a stage, or an in-range stage index, is a stage reference rather than
 an image.
+
+`args`, `labels`, `env_vars`, and `exposed_ports` are merged across all
+stages (and, for `args`, global `ARG`s before the first `FROM`); a later
+stage's value for a key replaces an earlier one. Use `stages` for the values
+each stage sets. `stages` lists every stage in Dockerfile order.
+`final_stage_info` is the last `Stage`, or None when there are no stages;
+`final_stage` keeps returning only the last stage's name.
 "]
 #[derive(Debug, PartialEq, Clone)]
 pub struct Analysis {
@@ -230,6 +329,8 @@ pub struct Analysis {
     pub labels: BTreeMap<String, String>,
     #[pyo3(get)]
     pub env_vars: BTreeMap<String, String>,
+    #[pyo3(get)]
+    pub stages: Vec<Stage>,
 }
 
 impl Analysis {
@@ -240,6 +341,11 @@ impl Analysis {
 
 #[pymethods]
 impl Analysis {
+    #[getter]
+    pub fn final_stage_info(&self) -> Option<Stage> {
+        self.stages.last().cloned()
+    }
+
     fn __repr__(&self) -> String {
         let images = join_images(&self.images);
         let copy_from_images = join_images(&self.copy_from_images);
@@ -282,6 +388,12 @@ impl Analysis {
         dict.set_item("args", &self.args)?;
         dict.set_item("labels", &self.labels)?;
         dict.set_item("env_vars", &self.env_vars)?;
+        let stages = self
+            .stages
+            .iter()
+            .map(|stage| stage.to_dict(py))
+            .collect::<PyResult<Vec<_>>>()?;
+        dict.set_item("stages", stages)?;
         Ok(dict.into())
     }
 }

dockerfile_analyzer-0.4.0/tests/test_stages.py

@@ -0,0 +1,192 @@
+"""Tests for the per-stage breakdown (Analysis.stages and final_stage_info)."""
+
+from pathlib import Path
+
+import dockerfile_analyzer as da
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+STAGE_KEYS = {
+    "index",
+    "name",
+    "base_image",
+    "parent_stage",
+    "platform",
+    "args",
+    "env_vars",
+    "labels",
+    "exposed_ports",
+    "user",
+    "workdir",
+}
+
+
+def test_multistage_fixture_stages():
+    analysis = da.analyze_dockerfile((FIXTURES / "multistage.Dockerfile").read_text())
+    base, test, final = analysis.stages
+
+    assert [stage.index for stage in analysis.stages] == [0, 1, 2]
+    assert [stage.name for stage in analysis.stages] == ["base", "test", None]
+    assert base.base_image.startswith("docker.abc.com/base-images/python:3.13-debian@")
+    assert base.parent_stage is None
+    assert test.base_image == "base"
+    assert test.parent_stage == "base"
+    assert final.parent_stage == "base"
+
+    assert base.labels["org.opencontainers.image.title"] == "My App"
+    assert base.env_vars["PYTHONPATH"] == "/src"
+    assert "GIT_COMMIT" not in base.env_vars
+    assert base.workdir == "/src"
+    assert base.user == "root:root"
+
+    assert test.env_vars == {}
+    assert test.labels == {}
+    assert test.user == "1000:1000"
+    assert test.workdir is None
+
+    assert final.args == {"GIT_COMMIT": None}
+    assert final.env_vars == {"GIT_COMMIT": "$GIT_COMMIT"}
+    assert final.exposed_ports == ["5000"]
+    assert final.platform is None
+
+    # Top-level values remain merged across stages.
+    assert set(analysis.env_vars) == set(base.env_vars) | set(final.env_vars)
+    assert analysis.final_stage is None
+    assert analysis.final_stage_info.to_dict() == final.to_dict()
+
+
+def test_parent_stage_only_resolves_earlier_stages():
+    dockerfile = """\
+FROM alpine:3.20 AS Base
+FROM base AS child
+FROM later AS early
+FROM node:20 AS later
+FROM unknown-image
+FROM child
+"""
+    stages = da.analyze_dockerfile(dockerfile).stages
+
+    assert [(s.name, s.base_image, s.parent_stage) for s in stages] == [
+        ("base", "alpine:3.20", None),
+        ("child", "base", "base"),
+        ("early", "later", None),
+        ("later", "node:20", None),
+        (None, "unknown-image", None),
+        (None, "child", "child"),
+    ]
+
+
+def test_platform_per_stage():
+    dockerfile = """\
+FROM --platform=$BUILDPLATFORM golang:1.22 AS build
+FROM --platform=linux/amd64 alpine:3.20
+"""
+    stages = da.analyze_dockerfile(dockerfile).stages
+    assert [s.platform for s in stages] == ["$BUILDPLATFORM", "linux/amd64"]
+
+
+def test_per_stage_values_and_overrides():
+    dockerfile = """\
+FROM golang:1.22 AS build
+ARG TARGETOS=linux
+ENV MODE=build
+LABEL stage=build
+EXPOSE 6060
+WORKDIR /src
+WORKDIR /src/cmd
+USER builder
+
+FROM alpine:3.20
+ENV MODE=runtime
+LABEL stage=runtime
+EXPOSE 8080/tcp
+USER root
+USER 65532
+"""
+    analysis = da.analyze_dockerfile(dockerfile)
+    build, runtime = analysis.stages
+
+    assert build.args == {"TARGETOS": "linux"}
+    assert build.env_vars == {"MODE": "build"}
+    assert build.labels == {"stage": "build"}
+    assert build.exposed_ports == ["6060"]
+    assert build.workdir == "/src/cmd"
+    assert build.user == "builder"
+
+    assert runtime.args == {}
+    assert runtime.env_vars == {"MODE": "runtime"}
+    assert runtime.labels == {"stage": "runtime"}
+    assert runtime.exposed_ports == ["8080/tcp"]
+    assert runtime.workdir is None
+    assert runtime.user == "65532"
+
+    assert analysis.env_vars == {"MODE": "runtime"}
+    assert analysis.labels == {"stage": "runtime"}
+    assert analysis.exposed_ports == ["6060", "8080/tcp"]
+    assert analysis.args == {"TARGETOS": "linux"}
+
+
+def test_global_args_not_attributed_to_first_stage():
+    dockerfile = """\
+ARG VERSION=1
+FROM alpine:${VERSION} AS base
+FROM base
+ARG VERSION
+"""
+    analysis = da.analyze_dockerfile(dockerfile)
+    assert analysis.stages[0].args == {}
+    assert analysis.stages[1].args == {"VERSION": None}
+    assert analysis.args == {"VERSION": "1"}
+
+
+def test_bare_arg_in_same_stage_clears_default():
+    analysis = da.analyze_dockerfile("FROM alpine\nARG VERSION=1\nARG VERSION\n")
+    assert analysis.stages[0].args == {"VERSION": None}
+    assert analysis.args == {"VERSION": "1"}
+
+
+def test_final_stage_info_and_final_stage_name():
+    analysis = da.analyze_dockerfile("FROM golang:1.22 AS build\nFROM build AS release\n")
+    assert analysis.final_stage == "release"
+    final = analysis.final_stage_info
+    assert isinstance(final, da.Stage)
+    assert final.index == 1
+    assert final.name == "release"
+    assert final.parent_stage == "build"
+
+
+def test_to_dict_adds_only_stages_key():
+    analysis = da.analyze_dockerfile((FIXTURES / "multistage.Dockerfile").read_text())
+    data = analysis.to_dict()
+
+    assert list(data) == [
+        "num_stages",
+        "images",
+        "stage_names",
+        "final_stage",
+        "copy_from_stages",
+        "add_from_stages",
+        "copy_from_images",
+        "add_from_images",
+        "multistage_analysis",
+        "exposed_ports",
+        "instructions",
+        "args",
+        "labels",
+        "env_vars",
+        "stages",
+    ]
+    assert len(data["stages"]) == 3
+    assert all(set(stage) == STAGE_KEYS for stage in data["stages"])
+    assert data["stages"][2] == analysis.stages[2].to_dict()
+    assert data["stages"][1]["parent_stage"] == "base"
+    assert data["stages"][2]["name"] is None
+
+
+def test_stage_repr():
+    stage = da.analyze_dockerfile("FROM alpine\nARG VERSION\n").stages[0]
+    assert repr(stage) == (
+        'Stage(index=0, name=None, base_image="alpine", parent_stage=None, '
+        'platform=None, args={"VERSION": None}, env_vars={}, labels={}, '
+        "exposed_ports=[], user=None, workdir=None)"
+    )