Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/user/reference/config/components.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ A component definition tells azldev where to find the spec file, how to customiz
| Spec source | `spec` | [SpecSource](#spec-source) | No | Where to find the spec file for this component. Inherited from distro defaults if not specified. |
| Release config | `release` | [ReleaseConfig](#release-configuration) | No | Controls how the Release tag is managed during rendering |
| Overlays | `overlays` | array of [Overlay](overlays.md) | No | Modifications to apply to the spec and/or source files |
| Overlay files | `overlay-files` | array of string | No | Path or glob patterns that load per-file overlay documents after component config resolution. Inherited relative patterns are resolved from the concrete component's config file, or from the matched spec file's directory for spec-discovered components. Use `[]` to disable inherited patterns. See [Per-file overlay format](overlays.md#per-file-overlay-format). |
| Overlay files | `overlay-files` | array of string | No | Path or glob patterns that load per-file overlay documents after component config resolution. Allowed in project defaults and component settings, but not distro-version or component-group defaults (including `[]`). Inherited relative patterns are resolved from the concrete component's config file, or from the matched spec file's directory for spec-discovered components. Use `[]` on a component to disable inherited patterns. See [Per-file overlay format](overlays.md#per-file-overlay-format). |
| Build config | `build` | [BuildConfig](#build-configuration) | No | Build-time options (macros, conditionals, check config) |
| Render config | `render` | [RenderConfig](#render-configuration) | No | Options controlling spec rendering behavior |
| Source files | `source-files` | array of [SourceFileReference](#source-file-references) | No | Additional source files to download for this component |
Expand Down
78 changes: 77 additions & 1 deletion docs/user/reference/config/overlays.md
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,9 @@ When a single logical change (a CVE backport, a feature disablement, a Fedora ch

Set `overlay-files` on the component to one or more globs (relative to the component config) and drop one overlay file per logical change into a directory of your choosing. The conventional layout uses a sibling `overlays/` directory and a `*.overlay.toml` filename suffix, but neither is required — `overlay-files` is just a glob, so any layout you can describe with `**`/`*` patterns works.

`overlay-files` can also be inherited from `default-component-config` at the project, distro, or component-group level. Inherited relative patterns are still resolved for each concrete component: from its component config file when it has one, or from the matched spec file's directory when it is discovered by a component group's `specs` pattern. This makes defaults useful for component-local discovery patterns such as `overlay-files = ["overlays/*.overlay.toml"]`. If a component sets `overlay-files`, that value replaces the inherited list; use `overlay-files = []` to disable inherited overlay files for a component, or include both patterns explicitly when you want to keep default discovery and add component-specific locations.
`overlay-files` on `[components.X]` is a plain glob resolved relative to the component's config file. Plain legacy patterns such as `overlays/*.overlay.toml` and explicit empty lists remain supported in project-level defaults and component settings, with unchanged path resolution and precedence. Inherited plain patterns resolve relative to the concrete component config file or matched spec directory. Project-level defaults can use [shared patterns with `{component}`](#shared-patterns-with-component-in-overlay-files) to locate overlays for known components. A component that inherits such a pattern substitutes its own name for `{component}`; use `overlay-files = []` to disable the inherited list, or set your own list to replace it wholesale.

`overlay-files` is only settable at project scope (the top-level `default-component-config`) or at component scope (`[components.X]`). Setting it inside a distro-version or component-group `default-component-config` is rejected at load time — even an empty list (`overlay-files = []`).

```
base/comps/mypackage/
Expand Down Expand Up @@ -293,6 +295,80 @@ lines = ["- Fix CVE-2024-1234"]

Use `azldev component metadata` to list documentation metadata for one or more components. By default it lists metadata from both sources — component overlays and the component groups each component belongs to — tagging each row with its `source`, and shows only entries that carry a `[metadata]` block. Pass `--overlays` or `--groups` to restrict to one source. The command is read-only and supports `--category` and `--upstream-status` filters; output is available as a table (default) or JSON (`-O json`).

### Shared patterns with `{component}` in `overlay-files`

For projects that keep each component's overlay files in a predictable per-component directory (e.g. `base/comps/<name>/overlays/*.overlay.toml`), declare components centrally and use a shared **project-level** `default-component-config.overlay-files` pattern containing `{component}`. This removes the need for declaration-only `.comp.toml` files without removing the declarations themselves.

**Overlay patterns only apply to known components.** A component must have a `[components.<name>]` declaration or be identified by another supported mechanism, such as a component-group `specs` glob. An entry that uses `{component}` **must** contain it exactly once, as a whole path segment, and **must** have at least one more path segment after it (the placeholder names a component directory, not a file). Additional constraints for placeholder entries enforced at load time:

* Use `/` as the path separator (backslashes are rejected; Windows is not supported).
* No glob metacharacters (`*`, `?`, `[`, `{`) before `{component}` — the prefix must be literal.
* No additional `{` or `}` after `{component}`, including brace alternatives such as `{base,extra}`. Use separate list entries for multiple directories. Ordinary patterns without `{component}` retain their existing brace support.
* `..` path segments are allowed before `{component}`, but never after it. For example, `../comps/{component}/overlays/*.overlay.toml` is valid. Both `comps/{component}/../overlays/*.overlay.toml` and `comps/{component}/nested/../overlays/*.overlay.toml` are rejected. Write the latter as `comps/{component}/overlays/*.overlay.toml` instead.
* The rest of the entry (after `{component}/`) must be a valid `doublestar` glob (validated with `doublestar.ValidatePattern`).

For example, a resolved component named `curl` substitutes its name into `comps/{component}/overlays/*.overlay.toml` and loads `comps/curl/overlays/fix.overlay.toml`. A matching directory for an undeclared component does not create a new component.

Each component inherits the project-level `overlay-files` list, including any shared patterns and `{component}` patterns, unless it sets its own: a component-specific list replaces the project list, and `[]` disables inherited overlay files.

An inherited `{component}` entry that matches no files is skipped, even if it ends in a literal filename such as `{component}/overlays.toml`. An ordinary literal path without `{component}` must still exist.

```toml
# base/comps/components.toml (included at project scope)
[default-component-config]
overlay-files = ["{component}/overlays/*.overlay.toml"]

[components.anaconda]

[components.curl]
```

The pattern is relative to the file that declares it. If declared in the root
`azldev.toml` instead, use `base/comps/{component}/overlays/*.overlay.toml`.
With the layout below, the central declarations load their respective overlay files.
Do not create an empty `anaconda.comp.toml`; keep `[components.anaconda]` in the
central file instead.

```
base/comps/
├── components.toml
├── anaconda/
│ └── overlays/
│ ├── 0001-cve-2024-1234.overlay.toml
│ └── 0002-disable-fips-tests.overlay.toml
└── curl/
└── overlays/
└── 0001-cve-2024-5678.overlay.toml
```

**Where `{component}` is allowed.** Only in **project-level** `default-component-config`, where plain and placeholder entries may coexist. Component settings accept plain patterns and `[]`, but reject `{component}`. Distro-version and component-group defaults must omit `overlay-files` entirely, including empty lists. A component-specific list replaces the project list rather than merging with it; an empty component list disables inherited overlay files.

**Inheritance with `{component}`.** A component that does not override `overlay-files` inherits the project entry and expands `{component}` with its own name at glob time. This also works for components identified by component-group spec globs.

A component that sets its own `overlay-files = [...]` replaces the inherited value; the placeholder pattern no longer applies to that component. Setting `overlay-files = []` disables inheritance entirely for that component.

Multiple patterns may select overlays for the same component. Files are loaded in pattern order, with duplicate file matches loaded only once.

**Explicit component-group members need a `[components.<name>]` table.** A component group can enumerate its members two ways: via a `specs` glob (spec files on disk) or via an explicit `components = ["<name>", ...]` list. Every name in the *explicit list* must have a matching `[components.<name>]` table in the project (validated at load time, error `ErrUndefinedComponent`). For example, retain `anaconda` centrally rather than adding an empty dedicated file:

```toml
# base/comps/components.toml (included at project scope)
[default-component-config]
overlay-files = ["{component}/overlays/*.overlay.toml"]

[components.anaconda]

[component-groups.installer]
components = ["anaconda"]
```

Once the table exists, the component inherits the project-level `{component}` overlay pattern normally. Group members matched via `specs` (not the explicit list) do **not** need a `.comp.toml` — the resolver synthesizes an empty config for them and inheritance still applies.

Keep a dedicated `.comp.toml` when it contains actual component-specific settings,
such as upstream pins, build options, inline overlays, or local-spec configuration.
Components with or without matching overlay files need an explicit declaration or
another supported mechanism, such as a group's `specs` glob.

## Examples

### Adding a Build Dependency
Expand Down
42 changes: 42 additions & 0 deletions internal/app/azldev/agentskill/agentskill_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -480,6 +480,48 @@ func TestFilesGitHubLayout(t *testing.T) {
assert.Contains(t, mockFile.Content, "name: azldev-mock")
}

func TestComponentSkillsExplainCentralDeclarationsAndPlaceholderOverlays(t *testing.T) {
for _, mode := range []struct {
name string
withoutLockfile bool
}{
{name: "default"},
{name: "without-lockfile", withoutLockfile: true},
} {
t.Run(mode.name, func(t *testing.T) {
catalog := agentskill.NewCatalog(mode.withoutLockfile)

for _, name := range []string{"azldev-add-component", "azldev-comp-toml", "azldev-overlays"} {
t.Run(name, func(t *testing.T) {
doc, err := catalog.SkillDocument(name, testParams())
require.NoError(t, err)

doc = strings.Join(strings.Fields(doc), " ")
assert.Contains(t, doc, "name: "+name)
assert.Contains(t, doc, "base/comps/{component}/overlays/*.overlay.toml")
assert.Contains(t, doc, "do not create an empty")
assert.Contains(t, doc, "base/comps/components.toml")
assert.Contains(t, doc, "without matching overlay files")
assert.Contains(t, doc, "upstream pins, build options, inline overlays,")
assert.Contains(t, doc, "do not discover undeclared components")
assert.NotContains(t, doc, "Declaration-free")
assert.NotContains(t, doc, "Discovery is opt-in.")
assert.Contains(t, doc, "unchanged path resolution and precedence")
assert.Contains(t, doc,
"Distro-version and component-group defaults must omit `overlay-files`, including empty lists.")
assert.NotContains(t, doc, "Every component lives under")
assert.NotContains(t, doc, "anything that needs overlays")

if name == "azldev-overlays" {
assert.Contains(t, doc, "Additional braces are forbidden after `{component}`")
assert.Contains(t, doc, "use separate list entries for multiple directories")
}
})
}
})
}
}

// schemaEnum extracts values from an authoritative jsonschema enum tag.
func schemaEnum(t *testing.T, structType reflect.Type, fieldName string) []string {
t.Helper()
Expand Down
29 changes: 25 additions & 4 deletions internal/app/azldev/agentskill/content/add-component.md.tmpl
Original file line number Diff line number Diff line change
Expand Up @@ -39,17 +39,38 @@ dist-git often fail bot detection):

4. Read the spec and plan any overlays.

## Inline vs dedicated file
## Central or dedicated declarations

For components whose only customization is per-file overlays, add files under
`base/comps/<name>/overlays/`; do not create an empty `<name>.comp.toml`. This requires
a shared project-level `default-component-config.overlay-files` pattern such as
`base/comps/{component}/overlays/*.overlay.toml` in the root config. The `{component}`
pattern substitutes each resolved component's name to load its overlays.
Retain `[components.<name>]` in `base/comps/components.toml`.
Overlay files do not discover undeclared components.

Plain legacy patterns such as `overlays/*.overlay.toml` and
`[]` remain supported in project defaults and component settings, with unchanged
path resolution and precedence; they do not discover components. Distro-version
and component-group defaults must omit `overlay-files`, including empty lists.
Only project-level defaults may use `{component}`.

If a component is explicitly listed in a component group, retain `[components.<name>]`
in `base/comps/components.toml` for membership validation. Components with or
without matching overlay files still need an
explicit declaration or another supported discovery mechanism (such as a group's
`specs` glob).

- **Inline** — a bare upstream import with no changes stays in a shared config file:

```toml
[components.jq]
```

- **Dedicated** — anything that needs overlays, build config, or a local spec gets its
own `<name>/<name>.comp.toml`. Rule of thumb: more than `[components.<name>]` earns a
dedicated file. An `includes = ["**/*.comp.toml"]` glob picks it up automatically.
- **Dedicated** — keep `<name>/<name>.comp.toml` when it contains actual
component-specific settings, such as upstream pins, build options, inline overlays,
or local-spec configuration. An `includes = ["**/*.comp.toml"]` glob picks it up
automatically.

`azldev comp add <name> [<name>...]` adds bare `[components.<name>]` entries that inherit
the distro defaults; it writes to the **root** config file and does not scaffold spec or
Expand Down
29 changes: 24 additions & 5 deletions internal/app/azldev/agentskill/content/comp-toml.md.tmpl
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ description: {{ printf "%q" .Description }}
# Component definition files (`*.comp.toml`)

A component definition tells azldev where a package's spec comes from and how to
customize it for your distro. Every component lives under `[components.<name>]`.
customize it for your distro. Explicit definitions live under `[components.<name>]`;
components may also be identified by component-group spec globs, but overlay files
do not discover undeclared components.

Get the authoritative, always-current field list from the schema:

Expand Down Expand Up @@ -102,11 +104,28 @@ the rare spec whose `Source`/`Patch` filenames use macros the filter cannot expa

## File organization

Plain legacy patterns such as `overlays/*.overlay.toml` and
`[]` remain supported in project defaults and component settings, with unchanged
path resolution and precedence; they do not discover components. Distro-version
and component-group defaults must omit `overlay-files`, including empty lists.
Only project-level defaults may use `{component}`.

- **Central declarations** — for components whose only customization is per-file
overlays, add files under `base/comps/<name>/overlays/`; do not create an empty
`<name>.comp.toml`. A shared project-level `default-component-config.overlay-files`
pattern such as `base/comps/{component}/overlays/*.overlay.toml` in the root config
substitutes the component's name to load its overlays. Retain
`[components.<name>]` in `base/comps/components.toml`.
- **Explicit group members** — if a component is explicitly listed in a component
group's `components` list, retain `[components.<name>]` in
`base/comps/components.toml`. Components with or without matching overlay files still need an explicit
declaration or another supported discovery mechanism (such as a group's `specs`
glob).
- **Inline** — put simple, customization-free components directly in a shared config
file (e.g. `[components.jq]`).
- **Dedicated** — give a component its own `<name>/<name>.comp.toml` once it needs
overlays, build config, or a local spec. Rule of thumb: anything more than
`[components.<name>]` earns a dedicated file.
- **Dedicated** — keep `<name>/<name>.comp.toml` when it contains actual
component-specific settings, such as upstream pins, build options, inline overlays,
or local-spec configuration.
- A parent config picks up dedicated files through an `includes` glob, for example
`includes = ["**/*.comp.toml"]`.

Expand All @@ -117,7 +136,7 @@ Start with `azldev comp list -p <name> -q -O json`, then use
For a change review, focus on the diff while checking enough surrounding context to
ensure it fits the component and repository conventions.

- **Organization:** The component follows the repository's inline-versus-dedicated-file
- **Organization:** The component follows the repository's central or dedicated-file
convention; its name matches upstream or sets `spec.upstream-name`; no stale or
orphaned component files remain.
- **Spec source:** The default upstream source is preferred. Pins explain why they are
Expand Down
Loading
Loading