feat(sources): add opt-in %fedora_upstream_* provenance macros (replaces #285)

[liunan-ms]

Summary

This PR supports azldev emits %fedora_upstream_version and %fedora_upstream_release macros for Fedora upstream components that opt in via a new build.emit-upstream-provenance flag. Values are read from the pristine upstream Fedora spec on disk (before overlays are applied) and the Release tag's %{?dist} token is expanded to the resolved Fedora dist tag (e.g. .fc43). The macros are surfaced through the component's existing generated macros file.

This is a replacement for #285 ("capture upstream version/release provenance and expose %azl_upstream_* macros"). That PR stored the version and release in the per-component lock file and derived the macros at build time from the lock. This PR takes a different, simpler approach.

Closed #285.

Advantages over #285

Aspect	#285 (lockfile-based)	This PR (render-time)
Data flow	Fetch NEVR at component update → store in lockfile → read at render/build	Read NEVR fresh at render/build from the pristine upstream spec that is already on disk
Lockfile schema	+4 fields per component (upstream-name, upstream-epoch, upstream-version, upstream-release)	No schema change
update command	New EVR-capture step, freshness/backfill guard, hasLockedUpstreamVersionRelease gate	Untouched
SourceIdentity plumbing	New struct + ResolveIdentity/ResolveSourceIdentity signature change threaded through Fedora, RPM, and local providers	Untouched
Network at resolution time	Extra clone + git show <commit>:<name>.spec per component during identity resolution	None (the render pipeline already clones the pristine spec)
Failure surface	Clone failure fatal for pinned commits (deterministic identity); best-effort for spec parse	Non-fatal Warn on missing/unparseable spec (opt-in components only)
Scope of rendered-output change	All Fedora upstream components acquire 4 new lock fields	Opt-in: only components that need the macros (currently just grub2 for SBAT) get a .azl.macros file
Provenance freshness	Cached in lock; can become stale if commit pin advances without an update run	Always reflects the pinned upstream commit
Diff size	~18 files, ~650 LOC	8 files (excl. regenerated schema), ~200 net LOC
Macro naming	%azl_upstream_*	%fedora_upstream_* (explicit about the source)

Design

• New option: sources.WithUpstreamProvenance(distTag string) on SourcePreparer. distTag is the resolved %{?dist} expansion (FedoraDistTag(distroName, releaseVer) returns .fc<N> for Fedora, "" otherwise, disabling the feature).
• Hook point: writeMacrosFile (in the pre-overlay window). The pristine spec exists on disk right after FetchComponent, before overlays rewrite it. parseSpecVersionRelease reads Version/Release verbatim via the existing spec.VisitTagsPackage path; only %{?dist} is substituted.
• Opt-in flag: build.emit-upstream-provenance = true in [components.<name>.build]. Fingerprintable — flipping it changes rendered output. Registered with the component history collector.
• Precedence: build.defines wins (macros are layered via setMacroIfAbsent).
• Emission mechanism unchanged: reuses the existing .azl.macros + %{load:%{_sourcedir}/...} + Source9999 path. No second mechanism.
• Gates in order: dist-tag non-empty → opt-in flag → spec.type = upstream. Local, SRPM, and non-Fedora upstream components are skipped, so the flag is a no-op for them.
• Failure mode: best-effort. If the opt-in is set but the spec can't be located or parsed, a WARN is logged and the macros are skipped; render/build proceeds without them.

Consumer example (grub2 SBAT)

An accompanying comp.toml change in the azurelinux repo enables the flag and adds a spec-search-replace overlay:

[components.grub2.build]
emit-upstream-provenance = true

[[components.grub2.overlays]]
description = "Use %fedora_upstream_* macros for the grub.rh SBAT vendor_version (@@VERSION_RELEASE@@)"
type = "spec-search-replace"
regex = '-e "s,@@VERSION_RELEASE@@,%\{version\}-%\{release\},g"'
replacement = '-e "s,@@VERSION_RELEASE@@,%{?fedora_upstream_version}-%{?fedora_upstream_release},g"'

Result: the built sbat.csv's grub.rh line carries the pristine upstream Fedora NEVR (e.g. grub.rh,2,Red Hat,grub2,2.12-45.fc43,...) instead of the AZL build V-R (…azl4).

Testing

• mage unit — passing (7 new tests cover happy path, opt-out, local skip, non-Fedora skip, user-define wins, missing spec best-effort, empty release, and dist-tag mapping).
• mage check all — passing (linting, static analysis, license, schema).
• mage docs regenerated the JSON schema for the new field.
• grub2 build succeeded and the SBAT overlay is verified working using command:

rpm2cpio base/out/rpms/rpm-base/grub2-efi-x64-2.12-46.azl4.x86_64.rpm \
  | cpio -i --to-stdout ./boot/efi/EFI/azurelinux/grubx64.efi 2>/dev/null \
  | objcopy -O binary --only-section=.sbat /dev/stdin /dev/stdout \
  | tr -d '\000'

Both EFI binaries (x64 and ia32) carry identical SBAT data:

sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
grub,5,Free Software Foundation,grub,2.12,https//www.gnu.org/software/grub/
grub.rh,2,Red Hat,grub2,2.12-40.fc43,mailto:secalert@redhat.com

Fix AB#12798

Limitations (documented)

• Tag values are read as plain text; only %{?dist} is expanded. A tag built from other macros (e.g. Version: %{majorver}.%{minorver}) is captured with those macros unexpanded.
• Listing fedora_upstream_version / _release in build.undefines does not suppress the injected macros. Use emit-upstream-provenance = false (or omit it) instead.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.