fix: preserve dotenv declaration order

internal/dotenv/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2013 John Barton
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

internal/dotenv/dotenv.go

@@ -0,0 +1,22 @@
+// Package dotenv reads environment files in declaration order.
+package dotenv
+
+import (
+	"os"
+
+	"github.com/elliotchance/orderedmap/v3"
+)
+
+// Read reads a dotenv file, preserving the order of its variable declarations.
+// Repeated keys retain their original position and take their last value.
+func Read(filename string) (*orderedmap.OrderedMap[string, string], error) {
+	data, err := os.ReadFile(filename)
+	if err != nil {
+		return nil, err
+	}
+	vars := orderedmap.NewOrderedMap[string, string]()
+	if err := parseBytes(data, vars); err != nil {
+		return nil, err
+	}
+	return vars, nil
+}

internal/dotenv/dotenv_test.go

@@ -0,0 +1,50 @@
+package dotenv_test
+
+import (
+	"maps"
+	"os"
+	"path/filepath"
+	"slices"
+	"testing"
+
+	"github.com/joho/godotenv"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/go-task/task/v3/internal/dotenv"
+)
+
+func TestRead(t *testing.T) {
+	t.Parallel()
+
+	tests := map[string]string{
+		"syntax":             "# comment\r\nexport Z=first\r\nA=${Z}/nested # comment\r\nM: yaml\r\nZ=last\r\nEMPTY=\r\n",
+		"quotes":             "BASE=/home/user\nSINGLE='$BASE'\nDOUBLE=\"${BASE}/nested\\nnext\"\nMULTI='line one\nline two'\nESCAPED=\\$BASE\nTEMPLATE={{.BASE}}/nested",
+		"invalid key":        "BAD-KEY=value\n",
+		"unterminated quote": "VALUE=\"unfinished\n",
+	}
+	for name, content := range tests {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+			path := filepath.Join(t.TempDir(), ".env")
+			require.NoError(t, os.WriteFile(path, []byte(content), 0o600))
+			expected, expectedErr := godotenv.Unmarshal(content)
+			actual, err := dotenv.Read(path)
+			if expectedErr != nil {
+				require.EqualError(t, err, expectedErr.Error())
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, expected, maps.Collect(actual.AllFromFront()))
+			if name == "syntax" {
+				assert.Equal(t, []string{"Z", "A", "M", "EMPTY"}, slices.Collect(actual.Keys()))
+			}
+		})
+	}
+}
+
+func TestReadMissingFile(t *testing.T) {
+	t.Parallel()
+	_, err := dotenv.Read(filepath.Join(t.TempDir(), "missing.env"))
+	require.ErrorIs(t, err, os.ErrNotExist)
+}

internal/dotenv/parser.go

