feat(resolver): exempt top-level == pins from release cooldown

[LalatenduMohanty]

Summary

• Top-level requirements with == version pins now bypass release cooldown enforcement — the operator has explicitly chosen that version
• Transitive == pins remain subject to cooldown to prevent malicious packages from bypassing the check via pinned dependencies
• Safe default: callers that don't pass req_type still get full cooldown enforcement

Closes #1123

[coderabbitai]

Warning

Rate limit exceeded

@LalatenduMohanty has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 54 minutes before requesting another review.

To continue reviewing without waiting, purchase usage credits in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5ddb1bc4-3843-44ad-b5ae-1f82cc6365f7

📥 Commits

Reviewing files that changed from the base of the PR and between 0d0fa24 and 8601726.

📒 Files selected for processing (6)

• docs/how-tos/release-age-cooldown.rst
• docs/proposals/release-cooldown.md
• src/fromager/resolver.py
• src/fromager/sources.py
• src/fromager/wheels.py
• tests/test_cooldown.py

📝 Walkthrough

Walkthrough

The resolver now considers requirement type when computing per-package release-age cooldowns. A new helper detects pure top-level exact == pins; when req_type is TOP_LEVEL and the requirement is a single exact == pin, resolve_package_cooldown returns None to bypass cooldown. Source and wheel provider construction now forward req_type into cooldown resolution. Tests add unit and end-to-end coverage for top-level exemption, transitive enforcement, wildcard/compound forms, and unspecified req_type. Documentation is updated to mark the behavior implemented and clarify scope.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and accurately describes the main change: exempting top-level == pins from release cooldown, which is the core objective of this PR.
Description check	✅ Passed	The description clearly relates to the changeset, explaining the feature (top-level == pins bypass cooldown), safety consideration (transitive pins still enforced), and safe defaults.
Linked Issues check	✅ Passed	The implementation fully satisfies #1123: top-level == pins bypass cooldown via _has_equality_pin() detection in resolve_package_cooldown(), while transitive pins remain subject to cooldown enforcement.
Out of Scope Changes check	✅ Passed	All changes directly support the cooldown exemption feature: resolver logic, provider integrations, test coverage, and documentation updates are within scope.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/fromager/resolver.py`:
- Around line 140-142: The helper _has_equality_pin currently treats any "=="
specifier as an exact pin; update it to only return True for true exact pins by
checking both spec.operator == "==" and that the spec's version contains no
wildcard characters (e.g., no '*' or patterns like '1.*'). In other words,
inside _has_equality_pin (working with the Requirement and its specifier
members), ensure you inspect spec.version (or str(spec)) and exclude specifiers
where '*' appears (or the version ends with '.*') so wildcard pins like "==1.*"
do not count as exact equality pins.

In `@tests/test_cooldown.py`:
- Around line 866-907: Add a new test that exercises the boundary case where a
top-level wildcard equality like Requirement("test-pkg==1.*") should NOT be
treated as an exact-pin exemption: call resolver.resolve_package_cooldown with
ctx from _make_ctx(tmp_path, cooldown=_COOLDOWN),
req_type=RequirementType.TOP_LEVEL and Requirement("test-pkg==1.*"), and assert
the returned value equals _COOLDOWN; place the test alongside the other
test_resolve_package_cooldown_* functions and name it something like
test_resolve_package_cooldown_toplevel_wildcard_equality_not_exempt to mirror
existing naming.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 44fe1182-608d-4129-aaa2-29b43592632d

📥 Commits

Reviewing files that changed from the base of the PR and between b5b31d9 and f234e1b.

📒 Files selected for processing (6)

• docs/how-tos/release-age-cooldown.rst
• docs/proposals/release-cooldown.md
• src/fromager/resolver.py
• src/fromager/sources.py
• src/fromager/wheels.py
• tests/test_cooldown.py

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/how-tos/release-age-cooldown.rst`:
- Around line 137-142: The wording currently states that top-level requirements
using "==" bypass cooldown but is too broad; change the text in the
release-age-cooldown docs to clarify this applies only to a single exact pin
(e.g., "package==1.2.3") and not to prefix/partial or compound specifiers like
"==1.*" or combined specifiers; update the sentences referencing "Top-level
requirements that use ``==``" and "``==`` specifiers in transitive dependencies"
to explicitly say "a single exact ``==`` pin (single version literal)" and add a
short example contrasting allowed exact pins (e.g., package==1.2.3) versus
non-exempt patterns (e.g., package==1.* or package==1.2.3,>=1.0).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 86d20d90-a812-49c5-9dfb-99d16cc4e7a8

📥 Commits

Reviewing files that changed from the base of the PR and between f234e1b and 0d0fa24.

📒 Files selected for processing (6)

• docs/how-tos/release-age-cooldown.rst
• docs/proposals/release-cooldown.md
• src/fromager/resolver.py
• src/fromager/sources.py
• src/fromager/wheels.py
• tests/test_cooldown.py

✅ Files skipped from review due to trivial changes (1)

• docs/proposals/release-cooldown.md

🚧 Files skipped from review as they are similar to previous changes (1)

• src/fromager/resolver.py

[smoparth]

LGTM!

[smoparth]

Not sure if we need to link this in proposal

[shifa-khan]

LGTM!