beads/internal/formula/parser.go

591 lines
17 KiB
Go

package formula
import (
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"regexp"
"strings"
"github.com/BurntSushi/toml"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/git"
)
// ErrVarValidation wraps a variable validation failure so callers with a
// fallback resolution path (e.g. "is this actually a proto/issue ID rather
// than a formula name?") can distinguish "not a formula" from "is a formula,
// but the provided variables are invalid" and surface the latter directly
// with errors.Is, instead of silently falling through to a worse error.
var ErrVarValidation = errors.New("variable validation failed")
// Formula file extensions. TOML is preferred, JSON is legacy fallback.
const (
FormulaExtTOML = ".formula.toml"
FormulaExtJSON = ".formula.json"
FormulaExt = FormulaExtJSON // Legacy alias for backwards compatibility
)
// Parser handles loading and resolving formulas.
//
// NOTE: Parser is NOT thread-safe. Create a new Parser per goroutine or
// synchronize access externally. The cache and resolving maps have no
// internal synchronization.
type Parser struct {
// searchPaths are directories to search for formulas (in order).
searchPaths []string
// cache stores loaded formulas by name.
cache map[string]*Formula
// resolvingSet tracks formulas currently being resolved (for cycle detection).
resolvingSet map[string]bool
// resolvingChain tracks the order of formulas being resolved (for error messages).
resolvingChain []string
}
// NewParser creates a new formula parser.
// searchPaths are directories to search for formulas when resolving extends.
// Default paths are the active beads project's formulas dir, then user-level,
// then GT_ROOT if configured.
func NewParser(searchPaths ...string) *Parser {
paths := searchPaths
if len(paths) == 0 {
paths = DefaultSearchPaths()
}
return &Parser{
searchPaths: paths,
cache: make(map[string]*Formula),
resolvingSet: make(map[string]bool),
resolvingChain: nil,
}
}
// DefaultSearchPaths returns the default formula search paths.
//
// The project-level path prefers the resolved beads directory so worktrees with
// shared/main-repo .beads state search the same formula registry as the rest of
// the command surface. If no beads project is resolved, fall back to cwd/.beads
// so formula registries can still be used before a project is initialized.
func DefaultSearchPaths() []string {
var paths []string
addPath := func(path string) {
if path == "" {
return
}
for _, existing := range paths {
if existing == path {
return
}
}
paths = append(paths, path)
}
// Project-level formulas via resolved beads directory.
if beadsDir := beads.FindBeadsDir(); beadsDir != "" {
addPath(filepath.Join(beadsDir, "formulas"))
}
// Checkout-local formulas should remain discoverable even when the active
// beads database resolves to a parent/shared .beads directory. This lets a
// repo ship workflow formulas under .beads/formulas without requiring every
// maintainer to copy them into ~/.beads.
if cwd, err := os.Getwd(); err == nil {
checkoutRoot := cwd
if repoRoot := git.GetRepoRoot(); repoRoot != "" {
checkoutRoot = repoRoot
}
addPath(filepath.Join(checkoutRoot, ".beads", "formulas"))
}
// User-level formulas
if home, err := os.UserHomeDir(); err == nil {
addPath(filepath.Join(home, ".beads", "formulas"))
}
// Orchestrator formulas (via GT_ROOT)
if gtRoot := os.Getenv("GT_ROOT"); gtRoot != "" {
addPath(filepath.Join(gtRoot, ".beads", "formulas"))
}
return paths
}
// ParseFile parses a formula from a file path.
// Detects format from extension: .formula.toml or .formula.json
func (p *Parser) ParseFile(path string) (*Formula, error) {
// Check cache first
absPath, err := filepath.Abs(path)
if err != nil {
return nil, fmt.Errorf("resolve path: %w", err)
}
if cached, ok := p.cache[absPath]; ok {
return cached, nil
}
// Read and parse the file
// #nosec G304 -- absPath comes from controlled search paths or explicit user input
data, err := os.ReadFile(absPath)
if err != nil {
return nil, fmt.Errorf("read %s: %w", path, err)
}
// Detect format from extension
var formula *Formula
if strings.HasSuffix(path, FormulaExtTOML) {
formula, err = p.ParseTOML(data)
} else {
formula, err = p.Parse(data)
}
if err != nil {
return nil, fmt.Errorf("parse %s: %w", path, err)
}
formula.Source = absPath
// Set source tracing info on all steps (gt-8tmz.18)
SetSourceInfo(formula)
p.cache[absPath] = formula
// Also cache by name for extends resolution
p.cache[formula.Formula] = formula
return formula, nil
}
// Parse parses a formula from JSON bytes.
func (p *Parser) Parse(data []byte) (*Formula, error) {
var formula Formula
if err := json.Unmarshal(data, &formula); err != nil {
return nil, fmt.Errorf("json: %w", err)
}
// Set defaults
if formula.Version == 0 {
formula.Version = 1
}
if formula.Type == "" {
formula.Type = TypeWorkflow
}
return &formula, nil
}
// ParseTOML parses a formula from TOML bytes.
func (p *Parser) ParseTOML(data []byte) (*Formula, error) {
var formula Formula
if err := toml.Unmarshal(data, &formula); err != nil {
return nil, fmt.Errorf("toml: %w", err)
}
// Set defaults
if formula.Version == 0 {
formula.Version = 1
}
if formula.Type == "" {
formula.Type = TypeWorkflow
}
return &formula, nil
}
// Resolve fully resolves a formula, processing extends and expansions.
// Returns a new formula with all inheritance applied.
func (p *Parser) Resolve(formula *Formula) (*Formula, error) {
// Check for cycles
if p.resolvingSet[formula.Formula] {
// Build the cycle chain for a clear error message
chain := append(p.resolvingChain, formula.Formula)
return nil, fmt.Errorf("circular extends detected: %s", strings.Join(chain, " -> "))
}
p.resolvingSet[formula.Formula] = true
p.resolvingChain = append(p.resolvingChain, formula.Formula)
defer func() {
delete(p.resolvingSet, formula.Formula)
p.resolvingChain = p.resolvingChain[:len(p.resolvingChain)-1]
}()
// If no extends, just validate and return
if len(formula.Extends) == 0 {
if err := formula.Validate(); err != nil {
return nil, err
}
return formula, nil
}
// Build merged formula from parents
merged := &Formula{
Formula: formula.Formula,
Description: formula.Description,
Version: formula.Version,
Type: formula.Type,
Source: formula.Source,
Vars: make(map[string]*VarDef),
Steps: nil,
Compose: nil,
}
// Apply each parent in order
for _, parentName := range formula.Extends {
parent, err := p.loadFormula(parentName)
if err != nil {
return nil, fmt.Errorf("extends %s: %w", parentName, err)
}
// Resolve parent recursively
parent, err = p.Resolve(parent)
if err != nil {
return nil, fmt.Errorf("resolve parent %s: %w", parentName, err)
}
// Merge parent vars (parent vars are inherited, child overrides)
for name, varDef := range parent.Vars {
if _, exists := merged.Vars[name]; !exists {
merged.Vars[name] = varDef
}
}
// Merge parent steps (append, child steps come after)
merged.Steps = append(merged.Steps, parent.Steps...)
// Merge parent compose rules
merged.Compose = mergeComposeRules(merged.Compose, parent.Compose)
}
// Apply child overrides
for name, varDef := range formula.Vars {
merged.Vars[name] = varDef
}
// Merge child steps: override parent steps by ID (preserving position),
// append new child steps at the end.
merged.Steps = mergeSteps(merged.Steps, formula.Steps)
merged.Compose = mergeComposeRules(merged.Compose, formula.Compose)
// Use child description if set
if formula.Description != "" {
merged.Description = formula.Description
}
if err := merged.Validate(); err != nil {
return nil, err
}
return merged, nil
}
// loadFormula loads a formula by name from search paths.
// Tries TOML first (.formula.toml), then falls back to JSON (.formula.json).
func (p *Parser) loadFormula(name string) (*Formula, error) {
// Check cache first
if cached, ok := p.cache[name]; ok {
return cached, nil
}
// Search for the formula file - try TOML first, then JSON
extensions := []string{FormulaExtTOML, FormulaExtJSON}
for _, dir := range p.searchPaths {
for _, ext := range extensions {
path := filepath.Join(dir, name+ext)
if _, err := os.Stat(path); err == nil {
return p.ParseFile(path)
}
}
}
return nil, fmt.Errorf("formula %q not found in search paths", name)
}
// LoadByName loads a formula by name from search paths.
// This is the public API for loading formulas used by expansion operators.
func (p *Parser) LoadByName(name string) (*Formula, error) {
return p.loadFormula(name)
}
// mergeSteps merges child steps into parent steps.
// Child steps with the same ID as a parent step replace the parent step
// in-place (preserving position). Child steps with new IDs are appended.
func mergeSteps(parent, child []*Step) []*Step {
// Index parent steps by ID for quick lookup
parentIdx := make(map[string]int, len(parent))
for i, s := range parent {
parentIdx[s.ID] = i
}
// Copy parent steps (will be modified in-place for overrides)
result := make([]*Step, len(parent))
copy(result, parent)
// Apply child steps
for _, cs := range child {
if idx, exists := parentIdx[cs.ID]; exists {
// Override: replace parent step at same position
result[idx] = cs
} else {
// New step: append at end
result = append(result, cs)
}
}
return result
}
// mergeComposeRules merges two compose rule sets.
func mergeComposeRules(base, overlay *ComposeRules) *ComposeRules {
if overlay == nil {
return base
}
if base == nil {
return overlay
}
result := &ComposeRules{
BondPoints: append([]*BondPoint{}, base.BondPoints...),
Hooks: append([]*Hook{}, base.Hooks...),
Expand: append([]*ExpandRule{}, base.Expand...),
Map: append([]*MapRule{}, base.Map...),
}
// Add overlay bond points (override by ID)
existingBP := make(map[string]int)
for i, bp := range result.BondPoints {
existingBP[bp.ID] = i
}
for _, bp := range overlay.BondPoints {
if idx, exists := existingBP[bp.ID]; exists {
result.BondPoints[idx] = bp
} else {
result.BondPoints = append(result.BondPoints, bp)
}
}
// Add overlay hooks (append, no override)
result.Hooks = append(result.Hooks, overlay.Hooks...)
// Add overlay expand rules (append, no override)
result.Expand = append(result.Expand, overlay.Expand...)
// Add overlay map rules (append, no override)
result.Map = append(result.Map, overlay.Map...)
return result
}
// varPattern matches {{variable}} placeholders.
var varPattern = regexp.MustCompile(`\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}`)
// ExtractVariables finds all {{variable}} references in a formula.
func ExtractVariables(formula *Formula) []string {
seen := make(map[string]bool)
var vars []string
// Helper to extract vars from a string
extract := func(s string) {
matches := varPattern.FindAllStringSubmatch(s, -1)
for _, match := range matches {
if len(match) >= 2 && !seen[match[1]] {
seen[match[1]] = true
vars = append(vars, match[1])
}
}
}
// Extract from formula fields
extract(formula.Description)
// Extract from steps
var extractFromStep func(*Step)
extractFromStep = func(step *Step) {
extract(step.Title)
extract(step.Description)
extract(step.Assignee)
extract(step.Condition)
if step.Gate != nil {
extract(step.Gate.Type)
extract(step.Gate.ID)
extract(step.Gate.AwaitID)
extract(step.Gate.Timeout)
extract(step.Gate.Repo)
}
for _, child := range step.Children {
extractFromStep(child)
}
}
for _, step := range formula.Steps {
extractFromStep(step)
}
return vars
}
// Substitute replaces {{variable}} placeholders with values.
func Substitute(s string, vars map[string]string) string {
return varPattern.ReplaceAllStringFunc(s, func(match string) string {
// Extract variable name from {{name}}
name := match[2 : len(match)-2]
if val, ok := vars[name]; ok {
return val
}
return match // Keep unresolved placeholders
})
}
// ValidateVars checks that all required variables are provided
// and all values pass their constraints.
func ValidateVars(formula *Formula, values map[string]string) error {
var errs []string
for name, def := range formula.Vars {
val, provided := values[name]
// Check required
if def.Required && !provided {
errs = append(errs, fmt.Sprintf("variable %q is required", name))
continue
}
errs = append(errs, validateVarValue(name, def, val, provided)...)
}
if len(errs) > 0 {
return fmt.Errorf("%w:\n - %s", ErrVarValidation, strings.Join(errs, "\n - "))
}
return nil
}
// ValidateProvidedVars checks enum/pattern/required-empty constraints only
// for variables that are present in values; it does not flag variables that
// are entirely absent. Callers that already surface a more specific
// missing-variable message (e.g. bd mol pour/wisp's hint path) should keep
// using that path for absent vars — this exists so those same callers still
// catch malformed *provided* values, which a presence-only check misses
// (mybd-u2r6).
func ValidateProvidedVars(formula *Formula, values map[string]string) error {
var errs []string
for name, def := range formula.Vars {
val, provided := values[name]
if !provided {
continue
}
errs = append(errs, validateVarValue(name, def, val, provided)...)
}
if len(errs) > 0 {
return fmt.Errorf("%w:\n - %s", ErrVarValidation, strings.Join(errs, "\n - "))
}
return nil
}
// validateVarValue applies the required-empty, enum, and pattern checks for
// a single variable given its (possibly defaulted) value. It assumes any
// "required and not provided at all" check has already been handled by the
// caller, since that case is presented differently by ValidateVars vs.
// ValidateProvidedVars.
func validateVarValue(name string, def *VarDef, val string, provided bool) []string {
var errs []string
// A variable with no default is effectively required: the command paths
// (extractRequiredVariables) demand a value for it, so a provided-but-empty
// value is the same unset-shell-variable trap as for required=true.
if (def.Required || def.Default == nil) && provided && val == "" {
errs = append(errs, fmt.Sprintf("variable %q is required and cannot be empty", name))
return errs
}
// Use default if not provided
if !provided && def.Default != nil {
val = *def.Default
}
// Skip further validation only when the var was genuinely not
// provided (absent from the map). A value that was explicitly
// provided as "" must still be checked against enum/pattern
// constraints rather than silently passing.
if !provided && val == "" {
return errs
}
// Check enum constraint
if len(def.Enum) > 0 {
found := false
for _, allowed := range def.Enum {
if val == allowed {
found = true
break
}
}
if !found {
errs = append(errs, fmt.Sprintf("variable %q: value %q not in allowed values %v", name, val, def.Enum))
}
}
// Check pattern constraint
if def.Pattern != "" {
re, err := regexp.Compile(def.Pattern)
if err != nil {
errs = append(errs, fmt.Sprintf("variable %q: invalid pattern %q: %v", name, def.Pattern, err))
} else if !re.MatchString(val) {
errs = append(errs, fmt.Sprintf("variable %q: value %q does not match pattern %q", name, val, def.Pattern))
}
}
return errs
}
// ApplyDefaults returns a new map with default values filled in.
func ApplyDefaults(formula *Formula, values map[string]string) map[string]string {
result := make(map[string]string)
// Copy provided values
for k, v := range values {
result[k] = v
}
// Apply defaults for missing values
for name, def := range formula.Vars {
if _, exists := result[name]; !exists && def.Default != nil {
result[name] = *def.Default
}
}
return result
}
// SetSourceInfo sets SourceFormula and SourceLocation on all steps in a formula.
// Called after parsing to enable source tracing during cooking (gt-8tmz.18).
func SetSourceInfo(formula *Formula) {
setSourceInfoRecursive(formula.Steps, formula.Formula, "steps")
// Also set source info on template steps for expansion formulas
setSourceInfoRecursive(formula.Template, formula.Formula, "template")
}
// setSourceInfoRecursive recursively sets source info on steps.
func setSourceInfoRecursive(steps []*Step, formulaName, pathPrefix string) {
for i, step := range steps {
step.SourceFormula = formulaName
step.SourceLocation = fmt.Sprintf("%s[%d]", pathPrefix, i)
if len(step.Children) > 0 {
childPath := fmt.Sprintf("%s[%d].children", pathPrefix, i)
setSourceInfoRecursive(step.Children, formulaName, childPath)
}
// Handle loop body steps
if step.Loop != nil && len(step.Loop.Body) > 0 {
bodyPath := fmt.Sprintf("%s[%d].loop.body", pathPrefix, i)
setSourceInfoRecursive(step.Loop.Body, formulaName, bodyPath)
}
}
}