From 4b598da968cfafeb20e8ab2f6f28606a62f79806 Mon Sep 17 00:00:00 2001 From: tannevaled Date: Mon, 16 Nov 2026 01:37:16 +0100 Subject: [PATCH 1/2] vm(augeas): #close, the block form, and create's real signature MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #950's row in testdata/open-doors.txt said Augeas.open's discarded block could not be fixed because "rbgo's Augeas has no #close method at all, so the helper would yield without closing", and go-ruby-augeas's handle exposes no Close either. ⛔ THAT WAS THE WRONG LAYER. The gem's #close frees a C handle, but what it makes OBSERVABLE is two things, and neither needs anything from the dependency: VALUE augeas_close (VALUE s) { augeas *aug = aug_handle(s); aug_close(aug); DATA_PTR(s) = NULL; return Qnil; } /* aug_handle, which EVERY method calls first */ if (aug == NULL) { rb_raise(rb_eSystemCallError, "Failed to retrieve connection"); } It answers nil, and afterwards every method raises — including a second #close, because aug_handle runs before aug_close. That is a flag plus a guard. I asked what #close FREES; the question was what it makes observable. The guard goes in augeas_bind.go's `self` accessor, which all seventeen instance methods already go through and nothing else does — the one-door shape #951 had to derive with a parser because `open` had five. Reading the reference properly also turned up a divergence nobody had filed: `create` and `open` were THE SAME positional native, and in the gem they are not the same function at all. lib/augeas.rb: def self.open(root = nil, loadpath = nil, flags = NONE, &block) lib/augeas.rb: def self.create(opts={}, &block) -> Augeas::Facade::create create takes an OPTIONS HASH. Three things about facade.rb's single `opts.each_key` pass are reproduced because each is what a tidier reimplementation gets wrong: - a flag is armed by its KEY'S PRESENCE, never its value, so create(type_check: false) sets TYPE_CHECK; - :root and :loadpath are excluded by the final elsif's own condition, not removed from the hash; - validation and assembly share ONE pass, so the FIRST offending key raises. create(save_mode: :bogus, nonsense: 1) says "Invalid save mode bogus." and the same two keys the other way round say "Unknown argument nonsense." Both orders are asserted, because agreeing with one of them is not agreeing with the gem. ⛔ BREAKING for this binding: Augeas.create("/root", "/lens", 5) was accepted and is now a TypeError. Below v1 that is a MINOR bump. ⛔⛔ AND THE RATCHET I LANDED YESTERDAY WAS BLIND TO ITS OWN SUBJECT. TestEveryOpenDoorIsAccountedFor marked every derived door `seen`, block-helper ones included, then called a table row stale only when no door carried its key. So it asked "does this door still exist?" when the question is "does this door still NEED a row?". Augeas.open went from an inline block-discarding handler to socketOpenWithBlock and the test stayed GREEN with the row still reading "⛔ CONFIRMED DEFECT" about it: a gate that cannot see the repair it exists to ask for goes on publishing a defect that is gone — the same artefact #931's prose was, in the other direction. It was not found by re-reading the test. It was found by changing the code the gate watches and noticing THE GATE DID NOT MOVE. The verdict is now compareOpenDoors, a pure function with its own control (TestTheDoorTableComparisonFailsInBothDirections, 7 cases) because the live package can only ever show the comparison AGREEING. Confirmed by hand too: re-adding the row makes the live test red and names the fix. Measured, not recalled: - the gem's lib/augeas.rb, lib/augeas/facade.rb and ext/augeas/_augeas.c were READ. There is no oracle to run here: the augeas gem is a C extension over libaugeas and is not installed, so the reference is the source, quoted in the code. - TestEveryMethodOfAClosedAugeasRaises derives the method population from Augeas.instance_methods(false) (18) rather than listing it, so a method added later that reaches the handle another way is in the test the day it exists. - the flag arithmetic is asserted as NUMBERS, not re-derived from the constants the code uses. It earned that immediately: [2, 8, 16] was written from memory for the three save modes, the test went red, and the source settled it against the test — SaveBackup 1<<0, SaveNewFile 1<<1, SaveNoop 1<<4, which is augeas.h's AUG_* order. - gofmt clean; buildscan --vet: "go vet passed under all 19". Refs #950, #951, #931 #950 stays OPEN: this is its Augeas half. Images::Image.open still discards its block, and that half is not a known defect — go-ruby-images documents no Ruby Image.open and no block form at all, so what it needs is a reference, not a patch. #951 is merged; it is named here because its ratchet is what this change repairs. #931 is untouched. Co-Authored-By: Claude Opus 5 --- internal/vm/augeas.go | 52 +++++- internal/vm/augeas_bind.go | 139 +++++++++++++++- internal/vm/augeas_internal_test.go | 213 +++++++++++++++++++++++++ internal/vm/open_doors_ratchet_test.go | 148 ++++++++++++++--- internal/vm/testdata/open-doors.txt | 16 +- 5 files changed, 531 insertions(+), 37 deletions(-) diff --git a/internal/vm/augeas.go b/internal/vm/augeas.go index cfe920e4..28081e4b 100644 --- a/internal/vm/augeas.go +++ b/internal/vm/augeas.go @@ -34,7 +34,23 @@ import ( // AugeasObj is a Ruby Augeas instance: one go-ruby-augeas handle over an engine // tree. -type AugeasObj struct{ a *augeas.Augeas } +// +// closed is what #close leaves behind. ruby-augeas's C layer frees the handle +// and sets the typed-data pointer to NULL (`aug_close(aug); DATA_PTR(s) = NULL;` +// in ext/augeas/_augeas.c), after which every method raises because they all go +// through aug_handle, whose nil check is +// `rb_raise(rb_eSystemCallError, "Failed to retrieve connection")`. There is +// nothing to free here — go-ruby-augeas's handle is an in-memory tree and +// exposes no Close — so the flag IS the whole mechanism, and the guard lives in +// the single `self` accessor that every instance method already calls +// (augeas_bind.go). ⛔ That is why "#close is blocked on a missing Close in the +// dependency", which this repository believed until #950 was looked at again, +// was the wrong layer: the question is not what #close FREES, it is what #close +// makes OBSERVABLE. +type AugeasObj struct { + a *augeas.Augeas + closed bool +} func (o *AugeasObj) ToS() string { return "#" } func (o *AugeasObj) Inspect() string { return o.ToS() } @@ -66,16 +82,36 @@ func (vm *VM) registerAugeas() { cls.consts[name] = object.IntValue(int64(val)) } - // Augeas.create(root=nil, loadpath=nil, flags=0) / Augeas.open(...) — build a - // handle. With no arguments the engine starts on an empty tree. - open := func(_ *VM, _ object.Value, args []object.Value, _ *Proc) object.Value { - if len(args) == 0 { - return &AugeasObj{a: augeas.New()} + // ⛔ create AND open, NOT one function under two names. This binding used to + // install the same positional native for both, which is wrong about `create`: + // in the gem the two constructors have DIFFERENT signatures and only `open` + // is positional. + // + // lib/augeas.rb: def self.open(root = nil, loadpath = nil, flags = NONE, &block) + // lib/augeas.rb: def self.create(opts={}, &block) -> Augeas::Facade::create + // + // Both honour a block the same way — `yield aug` with `ensure aug.close`, + // answering the block's value — which is socketOpenWithBlock's contract + // exactly, so each is wrapped in it rather than growing its own copy. + // + // augeas.New() is Open("", "", 0) (New, then three zero assignments), so the + // no-argument case needs no branch of its own. + + // Augeas.open(root=nil, loadpath=nil, flags=NONE) — the positional form. + openFn := func(_ *VM, _ object.Value, args []object.Value, _ *Proc) object.Value { + if len(args) > 3 { + raise("ArgumentError", "wrong number of arguments (given %d, expected 0..3)", len(args)) } return &AugeasObj{a: augeas.Open(augStrArg(args, 0), augStrArg(args, 1), augIntArg(args, 2))} } - cls.smethods["create"] = &Method{name: "create", owner: cls, native: open} - cls.smethods["open"] = &Method{name: "open", owner: cls, native: open} + cls.smethods["open"] = &Method{name: "open", owner: cls, native: socketOpenWithBlock(cls, openFn)} + + // Augeas.create(opts={}) — the options-hash form. + createFn := func(vm *VM, _ object.Value, args []object.Value, _ *Proc) object.Value { + root, loadPath, flags := augCreateOpts(vm, args) + return &AugeasObj{a: augeas.Open(root, loadPath, flags)} + } + cls.smethods["create"] = &Method{name: "create", owner: cls, native: socketOpenWithBlock(cls, createFn)} vm.registerAugeasMethods(cls) } diff --git a/internal/vm/augeas_bind.go b/internal/vm/augeas_bind.go index 81cd3e00..d839da69 100644 --- a/internal/vm/augeas_bind.go +++ b/internal/vm/augeas_bind.go @@ -41,6 +41,109 @@ func augPathArg(args []object.Value) string { return args[0].ToS() } +// augCreateOpts reads Augeas.create's options hash into the three values +// Facade::open3 is called with. It mirrors lib/augeas/facade.rb's create, whose +// whole validation is ONE pass over the caller's hash: +// +// opts.each_key do |key| +// if flags.key? key then aug_flags |= flags[key] +// elsif key == :save_mode then … or raise "Invalid save mode #{…}." +// elsif key != :root && key != :loadpath then raise "Unknown argument #{key}." +// end +// end +// aug = Augeas::Facade::open3(opts[:root], opts[:loadpath], aug_flags) +// +// Three consequences of that shape are reproduced on purpose, because each one +// is a thing a reasonable reimplementation would get wrong: +// +// - A FLAG IS SET BY ITS KEY'S PRESENCE, NOT ITS VALUE. `flags.key? key` never +// looks at the value, so `create(type_check: false)` sets TYPE_CHECK just as +// `create(type_check: true)` does. Surprising, and it is the contract. +// - :root and :loadpath are never removed from the hash; they are excluded by +// the final `elsif`'s own condition. The hash is not mutated. +// - VALIDATION AND ASSEMBLY SHARE ONE PASS, so the FIRST offending key raises +// and later keys are never visited. With two bad keys the error therefore +// depends on the caller's insertion order — `create(save_mode: :bogus, +// nonsense: 1)` says "Invalid save mode bogus." and the same two keys the +// other way round say "Unknown argument nonsense." Ranging over h.Keys, +// which rbgo keeps in insertion order, is what preserves that. +// +// The gem's base value is `defined?(Augeas::NO_ERR_CLOSE) ? Augeas::NO_ERR_CLOSE +// : Augeas::NONE`; rbgo defines no NO_ERR_CLOSE constant, so the fallback branch +// is the live one and the base is NONE. +func augCreateOpts(vm *VM, args []object.Value) (root, loadPath string, flags int) { + if len(args) > 1 { + raise("ArgumentError", "wrong number of arguments (given %d, expected 0..1)", len(args)) + } + flags = augeas.None + if len(args) == 0 || object.IsNil(args[0]) { + return "", "", flags + } + h := hashArgOrRaise(vm, args[0]) + + flagOf := map[object.Symbol]int{ + "type_check": augeas.TypeCheck, + "no_stdinc": augeas.NoStdinc, + "no_load": augeas.NoLoad, + "no_modl_autoload": augeas.NoModlAutoload, + "enable_span": augeas.EnableSpan, + } + saveMode := map[object.Symbol]int{ + "backup": augeas.SaveBackup, + "newfile": augeas.SaveNewFile, + "noop": augeas.SaveNoop, + } + + // ⛔ Every lookup below tests PRESENCE (`v, ok := m[k]`), never `m[k] != 0`. + // A zero-valued flag constant would make its key read as unknown, and the + // map's own contents would be deciding a question about the KEY SET. + for _, k := range h.Keys { + sym, isSym := k.(object.Symbol) + if !isSym { + raise("ArgumentError", "Unknown argument %s.", augInterp(k)) + } + if bit, ok := flagOf[sym]; ok { + flags |= bit + continue + } + if sym == "save_mode" { + mode, _ := h.Get(k) + m, isModeSym := mode.(object.Symbol) + bit, ok := saveMode[m] + if !isModeSym || !ok { + // `#{opts[:save_mode]}` is to_s: :bogus prints bogus, and nil + // prints nothing at all, which is the gem's message verbatim. + raise("ArgumentError", "Invalid save mode %s.", augInterp(mode)) + } + flags |= bit + continue + } + if sym == "root" || sym == "loadpath" { + continue // read after the loop, exactly as open3's arguments are + } + raise("ArgumentError", "Unknown argument %s.", augInterp(k)) + } + + if v, ok := h.Get(object.Symbol("root")); ok && !object.IsNil(v) { + root = v.ToS() + } + if v, ok := h.Get(object.Symbol("loadpath")); ok && !object.IsNil(v) { + loadPath = v.ToS() + } + return root, loadPath, flags +} + +// augInterp renders a value the way Ruby's "#{v}" does inside the gem's two +// ArgumentError messages: to_s, and the empty string for nil. ⛔ NOT Inspect: +// `"#{:bogus}"` is `bogus`, not `:bogus`, and getting that wrong would make +// every message off by one character in a way no Go test of the Go side notices. +func augInterp(v object.Value) string { + if object.IsNil(v) { + return "" + } + return v.ToS() +} + // augRaise turns a non-nil engine error into an Augeas::Error. func augRaise(err error) { if err != nil { @@ -60,7 +163,41 @@ func augLens(name string) augeas.Lens { // registerAugeasMethods installs the Augeas instance surface. func (vm *VM) registerAugeasMethods(cls *RClass) { - self := func(v object.Value) *augeas.Augeas { return v.(*AugeasObj).a } + // ⛔ THE ONE DOOR. Every method below reaches the handle through self(v) and + // nothing else does, which is why the closed-handle guard can live here + // instead of at seventeen call sites — the shape #951 had to derive with a + // parser because `open` had five. + // + // It is ruby-augeas's aug_handle: in ext/augeas/_augeas.c every method calls + // it first, and after #close has NULLed the typed-data pointer its check + // `if (aug == NULL) rb_raise(rb_eSystemCallError, "Failed to retrieve + // connection")` is what a closed handle answers. So a closed Augeas does not + // no-op and does not crash: it raises SystemCallError, for #get as much as + // for a second #close. + self := func(v object.Value) *augeas.Augeas { + o := v.(*AugeasObj) + if o.closed { + raise("SystemCallError", "Failed to retrieve connection") + } + return o.a + } + + // close — frees the handle in the gem and returns nil. Here there is nothing + // to free, so it only poisons the object; what matters is that it answers nil + // and that everything after it raises. + // + // self(v) runs FIRST, and that ordering is the gem's: augeas_close calls + // aug_handle before aug_close, so closing twice raises rather than quietly + // succeeding. Calling the guard rather than re-testing the flag is also what + // keeps the two from drifting apart. + cls.define("close", func(_ *VM, v object.Value, args []object.Value, _ *Proc) object.Value { + if len(args) != 0 { + raise("ArgumentError", "wrong number of arguments (given %d, expected 0)", len(args)) + } + self(v) + v.(*AugeasObj).closed = true + return object.NilV + }) // get(path) — the value at path, or nil when the node is absent / has none. cls.define("get", func(_ *VM, v object.Value, args []object.Value, _ *Proc) object.Value { diff --git a/internal/vm/augeas_internal_test.go b/internal/vm/augeas_internal_test.go index d1467255..ea32457c 100644 --- a/internal/vm/augeas_internal_test.go +++ b/internal/vm/augeas_internal_test.go @@ -172,3 +172,216 @@ func TestAugeasStringers(t *testing.T) { t.Errorf("augeas stringers = %q / %q / %v", o.ToS(), o.Inspect(), o.Truthy()) } } + +// TestAugeasOpenAndCreateHonourTheirBlock covers the two constructors' block +// form, which both discarded before #950. +// +// The gem's contract, from lib/augeas.rb's `self.open` and +// lib/augeas/facade.rb's `self.create`: `yield aug` inside `begin`, `aug.close` +// in `ensure`, and the method answers the BLOCK's value, not the handle. The +// third part is the one a yield-only fix would still get wrong, so each case +// returns something the handle could not be mistaken for. +func TestAugeasOpenAndCreateHonourTheirBlock(t *testing.T) { + got := augeasRun(t, ` +puts Augeas.open("/r", "/l", 0) { |a| a.set("/x", "1"); "open-block-value" }.inspect +puts Augeas.create(:root => "/r") { |a| a.set("/x", "1"); 42 }.inspect + +# Without a block each still answers the handle itself, open on both. +puts Augeas.open("/r").get("/anything").inspect +puts Augeas.create(:root => "/r").get("/anything").inspect + +# ⛔ The handle is closed on the way out, and closed is OBSERVABLE: the gem's +# #close NULLs the C handle, after which every method raises from aug_handle. +h = nil +Augeas.open { |a| h = a } +begin; h.get("/x"); rescue => e; puts "#{e.class}: #{e.message}"; end + +# ensure, not a trailing call: a block that raises still closes. +g = nil +begin + Augeas.create { |a| g = a; raise "boom" } +rescue RuntimeError +end +begin; g.get("/x"); rescue => e; puts "#{e.class} after a raising block"; end + +# And the block's own close is not a double-close fault: the helper closes +# through the class's #close, which raises on a handle the block already shut. +begin + Augeas.open { |a| a.close } +rescue => e + puts "#{e.class} when the block closed it first" +end +`) + want := `"open-block-value" +42 +nil +nil +SystemCallError: Failed to retrieve connection +SystemCallError after a raising block +SystemCallError when the block closed it first` + if got != want { + t.Fatalf("block forms:\n got=%q\nwant=%q", got, want) + } +} + +// TestEveryMethodOfAClosedAugeasRaises derives the population from the +// interpreter instead of listing it. +// +// ⛔ A HAND-WRITTEN LIST OF METHODS IS THE ARTEFACT THIS REPOSITORY KEEPS GETTING +// BURNED BY — #931's prose had lost UNIXServer, and #951 had to parse the package +// to find a fourth `open`. The guard being tested here lives at ONE site (the +// `self` accessor in augeas_bind.go), so the risk is not that a method is missed +// today but that a method added LATER reaches the handle another way. Asking +// `Augeas.instance_methods(false)` means such a method is in this test the day it +// exists, with no list to update. +// +// What it asserts is the weakest true thing: no method of a closed handle +// SUCCEEDS. It cannot assert the class, because arity is checked before the +// handle — which is also the gem's order, since rb_define_method's argc is +// enforced by Ruby before the C body runs — so `a.set` with no arguments is an +// ArgumentError there too. +func TestEveryMethodOfAClosedAugeasRaises(t *testing.T) { + got := augeasRun(t, ` +a = Augeas.create +a.close +bad = [] +Augeas.instance_methods(false).sort.each do |m| + begin + a.send(m) + bad << m + rescue ArgumentError, SystemCallError + end +end +puts Augeas.instance_methods(false).length +puts bad.inspect +`) + want := "18\n[]" + if got != want { + t.Fatalf("closed handle:\n got=%q\nwant=%q\n(a non-empty list is a method that reached the handle without self(); a count below 18 means instance_methods stopped answering and this test measured nothing)", got, want) + } +} + +// TestAugeasCloseAnswersNilThenPoisonsTheHandle pins #close itself, including +// the ordering a plain flag check would get wrong. +func TestAugeasCloseAnswersNilThenPoisonsTheHandle(t *testing.T) { + got := augeasRun(t, ` +a = Augeas.create +a.set("/x", "1") +puts a.close.inspect + +# ⛔ A SECOND close RAISES, it does not quietly succeed: augeas_close calls +# aug_handle before aug_close, so the nil check fires first. +begin; a.close; rescue => e; puts "second close: #{e.class}"; end + +# close takes no arguments. +b = Augeas.create +begin; b.close(1); rescue => e; puts "#{e.class}: #{e.message}"; end +# and that refusal left it usable. +puts b.get("/nothing").inspect +`) + want := `nil +second close: SystemCallError +ArgumentError: wrong number of arguments (given 1, expected 0) +nil` + if got != want { + t.Fatalf("close:\n got=%q\nwant=%q", got, want) + } +} + +// TestAugeasCreateReadsTheGemsOptionKeys covers Augeas.create's options hash, +// which this binding used to get wrong wholesale: `create` was the same +// positional native as `open`, while the gem's is `create(opts={})` through +// Augeas::Facade. +// +// The flag arithmetic is asserted as a NUMBER rather than by re-deriving it from +// the constants, so a test that read the same wrong constant as the code cannot +// agree with it. ⛔ And it earned that on its first run: these numbers were +// written from memory as [2, 8, 16] for the three save modes, the test went red, +// and the SOURCE settled it against the test — go-ruby-augeas has SaveBackup +// 1<<0, SaveNewFile 1<<1, TypeCheck 1<<2, NoStdinc 1<<3, SaveNoop 1<<4, NoLoad +// 1<<5, NoModlAutoload 1<<6, EnableSpan 1<<7, which is augeas.h's AUG_* order. +// Re-deriving them from the same constants the code uses would have agreed with +// a wrong binding in silence. 4|16 is AUG_TYPE_CHECK|AUG_SAVE_NOOP = 20. +func TestAugeasCreateReadsTheGemsOptionKeys(t *testing.T) { + got := augeasRun(t, ` +puts Augeas.create.flags +puts [Augeas.create.root, Augeas.create.load_path].inspect +a = Augeas.create(:root => "/r", :loadpath => "/l") +puts [a.root, a.load_path, a.flags].inspect + +# ⛔ A FLAG IS SET BY ITS KEY'S PRESENCE, NOT ITS VALUE. facade.rb tests +# "flags.key? key" and never looks at the value, so false arms it too. +puts Augeas.create(:type_check => false).flags +puts Augeas.create(:type_check => true).flags +puts Augeas.create(:type_check => false, :save_mode => :noop).flags + +puts [Augeas.create(:save_mode => :backup).flags, + Augeas.create(:save_mode => :newfile).flags, + Augeas.create(:save_mode => :noop).flags].inspect +puts [Augeas.create(:no_stdinc => 1).flags, + Augeas.create(:no_load => 1).flags, + Augeas.create(:no_modl_autoload => 1).flags, + Augeas.create(:enable_span => 1).flags].inspect + +# nil is the same as no hash at all, and a non-Hash is a TypeError. +puts Augeas.create(nil).flags +begin; Augeas.create("/r"); rescue => e; puts e.class; end +begin; Augeas.create({}, {}); rescue => e; puts "#{e.class}: #{e.message}"; end +`) + want := `0 +["", ""] +["/r", "/l", 0] +4 +4 +20 +[1, 2, 16] +[8, 32, 64, 128] +0 +TypeError +ArgumentError: wrong number of arguments (given 2, expected 0..1)` + if got != want { + t.Fatalf("create options:\n got=%q\nwant=%q", got, want) + } +} + +// TestAugeasCreateRaisesOnTheFIRSTBadKey pins the consequence of facade.rb +// validating and assembling in ONE `opts.each_key` pass: the first offending key +// raises and the rest are never looked at, so WHICH error you get depends on the +// order the caller wrote the keys in. +// +// ⛔ This is the case a reimplementation gets wrong by being tidier than the +// reference — validating all keys, or checking save_mode before the scan, gives +// a stable answer where the gem's is order-dependent. Both orders are asserted +// here precisely because agreeing with one of them is not agreeing with the gem. +func TestAugeasCreateRaisesOnTheFIRSTBadKey(t *testing.T) { + got := augeasRun(t, ` +[[:save_mode, :bogus, :nonsense, 1], [:nonsense, 1, :save_mode, :bogus]].each do |k1, v1, k2, v2| + begin + Augeas.create({k1 => v1, k2 => v2}) + rescue => e + puts "#{e.class}: #{e.message}" + end +end + +# The two messages on their own, including nil's empty interpolation. +begin; Augeas.create(:save_mode => :bogus); rescue => e; puts e.message; end +begin; Augeas.create(:save_mode => nil); rescue => e; puts e.message; end +begin; Augeas.create(:save_mode => "backup"); rescue => e; puts e.message; end +begin; Augeas.create(:nonsense => 1); rescue => e; puts e.message; end +begin; Augeas.create("root" => "/r"); rescue => e; puts e.message; end + +# A good key before a bad one still raises on the bad one. +begin; Augeas.create(:root => "/r", :nope => 1); rescue => e; puts e.message; end +`) + want := `ArgumentError: Invalid save mode bogus. +ArgumentError: Unknown argument nonsense. +Invalid save mode bogus. +Invalid save mode . +Invalid save mode backup. +Unknown argument nonsense. +Unknown argument root. +Unknown argument nope.` + if got != want { + t.Fatalf("create key errors:\n got=%q\nwant=%q", got, want) + } +} diff --git a/internal/vm/open_doors_ratchet_test.go b/internal/vm/open_doors_ratchet_test.go index caf91eaf..e86ec7d3 100644 --- a/internal/vm/open_doors_ratchet_test.go +++ b/internal/vm/open_doors_ratchet_test.go @@ -54,21 +54,7 @@ func TestEveryOpenDoorIsAccountedFor(t *testing.T) { } accounted := readOpenDoorTable(t) - var unlisted, aliases []string - seen := map[string]bool{} - for _, d := range doors { - seen[d.key] = true - if d.kind == openKindAlias { - aliases = append(aliases, fmt.Sprintf("%s (aliased to %s)", d.key, d.detail)) - continue - } - if d.kind == openKindBlockHelper || d.kind == openKindUnsupported { - continue // correct by construction; see the kind's own comment below - } - if _, ok := accounted[d.key]; !ok { - unlisted = append(unlisted, fmt.Sprintf("%s (%s)", d.key, d.detail)) - } - } + unlisted, aliases, stale := compareOpenDoors(doors, accounted) if len(aliases) > 0 { t.Errorf(`⛔ %d `+"`open`"+` door(s) are an ALIAS for another method: @@ -95,19 +81,63 @@ that is merely WRITTEN DOWN is the artefact this test exists to replace.`, len(unlisted), strings.Join(unlisted, "\n ")) } - // The table may not keep rows for doors that no longer exist: a stale row is - // how a list stops describing the code. - var stale []string + if len(stale) > 0 { + t.Errorf(`⛔ testdata/open-doors.txt holds %d row(s) for door(s) that no longer need one: + + %s + +Either the door is gone from the package, or IT WAS FIXED — it now goes through +socketOpenWithBlock (or unsupported(…)) and the table describes a defect that is +no longer there. Delete the row. ⛔ Moving the row to the "honours its block" +section is NOT the fix: that section is for doors with INLINE handlers, and a +socketOpenWithBlock door is correct by construction and belongs in no section.`, + len(stale), strings.Join(stale, "\n ")) + } +} + +// compareOpenDoors is the whole verdict of TestEveryOpenDoorIsAccountedFor, +// pulled out of it so it can be driven by a control +// (TestTheDoorTableComparisonFailsInBothDirections) instead of only ever seeing +// the live package, which is the one input that cannot show it is wrong. +// +// ⛔⛔ THIS FUNCTION USED TO BE RIGHT IN ONE DIRECTION ONLY, and the bug was +// mine, one day old. It marked EVERY derived door `seen`, block-helper ones +// included, and then called a row stale only when no door carried its key. So it +// asked "does this door still exist?" when the question is "does this door still +// NEED a row?". Fixing a door therefore moved nothing: Augeas.open went from an +// inline block-discarding handler to socketOpenWithBlock and the test stayed +// green with the row still reading "⛔ CONFIRMED DEFECT" about it. A gate that +// cannot see the repair it was built to ask for goes on publishing a defect that +// has been fixed — the same artefact #931's prose was, in the other direction. +// +// ⛔ It was not found by re-reading this file. It was found by changing the code +// the gate watches and noticing THE GATE DID NOT MOVE. That is the only reliable +// way to measure a check: see a-break-check-that-did-not-break. +func compareOpenDoors(doors []openDoor, accounted map[string]string) (unlisted, aliases, stale []string) { + // mustList holds the keys of the doors that OWE the table a row: the inline + // handlers, and nothing else. An alias owes no row either — the table refuses + // the form outright and `aliases` reports it on its own terms. + mustList := map[string]bool{} + for _, d := range doors { + switch d.kind { + case openKindAlias: + aliases = append(aliases, fmt.Sprintf("%s (aliased to %s)", d.key, d.detail)) + case openKindBlockHelper, openKindUnsupported: + // Correct by construction; see the kind's own comment. + default: + mustList[d.key] = true + if _, ok := accounted[d.key]; !ok { + unlisted = append(unlisted, fmt.Sprintf("%s (%s)", d.key, d.detail)) + } + } + } for key := range accounted { - if !seen[key] { + if !mustList[key] { stale = append(stale, key) } } sort.Strings(stale) - if len(stale) > 0 { - t.Errorf("testdata/open-doors.txt accounts for %d door(s) that are no longer in the package: %s", - len(stale), strings.Join(stale, ", ")) - } + return unlisted, aliases, stale } type openKind int @@ -128,6 +158,78 @@ const ( openKindInline ) +// TestTheDoorTableComparisonFailsInBothDirections is compareOpenDoors's control. +// +// The live package can only ever show the comparison AGREEING. It cannot show it +// disagreeing when it should, which is the half that was broken: the "fixed door +// leaves a stale row" case below is the one that passed for a day while the table +// went on calling a repaired door a confirmed defect. Each case here is a +// disagreement the function has to produce, so a future simplification that +// collapses one of them goes red. +func TestTheDoorTableComparisonFailsInBothDirections(t *testing.T) { + const ( + inline = "x.go:cls" + fixed = "y.go:cls" + ) + for _, tc := range []struct { + name string + doors []openDoor + accounted map[string]string + unlisted, aliases, wantStale []string + }{{ + name: "an inline door with a row agrees", + doors: []openDoor{{key: inline, kind: openKindInline, detail: "inline func literal"}}, + accounted: map[string]string{inline: "yields and closes"}, + }, { + name: "an inline door with NO row is unlisted", + doors: []openDoor{{key: inline, kind: openKindInline, detail: "inline func literal"}}, + unlisted: []string{inline + " (inline func literal)"}, + }, { + // ⛔ THE CASE THAT WAS GREEN AND SHOULD NOT HAVE BEEN. The door still + // exists under the same key; only its KIND changed, because it was fixed. + name: "a door FIXED into socketOpenWithBlock leaves its row stale", + doors: []openDoor{{key: fixed, kind: openKindBlockHelper, detail: "socketOpenWithBlock"}}, + accounted: map[string]string{fixed: "⛔ CONFIRMED DEFECT, discards its block"}, + wantStale: []string{fixed}, + }, { + name: "a door that left the package entirely leaves its row stale", + doors: nil, + accounted: map[string]string{fixed: "⛔ CONFIRMED DEFECT, discards its block"}, + wantStale: []string{fixed}, + }, { + name: "an unsupported door owes no row, so a row for it is stale", + doors: []openDoor{{key: fixed, kind: openKindUnsupported, detail: "unsupported(…)"}}, + accounted: map[string]string{fixed: "whatever it used to say"}, + wantStale: []string{fixed}, + }, { + name: "an alias is reported as an alias and owes no row", + doors: []openDoor{{key: inline, kind: openKindAlias, detail: `cls.smethods["new"]`}}, + aliases: []string{inline + ` (aliased to cls.smethods["new"])`}, + }, { + name: "an alias that someone wrote a row for is ALSO stale", + doors: []openDoor{{key: inline, kind: openKindAlias, detail: `cls.smethods["new"]`}}, + accounted: map[string]string{inline: "a row that cannot make an alias correct"}, + aliases: []string{inline + ` (aliased to cls.smethods["new"])`}, + wantStale: []string{inline}, + }} { + t.Run(tc.name, func(t *testing.T) { + if tc.accounted == nil { + tc.accounted = map[string]string{} + } + unlisted, aliases, stale := compareOpenDoors(tc.doors, tc.accounted) + if !slices.Equal(unlisted, tc.unlisted) { + t.Errorf("unlisted:\n got=%q\nwant=%q", unlisted, tc.unlisted) + } + if !slices.Equal(aliases, tc.aliases) { + t.Errorf("aliases:\n got=%q\nwant=%q", aliases, tc.aliases) + } + if !slices.Equal(stale, tc.wantStale) { + t.Errorf("stale:\n got=%q\nwant=%q", stale, tc.wantStale) + } + }) + } +} + type openDoor struct { key string // ":", stable across edits in a way a line number is not kind openKind diff --git a/internal/vm/testdata/open-doors.txt b/internal/vm/testdata/open-doors.txt index 81846c70..46a5779d 100644 --- a/internal/vm/testdata/open-doors.txt +++ b/internal/vm/testdata/open-doors.txt @@ -28,9 +28,15 @@ sqlite3.go:cls SQLite3::Database.open yields and closes the database in a defer bolt.go:cls The bbolt database's open yields and closes the handle (bolt.go:76), returning the block's value. # ───────── does NOT honour its block. #950 -# Both take `_ *Proc` and discard it. Listed here rather than fixed so the count -# is visible: two doors, both on binding surfaces, neither in MRI core. The two -# are NOT in the same state — one reference was read, the other does not -# document the method at all. -augeas.go:cls ⛔ CONFIRMED DEFECT, reference READ. Augeas.open discards its block (augeas.go:71). ruby-augeas lib/augeas.rb defines `def self.open(root = nil, loadpath = nil, flags = NONE, &block)` which does `rv = yield aug; return rv` under `block_given?` with `ensure aug.close` — exactly socketOpenWithBlock's contract. NOT fixed here because it is TWO parts: rbgo's Augeas has no #close method at all (`git grep close internal/vm/augeas.go` is empty), so the helper would yield without closing and `aug.close` in Ruby is a NoMethodError. See #950. +# Takes `_ *Proc` and discards it. Listed here rather than fixed so the count is +# visible: one door, on a binding surface, not in MRI core. +# +# ⛔ augeas.go:cls WAS THE OTHER ONE, and its row said the fix was "blocked" +# because rbgo's Augeas had no #close for socketOpenWithBlock to call and +# go-ruby-augeas's handle exposes no Close. That was the WRONG LAYER: #close in +# the gem frees a C handle, but what it makes OBSERVABLE is `nil` plus a poisoned +# object that raises SystemCallError from every method after it — a flag and a +# guard, needing nothing from the dependency. The door now goes through +# socketOpenWithBlock, so it is correct by construction and owes this file no +# row at all. images.go:cls UNSPECIFIED, not a known defect. Images::Image.open discards its block (images.go:93). go-ruby-images' README documents no Ruby `Image.open` and no block form at all — it documents the Go library (`images.Open("photo.jpg")`) — and ruby-vips and MiniMagick spell this operation without a block, so "no block form" may be the contract to DOCUMENT rather than a gap to fill. See #950. From 29f6917f3f79ca15ca2b9756461d1ffcb74b9a6d Mon Sep 17 00:00:00 2001 From: tannevaled Date: Mon, 16 Nov 2026 02:49:33 +0100 Subject: [PATCH 2/2] test(augeas): cover open's own arity guard, which the ratchet caught MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI: `internal/vm/augeas.go registerAugeas 94.4% (was fully covered)`. The uncovered branch is Augeas.open's arity guard — the gem's open takes three positional arguments, a fourth is an ArgumentError, and I wrote the guard and never executed it. create's two-argument case was tested; open's four-argument case was not, and they are different functions now. ⛔⛔ SECOND TIME IN ONE SESSION. #948 came back on `flushOneAtTeardown 83.3%`; this is `registerAugeas 94.4%`. 49 and 64 minutes of CI for a branch I had just written. And it is neither a missing tool nor a missing note. scripts/coverage/README.md gives the exact recipe — `covratchet -profile .func -require `, which REFUSES a name that matched nothing and prints its denominator — and states its own reason for existing: It exists because the ratchet, correct as it is, only refuses AFTER the spend. […] A gate that refuses after the spend teaches the lesson; one that refuses before it prevents the mistake. I ran gofmt, `buildscan --vet` and the full suite. NONE of the three answers "are the functions this commit claims to cover actually at 100%". Taken now, before pushing: required 7 function(s), matched 7 record(s) in a profile of 7627 all required functions at 100% (registerAugeas, registerAugeasMethods, augCreateOpts, augInterp, plus #948's trackOpenFile, flushOpenFiles, flushOneAtTeardown.) ⛔ Two things that measurement taught, both worth writing down: - `-require compareOpenDoors` matched NOTHING and the tool refused rather than reporting clean. Correct: it is defined in a _test.go file, so it is not in any profile. My -require list was wrong, not the code — which is the failure mode the tool was built to name. - the FULL `-record` comparison against BELOW100.macos-latest reported 87 functions "newly below 100%" from this profile. That is not a finding: the profile is `./internal/vm/` only, while the record is kept by a lane running `./...`, so compiler and bytecode coverage is absent by construction. Judge and subject must count alike. For a selective profile the `-require` form is the valid question, exactly as that README says. Refs #948, #950 Co-Authored-By: Claude Opus 5 --- internal/vm/augeas_internal_test.go | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/internal/vm/augeas_internal_test.go b/internal/vm/augeas_internal_test.go index ea32457c..2109890c 100644 --- a/internal/vm/augeas_internal_test.go +++ b/internal/vm/augeas_internal_test.go @@ -327,6 +327,14 @@ puts [Augeas.create(:no_stdinc => 1).flags, puts Augeas.create(nil).flags begin; Augeas.create("/r"); rescue => e; puts e.class; end begin; Augeas.create({}, {}); rescue => e; puts "#{e.class}: #{e.message}"; end + +# ⛔ open's OWN arity guard, which create's does not cover. The gem's open takes +# three positional arguments and no more; a fourth is an ArgumentError, not a +# silently ignored argument. This line is here because the CI coverage ratchet +# named it: registerAugeas read 94.4% "(was fully covered)" with the guard +# written and never executed — the second time in one session that a branch I +# added went unmeasured because I did not run covratchet locally. +begin; Augeas.open("/r", "/l", 0, 1); rescue => e; puts "#{e.class}: #{e.message}"; end `) want := `0 ["", ""] @@ -338,7 +346,8 @@ begin; Augeas.create({}, {}); rescue => e; puts "#{e.class}: #{e.message}"; end [8, 32, 64, 128] 0 TypeError -ArgumentError: wrong number of arguments (given 2, expected 0..1)` +ArgumentError: wrong number of arguments (given 2, expected 0..1) +ArgumentError: wrong number of arguments (given 4, expected 0..3)` if got != want { t.Fatalf("create options:\n got=%q\nwant=%q", got, want) }