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

package/dist/toolchain/index.js

@@ -24,6 +24,7 @@ import { readdirSync, readFileSync, mkdirSync, rmSync, existsSync, writeFileSync
 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';
@@ -36,7 +37,7 @@ import { NO_BOARD_CHIP } from '../chips/index.js';
 import { resolveChipFromBoard } from '../chips/resolve.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 —
  * from the board constants the transpile persisted next to the emitted
@@ -196,6 +197,36 @@ function scanPwmUsedPins(src, chip) {
     }
     return pins;
 }
+export function scanMatrix(src) {
+    // 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) {
+    // 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) {
+    // The shim's buffer declaration is the presence signal:
+    // `static struct led_rgb __tc_strip<N>_buf[<COUNT>];`
+    const out = new Map();
+    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
@@ -230,13 +261,23 @@ export function scanSpiTargets(src) {
 }
 export function scanSensorParts(src) {
     const out = new Map();
+    // 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 = { part: m[1], busIndex: parseInt(m[3], 10), port, busKind: m[2], spiHz: 0, spiMode: 0, alertPin: -1 };
+        const ref = { part: m[1], busIndex: parseInt(m[3], 10), port, busKind: m[2], 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}`;
@@ -631,11 +672,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_');
@@ -654,12 +697,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'),
@@ -723,7 +783,8 @@ export const Toolchain = {
         const isGdbDebug = o.debug === true && debugMode === 'gdb';
         const zc = o.zephyrConfig;
         const userKconfig = zc?.kconfig;
-        const configChanged = scaffoldZephyrProject(projectRoot, isGdbDebug, userKconfig, o.psram);
+        const traceCfg = zc?.trace;
+        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
         // the <default>.overlay it wrote does not match `west build -b <board>`.
@@ -757,28 +818,22 @@ 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;
             const spiPins = (dispCfg?.spiPins ?? undefined);
+            const i2cPins = (dispCfg?.i2cPins ?? undefined);
             const wiring = dispCfg
                 ? {
                     cs: typeof dispCfg.cs === 'number' ? dispCfg.cs : undefined,
@@ -788,8 +843,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.busyPin === 'number' ? dispCfg.busyPin : undefined,
+                    address: typeof dispCfg.address === 'number' ? dispCfg.address : undefined,
                 }
                 : undefined;
             // Extract touch pin wiring from the config display.touch section so the
@@ -841,13 +900,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'),
@@ -1029,6 +1105,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/dist/toolchain/scaffold.d.ts

@@ -21,4 +21,7 @@ export declare function appendLibraryOverlayFragments(overlay: string, projectRo
  *
  * Idempotent. Mirrors scaffoldEspIdfProject's writeIfChanged discipline.
  */
-export declare function scaffoldZephyrProject(projectRoot: string, debug?: boolean, userKconfig?: Record<string, string>, psram?: 'opi' | 'quad'): boolean;
+export declare function scaffoldZephyrProject(projectRoot: string, debug?: boolean, userKconfig?: Record<string, string>, psram?: 'opi' | 'quad', trace?: {
+    enabled?: boolean;
+    intervalMs?: number;
+}): boolean;

package/dist/toolchain/scaffold.js

@@ -9,7 +9,9 @@
 import { writeFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveKconfigFragments } 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';
 /** Write a file only if the content differs from the existing file.
@@ -96,7 +98,7 @@ export function appendLibraryOverlayFragments(overlay, projectRoot) {
  *
  * Idempotent. Mirrors scaffoldEspIdfProject's writeIfChanged discipline.
  */
-export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, psram) {
+export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, psram, trace) {
     const srcDir = join(projectRoot, 'src');
     if (!existsSync(srcDir))
         mkdirSync(srcDir, { recursive: true });
@@ -122,6 +124,22 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
     const usage = {
         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, debug = false, userKconfig, p
         // 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,32 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
         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).
+        ...(() => {
+            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.)
@@ -266,6 +307,29 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
             }
         }
     }
+    // ── 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 = [
+            ['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/dist/west-inventory.d.ts

@@ -0,0 +1,25 @@
+import type { ReadDir, ReadFile } from '@typecad/cuttlefish/api/shared';
+/** Normalize a path for case-insensitive, separator-agnostic comparison. */
+export declare function norm(p: string): string;
+/**
+ * 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 declare function filterLinkedModules(ccText: string, modules: {
+    name: string;
+    abspath: string;
+}[]): {
+    name: string;
+    abspath: string;
+}[];
+/**
+ * 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 declare function findCompileCommandsPath(readFile: ReadFile, readdir: ReadDir, cwd?: string): string | undefined;

package/dist/west-inventory.js

@@ -0,0 +1,97 @@
+// ---------------------------------------------------------------------------
+// @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';
+/** Normalize a path for case-insensitive, separator-agnostic comparison. */
+export function norm(p) {
+    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, modules) {
+    let arr;
+    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?.file === 'string' ? e.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, readdir, cwd = process.cwd()) {
+    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) => {
+        const n = norm(p);
+        return n.endsWith('/build/compile_commands.json') || n.endsWith('\\build\\compile_commands.json');
+    };
+    let found;
+    const seen = new Set();
+    const walk = (dir, depth) => {
+        if (found || depth > 4 || seen.has(dir))
+            return;
+        seen.add(dir);
+        let entries;
+        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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/framework-zephyr",
-  "version": "1.0.0-alpha.18",
+  "version": "1.0.0-alpha.19",
   "description": "TypeCAD framework package for the Zephyr RTOS \u2014 west/CMake build, devicetree-driven GPIO",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,10 +39,10 @@
     "dry-run": "node installer/install.mjs --dry-run"
   },
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.18"
+    "@typecad/cuttlefish": "1.0.0-alpha.19"
   },
   "devDependencies": {
-    "@typecad/hal": "1.0.0-alpha.18",
+    "@typecad/hal": "1.0.0-alpha.19",
     "typescript": "^5.7.3"
   },
   "license": "Apache-2.0",