refactor: taskfile/ast package (#1450)

* refactor: ast package

* feat: read -> taskfile

* refactor: taskfile.Taskfile -> taskfile.Read

* refactor: move merge function back into taskfile package

* refactor: rename taskfile.go to read.go

taskfile/ast/call.go

@@ -0,0 +1,9 @@
+package ast
+
+// Call is the parameters to a task call
+type Call struct {
+	Task   string
+	Vars   *Vars
+	Silent bool
+	Direct bool // Was the task called directly or via another task?
+}

taskfile/ast/cmd.go

@@ -0,0 +1,117 @@
+package ast
+
+import (
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/internal/deepcopy"
+)
+
+// Cmd is a task command
+type Cmd struct {
+	Cmd         string
+	Task        string
+	For         *For
+	Silent      bool
+	Set         []string
+	Shopt       []string
+	Vars        *Vars
+	IgnoreError bool
+	Defer       bool
+	Platforms   []*Platform
+}
+
+func (c *Cmd) DeepCopy() *Cmd {
+	if c == nil {
+		return nil
+	}
+	return &Cmd{
+		Cmd:         c.Cmd,
+		Task:        c.Task,
+		For:         c.For.DeepCopy(),
+		Silent:      c.Silent,
+		Set:         deepcopy.Slice(c.Set),
+		Shopt:       deepcopy.Slice(c.Shopt),
+		Vars:        c.Vars.DeepCopy(),
+		IgnoreError: c.IgnoreError,
+		Defer:       c.Defer,
+		Platforms:   deepcopy.Slice(c.Platforms),
+	}
+}
+
+func (c *Cmd) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+
+	case yaml.ScalarNode:
+		var cmd string
+		if err := node.Decode(&cmd); err != nil {
+			return err
+		}
+		c.Cmd = cmd
+		return nil
+
+	case yaml.MappingNode:
+
+		// A command with additional options
+		var cmdStruct struct {
+			Cmd         string
+			For         *For
+			Silent      bool
+			Set         []string
+			Shopt       []string
+			IgnoreError bool `yaml:"ignore_error"`
+			Platforms   []*Platform
+		}
+		if err := node.Decode(&cmdStruct); err == nil && cmdStruct.Cmd != "" {
+			c.Cmd = cmdStruct.Cmd
+			c.For = cmdStruct.For
+			c.Silent = cmdStruct.Silent
+			c.Set = cmdStruct.Set
+			c.Shopt = cmdStruct.Shopt
+			c.IgnoreError = cmdStruct.IgnoreError
+			c.Platforms = cmdStruct.Platforms
+			return nil
+		}
+
+		// A deferred command
+		var deferredCmd struct {
+			Defer string
+		}
+		if err := node.Decode(&deferredCmd); err == nil && deferredCmd.Defer != "" {
+			c.Defer = true
+			c.Cmd = deferredCmd.Defer
+			return nil
+		}
+
+		// A deferred task call
+		var deferredCall struct {
+			Defer Call
+		}
+		if err := node.Decode(&deferredCall); err == nil && deferredCall.Defer.Task != "" {
+			c.Defer = true
+			c.Task = deferredCall.Defer.Task
+			c.Vars = deferredCall.Defer.Vars
+			return nil
+		}
+
+		// A task call
+		var taskCall struct {
+			Task   string
+			Vars   *Vars
+			For    *For
+			Silent bool
+		}
+		if err := node.Decode(&taskCall); err == nil && taskCall.Task != "" {
+			c.Task = taskCall.Task
+			c.Vars = taskCall.Vars
+			c.For = taskCall.For
+			c.Silent = taskCall.Silent
+			return nil
+		}
+
+		return fmt.Errorf("yaml: line %d: invalid keys in command", node.Line)
+	}
+
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into command", node.Line, node.ShortTag())
+}

taskfile/ast/dep.go

@@ -0,0 +1,53 @@
+package ast
+
+import (
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+)
+
+// Dep is a task dependency
+type Dep struct {
+	Task   string
+	Vars   *Vars
+	Silent bool
+}
+
+func (d *Dep) DeepCopy() *Dep {
+	if d == nil {
+		return nil
+	}
+	return &Dep{
+		Task: d.Task,
+		Vars: d.Vars.DeepCopy(),
+	}
+}
+
+func (d *Dep) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+
+	case yaml.ScalarNode:
+		var task string
+		if err := node.Decode(&task); err != nil {
+			return err
+		}
+		d.Task = task
+		return nil
+
+	case yaml.MappingNode:
+		var taskCall struct {
+			Task   string
+			Vars   *Vars
+			Silent bool
+		}
+		if err := node.Decode(&taskCall); err != nil {
+			return err
+		}
+		d.Task = taskCall.Task
+		d.Vars = taskCall.Vars
+		d.Silent = taskCall.Silent
+		return nil
+	}
+
+	return fmt.Errorf("cannot unmarshal %s into dependency", node.ShortTag())
+}

