feat(upstreamcommit): add generated upstream-commit store

Add a store for the generated component configuration that pins resolved
upstream commits in lock-file-free mode. Each component gets a normal
component TOML holding only 'spec.upstream-commit', written with a header
marking it as generated, so the project's ordinary include and merge rules
supply the pin to every other command.

The package is self-contained and unused until the component commands adopt
it; nothing changes in azldev's default mode.

Refs: microsoft#323

Author: Copilot

internal/upstreamcommit/store.go

@@ -0,0 +1,249 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+// Package upstreamcommit manages generated component configuration files that
+// pin resolved upstream commits.
+package upstreamcommit
+
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/microsoft/azure-linux-dev-tools/internal/global/opctx"
+	"github.com/microsoft/azure-linux-dev-tools/internal/projectconfig"
+	"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"
+)
+
+const fileExtension = ".toml"
+
+const generatedFileHeader = `# This file was generated by 'azldev component refresh-upstream-commit'
+# Do not edit this file, changes will be lost
+# For more details see 'azldev component refresh-upstream-commit --help'
+`
+
+type generatedConfig struct {
+	Components map[string]generatedComponent `toml:"components"`
+}
+
+type generatedComponent struct {
+	Spec generatedSpec `toml:"spec"`
+}
+
+type generatedSpec struct {
+	UpstreamCommit string `toml:"upstream-commit"`
+}
+
+// Store reads and writes generated upstream-commit component configuration.
+type Store struct {
+	fs  opctx.FS
+	dir string
+}
+
+// NewStore creates a store rooted at dir.
+func NewStore(fs opctx.FS, dir string) *Store {
+	return &Store{fs: fs, dir: dir}
+}
+
+// Dir returns the generated configuration directory.
+func (s *Store) Dir() string {
+	return s.dir
+}
+
+// Path returns the generated TOML path for componentName.
+func (s *Store) Path(componentName string) (string, error) {
+	if err := fileutils.ValidateFilename(componentName); err != nil {
+		return "", fmt.Errorf("validating component name %#q for upstream commit TOML path:\n%w",
+			componentName, err)
+	}
+
+	return filepath.Join(s.dir, componentName+fileExtension), nil
+}
+
+// Get returns the upstream commit in a component's generated TOML file.
+func (s *Store) Get(componentName string) (commit string, exists bool, err error) {
+	path, err := s.Path(componentName)
+	if err != nil {
+		return "", false, err
+	}
+
+	exists, err = fileutils.Exists(s.fs, path)
+	if err != nil {
+		return "", false, fmt.Errorf("checking upstream commit TOML %#q:\n%w", path, err)
+	}
+
+	if !exists {
+		return "", false, nil
+	}
+
+	data, err := fileutils.ReadFile(s.fs, path)
+	if err != nil {
+		return "", true, fmt.Errorf("reading upstream commit TOML %#q:\n%w", path, err)
+	}
+
+	var config projectconfig.ConfigFile
+	if err := toml.Unmarshal(data, &config); err != nil {
+		return "", true, fmt.Errorf("parsing upstream commit TOML %#q:\n%w", path, err)
+	}
+
+	component, ok := config.Components[componentName]
+	if !ok {
+		return "", true, fmt.Errorf(
+			"upstream commit TOML %#q does not define component %#q", path, componentName)
+	}
+
+	return component.Spec.UpstreamCommit, true, nil
+}
+
+// Exists reports whether a generated TOML exists for componentName.
+func (s *Store) Exists(componentName string) (bool, error) {
+	path, err := s.Path(componentName)
+	if err != nil {
+		return false, err
+	}
+
+	exists, err := fileutils.Exists(s.fs, path)
+	if err != nil {
+		return false, fmt.Errorf("checking upstream commit TOML %#q:\n%w", path, err)
+	}
+
+	return exists, nil
+}
+
+// Remove deletes the generated TOML for componentName if it exists.
+func (s *Store) Remove(componentName string) (bool, error) {
+	path, err := s.Path(componentName)
+	if err != nil {
+		return false, err
+	}
+
+	exists, err := s.Exists(componentName)
+	if err != nil {
+		return false, err
+	}
+
+	if !exists {
+		return false, nil
+	}
+
+	if err := s.fs.Remove(path); err != nil {
+		return false, fmt.Errorf("removing upstream commit TOML %#q:\n%w", path, err)
+	}
+
+	return true, nil
+}
+
+// Save writes a generated component TOML override containing only upstreamCommit.
+func (s *Store) Save(componentName, upstreamCommit string) error {
+	path, err := s.Path(componentName)
+	if err != nil {
+		return err
+	}
+
+	config := generatedConfig{
+		Components: map[string]generatedComponent{
+			componentName: {
+				Spec: generatedSpec{UpstreamCommit: upstreamCommit},
+			},
+		},
+	}
+
+	data, err := toml.Marshal(config)
+	if err != nil {
+		return fmt.Errorf("serializing upstream commit TOML %#q:\n%w", path, err)
+	}
+
+	data = append([]byte(generatedFileHeader), data...)
+
+	if err := fileutils.MkdirAll(s.fs, s.dir); err != nil {
+		return fmt.Errorf("creating upstream commit TOML directory %#q:\n%w", s.dir, err)
+	}
+
+	if err := fileutils.WriteFile(s.fs, path, data, fileperms.PublicFile); err != nil {
+		return fmt.Errorf("writing upstream commit TOML %#q:\n%w", path, err)
+	}
+
+	return nil
+}
+
+// FindOrphans returns generated component TOMLs that do not correspond to an
+// upstream component in components.
+func (s *Store) FindOrphans(
+	components map[string]projectconfig.ComponentConfig,
+) ([]string, error) {
+	entries, err := fileutils.ReadDir(s.fs, s.dir)
+	if err != nil {
+		exists, existsErr := fileutils.DirExists(s.fs, s.dir)
+		if existsErr != nil {
+			return nil, fmt.Errorf("checking upstream commit TOML directory %#q:\n%w", s.dir, existsErr)
+		}
+
+		if !exists {
+			return nil, nil
+		}
+
+		return nil, fmt.Errorf("reading upstream commit TOML directory %#q:\n%w", s.dir, err)
+	}
+
+	var orphans []string
+
+	for _, entry := range entries {
+		if entry.IsDir() || strings.HasPrefix(entry.Name(), ".") ||
+			!strings.HasSuffix(entry.Name(), fileExtension) {
+			continue
+		}
+
+		name := strings.TrimSuffix(entry.Name(), fileExtension)
+
+		component, ok := components[name]
+		if !ok || component.Spec.SourceType != projectconfig.SpecSourceTypeUpstream {
+			orphans = append(orphans, name)
+		}
+	}
+
+	sort.Strings(orphans)
+
+	return orphans, nil
+}
+
+// PruneOrphans removes generated TOMLs that are no longer needed.
+func (s *Store) PruneOrphans(components map[string]projectconfig.ComponentConfig) (int, error) {
+	orphans, err := s.FindOrphans(components)
+	if err != nil {
+		return 0, err
+	}
+
+	var errs []error
+
+	pruned := 0
+
+	for _, name := range orphans {
+		path, pathErr := s.Path(name)
+		if pathErr != nil {
+			errs = append(errs, pathErr)
+
+			continue
+		}
+
+		slog.Info("Removing orphan upstream commit TOML", "component", name)
+
+		if removeErr := s.fs.Remove(path); removeErr != nil {
+			errs = append(errs, fmt.Errorf("removing upstream commit TOML for %#q:\n%w", name, removeErr))
+
+			continue
+		}
+
+		pruned++
+	}
+
+	if len(errs) > 0 {
+		return pruned, errors.Join(errs...)
+	}
+
+	return pruned, nil
+}