@@ -0,0 +1,276 @@
+// Adapted from github.com/joho/godotenv v1.5.1 to preserve declaration order.
+// See LICENSE for the original MIT license.
+package dotenv
+
+import (
+	"bytes"
+	"fmt"
+	"regexp"
+	"strings"
+	"unicode"
+
+	"github.com/elliotchance/orderedmap/v3"
+
+	"github.com/go-task/task/v3/errors"
+)
+
+const (
+	charComment       = '#'
+	prefixSingleQuote = '\''
+	prefixDoubleQuote = '"'
+
+	exportPrefix = "export"
+)
+
+func parseBytes(src []byte, out *orderedmap.OrderedMap[string, string]) error {
+	src = bytes.ReplaceAll(src, []byte("\r\n"), []byte("\n"))
+	cutset := src
+	for {
+		cutset = getStatementStart(cutset)
+		if cutset == nil {
+			// reached end of file
+			break
+		}
+
+		key, left, err := locateKeyName(cutset)
+		if err != nil {
+			return err
+		}
+
+		value, left, err := extractVarValue(left, out)
+		if err != nil {
+			return err
+		}
+
+		out.Set(key, value)
+		cutset = left
+	}
+
+	return nil
+}
+
+// getStatementPosition returns position of statement begin.
+//
+// It skips any comment line or non-whitespace character.
+func getStatementStart(src []byte) []byte {
+	pos := indexOfNonSpaceChar(src)
+	if pos == -1 {
+		return nil
+	}
+
+	src = src[pos:]
+	if src[0] != charComment {
+		return src
+	}
+
+	// skip comment section
+	pos = bytes.IndexFunc(src, isCharFunc('\n'))
+	if pos == -1 {
+		return nil
+	}
+
+	return getStatementStart(src[pos:])
+}
+
+// locateKeyName locates and parses key name and returns rest of slice
+func locateKeyName(src []byte) (key string, cutset []byte, err error) {
+	// trim "export" and space at beginning
+	src = bytes.TrimLeftFunc(src, isSpace)
+	if trimmed, found := bytes.CutPrefix(src, []byte(exportPrefix)); found {
+		if bytes.IndexFunc(trimmed, isSpace) == 0 {
+			src = bytes.TrimLeftFunc(trimmed, isSpace)
+		}
+	}
+
+	// locate key name end and validate it in single loop
+	offset := 0
+loop:
+	for i, char := range src {
+		rchar := rune(char)
+		if isSpace(rchar) {
+			continue
+		}
+
+		switch char {
+		case '=', ':':
+			// library also supports yaml-style value declaration
+			key = string(src[0:i])
+			offset = i + 1
+			break loop
+		case '_':
+		default:
+			// variable name should match [A-Za-z0-9_.]
+			if unicode.IsLetter(rchar) || unicode.IsNumber(rchar) || rchar == '.' {
+				continue
+			}
+
+			return "", nil, fmt.Errorf(
+				`unexpected character %q in variable name near %q`,
+				string(char), string(src))
+		}
+	}
+
+	if len(src) == 0 {
+		return "", nil, errors.New("zero length string")
+	}
+
+	// trim whitespace
+	key = strings.TrimRightFunc(key, unicode.IsSpace)
+	cutset = bytes.TrimLeftFunc(src[offset:], isSpace)
+	return key, cutset, nil
+}
+
+// extractVarValue extracts variable value and returns rest of slice
+func extractVarValue(src []byte, vars *orderedmap.OrderedMap[string, string]) (value string, rest []byte, err error) {
+	quote, hasPrefix := hasQuotePrefix(src)
+	if !hasPrefix {
+		// unquoted value - read until end of line
+		endOfLine := bytes.IndexFunc(src, isLineEnd)
+
+		// Hit EOF without a trailing newline
+		if endOfLine == -1 {
+			endOfLine = len(src)
+
+			if endOfLine == 0 {
+				return "", nil, nil
+			}
+		}
+
+		// Convert line to rune away to do accurate countback of runes
+		line := []rune(string(src[0:endOfLine]))
+
+		// Assume end of line is end of var
+		endOfVar := len(line)
+		if endOfVar == 0 {
+			return "", src[endOfLine:], nil
+		}
+
+		// Work backwards to check if the line ends in whitespace then
+		// a comment (ie asdasd # some comment)
+		for i := endOfVar - 1; i >= 0; i-- {
+			if line[i] == charComment && i > 0 {
+				if isSpace(line[i-1]) {
+					endOfVar = i
+					break
+				}
+			}
+		}
+
+		trimmed := strings.TrimFunc(string(line[0:endOfVar]), isSpace)
+
+		return expandVariables(trimmed, vars), src[endOfLine:], nil
+	}
+
+	// lookup quoted string terminator
+	for i := 1; i < len(src); i++ {
+		if char := src[i]; char != quote {
+			continue
+		}
+
+		// skip escaped quote symbol (\" or \', depends on quote)
+		if prevChar := src[i-1]; prevChar == '\\' {
+			continue
+		}
+
+		// trim quotes
+		trimFunc := isCharFunc(rune(quote))
+		value = string(bytes.TrimLeftFunc(bytes.TrimRightFunc(src[0:i], trimFunc), trimFunc))
+		if quote == prefixDoubleQuote {
+			// unescape newlines for double quote (this is compat feature)
+			// and expand environment variables
+			value = expandVariables(expandEscapes(value), vars)
+		}
+
+		return value, src[i+1:], nil
+	}
+
+	// return formatted error if quoted string is not terminated
+	valEndIndex := bytes.IndexFunc(src, isCharFunc('\n'))
+	if valEndIndex == -1 {
+		valEndIndex = len(src)
+	}
+
+	return "", nil, fmt.Errorf("unterminated quoted value %s", src[:valEndIndex])
+}
+
+func expandEscapes(str string) string {
+	out := escapeRegex.ReplaceAllStringFunc(str, func(match string) string {
+		c := strings.TrimPrefix(match, `\`)
+		switch c {
+		case "n":
+			return "\n"
+		case "r":
+			return "\r"
+		default:
+			return match
+		}
+	})
+	return unescapeCharsRegex.ReplaceAllString(out, "$1")
+}
+
+func indexOfNonSpaceChar(src []byte) int {
+	return bytes.IndexFunc(src, func(r rune) bool {
+		return !unicode.IsSpace(r)
+	})
+}
+
+// hasQuotePrefix reports whether charset starts with single or double quote and returns quote character
+func hasQuotePrefix(src []byte) (prefix byte, isQuored bool) {
+	if len(src) == 0 {
+		return 0, false
+	}
+
+	switch prefix := src[0]; prefix {
+	case prefixDoubleQuote, prefixSingleQuote:
+		return prefix, true
+	default:
+		return 0, false
+	}
+}
+
+func isCharFunc(char rune) func(rune) bool {
+	return func(v rune) bool {
+		return v == char
+	}
+}
+
+// isSpace reports whether the rune is a space character but not line break character
+//
+// this differs from unicode.IsSpace, which also applies line break as space
+func isSpace(r rune) bool {
+	switch r {
+	case '\t', '\v', '\f', '\r', ' ', 0x85, 0xA0:
+		return true
+	}
+	return false
+}
+
+func isLineEnd(r rune) bool {
+	if r == '\n' || r == '\r' {
+		return true
+	}
+	return false
+}
+
+var (
+	escapeRegex        = regexp.MustCompile(`\\.`)
+	expandVarRegex     = regexp.MustCompile(`(\\)?(\$)(\()?\{?([A-Z0-9_]+)?\}?`)
+	unescapeCharsRegex = regexp.MustCompile(`\\([^$])`)
+)
+
+func expandVariables(v string, m *orderedmap.OrderedMap[string, string]) string {
+	return expandVarRegex.ReplaceAllStringFunc(v, func(s string) string {
+		submatch := expandVarRegex.FindStringSubmatch(s)
+
+		if submatch == nil {
+			return s
+		}
+		if submatch[1] == "\\" || submatch[2] == "(" {
+			return submatch[0][1:]
+		} else if submatch[4] != "" {
+			value, _ := m.Get(submatch[4])
+			return value
+		}
+		return s
+	})
+}