beads/cmd/bd/markdown.go
Julian Knutsen 1f1e82ab08
fix(issueops): one default priority for every create path (#7426)
* fix(issueops): one create priority default; HTTP absent priority is P2

The CLI defaulted `bd create` to P2, but issues:create, issues:batchCreate
and batch:apply create items left Issue.Priority at 0 when `priority` was
absent, so a gc/curl create stored P0 (critical) against the spec's "absent
means the default".

The default now lives in one place, the shared create preparation
(PreparePublicCreateRequest), behind a presence flag because Issue.Priority's
zero value is P0:
- issueops.CreateRequest.DefaultPriority, BatchCreateItem.DefaultPriority and
  CreateItem.DefaultPriority ask for issueops.DefaultCreatePriority (2);
  setting it with a non-zero priority is ErrValidation
  (ValidateCreatePriority, shared with the HTTP client);
- every Lifecycle.Create, BatchCreator and BatchApplier leg (dolt, embedded,
  uow) reaches it; CloneCreateBatchRequest now keeps scalar item members;
- the three handlers set the flag for an absent member and never make up 0;
  the HTTP client omits `priority` for it (wirePriority) only when the
  server advertises the new additive issues.create.defaultPriority token,
  read from the cached handshake before the dial; an older server reads an
  absent priority as P0, so the client sends DefaultCreatePriority (2)
  explicitly to it (pinCreateDefaultPriority). An explicit 0 is still sent;
- `bd create` without --priority, `bd create --graph` nodes without priority
  and `bd create --file` templates without ### Priority rely on the flag; the
  flag's displayed default and the dry-run previews read the library
  constant. CLI output is byte-identical (checked against origin/main).

Spec: the three priority descriptions now say the create default is P2 on
a server advertising issues.create.defaultPriority (apigen regenerated); the
wireshape golden already had priority optional, so no wire-shape change.

Conformance: RunLifecycleCreateAppliesTheDefaultPriority,
RunBatchCreatorAppliesTheDefaultPriority and
RunBatchApplyAppliesTheDefaultPriority on dolt, embedded, uow and http, plus
handler and client encoding tests, and
TestCreateSendsTheDefaultPriorityToAServerThatPredatesIt (new client,
handshake without the token: all three create roles send 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(issueops): apply review fixups for the default create priority (bd-kb61wg)

Apply the minor and nit findings from the review of #7426:

- CHANGELOG: tell out-of-tree storage backends they must honor
  DefaultPriority (store issueops.DefaultCreatePriority, refuse it with a
  non-zero priority as ErrValidation) and which conformance cases check
  it; scope "CLI output is unchanged" to the in-tree backends.
- bd create --file: pin the default-priority path. The e2e test asserts
  the printed priorities, and a buildMarkdownBatchRequest unit test pins
  the flag and priority for an absent, a 0 and a 1 `### Priority`.
  Deleting `DefaultPriority: !template.PrioritySet` now fails both.
- bd create --file: warn on stderr about a `### Priority` that does not
  parse, as the `### Type` case already does, instead of dropping it
  silently.
- httpclient: document pinCreateDefaultPriority's same-build assumption
  (the handshake is cached per Store, so a stale one is silent here), and
  test its no-context and failed-handshake branches on all three roles.
- Formula steps, `bd q` and `bd todo add` spell
  issueops.DefaultCreatePriority instead of the literal 2.
- Conformance: the batch-creator and batch-apply default-priority cases
  also pin DefaultPriority with a non-zero priority as ErrValidation with
  nothing written.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(issueops): mark the out-of-tree DefaultPriority change BREAKING (bd-0tcn1o)

Apply the minor findings from the relaunch review of #7426:

- CHANGELOG: move the obligation on out-of-tree storage backends out of
  the `### Fixed` entry into its own `### Changed` entry, led by
  "BREAKING (out-of-tree storage backends)" as the close-guard change
  and the earlier out-of-tree contract changes are; RELEASING.md asks
  breaking changes to carry their migration. The entry says what such a
  backend used to receive from `bd create`, `--graph` and `--file`
  (priority 2), what it receives now (priority 0 with DefaultPriority
  set), the migration, and the conformance cases that check it. The
  `### Fixed` entry keeps the HTTP P2 fix, points at the new entry, and
  names the stale-handshake residual that only a code comment named: a
  create that lands on an older build behind the same URL still stores
  P0.
- bd cook: the proto root, the gate issue and the cooked formula root
  spell issueops.DefaultCreatePriority instead of the literal 2, as the
  formula steps in the same file already do. No behavior change.

Not taken:
- The literal 2s in create_form.go, gate.go and linear.go, and the
  "default 2" in todo.go's --priority help: explicit P2s outside the
  migrated paths (the help string also feeds the generated CLI
  reference). Left for a follow-up sweep.
- Reusing in.priorityDefault in the direct bd create route: that route
  builds no createInput (gatherCreateInput runs only on the proxied and
  --file routes, and each returns), so there is nothing to reuse.
- A member-level range check in the single-create HTTP decode, as the
  batch shapes have: the asymmetry predates this PR, and the role still
  refuses an out-of-range priority on all three shapes.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 01:37:27 +00:00

518 lines
16 KiB
Go

// Package main provides the bd command-line interface.
// This file implements markdown file parsing for bulk issue creation from structured markdown documents.
package main
import (
"bufio"
"context"
"fmt"
"os"
"path/filepath"
"regexp"
"strings"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/validation"
"github.com/steveyegge/beads/issueops"
)
var (
// h2Regex matches markdown H2 headers (## Title) for issue titles.
// Compiled once at package init for performance.
h2Regex = regexp.MustCompile(`^##\s+(.+)$`)
// h3Regex matches markdown H3 headers (### Section) for issue sections.
// Compiled once at package init for performance.
h3Regex = regexp.MustCompile(`^###\s+(.+)$`)
)
// IssueTemplate represents a parsed issue from markdown
type IssueTemplate struct {
Title string
Description string
Design string
AcceptanceCriteria string
Priority int
// PrioritySet records that the file named a priority. Without one the
// create asks the role for its default (BatchCreateItem.DefaultPriority);
// Priority then only carries that default for display.
PrioritySet bool
IssueType types.IssueType
Assignee string
Labels []string
Dependencies []string
}
// parseStringList extracts a list of strings from content, splitting by comma or whitespace.
// This is a generic helper used by parseLabels and parseDependencies.
func parseStringList(content string) []string {
var items []string
fields := strings.FieldsFunc(content, func(r rune) bool {
return r == ',' || r == ' ' || r == '\n'
})
for _, item := range fields {
item = strings.TrimSpace(item)
if item != "" {
items = append(items, item)
}
}
return items
}
// parseLabels extracts labels from content, splitting by comma or whitespace.
func parseLabels(content string) []string {
return parseStringList(content)
}
// parseDependencies extracts dependencies from content, splitting by comma or whitespace.
func parseDependencies(content string) []string {
return parseStringList(content)
}
// processIssueSection processes a parsed section and updates the issue template.
func processIssueSection(issue *IssueTemplate, section, content string) {
content = strings.TrimSpace(content)
if content == "" {
return
}
switch strings.ToLower(section) {
case "priority":
if p := validation.ParsePriority(content); p != -1 {
issue.Priority = p
issue.PrioritySet = true
} else {
fmt.Fprintf(os.Stderr, "Warning: invalid priority '%s' in '%s', using default P%d\n",
content, issue.Title, issueops.DefaultCreatePriority)
}
case "type":
t, err := validation.ParseIssueType(content)
if err != nil {
fmt.Fprintf(os.Stderr, "Warning: invalid issue type '%s' in '%s', using default 'task'\n",
strings.TrimSpace(content), issue.Title)
issue.IssueType = types.TypeTask
} else {
issue.IssueType = t
}
case "description":
issue.Description = content
case "design":
issue.Design = content
case "acceptance criteria", "acceptance":
issue.AcceptanceCriteria = content
case "assignee":
issue.Assignee = strings.TrimSpace(content)
case "labels":
issue.Labels = parseLabels(content)
case "dependencies", "deps":
issue.Dependencies = parseDependencies(content)
}
}
// validateMarkdownPath validates and cleans a markdown file path to prevent security issues.
// It checks for directory traversal attempts and ensures the file is a markdown file.
func validateMarkdownPath(path string) (string, error) {
// Clean the path
cleanPath := filepath.Clean(path)
// Prevent directory traversal
if strings.Contains(cleanPath, "..") {
return "", fmt.Errorf("invalid file path: directory traversal not allowed")
}
// Ensure it's a markdown file
ext := strings.ToLower(filepath.Ext(cleanPath))
if ext != ".md" && ext != ".markdown" {
return "", fmt.Errorf("invalid file type: only .md and .markdown files are supported")
}
// Check file exists and is not a directory
info, err := os.Stat(cleanPath)
if err != nil {
return "", fmt.Errorf("cannot access file: %w", err)
}
if info.IsDir() {
return "", fmt.Errorf("path is a directory, not a file")
}
return cleanPath, nil
}
// parseMarkdownFile parses a markdown file and extracts issue templates.
// Expected format:
//
// ## Issue Title
// Description text...
//
// ### Priority
// 2
//
// ### Type
// feature
//
// ### Description
// Detailed description...
//
// ### Design
// Design notes...
//
// ### Acceptance Criteria
// - Criterion 1
// - Criterion 2
//
// ### Assignee
// username
//
// ### Labels
// label1, label2
//
// ### Dependencies
// bd-10, bd-20
//
// markdownParseState holds state for parsing markdown files
type markdownParseState struct {
issues []*IssueTemplate
currentIssue *IssueTemplate
currentSection string
sectionContent strings.Builder
}
// finalizeSection processes and resets the current section
func (s *markdownParseState) finalizeSection() {
if s.currentIssue == nil || s.currentSection == "" {
return
}
content := s.sectionContent.String()
processIssueSection(s.currentIssue, s.currentSection, content)
s.sectionContent.Reset()
}
// handleH2Header handles H2 headers (new issue titles)
func (s *markdownParseState) handleH2Header(matches []string) {
// Finalize previous section if any
s.finalizeSection()
// Save previous issue if any
if s.currentIssue != nil {
s.issues = append(s.issues, s.currentIssue)
}
// Start new issue
s.currentIssue = &IssueTemplate{
Title: strings.TrimSpace(matches[1]),
Priority: issueops.DefaultCreatePriority, // the role's default, for display; see PrioritySet
IssueType: "task", // Default type
}
s.currentSection = ""
}
// handleH3Header handles H3 headers (section titles)
func (s *markdownParseState) handleH3Header(matches []string) {
// Finalize previous section
s.finalizeSection()
// Start new section
s.currentSection = strings.TrimSpace(matches[1])
}
// handleContentLine handles regular content lines
func (s *markdownParseState) handleContentLine(line string) {
if s.currentIssue == nil {
return
}
// Content within a section
if s.currentSection != "" {
if s.sectionContent.Len() > 0 {
s.sectionContent.WriteString("\n")
}
s.sectionContent.WriteString(line)
return
}
// Lines after title (before any section) become description
if line != "" {
if s.currentIssue.Description != "" {
s.currentIssue.Description += "\n"
}
s.currentIssue.Description += line
}
}
// finalize completes parsing and returns the results
func (s *markdownParseState) finalize() ([]*IssueTemplate, error) {
// Finalize last section and issue
s.finalizeSection()
if s.currentIssue != nil {
s.issues = append(s.issues, s.currentIssue)
}
// Check if we found any issues
if len(s.issues) == 0 {
return nil, fmt.Errorf("no issues found in markdown file (expected ## Issue Title format)")
}
return s.issues, nil
}
// createMarkdownScanner creates a scanner with appropriate buffer size
func createMarkdownScanner(file *os.File) *bufio.Scanner {
scanner := bufio.NewScanner(file)
// Increase buffer size for large markdown files
const maxScannerBuffer = 1024 * 1024 // 1MB
buf := make([]byte, maxScannerBuffer)
scanner.Buffer(buf, maxScannerBuffer)
return scanner
}
func parseMarkdownFile(path string) ([]*IssueTemplate, error) {
// Validate and clean the file path
cleanPath, err := validateMarkdownPath(path)
if err != nil {
return nil, err
}
// #nosec G304 -- Path is validated by validateMarkdownPath which prevents traversal
file, err := os.Open(cleanPath)
if err != nil {
return nil, fmt.Errorf("failed to open file: %w", err)
}
defer func() {
_ = file.Close() // Close errors on read-only operations are not actionable
}()
state := &markdownParseState{}
scanner := createMarkdownScanner(file)
for scanner.Scan() {
line := scanner.Text()
// Check for H2 (new issue)
if matches := h2Regex.FindStringSubmatch(line); matches != nil {
state.handleH2Header(matches)
continue
}
// Check for H3 (section within issue)
if matches := h3Regex.FindStringSubmatch(line); matches != nil {
state.handleH3Header(matches)
continue
}
// Regular content line
state.handleContentLine(line)
}
if err := scanner.Err(); err != nil {
return nil, fmt.Errorf("error reading file: %w", err)
}
return state.finalize()
}
// createIssuesFromMarkdown creates every issue in a markdown file as ONE act,
// through issueops.BatchCreator. It parses the file, lints it, builds one
// request and prints what came back; the proxied route builds the SAME request.
func createIssuesFromMarkdown(ctx context.Context, in createInput) error {
templates, err := parseMarkdownFile(in.markdownFile)
if err != nil {
return HandleError("parsing markdown file: %v", err)
}
if len(templates) == 0 {
return HandleError("no issues found in markdown file")
}
if store == nil {
return HandleErrorWithHint("database not initialized", diagHint())
}
request, err := buildMarkdownBatchRequest(templates, in)
if err != nil {
return err
}
// The role creates its Dolt version commit inside the storage layer, so
// `--dolt-auto-commit batch` can only defer it by saying so on the context.
// commitPendingIfEmbedded below is the OTHER half and cannot substitute: it
// correctly no-ops in batch mode, which is exactly why forgetting this line
// produces a per-write commit that nothing later suppresses.
opsCtx, err := issueOpsContext(ctx)
if err != nil {
return HandleError("%v", err)
}
creator, err := store.BatchCreator()
if err != nil {
return HandleError("%v", err)
}
result, err := creator.CreateBatch(opsCtx, request)
if err != nil {
return HandleError("creating issues from markdown: %v", err)
}
issueIDs := make([]string, 0, len(result.Issues))
for _, issue := range result.Issues {
issueIDs = append(issueIDs, issue.ID)
}
if err := commitPendingIfEmbedded(ctx, store, request.Actor, doltAutoCommitParams{
Command: "create",
IssueIDs: issueIDs,
MessageOverride: request.Provenance,
}); err != nil {
WarnError("failed to commit: %v", err)
}
return reportMarkdownBatch(result.Issues, in)
}
// buildMarkdownBatchRequest is the ONE projection of a parsed markdown file
// onto the role's request, shared by both front doors, so the two routes cannot
// answer differently.
//
// It lints first, because the lint is about the FILE the user wrote and
// refusing it here costs no transaction.
func buildMarkdownBatchRequest(templates []*IssueTemplate, in createInput) (issueops.CreateBatchRequest, error) {
if err := lintMarkdownTemplates(templates, in); err != nil {
return issueops.CreateBatchRequest{}, err
}
items := make([]issueops.BatchCreateItem, 0, len(templates))
for _, template := range templates {
dependencies, err := parseMarkdownDependencies(template.Dependencies, template.Title)
if err != nil {
return issueops.CreateBatchRequest{}, HandleError("%v", err)
}
// Resolved per template, not once for the file: the plan-wide flag
// applies to every item, but the per-type storage-class.<type> default
// keys on the template's own type, and the ephemeral spelling moves that
// item to the wisp plane. A conflict refuses the whole file here, before
// any transaction opens.
storageClass, ephemeral, err := resolveCreateStorageClass(in.storageClassFlag, template.IssueType, in.ephemeral, in.noHistory)
if err != nil {
return issueops.CreateBatchRequest{}, HandleError("template %q: %v", template.Title, err)
}
items = append(items, issueops.BatchCreateItem{
Issue: &types.Issue{
Title: template.Title,
Description: template.Description,
Design: template.Design,
AcceptanceCriteria: template.AcceptanceCriteria,
// Status is left unset rather than spelled out as
// types.StatusOpen: PreparePublicCreateRequest (shared by every
// backend, including the http client store's server) already
// defaults an empty Status to StatusOpen, so an explicit "open"
// here was never a different outcome — only a populated member
// the http wire's BatchCreateItem has no slot for and the role
// (correctly) refuses rather than drops. Leaving it unset removes
// that one refusal without changing what gets created; the http
// wire still refuses this request's Provenance and Owner (see
// internal/httpclient/batchcreator.go), so `--file` is not
// servable there yet.
Priority: markdownItemPriority(template),
IssueType: template.IssueType,
Assignee: template.Assignee,
Labels: template.Labels,
Ephemeral: ephemeral,
NoHistory: in.noHistory,
StorageClass: storageClass,
MolType: in.molType,
CreatedBy: in.createdBy,
Owner: in.owner,
},
Dependencies: dependencies,
DefaultPriority: !template.PrioritySet,
})
}
return issueops.CreateBatchRequest{
Actor: markdownBatchActor(in),
Items: items,
// The entry both routes have always written, spelled once. The role's
// own default would name a count and lose the file, which is the thing
// `bd dolt log` is read for after a bulk create.
Provenance: fmt.Sprintf("bd: create %d issue(s) from %s", len(templates), in.markdownFile),
}, nil
}
// markdownBatchActor is the actor a `--file` create is attributed to. The role
// refuses an empty one, and "bd" is the fallback this command has always used
// when nothing named a person.
func markdownBatchActor(in createInput) string {
if in.createdBy != "" {
return in.createdBy
}
if currentActor() != "" {
return currentActor()
}
return "bd"
}
// lintMarkdownTemplates applies the workspace's validation.on-create policy to
// every template, the same policy the single-issue create applies to its one
// issue.
func lintMarkdownTemplates(templates []*IssueTemplate, in createInput) error {
if in.validationMode != "error" && in.validationMode != "warn" {
return nil
}
for _, template := range templates {
lintIssue := &types.Issue{
IssueType: template.IssueType,
Description: template.Description,
AcceptanceCriteria: template.AcceptanceCriteria,
}
if err := validation.LintIssue(lintIssue); err != nil {
if in.validationMode == "error" {
return HandleError("template %q: %v", template.Title, err)
}
fmt.Fprintf(os.Stderr, "%s template %q: %v\n", ui.RenderWarn("⚠"), template.Title, err)
}
}
return nil
}
// parseMarkdownDependencies reads a template's `### Dependencies` section as
// the role's edge specs. `type:target` names the type; a bare target blocks.
func parseMarkdownDependencies(deps []string, templateTitle string) ([]issueops.CreateDependency, error) {
var out []issueops.CreateDependency
for _, raw := range deps {
raw = strings.TrimSpace(raw)
if raw == "" {
continue
}
var depType types.DependencyType
var target string
if strings.Contains(raw, ":") {
parts := strings.SplitN(raw, ":", 2)
if len(parts) != 2 {
return nil, fmt.Errorf("invalid dependency format %q for issue %q", raw, templateTitle)
}
depType = types.DependencyType(strings.TrimSpace(parts[0]))
target = strings.TrimSpace(parts[1])
} else {
depType = types.DepBlocks
target = raw
}
if !depType.IsValid() {
return nil, fmt.Errorf("invalid dependency type %q for issue %q", depType, templateTitle)
}
out = append(out, issueops.CreateDependency{Type: depType, TargetID: target})
}
return out, nil
}
// reportMarkdownBatch prints what the batch created, in the one shape both
// routes print.
func reportMarkdownBatch(issues []*types.Issue, in createInput) error {
if in.jsonOutput {
return outputJSON(issues)
}
fmt.Printf("%s Created %d issues from %s:\n", ui.RenderPass("✓"), len(issues), in.markdownFile)
for _, issue := range issues {
fmt.Printf(" %s: %s [P%d, %s]\n", issue.ID, issue.Title, issue.Priority, issue.IssueType)
}
return nil
}
// markdownItemPriority is the priority a template's create item carries: its
// own when the file named one, otherwise zero, because the item then asks the
// role for its default (BatchCreateItem.DefaultPriority).
func markdownItemPriority(template *IssueTemplate) int {
if template.PrioritySet {
return template.Priority
}
return 0
}