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 =<value>".

* 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 =<value>".

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

* 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 =<value>`.

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 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <agent@gascity.ai>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
This commit is contained in:
Harry Miller 2026-10-01 05:09:35 -07:00 • committed by GitHub
commit 35bac24ecc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 1157 additions and 24 deletions

View file

@ -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 =<value>` 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,

View file

@ -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",

View file

@ -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 {

View file

@ -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=<value>", 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 =<value>`.
//
// 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=<value>", 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)")

View file

@ -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)
}
})
}

View file

@ -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 =<value>`. 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 =<value>") {
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)
}
}

View file

@ -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),

View file

@ -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=<value>", 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 <proto>)
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 <proto>)
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)")

View file

@ -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=<value>", firstMissingVar(subgraph, vars)))
return handleVarErrorWithHint(err, firstMissingVar(subgraph, vars))
}
if in.dryRun {

View file

@ -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.

View file

@ -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)
}
})
}