[reteps]

Summary

dockerfmt could turn a working Dockerfile into one that no longer builds (or builds something different). This PR fixes every open issue of that kind and changes the design so the class of bug can't silently recur.

1. Semantic guard (lib/semantic.go)

After formatting each instruction, the output is parsed again with BuildKit and compared with BuildKit's reading of the original. The comparison covers:

• ENV/LABEL/ARG values as BuildKit expands them
• COPY/ADD sources and destinations
• flags and exec arrays
• heredoc contents
• shell commands, compared in a whitespace-insensitive canonical form

If anything differs, or the formatter panics, the instruction is emitted exactly as written and a warning goes to stderr (Dockerfile:12: left unformatted: ...). The fixture test fails on any fallback, so the guard can't hide regressions.

Cost: the wasm grows from 7.35 to 7.74 MB, or from 2.01 to 2.12 MB gzipped.

2. RUN/CMD shell pipeline rewritten without regexes (lib/shell.go)

• Old pipeline: comments were disguised as backtick command substitutions for shfmt, regexes moved && around them, more regexes undid it, and two regexes decided when to give up.
• New pipeline: each physical line is classified as code, comment, blank, or \-only. Only the code goes to mvdan/sh. Comments and separators are put back by walking the source and output syntax trees in parallel, so every line is anchored to the token after it.
• Placement: a comment the user indented past the next command stays with the previous one (e.g. under an argument list).
• Unchanged output: every pre-existing fixture formats exactly as before.

3. Decisions taken from BuildKit's parse tree

JSON form, heredocs, SHELL and flags are no longer guessed by re-parsing text. The custom JSON decoder and the google/shlex dependency are gone.

Issues fixed

• Preserve empty continuation lines (backslash-only separator lines) in RUN #59 Empty continuation lines (\) and comments among RUN flags are preserved. The first commit here is fix(run): preserve empty continuation lines and comments among flags #82.
• Legacy ENV key value with a multi-word value becomes an invalid key=value #69 Legacy ENV key value with spaces is quoted. This is fix(env): quote legacy ENV values that contain spaces #74 by @RyoKusnadi, merged in.
• MAINTAINER to LABEL conversion does not escape embedded quotes #70 MAINTAINER → LABEL escapes quotes and backslashes (fix(format): escape quotes and backslashes when converting MAINTAINER to LABEL #75 by @RyoKusnadi, merged in), plus $, because LABEL expands variables.
• COPY/ADD JSON form is rewritten to shell form even when paths contain spaces #71 COPY/ADD keep the JSON form when an argument contains whitespace.
• RUN is formatted as POSIX shell after SHELL switches to PowerShell or cmd #72 After SHELL selects a non-POSIX shell (pwsh, cmd), shell bodies are left as written until the next FROM.
• CRLF input produces mixed line endings #73 CRLF files stay CRLF consistently.
• Second heredoc in one instruction is dropped #76 Every heredoc in an instruction is kept.
• Blank line inside a RUN continuation splits it into a new instruction #77 A blank line inside a continuation no longer splits the instruction.
• Continuation lines inside a quoted ENV/LABEL/ARG value are indented, changing the value #78 Continuation lines inside quoted ENV/LABEL/ARG values keep their whitespace.
• Invalid JSON in CMD is rewritten to exec form #79 Arguments that aren't valid JSON (["a",]) stay shell form.
• Heredoc fed to a non-shell interpreter panics #80 Only heredocs the shell runs as a script are formatted. Bodies fed to python and similar programs, or with a non-shell shebang, are data.
• UTF-16 Dockerfile produces empty output with exit code 0 #81 Non-UTF-8 input (e.g. UTF-16 from PowerShell) is rejected with an error and the file is left untouched. New API: lib.Format(content, config) (string, error). JS rejects with an Error.

Other bugs found by the guard and fixed here

• An instruction with no formatter, such as a misspelled keyword, was deleted. --write removed it from the file.
• COPY/ADD with a heredoc dropped their flags, so COPY --chmod=755 <<EOF lost --chmod. Found in BuildKit's own Dockerfile.
• CMD JSON form dropped flags, and COPY dropped a -- end-of-flags marker.
• Three panics, and five outputs that no longer parsed, on BuildKit's parser test files.

Fixture changes

• run5: keeps its \ separator line, as Preserve empty continuation lines (backslash-only separator lines) in RUN #59 asks.
• label: the quoted multi-line QLC_DEPENDS value keeps its original indentation. The old expected output re-indented it, which changed the value (Continuation lines inside a quoted ENV/LABEL/ARG value are indented, changing the value #78).
• New fixtures: empty-continuation, and issue71–issue80. A CRLF variant of every fixture runs too.

Test plan

• go vet ./..., go test ./..., gofmt -l .
• JS: npm run build && node --test dist/format.test.js, 12/12
• Ran over 86 Dockerfiles: BuildKit's parser test files, BuildKit's own Dockerfiles, and all fixtures. Result: 0 fallbacks, 0 idempotency failures, and BuildKit reads every output the same as its input. The only differences are RUN heredoc scripts re-indented by shfmt, on purpose.
• Every fixture converted to CRLF: consistent CRLF output, no fallbacks.

Supersedes #82, #74, #75.

🤖 Generated with Claude Code