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>
This commit is contained in:
Vishnu J 2026-10-01 01:32:23 -07:00 • committed by GitHub
commit 765c272151
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 1925 additions and 27 deletions

View file

@ -660,9 +660,11 @@ go_test(
"diff_embedded_test.go",
"directory_flag_test.go",
"doctor_backend_guard_test.go",
"doctor_check_gate_test.go",
"doctor_context_test.go",
"doctor_conventions_test.go",
"doctor_embedded_test.go",
"doctor_fix_gate_wiring_test.go",
"doctor_fix_order_test.go",
"doctor_fix_pending_migrations_test.go",
"doctor_health_integration_test.go",

View file

@ -7,6 +7,7 @@ import (
"path/filepath"
"slices"
"strings"
"sync"
"time"
"github.com/spf13/cobra"
@ -247,10 +248,19 @@ Examples:
return nil
}
// GH#4993: assess once, before any branch that can write. Lazy so
// read-only paths skip the probe; memoised so repeats cannot disagree.
schemaGate := newSchemaGate(absPath)
// artifacts, conventions, and pollution work in embedded mode and run
// unconditionally; validate still requires a server-mode connection
// and stays gated (GH#3597).
if doctorCheckFlag != "" {
// GH#4993: these handlers return directly, so their destructive
// paths bypassed the gate. Refuse at the single branch point.
if err := destructiveCheckRefusal(doctorCheckFlag, doctorClean, doctorFix, schemaGate); err != nil {
return err
}
switch doctorCheckFlag {
case "artifacts":
return runArtifactsCheck(absPath, doctorClean, doctorYes)
@ -294,12 +304,17 @@ Examples:
result := runDiagnostics(absPath)
// GH#4993: guard once, on the result, before any emitter reads it.
// Per-renderer sanitizing exempted --json, --agent and --output.
sanitizeFixAdvice(&result, schemaGate())
if doctorDryRun {
previewFixes(result)
previewFixes(result, schemaGate())
} else if doctorFix {
applyFixes(result)
applyFixes(result, schemaGate())
fmt.Println("\nVerifying fixes...")
result = runDiagnostics(absPath)
sanitizeFixAdvice(&result, schemaGate())
}
if doctorOutput != "" || jsonOutput {
@ -315,7 +330,7 @@ Examples:
}
if doctorAgent {
agentResult := buildAgentResult(result)
agentResult := buildAgentResult(result, schemaGate())
if jsonOutput {
if err := outputJSON(agentResult); err != nil {
return err
@ -328,7 +343,7 @@ Examples:
return err
}
} else if doctorOutput == "" {
printDiagnostics(result)
printDiagnostics(result, schemaGate())
}
if !result.OverallOK {
@ -1184,7 +1199,96 @@ func exportDiagnostics(result doctorResult, outputPath string) error {
return nil
}
func printDiagnostics(result doctorResult) {
// checkFlagWrites reports whether a `--check=<flag>` can modify state and so
// must clear the schema gate (GH#4993). New destructive checks go here.
func checkFlagWrites(flag string, clean, fix bool) bool {
switch flag {
case "artifacts", "pollution":
return clean
case "validate":
return fix
}
return false
}
// checkFlagFixName names the classified repair a destructive `--check=<flag>`
// performs, so the schema gate can admit it through the same policy that governs
// the equivalent `bd doctor --fix` repair (GH#4993). "" means the flag's
// destructive work maps to no single classified fix and is therefore treated as
// schema-writing, exactly like an unlisted fix name in filesystemOnlyFixes.
//
// `pollution --clean` and `validate --fix` deliberately have no entry: both
// delete or rewrite rows through an opened store.
func checkFlagFixName(flag string) string {
if flag == "artifacts" {
// --clean removes the same on-disk artifacts as the "Classic Artifacts"
// fix, which fix_gate.go classifies filesystem-only.
return "Classic Artifacts"
}
return ""
}
// assessSchemaFixGate is the schema-gate assessor, indirected so tests can
// observe when and how often it is evaluated. Production always uses
// doctor.AssessSchemaFixGate.
var assessSchemaFixGate = doctor.AssessSchemaFixGate
// newSchemaGate returns this invocation's schema gate accessor (GH#4993). Lazy
// so a read-only path never probes the database, and memoised so every consumer
// in one invocation sees one verdict that repeats cannot disagree with.
func newSchemaGate(absPath string) func() doctor.FixGate {
return sync.OnceValue(func() doctor.FixGate {
return assessSchemaFixGate(absPath)
})
}
// destructiveCheckRefusal returns the refusal for a destructive `bd doctor
// --check=<flag>` the schema gate does not admit, or nil when the command may
// proceed (GH#4993). gate is an accessor rather than a value so a read-only
// --check never probes the database.
//
// The gate is consulted here, before the caller's switch dispatches to a
// handler, because the handler's own store open is the hazard: the migrating
// factory auto-starts a stopped server and applies pending migrations before the
// write lands.
func destructiveCheckRefusal(flag string, clean, fix bool, gate func() doctor.FixGate) error {
if !checkFlagWrites(flag, clean, fix) {
return nil
}
g := gate()
if !g.BlocksDestructiveWrites() {
return nil
}
// Filesystem-only cleanup is not what the gate is about: `bd doctor --fix`
// admits the same repair under the same blocked gate, so refusing it here
// would leave the two planes disagreeing about one operation.
if name := checkFlagFixName(flag); name != "" && g.AllowsFix(name) {
return nil
}
return HandleErrorWithHint(
fmt.Sprintf("refusing destructive 'bd doctor --check=%s': %s", flag, g.Reason),
"Re-run without --clean/--fix to inspect read-only, or resolve the schema state first",
)
}
// sanitizeFixAdvice rewrites each Fix tip in place so no emitter publishes
// advice the gate ruled unsafe (GH#4993). Index-based write is load-bearing:
// ranging by value over []doctorCheck mutates a copy.
func sanitizeFixAdvice(result *doctorResult, gate doctor.FixGate) {
if result == nil {
return
}
for i := range result.Checks {
if result.Checks[i].Fix == "" {
continue
}
result.Checks[i].Fix = doctor.SanitizeFixRecommendation(result.Checks[i].Fix, gate)
}
}
func printDiagnostics(result doctorResult, gate doctor.FixGate) {
// GH#4993: tips arrive already sanitized; do not re-assess the gate here.
// Pre-calculate counts and collect issues grouped by category
checksByCategory := make(map[string][]doctorCheck)
issuesByCategory := make(map[string][]doctorCheck)
@ -1330,6 +1434,11 @@ func printDiagnostics(result doctorResult) {
}
fmt.Printf("%s\n", ui.RenderMuted(fmt.Sprintf("(%d %s suppressed via doctor.suppress config)", result.SuppressedCount, noun)))
}
// GH#4993: surface the schema gate verdict assessed once in RunE.
if gate.Reason != "" {
fmt.Printf("\n%s Schema fix-gate: %s\n", ui.RenderWarn("⚠"), gate.Reason)
}
}
// printAllChecks prints all checks grouped by category with section headers.

View file

@ -19,6 +19,7 @@ go_library(
"dependency_sql.go",
"dolt.go",
"federation.go",
"fix_gate.go",
"fresh_clone_server.go",
"git.go",
"gitignore.go",
@ -74,6 +75,7 @@ go_library(
"//internal/storage/schema",
"//internal/types",
"//internal/utils",
"//schema",
"@com_github_go_sql_driver_mysql//:mysql",
"@com_github_spf13_viper//:viper",
"@in_gopkg_yaml_v3//:yaml_v3",
@ -105,6 +107,9 @@ go_test(
"dolt_phantom_test.go",
"dolt_test.go",
"federation_test.go",
"fix_gate_assess_dolt_test.go",
"fix_gate_assess_test.go",
"fix_gate_test.go",
"fresh_clone_server_test.go",
"git_hygiene_test.go",
"git_repo_template_test.go",
@ -164,6 +169,7 @@ go_test(
"//internal/testutil/bazeltest",
"//internal/types",
"//internal/utils",
"//schema",
"@com_github_data_dog_go_sqlmock//:go-sqlmock",
"@com_github_go_sql_driver_mysql//:mysql",
],

View file

@ -2,6 +2,7 @@ package doctor
import (
"fmt"
"sort"
"strings"
)
@ -33,7 +34,20 @@ type agentEnrichment struct {
type enricher func(dc DoctorCheck) agentEnrichment
// EnrichForAgent converts a DoctorCheck into an AgentDiagnostic with rich context.
func EnrichForAgent(dc DoctorCheck) AgentDiagnostic {
//
// Enrichers hardcode their own remediation commands (many are literally
// `bd doctor --fix`) and never read the already-sanitized dc.Fix, so the gate
// is applied to the finished Commands here, after enrichment (GH#4993). An
// agent is the consumer most likely to execute that list unattended.
func EnrichForAgent(dc DoctorCheck, gate FixGate) AgentDiagnostic {
ad := enrichForAgent(dc)
for i, c := range ad.Commands {
ad.Commands[i] = SanitizeFixRecommendation(c, gate)
}
return ad
}
func enrichForAgent(dc DoctorCheck) AgentDiagnostic {
ad := AgentDiagnostic{
Name: dc.Name,
Status: dc.Status,
@ -88,6 +102,19 @@ func buildGenericExplanation(dc DoctorCheck) string {
return s
}
// AgentEnricherNames returns every check name with a specialized agent
// enricher, sorted. Enrichers hardcode their own remediation commands, so
// tests that assert on agent output must cover each one rather than a
// hand-picked name that may fall through to the generic path (GH#4993).
func AgentEnricherNames() []string {
names := make([]string, 0, len(agentEnrichers))
for name := range agentEnrichers {
names = append(names, name)
}
sort.Strings(names)
return names
}
// agentEnrichers maps check names to specialized enrichment functions.
var agentEnrichers = map[string]enricher{
"Installation": enrichInstallation,

321
cmd/bd/doctor/fix_gate.go Normal file
View file

@ -0,0 +1,321 @@
package doctor
import (
"context"
"fmt"
"os"
"regexp"
"strings"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/schema"
)
// FixGate reports whether `bd doctor --fix` is safe given the schema/binary
// relationship (GH#4993): opening the store can apply pending migrations.
// Callers ask three distinct questions, so it answers three.
type FixGate struct {
// Determined is false when a database exists but its version could not be
// read — either the connection failed or the query did. Unknown is not safe.
Determined bool
// DBReachable is false whenever this process did not get a working
// connection. That covers both "there is no database" and "there is one but
// it could not be connected to", so it is not on its own a statement about
// hazard — see DBPresent.
DBReachable bool
// DBPresent is true when a beads database exists for this repo: either the
// connection succeeded, or a connection was impossible but the on-disk
// database is still there (a stopped server, a wrong port). It is the hazard
// question — a database that exists has a schema that a migrating open can
// rewrite, whether or not this process could read it. Without a connection,
// "exists" is databaseExistsOnDisk's verdict, and a workspace with no
// metadata.json reads as absent there even with a data directory on disk —
// see that function for why. DBReachable implies DBPresent; the converse
// does not hold.
DBPresent bool
// RecommendFix allows printed advice to steer at `bd doctor --fix`.
RecommendFix bool
// AllowDBFix allows repairs that may write schema or resume migrations.
AllowDBFix bool
// AllowFSFix allows filesystem-only repairs, which never touch the schema.
AllowFSFix bool
DBVersion int // max applied schema_migrations version (0 if unknown)
BinaryVersion int // schema.LatestVersion() for this binary
Reason string
Ahead bool // DB schema newer than this binary
Pending bool // binary knows migrations the DB has not applied
}
// AssessSchemaFixGate compares schema_migrations to this binary. It yields one
// memoised verdict per invocation, evaluated before any *gated* write and
// threaded through to every consumer: probing at print time cannot guard writes
// that already happened. The bd-jgxi auto-migrate that runs earlier in the
// command (cmd/bd/version_tracking.go) is deliberately outside this gate's
// jurisdiction — it is the sanctioned migration path, not a repair the gate
// withholds — so "before any gated write" is the contract, not "before
// anything that touches the schema".
func AssessSchemaFixGate(path string) FixGate {
binary := schema.LatestVersion()
// No database at all: scoped allowance, not a fail-open — DB fixes stay
// disallowed because there is no DB to fix, and no schema exists to skew.
unreachable := FixGate{
BinaryVersion: binary,
Determined: true,
RecommendFix: true,
AllowFSFix: true,
}
beadsDir := ResolveBeadsDirForRepo(path)
db, _, err := openDoltDB(beadsDir)
if err != nil {
// A failed connection is not evidence that there is no database. When
// the database is still on disk — a stopped server, a moved port — the
// schema hazard is real and unmeasured: every gated repair opens the
// store through the migrating factory, which auto-starts the server and
// applies pending migrations before writing. Fail closed on that, and
// keep the genuine no-database case above as the only no-hazard shape.
// Recovery fixers stay available either way (AllowsFix keys them on
// DBReachable, which is false here too) because they are the cure for a
// database that cannot be opened.
if !databaseExistsOnDisk(beadsDir) {
return unreachable
}
return FixGate{
BinaryVersion: binary,
DBPresent: true,
AllowFSFix: true,
Reason: "database exists but could not be opened, so its schema version is unknown; " +
"`bd doctor --fix` may apply migrations blind — start the database and re-run",
}
}
defer db.Close()
// Reachable but unreadable: fail closed rather than claim safety.
undetermined := FixGate{
BinaryVersion: binary,
DBReachable: true,
DBPresent: true,
AllowFSFix: true,
Reason: "database schema version could not be determined; " +
"`bd doctor --fix` may apply migrations blind — resolve the database state first",
}
ctx := context.Background()
dbVer, err := schema.CurrentVersion(ctx, db)
if err != nil || dbVer == 0 {
return undetermined
}
gate := FixGate{
Determined: true,
DBReachable: true,
DBPresent: true,
DBVersion: dbVer,
BinaryVersion: binary,
AllowFSFix: true,
}
switch {
case dbVer > binary:
gate.Ahead = true
gate.Reason = fmt.Sprintf(
"database schema is at v%d, this binary knows up to v%d (%s ahead). "+
"`bd doctor --fix` can write/migrate and is unsafe on a newer schema — upgrade bd first",
dbVer, binary, pluralMigrations(dbVer-binary),
)
case dbVer < binary:
gate.Pending = true
gate.Reason = fmt.Sprintf(
"database schema is at v%d, this binary expects v%d (%s pending). "+
"`bd doctor --fix` may apply write migrations — upgrade/migrate deliberately, not as a cosmetic tip",
dbVer, binary, pluralMigrations(binary-dbVer),
)
default:
gate.RecommendFix = true
gate.AllowDBFix = true
}
return gate
}
// databaseExistsOnDisk reports whether a beads database is present for this
// workspace, independent of whether anything can currently connect to it. It
// stats the path autoMigrateOnVersionBump stats (cmd/bd/version_tracking.go)
// and, like it, reads only ENOENT as absent: a path that cannot be stat'ed for
// any other reason is unknown, and unknown is not safe. An unloadable
// metadata.json reads as absent in both, which is safe: the store factory
// refuses to open such a workspace at all.
//
// It departs from that probe deliberately in two arms:
//
// - No metadata.json reads as absent, where auto-migrate falls back to
// DefaultConfig. The gate cannot connect without metadata.json (openDoltDB
// requires it), so a fail-closed verdict here could never be cleared by
// starting a server, and it would rewrite doctor's own advice for this
// state — regenerate metadata.json with `bd doctor --fix`, a
// filesystem-only repair — into "Do NOT run 'bd doctor --fix'". The cost is
// one unguarded state: 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 reads as present when its data directory is
// on disk. Auto-migrate skips proxied workspaces because their migration
// runs later, at UOW-provider init, not because they lack a local database:
// the proxied root defaults to this same directory. `bd doctor` itself is
// refused up front in proxied-server mode (proxy.doctor.unsupported); this
// arm fails closed so that it is already safe when doctor gains a proxied
// route.
func databaseExistsOnDisk(beadsDir string) bool {
cfg, err := configfile.Load(beadsDir)
if err != nil || cfg == nil {
return false
}
if _, err := os.Stat(cfg.DatabasePath(beadsDir)); os.IsNotExist(err) {
return false
}
return true
}
// BlocksDestructiveWrites reports whether an operation that can resume
// migrations must be refused outright. It is the hazard question rather than the
// connectivity one: a database that exists but whose schema state does not
// permit schema-writing repair blocks, whether or not this process reached it.
// A workspace with no database never blocks — there is nothing to skew.
func (g FixGate) BlocksDestructiveWrites() bool {
return g.DBPresent && !g.AllowDBFix
}
func pluralMigrations(n int) string {
if n == 1 {
return "1 migration"
}
return fmt.Sprintf("%d migrations", n)
}
// fixAdvicePattern matches a tip steering at `bd doctor --fix`, tolerating flag
// order and spacing. Best-effort: it is still a sniff over free-form prose.
var fixAdvicePattern = regexp.MustCompile(`(?i)\bdoctor\b[^\n]*--fix\b`)
// originalTipMarker prefixes preserved advice in a rewritten tip, and doubles
// as the idempotence sentinel.
const originalTipMarker = "Original tip was: "
// MentionsFixAdvice reports whether a tip steers at `bd doctor --fix`.
func MentionsFixAdvice(fix string) bool {
return fixAdvicePattern.MatchString(fix)
}
// SanitizeFixRecommendation rewrites Fix text that steers into `bd doctor
// --fix` when the gate says that is unsafe (GH#4993). Apply once to the
// result, not per-renderer — see sanitizeFixAdvice in cmd/bd.
func SanitizeFixRecommendation(fix string, gate FixGate) string {
if gate.RecommendFix || fix == "" || !MentionsFixAdvice(fix) {
return fix
}
// The --fix path sanitizes again after re-running diagnostics.
if strings.Contains(fix, originalTipMarker) {
return fix
}
switch {
case gate.Ahead:
return fmt.Sprintf("Do NOT run 'bd doctor --fix' until bd is upgraded (%s). %s%s",
gate.Reason, originalTipMarker, fix)
case gate.Pending:
return fmt.Sprintf(
"Avoid 'bd doctor --fix' for cosmetic repair while schema migrations are pending (%s). "+
"Prefer targeted fixes or an intentional migrate. %s%s",
gate.Reason, originalTipMarker, fix)
case !gate.Determined:
return fmt.Sprintf("Do NOT run 'bd doctor --fix' (%s). %s%s",
gate.Reason, originalTipMarker, fix)
}
return fix
}
// filesystemOnlyFixes are repairs that provably touch only files on disk.
// Unlisted names are treated as database-touching, so a fix added later is
// guarded by default rather than escaping the gate silently.
//
// Every name in applyFixList's dispatch switch (cmd/bd/doctor_fix.go) was
// audited against that rule. The ones deliberately left out open a store, so
// being withheld under a blocked gate is correct rather than an omission:
// "Database", "Database Integrity", "Fresh Clone", "Schema Compatibility",
// "Repo Fingerprint" (fix.RepoFingerprint and fix.FixMissingMetadata both write
// through the store), "Dolt Schema", "Pending Migrations", and the row-level
// data repairs. "Sync Divergence", "JSONL Config" and "Untracked Files" are
// retired no-ops that write nothing at all; they stay unlisted because they are
// not filesystem repairs, and withholding a no-op costs the user nothing.
var filesystemOnlyFixes = map[string]bool{
"Gitignore": true,
"Project Gitignore": true,
"Metadata Config": true,
"Redirect Tracking": true,
"Last-Touched Tracking": true,
"Tracked Runtime Files": true,
"Git Hooks": true,
"Hooks Path": true, // git-config unset, beads-managed paths only
"Permissions": true,
"Lock Files": true,
"Legacy MQ Files": true,
"Classic Artifacts": true,
"Btrfs NoCOW (dolt)": true,
"Circuit Breaker": true, // removes stale circuit-breaker marker files
"Database Config": true, // rewrites metadata.json only; refuses Dolt outright
}
// IsFilesystemOnlyFix reports whether the named fix touches only the
// filesystem. Unknown names report false — see filesystemOnlyFixes.
func IsFilesystemOnlyFix(checkName string) bool {
return filesystemOnlyFixes[strings.TrimSpace(checkName)]
}
// recoveryFixes are the repairs a user reaches for when the database cannot be
// opened at all. Each rewrites on-disk database state or metadata and none can
// migrate a schema that already exists elsewhere; each is the *cure* for an
// unreachable database rather than a schema write:
// - Corrupt Manifest moves .dolt/ aside and runs a plain `dolt init`.
// - Dolt Format seeds a marker file.
// - Dolt Schema probes the server over a plain read connection to find the
// right database name and writes only metadata.json.
// - Database Integrity moves the local dolt directory aside and runs
// `bd init --force`, which does open a store, but only the fresh one it
// just created; server-mode repos, whose schema lives on a shared server,
// are refused up front by serverModeIntegrityRecoveryGuard.
//
// Fresh Clone and Database are deliberately absent: they open the existing
// store through the migrating factory. Unlisted names are treated as
// schema-writing, as in filesystemOnlyFixes.
var recoveryFixes = map[string]bool{
"Corrupt Manifest": true, // backup + reinit of a corrupt .dolt/
"Database Integrity": true, // backup + `bd init --force`
"Dolt Format": true, // seeds a marker file
"Dolt Schema": true, // backfills dolt_database in metadata.json
}
// IsRecoveryFix reports whether the named fix repairs an unopenable database
// without a schema-writing open. See recoveryFixes.
func IsRecoveryFix(checkName string) bool {
return recoveryFixes[strings.TrimSpace(checkName)]
}
// AllowsFix is the single admission policy for applying (or previewing as
// runnable) the named fix under this gate. Filesystem-only fixes follow
// AllowFSFix. Everything else needs AllowDBFix, with one narrow exception:
// recovery fixers stay available while the database is unreachable, because
// with no readable schema there is nothing to skew, and withholding them would
// block the very repairs that make a dead database reachable again. When the
// database is reachable but skewed or undetermined they stay withheld.
func (g FixGate) AllowsFix(checkName string) bool {
switch {
case IsFilesystemOnlyFix(checkName):
return g.AllowFSFix
case g.AllowDBFix:
return true
case !g.DBReachable && IsRecoveryFix(checkName):
return true
}
return false
}

View file

@ -0,0 +1,213 @@
//go:build cgo
package doctor
import (
"context"
"crypto/rand"
"database/sql"
"encoding/hex"
"fmt"
"strings"
"testing"
"time"
"github.com/steveyegge/beads/internal/storage/doltutil"
"github.com/steveyegge/beads/internal/testutil"
"github.com/steveyegge/beads/schema"
)
// seedGateDatabase creates a throwaway database on the shared test server and
// runs setup against it. Returns the database name; dropped on cleanup.
func seedGateDatabase(t *testing.T, port int, setup func(t *testing.T, db *sql.DB)) string {
t.Helper()
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
buf := make([]byte, 6)
if _, err := rand.Read(buf); err != nil {
t.Fatalf("rand: %v", err)
}
dbName := "gateassess_" + hex.EncodeToString(buf)
dsn := doltutil.ServerDSN{Host: "127.0.0.1", Port: port, User: "root", Timeout: 10 * time.Second}.String()
admin, err := sql.Open("mysql", dsn)
if err != nil {
t.Fatalf("open admin connection: %v", err)
}
t.Cleanup(func() {
dropCtx, dropCancel := context.WithTimeout(context.Background(), 30*time.Second)
defer dropCancel()
_, _ = admin.ExecContext(dropCtx, fmt.Sprintf("DROP DATABASE IF EXISTS `%s`", dbName))
_ = admin.Close()
})
// Single connection: USE and the statements that follow must share a session.
admin.SetMaxOpenConns(1)
if _, err := admin.ExecContext(ctx, fmt.Sprintf("CREATE DATABASE `%s`", dbName)); err != nil {
t.Fatalf("create database: %v", err)
}
if _, err := admin.ExecContext(ctx, fmt.Sprintf("USE `%s`", dbName)); err != nil {
t.Fatalf("use database: %v", err)
}
setup(t, admin)
return dbName
}
// seedMigrations returns a setup func that creates schema_migrations and
// records the given versions as applied.
func seedMigrations(versions ...int) func(t *testing.T, db *sql.DB) {
return func(t *testing.T, db *sql.DB) {
t.Helper()
if _, err := db.ExecContext(t.Context(),
"CREATE TABLE schema_migrations (version INT NOT NULL PRIMARY KEY)"); err != nil {
t.Fatalf("create schema_migrations: %v", err)
}
for _, v := range versions {
if _, err := db.ExecContext(t.Context(), "INSERT INTO schema_migrations (version) VALUES (?)", v); err != nil {
t.Fatalf("insert version %d: %v", v, err)
}
}
}
}
// TestAssessSchemaFixGate_RealDolt exercises the function that decides ahead /
// pending / equal / undetermined against a real Dolt server with a seeded
// schema_migrations. Every other gate test builds a FixGate literal by hand, so
// without this the assessor itself — the headline guard of GH#4993 — is never
// run: `case dbVer > binary:` could be replaced by `case false:` and the suite
// stayed green.
func TestAssessSchemaFixGate_RealDolt(t *testing.T) {
if testutil.DoltContainerCrashed() {
t.Skipf("Dolt test server crashed: %v", testutil.DoltContainerCrashError())
}
port := doctorTestServerPort()
if port == 0 {
t.Skip("Dolt test server not available, skipping")
}
binary := schema.LatestVersion()
if binary < 2 {
t.Fatalf("test needs at least 2 known migrations, binary knows %d", binary)
}
// The reachable-but-not-readable states share one expectation: fail closed.
failClosed := func(t *testing.T, g FixGate) {
t.Helper()
if !g.DBReachable {
t.Error("DBReachable = false, want true (the server answered)")
}
if g.Determined || g.AllowDBFix || g.RecommendFix {
t.Errorf("Determined=%v AllowDBFix=%v RecommendFix=%v, want all false: unknown is not safe",
g.Determined, g.AllowDBFix, g.RecommendFix)
}
if g.Ahead || g.Pending {
t.Errorf("Ahead=%v Pending=%v, want neither when the version is unknown", g.Ahead, g.Pending)
}
if !strings.Contains(g.Reason, "could not be determined") {
t.Errorf("Reason = %q, want it to say the version could not be determined", g.Reason)
}
}
cases := []struct {
name string
setup func(t *testing.T, db *sql.DB)
verify func(t *testing.T, g FixGate)
}{
{
name: "ahead",
setup: seedMigrations(binary + 3),
verify: func(t *testing.T, g FixGate) {
if !g.Ahead || g.Pending {
t.Errorf("Ahead=%v Pending=%v, want Ahead only", g.Ahead, g.Pending)
}
if g.AllowDBFix || g.RecommendFix {
t.Errorf("AllowDBFix=%v RecommendFix=%v, want both false on a newer schema", g.AllowDBFix, g.RecommendFix)
}
if g.DBVersion != binary+3 || g.BinaryVersion != binary {
t.Errorf("DBVersion=%d BinaryVersion=%d, want %d/%d", g.DBVersion, g.BinaryVersion, binary+3, binary)
}
if !strings.Contains(g.Reason, "3 migrations ahead") {
t.Errorf("Reason = %q, want it to name 3 migrations ahead", g.Reason)
}
},
},
{
name: "behind (pending)",
setup: seedMigrations(binary - 1),
verify: func(t *testing.T, g FixGate) {
if !g.Pending || g.Ahead {
t.Errorf("Ahead=%v Pending=%v, want Pending only", g.Ahead, g.Pending)
}
if g.AllowDBFix || g.RecommendFix {
t.Errorf("AllowDBFix=%v RecommendFix=%v, want both false while migrations are pending", g.AllowDBFix, g.RecommendFix)
}
if g.DBVersion != binary-1 {
t.Errorf("DBVersion = %d, want %d", g.DBVersion, binary-1)
}
if !strings.Contains(g.Reason, "1 migration pending") {
t.Errorf("Reason = %q, want it to name 1 migration pending", g.Reason)
}
},
},
{
name: "equal",
setup: seedMigrations(binary-1, binary),
verify: func(t *testing.T, g FixGate) {
if g.Ahead || g.Pending {
t.Errorf("Ahead=%v Pending=%v, want neither at parity", g.Ahead, g.Pending)
}
if !g.AllowDBFix || !g.RecommendFix || !g.Determined {
t.Errorf("AllowDBFix=%v RecommendFix=%v Determined=%v, want all true at parity",
g.AllowDBFix, g.RecommendFix, g.Determined)
}
if g.Reason != "" {
t.Errorf("Reason = %q, want empty at parity", g.Reason)
}
if g.DBVersion != binary {
t.Errorf("DBVersion = %d, want %d", g.DBVersion, binary)
}
},
},
{
// Pins current behavior, not an endorsement: a version of 0 (empty
// table) is treated as "could not be determined" and so fails
// closed. Revisit together with the table-absent case below.
name: "empty schema_migrations",
setup: seedMigrations(),
verify: failClosed,
},
{
name: "no schema_migrations table",
setup: func(*testing.T, *sql.DB) {},
verify: failClosed,
},
{
name: "schema_migrations unreadable",
setup: func(t *testing.T, db *sql.DB) {
if _, err := db.ExecContext(t.Context(), "CREATE TABLE schema_migrations (unrelated INT)"); err != nil {
t.Fatalf("create malformed schema_migrations: %v", err)
}
},
verify: failClosed,
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
dbName := seedGateDatabase(t, port, tc.setup)
setGatePort(t, port)
gate := AssessSchemaFixGate(writeGateWorkspace(t, dbName))
// Invariants for every reachable assessment.
if !gate.DBReachable {
t.Fatalf("DBReachable = false; the seeded database should be reachable: %+v", gate)
}
if !gate.AllowFSFix {
t.Error("AllowFSFix = false; filesystem repair must not depend on schema state")
}
if gate.BinaryVersion != binary {
t.Errorf("BinaryVersion = %d, want %d", gate.BinaryVersion, binary)
}
tc.verify(t, gate)
})
}
}

View file

@ -0,0 +1,280 @@
package doctor
import (
"net"
"os"
"path/filepath"
"runtime"
"strconv"
"testing"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/schema"
)
// writeGateWorkspace writes a Dolt-backend .beads/metadata.json naming dbName
// and returns the repo path handed to AssessSchemaFixGate.
func writeGateWorkspace(t *testing.T, dbName string) string {
t.Helper()
return writeGateConfig(t, &configfile.Config{Backend: configfile.BackendDolt, DoltDatabase: dbName})
}
// writeGateConfig writes cfg as .beads/metadata.json in a fresh repo and
// returns the repo path.
func writeGateConfig(t *testing.T, cfg *configfile.Config) string {
t.Helper()
repo := t.TempDir()
beadsDir := filepath.Join(repo, ".beads")
if err := os.MkdirAll(beadsDir, 0o750); err != nil {
t.Fatal(err)
}
if err := cfg.Save(beadsDir); err != nil {
t.Fatalf("save metadata.json: %v", err)
}
return repo
}
// mkdirGateDoltDir creates <repo>/.beads/dolt, where DatabasePath resolves for
// a config with no dolt_data_dir.
func mkdirGateDoltDir(t *testing.T, repo string) {
t.Helper()
if err := os.MkdirAll(filepath.Join(repo, ".beads", "dolt"), 0o750); err != nil {
t.Fatal(err)
}
}
// closedPort returns a loopback port with nothing listening on it.
func closedPort(t *testing.T) int {
t.Helper()
l, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
port := l.Addr().(*net.TCPAddr).Port
if err := l.Close(); err != nil {
t.Fatal(err)
}
return port
}
// setGatePort routes doltserver port resolution to port for this test.
func setGatePort(t *testing.T, port int) {
t.Helper()
// BEADS_DOLT_SERVER_PORT is the highest-priority source in
// doltserver.DefaultConfig, which openDoltDB resolves the port through.
t.Setenv("BEADS_DOLT_SERVER_PORT", strconv.Itoa(port))
}
// TestAssessSchemaFixGate_Unreachable pins the no-database shape: no schema
// hazard exists to guard against, so filesystem repair and printed advice are
// unaffected, but schema-writing fixes stay disallowed because there is no
// database to fix. Both cases reach it with nothing on disk to migrate — a
// missing config, and a config whose database directory was never created.
//
// "Configured, on disk, and unreachable" is deliberately NOT this shape: see
// TestAssessSchemaFixGate_PresentButUnopenableFailsClosed, which pins the
// fail-closed complement.
func TestAssessSchemaFixGate_Unreachable(t *testing.T) {
cases := map[string]func(t *testing.T) string{
"no metadata.json": func(t *testing.T) string {
repo := t.TempDir()
if err := os.MkdirAll(filepath.Join(repo, ".beads"), 0o750); err != nil {
t.Fatal(err)
}
setGatePort(t, closedPort(t))
return repo
},
"configured but no database on disk": func(t *testing.T) string {
setGatePort(t, closedPort(t))
return writeGateWorkspace(t, "gate_unreachable")
},
}
for name, setup := range cases {
t.Run(name, func(t *testing.T) {
gate := AssessSchemaFixGate(setup(t))
if gate.DBReachable {
t.Error("DBReachable = true, want false")
}
if gate.AllowDBFix {
t.Error("AllowDBFix = true on an unreachable database; schema-writing fixes must stay withheld")
}
if !gate.AllowFSFix {
t.Error("AllowFSFix = false; filesystem repair must not depend on the database")
}
if !gate.RecommendFix || !gate.Determined {
t.Errorf("RecommendFix=%v Determined=%v, want both true (no hazard to warn about)",
gate.RecommendFix, gate.Determined)
}
if gate.Ahead || gate.Pending {
t.Errorf("Ahead=%v Pending=%v, want neither without a database", gate.Ahead, gate.Pending)
}
if gate.BinaryVersion != schema.LatestVersion() {
t.Errorf("BinaryVersion = %d, want %d", gate.BinaryVersion, schema.LatestVersion())
}
if gate.DBPresent {
t.Error("DBPresent = true with no database on disk; nothing exists to guard")
}
if gate.BlocksDestructiveWrites() {
t.Error("BlocksDestructiveWrites() = true with no database; there is no schema to skew")
}
})
}
}
// TestAssessSchemaFixGate_PresentButUnopenableFailsClosed is the regression test
// for the fail-open reported on PR #5145: a server-mode repo whose database is
// still on disk but whose server is stopped assessed identically to a repo with
// no database at all. That shape left DBReachable false, which the destructive
// `--check` refusal keyed on, so `bd doctor --check=pollution --clean` skipped
// the refusal, auto-started the server through the migrating factory, applied
// pending migrations blind and then deleted rows — while the identical command
// against the identical schema was refused whenever the server happened to be up.
//
// A database that exists has a schema a migrating open can rewrite, whether or
// not this process could read it, so the verdict must fail closed. The other
// cases pin the arms where databaseExistsOnDisk departs from, or had drifted
// from, autoMigrateOnVersionBump's probe: a proxied-server workspace, whose
// data directory is local even though auto-migrate skips it, and a data
// directory whose stat fails with something other than ENOENT.
func TestAssessSchemaFixGate_PresentButUnopenableFailsClosed(t *testing.T) {
cases := map[string]func(t *testing.T) string{
"stopped server": func(t *testing.T) string {
repo := writeGateWorkspace(t, "gate_present_unopenable")
// The database directory is what makes this distinct from the
// unreachable case.
mkdirGateDoltDir(t, repo)
return repo
},
"proxied-server workspace": func(t *testing.T) string {
repo := writeGateConfig(t, &configfile.Config{
Backend: configfile.BackendDolt,
DoltMode: configfile.DoltModeProxiedServer,
DoltDatabase: "gate_proxied",
})
// The proxied root defaults to the same directory.
mkdirGateDoltDir(t, repo)
return repo
},
"data directory cannot be stat'ed": func(t *testing.T) string {
if runtime.GOOS == "windows" {
t.Skip("POSIX-only: Windows can report a file used as a directory as path-not-found, which os.IsNotExist matches")
}
// A data directory configured beneath a regular file fails its
// stat with ENOTDIR: unknown, not absent. Relative, because Save
// drops an absolute dolt_data_dir as machine-local.
repo := writeGateConfig(t, &configfile.Config{
Backend: configfile.BackendDolt,
DoltDatabase: "gate_unstatable",
DoltDataDir: filepath.Join("not-a-directory", "dolt"),
})
if err := os.WriteFile(filepath.Join(repo, ".beads", "not-a-directory"), nil, 0o600); err != nil {
t.Fatal(err)
}
return repo
},
}
for name, setup := range cases {
t.Run(name, func(t *testing.T) {
setGatePort(t, closedPort(t))
t.Setenv("BEADS_DOLT_DATA_DIR", "") // would override DatabasePath
gate := AssessSchemaFixGate(setup(t))
assertPresentButUnopenable(t, gate)
})
}
}
// TestAssessSchemaFixGate_MissingMetadataReadsAbsent pins databaseExistsOnDisk's
// deliberate departure from autoMigrateOnVersionBump, which falls back to
// DefaultConfig: with no metadata.json, a data directory on disk still assesses
// as the no-database shape. The gate cannot connect without metadata.json, so
// failing closed could never be cleared, and it would turn doctor's advice for
// this state — the filesystem-only `bd doctor --fix` that regenerates
// metadata.json — into "Do NOT run 'bd doctor --fix'".
func TestAssessSchemaFixGate_MissingMetadataReadsAbsent(t *testing.T) {
setGatePort(t, closedPort(t))
repo := t.TempDir()
mkdirGateDoltDir(t, repo)
gate := AssessSchemaFixGate(repo)
if gate.DBPresent || gate.BlocksDestructiveWrites() {
t.Errorf("DBPresent=%v BlocksDestructiveWrites()=%v, want both false without metadata.json",
gate.DBPresent, gate.BlocksDestructiveWrites())
}
if !gate.RecommendFix || !gate.Determined {
t.Errorf("RecommendFix=%v Determined=%v, want both true: the advice for this state is `bd doctor --fix`",
gate.RecommendFix, gate.Determined)
}
if !gate.AllowsFix("Metadata Config") {
t.Error(`AllowsFix("Metadata Config") = false; regenerating metadata.json is the repair for this state`)
}
}
// assertPresentButUnopenable checks the fail-closed shape for a database that
// may exist but whose schema version was never read.
func assertPresentButUnopenable(t *testing.T, gate FixGate) {
t.Helper()
if !gate.DBPresent {
t.Fatal("DBPresent = false; a database that may be on disk must be guarded")
}
if gate.DBReachable {
t.Error("DBReachable = true although nothing is listening; the connection did not happen")
}
if !gate.BlocksDestructiveWrites() {
t.Error("BlocksDestructiveWrites() = false; a destructive --check must be refused here")
}
if gate.AllowDBFix {
t.Error("AllowDBFix = true for a database whose schema version was never read")
}
if gate.Determined {
t.Error("Determined = true although the schema version could not be read")
}
if gate.RecommendFix {
t.Error("RecommendFix = true; printed advice must not steer at --fix for an unread schema")
}
if gate.Reason == "" {
t.Error("Reason is empty; the refusal and the sanitized advice both interpolate it")
}
if !gate.AllowFSFix {
t.Error("AllowFSFix = false; filesystem repair does not depend on the schema")
}
// Recovery fixers are the cure for a database that cannot be opened, so they
// must survive this shape exactly as they survive the no-database one.
for _, name := range []string{"Corrupt Manifest", "Database Integrity"} {
if !gate.AllowsFix(name) {
t.Errorf("AllowsFix(%q) = false; the recovery fixers for an unopenable database must stay available", name)
}
}
// ...but a repair that opens the store through the migrating factory is
// exactly the hazard, and stays withheld.
for _, name := range []string{"Fresh Clone", "Schema Compatibility"} {
if gate.AllowsFix(name) {
t.Errorf("AllowsFix(%q) = true; a migrating open is the hazard this gate exists for", name)
}
}
}
// TestFixGateBlocksDestructiveWrites pins the hazard predicate across every
// shape, so the destructive `--check` refusal cannot drift back onto a
// connectivity test. Only "no database at all" and "schema verified current"
// may admit a destructive write.
func TestFixGateBlocksDestructiveWrites(t *testing.T) {
cases := []struct {
name string
gate FixGate
want bool
}{
{"no database", FixGate{Determined: true, RecommendFix: true, AllowFSFix: true}, false},
{"schema current", FixGate{Determined: true, DBReachable: true, DBPresent: true, AllowDBFix: true, AllowFSFix: true}, false},
{"present but unopenable", FixGate{DBPresent: true, AllowFSFix: true}, true},
{"reachable but unreadable", FixGate{DBReachable: true, DBPresent: true, AllowFSFix: true}, true},
{"pending", FixGate{Determined: true, DBReachable: true, DBPresent: true, Pending: true, AllowFSFix: true}, true},
{"ahead", FixGate{Determined: true, DBReachable: true, DBPresent: true, Ahead: true, AllowFSFix: true}, true},
}
for _, c := range cases {
if got := c.gate.BlocksDestructiveWrites(); got != c.want {
t.Errorf("%s: BlocksDestructiveWrites() = %v, want %v", c.name, got, c.want)
}
}
}

View file

@ -0,0 +1,199 @@
package doctor
import (
"strings"
"testing"
)
func safeGate() FixGate {
return FixGate{
Determined: true,
DBReachable: true,
RecommendFix: true,
AllowDBFix: true,
AllowFSFix: true,
}
}
func TestSanitizeFixRecommendation_SafePassesThrough(t *testing.T) {
in := "Run 'bd doctor --fix' to untrack runtime files"
if got := SanitizeFixRecommendation(in, safeGate()); got != in {
t.Fatalf("safe gate should pass through, got %q", got)
}
}
func TestSanitizeFixRecommendation_AheadBlocksTip(t *testing.T) {
gate := FixGate{
Determined: true,
DBReachable: true,
Ahead: true,
AllowFSFix: true,
DBVersion: 52,
BinaryVersion: 49,
Reason: "database schema is at v52, this binary knows up to v49 (3 migrations ahead)",
}
in := "Run 'bd doctor --fix' to untrack, or manually: git rm --cached .beads/redirect"
got := SanitizeFixRecommendation(in, gate)
if got == in {
t.Fatal("expected rewrite when schema is ahead")
}
for _, part := range []string{"Do NOT run", "doctor --fix", "Original tip"} {
if !strings.Contains(got, part) {
t.Fatalf("rewrite missing %q: %q", part, got)
}
}
}
func TestSanitizeFixRecommendation_PendingWarns(t *testing.T) {
gate := FixGate{
Determined: true,
DBReachable: true,
Pending: true,
AllowFSFix: true,
DBVersion: 48,
BinaryVersion: 52,
Reason: "pending migrations",
}
in := "Run: bd doctor --fix"
got := SanitizeFixRecommendation(in, gate)
if got == in {
t.Fatal("expected rewrite when migrations pending")
}
for _, part := range []string{"Avoid", "pending", "Original tip"} {
if !strings.Contains(got, part) {
t.Fatalf("rewrite missing %q: %q", part, got)
}
}
}
func TestSanitizeFixRecommendation_NoDoctorFixUnchanged(t *testing.T) {
gate := FixGate{Determined: true, DBReachable: true, Ahead: true, Reason: "skew"}
in := "Run 'bd bootstrap' as recovery"
if got := SanitizeFixRecommendation(in, gate); got != in {
t.Fatalf("non --fix tip should pass through, got %q", got)
}
}
// TestSanitizeFixRecommendation_UndeterminedFailsClosed pins the property that
// "we could not determine the schema version" is not the same as "safe".
func TestSanitizeFixRecommendation_UndeterminedFailsClosed(t *testing.T) {
gate := FixGate{
DBReachable: true,
Determined: false,
AllowFSFix: true,
Reason: "database schema version could not be determined",
}
in := "Run 'bd doctor --fix' to repair"
got := SanitizeFixRecommendation(in, gate)
if got == in {
t.Fatal("an undetermined schema version must not pass --fix advice through unchanged")
}
if !strings.Contains(got, "Do NOT run") {
t.Fatalf("undetermined gate should refuse, got %q", got)
}
}
// TestMentionsFixAdvice_ToleratesFlagOrderAndSpacing covers the wordings the
// previous strings.Contains("doctor --fix") sniff silently missed.
func TestMentionsFixAdvice_ToleratesFlagOrderAndSpacing(t *testing.T) {
shouldMatch := []string{
"Run 'bd doctor --fix'",
"bd doctor --fix",
"bd doctor --yes --fix",
"try `bd doctor --fix --verbose` next",
"Run BD DOCTOR --FIX",
}
for _, s := range shouldMatch {
if !MentionsFixAdvice(s) {
t.Errorf("expected %q to be recognised as --fix advice", s)
}
}
shouldNotMatch := []string{
"Run 'bd bootstrap'",
"see the doctor documentation",
"pass --fixture to the test runner",
}
for _, s := range shouldNotMatch {
if MentionsFixAdvice(s) {
t.Errorf("did not expect %q to be treated as --fix advice", s)
}
}
}
// TestIsFilesystemOnlyFix_DefaultsToGuarded pins the fail-closed default: a fix
// nobody has classified is treated as database-touching, so a check added later
// is guarded rather than silently escaping the gate.
func TestIsFilesystemOnlyFix_DefaultsToGuarded(t *testing.T) {
for _, name := range []string{"Gitignore", "Permissions", "Lock Files", "Git Hooks"} {
if !IsFilesystemOnlyFix(name) {
t.Errorf("%q should be classified filesystem-only", name)
}
}
for _, name := range []string{
"Database", "Schema Compatibility", "Blocked State",
"Some Check Added Next Year", "",
} {
if IsFilesystemOnlyFix(name) {
t.Errorf("%q must default to database-touching (guarded)", name)
}
}
}
// TestFixGateAllowsFix pins the single admission policy: filesystem-only fixes
// follow AllowFSFix; everything else needs AllowDBFix, except recovery fixers,
// which stay available only while the database is unreachable.
func TestFixGateAllowsFix(t *testing.T) {
ahead := FixGate{Determined: true, DBReachable: true, Ahead: true, AllowFSFix: true}
unreachable := FixGate{Determined: true, RecommendFix: true, AllowFSFix: true}
undetermined := FixGate{DBReachable: true, AllowFSFix: true}
safe := safeGate()
cases := []struct {
gate string
g FixGate
fix string
want bool
}{
{"safe", safe, "Schema Compatibility", true},
{"safe", safe, "Corrupt Manifest", true},
{"safe", safe, "Gitignore", true},
{"ahead", ahead, "Schema Compatibility", false},
{"ahead", ahead, "Pending Migrations", false},
{"ahead", ahead, "Corrupt Manifest", false},
{"ahead", ahead, "Database Integrity", false},
{"ahead", ahead, "Gitignore", true},
{"undetermined", undetermined, "Corrupt Manifest", false},
{"undetermined", undetermined, "Schema Compatibility", false},
{"unreachable", unreachable, "Schema Compatibility", false},
{"unreachable", unreachable, "Pending Migrations", false},
{"unreachable", unreachable, "Database", false},
{"unreachable", unreachable, "Fresh Clone", false},
{"unreachable", unreachable, "Some Future Fix", false},
{"unreachable", unreachable, "Corrupt Manifest", true},
{"unreachable", unreachable, "Database Integrity", true},
{"unreachable", unreachable, "Dolt Format", true},
{"unreachable", unreachable, "Dolt Schema", true},
{"unreachable", unreachable, " Corrupt Manifest ", true},
{"unreachable", unreachable, "Gitignore", true},
{"no-fs", FixGate{}, "Gitignore", false},
}
for _, c := range cases {
if got := c.g.AllowsFix(c.fix); got != c.want {
t.Errorf("%s gate: AllowsFix(%q) = %v, want %v", c.gate, c.fix, got, c.want)
}
}
}
// Recovery and filesystem-only are disjoint classes; a name in both would
// silently take the filesystem branch and ignore the reachability rule.
func TestRecoveryFixesAreNotFilesystemOnly(t *testing.T) {
for name := range recoveryFixes {
if IsFilesystemOnlyFix(name) {
t.Errorf("%q is listed as both a recovery fix and a filesystem-only fix", name)
}
}
}

View file

@ -19,7 +19,8 @@ type agentDoctorResult struct {
// buildAgentResult converts a standard doctorResult to an agent-enriched result.
// Only non-OK checks are included in diagnostics — agents don't need 45 "ok" entries.
func buildAgentResult(result doctorResult) agentDoctorResult {
// The gate is applied to each enriched command list; see doctor.EnrichForAgent.
func buildAgentResult(result doctorResult, gate doctor.FixGate) agentDoctorResult {
ar := agentDoctorResult{
Path: result.Path,
OverallOK: result.OverallOK,
@ -40,7 +41,7 @@ func buildAgentResult(result doctorResult) agentDoctorResult {
Detail: check.Detail,
Fix: check.Fix,
Category: check.Category,
}))
}, gate))
case statusWarning:
warnCount++
ar.Diagnostics = append(ar.Diagnostics, doctor.EnrichForAgent(doctor.DoctorCheck{
@ -50,7 +51,7 @@ func buildAgentResult(result doctorResult) agentDoctorResult {
Detail: check.Detail,
Fix: check.Fix,
Category: check.Category,
}))
}, gate))
}
}

View file

@ -0,0 +1,204 @@
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)
}
}

View file

@ -16,17 +16,36 @@ import (
"golang.org/x/term"
)
// previewFixes shows what would be fixed without applying changes
func previewFixes(result doctorResult) {
// Collect all fixable issues
var fixableIssues []doctorCheck
// collectFixableIssues returns actionable fixes split by whether applying them
// can touch the database schema (GH#4993). A schema gate should withhold schema
// writes, not refuse to repair a file mode.
func collectFixableIssues(result doctorResult) (dbFixes, fsFixes []doctorCheck) {
for _, check := range result.Checks {
if (check.Status == statusWarning || check.Status == statusError) && check.Fix != "" {
fixableIssues = append(fixableIssues, check)
if check.Status != statusWarning && check.Status != statusError {
continue
}
if check.Fix == "" {
continue
}
if doctor.IsFilesystemOnlyFix(check.Name) {
fsFixes = append(fsFixes, check)
} else {
dbFixes = append(dbFixes, check)
}
}
return dbFixes, fsFixes
}
if len(fixableIssues) == 0 {
// previewFixes shows what would be fixed without applying changes. A dry run
// writes nothing, so it is never refused on schema grounds; the gate decides
// how each fix is labeled, not whether the preview runs.
func previewFixes(result doctorResult, gate doctor.FixGate) {
if gate.Reason != "" {
fmt.Printf("\n%s Schema gate: %s\n", ui.RenderWarn("⚠"), gate.Reason)
}
dbFixes, fsFixes := collectFixableIssues(result)
if len(dbFixes)+len(fsFixes) == 0 {
fmt.Println("\n✓ No fixable issues found (dry-run)")
return
}
@ -34,9 +53,10 @@ func previewFixes(result doctorResult) {
fmt.Println("\n[DRY-RUN] The following issues would be fixed with --fix:")
fmt.Println()
for i, issue := range fixableIssues {
// Show the issue details
fmt.Printf(" %d. %s\n", i+1, issue.Name)
n := 0
printIssue := func(issue doctorCheck, blocked bool) {
n++
fmt.Printf(" %d. %s\n", n, issue.Name)
if issue.Status == statusError {
fmt.Printf(" Status: %s\n", ui.RenderFail("ERROR"))
} else {
@ -47,19 +67,75 @@ func previewFixes(result doctorResult) {
fmt.Printf(" Detail: %s\n", issue.Detail)
}
fmt.Printf(" Fix: %s\n", issue.Fix)
if blocked {
fmt.Printf(" %s\n", ui.RenderWarn("Blocked by the schema gate — would be skipped"))
}
fmt.Println()
}
fmt.Printf("[DRY-RUN] Would attempt to fix %d issue(s)\n", len(fixableIssues))
fmt.Println("Run 'bd doctor --fix' to apply these fixes")
// GH#4993: admission is FixGate.AllowsFix alone. Reason is advisory text,
// not a safety signal — an unreachable/undetermined gate leaves Reason at
// its zero value ("") while still needing schema-writing fixes withheld,
// so admitting on gate.Reason == "" reopened the bypass this gate closes.
blocked := 0
for _, issue := range append(append([]doctorCheck{}, fsFixes...), dbFixes...) {
withheld := !gate.AllowsFix(issue.Name)
if withheld {
blocked++
}
printIssue(issue, withheld)
}
total := len(fsFixes) + len(dbFixes)
switch {
case blocked > 0 && blocked < total:
fmt.Printf("[DRY-RUN] Would apply %d fix(es); %d fix(es) are blocked by the schema gate\n",
total-blocked, blocked)
fmt.Println("Run 'bd doctor --fix' to apply the permitted fixes; resolve the schema state to apply the rest")
case blocked > 0:
fmt.Printf("[DRY-RUN] All %d fix(es) are blocked by the schema gate\n", total)
fmt.Println("Resolve the schema state shown above before running 'bd doctor --fix'")
default:
fmt.Printf("[DRY-RUN] Would attempt to fix %d issue(s)\n", total)
fmt.Println("Run 'bd doctor --fix' to apply these fixes")
}
}
func applyFixes(result doctorResult) {
// Collect all fixable issues
var fixableIssues []doctorCheck
for _, check := range result.Checks {
if (check.Status == statusWarning || check.Status == statusError) && check.Fix != "" {
fixableIssues = append(fixableIssues, check)
func applyFixes(result doctorResult, gate doctor.FixGate) {
if gate.Reason != "" {
fmt.Printf("\n%s Schema gate: %s\n", ui.RenderWarn("⚠"), gate.Reason)
}
dbFixes, fsFixes := collectFixableIssues(result)
// GH#4993: withhold only what the gate is about. Filesystem-only fixes
// are never schema writes, and recovery fixers stay available when the
// database is unreachable (FixGate.AllowsFix); everything else is withheld
// whenever the gate blocks. Admission is AllowsFix alone, never
// gate.Reason == "".
// Everything AllowsFix rejects is reported. Qualifying this with
// !IsFilesystemOnlyFix would drop a withheld filesystem-only fix from both
// lists, silently no-opping it: unreachable while every constructed gate sets
// AllowFSFix, but a future gate shape that does not would fix nothing and say
// nothing. The label stays generic for the same reason — the withheld set is
// whatever the gate blocked, not necessarily database work.
var fixableIssues, withheld []doctorCheck
for _, issue := range append(append([]doctorCheck{}, fsFixes...), dbFixes...) {
if gate.AllowsFix(issue.Name) {
fixableIssues = append(fixableIssues, issue)
} else {
withheld = append(withheld, issue)
}
}
if len(withheld) > 0 {
reason := gate.Reason
if reason == "" {
reason = "database schema state could not be assessed"
}
fmt.Printf("\n%s Skipping %d gated fix(es) — %s\n",
ui.RenderFail("✗"), len(withheld), reason)
for _, issue := range withheld {
fmt.Printf(" · %s\n", issue.Name)
}
}

View file

@ -0,0 +1,460 @@
package main
import (
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/cmd/bd/doctor"
)
// The tests in this file cover the WIRING of the schema fix gate, not its
// predicate logic (that lives in cmd/bd/doctor/fix_gate_test.go).
//
// This distinction is the whole point. GH#4993 originally shipped with a
// correct predicate and a full suite of green tests, while three of the four
// output paths emitted unguarded advice, one command family bypassed the gate
// entirely, and a bare `bd doctor` applied migrations before the gate was
// consulted. Every one of those is a wiring defect, and a test that constructs
// a FixGate by hand cannot observe any of them.
const rawFixTip = "Run 'bd doctor --fix' to untrack runtime files"
// blockedGate is a determined gate that forbids recommending --fix.
func blockedGate() doctor.FixGate {
return doctor.FixGate{
Determined: true,
DBReachable: true,
Ahead: true,
AllowFSFix: true,
DBVersion: 52,
BinaryVersion: 49,
Reason: "database schema is at v52, this binary knows up to v49 (3 migrations ahead)",
}
}
func resultWithFixTip() doctorResult {
return doctorResult{
Path: "/tmp/does-not-need-to-exist",
CLIVersion: "test",
Checks: []doctorCheck{
{
Name: "Tracked Runtime Files",
Status: statusWarning,
Message: "runtime files are tracked",
Category: "Core",
Fix: rawFixTip,
},
},
}
}
// assertNoUnguardedFixAdvice fails if the raw tip appears anywhere that is not
// inside the gate's own "Original tip was: ..." rewrite.
func assertNoUnguardedFixAdvice(t *testing.T, label, out string) {
t.Helper()
if !strings.Contains(out, rawFixTip) {
return
}
guarded := strings.Count(out, "Original tip was: "+rawFixTip)
total := strings.Count(out, rawFixTip)
if guarded != total {
t.Errorf("%s emitted --fix advice the schema gate had ruled unsafe\n"+
" %d occurrence(s), only %d guarded\n---output---\n%s",
label, total, guarded, out)
}
}
// TestNoEmitterLeaksUnguardedFixAdvice is the regression test for the central
// defect: the sanitizer used to run inside printDiagnostics only, so --json,
// --agent and --output published advice the gate had already ruled unsafe.
//
// It is written as a property over the whole emitter set rather than as one
// example per format, because the failure mode is "somebody added an output
// path and did not know the guard existed."
func TestNoEmitterLeaksUnguardedFixAdvice(t *testing.T) {
gate := blockedGate()
result := resultWithFixTip()
sanitizeFixAdvice(&result, gate)
tmp := t.TempDir()
emitters := []struct {
name string
emit func(t *testing.T, r doctorResult) string
}{
{
name: "text/printDiagnostics",
emit: func(t *testing.T, r doctorResult) string {
return captureStdout(t, func() error {
printDiagnostics(r, gate)
return nil
})
},
},
{
name: "json/doctorResult",
emit: func(t *testing.T, r doctorResult) string {
b, err := json.Marshal(r)
if err != nil {
t.Fatalf("marshal: %v", err)
}
return string(b)
},
},
{
name: "agent/buildAgentResult",
emit: func(t *testing.T, r doctorResult) string {
b, err := json.Marshal(buildAgentResult(r, gate))
if err != nil {
t.Fatalf("marshal agent result: %v", err)
}
return string(b)
},
},
{
name: "export/exportDiagnostics",
emit: func(t *testing.T, r doctorResult) string {
p := filepath.Join(tmp, "diag.json")
if err := exportDiagnostics(r, p); err != nil {
t.Fatalf("export: %v", err)
}
b, err := os.ReadFile(p) // #nosec G304 - test-controlled path
if err != nil {
t.Fatalf("read export: %v", err)
}
return string(b)
},
},
}
for _, e := range emitters {
t.Run(e.name, func(t *testing.T) {
assertNoUnguardedFixAdvice(t, e.name, e.emit(t, result))
})
}
}
// assertAgentCommandsGuarded fails if any remediation command in the agent
// output steers at `bd doctor --fix` without the gate's rewrite marker.
// Agent enrichers hardcode their own commands, so the raw tip used by the
// other emitters is not what leaks here; the command text itself is.
func assertAgentCommandsGuarded(t *testing.T, label string, ar agentDoctorResult) {
t.Helper()
for _, d := range ar.Diagnostics {
for _, c := range d.Commands {
if doctor.MentionsFixAdvice(c) && !strings.Contains(c, "Original tip was: ") {
t.Errorf("%s: check %q (%s) published unguarded --fix command %q under a blocked gate",
label, d.Name, d.Status, c)
}
}
}
}
// TestNoAgentEnricherLeaksUnguardedFixCommand runs the --agent emitter over
// EVERY registered enricher, plus a name with no enricher (generic path).
// The original fixture used only an unenriched name, so the ~18 enrichers that
// hardcode `bd doctor --fix` were never exercised and the test passed
// vacuously. Both statuses are covered because some enrichers branch on it.
func TestNoAgentEnricherLeaksUnguardedFixCommand(t *testing.T) {
names := append(doctor.AgentEnricherNames(), "Tracked Runtime Files")
if len(names) < 20 {
t.Fatalf("expected the full enricher registry plus the unenriched case, got %d names", len(names))
}
build := func(gate doctor.FixGate) agentDoctorResult {
var r doctorResult
for _, name := range names {
for _, status := range []string{statusError, statusWarning} {
r.Checks = append(r.Checks, doctorCheck{
Name: name, Status: status, Message: "m", Category: "Core", Fix: rawFixTip,
})
}
}
sanitizeFixAdvice(&r, gate)
return buildAgentResult(r, gate)
}
// Non-vacuity: under a safe gate the fixture must actually surface
// `bd doctor --fix` commands from enrichers, or the blocked-gate assertion
// below proves nothing. Schema Compatibility and Database Integrity are
// the checks that fire on the very skew this gate exists for.
surfaced := map[string]bool{}
for _, d := range build(doctor.FixGate{Determined: true, DBReachable: true, RecommendFix: true, AllowDBFix: true, AllowFSFix: true}).Diagnostics {
for _, c := range d.Commands {
if doctor.MentionsFixAdvice(c) {
surfaced[d.Name] = true
}
}
}
for _, must := range []string{"Schema Compatibility", "Database Integrity", "Tracked Runtime Files"} {
if !surfaced[must] {
t.Fatalf("fixture too weak: %q surfaced no --fix command under a safe gate", must)
}
}
if len(surfaced) < 15 {
t.Fatalf("fixture too weak: only %d names surfaced --fix commands", len(surfaced))
}
assertAgentCommandsGuarded(t, "blocked gate", build(blockedGate()))
}
// TestSanitizeFixAdviceWritesThroughSlice pins the specific Go mistake that
// made the original guard a no-op: ranging by value over []doctorCheck mutates
// a copy. Asserting on the caller's slice — not on a returned value — is what
// makes this test able to fail.
func TestSanitizeFixAdviceWritesThroughSlice(t *testing.T) {
result := resultWithFixTip()
sanitizeFixAdvice(&result, blockedGate())
if result.Checks[0].Fix == rawFixTip {
t.Fatal("sanitizeFixAdvice did not write through to result.Checks — " +
"the mutation was applied to a copy")
}
if !strings.Contains(result.Checks[0].Fix, "Do NOT run") {
t.Fatalf("expected a guarded tip, got %q", result.Checks[0].Fix)
}
}
// TestSanitizeFixAdviceIsIdempotent guards against double-wrapping now that the
// pass runs again after --fix re-runs diagnostics.
func TestSanitizeFixAdviceIsIdempotent(t *testing.T) {
gate := blockedGate()
result := resultWithFixTip()
sanitizeFixAdvice(&result, gate)
once := result.Checks[0].Fix
sanitizeFixAdvice(&result, gate)
twice := result.Checks[0].Fix
if strings.Count(twice, "Original tip was:") > 1 {
t.Fatalf("sanitizing twice nested the guard:\n once: %q\ntwice: %q", once, twice)
}
}
// TestCheckFlagWrites enumerates which --check= invocations can modify state.
// The gate is applied at a single branch point in RunE keyed off this function,
// so this table is the complete statement of what is guarded — a new
// destructive check that is missing here is a silent bypass.
func TestCheckFlagWrites(t *testing.T) {
cases := []struct {
flag string
clean bool
fix bool
want bool
}{
{"pollution", true, false, true},
{"pollution", false, false, false},
{"artifacts", true, false, true},
{"artifacts", false, false, false},
{"validate", false, true, true},
{"validate", false, false, false},
{"conventions", true, true, false},
{"unknown-check", true, true, false},
}
for _, c := range cases {
if got := checkFlagWrites(c.flag, c.clean, c.fix); got != c.want {
t.Errorf("checkFlagWrites(%q, clean=%v, fix=%v) = %v, want %v",
c.flag, c.clean, c.fix, got, c.want)
}
}
}
// unreachableGate mirrors the `unreachable` FixGate literal in
// cmd/bd/doctor/fix_gate.go (AssessSchemaFixGate, openDoltDB failure branch):
// Determined and AllowFSFix are true, but AllowDBFix and Reason are left at
// their zero values (false, ""). A gate keyed off `gate.Reason == ""` reads
// this shape as "safe to fix" and admits database fixes on a stopped or
// unreachable Dolt server — the bypass GH#4993 exists to close.
func unreachableGate() doctor.FixGate {
return doctor.FixGate{
Determined: true,
RecommendFix: true,
AllowFSFix: true,
BinaryVersion: 49,
}
}
func resultWithDBFix() doctorResult {
return doctorResult{
Path: "/tmp/does-not-need-to-exist",
CLIVersion: "test",
Checks: []doctorCheck{
{
Name: "Schema Compatibility",
Status: statusError,
Message: "schema version mismatch",
Category: "Core",
Fix: "run 'bd doctor --fix' to migrate",
},
},
}
}
// TestApplyFixesWithholdsDBFixOnUnreachableGate is the regression test for the
// gate bypass: applyFixes admitted a database fix whenever
// `gate.AllowDBFix || gate.Reason == ""`, which is true for the unreachable
// shape above even though AllowDBFix is false. Gating on AllowDBFix alone
// withholds it.
func TestApplyFixesWithholdsDBFixOnUnreachableGate(t *testing.T) {
gate := unreachableGate()
result := resultWithDBFix()
out := captureStdout(t, func() error {
applyFixes(result, gate)
return nil
})
if strings.Contains(out, "Fixing Schema Compatibility") {
t.Fatalf("applyFixes attempted a database fix on an unreachable gate:\n%s", out)
}
if !strings.Contains(out, "No fixable issues found") {
t.Fatalf("expected applyFixes to withhold the only fix (a database fix) on an unreachable gate, got:\n%s", out)
}
}
// withNullStdin points os.Stdin at /dev/null so applyFixes takes its
// non-interactive early return after listing what it would fix, instead of
// prompting or running a real fixer against the test's fake path.
func withNullStdin(t *testing.T) {
t.Helper()
f, err := os.Open(os.DevNull)
if err != nil {
t.Fatal(err)
}
orig := os.Stdin
os.Stdin = f
t.Cleanup(func() {
os.Stdin = orig
_ = f.Close()
})
}
func resultWithRecoveryAndSchemaFixes() doctorResult {
return doctorResult{
Path: "/tmp/does-not-need-to-exist",
CLIVersion: "test",
Checks: []doctorCheck{
{Name: "Corrupt Manifest", Status: statusError, Message: "manifest corrupt", Fix: "bd doctor --fix"},
{Name: "Dolt Format", Status: statusWarning, Message: "pre-v56 dolt dir", Fix: "bd doctor --fix"},
{Name: "Database Integrity", Status: statusError, Message: "integrity check failed", Fix: "bd doctor --fix"},
{Name: "Dolt Schema", Status: statusWarning, Message: "dolt_database missing", Fix: "bd doctor --fix"},
{Name: "Schema Compatibility", Status: statusError, Message: "schema mismatch", Fix: "bd doctor --fix"},
{Name: "Pending Migrations", Status: statusWarning, Message: "pending", Fix: "bd doctor --fix"},
},
}
}
// TestApplyFixesKeepsRecoveryFixesOnUnreachableGate pins the narrow rule that
// an unopenable database must not withhold the fixes that repair an unopenable
// database: recovery fixers are listed as runnable, schema-writing fixes are
// still skipped.
func TestApplyFixesKeepsRecoveryFixesOnUnreachableGate(t *testing.T) {
withNullStdin(t)
out := captureStdout(t, func() error {
applyFixes(resultWithRecoveryAndSchemaFixes(), unreachableGate())
return nil
})
for _, name := range []string{"Corrupt Manifest", "Dolt Format", "Database Integrity", "Dolt Schema"} {
if !strings.Contains(out, name+": ") {
t.Errorf("recovery fix %q was not offered on an unreachable gate:\n%s", name, out)
}
}
for _, name := range []string{"Schema Compatibility", "Pending Migrations"} {
if strings.Contains(out, name+": ") {
t.Errorf("schema-writing fix %q was offered on an unreachable gate:\n%s", name, out)
}
if !strings.Contains(out, "· "+name) {
t.Errorf("schema-writing fix %q was not reported as skipped:\n%s", name, out)
}
}
}
// TestApplyFixesWithholdsRecoveryFixesWhenDatabaseReachableButBlocked is the
// other edge of the same rule: the exception exists because an unreachable
// database has no readable schema to skew. A reachable database that is ahead
// of the binary still gets backup+reinit withheld.
func TestApplyFixesWithholdsRecoveryFixesWhenDatabaseReachableButBlocked(t *testing.T) {
withNullStdin(t)
out := captureStdout(t, func() error {
applyFixes(resultWithRecoveryAndSchemaFixes(), blockedGate())
return nil
})
if !strings.Contains(out, "No fixable issues found") {
t.Fatalf("expected every fix withheld on a reachable, skewed gate, got:\n%s", out)
}
if strings.Contains(out, "Corrupt Manifest: ") {
t.Fatalf("recovery fix offered while the database is reachable and ahead:\n%s", out)
}
}
// TestPreviewFixesLabelsOnlySchemaWritingFixesBlockedOnUnreachableGate is the
// dry-run half of the recovery rule.
func TestPreviewFixesLabelsOnlySchemaWritingFixesBlockedOnUnreachableGate(t *testing.T) {
out := captureStdout(t, func() error {
previewFixes(resultWithRecoveryAndSchemaFixes(), unreachableGate())
return nil
})
if got := strings.Count(out, "Blocked by the schema gate"); got != 2 {
t.Fatalf("expected exactly the 2 schema-writing fixes labelled blocked, got %d:\n%s", got, out)
}
if !strings.Contains(out, "Would apply 4 fix(es); 2 fix(es) are blocked by the schema gate") {
t.Fatalf("unexpected dry-run summary:\n%s", out)
}
}
// TestPreviewFixesFlagsDBFixAsBlockedOnUnreachableGate is the dry-run half of
// the same regression: blockDB used `!gate.AllowDBFix && gate.Reason != ""`,
// which is false (not blocked) for the same unreachable shape, so a dry run
// never warned that the fix would actually be withheld.
func TestPreviewFixesFlagsDBFixAsBlockedOnUnreachableGate(t *testing.T) {
gate := unreachableGate()
result := resultWithDBFix()
out := captureStdout(t, func() error {
previewFixes(result, gate)
return nil
})
if !strings.Contains(out, "Blocked by the schema gate") {
t.Fatalf("previewFixes did not flag the database fix as blocked on an unreachable gate:\n%s", out)
}
if !strings.Contains(out, "blocked by the schema gate") {
t.Fatalf("expected the dry-run summary to report the fix(es) as blocked, got:\n%s", out)
}
}
// TestCollectFixableIssuesPartitionsByBlastRadius pins the split that lets a
// schema gate withhold schema writes without also refusing to repair a file
// mode — the "no hatch for filesystem-only fixes" complaint.
func TestCollectFixableIssuesPartitionsByBlastRadius(t *testing.T) {
result := doctorResult{
Checks: []doctorCheck{
{Name: "Gitignore", Status: statusWarning, Fix: "add entries"},
{Name: "Permissions", Status: statusError, Fix: "chmod"},
{Name: "Schema Compatibility", Status: statusError, Fix: "migrate"},
{Name: "Database", Status: statusWarning, Fix: "repair"},
{Name: "Healthy Thing", Status: statusOK, Fix: "should be ignored"},
{Name: "No Fix Available", Status: statusError},
},
}
dbFixes, fsFixes := collectFixableIssues(result)
if len(fsFixes) != 2 {
t.Errorf("expected 2 filesystem fixes, got %d: %+v", len(fsFixes), fsFixes)
}
if len(dbFixes) != 2 {
t.Errorf("expected 2 database fixes, got %d: %+v", len(dbFixes), dbFixes)
}
for _, f := range fsFixes {
if !doctor.IsFilesystemOnlyFix(f.Name) {
t.Errorf("%q was partitioned as filesystem-only but is not", f.Name)
}
}
}