feat(component): add overlay metadata and 'component overlays' command#242
Open
liunan-ms wants to merge 4 commits into
Open
feat(component): add overlay metadata and 'component overlays' command#242liunan-ms wants to merge 4 commits into
liunan-ms wants to merge 4 commits into
Conversation
Add an optional [metadata] block on overlays (category, commits, PR, bug links, upstreamability) and a per-file .overlay.toml format loaded from a component's overlay-dir. Add the read-only 'azldev component overlays' command with --category, --only-annotated, and --upstreamability filters. Metadata and overlay-dir are excluded from fingerprints. Regenerate docs, JSON schema, and scenario snapshots.
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds structured overlay metadata and per-file overlay support, plus a new CLI/MCP command to list overlays across components.
Changes:
- Extend project config schema with
overlay-dirfor components andmetadatafor overlays. - Implement
.overlay.tomloverlay directory loading (file-level metadata stamped onto overlays) and validation. - Add
azldev component overlayscommand (and docs/snapshots) to inspect overlays and filter by metadata.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| schemas/azldev.schema.json | Adds overlay-dir and OverlayMetadata schema definitions. |
| scenario/snapshots/TestSnapshots_config_generate-schema_stdout_1.snap | Updates schema-generation snapshot to include new fields/defs. |
| scenario/snapshots/TestSnapshotsContainer_config_generate-schema_stdout_1.snap | Updates container schema-generation snapshot to include new fields/defs. |
| scenario/snapshots/TestMCPServerMode_1.snap.json | Adds new MCP tool entry for component-overlays. |
| internal/projectconfig/overlay_metadata.go | Introduces metadata types/enums and validation rules. |
| internal/projectconfig/overlay_metadata_test.go | Adds validation tests for overlay metadata and overlay validation integration. |
| internal/projectconfig/overlay_file.go | Implements overlay-dir scanning + .overlay.toml parsing/stamping behavior. |
| internal/projectconfig/overlay_file_test.go | Adds tests for overlay-dir load/stamping, ordering, path resolution, and errors. |
| internal/projectconfig/overlay.go | Adds optional Metadata to overlays and validates it when present. |
| internal/projectconfig/loader.go | Hooks overlay-dir resolution into config load pipeline (pre-validation). |
| internal/projectconfig/fingerprint_test.go | Marks ComponentOverlay.Metadata and ComponentConfig.OverlayDir as excluded from fingerprinting. |
| internal/projectconfig/component.go | Adds OverlayDir field and preserves verbatim value in WithAbsolutePaths. |
| internal/app/azldev/cmds/component/overlays.go | Adds azldev component overlays command + filtering/sorting logic. |
| internal/app/azldev/cmds/component/overlays_test.go | Adds tests for listing and filtering overlays by annotation/category/upstreamability. |
| internal/app/azldev/cmds/component/component.go | Registers the new overlays subcommand. |
| docs/user/reference/config/overlays.md | Documents overlay metadata and per-file .overlay.toml overlay-dir format. |
| docs/user/reference/cli/azldev_component_overlays.md | Adds auto-generated CLI reference for the new command. |
| docs/user/reference/cli/azldev_component.md | Adds the new subcommand to the CLI index. |
dmcilvaney
reviewed
Jun 16, 2026
| } | ||
|
|
||
| if c.Metadata != nil { | ||
| if err := c.Metadata.Validate(); err != nil { |
Contributor
There was a problem hiding this comment.
Need to handle permissive mode.
- Replace commas with semicolons in Upstreamability jsonschema description to prevent jsonschema tag parser from truncating the description. - Replace deep.MustCopy with a non-panicking OverlayMetadata.clone() so config load can never panic when stamping per-file metadata. - Reuse a package-level validator instance in OverlayMetadata.Validate to avoid per-call allocations. - Compute normalized --upstreamability filter once in ListOverlays and pass it to overlayInfoMatchesFilters instead of re-normalizing per overlay. - Fail loudly when an overlay-dir matches no *.overlay.toml files (or the directory is missing) via WithFailOnPatternNotExist and a new ErrOverlayDirNoFiles sentinel. - Reject overlay-dir on default-component-config (project, group, and distro-version layers) with ErrOverlayDirInDefaultConfig as a stopgap until overlay-dir is plumbed through the default-merge path. - Regenerate JSON schema and scenario snapshots.
Per-file overlay metadata validation now warns and continues under --permissive-config instead of failing the load, aligning with the behavior introduced in microsoft#216. This lets older .overlay.toml files that use fields or values deprecated by a newer Metadata.Validate() still be loaded when permissive parsing is requested.
dmcilvaney
approved these changes
Jun 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Overlays currently carry no record of why they exist or when they can be removed, so reviewers can't tell a temporary Fedora backport from a permanent AZL branding change. This PR adds an optional
[metadata]block to overlays, a per-file.overlay.tomlformat for grouping related overlays, and a read-onlyazldev component overlayscommand for inspecting them.What's new
Overlays can now declare optional documentation metadata:
A component can set
overlay-dir = "overlays"to load*.overlay.tomlfiles, one per logical change. Each file has a single file-level[metadata]block (stamped onto every overlay in the file) plus an ordered list of[[overlays]]. Files load in filename order (0001-, 0002- convention), are appended after inline overlays, and resolve source paths relative to the overlay file. Per-overlay metadata inside these files is rejected.azldev component overlayscommandA read-only command listing overlays and their metadata across components, with
--category,--only-annotated, and--upstreamabilityfilters. Table (default) or JSON output. Available as an MCP tool. Does not parse spec files or fetch sources, so it's fast and works with missing/stale locks.Validated against real overlays (microsoft/azurelinux#17727)