diff --git a/CHANGELOG.md b/CHANGELOG.md index e2f6684ee..28cbd3d10 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -867,6 +867,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 enable it where a firewall, private interface, or tunnel bounds who can reach the port. +- **`bd mol pour` and `bd mol wisp` now reject a `--var` name the proto cannot + consume, instead of dropping it silently.** An unusable name was accepted and + ignored, which turned a typo in an optional var into a conditional step that + quietly never appeared, or a defaulted var that quietly kept its default - + with a successful exit and no output to suggest otherwise. A name is accepted + if any proto being poured declares it, references it as a `{{handlebar}}` in + any field the pour substitutes - the prose fields, `assignee`, `labels`, a + gate's `await_id`, and every string value in its metadata - references it + from a step `condition` or from a step that `condition` removed, or uses it + as a `{name}` placeholder that a standalone `type = "expansion"` formula + substitutes as it builds its steps from `[[template]]`. The last + three matter because the condition filter and the `[[template]]` expansion + both run before the cook, and nothing in the cooked subgraph records + the names they consume or drop; collecting them ahead of the filter + also keeps a name's validity a property of the formula rather than of + another var's value. Anything left over cannot affect the pour, so it + is reported: `unknown variables: has_spke (available: has_spike, story)`. A + var belonging to an `--attach` proto still passes, as do a proto's + documentation handlebars. The refusal applies only where the declared-var set + is fully known, which means a proto cooked from a formula: a proto loaded from + the database (`bd cook --persist` output, and every `--attach` proto) no + longer has its `[vars]` declarations, so a declared-but-unreferenced name is + indistinguishable from a typo and nothing is refused for that pour rather than + risk breaking one that works. Out of scope for now: `bd mol bond --var` and + `bd mol seed --var` go through `formula.ValidateProvidedVars`, which only + iterates declared vars, so they still drop an unknown name silently. Also + fixed alongside: the missing-var hint printed `--var =` when there was + no missing var to name. + - **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, diff --git a/cmd/bd/BUILD.bazel b/cmd/bd/BUILD.bazel index e6045c935..7c9261123 100644 --- a/cmd/bd/BUILD.bazel +++ b/cmd/bd/BUILD.bazel @@ -957,6 +957,8 @@ go_test( "orphans_test.go", "output_test.go", "pour_proxied_integration_test.go", + "pour_unknown_vars_pipeline_test.go", + "pour_unknown_vars_test.go", "pour_wisp_var_validation_test.go", "preflight_test.go", "prime_divergence_test.go", diff --git a/cmd/bd/cook.go b/cmd/bd/cook.go index f278c4c4f..d76422c97 100644 --- a/cmd/bd/cook.go +++ b/cmd/bd/cook.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "fmt" + "sort" "strings" "time" @@ -774,6 +775,20 @@ func resolveAndCookFormulaWithVars(formulaName string, searchPaths []string, con } } + // Record which variables the formula's steps reference, before the filter + // below removes steps. Both a condition var and a handlebar that lives only + // inside a dropped step leave no trace in the cooked subgraph, so this is + // the only point at which those names are still visible. Collected + // unconditionally: the names are a property of the formula, not of this + // pour's --var values. + formulaVarNames := formulaVarRefs(resolved.Steps) + // A standalone expansion formula's steps are materialized from its template + // below, against this synthetic target, and that substitutes --var values + // into the template's {name} placeholders as it builds them: a name used + // only there is consumed without leaving a trace either. + const expansionTarget = "main" + formulaVarNames = append(formulaVarNames, formula.ExpansionVarRefs(resolved, expansionTarget)...) + // Apply step condition filtering if vars provided (bd-7zka.1) // This filters out steps whose conditions evaluate to false if conditionVars != nil { @@ -811,13 +826,83 @@ func resolveAndCookFormulaWithVars(formulaName string, searchPaths []string, con expansionVars[k] = v } } - if err := formula.MaterializeExpansion(resolved, "main", expansionVars); err != nil { + if err := formula.MaterializeExpansion(resolved, expansionTarget, expansionVars); err != nil { return nil, fmt.Errorf("standalone expansion %q: %w", formulaName, err) } } // Cook to in-memory subgraph, including variable definitions for default handling - return cookFormulaToSubgraphWithVars(resolved, resolved.Formula, resolved.Vars) + subgraph, err := cookFormulaToSubgraphWithVars(resolved, resolved.Formula, resolved.Vars) + if err != nil { + return nil, err + } + subgraph.FormulaVarRefs = formulaVarNames + return subgraph, nil +} + +// formulaVarRefs returns the variable names the steps reference, walking +// children, deduplicated and sorted. Call it on the UNFILTERED steps: every +// name it finds can be erased by formula.FilterStepsByCondition. +// +// Two kinds of reference are collected, and both are consumable: +// +// - step conditions, which the filter consumes and never copies to an issue +// field. These are handlebar expressions - `{{spike}}`, `!{{spike}}`, +// `{{env}} == "prod"` (internal/formula/stepcondition.go) - so the same +// extractor the substitutable fields use finds their names. +// - the substitutable fields of the steps themselves - prose, assignee, +// labels and metadata values - which vanish when the filter drops the +// step. Without them, `--var deploy=false --var deploy_target=prod` would +// reject deploy_target while `deploy=true` accepted it, making one name's +// validity depend on another name's value. +// +// The step fields read here are the ones processStepToIssue copies into a +// substituted issue field, plus the gate fields createGateIssue derives from +// step.Gate; keep them in sync with those two functions and with +// substitutedIssueFields, which is the same question asked of a cooked issue. +func formulaVarRefs(steps []*formula.Step) []string { + seen := make(map[string]bool) + var walk func([]*formula.Step) + walk = func(ss []*formula.Step) { + for _, step := range ss { + if step == nil { + continue + } + texts := []string{step.Condition, step.Title, step.Description, step.Notes, step.Assignee} + texts = append(texts, step.Labels...) + // processStepToIssue carries the metadata onto the issue as JSON, + // and the pour substitutes every string value in it but never a + // key, so read it back the way substitutedIssueFields does. + if len(step.Metadata) > 0 { + if metaJSON, err := json.Marshal(step.Metadata); err == nil { + texts = append(texts, metadataVarStrings(metaJSON)...) + } + } + if step.Gate != nil { + // createGateIssue mirrors the awaitID into the gate issue's + // Title and AwaitID, and writes Repo to metadata.repo only for + // gh:* gate types. + texts = append(texts, gateAwaitID(step.Gate)) + if isGitHubGateType(step.Gate.Type) { + texts = append(texts, step.Gate.Repo) + } + } + for _, text := range texts { + for _, name := range extractVariables(text) { + seen[name] = true + } + } + walk(step.Children) + } + } + walk(steps) + + names := make([]string, 0, len(seen)) + for name := range seen { + names = append(names, name) + } + sort.Strings(names) + return names } // cookFormulaToSubgraphWithVars creates an in-memory subgraph with variable info attached @@ -826,6 +911,13 @@ func cookFormulaToSubgraphWithVars(f *formula.Formula, protoID string, vars map[ if err != nil { return nil, err } + // The formula is in hand here, so whatever VarDefs ends up being IS its + // complete declared-variable set - including the nil map a formula with no + // [vars] section produces. Persistence is what loses the declarations, so + // only this path may claim they are known (see TemplateSubgraph. + // DeclaredVarsKnown). + subgraph.DeclaredVarsKnown = true + // Attach variable definitions to the subgraph for default handling during pour // Convert from *VarDef to VarDef for simpler handling if vars != nil { diff --git a/cmd/bd/pour.go b/cmd/bd/pour.go index 5b3b628fd..91aa946eb 100644 --- a/cmd/bd/pour.go +++ b/cmd/bd/pour.go @@ -4,6 +4,7 @@ import ( "errors" "fmt" "os" + "sort" "strings" "github.com/spf13/cobra" @@ -185,7 +186,7 @@ func runPour(cmd *cobra.Command, args []string) error { attachSubgraphs = append(attachSubgraphs, a.subgraph) } if err := checkPourVars(subgraph, attachSubgraphs, vars); err != nil { - return HandleErrorWithHint(err.Error(), fmt.Sprintf("Provide them with: --var %s=", missingVarHint(subgraph, attachSubgraphs, vars))) + return handleVarErrorWithHint(err, missingVarHint(subgraph, attachSubgraphs, vars)) } if in.dryRun { @@ -261,7 +262,113 @@ func checkPourVars(subgraph *TemplateSubgraph, attachSubgraphs []*TemplateSubgra if len(missingVars) > 0 { return fmt.Errorf("missing required variables: %s", strings.Join(missingVars, ", ")) } - return nil + return checkUnknownVars(subgraph, attachSubgraphs, vars) +} + +// checkUnknownVars rejects --var names the protos being poured cannot consume. +// A name is accepted if any proto declares it in [vars], references it as a +// {{handlebar}} in a field the pour substitutes (including the assignee, +// labels, a gate's AwaitID and metadata values), references it from a step +// condition, or - in a standalone expansion formula - uses it as a {name} +// placeholder in the template; so documentation handlebars and vars belonging +// to an --attach proto still pass. What is left over cannot affect the pour, and silently dropping it +// turns a typo in an optional var into a conditional step that quietly never +// appears. +// +// The check applies only when the known set is complete - see knownVarsAcross. +// Where it is not, no name is refused at all: a wrong refusal breaks a pour that +// works, which is worse than the silent drop this replaces. +func checkUnknownVars(subgraph *TemplateSubgraph, attachSubgraphs []*TemplateSubgraph, vars map[string]string) error { + known, complete := knownVarsAcross(subgraph, attachSubgraphs) + if !complete { + return nil + } + + var unknown []string + for name := range vars { + if !known[name] { + unknown = append(unknown, name) + } + } + if len(unknown) == 0 { + return nil + } + sort.Strings(unknown) + + knownNames := make([]string, 0, len(known)) + for name := range known { + knownNames = append(knownNames, name) + } + sort.Strings(knownNames) + + if len(knownNames) == 0 { + return fmt.Errorf("unknown variables: %s (this proto takes no variables)", strings.Join(unknown, ", ")) + } + return fmt.Errorf("unknown variables: %s (available: %s)", strings.Join(unknown, ", "), strings.Join(knownNames, ", ")) +} + +// knownVarsAcross returns the variable names the protos being poured can +// consume, and whether that set is COMPLETE. +// +// It is incomplete as soon as one participating proto was loaded from the +// database instead of cooked from a formula. Persistence keeps the issues but +// not the formula, so VarDefs is gone and all that survives is the handlebars +// visible in issue text: a variable the formula declared in [vars] but never +// wrote into a substituted field is then indistinguishable from a typo, and +// refusing it would reject a --var the pour does consume. That covers every +// `bd cook --persist` proto and every --attach proto, which is always DB-loaded. +func knownVarsAcross(subgraph *TemplateSubgraph, attachSubgraphs []*TemplateSubgraph) (map[string]bool, bool) { + known := make(map[string]bool) + complete := true + add := func(sg *TemplateSubgraph) { + if sg == nil { + return + } + if !sg.DeclaredVarsKnown { + complete = false + } + for name := range sg.VarDefs { + known[name] = true + } + // Every field the clone substitutes, not just the prose: the + // assignee, labels, a gate's await_id and every metadata value carry + // handlebars that the pour fills in, so names appearing only there + // are consumable too. + for _, name := range extractConsumableVariables(sg) { + known[name] = true + } + // Names the formula referenced that were consumed or erased before the + // cook - a step condition, the text of a step the condition filter + // dropped, or a standalone expansion template's {name} placeholder. All + // are consumable: a condition decides which steps get poured at all, + // dropped text must not stop being valid just because another var + // switched its step off, and a placeholder was substituted while the + // steps were being built. + for _, name := range sg.FormulaVarRefs { + known[name] = true + } + } + + add(subgraph) + for _, attachSubgraph := range attachSubgraphs { + add(attachSubgraph) + } + return known, complete +} + +// handleVarErrorWithHint reports a --var error, attaching the "Provide them +// with" hint only when there is a name to put in it. An unknown-var error has no +// missing name to suggest, and an unguarded hint renders as the nonsense +// `--var =`. +// +// Shared by every route that reports one of these errors (bd mol pour, bd mol +// wisp, and the proxied wisp server) so the guard cannot be dropped at one site +// while the others keep it. +func handleVarErrorWithHint(err error, hint string) error { + if hint != "" { + return HandleErrorWithHint(err.Error(), fmt.Sprintf("Provide them with: --var %s=", hint)) + } + return HandleError("%v", err) } func missingVarHint(subgraph *TemplateSubgraph, attachSubgraphs []*TemplateSubgraph, vars map[string]string) string { @@ -318,7 +425,7 @@ func renderPourResult(result *InstantiateResult, totalAttached, attachCount int) func init() { // Pour command flags - pourCmd.Flags().StringArray("var", []string{}, "Variable substitution (key=value)") + pourCmd.Flags().StringArray("var", []string{}, "Variable substitution (key=value); a name the proto cannot consume is an error") pourCmd.Flags().Bool("dry-run", false, "Preview what would be created") pourCmd.Flags().String("assignee", "", "Assign the root issue to this agent/user") pourCmd.Flags().StringSlice("attach", []string{}, "Proto to attach after spawning (repeatable)") diff --git a/cmd/bd/pour_unknown_vars_pipeline_test.go b/cmd/bd/pour_unknown_vars_pipeline_test.go new file mode 100644 index 000000000..21598915c --- /dev/null +++ b/cmd/bd/pour_unknown_vars_pipeline_test.go @@ -0,0 +1,327 @@ +package main + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +// has_spike appears ONLY in a step condition: it is not declared in [vars] and +// no issue field references it. spike_area appears ONLY in the text of the step +// that same condition can remove, so it is undeclared too and survives into the +// cooked subgraph only while has_spike is truthy. +const conditionVarFormula = `formula = "condvar-pour" +version = 1 +type = "workflow" + +[vars.story] +required = true + +[[steps]] +id = "design" +title = "Design {{story}}" +type = "task" + +[[steps]] +id = "spike" +title = "Spike {{spike_area}} first" +type = "task" +condition = "{{has_spike}}" +` + +// writePipelineFormula puts a formula where the cook pipeline will find it. +func writePipelineFormula(t *testing.T, name, body string) string { + t.Helper() + dir := filepath.Join(t.TempDir(), "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) + } + return dir +} + +// The unknown-var check runs against a subgraph produced by the REAL cook +// pipeline, which is where its known set is actually assembled. +// +// The unit tests above hand-build subgraphs, so they cannot see the ordering +// that matters most here: formula.FilterStepsByCondition consumes step +// conditions and drops the steps carrying them BEFORE the cook, so a var used +// only in a condition leaves no trace in the cooked subgraph. cook records +// those names ahead of the filter for exactly this reason. +// +// Pouring with the condition var set to a FALSEY value is the case that +// regresses if the collection ever moves after the filter: the step is gone, +// and the var that removed it must still count as consumable. Reviewing this +// fix, that was the case a plausible-looking fix one call later would have +// missed. +func TestCookedSubgraphAcceptsAVarUsedOnlyByAStepCondition(t *testing.T) { + searchPaths := []string{writePipelineFormula(t, "condvar-pour", conditionVarFormula)} + + for _, spike := range []string{"true", "false"} { + t.Run("has_spike_"+spike, func(t *testing.T) { + vars := map[string]string{"story": "s1", "has_spike": spike} + + subgraph, err := resolveAndCookFormulaWithVars("condvar-pour", searchPaths, vars) + if err != nil { + t.Fatalf("cook: %v", err) + } + // The premise of the falsey case: the step really is gone, so + // nothing in the subgraph mentions has_spike any more. + if spike == "false" { + for _, issue := range subgraph.Issues { + if strings.Contains(issue.Title, "Spike") { + t.Fatalf("the conditional step survived a falsey condition, so this case is not testing the ordering: %q", issue.Title) + } + } + } + + if err := checkPourVars(subgraph, nil, applyVariableDefaults(vars, subgraph)); err != nil { + t.Errorf("pour rejected a var its own step condition consumes (has_spike=%s): %v", spike, err) + } + }) + } + + // A var referenced only inside the step the condition removes must not lose + // its validity when that step goes: otherwise `--var has_spike=false --var + // spike_area=parser` fails while `has_spike=true` succeeds, and whether a + // name is accepted depends on another name's VALUE. The falsey case is the + // one that regresses if collection ever moves after the filter. + for _, spike := range []string{"true", "false"} { + t.Run("dropped_step_text_var_has_spike_"+spike, func(t *testing.T) { + vars := map[string]string{"story": "s1", "has_spike": spike, "spike_area": "parser"} + + subgraph, err := resolveAndCookFormulaWithVars("condvar-pour", searchPaths, vars) + if err != nil { + t.Fatalf("cook: %v", err) + } + if spike == "false" { + for _, issue := range subgraph.Issues { + if strings.Contains(issue.Title, "spike_area") { + t.Fatalf("the conditional step survived, so this case is not testing the dropped-step path: %q", issue.Title) + } + } + } + + if err := checkPourVars(subgraph, nil, applyVariableDefaults(vars, subgraph)); err != nil { + t.Errorf("pour rejected a var referenced only by a step it dropped (has_spike=%s): %v", spike, err) + } + }) + } + + // The condition var widens the known set; it does not disable the check. + t.Run("typo_in_the_condition_var_is_still_rejected", func(t *testing.T) { + vars := map[string]string{"story": "s1", "has_spke": "true"} + + subgraph, err := resolveAndCookFormulaWithVars("condvar-pour", searchPaths, vars) + if err != nil { + t.Fatalf("cook: %v", err) + } + + err = checkPourVars(subgraph, nil, applyVariableDefaults(vars, subgraph)) + if err == nil { + t.Fatal("pour accepted a typo'd var name") + } + if !strings.Contains(err.Error(), "has_spke") { + t.Errorf("error does not name the unusable var: %v", err) + } + // The real name has to be offered, which is the whole point of + // carrying condition vars into the known set. + if !strings.Contains(err.Error(), "has_spike") { + t.Errorf("error does not offer the condition var among the available names: %v", err) + } + }) +} + +// run_id and gate_repo appear ONLY in the gate of a step that deploy can +// remove, and neither is declared in [vars]. createGateIssue turns that gate +// into its own issue - await_id mirrored into its title and AwaitID, and a +// gh:* gate's repo selector into metadata.repo - which goes with the step. +const gateVarFormula = `formula = "gatevar-pour" +version = 1 +type = "workflow" + +[[steps]] +id = "build" +title = "Build" +type = "task" + +[[steps]] +id = "await-ci" +title = "Wait for CI" +type = "task" +condition = "{{deploy}}" + +[steps.gate] +type = "gh:run" +await_id = "{{run_id}}" +repo = "{{gate_repo}}" +` + +// A var referenced only by the GATE of a step the condition filter drops stays +// consumable, for the same reason dropped step text does: otherwise whether +// run_id is accepted would depend on deploy's value. cook reads a step's gate +// fields ahead of the filter along with its text, and the falsey case is the +// one that regresses if it ever stops - the gate issue is gone, so nothing +// else in the subgraph names either var. +func TestCookedSubgraphAcceptsAVarUsedOnlyByADroppedStepsGate(t *testing.T) { + searchPaths := []string{writePipelineFormula(t, "gatevar-pour", gateVarFormula)} + + for _, deploy := range []string{"true", "false"} { + t.Run("deploy_"+deploy, func(t *testing.T) { + vars := map[string]string{"deploy": deploy, "run_id": "ci.yml", "gate_repo": "octo/app"} + + subgraph, err := resolveAndCookFormulaWithVars("gatevar-pour", searchPaths, vars) + if err != nil { + t.Fatalf("cook: %v", err) + } + // The premise, both ways: the gate issue exists exactly while + // its step does. + gates := 0 + for _, issue := range subgraph.Issues { + if issue.AwaitType != "" { + gates++ + } + } + if want := map[string]int{"true": 1, "false": 0}[deploy]; gates != want { + t.Fatalf("deploy=%s cooked %d gate issues, want %d, so this case is not testing the dropped-gate path", deploy, gates, want) + } + + if err := checkPourVars(subgraph, nil, applyVariableDefaults(vars, subgraph)); err != nil { + t.Errorf("pour rejected a var referenced only by a step's gate (deploy=%s): %v", deploy, err) + } + }) + } +} + +// release_owner, release_train and change_ticket appear ONLY in the assignee, a +// label and a nested metadata value of the step deploy can remove, and none is +// declared in [vars]. The pour substitutes all three fields (GH#5110, +// GH#5754), but no prose field mirrors them. +const fieldVarFormula = `formula = "fieldvar-pour" +version = 1 +type = "workflow" + +[[steps]] +id = "build" +title = "Build" +type = "task" + +[[steps]] +id = "release" +title = "Release" +type = "task" +condition = "{{deploy}}" +assignee = "{{release_owner}}" +labels = ["train:{{release_train}}"] +metadata = { change = { ticket = "{{change_ticket}}" } } +` + +// A var referenced only by the assignee, a label or a metadata value of a step +// the condition filter drops stays consumable too: cook reads those fields +// ahead of the filter along with the step's text, and the falsey case is the +// one that regresses if it ever stops - the step is gone, so nothing else in +// the subgraph names any of the three. +func TestCookedSubgraphAcceptsAVarUsedOnlyByADroppedStepsNonProseFields(t *testing.T) { + searchPaths := []string{writePipelineFormula(t, "fieldvar-pour", fieldVarFormula)} + + for _, deploy := range []string{"true", "false"} { + t.Run("deploy_"+deploy, func(t *testing.T) { + vars := map[string]string{"deploy": deploy, "release_owner": "alice", "release_train": "r42", "change_ticket": "CHG-7"} + + subgraph, err := resolveAndCookFormulaWithVars("fieldvar-pour", searchPaths, vars) + if err != nil { + t.Fatalf("cook: %v", err) + } + // The premise, both ways: the release step - and with it every + // field naming these vars - exists exactly while deploy is truthy. + released := false + for _, issue := range subgraph.Issues { + if issue.Title != "Release" { + continue + } + released = true + if issue.Assignee == "" || len(issue.Labels) == 0 || len(issue.Metadata) == 0 { + t.Fatalf("the release step lost its assignee, labels or metadata in the cook, so this case is not testing them: %+v", issue) + } + } + if released != (deploy == "true") { + t.Fatalf("deploy=%s cooked the release step = %v, so this case is not testing the dropped-step path", deploy, released) + } + + if err := checkPourVars(subgraph, nil, applyVariableDefaults(vars, subgraph)); err != nil { + t.Errorf("pour rejected a var referenced only by a step's assignee, label or metadata (deploy=%s): %v", deploy, err) + } + }) + } +} + +// A standalone expansion formula has no [[steps]]: formula.MaterializeExpansion +// builds them from its [[template]] before the cook, substituting --var values +// into the template's single-brace {name} placeholders as it goes. component +// is not declared in [vars], so once it has been substituted nothing in the +// cooked subgraph - no issue field, not VarDefs - names it any more. +const expansionVarFormula = `formula = "expansion-pour" +version = 1 +type = "expansion" + +[[template]] +id = "{target}.build" +title = "Build {component}" +type = "task" +` + +// A var that a standalone expansion formula's template consumes is accepted, +// even though consuming it is what erased every trace of it: like a step +// condition, the placeholder is used up before the cook, so cook has to record +// the name ahead of time. That widens the known set without disabling the +// check - a typo is still refused, and offered the real name. +func TestCookedSubgraphAcceptsAVarAStandaloneExpansionTemplateConsumes(t *testing.T) { + searchPaths := []string{writePipelineFormula(t, "expansion-pour", expansionVarFormula)} + + t.Run("template_placeholder_var", func(t *testing.T) { + vars := map[string]string{"component": "api"} + + subgraph, err := resolveAndCookFormulaWithVars("expansion-pour", searchPaths, vars) + if err != nil { + t.Fatalf("cook: %v", err) + } + // The premise: the template really did consume the var before the + // cook, so the subgraph no longer mentions it. + consumed := false + for _, issue := range subgraph.Issues { + if issue.Title == "Build api" { + consumed = true + } + } + if !consumed { + t.Fatal("the template did not substitute component, so this case is not testing a consumed var") + } + + if err := checkPourVars(subgraph, nil, applyVariableDefaults(vars, subgraph)); err != nil { + t.Errorf("pour rejected a var the expansion template consumed: %v", err) + } + }) + + t.Run("typo_is_still_rejected", func(t *testing.T) { + vars := map[string]string{"componnet": "api"} + + subgraph, err := resolveAndCookFormulaWithVars("expansion-pour", searchPaths, vars) + if err != nil { + t.Fatalf("cook: %v", err) + } + + err = checkPourVars(subgraph, nil, applyVariableDefaults(vars, subgraph)) + if err == nil { + t.Fatal("pour accepted a typo'd var name") + } + if !strings.Contains(err.Error(), "componnet") { + t.Errorf("error does not name the unusable var: %v", err) + } + if !strings.Contains(err.Error(), "available: component") { + t.Errorf("error does not offer the template's placeholder among the available names: %v", err) + } + }) +} diff --git a/cmd/bd/pour_unknown_vars_test.go b/cmd/bd/pour_unknown_vars_test.go new file mode 100644 index 000000000..7620b3aa0 --- /dev/null +++ b/cmd/bd/pour_unknown_vars_test.go @@ -0,0 +1,354 @@ +package main + +import ( + "encoding/json" + "strconv" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/formula" + "github.com/steveyegge/beads/internal/types" +) + +// varSubgraph models a proto COOKED FROM A FORMULA: DeclaredVarsKnown is what +// the cook stamps, and it is what licenses the refusal at all, so leaving it +// unset here would silently turn every rejection case below into a no-op. +// dbVarSubgraph is the other shape. +func varSubgraph(text string, varDefs map[string]formula.VarDef) *TemplateSubgraph { + return &TemplateSubgraph{ + Issues: []*types.Issue{{ID: "t-1", Title: "step", Description: text}}, + VarDefs: varDefs, + DeclaredVarsKnown: true, + } +} + +// dbVarSubgraph models a proto LOADED FROM THE DATABASE - `bd cook --persist` +// output, or any --attach proto. loadTemplateSubgraph cannot recover the +// formula's [vars], so DeclaredVarsKnown stays false. +func dbVarSubgraph(text string) *TemplateSubgraph { + sg := varSubgraph(text, nil) + sg.DeclaredVarsKnown = false + return sg +} + +// formulaVarRefSubgraph is varSubgraph plus the names the formula referenced +// that the condition filter erased before the cook: a step condition, or the +// text of a step it dropped. cook records these ahead of the filter. +func formulaVarRefSubgraph(text string, varDefs map[string]formula.VarDef, formulaVarRefs ...string) *TemplateSubgraph { + sg := varSubgraph(text, varDefs) + sg.FormulaVarRefs = formulaVarRefs + return sg +} + +// gateVarSubgraph models a cooked proto whose only reference to a var is a GATE +// field: the await_id, or the metadata.repo selector createGateIssue writes for +// a gh:* gate. Neither is a prose field, and neither has to be declared in +// [vars] - but cloneSubgraphInto substitutes both, so both are consumable. +func gateVarSubgraph(awaitType, awaitID, repoSelector string) *TemplateSubgraph { + gate := &types.Issue{ + ID: "t-1.gate-deploy", + Title: "Gate: " + awaitType, + AwaitType: awaitType, + AwaitID: awaitID, + } + if repoSelector != "" { + gate.Metadata = json.RawMessage(`{"repo":` + strconv.Quote(repoSelector) + `}`) + } + return &TemplateSubgraph{ + Issues: []*types.Issue{{ID: "t-1", Title: "root"}, gate}, + DeclaredVarsKnown: true, + } +} + +// issueVarSubgraph models a cooked proto, with no [vars], whose only reference +// to a var is in one of the non-prose fields cloneSubgraphInto substitutes on +// any issue (GH#5110, GH#5754) - the assignee, a label, or a metadata value - +// which the caller sets on step. +func issueVarSubgraph(step *types.Issue) *TemplateSubgraph { + step.ID = "t-1.step" + step.Title = "step" + return &TemplateSubgraph{ + Issues: []*types.Issue{{ID: "t-1", Title: "root"}, step}, + DeclaredVarsKnown: true, + } +} + +func TestCheckPourVarsRejectsUnknownVars(t *testing.T) { + defaulted := map[string]formula.VarDef{"component": {Default: strPtr("core")}} + + tests := []struct { + name string + subgraph *TemplateSubgraph + attached []*TemplateSubgraph + vars map[string]string + wantErr bool + wantInError []string + }{ + { + name: "declared var is accepted", + subgraph: varSubgraph("build {{component}}", defaulted), + vars: map[string]string{"component": "rule"}, + }, + { + name: "var referenced only as a handlebar is accepted", + subgraph: varSubgraph("notes for {{reviewer}}", defaulted), + vars: map[string]string{"reviewer": "harry"}, + }, + { + name: "var belonging to an attached proto is accepted", + subgraph: varSubgraph("build {{component}}", defaulted), + attached: []*TemplateSubgraph{varSubgraph("deploy to {{cluster}}", nil)}, + vars: map[string]string{"component": "rule", "cluster": "prod"}, + }, + { + name: "typo in a defaulted var is rejected", + subgraph: varSubgraph("build {{component}}", defaulted), + vars: map[string]string{"compnent": "rule"}, + wantErr: true, + wantInError: []string{"compnent", "component"}, + }, + { + name: "proto with no variables at all", + subgraph: varSubgraph("no placeholders here", nil), + vars: map[string]string{"anything": "x"}, + wantErr: true, + wantInError: []string{"anything", "takes no variables"}, + }, + { + name: "unknown vars are reported together and sorted", + subgraph: varSubgraph("build {{component}}", defaulted), + vars: map[string]string{"zeta": "1", "alpha": "2"}, + wantErr: true, + wantInError: []string{"alpha, zeta"}, + }, + { + // A var used only in a step condition appears in no issue field + // and need not be declared in [vars], but it decides which steps + // get poured at all - so it is consumable, and rejecting it would + // fail a pour the var demonstrably changes. + name: "var referenced only by a step condition is accepted", + subgraph: formulaVarRefSubgraph("build {{component}}", defaulted, "has_spike"), + vars: map[string]string{"component": "rule", "has_spike": "true"}, + }, + { + // The condition var widens the known set; it does not disable the + // check. A typo in it is still unusable. + name: "typo in a condition var is still rejected", + subgraph: formulaVarRefSubgraph("build {{component}}", defaulted, "has_spike"), + vars: map[string]string{"has_spke": "true"}, + wantErr: true, + wantInError: []string{"has_spke", "has_spike"}, + }, + { + // A handlebar living only inside a step the condition filter + // dropped is still the formula's, so its name stays valid - a var + // must not become unusable because another var's VALUE switched its + // step off. + name: "var referenced only by a filtered-out step is accepted", + subgraph: formulaVarRefSubgraph("build {{component}}", defaulted, "deploy", "deploy_target"), + vars: map[string]string{"deploy": "false", "deploy_target": "prod"}, + }, + { + // cloneSubgraphInto substitutes AwaitID, so a name that appears + // only in a gate's await_id is consumed by the pour. createGateIssue + // normally also mirrors the awaitID into the gate Title, which would + // make this pass through the prose path; the Title here carries no + // mirror (a hand-edited or pre-format proto) so the case pins the + // direct AwaitID read instead. + name: "var referenced only by a gate await_id is accepted", + subgraph: gateVarSubgraph("gh:pr", "{{pr_number}}", ""), + vars: map[string]string{"pr_number": "5762"}, + }, + { + // ...and so is metadata.repo on a gh:* gate, which is the arm with + // no mirror anywhere else on the issue: createGateIssue stores the + // selector literally and substituteMetadataVars fills it at clone + // time. + name: "var referenced only by a gh gate metadata.repo is accepted", + subgraph: gateVarSubgraph("gh:run", "12345", "{{gate_repo}}"), + vars: map[string]string{"gate_repo": "owner/repo"}, + }, + { + // The gate fields widen the known set; they do not disable the + // check. (With no [vars], gate_repo is also REQUIRED - the + // required-var check reads metadata values too - so it is supplied + // alongside the typo, or the missing-var error would fire first.) + name: "typo against a gate-only proto is still rejected", + subgraph: gateVarSubgraph("gh:run", "12345", "{{gate_repo}}"), + vars: map[string]string{"gate_repo": "owner/repo", "gate_rpo": "owner/repo"}, + wantErr: true, + wantInError: []string{"gate_rpo", "gate_repo"}, + }, + { + // `repo` on a non-gh gate is ordinary metadata, not a repo + // selector - but the pour substitutes every metadata string value + // whatever the gate type (#5758 superseded the gh:*-only rule), so + // a name used there is consumed. Refusing it would be a closed + // loop: with no [vars], the required-var check demands the very + // name this check would refuse, and the proto can never be poured. + name: "repo on a non-github gate is substituted like any metadata value", + subgraph: gateVarSubgraph("human", "sign-off", "{{gate_repo}}"), + vars: map[string]string{"gate_repo": "owner/repo"}, + }, + { + // The same holds on any issue for every non-prose field the pour + // substitutes: a name used only in the assignee... + name: "var referenced only by an assignee is accepted", + subgraph: issueVarSubgraph(&types.Issue{Assignee: "{{owner}}"}), + vars: map[string]string{"owner": "alice"}, + }, + { + // ...only in a label... + name: "var referenced only by a label is accepted", + subgraph: issueVarSubgraph(&types.Issue{Labels: []string{"area:{{area}}"}}), + vars: map[string]string{"area": "parser"}, + }, + { + // ...or only in a metadata value, at any depth. + name: "var referenced only by a nested metadata value is accepted", + subgraph: issueVarSubgraph(&types.Issue{Metadata: json.RawMessage(`{"owner":{"teams":["{{team}}"]}}`)}), + vars: map[string]string{"team": "core"}, + }, + { + // substituteMetadataVars never rewrites an object KEY, so a name + // that appears only in one is not consumable and must still be + // refused. This is the polarity that keeps the read side honest + // about WHICH metadata strings the pour substitutes. + name: "var referenced only by a metadata key is rejected", + subgraph: issueVarSubgraph(&types.Issue{Metadata: json.RawMessage(`{"{{team}}":"core"}`)}), + vars: map[string]string{"team": "core"}, + wantErr: true, + wantInError: []string{"team", "takes no variables"}, + }, + { + // A DB-loaded proto has no formula behind it, so its [vars] + // declarations are gone: a declared var that was never written into + // a substituted field cannot be told apart from a typo, and + // refusing it would break a pour that works today. (Its text + // handlebars are all REQUIRED - the nil-VarDefs legacy path in + // extractRequiredVariables - so component must be supplied; the + // point of the case is gate_repo, which nothing in the subgraph + // mentions.) + name: "db-loaded proto accepts a name it cannot vouch for", + subgraph: dbVarSubgraph("build {{component}}"), + vars: map[string]string{"component": "core", "gate_repo": "owner/repo"}, + }, + { + // One DB-loaded --attach proto is enough: the name could belong to + // it, so no name in the pour can be refused. + name: "a db-loaded attachment stands the check down for the whole pour", + subgraph: varSubgraph("build {{component}}", defaulted), + attached: []*TemplateSubgraph{dbVarSubgraph("deploy to {{cluster}}")}, + vars: map[string]string{"cluster": "prod", "anything": "x"}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := checkPourVars(tt.subgraph, tt.attached, tt.vars) + if tt.wantErr && err == nil { + t.Fatalf("checkPourVars() = nil, want an unknown-variable error") + } + if !tt.wantErr { + if err != nil { + t.Fatalf("checkPourVars() = %v, want nil", err) + } + return + } + for _, want := range tt.wantInError { + if !strings.Contains(err.Error(), want) { + t.Errorf("checkPourVars() error = %q, want it to contain %q", err, want) + } + } + }) + } +} + +// A missing required var must still be reported as missing rather than being +// reframed by the unknown-var check, because the caller's hint depends on it. +func TestCheckPourVarsReportsMissingBeforeUnknown(t *testing.T) { + subgraph := varSubgraph("build {{component}}", map[string]formula.VarDef{"component": {}}) + + err := checkPourVars(subgraph, nil, map[string]string{"typo": "x"}) + if err == nil { + t.Fatal("checkPourVars() = nil, want an error") + } + if !strings.Contains(err.Error(), "missing required variables") { + t.Errorf("checkPourVars() error = %q, want the missing-variable error", err) + } +} + +// The hint is only meaningful for a MISSING var, whose name it suggests +// supplying. An unknown-var error has no such name, and the unguarded form this +// PR replaced rendered as `Provide them with: --var =`. All three routes +// share handleVarErrorWithHint, so pinning it here pins every site. +func TestVarErrorHintIsSuppressedWhenThereIsNoNameToSuggest(t *testing.T) { + unknown := checkPourVars(varSubgraph("no placeholders here", nil), nil, map[string]string{"anything": "x"}) + if unknown == nil { + t.Fatal("checkPourVars() = nil, want an unknown-variable error to report") + } + + missing := checkPourVars(varSubgraph("build {{component}}", map[string]formula.VarDef{"component": {}}), nil, nil) + if missing == nil { + t.Fatal("checkPourVars() = nil, want a missing-variable error to report") + } + + tests := []struct { + name string + err error + hint string + wantHint bool + }{ + { + name: "unknown variables carry no hint", + err: unknown, + // What missingVarHint returns when nothing is missing. + hint: "", + wantHint: false, + }, + { + name: "a missing variable still names itself in the hint", + err: missing, + hint: "component", + wantHint: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + stderr := captureStderr(t, func() { + if err := handleVarErrorWithHint(tt.err, tt.hint); err == nil { + t.Error("handleVarErrorWithHint() = nil, want a non-nil exit error") + } + }) + + if !strings.Contains(stderr, tt.err.Error()) { + t.Errorf("stderr = %q, want it to report %q", stderr, tt.err) + } + if got := strings.Contains(stderr, "Provide them with:"); got != tt.wantHint { + t.Errorf("stderr = %q, hint present = %v, want %v", stderr, got, tt.wantHint) + } + if strings.Contains(stderr, "--var =") { + t.Errorf("stderr = %q, want no empty-name hint", stderr) + } + }) + } +} + +// bd mol wisp takes --var through its own check, which must reject an +// unusable name for the same reason bd mol pour does. +func TestCheckRequiredVarsRejectsUnknownVars(t *testing.T) { + subgraph := varSubgraph("build {{component}}", map[string]formula.VarDef{"component": {Default: strPtr("core")}}) + + if err := checkRequiredVars(subgraph, map[string]string{"component": "rule"}); err != nil { + t.Fatalf("checkRequiredVars() = %v, want nil for a declared var", err) + } + + err := checkRequiredVars(subgraph, map[string]string{"compnent": "rule"}) + if err == nil { + t.Fatal("checkRequiredVars() = nil, want an unknown-variable error") + } + if !strings.Contains(err.Error(), "compnent") { + t.Errorf("checkRequiredVars() error = %q, want it to name the unknown var", err) + } +} diff --git a/cmd/bd/template.go b/cmd/bd/template.go index b411ed499..e8ad2d576 100644 --- a/cmd/bd/template.go +++ b/cmd/bd/template.go @@ -41,6 +41,44 @@ type TemplateSubgraph struct { VarDefs map[string]formula.VarDef // Variable definitions from formula (for defaults) Phase string // Recommended phase: "liquid" (pour) or "vapor" (wisp) Pour bool // If true, steps should be materialized as sub-issues (from formula pour=true) + + // FormulaVarRefs names the variables referenced by the formula this + // subgraph was cooked from that may leave no trace in the subgraph itself, + // because they are consumed or erased BEFORE the cook: + // + // - a step condition is consumed by formula.FilterStepsByCondition and is + // never copied to an issue field, and nothing requires a condition var + // to be declared in [vars], so it would appear in neither the issues + // nor VarDefs; + // - the substitutable text of a step the filter DROPPED disappears along + // with the step; + // - a {name} placeholder in a standalone expansion formula's template is + // replaced by its --var value while formula.MaterializeExpansion builds + // the steps, so the name is gone before the cook sees them. + // + // All three are recorded ahead of the filter so the set of variables a + // proto can consume stays a property of the formula rather than of one + // pour's --var values: a var that changes which steps get poured, or that + // is referenced only inside a step the user just switched off, must not be + // reported as one the proto cannot consume. + // + // Empty for a persisted proto loaded from the database, which has no + // formula behind it - its conditions were already resolved at cook time. + FormulaVarRefs []string + + // DeclaredVarsKnown reports whether VarDefs is the formula's complete + // declared-variable set. Only the cook can know that, so only the cook + // sets it (cookFormulaToSubgraphWithVars); a subgraph built any other way + // - loadTemplateSubgraph for a persisted or --attach proto, or a test + // fixture - leaves it false. + // + // It is NOT the same question as `VarDefs != nil`: a cooked formula that + // declares no [vars] at all also has a nil VarDefs, and that proto really + // does take no variables. Persistence, by contrast, drops the declarations + // entirely, so a var the formula declared but never wrote into a + // substituted field becomes indistinguishable from a typo - which is why + // checkUnknownVars stands down rather than guessing when this is false. + DeclaredVarsKnown bool } // InstantiateResult holds the result of template instantiation @@ -367,6 +405,55 @@ func extractAllVariables(subgraph *TemplateSubgraph) []string { return extractVariables(sb.String()) } +// substitutedIssueFields returns every string on a proto issue that +// cloneSubgraphInto substitutes variables into when the proto is poured: the +// prose, the assignee, a gate's AwaitID, each label, and every string value in +// the metadata (GH#5110, GH#5754). +// +// KEEP IN SYNC with cloneSubgraphInto's newIssue literal: it is the write side +// of this read. Any field that gains a substituteVariables call there has to be +// added here in the same commit, or knownVarsAcross under-approximates what a +// pour consumes and checkUnknownVars refuses a --var the clone would have used. +// extractAllVariables reads the same fields for the variables a pour DEMANDS, +// so the two must agree as well: a name demanded there but missing here can +// never be poured, because supplying it is refused. Conversely, anything the +// clone copies verbatim must stay out - naming it would advertise a +// substitution that never happens: AwaitType and IssueType, and every metadata +// object KEY (substituteMetadataVars rewrites string values only, which is all +// metadataVarStrings returns). +func substitutedIssueFields(issue *types.Issue) []string { + if issue == nil { + return nil + } + fields := []string{ + issue.Title, + issue.Description, + issue.Design, + issue.AcceptanceCriteria, + issue.Notes, + issue.Assignee, + issue.AwaitID, + } + fields = append(fields, issue.Labels...) + return append(fields, metadataVarStrings(issue.Metadata)...) +} + +// extractConsumableVariables finds every variable name the subgraph's issues +// can consume at clone time - every field substitutedIssueFields names, not +// just the prose. +func extractConsumableVariables(subgraph *TemplateSubgraph) []string { + if subgraph == nil { + return nil + } + allText := "" + for _, issue := range subgraph.Issues { + for _, field := range substitutedIssueFields(issue) { + allText += field + " " + } + } + return extractVariables(allText) +} + // extractRequiredVariables returns only variables that don't have defaults. // If VarDefs is available (from a cooked formula), uses it to filter out defaulted vars. // Otherwise, falls back to returning all variables. @@ -802,6 +889,10 @@ func cloneSubgraphInto(ctx context.Context, w molWriter, subgraph *TemplateSubgr issueAssignee = opts.Assignee } + // Every field substituted below - and issueAssignee above - is one a + // --var can reach, so substitutedIssueFields must name it too - that + // read side is what checkUnknownVars uses to decide a supplied name is + // usable. newIssue := &types.Issue{ // ID will be set below based on bonding options Title: substituteVariables(oldIssue.Title, opts.Vars), diff --git a/cmd/bd/wisp.go b/cmd/bd/wisp.go index ea5ff1887..32ced536e 100644 --- a/cmd/bd/wisp.go +++ b/cmd/bd/wisp.go @@ -270,7 +270,7 @@ func runWispCreateCore(cmd *cobra.Command, args []string) error { vars = applyVariableDefaults(vars, subgraph) if err := checkRequiredVars(subgraph, vars); err != nil { - return HandleErrorWithHint(err.Error(), fmt.Sprintf("Provide them with: --var %s=", firstMissingVar(subgraph, vars))) + return handleVarErrorWithHint(err, firstMissingVar(subgraph, vars)) } if dryRun { @@ -302,7 +302,7 @@ func checkRequiredVars(subgraph *TemplateSubgraph, vars map[string]string) error if len(missingVars) > 0 { return fmt.Errorf("missing required variables: %s", strings.Join(missingVars, ", ")) } - return nil + return checkUnknownVars(subgraph, nil, vars) } func firstMissingVar(subgraph *TemplateSubgraph, vars map[string]string) string { @@ -998,12 +998,12 @@ func runWispPurgeClosed(ctx context.Context, dryRun bool, force bool, excludeTyp func init() { // Wisp command flags (for direct create: bd mol wisp ) - wispCmd.Flags().StringArray("var", []string{}, "Variable substitution (key=value)") + wispCmd.Flags().StringArray("var", []string{}, "Variable substitution (key=value); a name the proto cannot consume is an error") wispCmd.Flags().Bool("dry-run", false, "Preview what would be created") wispCmd.Flags().Bool("root-only", false, "Create only the root issue (no child step issues)") // Wisp create command flags (kept for backwards compat: bd mol wisp create ) - wispCreateCmd.Flags().StringArray("var", []string{}, "Variable substitution (key=value)") + wispCreateCmd.Flags().StringArray("var", []string{}, "Variable substitution (key=value); a name the proto cannot consume is an error") wispCreateCmd.Flags().Bool("dry-run", false, "Preview what would be created") wispCreateCmd.Flags().Bool("root-only", false, "Create only the root issue (no child step issues)") diff --git a/cmd/bd/wisp_proxied_server.go b/cmd/bd/wisp_proxied_server.go index ab9d78798..edc727ea8 100644 --- a/cmd/bd/wisp_proxied_server.go +++ b/cmd/bd/wisp_proxied_server.go @@ -80,7 +80,7 @@ func runWispCreateProxiedServer(ctx context.Context, in wispCreateInput) error { vars = applyVariableDefaults(vars, subgraph) if err := checkRequiredVars(subgraph, vars); err != nil { - return HandleErrorWithHint(err.Error(), fmt.Sprintf("Provide them with: --var %s=", firstMissingVar(subgraph, vars))) + return handleVarErrorWithHint(err, firstMissingVar(subgraph, vars)) } if in.dryRun { diff --git a/internal/formula/expand.go b/internal/formula/expand.go index dba11ffab..b276d2c39 100644 --- a/internal/formula/expand.go +++ b/internal/formula/expand.go @@ -17,6 +17,7 @@ package formula import ( "fmt" + "sort" "strings" ) @@ -194,6 +195,17 @@ func countStepIDs(steps []*Step, counts map[string]int) { // DefaultMaxExpansionDepth, an error is returned. // The vars parameter provides variable values for {varname} substitution. func expandStep(target *Step, template []*Step, depth int, vars map[string]string) ([]*Step, error) { + return expandStepWith(target, template, depth, func(s string) string { + return substituteVars(s, vars) + }) +} + +// expandStepWith is expandStep with the {varname} substitution supplied as +// subst, which receives every string the expansion substitutes variables into - +// after the {target} placeholders in it are replaced, where those apply. It +// exists so ExpansionVarRefs can see exactly those strings without keeping a +// second list of the fields that carry them. +func expandStepWith(target *Step, template []*Step, depth int, subst func(string) string) ([]*Step, error) { if depth > DefaultMaxExpansionDepth { return nil, fmt.Errorf("expansion depth limit exceeded: max %d levels (currently at %d) - step %q", DefaultMaxExpansionDepth, depth, target.ID) @@ -203,12 +215,12 @@ func expandStep(target *Step, template []*Step, depth int, vars map[string]strin for _, tmpl := range template { expanded := &Step{ - ID: substituteVars(substituteTargetPlaceholders(tmpl.ID, target), vars), - Title: substituteVars(substituteTargetPlaceholders(tmpl.Title, target), vars), - Description: substituteVars(substituteTargetPlaceholders(tmpl.Description, target), vars), + ID: subst(substituteTargetPlaceholders(tmpl.ID, target)), + Title: subst(substituteTargetPlaceholders(tmpl.Title, target)), + Description: subst(substituteTargetPlaceholders(tmpl.Description, target)), Type: tmpl.Type, Priority: tmpl.Priority, - Assignee: substituteVars(tmpl.Assignee, vars), + Assignee: subst(tmpl.Assignee), SourceFormula: tmpl.SourceFormula, // Preserve source from template SourceLocation: tmpl.SourceLocation, // Preserve source location } @@ -217,7 +229,7 @@ func expandStep(target *Step, template []*Step, depth int, vars map[string]strin if len(tmpl.Labels) > 0 { expanded.Labels = make([]string, len(tmpl.Labels)) for i, l := range tmpl.Labels { - expanded.Labels[i] = substituteVars(substituteTargetPlaceholders(l, target), vars) + expanded.Labels[i] = subst(substituteTargetPlaceholders(l, target)) } } @@ -225,20 +237,20 @@ func expandStep(target *Step, template []*Step, depth int, vars map[string]strin if len(tmpl.DependsOn) > 0 { expanded.DependsOn = make([]string, len(tmpl.DependsOn)) for i, d := range tmpl.DependsOn { - expanded.DependsOn[i] = substituteVars(substituteTargetPlaceholders(d, target), vars) + expanded.DependsOn[i] = subst(substituteTargetPlaceholders(d, target)) } } if len(tmpl.Needs) > 0 { expanded.Needs = make([]string, len(tmpl.Needs)) for i, n := range tmpl.Needs { - expanded.Needs[i] = substituteVars(substituteTargetPlaceholders(n, target), vars) + expanded.Needs[i] = subst(substituteTargetPlaceholders(n, target)) } } // Handle children recursively with depth tracking if len(tmpl.Children) > 0 { - children, err := expandStep(target, tmpl.Children, depth+1, vars) + children, err := expandStepWith(target, tmpl.Children, depth+1, subst) if err != nil { return nil, err } @@ -422,13 +434,7 @@ func MaterializeExpansion(f *Formula, targetID string, vars map[string]string) e return nil } - target := &Step{ - ID: targetID, - Title: f.Formula, - Description: f.Description, - } - - expandedSteps, err := expandStep(target, f.Template, 0, vars) + expandedSteps, err := expandStep(materializeTarget(f, targetID), f.Template, 0, vars) if err != nil { return fmt.Errorf("materializing expansion %q: %w", f.Formula, err) } @@ -437,6 +443,57 @@ func MaterializeExpansion(f *Formula, targetID string, vars map[string]string) e return nil } +// materializeTarget is the synthetic target step a standalone expansion +// formula's template is expanded against. +func materializeTarget(f *Formula, targetID string) *Step { + return &Step{ + ID: targetID, + Title: f.Formula, + Description: f.Description, + } +} + +// ExpansionVarRefs returns the names of the {varname} placeholders that +// MaterializeExpansion(f, targetID, vars) substitutes from vars, deduplicated +// and sorted; nil when f is not an expansion formula with a Template. +// +// Those names are consumed while the template is expanded, so none of them +// survives into the steps MaterializeExpansion produces: a caller that needs +// to know which variables a standalone expansion formula can consume has to +// ask before materializing it. The answer comes from running that same +// expansion with a substitution that records names instead of replacing them, +// so it covers every field the expansion substitutes into - including a name +// that {target.description} pulls in from the formula's own description. +// +// Unlike MaterializeExpansion, this does not skip a formula that already has +// Steps: FilterStepsByCondition can remove all of them first, and then the +// template is materialized after all, so the names are reported either way. +func ExpansionVarRefs(f *Formula, targetID string) []string { + if f.Type != TypeExpansion || len(f.Template) == 0 { + return nil + } + + seen := make(map[string]bool) + record := func(s string) string { + for _, m := range rangeVarPattern.FindAllStringSubmatch(s, -1) { + seen[m[1]] = true + } + return s + } + if _, err := expandStepWith(materializeTarget(f, targetID), f.Template, 0, record); err != nil { + // The template cannot be expanded at all; MaterializeExpansion + // reports why. + return nil + } + + names := make([]string, 0, len(seen)) + for name := range seen { + names = append(names, name) + } + sort.Strings(names) + return names +} + // ApplyInlineExpansions applies Step.Expand fields to inline expansions. // Steps with the Expand field set are replaced by the referenced expansion template. // The step's ExpandVars are passed as variable overrides to the expansion. diff --git a/internal/formula/expand_test.go b/internal/formula/expand_test.go index 11a4b4f2b..63b2bb968 100644 --- a/internal/formula/expand_test.go +++ b/internal/formula/expand_test.go @@ -1197,3 +1197,77 @@ func TestMaterializeExpansion(t *testing.T) { } }) } + +func TestExpansionVarRefs(t *testing.T) { + t.Run("reports every name the expansion substitutes", func(t *testing.T) { + f := &Formula{ + Formula: "deploy", + Description: "Ship {release}", + Type: TypeExpansion, + Template: []*Step{ + { + ID: "{target}.build-{env}", + Title: "Build {component} for {target.title}", + Description: "{target.description}", + Assignee: "{owner}", + Labels: []string{"team:{team}"}, + DependsOn: []string{"{target}.prep-{stage}"}, + Needs: []string{"{target.id}.gate-{gate}"}, + // Neither field is carried into the expanded step, so + // nothing in them is ever substituted. + Notes: "{notes_only}", + Condition: "{{condition_only}}", + Children: []*Step{ + {ID: "{target}.child", Title: "Work on {{feature}}"}, + }, + }, + }, + } + + // {target}, {target.id} and {target.title} are replaced before any + // variable is, so none of them is a name; {target.description} pulls + // in the formula's description, whose {release} IS substituted. The + // single-brace pattern also matches inside {{feature}}, so a + // --var feature=x is consumed there too. + got := strings.Join(ExpansionVarRefs(f, "main"), " ") + if want := "component env feature gate owner release stage team"; got != want { + t.Errorf("ExpansionVarRefs() = %q, want %q", got, want) + } + if f.Steps != nil { + t.Errorf("ExpansionVarRefs materialized the formula: Steps = %v", f.Steps) + } + }) + + t.Run("reported even when the formula already has steps", func(t *testing.T) { + // MaterializeExpansion skips this formula as it stands, but condition + // filtering can remove every step first, and then the template is + // materialized after all. + f := &Formula{ + Formula: "exp", + Type: TypeExpansion, + Steps: []*Step{{ID: "only", Title: "Only", Condition: "{{flag}}"}}, + Template: []*Step{{ID: "{target}.build", Title: "Build {component}"}}, + } + + got := strings.Join(ExpansionVarRefs(f, "main"), " ") + if want := "component"; got != want { + t.Errorf("ExpansionVarRefs() = %q, want %q", got, want) + } + }) + + t.Run("nil unless the formula is an expansion with a template", func(t *testing.T) { + workflow := &Formula{ + Formula: "wf", + Type: TypeWorkflow, + Template: []*Step{{ID: "{target}.build", Title: "Build {component}"}}, + } + if got := ExpansionVarRefs(workflow, "main"); got != nil { + t.Errorf("workflow formula: ExpansionVarRefs() = %v, want nil", got) + } + + noTemplate := &Formula{Formula: "exp", Type: TypeExpansion} + if got := ExpansionVarRefs(noTemplate, "main"); got != nil { + t.Errorf("expansion without a template: ExpansionVarRefs() = %v, want nil", got) + } + }) +}