refactor(bootstrapper): simplify top-level requirement interface

[dhellmann]

Pull Request Description

What

Add public bootstrap(requirements: list[Requirement]) that combines the resolution loop (previously resolve_and_add_top_level()) and the DFS processing loop into a single method. Callers no longer need to manage requirement_ctxvar context or track which requirements resolved successfully.

Rename the old bootstrap(req, req_type) to _bootstrap_one() (private) since it is only used by the git URL resolution path in _handle_build_requirements(). Rename resolve_and_add_top_level() to _resolve_and_add_top_level() (private) as it is now only called inside bootstrap().

bootstrap() and _bootstrap_one() shared an identical DFS while-loop. Extract it into _run_bootstrap_loop(stack) so there is a single implementation to maintain.

Remove the per-requirement failed-version reporting block from _bootstrap_one() since finalize() already produces a complete summary.

Update commands/bootstrap.py to replace the two-loop pattern with a single bt.bootstrap(to_build) call, and remove the now-unused requirement_ctxvar import.

Update all affected tests to use the renamed private methods or the new public interface.

Why

Closes: #1211

• PR follows CONTRIBUTING.md guidelines

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3e61a845-3dd3-4219-a6e3-a1159db0d803

📥 Commits

Reviewing files that changed from the base of the PR and between a13e1fd and 4d82de9.

📒 Files selected for processing (6)

• src/fromager/bootstrapper.py
• src/fromager/commands/bootstrap.py
• tests/test_bootstrap.py
• tests/test_bootstrap_test_mode.py
• tests/test_bootstrapper.py
• tests/test_bootstrapper_iterative.py

💤 Files with no reviewable changes (1)

• tests/test_bootstrap.py

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

• tests/test_bootstrapper_iterative.py
• tests/test_bootstrap_test_mode.py
• src/fromager/commands/bootstrap.py
• src/fromager/bootstrapper.py

---

📝 Walkthrough

Walkthrough

Bootstrapper.bootstrap is redesigned to accept list[Requirement] instead of a single Requirement plus RequirementType. The new method resolves each top-level requirement via the now-private _resolve_and_add_top_level, manages requirement_ctxvar tokens internally, builds an initial RESOLVE-phase WorkItem stack, and delegates DFS iteration to a new _run_bootstrap_loop helper. The former public bootstrap(req, req_type) is renamed to _bootstrap_one (used by the git-URL path) and similarly delegates to _run_bootstrap_loop. _handle_build_requirements is updated to call _bootstrap_one. The CLI command in commands/bootstrap.py drops its manual resolve/bootstrap/context-var loop in favour of a single bt.bootstrap(list(to_build)) call. Tests are updated throughout to reflect the new signatures and private method names.

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 clearly describes the main change: refactoring the bootstrapper's top-level requirement interface by simplifying it.
Description check	✅ Passed	The description comprehensively explains what was changed, why it was changed, and how the changes address the problem of an inconsistent public interface.
Linked Issues check	✅ Passed	The PR fully implements the requirements from issue #1211: new public bootstrap(requirements: list[Requirement]) method, renaming of old methods to private, DFS loop extraction, and command layer updates.
Out of Scope Changes check	✅ Passed	All changes are scoped to the refactoring objective: bootstrapper API changes, command layer simplification, and test updates. No unrelated modifications detected.

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/fromager/bootstrapper.py (1)

329-341: 🧹 Nitpick | 🔵 Trivial | 💤 Low value

Consider adding versionadded directive for the new public API.

This is a new public method with a different signature than the former bootstrap(req, req_type). Per coding guidelines, user-facing changes should include Sphinx version directives for documentation.

     def bootstrap(self, requirements: list[Requirement]) -> None:
         """Bootstrap all top-level requirements and their transitive dependencies.
 
+        .. versionadded:: X.Y
+           Replaces the former ``bootstrap(req, req_type)`` signature.
+
         Resolves each requirement, adds it to the dependency graph, and processes

🤖 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/bootstrapper.py` around lines 329 - 341, The bootstrap method in
the bootstrapper.py file is a new public API with a modified signature that
requires documentation of when it was introduced. Add a Sphinx versionadded
directive to the docstring of the bootstrap method, placing it after the main
description and before the Args section. The directive should follow the format
`.. versionadded:: <version>` to document this as a new or changed public API
per the coding guidelines.

Source: Coding guidelines

🤖 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 `@tests/test_bootstrapper.py`:
- Around line 764-787: The assertion at the end of
test_bootstrap_two_requirements_both_processed converts dispatch_calls to a set
for comparison, which masks duplicate processing of the same requirement. Change
the assertion to compare the sorted list directly instead of converting to a
set, so that duplicate dispatches of pkg1 or pkg2 are caught and the test fails
when a requirement is processed more than once. This ensures the test actually
verifies that each requirement is processed exactly once without duplicates.

---

Nitpick comments:
In `@src/fromager/bootstrapper.py`:
- Around line 329-341: The bootstrap method in the bootstrapper.py file is a new
public API with a modified signature that requires documentation of when it was
introduced. Add a Sphinx versionadded directive to the docstring of the
bootstrap method, placing it after the main description and before the Args
section. The directive should follow the format `.. versionadded:: <version>` to
document this as a new or changed public API per the coding guidelines.

🪄 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: 0d0c3b1d-72d2-4dcc-8362-da9b30571f20

📥 Commits

Reviewing files that changed from the base of the PR and between 7ce238d and a13e1fd.

📒 Files selected for processing (6)

• src/fromager/bootstrapper.py
• src/fromager/commands/bootstrap.py
• tests/test_bootstrap.py
• tests/test_bootstrap_test_mode.py
• tests/test_bootstrapper.py
• tests/test_bootstrapper_iterative.py

💤 Files with no reviewable changes (1)

• tests/test_bootstrap.py

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request