fix(library-select): honor Arduino library spec for 1.0 flat layout; release v2.2.6

Closes #267 (Fix 2 — the scanner correctness fix).

## The bug

`fbuild 2.2.5` fails to build any sketch for `teensy41`:

    fatal error: ft2build.h: No such file or directory
       23 | #include <ft2build.h>
    compilation terminated.

The offending file is `framework-arduinoteensy/libraries/ssd1351/fontconvert/fontconvert.c`
— a *host-only* desktop tool that links `-lfreetype`. ssd1351 ships it
as a font preprocessor; it was never intended to be ARM-cross-compiled.

## Root cause

`collect_library_sources` in `framework_library.rs` walked the entire
library directory recursively for 1.0 flat-layout libraries (no `src/`),
violating the Arduino library specification. The spec says:

- **1.5 recursive layout** (has `src/`): scan `src/**` only.
- **1.0 flat layout** (no `src/`): scan root *non-recursively* plus
  the literal `utility/` subdirectory.

Subdirectories like `fontconvert/`, `util/`, `Fonts/`, `examples/`,
and `extras/` must be ignored. The ssd1351 author parked `fontconvert.c`
in `fontconvert/` (not `utility/`) precisely so Arduino IDE / PlatformIO
would skip it. fbuild's recursive walk swept it in.

## The fix

Rewrite `collect_library_sources` to dispatch on layout:
- 1.5 (has `src/`): recurse into `src/` only — already correct.
- 1.0 (no `src/`): `collect_root_level_sources` (non-recursive) +
  recurse into `utility/` only.

This matches `arduino-cli` exactly and protects fbuild from any
well-formed library shipping companion tooling in a non-`utility/`
subdirectory.

## Tests

- `collect_library_sources_flat_layout_arduino_spec` — fixture mimics
  ssd1351 (root .cpp + utility/ + fontconvert/ + util/ + Fonts/ +
  examples/). Asserts only root + utility/ are returned; fontconvert/
  (with the `#include <ft2build.h>` that breaks the build), util/,
  Fonts/, and examples/ are dropped.
- `collect_library_sources_recursive_layout_arduino_spec` — fixture
  with `src/SPI.cpp`, `src/sub/bar.cpp`, root-level `baz.cpp`,
  and `examples/`. Asserts only `src/**` is returned; root `baz.cpp`
  and examples/ are dropped.

Full workspace cargo check / clippy / fmt / test all green.

## Release v2.2.6

Patch release rolling up the #267 scanner-correctness fix. Both teensy41
regressions from earlier today (#261 LTO tmpdir, #263 bundled FastLED
dup) carry over from v2.2.5.

Cargo.toml + pyproject.toml bumped to 2.2.6.

## Deferred (out of scope for this PR)

Fix 1 from #267 — investigate why ssd1351 is reaching the compile set
at all when Blink doesn't `#include <ssd1351.h>` — is a separate
LDF-leak investigation. With Fix 2 in place, even if ssd1351 IS
selected, only `ssd1351.cpp` at the root would be compiled (which
should cross-compile fine for ARM). The user-reported build failure
is resolved.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: zackees

Cargo.lock

@@ -18,7 +18,7 @@ members = [
 ]
 
 [workspace.package]
-version = "2.2.5"
+version = "2.2.6"
 edition = "2021"
 rust-version = "1.94.1"
 license = "MIT OR Apache-2.0"

Cargo.toml

@@ -77,26 +77,61 @@ pub fn library_include_dirs(lib_dir: &Path) -> Vec<PathBuf> {
     dirs
 }
 
-/// Collect every buildable source file from a library.
+/// Collect every buildable source file from a library, honoring the
+/// [Arduino library specification](https://arduino.github.io/arduino-cli/1.5/library-specification/).
 ///
