NewStages(): "only allow header args" (dc7bc4f) also drops ARGs declared between stages, breaking a documented-valid Dockerfile pattern

先阅读 NewStages() 和 extractHeadingArgsFromNode，然后重现一个在各 stage 之间包含 ARG 的 Dockerfile 示例，并将其与在第一个 FROM 之前包含相同 ARG 的示例进行比较。跟踪现有的 stage 和 heading-argument 处理；完成的标准是 stage 局部的 ARG 保持隔离，同时放置在 stage 之间的 ARG 能解析后续的 FROM，并且文档中描述的行为有测试覆盖。

Description

Commit dc7bc4f ("NewStages(): only allow header args", first released in v1.2.12) narrowed the set of ARGs considered "globally allowed" for resolving a stage's FROM from every ARG declared anywhere in the file down to only ARGs appearing before the very first FROM (via extractHeadingArgsFromNode, which permanently stops collecting once it sees the first FROM).

Besides the stated goal ("the full set of ARGs declared in every stage" was too permissive), it seems to have a side effect: an ARG declared between two stages, after an earlier stage's body, but before a later stage's FROM, is no longer available to resolve that later FROM. That placement is not the same as a stage-local ARG; it's the documented Docker/BuildKit pattern for parameterizing a later stage's base image without hoisting the ARG to the very top of the file:

[An ARG] declared before a FROM ... can be used in any FROM instruction in the build.
(Docker docs, "Understand how ARG and FROM interact")

Docker's wording says "before a FROM," not "before the first FROM", i.e. it documents exactly the pattern this commit stopped supporting.

Reproduction

FROM scratch AS config
COPY somefile /build/

ARG UPSTREAM_IMAGE
FROM ${UPSTREAM_IMAGE} AS base

RUN echo "base stage ran"

Building this with buildah bud --build-arg UPSTREAM_IMAGE=busybox ... (buildah ≥1.37, i.e. imagebuilder ≥1.2.12) fails: ${UPSTREAM_IMAGE} in the second FROM resolves to empty, and the caller (buildah) reports "no FROM statement found" because the resulting FROM line is blank. Moving the identical ARG UPSTREAM_IMAGE line above the first FROM fixes it with no other change. Ruled out as a factor: default values on the ARG, --build-arg presence, whether the earlier stage's output is consumed downstream, buildah's --skip-unused-stages, rootless vs rootful, storage driver. Full bisection and analysis (across buildah v1.29–v1.43) in the companion issue: containers/buildah#7016.

Ask

Could NewStages()/extractHeadingArgsFromNode be adjusted to keep collecting ARG nodes that appear between stages (i.e., outside of any stage's own body, at the top level of the file) rather than stopping for good at the first FROM? That would preserve the original commit's goal, stage-local ARGs (declared after a FROM, inside a stage) still wouldn't leak to later stages, while restoring the documented "ARG before the FROM that uses it" pattern.

If the current, stricter behavior is intentional, it'd be worth a changelog/release-notes callout, since right now it fails silently with a message that gives no hint the cause is ARG placement.

Environment

Observed via buildah (which vendors this library): v1.37.0 through v1.45.0 all reproduce; v1.36.0 (imagebuilder v1.2.9) does not.