feat: initial overlay support (#381)

* Extends TOML config file format with support for defining overlays, semantic patches for RPM spec files / sources.
* Documentation for the overlay definition format has been added to `docs/reference/overlays.md`.

Author: reubeno

docs/reference/overlays.md

@@ -0,0 +1,187 @@
+# Overlays
+
+Overlays are semantic patches that modify RPM spec files and other source files during component processing. They allow you to make targeted changes to upstream specs without maintaining full forks.
+
+Overlays are defined within a component's configuration in your TOML config file and are applied in the order they appear. Each overlay specifies a type and the parameters needed to perform its modification.
+
+> **Note:** Overlays are applied in sequence and modifications are non-atomic. If an overlay fails mid-way, previously applied changes remain. Work on copies if atomicity is required.
+
+## Overlay Types
+
+### Spec Overlays
+
+These overlays modify `.spec` files using the structured spec parser, allowing precise targeting of tags and sections.
+
+| Type | Description | Required Fields |
+|------|-------------|-----------------|
+| `spec-add-tag` | Adds a tag to the spec; **fails if the tag already exists** | `tag`, `value` |
+| `spec-set-tag` | Sets a tag value; replaces if exists, adds if not | `tag`, `value` |
+| `spec-update-tag` | Updates an existing tag; **fails if the tag doesn't exist** | `tag`, `value` |
+| `spec-remove-tag` | Removes a tag from the spec; **fails if the tag doesn't exist** | `tag` |
+| `spec-prepend-lines` | Prepends lines to the start of a section; **fails if section doesn't exist** | `lines` |
+| `spec-append-lines` | Appends lines to the end of a section; **fails if section doesn't exist** | `lines` |
+| `spec-search-replace` | Regex-based search and replace on spec content | `regex` |
+
+### File Overlays
+
+These overlays modify non-spec source files directly. They cannot be used on `.spec` files. These
+overlays are typically only used to modify loose files next to specs when standard patching mechanisms
+can't easily be used.
+
+| Type | Description | Required Fields |
+|------|-------------|-----------------|
+| `file-prepend-lines` | Prepends lines to a file | `file`, `lines` |
+| `file-search-replace` | Regex-based search and replace on a file | `file`, `regex` |
+| `file-add` | Copies a new file from a source location | `file`, `source` |
+
+## Field Reference
+
+| Field | TOML Key | Description | Used By |
+|-------|----------|-------------|---------|
+| Type | `type` | **Required.** The overlay type to apply | All overlays |
+| Description | `description` | Human-readable explanation documenting the need for the change; helps identify overlays in error messages | All (optional) |
+| Tag | `tag` | The spec tag name (e.g., `BuildRequires`, `Requires`, `Version`) | `spec-add-tag`, `spec-set-tag`, `spec-update-tag`, `spec-remove-tag` |
+| Value | `value` | The tag value to set, or value to match for removal | `spec-add-tag`, `spec-set-tag`, `spec-update-tag`, `spec-remove-tag` (optional for matching) |
+| Section | `section` | The spec section to target (e.g., `%build`, `%install`, `%files`, `%description`) | `spec-prepend-lines`, `spec-append-lines`, `spec-search-replace` (optional) |
+| Package | `package` | The sub-package name for multi-package specs; omit to target the main package | All spec overlays (optional) |
+| Regex | `regex` | Regular expression pattern to match | `spec-search-replace`, `file-search-replace` |
+| Replacement | `replacement` | Literal replacement text; omit or leave empty to delete matched text | `spec-search-replace`, `file-search-replace` (optional) |
+| Lines | `lines` | Array of text lines to insert | `spec-prepend-lines`, `spec-append-lines`, `file-prepend-lines` |
+| File | `file` | The name of the non-spec file to modify or add | `file-prepend-lines`, `file-search-replace`, `file-add` |
+| Source | `source` | Path to source file for `file-add`; relative paths are relative to the config file | `file-add` |
+
+## Examples
+
+### Adding a Build Dependency
+
+```toml
+[[components.mypackage.overlays]]
+type = "spec-add-tag"
+description = "Add missing build dependency"
+tag = "BuildRequires"
+value = "some-devel-package"
+```
+
+### Setting a Version
+
+Use `spec-set-tag` when you want to set a value regardless of whether the tag exists:
+
+```toml
+[[components.mypackage.overlays]]
+type = "spec-set-tag"
+tag = "Version"
+value = "2.0.0"
+```
+
+### Removing a Dependency
+
+Remove a specific tag by matching both the tag name and value:
+
+```toml
+[[components.mypackage.overlays]]
+type = "spec-remove-tag"
+description = "Remove problematic dependency"
+tag = "BuildRequires"
+value = "unwanted-package"
+```
+
+### Appending Lines to a Section
+
+```toml
+[[components.mypackage.overlays]]
+type = "spec-append-lines"
+section = "%install"
+lines = [
+    "mkdir -p %{buildroot}%{_datadir}/mypackage",
+    "install -m 644 extra.conf %{buildroot}%{_datadir}/mypackage/"
+]
+```
+
+### Prepending Lines to a Section
+
+```toml
+[[components.mypackage.overlays]]
+type = "spec-prepend-lines"
+section = "%build"
+lines = ["export CFLAGS=\"$CFLAGS -DEXTRA_FLAG\""]
+```
+
+### Search and Replace in Spec
+
+> **Tip:** The regex must match at least once or an error is raised. This prevents silent no-ops from typos or upstream changes.
+
+```toml
+[[components.mypackage.overlays]]
+type = "spec-search-replace"
+description = "Remove unwanted configure flag"
+section = "%build"
+regex = "--enable-deprecated-feature\\s*"
+replacement = ""
+```
+
+### Targeting a Sub-Package
+
+For multi-package specs, use the `package` field to target a specific sub-package:
+
+```toml
+[[components.mypackage.overlays]]
+type = "spec-append-lines"
+section = "%files"
+package = "devel"
+lines = ["%{_includedir}/mypackage/*.h"]
+```
+
+```toml
+[[components.mypackage.overlays]]
+type = "spec-set-tag"
+package = "libs"
+tag = "Summary"
+value = "Shared libraries for mypackage"
+```
+
+### Prepending Lines to a Non-Spec File
+
+```toml
+[[components.mypackage.overlays]]
+type = "file-prepend-lines"
+file = "Makefile"
+lines = ["# Modified by azldev overlay", "EXTRA_FLAGS := -O2"]
+```
+
+### Search and Replace in a File
+
+```toml
+[[components.mypackage.overlays]]
+type = "file-search-replace"
+file = "configure.ac"
+regex = "AC_INIT\\(\\[mypackage\\],\\s*\\[\\d+\\.\\d+\\]"
+replacement = "AC_INIT([mypackage], [2.0]"
+description = "Update version in configure.ac"
+```
+
+### Adding a New File
+
+The `source` path is relative to the config file that defines the overlay:
+
+```toml
+[[components.mypackage.overlays]]
+type = "file-add"
+file = "extra-config.conf"
+source = "files/mypackage/extra-config.conf"
+description = "Add custom configuration file"
+```
+
+## Validation
+
+Overlay configurations are validated when the config file is loaded. Validation checks:
+
+- Required fields are present for each overlay type
+- Regex patterns compile successfully
+- Error messages include the `description` field (if provided) to help identify which overlay failed
+
+> **Tip:** Always provide a `description` for overlays to make debugging easier when validation or application fails.
+
+## Related Resources
+
+- [JSON Schema](../../schemas/azldev.schema.json) — Use with editors that support JSON Schema for TOML to get validation and auto-completion
+- Component configuration is defined in the `[[components.<name>.overlays]]` array within your project's TOML config files

internal/app/azldev/cmds/component/build.go

@@ -171,7 +171,7 @@ func BuildComponent(
 		return nil
 	}, &err)
 
