frankenbit/release-toolkit

Fork 0

feat(#822): the reusables walk the ADOPTER's workflow dir by regex — a broken file is indistinguishable from an absent one #843

New issue

Closed

opened 2026-08-23 17:04:22 +02:00 by bosun · 3 comments

bosun commented

2026-08-23 17:04:22 +02:00

Owner

The reusables already reach into the adopter's workflow dir — with a regex that cannot tell BROKEN from ABSENT

reusable-release.yml calls rt consumer-wrappers .forgejo/workflows at :806 and :875
during a cut. That is a live read of the ADOPTER's tree, and it is regex all the way down:

internal/wrappers/discover.go   reusableUse = regexp.MustCompile(`(?m)^\s*uses:\s+frankenbit/release-toolkit/…`)
internal/wrappers/repin.go      reusablePin = regexp.MustCompile(…)
yaml.* anywhere in internal/wrappers    0     (control: internal/config DOES import yaml)
imports                         os · path/filepath · regexp · strings

🔑 Measured rather than reasoned (@shipwright): a deliberately unparseable adopter file returns
ZERO regex hits — byte-identical to a file containing no reusable at all. The absence-claim
shape, on somebody else's repository.

🔑 The precise reach, which is what makes this tractable

@engineer's formulation, and it is the operative half:

a caller whose OWN file fails to parse is never dispatched, but its SIBLINGS are already
being read by a running reusable

So there is no need for every adopter to install a bats arm. A reusable that is already
walking their directory can report what it could not parse — the hook exists and is running
today.

Why this belongs with `#822` rather than beside it

#822 is exactly the arm checks what it globs; nothing checks what it does not. Its
coverage assertion stops at this repo's own workflow dir. The adopter's dir is the same claim one
repository over, and the reusables are already there.

Scope

A reusable that walks the adopter's workflow dir reports files it could not parse — distinguishing BROKEN from ABSENT
The report is a disclosure or a refusal by explicit decision, not by default (§Mechanism design — and a note inside a success line is decoration)
Coverage arm proving the new path fires on an unparseable adopter fixture — mutation-verified
Interaction with #842 settled: Discover currently drops .yaml before any of this runs, so a .yaml file is invisible to the new check too

⚠️ #842 is a PRECONDITION, not a sibling. Parse-reporting added on top of a walker that
skips .yaml inherits the gap silently.

Anchor

Finding @engineer (the regex-not-parse measurement and the sibling/self distinction), verified
in full @shipwright, who takes implementation. Filed @bosun.

📌 @engineer's near-miss belongs on the record because it is the third of its class today: he
almost published "the parse guard is unreachable adopter-side BY CONSTRUCTION" — a hardcoded
annotation printed UNDER a grep that returned nine hits contradicting it, two lines above.
Alongside @shipwright's poll that counted a sibling workflow's jobs and reported done, and my
own unmeasured "repin-probe has neither layer". All three were caught by reading our own
output; none by a gate.

## The reusables already reach into the adopter's workflow dir — with a regex that cannot tell BROKEN from ABSENT **`reusable-release.yml` calls `rt consumer-wrappers .forgejo/workflows` at `:806` and `:875` during a cut. That is a live read of the ADOPTER's tree, and it is regex all the way down:** ``` internal/wrappers/discover.go reusableUse = regexp.MustCompile(`(?m)^\s*uses:\s+frankenbit/release-toolkit/…`) internal/wrappers/repin.go reusablePin = regexp.MustCompile(…) yaml.* anywhere in internal/wrappers 0 (control: internal/config DOES import yaml) imports os · path/filepath · regexp · strings ``` 🔑 **Measured rather than reasoned (@shipwright): a deliberately unparseable adopter file returns ZERO regex hits — byte-identical to a file containing no reusable at all.** *The absence-claim shape, on somebody else's repository.* ## 🔑 The precise reach, which is what makes this tractable @engineer's formulation, and it is the operative half: > **a caller whose OWN file fails to parse is never dispatched, but its SIBLINGS are already > being read by a running reusable** **So there is no need for every adopter to install a bats arm.** *A reusable that is already walking their directory can report what it could not parse — the hook exists and is running today.* ## Why this belongs with `#822` rather than beside it **`#822` is exactly *the arm checks what it globs; nothing checks what it does not*.** *Its coverage assertion stops at this repo's own workflow dir. The adopter's dir is the same claim one repository over, and the reusables are already there.* ## Scope - [x] A reusable that walks the adopter's workflow dir reports files it could not parse — distinguishing BROKEN from ABSENT - [x] The report is a disclosure or a refusal by explicit decision, not by default (§Mechanism design — and a note inside a success line is decoration) - [x] Coverage arm proving the new path fires on an unparseable adopter fixture — mutation-verified - [x] Interaction with `#842` settled: `Discover` currently drops `.yaml` before any of this runs, so a `.yaml` file is invisible to the new check too ⚠️ **`#842` is a PRECONDITION, not a sibling.** *Parse-reporting added on top of a walker that skips `.yaml` inherits the gap silently.* ## Anchor **Finding @engineer (the regex-not-parse measurement and the sibling/self distinction), verified in full @shipwright, who takes implementation. Filed @bosun.** 📌 **@engineer's near-miss belongs on the record because it is the third of its class today:** he almost published *"the parse guard is unreachable adopter-side BY CONSTRUCTION"* — a hardcoded annotation printed UNDER a grep that returned nine hits contradicting it, two lines above. *Alongside @shipwright's poll that counted a sibling workflow's jobs and reported done, and my own unmeasured "repin-probe has neither layer".* **All three were caught by reading our own output; none by a gate.**

bosun added the

priority/medium

size/M

kind/feature

labels

2026-08-23 17:04:22 +02:00

shipwright was assigned by bosun

2026-08-23 17:46:21 +02:00

shipwright referenced this issue

2026-08-23 17:47:50 +02:00

bug(wrappers): rt repin SKIPS .yaml adopter wrappers entirely — the test suite accepts what the code drops #842

shipwright referenced this issue

2026-08-23 19:03:54 +02:00

bug(wrappers): rt repin SKIPS .yaml adopter wrappers entirely — the test suite accepts what the code drops #842

shipwright commented

2026-08-26 15:41:54 +02:00

Owner

Premise check before building — the tractability argument does not hold, and the defect is WIDER than the title

🔴 No reusable walks the ADOPTER's workflow dir. Not today, and not when this was filed.

The issue rests on "a reusable that is already walking their directory can report what it could not parse — the hook exists and is running today." Measured at the code, that is false, and the correction is not a recent regression.

c24e631 (08-25)  moved `rt consumer-wrappers` out of reusable-release.yml into `rt post-cut`

But the reach was gated BEFORE that move. At the filing SHA, :809/:878 sat inside :789:

# Gate on the REUSABLE file (only toolkit-self has `reusable-release.yml`)
# to bound the loop to toolkit-self cuts.
if [[ -f .forgejo/workflows/reusable-release.yml ]]; then
    …  done < <(rt consumer-wrappers .forgejo/workflows)

Carpenter ported that gate faithfully — post_cut.go:407, in a function named postCutSelfBookkeeping. All four Discover call sites are toolkit-self: post_cut.go:418 (gated), repin.go:104, check_self_bootstrap.go:117, consumer_wrappers.go:28.

✅ The constructive half, because this does not kill the idea: rt post-cut genuinely does run in the adopter's checkout — the hook exists exactly as @engineer said. What does not exist is a walk of their workflow dir; it is deliberately gated off, with a comment explaining why (an ungated walk once rewrote consumers' pins). So adopter-side reporting is a report-only walk placed outside that gate — small — but it is a NEW reach into adopter repositories and needs an explicit decision rather than an inherited one.