-/// Skips `examples/`, `tests/`, and `extras/` subtrees to keep user-facing
-/// demos out of the build.
+/// - **1.5 recursive layout** (library has `src/`): scan `src/**` recursively.
+///   The library root is *not* scanned. This is the modern layout used by
+///   well-organized libraries.
+/// - **1.0 flat layout** (no `src/`): scan the library root *non-recursively*
+///   plus the literal `utility/` subdirectory recursively. Every other
+///   subdirectory (`fontconvert/`, `util/`, `Fonts/`, `examples/`, `extras/`,
+///   etc.) is ignored.
+///
+/// The flat-layout rule is what protects fbuild from compiling host-only
+/// tools that ship inside libraries — e.g. `ssd1351/fontconvert/fontconvert.c`
+/// (a libfreetype-linked desktop utility) under
+/// `framework-arduinoteensy/libraries/ssd1351/`. Arduino IDE and PlatformIO
+/// skip those because the spec says to scan only root + `utility/`; fbuild
+/// previously walked the full tree and tried to ARM-cross-compile the host
+/// tool, which fails at `#include <ft2build.h>`. See FastLED/fbuild#267.
 pub fn collect_library_sources(lib_dir: &Path) -> Vec<PathBuf> {
-    let search_dir = {
-        let src = lib_dir.join("src");
-        if src.is_dir() {
-            src
-        } else {
-            lib_dir.to_path_buf()
-        }
-    };
-
     let mut sources = Vec::new();
-    collect_library_sources_inner(&search_dir, &mut sources);
+    let src = lib_dir.join("src");
+    if src.is_dir() {
+        // 1.5 layout — recursive scan of src/ only.
+        collect_library_sources_inner(&src, &mut sources);
+    } else {
+        // 1.0 flat layout per Arduino spec:
+        //   * root level (non-recursive)
+        //   * utility/ (recursive, literal lowercase per the spec)
+        collect_root_level_sources(lib_dir, &mut sources);
+        let utility = lib_dir.join("utility");
+        if utility.is_dir() {
+            collect_library_sources_inner(&utility, &mut sources);
+        }
+    }
     sources.sort();
     sources
 }
 
+/// Non-recursive scan of a directory for buildable source files.
+/// Used only for the root of a 1.0 flat-layout library.
+fn collect_root_level_sources(dir: &Path, out: &mut Vec<PathBuf>) {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.is_file() && is_buildable_source(&path) {
+            out.push(path);
+        }
+    }
+}
+
+/// Recursive scan used inside `src/` (1.5 layout) and `utility/` (1.0 layout).
+/// Still skips `examples/`, `tests/`, and `extras/` defensively in case a
+/// library nests them under `src/` or `utility/`.
 fn collect_library_sources_inner(dir: &Path, out: &mut Vec<PathBuf>) {
     let Ok(entries) = std::fs::read_dir(dir) else {
         return;
@@ -117,19 +152,21 @@ fn collect_library_sources_inner(dir: &Path, out: &mut Vec<PathBuf>) {
                 continue;
             }
             collect_library_sources_inner(&path, out);
-        } else {
-            let ext = path
-                .extension()
-                .unwrap_or_default()
-                .to_string_lossy()
-                .to_lowercase();
-            if matches!(ext.as_str(), "c" | "cpp" | "cc" | "cxx" | "s") {
-                out.push(path);
-            }
+        } else if is_buildable_source(&path) {
+            out.push(path);
         }
     }
 }
 
