Skip to content

README: six names claimed a go-ruby-* address that does not exist - #954

Merged
tannevaled merged 1 commit into
mainfrom
readme-bound-family
Nov 16, 2026
Merged

tannevaled merged 1 commit into
mainfrom
readme-bound-family

Conversation

@tannevaled

@tannevaled tannevaled commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Six names claimed an address that does not exist

The bound-family list names commonmark, kramdown, liquid, mustache, nokogiri and rouge as members of the go-ruby-* family, whose closing sentence says "each at github.com/go-ruby-<name>/<name>". Twenty-six lines later the same six appear again:

Seven more are bound from outside the go-ruby-* naming convention, at github.com/go-<name>/<name>: commonmark, kramdown, liquid, mustache, nokogiri, rouge and xslt.

go.mod settles which paragraph is right — there is no go-ruby-nokogiri:

github.com/go-commonmark/commonmark v0.1.0
github.com/go-kramdown/kramdown     v0.3.1
github.com/go-liquid/liquid         v0.2.0
github.com/go-mustache/mustache     v0.1.0
github.com/go-nokogiri/nokogiri     v0.1.0
github.com/go-rouge/rouge           v0.7.1
github.com/go-xslt/xslt             v0.1.0

Six names removed from the first list. (xslt was never in it, which is why six and not seven.)

⛔ The counts were correct the whole time

178 modules across 176 orgs — exactly what go.mod requires, with go-ruby-widgets contributing three. A reader checking the figure would have been reassured while the list named six modules that do not exist. The list held 182 entries against 176 orgs, and 182 minus the six interlopers is 176: the remainder was already right.

⛔ And the documented counting method could not see this at all

The README states how to get the number:

(count: grep -oE 'github\.com/go-ruby-[a-z0-9-]*/[a-z0-9-]*' go.mod | sort -u | wc -l; go-ruby-widgets contributes three)

That pipeline cannot tell a changed count from a broken pattern: tighten the character class, mistype the host or point it at the wrong file and it prints a smaller number, never "I matched nothing of the shape you meant" — and it is the same pipeline a reader would run to check the figure, so it would confirm whatever it was mistyped into.

More to the point, it is structurally blind to this defect: the six names are not in go.mod under that shape, so the grep never counted them. Only the list carried them.

The gate

TestTheBoundFamilyListMatchesGoMod derives all three claims from go.mod and compares the list both ways. One direction is not enough — a list can be short, or carry a name go.mod no longer requires, and only the second direction sees the second kind, which is exactly the kind this was. (See a-check-in-one-direction-cannot-see-something-extra, whose other half cost a recurrence earlier tonight.)

Two deliberate choices:

  • It reuses requiredModules from bench_backing_test.go instead of parsing go.mod again. That helper is documented as "a parse of the text rather than a call to go list: the test has to answer the same question a reader of go.mod would", and a second parser beside it would be a second answer to one question. That is why this file is package ruby, not package ruby_test like its sibling README gates.
  • Orgs and modules are counted separately, never one derived from the other: go-ruby-widgets holds three modules (widgets, tui, mvvm), so modules = orgs + 2. Deriving either would make the pair agree by construction instead of by measurement.

Every absence is a failure rather than nothing to report: a missing counts sentence, missing list delimiters, an empty list and zero matching modules each Fatal with what to do about it.

Measured

  • The gate run before the fix named the six and nothing else:
    the README's bound-family list names 6 entr(ies) go.mod no longer requires: commonmark, kramdown, liquid, mustache, nokogiri, rouge
  • After it, green, logging its denominators: go.mod: 178 go-ruby module(s) across 176 org(s); README lists 176 name(s)
  • The two stated counts already matched and still do.
  • gofmt -l . prints nothing; go test . green; buildscan --dir . --vet → "go vet passed under all 19".

⚠ One thing this gate cannot reach

The landing page (go-embedded-ruby.github.io, hugo.toml params.phases) repeats "178 modules across 176 orgs" by hand, in another repository. The number is correct today — checked for this PR — so nothing there changes, but it is a hand-copy.

⛔ To be precise, because the sentence above would otherwise read as "the landing is ungated": it is not. deploy-pages.yml:147 runs conformancefigure@v0.8.0 --root ., which already derives three facts from this repository and checks them against the landing's claims — the passing total, the Ruby version those guards resolve at, and which mspec helpers the shim stubs. What no gate there reads is go.mod, and nothing anywhere reads BASELINE's record counts (as opposed to its example sum). Filed as go-embedded-ruby/docs#53, with the two measurements and the suggested shape: a fourth and fifth fact in that tool, then the pin bump — which its own lane comment already insists is part of the work, "a gate pinned to a version that cannot see a line is indistinguishable from a page with nothing wrong."

