From 8d86c06bf231cbc0907436a111fb7b75d39ee12d Mon Sep 17 00:00:00 2001 From: Jacob Hausler Date: Sun, 23 Aug 2026 17:44:19 -0500 Subject: [PATCH] fix(dep): warn on stderr when dep add uses the implicit type=blocks default (#5854) Merged per the MERGE-ON-GREEN verdict (issuecomment-5384481169): TTY-gated stderr warning on implicit type=blocks default, honoring --quiet and BD_NO_DEP_TYPE_WARNING. Head CI fully green after the misspell fix-push (4fe7c45d8) and a rerun past the known #5962 storage testcontainer flake. --- CHANGELOG.md | 12 +++++ cmd/bd/dep.go | 80 +++++++++++++++++++++++++-- cmd/bd/dep_proxied_server.go | 12 +++++ cmd/bd/dep_warning_test.go | 83 +++++++++++++++++++++++++++++ cmd/bd/update_notes_warning_test.go | 21 ++++++++ 5 files changed, 204 insertions(+), 4 deletions(-) create mode 100644 cmd/bd/dep_warning_test.go create mode 100644 cmd/bd/update_notes_warning_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 87b5bf384..9bfa8c421 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -53,6 +53,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- **`bd dep add` names the implicit `type=blocks` default, but only to an + interactive operator** (#5854). Creating an edge with no `-t/--type` silently + produces a `blocks` edge, which drops the dependent out of `bd ready` — the + usual surprise when someone meant structural parent/child linkage. `bd dep + add` now says so on stderr. Because `blocks` is the documented default and + the majority-correct case, the note is gated: it is emitted only when stderr + is a TTY, so scripted and agent callers (and CI, and `bd dep add 2>log`) + never see it and are not trained to ignore stderr. `--quiet` silences it, as + it does the other non-error stderr notices, and `BD_NO_DEP_TYPE_WARNING=1` + turns it off for operators who have internalised the default. `--json` output + is unchanged. + - **`bd show` labels `created_by` as `Created by:`, not `Owner:`** (be-ss66). The text view rendered `created_by` under a label naming a different concept. `owner` is a separate field holding a separate value — the git diff --git a/cmd/bd/dep.go b/cmd/bd/dep.go index 955397f2b..e28136ab4 100644 --- a/cmd/bd/dep.go +++ b/cmd/bd/dep.go @@ -275,6 +275,11 @@ External references are stored as-is and resolved at query time using the external_projects config. They block the issue until the capability is "shipped" in the target project. +With no -t/--type the edge is created as type=blocks, which excludes the +dependent from bd ready. When stderr is an interactive terminal, an advisory +note says so once per command; it is silent for scripted and agent callers +(non-TTY stderr) and can be turned off with --quiet or BD_NO_DEP_TYPE_WARNING=1. + Examples: bd dep add bd-42 bd-41 # Positional args bd dep add bd-42 --blocked-by bd-41 # Flag syntax (same effect) @@ -419,6 +424,9 @@ Examples: return HandleErrorRespectJSON("failed to commit: %v", err) } + explicit := cmd.Flags().Changed("type") || cmd.Flags().Changed("blocked-by") || cmd.Flags().Changed("depends-on") + warnImplicitBlocksDefault(dt, explicit) + if jsonOutput { return outputJSON(map[string]interface{}{ "status": "added", @@ -434,6 +442,55 @@ Examples: }, } +// warnImplicitBlocksDefault is the D1 guard: when a dep add edge is created +// with the implicit type=blocks default it warns on stderr. A silent blocks +// edge drops the dependent from bd ready, which is not what an operator +// usually means when wiring a structural parent/child link. An explicit +// choice never warns: -t (including an explicit -t blocks), and the +// --blocked-by/--depends-on aliases, whose names already express the +// blocking relationship. Non-blocks defaults do not warn either. +// +// The warning is advisory and fires on the documented-default majority path, +// so it is scoped to an interactive operator: it is emitted only when stderr +// is a TTY, and it honors the global --quiet flag and BD_NO_DEP_TYPE_WARNING. +// Scripted and agent callers — whose stderr is a pipe or a log file — never +// see it, so it cannot train them to ignore stderr. +func warnImplicitBlocksDefault(dt types.DependencyType, explicit bool) { + if !shouldWarnImplicitBlocksDefault(dt, explicit, quietFlag, os.Getenv("BD_NO_DEP_TYPE_WARNING"), ui.IsStderrTerminal()) { + return + } + emitImplicitBlocksDefaultWarning() +} + +// shouldWarnImplicitBlocksDefault is the testable predicate behind +// warnImplicitBlocksDefault. It takes the quiet flag, the suppression env +// value and the stderr TTY result as parameters so tests can cover every +// combination without a real terminal — the same shape as +// ui.shouldUseHyperlinks. +func shouldWarnImplicitBlocksDefault(dt types.DependencyType, explicit, quiet bool, noWarnEnv string, stderrIsTerminal bool) bool { + if explicit || dt != types.DepBlocks { + return false + } + // --quiet is documented as "Suppress non-essential output (errors only)", + // and the other non-error stderr notices in this package (tips.go, + // metrics.go, routing_read.go) respect it the same way. + if quiet { + return false + } + // Explicit opt-out for operators who have internalized the default, + // following the BD_NO_EMOJI / BD_NO_COLOR precedent. + if noWarnEnv != "" { + return false + } + return stderrIsTerminal +} + +// emitImplicitBlocksDefaultWarning writes the D1 warning. Split from the gate +// so the message text can be asserted under a captured (non-TTY) stderr. +func emitImplicitBlocksDefaultWarning() { + fmt.Fprintf(os.Stderr, "warning: no -t/--type given; edge created as type=blocks — the dependent is excluded from bd ready until the edge resolves. Use -t parent-child for structural parent/child linkage (silence with --quiet or BD_NO_DEP_TYPE_WARNING=1)\n") //nolint:gosec // G705: stderr, not a browser context +} + type bulkDepInput struct { From string `json:"from"` To string `json:"to"` @@ -447,9 +504,13 @@ type bulkDepEdge struct { IssueID string DependsOnID string Type types.DependencyType - Store storage.DoltStorage - StoreKey string - Cleanups []func() + // Defaulted is true when the line carried no "type" and fell back to + // the command-line default (D1 guard: the implicit default is what the + // stderr warning targets; explicit per-line types are the user's choice). + Defaulted bool + Store storage.DoltStorage + StoreKey string + Cleanups []func() } func addBulkDependencies(cmd *cobra.Command, file string, defaultType string) error { @@ -510,6 +571,15 @@ func addBulkDependencies(cmd *cobra.Command, file string, defaultType string) er warnIfCyclesExist(targetStore) } + if !cmd.Flags().Changed("type") { + for _, edge := range resolved { + if edge.Defaulted && edge.Type == types.DepBlocks { + warnImplicitBlocksDefault(edge.Type, false) + break + } + } + } + if jsonOutput { out := make([]map[string]interface{}, 0, len(resolved)) for _, edge := range resolved { @@ -572,7 +642,8 @@ func readBulkDepEdges(file string, defaultType string) ([]bulkDepEdge, error) { to = strings.TrimSpace(in.DependsOnID) } depType := strings.TrimSpace(in.Type) - if depType == "" { + defaulted := depType == "" + if defaulted { depType = defaultType } @@ -596,6 +667,7 @@ func readBulkDepEdges(file string, defaultType string) ([]bulkDepEdge, error) { IssueID: from, DependsOnID: to, Type: dt, + Defaulted: defaulted, }) } if err := scanner.Err(); err != nil { diff --git a/cmd/bd/dep_proxied_server.go b/cmd/bd/dep_proxied_server.go index a52cc4468..bd7b39440 100644 --- a/cmd/bd/dep_proxied_server.go +++ b/cmd/bd/dep_proxied_server.go @@ -244,6 +244,9 @@ func runDepAddProxiedServer(cmd *cobra.Command, ctx context.Context, args []stri printCycleDetectionError(res.cycleErr) printCycleWarnings(res.cycles) + explicit := cmd.Flags().Changed("type") || cmd.Flags().Changed("blocked-by") || cmd.Flags().Changed("depends-on") + warnImplicitBlocksDefault(dt, explicit) + if jsonOutput { _ = outputJSON(map[string]interface{}{ "status": "added", @@ -299,6 +302,15 @@ func runDepAddBulkProxied(cmd *cobra.Command, ctx context.Context, file, default printCycleDetectionError(res.cycleErr) printCycleWarnings(res.cycles) + if !cmd.Flags().Changed("type") { + for _, edge := range edges { + if edge.Defaulted && edge.Type == types.DepBlocks { + warnImplicitBlocksDefault(edge.Type, false) + break + } + } + } + if jsonOutput { out := make([]map[string]interface{}, 0, len(depEdges)) for _, edge := range depEdges { diff --git a/cmd/bd/dep_warning_test.go b/cmd/bd/dep_warning_test.go new file mode 100644 index 000000000..abe83eadb --- /dev/null +++ b/cmd/bd/dep_warning_test.go @@ -0,0 +1,83 @@ +package main + +import ( + "strings" + "testing" + + "github.com/steveyegge/beads/internal/types" +) + +// TestShouldWarnImplicitBlocksDefault is the D1 guard test: a dep add edge +// created with the implicit type=blocks default must warn on stderr that the +// edge is type=blocks and that structural parent/child linkage requires -t +// parent-child, so children don't silently drop from bd ready. At the command +// layer, explicit is true when the user passed -t (any value, including +// blocks) or the --blocked-by/--depends-on aliases. +// +// The warning fires on the documented-default majority path, so it is scoped +// to an interactive operator: a non-TTY stderr (scripted and agent callers, +// CI, `bd dep add 2>log`), --quiet, and BD_NO_DEP_TYPE_WARNING each suppress +// it. Those three cases are the anti-inversion controls — without them the +// warning would train operators and agents to ignore stderr on the correct +// path. +func TestShouldWarnImplicitBlocksDefault(t *testing.T) { + tests := []struct { + name string + dt types.DependencyType + explicit bool + quiet bool + noWarnEnv string + stderrIsTerminal bool + want bool + }{ + {name: "implicit blocks default on a TTY warns", dt: types.DepBlocks, stderrIsTerminal: true, want: true}, + {name: "explicit blocks (-t or --blocked-by/--depends-on) does not warn", dt: types.DepBlocks, explicit: true, stderrIsTerminal: true, want: false}, + {name: "parent-child default does not warn", dt: types.DepParentChild, stderrIsTerminal: true, want: false}, + {name: "tracks default does not warn", dt: types.DepTracks, stderrIsTerminal: true, want: false}, + {name: "non-TTY stderr does not warn (scripted and agent callers)", dt: types.DepBlocks, stderrIsTerminal: false, want: false}, + {name: "--quiet does not warn", dt: types.DepBlocks, quiet: true, stderrIsTerminal: true, want: false}, + {name: "BD_NO_DEP_TYPE_WARNING does not warn", dt: types.DepBlocks, noWarnEnv: "1", stderrIsTerminal: true, want: false}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := shouldWarnImplicitBlocksDefault(tt.dt, tt.explicit, tt.quiet, tt.noWarnEnv, tt.stderrIsTerminal) + if got != tt.want { + t.Errorf("shouldWarnImplicitBlocksDefault(%v, explicit=%v, quiet=%v, env=%q, tty=%v) = %v, want %v", + tt.dt, tt.explicit, tt.quiet, tt.noWarnEnv, tt.stderrIsTerminal, got, tt.want) + } + }) + } +} + +// TestEmitImplicitBlocksDefaultWarning locks the message content. It calls the +// emitter directly because captureStderr replaces stderr with a pipe, which is +// exactly the non-TTY case the gate above suppresses. +func TestEmitImplicitBlocksDefaultWarning(t *testing.T) { + got := captureStderr(t, emitImplicitBlocksDefaultWarning) + + if !strings.Contains(got, "type=blocks") { + t.Errorf("warning must state the edge is type=blocks, got %q", got) + } + if !strings.Contains(got, "-t parent-child") { + t.Errorf("warning must name -t parent-child for structural linkage, got %q", got) + } + if !strings.Contains(got, "bd ready") { + t.Errorf("warning must explain the bd ready impact, got %q", got) + } + if !strings.Contains(got, "--quiet") || !strings.Contains(got, "BD_NO_DEP_TYPE_WARNING") { + t.Errorf("warning must name both suppression knobs, got %q", got) + } +} + +// TestWarnImplicitBlocksDefaultStaysSilentUnderCapturedStderr is the +// end-to-end control: the command-layer entry point must print nothing when +// stderr is not a terminal, which is every scripted and agent invocation. +func TestWarnImplicitBlocksDefaultStaysSilentUnderCapturedStderr(t *testing.T) { + got := captureStderr(t, func() { + warnImplicitBlocksDefault(types.DepBlocks, false) + }) + if got != "" { + t.Errorf("expected no warning when stderr is not a terminal, got %q", got) + } +} diff --git a/cmd/bd/update_notes_warning_test.go b/cmd/bd/update_notes_warning_test.go new file mode 100644 index 000000000..5d34449a8 --- /dev/null +++ b/cmd/bd/update_notes_warning_test.go @@ -0,0 +1,21 @@ +package main + +import ( + "testing" +) + +// TestWarnNotesReplacement is the D2 guard test: a `bd update --notes` that +// replaces a non-empty notes field warns on stderr, naming --append-notes as +// the history-preserving alternative (the warning itself shipped on main via +// #4743). The predicate deciding WHEN the warning fires is covered by +// TestReplacesExistingNotes. +func TestWarnNotesReplacement(t *testing.T) { + got := captureStderr(t, func() { + warnNotesReplacement("tc-dg6") + }) + + want := "warning: tc-dg6: --notes replaced existing notes (use --append-notes to preserve history)\n" + if got != want { + t.Fatalf("warnNotesReplacement stderr = %q, want %q", got, want) + } +}