beads/cmd/bd/preflight.go
matt wilkie 8694c53589
doctor: detect AGENTS.md / CLAUDE.md user-authored divergence (#3600)
* doctor: detect AGENTS.md / CLAUDE.md user-authored divergence

Adds CheckAgentDocDivergence to bd doctor and bd preflight. The check
flags cases where AGENTS.md and CLAUDE.md exist as independent regular
files whose content outside the BEGIN/END BEADS INTEGRATION markers has
drifted apart — a common drift mode when agents hand-edit one of the
pair without mirroring the change.

Skipped when:
  - Either file is missing
  - The pair is symlinked or shares an inode (hardlink)
  - Normalized user-authored content matches
  - Either file contains the opt-out marker
    <!-- bd-doctor-divergence: ok --> (for projects that intentionally
    keep distinct files for different audiences, like beads itself)

Adds the opt-out marker to AGENTS.md so the upstream beads repo, whose
AGENTS.md and CLAUDE.md serve intentionally different audiences, does
not regress its own preflight.

Closes mybd-31m.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(lint): hyphenate hardlinked to satisfy misspell linter

misspell flags 'hardlinked' as a typo for 'hardline'. Hyphenating to
'hard-linked' is a common alternate spelling and sidesteps the false
positive without changing meaning.

---------

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

559 lines
15 KiB
Go

package main
import (
"encoding/json"
"fmt"
"os"
"os/exec"
"path/filepath"
"regexp"
"strings"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/cmd/bd/doctor"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/git"
)
// CheckResult represents the result of a single preflight check.
type CheckResult struct {
Name string `json:"name"`
Passed bool `json:"passed"`
Skipped bool `json:"skipped,omitempty"`
Warning bool `json:"warning,omitempty"`
Output string `json:"output,omitempty"`
Command string `json:"command"`
}
// PreflightResult represents the overall preflight check results.
type PreflightResult struct {
Checks []CheckResult `json:"checks"`
Passed bool `json:"passed"`
Summary string `json:"summary"`
}
var preflightCmd = &cobra.Command{
Use: "preflight",
GroupID: "maint",
Short: "Show PR readiness checklist",
Long: `Display a checklist of common pre-PR checks for contributors.
This command helps catch common issues before pushing to CI:
- Tests not run locally
- Lint errors
- Unformatted Go files
- .beads/issues.jsonl pollution
- Stale nix vendorHash
- Version mismatches
Examples:
bd preflight # Show checklist
bd preflight --check # Run checks automatically
bd preflight --check --json # JSON output for programmatic use
bd preflight --check --skip-lint # Explicitly skip lint check
`,
Run: runPreflight,
}
func init() {
preflightCmd.Flags().Bool("check", false, "Run checks automatically")
preflightCmd.Flags().Bool("fix", false, "Auto-fix issues where possible (not yet implemented)")
preflightCmd.Flags().Bool("json", false, "Output results as JSON")
preflightCmd.Flags().Bool("skip-lint", false, "Skip lint check explicitly")
rootCmd.AddCommand(preflightCmd)
}
func runPreflight(cmd *cobra.Command, args []string) {
check, _ := cmd.Flags().GetBool("check")
fix, _ := cmd.Flags().GetBool("fix")
jsonOutput, _ := cmd.Flags().GetBool("json")
skipLint, _ := cmd.Flags().GetBool("skip-lint")
if fix {
fmt.Println("Note: --fix is not yet implemented.")
fmt.Println("See bd-lfak.3 through bd-lfak.5 for implementation roadmap.")
fmt.Println()
}
if check {
runChecks(jsonOutput, skipLint)
return
}
// Static checklist mode
fmt.Println("PR Readiness Checklist:")
fmt.Println()
fmt.Println("[ ] Tests pass: go test -tags gms_pure_go -short ./...")
fmt.Println("[ ] Lint passes: golangci-lint run --build-tags=gms_pure_go ./...")
fmt.Println("[ ] Formatting: gofmt -l .")
fmt.Println("[ ] No beads pollution: check .beads/issues.jsonl diff")
fmt.Println("[ ] Nix hash current: go.sum unchanged or vendorHash updated")
fmt.Println("[ ] Version sync: version.go matches default.nix")
fmt.Println()
fmt.Println("Run 'bd preflight --check' to validate automatically.")
}
// runChecks executes all preflight checks and reports results.
func runChecks(jsonOutput, skipLint bool) {
var results []CheckResult
// Run test check
testResult := runTestCheck()
results = append(results, testResult)
// Run lint check
lintResult := runLintCheck(skipLint)
results = append(results, lintResult)
// Run formatting check
fmtResult := runFmtCheck()
results = append(results, fmtResult)
// Run beads pollution check
beadsResult := runBeadsPollutionCheck()
results = append(results, beadsResult)
// Run nix hash check
nixResult := runNixHashCheck()
results = append(results, nixResult)
// Run version sync check
versionResult := runVersionSyncCheck()
results = append(results, versionResult)
// Run AGENTS.md / CLAUDE.md divergence check
divergenceResult := runAgentDocDivergenceCheck()
results = append(results, divergenceResult)
// Calculate overall result
allPassed := true
passCount := 0
skipCount := 0
warnCount := 0
for _, r := range results {
if r.Skipped {
skipCount++
} else if r.Warning {
warnCount++
// Warnings don't fail the overall result but count as "not passed"
} else if r.Passed {
passCount++
} else {
allPassed = false
}
}
runCount := len(results) - skipCount
summary := fmt.Sprintf("%d/%d checks passed", passCount, runCount)
if warnCount > 0 {
summary += fmt.Sprintf(", %d warning(s)", warnCount)
}
if skipCount > 0 {
summary += fmt.Sprintf(" (%d skipped)", skipCount)
}
if jsonOutput {
result := PreflightResult{
Checks: results,
Passed: allPassed,
Summary: summary,
}
enc := json.NewEncoder(os.Stdout)
enc.SetIndent("", " ")
if err := enc.Encode(result); err != nil {
fmt.Fprintf(os.Stderr, "Error encoding preflight result: %v\n", err)
}
} else {
// Human-readable output
for _, r := range results {
if r.Skipped {
fmt.Printf("⚠ %s (skipped)\n", r.Name)
} else if r.Warning {
fmt.Printf("⚠ %s\n", r.Name)
} else if r.Passed {
fmt.Printf("✓ %s\n", r.Name)
} else {
fmt.Printf("✗ %s\n", r.Name)
}
fmt.Printf(" Command: %s\n", r.Command)
if r.Skipped && r.Output != "" {
// Show skip reason
fmt.Printf(" Reason: %s\n", r.Output)
} else if r.Warning && r.Output != "" {
// Show warning message
fmt.Printf(" Warning: %s\n", r.Output)
} else if !r.Passed && r.Output != "" {
// Truncate output for terminal display
output := truncateOutput(r.Output, 500)
fmt.Printf(" Output:\n")
for _, line := range strings.Split(output, "\n") {
fmt.Printf(" %s\n", line)
}
}
fmt.Println()
}
fmt.Println(summary)
}
if !allPassed {
os.Exit(1)
}
}
// runTestCheck runs go test -short ./... and returns the result.
func runTestCheck() CheckResult {
command := "go test -tags gms_pure_go -short ./..."
cmd := exec.Command("go", "test", "-tags", "gms_pure_go", "-short", "./...")
output, err := cmd.CombinedOutput()
return CheckResult{
Name: "Tests pass",
Passed: err == nil,
Output: string(output),
Command: command,
}
}
// runLintCheck runs golangci-lint and returns the result.
func runLintCheck(skipLint bool) CheckResult {
command := "golangci-lint run --build-tags=gms_pure_go ./..."
if skipLint {
return CheckResult{
Name: "Lint passes",
Passed: false,
Skipped: true,
Warning: true,
Output: "lint check explicitly skipped by --skip-lint",
Command: command,
}
}
// Check if golangci-lint is available
if _, err := exec.LookPath("golangci-lint"); err != nil {
return CheckResult{
Name: "Lint passes",
Passed: false,
Output: "golangci-lint not found in PATH (install it or rerun with --skip-lint)",
Command: command,
}
}
cmd := exec.Command("golangci-lint", "run", "--build-tags=gms_pure_go", "./...")
output, err := cmd.CombinedOutput()
return CheckResult{
Name: "Lint passes",
Passed: err == nil,
Output: string(output),
Command: command,
}
}
// runFmtCheck runs gofmt -l and fails if any files need formatting.
func runFmtCheck() CheckResult {
command := "gofmt -l ."
// Check if gofmt is available
if _, err := exec.LookPath("gofmt"); err != nil {
return CheckResult{
Name: "Formatting",
Passed: false,
Output: "gofmt not found in PATH (install Go toolchain)",
Command: command,
}
}
cmd := exec.Command("gofmt", "-l", ".")
output, err := cmd.CombinedOutput()
if err != nil {
return CheckResult{
Name: "Formatting",
Passed: false,
Output: string(output),
Command: command,
}
}
unformatted := strings.TrimSpace(string(output))
if unformatted != "" {
return CheckResult{
Name: "Formatting",
Passed: false,
Output: fmt.Sprintf("Unformatted files:\n%s\nRun: gofmt -w .", unformatted),
Command: command,
}
}
return CheckResult{
Name: "Formatting",
Passed: true,
Command: command,
}
}
// runBeadsPollutionCheck detects .beads/issues.jsonl modifications vs merge base.
func runBeadsPollutionCheck() CheckResult {
command := "git diff -- .beads/issues.jsonl"
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return CheckResult{
Name: "No beads pollution",
Passed: true,
Command: command,
}
}
// git diff requires a path relative to the worktree root.
// If beadsDir points outside the worktree (shared .beads in a
// worktree setup), convert to a relative path. When the path is
// outside the worktree, the pollution check is skipped since git
// cannot diff paths outside the working tree.
issuesPath := filepath.Join(beadsDir, "issues.jsonl")
if filepath.IsAbs(issuesPath) {
repoRoot := git.GetRepoRoot()
if repoRoot == "" {
return CheckResult{
Name: "No beads pollution",
Passed: true,
Command: command,
}
}
rel, err := filepath.Rel(repoRoot, issuesPath)
if err != nil || isPathOutsideRepo(rel) {
return CheckResult{
Name: "No beads pollution",
Passed: true,
Command: command,
Output: "Skipped: .beads is outside working tree (worktree setup)",
}
}
issuesPath = rel
}
branchCmd := exec.Command("git", "rev-parse", "--abbrev-ref", "HEAD")
branchOut, err := branchCmd.Output()
if err != nil {
return CheckResult{
Name: "No beads pollution",
Passed: false,
Skipped: true,
Output: fmt.Sprintf("Cannot determine branch: %v", err),
Command: command,
}
}
branch := strings.TrimSpace(string(branchOut))
var diffOutput []byte
if branch != "main" && branch != "HEAD" {
cmd := exec.Command("git", "diff", "origin/main...HEAD", "--", issuesPath)
diffOutput, _ = cmd.Output()
} else {
cmd := exec.Command("git", "diff", "HEAD", "--", issuesPath)
out1, _ := cmd.Output()
cmd2 := exec.Command("git", "diff", "--cached", "--", issuesPath)
out2, _ := cmd2.Output()
diffOutput = append(out1, out2...)
}
if len(strings.TrimSpace(string(diffOutput))) > 0 {
return CheckResult{
Name: "No beads pollution",
Passed: false,
Output: ".beads/issues.jsonl has been modified — revert changes before pushing",
Command: command,
}
}
return CheckResult{
Name: "No beads pollution",
Passed: true,
Command: command,
}
}
// isPathOutsideRepo checks if a relative path (from filepath.Rel) points
// outside the base directory by inspecting the first path segment.
func isPathOutsideRepo(rel string) bool {
if rel == "" {
return false
}
first := rel
if i := strings.IndexAny(rel, "/\\"); i > 0 {
first = rel[:i]
}
return first == ".."
}
// runNixHashCheck checks if go.sum has uncommitted changes that may require vendorHash update.
func runNixHashCheck() CheckResult {
command := "git diff HEAD -- go.sum"
// Check for unstaged changes to go.sum
cmd := exec.Command("git", "diff", "--name-only", "HEAD", "--", "go.sum")
output, _ := cmd.Output()
// Check for staged changes to go.sum
stagedCmd := exec.Command("git", "diff", "--name-only", "--cached", "--", "go.sum")
stagedOutput, _ := stagedCmd.Output()
hasChanges := len(strings.TrimSpace(string(output))) > 0 || len(strings.TrimSpace(string(stagedOutput))) > 0
if hasChanges {
return CheckResult{
Name: "Nix hash current",
Passed: false,
Warning: true,
Output: "go.sum has uncommitted changes - vendorHash in default.nix may need updating",
Command: command,
}
}
return CheckResult{
Name: "Nix hash current",
Passed: true,
Output: "",
Command: command,
}
}
// runVersionSyncCheck checks that all version files are in sync.
// Prefers scripts/check-versions.sh (matches CI) with fallback to inline logic.
func runVersionSyncCheck() CheckResult {
command := "scripts/check-versions.sh"
// Try using the script (matches CI's check-version-consistency job)
if _, err := os.Stat("scripts/check-versions.sh"); err == nil {
cmd := exec.Command("bash", "scripts/check-versions.sh")
output, err := cmd.CombinedOutput()
if err != nil {
return CheckResult{
Name: "Version sync",
Passed: false,
Output: string(output),
Command: command,
}
}
return CheckResult{
Name: "Version sync",
Passed: true,
Output: string(output),
Command: command,
}
}
// Fallback: inline comparison of version.go and default.nix
command = "Compare cmd/bd/version.go and default.nix"
// Read version.go
versionGoContent, err := os.ReadFile("cmd/bd/version.go")
if err != nil {
return CheckResult{
Name: "Version sync",
Passed: false,
Skipped: true,
Output: fmt.Sprintf("Cannot read cmd/bd/version.go: %v", err),
Command: command,
}
}
// Extract version from version.go
versionGoRe := regexp.MustCompile(`Version\s*=\s*"([^"]+)"`)
versionGoMatch := versionGoRe.FindSubmatch(versionGoContent)
if versionGoMatch == nil {
return CheckResult{
Name: "Version sync",
Passed: false,
Skipped: true,
Output: "Cannot parse version from version.go",
Command: command,
}
}
goVersion := string(versionGoMatch[1])
// Read default.nix
nixContent, err := os.ReadFile("default.nix")
if err != nil {
return CheckResult{
Name: "Version sync",
Passed: true,
Skipped: true,
Output: "default.nix not found (skipping nix version check)",
Command: command,
}
}
// Extract version from default.nix
nixRe := regexp.MustCompile(`version\s*=\s*"([^"]+)"`)
nixMatch := nixRe.FindSubmatch(nixContent)
if nixMatch == nil {
return CheckResult{
Name: "Version sync",
Passed: false,
Skipped: true,
Output: "Cannot parse version from default.nix",
Command: command,
}
}
nixVersion := string(nixMatch[1])
if goVersion != nixVersion {
return CheckResult{
Name: "Version sync",
Passed: false,
Output: fmt.Sprintf("Version mismatch: version.go=%s, default.nix=%s", goVersion, nixVersion),
Command: command,
}
}
return CheckResult{
Name: "Version sync",
Passed: true,
Output: fmt.Sprintf("Versions match: %s", goVersion),
Command: command,
}
}
// runAgentDocDivergenceCheck flags drift between AGENTS.md and CLAUDE.md
// user-authored regions so the inconsistency is caught pre-PR rather than in
// review.
func runAgentDocDivergenceCheck() CheckResult {
command := "bd doctor (Agent Doc Divergence)"
repoRoot := git.GetRepoRoot()
if repoRoot == "" {
repoRoot = "."
}
check := doctor.CheckAgentDocDivergence(repoRoot)
if check.Status == doctor.StatusOK {
return CheckResult{
Name: "AGENTS.md/CLAUDE.md in sync",
Passed: true,
Command: command,
}
}
output := check.Message
if check.Detail != "" {
output += "\n" + check.Detail
}
if check.Fix != "" {
output += "\n" + check.Fix
}
return CheckResult{
Name: "AGENTS.md/CLAUDE.md in sync",
Passed: false,
Warning: true,
Output: output,
Command: command,
}
}
// truncateOutput truncates output to maxLen characters, adding ellipsis if truncated.
func truncateOutput(s string, maxLen int) string {
if len(s) <= maxLen {
return strings.TrimSpace(s)
}
return strings.TrimSpace(s[:maxLen]) + "\n... (truncated)"
}