fix: validate include 'taskfile' field, suggest 'vars:' if missing

task_test.go

@@ -1064,6 +1064,25 @@ func TestIncludeCycle(t *testing.T) {
 	assert.Contains(t, err.Error(), "task: include cycle detected between")
 }
 
+func TestIncludesMissingTaskfile(t *testing.T) {
+	t.Parallel()
+
+	const dir = "testdata/includes_missing_taskfile"
+
+	var buff bytes.Buffer
+	e := task.NewExecutor(
+		task.WithDir(dir),
+		task.WithStdout(&buff),
+		task.WithStderr(&buff),
+		task.WithSilent(true),
+	)
+
+	err := e.Setup()
+	require.Error(t, err)
+	assert.NotContains(t, err.Error(), "include cycle detected", "should not report a cycle error for a missing taskfile field")
+	assert.Contains(t, err.Error(), "missing the required \"taskfile\" field")
+}
+
 func TestIncludesIncorrect(t *testing.T) {
 	t.Parallel()
 

taskfile/ast/include.go

@@ -1,6 +1,7 @@
 package ast
 
 import (
+	"fmt"
 	"iter"
 	"sync"
 
@@ -133,6 +134,26 @@ func (includes *Includes) UnmarshalYAML(node *yaml.Node) error {
 				return errors.NewTaskfileDecodeError(err, node)
 			}
 
+			// Validate that the include has a Taskfile path specified.
+			// If it doesn't, suggest the user may have meant to use 'vars:' instead
+			// of 'includes:' — a common copy-paste mistake that otherwise produces
+			// a misleading "include cycle detected" error downstream.
+			if v.Taskfile == "" {
+				rawKeys := []string{}
+				for j := 0; j < len(valueNode.Content); j += 2 {
+					rawKeys = append(rawKeys, valueNode.Content[j].Value)
+				}
+				keysStr := ""
+				if len(rawKeys) > 0 {
+					keysStr = fmt.Sprintf(" (unexpected keys: %v)", rawKeys)
+				}
+				err := fmt.Errorf(
+					"include \"%s\" is missing the required \"taskfile\" field%s; did you mean to use \"vars:\" instead?",
+					keyNode.Value, keysStr,
+				)
+				return errors.NewTaskfileDecodeError(err, valueNode)
+			}
+
 			// Set the include namespace
 			v.Namespace = keyNode.Value
 

testdata/includes_missing_taskfile/Taskfile.yml

@@ -0,0 +1,9 @@
+version: '3'
+
+includes:
+  common: ./TaskfileCommon.yml
+
+tasks:
+  test:
+    cmds:
+      - task: common:test

testdata/includes_missing_taskfile/TaskfileCommon.yml

@@ -0,0 +1,10 @@
+version: '3'
+
+includes:
+  GOBIN:
+    sh: echo $(go env GOPATH)/bin
+
+tasks:
+  test:
+    cmds:
+      - "{{.GOBIN}}/richgo test ./..."