taskfile/ast/for.go

@@ -0,0 +1,68 @@
+package ast
+
+import (
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/internal/deepcopy"
+)
+
+type For struct {
+	From  string
+	List  []any
+	Var   string
+	Split string
+	As    string
+}
+
+func (f *For) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+
+	case yaml.ScalarNode:
+		var from string
+		if err := node.Decode(&from); err != nil {
+			return err
+		}
+		f.From = from
+		return nil
+
+	case yaml.SequenceNode:
+		var list []any
+		if err := node.Decode(&list); err != nil {
+			return err
+		}
+		f.List = list
+		return nil
+
+	case yaml.MappingNode:
+		var forStruct struct {
+			Var   string
+			Split string
+			As    string
+		}
+		if err := node.Decode(&forStruct); err == nil && forStruct.Var != "" {
+			f.Var = forStruct.Var
+			f.Split = forStruct.Split
+			f.As = forStruct.As
+			return nil
+		}
+
+		return fmt.Errorf("yaml: line %d: invalid keys in for", node.Line)
+	}
+
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into for", node.Line, node.ShortTag())
+}
+
+func (f *For) DeepCopy() *For {
+	if f == nil {
+		return nil
+	}
+	return &For{
+		From:  f.From,
+		List:  deepcopy.Slice(f.List),
+		Var:   f.Var,
+		Split: f.Split,
+		As:    f.As,
+	}
+}

taskfile/ast/glob.go

@@ -0,0 +1,32 @@
+package ast
+
+import (
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+)
+
+type Glob struct {
+	Glob   string
+	Negate bool
+}
+
+func (g *Glob) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+	case yaml.ScalarNode:
+		g.Glob = node.Value
+		return nil
+	case yaml.MappingNode:
+		var glob struct {
+			Exclude string
+		}
+		if err := node.Decode(&glob); err != nil {
+			return err
+		}
+		g.Glob = glob.Exclude
+		g.Negate = true
+		return nil
+	default:
+		return fmt.Errorf("yaml: line %d: cannot unmarshal %s into task", node.Line, node.ShortTag())
+	}
+}

taskfile/ast/included_taskfile.go

