@typecad/framework-zephyr 1.0.0-alpha.18 → 1.0.0-alpha.19

package/src/toolchain/index.ts

@@ -26,6 +26,7 @@ import type { ToolchainOptions, CompileResult, UploadResult } from '@typecad/cut
 import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
 import { scaffoldZephyrProject, writeIfChanged, appendLibraryOverlayFragments } from './scaffold.js';
 import { parseZephyrDts, asBuiltJson } from '../as-built.js';
+import { stampBuildSbom } from '../sbom.js';
 import { westSpawn, buildEnv } from './west-spawn.js';
 import { discoverWest } from './west-discover.js';
 import { writeDebugConfig, resolveDebugLocations, debugArtifactsNeedRewrite, DEBUG_SERVER_PORT, DEBUG_SERVER_TCL_PORT } from './debug-config.js';
@@ -39,7 +40,7 @@ import { resolveChipFromBoard } from '../chips/resolve.js';
 import type { ZephyrChipDescriptor } from '../chips/types.js';
 import { pwmDtAliasToken } from '../lowering/pwm.js';
 import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './compat.js';
-import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from '../display/profiles.js';
+import { DEFAULT_ZEPHYR_DISPLAY_PROFILE, profileFromEmittedSource } from '../display/profiles.js';
 
 /**
  * Resolve the chip for a build the same way the strategy does at emit time —
@@ -194,6 +195,35 @@ function scanPwmUsedPins(src: string, chip: ZephyrChipDescriptor): number[] {  c
   return pins;
 }
 
+export function scanMatrix(src: string): { rows: number[]; cols: number[] } | undefined {
+  // The on_key lowering's comment marker carries the construction lists.
+  const m = src.match(/cuttlefish-matrix: rows=([\d,]*) cols=([\d,]*)/);
+  if (!m) return undefined;
+  const rows = m[1] ? m[1].split(',').filter(Boolean).map(Number) : [];
+  const cols = m[2] ? m[2].split(',').filter(Boolean).map(Number) : [];
+  if (rows.length === 0 || cols.length === 0) return undefined;
+  return { rows, cols };
+}
+
+export function scanHid(src: string): 'keyboard' | 'mouse' | undefined {
+  // The shim's report buffer names are the presence signal.
+  if (src.includes('__tc_mouse_report')) return 'mouse';
+  if (src.includes('__tc_kb_report')) return 'keyboard';
+  return undefined;
+}
+
+export function scanStrips(src: string): Array<{ index: number; count: number }> {
+  // The shim's buffer declaration is the presence signal:
+  // `static struct led_rgb __tc_strip<N>_buf[<COUNT>];`
+  const out = new Map<number, number>();
+  for (const m of src.matchAll(/__tc_strip(\d+)_buf\[(\d+)\]/g)) {
+    const idx = Number(m[1]);
+    const count = Number(m[2]);
+    out.set(idx, Math.max(out.get(idx) ?? 0, count));
+  }
+  return [...out.entries()].map(([index, count]) => ({ index, count }));
+}
+
 /**
  * Bus controller indexes the emitted sources actually reference — the shim
  * declares one `__tc_<bus><N>_dev` state block per used instance (gated by
@@ -226,8 +256,10 @@ function scanUsedBusInstances(
  * compatible containing '_i2c<N>_' still resolves to the longest part match.
  */
 export interface ScannedSensorPart {
-  part: string; busIndex: number; port: number; busKind: 'i2c' | 'spi';
+  part: string; busIndex: number; port: number; busKind: 'i2c' | 'spi' | 'w1';
   spiHz: number; spiMode: number; alertPin: number;
+  /** 1-Wire parts: the converter resolution in bits. */
+  resolution: number;
 }
 
 export interface ScannedSpiTarget {
@@ -248,13 +280,22 @@ export function scanSpiTargets(src: string): ScannedSpiTarget[] {
 
 export function scanSensorParts(src: string): ScannedSensorPart[] {
   const out = new Map<string, ScannedSensorPart>();
+  // 1-Wire sensors: the stem carries the data pin (w1 master's GPIO).
+  for (const m of src.matchAll(/__tc_sensor_([a-z0-9_]+)_w1_p(\d+)_dev\b/g)) {
+    out.set(`${m[1]}|w1|${m[2]}`, { part: m[1], busIndex: 0, port: parseInt(m[2], 10), busKind: 'w1', spiHz: 0, spiMode: 0, alertPin: -1, resolution: 12 });
+  }
   for (const m of src.matchAll(/__tc_sensor_([a-z0-9_]+)_(i2c|spi)(\d+)_(0x[0-9a-f]+|cs[0-9]+)_dev\b/g)) {
     const port = m[4].startsWith('0x') ? parseInt(m[4], 16) : parseInt(m[4].slice(2), 10);
-    const ref: ScannedSensorPart = { part: m[1], busIndex: parseInt(m[3], 10), port, busKind: m[2] as 'i2c' | 'spi', spiHz: 0, spiMode: 0, alertPin: -1 };
+    const ref: ScannedSensorPart = { part: m[1], busIndex: parseInt(m[3], 10), port, busKind: m[2] as 'i2c' | 'spi', spiHz: 0, spiMode: 0, alertPin: -1, resolution: 12 };
     out.set(`${ref.part}|${ref.busKind}${ref.busIndex}|${ref.port}`, ref);
   }
   // Construction facts ride the state block's config comment — merge by
   // nodelabel so the scanner stays the single source for the overlay.
+  for (const m of src.matchAll(/tc-sensor-cfg: tc_([a-z0-9_]+)_w1_p(\d+) res=(\d+)/g)) {
+    const key = `${m[1]}|w1|${m[2]}`;
+    const existing = out.get(key);
+    if (existing) existing.resolution = parseInt(m[3], 10);
+  }
   for (const m of src.matchAll(/tc-sensor-cfg: tc_([a-z0-9_]+)_(i2c|spi)(\d+)_(0x[0-9a-f]+|cs[0-9]+) hz=(\d+) mode=(\d+) alert=(-?\d+)/g)) {
     const port = m[4].startsWith('0x') ? parseInt(m[4], 16) : parseInt(m[4].slice(2), 10);
     const key = `${m[1]}|${m[2]}${m[3]}|${port}`;
@@ -765,11 +806,13 @@ export const Toolchain = {
     const usesDisplay = uses('display_write') || uses('display_init')
       || uses('display_fill_rect') || uses('__tc_display_dev')
       || uses('CuttlefishDisplayTarget');
-    // Both registered Zephyr display profiles use dtLabel 'display0', so the
-    // default profile's overlay block (&display0 { status="okay" }) is correct
-    // for either driver. Thread a non-default profile here only if a future
-    // board carries a display node under a different nodelabel.
-    const displayProfile = usesDisplay ? DEFAULT_ZEPHYR_DISPLAY_PROFILE : undefined;
+    // Recover the exact display profile from the marker the adapter stamped
+    // into the emitted source (the registry is the single source of truth).
+    // Fall back to the default profile only when a display is used but no
+    // marker matched (e.g. hand-written source).
+    const displayProfile = usesDisplay
+      ? (profileFromEmittedSource(src) ?? DEFAULT_ZEPHYR_DISPLAY_PROFILE)
+      : undefined;
     // Touch controller kind comes from which DT nodelabel the emitted adapter
     // references (FT6336U on I2C, XPT2046 on the display's SPI bus).
     const usesTouch = uses('ft6336u') || uses('touch_');
@@ -788,12 +831,29 @@ export const Toolchain = {
       spiTargets: spiTargetParts,
       usesSpi: uses('spi_') || uses('__tc_spi') || spiTargetParts.length > 0,
       usesUart: uses('__tc_uart'),
-      usesUsb: uses('__tc_usb'),
+      usesUsb: uses('__tc_usb0'),
       usesPwm: uses('pwm_'),
       usesAdc: uses('adc_'),
       adcReadPins: scanAdcReadPins(src, chip),
       dacWritePins: scanDacWritePins(src),
       pwmUsedPins: scanPwmUsedPins(src, chip),
+      usesStrip: uses('led_strip'),
+      strips: scanStrips(src),
+      usesClock: uses('__tc_rtc'),
+      usesCan: uses('can_'),
+      canLoopback: uses('CAN_MODE_LOOPBACK'),
+      usesI2s: uses('i2s_'),
+      clockShimCounter: chip.hwtimer && chip.hwtimer.controllers.length > 0
+        ? {
+            label: chip.hwtimer.controllers[0].nodeLabel,
+            ...(chip.hwtimer.controllers[0].counterParent ? { parent: chip.hwtimer.controllers[0].counterParent } : {}),
+          }
+        : undefined,
+      usesHid: uses('__tc_hid_'),
+      hidProtocol: scanHid(src),
+      usesMatrix: uses('__tc_matrix'),
+      matrix: scanMatrix(src),
+      usesPower: uses('sys_poweroff'),
       i2cUsedInstances: scanUsedBusInstances(src, chip.i2c?.controllers, 'i2c'),
       spiUsedInstances: scanUsedBusInstances(src, chip.spi?.controllers, 'spi'),
       uartUsedInstances: scanUsedBusInstances(src, chip.uart?.controllers, 'uart'),
@@ -864,7 +924,8 @@ export const Toolchain = {
     const isGdbDebug = o.debug === true && debugMode === 'gdb';
     const zc = o.zephyrConfig as Record<string, unknown> | undefined;
     const userKconfig = zc?.kconfig as Record<string, string> | undefined;
-    const configChanged = scaffoldZephyrProject(projectRoot, isGdbDebug, userKconfig, o.psram);
+    const traceCfg = zc?.trace as { enabled?: boolean; intervalMs?: number } | undefined;
+    const configChanged = scaffoldZephyrProject(projectRoot, isGdbDebug, userKconfig, o.psram, traceCfg);
 
     // Regenerate the DT overlay for the ACTUAL target board. prepare() writes
     // it for the default board (the real target is unknown until compile), so
@@ -900,29 +961,24 @@ export const Toolchain = {
       const usesDisplay = uses('display_write') || uses('display_init')
         || uses('display_fill_rect') || uses('__tc_display_dev')
         || uses('CuttlefishDisplayTarget');
-      // Derive the display dimensions from the emitted adapter code
-      // (display_width/height return the profile's w/h). This ensures the DT
-      // overlay's width/height match the panel the adapter targets, not the
-      // default profile — critical for drivers like ST7796S that initialize
-      // the panel geometry from the DT node.
-      let displayProfile = usesDisplay ? DEFAULT_ZEPHYR_DISPLAY_PROFILE : undefined;
-      if (usesDisplay) {
-        const wMatch = src.match(/display_width\(\)\s*\{\s*return\s+(\d+)\s*;\s*\}/);
-        const hMatch = src.match(/display_height\(\)\s*\{\s*return\s+(\d+)\s*;\s*\}/);
-        if (wMatch && hMatch) {
-          displayProfile = {
-            ...DEFAULT_ZEPHYR_DISPLAY_PROFILE,
-            width: parseInt(wMatch[1], 10),
-            height: parseInt(hMatch[1], 10),
-          };
-        }
-      }
+      // Recover the exact display profile from the marker the adapter emitted
+      // (`typecad-display-profile: <driver>`), so the DT overlay's compatible
+      // string, geometry, and rotation match the panel the adapter targets.
+      // The width/height regex this replaces could produce franken-profiles —
+      // e.g. an ST7796S build (480x320) on the default ILI9341 profile's
+      // controller/compatible, which emitted an ilitek,ili9341 DT node for a
+      // panel the ST7796S adapter drives.
+      const displayProfile = usesDisplay
+        ? (profileFromEmittedSource(src) ?? DEFAULT_ZEPHYR_DISPLAY_PROFILE)
+        : undefined;
       // Extract display pin wiring (cs/dc/rst/spiFrequency/spiPins) from the
       // config display section so the DT overlay wires the MIPI DBI bridge to
       // the correct GPIOs + SPI bus pins.
       const dispCfg = o.display as Record<string, unknown> | undefined;
       const spiPins = (dispCfg?.spiPins ?? undefined) as
         { sck?: unknown; mosi?: unknown; miso?: unknown } | undefined;
+      const i2cPins = (dispCfg?.i2cPins ?? undefined) as
+        { sda?: unknown; scl?: unknown } | undefined;
       const wiring: DisplayWiring | undefined = dispCfg
         ? {
             cs: typeof dispCfg.cs === 'number' ? dispCfg.cs : undefined,
@@ -932,8 +988,12 @@ export const Toolchain = {
             sck: typeof spiPins?.sck === 'number' ? spiPins.sck : undefined,
             mosi: typeof spiPins?.mosi === 'number' ? spiPins.mosi : undefined,
             miso: typeof spiPins?.miso === 'number' ? spiPins.miso : undefined,
+            sda: typeof i2cPins?.sda === 'number' ? i2cPins.sda : undefined,
+            scl: typeof i2cPins?.scl === 'number' ? i2cPins.scl : undefined,
             backlightPin: typeof dispCfg.backlightPin === 'number' ? dispCfg.backlightPin : undefined,
             tearingEffectPin: typeof dispCfg.tearingEffectPin === 'number' ? dispCfg.tearingEffectPin : undefined,
+            busyPin: typeof (dispCfg as { busyPin?: number }).busyPin === 'number' ? (dispCfg as { busyPin?: number }).busyPin : undefined,
+            address: typeof dispCfg.address === 'number' ? dispCfg.address : undefined,
           }
         : undefined;
       // Extract touch pin wiring from the config display.touch section so the
@@ -986,13 +1046,30 @@ export const Toolchain = {
         spiTargets: spiTargetParts,
         usesSpi: uses('spi_') || uses('__tc_spi') || spiTargetParts.length > 0,
         usesUart: uses('__tc_uart'),
-        usesUsb: uses('__tc_usb'),
+        usesUsb: uses('__tc_usb0'),
         usesPwm: uses('pwm_'),
         usesAdc: uses('adc_'),
         adcReadPins: scanAdcReadPins(src, chip),
         usesDac: uses('dac_') || uses('__tc_dac'),
         dacWritePins: scanDacWritePins(src),
         pwmUsedPins: scanPwmUsedPins(src, chip),
+      usesStrip: uses('led_strip'),
+      strips: scanStrips(src),
+      usesHid: uses('__tc_hid_'),
+      hidProtocol: scanHid(src),
+      usesMatrix: uses('__tc_matrix'),
+      matrix: scanMatrix(src),
+      usesPower: uses('sys_poweroff'),
+      usesClock: uses('__tc_rtc'),
+      usesCan: uses('can_'),
+      canLoopback: uses('CAN_MODE_LOOPBACK'),
+      usesI2s: uses('i2s_'),
+      clockShimCounter: chip.hwtimer && chip.hwtimer.controllers.length > 0
+        ? {
+            label: chip.hwtimer.controllers[0].nodeLabel,
+            ...(chip.hwtimer.controllers[0].counterParent ? { parent: chip.hwtimer.controllers[0].counterParent } : {}),
+          }
+        : undefined,
         i2cUsedInstances: scanUsedBusInstances(src, chip.i2c?.controllers, 'i2c'),
         spiUsedInstances: scanUsedBusInstances(src, chip.spi?.controllers, 'spi'),
         uartUsedInstances: scanUsedBusInstances(src, chip.uart?.controllers, 'uart'),
@@ -1175,6 +1252,18 @@ export const Toolchain = {
       } catch { /* best-effort snapshot — nothing to harvest or unreadable */ }
     }
 
+    // SBOM stamp: after a successful build, record what the binary is made of
+    // — kernel + linked west modules with commit SHAs + the hashed firmware
+    // artifact (CycloneDX 1.6, next to zephyr.bin) — so `typecad-hal sbom
+    // --check` can gate releases on the record still matching the build
+    // (EU CRA essential-requirements support). Best-effort: a west-list or
+    // hashing failure never blocks the build.
+    if (result.status === 0) {
+      try {
+        stampBuildSbom({ buildDir, board, projectRoot });
+      } catch { /* best-effort SBOM stamp */ }
+    }
+
     return {
       success: result.status === 0,
       output: header + output,

package/src/toolchain/scaffold.ts

@@ -10,7 +10,9 @@
 import { writeFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveKconfigFragments, type KconfigUsage } from '../dt-config/kconfig.js';
-import { scanSensorParts } from './index.js';
+import { scanSensorParts, scanStrips, scanHid, scanMatrix } from './index.js';
+import { profileFromEmittedSource, transportFor, panelControllerFor } from '../display/profiles.js';
+import { readDisplayBinding } from '../display/bindings.js';
 import { readCuttlefishLibrarySidecar } from '@typecad/cuttlefish/library-packages';
 import { SENSOR_PART_INFO } from '@typecad/hal';
 
@@ -96,7 +98,7 @@ export function appendLibraryOverlayFragments(overlay: string, projectRoot: stri
  *
  * Idempotent. Mirrors scaffoldEspIdfProject's writeIfChanged discipline.
  */
-export function scaffoldZephyrProject(projectRoot: string, debug = false, userKconfig?: Record<string, string>, psram?: 'opi' | 'quad'): boolean {
+export function scaffoldZephyrProject(projectRoot: string, debug = false, userKconfig?: Record<string, string>, psram?: 'opi' | 'quad', trace?: { enabled?: boolean; intervalMs?: number }): boolean {
   const srcDir = join(projectRoot, 'src');
   if (!existsSync(srcDir)) mkdirSync(srcDir, { recursive: true });
 
@@ -122,6 +124,22 @@ export function scaffoldZephyrProject(projectRoot: string, debug = false, userKc
   const usage: KconfigUsage = {
     usesAdc: uses('adc_'),
     usesPwm: uses('pwm_'),
+    usesStrip: uses('led_strip'),
+    strips: scanStrips(src),
+    // Sensor parts drive CONFIG_W1 (1-Wire masters) and the exception
+    // lines; the same scan the exception block below re-runs.
+    sensorParts: scanSensorParts(src),
+    usesHid: uses('__tc_hid_'),
+    hidProtocol: scanHid(src),
+    usesMatrix: uses('__tc_matrix'),
+    matrix: scanMatrix(src),
+    usesPower: uses('sys_poweroff'),
+    usesClock: uses('__tc_rtc'),
+    usesCan: uses('can_'),
+    canLoopback: uses('CAN_MODE_LOOPBACK'),
+    usesI2s: uses('i2s_'),
+    // No chip facts at scaffold time — the prepare overlay omits the shim;
+    // the chip-aware build path synthesizes it.
     usesDac: uses('dac_') || uses('__tc_dac'),
     usesFS: uses('__tc_fs'),
     usesHwtimer: uses('counter_') || uses('__tc_hw'),
@@ -130,6 +148,9 @@ export function scaffoldZephyrProject(projectRoot: string, debug = false, userKc
     // call yet), but the shim still declared DEVICE_DT_GET(DT_NODELABEL(...))
     // so the overlay must enable the node or the device symbol is missing.
     usesI2c: uses('i2c_') || uses('__tc_i2c'),
+    // I2C target mode: every i2c.resp_* lowering calls i2c_target_register
+    // (and the shim's state carries the i2c_target_* vocabulary).
+    usesI2cTarget: uses('i2c_target_'),
     // DT-bound sensor parts: the __tc_sensor_* state references and the
     // sensor_sample_fetch/sensor_channel_get calls both carry the token.
     usesSensor: uses('sensor_') || uses('__tc_sensor'),
@@ -138,12 +159,28 @@ export function scaffoldZephyrProject(projectRoot: string, debug = false, userKc
     usesUart: uses('uart_') || uses('__tc_uart'),
     // USB CDC serial: every usb.* lowering calls into the __tc_usb<N>_* shim
     // (device + init helper emitted under usesUsb).
-    usesUsb: uses('__tc_usb'),
+    usesUsb: uses('__tc_usb0'),
     // STM32F4 DBGMCU keep-SWD-alive init present (emitted for stm32f4 socs).
     usesStm32DebugSleep: uses('__tc_stm32_dbgmcu'),
     usesWdt: uses('wdt_'),
     usesBle: uses('bt_') || uses('bt_gatt') || uses('bt_le_'),
     usesDisplay: uses('display_write') || uses('display_init') || uses('display_fill_rect') || uses('__tc_display_dev') || uses('CuttlefishDisplayTarget'),
+    // Display transport + controller: recovered from the profile marker the
+    // display adapters stamp into the emitted source (the profile registry is
+    // the single source of truth — no geometry re-derivation here).
+    ...((): Pick<KconfigUsage, 'displayTransport' | 'displayController' | 'displayBus' | 'displayKconfigExtra'> => {
+      const profile = profileFromEmittedSource(src);
+      if (!profile) return {};
+      // Registry profiles name a DT compatible via dtCompatible (the driver
+      // id itself isn't one); drop-in profiles use the driver string directly.
+      const bus = readDisplayBinding(profile.dtCompatible ?? profile.driver)?.busFamily;
+      if (bus === 'i2c') return { displayBus: 'i2c' };
+      // Board-provided panels (native_sim's sdl_dc) carry their own fragments
+      // and no bus at all.
+      if (profile.boardProvidesDisplay) return { displayKconfigExtra: profile.kconfig };
+      if (transportFor(profile) !== 'zephyr-display') return {};
+      return { displayTransport: 'zephyr-display', displayController: panelControllerFor(profile) };
+    })(),
     usesTouch: uses('ft6336u') || uses('touch_'),
     // (The power HAL is removed; its former pm_/k_sleep token scan is gone —
     // nothing here must match tx_power_dbm's `power` substring.)
@@ -267,6 +304,28 @@ export function scaffoldZephyrProject(projectRoot: string, debug = false, userKc
       }
     }
   }
+  // ── Trace heartbeat Kconfig ────────────────────────────────────────────────
+  // zephyr.trace.enabled in typecad-hal.config.ts turns on the [TR: sampler
+  // (emitted by the strategy at transpile time from the same config record).
+  // The symbol set is exactly what the sampler calls: runtime stats
+  // (k_thread_runtime_stats_*), the monitor list (k_thread_foreach —
+  // kernel/thread_monitor.c only links under THREAD_MONITOR), thread names
+  // (k_thread_name_get/set), and stack inspection (0xAA fill +
+  // stack_info.size). User zephyr.kconfig overrides still win.
+  if (trace?.enabled === true) {
+    const traceSymbols: Array<[string, string]> = [
+      ['CONFIG_THREAD_RUNTIME_STATS', 'y'],
+      ['CONFIG_THREAD_MONITOR', 'y'],
+      ['CONFIG_THREAD_NAME', 'y'],
+      ['CONFIG_INIT_STACKS', 'y'],
+      ['CONFIG_THREAD_STACK_INFO', 'y'],
+    ];
+    prjConf.push('', '# Trace heartbeat (typecad-hal.config.ts → zephyr.trace).');
+    for (const [sym, val] of traceSymbols) {
+      if (userKconfig && userKconfig.hasOwnProperty(sym)) continue;
+      prjConf.push(`${sym}=${val}`);
+    }
+  }
   // Per-part Kconfig exceptions: catalog parts whose driver is NOT default-y
   // on its DT node carry extra lines here (empty today — every in-tree sensor
   // driver lights up from the node; the path exists so the first exception

package/src/west-inventory.ts

@@ -0,0 +1,102 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-zephyr — shared west workspace ground truth
+//
+// The as-built inventory both `typecad-hal licenses` and `typecad-hal sbom`
+// report from: which west manifest modules the last build ACTUALLY compiled
+// (linked-module filtering via the build's compile_commands.json), plus the
+// build-directory discovery that locates it. A west manifest carries every
+// vendor HAL/library; almost none are linked by a single project — both the
+// license table and the SBOM scope to the linked set by default, so they stay
+// honest about what is actually inside the firmware.
+//
+// Moved out of licenses.ts when the sbom command grew a second consumer; the
+// behavior (case-insensitive, separator-agnostic path matching; degrade to
+// "no filtering" on unparseable build data) is unchanged.
+// ---------------------------------------------------------------------------
+
+import * as path from 'node:path';
+import type { ReadDir, ReadFile } from '@typecad/cuttlefish/api/shared';
+
+/** Normalize a path for case-insensitive, separator-agnostic comparison. */
+export function norm(p: string): string {
+  return p.split('\\').join('/').toLowerCase();
+}
+
+/**
+ * Filter the west manifest to the modules whose sources were compiled in the
+ * last build. A module is "linked" iff some compiled translation unit lives
+ * under its abspath. If the build data is unparseable, no filtering is applied
+ * (degrade to listing all modules rather than reporting nothing).
+ */
+export function filterLinkedModules(
+  ccText: string,
+  modules: { name: string; abspath: string }[],
+): { name: string; abspath: string }[] {
+  let arr: unknown;
+  try {
+    arr = JSON.parse(ccText);
+  } catch {
+    return modules;
+  }
+  if (!Array.isArray(arr)) return modules;
+  // One normalized blob of every compiled source path; membership is then a
+  // substring check per module (O(modules) after an O(TUs) join).
+  const blob = arr
+    .map((e) => norm(typeof (e as { file?: unknown })?.file === 'string' ? (e as { file: string }).file : ''))
+    .join('\n');
+  return modules.filter((m) => blob.includes(norm(m.abspath) + '/'));
+}
+
+/**
+ * Find the build's compile_commands.json path under `cwd`. Cuttlefish's Zephyr
+ * project root is the transpile output dir (e.g. `<cwd>/src/out`), so the
+ * build dir is `<root>/build` — not necessarily `<cwd>/build`. Check the
+ * common layouts, then fall back to a bounded search (skipping
+ * node_modules/.git/dist and dot-directories). Returns the PATH (the caller
+ * decides whether to read it); undefined when no build exists.
+ */
+export function findCompileCommandsPath(
+  readFile: ReadFile,
+  readdir: ReadDir,
+  cwd = process.cwd(),
+): string | undefined {
+  const direct = [
+    path.join(cwd, 'build', 'compile_commands.json'),
+    path.join(cwd, 'out', 'build', 'compile_commands.json'),
+    path.join(cwd, 'src', 'out', 'build', 'compile_commands.json'),
+  ];
+  for (const c of direct) {
+    if (readFile(c)) return c;
+  }
+  // Bounded recursive search for a build/compile_commands.json.
+  const isCc = (p: string) => {
+    const n = norm(p);
+    return n.endsWith('/build/compile_commands.json') || n.endsWith('\\build\\compile_commands.json');
+  };
+  let found: string | undefined;
+  const seen = new Set<string>();
+  const walk = (dir: string, depth: number): void => {
+    if (found || depth > 4 || seen.has(dir)) return;
+    seen.add(dir);
+    let entries: string[];
+    try {
+      entries = readdir(dir);
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e);
+      if (e === 'compile_commands.json' && isCc(full)) {
+        found = full;
+        return;
+      }
+    }
+    for (const e of entries) {
+      if (found) return;
+      if (e === 'node_modules' || e === '.git' || e === 'dist' || e.startsWith('.')) continue;
+      walk(path.join(dir, e), depth + 1);
+    }
+  };
+  walk(cwd, 0);
+  return found;
+}