+fn is_buildable_source(path: &Path) -> bool {
+    let ext = path
+        .extension()
+        .unwrap_or_default()
+        .to_string_lossy()
+        .to_lowercase();
+    matches!(ext.as_str(), "c" | "cpp" | "cc" | "cxx" | "s")
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -164,6 +201,102 @@ mod tests {
         assert_eq!(sources, vec![tmp.path().join("OctoWS2811.cpp")]);
     }
 
+    /// Regression for FastLED/fbuild#267 — 1.0 flat-layout libraries
+    /// (no `src/`) must scan only the library root non-recursively plus
+    /// the literal `utility/` subdirectory. Subdirectories like
+    /// `fontconvert/`, `util/`, `Fonts/`, and `examples/` are ignored
+    /// per the Arduino library spec.
+    ///
+    /// The specific failure this guards: `ssd1351/fontconvert/fontconvert.c`
+    /// is a desktop host tool linking `-lfreetype`; ARM-cross-compiling it
+    /// fails on `#include <ft2build.h>`. Arduino IDE / PlatformIO skip
+    /// `fontconvert/` because the spec says scan root + `utility/` only.
+    #[test]
+    fn collect_library_sources_flat_layout_arduino_spec() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let lib = tmp.path().join("ssd1351");
+        std::fs::create_dir_all(&lib).unwrap();
+
+        // Root level — compiled.
+        std::fs::write(lib.join("ssd1351.cpp"), "").unwrap();
+        std::fs::write(lib.join("ssd1351.h"), "").unwrap(); // header, not source
+
+        // `utility/` — compiled (recursive).
+        std::fs::create_dir_all(lib.join("utility")).unwrap();
+        std::fs::write(lib.join("utility").join("helpers.cpp"), "").unwrap();
+        std::fs::create_dir_all(lib.join("utility").join("nested")).unwrap();
+        std::fs::write(lib.join("utility").join("nested").join("deep.cpp"), "").unwrap();
+
+        // Non-standard subdirs — ALL must be skipped.
+        std::fs::create_dir_all(lib.join("fontconvert")).unwrap();
+        std::fs::write(
+            lib.join("fontconvert").join("fontconvert.c"),
+            "#include <ft2build.h>\n", // would fail to ARM-cross-compile
+        )
+        .unwrap();
+        std::fs::create_dir_all(lib.join("util")).unwrap();
+        std::fs::write(lib.join("util").join("misc.cpp"), "").unwrap();
+        std::fs::create_dir_all(lib.join("Fonts")).unwrap();
+        std::fs::write(lib.join("Fonts").join("Roboto.c"), "").unwrap();
+        std::fs::create_dir_all(lib.join("examples").join("Demo")).unwrap();
+        std::fs::write(lib.join("examples").join("Demo").join("Demo.ino"), "").unwrap();
+
+        let sources = collect_library_sources(&lib);
+
+        let mut expected = vec![
+            lib.join("ssd1351.cpp"),
+            lib.join("utility").join("helpers.cpp"),
+            lib.join("utility").join("nested").join("deep.cpp"),
+        ];
+        expected.sort();
+
+        assert_eq!(
+            sources, expected,
+            "1.0 flat layout must yield ONLY root non-recursive + utility/ \
+             recursive per Arduino spec — see #267. \
+             Got {sources:?}, expected {expected:?}"
+        );
+    }
+
+    /// Regression for FastLED/fbuild#267 — 1.5 recursive layout (library
+    /// has `src/`) must scan only `src/**`. Any root-level source files
+    /// are intentionally ignored per the Arduino library spec; the
+    /// library's `library.properties` declares it as 1.5 by virtue of
+    /// shipping `src/`.
+    #[test]
+    fn collect_library_sources_recursive_layout_arduino_spec() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let lib = tmp.path().join("SPI");
+        std::fs::create_dir_all(lib.join("src")).unwrap();
+        std::fs::create_dir_all(lib.join("src").join("sub")).unwrap();
+
+        // src/ — recursive scan.
+        std::fs::write(lib.join("src").join("SPI.cpp"), "").unwrap();
+        std::fs::write(lib.join("src").join("sub").join("bar.cpp"), "").unwrap();
+
+        // Root-level — must NOT be compiled (1.5 layout ignores root).
+        std::fs::write(lib.join("baz.cpp"), "").unwrap();
+
+        // examples/, tests/ — always skipped.
+        std::fs::create_dir_all(lib.join("examples")).unwrap();
+        std::fs::write(lib.join("examples").join("Demo.cpp"), "").unwrap();
+
+        let sources = collect_library_sources(&lib);
+
+        let mut expected = vec![
+            lib.join("src").join("SPI.cpp"),
+            lib.join("src").join("sub").join("bar.cpp"),
+        ];
+        expected.sort();
+
+        assert_eq!(
+            sources, expected,
+            "1.5 recursive layout must yield ONLY src/** per Arduino spec — \
+             root-level `baz.cpp` must be ignored — see #267. \
+             Got {sources:?}, expected {expected:?}"
+        );
+    }
+
     #[test]
     fn discover_framework_libraries_walks_each_subdirectory() {
         let tmp = tempfile::TempDir::new().unwrap();

crates/fbuild-packages/src/library/framework_library.rs

@@ -1,6 +1,6 @@
 [project]
 name = "fbuild"
-version = "2.2.5"
+version = "2.2.6"
 description = "PlatformIO-compatible embedded build tool (Rust implementation)"
 readme = "README.md"
 requires-python = ">=3.10"