@@ -0,0 +1,172 @@
+package ast
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+
+	"github.com/go-task/task/v3/internal/execext"
+	"github.com/go-task/task/v3/internal/filepathext"
+
+	"golang.org/x/exp/slices"
+	"gopkg.in/yaml.v3"
+)
+
+// IncludedTaskfile represents information about included taskfiles
+type IncludedTaskfile struct {
+	Taskfile       string
+	Dir            string
+	Optional       bool
+	Internal       bool
+	Aliases        []string
+	AdvancedImport bool
+	Vars           *Vars
+	BaseDir        string // The directory from which the including taskfile was loaded; used to resolve relative paths
+}
+
+// IncludedTaskfiles represents information about included tasksfiles
+type IncludedTaskfiles struct {
+	Keys    []string
+	Mapping map[string]IncludedTaskfile
+}
+
+// UnmarshalYAML implements the yaml.Unmarshaler interface.
+func (tfs *IncludedTaskfiles) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+	case yaml.MappingNode:
+		// NOTE(@andreynering): on this style of custom unmarshalling,
+		// even number contains the keys, while odd numbers contains
+		// the values.
+		for i := 0; i < len(node.Content); i += 2 {
+			keyNode := node.Content[i]
+			valueNode := node.Content[i+1]
+
+			var v IncludedTaskfile
+			if err := valueNode.Decode(&v); err != nil {
+				return err
+			}
+			tfs.Set(keyNode.Value, v)
+		}
+		return nil
+	}
+
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into included taskfiles", node.Line, node.ShortTag())
+}
+
+// Len returns the length of the map
+func (tfs *IncludedTaskfiles) Len() int {
+	if tfs == nil {
+		return 0
+	}
+	return len(tfs.Keys)
+}
+
+// Set sets a value to a given key
+func (tfs *IncludedTaskfiles) Set(key string, includedTaskfile IncludedTaskfile) {
+	if tfs.Mapping == nil {
+		tfs.Mapping = make(map[string]IncludedTaskfile, 1)
+	}
+	if !slices.Contains(tfs.Keys, key) {
+		tfs.Keys = append(tfs.Keys, key)
+	}
+	tfs.Mapping[key] = includedTaskfile
+}
+
+// Range allows you to loop into the included taskfiles in its right order
+func (tfs *IncludedTaskfiles) Range(yield func(key string, includedTaskfile IncludedTaskfile) error) error {
+	if tfs == nil {
+		return nil
+	}
+	for _, k := range tfs.Keys {
+		if err := yield(k, tfs.Mapping[k]); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (it *IncludedTaskfile) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+
+	case yaml.ScalarNode:
+		var str string
+		if err := node.Decode(&str); err != nil {
+			return err
+		}
+		it.Taskfile = str
+		return nil
+
+	case yaml.MappingNode:
+		var includedTaskfile struct {
+			Taskfile string
+			Dir      string
+			Optional bool
+			Internal bool
+			Aliases  []string
+			Vars     *Vars
+		}
+		if err := node.Decode(&includedTaskfile); err != nil {
+			return err
+		}
+		it.Taskfile = includedTaskfile.Taskfile
+		it.Dir = includedTaskfile.Dir
+		it.Optional = includedTaskfile.Optional
+		it.Internal = includedTaskfile.Internal
+		it.Aliases = includedTaskfile.Aliases
+		it.AdvancedImport = true
+		it.Vars = includedTaskfile.Vars
+		return nil
+	}
+
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into included taskfile", node.Line, node.ShortTag())
+}
+
+// DeepCopy creates a new instance of IncludedTaskfile and copies
+// data by value from the source struct.
+func (it *IncludedTaskfile) DeepCopy() *IncludedTaskfile {
+	if it == nil {
+		return nil
+	}
+	return &IncludedTaskfile{
+		Taskfile:       it.Taskfile,
+		Dir:            it.Dir,
+		Optional:       it.Optional,
+		Internal:       it.Internal,
+		AdvancedImport: it.AdvancedImport,
+		Vars:           it.Vars.DeepCopy(),
+		BaseDir:        it.BaseDir,
+	}
+}
+
+// FullTaskfilePath returns the fully qualified path to the included taskfile
+func (it *IncludedTaskfile) FullTaskfilePath() (string, error) {
+	return it.resolvePath(it.Taskfile)
+}
+
+// FullDirPath returns the fully qualified path to the included taskfile's working directory
+func (it *IncludedTaskfile) FullDirPath() (string, error) {
+	return it.resolvePath(it.Dir)
+}
+
+func (it *IncludedTaskfile) resolvePath(path string) (string, error) {
+	// If the file is remote, we don't need to resolve the path
+	if strings.Contains(it.Taskfile, "://") {
+		return path, nil
+	}
+
+	path, err := execext.Expand(path)
+	if err != nil {
+		return "", err
+	}
+
+	if filepathext.IsAbs(path) {
+		return path, nil
+	}
+
+	result, err := filepath.Abs(filepathext.SmartJoin(it.BaseDir, path))
+	if err != nil {
+		return "", fmt.Errorf("task: error resolving path %s relative to %s: %w", path, it.BaseDir, err)
+	}
+
+	return result, nil
+}

taskfile/ast/location.go

@@ -0,0 +1,18 @@
+package ast
+
+type Location struct {
+	Line     int
+	Column   int
+	Taskfile string
+}
+
+func (l *Location) DeepCopy() *Location {
+	if l == nil {
+		return nil
+	}
+	return &Location{
+		Line:     l.Line,
+		Column:   l.Column,
+		Taskfile: l.Taskfile,
+	}
+}

taskfile/ast/output.go

@@ -0,0 +1,65 @@
+package ast
+
+import (
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+)
+
+// Output of the Task output
+type Output struct {
+	// Name of the Output.
+	Name string `yaml:"-"`
+	// Group specific style
+	Group OutputGroup
+}
+
+// IsSet returns true if and only if a custom output style is set.
+func (s *Output) IsSet() bool {
+	return s.Name != ""
+}
+
+func (s *Output) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+
+	case yaml.ScalarNode:
+		var name string
+		if err := node.Decode(&name); err != nil {
+			return err
+		}
+		s.Name = name
+		return nil
+
+	case yaml.MappingNode:
+		var tmp struct {
+			Group *OutputGroup
+		}
+		if err := node.Decode(&tmp); err != nil {
+			return fmt.Errorf("task: output style must be a string or mapping with a \"group\" key: %w", err)
+		}
+		if tmp.Group == nil {
+			return fmt.Errorf("task: output style must have the \"group\" key when in mapping form")
+		}
+		*s = Output{
+			Name:  "group",
+			Group: *tmp.Group,
+		}
+		return nil
+	}
+
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into output", node.Line, node.ShortTag())
+}
+
+// OutputGroup is the style options specific to the Group style.
+type OutputGroup struct {
+	Begin, End string
+	ErrorOnly  bool `yaml:"error_only"`
+}
+
+// IsSet returns true if and only if a custom output style is set.
+func (g *OutputGroup) IsSet() bool {
+	if g == nil {
+		return false
+	}
+	return g.Begin != "" || g.End != ""
+}

