refactor: move Cooldown class from context to candidate module

[tiran]

Pull Request Description

What

Cooldown is a data class closely related to candidate filtering, not to the WorkContext lifecycle.

Why

Moving it to fromager.candidate removes a circular import workaround in resolver.py and keeps the candidate module self-contained.

• PR follows CONTRIBUTING.md guidelines

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request moves the Cooldown dataclass from src/fromager/context.py to src/fromager/candidate.py. The dataclass definition, containing min_age and bootstrap_time fields, is relocated unchanged. All import statements and type annotations across six source files and one test file are updated to reference candidate.Cooldown instead of context.Cooldown. The dataclasses import is removed from context.py as it is no longer needed.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically describes the main change: moving the Cooldown class from context to candidate module.
Description check	✅ Passed	The description clearly relates to the changeset, explaining the what (moving Cooldown) and why (removes circular import, keeps candidate module self-contained).
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

tests/test_cooldown.py (1)

116-116: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Local variable candidate shadows the imported candidate module.

Five test functions assign a local variable named candidate, which shadows from fromager import candidate for the rest of that scope. No test currently uses candidate.Cooldown after the shadowing, so there's no immediate bug — but any future edit that tries to do so inside one of these functions will get AttributeError: 'Candidate' object has no attribute 'Cooldown'.

🛠️ Suggested fix — rename local variables

-        candidate = result.mapping["test-pkg"]
-        assert str(candidate.version) == "1.3.2"
+        resolved = result.mapping["test-pkg"]
+        assert str(resolved.version) == "1.3.2"

Apply the same rename (resolved or c) in the other affected lines (137, 166, 535, 604).

Also applies to: 137-137, 166-166, 535-535, 604-604

🤖 Prompt for 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.

In `@tests/test_cooldown.py` at line 116, A local variable named "candidate" is
shadowing the imported module "candidate" (from fromager), so rename the local
variable instances (e.g., the assignment "candidate =
result.mapping['test-pkg']" and the other similar assignments) to a
non-conflicting name like "resolved" or "c" and update any subsequent uses in
those test functions; ensure any references to the module's symbol
candidate.Cooldown still refer to the imported module rather than the local
variable.

🧹 Nitpick comments (1)

src/fromager/candidate.py (1)

18-29: ⚡ Quick win

Consider adding frozen=True to Cooldown to match the docstring's immutability guarantee.

The docstring says bootstrap_time is "fixed at construction", but the dataclass allows post-construction mutation. Candidate in the same file is frozen=True; Cooldown should follow suit. No current callers mutate fields after creation, so the change is safe.

♻️ Proposed refactor

-@dataclasses.dataclass
+@dataclasses.dataclass(frozen=True)
 class Cooldown:

🤖 Prompt for 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.

In `@src/fromager/candidate.py` around lines 18 - 29, The Cooldown dataclass is
mutable but the docstring states bootstrap_time is fixed; make it immutable by
adding frozen=True to the `@dataclasses.dataclass` decorator for class Cooldown so
its fields (including bootstrap_time) cannot be modified after construction;
locate the Cooldown class definition and change `@dataclasses.dataclass` to
`@dataclasses.dataclass`(frozen=True) (mirroring Candidate) to enforce
immutability.

🤖 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.

Outside diff comments:
In `@tests/test_cooldown.py`:
- Line 116: A local variable named "candidate" is shadowing the imported module
"candidate" (from fromager), so rename the local variable instances (e.g., the
assignment "candidate = result.mapping['test-pkg']" and the other similar
assignments) to a non-conflicting name like "resolved" or "c" and update any
subsequent uses in those test functions; ensure any references to the module's
symbol candidate.Cooldown still refer to the imported module rather than the
local variable.

---

Nitpick comments:
In `@src/fromager/candidate.py`:
- Around line 18-29: The Cooldown dataclass is mutable but the docstring states
bootstrap_time is fixed; make it immutable by adding frozen=True to the
`@dataclasses.dataclass` decorator for class Cooldown so its fields (including
bootstrap_time) cannot be modified after construction; locate the Cooldown class
definition and change `@dataclasses.dataclass` to
`@dataclasses.dataclass`(frozen=True) (mirroring Candidate) to enforce
immutability.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 63fee026-f4a3-4e72-b366-3793ab9f70b4

📥 Commits

Reviewing files that changed from the base of the PR and between bc300d4 and a11cb19.

📒 Files selected for processing (6)

• src/fromager/__main__.py
• src/fromager/candidate.py
• src/fromager/context.py
• src/fromager/packagesettings/_pbi.py
• src/fromager/resolver.py
• tests/test_cooldown.py