From f481ca5d7bc5756cacac475c25ed75ddda4ed847 Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Thu, 20 Aug 2026 13:49:21 -0700 Subject: [PATCH 1/5] fix(workflow-pins): stop the step-output reader failing compliant spellings (BE-8130) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cursor-review panel findings on the BE-8130 detector. Each of these was a site the reader could not see, and each mirrors a precedent already in this file rather than inventing a rule. - `_skips_on_empty_output` scanned only lines at the step's key column, so `- if: steps.x.outputs.ref != ''` — the condition on the list-marker line — was never seen and a correctly guarded checkout was reported unguarded. Normalize the marker exactly as `_binding_step_id` already does to read an `id:` off it. - The same reader demanded spaces around `!=`. Actions accepts `…outputs.ref!=''`, so the lint was failing the remedy it had just asked for. Spacing is now normalized to one space either side; nothing else is, so an OR-widened condition and an `if:` on a different output stay refused however they are spaced (both pinned by tests). - `steps_output_ref`'s flow matcher took the LEFTMOST `[{,]` boundary, which a comma inside a quoted sibling can meet — planting a decoy `ref:` that is string content, resolving to a step no `resolvers` entry holds, and so dropping the real checkout out of coverage entirely. It now keeps looking past a match that is inside quotes, using the `_outside_quotes` helper `_pins_to_job_workflow_sha` already applies to its own flow match. Stopping at the decoy the way that function does would lose the site, so this one iterates. - README: the prose claimed coverage whenever the producing step's `env:` "binds workflows_ref", which is wider than what the code detects — say "in one of the two literal spellings below", which the preconditions block then gives. Two tests that were passing vacuously now assert what they name: `test_a_resolver_below_its_consumer_is_never_credited` filtered on `guarded`, which an empty site list satisfies, so it could not tell "reported" from "dropped" — it now pins the site list and documents that today it is dropped, though the runtime value is guaranteed ''. And `_binding_step_id`'s own list-marker normalization had no test at all; deleting it kept the suite green. --- .github/workflow-pins/README.md | 5 +- .github/workflow-pins/check_workflow_pins.py | 34 ++++++++- .../tests/test_check_workflow_pins.py | 74 +++++++++++++++++++ 3 files changed, 107 insertions(+), 6 deletions(-) diff --git a/.github/workflow-pins/README.md b/.github/workflow-pins/README.md index 5a6af6ef..8bb8d673 100644 --- a/.github/workflow-pins/README.md +++ b/.github/workflow-pins/README.md @@ -70,8 +70,9 @@ checkout reads `ref: ${{ steps..outputs. }}`, which names no input — so it used to leave the lint entirely, with a hand-written `if:` as the only thing between an unresolvable ref and a silent default-branch checkout of the scripts the job executes. The detector now follows a `ref:` through the step -output: when the producing step's `env:` binds `workflows_ref`, the checkout is -a ref use, and it is covered only if **either** that step is itself a +output: when the producing step's `env:` binds `workflows_ref` *in one of the +two literal spellings below*, the checkout is a ref use, and it is covered only +if **either** that step is itself a fail-closed guard, **or** the consuming step carries exactly `if: steps..outputs. != ''` on that same output — bare or `${{ … }}`-wrapped, either spelling optionally double-quoted. Nothing wider: diff --git a/.github/workflow-pins/check_workflow_pins.py b/.github/workflow-pins/check_workflow_pins.py index d6ec9368..bb3b3728 100644 --- a/.github/workflow-pins/check_workflow_pins.py +++ b/.github/workflow-pins/check_workflow_pins.py @@ -552,7 +552,20 @@ def steps_output_ref(line, cont=False): if cont: match = _STEPS_OUTPUT_CONT_RE.match(code) else: - match = _STEPS_OUTPUT_BLOCK_RE.match(code) or _STEPS_OUTPUT_FLOW_RE.search(code) + match = _STEPS_OUTPUT_BLOCK_RE.match(code) + if match is None: + # The flow form `search`es mid-line, so its `[{,]` entry boundary can + # be met by a comma INSIDE a quoted sibling — planting a decoy `ref:` + # that resolves to a step no checkout consumes, while the real `ref:` + # further along the line is never examined. `_pins_to_job_workflow_sha` + # answers that by requiring its match to sit outside quotes; here the + # walk must also keep LOOKING past the decoy, because stopping at it + # drops the site out of coverage entirely rather than merely scoring + # it weaker. + for candidate in _STEPS_OUTPUT_FLOW_RE.finditer(code): + if _outside_quotes(code, candidate.start()): + match = candidate + break return (match.group("id"), match.group("out")) if match else None @@ -896,7 +909,15 @@ def _skips_on_empty_output(lines, idx, step_id, out): wanted = "steps.%s.outputs.%s != ''" % (step_id, out) for j in range(start, end): line = lines[j] - if _is_skippable(line) or _indent(line) != key_indent: + if _is_skippable(line): + continue + if j == start and line.lstrip().startswith("- "): + # The list marker occupies the step's key column, so `- if: …` + # declares the condition there exactly as a later `if:` line does. + # Same rewrite `_binding_step_id` makes to read an `id:` off it — + # without it a correctly guarded checkout reads as unguarded. + line = " " * key_indent + line.lstrip()[2:] + if _indent(line) != key_indent: continue if not _STEP_IF_RE.match(line): continue @@ -920,8 +941,13 @@ def _skips_on_empty_output(lines, idx, step_id, out): cond = cond[3:-2].strip() # Runs of whitespace collapse to one space, which can only ever REJECT # a condition that is not the wanted one — it never removes a character - # and so can never manufacture the `''` this test hinges on. - if re.sub(r"\s+", " ", cond) == wanted: + # and so can never manufacture the `''` this test hinges on. The spacing + # AROUND `!=` is then pinned to one space either side, because Actions + # accepts `…outputs.ref!=''` and a lint that failed it would be failing + # the remedy it just asked for. Normalizing spacing cannot turn a + # different condition into this one: every other character still has to + # match exactly, `!=` included. + if re.sub(r"\s*!=\s*", " != ", re.sub(r"\s+", " ", cond)) == wanted: return True return False diff --git a/.github/workflow-pins/tests/test_check_workflow_pins.py b/.github/workflow-pins/tests/test_check_workflow_pins.py index 2120d768..5fdd682b 100644 --- a/.github/workflow-pins/tests/test_check_workflow_pins.py +++ b/.github/workflow-pins/tests/test_check_workflow_pins.py @@ -1012,6 +1012,54 @@ def test_unwrapping_quotes_does_not_widen_the_match(self): widened = ' if: "steps.resolve_ref.outputs.ref != \'\' || always()"\n' self.assertEqual(len(self._jobs(self.RESOLVER + self._step_output_checkout(widened))), 1) + def test_the_id_on_the_list_marker_line_registers_the_resolver(self): + # `_binding_step_id` normalizes the marker so `- id: …` is read at the + # step's key column. Without it the resolver registers under no id, and + # the consuming checkout drops out of coverage — silently, since an + # unresolvable `` is treated as "not this lint's subject". + marker_resolver = self.RESOLVER.replace( + " - name: Resolve the asset ref\n id: resolve_ref\n", + " - id: resolve_ref\n name: Resolve the asset ref\n", + 1, + ) + self.assertNotEqual(marker_resolver, self.RESOLVER, "fixture drifted") + sites = cwp.ref_checkouts( + self._wrap(marker_resolver + self._step_output_checkout(self.EXACT_IF)).split("\n") + ) + self.assertEqual( + [(fb, guarded, via) for _, fb, guarded, via in sites], [(False, True, True)] + ) + + def test_the_if_on_the_list_marker_line_is_seen(self): + # `- if: …` puts the condition at the step's key column via the list + # marker. Missing it reports a correctly guarded checkout as unguarded — + # `_binding_step_id` already normalizes the same marker to read an `id:`. + marker = ( + " - if: steps.resolve_ref.outputs.ref != ''\n" + " uses: actions/checkout@abc\n" + " with:\n" + " ref: ${{ steps.resolve_ref.outputs.ref }}\n" + ) + self.assertEqual(self._jobs(self.RESOLVER + marker), []) + + def test_a_tightly_spaced_if_passes(self): + # `a!=''` is valid Actions, and failing it would fail the very remedy + # the lint asks for. + tight = " if: steps.resolve_ref.outputs.ref!=''\n" + self.assertEqual(self._jobs(self.RESOLVER + self._step_output_checkout(tight)), []) + + def test_normalizing_the_spacing_does_not_widen_the_match(self): + # Spacing is normalized; nothing else is. An OR-widened condition and an + # `if:` naming a different output stay refused however they are spaced. + for cond in ( + " if: steps.resolve_ref.outputs.ref!=''||always()\n", + " if: steps.resolve_ref.outputs.status!=''\n", + ): + with self.subTest(cond=cond.strip()): + self.assertEqual( + len(self._jobs(self.RESOLVER + self._step_output_checkout(cond))), 1 + ) + def test_a_job_level_if_does_not_cover_a_step_output_checkout(self): # A job-level `if:` skips the RESOLVER too, so it can never tell an # empty output from a populated one. Only the consuming step's own @@ -1046,6 +1094,17 @@ def test_a_resolver_below_its_consumer_is_never_credited(self): self._wrap(self._step_output_checkout(self.EXACT_IF) + self.RESOLVER).split("\n") ) self.assertEqual([s for s in sites if s[2]], []) + # Pinned to the SITE LIST, not just to `guarded`: the filter above is + # satisfied by an empty list, so on its own it cannot tell "reported as + # unguarded" from "dropped and never seen". Today it is the latter — + # `` matches no earlier step, so `_record_steps_output` returns + # without recording. At runtime that output is guaranteed `''` and the + # checkout takes the DEFAULT BRANCH, so reporting it would be the + # stronger answer; distinguishing it from the legitimately out-of-scope + # case (an earlier step that exists and never touches `workflows_ref`) + # needs a per-job pre-scan of step ids. Asserted as-is so the gap is + # visible in the suite rather than hidden behind a vacuous filter. + self.assertEqual(sites, [], "behaviour changed — see the note above") def test_a_step_output_unrelated_to_the_input_is_not_a_ref_use(self): # The producing step binds no `workflows_ref`, so this checkout has @@ -1068,6 +1127,21 @@ def test_the_flow_form_of_a_step_output_checkout_behaves_the_same(self): self.assertEqual(self._jobs(self.RESOLVER + flow % self.EXACT_IF), []) self.assertEqual(len(self._jobs(self.RESOLVER + flow % "")), 1) + def test_a_quoted_sibling_cannot_plant_a_decoy_step_output(self): + # The twin of `test_a_quoted_sibling_cannot_plant_a_decoy_ref`, on this + # path. A comma inside a quoted sibling meets the flow matcher's `[{,]` + # boundary, so the leftmost match can be a `ref:` that is string + # CONTENT — naming a step no `resolvers` entry holds, which drops the + # real checkout out of coverage entirely. Keep looking past it. + line = ( + " with: {path: \"x, ref: ${{ steps.other.outputs.ref }}\", " + "ref: \"${{ steps.resolve_ref.outputs.ref }}\"}" + ) + self.assertEqual(cwp.steps_output_ref(line), ("resolve_ref", "ref")) + # …and a real flow-form step output is still read, decoy or not. + plain = " with: {repository: a/b, ref: ${{ steps.r.outputs.ref }}}" + self.assertEqual(cwp.steps_output_ref(plain), ("r", "ref")) + def test_the_block_scalar_form_of_a_step_output_checkout_behaves_the_same(self): # `ref: >-` leaves the key line with no expression on it and the # expression line with no `ref:` key — the vertical spelling of the From 61cbc05fd4bd10fa5b12d1dc63177128bc1293fd Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Thu, 20 Aug 2026 15:49:20 -0700 Subject: [PATCH 2/5] fix(workflow-pins): report dangling step-output refs and read the `||` fallback spelling (BE-8220) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A step-output `ref:` whose id matches no step declared before the consuming one used to be silently dropped — at runtime the expression is '' and checkout takes the default branch unconditionally. A per-job step-id pre-scan now separates that dangling case (reported, with its own BE-8215 message) from the legitimately out-of-scope earlier step. `_STEPS_OUTPUT_BODY` also reads `||` continuations now, judged by leading-operand order exactly as the input side is. --- .github/workflow-pins/README.md | 28 ++- .github/workflow-pins/check_workflow_pins.py | 203 ++++++++++++++---- .../tests/test_check_workflow_pins.py | 173 +++++++++++++-- 3 files changed, 346 insertions(+), 58 deletions(-) diff --git a/.github/workflow-pins/README.md b/.github/workflow-pins/README.md index 8bb8d673..def85fa8 100644 --- a/.github/workflow-pins/README.md +++ b/.github/workflow-pins/README.md @@ -83,9 +83,8 @@ skips the resolver too. A never-fail resolver can only take the second route — not a guard. A `ref:` resolved from a step that never touches `workflows_ref` is not this lint's subject and is left alone. -Two preconditions decide whether the detector SEES that site at all, and an -unrecognized resolver is silent — it drops the consumer out of coverage rather -than raising a different error, so copy the idiom with both intact: +Two preconditions decide whether the detector treats the resolver as one, so +copy the idiom with both intact: - **The binding is matched literally.** The producing step's `env:` must bind `WORKFLOWS_REF: ${{ inputs.workflows_ref }}` or @@ -97,6 +96,29 @@ than raising a different error, so copy the idiom with both intact: and a resolver declared below its consumer cannot have run first, so neither is credited — the same rule the guard steps already follow. +**A `ref:` naming a nonexistent or later step is an ERROR in its own right +(BE-8215).** A step-output `ref:` whose `` matches no step declared before +the consuming one — a typo'd id, a step in another job, a resolver declared +below its consumer — used to be silently dropped as "not this lint's subject". +At runtime that expression is `''`, which `actions/checkout` reads as the +default branch, so the checkout runs **unconditionally** at a mutable ref — the +exact hole this lint exists to close, on the one spelling where it was +fail-open. A per-job step-id pre-scan now separates the two cases: a `ref:` +resolved from an EARLIER step that exists but never touches `workflows_ref` +stays out of scope, while a dangling id fails with its own message (the +BE-8130 remedies don't apply — adding the `if:` on a nonexistent output guards +nothing that will ever run; the fix is the id itself, or the step order). + +**`||` fallbacks are read on this path too, with leading-operand judgment +(BE-8215).** `ref: ${{ steps..outputs. || 'main' }}` used to match +nothing anywhere and record nothing. Now it is a site like any other, judged +by operand order exactly as the input side is: when the FIRST `||` operand is +the step output, the site is covered by the usual routes (a fail-closed +resolver, or the exact `if:` — under which the fallback arm is unreachable +dead code, so it passes); when the leading operand is anything else +(`${{ 'main' || steps..outputs. }}`), the literal wins on every +runner and the site is unguarded unconditionally. + **The lint enforces that split, rather than trusting the prose.** The fallback answers *mutability*; the guard answers *emptiness*; a checkout using the fallback is exempt from the first check and still held to the second. Until diff --git a/.github/workflow-pins/check_workflow_pins.py b/.github/workflow-pins/check_workflow_pins.py index bb3b3728..9e41b297 100644 --- a/.github/workflow-pins/check_workflow_pins.py +++ b/.github/workflow-pins/check_workflow_pins.py @@ -118,9 +118,18 @@ # `_REF_USE_FLOW_RE` bounds its own value, so a SIBLING entry carrying a step # output cannot be misread as the ref), and a continuation line that IS the # expression, for the `ref: >-` / `ref: |` spellings `_REF_KEY_OPEN_RE` opens. +# +# The interpolation may CONTINUE past the output name, and open before it +# (BE-8215): anchoring `}}` right after the name meant `ref: ${{ +# steps.x.outputs.ref || 'main' }}` matched nothing anywhere and recorded +# nothing — the `||` spelling left the lint entirely, exactly the hole +# `_leading_operand_reaches_input` closes on the input side. The `lead` group +# carries what precedes the step output inside the interpolation so operand +# order can be judged the same way there; both widened stretches keep the flow +# form's `[^,}]` entry-boundary discipline. _STEPS_OUTPUT_BODY = ( - r"""\$\{\{\s*steps\.(?P[A-Za-z0-9_-]+)""" - r"""\.outputs\.(?P[A-Za-z0-9_-]+)\s*\}\}""" + r"""\$\{\{(?P[^,}]*?)steps\.(?P[A-Za-z0-9_-]+)""" + r"""\.outputs\.(?P[A-Za-z0-9_-]+)\s*(?:\|\|[^,}]*?)?\}\}""" ) _STEPS_OUTPUT_BLOCK_RE = re.compile(r"""^\s*(['"]?)ref\1\s*:.*%s""" % _STEPS_OUTPUT_BODY) _STEPS_OUTPUT_FLOW_RE = re.compile(r"""[{,]\s*(['"]?)ref\1\s*:[^,}]*%s""" % _STEPS_OUTPUT_BODY) @@ -131,6 +140,12 @@ # — both are valid Actions YAML — and `\S+` stops before a trailing comment on # its own, because YAML needs whitespace ahead of a `#` for it to open one. _STEP_ID_RE = re.compile(r"""^\s*(['"]?)id\1\s*:\s*(\S+)""") +# The same key inside a flow mapping (`- {id: x, run: …}`), for the pre-scan +# `_job_step_ids` runs (BE-8215). An id the pre-scan misses turns a compliant +# workflow into a false FAILURE under the dangling check, so under-collection +# is the costly direction — over-collection merely reproduces the old +# fail-open drop for that one site. +_STEP_ID_FLOW_RE = re.compile(r"""[{,]\s*(['"]?)id\1\s*:\s*([^,}\s]+)""") # How the guard RECEIVES the ref: through `env:` (never interpolated into the # script body) under this one name. Half the signature — `is_guard_step` below # checks the other half, that the step actually rejects an empty value. @@ -530,6 +545,26 @@ def is_ref_use(line, res=None): return bool(block_re.match(line) or flow_re.search(line)) +def _steps_output_match(code, cont=False): + """The `_STEPS_OUTPUT_*` match object for `code`, or None.""" + if cont: + return _STEPS_OUTPUT_CONT_RE.match(code) + match = _STEPS_OUTPUT_BLOCK_RE.match(code) + if match is None: + # The flow form `search`es mid-line, so its `[{,]` entry boundary can + # be met by a comma INSIDE a quoted sibling — planting a decoy `ref:` + # that resolves to a step no checkout consumes, while the real `ref:` + # further along the line is never examined. `_pins_to_job_workflow_sha` + # answers that by requiring its match to sit outside quotes; here the + # walk must also keep LOOKING past the decoy, because stopping at it + # drops the site out of coverage entirely rather than merely scoring + # it weaker. + for candidate in _STEPS_OUTPUT_FLOW_RE.finditer(code): + if _outside_quotes(code, candidate.start()): + return candidate + return match + + def steps_output_ref(line, cont=False): """(step id, output name) when `line`'s `ref:` IS a step output, else None. @@ -548,27 +583,31 @@ def steps_output_ref(line, cont=False): # the common case before paying for the comment strip and the regexes. if "steps." not in line: return None - code = _strip_comment(line) - if cont: - match = _STEPS_OUTPUT_CONT_RE.match(code) - else: - match = _STEPS_OUTPUT_BLOCK_RE.match(code) - if match is None: - # The flow form `search`es mid-line, so its `[{,]` entry boundary can - # be met by a comma INSIDE a quoted sibling — planting a decoy `ref:` - # that resolves to a step no checkout consumes, while the real `ref:` - # further along the line is never examined. `_pins_to_job_workflow_sha` - # answers that by requiring its match to sit outside quotes; here the - # walk must also keep LOOKING past the decoy, because stopping at it - # drops the site out of coverage entirely rather than merely scoring - # it weaker. - for candidate in _STEPS_OUTPUT_FLOW_RE.finditer(code): - if _outside_quotes(code, candidate.start()): - match = candidate - break + match = _steps_output_match(_strip_comment(line), cont) return (match.group("id"), match.group("out")) if match else None +def _steps_output_site(line, cont=False): + """(step id, output name, leading) for the walk's judgment, else None. + + `leading` is True when the ref expression's first `||` operand IS the step + output — the step-output twin of `_leading_operand_reaches_input`. GitHub's + `||` returns the first truthy operand, so `ref: ${{ 'main' || + steps.x.outputs.ref }}` reads the output while resolving to a mutable + branch on every runner; neither a hard-guard resolver nor the exact `if:` + can change that, so a non-leading output is unguarded unconditionally. + Judged from the `lead` group of the SAME match rather than from the line's + first interpolation, because a quoted decoy sibling can put an unrelated + interpolation ahead of the real one. + """ + if "steps." not in line: + return None + match = _steps_output_match(_strip_comment(line), cont) + if match is None: + return None + return match.group("id"), match.group("out"), not match.group("lead").strip() + + def _consumes_input(text): """True when `text` uses the input as a mapping value in any YAML style.""" return bool( @@ -866,6 +905,41 @@ def _binding_step_id(lines, idx): return None +def _job_step_ids(lines, start, job_indent): + """{step id: first line index} over the job block opened at `start`. + + A pre-scan ahead of the walk (BE-8215), because the question it answers is + different from `resolvers`': not "which resolver covers this ref" but "does + the id exist AT ALL in this job, and where". Over-collection is tolerated + by design — an id collected from too deep a nesting (an action input named + `id:`, a script line that looks like one) merely reproduces the old + fail-open drop for that one site — while an id this scan MISSES turns a + compliant workflow into a false failure under the dangling check. So both + the block and flow spellings are read, with the same `- id:` list-marker + normalization `_binding_step_id` makes, and nesting depth is deliberately + not enforced. + """ + ids = {} + for i, line in _block_body(lines, start, job_indent): + stripped = line.lstrip() + if stripped.startswith("- "): + # The list marker occupies the step's key column, so `- id: x` + # declares the id there exactly as a later `id:` line does. + line = line[: _indent(line)] + " " + stripped[2:] + match = _STEP_ID_RE.match(line) + if match: + # `rstrip` before the quote strip: on the continuation line of a + # multi-line flow mapping (`- {uses: x,` / `id: y}`) the block + # pattern's `\S+` captures the closing punctuation too, and a + # legitimate step id can never end in `,` or `}` — leaving it on + # is the under-collection this scan must not commit. + ids.setdefault(match.group(2).rstrip(",}").strip("'\""), i) + continue + for flow in _STEP_ID_FLOW_RE.finditer(_strip_comment(line)): + ids.setdefault(flow.group(2).strip("'\""), i) + return ids + + def _consuming_step_bounds(lines, idx): """`_step_bounds` for a `ref:` line, tolerating the flow form. @@ -952,31 +1026,54 @@ def _skips_on_empty_output(lines, idx, step_id, out): return False -def _record_steps_output(found, lines, idx, resolved, resolvers): +def _record_steps_output(found, lines, idx, resolved, resolvers, step_ids): """Record the `ref:` at `idx`, which reads `steps..outputs.`. - Records NOTHING when `` names no resolver seen earlier in this job. A - checkout resolved from a step that never touches `workflows_ref` — a - `git rev-parse`, a release lookup — is not this lint's subject, and - demanding an empty-ref `if:` of it would fail workflows the lint has no - claim on. (Fail-open only in the sense that this lint never covered such a - checkout in the first place; what it must not do is silently drop one that - IS resolved from the input, which is precisely what `resolvers` catches.) + Records NOTHING only when `` names a real step declared AHEAD of the + consuming one that never touches `workflows_ref` — a `git rev-parse`, a + release lookup — which is not this lint's subject, and demanding an + empty-ref `if:` of it would fail workflows the lint has no claim on. + + When `` matches NO step declared before the consuming one (a typo'd + id, a step in another job, a resolver declared below its consumer), the + site is recorded as a DANGLING ref use (BE-8215): at runtime the + expression is `''`, `actions/checkout` reads `''` as the default branch, + and the checkout runs unconditionally. That used to be silently dropped — + fail-open on exactly the shape whose runtime behavior is the hole this + lint exists to close. `via_step_output` carries `'dangling'` (truthy, so + `unguarded_ref_checkouts` needs no change) for `check_dir`'s message. Otherwise it IS a ref use, guarded when EITHER the resolving step is itself a fail-closed guard (nothing empty ever leaves it), OR the consuming step carries the exact non-empty `if:` on that same output. The never-fail idiom can only take the second route: its resolver runs `continue-on-error: true`, which `is_guard_step` disqualifies on purpose — an `exit 1` that does not - fail the job leaves the checkout running anyway. + fail the job leaves the checkout running anyway. Neither route covers an + output that is not the expression's FIRST `||` operand: `${{ 'main' || + steps..outputs. }}` resolves to the literal on every runner, so + that spelling is unguarded unconditionally — while a TRAILING fallback + (`${{ steps..outputs. || 'main' }}`) under a covering guard or + `if:` is unreachable dead code and passes. Recorded as a NON-fallback site: `uses_fallback` exists to compare a checkout's expression against the strength of the guard that covered it, and there is no expression to compare here — the `if:` tests the resolved VALUE, so guard strength is moot on this path. """ - step_id, out = resolved + step_id, out, leading = resolved if step_id not in resolvers: + declared = step_ids.get(step_id) + bounds = _consuming_step_bounds(lines, idx) + consumer_start = bounds[0] if bounds is not None else idx + # A step's OWN id must not excuse a ref consuming it — during the + # step's `with:` evaluation its output does not exist yet — so the + # boundary is the consuming STEP's first line, not the `ref:` line. + if declared is not None and declared < consumer_start: + return + found.append((idx + 1, False, False, "dangling")) + return + if not leading: + found.append((idx + 1, False, False, True)) return guarded = resolvers[step_id] or _skips_on_empty_output(lines, idx, step_id, out) found.append((idx + 1, False, guarded, True)) @@ -1009,7 +1106,11 @@ def ref_checkouts(lines): carry `via_step_output`, are judged by `_record_steps_output` — a fail-closed resolver, or the exact non-empty `if:` on the consuming step — and never earn the fallback-strength exemption, because the `if:` tests the - resolved value rather than an expression. + resolved value rather than an expression. `via_step_output` is three-state + (BE-8215): `False` (the ref names the input), `True` (a step output), or + `'dangling'` — a step output whose id matches no step declared before the + consuming one, so the expression is `''` at runtime and the checkout takes + the default branch unconditionally. """ aliases = env_aliases(lines) ref_res = _ref_use_res(aliases) @@ -1049,6 +1150,12 @@ def ref_checkouts(lines): # be credited; the walk order gives that ordering for free, exactly as # it does for the guard flags above. resolvers = {} + # EVERY step id in this job, pre-scanned (BE-8215): the walk-order + # `resolvers` map cannot tell "an earlier step this lint has no claim + # on" from "no such step at all", and the two demand opposite answers — + # the first is out of scope, the second is a ref that is `''` at + # runtime and must be reported. + step_ids = _job_step_ids(lines, start, job_indent) # An open `ref:` whose value continues below, as (line index, indent). # Continuation lines are the more-indented ones that follow; the first # line back at or above the key's indent closes the scalar. @@ -1066,13 +1173,15 @@ def ref_checkouts(lines): found.append((pending[0] + 1, fallback, guarded, False)) pending = None continue - resolved = steps_output_ref(line, cont=True) + resolved = _steps_output_site(line, cont=True) if resolved is not None: # The `ref: >-` / `ref: |` spelling of the resolve-then- # consume shape. Judged from the same place as the block # form — the KEY line is the checkout, and it is the key # line's own step that must carry the skip `if:`. - _record_steps_output(found, lines, pending[0], resolved, resolvers) + _record_steps_output( + found, lines, pending[0], resolved, resolvers, step_ids + ) pending = None continue # Scalar closed — fall through and judge this line normally. @@ -1128,19 +1237,21 @@ def ref_checkouts(lines): # it can never take a `ref: ${{ … }}` off the branch below.) pending = (i, _indent(line)) else: - resolved = steps_output_ref(line) + resolved = _steps_output_site(line) if resolved is not None: - _record_steps_output(found, lines, i, resolved, resolvers) + _record_steps_output(found, lines, i, resolved, resolvers, step_ids) return found def unguarded_ref_checkouts(lines): """(1-based line, uses_fallback, via_step_output) for every unguarded checkout. - `via_step_output` separates the two shapes only so `check_dir` can name the + `via_step_output` separates the shapes only so `check_dir` can name the right remedy: "copy the guard step in ahead of it" is the wrong advice for a checkout whose ref is resolved a step earlier — there the missing piece is - the consuming step's own `if:`. + the consuming step's own `if:` — and BOTH are the wrong advice for a + `'dangling'` site, where no step with that id precedes the checkout at all + and the fix is the id itself (BE-8215). """ return [ (lineno, fb, via_step) @@ -1253,6 +1364,24 @@ def check_dir(workflows_dir, exempt=KNOWN_EXEMPT): ) for lineno, uses_fallback, via_step_output in unguarded_ref_checkouts(lines): + if via_step_output == "dangling": + # The `ref:` reads a step output whose id matches NO step + # declared before the consuming one (BE-8215). The BE-8130 + # remedies below do not apply — adding the `if:` on a + # nonexistent output guards nothing that will ever run, and + # there is no resolving step to make fail-closed. + errors.append( + "::error file=%s,line=%d::%s checks out at a `ref:` that " + "reads `steps..outputs.`, but no step `` " + "precedes this checkout in its job — a typo'd id, a step " + "in another job, or a resolver declared below its " + "consumer. At runtime that expression is '' and " + "`actions/checkout` reads '' as the DEFAULT BRANCH, so " + "the checkout runs unconditionally at a mutable ref. Fix " + "the step id, or move the resolving step above this " + "checkout. See BE-8215." % (path, lineno, name) + ) + continue if via_step_output: # The resolve-then-consume shape (BE-8130): the ref reaches the # checkout through a step output, so the empty case moves to the diff --git a/.github/workflow-pins/tests/test_check_workflow_pins.py b/.github/workflow-pins/tests/test_check_workflow_pins.py index 5fdd682b..65996277 100644 --- a/.github/workflow-pins/tests/test_check_workflow_pins.py +++ b/.github/workflow-pins/tests/test_check_workflow_pins.py @@ -1079,37 +1079,174 @@ def test_a_hard_guard_resolver_covers_its_consumer_without_an_if(self): def test_a_resolver_in_another_job_is_not_reachable(self): # Jobs run independently: `steps.resolve_ref` in job B names job B's - # step, not job A's. With nothing in the job binding the input, this - # checkout is not this lint's subject at all — not a covered site that - # happens to pass. + # step, not job A's — and job B declares no step under that id, so the + # output is '' at runtime and the checkout takes the default branch + # unconditionally. REPORTED, deliberately (BE-8215): this used to be + # silently dropped as "not this lint's subject", which is fail-open on + # exactly the runtime behavior the lint exists to close. sites = cwp.ref_checkouts( self._wrap(self.RESOLVER, self._step_output_checkout()).split("\n") ) - self.assertEqual(sites, []) + self.assertEqual( + [(fb, guarded, via) for _, fb, guarded, via in sites], + [(False, False, "dangling")], + ) def test_a_resolver_below_its_consumer_is_never_credited(self): # Declared after the checkout it would cover, so it cannot have run - # first. Skipped or reported, but never scored as guarding anything. + # first: at runtime the output is guaranteed '' and the checkout takes + # the DEFAULT BRANCH — the exact `if:` on it tests the same dangling + # output, so it cannot save the site either. Reported as the ONE + # unguarded dangling site (BE-8215); the per-job step-id pre-scan is + # what tells this apart from the legitimately out-of-scope case (an + # EARLIER step that exists and never touches `workflows_ref`). sites = cwp.ref_checkouts( self._wrap(self._step_output_checkout(self.EXACT_IF) + self.RESOLVER).split("\n") ) - self.assertEqual([s for s in sites if s[2]], []) - # Pinned to the SITE LIST, not just to `guarded`: the filter above is - # satisfied by an empty list, so on its own it cannot tell "reported as - # unguarded" from "dropped and never seen". Today it is the latter — - # `` matches no earlier step, so `_record_steps_output` returns - # without recording. At runtime that output is guaranteed `''` and the - # checkout takes the DEFAULT BRANCH, so reporting it would be the - # stronger answer; distinguishing it from the legitimately out-of-scope - # case (an earlier step that exists and never touches `workflows_ref`) - # needs a per-job pre-scan of step ids. Asserted as-is so the gap is - # visible in the suite rather than hidden behind a vacuous filter. - self.assertEqual(sites, [], "behaviour changed — see the note above") + self.assertEqual( + [(fb, guarded, via) for _, fb, guarded, via in sites], + [(False, False, "dangling")], + ) + + def test_a_typoed_step_id_is_reported_dangling(self): + # The resolver is present and correct — the checkout just misspells + # its id, so the expression is '' at runtime and checkout takes the + # default branch. The old early return dropped this silently. + steps = self.RESOLVER + self._step_output_checkout( + ref="${{ steps.resolve_reff.outputs.ref }}" + ) + sites = cwp.ref_checkouts(self._wrap(steps).split("\n")) + self.assertEqual( + [(fb, guarded, via) for _, fb, guarded, via in sites], + [(False, False, "dangling")], + ) + # `'dangling'` is truthy on purpose — the unguarded projection needs + # no change to report it. + self.assertEqual(len(self._jobs(steps)), 1) + + def test_a_dangling_step_id_gets_its_own_error_text(self): + # The BE-8130 remedies (add the exact `if:`, make the resolver + # fail-closed) do not fix a nonexistent id — the dangling case needs + # its own message naming the id as the thing to fix. + tmp = tempfile.mkdtemp() + self.addCleanup(shutil.rmtree, tmp, True) + text = _reusable(PINNED).replace( + " steps:\n - run: echo hi\n", + " steps:\n" + + self.RESOLVER + + self._step_output_checkout(ref="${{ steps.resolve_reff.outputs.ref }}"), + ) + with open(os.path.join(tmp, "w.yml"), "w", encoding="utf-8") as f: + f.write(text) + errors, _, _ = cwp.check_dir(tmp, exempt=frozenset()) + self.assertEqual(len(errors), 1, errors) + self.assertIn("BE-8215", errors[0]) + self.assertIn("DEFAULT BRANCH", errors[0]) + self.assertIn("Fix the step id", errors[0]) + for be8130_remedy in ("BE-8130", "non-empty", "fail-closed", "never-fail"): + self.assertNotIn(be8130_remedy, errors[0]) + + def test_a_steps_own_id_does_not_excuse_its_own_ref(self): + # The checkout step's own `id:` is the referenced one — but during the + # step's `with:` evaluation its output does not exist yet, so the + # expression is '' at runtime. The pre-scan boundary is the consuming + # STEP's first line, not the `ref:` line, precisely so this id cannot + # count as "declared before". + steps = ( + " - name: Load assets\n" + " id: resolve_ref\n" + " uses: actions/checkout@abc\n" + " with:\n" + " ref: ${{ steps.resolve_ref.outputs.ref }}\n" + ) + sites = cwp.ref_checkouts(self._wrap(steps).split("\n")) + self.assertEqual( + [(fb, guarded, via) for _, fb, guarded, via in sites], + [(False, False, "dangling")], + ) + + def test_a_flow_style_resolver_consumer_is_not_reported_dangling(self): + # `- {id: resolve_ref, …}` is the flow spelling of a step id. A + # flow-form guard BINDING deliberately reads as absent, so this step + # can never be credited as a resolver — but the id EXISTS, and the + # pre-scan must see it or a compliant workflow's consumer would be a + # false dangling FAILURE rather than the old out-of-scope drop. + flow_resolver = ( + " - {id: resolve_ref, run: echo hi}\n" + ) + sites = cwp.ref_checkouts( + self._wrap(flow_resolver + self._step_output_checkout()).split("\n") + ) + self.assertEqual(sites, []) + + def test_a_trailing_or_fallback_after_a_covered_output_passes(self): + # `${{ steps.resolve_ref.outputs.ref || 'main' }}` under the exact + # `if:`: the checkout only runs when the output is non-empty, so the + # `|| 'main'` arm is unreachable dead code. Before BE-8215 this + # spelling matched nothing anywhere and recorded nothing. + fallback = "${{ steps.resolve_ref.outputs.ref || 'main' }}" + steps = self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=fallback) + self.assertEqual(self._jobs(steps), []) + # …and it IS a covered site, not an invisible one. + sites = cwp.ref_checkouts(self._wrap(steps).split("\n")) + self.assertEqual( + [(fb, guarded, via) for _, fb, guarded, via in sites], + [(False, True, True)], + ) + + def test_a_trailing_or_fallback_without_the_if_is_reported(self): + # Without the `if:` the fallback IS reachable — the empty case + # resolves to a mutable branch instead of skipping the checkout. + fallback = "${{ steps.resolve_ref.outputs.ref || 'main' }}" + self.assertEqual( + len(self._jobs(self.RESOLVER + self._step_output_checkout(ref=fallback))), 1 + ) + + def test_a_leading_literal_operand_is_reported_even_with_the_if(self): + # GitHub's `||` returns the first truthy operand, so `'main'` wins on + # EVERY runner — the output is never consulted and the exact `if:` + # guards a value the checkout does not use. Same rule as the input + # side's `_leading_operand_reaches_input`. + leading = "${{ 'main' || steps.resolve_ref.outputs.ref }}" + self.assertEqual( + len(self._jobs(self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=leading))), + 1, + ) + + def test_the_or_spellings_behave_the_same_in_flow_form(self): + flow = ( + " - name: Load assets\n" + "%s" + " uses: actions/checkout@abc\n" + ' with: {repository: a/b, ref: "${{ %s }}"}\n' + ) + trailing = "steps.resolve_ref.outputs.ref || 'main'" + leading = "'main' || steps.resolve_ref.outputs.ref" + self.assertEqual(self._jobs(self.RESOLVER + flow % (self.EXACT_IF, trailing)), []) + self.assertEqual(len(self._jobs(self.RESOLVER + flow % ("", trailing))), 1) + self.assertEqual(len(self._jobs(self.RESOLVER + flow % (self.EXACT_IF, leading))), 1) + + def test_the_or_spellings_behave_the_same_in_continuation_form(self): + scalar = ( + " - name: Load assets\n" + "%s" + " uses: actions/checkout@abc\n" + " with:\n" + " ref: >-\n" + " ${{ %s }}\n" + ) + trailing = "steps.resolve_ref.outputs.ref || 'main'" + leading = "'main' || steps.resolve_ref.outputs.ref" + self.assertEqual(self._jobs(self.RESOLVER + scalar % (self.EXACT_IF, trailing)), []) + self.assertEqual(len(self._jobs(self.RESOLVER + scalar % ("", trailing))), 1) + self.assertEqual(len(self._jobs(self.RESOLVER + scalar % (self.EXACT_IF, leading))), 1) def test_a_step_output_unrelated_to_the_input_is_not_a_ref_use(self): # The producing step binds no `workflows_ref`, so this checkout has # nothing to do with the pin contract. Demanding an empty-ref `if:` of - # it would fail workflows this lint has no claim on. + # it would fail workflows this lint has no claim on. The id EXISTS and + # precedes the consumer — which is what separates this from the + # dangling case the pre-scan now reports (BE-8215). sites = cwp.ref_checkouts( self._wrap(self.UNRELATED_RESOLVER + self._step_output_checkout()).split("\n") ) From b68df60c415a332ba73fb8f4fe819a621298e0fa Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Thu, 20 Aug 2026 16:37:03 -0700 Subject: [PATCH 3/5] fix(workflow-pins): keep the dangling check to real checkouts, and judge any leading operand (BE-8220) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review follow-ups on the BE-8220 dangling/`||` reader. - **The dangling verdict no longer fires on lines that are not checkouts.** The walk asks EVERY line of the job about step-output refs, so a job-level `outputs:` mapping — which conventionally sits above `steps:`, and therefore above every step id — and a `ref:` line inside a `run:` heredoc both reached `_record_steps_output` looking exactly like a dangling consumer. Verified: a compliant workflow whose job declares `outputs: {ref: ${{ steps.pick.outputs.ref }}}` HARD-FAILED with an error naming a mutable checkout ref where there is no checkout at all. `_is_ref_input` gates on the one thing every real site has and neither of those does — the `ref:` is an entry of its step's `with:` mapping — restoring the old harmless drop for the rest. - **A non-leading step output gets its own message.** `${{ 'main' || steps.x.outputs.ref }}` was recorded as an ordinary step-output site, so `check_dir` printed the two BE-8130 remedies, neither of which can ever make it pass; the author applies the printed advice and CI stays red with the identical error. It is now a distinct state whose message names operand order. Worded for any leading operator, not just `||`, because `${{ A && steps.x.outputs.ref }}` reaches the same state. Judged before step existence: when the leading operand wins, the output is never consulted, so "no such step" is a red herring. - **A leading operand `||` falls THROUGH still reaches the output.** `||` returns the first TRUTHY operand, so `${{ false || steps.x.outputs.ref }}` and `${{ '' || steps.x.outputs.ref }}` resolve to exactly the guarded output — yet were reported unguarded unconditionally, with a message no edit can satisfy. `_lead_reaches_output` reads the chain instead of testing emptiness. - **`[^,}]` is the FLOW form's entry boundary and nothing else's.** Carrying it into the block and continuation bodies left `|| 'a,b'` matching nothing at all — the same fail-open the `||` reader exists to close. Those two bodies now use `[^}]`, which still cannot cross a `}}`; the flow form keeps `[^,}]`, so a sibling entry is still not swallowed into the ref's value. - **The dangling error names the actual id and output** rather than the `` / `` placeholders, since a typo'd id is the first cause it lists. - **README**: the deleted "an unrecognized resolver is silent" warning is narrowed back rather than dropped — it still holds for the BINDING precondition, which the pre-scan did not touch — and the spellings this reader still does not recognize (a brace inside the fallback, a parenthesized operand, `&&`) are documented as recording no site. Tests: 139 passed, 0 failed (133 before). Six mutation checks — reverting the `with:` gate, the `[^}]` widening, the falsey-lead judgment, the non-leading state, the id interpolation, and the operator-agnostic wording — each fails exactly the tests that name it and nothing else. `check_workflow_pins.py` is green on the repo's real tree, 16 sites, 0 exempt. --- .github/workflow-pins/README.md | 23 ++- .github/workflow-pins/check_workflow_pins.py | 167 ++++++++++++++++-- .../tests/test_check_workflow_pins.py | 119 +++++++++++++ 3 files changed, 288 insertions(+), 21 deletions(-) diff --git a/.github/workflow-pins/README.md b/.github/workflow-pins/README.md index def85fa8..436fc7ee 100644 --- a/.github/workflow-pins/README.md +++ b/.github/workflow-pins/README.md @@ -84,7 +84,9 @@ not a guard. A `ref:` resolved from a step that never touches `workflows_ref` is not this lint's subject and is left alone. Two preconditions decide whether the detector treats the resolver as one, so -copy the idiom with both intact: +copy the idiom with both intact. The second is now an error in its own right +(below), but the FIRST is still silent — an unrecognized *binding* drops the +consumer out of coverage rather than raising a different error: - **The binding is matched literally.** The producing step's `env:` must bind `WORKFLOWS_REF: ${{ inputs.workflows_ref }}` or @@ -107,7 +109,10 @@ fail-open. A per-job step-id pre-scan now separates the two cases: a `ref:` resolved from an EARLIER step that exists but never touches `workflows_ref` stays out of scope, while a dangling id fails with its own message (the BE-8130 remedies don't apply — adding the `if:` on a nonexistent output guards -nothing that will ever run; the fix is the id itself, or the step order). +nothing that will ever run; the fix is the id itself, or the step order). Only +a `ref:` that is a step's `with:` INPUT is judged this way — a job-level +`outputs:` mapping or a `ref:` line inside a `run:` heredoc is not a checkout +and is left alone, as it always was. **`||` fallbacks are read on this path too, with leading-operand judgment (BE-8215).** `ref: ${{ steps..outputs. || 'main' }}` used to match @@ -116,8 +121,18 @@ by operand order exactly as the input side is: when the FIRST `||` operand is the step output, the site is covered by the usual routes (a fail-closed resolver, or the exact `if:` — under which the fallback arm is unreachable dead code, so it passes); when the leading operand is anything else -(`${{ 'main' || steps..outputs. }}`), the literal wins on every -runner and the site is unguarded unconditionally. +(`${{ 'main' || steps..outputs. }}`), it wins on every runner and the +site is unguarded unconditionally — with its own +message, because neither BE-8130 remedy can fix operand order. A leading +operand `||` falls *through* (`false`, `''`, `""`, `0`, `null`) still reaches +the output and is judged normally. + +Spellings this reader still does not recognize — a fallback containing a brace +(`|| format('refs/heads/{0}', 'main')`), a parenthesized operand +(`(steps..outputs.) || 'main'`), and `&&` rather than `||` — match +nothing and record no site, exactly as every `||` spelling did before BE-8215. +Write the ref as a bare `${{ steps..outputs. }}` under the exact +`if:`, or as a plain `|| ` fallback, and it is covered. **The lint enforces that split, rather than trusting the prose.** The fallback answers *mutability*; the guard answers *emptiness*; a checkout using the diff --git a/.github/workflow-pins/check_workflow_pins.py b/.github/workflow-pins/check_workflow_pins.py index 9e41b297..a7177f50 100644 --- a/.github/workflow-pins/check_workflow_pins.py +++ b/.github/workflow-pins/check_workflow_pins.py @@ -125,14 +125,30 @@ # nothing — the `||` spelling left the lint entirely, exactly the hole # `_leading_operand_reaches_input` closes on the input side. The `lead` group # carries what precedes the step output inside the interpolation so operand -# order can be judged the same way there; both widened stretches keep the flow -# form's `[^,}]` entry-boundary discipline. -_STEPS_OUTPUT_BODY = ( - r"""\$\{\{(?P[^,}]*?)steps\.(?P[A-Za-z0-9_-]+)""" - r"""\.outputs\.(?P[A-Za-z0-9_-]+)\s*(?:\|\|[^,}]*?)?\}\}""" -) +# order can be judged the same way there. +# +# Those two widened stretches are bounded by `[^}]`, NOT the flow form's +# `[^,}]`: only the flow spelling needs a comma to end its entry, and carrying +# that bound into the block and continuation forms left a fallback containing a +# comma (`|| 'a,b'`) matching nothing at all — the same fail-open this change +# closes for the plain `|| ` spelling. `[^}]` still cannot cross a +# `}}`, so a match can never span two interpolations. The flow form keeps +# `[^,}]` throughout, exactly as `_REF_USE_FLOW_RE` bounds its own value, so a +# SIBLING entry carrying a step output cannot be misread as the ref. +def _steps_output_body(bound): + """The `${{ … steps..outputs. … }}` body, bounded by `bound`.""" + return ( + r"""\$\{\{(?P%s*?)steps\.(?P[A-Za-z0-9_-]+)""" + r"""\.outputs\.(?P[A-Za-z0-9_-]+)\s*(?:\|\|%s*?)?\}\}""" + ) % (bound, bound) + + +_STEPS_OUTPUT_BODY = _steps_output_body(r"""[^}]""") +_STEPS_OUTPUT_FLOW_BODY = _steps_output_body(r"""[^,}]""") _STEPS_OUTPUT_BLOCK_RE = re.compile(r"""^\s*(['"]?)ref\1\s*:.*%s""" % _STEPS_OUTPUT_BODY) -_STEPS_OUTPUT_FLOW_RE = re.compile(r"""[{,]\s*(['"]?)ref\1\s*:[^,}]*%s""" % _STEPS_OUTPUT_BODY) +_STEPS_OUTPUT_FLOW_RE = re.compile( + r"""[{,]\s*(['"]?)ref\1\s*:[^,}]*%s""" % _STEPS_OUTPUT_FLOW_BODY +) _STEPS_OUTPUT_CONT_RE = re.compile( r"""^\s*(?P['"]?)%s(?P=q)[^\S\n]*$""" % _STEPS_OUTPUT_BODY ) @@ -587,6 +603,36 @@ def steps_output_ref(line, cont=False): return (match.group("id"), match.group("out")) if match else None +# Operands `||` falls THROUGH, so a leading one of these still lets the step +# output be the value (BE-8215). `||` returns the first TRUTHY operand, not the +# first operand — reading `leading` as "nothing precedes the output" reported +# `${{ false || steps.x.outputs.ref }}` as unguarded unconditionally, with a +# message no edit can satisfy, even though it resolves to exactly the output a +# guard covers. GitHub's expression language treats these five as false. +_FALSEY_OPERANDS = frozenset(("false", "''", '""', "0", "null")) + + +def _lead_reaches_output(lead): + """True when `lead` cannot stop the step output being the ref's value. + + `lead` is what precedes `steps..outputs.` inside the `${{ … }}`. + Empty is the common case. Anything else has to be a chain of `||` operands + that all fall through — a truthy leading operand (`'main' ||`) wins on + every runner, and nothing the consuming step or the resolver can do will + change that, so the site is unguarded unconditionally. + """ + lead = lead.strip() + if not lead: + return True + if not lead.endswith("||"): + # Not an `||` chain at all — a `(`, a `format(`, an `&&`. Unrecognized + # rather than proven harmless, so judge it the fail-closed way. + return False + return all( + operand.strip() in _FALSEY_OPERANDS for operand in lead[:-2].split("||") + ) + + def _steps_output_site(line, cont=False): """(step id, output name, leading) for the walk's judgment, else None. @@ -605,7 +651,7 @@ def _steps_output_site(line, cont=False): match = _steps_output_match(_strip_comment(line), cont) if match is None: return None - return match.group("id"), match.group("out"), not match.group("lead").strip() + return match.group("id"), match.group("out"), _lead_reaches_output(match.group("lead")) def _consumes_input(text): @@ -940,6 +986,48 @@ def _job_step_ids(lines, start, job_indent): return ids +# A step's `with:` key, block form and flow form (`- {uses: …, with: {…}}`). +_WITH_KEY_RE = re.compile(r"""^\s*(['"]?)with\1\s*:""") +_WITH_FLOW_RE = re.compile(r"""(?:^|[{,\s])(['"]?)with\1\s*:\s*\{""") + + +def _is_ref_input(lines, idx): + """True when the `ref:` at `idx` is a step's `with:` INPUT — a checkout. + + The walk asks EVERY line of the job about step-output refs, so `ref:` keys + that are not action inputs reach `_record_steps_output` too: a job-level + `outputs:` block (`ref: ${{ steps.pick.outputs.ref }}`, which conventionally + sits ABOVE `steps:` and therefore above every step id) and a `run:` heredoc + emitting fixture YAML, a shape this repo itself uses. Those used to be + dropped harmlessly by the resolver early return; under the dangling check + they would instead HARD-FAIL a compliant workflow with an error naming a + checkout at a mutable ref where there is no checkout at all. So the gate is + the one thing every real site has and neither of those does: a checkout's + `ref:` is an entry of its step's `with:` mapping. + + Answered from the enclosing key rather than from `_consuming_step_bounds`, + which resolves the `- ` list item and so cannot see the difference between + `with:` and `run:` — a heredoc line is inside a step exactly as an input + is. The flow spelling writes `with: {…, ref: …}` on one line, so that line + carries its own answer; the continuation spelling (`ref: >-`) is judged from + its KEY line, which is where the walk reports it. + + Fail-open when the enclosing key is not `with:` (return False → the site is + dropped), because that is the behavior every one of these shapes had before + the dangling check existed. Narrowing a false FAILURE back to the old miss + is the safe direction; the reverse is not. + """ + if _WITH_FLOW_RE.search(_strip_comment(lines[idx])): + return True + ind = _indent(lines[idx]) + for j in range(idx - 1, -1, -1): + if _is_skippable(lines[j]): + continue + if _indent(lines[j]) < ind: + return bool(_WITH_KEY_RE.match(lines[j])) + return False + + def _consuming_step_bounds(lines, idx): """`_step_bounds` for a `ref:` line, tolerating the flow form. @@ -1061,6 +1149,20 @@ def _record_steps_output(found, lines, idx, resolved, resolvers, step_ids): VALUE, so guard strength is moot on this path. """ step_id, out, leading = resolved + if not _is_ref_input(lines, idx): + # Not an action input, so not a checkout — a job-level `outputs:` + # mapping, a `run:` heredoc. Nothing to judge and nothing to fail. + return + if not leading: + # Judged BEFORE step existence on purpose: when the leading operand + # wins, the output is never consulted, so "no such step" is a red + # herring and fixing the id changes nothing. Operand order is the only + # fix, and it needs its own message to say so. + found.append((idx + 1, False, False, "non-leading")) + return + # From here the output IS what the expression resolves to, so the two + # questions that remain — does the step exist, and does anything cover it — + # are worth asking. if step_id not in resolvers: declared = step_ids.get(step_id) bounds = _consuming_step_bounds(lines, idx) @@ -1072,9 +1174,6 @@ def _record_steps_output(found, lines, idx, resolved, resolvers, step_ids): return found.append((idx + 1, False, False, "dangling")) return - if not leading: - found.append((idx + 1, False, False, True)) - return guarded = resolvers[step_id] or _skips_on_empty_output(lines, idx, step_id, out) found.append((idx + 1, False, guarded, True)) @@ -1106,11 +1205,13 @@ def ref_checkouts(lines): carry `via_step_output`, are judged by `_record_steps_output` — a fail-closed resolver, or the exact non-empty `if:` on the consuming step — and never earn the fallback-strength exemption, because the `if:` tests the - resolved value rather than an expression. `via_step_output` is three-state - (BE-8215): `False` (the ref names the input), `True` (a step output), or + resolved value rather than an expression. `via_step_output` is four-state + (BE-8215), every non-`False` value truthy so the unguarded projection needs + no change: `False` (the ref names the input), `True` (a step output), `'dangling'` — a step output whose id matches no step declared before the consuming one, so the expression is `''` at runtime and the checkout takes - the default branch unconditionally. + the default branch unconditionally — or `'non-leading'`, a step output the + expression does not start with, so something ahead of it decides the value. """ aliases = env_aliases(lines) ref_res = _ref_use_res(aliases) @@ -1251,7 +1352,8 @@ def unguarded_ref_checkouts(lines): checkout whose ref is resolved a step earlier — there the missing piece is the consuming step's own `if:` — and BOTH are the wrong advice for a `'dangling'` site, where no step with that id precedes the checkout at all - and the fix is the id itself (BE-8215). + and the fix is the id itself, or a `'non-leading'` one, where the fix is + operand order and no guard anywhere can substitute for it (BE-8215). """ return [ (lineno, fb, via_step) @@ -1364,6 +1466,14 @@ def check_dir(workflows_dir, exempt=KNOWN_EXEMPT): ) for lineno, uses_fallback, via_step_output in unguarded_ref_checkouts(lines): + if via_step_output in ("dangling", "non-leading"): + # Name the ACTUAL id and output where the reported line still + # holds the expression, so a typo — the first cause the + # dangling message lists — is visible in the annotation itself. + # The `ref: >-` continuation spelling reports the KEY line and + # keeps its value below it, so fall back to the placeholders + # there rather than naming the wrong step. + step_id, out = steps_output_ref(lines[lineno - 1]) or ("", "") if via_step_output == "dangling": # The `ref:` reads a step output whose id matches NO step # declared before the consuming one (BE-8215). The BE-8130 @@ -1372,14 +1482,37 @@ def check_dir(workflows_dir, exempt=KNOWN_EXEMPT): # there is no resolving step to make fail-closed. errors.append( "::error file=%s,line=%d::%s checks out at a `ref:` that " - "reads `steps..outputs.`, but no step `` " + "reads `steps.%s.outputs.%s`, but no step `%s` " "precedes this checkout in its job — a typo'd id, a step " "in another job, or a resolver declared below its " "consumer. At runtime that expression is '' and " "`actions/checkout` reads '' as the DEFAULT BRANCH, so " "the checkout runs unconditionally at a mutable ref. Fix " "the step id, or move the resolving step above this " - "checkout. See BE-8215." % (path, lineno, name) + "checkout. See BE-8215." + % (path, lineno, name, step_id, out, step_id) + ) + continue + if via_step_output == "non-leading": + # The output IS read, but something precedes it inside the + # `${{ … }}` (BE-8215). The BE-8130 remedies are worse than + # useless here: both harden a value this ref never reliably + # resolves to, so applying the printed advice leaves CI red + # with the identical error and never names operand order — the + # one thing that can fix it. + errors.append( + "::error file=%s,line=%d::%s checks out at a `ref:` that " + "reads `steps.%s.outputs.%s`, but the expression does not " + "START with it. GitHub's `||` returns the first TRUTHY " + "operand, so a leading `'main' || …` wins on every runner " + "and the output is never consulted; any other leading " + "operator can likewise resolve this ref to a value no " + "guard proved. No `if:` on this step and no change to the " + "resolving step can alter that. Make " + "`steps.%s.outputs.%s` the expression's FIRST operand (a " + "trailing `|| ` fallback is fine), or drop what " + "precedes it. See BE-8215." + % (path, lineno, name, step_id, out, step_id, out) ) continue if via_step_output: diff --git a/.github/workflow-pins/tests/test_check_workflow_pins.py b/.github/workflow-pins/tests/test_check_workflow_pins.py index 65996277..2118dd3a 100644 --- a/.github/workflow-pins/tests/test_check_workflow_pins.py +++ b/.github/workflow-pins/tests/test_check_workflow_pins.py @@ -1317,6 +1317,125 @@ def test_an_unguarded_step_output_checkout_gets_its_own_remedy(self): self.assertIn("resolved from a step", errors[0]) self.assertNotIn("BE-5546", errors[0]) + def test_a_job_level_outputs_ref_is_not_a_checkout(self): + # The walk asks EVERY line of the job about step-output refs, so a + # job-level `outputs:` mapping — which conventionally sits ABOVE + # `steps:`, and therefore above every step id — reaches + # `_record_steps_output` looking exactly like a dangling consumer. + # It is not a checkout at all, and hard-failing a compliant workflow + # with an error naming a mutable checkout ref is worse than the drop + # the dangling check replaced. `_is_ref_input` is the gate. + text = ( + "name: F\non:\n workflow_call:\njobs:\n" + " job0:\n" + " runs-on: ubuntu-latest\n" + " outputs:\n" + " ref: ${{ steps.resolve_ref.outputs.ref }}\n" + " steps:\n" + self.RESOLVER + ) + self.assertEqual(cwp.ref_checkouts(text.split("\n")), []) + + def test_a_ref_line_inside_a_run_heredoc_is_not_a_checkout(self): + # A `run:` script emitting fixture YAML — a shape this repo itself + # uses. The line is inside a step, so the `- ` list item resolves and + # the step-bounds question cannot tell it apart from an input; the + # ENCLOSING KEY can, and it is `run:`, not `with:`. + heredoc = ( + " - name: Write a fixture\n" + " run: |\n" + " cat <<'EOF' > f.yml\n" + " ref: ${{ steps.resolve_ref.outputs.ref }}\n" + " EOF\n" + ) + self.assertEqual(cwp.ref_checkouts(self._wrap(heredoc).split("\n")), []) + + def test_a_fallback_containing_a_comma_is_still_read(self): + # `[^,}]` is the FLOW form's entry boundary and nothing else's. + # Carrying it into the block form dropped every fallback holding a + # comma out of the lint entirely — the same fail-open the `||` reader + # exists to close. + ref = "${{ steps.resolve_ref.outputs.ref || 'a,b' }}" + self.assertEqual( + self._jobs(self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=ref)), [] + ) + self.assertEqual( + len(self._jobs(self.RESOLVER + self._step_output_checkout(ref=ref))), 1 + ) + # The flow form keeps `[^,}]`, so its entry boundary still holds: a + # sibling entry after the comma is not swallowed into the ref's value. + line = ' with: {ref: "${{ steps.r.outputs.ref }}", repository: a/b}' + self.assertEqual(cwp.steps_output_ref(line), ("r", "ref")) + + def test_a_falsey_leading_operand_still_reaches_the_output(self): + # `||` returns the first TRUTHY operand, not the first operand, so a + # leading `false`/`''` falls THROUGH to the step output — the value is + # exactly the one the guard covers. Reading `leading` as "nothing + # precedes the output" failed these with a message no edit can satisfy. + for lead in ("false", "''", '""', "0", "null", "'' || false"): + with self.subTest(lead=lead): + ref = "${{ %s || steps.resolve_ref.outputs.ref }}" % lead + self.assertEqual( + self._jobs( + self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=ref) + ), + [], + lead, + ) + # …and a TRUTHY leading operand is still unguarded unconditionally. + truthy = "${{ 'main' || steps.resolve_ref.outputs.ref }}" + self.assertEqual( + len(self._jobs(self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=truthy))), + 1, + ) + + def _one_error(self, steps): + tmp = tempfile.mkdtemp() + self.addCleanup(shutil.rmtree, tmp, True) + text = _reusable(PINNED).replace( + " steps:\n - run: echo hi\n", " steps:\n" + steps + ) + with open(os.path.join(tmp, "w.yml"), "w", encoding="utf-8") as f: + f.write(text) + errors, _, _ = cwp.check_dir(tmp, exempt=frozenset()) + self.assertEqual(len(errors), 1, errors) + return errors[0] + + def test_a_non_leading_operand_gets_its_own_error_text(self): + # The BE-8130 remedies are worse than useless here: both harden a value + # this ref never resolves to, so applying the printed advice leaves CI + # red with the identical error and never names operand order — the one + # thing that fixes it. Nor is it the dangling case: the step EXISTS. + ref = "${{ 'main' || steps.resolve_ref.outputs.ref }}" + error = self._one_error( + self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=ref) + ) + self.assertIn("does not START with it", error) + self.assertIn("steps.resolve_ref.outputs.ref", error) + for wrong_remedy in ("BE-8130", "fail-closed", "never-fail", "no step"): + self.assertNotIn(wrong_remedy, error) + + def test_a_non_or_leading_operator_is_reported_the_same_way(self): + # `A && steps.x.outputs.ref` resolves to the output when `A` is truthy + # and to '' when it is not — an unguarded path either way, and one no + # `if:` on this step closes. The message must not claim `||`. + ref = "${{ github.event_name && steps.resolve_ref.outputs.ref }}" + error = self._one_error( + self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=ref) + ) + self.assertIn("does not START with it", error) + + def test_the_dangling_error_names_the_actual_step_id(self): + # A typo'd id is the first cause the message lists, so the annotation + # has to show which id it read — the placeholders leave the reader + # hunting for it. + error = self._one_error( + self.RESOLVER + + self._step_output_checkout(ref="${{ steps.resolve_reff.outputs.ref }}") + ) + self.assertIn("steps.resolve_reff.outputs.ref", error) + self.assertIn("no step `resolve_reff` precedes", error) + self.assertNotIn("", error) + def test_this_repos_own_workflows_guard_every_ref_checkout(self): root = os.path.normpath( os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "workflows") From 1c66f7f9ecb4406d0fbfd1e13f31fb882e9e95b4 Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Thu, 20 Aug 2026 17:21:11 -0700 Subject: [PATCH 4/5] fix(workflow-pins): keep the scope gate ahead of operand order, and read a `with:` the YAML nests differently (BE-8220) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round-2 review of #202. Six findings, all reproduced before they were fixed. Two were false FAILURES — a compliant workflow hard-failing, the worst direction for a lint people can route around: - Hoisting the `not leading` verdict above the `step_id not in resolvers` block also hoisted it above the OUT-OF-SCOPE early return, so `ref: ${{ inputs.pr_sha || steps.detect.outputs.sha }}` resolved from a real earlier step this lint has no claim on was reported `'non-leading'` — an error demanding an operand reorder that changes runtime semantics. Scope is asked first now; it holds in every operand position. The dangling/non-leading ordering the hoist existed for is unchanged: a dangling id behind a leading operand still gets the operand-order message. - `_is_ref_input` answered "which key encloses this `ref:`" from indentation alone, so a `run: |` heredoc emitting a whole STEP put a `with:` line at exactly the indent the backward walk stops on and its script output was judged a checkout. `_in_block_scalar` tracks the open `|`/`>` scalar, which closes the flow spelling's copy of the same hole. Two were fail-OPEN drops of the shape the lint exists to close: - `_WITH_KEY_RE` could not match a `with:` riding the list-item line (`- with:` / `ref:` / `uses: checkout` is valid Actions YAML — mapping keys are unordered), so the site was dropped entirely. `_dedash` hoists the `- ` normalization the sibling readers already make into one helper. That exposed a second gap it would otherwise have introduced: `_step_bounds` read the MARKER's column as the step's key column, so a correctly guarded `- with:` checkout could not resolve its own `if:` — now normalized too. - A `ref: >-` whose expression is split across physical lines folds to one value at runtime, so a single newline hid the `|| ` spelling BE-8215 just closed. The pending scalar's lines are joined and re-asked, only after the single line has failed, so the join can only ever add a site. Two were README claims that did not match the code, both verified against it: a LEADING `&&` matches and fails `non-leading` (only a TRAILING one is silent), and the flow spelling of a fallback whose literal contains a comma records no site — now named in the unrecognized list beside the brace and parenthesized operands. Five regression tests, one per fix. --- .github/workflow-pins/README.md | 21 ++- .github/workflow-pins/check_workflow_pins.py | 156 +++++++++++++++--- .../tests/test_check_workflow_pins.py | 110 ++++++++++++ 3 files changed, 261 insertions(+), 26 deletions(-) diff --git a/.github/workflow-pins/README.md b/.github/workflow-pins/README.md index 436fc7ee..ea683154 100644 --- a/.github/workflow-pins/README.md +++ b/.github/workflow-pins/README.md @@ -107,12 +107,15 @@ default branch, so the checkout runs **unconditionally** at a mutable ref — th exact hole this lint exists to close, on the one spelling where it was fail-open. A per-job step-id pre-scan now separates the two cases: a `ref:` resolved from an EARLIER step that exists but never touches `workflows_ref` -stays out of scope, while a dangling id fails with its own message (the +stays out of scope — in **any** operand position, since the lint has no claim +on that step either way — while a dangling id fails with its own message (the BE-8130 remedies don't apply — adding the `if:` on a nonexistent output guards nothing that will ever run; the fix is the id itself, or the step order). Only a `ref:` that is a step's `with:` INPUT is judged this way — a job-level `outputs:` mapping or a `ref:` line inside a `run:` heredoc is not a checkout -and is left alone, as it always was. +and is left alone, as it always was — including a heredoc emitting a whole +STEP, where the enclosing key is a `with:` the script itself printed: an open +`|`/`>` block scalar is tracked so its body is read as text, not structure. **`||` fallbacks are read on this path too, with leading-operand judgment (BE-8215).** `ref: ${{ steps..outputs. || 'main' }}` used to match @@ -129,10 +132,18 @@ the output and is judged normally. Spellings this reader still does not recognize — a fallback containing a brace (`|| format('refs/heads/{0}', 'main')`), a parenthesized operand -(`(steps..outputs.) || 'main'`), and `&&` rather than `||` — match +(`(steps..outputs.) || 'main'`), a TRAILING `&&` +(`${{ steps..outputs. && 'main' }}`), and the FLOW spelling of a +fallback whose literal contains a comma (`with: {ref: "${{ +steps..outputs. || 'a,b' }}"}`, where the flow reader's `[^,}]` entry +boundary ends the match inside the quotes — the block form reads it) — match nothing and record no site, exactly as every `||` spelling did before BE-8215. -Write the ref as a bare `${{ steps..outputs. }}` under the exact -`if:`, or as a plain `|| ` fallback, and it is covered. +A *leading* `&&` is the opposite case, not this one: it MATCHES, nothing but an +`||` chain clears the leading-operand check, and a site the lint has a claim on +at all — one naming a resolver, or a dangling id — fails as `non-leading`, red +CI rather than silence. Write the ref as a bare +`${{ steps..outputs. }}` under the exact `if:`, or as a plain +`|| ` fallback, and it is covered. **The lint enforces that split, rather than trusting the prose.** The fallback answers *mutability*; the guard answers *emptiness*; a checkout using the diff --git a/.github/workflow-pins/check_workflow_pins.py b/.github/workflow-pins/check_workflow_pins.py index a7177f50..606fc299 100644 --- a/.github/workflow-pins/check_workflow_pins.py +++ b/.github/workflow-pins/check_workflow_pins.py @@ -678,6 +678,22 @@ def _indent(line): return len(line) - len(line.lstrip(" ")) +def _dedash(line): + """`line` with a leading `- ` list marker rewritten as two spaces. + + The marker occupies the step's key column, so `- with:` declares that key + exactly where a later `with:` line does. `_binding_step_id` and + `_skips_on_empty_output` make the same normalization inline, against a + `key_indent` they already hold; this is the form for readers that must + DERIVE the column, so they cannot drift apart. Column-preserving: the key + lands where YAML puts it, which is what indentation comparisons need. + """ + stripped = line.lstrip() + if not stripped.startswith("- "): + return line + return line[: _indent(line)] + " " + stripped[2:] + + def _key_re(indent, key): """`key:` at exactly `indent`, bare or quoted (both are valid Actions YAML).""" return re.compile(r"""^ {%d}(['"]?)%s\1\s*:""" % (indent, re.escape(key))) @@ -806,7 +822,16 @@ def _step_bounds(lines, idx): if _is_skippable(lines[j]): continue if _indent(lines[j]) < ind: - key_indent = _indent(lines[j]) + # The enclosing key may RIDE the list marker (`- with:`, `- env:`), + # where it sits at the step's key column and not at the marker's. + # Reading the marker's column instead put `key_indent` a level too + # shallow, and the `start` scan below — which looks for the marker + # BENEATH `key_indent` — then found nothing and answered None, + # leaving the step unresolvable: no `id:`, no `if:`, no guard. The + # scan below still wants the marker's OWN column, so only this + # question is normalized. + dedashed = _indent(_dedash(lines[j])) + key_indent = dedashed if dedashed < ind else _indent(lines[j]) break if key_indent is None: return None @@ -961,17 +986,12 @@ def _job_step_ids(lines, start, job_indent): `id:`, a script line that looks like one) merely reproduces the old fail-open drop for that one site — while an id this scan MISSES turns a compliant workflow into a false failure under the dangling check. So both - the block and flow spellings are read, with the same `- id:` list-marker - normalization `_binding_step_id` makes, and nesting depth is deliberately - not enforced. + the block and flow spellings are read, through the shared `_dedash` + list-marker normalization, and nesting depth is deliberately not enforced. """ ids = {} for i, line in _block_body(lines, start, job_indent): - stripped = line.lstrip() - if stripped.startswith("- "): - # The list marker occupies the step's key column, so `- id: x` - # declares the id there exactly as a later `id:` line does. - line = line[: _indent(line)] + " " + stripped[2:] + line = _dedash(line) match = _STEP_ID_RE.match(line) if match: # `rstrip` before the quote strip: on the continuation line of a @@ -989,6 +1009,54 @@ def _job_step_ids(lines, start, job_indent): # A step's `with:` key, block form and flow form (`- {uses: …, with: {…}}`). _WITH_KEY_RE = re.compile(r"""^\s*(['"]?)with\1\s*:""") _WITH_FLOW_RE = re.compile(r"""(?:^|[{,\s])(['"]?)with\1\s*:\s*\{""") +# A key whose value is a BLOCK SCALAR (`run: |`, `script: >-`). Everything +# indented past it is literal TEXT — a shell script, a heredoc emitting fixture +# YAML — and must never be read as workflow structure. `\d*` is the explicit +# indentation indicator, `[+-]?` the chomping indicator; both are optional and +# may appear in either order, but Actions workflows in the wild write at most +# one, so accepting `|`/`>` plus an optional suffix is enough. +_BLOCK_SCALAR_OPEN_RE = re.compile( + r"""^\s*(['"]?)[A-Za-z0-9_.-]+\1\s*:[^\S\n]*[|>][+-]?\d*[^\S\n]*(?:#.*)?$""" +) + + +def _in_block_scalar(lines, idx): + """True when `lines[idx]` is TEXT inside an open `|`/`>` block scalar. + + `_is_ref_input` answers "which key encloses this `ref:`" from indentation, + and indentation cannot by itself tell a step's real `with:` from the word + `with:` printed by a heredoc: a `run: |` emitting a whole STEP — + + run: | + cat <<'EOF' > f.yml + with: + ref: ${{ steps.x.outputs.ref }} + EOF + + — puts a `with:` line at exactly the indent the backward walk stops on, so + script output was judged a checkout and hard-failed a compliant workflow + with the dangling error. Tracking the open scalar answers it directly: + inside one, there is no enclosing key to find, because there is no YAML. + + Scanned forward, since a block scalar is opened by its key and closed by + the first non-skippable line back at or above that key's column. `idx` + itself is never consulted as an opener — the `ref: >-` continuation + spelling is reported at its own KEY line, which OPENS a scalar rather than + sitting inside one. + """ + open_indent = None + for j in range(idx): + if _is_skippable(lines[j]): + continue + line = _dedash(lines[j]) + ind = _indent(line) + if open_indent is not None: + if ind > open_indent: + continue + open_indent = None + if _BLOCK_SCALAR_OPEN_RE.match(line): + open_indent = ind + return open_indent is not None and _indent(lines[idx]) > open_indent def _is_ref_input(lines, idx): @@ -1005,6 +1073,10 @@ def _is_ref_input(lines, idx): the one thing every real site has and neither of those does: a checkout's `ref:` is an entry of its step's `with:` mapping. + An open `|`/`>` block scalar is tracked first, because indentation alone + cannot tell a step's real `with:` from one a `run:` script PRINTS — see + `_in_block_scalar`. + Answered from the enclosing key rather than from `_consuming_step_bounds`, which resolves the `- ` list item and so cannot see the difference between `with:` and `run:` — a heredoc line is inside a step exactly as an input @@ -1017,6 +1089,11 @@ def _is_ref_input(lines, idx): the dangling check existed. Narrowing a false FAILURE back to the old miss is the safe direction; the reverse is not. """ + if _in_block_scalar(lines, idx): + # Script text, not YAML — asked FIRST, so it also closes the flow + # spelling's copy of the same hole (a heredoc line reading + # `with: {ref: "${{ … }}"}` carries its own false answer). + return False if _WITH_FLOW_RE.search(_strip_comment(lines[idx])): return True ind = _indent(lines[idx]) @@ -1024,7 +1101,14 @@ def _is_ref_input(lines, idx): if _is_skippable(lines[j]): continue if _indent(lines[j]) < ind: - return bool(_WITH_KEY_RE.match(lines[j])) + # `_dedash` because `with:` may ride the list-item line: mapping + # keys are unordered, so `- with:` / `ref: …` / `uses: checkout` + # is valid Actions YAML. Without it the marker holds the key + # column, the match fails, and the site is DROPPED — turning the + # fail-closed report this gate protects into a silent fail-open on + # exactly the shape the lint exists to close, one an author could + # pick deliberately to evade it. + return bool(_WITH_KEY_RE.match(_dedash(lines[j]))) return False @@ -1122,6 +1206,10 @@ def _record_steps_output(found, lines, idx, resolved, resolvers, step_ids): release lookup — which is not this lint's subject, and demanding an empty-ref `if:` of it would fail workflows the lint has no claim on. + That scope question is asked FIRST, ahead of operand order, because it + holds in every operand position — the lint has no claim on such a step + whether or not the ref's expression starts with its output. + When `` matches NO step declared before the consuming one (a typo'd id, a step in another job, a resolver declared below its consumer), the site is recorded as a DANGLING ref use (BE-8215): at runtime the @@ -1153,16 +1241,6 @@ def _record_steps_output(found, lines, idx, resolved, resolvers, step_ids): # Not an action input, so not a checkout — a job-level `outputs:` # mapping, a `run:` heredoc. Nothing to judge and nothing to fail. return - if not leading: - # Judged BEFORE step existence on purpose: when the leading operand - # wins, the output is never consulted, so "no such step" is a red - # herring and fixing the id changes nothing. Operand order is the only - # fix, and it needs its own message to say so. - found.append((idx + 1, False, False, "non-leading")) - return - # From here the output IS what the expression resolves to, so the two - # questions that remain — does the step exist, and does anything cover it — - # are worth asking. if step_id not in resolvers: declared = step_ids.get(step_id) bounds = _consuming_step_bounds(lines, idx) @@ -1171,8 +1249,27 @@ def _record_steps_output(found, lines, idx, resolved, resolvers, step_ids): # step's `with:` evaluation its output does not exist yet — so the # boundary is the consuming STEP's first line, not the `ref:` line. if declared is not None and declared < consumer_start: + # OUT OF SCOPE, and asked ahead of operand order on purpose: a + # `ref:` resolved from a real earlier step that never touches + # `workflows_ref` is not this lint's subject in ANY operand + # position. Judging `leading` first reported + # `ref: ${{ inputs.pr_sha || steps.detect.outputs.sha }}` — a + # perfectly ordinary checkout — as 'non-leading', printing an + # error that demands an operand reorder which CHANGES the + # workflow's runtime semantics. return - found.append((idx + 1, False, False, "dangling")) + if leading: + # No step of that id runs ahead of the checkout, and the output IS + # what the expression resolves to: `''` at runtime, which + # `actions/checkout` reads as the default branch. + found.append((idx + 1, False, False, "dangling")) + return + # A dangling id whose operand does not lead falls through to the + # non-leading verdict below: the leading operand wins, so the output is + # never consulted, "no such step" is a red herring, and fixing the id + # changes nothing. Operand order is the only fix. + if not leading: + found.append((idx + 1, False, False, "non-leading")) return guarded = resolvers[step_id] or _skips_on_empty_output(lines, idx, step_id, out) found.append((idx + 1, False, guarded, True)) @@ -1261,6 +1358,13 @@ def ref_checkouts(lines): # Continuation lines are the more-indented ones that follow; the first # line back at or above the key's indent closes the scalar. pending = None + # Those continuation lines, stripped, in order. A block scalar may + # split the ref's `${{ … }}` across PHYSICAL lines and still fold to + # one expression at runtime, so matching each line on its own left a + # single newline enough to hide the very spelling BE-8215 closed: + # `ref: >-` / `${{ steps.r.outputs.ref ||` / `'main' }}` matched + # neither continuation arm and recorded no site. + pending_parts = [] for i, line in _block_body(lines, start, job_indent): if pending is not None: if _indent(line) > pending[1]: @@ -1274,7 +1378,16 @@ def ref_checkouts(lines): found.append((pending[0] + 1, fallback, guarded, False)) pending = None continue + pending_parts.append(_strip_comment(line)) resolved = _steps_output_site(line, cont=True) + if resolved is None and len(pending_parts) > 1: + # Ask the FOLDED value — what the runtime actually + # sees — only once the single line has failed, so the + # common one-line spelling keeps its exact behavior and + # the join can only ever ADD a site. The `[^}]` bounds + # still cannot cross a `}}`, so a join can never span + # two interpolations. + resolved = _steps_output_site(" ".join(pending_parts), cont=True) if resolved is not None: # The `ref: >-` / `ref: |` spelling of the resolve-then- # consume shape. Judged from the same place as the block @@ -1337,6 +1450,7 @@ def ref_checkouts(lines): # (`_REF_KEY_OPEN_RE` needs end-of-line right after the key, so # it can never take a `ref: ${{ … }}` off the branch below.) pending = (i, _indent(line)) + pending_parts = [] else: resolved = _steps_output_site(line) if resolved is not None: diff --git a/.github/workflow-pins/tests/test_check_workflow_pins.py b/.github/workflow-pins/tests/test_check_workflow_pins.py index 2118dd3a..dcee69c6 100644 --- a/.github/workflow-pins/tests/test_check_workflow_pins.py +++ b/.github/workflow-pins/tests/test_check_workflow_pins.py @@ -1349,6 +1349,116 @@ def test_a_ref_line_inside_a_run_heredoc_is_not_a_checkout(self): ) self.assertEqual(cwp.ref_checkouts(self._wrap(heredoc).split("\n")), []) + def test_an_unrelated_earlier_step_stays_out_of_scope_in_any_operand_position(self): + # `ref: ${{ inputs.pr_sha || steps.detect.outputs.sha }}` resolved from + # a REAL earlier step that never touches `workflows_ref` is an ordinary + # checkout this lint has no claim on. Judging operand order ahead of + # scope hoisted it past the out-of-scope return and hard-failed it as + # 'non-leading' — printing an error that demands an operand reorder, + # which changes the workflow's runtime semantics. + ref = "${{ inputs.pr_sha || steps.resolve_ref.outputs.ref }}" + steps = self.UNRELATED_RESOLVER + self._step_output_checkout(ref=ref) + self.assertEqual(cwp.ref_checkouts(self._wrap(steps).split("\n")), []) + # …and the same step in the LEADING position is equally out of scope, + # which is the behavior that was already correct. + self.assertEqual( + cwp.ref_checkouts( + self._wrap( + self.UNRELATED_RESOLVER + self._step_output_checkout() + ).split("\n") + ), + [], + ) + + def test_a_dangling_id_behind_a_leading_operand_is_reported_non_leading(self): + # Scope moved ahead of operand order; the ordering between DANGLING and + # 'non-leading' did not. With the leading operand winning, the output is + # never consulted, so "no such step" is a red herring and fixing the id + # changes nothing — operand order is the only fix, and it needs the + # message that says so. + ref = "${{ 'main' || steps.resolve_reff.outputs.ref }}" + sites = cwp.ref_checkouts( + self._wrap(self.RESOLVER + self._step_output_checkout(ref=ref)).split("\n") + ) + self.assertEqual( + [(fb, guarded, via) for _, fb, guarded, via in sites], + [(False, False, "non-leading")], + ) + + def test_a_with_key_on_the_list_marker_line_is_seen(self): + # Mapping keys are unordered, so `- with:` ahead of `uses:` is valid + # Actions YAML — and the marker holds the key column, exactly as it does + # for `- id:` and `- if:`. Without the same normalization the `with:` + # gate answers False and the site is DROPPED, turning a fail-closed + # report into a silent fail-open on the shape the lint exists to close. + marker = ( + " - with:\n" + " ref: ${{ steps.resolve_ref.outputs.ref }}\n" + " uses: actions/checkout@abc\n" + ) + self.assertEqual(len(self._jobs(self.RESOLVER + marker)), 1) + # …and it is a real COVERED site once the exact `if:` is on it, rather + # than passing by being invisible. + guarded_marker = marker + self.EXACT_IF + sites = cwp.ref_checkouts(self._wrap(self.RESOLVER + guarded_marker).split("\n")) + self.assertEqual( + [(fb, guarded, via) for _, fb, guarded, via in sites], [(False, True, True)] + ) + + def test_a_heredoc_emitting_a_whole_step_is_not_a_checkout(self): + # The flat heredoc is not the only shape: a script emitting a STEP puts + # the word `with:` at exactly the indent the enclosing-key walk stops + # on, so indentation alone reads script output as an action input and + # hard-fails a compliant workflow. The open `|` block scalar is what + # tells the two apart. Both the block and the flow spelling. + for emitted in ( + " with:\n ref: ${{ steps.resolve_ref.outputs.ref }}\n", + ' - uses: actions/checkout@abc\n' + ' with: {ref: "${{ steps.resolve_ref.outputs.ref }}"}\n', + ): + with self.subTest(emitted=emitted.strip()): + heredoc = ( + " - name: Write a fixture\n" + " run: |\n" + " cat <<'EOF' > f.yml\n" + emitted + " EOF\n" + ) + self.assertEqual(cwp.ref_checkouts(self._wrap(heredoc).split("\n")), []) + # The scalar CLOSES: a real checkout after the heredoc is still judged. + after = ( + " - name: Write a fixture\n" + " run: |\n" + " cat <<'EOF' > f.yml\n" + " with:\n" + " EOF\n" + ) + self._step_output_checkout() + self.assertEqual(len(self._jobs(self.RESOLVER + after)), 1) + + def test_a_folded_ref_split_across_lines_is_read_as_one_expression(self): + # `ref: >-` folds its continuation lines into ONE value, so an + # expression split across two of them is at runtime exactly the + # mutable-fallback ref BE-8215 closed. Matching each physical line on + # its own left a single newline enough to hide it. + split = ( + " - name: Load assets\n" + " uses: actions/checkout@abc\n" + " with:\n" + " ref: >-\n" + " ${{ steps.resolve_ref.outputs.ref ||\n" + " 'main' }}\n" + ) + self.assertEqual(len(self._jobs(self.RESOLVER + split)), 1) + # Reported at the `ref:` KEY line — the checkout the reader must find — + # as the single-line continuation spelling already is. + text = self._wrap(self.RESOLVER + split).split("\n") + self.assertEqual(text[cwp.find_unguarded_ref_checkouts(text)[0] - 1].strip(), "ref: >-") + # …and the exact `if:` on the consuming step still covers it. + guarded = split.replace( + " - name: Load assets\n", + " - name: Load assets\n" + self.EXACT_IF, + 1, + ) + self.assertEqual(self._jobs(self.RESOLVER + guarded), []) + def test_a_fallback_containing_a_comma_is_still_read(self): # `[^,}]` is the FLOW form's entry boundary and nothing else's. # Carrying it into the block form dropped every fallback holding a From 91ab7fb5600fd1e9587a7b8df989c412351374ab Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Thu, 20 Aug 2026 17:22:46 -0700 Subject: [PATCH 5/5] fix(workflow-pins): fail loud on a `ref:` expression the step-output reader cannot parse (BE-8253) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The step-output reader gave ONE verdict per line from ONE regex family, and `ref_checkouts`'s else-arm silently skipped anything it could not match. Five shapes escaped it, confirmed fail-open through the real CLI: a fixture whose checkout reads `ref: ${{ steps.x.outputs.ref || format('refs/heads/{0}', 'main') }}` passed the lint (exit 0, "every ref checkout guarded") while the identical workflow spelled bare correctly failed. The reader is now two-tier. A LOOSE tier counts `steps..outputs.` mentions in the comment-stripped `ref:` VALUE; the STRICT tier reads every interpolation and every top-level `||` operand in that value. Loose > strict records the site as `'unparsed'` — truthy, so the unguarded projection needs no change, same trick as `'dangling'`/`'non-leading'` — and `check_dir` prints a message naming the two spellings the lint CAN judge. Widening the strict reader to evaluate `format()`, `&&` or parenthesized operands is deliberately not the fix: an unknown spelling asks its author for a supported one. The exhaustive strict tier also closes two partial parses where the operand nobody judged was a live checkout ref: a value concatenating two interpolations (the block pattern's greedy `.*` judged only the last) and a `||` chain of two step outputs (the fallback stretch swallowed the second). Every operand is now judged independently and the strongest requirement wins — a covered sibling excuses nothing. A step output ahead of another operand no longer makes it non-leading, because an unresolved output is `''` and `||` really falls through it; that leading output is judged in its own right. Gated by `_is_ref_input` exactly as the other states are: a job-level `outputs:` mapping or a `run:` heredoc holding an unparseable expression is not a checkout, and hard-failing one is the false-CI-failure channel BE-8215 already closed once. The flow entry boundary is now interpolation-aware, since the naive `[^,}]` bound cut a value mid-expression and hid the rest from both tiers. Refs BE-8253 --- .github/workflow-pins/README.md | 34 +- .github/workflow-pins/check_workflow_pins.py | 453 +++++++++++++----- .../tests/test_check_workflow_pins.py | 256 ++++++++++ 3 files changed, 623 insertions(+), 120 deletions(-) diff --git a/.github/workflow-pins/README.md b/.github/workflow-pins/README.md index 436fc7ee..f9c46ce3 100644 --- a/.github/workflow-pins/README.md +++ b/.github/workflow-pins/README.md @@ -127,12 +127,36 @@ message, because neither BE-8130 remedy can fix operand order. A leading operand `||` falls *through* (`false`, `''`, `""`, `0`, `null`) still reaches the output and is judged normally. -Spellings this reader still does not recognize — a fallback containing a brace +**A spelling the reader cannot parse is REFUSED, not skipped (BE-8253).** The +reader is two-tier: a permissive tier asks whether the comment-stripped `ref:` +value mentions `steps..outputs.` at all, and the strict tier reads +every interpolation and every top-level `||` operand in it. When the first +counts more mentions than the second could account for, the site is reported — +the lint says it cannot judge this expression and names the spellings it can. +Unrecognized spellings include a fallback containing a brace (`|| format('refs/heads/{0}', 'main')`), a parenthesized operand -(`(steps..outputs.) || 'main'`), and `&&` rather than `||` — match -nothing and record no site, exactly as every `||` spelling did before BE-8215. -Write the ref as a bare `${{ steps..outputs. }}` under the exact -`if:`, or as a plain `|| ` fallback, and it is covered. +(`(steps..outputs.) || 'main'`), `&&` rather than `||`, and — in the +flow form only, whose entry boundary is a comma — a fallback containing one +(`|| 'a,b'`). Each of those used to match nothing and record no site, so the +lint PASSED a workflow it had never read while failing the identical one +spelled bare. Write the ref as a bare `${{ steps..outputs. }}` under +the exact `if:`, or as that expression with a trailing `|| ` fallback, +and it is covered. The reader does not evaluate `format()`, `&&` or +parenthesized expressions on purpose: an unknown spelling asks its author for a +supported one rather than growing an expression parser inside the lint. + +**Every operand is judged, and the strongest requirement wins (BE-8253).** A +`ref:` value can read more than one step output, and each one is a ref the +checkout can really resolve to — so each must independently pass (declared as +an earlier step, covered by a fail-closed resolver or the exact non-empty `if:`, +and reachable by operand order). A covered sibling excuses nothing. Two shapes +used to slip through on a single verdict per line: +`ref: "${{ steps.a.outputs.ref }}${{ steps.b.outputs.ref }}"`, where only the +LAST interpolation was judged even though both feed the value, and +`ref: ${{ steps.a.outputs.ref || steps.b.outputs.ref }}`, where the fallback +stretch swallowed `b`. A step output ahead of another operand does not make it +non-leading: an unresolved output is `''`, so `||` really can fall through to +what follows — and that leading output is judged in its own right. **The lint enforces that split, rather than trusting the prose.** The fallback answers *mutability*; the guard answers *emptiness*; a checkout using the diff --git a/.github/workflow-pins/check_workflow_pins.py b/.github/workflow-pins/check_workflow_pins.py index a7177f50..36f2840a 100644 --- a/.github/workflow-pins/check_workflow_pins.py +++ b/.github/workflow-pins/check_workflow_pins.py @@ -127,31 +127,66 @@ # carries what precedes the step output inside the interpolation so operand # order can be judged the same way there. # -# Those two widened stretches are bounded by `[^}]`, NOT the flow form's -# `[^,}]`: only the flow spelling needs a comma to end its entry, and carrying -# that bound into the block and continuation forms left a fallback containing a -# comma (`|| 'a,b'`) matching nothing at all — the same fail-open this change -# closes for the plain `|| ` spelling. `[^}]` still cannot cross a -# `}}`, so a match can never span two interpolations. The flow form keeps -# `[^,}]` throughout, exactly as `_REF_USE_FLOW_RE` bounds its own value, so a -# SIBLING entry carrying a step output cannot be misread as the ref. -def _steps_output_body(bound): - """The `${{ … steps..outputs. … }}` body, bounded by `bound`.""" - return ( - r"""\$\{\{(?P%s*?)steps\.(?P[A-Za-z0-9_-]+)""" - r"""\.outputs\.(?P[A-Za-z0-9_-]+)\s*(?:\|\|%s*?)?\}\}""" - ) % (bound, bound) - - -_STEPS_OUTPUT_BODY = _steps_output_body(r"""[^}]""") -_STEPS_OUTPUT_FLOW_BODY = _steps_output_body(r"""[^,}]""") -_STEPS_OUTPUT_BLOCK_RE = re.compile(r"""^\s*(['"]?)ref\1\s*:.*%s""" % _STEPS_OUTPUT_BODY) -_STEPS_OUTPUT_FLOW_RE = re.compile( - r"""[{,]\s*(['"]?)ref\1\s*:[^,}]*%s""" % _STEPS_OUTPUT_FLOW_BODY +# …and the reader is TWO-TIER (BE-8253), because ONE regex per line can only +# give ONE verdict per line, while a `ref:` value can hold several step outputs +# — or a spelling this reader does not understand at all: +# +# LOOSE — does the comment-stripped `ref:` VALUE mention +# `steps..outputs.` anywhere, any number of times? +# STRICT — the patterns below, run over EVERY interpolation in that value and +# every top-level `||` operand inside each one. +# +# When LOOSE counts more mentions than STRICT accounted for, the value plainly +# reaches a step output this reader cannot judge, and the site is recorded +# `'unparsed'` so the lint REFUSES it out loud. Before the split it answered +# "no site" instead: `ref: ${{ steps.x.outputs.ref || format('refs/heads/{0}', +# 'main') }}` matched nothing (the `}` in `{0}` breaks the fallback stretch), +# recorded nothing, and PASSED — fail-open on exactly the runtime behavior this +# lint exists to close, and the identical workflow spelled bare failed. So did +# `(steps.x.outputs.ref) || 'main'` and `steps.x.outputs.ref && 'main'`. +# Teaching the strict reader to EVALUATE `format()` / `&&` / parenthesized +# operands is deliberately not the fix: an unknown spelling asks its author for +# a supported one rather than growing an expression parser in here. +# +# The strict stretches are bounded by `[^}]`, NOT the flow form's `[^,}]`: only +# the flow spelling needs a comma to end its entry, and carrying that bound +# into the block and continuation forms left a fallback containing a comma +# (`|| 'a,b'`) matching nothing at all — the same fail-open. `[^}]` still +# cannot cross a `}}`, so an interpolation match can never span two of them, +# and a body carrying a brace of its own is how shape 1 above reaches +# `'unparsed'` rather than being silently skipped. +_LOOSE_STEPS_OUTPUT_RE = re.compile( + r"""steps\.[A-Za-z0-9_-]+\.outputs\.[A-Za-z0-9_-]+""" +) +# An operand that is NOTHING BUT a step output. `||` falls through an empty +# one, so unlike a truthy literal it does not decide the value for the operands +# behind it — see `_lead_reaches_output`. +_BARE_STEPS_OUTPUT_RE = re.compile( + r"""^steps\.[A-Za-z0-9_-]+\.outputs\.[A-Za-z0-9_-]+$""" ) -_STEPS_OUTPUT_CONT_RE = re.compile( - r"""^\s*(?P['"]?)%s(?P=q)[^\S\n]*$""" % _STEPS_OUTPUT_BODY +# The strict tier's unit: what the old single-match body required of the +# stretch AROUND the output, asked of one `||` operand at a time. `lead` keeps +# its meaning (what precedes the output, judged by `_lead_reaches_output`), and +# the `\s*$` anchor is what refuses the parenthesized and `&&` spellings — +# both carry something AFTER the output name that this reader cannot evaluate. +_STEPS_OUTPUT_OPERAND_RE = re.compile( + r"""^(?P.*?)steps\.(?P[A-Za-z0-9_-]+)""" + r"""\.outputs\.(?P[A-Za-z0-9_-]+)\s*$""" ) + + +def _steps_interp_re(bound): + """`${{ … }}`, its body bounded by `bound` — one strict-tier unit.""" + return re.compile(r"""\$\{\{(?P%s*)\}\}""" % bound) + + +_STEPS_INTERP_RE = _steps_interp_re(r"""[^}]""") +_STEPS_INTERP_FLOW_RE = _steps_interp_re(r"""[^,}]""") +# Where a `ref:` VALUE begins, per spelling. The block form takes the rest of +# the line; a flow entry is delimited by `_flow_entry_value`; the continuation +# line under `ref: >-` / `ref: |` IS the value and carries no key at all. +_REF_KEY_VALUE_RE = re.compile(r"""^\s*(['"]?)ref\1\s*:(?P.*)$""") +_REF_FLOW_KEY_RE = re.compile(r"""[{,]\s*(['"]?)ref\1\s*:""") # The producing step's `id:`, read at the step's own key column. Quoted or bare # — both are valid Actions YAML — and `\S+` stops before a trailing comment on # its own, because YAML needs whitespace ahead of a `#` for it to open one. @@ -561,65 +596,91 @@ def is_ref_use(line, res=None): return bool(block_re.match(line) or flow_re.search(line)) -def _steps_output_match(code, cont=False): - """The `_STEPS_OUTPUT_*` match object for `code`, or None.""" - if cont: - return _STEPS_OUTPUT_CONT_RE.match(code) - match = _STEPS_OUTPUT_BLOCK_RE.match(code) - if match is None: - # The flow form `search`es mid-line, so its `[{,]` entry boundary can - # be met by a comma INSIDE a quoted sibling — planting a decoy `ref:` - # that resolves to a step no checkout consumes, while the real `ref:` - # further along the line is never examined. `_pins_to_job_workflow_sha` - # answers that by requiring its match to sit outside quotes; here the - # walk must also keep LOOKING past the decoy, because stopping at it - # drops the site out of coverage entirely rather than merely scoring - # it weaker. - for candidate in _STEPS_OUTPUT_FLOW_RE.finditer(code): - if _outside_quotes(code, candidate.start()): - return candidate - return match +def _flow_entry_value(code, start): + """The flow-mapping entry value beginning at `start`, up to its boundary. + `${{ … }}` is ATOMIC here: a `,` or `}` INSIDE an interpolation belongs to + the expression (`|| 'a,b'`, `format('refs/heads/{0}', 'main')`), not to the + mapping, so the naive `[^,}]` bound cuts the value mid-expression and hides + the rest of it from BOTH tiers — which would read as "nothing to see" on + exactly the shapes BE-8253 exists to refuse. Outside an interpolation the + first `,` or `}` still ends the entry, so a SIBLING entry carrying a step + output cannot be misread as the ref. + """ + depth = 0 + i = start + while i < len(code): + if code.startswith("${{", i): + depth += 1 + i += 3 + continue + if depth and code.startswith("}}", i): + depth -= 1 + i += 2 + continue + if not depth and code[i] in ",}": + break + i += 1 + return code[start:i] -def steps_output_ref(line, cont=False): - """(step id, output name) when `line`'s `ref:` IS a step output, else None. - Answers only "which step produced this ref" — never whether the checkout is - covered. `ref_checkouts` decides that, because the answer depends on which - steps the job has already walked past. `cont=True` judges a CONTINUATION - line instead: the bare expression under a `ref: >-` / `ref: |` key, which - carries no `ref:` of its own. +def _ref_values(code, cont=False): + """[(value, flow)] for every `ref:` value on the comment-stripped `code`. + + Empty when the line carries no `ref:` key at all — the answer for most + lines, since the walk asks this of every line in the job. - Comments are stripped first, for the same reason `_pins_to_job_workflow_sha` - strips them: prose merely naming a step output (`ref: main # was - ${{ steps.x.outputs.ref }}`) is not a checkout resolved from one. + The flow form yields one entry per `ref:` sitting OUTSIDE any quoted + scalar. A comma inside a quoted sibling meets the `[{,]` entry boundary, so + a decoy `ref:` can be planted in string content; those are skipped and the + scan keeps LOOKING past them, the same discipline `_pins_to_job_workflow_sha` + applies — stopping at a decoy drops the real site out of coverage entirely + rather than merely scoring it weaker. """ - # Asked of nearly every line of every job (the `else` arm of the walk), and - # a `steps.` substring is a precondition of all three patterns — so answer - # the common case before paying for the comment strip and the regexes. - if "steps." not in line: - return None - match = _steps_output_match(_strip_comment(line), cont) - return (match.group("id"), match.group("out")) if match else None + if cont: + return [(code, False)] + match = _REF_KEY_VALUE_RE.match(code) + if match: + return [(match.group("value"), False)] + return [ + (_flow_entry_value(code, entry.end()), True) + for entry in _REF_FLOW_KEY_RE.finditer(code) + if _outside_quotes(code, entry.start()) + ] # Operands `||` falls THROUGH, so a leading one of these still lets the step # output be the value (BE-8215). `||` returns the first TRUTHY operand, not the -# first operand — reading `leading` as "nothing precedes the output" reported +# first operand, so reading `leading` as "nothing precedes the output" reported # `${{ false || steps.x.outputs.ref }}` as unguarded unconditionally, with a # message no edit can satisfy, even though it resolves to exactly the output a # guard covers. GitHub's expression language treats these five as false. _FALSEY_OPERANDS = frozenset(("false", "''", '""', "0", "null")) +def _falls_through(operand): + """True when `||` cannot stop at `operand` — so what follows may be the ref. + + The five falsey literals, plus a bare `steps..outputs.`: an + unresolved output is `''`, which is falsey, so `${{ steps.a.outputs.ref || + steps.b.outputs.ref }}` really can resolve to `b`. That second operand only + became VISIBLE with the exhaustive reader (BE-8253) — the single-match one + swallowed it into the fallback stretch and judged `a` alone — and it is + judged in its own right, so nothing is excused by falling through here. + """ + operand = operand.strip() + return operand in _FALSEY_OPERANDS or bool(_BARE_STEPS_OUTPUT_RE.match(operand)) + + def _lead_reaches_output(lead): """True when `lead` cannot stop the step output being the ref's value. - `lead` is what precedes `steps..outputs.` inside the `${{ … }}`. - Empty is the common case. Anything else has to be a chain of `||` operands - that all fall through — a truthy leading operand (`'main' ||`) wins on - every runner, and nothing the consuming step or the resolver can do will - change that, so the site is unguarded unconditionally. + `lead` is what precedes `steps..outputs.` inside the `${{ … }}`, + operands ahead of it included. Empty is the common case. Anything else has + to be a chain of `||` operands that all fall through — a truthy leading + operand (`'main' ||`) wins on every runner, and nothing the consuming step + or the resolver can do will change that, so the site is unguarded + unconditionally. """ lead = lead.strip() if not lead: @@ -628,30 +689,128 @@ def _lead_reaches_output(lead): # Not an `||` chain at all — a `(`, a `format(`, an `&&`. Unrecognized # rather than proven harmless, so judge it the fail-closed way. return False - return all( - operand.strip() in _FALSEY_OPERANDS for operand in lead[:-2].split("||") - ) + return all(_falls_through(operand) for operand in lead[:-2].split("||")) -def _steps_output_site(line, cont=False): - """(step id, output name, leading) for the walk's judgment, else None. +def _strict_steps_output_sites(value, flow): + """[(id, out, leading)] for every step output the strict tier can read. - `leading` is True when the ref expression's first `||` operand IS the step - output — the step-output twin of `_leading_operand_reaches_input`. GitHub's - `||` returns the first truthy operand, so `ref: ${{ 'main' || - steps.x.outputs.ref }}` reads the output while resolving to a mutable - branch on every runner; neither a hard-guard resolver nor the exact `if:` - can change that, so a non-leading output is unguarded unconditionally. - Judged from the `lead` group of the SAME match rather than from the line's - first interpolation, because a quoted decoy sibling can put an unrelated - interpolation ahead of the real one. + EXHAUSTIVE, where the old reader stopped at its first match: every + interpolation in `value`, and every top-level `||` operand inside each one. + Two whole shapes hid behind that first match, and in both the operand + nobody judged is a live checkout ref (BE-8253): + + - `ref: "${{ steps.a.outputs.ref }}${{ steps.b.outputs.ref || 'main' }}"` — + the block pattern's greedy `.*` landed on the LAST interpolation, so `a` + was never judged. Both interpolations feed the value, so both must be. + - `ref: ${{ steps.a.outputs.ref || steps.b.outputs.ref }}` — the fallback + stretch swallowed `b`, so a covered `a` passed the whole site while `b` + reached an uncovered output. + + `leading` is per operand and reads the operands AHEAD of it, so the + single-operand answers are unchanged: `${{ 'main' || }}` is still + non-leading and `${{ false || }}` still reaches the output. """ + interp_re = _STEPS_INTERP_FLOW_RE if flow else _STEPS_INTERP_RE + sites = [] + for interp in interp_re.finditer(value): + operands = interp.group("body").split("||") + for pos, operand in enumerate(operands): + match = _STEPS_OUTPUT_OPERAND_RE.match(operand) + if match is None: + continue + lead = match.group("lead") + if pos: + lead = "||".join(operands[:pos]) + "||" + lead + sites.append( + (match.group("id"), match.group("out"), _lead_reaches_output(lead)) + ) + return sites + + +# Recorded in place of a site list when the LOOSE tier sees a step output the +# STRICT tier could not account for. A module constant so the walk, the +# recorder and `check_dir` all name the same state. +UNPARSED = "unparsed" + + +def _steps_output_sites(line, cont=False): + """Every step output `line`'s `ref:` reads, `UNPARSED`, or None (BE-8253). + + None when the value names no step output at all — the common case, and the + answer for prose that merely mentions one, since comments are stripped + first for the same reason `_pins_to_job_workflow_sha` strips them: + `ref: main # was ${{ steps.x.outputs.ref }}` is not a checkout resolved + from a step output. The loose tier runs only on the comment-stripped VALUE, + so it cannot fire on that line either. + + `UNPARSED` when the loose tier counts more mentions than the strict tier + accounted for. The value plainly reaches a step output and this reader + cannot say WHICH, or under what condition — so it must not answer "no + site", which is the fail-open this state closes: the lint passed + `${{ steps.x.outputs.ref || format('refs/heads/{0}', 'main') }}` while + failing the identical workflow spelled bare. + + Otherwise the list, one tuple per operand, for `_record_steps_output` to + judge INDEPENDENTLY. `cont=True` judges a CONTINUATION line instead: the + value under a `ref: >-` / `ref: |` key, which carries no `ref:` of its own. + """ + # Asked of nearly every line of every job (the `else` arm of the walk), and + # a `steps.` substring is a precondition of every pattern below — so answer + # the common case before paying for the comment strip and the scan. if "steps." not in line: return None - match = _steps_output_match(_strip_comment(line), cont) - if match is None: + code = _strip_comment(line) + for value, flow in _ref_values(code, cont): + mentions = len(_LOOSE_STEPS_OUTPUT_RE.findall(value)) + if not mentions: + continue + sites = _strict_steps_output_sites(value, flow) + # A strictly-read operand contains exactly one mention and operands do + # not overlap, so the strict tier can never account for MORE than the + # loose tier saw; fewer means at least one mention went unread. + return sites if len(sites) >= mentions else UNPARSED + return None + + +def steps_output_ref(line, cont=False): + """(step id, output name) for the FIRST step output `line`'s `ref:` reads. + + Answers only "which step produced this ref" — never whether the checkout is + covered. `ref_checkouts` decides that, because the answer depends on which + steps the job has already walked past. None when the value reads none, and + None for an `UNPARSED` value too: there is no id to name where the reader + could not read one. + """ + sites = _steps_output_sites(line, cont) + if not isinstance(sites, list) or not sites: return None - return match.group("id"), match.group("out"), _lead_reaches_output(match.group("lead")) + step_id, out, _ = sites[0] + return step_id, out + + +def _reported_step_output(line, state): + """The `steps..outputs.` an error message for `state` should NAME. + + A `ref:` can read SEVERAL step outputs (BE-8253) and only one of them need + be the offending operand, so naming the first would point the author at a + sibling that is fine. `'non-leading'` is answerable from the line alone — + it is the first operand something precedes — while `'dangling'` is a + property of the JOB, not the line, so a multi-output value falls back to + the placeholders rather than naming the wrong step. Same fallback the + `ref: >-` continuation spelling already takes, which reports the KEY line + and keeps its value below it. + """ + sites = _steps_output_sites(line) + if not isinstance(sites, list) or not sites: + return "", "" + if state == "non-leading": + for step_id, out, leading in sites: + if not leading: + return step_id, out + if len(sites) == 1: + return sites[0][0], sites[0][1] + return "", "" def _consumes_input(text): @@ -1114,9 +1273,24 @@ def _skips_on_empty_output(lines, idx, step_id, out): return False -def _record_steps_output(found, lines, idx, resolved, resolvers, step_ids): +def _record_steps_output(found, lines, idx, sites, resolvers, step_ids): """Record the `ref:` at `idx`, which reads `steps..outputs.`. + `sites` is EVERY step output the value reads (BE-8253), and every one of + them is judged INDEPENDENTLY: an operand reaching an uncovered step output + is not excused by a covered sibling, and for a value concatenating two + interpolations both feed the ref, so both must be covered. The strongest + requirement wins — the site is guarded only when all of them are. + + `sites` is `UNPARSED` when the value plainly reads a step output the strict + reader could not account for. There is nothing to resolve then, and the one + honest answer is to REFUSE the expression rather than pass it unexamined, + so the site is recorded `'unparsed'` for `check_dir` to name a supported + spelling. Gated by `_is_ref_input` like every other state below it: a + job-level `outputs:` mapping or a `run:` heredoc holding an unparseable + expression is not a checkout, and hard-failing one is the false-CI-failure + channel the dangling check already had to close once. + Records NOTHING only when `` names a real step declared AHEAD of the consuming one that never touches `workflows_ref` — a `git rev-parse`, a release lookup — which is not this lint's subject, and demanding an @@ -1148,34 +1322,54 @@ def _record_steps_output(found, lines, idx, resolved, resolvers, step_ids): and there is no expression to compare here — the `if:` tests the resolved VALUE, so guard strength is moot on this path. """ - step_id, out, leading = resolved if not _is_ref_input(lines, idx): # Not an action input, so not a checkout — a job-level `outputs:` # mapping, a `run:` heredoc. Nothing to judge and nothing to fail. return - if not leading: - # Judged BEFORE step existence on purpose: when the leading operand - # wins, the output is never consulted, so "no such step" is a red - # herring and fixing the id changes nothing. Operand order is the only - # fix, and it needs its own message to say so. - found.append((idx + 1, False, False, "non-leading")) + if sites == UNPARSED: + found.append((idx + 1, False, False, UNPARSED)) return - # From here the output IS what the expression resolves to, so the two - # questions that remain — does the step exist, and does anything cover it — - # are worth asking. - if step_id not in resolvers: - declared = step_ids.get(step_id) - bounds = _consuming_step_bounds(lines, idx) - consumer_start = bounds[0] if bounds is not None else idx - # A step's OWN id must not excuse a ref consuming it — during the - # step's `with:` evaluation its output does not exist yet — so the - # boundary is the consuming STEP's first line, not the `ref:` line. - if declared is not None and declared < consumer_start: - return - found.append((idx + 1, False, False, "dangling")) + verdicts = [] + for step_id, out, leading in sites: + if not leading: + # Judged BEFORE step existence on purpose: when the leading operand + # wins, the output is never consulted, so "no such step" is a red + # herring and fixing the id changes nothing. Operand order is the + # only fix, and it needs its own message to say so. + verdicts.append("non-leading") + continue + # From here the output IS a value this operand can resolve to, so the + # two questions that remain — does the step exist, and does anything + # cover it — are worth asking. + if step_id not in resolvers: + declared = step_ids.get(step_id) + bounds = _consuming_step_bounds(lines, idx) + consumer_start = bounds[0] if bounds is not None else idx + # A step's OWN id must not excuse a ref consuming it — during the + # step's `with:` evaluation its output does not exist yet — so the + # boundary is the consuming STEP's first line, not the `ref:` line. + if declared is not None and declared < consumer_start: + # Out of scope, not covered: an operand this lint has no claim + # on neither fails the site nor vouches for its siblings. + continue + verdicts.append("dangling") + continue + verdicts.append( + bool(resolvers[step_id] or _skips_on_empty_output(lines, idx, step_id, out)) + ) + if not verdicts: + # Every operand was out of scope — the same drop the single-operand + # reader made, for the same reason. return - guarded = resolvers[step_id] or _skips_on_empty_output(lines, idx, step_id, out) - found.append((idx + 1, False, guarded, True)) + # A failing operand decides the site, and its state decides the REMEDY the + # message prints, so the two states with their own message come first. + # `'non-leading'` outranks `'dangling'` for the reason it is judged first + # above: no change to the id or the step order can fix operand order. + for state in ("non-leading", "dangling"): + if state in verdicts: + found.append((idx + 1, False, False, state)) + return + found.append((idx + 1, False, all(verdicts), True)) def ref_checkouts(lines): @@ -1205,13 +1399,16 @@ def ref_checkouts(lines): carry `via_step_output`, are judged by `_record_steps_output` — a fail-closed resolver, or the exact non-empty `if:` on the consuming step — and never earn the fallback-strength exemption, because the `if:` tests the - resolved value rather than an expression. `via_step_output` is four-state - (BE-8215), every non-`False` value truthy so the unguarded projection needs - no change: `False` (the ref names the input), `True` (a step output), - `'dangling'` — a step output whose id matches no step declared before the - consuming one, so the expression is `''` at runtime and the checkout takes - the default branch unconditionally — or `'non-leading'`, a step output the - expression does not start with, so something ahead of it decides the value. + resolved value rather than an expression. `via_step_output` is five-state + (BE-8215, BE-8253), every non-`False` value truthy so the unguarded + projection needs no change: `False` (the ref names the input), `True` (a + step output, every operand of it covered), `'dangling'` — a step output + whose id matches no step declared before the consuming one, so the + expression is `''` at runtime and the checkout takes the default branch + unconditionally — `'non-leading'`, a step output the expression does not + start with, so something ahead of it decides the value — or `'unparsed'`, + a value that plainly reads a step output in a spelling this reader cannot + judge at all, which used to record no site and pass. """ aliases = env_aliases(lines) ref_res = _ref_use_res(aliases) @@ -1274,7 +1471,7 @@ def ref_checkouts(lines): found.append((pending[0] + 1, fallback, guarded, False)) pending = None continue - resolved = _steps_output_site(line, cont=True) + resolved = _steps_output_sites(line, cont=True) if resolved is not None: # The `ref: >-` / `ref: |` spelling of the resolve-then- # consume shape. Judged from the same place as the block @@ -1338,7 +1535,7 @@ def ref_checkouts(lines): # it can never take a `ref: ${{ … }}` off the branch below.) pending = (i, _indent(line)) else: - resolved = _steps_output_site(line) + resolved = _steps_output_sites(line) if resolved is not None: _record_steps_output(found, lines, i, resolved, resolvers, step_ids) return found @@ -1353,7 +1550,9 @@ def unguarded_ref_checkouts(lines): the consuming step's own `if:` — and BOTH are the wrong advice for a `'dangling'` site, where no step with that id precedes the checkout at all and the fix is the id itself, or a `'non-leading'` one, where the fix is - operand order and no guard anywhere can substitute for it (BE-8215). + operand order and no guard anywhere can substitute for it (BE-8215), or an + `'unparsed'` one, where the fix is to rewrite the expression in a spelling + the lint can judge (BE-8253). """ return [ (lineno, fb, via_step) @@ -1466,6 +1665,30 @@ def check_dir(workflows_dir, exempt=KNOWN_EXEMPT): ) for lineno, uses_fallback, via_step_output in unguarded_ref_checkouts(lines): + if via_step_output == UNPARSED: + # The value reads a step output in a spelling this lint cannot + # judge (BE-8253). Every other remedy below presumes a parse — + # naming an id, an operand order, an `if:` on a known output — + # so the only honest instruction is "write one of the two + # spellings that ARE judged". Deliberately no expression parser: + # an unknown spelling asks its author for a supported one. + errors.append( + "::error file=%s,line=%d::%s checks out at a `ref:` that " + "reads a `steps..outputs.` this lint cannot " + "parse, so it cannot tell whether the checkout is guarded " + "— and an unparsed ref used to pass silently while the " + "same workflow spelled bare failed. Unrecognized " + "spellings include a fallback containing a brace " + "(`|| format('refs/heads/{0}', 'main')`), a parenthesized " + "operand (`(steps..outputs.) || 'main'`), and " + "`&&` in place of `||`. Rewrite the ref as a bare " + "`${{ steps..outputs. }}` with the exact " + "non-empty `if:` on this step, or as that expression with " + "a trailing `|| ` fallback — the supported " + "spellings in .github/workflow-pins/README.md. " + "See BE-8253." % (path, lineno, name) + ) + continue if via_step_output in ("dangling", "non-leading"): # Name the ACTUAL id and output where the reported line still # holds the expression, so a typo — the first cause the @@ -1473,7 +1696,7 @@ def check_dir(workflows_dir, exempt=KNOWN_EXEMPT): # The `ref: >-` continuation spelling reports the KEY line and # keeps its value below it, so fall back to the placeholders # there rather than naming the wrong step. - step_id, out = steps_output_ref(lines[lineno - 1]) or ("", "") + step_id, out = _reported_step_output(lines[lineno - 1], via_step_output) if via_step_output == "dangling": # The `ref:` reads a step output whose id matches NO step # declared before the consuming one (BE-8215). The BE-8130 diff --git a/.github/workflow-pins/tests/test_check_workflow_pins.py b/.github/workflow-pins/tests/test_check_workflow_pins.py index 2118dd3a..a47911dc 100644 --- a/.github/workflow-pins/tests/test_check_workflow_pins.py +++ b/.github/workflow-pins/tests/test_check_workflow_pins.py @@ -1436,6 +1436,262 @@ def test_the_dangling_error_names_the_actual_step_id(self): self.assertIn("no step `resolve_reff` precedes", error) self.assertNotIn("", error) + # ------------------------------------------------------------------ + # The two-tier reader (BE-8253). One regex per line gives one verdict per + # line, so a `ref:` value the strict reader cannot chew — or one holding + # SEVERAL step outputs — used to record no site and pass the lint, while + # the identical workflow spelled bare failed. Loose tier: does the + # comment-stripped VALUE mention a step output at all? Strict tier: every + # interpolation, every top-level `||` operand. Loose > strict = refuse. + # ------------------------------------------------------------------ + + def _states(self, steps): + """(uses_fallback, guarded, via_step_output) for each site in one job.""" + return [ + (fb, guarded, via) + for _, fb, guarded, via in cwp.ref_checkouts(self._wrap(steps).split("\n")) + ] + + def _second_resolver(self, base, step_id="lookup"): + """`base` re-declared under a second id, so a two-operand `ref:` can + have each of its operands covered — or not — independently.""" + other = base.replace("id: resolve_ref", "id: %s" % step_id).replace( + "Resolve the asset ref", "Resolve the %s ref" % step_id + ) + self.assertNotEqual(other, base, "fixture drifted") + return other + + def test_a_fallback_containing_a_brace_is_refused_not_skipped(self): + # The `}` in `{0}` breaks the fallback stretch, so the strict reader + # matches nothing and the line used to leave the lint entirely — a + # confirmed fail-open through the real CLI: this workflow passed while + # the identical one spelled bare failed. + ref = "${{ steps.resolve_ref.outputs.ref || format('refs/heads/{0}', 'main') }}" + steps = self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=ref) + self.assertEqual(self._states(steps), [(False, False, "unparsed")]) + self.assertEqual(len(self._jobs(steps)), 1) + + def test_a_parenthesized_operand_is_refused_not_skipped(self): + # `)` after the output name matches neither `||` nor `}}`, so the + # strict reader stops — but the value plainly reads a step output. + ref = "${{ (steps.resolve_ref.outputs.ref) || 'main' }}" + steps = self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=ref) + self.assertEqual(self._states(steps), [(False, False, "unparsed")]) + + def test_an_and_operator_after_the_output_is_refused_not_skipped(self): + # Only `||` is read. `&&` is wrong in BOTH arms at runtime — truthy + # checks out at the mutable literal, falsey resolves to '' and checkout + # takes the default branch — so the one shape that must NOT happen is + # the lint staying quiet about it. + ref = "${{ steps.resolve_ref.outputs.ref && 'main' }}" + steps = self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=ref) + self.assertEqual(self._states(steps), [(False, False, "unparsed")]) + + def test_the_flow_and_continuation_spellings_refuse_it_too(self): + # Same treatment on all three spellings — a shape refused in the block + # form and skipped in the other two is the one-line bypass again. + expr = "${{ steps.resolve_ref.outputs.ref && 'main' }}" + flow = ( + " - name: Load assets\n" + " uses: actions/checkout@abc\n" + ' with: {repository: Comfy-Org/github-workflows, ref: "%s"}\n' % expr + ) + scalar = ( + " - name: Load assets\n" + " uses: actions/checkout@abc\n" + " with:\n" + " ref: >-\n" + " %s\n" % expr + ) + for spelling, steps in (("flow", flow), ("block scalar", scalar)): + with self.subTest(spelling=spelling): + self.assertEqual( + self._states(self.RESOLVER + steps), [(False, False, "unparsed")] + ) + + def test_a_flow_fallback_holding_a_comma_is_refused_not_skipped(self): + # `[^,}]` is the flow form's entry boundary, so a fallback carrying a + # comma is a spelling the strict reader genuinely cannot read there. + # The block form reads it (`test_a_fallback_containing_a_comma_is_still_read`); + # the flow form now REFUSES it instead of dropping the site. + flow = ( + " - name: Load assets\n" + " uses: actions/checkout@abc\n" + ' with: {ref: "${{ steps.resolve_ref.outputs.ref || \'a,b\' }}"}\n' + ) + self.assertEqual( + self._states(self.RESOLVER + flow), [(False, False, "unparsed")] + ) + + def test_a_commented_out_step_output_is_not_a_ref_use(self): + # The loose tier is permissive by design, so it MUST run on the + # comment-stripped value only — prose naming a step output is not a + # checkout resolved from one, and reporting it would fail a workflow + # whose `ref:` is a plain literal. + checkout = self._step_output_checkout(ref="main # was ${{ steps.resolve_ref.outputs.ref }}") + self.assertEqual(self._states(self.RESOLVER + checkout), []) + + def test_an_unparseable_expression_outside_a_with_input_is_not_a_checkout(self): + # The `_is_ref_input` gate, on the new state. The walk asks EVERY line + # of the job, so a job-level `outputs:` mapping and a `run:` heredoc + # emitting fixture YAML both reach the recorder — and hard-failing a + # compliant workflow with an error naming a checkout where there is no + # checkout is the false-CI-failure channel BE-8215 already had to close + # once. Do not reopen it. + expr = "${{ steps.resolve_ref.outputs.ref && 'main' }}" + heredoc = ( + " - name: Write a fixture\n" + " run: |\n" + " cat <<'EOF' > f.yml\n" + " ref: %s\n" + " EOF\n" % expr + ) + self.assertEqual(self._states(self.RESOLVER + heredoc), []) + job_outputs = ( + "name: F\non:\n workflow_call:\njobs:\n" + " job0:\n" + " runs-on: ubuntu-latest\n" + " outputs:\n" + " ref: %s\n" + " steps:\n" % expr + ) + self.RESOLVER + self.assertEqual(cwp.ref_checkouts(job_outputs.split("\n")), []) + + def test_a_quoted_decoy_does_not_hide_an_unparseable_real_ref(self): + # The decoy discipline and the new state compose: a `ref:` planted in + # string content meets the flow matcher's `[{,]` boundary, and stopping + # there would drop the REAL ref — which is itself unparseable — out of + # coverage entirely. + flow = ( + " - name: Load assets\n" + " uses: actions/checkout@abc\n" + ' with: {path: "x, ref: ${{ steps.decoy.outputs.ref }}", ' + 'ref: "${{ (steps.resolve_ref.outputs.ref) || \'main\' }}"}\n' + ) + self.assertEqual( + self._states(self.RESOLVER + flow), [(False, False, "unparsed")] + ) + + def test_both_concatenated_interpolations_are_judged(self): + # The block pattern's greedy `.*` landed on the LAST interpolation, so + # the first was never judged at all. Both feed the ref's value, so both + # must be covered — a fail-closed resolver each, since one step can + # carry only one exact `if:`. + ref = "${{ steps.lookup.outputs.ref }}${{ steps.resolve_ref.outputs.ref }}" + checkout = self._step_output_checkout(ref='"%s"' % ref) + both_hard = self._second_resolver(self.HARD_RESOLVER) + self.HARD_RESOLVER + self.assertEqual(self._jobs(both_hard + checkout), []) + # Cover only the SECOND — the one the old reader judged — and the site + # must still fail on the first. + one_hard = self._second_resolver(self.RESOLVER) + self.HARD_RESOLVER + self.assertEqual(len(self._jobs(one_hard + checkout)), 1) + # …and only the first: the same failure, from the other side. + other_hard = self._second_resolver(self.HARD_RESOLVER) + self.RESOLVER + self.assertEqual(len(self._jobs(other_hard + checkout)), 1) + + def test_every_or_operand_must_be_covered(self): + # `A || B` with both operands step outputs: the fallback stretch + # swallowed `B`, so a covered `A` passed the whole site while `B` + # reached an output nothing had judged. An unresolved `A` really is + # falsey, so `B` really can be the ref. + ref = "${{ steps.lookup.outputs.ref || steps.resolve_ref.outputs.ref }}" + checkout = self._step_output_checkout(ref=ref) + both_hard = self._second_resolver(self.HARD_RESOLVER) + self.HARD_RESOLVER + self.assertEqual(self._jobs(both_hard + checkout), []) + # Leading operand covered, trailing one not — the shape that used to + # pass. A covered sibling excuses nothing. + lead_hard = self._second_resolver(self.HARD_RESOLVER) + self.RESOLVER + self.assertEqual(len(self._jobs(lead_hard + checkout)), 1) + # …and the trailing operand is not reported `'non-leading'` merely for + # sitting behind another step output: `||` falls through an empty one. + self.assertEqual(self._states(lead_hard + checkout), [(False, False, True)]) + + def test_a_second_operand_naming_no_step_is_dangling(self): + # The exhaustive reader sees the operand the old one swallowed, so a + # typo in it is caught rather than excused by a covered leading operand. + ref = "${{ steps.resolve_ref.outputs.ref || steps.resolve_reff.outputs.ref }}" + steps = self.HARD_RESOLVER + self._step_output_checkout(ref=ref) + self.assertEqual(self._states(steps), [(False, False, "dangling")]) + + def test_the_supported_spellings_are_unchanged(self): + # No behavior change for a parsed single-operand site — the whole point + # of leaving the strict reader alone and adding a tier around it. + for ref in ( + "${{ steps.resolve_ref.outputs.ref }}", + "${{ steps.resolve_ref.outputs.ref || 'main' }}", + "${{ steps.resolve_ref.outputs.ref || 'a,b' }}", + ): + with self.subTest(ref=ref): + self.assertEqual( + self._states( + self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=ref) + ), + [(False, True, True)], + ref, + ) + self.assertEqual( + self._states(self.RESOLVER + self._step_output_checkout(ref=ref)), + [(False, False, True)], + ref, + ) + + def test_a_continuation_value_with_a_literal_prefix_is_a_site(self): + # The block form always read a value that only CONTAINS the + # interpolation (`ref: refs/heads/${{ … }}`); the continuation form used + # to demand the whole line BE one, so the same concatenation under + # `ref: >-` recorded no site. Reading the value the same way in all + # three spellings is the point — a checkout is not less of a checkout + # for having a prefix, and the value still resolves through the output. + scalar = ( + " - name: Load assets\n" + "%s" + " uses: actions/checkout@abc\n" + " with:\n" + " ref: >-\n" + " refs/heads/${{ steps.resolve_ref.outputs.ref }}\n" + ) + self.assertEqual( + self._states(self.RESOLVER + scalar % ""), [(False, False, True)] + ) + self.assertEqual(self._jobs(self.RESOLVER + scalar % self.EXACT_IF), []) + + def test_an_unparsed_ref_gets_its_own_error_text(self): + # Every other remedy presumes a parse — an id to name, an operand order + # to fix, an `if:` on a known output — so printing one of those here + # sends the author to edit something the lint never read. The message + # has to name the SUPPORTED spellings instead. + ref = "${{ steps.resolve_ref.outputs.ref || format('refs/heads/{0}', 'main') }}" + error = self._one_error( + self.RESOLVER + self._step_output_checkout(self.EXACT_IF, ref=ref) + ) + self.assertIn("cannot parse", error) + self.assertIn("BE-8253", error) + self.assertIn(".github/workflow-pins/README.md", error) + for wrong_remedy in ("BE-8130", "does not START with it", "no step `"): + self.assertNotIn(wrong_remedy, error) + + def test_a_multi_operand_error_does_not_name_the_wrong_step(self): + # The dangling message's whole value is naming the id to fix, and with + # two operands only one of them is the offending one — naming the first + # would send the author to edit a sibling that is fine. Step existence + # is a property of the JOB, not the line, so the placeholders are the + # honest answer there; a NON-leading operand is answerable from the + # line itself, so that one is still named exactly. + dangling = "${{ steps.resolve_ref.outputs.ref || steps.resolve_reff.outputs.ref }}" + error = self._one_error( + self.HARD_RESOLVER + self._step_output_checkout(ref=dangling) + ) + self.assertIn("no step `` precedes", error) + self.assertNotIn("no step `resolve_ref` precedes", error) + non_leading = "${{ steps.resolve_ref.outputs.ref || 'main' || steps.lookup.outputs.ref }}" + error = self._one_error( + self._second_resolver(self.HARD_RESOLVER) + + self.HARD_RESOLVER + + self._step_output_checkout(ref=non_leading) + ) + self.assertIn("steps.lookup.outputs.ref", error) + self.assertNotIn("", error) + def test_this_repos_own_workflows_guard_every_ref_checkout(self): root = os.path.normpath( os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "workflows")