taskfile/ast/platforms.go

@@ -0,0 +1,100 @@
+package ast
+
+import (
+	"fmt"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/internal/goext"
+)
+
+// Platform represents GOOS and GOARCH values
+type Platform struct {
+	OS   string
+	Arch string
+}
+
+func (p *Platform) DeepCopy() *Platform {
+	if p == nil {
+		return nil
+	}
+	return &Platform{
+		OS:   p.OS,
+		Arch: p.Arch,
+	}
+}
+
+type ErrInvalidPlatform struct {
+	Platform string
+}
+
+func (err *ErrInvalidPlatform) Error() string {
+	return fmt.Sprintf(`task: Invalid platform "%s"`, err.Platform)
+}
+
+// UnmarshalYAML implements yaml.Unmarshaler interface.
+func (p *Platform) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+	case yaml.ScalarNode:
+		var platform string
+		if err := node.Decode(&platform); err != nil {
+			return err
+		}
+		if err := p.parsePlatform(platform); err != nil {
+			return err
+		}
+		return nil
+	}
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into platform", node.Line, node.ShortTag())
+}
+
+// parsePlatform takes a string representing an OS/Arch combination (or either on their own)
+// and parses it into the Platform struct. It returns an error if the input string is invalid.
+// Valid combinations for input: OS, Arch, OS/Arch
+func (p *Platform) parsePlatform(input string) error {
+	splitValues := strings.Split(input, "/")
+	if len(splitValues) > 2 {
+		return &ErrInvalidPlatform{Platform: input}
+	}
+	if err := p.parseOsOrArch(splitValues[0]); err != nil {
+		return &ErrInvalidPlatform{Platform: input}
+	}
+	if len(splitValues) == 2 {
+		if err := p.parseArch(splitValues[1]); err != nil {
+			return &ErrInvalidPlatform{Platform: input}
+		}
+	}
+	return nil
+}
+
+// parseOsOrArch will check if the given input is a valid OS or Arch value.
+// If so, it will store it. If not, an error is returned
+func (p *Platform) parseOsOrArch(osOrArch string) error {
+	if osOrArch == "" {
+		return fmt.Errorf("task: Blank OS/Arch value provided")
+	}
+	if goext.IsKnownOS(osOrArch) {
+		p.OS = osOrArch
+		return nil
+	}
+	if goext.IsKnownArch(osOrArch) {
+		p.Arch = osOrArch
+		return nil
+	}
+	return fmt.Errorf("task: Invalid OS/Arch value provided (%s)", osOrArch)
+}
+
+func (p *Platform) parseArch(arch string) error {
+	if arch == "" {
+		return fmt.Errorf("task: Blank Arch value provided")
+	}
+	if p.Arch != "" {
+		return fmt.Errorf("task: Multiple Arch values provided")
+	}
+	if goext.IsKnownArch(arch) {
+		p.Arch = arch
+		return nil
+	}
+	return fmt.Errorf("task: Invalid Arch value provided (%s)", arch)
+}

taskfile/ast/platforms_test.go

@@ -0,0 +1,50 @@
+package ast
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPlatformParsing(t *testing.T) {
+	tests := []struct {
+		Input        string
+		ExpectedOS   string
+		ExpectedArch string
+		Error        string
+	}{
+		{Input: "windows", ExpectedOS: "windows", ExpectedArch: ""},
+		{Input: "linux", ExpectedOS: "linux", ExpectedArch: ""},
+		{Input: "darwin", ExpectedOS: "darwin", ExpectedArch: ""},
+
+		{Input: "386", ExpectedOS: "", ExpectedArch: "386"},
+		{Input: "amd64", ExpectedOS: "", ExpectedArch: "amd64"},
+		{Input: "arm64", ExpectedOS: "", ExpectedArch: "arm64"},
+
+		{Input: "windows/386", ExpectedOS: "windows", ExpectedArch: "386"},
+		{Input: "windows/amd64", ExpectedOS: "windows", ExpectedArch: "amd64"},
+		{Input: "windows/arm64", ExpectedOS: "windows", ExpectedArch: "arm64"},
+
+		{Input: "invalid", Error: `task: Invalid platform "invalid"`},
+		{Input: "invalid/invalid", Error: `task: Invalid platform "invalid/invalid"`},
+		{Input: "windows/invalid", Error: `task: Invalid platform "windows/invalid"`},
+		{Input: "invalid/amd64", Error: `task: Invalid platform "invalid/amd64"`},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Input, func(t *testing.T) {
+			var p Platform
+			err := p.parsePlatform(test.Input)
+
+			if test.Error != "" {
+				require.Error(t, err)
+				assert.Equal(t, test.Error, err.Error())
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, test.ExpectedOS, p.OS)
+				assert.Equal(t, test.ExpectedArch, p.Arch)
+			}
+		})
+	}
+}