-	sourcePreparer, err := sources.NewPreparer(sourceManager, env.FS())
+	sourcePreparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env)
 	if err != nil {
 		return ComponentBuildResults{},
 			fmt.Errorf("failed to create source preparer for component %q:\n%w", component.GetName(), err)

internal/app/azldev/cmds/component/preparesources.go

@@ -84,7 +84,7 @@ func PrepareComponentSources(env *azldev.Env, options *PrepareSourcesOptions) er
 		return fmt.Errorf("failed to create source manager:\n%w", err)
 	}
 
-	preparer, err := sources.NewPreparer(sourceManager, env.FS())
+	preparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env)
 	if err != nil {
 		return fmt.Errorf("failed to create source preparer:\n%w", err)
 	}

internal/app/azldev/core/componentbuilder/componentbuilder_test.go

@@ -49,7 +49,7 @@ func setupBuilder(t *testing.T) *componentBuilderTestParams {
 
 	sourceManager := sourceproviders_test.NewNoOpMockSourceManager(ctrl)
 
-	preparer, err := sources.NewPreparer(sourceManager, testEnv.Env.FS())
+	preparer, err := sources.NewPreparer(sourceManager, testEnv.Env.FS(), testEnv.Env, testEnv.Env)
 
 	require.NoError(t, err)