Module dockerfile 

Typed border for a REGULAR Dockerfile (BuildKit-syntax, not a Nix derivation) digested into a content-addressed derivation graph.

Sui-spec proves it can consume plain Dockerfiles without rewriting them: a hand-rolled instruction-line parser scoped to exactly the instruction set below produces a typed DockerfileGraph whose node hashes are computed the same way crate::hash and crate::derivation compute nix store-path hashes – a function of (instruction-kind, prior-layer-digest, resolved-build-arg-values). Two runs over identical input produce hash-identical graphs; changing one instruction’s content invalidates only that node and its downstream dependents.

Scope (deliberately narrow)

Supported instructions: FROM, RUN (incl. --mount=type=bind), COPY (incl. --from=<stage>), ARG (incl. default values), ENV, WORKDIR, CMD, ENTRYPOINT, VOLUME (plain or JSON-array form). ARG TARGETARCH is resolved from the environment’s build-arg map like any other ARG. Multi-stage FROM ... AS <alias> aliasing beyond the --from= reference on COPY, full BuildKit heredoc syntax, and ARG default-value precedence beyond “declared default, overridden by environment” are explicitly OUT OF SCOPE for this phase (see the module-level doc on the missing pieces, or the phase report).

Authoring surface

(defdockerfile-graph
  :name        "simple-three-instruction"
  :description "..."
  :source-text "FROM debian:bookworm-slim\nRUN ...\nCMD [...]\n")

Structs

DockerfileArgs

Inputs to a dockerfile-graph run. path is passed to DockerfileEnvironment::read_dockerfile; for the canonical- instance tests it is conventionally the spec’s name.

DockerfileGraph

The full parsed + hashed graph — a linear chain (Dockerfile instructions execute strictly top-to-bottom; no branching), so “graph” here is a hash-linked list, the same shape a derivation’s input closure takes at each single-output layer.

DockerfileGraphSpec

One canonical (defdockerfile-graph ...) instance. source_text is the raw Dockerfile text the interpreter parses; canonical instances exist so the graph-build algorithm has a fixed corpus to prove determinism + cache-leverage against.

DockerfileNode

One node in the content-addressed build graph. content_hash is BLAKE3 over (kind, prior_layer_digest, resolved_build_arg_values, instruction_content_bytes) — reusing crate::hash’s BLAKE3 convention (the same primitive lockfile_graph/ast_graph use for their content-addressed forms).

MockDockerfileEnvironment

In-memory mock environment for tests. Pre-load Dockerfile text by path + build-arg values by name.

Enums

DockerfileInstruction

One parsed Dockerfile instruction. Bad states (a COPY with no source, an ARG reference that never resolves) are rejected at parse time via SpecError::Interp — never silently accepted.

InstructionKind

Which instruction kind a node represents — the coarse key used in the node’s content hash alongside its resolved argument bytes.

Constants

CANONICAL_DOCKERFILE_LISP

Traits

DockerfileEnvironment

Abstract IO environment for the dockerfile interpreter. The only side effect this domain performs is reading Dockerfile text and resolving build-arg values from environment — both behind this trait so tests use a mock and production wraps real filesystem/env access.

Functions

apply

Parse + content-address a Dockerfile into its typed DockerfileGraph.

apply_canonical

Convenience wrapper: run apply against a canonical instance’s own source_text, via a MockDockerfileEnvironment pre-loaded with that text under its own name as the path.

load_canonical

Compile every authored (defdockerfile-graph ...) instance.

load_named

Return the canonical instance whose name matches.