taskfile/ast/precondition.go

@@ -0,0 +1,59 @@
+package ast
+
+import (
+	"errors"
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+)
+
+// ErrCantUnmarshalPrecondition is returned for invalid precond YAML.
+var ErrCantUnmarshalPrecondition = errors.New("task: Can't unmarshal precondition value")
+
+// Precondition represents a precondition necessary for a task to run
+type Precondition struct {
+	Sh  string
+	Msg string
+}
+
+func (p *Precondition) DeepCopy() *Precondition {
+	if p == nil {
+		return nil
+	}
+	return &Precondition{
+		Sh:  p.Sh,
+		Msg: p.Msg,
+	}
+}
+
+// UnmarshalYAML implements yaml.Unmarshaler interface.
+func (p *Precondition) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+
+	case yaml.ScalarNode:
+		var cmd string
+		if err := node.Decode(&cmd); err != nil {
+			return err
+		}
+		p.Sh = cmd
+		p.Msg = fmt.Sprintf("`%s` failed", cmd)
+		return nil
+
+	case yaml.MappingNode:
+		var sh struct {
+			Sh  string
+			Msg string
+		}
+		if err := node.Decode(&sh); err != nil {
+			return err
+		}
+		p.Sh = sh.Sh
+		p.Msg = sh.Msg
+		if p.Msg == "" {
+			p.Msg = fmt.Sprintf("%s failed", sh.Sh)
+		}
+		return nil
+	}
+
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into precondition", node.Line, node.ShortTag())
+}

taskfile/ast/precondition_test.go

@@ -0,0 +1,51 @@
+package ast_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/taskfile/ast"
+)
+
+func TestPreconditionParse(t *testing.T) {
+	tests := []struct {
+		content  string
+		v        any
+		expected any
+	}{
+		{
+			"test -f foo.txt",
+			&ast.Precondition{},
+			&ast.Precondition{Sh: `test -f foo.txt`, Msg: "`test -f foo.txt` failed"},
+		},
+		{
+			"sh: '[ 1 = 0 ]'",
+			&ast.Precondition{},
+			&ast.Precondition{Sh: "[ 1 = 0 ]", Msg: "[ 1 = 0 ] failed"},
+		},
+		{
+			`
+sh: "[ 1 = 2 ]"
+msg: "1 is not 2"
+`,
+			&ast.Precondition{},
+			&ast.Precondition{Sh: "[ 1 = 2 ]", Msg: "1 is not 2"},
+		},
+		{
+			`
+sh: "[ 1 = 2 ]"
+msg: "1 is not 2"
+`,
+			&ast.Precondition{},
+			&ast.Precondition{Sh: "[ 1 = 2 ]", Msg: "1 is not 2"},
+		},
+	}
+	for _, test := range tests {
+		err := yaml.Unmarshal([]byte(test.content), test.v)
+		require.NoError(t, err)
+		assert.Equal(t, test.expected, test.v)
+	}
+}

taskfile/ast/requires.go

@@ -0,0 +1,18 @@
+package ast
+
+import "github.com/go-task/task/v3/internal/deepcopy"
+
+// Requires represents a set of required variables necessary for a task to run
+type Requires struct {
+	Vars []string
+}
+
+func (r *Requires) DeepCopy() *Requires {
+	if r == nil {
+		return nil
+	}
+
+	return &Requires{
+		Vars: deepcopy.Slice(r.Vars),
+	}
+}

taskfile/ast/task.go