Dispositions

Refs #799, go-embedded-ruby/docs#53

#799 is already closed; it is named only because the counts sentence sits in the same README region this touches. docs#53 stays open on purpose — it is the landing half, which this PR cannot reach from here.

🤖 Generated with Claude Code

The bound-family list named `commonmark`, `kramdown`, `liquid`,
`mustache`, `nokogiri` and `rouge` as members of the `go-ruby-*` family,
whose closing sentence says "each at
`github.com/go-ruby-<name>/<name>`". Twenty-six lines later the SAME SIX
appear again, under:

    Seven more are bound from **outside** the `go-ruby-*` naming
    convention, at `github.com/go-<name>/<name>`: `commonmark`,
    `kramdown`, `liquid`, `mustache`, `nokogiri`, `rouge` and `xslt`.

go.mod settles it — there is no go-ruby-nokogiri:

    github.com/go-commonmark/commonmark v0.1.0
    github.com/go-kramdown/kramdown     v0.3.1
    github.com/go-liquid/liquid         v0.2.0
    github.com/go-mustache/mustache     v0.1.0
    github.com/go-nokogiri/nokogiri     v0.1.0
    github.com/go-rouge/rouge           v0.7.1
    github.com/go-xslt/xslt             v0.1.0

so the list was wrong and the paragraph was right. Six names removed.
(`xslt` was never in the first list, which is why six and not seven.)

⛔ AND THE COUNTS WERE CORRECT THE WHOLE TIME: 178 modules across 176
orgs, exactly what go.mod requires, with go-ruby-widgets contributing
three. A reader checking the FIGURE would have been reassured while the
LIST named six modules that do not exist. The list had 182 entries
against 176 orgs — and 182 minus the six interlopers is 176, so the
remainder was already right.

⛔ THE README DOCUMENTED ITS OWN COUNTING METHOD AS A PIPELINE:

    (count: `grep -oE 'github\.com/go-ruby-[a-z0-9-]*/[a-z0-9-]*' go.mod
    | sort -u | wc -l`; `go-ruby-widgets` contributes three)

which cannot tell a CHANGED COUNT from a BROKEN PATTERN. Tighten the
character class, mistype the host or point it at the wrong file and it
prints a smaller number, never "I matched nothing of the shape you
meant" — and it is the same pipeline a reader would run to check the
figure, so it would confirm whatever it was mistyped into. It also
cannot see this defect at all: the six names are not in go.mod under
that shape, so the grep never counted them, and only the LIST carried
them.

TestTheBoundFamilyListMatchesGoMod derives all three claims from go.mod
and compares the list BOTH WAYS. One direction is not enough: a list can
be short, or carry a name go.mod no longer requires, and only the second
direction sees the second kind — which is exactly the kind this was. See
a-check-in-one-direction-cannot-see-something-extra, whose other half
cost a recurrence earlier tonight.

It reuses requiredModules from bench_backing_test.go rather than parsing
go.mod again — that helper is documented as "a parse of the text rather
than a call to `go list`: the test has to answer the same question a
reader of go.mod would", and a second parser beside it would be a second
answer to one question. That is why this file is `package ruby` and not
`package ruby_test` like its sibling README gates.

Orgs and modules are counted SEPARATELY, never one derived from the
other: go-ruby-widgets holds three modules (widgets, tui, mvvm), so
modules = orgs + 2, and deriving either would make the pair agree by
construction instead of by measurement.

Measured:
  - the gate run BEFORE the fix named the six, and nothing else:
    "the README's bound-family list names 6 entr(ies) go.mod no longer
    requires: commonmark, kramdown, liquid, mustache, nokogiri, rouge";
  - after it, green, logging its denominators: "go.mod: 178 go-ruby
    module(s) across 176 org(s); README lists 176 name(s)";
  - the two stated counts already matched and still do;
  - gofmt clean, `go test .` green, buildscan --vet under all 19.

⚠ The landing page (go-embedded-ruby.github.io, hugo.toml params.phases)
repeats "178 modules across 176 orgs". That number is correct, so
nothing there changes — but it is a hand-copy in another repository that
this gate cannot reach, and no gate there reads go.mod.

Refs #799

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@tannevaled
tannevaled merged commit b84b5f5 into main Nov 16, 2026
26 checks passed
@tannevaled
tannevaled deleted the readme-bound-family branch November 16, 2026 03:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant