feat(lock): Add lock file foundations

Add the initial structure for saving and loading lock files. The lock files will
track component identities and other metadata to help determine which components
have changed, and to assist with generating changelogs and managing releases.

Author: dmcilvaney

internal/lockfile/lockfile.go

@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+// Package lockfile reads and writes azldev.lock files, which pin resolved
+// upstream commit hashes for deterministic builds. The lock file is a TOML
+// file at the project root, managed by [azldev component update].
+package lockfile
+
+import (
+	"fmt"
+
+	"github.com/microsoft/azure-linux-dev-tools/internal/global/opctx"
+	"github.com/microsoft/azure-linux-dev-tools/internal/utils/fileperms"
+	"github.com/microsoft/azure-linux-dev-tools/internal/utils/fileutils"
+	toml "github.com/pelletier/go-toml/v2"
+)
+
+// FileName is the lock file name, placed at the project root.
+const FileName = "azldev.lock"
+
+// currentVersion is the lock file format version.
+const currentVersion = 1
+
+// LockFile holds the parsed contents of an azldev.lock file.
+type LockFile struct {
+	// Version is the lock file format version.
+	Version int `toml:"version" comment:"azldev.lock - Managed by azldev component update. Do not edit manually."`
+	// Components maps component name → locked state.
+	Components map[string]ComponentLock `toml:"components"`
+}
+
+// ComponentLock holds the locked state for a single component.
+type ComponentLock struct {
+	// UpstreamCommit is the resolved full commit hash from the upstream dist-git.
+	// Empty for local components.
+	UpstreamCommit string `toml:"upstream-commit,omitempty"`
+}
+
+// New creates an empty lock file with the current format version.
+func New() *LockFile {
+	return &LockFile{
+		Version:    currentVersion,
+		Components: make(map[string]ComponentLock),
+	}
+}
+
+// Load reads and parses a lock file from the given path. Returns an error if the
+// file cannot be read or parsed, or if the format version is unsupported.
+func Load(fs opctx.FS, path string) (*LockFile, error) {
+	data, err := fileutils.ReadFile(fs, path)
+	if err != nil {
+		return nil, fmt.Errorf("reading lock file %#q:\n%w", path, err)
+	}
+
+	var lockFile LockFile
+	if err := toml.Unmarshal(data, &lockFile); err != nil {
+		return nil, fmt.Errorf("parsing lock file %#q:\n%w", path, err)
+	}
+
+	if lockFile.Version != currentVersion {
+		return nil, fmt.Errorf(
+			// Backwards compatibility is a future consideration if we need to make non-compatible changes.
+			// For now, we can just error on unsupported versions.
+			"unsupported lock file version %d in %#q (expected %d)",
+			lockFile.Version, path, currentVersion)
+	}
+
+	if lockFile.Components == nil {
+		lockFile.Components = make(map[string]ComponentLock)
+	}
+
+	return &lockFile, nil
+}
+
+// Save writes the lock file to the given path. [toml.Marshal] sorts map keys
+// alphabetically, producing deterministic output.
+func (lockFile *LockFile) Save(fs opctx.FS, path string) error {
+	data, err := toml.Marshal(lockFile)
+	if err != nil {
+		return fmt.Errorf("marshaling lock file:\n%w", err)
+	}
+
+	if err := fileutils.WriteFile(fs, path, data, fileperms.PublicFile); err != nil {
+		return fmt.Errorf("writing lock file %#q:\n%w", path, err)
+	}
+
+	return nil
+}
+
+// SetUpstreamCommit sets the locked upstream commit for a component.
+func (lockFile *LockFile) SetUpstreamCommit(componentName, commitHash string) {
+	entry := lockFile.Components[componentName]
+	entry.UpstreamCommit = commitHash
+	lockFile.Components[componentName] = entry
+}
+
+// GetUpstreamCommit returns the locked upstream commit for a component.
+// Returns empty string and false if the component has no lock entry.
+func (lockFile *LockFile) GetUpstreamCommit(componentName string) (string, bool) {
+	entry, ok := lockFile.Components[componentName]
+	if !ok || entry.UpstreamCommit == "" {
+		return "", false
+	}
+
+	return entry.UpstreamCommit, true
+}

internal/lockfile/lockfile_test.go

