[Nan Liu (liunan-ms)]

Why this is needed

patch-add copies a patch and registers a PatchN: tag or %patchlist entry, but registration alone does not establish that preparation applies it. A package can build without the intended downstream fix, or fail later because the patch
paths and strip level do not agree.

Related open issues:

• #408:
  added patches can be silently skipped in specs with hand-written %patch
  sequences. This PR makes missing recognized application visible during rendering.
• #409:
  bare %autosetup can use an incompatible strip level for subdirectory patches.
  This PR reports likely path/strip mismatches before the build.
• #423:
  proposed strip-aware application and final-render diagnostics. This PR implements
  the diagnostic portion using a deliberately narrower static-analysis contract.

These are related/partially addressed issues, not automatic-closing references:
this PR does not implement a strip configuration field, insert application commands, or rewrite existing preparation commands.

Changes

• Inspect the final spec and final added-patch contents after all overlays, including overlays that repair application or remove a declaration.
• Share read-only lexical analysis between the legacy and experimental structural editors.
• Recognize %patch forms, %autopatch, %autosetup, and supported %forgeautosetup / %goprep behavior, including disabled patching and ranges.
• Check relevant unconditional macro-helper redefinitions, execution hazards, backend behavior, and likely header-path/strip mismatches.
• Expose per-component patchWarnings in render JSON and add --patch-warnings=warn|error.
• Update user reference, generated CLI documentation, both emitted agent-guidance variants, unit/integration tests, and CLI snapshots.

Decision flow

For each supplied overlay-added patch:

1. Find its declaration in the final spec. If a later overlay removed it, skip it.
2. Warn if its final file is missing, its declaration is conditional/repeated, or another declaration uses its known number.
3. Keep explicit/implicit numbering information. An unknown number can match an unrestricted bulk command, but cannot establish a numbered/range selection.
4. Require one ordinary unconditional %prep. Repeated, conditional, augmented (%prep -a / %prep -p), or malformed preparation remains unverified.
5. Collect supported unconditional application candidates:
   • Respect -N, wrapper defaults, explicit selections, inclusive ranges, backend, and strip options.
   • Accept braced directory-name macros in -n without evaluating them.
   • Capture relevant preceding unconditional directory/control-flow hazards and invoked helper redefinitions; do not invalidate earlier candidates because of unrelated later commands.
6. If any selecting candidate has no detected relevant problem, emit no diagnostic. Otherwise report a candidate's problem or the absence of recognized unconditional selection.

Ordinary preamble macros, unrelated generated definitions, and opaque surrounding commands do not veto an otherwise understood selection. Conditional commands and their side effects are skipped. Duplicate application is deliberately not detected. Loaded macro files and macro expressions are not evaluated.

Rendering policy

Finding	Default --patch-warnings=warn	--patch-warnings=error
Missing unconditional selection, including a simple missing/excluding command	Warning; component can render	Component error
Unsupported/uncertain preparation or likely strip mismatch	Warning; component can render	Component error

--fail-on-error controls whether component failures cause a nonzero invocation exit. Successful components retain their output when another component fails.
--check-only retains its existing freshness/drift semantics.

Validation

Automated checks

The following commands passed during implementation/review:

• mage fix all - passed.
• mage unit - passed, including both-editor selection/numbering/helper regressions
  and render JSON/default/strict-policy tests.
• mage check all - passed.
• mage docs - passed; CLI reference regenerated.
• TESTING_DISABLE_NETWORK_TESTS=1 mage scenarioUpdate - passed; snapshots updated.
• TESTING_DISABLE_NETWORK_TESTS=1 mage all - passed: build, unit tests,
  formatting/lint, static analysis, licenses, offline scenarios, and docs/schema.

Rendered 56 components with patch-add overlays

3 patch warnings:

Component	Added patch	Reason	Warning
fido-device-onboard	pin-libcryptsetup-rs-0.13.2.patch (Patch1001)	Application commands are conditional; no unconditional selection. The RHEL range ends at 999.	Conditional patch application cannot be verified for every build configuration
python-blivet	bb696202-fix-cpe-2.3-version-parsing.patch (Patch104)	Applying %autosetup uses additional archive extraction (-b1), outside the modeled setup flow.	Custom or multi-source setup cannot be resolved
uv	0001-use-python314-tests.patch (Patch4)	%prep -a is intentionally unsupported; implicit build-system preparation is not modeled.	Multiple, conditional, or nonstandard preparation sections cannot be resolved

A separate negative check intentionally removed the application overlay for golang-github-gorilla-sessions: the patch remained declared, while bare %goprep and cp supplied no recognized application. Rendering correctly returned
status: "ok" with a missing-unconditional-selection warning under default policy.

