beads/internal/formula/expand.go
Xexr 8561884cba
feat(cook): support standalone expansion formula execution in bd mol wisp (#1903)
Expansion formulas (e.g. rule-of-five, spec-brainstorm-expansion) could
only run via Compose workflow wrappers that resolve {target} placeholders.
Running them directly with `bd mol wisp` produced an empty epic with no
child steps.

Add MaterializeExpansion() to convert a standalone expansion formula's
Template into Steps using a synthetic "main" target. Call it in
resolveAndCookFormulaWithVars() before cooking to subgraph so the normal
pipeline processes the expanded steps.

Also fix propagateTargetDeps() to carry the target step's dependencies
into the root steps of each expansion, and rebuild stepMap after each
UpdateDependenciesForExpansion call so subsequent iterations see resolved
references.

All 9 expansion formulas now work standalone:
  bd mol wisp rule-of-five --dry-run → 6 issues
  bd mol wisp spec-multimodal-scope-questions-expansion \
    --var feature=X --var brief=Y --dry-run → 9 issues

Closes #663

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Executed-By: beads/crew/leeloo
Rig: beads
Role: crew
2026-02-22 13:00:25 -08:00

520 lines
16 KiB
Go

// Package formula provides expansion operators for macro-style step transformation.
//
// Expansion operators replace target steps with template-expanded steps.
// Unlike advice operators which insert steps around targets, expansion
// operators completely replace the target with the expansion template.
//
// Two operators are supported:
// - expand: Apply template to a single target step
// - map: Apply template to all steps matching a pattern
//
// Templates use {target} and {target.description} placeholders that are
// substituted with the target step's values during expansion.
//
// A maximum expansion depth (default 5) prevents runaway nested expansions.
// This allows massive work generation while providing a safety bound.
package formula
import (
"fmt"
"strings"
)
// DefaultMaxExpansionDepth is the maximum depth for recursive template expansion.
// This prevents runaway nested expansions while still allowing substantial work
// generation. The limit applies to template children, not to expansion rules.
const DefaultMaxExpansionDepth = 5
// ApplyExpansions applies all expand and map rules to a formula's steps.
// Returns a new steps slice with expansions applied.
// The original steps slice is not modified.
//
// The parser is used to load referenced expansion formulas by name.
// If parser is nil, no expansions are applied.
func ApplyExpansions(steps []*Step, compose *ComposeRules, parser *Parser) ([]*Step, error) {
if compose == nil || parser == nil {
return steps, nil
}
if len(compose.Expand) == 0 && len(compose.Map) == 0 {
return steps, nil
}
// Build a map of step ID -> step for quick lookup
stepMap := buildStepMap(steps)
// Track which steps have been expanded (to avoid double expansion)
expanded := make(map[string]bool)
// Apply expand rules first (specific targets)
result := steps
for _, rule := range compose.Expand {
targetStep, ok := stepMap[rule.Target]
if !ok {
return nil, fmt.Errorf("expand: target step %q not found", rule.Target)
}
if expanded[rule.Target] {
continue // Already expanded
}
// Load the expansion formula
expFormula, err := parser.LoadByName(rule.With)
if err != nil {
return nil, fmt.Errorf("expand: loading %q: %w", rule.With, err)
}
if expFormula.Type != TypeExpansion {
return nil, fmt.Errorf("expand: %q is not an expansion formula (type=%s)", rule.With, expFormula.Type)
}
if len(expFormula.Template) == 0 {
return nil, fmt.Errorf("expand: %q has no template steps", rule.With)
}
// Merge formula default vars with rule overrides
vars := mergeVars(expFormula, rule.Vars)
// Expand the target step (start at depth 0)
expandedSteps, err := expandStep(targetStep, expFormula.Template, 0, vars)
if err != nil {
return nil, fmt.Errorf("expand %q: %w", rule.Target, err)
}
// Propagate target step's dependencies to root steps of the expansion.
// Root steps are those whose needs/dependsOn only reference IDs within
// the expansion (or are empty) — they are the entry points.
propagateTargetDeps(targetStep, expandedSteps)
// Replace the target step with expanded steps
result = replaceStep(result, rule.Target, expandedSteps)
expanded[rule.Target] = true
// Update dependencies: any step that depended on the target should now
// depend on the last step of the expansion
if len(expandedSteps) > 0 {
lastStepID := expandedSteps[len(expandedSteps)-1].ID
result = UpdateDependenciesForExpansion(result, rule.Target, lastStepID)
}
// Rebuild stepMap from result so subsequent iterations see resolved deps
stepMap = buildStepMap(result)
}
// Apply map rules (pattern matching)
for _, rule := range compose.Map {
// Load the expansion formula
expFormula, err := parser.LoadByName(rule.With)
if err != nil {
return nil, fmt.Errorf("map: loading %q: %w", rule.With, err)
}
if expFormula.Type != TypeExpansion {
return nil, fmt.Errorf("map: %q is not an expansion formula (type=%s)", rule.With, expFormula.Type)
}
if len(expFormula.Template) == 0 {
return nil, fmt.Errorf("map: %q has no template steps", rule.With)
}
// Merge formula default vars with rule overrides
vars := mergeVars(expFormula, rule.Vars)
// Find all matching steps (including nested children)
// Rebuild stepMap to capture any changes from previous expansions
stepMap = buildStepMap(result)
var toExpand []*Step
for id, step := range stepMap {
if MatchGlob(rule.Select, id) && !expanded[id] {
toExpand = append(toExpand, step)
}
}
// Expand each matching step
for _, targetStep := range toExpand {
expandedSteps, err := expandStep(targetStep, expFormula.Template, 0, vars)
if err != nil {
return nil, fmt.Errorf("map %q -> %q: %w", rule.Select, targetStep.ID, err)
}
// Propagate target step's dependencies to root steps of the expansion
propagateTargetDeps(targetStep, expandedSteps)
result = replaceStep(result, targetStep.ID, expandedSteps)
expanded[targetStep.ID] = true
// Update dependencies: any step that depended on the target should now
// depend on the last step of the expansion
if len(expandedSteps) > 0 {
lastStepID := expandedSteps[len(expandedSteps)-1].ID
result = UpdateDependenciesForExpansion(result, targetStep.ID, lastStepID)
}
// Rebuild stepMap from result so subsequent iterations see resolved deps
stepMap = buildStepMap(result)
}
}
// Validate no duplicate step IDs after expansion
if dups := findDuplicateStepIDs(result); len(dups) > 0 {
return nil, fmt.Errorf("duplicate step IDs after expansion: %v", dups)
}
return result, nil
}
// findDuplicateStepIDs returns any duplicate step IDs found in the steps slice.
// It recursively checks all children.
func findDuplicateStepIDs(steps []*Step) []string {
seen := make(map[string]int)
countStepIDs(steps, seen)
var dups []string
for id, count := range seen {
if count > 1 {
dups = append(dups, id)
}
}
return dups
}
// countStepIDs counts occurrences of each step ID recursively.
func countStepIDs(steps []*Step, counts map[string]int) {
for _, step := range steps {
counts[step.ID]++
if len(step.Children) > 0 {
countStepIDs(step.Children, counts)
}
}
}
// expandStep expands a target step using the given template.
// Returns the expanded steps with placeholders substituted.
// The depth parameter tracks recursion depth for children; if it exceeds
// 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) {
if depth > DefaultMaxExpansionDepth {
return nil, fmt.Errorf("expansion depth limit exceeded: max %d levels (currently at %d) - step %q",
DefaultMaxExpansionDepth, depth, target.ID)
}
result := make([]*Step, 0, len(template))
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),
Type: tmpl.Type,
Priority: tmpl.Priority,
Assignee: substituteVars(tmpl.Assignee, vars),
SourceFormula: tmpl.SourceFormula, // Preserve source from template
SourceLocation: tmpl.SourceLocation, // Preserve source location
}
// Substitute placeholders in labels
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)
}
}
// Substitute placeholders in dependencies
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)
}
}
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)
}
}
// Handle children recursively with depth tracking
if len(tmpl.Children) > 0 {
children, err := expandStep(target, tmpl.Children, depth+1, vars)
if err != nil {
return nil, err
}
expanded.Children = children
}
result = append(result, expanded)
}
return result, nil
}
// substituteTargetPlaceholders replaces {target} and {target.*} placeholders.
func substituteTargetPlaceholders(s string, target *Step) string {
if s == "" {
return s
}
// Replace {target} with target step ID
s = strings.ReplaceAll(s, "{target}", target.ID)
// Replace {target.id} with target step ID
s = strings.ReplaceAll(s, "{target.id}", target.ID)
// Replace {target.title} with target step title
s = strings.ReplaceAll(s, "{target.title}", target.Title)
// Replace {target.description} with target step description
s = strings.ReplaceAll(s, "{target.description}", target.Description)
return s
}
// mergeVars merges formula default vars with rule overrides.
// Override values take precedence over defaults.
func mergeVars(formula *Formula, overrides map[string]string) map[string]string {
result := make(map[string]string)
// Start with formula defaults
for name, def := range formula.Vars {
if def.Default != nil {
result[name] = *def.Default
}
}
// Apply overrides (these win)
for name, value := range overrides {
result[name] = value
}
return result
}
// buildStepMap creates a map of step ID to step (recursive).
func buildStepMap(steps []*Step) map[string]*Step {
result := make(map[string]*Step)
for _, step := range steps {
result[step.ID] = step
// Add children recursively
for id, child := range buildStepMap(step.Children) {
result[id] = child
}
}
return result
}
// replaceStep replaces a step with the given ID with a slice of new steps.
// Searches recursively through children to find and replace the target.
func replaceStep(steps []*Step, targetID string, replacement []*Step) []*Step {
result := make([]*Step, 0, len(steps)+len(replacement)-1)
for _, step := range steps {
if step.ID == targetID {
// Replace with expanded steps
result = append(result, replacement...)
} else {
// Keep the step, but check children
if len(step.Children) > 0 {
// Clone step and replace in children
clone := cloneStep(step)
clone.Children = replaceStep(step.Children, targetID, replacement)
result = append(result, clone)
} else {
result = append(result, step)
}
}
}
return result
}
// UpdateDependenciesForExpansion updates dependency references after expansion.
// When step X is expanded into X.draft, X.refine-1, etc., any step that
// depended on X should now depend on the last step in the expansion.
func UpdateDependenciesForExpansion(steps []*Step, expandedID string, lastExpandedStepID string) []*Step {
result := make([]*Step, len(steps))
for i, step := range steps {
clone := cloneStep(step)
// Update DependsOn references
for j, dep := range clone.DependsOn {
if dep == expandedID {
clone.DependsOn[j] = lastExpandedStepID
}
}
// Update Needs references
for j, need := range clone.Needs {
if need == expandedID {
clone.Needs[j] = lastExpandedStepID
}
}
// Handle children recursively
if len(step.Children) > 0 {
clone.Children = UpdateDependenciesForExpansion(step.Children, expandedID, lastExpandedStepID)
}
result[i] = clone
}
return result
}
// propagateTargetDeps copies the target step's Needs and DependsOn to the root
// steps of an expansion. Root steps are those whose existing dependencies only
// reference other steps within the expansion (i.e., they have no external deps
// from the template). This preserves cross-expansion dependency chains that would
// otherwise be lost when the target step is replaced.
func propagateTargetDeps(target *Step, expandedSteps []*Step) {
if len(target.Needs) == 0 && len(target.DependsOn) == 0 {
return
}
expandedIDs := make(map[string]bool, len(expandedSteps))
for _, s := range expandedSteps {
expandedIDs[s.ID] = true
}
for _, s := range expandedSteps {
isRoot := true
for _, n := range s.Needs {
if expandedIDs[n] {
isRoot = false
break
}
}
if isRoot {
for _, d := range s.DependsOn {
if expandedIDs[d] {
isRoot = false
break
}
}
}
if isRoot {
// Prepend target's deps (new slice to avoid aliasing)
if len(target.Needs) > 0 {
s.Needs = append(append([]string{}, target.Needs...), s.Needs...)
}
if len(target.DependsOn) > 0 {
s.DependsOn = append(append([]string{}, target.DependsOn...), s.DependsOn...)
}
}
}
}
// MaterializeExpansion converts a standalone expansion formula into a cookable
// form by expanding its Template into Steps. A synthetic target step is created
// using targetID as the step ID and the formula's own name/description for
// {target.title} and {target.description} placeholders.
//
// This enables expansion formulas to be directly instantiated via wisp/pour
// without requiring a Compose wrapper (bd-qzb).
//
// No-op if the formula is not an expansion type, has no Template, or already
// has Steps.
func MaterializeExpansion(f *Formula, targetID string, vars map[string]string) error {
if f.Type != TypeExpansion || len(f.Template) == 0 || len(f.Steps) > 0 {
return nil
}
target := &Step{
ID: targetID,
Title: f.Formula,
Description: f.Description,
}
expandedSteps, err := expandStep(target, f.Template, 0, vars)
if err != nil {
return fmt.Errorf("materializing expansion %q: %w", f.Formula, err)
}
f.Steps = expandedSteps
return nil
}
// 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.
//
// This differs from compose.Expand in that the expansion is declared inline on the
// step itself rather than in a central compose section.
//
// Returns a new steps slice with inline expansions applied.
// The original steps slice is not modified.
func ApplyInlineExpansions(steps []*Step, parser *Parser) ([]*Step, error) {
if parser == nil {
return steps, nil
}
return applyInlineExpansionsRecursive(steps, parser, 0)
}
// applyInlineExpansionsRecursive handles inline expansions for a slice of steps.
// depth tracks recursion to prevent infinite expansion loops.
func applyInlineExpansionsRecursive(steps []*Step, parser *Parser, depth int) ([]*Step, error) {
if depth > DefaultMaxExpansionDepth {
return nil, fmt.Errorf("inline expansion depth limit exceeded: max %d levels", DefaultMaxExpansionDepth)
}
var result []*Step
for _, step := range steps {
// Check if this step has an inline expansion
if step.Expand != "" {
// Load the expansion formula
expFormula, err := parser.LoadByName(step.Expand)
if err != nil {
return nil, fmt.Errorf("inline expand on step %q: loading %q: %w", step.ID, step.Expand, err)
}
if expFormula.Type != TypeExpansion {
return nil, fmt.Errorf("inline expand on step %q: %q is not an expansion formula (type=%s)",
step.ID, step.Expand, expFormula.Type)
}
if len(expFormula.Template) == 0 {
return nil, fmt.Errorf("inline expand on step %q: %q has no template steps", step.ID, step.Expand)
}
// Merge formula default vars with step's ExpandVars overrides
vars := mergeVars(expFormula, step.ExpandVars)
// Expand the step using the template (reuse existing expandStep)
expandedSteps, err := expandStep(step, expFormula.Template, 0, vars)
if err != nil {
return nil, fmt.Errorf("inline expand on step %q: %w", step.ID, err)
}
// Propagate the original step's dependencies to root steps of the expansion
propagateTargetDeps(step, expandedSteps)
// Recursively process expanded steps for nested inline expansions
processedSteps, err := applyInlineExpansionsRecursive(expandedSteps, parser, depth+1)
if err != nil {
return nil, err
}
result = append(result, processedSteps...)
} else {
// No inline expansion - keep the step, but process children recursively
clone := cloneStep(step)
if len(step.Children) > 0 {
processedChildren, err := applyInlineExpansionsRecursive(step.Children, parser, depth)
if err != nil {
return nil, err
}
clone.Children = processedChildren
}
result = append(result, clone)
}
}
return result, nil
}