@@ -0,0 +1,152 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package lockfile_test
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/microsoft/azure-linux-dev-tools/internal/lockfile"
+	"github.com/microsoft/azure-linux-dev-tools/internal/utils/fileperms"
+	"github.com/microsoft/azure-linux-dev-tools/internal/utils/fileutils"
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const testProjectDir = "/project"
+
+func TestNew(t *testing.T) {
+	lf := lockfile.New()
+	assert.Equal(t, 1, lf.Version)
+	assert.NotNil(t, lf.Components)
+	assert.Empty(t, lf.Components)
+}
+
+func TestSetAndGetUpstreamCommit(t *testing.T) {
+	lf := lockfile.New()
+
+	lf.SetUpstreamCommit("curl", "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2")
+
+	commit, ok := lf.GetUpstreamCommit("curl")
+	assert.True(t, ok)
+	assert.Equal(t, "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2", commit)
+}
+
+func TestGetUpstreamCommitMissing(t *testing.T) {
+	lf := lockfile.New()
+
+	commit, ok := lf.GetUpstreamCommit("nonexistent")
+	assert.False(t, ok)
+	assert.Empty(t, commit)
+}
+
+func TestSaveAndLoad(t *testing.T) {
+	memFS := afero.NewMemMapFs()
+	lockPath := filepath.Join(testProjectDir, lockfile.FileName)
+
+	require.NoError(t, fileutils.MkdirAll(memFS, testProjectDir))
+
+	// Create and save a lock file.
+	original := lockfile.New()
+	original.SetUpstreamCommit("curl", "aaaa")
+	original.SetUpstreamCommit("bash", "bbbb")
+	original.SetUpstreamCommit("vim", "cccc")
+
+	require.NoError(t, original.Save(memFS, lockPath))
+
+	// Load it back.
+	loaded, err := lockfile.Load(memFS, lockPath)
+	require.NoError(t, err)
+
+	assert.Equal(t, 1, loaded.Version)
+
+	commit, found := loaded.GetUpstreamCommit("curl")
+	assert.True(t, found)
+	assert.Equal(t, "aaaa", commit)
+
+	commit, found = loaded.GetUpstreamCommit("bash")
+	assert.True(t, found)
+	assert.Equal(t, "bbbb", commit)
+
+	commit, found = loaded.GetUpstreamCommit("vim")
+	assert.True(t, found)
+	assert.Equal(t, "cccc", commit)
+}
+
+func TestSaveSortsComponents(t *testing.T) {
+	memFS := afero.NewMemMapFs()
+	lockPath := filepath.Join(testProjectDir, lockfile.FileName)
+
+	require.NoError(t, fileutils.MkdirAll(memFS, testProjectDir))
+
+	lockFile := lockfile.New()
+	// Insert in non-alphabetical order.
+	lockFile.SetUpstreamCommit("zlib", "zzzz")
+	lockFile.SetUpstreamCommit("curl", "aaaa")
+	lockFile.SetUpstreamCommit("bash", "bbbb")
+
+	require.NoError(t, lockFile.Save(memFS, lockPath))
+
+	data, err := fileutils.ReadFile(memFS, lockPath)
+	require.NoError(t, err)
+
+	content := string(data)
+
+	// bash should appear before curl, which should appear before zlib.
+	bashIdx := strings.Index(content, "[components.bash]")
+	curlIdx := strings.Index(content, "[components.curl]")
+	zlibIdx := strings.Index(content, "[components.zlib]")
+
+	assert.Less(t, bashIdx, curlIdx, "bash should come before curl")
+	assert.Less(t, curlIdx, zlibIdx, "curl should come before zlib")
+}
+
+func TestLoadUnsupportedVersion(t *testing.T) {
+	memFS := afero.NewMemMapFs()
+	lockPath := filepath.Join(testProjectDir, lockfile.FileName)
+
+	content := "version = 99\n"
+
+	require.NoError(t, fileutils.MkdirAll(memFS, testProjectDir))
+	require.NoError(t, fileutils.WriteFile(memFS, lockPath, []byte(content), fileperms.PublicFile))
+
+	_, err := lockfile.Load(memFS, lockPath)
+	assert.ErrorContains(t, err, "unsupported lock file version")
+}
+
+func TestLoadMissingFile(t *testing.T) {
+	fs := afero.NewMemMapFs()
+
+	_, err := lockfile.Load(fs, "/nonexistent/azldev.lock")
+	assert.Error(t, err)
+}
+
+func TestLoadInvalidTOML(t *testing.T) {
+	memFS := afero.NewMemMapFs()
+	lockPath := filepath.Join(testProjectDir, lockfile.FileName)
+
+	require.NoError(t, fileutils.MkdirAll(memFS, testProjectDir))
+	require.NoError(t, fileutils.WriteFile(memFS, lockPath, []byte("not valid toml {{{"), fileperms.PublicFile))
+
+	_, err := lockfile.Load(memFS, lockPath)
+	assert.ErrorContains(t, err, "parsing lock file")
+}
+
+func TestSaveContainsVersion(t *testing.T) {
+	memFS := afero.NewMemMapFs()
+	lockPath := filepath.Join(testProjectDir, lockfile.FileName)
+
+	require.NoError(t, fileutils.MkdirAll(memFS, testProjectDir))
+
+	lockFile := lockfile.New()
+	require.NoError(t, lockFile.Save(memFS, lockPath))
+
+	data, err := fileutils.ReadFile(memFS, lockPath)
+	require.NoError(t, err)
+
+	assert.Contains(t, string(data), "version = 1")
+	assert.Contains(t, string(data), "# azldev.lock")
+}