From 67b066b58e1fa9bff3ea4ec8eeb6ec28d0e35c9f Mon Sep 17 00:00:00 2001 From: Vishnu J Date: Wed, 2 Sep 2026 18:11:56 -0700 Subject: [PATCH] fix(create): say --file is one issue per ## heading (#5921) bd create --file/-f is a batch-import route: it creates one issue per H2 ("##") heading, and ### subsections attach fields to that issue. The old Usage was "Create multiple issues from markdown file", which never named those semantics or --body-file. Callers who wanted "one issue, description loaded from a file" reached for the shortest flag and got a silent bulk import instead -- reported by @seanmartinsmith with a 3-section briefing file (## Problem / ## Context / ## Acceptance Criteria) that became 3 issues instead of one. gatherCreateInput already rejects a positional title combined with --file. That is the reporter's literal repro, so this keeps the rejection and adds a --body-file hint on the error they actually see. The remaining trap -- --file used alone on a section-headed file -- is unchanged, because bd cannot tell that apart from a genuine batch file by content. Tests: parseMarkdownFile reproduces the trap file; gatherCreateInput locks in the title+--file rejection and --body-file hint; flag Usage names the per-heading behavior. The existing TestCreateFromMarkdownFile binary path already covers well-formed --file creates. --- cmd/bd/create.go | 2 +- cmd/bd/create_dispatch_test.go | 43 ++++++++++++++++++++++++++++++++++ cmd/bd/create_input.go | 2 +- cmd/bd/create_input_test.go | 30 ++++++++++++++++++++++++ cmd/bd/markdown_test.go | 32 +++++++++++++++++++++++++ 5 files changed, 107 insertions(+), 2 deletions(-) diff --git a/cmd/bd/create.go b/cmd/bd/create.go index f18870665..09ad2db99 100644 --- a/cmd/bd/create.go +++ b/cmd/bd/create.go @@ -895,7 +895,7 @@ func createDepsAcceptedTypeList() string { } func init() { - createCmd.Flags().StringP("file", "f", "", "Create multiple issues from markdown file") + createCmd.Flags().StringP("file", "f", "", "Create one issue per ## heading (### fields attach to that issue); for title plus description-from-file, use --body-file") createCmd.Flags().String("graph", "", "Create a graph of issues with dependencies from JSON plan file") createCmd.Flags().String("title", "", "Issue title (alternative to positional argument)") createCmd.Flags().Bool("silent", false, "Output only the issue ID (for scripting)") diff --git a/cmd/bd/create_dispatch_test.go b/cmd/bd/create_dispatch_test.go index 3f64487a2..0ee433a8a 100644 --- a/cmd/bd/create_dispatch_test.go +++ b/cmd/bd/create_dispatch_test.go @@ -171,3 +171,46 @@ func TestCreateSingleIssueAllowEmptyDescriptionRoundTrip(t *testing.T) { t.Fatalf("expected issue %q to be created via --allow-empty-description opt-in", title) } } + +// TestCreateFileDispatchRejectsPositionalTitle is a regression test for +// gastownhall/beads#4643: --file is a batch-import route, so a positional +// title has nowhere to go once createIssuesFromMarkdown takes over. This +// asserts gatherCreateInput's existing guard still rejects the combination +// before any issue is written, rather than silently discarding the title. +func TestCreateFileDispatchRejectsPositionalTitle(t *testing.T) { + saveAndRestoreGlobals(t) + ensureCleanGlobalState(t) + + readonlyMode = false + t.Cleanup(func() { readonlyMode = false }) + + fileFlag := createCmd.Flags().Lookup("file") + t.Cleanup(func() { + _ = fileFlag.Value.Set("") + fileFlag.Changed = false + }) + + tmpDir := t.TempDir() + mdPath := filepath.Join(tmpDir, "single.md") + if err := os.WriteFile(mdPath, []byte("## My Bead\n\nBody text.\n"), 0644); err != nil { + t.Fatalf("write markdown fixture: %v", err) + } + + if err := createCmd.Flags().Set("file", mdPath); err != nil { + t.Fatalf("set --file: %v", err) + } + + var err error + stderr := captureStderr(t, func() { + err = createCmd.RunE(createCmd, []string{"my new bead"}) + }) + if err == nil { + t.Fatal("expected --file dispatch with a positional title to be rejected") + } + if !strings.Contains(stderr, "cannot specify both title and --file flag") { + t.Fatalf("expected title/--file conflict message on stderr, got: %v (err: %v)", stderr, err) + } + if !strings.Contains(stderr, "--body-file") { + t.Fatalf("expected title/--file conflict to hint at --body-file, got: %v (err: %v)", stderr, err) + } +} diff --git a/cmd/bd/create_input.go b/cmd/bd/create_input.go index 7a51d7324..36279f721 100644 --- a/cmd/bd/create_input.go +++ b/cmd/bd/create_input.go @@ -95,7 +95,7 @@ func gatherCreateInput(cmd *cobra.Command, args []string) (createInput, error) { } if in.markdownFile != "" { if len(args) > 0 { - return in, HandleError("cannot specify both title and --file flag") + return in, HandleError("cannot specify both title and --file flag; for a single issue's description from a file, use --body-file") } if in.dryRun { return in, HandleError("--dry-run is not supported with --file flag") diff --git a/cmd/bd/create_input_test.go b/cmd/bd/create_input_test.go index 0574e8300..9fb796be1 100644 --- a/cmd/bd/create_input_test.go +++ b/cmd/bd/create_input_test.go @@ -40,6 +40,36 @@ func TestCreateCommandRegistersEmptyDescriptionOptIn(t *testing.T) { } } +func TestCreateFileFlagHelpDoesNotClaimSingleIssueGH4643(t *testing.T) { + f := createCmd.Flags().Lookup("file") + if f == nil { + t.Fatal("expected create to register --file") + } + if !strings.Contains(f.Usage, "one issue per") { + t.Fatalf("expected --file help text to name its per-heading batch behavior, got: %q", f.Usage) + } + if !strings.Contains(f.Usage, "--body-file") { + t.Fatalf("expected --file help text to point single-issue callers at --body-file, got: %q", f.Usage) + } +} + +func TestGatherCreateInputRejectsTitleWithFile(t *testing.T) { + cmd := newCreateFlagsCommand(t, "--file", "issues.md") + var err error + stderr := captureStderr(t, func() { + _, err = gatherCreateInput(cmd, []string{"Some title"}) + }) + if err == nil { + t.Fatal("expected gatherCreateInput to reject a positional title with --file") + } + if !strings.Contains(stderr, "cannot specify both title and --file flag") { + t.Fatalf("expected title/--file conflict on stderr, got stderr=%q err=%v", stderr, err) + } + if !strings.Contains(stderr, "--body-file") { + t.Fatalf("expected title/--file conflict to hint at --body-file, got stderr=%q err=%v", stderr, err) + } +} + func TestGatherCreateInputRejectsEmptyBodyFile(t *testing.T) { filePath := filepath.Join(t.TempDir(), "empty.md") if err := os.WriteFile(filePath, nil, 0644); err != nil { diff --git a/cmd/bd/markdown_test.go b/cmd/bd/markdown_test.go index 1dca3462e..e91ef89d7 100644 --- a/cmd/bd/markdown_test.go +++ b/cmd/bd/markdown_test.go @@ -154,6 +154,38 @@ Just a title and description. }, }, }, + { + name: "GH-4643 H2-per-section briefing file parses as three issues", + content: `## Problem +Something is broken. + +## Context +Extra background. + +## Acceptance Criteria +It should work. +`, + expected: []*IssueTemplate{ + { + Title: "Problem", + Description: "Something is broken.", + Priority: 2, + IssueType: "task", + }, + { + Title: "Context", + Description: "Extra background.", + Priority: 2, + IssueType: "task", + }, + { + Title: "Acceptance Criteria", + Description: "It should work.", + Priority: 2, + IssueType: "task", + }, + }, + }, } for _, tt := range tests {