beads/cmd/bd/doctor_conventions.go
Julian Knutsen 0c5fa422d8
feat(cli): opt out of store init via bd:skip_store annotation (#5060)
Commands that don't need the database (version, doctor, completions, ...)
skip store initialization in PersistentPreRunE. Today that exemption is the
central noDbCommands []string in cmd/bd/main.go — a command defined in
another file, or a build-tagged variant, cannot add itself without editing
that shared list, which is a recurring merge-conflict point for downstream
forks and plugins.

Add a cobra-annotation seam: a command (or any ancestor) carrying
Annotations{"bd:skip_store":"1"} is treated as no-store, via the new
commandOptsOutOfStore helper OR-d into the existing store-skip gate. This is
a no-op for OSS today (no command sets it) and lets out-of-tree or
build-tagged commands opt out locally, where they are defined.

Dogfood it on doctor: doctor now opts out via the annotation on its Command
literal instead of a noDbCommands entry, so the seam has a live in-tree
consumer already exercised by the existing doctor PersistentPreRunE tests.

Tests: pure-helper coverage (self / parent / grandparent / nil-safe) plus a
self-validating end-to-end gate test — a non-annotated control command proves
the environment does open a store when a command is not skipped, so the
annotated command's clean return is a real signal, not incidental.

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-26 06:13:54 -07:00

227 lines
6.1 KiB
Go

package main
import (
"fmt"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/validation"
)
// runConventionsCheck runs a composite conventions check: lint, stale, and orphans.
// All findings are advisory (warning, never error) - conventions are a choice.
func runConventionsCheck(path string) error {
// doctor opts out of PersistentPreRun DB init via skipStoreAnnotation, so
// PersistentPreRun doesn't open the store.
// The lint/stale/orphans primitives all require the global store, so
// initialize it lazily here; ensureDirectMode routes to embedded or
// server based on metadata.json (GH#3597).
if err := ensureDirectMode("conventions check requires direct mode"); err != nil {
return HandleError("%v", err)
}
var checks []doctorCheck
lintChecks, err := runConventionsLint()
if err != nil {
return err
}
checks = append(checks, lintChecks...)
checks = append(checks, runConventionsStale()...)
checks = append(checks, runConventionsOrphans(path)...)
if jsonOutput {
overallOK := true
for _, c := range checks {
if c.Status != statusOK {
overallOK = false
break
}
}
return outputJSON(struct {
Path string `json:"path"`
Checks []doctorCheck `json:"checks"`
OverallOK bool `json:"overall_ok"`
}{
Path: path,
Checks: checks,
OverallOK: overallOK,
})
}
// Human-readable output
fmt.Println()
fmt.Println(ui.RenderCategory("Conventions"))
var passCount, warnCount int
for _, c := range checks {
var statusIcon string
switch c.Status {
case statusOK:
statusIcon = ui.RenderPassIcon()
passCount++
case statusWarning:
statusIcon = ui.RenderWarnIcon()
warnCount++
}
fmt.Printf(" %s %s", statusIcon, c.Name)
if c.Message != "" {
fmt.Printf("%s", ui.RenderMuted(" "+c.Message))
}
fmt.Println()
if c.Detail != "" {
fmt.Printf(" %s%s\n", ui.MutedStyle.Render(ui.TreeLast), ui.RenderMuted(c.Detail))
}
if c.Fix != "" {
fmt.Printf(" %s\n", ui.RenderMuted("Fix: "+c.Fix))
}
}
fmt.Println()
fmt.Println(ui.RenderSeparator())
fmt.Printf("%s %d passed %s %d warnings\n",
ui.RenderPassIcon(), passCount,
ui.RenderWarnIcon(), warnCount,
)
if warnCount == 0 {
fmt.Println()
fmt.Printf("%s\n", ui.RenderPass("✓ All convention checks passed"))
}
return nil
}
// runConventionsLint checks open issues for missing template sections.
// runConventionsLint's doctorCheck results are advisory (per the composite
// comment above), but a MaxRows cap violation is a different kind of
// failure — an infrastructure circuit breaker, not a data-quality finding —
// so it returns a non-nil error instead of a doctorCheck in that one case.
// The caller must propagate it rather than folding it into the checks list.
func runConventionsLint() ([]doctorCheck, error) {
if store == nil {
return []doctorCheck{{
Name: "conventions.lint",
Status: statusWarning,
Message: "database not available",
Category: "Conventions",
}}, nil
}
ctx := rootCtx
openStatus := types.StatusOpen
// Env-only cap (designer §4): operator opt-in via BEADS_MAX_ROWS.
maxRows, maxRowsSource := resolveMaxRowsEnvOnly()
issues, err := store.SearchIssues(ctx, "", types.IssueFilter{
Status: &openStatus,
MaxRows: maxRows,
MaxRowsSource: maxRowsSource,
})
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return nil, capErr
}
return []doctorCheck{{
Name: "conventions.lint",
Status: statusWarning,
Message: fmt.Sprintf("error reading issues: %v", err),
Category: "Conventions",
}}, nil
}
warningCount := 0
for _, issue := range issues {
if err := validation.LintIssue(issue); err != nil {
warningCount++
}
}
if warningCount == 0 {
return []doctorCheck{{
Name: "conventions.lint",
Status: statusOK,
Message: fmt.Sprintf("all %d open issues pass template checks", len(issues)),
Category: "Conventions",
}}, nil
}
return []doctorCheck{{
Name: "conventions.lint",
Status: statusWarning,
Message: fmt.Sprintf("%d of %d open issues missing recommended sections", warningCount, len(issues)),
Fix: "bd lint",
Category: "Conventions",
}}, nil
}
// runConventionsStale checks for issues with no recent activity.
func runConventionsStale() []doctorCheck {
if store == nil {
return []doctorCheck{{
Name: "conventions.stale",
Status: statusWarning,
Message: "database not available",
Category: "Conventions",
}}
}
ctx := rootCtx
filter := types.StaleFilter{Days: 14, Limit: 100}
staleIssues, err := store.GetStaleIssues(ctx, filter)
if err != nil {
return []doctorCheck{{
Name: "conventions.stale",
Status: statusWarning,
Message: fmt.Sprintf("error checking stale issues: %v", err),
Category: "Conventions",
}}
}
if len(staleIssues) == 0 {
return []doctorCheck{{
Name: "conventions.stale",
Status: statusOK,
Message: "no issues inactive for 14+ days",
Category: "Conventions",
}}
}
return []doctorCheck{{
Name: "conventions.stale",
Status: statusWarning,
Message: fmt.Sprintf("%d issues inactive for 14+ days", len(staleIssues)),
Fix: "bd stale",
Category: "Conventions",
}}
}
// runConventionsOrphans checks for issues referenced in commits but still open.
func runConventionsOrphans(path string) []doctorCheck {
orphans, err := findOrphanedIssues(path, nil, nil)
if err != nil {
// Not an error - orphan detection may fail in non-git repos
return []doctorCheck{{
Name: "conventions.orphans",
Status: statusOK,
Message: "orphan check skipped (no git history)",
Category: "Conventions",
}}
}
if len(orphans) == 0 {
return []doctorCheck{{
Name: "conventions.orphans",
Status: statusOK,
Message: "no orphaned issues found",
Category: "Conventions",
}}
}
return []doctorCheck{{
Name: "conventions.orphans",
Status: statusWarning,
Message: fmt.Sprintf("%d issues referenced in commits but still open", len(orphans)),
Fix: "bd orphans",
Category: "Conventions",
}}
}