feat: warn on overlapping output files and unused staging files

[wolfv]

Ref #2730 (see also #2753)

Adds two cross-output consistency checks that run after all outputs are built:

• Overlapping files — two outputs of the same recipe package the same file, so installing both clobbers it. With staging caches this usually means an output forgot to narrow its files selection.
• Unused staging files — files from a staging cache were not included in any output that inherits from it (the "silently dropped or silently duplicated" ambiguity from BUG: output with no files: constraint inherits entire staging output as content #2730).

Both are warnings by default; --error-overlapping-files and --error-unused-staging-files turn them into hard errors. Warnings are also recorded on the involved outputs so they appear in build/markdown summaries.

⚠ Outputs 'liba' and 'libb' both package 1 file(s), which will clobber each other on installation:
    - lib/libcore.so
⚠ 1 file(s) from staging cache 'stage' were not included in any of the outputs that inherit from it (liba, libb):
    - include/unused.h

How

create_package now records the prefix-relative files each output selected for packaging (before noarch path remapping) in the build summary. The checks in the new output_checks module compare those sets:

• Overlap: pairwise within one recipe, on prefix-relative paths — so a noarch and an arch output shipping the same prefix file are caught even though their packaged paths differ. Same-name outputs are never compared (they can't be co-installed); variant repeats of a pair are deduped.
• Unused: per cache directory (one per staging output + variant selection), against prefix_files from the cache's metadata.json, minus files packaging always drops (CACHEDIR.TAG, .pyo, …). A cache is only judged when all of its inheriting outputs were packaged in the run — a consumer skipped by --skip-existing/--noarch-build-platform or failed under --continue-on-failure leaves usage unknown, so no false errors (verified manually with --skip-existing=local --error-unused-staging-files).

Notes

• test-data/recipes/staging/multiple-staging-caches.yaml now (correctly) warns: libcore and core-headers genuinely both package include/core.h.
• Flag plumbing follows --error-prefix-in-binary; py-rattler-build passes the defaults (can be exposed as kwargs later).
• CLI docs regenerated with rattler_build_docs; prose section added to docs/multiple_output_cache.md.

Tests

• e2e test_staging_consistency_checks: both warnings fire on a new fixture, and each flag makes the build fail.
• e2e test_staging_checks_quiet_when_all_files_used: a recipe whose outputs cover the cache and share nothing builds clean under both strict flags.
• Full workspace tests green except pre-existing test_system_tool (no patchelf in the dev container); all 23 staging e2e tests pass; fmt and clippy clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_016Rj3CRpTRFpCtsnCVdaaQd

---

Generated by Claude Code