fix(releasing): handle proc-macro packages

[sgalkin]

Summary

• detect proc-macro-only packages from Cargo metadata before invoking cargo-semver-checks, then use the standard package review prompt and decision path for explicit manual classification
• when a proc-macro release is marked breaking, require manual review of crates that directly depend on it
• continue that review to the next layer only when a reviewed dependent is also marked breaking; each crate keeps its own classification
• treat No material changes as a completed review: an out-of-plan proc macro is released only if later cascade requires it, at the normal patch floor and without a second prompt
• align CI SemVer reporting, workflow guidance, release documentation, and focused Pester coverage without changing ordinary-library analysis

The supported release command is:

./scripts/release-packages.ps1 -Packages 'templated_uri_macros@patch'

The provisional patch entry is replaced or retained by the standard interactive review decision.

Validation

• 230 focused Pester tests passed, including all 28 release scenarios
• reproduced direct and cascade release-planner paths and the CI SemVer report path
• package-scoped formatting completed for all 45 workspace packages
• just readme completed
• final read-only changeset review found no high-confidence defects

just spellcheck could not run locally because the pinned cargo-spellcheck build requires libclang, which is unavailable on this Windows host; CI provisions that dependency.

[Copilot]

Pull request overview

This PR updates the release tooling to detect proc-macro-only crates via cargo metadata, bypass unsupported cargo-semver-checks analysis for those crates, and require explicit manual SemVer classification—propagating mandatory manual review to direct published consumers one dependency edge at a time only when the upstream increment is breaking. It also aligns CI SemVer reporting, documentation, and Pester coverage with the new proc-macro behavior.

Changes:

• Add proc-macro-only target detection (HasLibraryTarget / IsProcMacroOnly) and ensure proc-macro-only crates are classified as manual instead of invoking cargo-semver-checks.
• Implement and test one-edge-at-a-time mandatory manual review propagation for breaking proc-macro compatibility chains (planner + CI report).
• Expand Pester unit/scenario/integration coverage and update release docs/CI workflow guidance to reflect proc-macro handling.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/lib/releasing.ps1	Adds cargo-metadata target classification and proc-macro-only bypass in the semver classifier; introduces helper for direct published dependents.
scripts/lib/release-flow.ps1	Implements planner manual-review queue and propagation logic; updates menu behavior for “keep planned level” when already in release set.
scripts/ci/semver-report.ps1	Extends CI SemVer report to warn for proc-macro-only crates and propagate manual-review warnings through breaking chains (direct dependents only).
scripts/release-packages.ps1	Updates release-script help text to document proc-macro-only manual review and downstream propagation semantics.
docs/releasing.md	Documents proc-macro-only manual review workflow and how CI/reporting behaves for proc-macro chains and unknown baselines.
.github/workflows/main.yml	Updates workflow comments to reflect proc-macro detection + manual review reporting behavior.
scripts/tests/Pester/unit/releasing/GitFs.Tests.ps1	Adds unit coverage for proc-macro-only metadata classification and semver-checks bypass.
scripts/tests/Pester/unit/release-packages/ResolveReleaseSet.Tests.ps1	Adds tests for direct-dependents logic and proc-macro-only cascade/manual review propagation behaviors.
scripts/tests/Pester/unit/release-crate/PromptFlow.Tests.ps1	Adds tests ensuring proc-macro manual-review findings reuse the standard menu and checks re-prompt precedence behavior.
scripts/tests/Pester/_common/New-SyntheticWorkspace.ps1	Enables synthetic workspaces to generate proc-macro crates via [lib] proc-macro = true.
scripts/tests/Pester/integration/SemverReport.Tests.ps1	Adds integration coverage for CI semver-report proc-macro-only behavior and missing-consumer reporting.
scripts/tests/Pester/scenarios/S25-proc-macro-user-review.scenario.psd1	Adds scenario coverage for user-selected proc-macro manual review + direct consumer review.
scripts/tests/Pester/scenarios/S26-proc-macro-cascade-review.scenario.psd1	Adds scenario coverage for cascade-added proc-macro manual review at patch floor with non-breaking override.
scripts/tests/Pester/scenarios/S27-proc-macro-recursive-review.scenario.psd1	Adds scenario coverage for multi-hop (proc-macro → facade → app) one-edge-at-a-time review propagation.

Comments suppressed due to low confidence (1)

scripts/lib/release-flow.ps1:1834

• $reviewedManualSemver is updated before the ignore/accept branch, so a proc-macro package that was skipped while not in the release set is treated as “manual review completed” and will not be re-prompted if it later becomes a required cascade member. The reviewed set should only be updated when the package is being released (InReleaseSet) or the reviewer explicitly chose a release level (non-ignore action).

            $decision  = Get-PackageReleaseDecision -Finding $next -RemainingCount $remaining -RepoRoot $RepoRoot
            $isManualSemverReview = [bool]$next.RequiresManualSemverReview
            if ($isManualSemverReview) {
                # Proc-macro status affects why this decision is required and
                # how review propagates, not the menu or decision semantics.
                [void]$reviewedManualSemver.Add($next.Folder)
            }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (b650922) to head (b648617).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #602   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files         443      443           
  Lines       43446    43446           
=======================================
  Hits        43446    43446           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sandersaares]

propagate mandatory review one direct published-dependent edge at a time only through actual breaking version transitions, including correct 0.x and forced-pin handling

What does this mean?

[ralfbiedert]

Approved. I found no blocking correctness, performance, standards, or unsafe issues. The proc-macro manual SemVer flow and dependent propagation appear sound.

[sgalkin]

@sandersaares Put simply: when a proc-macro release is marked breaking, we ask the maintainer to review the crates that directly depend on it. If one of those crates is also marked breaking, we then review its direct dependents. Otherwise the extra review stops there. Each crate gets its own classification; the proc macro's classification is never copied downstream.

I updated the PR summary to use this wording.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

scripts/lib/release-flow.ps1:2180

• Same issue for cascade entries: the proc-macro chain annotation is printed when ManualSemverReviewCompleted is true even if there are no ManualSemverReviewSources, which can lead to empty parentheses in the release-plan output.

        } elseif ($entry.ManualSemverReviewCompleted) {
            $sources = @($entry.ManualSemverReviewSources) -join ', '
            Write-Host "      SemVer classification: cargo-semver-checks plus manual review of breaking proc-macro dependency chain ($sources)" -ForegroundColor Yellow
        }

scripts/lib/release-flow.ps1:2165

• Show-ReleasePlan prints the proc-macro dependency-chain annotation whenever ManualSemverReviewCompleted is true, even if ManualSemverReviewSources is empty. This can produce confusing output like "(... chain ())" for entries that were reviewed earlier but no longer require propagated review in the final plan. Guard the message on having at least one source (or populate sources for all completed reviews).

This issue also appears on line 2177 of the same file.

        } elseif ($entry.ManualSemverReviewCompleted) {
            $sources = @($entry.ManualSemverReviewSources) -join ', '
            Write-Host "      SemVer classification: cargo-semver-checks plus manual review of breaking proc-macro dependency chain ($sources)" -ForegroundColor Yellow
        }