ci: switch compile to fbuild compile-many

[zackees]

Summary

• switch the fbuild-backed ./compile path to use a single fbuild compile-many invocation when the installed fbuild supports it
• stage one build project per example for compile-many, parse per-sketch results, and retain the legacy serial loop as a fallback until a released fbuild exposes the new subcommand
• remove the GITHUB_ACTIONS CPU-count short-circuit and add tests for the new wrapper/job defaults and compile-many integration

Testing

• uv run pytest ci/tests/test_fbuild_compile_many.py ci/tests/test_fbuild_default_selection.py -q
• uv run ruff check ci/util/cpu_count.py ci/util/fbuild_runner.py ci/compiler/pio.py ci/tests/test_fbuild_compile_many.py

Closes#2470.

Summary by CodeRabbit

• New Features

  • Batched "compile-many" build mode that stages isolated per-example project directories and runs a single aggregated build, producing per-example results and logs.

• Improvements

  • CPU/job defaults and detection refined; clearer per-example SUCCESS/FAILED output, per-sketch log substitution, generation/copying of per-example build_info artifacts, and safer platform lock handling with fallbacks to legacy paths.

• Tests

  • New tests for compile-many parsing, failure handling, job calculations, and end-to-end build integration.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds batched fbuild support: uncaps cpu_count on Actions, implements a compile-many/ci batch runner that parses per-sketch results, stages isolated per-example PlatformIO projects, routes PioCompiler to invoke a single batched run, and adds tests covering parsing, staging, and artifact generation.

Changes

fbuild compile-many integration

Layer / File(s)	Summary
Remove GitHub Actions CPU capping ci/util/cpu_count.py	cpu_count() no longer checks GITHUB_ACTIONS to force single-CPU mode; behavior now depends only on NO_PARALLEL.
fbuild_runner imports and datatypes ci/util/fbuild_runner.py	Adds imports for env/caching/regex/dataclasses and introduces dataclasses and a compiled regex to represent and parse compile-many per-sketch results.
Job/probe/parser helpers ci/util/fbuild_runner.py	Adds default_fbuild_framework_jobs/default_fbuild_sketch_jobs, a cached fbuild_supports_compile_many() probe, and a parser converting compile-many stdout into structured sketch results.
Batched fbuild runner & wrappers ci/util/fbuild_runner.py	Implements _run_fbuild_batch_command to execute fbuild ci/fbuild compile-many with computed job counts and sketch dirs, parse stdout into per-sketch results, handle timeouts/interrupts/format-drift, and exposes run_fbuild_ci/run_fbuild_compile_many.
PioCompiler staging and compile-many routing ci/compiler/pio.py	Adds hashlib import; extends _init_platformio_build(..., build_dir) for per-example staging; adds _build_fbuild() dispatcher and helpers (_compile_many_project_dir, _stage_fbuild_compile_many_projects, _build_fbuild_compile_many, _build_fbuild_ci, and shared batch path) to stage per-example projects, invoke a single batched run, map results to examples, read logs, print SUCCESS/FAILED lines, produce/copy build_info_<example>.json, and ensure platform lock release.
Comprehensive test coverage ci/tests/test_fbuild_compile_many.py	Adds tests for cpu_count uncapping under Actions, verifying run_fbuild_ci command construction and parsing (including partial-parse failure), and validating PioCompiler.build() integration consuming compile-many/ci results and creating build_info artifacts.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

• feat(cli): normalize compile-many under a PlatformIO-compatible fbuild ci command fbuild#242: The new fbuild_runner ci path and compile-many parsing implement CLI normalization and batching discussed in this issue.
• CI: migrate all QEMU emulation tests to fbuild for faster native-tooling builds #2287: Both changes touch PioCompiler and CI build routing related to migrating CI builds from PlatformIO to fbuild.

Possibly related PRs

• FastLED/FastLED#2299: Overlaps on fbuild artifact handling and where fbuild-produced artifacts are read from or mirrored.
• FastLED/FastLED#2409: Threads use_fbuild/backend selection into compilation flow which this PR consumes and extends with batched compile-many/ci logic.

Poem

