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.
This commit is contained in:
Jacob Hausler 2026-08-23 17:44:19 -05:00 • committed by GitHub
commit 8d86c06bf2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 204 additions and 4 deletions

View file

@ -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

View file

@ -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 {

View file

@ -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 {

View file

@ -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)
}
}

View file

@ -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)
}
}