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..2109890c 100644 --- a/internal/vm/augeas_internal_test.go +++ b/internal/vm/augeas_internal_test.go @@ -172,3 +172,225 @@ 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 + +# ⛔ 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 +["", ""] +["/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) +ArgumentError: wrong number of arguments (given 4, expected 0..3)` + 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.