diff --git a/CHANGELOG.md b/CHANGELOG.md index bdd832f5a..3015a51d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -528,6 +528,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- **A formula with a `waits_for` gate and no spawner to wait for is now + rejected, and an invalid formula is no longer reported as not found.** A gate + step infers its spawner from `needs[0]`, so with nothing to infer from, + cooking stamped the `gate:` label and emitted no dependency edge at + all - a gate bead that never blocks and never resolves. `bd create` already + refused `--waits-for-gate` without `--waits-for`; the formula path was the + outlier. `Formula.Validate` now enforces the same rule. Separately, a + validation failure is distinguishable from "this name is not a formula": + callers that fall back to a proto/issue lookup previously swallowed the real + error and reported `not found as issue or formula`, so an invalid formula + looked like a typo. `bd mol bond --dry-run` also resolves through + `parser.Resolve` now, so it resolves and validates the same way the real + bond does rather than previewing a bond that then errors on those checks. + Later cook transforms (inline expansions, expansions, aspects and + condition filtering) are still only exercised by the real bond. + - **`bd prime` describes the memory split instead of prohibiting `MEMORY.md`** ([#6111](https://github.com/gastownhall/beads/pull/6111), refs [#5169](https://github.com/gastownhall/beads/issues/5169)). The guidance diff --git a/cmd/bd/BUILD.bazel b/cmd/bd/BUILD.bazel index 6a77df6ab..cae4c880c 100644 --- a/cmd/bd/BUILD.bazel +++ b/cmd/bd/BUILD.bazel @@ -890,6 +890,7 @@ go_test( "migrate_test.go", "migration_freeze_gate_test.go", "mol_bond_compound_label_test.go", + "mol_bond_dryrun_validation_test.go", "mol_bond_gwn_test.go", "mol_bond_proxied_integration_test.go", "mol_bond_ref_attach_test.go", diff --git a/cmd/bd/mol_bond.go b/cmd/bd/mol_bond.go index a3316f820..2a61f0908 100644 --- a/cmd/bd/mol_bond.go +++ b/cmd/bd/mol_bond.go @@ -698,14 +698,28 @@ func resolveOrDescribe(ctx context.Context, s molReader, operand string, vars ma return nil, "", fmt.Errorf("'%s' not found as issue or formula: %w", operand, err) } - // A dry-run must fail the same way the real bond would: an enum/pattern/ - // provided-empty violation in --var values fails resolveOrCookToSubgraph, - // so reporting "will be cooked" here would be a false preview. - if err := formula.ValidateProvidedVars(f, vars); err != nil { - return nil, "", err + // A dry-run must fail the same way the real bond would, and the real bond + // (resolveAndCookFormulaWithVars) resolves inheritance BEFORE it validates + // anything. parser.Resolve is what calls Formula.Validate - LoadByName -> + // loadFormula -> ParseFile never does - so skipping it here previewed a + // successful bond for a formula the real bond rejects, including the + // unspawnable waits_for gate this PR adds. Resolving first also means the + // --var check runs against the merged formula rather than the unmerged + // one, so a var declared only in a parent is checked too. + resolved, err := parser.Resolve(f) + if err != nil { + return nil, "", fmt.Errorf("resolving formula %q: %w", operand, err) } - return nil, f.Formula, nil + // An enum/pattern/provided-empty violation in --var values fails + // resolveOrCookToSubgraph, so reporting "will be cooked" here would be a + // false preview. Wrapped the same way the real path wraps it, so the two + // produce the same message rather than merely the same exit code. + if err := formula.ValidateProvidedVars(resolved, vars); err != nil { + return nil, "", fmt.Errorf("formula %q: %w", operand, err) + } + + return nil, resolved.Formula, nil } // resolveOrCookToSubgraph tries to resolve an operand as an issue ID or formula. @@ -742,10 +756,10 @@ func resolveOrCookToSubgraph(ctx context.Context, s molReader, operand string, v // condition filtering (bd-7zka.1). subgraph, err := resolveAndCookFormulaWithVars(operand, nil, vars) if err != nil { - if errors.Is(err, formula.ErrVarValidation) { - // Don't double-wrap: operand IS a formula, and the --var values - // it was given fail enum/pattern/required-empty constraints, - // which is a distinct condition from "not found". + if errors.Is(err, formula.ErrVarValidation) || errors.Is(err, formula.ErrValidation) { + // Don't double-wrap: operand IS a formula that either does not + // validate or was given --var values failing its enum/pattern/ + // required-empty constraints, both distinct from "not found". return nil, false, err } return nil, false, fmt.Errorf("'%s' not found as issue or formula: %w", operand, err) diff --git a/cmd/bd/mol_bond_dryrun_validation_test.go b/cmd/bd/mol_bond_dryrun_validation_test.go new file mode 100644 index 000000000..f80789236 --- /dev/null +++ b/cmd/bd/mol_bond_dryrun_validation_test.go @@ -0,0 +1,160 @@ +package main + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/formula" + "github.com/steveyegge/beads/internal/types" +) + +// noIssuesMolReader answers "no such issue" so an operand falls through to the +// formula registry, which is the only branch these cases exercise. It embeds +// the molReader INTERFACE rather than implementing it, so any read beyond the +// three ResolvePartialID makes panics loudly instead of quietly answering zero. +type noIssuesMolReader struct { + molReader +} + +func (r *noIssuesMolReader) SearchIssues(context.Context, string, types.IssueFilter) ([]*types.Issue, error) { + return nil, nil +} + +func (r *noIssuesMolReader) SearchIssueIDs(context.Context, string, types.IssueFilter) ([]string, error) { + return nil, nil +} + +func (r *noIssuesMolReader) GetConfig(context.Context, string) (string, error) { + return "", nil +} + +// writeSearchableFormula puts a formula where formula.DefaultSearchPaths will +// find it, via the GT_ROOT arm - the one search path a test can set without +// touching HOME or the working directory. +func writeSearchableFormula(t *testing.T, name, body string) { + t.Helper() + root := t.TempDir() + dir := filepath.Join(root, ".beads", "formulas") + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatalf("mkdir formulas dir: %v", err) + } + if err := os.WriteFile(filepath.Join(dir, name+".formula.toml"), []byte(body), 0o644); err != nil { + t.Fatalf("write formula: %v", err) + } + t.Setenv("GT_ROOT", root) +} + +// A waits_for gate with no needs: nothing to infer a spawner from, so the +// cooked gate would carry its gate: label and no dependency edge. +const invalidGateFormula = `formula = "dryrun-invalid-gate" +version = 1 +type = "workflow" + +[[steps]] +id = "fanout" +title = "Fan out" +type = "task" + +[[steps]] +id = "gate" +title = "Wait for the children" +type = "task" +waits_for = "all-children" +` + +// A `bd mol bond --dry-run` must fail on exactly what the real bond fails on. +// +// The dry-run path (resolveOrDescribe) resolved a formula with +// parser.LoadByName, which never calls Formula.Validate - only parser.Resolve +// does, and the real path (resolveOrCookToSubgraph -> resolveAndCookFormulaWithVars) +// calls it. So a formula the real bond rejects previewed as a successful bond, +// including for the waits_for-without-a-spawner rule this branch adds. +// +// The two routes are asserted against EACH OTHER rather than against a literal +// message: that is what stops a validation rule added later from re-opening the +// same gap. +func TestBondDryRunRejectsWhatTheRealBondRejects(t *testing.T) { + writeSearchableFormula(t, "dryrun-invalid-gate", invalidGateFormula) + + // The control, and the reason the bug existed: LoadByName alone accepts + // this formula. If this ever starts failing, the two assertions below stop + // distinguishing the routes and this test is no longer about anything. + if _, err := formula.NewParser().LoadByName("dryrun-invalid-gate"); err != nil { + t.Fatalf("LoadByName should still accept an invalid formula (it does not validate): %v", err) + } + + ctx := context.Background() + reader := &noIssuesMolReader{} + + _, _, dryErr := resolveOrDescribe(ctx, reader, "dryrun-invalid-gate", nil) + _, _, realErr := resolveOrCookToSubgraph(ctx, reader, "dryrun-invalid-gate", nil) + + if realErr == nil { + t.Fatal("the real bond accepted an invalid formula, so this test is no longer testing the gap") + } + if dryErr == nil { + t.Fatalf("dry-run previewed a bond the real bond rejects (real bond said: %v)", realErr) + } + + // Both routes must name the actual problem, not "not found as issue or + // formula" - the formula resolved fine, it just does not validate. + for name, err := range map[string]error{"dry-run": dryErr, "real bond": realErr} { + if !strings.Contains(err.Error(), "waits_for") { + t.Errorf("%s error does not name the failing field: %v", name, err) + } + if strings.Contains(err.Error(), "not found as issue or formula") { + t.Errorf("%s reported an invalid formula as not found: %v", name, err) + } + } +} + +// Resolving before validating --var values also closes a second-order gap: the +// real path validates against the MERGED formula, so a var declared only in a +// parent was unchecked by the dry-run, which validated the unmerged one. +func TestBondDryRunValidatesVarsAgainstTheMergedFormula(t *testing.T) { + root := t.TempDir() + dir := filepath.Join(root, ".beads", "formulas") + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatalf("mkdir formulas dir: %v", err) + } + write := func(name, body string) { + if err := os.WriteFile(filepath.Join(dir, name+".formula.toml"), []byte(body), 0o644); err != nil { + t.Fatalf("write %s: %v", name, err) + } + } + write("dryrun-parent", `formula = "dryrun-parent" +version = 1 +type = "workflow" + +[vars.env] +enum = ["dev", "prod"] + +[[steps]] +id = "deploy" +title = "Deploy to {{env}}" +type = "task" +`) + write("dryrun-child", `formula = "dryrun-child" +version = 1 +type = "workflow" +extends = ["dryrun-parent"] +`) + t.Setenv("GT_ROOT", root) + + ctx := context.Background() + reader := &noIssuesMolReader{} + vars := map[string]string{"env": "staging"} // not in the parent's enum + + _, _, dryErr := resolveOrDescribe(ctx, reader, "dryrun-child", vars) + _, _, realErr := resolveOrCookToSubgraph(ctx, reader, "dryrun-child", vars) + + if realErr == nil { + t.Fatal("the real bond accepted a var value outside the inherited enum") + } + if dryErr == nil { + t.Fatalf("dry-run accepted a var value the real bond rejects; the enum is declared only in the parent (real bond said: %v)", realErr) + } +} diff --git a/cmd/bd/mol_proxied_server.go b/cmd/bd/mol_proxied_server.go index efb2e1cd0..6136499dc 100644 --- a/cmd/bd/mol_proxied_server.go +++ b/cmd/bd/mol_proxied_server.go @@ -44,9 +44,10 @@ func runPourProxiedServer(ctx context.Context, in pourInput) error { if sg.Phase == "vapor" { warnPourVaporFormula(in.protoArg, in.varFlags) } - } else if errors.Is(err, formula.ErrVarValidation) { - // in.protoArg IS a formula; the --var values it was given fail - // enum/pattern/required-empty constraints. Report that directly + } else if errors.Is(err, formula.ErrVarValidation) || errors.Is(err, formula.ErrValidation) { + // in.protoArg IS a formula; either the formula itself does not + // validate, or the --var values it was given fail enum/pattern/ + // required-empty constraints. Report that directly // instead of falling through to the proto-ID lookup below, which // would otherwise mask this as "not found as formula or proto ID". return HandleError("%v", err) diff --git a/cmd/bd/mol_seed.go b/cmd/bd/mol_seed.go index e8a1de779..b7df281aa 100644 --- a/cmd/bd/mol_seed.go +++ b/cmd/bd/mol_seed.go @@ -78,7 +78,7 @@ func verifyFormula(formulaName string, vars map[string]string) error { // 4. Formula can be cooked to subgraph _, err := resolveAndCookFormulaWithVars(formulaName, nil, vars) if err != nil { - if errors.Is(err, formula.ErrVarValidation) { + if errors.Is(err, formula.ErrVarValidation) || errors.Is(err, formula.ErrValidation) { // Don't double-wrap: the --var values fail enum/pattern/ // required-empty constraints, which is a distinct condition // from the formula itself being inaccessible. diff --git a/cmd/bd/pour.go b/cmd/bd/pour.go index 0278c69d4..5b3b628fd 100644 --- a/cmd/bd/pour.go +++ b/cmd/bd/pour.go @@ -123,9 +123,10 @@ func runPour(cmd *cobra.Command, args []string) error { if sg.Phase == "vapor" { warnPourVaporFormula(in.protoArg, in.varFlags) } - } else if errors.Is(err, formula.ErrVarValidation) { - // in.protoArg IS a formula; the --var values it was given fail - // enum/pattern/required-empty constraints. Report that directly + } else if errors.Is(err, formula.ErrVarValidation) || errors.Is(err, formula.ErrValidation) { + // in.protoArg IS a formula; either the formula itself does not + // validate, or the --var values it was given fail enum/pattern/ + // required-empty constraints. Report that directly // instead of falling through to the proto-ID lookup below, which // would otherwise mask this as "not found as formula or proto ID". return HandleError("%v", err) diff --git a/cmd/bd/wisp.go b/cmd/bd/wisp.go index b1ed09f71..ea5ff1887 100644 --- a/cmd/bd/wisp.go +++ b/cmd/bd/wisp.go @@ -210,9 +210,10 @@ func runWispCreateCore(cmd *cobra.Command, args []string) error { if err == nil { subgraph = sg protoID = sg.Root.ID - } else if errors.Is(err, formula.ErrVarValidation) { - // args[0] IS a formula; the --var values it was given fail - // enum/pattern/required-empty constraints. Report that directly + } else if errors.Is(err, formula.ErrVarValidation) || errors.Is(err, formula.ErrValidation) { + // args[0] IS a formula; either the formula itself does not + // validate, or the --var values it was given fail enum/pattern/ + // required-empty constraints. Report that directly // instead of falling through to the legacy proto-ID lookup below, // which would otherwise mask this as "not found as formula or proto". return HandleError("%v", err) diff --git a/cmd/bd/wisp_proxied_server.go b/cmd/bd/wisp_proxied_server.go index b05792e69..ab9d78798 100644 --- a/cmd/bd/wisp_proxied_server.go +++ b/cmd/bd/wisp_proxied_server.go @@ -37,9 +37,10 @@ func runWispCreateProxiedServer(ctx context.Context, in wispCreateInput) error { if sg, err := resolveAndCookFormulaWithVars(in.protoArg, nil, vars); err == nil { formulaSubgraph = sg formulaProtoID = sg.Root.ID - } else if errors.Is(err, formula.ErrVarValidation) { - // in.protoArg IS a formula; the --var values it was given fail - // enum/pattern/required-empty constraints. Report that directly + } else if errors.Is(err, formula.ErrVarValidation) || errors.Is(err, formula.ErrValidation) { + // in.protoArg IS a formula; either the formula itself does not + // validate, or the --var values it was given fail enum/pattern/ + // required-empty constraints. Report that directly // instead of falling through to the proto-ID lookup below, which // would otherwise mask this as "not found as formula or proto". return HandleError("%v", err) diff --git a/docs/workflows/gates.md b/docs/workflows/gates.md index a2c7cd2f1..6387814c9 100644 --- a/docs/workflows/gates.md +++ b/docs/workflows/gates.md @@ -178,12 +178,22 @@ id = "merge-results" title = "Merge results" needs = ["test-a", "test-b"] # fan-in on named steps +[[steps]] +id = "fan-out" +title = "Spawn a worker per shard" + [[steps]] id = "summarize" title = "Summarize all spawned work" -waits_for = "all-children" # or "any-children", or "children-of(step-id)" +needs = ["fan-out"] # the spawner whose children to wait for +waits_for = "all-children" # or "any-children", or "children-of(fan-out)" ``` +`all-children` and `any-children` wait for the children of `needs[0]`, so a step +using them must declare `needs`; `children-of(step-id)` names the spawner itself +and does not. A bare gate with neither is rejected when the formula is cooked, +because it would wait for no one. + ## Working with gated molecules ```bash diff --git a/internal/formula/BUILD.bazel b/internal/formula/BUILD.bazel index 24e6ae87f..5e53e92d4 100644 --- a/internal/formula/BUILD.bazel +++ b/internal/formula/BUILD.bazel @@ -36,6 +36,7 @@ go_test( "schema_gen_test.go", "schema_test.go", "stepcondition_test.go", + "validation_sentinel_test.go", ], data = [ "schema_gen.go", diff --git a/internal/formula/parser_test.go b/internal/formula/parser_test.go index 0cf01d454..6770ff933 100644 --- a/internal/formula/parser_test.go +++ b/internal/formula/parser_test.go @@ -1022,6 +1022,67 @@ func TestValidate_WaitsForField(t *testing.T) { } } +// A bare all-children/any-children gate takes its spawner from needs[0], so a +// step with no needs gates on nothing: cooking gives it a gate: label, +// no dependency, and immediate readiness. +func TestValidate_WaitsForWithoutSpawner(t *testing.T) { + for _, gate := range []string{"all-children", "any-children"} { + t.Run(gate, func(t *testing.T) { + f := &Formula{ + Formula: "mol-spawnerless", + Version: 1, + Type: TypeWorkflow, + Steps: []*Step{ + {ID: "fanout", Title: "Fanout"}, + {ID: "summarize", Title: "Summarize", WaitsFor: gate}, + }, + } + + err := f.Validate() + if err == nil { + t.Fatalf("Validate() = nil, want an error for %s with no needs", gate) + } + if !strings.Contains(err.Error(), "needs") { + t.Errorf("Validate() error = %q, want it to point at needs", err) + } + }) + } + + t.Run("children-of names its own spawner", func(t *testing.T) { + f := &Formula{ + Formula: "mol-explicit-spawner", + Version: 1, + Type: TypeWorkflow, + Steps: []*Step{ + {ID: "fanout", Title: "Fanout"}, + {ID: "summarize", Title: "Summarize", WaitsFor: "children-of(fanout)"}, + }, + } + + if err := f.Validate(); err != nil { + t.Errorf("Validate() = %v, want nil: children-of() needs no needs", err) + } + }) + + t.Run("nested child step", func(t *testing.T) { + f := &Formula{ + Formula: "mol-spawnerless-child", + Version: 1, + Type: TypeWorkflow, + Steps: []*Step{ + {ID: "parent", Title: "Parent", Children: []*Step{ + {ID: "child1", Title: "Child 1"}, + {ID: "child2", Title: "Child 2", WaitsFor: "all-children"}, + }}, + }, + } + + if err := f.Validate(); err == nil { + t.Error("Validate() = nil, want an error for a spawnerless gate on a child step") + } + }) +} + // TestValidate_WaitsForChildrenOf tests the children-of(step) syntax (gt-8tmz.38) func TestValidate_WaitsForChildrenOf(t *testing.T) { // Valid children-of() syntax diff --git a/internal/formula/schema_gen.go b/internal/formula/schema_gen.go index c7a0b9524..08a9fe3b6 100644 --- a/internal/formula/schema_gen.go +++ b/internal/formula/schema_gen.go @@ -705,7 +705,10 @@ Either Needs or DependsOn can be used; they are merged during cooking.`, JSONName: "waits_for", Doc: `WaitsFor specifies a fanout gate type for this step. Values: "all-children" (wait for all dynamic children) or "any-children" (wait for first). -When set, the cooked issue gets a "gate:" label.`, +When set, the cooked issue gets a "gate:" label. +Requires needs: the gate waits on the children of the +step it names, so with nothing to name there is nothing to wait for and +the cooked gate would carry the label but no dependency edge at all.`, }, { Name: "Assignee", diff --git a/internal/formula/types.go b/internal/formula/types.go index 0ae217469..e5d25969e 100644 --- a/internal/formula/types.go +++ b/internal/formula/types.go @@ -28,10 +28,17 @@ package formula import ( + "errors" "fmt" "strings" ) +// ErrValidation wraps a formula validation failure so callers with a fallback +// resolution path (e.g. "is this actually a proto/issue ID rather than a +// formula name?") can tell "not a formula" from "is a formula, but it does not +// validate" with errors.Is, instead of reporting the latter as not found. +var ErrValidation = errors.New("formula validation failed") + // FormulaType categorizes formulas by their purpose. type FormulaType string @@ -234,6 +241,9 @@ type Step struct { // WaitsFor specifies a fanout gate type for this step. // Values: "all-children" (wait for all dynamic children) or "any-children" (wait for first). // When set, the cooked issue gets a "gate:" label. + // Requires needs: the gate waits on the children of the + // step it names, so with nothing to name there is nothing to wait for and + // the cooked gate would carry the label but no dependency edge at all. WaitsFor string `json:"waits_for,omitempty" toml:"waits_for,omitempty"` // Assignee is the default assignee (supports substitution). @@ -630,7 +640,7 @@ func (f *Formula) Validate() error { // Validate waits_for field // Valid formats: "all-children", "any-children", "children-of(step-id)" if step.WaitsFor != "" { - if err := validateWaitsFor(step.WaitsFor, stepIDLocations); err != nil { + if err := validateWaitsFor(step.WaitsFor, stepIDLocations, step.Needs); err != nil { errs = append(errs, fmt.Sprintf("steps[%d] (%s): %s", i, step.ID, err.Error())) } } @@ -674,7 +684,7 @@ func (f *Formula) Validate() error { } if len(errs) > 0 { - return fmt.Errorf("formula validation failed:\n - %s", strings.Join(errs, "\n - ")) + return fmt.Errorf("%w:\n - %s", ErrValidation, strings.Join(errs, "\n - ")) } return nil @@ -747,9 +757,17 @@ func ParseWaitsFor(value string) *WaitsForSpec { // - "all-children": wait for all dynamically-bonded children // - "any-children": wait for first child to complete // - "children-of(step-id)": wait for children of a specific step -func validateWaitsFor(value string, stepIDLocations map[string]string) error { +// +// The bare gates name no spawner, so cooking infers one from needs[0] and emits +// no dependency at all when there is nothing to infer from. A step that gates on +// nothing is rejected here rather than cooked into a step that carries a +// gate: label, waits for no one and is immediately ready. +func validateWaitsFor(value string, stepIDLocations map[string]string, needs []string) error { // Simple gate types if value == "all-children" || value == "any-children" { + if len(needs) == 0 { + return fmt.Errorf("waits_for %q waits for the children of needs[0], but this step declares no needs (add needs, or name the spawner with children-of(step-id))", value) + } return nil } @@ -785,7 +803,7 @@ func validateChildDependsOn(children []*Step, idLocations map[string]string, err } // Validate waits_for field if child.WaitsFor != "" { - if err := validateWaitsFor(child.WaitsFor, idLocations); err != nil { + if err := validateWaitsFor(child.WaitsFor, idLocations, child.Needs); err != nil { *errs = append(*errs, fmt.Sprintf("%s (%s): %s", childPrefix, child.ID, err.Error())) } } diff --git a/internal/formula/validation_sentinel_test.go b/internal/formula/validation_sentinel_test.go new file mode 100644 index 000000000..62177be1e --- /dev/null +++ b/internal/formula/validation_sentinel_test.go @@ -0,0 +1,48 @@ +package formula + +import ( + "errors" + "strings" + "testing" +) + +// A caller that falls back to a proto/issue lookup when a name is not a formula +// needs to tell "not a formula" from "is a formula, but invalid"; otherwise an +// invalid formula is reported as not found and its real error never surfaces. +func TestValidateErrorIsErrValidation(t *testing.T) { + f := &Formula{ + Formula: "mol-invalid", + Version: 1, + Type: TypeWorkflow, + Steps: []*Step{ + {ID: "step1", Title: "Step 1", WaitsFor: "totally-bogus"}, + }, + } + + err := f.Validate() + if err == nil { + t.Fatal("Validate() = nil, want an error") + } + if !errors.Is(err, ErrValidation) { + t.Errorf("errors.Is(err, ErrValidation) = false for %v", err) + } +} + +func TestValidateErrorKeepsItsMessage(t *testing.T) { + f := &Formula{ + Formula: "mol-invalid", + Version: 1, + Type: TypeWorkflow, + Steps: []*Step{ + {ID: "step1", Title: "Step 1", WaitsFor: "totally-bogus"}, + }, + } + + err := f.Validate() + if err == nil { + t.Fatal("Validate() = nil, want an error") + } + if got := err.Error(); !strings.HasPrefix(got, "formula validation failed") { + t.Errorf("Validate() error = %q, want it to still open with the original text", got) + } +}