@@ -0,0 +1,190 @@
+package ast
+
+import (
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/internal/deepcopy"
+)
+
+// Task represents a task
+type Task struct {
+	Task                 string
+	Cmds                 []*Cmd
+	Deps                 []*Dep
+	Label                string
+	Desc                 string
+	Prompt               string
+	Summary              string
+	Requires             *Requires
+	Aliases              []string
+	Sources              []*Glob
+	Generates            []*Glob
+	Status               []string
+	Preconditions        []*Precondition
+	Dir                  string
+	Set                  []string
+	Shopt                []string
+	Vars                 *Vars
+	Env                  *Vars
+	Dotenv               []string
+	Silent               bool
+	Interactive          bool
+	Internal             bool
+	Method               string
+	Prefix               string
+	IgnoreError          bool
+	Run                  string
+	IncludeVars          *Vars
+	IncludedTaskfileVars *Vars
+	IncludedTaskfile     *IncludedTaskfile
+	Platforms            []*Platform
+	Location             *Location
+	Watch                bool
+}
+
+func (t *Task) Name() string {
+	if t.Label != "" {
+		return t.Label
+	}
+	return t.Task
+}
+
+func (t *Task) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+
+	// Shortcut syntax for a task with a single command
+	case yaml.ScalarNode:
+		var cmd Cmd
+		if err := node.Decode(&cmd); err != nil {
+			return err
+		}
+		t.Cmds = append(t.Cmds, &cmd)
+		return nil
+
+	// Shortcut syntax for a simple task with a list of commands
+	case yaml.SequenceNode:
+		var cmds []*Cmd
+		if err := node.Decode(&cmds); err != nil {
+			return err
+		}
+		t.Cmds = cmds
+		return nil
+
+	// Full task object
+	case yaml.MappingNode:
+		var task struct {
+			Cmds          []*Cmd
+			Cmd           *Cmd
+			Deps          []*Dep
+			Label         string
+			Desc          string
+			Prompt        string
+			Summary       string
+			Aliases       []string
+			Sources       []*Glob
+			Generates     []*Glob
+			Status        []string
+			Preconditions []*Precondition
+			Dir           string
+			Set           []string
+			Shopt         []string
+			Vars          *Vars
+			Env           *Vars
+			Dotenv        []string
+			Silent        bool
+			Interactive   bool
+			Internal      bool
+			Method        string
+			Prefix        string
+			IgnoreError   bool `yaml:"ignore_error"`
+			Run           string
+			Platforms     []*Platform
+			Requires      *Requires
+			Watch         bool
+		}
+		if err := node.Decode(&task); err != nil {
+			return err
+		}
+		if task.Cmd != nil {
+			if task.Cmds != nil {
+				return fmt.Errorf("yaml: line %d: task cannot have both cmd and cmds", node.Line)
+			}
+			t.Cmds = []*Cmd{task.Cmd}
+		} else {
+			t.Cmds = task.Cmds
+		}
+		t.Deps = task.Deps
+		t.Label = task.Label
+		t.Desc = task.Desc
+		t.Prompt = task.Prompt
+		t.Summary = task.Summary
+		t.Aliases = task.Aliases
+		t.Sources = task.Sources
+		t.Generates = task.Generates
+		t.Status = task.Status
+		t.Preconditions = task.Preconditions
+		t.Dir = task.Dir
+		t.Set = task.Set
+		t.Shopt = task.Shopt
+		t.Vars = task.Vars
+		t.Env = task.Env
+		t.Dotenv = task.Dotenv
+		t.Silent = task.Silent
+		t.Interactive = task.Interactive
+		t.Internal = task.Internal
+		t.Method = task.Method
+		t.Prefix = task.Prefix
+		t.IgnoreError = task.IgnoreError
+		t.Run = task.Run
+		t.Platforms = task.Platforms
+		t.Requires = task.Requires
+		t.Watch = task.Watch
+		return nil
+	}
+
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into task", node.Line, node.ShortTag())
+}
+
+// DeepCopy creates a new instance of Task and copies
+// data by value from the source struct.
+func (t *Task) DeepCopy() *Task {
+	if t == nil {
+		return nil
+	}
+	c := &Task{
+		Task:                 t.Task,
+		Cmds:                 deepcopy.Slice(t.Cmds),
+		Deps:                 deepcopy.Slice(t.Deps),
+		Label:                t.Label,
+		Desc:                 t.Desc,
+		Prompt:               t.Prompt,
+		Summary:              t.Summary,
+		Aliases:              deepcopy.Slice(t.Aliases),
+		Sources:              deepcopy.Slice(t.Sources),
+		Generates:            deepcopy.Slice(t.Generates),
+		Status:               deepcopy.Slice(t.Status),
+		Preconditions:        deepcopy.Slice(t.Preconditions),
+		Dir:                  t.Dir,
+		Set:                  deepcopy.Slice(t.Set),
+		Shopt:                deepcopy.Slice(t.Shopt),
+		Vars:                 t.Vars.DeepCopy(),
+		Env:                  t.Env.DeepCopy(),
+		Dotenv:               deepcopy.Slice(t.Dotenv),
+		Silent:               t.Silent,
+		Interactive:          t.Interactive,
+		Internal:             t.Internal,
+		Method:               t.Method,
+		Prefix:               t.Prefix,
+		IgnoreError:          t.IgnoreError,
+		Run:                  t.Run,
+		IncludeVars:          t.IncludeVars.DeepCopy(),
+		IncludedTaskfileVars: t.IncludedTaskfileVars.DeepCopy(),
+		IncludedTaskfile:     t.IncludedTaskfile.DeepCopy(),
+		Platforms:            deepcopy.Slice(t.Platforms),
+		Location:             t.Location.DeepCopy(),
+		Requires:             t.Requires.DeepCopy(),
+	}
+	return c
+}