🐰 I hashed each sketch to its cozy den,
Batched the builds so fbuild wakes just when,
One daemon hums and many logs unfurl,
SUCCESS or FAILED for each tiny world.
Hop, compile, copy — carrots for the build!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 65.71% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'ci: switch compile to fbuild compile-many' accurately summarizes the main objective: replacing per-example fbuild invocations with a single compile-many call for improved CI performance.
Linked Issues check	✅ Passed	The PR successfully implements all key coding requirements from #2470: adds compile-many support via fbuild_runner functions, stages per-example projects, removes GITHUB_ACTIONS CPU short-circuit, adds job-control env vars, and includes comprehensive tests.
Out of Scope Changes check	✅ Passed	All changes directly support the primary objective of switching to fbuild compile-many: fbuild_runner infrastructure, cpu_count simplification, PioCompiler batching, and validation tests. No unrelated modifications detected.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/2470-fbuild-compile-many

---

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 `@ci/tests/test_fbuild_compile_many.py`:
- Around line 134-141: The constructor call to
fbuild_runner.FbuildCompileManySketchResult has inconsistent indentation: align
the stage="stage1" argument with the other keyword arguments
(sketch_dir=root_project, success=True, build_time_secs=1.0, log_path=root_log,
message="ok") so all parameters have the same indentation level inside the
fbuild_runner.FbuildCompileManySketchResult(...) invocation.
In `@ci/util/fbuild_runner.py`:
- Around line 51-68: The two dataclasses FbuildCompileManySketchResult and
FbuildCompileManyResult must be decorated with `@typechecked` for runtime type
validation; add "from typeguard import typechecked" if missing and place
`@typechecked` immediately above each `@dataclass` declaration (i.e., above
FbuildCompileManySketchResult and above FbuildCompileManyResult) so their fields
are validated at runtime (FbuildCompileManyResult still inherits from
FbuildCommandResult).

🪄 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: b52caa49-26bc-4b92-93ba-4edbf9aa9efc

📥 Commits

Reviewing files that changed from the base of the PR and between 36abcfb and 6a8abe5.

📒 Files selected for processing (4)

• ci/compiler/pio.py
• ci/tests/test_fbuild_compile_many.py
• ci/util/cpu_count.py
• ci/util/fbuild_runner.py

💤 Files with no reviewable changes (1)

• ci/util/cpu_count.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 `@ci/util/fbuild_runner.py`:
- Around line 73-79: The parser currently requires exact two-space separators in
_COMPILE_MANY_RESULT_RE and _parse_compile_many_results silently drops
non-matching lines; update run_fbuild_compile_many so that after calling
_parse_compile_many_results you check the raw fbuild stdout/stderr and if they
are non-empty but the returned sketch_results list is empty, emit a warning (via
logger) and mark success=False (or return an explicit error) so callers don't
treat an empty parse as success; reference _COMPILE_MANY_RESULT_RE,
_parse_compile_many_results and run_fbuild_compile_many when making the change.

🪄 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: b0f77402-4ac8-4836-994a-a5dbe0440aeb

📥 Commits

Reviewing files that changed from the base of the PR and between 6a8abe5 and ec12d7f.

📒 Files selected for processing (2)

• ci/tests/test_fbuild_compile_many.py
• ci/util/fbuild_runner.py

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