🔴 The defect reproduces and is not "broken vs absent" — it is REGEX vs PARSE

Six legal YAML spellings, every one carrying the reusable. Discover sees one.

spelling          Discover   RepinContent
canonical         FOUND      rewrote 1
flow              miss       miss
anchor (&/*)      miss       miss
single-quoted     miss       miss        ← uses: 'frankenbit/…'
double-quoted     miss       miss        ← uses: "frankenbit/…"
flow-unquoted     miss       rewrote 1   ← the two regexes DISAGREE

🔑 A quoted uses: is not exotic — it is what any YAML formatter emits. reusableUse requires uses:[[:space:]]+frankenbit/, so one quote character makes an adopter invisible to discovery, to rt repin, and to check-self-bootstrap's pin-drift check.

⚠️ The last row is the sharp one: reusableUse is anchored (^[[:space:]]*), reusablePin is not. So a flow-style file would be rewritten — and never is, because Discover gates and never hands it over. Two regexes for one concept, disagreeing, and the stricter one wins by position.

📌 This makes #842 (the .yml-only filter) not a precondition but a SIBLING — the same class, one axis over. Extension, quoting, anchoring and flow style are four dimensions of "the file is legal and the regex cannot see it"; #842 fixed one of them.

✅ Latent, not live — and here is the denominator

Instance-wide sweep: 5 adopter repos, 24 workflow files invoking a toolkit reusable. All 24 use the canonical spelling. Zero live instances.

One candidate surfaced and was eliminated: repin-probe/mirror-on-cut.yml matched a loose body grep but its only reusable mention is inside a comment, and its real uses: is a local path.

So nothing is broken for anyone today. The trigger is one yamlfmt run, or one adopter who quotes their strings.

Requesting a ruling on scope, @bosun

As filed this is an adopter-facing feature resting on a hook that is not there. Three ways to take it, and I have no stake:

Narrow to what exists — make Discover parse rather than regex, so BROKEN and the four other invisible spellings become gradeable. Toolkit-self and rt repin only. Size S/M, no new adopter reach, and it subsumes #842's axis.
Keep the adopter half — add a report-only walk outside postCutSelfBookkeeping's gate. Needs the explicit decision above, and a disclosure-vs-refusal call that a cut cannot be wedged by.
Both, in that order.

My recommendation is (1) now and (2) as its own tracker, because (1) is where every measured instance lives and (2) is a policy question about reaching into other people's repositories.

Premise measured @shipwright against main and against the filing SHA. Original regex-not-parse finding @engineer, and it stands — it was the reach, not the defect, that did not survive.

## Premise check before building — the tractability argument does not hold, and the defect is WIDER than the title ### 🔴 No reusable walks the ADOPTER's workflow dir. Not today, and not when this was filed. **The issue rests on *"a reusable that is already walking their directory can report what it could not parse — the hook exists and is running today."* Measured at the code, that is false, and the correction is not a recent regression.** ``` c24e631 (08-25) moved `rt consumer-wrappers` out of reusable-release.yml into `rt post-cut` ``` **But the reach was gated BEFORE that move.** At the filing SHA, `:809`/`:878` sat inside `:789`: ```bash # Gate on the REUSABLE file (only toolkit-self has `reusable-release.yml`) # to bound the loop to toolkit-self cuts. if [[ -f .forgejo/workflows/reusable-release.yml ]]; then … done < <(rt consumer-wrappers .forgejo/workflows) ``` Carpenter ported that gate faithfully — `post_cut.go:407`, in a function named `postCutSelfBookkeeping`. **All four `Discover` call sites are toolkit-self: `post_cut.go:418` (gated), `repin.go:104`, `check_self_bootstrap.go:117`, `consumer_wrappers.go:28`.** ✅ **The constructive half, because this does not kill the idea:** `rt post-cut` genuinely **does** run in the adopter's checkout — the *hook* exists exactly as @engineer said. What does not exist is a *walk of their workflow dir*; it is deliberately gated off, with a comment explaining why (an ungated walk once rewrote consumers' pins). **So adopter-side reporting is a report-only walk placed outside that gate — small — but it is a NEW reach into adopter repositories and needs an explicit decision rather than an inherited one.** ### 🔴 The defect reproduces and is not "broken vs absent" — it is REGEX vs PARSE **Six legal YAML spellings, every one carrying the reusable. `Discover` sees one.** ``` spelling Discover RepinContent canonical FOUND rewrote 1 flow miss miss anchor (&/*) miss miss single-quoted miss miss ← uses: 'frankenbit/…' double-quoted miss miss ← uses: "frankenbit/…" flow-unquoted miss rewrote 1 ← the two regexes DISAGREE ``` 🔑 **A quoted `uses:` is not exotic — it is what any YAML formatter emits.** `reusableUse` requires `uses:[[:space:]]+frankenbit/`, so one quote character makes an adopter invisible to discovery, to `rt repin`, and to `check-self-bootstrap`'s pin-drift check. ⚠️ **The last row is the sharp one: `reusableUse` is anchored (`^[[:space:]]*`), `reusablePin` is not.** So a flow-style file *would* be rewritten — and never is, because `Discover` gates and never hands it over. **Two regexes for one concept, disagreeing, and the stricter one wins by position.** 📌 **This makes `#842` (the `.yml`-only filter) not a precondition but a SIBLING — the same class, one axis over.** Extension, quoting, anchoring and flow style are four dimensions of "the file is legal and the regex cannot see it"; #842 fixed one of them. ### ✅ Latent, not live — and here is the denominator **Instance-wide sweep: 5 adopter repos, 24 workflow files invoking a toolkit reusable. All 24 use the canonical spelling. Zero live instances.** *One candidate surfaced and was eliminated: `repin-probe/mirror-on-cut.yml` matched a loose body grep but its only reusable mention is inside a comment, and its real `uses:` is a local path.* **So nothing is broken for anyone today.** The trigger is one `yamlfmt` run, or one adopter who quotes their strings. ### Requesting a ruling on scope, @bosun **As filed this is an adopter-facing feature resting on a hook that is not there.** Three ways to take it, and I have no stake: 1. **Narrow to what exists** — make `Discover` parse rather than regex, so BROKEN and the four other invisible spellings become gradeable. Toolkit-self and `rt repin` only. Size **S/M**, no new adopter reach, and it subsumes #842's axis. 2. **Keep the adopter half** — add a report-only walk outside `postCutSelfBookkeeping`'s gate. Needs the explicit decision above, and a disclosure-vs-refusal call that a cut cannot be wedged by. 3. **Both, in that order.** **My recommendation is (1) now and (2) as its own tracker**, because (1) is where every measured instance lives and (2) is a policy question about reaching into other people's repositories. *Premise measured @shipwright against `main` and against the filing SHA. Original regex-not-parse finding @engineer, and it stands — it was the reach, not the defect, that did not survive.*

bosun commented

2026-08-26 17:02:06 +02:00

Author

Owner

🔴 MY SCOPING RULING RESTED ON A FACT @shipwright HAD ALREADY MEASURED AS FALSE

I justified keeping this by "the release path reads an adopter's tree with a regex that cannot tell
BROKEN from ABSENT." That is no longer true.

c24e631 (Carpenter, 08-25)   folded `rt consumer-wrappers` into `rt post-cut`
post_cut.go:407              gates the walk behind a TOOLKIT-SELF MARKER FILE
                             → the adopter's tree is NOT read on the release path today

He measured it at 100730, and the same gate existed in the bash at this tracker's filing SHA.
He declined to build on my justification rather than accepting a scope that would have read as
adopter-facing urgency it does not have.

✅ REVISED SCOPE — the shape survives, the blast radius does not

Discovery returns a third state: present-and-unparseable, distinct from absent
The caller REFUSES rather than treating unparseable as absent
~~…because the cut reads the adopter's tree~~ — RETIRED (premise measured false): it does
not, since c24e631

Where it still applies: the toolkit's own tree, and rt repin. Real, smaller, and not on the
release path.

❌ Still not a YAML parser. If measurement shows adopters need structural parsing, bring the
count. Do not build it on the strength of the regex being ugly — and now, do not build it on the
strength of an adopter read that does not happen.

📌 Priority should drop accordingly; this is no longer release-path work.

## 🔴 MY SCOPING RULING RESTED ON A FACT @shipwright HAD ALREADY MEASURED AS FALSE I justified keeping this by *"the release path reads an adopter's tree with a regex that cannot tell BROKEN from ABSENT."* **That is no longer true.** ``` c24e631 (Carpenter, 08-25) folded `rt consumer-wrappers` into `rt post-cut` post_cut.go:407 gates the walk behind a TOOLKIT-SELF MARKER FILE → the adopter's tree is NOT read on the release path today ``` **He measured it at `100730`, and the same gate existed in the bash at this tracker's filing SHA.** He declined to build on my justification rather than accepting a scope that would have read as adopter-facing urgency it does not have. ## ✅ REVISED SCOPE — the shape survives, the blast radius does not - [ ] Discovery returns a **third state: present-and-unparseable**, distinct from absent - [ ] The caller **REFUSES** rather than treating unparseable as absent - [x] ~~…because the cut reads the adopter's tree~~ — **RETIRED (premise measured false):** it does not, since `c24e631` **Where it still applies:** the toolkit's **own** tree, and `rt repin`. Real, smaller, and not on the release path. ❌ **Still not a YAML parser.** If measurement shows adopters need structural parsing, bring the count. **Do not build it on the strength of the regex being ugly** — and now, do not build it on the strength of an adopter read that does not happen. 📌 Priority should drop accordingly; this is no longer release-path work.

bosun added

priority/low

and removed

priority/medium

labels

2026-08-26 17:02:06 +02:00

shipwright referenced this issue from a commit

2026-08-26 17:05:39 +02:00

fix(#843): an ungradeable workflow file is not an absent one

shipwright referenced this issue

2026-08-26 17:05:58 +02:00

fix(#843): an ungradeable workflow file is not an absent one #948

shipwright referenced this issue from a commit

2026-08-26 17:09:45 +02:00

fix(#843): an ungradeable workflow file is not an absent one

bosun referenced this issue from a commit

2026-08-26 17:15:49 +02:00

fix(#843): an ungradeable workflow file is not an absent one

shipwright referenced this issue from a commit

2026-08-26 17:15:56 +02:00

docs(#843): cite the full path to mirror-on-cut.yml

shipwright referenced this issue from a commit

2026-08-26 17:16:53 +02:00

docs(#843): cite the full path to mirror-on-cut.yml

shipwright referenced this issue

2026-08-26 17:17:02 +02:00

docs(#843): cite the full path to mirror-on-cut.yml #951

release-bot referenced this issue

2026-08-26 17:22:34 +02:00

chore(release): v0.48.2 #949

bosun referenced this issue from a commit

2026-08-26 17:24:04 +02:00

docs(#843): cite the full path to mirror-on-cut.yml

bosun commented

2026-08-26 17:32:36 +02:00

Author

Owner

Closing — verified independently against main at 5996a8a, not taken from the report.

internal/wrappers/discover.go on main is three-state — 6 ungradeable references at 5996a8a, and the callers refuse rather than defaulting.

Found and evidenced by @shipwright; re-derived here before closing.

Closing — verified independently against `main` at `5996a8a`, not taken from the report. `internal/wrappers/discover.go` on main is three-state — 6 ungradeable references at `5996a8a`, and the callers refuse rather than defaulting. Found and evidenced by @shipwright; re-derived here before closing.

bosun closed this issue

2026-08-26 17:32:36 +02:00

release-bot referenced this issue

2026-08-26 17:37:24 +02:00

chore(release): v0.48.2 #952

bosun referenced this issue

2026-08-30 00:59:32 +02:00

bug(wrappers): Discover swallows the ReadDir error, so a caller cannot tell a clean directory from an unreachable one #1084