beads/cmd/bd/doctor_check_gate_test.go
Vishnu J 765c272151
fix(doctor): gate --fix when schema is skewed (#5145)
* fix(doctor): gate --fix when schema is skewed (GH#4993)

`bd doctor` printed `bd doctor --fix` for cosmetic warnings without
checking whether the DB schema is ahead of (or behind) the running
binary. Following that tip can resume/write migrations on shared state —
exactly what burned a fleet change-freeze.

- AssessSchemaFixGate compares schema_migrations to LatestVersion
- Refuse apply/dry-run when the database is ahead of the binary
- Sanitize Fix recommendations so tips do not steer into unsafe --fix
- Surface a schema fix-gate footer on doctor output

Fixes #4993

* fix(doctor): assess the schema fix gate before anything can write (GH#4993)

The gate shipped downstream of the hazard it guards, which produced three
separate-looking defects with one cause:

- Fix advice was sanitized inside printDiagnostics, the else branch of the
  emitter chain, and by value over a []doctorCheck. --json, --agent and
  --output therefore published advice the gate had ruled unsafe.
- The --check= handlers return before any gate exists, so --check=pollution
  --clean and --check=validate --fix wrote with no gate consulted.
- runDiagnostics auto-migrates near its top while the gate was assessed at
  print time, so a bare `bd doctor` applied pending migrations and then
  warned about them.

Assess once in the RunE preamble, before any branch that can write, and
thread that verdict through. Sanitize once into result.Checks by index so
every emitter inherits it. Gate the --check= paths at the single branch
point via checkFlagWrites.

Also splits the overloaded Safe flag into RecommendFix / AllowDBFix /
AllowFSFix, since callers were asking three different questions of it, and
adds Determined / DBReachable so an unreadable schema version fails closed
while a genuinely absent database still permits filesystem repair. Fixes
follow from that: the --fix dry-run no longer refuses (it writes nothing),
filesystem-only repairs are no longer blocked by a schema hazard that cannot
affect them, and the dead `&& !g.Safe` conjunct and a leaked internal symbol
in operator-facing output are gone.

Tests move from asserting the predicate to asserting the wiring: a property
over the whole emitter set, the --check= enumeration, and a fail-closed case.
Verified against the original range-by-value bug, which they detect.

Reported by maphew.

* fix(doctor): gate DB fixes solely on AllowDBFix, not Reason == "" (GH#4993)

AssessSchemaFixGate's unreachable branch (openDoltDB failure) returns
AllowDBFix:false and Reason:"" — both zero values. doctor_fix.go's
`gate.AllowDBFix || gate.Reason == ""` in applyFixes and
`!gate.AllowDBFix && gate.Reason != ""` in previewFixes both treated
that empty Reason as "safe to fix", admitting database repairs (and
not even flagging them as blocked in a dry run) whenever the Dolt
server is stopped or unreachable — exactly the case this gate exists
to withhold.

Gate on AllowDBFix alone in both places. Enumerated every FixGate
literal in fix_gate.go (unreachable, undetermined, ahead, pending,
default/equal) against the new condition: only the unreachable case
changes (admitted -> withheld, the fix); undetermined/ahead/pending
stay withheld and the equal/default case stays admitted, so no
legitimate case is newly blocked.

Adds doctor_fix_gate_wiring_test.go coverage driving applyFixes and
previewFixes with an unreachable-shaped gate fixture, asserting no
database fix is applied or shown as unblocked.

* fix(doctor): correct comment typo labelled->labeled

The misspell linter flags 'labelled' (British spelling) in a comment
in previewFixes, failing the Lint / PR Lint (wrapper timing) / CI
Gate checks on PR #5145.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(doctor): guard --agent commands, test the gate assessor, keep recovery fixes (GH#4993)

- --agent: enrichers hardcode `bd doctor --fix` in their Commands and never
  read the sanitized dc.Fix. EnrichForAgent now takes the FixGate and
  sanitizes the finished Commands. TestNoAgentEnricherLeaksUnguardedFixCommand
  runs over every registered enricher (doctor.AgentEnricherNames) plus an
  unenriched name, with a non-vacuity check under a safe gate.
- AssessSchemaFixGate now has tests against a real Dolt server with a seeded
  schema_migrations (ahead, pending, equal, empty/absent/unreadable table)
  and unreachable cases, each guard verified by mutation.
- An unopenable database no longer withholds the recovery fixers that repair
  it: FixGate.AllowsFix is the single admission policy; Corrupt Manifest,
  Database Integrity, Dolt Format and Dolt Schema stay available when the DB
  is unreachable, schema-writing fixes stay withheld whenever the gate blocks.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* chore(bazel): sync BUILD.bazel srcs/deps for the new doctor fix-gate files

The PR adds cmd/bd/doctor/fix_gate.go (which imports //schema), three
fix_gate*_test.go files in that package, and
cmd/bd/doctor_fix_gate_wiring_test.go. The rebase target added
cmd/bd/doctor/BUILD.bazel after this PR was opened, and it enumerates srcs
and deps exactly, so the merged tree left all five files unlisted and the
go_library missing //schema. Regenerated with `make bazel-sync`
(gazelle + tools/bazel/go_srcs.py + bazel mod tidy).

* fix(doctor): fail closed when the schema gate cannot open an existing database

Maintainer review fixes for the GH#4993 fix gate (adoption review of #5145).

The blocking defect: AssessSchemaFixGate conflated "there is no database" with
"I could not connect to one". Any openDoltDB error returned the no-hazard
unreachable shape, and the destructive `--check` refusal keyed on
gate.DBReachable, so in a server-mode repo whose server was merely stopped
`bd doctor --check=pollution --clean` skipped the refusal entirely, then the
handler's own factory open auto-started the server, applied the pending
migrations blind, and deleted rows. The identical command against the identical
schema was refused whenever the server happened to be running, so the guard was
conditional on incidental server liveness.

Split the two states. A failed connection is no longer evidence that there is
no database: when the configured database is still on disk the gate now reports
DBPresent with Determined=false, a Reason, and RecommendFix cleared, so the
refusal fires and printed advice stops steering at --fix for a schema version
it never read. The discriminator stats the path autoMigrateOnVersionBump
stats, os.Stat(cfg.DatabasePath(...)), and like it reads only ENOENT as absent,
so the gate and the auto-migrate agree about when a schema exists outside the
two deliberate departures described under the second review iteration below.
A repo with no database at all keeps the existing no-hazard shape.

DBPresent, not DBReachable, is now the hazard question, via
FixGate.BlocksDestructiveWrites(). Keeping DBReachable literal preserves the
recovery-fixer carve-out in AllowsFix unchanged: Corrupt Manifest and
Database Integrity stay available for a database that cannot be opened, which
is exactly the state they are the cure for, while a repair that opens the
migrating factory stays withheld.

Also from the review, all non-blocking:

- `--check=artifacts --clean` was refused under a blocked gate although the PR
  itself classifies artifact cleanup filesystem-only, so the two planes
  disagreed about one operation. The `--check` guard now routes through
  FixGate.AllowsFix; pollution and validate have no filesystem-only
  classification and stay refused.
- filesystemOnlyFixes omitted "Hooks Path" (a git-config unset) and
  "Circuit Breaker" (stale marker files), so a blocked gate withheld them and
  printed them as database fixes. Added both, plus "Database Config" (rewrites
  metadata.json only and refuses Dolt outright). Audited the rest of
  applyFixList's 42 dispatch names and recorded why the others stay guarded --
  "Repo Fingerprint" writes through the store, so it is correctly withheld.
- applyFixes dropped a gate-withheld filesystem-only fix from both the fixable
  and withheld lists, reporting nothing at all. Removed the qualifier and
  relabelled the line "gated fix(es)", since the withheld set is whatever the
  gate blocked.
- Corrected the gate's own ordering contract comment, which claimed assessment
  happens "before anything that can write". The load-bearing guarantee is one
  memoised verdict per invocation before any *gated* write, with the bd-jgxi
  auto-migrate deliberately outside the gate's jurisdiction.

Tests: the fail-closed shape and its recovery/hazard admissions, the hazard
predicate across all six gate shapes, the `--check` refusal routing (including
that a read-only --check never probes the database), and the gate accessor's
laziness and memoisation. The review also asked for an assertion that the gate
is evaluated before autoMigrateOnVersionBump; that is declined deliberately,
because it would pin a contract the same review established is false -- the
auto-migrate precedes the gate by design. The lazy/memoised pins cover the part
of the contract that is real.

Validation: 29 focused fix-gate tests pass, and each of the four behavioural
changes was confirmed non-vacuous by mutating it and observing only its own
test fail. Full cmd/bd/doctor package is 387 pass / 7 fail, all 7 identical to
the same tests at the rebase base (ambient-env reds needing BEADS_TEST_SERVER
or a configured beads role). BUILD.bazel regenerated with gazelle; the new
cmd/bd test file runs under `bazel test //cmd/bd:bd_test`.

Second review iteration (one minor, non-gating): databaseExistsOnDisk's doc
called it the same probe autoMigrateOnVersionBump uses, but the two differed in
three arms. Each is now either aligned or a documented, pinned departure:

- Any stat error read as absent, where auto-migrate reads only ENOENT so. Now
  only ENOENT reads as absent: a data directory that cannot be stat'ed for
  another reason (ENOTDIR, EACCES) is unknown, and the gate fails closed.
- No metadata.json reads as absent, where auto-migrate falls back to
  DefaultConfig. Kept deliberately and documented: the gate cannot connect
  without metadata.json, so a fail-closed verdict could never be cleared by
  starting a server, and SanitizeFixRecommendation would rewrite doctor's own
  advice for this state (`bd doctor --fix` regenerating metadata.json, a
  filesystem-only repair) into "Do NOT run 'bd doctor --fix'". The cost is one
  unguarded state, left as follow-up: server mode selected by the environment
  or config.yaml while metadata.json is missing, where a gated repair still
  reaches the server's schema unmeasured.
- A proxied-server workspace was documented as reading absent because it
  "keeps no local database", but it reads present whenever its data directory
  is on disk, and the proxied root defaults to that same directory. Kept
  fail-closed and corrected the doc. `bd doctor` is refused up front in
  proxied-server mode (proxy.doctor.unsupported), so this arm only matters once
  doctor gains a proxied route.

Also corrected the DBPresent field doc, which said only a repo with no database
at all is DBPresent:false.

Tests: the fail-closed test is now table-driven over a stopped server, a
proxied-server workspace, and a data directory whose stat fails with ENOTDIR
(skipped on Windows, where that error surfaces as path-not-found, which
os.IsNotExist matches). A new test pins the missing-metadata.json departure:
the no-hazard shape, RecommendFix kept, and Metadata Config admitted. Each arm
was confirmed non-vacuous by mutating it (a DefaultConfig fallback, an
any-error stat predicate, a proxied-mode early return) and observing only its
own test fail.

Not covered, and unchanged from main: an embedded-mode workspace keeps its
store under .beads/embeddeddolt, which this probe does not stat, so
`bd doctor --check=pollution --clean` there still gets the no-database verdict.

Validation (second iteration): git diff --check is clean; the 11 focused
doctor gate tests and the 13 cmd/bd gate-wiring tests pass.
databaseExistsOnDisk's only caller is AssessSchemaFixGate, whose only
production caller is doctor's newSchemaGate, so those suites cover every path
the predicate change reaches.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
2026-10-01 01:32:23 -07:00

204 lines
8.2 KiB
Go

package main
import (
"strings"
"sync/atomic"
"testing"
"github.com/steveyegge/beads/cmd/bd/doctor"
)
// gateStub builds the accessor destructiveCheckRefusal takes, counting how many
// times the gate was actually evaluated.
func gateStub(g doctor.FixGate, calls *atomic.Int32) func() doctor.FixGate {
return func() doctor.FixGate {
calls.Add(1)
return g
}
}
// presentButUnopenableGate is the shape AssessSchemaFixGate returns for a
// database that is on disk but could not be opened.
func presentButUnopenableGate() doctor.FixGate {
return doctor.FixGate{
DBPresent: true,
AllowFSFix: true,
Reason: "database exists but could not be opened, so its schema version is unknown",
}
}
// TestDestructiveCheckRefusalRefusesOnPresentButUnopenableDatabase is the
// call-site half of the PR #5145 fail-open: the refusal must fire for a database
// that exists but could not be opened, because the handler it guards opens the
// store through the migrating factory, which auto-starts a stopped server and
// applies pending migrations before writing.
func TestDestructiveCheckRefusalRefusesOnPresentButUnopenableDatabase(t *testing.T) {
var calls atomic.Int32
var err error
// HandleErrorWithHint reports on stderr and returns a bare exit code, so the
// refusal text — which interpolates the gate's Reason — is only observable
// there.
stderr := captureStderrDuring(t, func() {
err = destructiveCheckRefusal("pollution", true, false, gateStub(presentButUnopenableGate(), &calls))
})
if err == nil {
t.Fatal("destructiveCheckRefusal returned nil; --check=pollution --clean must be refused on an unopenable database")
}
if !strings.Contains(stderr, "refusing destructive 'bd doctor --check=pollution'") {
t.Errorf("refusal did not name the command it refused:\n%s", stderr)
}
if !strings.Contains(stderr, "could not be opened") {
t.Errorf("refusal did not explain why, so the operator cannot act on it:\n%s", stderr)
}
if calls.Load() != 1 {
t.Errorf("gate evaluated %d times, want exactly 1", calls.Load())
}
}
// TestDestructiveCheckRefusalAllowsFilesystemOnlyCleanup pins the two planes
// agreeing about one operation: `bd doctor --fix` admits "Classic Artifacts"
// under a blocked gate because it is filesystem-only, so
// `--check=artifacts --clean` must not be refused with a schema-skew message in
// exactly the degraded state where clearing stale artifacts is safe and useful.
func TestDestructiveCheckRefusalAllowsFilesystemOnlyCleanup(t *testing.T) {
blocked := []struct {
name string
gate doctor.FixGate
}{
{"present but unopenable", presentButUnopenableGate()},
{"pending", doctor.FixGate{Determined: true, DBReachable: true, DBPresent: true, Pending: true, AllowFSFix: true, Reason: "pending"}},
{"ahead", doctor.FixGate{Determined: true, DBReachable: true, DBPresent: true, Ahead: true, AllowFSFix: true, Reason: "ahead"}},
}
for _, b := range blocked {
var calls atomic.Int32
if err := destructiveCheckRefusal("artifacts", true, false, gateStub(b.gate, &calls)); err != nil {
t.Errorf("%s gate: --check=artifacts --clean refused, but the same cleanup is admitted by --fix: %v", b.name, err)
}
// The same gate must still refuse the row-deleting sibling, or this test
// would pass by disabling the guard rather than by scoping it.
if err := destructiveCheckRefusal("pollution", true, false, gateStub(b.gate, &calls)); err == nil {
t.Errorf("%s gate: --check=pollution --clean was admitted; it deletes rows and must stay refused", b.name)
}
if err := destructiveCheckRefusal("validate", false, true, gateStub(b.gate, &calls)); err == nil {
t.Errorf("%s gate: --check=validate --fix was admitted; it writes through an opened store", b.name)
}
}
}
// TestDestructiveCheckRefusalAdmitsWhenNoDatabaseExists keeps the no-hazard case
// unguarded: with no database on disk there is no schema to skew, so refusing
// would block a cleanup that cannot possibly migrate anything.
func TestDestructiveCheckRefusalAdmitsWhenNoDatabaseExists(t *testing.T) {
noDB := doctor.FixGate{Determined: true, RecommendFix: true, AllowFSFix: true}
for _, flag := range []string{"artifacts", "pollution"} {
var calls atomic.Int32
if err := destructiveCheckRefusal(flag, true, false, gateStub(noDB, &calls)); err != nil {
t.Errorf("--check=%s --clean refused with no database present: %v", flag, err)
}
}
}
// TestDestructiveCheckRefusalDoesNotProbeReadOnlyChecks pins the laziness the
// gate's contract claims: a read-only `--check` must not evaluate the gate at
// all, because the probe is the only thing that would touch the database on a
// path that otherwise does not.
func TestDestructiveCheckRefusalDoesNotProbeReadOnlyChecks(t *testing.T) {
cases := []struct {
flag string
clean bool
fix bool
}{
{"artifacts", false, false},
{"pollution", false, false},
{"conventions", true, true},
{"validate", true, false},
}
for _, c := range cases {
var calls atomic.Int32
if err := destructiveCheckRefusal(c.flag, c.clean, c.fix, gateStub(presentButUnopenableGate(), &calls)); err != nil {
t.Errorf("--check=%s (clean=%v fix=%v) refused although it cannot write: %v", c.flag, c.clean, c.fix, err)
}
if calls.Load() != 0 {
t.Errorf("--check=%s (clean=%v fix=%v) evaluated the gate %d times; a read-only check must not probe",
c.flag, c.clean, c.fix, calls.Load())
}
}
}
// TestNewSchemaGateIsLazyAndMemoised pins the half of the gate's stated contract
// that is a real invariant rather than a call-order claim: one verdict per
// invocation, produced on first use and reused by every later consumer. The
// assessor is the only thing in the command that opens a connection for the
// gate, so evaluating it eagerly would probe on read-only paths, and evaluating
// it twice would let two consumers in one invocation disagree.
func TestNewSchemaGateIsLazyAndMemoised(t *testing.T) {
var calls atomic.Int32
original := assessSchemaFixGate
t.Cleanup(func() { assessSchemaFixGate = original })
assessSchemaFixGate = func(path string) doctor.FixGate {
calls.Add(1)
return doctor.FixGate{Determined: true, DBReachable: true, DBPresent: true, DBVersion: 7, AllowFSFix: true}
}
gate := newSchemaGate("/some/repo")
if calls.Load() != 0 {
t.Fatalf("assessor ran %d times before first use; the gate must be lazy", calls.Load())
}
first := gate()
for i := 0; i < 4; i++ {
if got := gate(); got != first {
t.Fatalf("gate() returned %+v on call %d, want the memoised %+v", got, i+2, first)
}
}
if calls.Load() != 1 {
t.Errorf("assessor ran %d times across five reads, want exactly 1", calls.Load())
}
}
// TestNewSchemaGatePassesTheRepoPathThrough guards against a seam that reads a
// different workspace than the command was pointed at.
func TestNewSchemaGatePassesTheRepoPathThrough(t *testing.T) {
original := assessSchemaFixGate
t.Cleanup(func() { assessSchemaFixGate = original })
var seen string
assessSchemaFixGate = func(path string) doctor.FixGate {
seen = path
return doctor.FixGate{}
}
newSchemaGate("/repo/under/test")()
if seen != "/repo/under/test" {
t.Errorf("assessor received %q, want %q", seen, "/repo/under/test")
}
}
// TestApplyFixesReportsWithheldFilesystemOnlyFix pins the reporting hole: a
// filesystem-only fix the gate rejects used to be appended to neither the
// fixable list nor the withheld list, so it was silently no-opped with no
// output. Unreachable while every assessed gate sets AllowFSFix, which is why
// this drives the gate shape directly.
func TestApplyFixesReportsWithheldFilesystemOnlyFix(t *testing.T) {
result := doctorResult{
Checks: []doctorCheck{
{Name: "Gitignore", Status: statusWarning, Fix: "add entries"},
},
}
// AllowFSFix false is the shape that exposed the hole.
out := captureStdout(t, func() error {
applyFixes(result, doctor.FixGate{DBReachable: true, DBPresent: true, Reason: "schema state unknown"})
return nil
})
if !strings.Contains(out, "Gitignore") {
t.Errorf("withheld filesystem-only fix was not reported at all:\n%s", out)
}
if !strings.Contains(out, "Skipping 1 gated fix(es)") {
t.Errorf("withheld count/label missing; the withheld set is whatever the gate blocked:\n%s", out)
}
if strings.Contains(out, "database fix(es)") {
t.Errorf("a withheld filesystem-only fix was labelled a database fix:\n%s", out)
}
}