• ci/tests/test_fbuild_compile_many.py

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@ci/util/fbuild_runner.py`:
- Around line 295-301: The public function run_fbuild_compile_many currently
defines defaults for operational flags (verbose: bool = False, timeout: float =
1800, quiet: bool = False, log_file: IO[str] | None = None) which violates the
project's rule that public Python function parameters must not have default
values; change the signature of run_fbuild_compile_many to remove the default
assignments so each parameter (verbose, timeout, quiet, log_file) is required
(keep existing type annotations), and update all call sites to pass these
arguments explicitly (or propagate callers similarly) to preserve behavior.
- Around line 154-163: The feature-probe subprocess call that invokes
subprocess.run([fbuild_exe, "help", "compile-many"], ...) must handle
KeyboardInterrupt before the broader exception clause; add an explicit "except
KeyboardInterrupt:" block immediately after the try to re-raise the interrupt
(or propagate it) so cancellation is handled identically to other fbuild
runners, then keep the existing "except (FileNotFoundError,
subprocess.SubprocessError, OSError): return False" branch; locate the try
around subprocess.run and insert the KeyboardInterrupt handler there.
- Around line 354-366: The current success branch only fails when zero parse
results are returned; update the post-parse validation in the block that handles
returncode==0 to also compare the number of parsed results against the expected
count (len(sketch_project_dirs)) and fail if they differ. Specifically, after
calling _parse_compile_many_results(output) and computing success from
returncode, detect if success and output.strip() but (not sketch_results or
len(sketch_results) != len(sketch_project_dirs)), then print a descriptive
message and return an FbuildCompileManyResult with success=False, the raw output
and returncode so callers fail fast on partial parse drift.

🪄 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: 7420ef22-2b34-4234-b893-b64e69eafb41

📥 Commits

Reviewing files that changed from the base of the PR and between ec12d7f and 2b46eed.

📒 Files selected for processing (2)

• ci/tests/test_fbuild_compile_many.py
• ci/util/fbuild_runner.py

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

• ci/tests/test_fbuild_compile_many.py

[coderabbitai]

Caution

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

⚠️ Outside diff range comments (1)

ci/compiler/pio.py (1)

57-67: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

The new build_dir parameter broke the existing positional call path.

Adding build_dir before the additional_* parameters shifts the positional call in _internal_init_build_no_lock(): self.additional_defines now binds to build_dir, self.additional_include_dirs binds to additional_defines, and self.additional_libs binds to additional_include_dirs. That means any non-Noneadditional_defines will blow up on build_dir.mkdir(...), and even the None case silently misroutes include/lib overrides.

Suggested fix

 def _init_platformio_build(
board: Board,
verbose: bool,
example: str,
paths: FastLEDPaths,
+ *,
build_dir: Optional[Path] = None,
additional_defines: Optional[list[str]] = None,
additional_include_dirs: Optional[list[str]] = None,
additional_libs: Optional[list[str]] = None,
use_fbuild: bool = False,
) -> InitResult:

 result = _init_platformio_build(
self.board,
self.verbose,
example,
self.paths,
- self.additional_defines,- self.additional_include_dirs,- self.additional_libs,+ additional_defines=self.additional_defines,+ additional_include_dirs=self.additional_include_dirs,+ additional_libs=self.additional_libs,
use_fbuild=self.use_fbuild,
)

🤖 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 `@ci/compiler/pio.py` around lines 57 - 67, The new positional parameter
build_dir in _init_platformio_build shifts downstream positional arguments and
breaks calls (e.g., _internal_init_build_no_lock), causing
self.additional_defines/include_dirs/libs to bind incorrectly; fix by making
build_dir a keyword-only parameter (move it after a * or place it after
additional_* so callers aren’t affected) or update all call sites (notably
_internal_init_build_no_lock) to pass build_dir by name; ensure the signature
change is applied consistently and tests/callers use keywords to prevent
positional misbinding of
additional_defines/additional_include_dirs/additional_libs.

🤖 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 `@ci/compiler/pio.py`:
- Around line 57-67: The new positional parameter build_dir in
_init_platformio_build shifts downstream positional arguments and breaks calls
(e.g., _internal_init_build_no_lock), causing
self.additional_defines/include_dirs/libs to bind incorrectly; fix by making
build_dir a keyword-only parameter (move it after a * or place it after
additional_* so callers aren’t affected) or update all call sites (notably
_internal_init_build_no_lock) to pass build_dir by name; ensure the signature
change is applied consistently and tests/callers use keywords to prevent
positional misbinding of
additional_defines/additional_include_dirs/additional_libs.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5b103a12-6a6f-45fd-9a22-782aeac473b9

📥 Commits

Reviewing files that changed from the base of the PR and between 2b46eed and 4d1efb0.

📒 Files selected for processing (4)

• ci/compiler/pio.py
• ci/tests/test_fbuild_compile_many.py
• ci/util/cpu_count.py
• ci/util/fbuild_runner.py

💤 Files with no reviewable changes (1)

• ci/util/cpu_count.py