test/packaging/lint-once.test.ts

@@ -39,18 +39,31 @@
 // one pass over literals, so a value that itself names another variable, a
 // value built by a make function (`$(shell ...)`, `$(addprefix ...)`), and the
 // body of a `define`/`endef` block are not expanded and not followed. A
-// `docker build` resolves to the file named by `-f`, `-f=`, `-f<file>` with
+// build is recognised as `docker build`, as `docker buildx build`, and as
-// the value attached to the flag, `--file` or `--file=`, wherever in that
+// either of those reached through global flags standing between the command
-// invocation the flag sits, and to `Dockerfile` when it names none; a
+// and the subcommand (`docker --context ci build`, `docker -H tcp://h:2375
-// Dockerfile chosen some other way — a bundled short flag cluster
+// buildx build`), a flag's separate argument being stepped over; `docker
-// (`-qf <file>`), a value this walk cannot expand to a literal — resolves to
+// compose build` is deliberately not, since it builds services out of a
-// the default rather than to the real file. Each `docker build` on a line is
+// compose file this walk does not read, and neither is any other non-flag word
-// followed separately, and the flag search for one is bounded to the slice
+// in that position. Matching only a literal `docker build` was worse than a
+// wrong file: `docker buildx build -f <file> .` emitted no edge at all, not
+// even the default one. A recognised build resolves to the file named by
+// `-f`, `-f=`, `-f<file>` with the value attached to the flag, `--file` or
+// `--file=`, wherever in that invocation the flag sits, and to `Dockerfile`
+// when it names none; a Dockerfile chosen some other way — a bundled short
+// flag cluster (`-qf <file>`), a value this walk cannot expand to a literal —
+// resolves to the default rather than to the real file. Each build on a line
+// is followed separately, and the flag search for one is bounded to the slice
 // running from that command to the next `&&`, `||`, `;` or `|`, so a second
 // build on the same line is not swallowed by the first and a later command's
 // `-f` is not read as the build's. That bounding is a split on those four
 // separators, not a shell parse: a separator appearing inside quotes or a
-// command substitution still ends the slice. Within those edges, a prettier
+// command substitution still ends the slice, so a flag standing after one —
+// `docker build --build-arg MSG="a;b" -f Dockerfile.lint .` — is not read.
+// Inside a Dockerfile the `RUN` keyword is matched case-insensitively and may
+// be followed by any whitespace, because Docker executes `run ...` and a
+// tab-separated `RUN\t...` exactly as it executes `RUN ...`; an instruction
+// indented from the left margin is read too. Within those edges, a prettier
 // call is caught wherever it is added.
 //
 // Two entrypoints are walked, because they cover different graphs: `make check`