[Copilot]

🟡 Changes recommended

Active analyzer defects can silently accept unapplied patches and falsely reject valid components in strict mode because function declarations, macro state, helper overrides, and diff hunk boundaries are mishandled.

4 open issues

• Process macro bodies before skipping blank lines · New
• Track patch helper overrides outside the prep section · New
• Recognize POSIX function declarations as uncertain control flow · New
• Ignore hunk content when checking patch file headers · New

What changed in this PR

Adds static diagnostics for overlay-added patches during source preparation and rendering, partially addressing #408, #409, and #423 without inserting application commands or changing strip levels.

Changes:

• Shares final-spec patch analysis across both editors to identify missing selection, uncertain application, and likely strip mismatches.
• Adds render JSON patchWarnings and the --patch-warnings=warn|error policy.
• Updates regression coverage, CLI snapshots, user documentation, and both agent-guidance variants.

File	Description
scenario/​component_render_test.go	Tests warning JSON and strict rendering behavior.
scenario/​clismoke_test.go	Adds render-help snapshot coverage.
scenario/​__snapshots__/​TestSnapshots_component_render_help_stdout_1.snap	Records render help and warning policy.
scenario/​__snapshots__/​TestSnapshots_component_render_help_stderr_1.snap	Records help startup logging.
scenario/​__snapshots__/​TestSnapshots_component_render_help_1.snap.json	Records successful help exit status.
internal/​rpm/​spec/​patch_application.go	Implements shared lexical patch-application analysis.
internal/​rpm/​spec/​patch_application_test.go	Covers selection, macros, execution hazards, and paths.
internal/​app/​azldev/​core/​sources/​sourceprep.go	Invokes diagnostics after overlays and adds a reporting callback.
internal/​app/​azldev/​core/​sources/​patch_application.go	Reads final patch contents and reports diagnostics.
internal/​app/​azldev/​core/​sources/​patch_application_internal_test.go	Tests final-overlay analysis and reporting.
internal/​app/​azldev/​cmds/​component/​render.go	Adds warning policy and preserves diagnostics in results.
internal/​app/​azldev/​cmds/​component/​render_test.go	Tests flag registration and policy validation.
internal/​app/​azldev/​cmds/​component/​render_patch_warnings_internal_test.go	Tests JSON, strict rejection, freshness checks, and failures.
internal/​app/​azldev/​agentskill/​content/​withoutlockfile/​overlays.md.tmpl	Documents diagnostics for lockfile-free workflows.
internal/​app/​azldev/​agentskill/​content/​overlays.md.tmpl	Documents diagnostics for default workflows.
internal/​app/​azldev/​agentskill/​agentskill_test.go	Checks diagnostic guidance in both modes.
docs/​user/​reference/​config/​overlays.md	Explains analysis limits and strict rendering policy.
docs/​user/​reference/​cli/​azldev_component_render.md	Updates generated render command reference.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Unresolved parsing issues falsely reject valid patch applications and allow patches running in a subshell’s changed directory to pass strict checks without a diagnostic.

3 open issues

• Clear continuation state on unconditional blank or comment lines · New
• Flag subshell openers as unverified shell control · New
• Recognize context-diff hunk headers during path checks · New

4 resolved since last review

• Ignore hunk content when checking patch file headers
• Recognize POSIX function declarations as uncertain control flow
• Track patch helper overrides outside the prep section
• Process macro bodies before skipping blank lines

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The scanner misses assignment- and builtin-prefixed commands that can skip or misdirect patch application even under strict rendering, while misclassified backslashes can also cause valid components to be rejected.

2 open issues

• Detect hazardous commands behind assignments and builtin prefixes · New
• Ignore comments and escaped backslashes when detecting continuations · New

3 resolved since last review

• Recognize context-diff hunk headers during path checks
• Flag subshell openers as unverified shell control
• Clear continuation state on unconditional blank or comment lines

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

A critical control-flow gap ignores ! exit 0, allowing an unreachable %patch0 -p1 to pass without diagnostics even in strict mode; both editors need a fix and regression coverage.

1 open issue

• Recognize negated exit commands as shell control flow · New

2 resolved since last review

• Detect hazardous commands behind assignments and builtin prefixes
• Ignore comments and escaped backslashes when detecting continuations

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Critical parsing and backend-state gaps suppress diagnostics for missing or unreachable patch applications and incorrect strip levels, including under strict policy.

4 open issues

• Ignore colons inside macros when parsing Patch tags · New
• Parse leading redirections before classifying shell commands · New
• Propagate backend uncertainty from macro-valued -S options · New
• Check old filenames in context diff headers · New

1 resolved since last review

• Recognize negated exit commands as shell control flow

_{Review effort: Balanced}