From 6e148dd71e1753557b6d223edb200c4d841c7540 Mon Sep 17 00:00:00 2001 From: tannevaled Date: Mon, 16 Nov 2026 03:22:53 +0100 Subject: [PATCH] README: six names claimed a go-ruby-* address that does not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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-/`". 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-/`: `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 --- README.md | 10 +-- readme_bound_family_test.go | 162 ++++++++++++++++++++++++++++++++++++ 2 files changed, 167 insertions(+), 5 deletions(-) create mode 100644 readme_bound_family_test.go diff --git a/README.md b/README.md index d763dd7c..38c153f6 100644 --- a/README.md +++ b/README.md @@ -69,23 +69,23 @@ The full bound family (alphabetical, all native modules in `go.mod`): `actionview`, `activejob`, `activemodel`, `activerecord`, `activestorage`, `activesupport`, `addressable`, `age`, `arrow`, `async`, `augeas`, `base64`, `bbolt`, `bcrypt`, `benchmark`, `bigdecimal`, `bleve`, `builder`, `bundler`, -`cancancan`, `capistrano`, `capybara`, `cgi`, `chronic`, `cmath`, `commonmark`, +`cancancan`, `capistrano`, `capybara`, `cgi`, `chronic`, `cmath`, `concurrent-ruby`, `confd`, `connection-pool`, `csv`, `date`, `deep-merge`, `devise`, `did-you-mean`, `digest`, `dotenv`, `dry-struct`, `dry-types`, `dry-validation`, `erb`, `erubi`, `etcd`, `excon`, `facter`, `factory-bot`, `faker`, `faraday`, `fast-gettext`, `find`, `format`, `friendly-id`, `getoptlong`, `grape`, `graphql`, `grpc`, `haml`, `hanami`, `hcl2`, `hiera`, `hocon`, `http`, `httparty`, `i18n`, `images`, `ipaddr`, `irb`, `jbuilder`, -`jekyll`, `json`, `jwt`, `kafka`, `kaminari`, `kramdown`, `liquid`, `logger`, +`jekyll`, `json`, `jwt`, `kafka`, `kaminari`, `logger`, `mail`, `marshal`, `matrix`, `mime-types`, `minitest`, `money`, `mongodb`, -`msgpack`, `multi-json`, `mustache`, `mysql`, `nats`, `net-ftp`, `net-http`, -`net-imap`, `net-pop`, `net-sftp`, `net-smtp`, `nokogiri`, `oauth2`, `observer`, +`msgpack`, `multi-json`, `mysql`, `nats`, `net-ftp`, `net-http`, +`net-imap`, `net-pop`, `net-sftp`, `net-smtp`, `oauth2`, `observer`, `oidc`, `omniauth`, `openbao`, `openstack`, `opentelemetry`, `opentype`, `optparse`, `ostruct`, `pagy`, `paper-trail`, `parquet`, `parser`, `pathname`, `pg`, `prawn`, `prettyprint`, `prime`, `protobuf`, `pstore`, `public-suffix`, `puma`, `pundit`, `puppet`, `puppet-resource-api`, `racc`, `rack`, `rails`, `railties`, `rake`, `ransack`, `rdoc`, `redis`, `regexp`, `reline`, `resolv`, -`resque`, `rexml`, `roda`, `rolify`, `rouge`, `rqrcode`, `rspec`, `rss`, +`resque`, `rexml`, `roda`, `rolify`, `rqrcode`, `rspec`, `rss`, `rubocop`, `rubygems`, `saml`, `sass`, `scanf`, `securerandom`, `semantic-puppet`, `sequel`, `shellwords`, `shrine`, `sidekiq`, `simplecov`, `sinatra`, `slim`, `sodium`, `sqlite3`, `strscan`, `thor`, diff --git a/readme_bound_family_test.go b/readme_bound_family_test.go new file mode 100644 index 00000000..58c9abaa --- /dev/null +++ b/readme_bound_family_test.go @@ -0,0 +1,162 @@ +// Copyright (c) the go-embedded-ruby/ruby authors +// +// SPDX-License-Identifier: BSD-3-Clause + +// ⛔ package ruby, not ruby_test, unlike its sibling README gates. It reuses +// requiredModules and unixEndings from bench_backing_test.go, which is the +// INTERNAL test package; the alternative was a second go.mod parser beside the +// one documented as the single answer to this question. +package ruby + +import ( + "os" + "regexp" + "sort" + "strconv" + "strings" + "testing" +) + +// ⛔ THE README COUNTS THE BOUND FAMILY BY HAND, AND SAYS SO. +// +// The `go.mod` currently **binds 178 such modules across 176 orgs** into rbgo +// as native modules (count: +// `grep -oE 'github\.com/go-ruby-[a-z0-9-]*/[a-z0-9-]*' go.mod | sort -u | wc -l`; +// `go-ruby-widgets` contributes three) +// +// and then prints all 176 org names in a backticked list. +// +// Two numbers and a 176-element list, in a family that gains members weekly, +// with nothing checking any of it. The documented method is the problem as much +// as the absence of a gate: a `grep | sort -u | wc -l` 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". The same pipeline is what a reader would run +// to check the figure, so it would confirm whatever it was mistyped into. +// +// The LIST is the part most likely to rot: adding a module means editing an +// alphabetical run of 176 names by hand, and a reader cannot tell a missing one +// from a name they simply did not notice. +// +// This derives all three from go.mod and compares BOTH WAYS. One direction is +// not enough — a list can be short OR carry a name that go.mod no longer has, +// and only the second direction sees the second kind +// (a-check-in-one-direction-cannot-see-something-extra). +// +// It reuses requiredModules from bench_backing_test.go rather than parsing +// go.mod again: that helper exists, 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. +func TestTheBoundFamilyListMatchesGoMod(t *testing.T) { + gomod, err := os.ReadFile("go.mod") + if err != nil { + t.Fatalf("reading go.mod: %v", err) + } + required := requiredModules(unixEndings(string(gomod))) + if len(required) < 100 { + t.Fatalf("go.mod parsed to %d requirements, which cannot be right: this test measured nothing", len(required)) + } + + // ⛔ ORGS AND MODULES ARE DIFFERENT POPULATIONS and the README states both. + // go-ruby-widgets holds three modules (widgets, tui, mvvm), so modules = + // orgs + 2 — and deriving one count from the other would make the pair + // agree by construction instead of by measurement. + goRuby := regexp.MustCompile(`^github\.com/go-ruby-([a-z0-9-]+)/([a-z0-9-]+)$`) + orgs := map[string]bool{} + modules := 0 + for path := range required { + if m := goRuby.FindStringSubmatch(path); m != nil { + orgs[m[1]] = true + modules++ + } + } + if modules == 0 { + t.Fatal("no github.com/go-ruby-*/* module required by go.mod: the pattern is wrong, not the repository") + } + + readmeBytes, err := os.ReadFile("README.md") + if err != nil { + t.Fatalf("reading README.md: %v", err) + } + readme := unixEndings(string(readmeBytes)) + + // The two stated counts. + // ⛔ The emphasis opens BEFORE "binds": `**binds 178 such modules across 176 + // orgs**`. Written the other way round the pattern matched nothing, and this + // test said so instead of passing — which is the only reason the mistake was + // mine to fix rather than a silent hole. + counts := regexp.MustCompile(`\*\*binds (\d+) such modules across (\d+) orgs\*\*`) + cm := counts.FindStringSubmatch(readme) + if cm == nil { + t.Fatalf("README.md no longer states %q: this test cannot judge counts it cannot find. "+ + "If the sentence was reworded, reword it here too rather than deleting the gate.", + "**binds N such modules across N orgs**") + } + if got, _ := strconv.Atoi(cm[1]); got != modules { + t.Errorf("README.md says go.mod binds %d modules; it requires %d github.com/go-ruby-*/* module(s)", got, modules) + } + if got, _ := strconv.Atoi(cm[2]); got != len(orgs) { + t.Errorf("README.md says those modules span %d orgs; they come from %d", got, len(orgs)) + } + + // The list itself: every backticked name between "The full bound family" and + // the "each at `github.com/go-ruby-/`" that closes it. + lines := strings.Split(readme, "\n") + start, end := -1, -1 + for i, line := range lines { + if start < 0 && strings.Contains(line, "The full bound family") { + start = i + continue + } + if start >= 0 && strings.Contains(line, "github.com/go-ruby-/") { + end = i + break + } + } + if start < 0 || end < 0 { + t.Fatalf("README.md: could not find the bound-family list (start=%d, end=%d). "+ + "Both delimiters must be present for this test to read the list at all.", start, end) + } + + // A backticked token that is a plain name. The closing sentence also holds + // `github.com/go-ruby-/`, which is a shape and not a member, so + // anything with a slash or an angle bracket is skipped. + tick := regexp.MustCompile("`([a-z0-9-]+)`") + listed := map[string]bool{} + for _, line := range lines[start+1 : end+1] { + for _, m := range tick.FindAllStringSubmatch(line, -1) { + listed[m[1]] = true + } + } + if len(listed) == 0 { + t.Fatal("README.md: the bound-family list yielded no names, so this test compared nothing") + } + + var missing, extra []string + for org := range orgs { + if !listed[org] { + missing = append(missing, org) + } + } + for name := range listed { + if !orgs[name] { + extra = append(extra, name) + } + } + sort.Strings(missing) + sort.Strings(extra) + + if len(missing) > 0 { + t.Errorf("go.mod requires %d go-ruby org(s) the README's bound-family list does not name (%d):\n %s\n\n"+ + "Add them to the alphabetical run and update the two counts in the same edit.", + len(orgs), len(missing), strings.Join(missing, ", ")) + } + if len(extra) > 0 { + t.Errorf("the README's bound-family list names %d entr(ies) go.mod no longer requires:\n %s\n\n"+ + "A name left behind after a module is dropped is how the list stops describing go.mod. "+ + "⛔ This is the direction a one-way check cannot see.", + len(extra), strings.Join(extra, ", ")) + } + t.Logf("go.mod: %d go-ruby module(s) across %d org(s); README lists %d name(s)", modules, len(orgs), len(listed)) +}