Dep scan forfeits a whole command when a harmless prefix precedes the compiler

[typeless]

Found during the #345 investigation. Rewritten 2026-08-12: the original title and body said the refusal was silent, and described the fix as skipping leading separators in a matcher that read word_ids[0]. Both are stale — see "What changed" below. The defect that remains is the narrowness of recognition, unchanged in substance since filing.

What remains

putup forfeits the dependency scan for an entire command when it cannot recognize every one of that command's invocations as a compile it can reproduce. A harmless prefix — one that provably cannot change what the compile reads — costs the rule all of its header dependencies.

The live shapes, all reproducible today:

: hidden.c |> echo building %f && gcc -c %f -o %o |> %B.o   # test-pinned, see below
: foo.c    |> FOO=1 gcc -c %f -o %o |> %B.o                  # env assignment before the compiler
: foo.c    |> ; gcc -c %f -o %o |> %B.o                      # empty leading invocation

None of these can affect what the preprocessor reads, and all three forfeit the scan.

Current mechanism

every_invocation_is_a_compile (src/graph/scanners/gcc.cpp:126-134) requires compiler_index to succeed on every invocation. compiler_index (gcc.cpp:109-121) accepts the compiler at position 0, or behind exactly one recognized wrapper — nothing else. echo, FOO=1, and the empty span produced by a leading separator all fail it.

split_invocations (src/graph/scanners/dep_words.cpp:135-151) emits an empty invocation for an operator with nothing before it, and its comment asserts that this "is a command no scan can reproduce". That assertion is the narrow half of this issue stated as a code comment: an invocation that runs nothing cannot change the directory, the environment, or what a compile reads.

matches_clang_cl_compile carries the identical shape in driver_index (src/graph/scanners/clang_cl.cpp:121-134) and must move in lockstep.

The fix, as 276baf2 scoped it

The matcher fix — recognizing a compile behind a harmless prefix — is tracked in #352 and lands next, as an allowlist of prefix words that provably cannot change what the compile reads.

Still the right shape, with one update: the allowlist now belongs inside compiler_index, applied per invocation, rather than at the head of the whole command. The empty-invocation case is separable and simpler — an invocation with no words runs nothing, so it can be skipped rather than allowlisted.

The allowlist is convention-lagging by construction: a prefix nobody has added is a rule that still forfeits its scan. That is acceptable only because the lag is now loud (below), and the diagnostic is what measures it.

What changed since filing

The refusal is declared, not silent. 276baf2ee shipped the reporter. putup parse names each rule producing an object no scan covers —

no dependency scan for '<obj>': putup recognizes no compile it can reproduce in this command, so any header this rule reads goes unrecorded. Harmless if it preprocesses none — an assembler, a copy, a partial link.
— src/cli/strict_checks.cpp:195-198

— and a build prints a one-line count (src/cli/cmd_build.cpp:2206-2212). Pinned by Scenario: A compile-shaped rule with no dependency scan is reported (test/unit/test_e2e.cpp:11162), whose fixture uses the echo … && gcc -c shape above. So the 103 objects are declared, not hidden; the harm is the missing dependency edges, not the concealment.

The criterion moved and got stricter, not wider. PR #400 (2bf0cce0c, 0e7907602, closing #356) made invocations a nameable unit and asks the criterion once per invocation through one enforcement point. It deliberately narrowed what is scanned — a command is scanned only if all of its invocations are recognized compiles — because a scan reproduces one invocation from the rule's directory with the rest stripped, so anything it cannot account for could have changed the state the compile ran in. This issue's fix widens recognition within that criterion; it does not relax it.

The 103 figure is stale. It was measured before #400 tightened the criterion, so the current count is at least that and probably higher. Re-measure with putup parse before using it as a baseline.

Boundaries

Recognition narrowness (this issue) is not the same defect as scan granularity. #355 is that a recognized multi-invocation command folds every invocation's sources under the first invocation's flags, which redirects rather than narrows the header search. Its full fix — one scan node per compile invocation — is being filed separately as its own issue and is gated on widening the unscanned reporter, not on this.

Related: #355 (granularity), #356 (closed by #400, the criterion), #357 (self-depfiling commands the reporter skips).

[typeless]

Correcting this issue: I filed it wrong twice

Investigation found both the repro and the framing are defective. Recording that before any fix, since this issue is the reference.

1. The repro in the description is a shell syntax error, not a silent bug

: foo.c |> ; gcc -c %f -o %o |> %B.o does not "run an empty first command and then the compile":

$ sh -c '; gcc --version'
sh: 1: Syntax error: ";" unexpected

putup reports Build completed: 0 commands (1 failed). That spelling fails loudly and is not an instance of the silent class.

2. The trigger is not "a leading separator" — it is "the compiler is not the command's first word"

matches_gcc_compile takes the compiler from word_ids[0] (or [1] behind a wrapper) and requires a compiler name at that index. So the reachable, idiomatic silent spellings are the ones no separator-focused reading would find:

command	scanned?	header edit rebuilds?
gcc -c foo.c -o foo.o	yes	yes
echo building %f && gcc -c %f -o %o	no	NO — Nothing to do
cd . && gcc -c %f -o %o	no	NO
mkdir -p out && gcc -Iinc -c foo.c -o out/foo.o	no	NO
echo x && ccache gcc -c foo.c -o foo.o	no	NO

matches_clang_cl_compile shares the assumption line for line.

3. Most importantly: this is a deliberate decision, not an oversight

The word-0 rule was introduced by dbdbffdbf ("Skip DEP generation for compound shell commands"):

Fixes build-gcc-bsp CI failure: binutils Tupfile uses for-loop batch compilation rules that triggered the false positive.

and is pinned by test/unit/test_dep_scanner.cpp:439, TEST_CASE("GccScanner rejects compound shell commands") — three sections asserting no scan for the binutils for-loop, for cd /build && gcc -c …, and for SRCDIR=$PWD && cd /build && gcc -c ….

The cd hazard behind that decision is real by construction. A scan node is created with the parent's SourceDir, and src/exec/scheduler.cpp:680-687 sets a job's working directory from it — so a scan always runs from the Tupfile's directory with the prefix stripped. Relative -I paths and source words in a cd-prefixed command would resolve somewhere else entirely. Any fix that skips a command prefix unconditionally re-opens the CI failure dbdbffdbf closed.

What is actually wrong, and is worth fixing

103 objects in the CI-gated binutils BSP compile today with no header dependencies recorded — examples/bsp/binutils/Tupfile lines 86, 110, 121, 140-145, 167, five for-loop rules. The build-gcc-bsp job builds the whole graph; its dry run shows 1692 DEP nodes and none belong to those rules.

So the defensible complaint is not "putup refuses to scan these" — it cannot reproduce arbitrary shell state and should refuse. It is that putup refuses silently. A rule that produces object files and gets no scan should say so, rather than leaving a build that looks complete and is not.

Also found, filed separately

• Source words are folded across a cd mid-command with no directory check: gcc -c a.c -o a.o && cd sub && gcc -c b.c -o b.o emits gcc -M a.c b.c and breaks its own build. The prefix guard is not the whole story — the back door is open mid-command.
• Flag-folding staleness in the same twenty lines, which is more deceptive than this issue.
• Six HOSTCC compile-and-link rules (examples/bsp/gcc/gmp/Tupfile:49-54) are a second never-scanned class, invisible to the matcher because they carry no -c.

Cosmetic while in there: examples/bsp/binutils/Tupfile:86 displays CC-BFD (38 files) but the rule builds 47.

[typeless]

One sharpening of the claim above, because the loose version invites a wrong rebuttal.

"103 objects in CI with no recorded header dependencies" is true but misleading. CI compiles those objects from scratch on every run, so CI itself never observes the staleness — a from-scratch build has no stale objects by construction. The harm lands on incremental local builds of the BSP: a developer edits a header, and the 103 objects that depend on it are not rebuilt.

Stated precisely: the missing dependency edges are real and CI is the place we can count them, but CI is not where they bite. Anyone reading the original phrasing could reasonably answer "but the BSP job is green", and be right about the wrong thing.