From 35bac24ecc2ea2f30e10ac83bd4ed5a84136d4ab Mon Sep 17 00:00:00 2001 From: Harry Miller Date: Thu, 1 Oct 2026 05:09:35 -0700 Subject: [PATCH] fix(pour): reject --var names the proto cannot consume (#5762) * fix(pour): reject --var names the proto cannot consume An unrecognized --var name was dropped without comment. The failure that surfaces is not a missing substitution but a missing step: a typo in an optional var leaves its condition evaluating against an unset name, so the conditional step is quietly never poured and the molecule looks like it simply does not have that step. checkPourVars now rejects names that no proto in the pour declares in VarDefs or references as a {{handlebar}}, listing what is available. Anything that could still affect the pour is accepted: a documentation handlebar the formula never declared, and a var belonging to an --attach proto rather than the root, both pass. Missing required vars are reported first, unchanged, since the caller's hint is derived from them. That hint is now only attached when a required var really is missing. It interpolated missingVarHint unconditionally, so any other failure from checkPourVars would have advised "--var =". * fix(wisp): reject --var names the proto cannot consume bd mol wisp validates vars through checkRequiredVars rather than checkPourVars, so the unknown-name rejection added for pour did not reach it and a typo was still dropped without comment on the wisp path. Route it through the same check. A wisp instantiates one proto with no attachments, so the known set is that proto's declared vars plus the handlebars it references. The missing-var hint is now only attached when a var really is missing here too, matching pour: otherwise any other failure from this check advised "--var =". * fix(pour): count a var used only by a step condition as consumable checkUnknownVars built its known set from the cooked subgraph, so it could not see step conditions: formula.FilterStepsByCondition consumes them and drops the steps carrying them BEFORE the cook, and nothing requires a condition var to be declared in [vars]. An undeclared var that decides which steps get poured therefore left no trace anywhere the check looked, and a hard error turned a working pour into a failing one - exactly the case the rule ("a name is rejected only when nothing in the pour could consume it") means to accept. TemplateSubgraph gains ConditionVars, recorded by resolveAndCookFormulaWithVars immediately before the condition filter runs - the last point at which those names are still visible. Collected unconditionally, since they are a property of the formula rather than of this pour's --var values, which is what makes the falsey case work: the step is gone, and the var that removed it still counts. knownVarsAcross adds them. A persisted proto loaded from the database leaves the field empty, correctly: it has no formula behind it and its conditions were resolved at cook time. The reviewer's reproduction, against the pre-fix code: Error: unknown variables: has_spike (available: story) Regression coverage answers the fifth review point as well - that every existing test called checkPourVars directly with a hand-built subgraph, which is precisely why this was invisible. TestBdMolPour_AcceptsAVarUsedOnlyByAStepCondition runs the CLI through the real cook pipeline with has_spike both true and false (the falsey case being the one that regresses if the collection ever moves after the filter), plus a typo case proving the widened set does not disable the check. Two unit cases cover the same pair. The check does not disable itself: a typo in a condition var is still reported, now with the condition var among the available names. Non-blocking review points 3 and 4: pour's and wisp's --var flag help says an unusable name is an error, and the CHANGELOG entry states the new behavior and says plainly that `bd mol bond --var` and `bd mol seed --var` remain out of scope - both go through formula.ValidateProvidedVars, which only iterates declared vars and so never examines a provided name with no VarDef. On review point 2 (the interaction with #5758): no action needed either way round. #5758 widens extractAllVariables itself, and knownVarsAcross calls that same function, so a var referenced only from a step's assignee/labels/metadata joins this known set automatically when #5758 lands, in whichever order the two merge. Reported-by: bee-ghosttrack Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller Co-Authored-By: Claude Opus 5 (1M context) * test(pour): exercise the real cook pipeline without spawning a binary The end-to-end case spawned an embedded bd and ran three CLI invocations, the most expensive shape of test in cmd/bd - and cmd/bd already runs 477s of its 600s budget on the macos runner, so the addition timed the package out. The process boundary was not the point. What the unit tests could not see was the ORDERING inside the cook pipeline, and resolveAndCookFormulaWithVars takes its search paths as an argument, so the real pipeline - control flow, expansions, FilterStepsByCondition, the cook - runs directly against a formula in a temp dir. Same coverage in 0.01s instead of 32s. It is also a sharper test than the CLI version was. It now asserts the PREMISE of the falsey case (that the conditional step really is absent from the cooked subgraph, so the case is testing the ordering rather than passing for an unrelated reason), and that the typo error offers the condition var among the available names, which is the actual user-visible point of carrying those names into the known set. Both reds confirmed, including the near-miss: with the known-set change reverted all three cases fail, and with the collection moved to AFTER the condition filter - the plausible fix, and the one the reviewer's suggested call site would have produced - has_spike=true passes while has_spike=false still fails: --- FAIL: .../has_spike_false pour rejected a var its own step condition consumes (has_spike=false): unknown variables: has_spike (available: story) Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller Co-Authored-By: Claude Opus 5 (1M context) * docs(changelog): move this PR's entry under [Unreleased] The 1.3.0 cut renamed the old [Unreleased] block, so the entry this branch added there now merges cleanly into the released [1.3.0] section (#6643). Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller Co-Authored-By: Claude Opus 5.5 (1M context) * chore(bazel): enumerate the PR's new cmd/bd test files in go_test srcs gazelle-generated. cmd/bd/BUILD.bazel lists go_test srcs explicitly, so the two untagged test files this PR adds would not run under the advisory Bazel lane added in #6881. Base parity at 6da2a4347 is exhaustive for untagged tests (the only two unenumerated files are //go:build cgo && integration), so the omission is PR-introduced rather than a pre-existing pattern. Produced by make bazel-sync; no deps line was needed because go_test embeds :bd_lib, which already depends on //internal/formula and //internal/types. Co-Authored-By: Claude Opus 5 * fix(pour): read every substituted field into the unknown-var known set Maintainer review fixup for the unknown-`--var` refusal. The refusal failed CLOSED on a known set narrower than what the pour actually substitutes, so it rejected names the clone demonstrably consumes. - knownVarsAcross read the five prose fields only, missing a gate's await_id and a gh:* gate's metadata.repo selector; a formula's `repo = "{{gate_repo}}"` is stored literally on the proto and filled in at clone time, and nothing mirrors that name into a scanned field. substitutedIssueFields now mirrors cloneSubgraphInto's substitution set, and gateRepoSelector is factored out of substituteMetadataRepo so the read and write sides of the selector cannot disagree about which issues carry one. - a proto loaded from the database has no formula behind it, so its [vars] declarations are gone and a declared-but-unreferenced name cannot be told apart from a typo. `VarDefs == nil` does not identify that case - a formula declaring no [vars] is also nil, and that proto really does take none - so the cook stamps DeclaredVarsKnown and the refusal stands down without it. That covers every `bd cook --persist` proto and every --attach proto, which is always DB-loaded. - a handlebar living only inside a step the condition filter dropped left the known set, so `--var deploy=false --var deploy_target=prod` failed while deploy=true succeeded. ConditionVars becomes FormulaVarRefs and is collected from the unfiltered steps' text and gate fields as well as their conditions, making a name's validity a property of the formula rather than of another var's value. - a standalone `type = "expansion"` formula has no [[steps]]: MaterializeExpansion builds them from its [[template]] before the cook, substituting --var values into single-brace `{name}` placeholders, so a name used only there was consumed and then refused as unknown. formula.ExpansionVarRefs reports those names by running that same expansion - expandStep now wraps expandStepWith - with a substitution that records instead of replacing, so it covers exactly the fields the expansion fills in, including a name that `{target.description}` pulls in from the formula's own description. cook adds them to FormulaVarRefs ahead of the filter, and without MaterializeExpansion's has-Steps skip: the filter can remove every step, and then the template is materialized after all. The hint-suppression branch was hand-copied to three sites and tested at none; it is now handleVarErrorWithHint, pinned by a stderr assertion that an unknown-var error prints no `Provide them with: --var =`. Tests: table cases for both gate fields and for `repo` on a non-gh gate staying unsubstituted (the polarity that keeps the read side honest), for the DB-loaded stand-down directly and via an --attach proto, and real-pipeline cases for the dropped-step var, for vars only a dropped step's gate uses (await_id and a gh:* repo), and for a template-only placeholder var, whose typo is still refused with the real name offered. ExpansionVarRefs is pinned per substituted field, per field the expansion drops (notes, condition), and for an expansion formula that also has steps. Mutating each arm reds exactly the matching cases and nothing else. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5 (1M context) Co-authored-by: Julian Knutsen Co-authored-by: Gas City Adopt-PR --- CHANGELOG.md | 29 ++ cmd/bd/BUILD.bazel | 2 + cmd/bd/cook.go | 96 +++++- cmd/bd/pour.go | 113 ++++++- cmd/bd/pour_unknown_vars_pipeline_test.go | 327 ++++++++++++++++++++ cmd/bd/pour_unknown_vars_test.go | 354 ++++++++++++++++++++++ cmd/bd/template.go | 91 ++++++ cmd/bd/wisp.go | 8 +- cmd/bd/wisp_proxied_server.go | 2 +- internal/formula/expand.go | 87 +++++- internal/formula/expand_test.go | 74 +++++ 11 files changed, 1158 insertions(+), 25 deletions(-) create mode 100644 cmd/bd/pour_unknown_vars_pipeline_test.go create mode 100644 cmd/bd/pour_unknown_vars_test.go 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) + } + }) +}