chore: add comments to overlayed spec file for macro file and header (#408)

Author: tobiasb-ms

internal/app/azldev/core/sources/sourceprep.go

@@ -19,6 +19,7 @@ import (
 	"github.com/gim-home/azldev-preview/internal/utils/fileperms"
 	"github.com/gim-home/azldev-preview/internal/utils/fileutils"
 	"github.com/samber/lo"
+	"go.szostok.io/version"
 )
 
 // MacrosFileExtension is the file extension used for azldev-generated macros files.
@@ -201,6 +202,9 @@ func (p *sourcePreparerImpl) postProcessSources(
 		return fmt.Errorf("failed to compute macros load overlays:\n%w", err)
 	}
 
+	// Get the file header overlay.
+	headerOverlay := generateFileHeaderOverlay()
+
 	// Apply those overlays *first*, in sequence.
 	for _, overlay := range macroOverlays {
 		err = ApplyOverlayToSources(p.dryRunnable, p.fs, overlay, sourcesDirPath, absSpecPath)
@@ -220,6 +224,14 @@ func (p *sourcePreparerImpl) postProcessSources(
 		}
 	}
 
+	// Finally, apply the file header overlay.
+	for _, overlay := range headerOverlay {
+		err = ApplyOverlayToSources(p.dryRunnable, p.fs, overlay, sourcesDirPath, absSpecPath)
+		if err != nil {
+			return fmt.Errorf("failed to apply file header overlay to sources for component %#q:\n%w", component.GetName(), err)
+		}
+	}
+
 	return nil
 }
 
@@ -240,7 +252,10 @@ func synthesizeMacroLoadOverlays(macrosFileName string) ([]projectconfig.Compone
 			// Prepend the %{load:...} directive to the spec.
 			Type: projectconfig.ComponentOverlayPrependSpecLines,
 			Lines: []string{
+				"# All Azure Linux specs with overlays include this macro file, irrespective of" +
+					" whether new macros have been added.",
 				fmt.Sprintf("%%{load:%%{_sourcedir}/%s}", macrosFileName),
+				"",
 			},
 		},
 		{
@@ -256,6 +271,23 @@ func synthesizeMacroLoadOverlays(macrosFileName string) ([]projectconfig.Compone
 	}, nil
 }
 
+// generateFileHeaderOverlay generates an overlay that prepends a header to the spec.
+// It should be applied after all other overlays, as it should be the first thing in the spec file.
+func generateFileHeaderOverlay() []projectconfig.ComponentOverlay {
+	ver := version.Get()
+
+	return []projectconfig.ComponentOverlay{
+		{
+			Type: projectconfig.ComponentOverlayPrependSpecLines,
+			Lines: []string{
+				"# This spec file has been modified by azldev to include build configuration overlays. Version: " + ver.Version,
+				"# Do not edit manually; changes may be overwritten.",
+				"",
+			},
+		},
+	}
+}
+
 func findSpecInDir(
 	fs opctx.FS, component components.Component, dirPath string,
 ) (string, error) {