taskfile/ast/taskfile.go

@@ -0,0 +1,80 @@
+package ast
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/Masterminds/semver/v3"
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/errors"
+)
+
+var V3 = semver.MustParse("3")
+
+// Taskfile is the abstract syntax tree for a Taskfile
+type Taskfile struct {
+	Location string
+	Version  *semver.Version
+	Output   Output
+	Method   string
+	Includes *IncludedTaskfiles
+	Set      []string
+	Shopt    []string
+	Vars     *Vars
+	Env      *Vars
+	Tasks    Tasks
+	Silent   bool
+	Dotenv   []string
+	Run      string
+	Interval time.Duration
+}
+
+func (tf *Taskfile) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+	case yaml.MappingNode:
+		var taskfile struct {
+			Version  *semver.Version
+			Output   Output
+			Method   string
+			Includes *IncludedTaskfiles
+			Set      []string
+			Shopt    []string
+			Vars     *Vars
+			Env      *Vars
+			Tasks    Tasks
+			Silent   bool
+			Dotenv   []string
+			Run      string
+			Interval time.Duration
+		}
+		if err := node.Decode(&taskfile); err != nil {
+			return err
+		}
+		tf.Version = taskfile.Version
+		tf.Output = taskfile.Output
+		tf.Method = taskfile.Method
+		tf.Includes = taskfile.Includes
+		tf.Set = taskfile.Set
+		tf.Shopt = taskfile.Shopt
+		tf.Vars = taskfile.Vars
+		tf.Env = taskfile.Env
+		tf.Tasks = taskfile.Tasks
+		tf.Silent = taskfile.Silent
+		tf.Dotenv = taskfile.Dotenv
+		tf.Run = taskfile.Run
+		tf.Interval = taskfile.Interval
+		if tf.Version == nil {
+			return errors.New("task: 'version' is required")
+		}
+		if tf.Vars == nil {
+			tf.Vars = &Vars{}
+		}
+		if tf.Env == nil {
+			tf.Env = &Vars{}
+		}
+		return nil
+	}
+
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into taskfile", node.Line, node.ShortTag())
+}

taskfile/ast/taskfile_test.go

@@ -0,0 +1,98 @@
+package ast_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/internal/orderedmap"
+	"github.com/go-task/task/v3/taskfile/ast"
+)
+
+func TestCmdParse(t *testing.T) {
+	const (
+		yamlCmd      = `echo "a string command"`
+		yamlDep      = `"task-name"`
+		yamlTaskCall = `
+task: another-task
+vars:
+  PARAM1: VALUE1
+  PARAM2: VALUE2
+`
+		yamlDeferredCall = `defer: { task: some_task, vars: { PARAM1: "var" } }`
+		yamlDeferredCmd  = `defer: echo 'test'`
+	)
+	tests := []struct {
+		content  string
+		v        any
+		expected any
+	}{
+		{
+			yamlCmd,
+			&ast.Cmd{},
+			&ast.Cmd{Cmd: `echo "a string command"`},
+		},
+		{
+			yamlTaskCall,
+			&ast.Cmd{},
+			&ast.Cmd{
+				Task: "another-task", Vars: &ast.Vars{
+					OrderedMap: orderedmap.FromMapWithOrder(
+						map[string]ast.Var{
+							"PARAM1": {Value: "VALUE1"},
+							"PARAM2": {Value: "VALUE2"},
+						},
+						[]string{"PARAM1", "PARAM2"},
+					),
+				},
+			},
+		},
+		{
+			yamlDeferredCmd,
+			&ast.Cmd{},
+			&ast.Cmd{Cmd: "echo 'test'", Defer: true},
+		},
+		{
+			yamlDeferredCall,
+			&ast.Cmd{},
+			&ast.Cmd{
+				Task: "some_task", Vars: &ast.Vars{
+					OrderedMap: orderedmap.FromMapWithOrder(
+						map[string]ast.Var{
+							"PARAM1": {Value: "var"},
+						},
+						[]string{"PARAM1"},
+					),
+				},
+				Defer: true,
+			},
+		},
+		{
+			yamlDep,
+			&ast.Dep{},
+			&ast.Dep{Task: "task-name"},
+		},
+		{
+			yamlTaskCall,
+			&ast.Dep{},
+			&ast.Dep{
+				Task: "another-task", Vars: &ast.Vars{
+					OrderedMap: orderedmap.FromMapWithOrder(
+						map[string]ast.Var{
+							"PARAM1": {Value: "VALUE1"},
+							"PARAM2": {Value: "VALUE2"},
+						},
+						[]string{"PARAM1", "PARAM2"},
+					),
+				},
+			},
+		},
+	}
+	for _, test := range tests {
+		err := yaml.Unmarshal([]byte(test.content), test.v)
+		require.NoError(t, err)
+		assert.Equal(t, test.expected, test.v)
+	}
+}

