Fix #22602: targets in extra_build_args

[ademariag]

Summary

• Fix docker_build_args with Target References not working #22602
• Fixed Docker image target references not being resolved when passed via extra_build_args in BUILD files
• Modified DockerBuildContext.create() to consistently use merged build args (including extra_build_args) for both interpolation context and Dockerfile stage parsing
• Added comprehensive test coverage for scenarios where extra_build_args override default ARG values in Dockerfiles

Problem

Previously, when using target references like :base-image in extra_build_args, Pants failed to resolve these to actual Docker image tags during build context creation. This prevented users from creating hierarchical Docker image dependencies and dynamic base image selection.

Solution

The fix ensures that extra_build_args from BUILD files are properly merged and made available during all phases of build context creation, particularly when parsing Dockerfile stages that contain FROM instructions with variable substitution.

Test Coverage

Added test_from_image_build_arg_with_extra_build_args() which validates:

• Default build args can be overridden via extra_build_args
• Target references in extra_build_args resolve to proper image tags
• Multiple downstream images can reference different base images via build arg overrides

[benjyw]

I haven't forgotten about this, will try and get to it this weekend.

[benjyw]

Meanwhile the CI test failures look meaningful.

[benjyw]

Thanks for the fix!

Having paged some of this backend into my brain, this seems right. But see my question, which will help me understand this better.

[benjyw]

This change is quite subtle, so help me understand something...

This seems to be the critical line, where it's important for some reason that merged_build_args_with_extensions is not converted to a DockerBuildArgsInterpolationValue. Why does this fix the issue?

[ademariag]

Candidly confessing I asked Claude Code :)

The Problem:

When InterpolationContext.from_dict(interpolation_context) is called on line 168, it processes all values through the create_value() method from value_interpolation.py:45-49:

def create_value(value: str | Mapping[str, str]) -> str | InterpolationValue:
    if isinstance(value, (str, InterpolationValue)):
        return value  # Already wrapped, keep as-is
    return InterpolationValue(value)  # Plain dict, wrap in generic InterpolationValue

The Fix:

Lines 145-147: Wraps the dict in DockerBuildArgsInterpolationValue and stores it in the interpolation context
Line 158: Passes the unwrapped dict to _get_stages_and_tags() (which only needs the raw data)
Line 168: When from_dict() processes the interpolation context, it checks each value with isinstance(value, InterpolationValue).

Since DockerBuildArgsInterpolationValue is already an InterpolationValue subclass, it's preserved as-is rather than being re-wrapped in a generic InterpolationValue

Why it matters:

DockerBuildArgsInterpolationValue provides custom error messages via its _attribute_error_type, which helps users understand missing build args.

If it got replaced by a generic InterpolationValue, users would get less helpful error messages.

The subtlety

Passing the unwrapped dict to line 146 (instead of the DockerBuildArgsInterpolationValue wrapper) ensures the wrapper survives the from_dict() call on line 168, because from_dict() only checks isinstance(value, InterpolationValue) and preserves objects that are already InterpolationValue instances.

[benjyw]

I don't think that answers my question... To clarify: How is merged_build_args_with_extensions different from interpolation_context["build_args"] and why does that matter?

[benjyw]

My previous comment was that you appear to have stomped on the functionality that should_suggest_renames provides. Restoring it in the signature is not enough...

Was this change handwritten or claude code generated?

[benjyw]

I don't think that answers my question... To clarify: How is merged_build_args_with_extensions different from interpolation_context["build_args"] and why does that matter?