feat: add TASK_SOURCES special variable

This commit adds the `TASK_SOURCES` variable to tasks. If a task defines
the `sources` key, `TASK_SOURCES` contains the list of paths referenced
by `sources`. Globs are expanded.

This was initially implemented by @hernandanielg in #1146 to fix #948.

Author: fhofherr

internal/compiler/compiler.go

@@ -12,6 +12,7 @@ import (
 	"github.com/go-task/task/v3/internal/env"
 	"github.com/go-task/task/v3/internal/execext"
 	"github.com/go-task/task/v3/internal/filepathext"
+	"github.com/go-task/task/v3/internal/fingerprint"
 	"github.com/go-task/task/v3/internal/logger"
 	"github.com/go-task/task/v3/internal/templater"
 	"github.com/go-task/task/v3/internal/version"
@@ -184,19 +185,27 @@ func (c *Compiler) ResetCache() {
 	c.dynamicCache = nil
 }
 
-func (c *Compiler) getSpecialVars(t *ast.Task, call *ast.Call) (map[string]string, error) {
-	allVars := map[string]string{
+func (c *Compiler) getSpecialVars(t *ast.Task, call *ast.Call) (map[string]any, error) {
+	allVars := map[string]any{
 		"TASK_EXE":         filepath.ToSlash(os.Args[0]),
 		"ROOT_TASKFILE":    filepathext.SmartJoin(c.Dir, c.Entrypoint),
 		"ROOT_DIR":         c.Dir,
 		"USER_WORKING_DIR": c.UserWorkingDir,
 		"TASK_VERSION":     version.GetVersion(),
 	}
 	if t != nil {
+		dir := filepathext.SmartJoin(c.Dir, t.Dir)
+
+		taskSources, err := fingerprint.Globs(dir, t.Sources)
+		if err != nil {
+			return allVars, fmt.Errorf("expand globs: %v", err)
+		}
+
 		allVars["TASK"] = t.Task
-		allVars["TASK_DIR"] = filepathext.SmartJoin(c.Dir, t.Dir)
+		allVars["TASK_DIR"] = dir
 		allVars["TASKFILE"] = t.Location.Taskfile
 		allVars["TASKFILE_DIR"] = filepath.Dir(t.Location.Taskfile)
+		allVars["TASK_SOURCES"] = taskSources
 	}
 	if call != nil {
 		allVars["ALIAS"] = call.Task

task_test.go

@@ -231,6 +231,15 @@ func TestSpecialVars(t *testing.T) {
 		{target: "print-taskfile-dir", expected: toAbs(dir)},
 		{target: "print-task-version", expected: "unknown"},
 		{target: "print-task-dir", expected: toAbs(dir) + "/foo"},
+		{
+			target: "print-task-sources",
+			expected: "[" +
+				toAbs(dir) + "/sources-as-var/file.txt, " +
+				toAbs(dir) + "/sources-as-var/subdir1/file.txt, " +
+				toAbs(dir) + "/sources-as-var/subdir2/file.txt" +
+				"]",
+		},
+		{target: "print-task-sources-empty", expected: "[]"},
 		// Included
 		{target: "included:print-task", expected: "included:print-task"},
 		{target: "included:print-root-dir", expected: toAbs(dir)},
@@ -251,6 +260,8 @@ func TestSpecialVars(t *testing.T) {
 					Stderr:             &buff,
 					Silent:             true,
 					EnableVersionCheck: true,
+					// NOTE needed to enable Force to ignore fingerprints generated
+					Force: true,
 				}
 				require.NoError(t, e.Setup())
 				require.NoError(t, e.Run(context.Background(), &ast.Call{Task: test.target}))

testdata/special_vars/Taskfile.yml

@@ -22,3 +22,14 @@ tasks:
   print-task-dir:
     dir: 'foo'
     cmd: echo {{.TASK_DIR}}
+
+  print-task-sources:
+    sources:
+      - sources-as-var/**/*.txt
+    cmds:
+      - echo "[{{.TASK_SOURCES | sortAlpha | join ", "}}]"
+
+  print-task-sources-empty:
+    # No sources defined, yet we try to use TASK_SOURCES.
+    cmds:
+      - echo "{{.TASK_SOURCES}}"

testdata/special_vars/sources-as-var/file.txt

@@ -115,6 +115,7 @@ special variable will be overridden.
 | `TASKFILE`         | The absolute path of the included Taskfile.                                                                                                              |
 | `TASKFILE_DIR`     | The absolute path of the included Taskfile directory.                                                                                                    |
 | `TASK_DIR`         | The absolute path of the directory where the task is executed.                                                                                           |
+| `TASK_SOURCES`     | List of files referenced by task `sources` key. Empty if task does not define `sources`.                                                                 |
 | `USER_WORKING_DIR` | The absolute path of the directory `task` was called from.                                                                                               |
 | `CHECKSUM`         | The checksum of the files listed in `sources`. Only available within the `status` prop and if method is set to `checksum`.                               |
 | `TIMESTAMP`        | The date object of the greatest timestamp of the files listed in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |