feat(lint): configurable per-type lint sections via lint.sections.<type> (#5855)

* feat(lint): configurable per-type lint sections via lint.sections.<type>

bd lint, bd create --validate, doctor conventions, and markdown import all
check issue descriptions against built-in required sections that are
hardcoded per issue type. This adds a config knob:

  bd config set lint.sections.epic "Standards scorecard, Cost"

- lint.sections.<type> holds a comma-separated list of section headings,
  stored in config.yaml (yaml-only key, same path as validation.*).
- The list is ADDITIVE to types.IssueType.RequiredSections: built-in
  requirements are never relaxed, only extended.
- Entries are normalized to "## <heading>" (any leading '#' run and
  surrounding whitespace stripped) and deduped case-insensitively against
  both the built-ins and each other, so re-declaring a built-in changes
  nothing.
- Consumed in internal/validation.ValidateTemplate (the single choke point
  behind LintIssue and every lint consumer) via mergeLintSections.
- lint.* is a recognized config prefix and documented in bd config and
  bd lint help.

* docs(config): list the lint.* namespace and lint.sections.<type> in YAML-only keys

Address review feedback: the PR routes lint.* through config.yaml
(internal/config/yaml_config.go) but the YAML-only Keys section of
docs/reference/configuration.md did not list it. Add the namespace and a
one-line key description. (The pre-existing audit. and storage-class.
omissions are left as-is, out of scope for this PR.)
This commit is contained in:
Jacob Hausler 2026-08-19 13:23:33 -05:00 • committed by GitHub
commit d2fc47949d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 246 additions and 6 deletions

View file

@ -42,6 +42,7 @@ Common namespaces:
- status.* Issue status configuration
- claim.* Claim arbitration settings (pool-aware claiming)
- doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)
- lint.* Additional per-type lint sections (stored in config.yaml)
Auto-Export (config.yaml):
Optional JSONL export to .beads/issues.jsonl after write commands (throttled).
@ -106,6 +107,7 @@ Examples:
bd config set doctor.suppress.pending-migrations true
bd config set dolt.debug true # Enable Dolt sql-server debug mode (loglevel=debug, --prof cpu)
bd config set dolt.local-only true # Skip wiring a Dolt sync remote during bd init
bd config set lint.sections.epic "Standards scorecard, Cost" # Extra sections bd lint requires for epics
bd config get export.auto
bd config list
bd config unset jira.url`,
@ -970,8 +972,8 @@ var recognizedConfigPrefixes = []string{
"export.", "import.", "dolt.", "custom.",
"status.", "types.", "doctor.suppress.", "routing.", "sync.", "git.",
"directory.", "repos.", "external_projects.", "validation.",
"hierarchy.", "ai.", "backup.", "federation.", "metrics.", "agent.",
"claim.", "storage-class.",
"lint.", "hierarchy.", "ai.", "backup.", "federation.", "metrics.",
"agent.", "claim.", "storage-class.",
}
// validateStorageClassConfig validates a storage-class.<type> per-type

View file

@ -36,6 +36,11 @@ Section requirements by type:
epic: Success Criteria (or Acceptance Criteria)
chore: (none)
Additional per-type sections can be required via config; they are ADDITIVE
to the built-ins above (built-in requirements are never relaxed):
bd config set lint.sections.epic "Standards scorecard, Cost"
Examples:
bd lint # Lint all open issues
bd lint bd-abc # Lint specific issue

View file

@ -82,7 +82,9 @@ These keys must live in `config.yaml`, not the database, because they are read b
The full namespaces routed to YAML are:
`routing.*`, `sync.*`, `git.*`, `directory.*`, `repos.*`, `external_projects.*`, `validation.*`, `hierarchy.*`, `ai.*`, `backup.*`, `export.*`, `dolt.*`, `federation.*`, `metrics.*`, `list.*`
`routing.*`, `sync.*`, `git.*`, `directory.*`, `repos.*`, `external_projects.*`, `validation.*`, `lint.*`, `hierarchy.*`, `ai.*`, `backup.*`, `export.*`, `dolt.*`, `federation.*`, `metrics.*`, `list.*`
`lint.*` holds lint settings: `lint.sections.<type>` is a comma-separated, additive list of sections that `bd lint` additionally requires for issues of that type (built-in required sections still apply; unset means no behavior change).
Plus these individual keys:

View file

@ -115,7 +115,7 @@ func IsYamlOnlyKey(key string) bool {
}
// Check prefix matches for nested keys
prefixes := []string{"routing.", "sync.", "git.", "directory.", "repos.", "external_projects.", "validation.", "hierarchy.", "ai.", "backup.", "export.", "dolt.", "federation.", "metrics.", "list.", "audit.", "storage-class."}
prefixes := []string{"routing.", "sync.", "git.", "directory.", "repos.", "external_projects.", "validation.", "lint.", "hierarchy.", "ai.", "backup.", "export.", "dolt.", "federation.", "metrics.", "list.", "audit.", "storage-class."}
for _, prefix := range prefixes {
if strings.HasPrefix(key, prefix) {
return true

View file

@ -4,6 +4,7 @@ import (
"fmt"
"strings"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/types"
)
@ -32,14 +33,91 @@ func (e *TemplateError) Error() string {
return b.String()
}
// LintSectionsConfigPrefix is the config namespace for per-issue-type
// additional lint sections (G4): lint.sections.<type> holds a
// comma-separated list of section headings, e.g.
//
// bd config set lint.sections.epic "Standards scorecard, Cost"
//
// The list is ADDITIVE to the built-in sections in
// types.IssueType.RequiredSections: built-in requirements are never relaxed.
const LintSectionsConfigPrefix = "lint.sections."
// ConfiguredLintSections returns the extra required sections configured for
// the issue type under lint.sections.<type>. Each comma-separated entry is
// normalized to a canonical "## <heading>" form (a leading run of '#' and
// surrounding whitespace is stripped, so "# Cost", "## Cost", and "cost"
// all yield "## Cost"), empty entries are dropped, and entries are deduped
// case-insensitively with the first occurrence's casing kept. Returns nil
// when the key is unset or empty.
func ConfiguredLintSections(issueType types.IssueType) []types.RequiredSection {
raw := config.GetString(LintSectionsConfigPrefix + string(issueType))
var out []types.RequiredSection
seen := make(map[string]bool)
for _, part := range strings.Split(raw, ",") {
text := strings.TrimSpace(part)
text = strings.TrimSpace(strings.TrimLeft(text, "#"))
if text == "" {
continue
}
if seen[headingKey("## "+text)] {
continue
}
seen[headingKey("## "+text)] = true
out = append(out, types.RequiredSection{
Heading: "## " + text,
Hint: "Required by " + LintSectionsConfigPrefix + string(issueType) + " config",
})
}
return out
}
// headingKey normalizes a section heading to a case-insensitive comparison
// key: markdown prefix hashes and surrounding whitespace are dropped.
func headingKey(heading string) string {
return strings.ToLower(strings.TrimSpace(strings.TrimLeft(strings.TrimSpace(heading), "#")))
}
// mergeLintSections returns the sections ValidateTemplate requires for the
// issue type: the built-ins from types.IssueType.RequiredSections plus the
// additive configured sections from lint.sections.<type> (G4). Deduped
// case-insensitively by heading text, built-ins first so their canonical
// hints win.
func mergeLintSections(issueType types.IssueType) []types.RequiredSection {
builtIn := issueType.RequiredSections()
configured := ConfiguredLintSections(issueType)
if len(configured) == 0 {
return builtIn
}
merged := make([]types.RequiredSection, 0, len(builtIn)+len(configured))
seen := make(map[string]bool, len(builtIn)+len(configured))
for _, s := range builtIn {
if seen[headingKey(s.Heading)] {
continue
}
seen[headingKey(s.Heading)] = true
merged = append(merged, s)
}
for _, s := range configured {
if seen[headingKey(s.Heading)] {
continue
}
seen[headingKey(s.Heading)] = true
merged = append(merged, s)
}
return merged
}
// ValidateTemplate checks if the description contains all required sections
// for the given issue type. Returns nil if validation passes or if the
// for the given issue type: the built-ins from
// types.IssueType.RequiredSections plus the additive configured sections from
// lint.sections.<type> (G4). Returns nil if validation passes or if the
// issue type has no required sections.
//
// Section matching is case-insensitive and looks for the heading text
// anywhere in the description (doesn't require exact markdown format).
func ValidateTemplate(issueType types.IssueType, description string) error {
required := issueType.RequiredSections()
required := mergeLintSections(issueType)
if len(required) == 0 {
return nil
}

View file

@ -0,0 +1,153 @@
package validation
import (
"testing"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/types"
)
// isolateLintConfig resets the process-wide config singleton so the test
// starts from a known state and can set lint.sections.* values in memory.
// BEADS_TEST_IGNORE_REPO_CONFIG keeps the checkout's own .beads/config.yaml
// out of the picture; the real user-level config on dev machines carries no
// lint.* keys, and config.Set() overrides any file value anyway.
func isolateLintConfig(t *testing.T) {
t.Helper()
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
config.ResetForTesting()
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
t.Cleanup(config.ResetForTesting)
}
// missingHeadings extracts the ordered list of missing headings from a
// TemplateError, or nil when validation passed.
func missingHeadings(t *testing.T, err error) []string {
t.Helper()
if err == nil {
return nil
}
te, ok := err.(*TemplateError)
if !ok {
t.Fatalf("expected *TemplateError, got %T: %v", err, err)
}
out := make([]string, len(te.Missing))
for i, m := range te.Missing {
out[i] = m.Heading
}
return out
}
// assertMissing fails unless err is a TemplateError whose missing headings
// match want exactly (order and content).
func assertMissing(t *testing.T, err error, want ...string) {
t.Helper()
got := missingHeadings(t, err)
if len(got) != len(want) {
t.Fatalf("missing sections = %v, want %v", got, want)
}
for i := range want {
if got[i] != want[i] {
t.Fatalf("missing sections = %v, want %v", got, want)
}
}
}
// TestLintSectionsConfigAdditive is the G4 contract: lint.sections.<type>
// (comma-separated, read through the normal config plumbing) ADDS sections
// to the built-ins in types.IssueType.RequiredSections; it never replaces
// them. Deduping is case-insensitive, so configuring a section a type
// already requires changes nothing.
func TestLintSectionsConfigAdditive(t *testing.T) {
const epicWithSuccess = "## Success Criteria\n- Shipped"
t.Run("built-in behavior without config", func(t *testing.T) {
isolateLintConfig(t)
if err := ValidateTemplate(types.TypeEpic, epicWithSuccess); err != nil {
t.Fatalf("epic with built-in section should pass, got %v", err)
}
assertMissing(t, ValidateTemplate(types.TypeEpic, "big initiative"), "## Success Criteria")
})
t.Run("configured sections are additive to built-ins", func(t *testing.T) {
isolateLintConfig(t)
config.Set("lint.sections.epic", "Standards scorecard, ## Cost")
assertMissing(t, ValidateTemplate(types.TypeEpic, epicWithSuccess),
"## Standards scorecard", "## Cost")
full := epicWithSuccess + "\n\n## Standards scorecard\n- meets score\n\n## Cost\n- low"
if err := ValidateTemplate(types.TypeEpic, full); err != nil {
t.Fatalf("epic with all built-in and configured sections should pass, got %v", err)
}
})
t.Run("configured section duplicating a built-in is deduped", func(t *testing.T) {
isolateLintConfig(t)
config.Set("lint.sections.epic", "Success Criteria")
if err := ValidateTemplate(types.TypeEpic, epicWithSuccess); err != nil {
t.Fatalf("deduped built-in must not double-report, got %v", err)
}
assertMissing(t, ValidateTemplate(types.TypeEpic, "nope"), "## Success Criteria")
})
t.Run("other issue types are unaffected", func(t *testing.T) {
isolateLintConfig(t)
config.Set("lint.sections.epic", "Standards scorecard")
if err := ValidateTemplate(types.TypeTask, "## Acceptance Criteria\n- done"); err != nil {
t.Fatalf("task must not be affected by an epic-only config, got %v", err)
}
})
t.Run("empty and whitespace-only value is inert", func(t *testing.T) {
isolateLintConfig(t)
config.Set("lint.sections.epic", " , ,")
if err := ValidateTemplate(types.TypeEpic, epicWithSuccess); err != nil {
t.Fatalf("empty configured list should be inert, got %v", err)
}
})
t.Run("LintIssue sees configured sections too", func(t *testing.T) {
isolateLintConfig(t)
config.Set("lint.sections.epic", "Cost")
// Description carries Success Criteria; the configured Cost section is missing.
issue := &types.Issue{IssueType: types.TypeEpic, Description: epicWithSuccess}
assertMissing(t, LintIssue(issue), "## Cost")
// AcceptanceCriteria field satisfies Success Criteria (no heading needed),
// but the configured section still has to appear in the description.
issue = &types.Issue{IssueType: types.TypeEpic, Description: "epic body", AcceptanceCriteria: "done"}
assertMissing(t, LintIssue(issue), "## Cost")
})
}
// TestConfiguredLintSectionsNormalizesHeadings pins the value grammar:
// comma-separated entries, arbitrary leading '#' runs and surrounding
// whitespace normalized to "## <heading>", empties dropped, case-insensitive
// dedupe keeping the first occurrence's casing.
func TestConfiguredLintSectionsNormalizesHeadings(t *testing.T) {
isolateLintConfig(t)
config.Set("lint.sections.bug", " # repro steps , ## RePro Steps , , Acceptance criteria")
got := ConfiguredLintSections(types.TypeBug)
want := []types.RequiredSection{
{Heading: "## repro steps", Hint: "Required by lint.sections.bug config"},
{Heading: "## Acceptance criteria", Hint: "Required by lint.sections.bug config"},
}
if len(got) != len(want) {
t.Fatalf("ConfiguredLintSections = %+v, want %+v", got, want)
}
for i := range want {
if got[i] != want[i] {
t.Fatalf("ConfiguredLintSections[%d] = %+v, want %+v", i, got[i], want[i])
}
}
// Unset key: no configured sections.
config.Set("lint.sections.spike", "")
if got := ConfiguredLintSections(types.TypeSpike); len(got) != 0 {
t.Fatalf("empty value should yield no sections, got %+v", got)
}
}