taskfile/ast/tasks.go

@@ -0,0 +1,54 @@
+package ast
+
+import (
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/internal/orderedmap"
+)
+
+// Tasks represents a group of tasks
+type Tasks struct {
+	orderedmap.OrderedMap[string, *Task]
+}
+
+func (t *Tasks) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+	case yaml.MappingNode:
+		tasks := orderedmap.New[string, *Task]()
+		if err := node.Decode(&tasks); err != nil {
+			return err
+		}
+
+		// nolint: errcheck
+		tasks.Range(func(name string, task *Task) error {
+			// Set the task's name
+			if task == nil {
+				task = &Task{
+					Task: name,
+				}
+			}
+			task.Task = name
+
+			// Set the task's location
+			for _, keys := range node.Content {
+				if keys.Value == name {
+					task.Location = &Location{
+						Line:   keys.Line,
+						Column: keys.Column,
+					}
+				}
+			}
+			tasks.Set(name, task)
+			return nil
+		})
+
+		*t = Tasks{
+			OrderedMap: tasks,
+		}
+		return nil
+	}
+
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into tasks", node.Line, node.ShortTag())
+}

taskfile/ast/var.go

@@ -0,0 +1,121 @@
+package ast
+
+import (
+	"fmt"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/internal/experiments"
+	"github.com/go-task/task/v3/internal/orderedmap"
+)
+
+// Vars is a string[string] variables map.
+type Vars struct {
+	orderedmap.OrderedMap[string, Var]
+}
+
+// ToCacheMap converts Vars to a map containing only the static
+// variables
+func (vs *Vars) ToCacheMap() (m map[string]any) {
+	m = make(map[string]any, vs.Len())
+	_ = vs.Range(func(k string, v Var) error {
+		if v.Sh != "" {
+			// Dynamic variable is not yet resolved; trigger
+			// <no value> to be used in templates.
+			return nil
+		}
+
+		if v.Live != nil {
+			m[k] = v.Live
+		} else {
+			m[k] = v.Value
+		}
+		return nil
+	})
+	return
+}
+
+// Wrapper around OrderedMap.Set to ensure we don't get nil pointer errors
+func (vs *Vars) Range(f func(k string, v Var) error) error {
+	if vs == nil {
+		return nil
+	}
+	return vs.OrderedMap.Range(f)
+}
+
+// Wrapper around OrderedMap.Merge to ensure we don't get nil pointer errors
+func (vs *Vars) Merge(other *Vars) {
+	if vs == nil || other == nil {
+		return
+	}
+	vs.OrderedMap.Merge(other.OrderedMap)
+}
+
+// Wrapper around OrderedMap.Len to ensure we don't get nil pointer errors
+func (vs *Vars) Len() int {
+	if vs == nil {
+		return 0
+	}
+	return vs.OrderedMap.Len()
+}
+
+// DeepCopy creates a new instance of Vars and copies
+// data by value from the source struct.
+func (vs *Vars) DeepCopy() *Vars {
+	if vs == nil {
+		return nil
+	}
+	return &Vars{
+		OrderedMap: vs.OrderedMap.DeepCopy(),
+	}
+}
+
+// Var represents either a static or dynamic variable.
+type Var struct {
+	Value any
+	Live  any
+	Sh    string
+	Dir   string
+}
+
+func (v *Var) UnmarshalYAML(node *yaml.Node) error {
+	if experiments.AnyVariables {
+		var value any
+		if err := node.Decode(&value); err != nil {
+			return err
+		}
+		// If the value is a string and it starts with $, then it's a shell command
+		if str, ok := value.(string); ok {
+			if str, ok = strings.CutPrefix(str, "$"); ok {
+				v.Sh = str
+				return nil
+			}
+		}
+		v.Value = value
+		return nil
+	}
+
+	switch node.Kind {
+
+	case yaml.ScalarNode:
+		var str string
+		if err := node.Decode(&str); err != nil {
+			return err
+		}
+		v.Value = str
+		return nil
+
+	case yaml.MappingNode:
+		var sh struct {
+			Sh string
+		}
+		if err := node.Decode(&sh); err != nil {
+			return err
+		}
+		v.Sh = sh.Sh
+		return nil
+	}
+
+	return fmt.Errorf("yaml: line %d: cannot unmarshal %s into variable", node.Line, node.ShortTag())
+}