@typecad/framework-zephyr 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/sdk/catalog-walker.js

@@ -0,0 +1,682 @@
+// ---------------------------------------------------------------------------
+// catalog-walker.ts — walk a Zephyr tree's boards/ and build the board data
+// catalog (records + provenance).
+//
+// For every board variant yaml that carries an `identifier:` (the qualified
+// west build target) and a same-basename .dts, extract the board-level facts
+// with the tolerant dts-reader. One record per board VARIANT (identifier),
+// keyed by the identifier.
+//
+// This is the ONE walker shared by both catalog producers:
+//   - repo build: scripts/gen-zephyr-board-data.mjs emits the compiled-in
+//     pack (packages/cuttlefish/src/create/board-catalog.generated.ts);
+//   - user runtime: `cuttlefish board sync` (sdk/board-catalog-sync.ts)
+//     regenerates a local overlay from the user's own Zephyr tree, so board
+//     add/change/remove tracks `west update` instead of cuttlefish releases.
+//
+// Silicon facts (ADC channels, PWM matrices) are NOT extracted — they never
+// live in devicetree. They are the curated chips/soc/ descriptors.
+// ----------------------------------------------------------------------------
+import fs from 'node:fs';
+import path from 'node:path';
+import { readBoardDts } from './dts-reader.js';
+/** Cut an inline `# comment` — safe inside quoted values (variant yamls
+ *  carry them, e.g. ai_m61_32s_kit's revision note). */
+function stripYamlComment(value) {
+    const q = value[0];
+    if (q === '"' || q === "'") {
+        const end = value.indexOf(q, 1);
+        return end > 0 ? value.slice(0, end + 1) : value;
+    }
+    const hash = value.indexOf(' #');
+    return hash >= 0 ? value.slice(0, hash) : value;
+}
+/** Minimal line yaml reads (identifier:, name:) — full yaml not needed. */
+function yamlField(file, field) {
+    const m = fs.readFileSync(file, 'utf8').match(new RegExp(`^${field}:\\s*(.+)$`, 'm'));
+    return m ? stripYamlComment(m[1]).trim() : undefined;
+}
+/** Read board.yml's board→soc index (see BoardYmlSocIndex). */
+export function boardYmlSocIndex(dir) {
+    const yml = path.join(dir, 'board.yml');
+    if (!fs.existsSync(yml))
+        return { byName: new Map(), uniqueSocs: [], boardNames: [] };
+    const byName = new Map();
+    const uniqueSocs = [];
+    const boardNames = [];
+    let inBoardsList = false; // top-level `boards:` present (multi-board format)
+    let currentBoard;
+    let currentSocs = []; // socs collected for currentBoard
+    // A key line with its indent, innermost last. A `- name:` list entry is
+    // owned by the topmost key at an indent ≤ the entry's — the tree's
+    // board.ymls are not indent-consistent (xiao_ble puts soc entries at the
+    // same indent as the socs: key, lyra nests them two deeper), so the
+    // enclosing KEY, not the indentation depth, decides ownership.
+    const keyStack = [];
+    const flushEntry = () => {
+        // Only single-soc entries map board name → soc: multi-soc entries need
+        // qualified identifiers in their variant yamls.
+        if (currentBoard && currentSocs.length === 1)
+            byName.set(currentBoard, currentSocs[0]);
+    };
+    for (const rawLine of fs.readFileSync(yml, 'utf8').split('\n')) {
+        const line = rawLine.replace(/\r$/, '');
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const indent = line.length - line.trimStart().length;
+        const entry = trimmed.match(/^- name:\s*(.+)$/);
+        const key = trimmed.match(/^([\w.-]+):(?:\s|$)/);
+        if (key) {
+            while (keyStack.length > 0 && keyStack[keyStack.length - 1].indent > indent)
+                keyStack.pop();
+            keyStack.push({ indent, key: key[1] });
+            if (indent === 0 && key[1] === 'boards')
+                inBoardsList = true;
+            continue;
+        }
+        // Legacy single-board header: `board: xiao_ble` (value on the key line).
+        if (indent === 0) {
+            const legacyBoard = trimmed.match(/^board:\s*(\S.*)$/);
+            if (legacyBoard)
+                boardNames.push(stripYamlComment(legacyBoard[1]).trim());
+        }
+        if (entry) {
+            const name = stripYamlComment(entry[1]).trim();
+            if (!name)
+                continue;
+            // Innermost enclosing key that owns a list at this entry's indent.
+            let owner;
+            for (let i = keyStack.length - 1; i >= 0; i--) {
+                if (keyStack[i].indent <= indent) {
+                    owner = keyStack[i];
+                    break;
+                }
+            }
+            if (owner?.key === 'boards') {
+                // A board entry under boards: — its socs follow under its own
+                // socs: key.
+                flushEntry();
+                currentBoard = name;
+                currentSocs = [];
+                boardNames.push(name);
+            }
+            else if (owner?.key === 'socs') {
+                if (inBoardsList)
+                    currentSocs.push(name);
+                else
+                    uniqueSocs.push(name);
+            }
+            // Every other list (variants:, …) is not ours.
+        }
+    }
+    flushEntry();
+    return { byName, uniqueSocs, boardNames };
+}
+/**
+ * west runner → probe-method metadata. Ids match the curated soc tables
+ * ('stlink', 'dfu', 'jlink', 'bossac', …) so `zephyr.probe` values stay
+ * stable across tiers; runners with no curated counterpart use their west
+ * runner name as the id (stm32cubeprogrammer, uf2, …). Flash-only tools
+ * carry debug: false (a bootloader is not a debugger — the debug path
+ * rejects them, resolveProbeMethod enforces it). Simulation-only runners
+ * (renode, simics) and debug-server helpers (stlink_gdbserver, trace32)
+ * stay unmapped — cuttlefish flashes real hardware.
+ */
+const RUNNER_METHODS = {
+    'openocd': { id: 'openocd', description: 'Any SWD/JTAG probe openocd supports', debug: true },
+    // Vendor-flavored openocd runner includes — the same openocd runner with
+    // vendor defaults (ST: onboard ST-Link; nRF5: nRF tap config). Without
+    // these, every ST board (118 in the tree) lost its primary probe method.
+    'openocd-stm32': { id: 'openocd', description: 'ST-Link onboard or any SWD probe openocd supports', debug: true },
+    'openocd-nrf5': { id: 'openocd', description: 'Any SWD/JTAG probe openocd supports (nRF5 defaults)', debug: true },
+    'jlink': { id: 'jlink', description: 'J-Link probe (SWD)', debug: true },
+    'dfu-util': { id: 'dfu', description: 'Built-in USB DFU bootloader: hold BOOT0, tap reset (no debug)', debug: false },
+    'pyocd': { id: 'pyocd', description: 'Any CMSIS-DAP probe via pyOCD (no debug)', debug: false },
+    'blackmagicprobe': { id: 'blackmagicprobe', description: 'Black Magic Probe (no debug)', debug: false },
+    'stm32flash': { id: 'stm32flash', description: 'Built-in UART bootloader (no debug)', debug: false },
+    'bossac': { id: 'bossac', description: 'Built-in USB bootloader: double-tap reset (no debug)', debug: false },
+    'nrfjprog': { id: 'nrfjprog', description: 'Segger nRF command-line flasher (no debug)', debug: false },
+    'esptool': { id: 'esptool', description: 'Espressif ROM bootloader over USB-serial (no debug)', debug: false },
+    // The ESP32 family's include name for the esptool runner.
+    'esp32': { id: 'esptool', description: 'Espressif ROM bootloader over USB-serial (no debug)', debug: false },
+    'linkserver': { id: 'linkserver', description: 'NXP LinkServer (no debug)', debug: false },
+    'ezflashcli': { id: 'ezflashcli', description: 'Renesas EZ flash CLI (no debug)', debug: false },
+    'stm32cubeprogrammer': { id: 'stm32cubeprogrammer', description: 'STM32CubeProgrammer CLI via ST-Link (no debug)', debug: false },
+    'nrfutil': { id: 'nrfutil', description: 'nrfutil device — Nordic USB DFU / serial bootloader (no debug)', debug: false },
+    'uf2': { id: 'uf2', description: 'UF2 bootloader: copy the firmware file (no debug)', debug: false },
+    'silabs_commander': { id: 'silabs_commander', description: 'Simplicity Commander CLI (no debug)', debug: false },
+    'probe-rs': { id: 'probe-rs', description: 'probe-rs flasher (no debug)', debug: false },
+    'rfp': { id: 'rfp', description: 'Renesas Flash Programmer CLI (no debug)', debug: false },
+    'bflb_mcu_tool': { id: 'bflb_mcu_tool', description: 'BouffaloLab bflb_mcu_tool (no debug)', debug: false },
+    'xsdb': { id: 'xsdb', description: 'Xilinx xsdb flasher (no debug)', debug: false },
+    'wchisp': { id: 'wchisp', description: 'WCH ISP bootloader (no debug)', debug: false },
+    'spsdk': { id: 'spsdk', description: 'NXP SPSDK blhost (no debug)', debug: false },
+    'minichlink': { id: 'minichlink', description: 'minichlink (WCH CH32, no debug)', debug: false },
+    'mdb-hw': { id: 'mdb-hw', description: 'Synopsys MetaWare Debugger, hardware target (no debug)', debug: false },
+    'wlink': { id: 'wlink', description: 'WCH-Link probe (no debug)', debug: false },
+    'gd32isp': { id: 'gd32isp', description: 'GD32 UART ISP bootloader (no debug)', debug: false },
+    'sftool': { id: 'sftool', description: 'SiFli sftool (no debug)', debug: false },
+    'teensy': { id: 'teensy', description: 'Teensy loader (no debug)', debug: false },
+    'nulink': { id: 'nulink', description: 'Nuvoton NuLink (no debug)', debug: false },
+};
+/**
+ * Scan board.cmake line-by-line tracking if/elseif/else/endif, recording
+ * every board_runner_args occurrence and every runner include with its
+ * condition stack. Variant selection happens later (pickArgs /
+ * activeRunners) — a dir shared by several boards guards each variant's
+ * runner args behind its own CONFIG_BOARD_<ID>, and boards guard whole
+ * RUNNERS behind core-specific configs (variscite's jlink sits inside
+ * if(CONFIG_SOC_MIMX8ML8_M7): the A53 target has no jlink at all).
+ * Args containing CMake variable references (${CONFIG_SOC}, …) only
+ * resolve inside the build — carried verbatim they would poison a real
+ * `west flash` invocation, so they are dropped at capture.
+ */
+function scanBoardCmake(text) {
+    const runnerArgs = new Map();
+    const includes = [];
+    const conds = [];
+    for (const line of text.split('\n')) {
+        const branch = line.match(/^\s*(if|elseif|else|endif)\b\s*\(?\s*(.*?)\s*\)?\s*$/);
+        if (branch) {
+            const kw = branch[1];
+            const cond = kw === 'else' ? '' : branch[2];
+            if (kw === 'if')
+                conds.push(cond);
+            else if (kw === 'elseif')
+                conds[conds.length - 1] = cond;
+            else if (kw === 'else')
+                conds[conds.length - 1] = '';
+            else if (kw === 'endif')
+                conds.pop();
+            continue;
+        }
+        const argsM = line.match(/^\s*board_runner_args\(([\w.-]+)\s+(.*)\)\s*$/);
+        if (argsM) {
+            const args = [...argsM[2].matchAll(/"([^"]*)"/g)].map((q) => q[1]).filter((q) => !q.includes('${'));
+            const list = runnerArgs.get(argsM[1]) ?? [];
+            list.push({ conds: [...conds], args });
+            runnerArgs.set(argsM[1], list);
+            continue;
+        }
+        const incM = line.match(/^\s*include\(\$\{ZEPHYR_BASE\}\/boards\/common\/([\w.-]+)\.board\.cmake\)/);
+        if (incM)
+            includes.push({ name: incM[1], conds: [...conds] });
+    }
+    return { runnerArgs, includes };
+}
+/**
+ * Does one condition line apply to THIS target? Empty = always. A
+ * CONFIG_BOARD stem must match on a token boundary (a prefix must not
+ * match a longer board name); a CONFIG_SOC_<soc> guard matches any
+ * variant of that soc, and CONFIG_SOC_<soc>_<X> matches variants whose
+ * qualifiers include X.
+ */
+function conditionMatchesTarget(cond, boardConfigs, soc, quals) {
+    if (!cond)
+        return true;
+    const cu = cond.toUpperCase();
+    for (const cfg of boardConfigs) {
+        if (new RegExp(`CONFIG_BOARD_${cfg}(?![A-Za-z0-9_])`).test(cu))
+            return true;
+    }
+    if (soc) {
+        const socUpper = soc.toUpperCase();
+        if (new RegExp(`CONFIG_SOC_${socUpper}(?![A-Za-z0-9_])`).test(cu))
+            return true;
+        if (quals.some((q) => cu.includes(`_${q.toUpperCase()}`)) && cu.includes(`CONFIG_SOC_${socUpper}`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Pick the occurrence for one variant. Priority:
+ *   1. a condition naming one of this target's CONFIG_BOARD_<name> tokens
+ *      (both Zephyr naming shapes: the board.yml entry name — duo_board_b —
+ *      and the full underscored target — raytac's …_NRF5340_CPUNET), matched
+ *      with a token boundary so CONFIG_BOARD_IMX8MM_EVK does not match
+ *      …_EVK_MIMX8MM6_M4;
+ *   2. a CONFIG_SOC_<soc>_… condition mentioning one of the target's
+ *      qualifier tokens (imx8mm guards its A53 args that way);
+ *   3. an unconditional occurrence;
+ *   4. the first (documented fallback).
+ */
+function pickArgs(list, boardConfigs, soc, quals) {
+    for (const cfg of boardConfigs) {
+        const boardGuarded = list.find((o) => o.conds.some((c) => conditionMatchesTarget(c, [cfg], undefined, [])));
+        if (boardGuarded)
+            return boardGuarded.args;
+    }
+    if (soc && quals.length > 0) {
+        const socGuarded = list.find((o) => o.conds.some((c) => c && conditionMatchesTarget(c, [], soc, quals) && /CONFIG_SOC_/i.test(c)));
+        if (socGuarded)
+            return socGuarded.args;
+    }
+    const plain = list.find((o) => o.conds.length === 0 || o.conds.every((c) => c === ''));
+    if (plain)
+        return plain.args;
+    return list[0]?.args ?? [];
+}
+export function boardProbeMethods(dir, variant) {
+    const cmake = path.join(dir, 'board.cmake');
+    if (!fs.existsSync(cmake))
+        return undefined;
+    const text = fs.readFileSync(cmake, 'utf8');
+    const scan = scanBoardCmake(text);
+    const boardConfigs = variant?.boardConfigs ?? [];
+    const soc = variant?.soc;
+    const quals = variant?.quals ?? [];
+    // Active runners for THIS variant: unconditional includes always apply;
+    // guarded includes apply only when their condition names this target
+    // (variscite's jlink is inside if(CONFIG_SOC_…_M7) — the A53 target has
+    // no jlink at all, and offering it would flash the wrong core). Only
+    // ~24 files in the tree guard every include; a target matching none of
+    // a file's guards honestly gets no probe methods.
+    let includeNames = scan.includes.map((i) => i.name);
+    const anyGuarded = scan.includes.some((i) => i.conds.length > 0 && i.conds.some((c) => c !== ''));
+    if (anyGuarded) {
+        const active = new Set();
+        for (const inc of scan.includes) {
+            if (inc.conds.length === 0 || inc.conds.every((c) => c === ''))
+                active.add(inc.name);
+            else if (inc.conds.some((c) => conditionMatchesTarget(c, boardConfigs, soc, quals)))
+                active.add(inc.name);
+        }
+        includeNames = [...active];
+    }
+    // First include = west's default runner (preserve scan order).
+    const runners = [...new Set(includeNames)];
+    if (runners.length === 0)
+        return undefined;
+    let cfgLines = null;
+    const cfgPath = path.join(dir, 'support', 'openocd.cfg');
+    if (fs.existsSync(cfgPath)) {
+        cfgLines = fs.readFileSync(cfgPath, 'utf8').split('\n').map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith('#'));
+    }
+    const methods = [];
+    for (const runner of runners) {
+        // The vendor-flavored openocd includes get the same cfg treatment as
+        // plain openocd (stlink interface detection + debugCfg attach).
+        if (runner === 'openocd' || runner === 'openocd-stm32' || runner === 'openocd-nrf5') {
+            // An ST-Link interface cfg means the method is really 'stlink' — the
+            // curated-table id users know. debugCfg carries the whole cfg file,
+            // original line order (source/transport/events), comma-free join is
+            // not assumed by the consumer.
+            const isStlink = cfgLines?.some((l) => l.includes('interface/stlink')) ?? false;
+            methods.push({
+                id: isStlink ? 'stlink' : 'openocd',
+                description: isStlink
+                    ? 'ST-Link or any SWD probe openocd supports (no BOOT0 needed) — also debugs'
+                    : 'Any SWD/JTAG probe openocd supports — also debugs',
+                runner,
+                debug: true,
+                ...(cfgLines ? { debugCfg: cfgLines } : {}),
+            });
+            continue;
+        }
+        const meta = RUNNER_METHODS[runner];
+        if (!meta)
+            continue;
+        // Per-variant args: the occurrence whose CONFIG_BOARD / CONFIG_SOC
+        // guard names THIS variant wins (pickArgs).
+        const args = pickArgs(scan.runnerArgs.get(runner) ?? [], boardConfigs, soc, quals);
+        if (runner === 'jlink') {
+            const device = args.find((a) => a.startsWith('--device='));
+            methods.push({
+                id: 'jlink',
+                description: 'J-Link probe (SWD) — also debugs',
+                runner,
+                debug: true,
+                ...(device ? { debugDevice: device.slice('--device='.length) } : {}),
+            });
+            continue;
+        }
+        methods.push({ ...meta, runner, ...(args.length > 0 ? { args: [...args] } : {}) });
+    }
+    // Dedupe by method id: vendor-flavored includes can coexist with the
+    // plain one (openocd + openocd-stm32) — one method per id, first wins.
+    const seen = new Set();
+    const unique = methods.filter((m) => (seen.has(m.id) ? false : (seen.add(m.id), true)));
+    return unique.length > 0 ? unique : undefined;
+}
+/** VERSION file → 'MAJOR.MINOR.PATCH' ('' when unreadable). */
+export function zephyrVersionOf(zephyrBase) {
+    try {
+        const text = fs.readFileSync(path.join(zephyrBase, 'VERSION'), 'utf8');
+        const m = text.match(/VERSION_MAJOR\s*=\s*(\d+)[\s\S]*?VERSION_MINOR\s*=\s*(\d+)/);
+        if (!m)
+            return '';
+        const patch = text.match(/PATCHLEVEL\s*=\s*(\d+)/);
+        return patch ? `${m[1]}.${m[2]}.${patch[1]}` : `${m[1]}.${m[2]}`;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Git HEAD of the tree, read straight off the filesystem (no git spawn —
+ * sync runs where git may be absent). Handles the plain clone (.git dir,
+ * HEAD → ref → loose ref or packed-refs) and the worktree/submodule form
+ * (.git file pointing at a gitdir). Best-effort: undefined when unreadable.
+ */
+export function gitHeadOf(zephyrBase) {
+    try {
+        const dotGit = path.join(zephyrBase, '.git');
+        let gitDir = dotGit;
+        const st = fs.statSync(dotGit);
+        if (st.isFile()) {
+            const text = fs.readFileSync(dotGit, 'utf8');
+            const m = text.match(/gitdir:\s*(.+)/);
+            if (!m)
+                return undefined;
+            const dir = m[1].trim();
+            gitDir = path.isAbsolute(dir) ? dir : path.resolve(zephyrBase, dir);
+        }
+        const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
+        if (!head.startsWith('ref: '))
+            return head || undefined;
+        const ref = head.slice(5).trim();
+        const refFile = path.join(gitDir, ref);
+        if (fs.existsSync(refFile))
+            return fs.readFileSync(refFile, 'utf8').trim() || undefined;
+        const packed = fs.readFileSync(path.join(gitDir, 'packed-refs'), 'utf8');
+        const m = packed.match(new RegExp(`^([0-9a-f]{40,}) ${ref.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'm'));
+        return m ? m[1] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parse board.yml into its declared build targets, both shapes:
+ * multi-board (`boards:` list) and legacy (`board:` block), with socs and
+ * (nested) variants. Variant chains accumulate through nesting levels
+ * (board/soc/v1/v2).
+ */
+export function boardYmlTargets(dir) {
+    const yml = path.join(dir, 'board.yml');
+    if (!fs.existsSync(yml))
+        return [];
+    const targets = [];
+    const boards = [];
+    let board;
+    let soc;
+    const keyStack = [];
+    const chainBases = [];
+    let chain = [];
+    const flushSoc = () => {
+        if (board && soc) {
+            board.socs.set(soc.name, soc.chains);
+            soc = undefined;
+            chain = [];
+            chainBases.length = 0;
+        }
+    };
+    const flushBoard = () => {
+        flushSoc();
+        board = undefined;
+    };
+    for (const rawLine of fs.readFileSync(yml, 'utf8').split('\n')) {
+        const line = rawLine.replace(/\r$/, '');
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const indent = line.length - line.trimStart().length;
+        const entry = trimmed.match(/^- name:\s*(.+)$/);
+        const key = trimmed.match(/^([\w.-]+):(?:\s+(.*))?$/);
+        if (key && !trimmed.startsWith('-')) {
+            while (keyStack.length > 0 && keyStack[keyStack.length - 1].indent > indent)
+                keyStack.pop();
+            const k = key[1];
+            const v = (key[2] ?? '').trim();
+            if (indent === 0 && k === 'boards') {
+                flushBoard();
+            }
+            else if (indent === 0 && k === 'board' && v) {
+                // Legacy inline form: board: xiao_ble
+                flushBoard();
+                board = { name: stripYamlComment(v).trim(), socs: new Map() };
+                boards.push(board);
+            }
+            else if (k === 'variants') {
+                // Chains under this level accumulate from the enclosing chain.
+                chainBases.push([...chain]);
+            }
+            else if ((k === 'name' || k === 'full_name' || k === 'vendor') && v) {
+                const val = stripYamlComment(v).trim();
+                // A name: under a legacy board: block names the board.
+                if (k === 'name' && !board && keyStack.some((s) => s.key === 'board')) {
+                    board = { name: val, socs: new Map() };
+                    boards.push(board);
+                }
+                else if (k !== 'name' && board && !soc) {
+                    if (k === 'full_name')
+                        board.fullName = val;
+                    if (k === 'vendor')
+                        board.vendor = val;
+                }
+            }
+            keyStack.push({ indent, key: k });
+            continue;
+        }
+        if (entry) {
+            const name = stripYamlComment(entry[1]).trim().replace(/^['"]|['"]$/g, '');
+            if (!name)
+                continue;
+            let owner;
+            for (let i = keyStack.length - 1; i >= 0; i--) {
+                if (keyStack[i].indent <= indent) {
+                    owner = keyStack[i].key;
+                    break;
+                }
+            }
+            if (owner === 'boards') {
+                flushBoard();
+                board = { name, socs: new Map() };
+                boards.push(board);
+            }
+            else if (owner === 'socs') {
+                flushSoc();
+                soc = { name, chains: [] };
+            }
+            else if (owner === 'variants') {
+                const base = chainBases[chainBases.length - 1] ?? [];
+                chain = [...base, name];
+                soc?.chains.push([...chain]);
+            }
+        }
+    }
+    flushBoard();
+    for (const b of boards) {
+        for (const [socName, chains] of b.socs) {
+            targets.push({ identifier: `${b.name}/${socName}`, boardName: b.name, soc: socName, chain: [], ...(b.fullName ? { fullName: b.fullName } : {}), ...(b.vendor ? { vendor: b.vendor } : {}) });
+            for (const c of chains) {
+                targets.push({ identifier: [b.name, socName, ...c].join('/'), boardName: b.name, soc: socName, chain: c, ...(b.fullName ? { fullName: b.fullName } : {}), ...(b.vendor ? { vendor: b.vendor } : {}) });
+            }
+        }
+    }
+    return targets;
+}
+/** Compose the catalog record from one DTS's extracted facts. The canonical
+ *  LED/button picks follow the DEVICETREE numbering, not child order: led0
+ *  when aliased (mm_swiftio declares led0 = green_led as the SECOND child —
+ *  picking the first aliased child made the manifest's LED0 contradict the
+ *  devicetree's led0). Same for sw0. Extras then carry the remaining
+ *  aliased nodes and the LED<N>/BUTTON<N> indices line up with dtSpec
+ *  numbering. */
+function composeRecord(base, facts) {
+    const led = facts.leds.find((l) => l.alias === 'led0') ?? facts.leds.find((l) => l.alias);
+    const button = facts.buttons.find((b) => b.alias === 'sw0') ?? facts.buttons.find((b) => b.alias);
+    const rec = {
+        ...base,
+        console: facts.chosen['zephyr,console'],
+        // Addressable user LED (ws2812) only when no gpio-leds LED exists —
+        // a board with both keeps its devicetree-chosen led0.
+        ...(facts.stripLed && !led ? { stripLed: { controller: facts.stripLed.controller, pin: facts.stripLed.pin } } : {}),
+        ...(facts.usbDevice ? { usbDevice: facts.usbDevice } : {}),
+        ...(facts.usbController ? { usbController: facts.usbController } : {}),
+        ...(facts.aliases['watchdog0'] ? { wdtNodeLabel: facts.aliases['watchdog0'] } : {}),
+        ...(facts.buses.i2c.length > 0 || facts.buses.spi.length > 0 || facts.buses.uart.length > 0
+            ? { buses: facts.buses }
+            : {}),
+        ...(facts.pwmLeds.length > 0
+            ? { pwmLeds: facts.pwmLeds.map((p) => ({
+                    ...(p.alias ? { alias: p.alias } : {}),
+                    controller: p.controller, channel: p.channel,
+                    ...(p.periodNs != null ? { periodNs: p.periodNs } : {}),
+                    ...(p.flags && p.flags.length > 0 ? { flags: [...p.flags] } : {}),
+                })) }
+            : {}),
+        ...(led ? { led: { dtSpec: led.alias, controller: led.controller, pin: led.pin, flags: led.flags } } : {}),
+        ...(button ? { button: { dtSpec: button.alias, controller: button.controller, pin: button.pin, flags: button.flags } } : {}),
+        ...(facts.leds.length > 1 || facts.buttons.length > 1
+            ? {
+                extraLeds: facts.leds.filter((l) => l !== led && l.alias).map((l) => ({ dtSpec: l.alias, controller: l.controller, pin: l.pin, flags: l.flags })),
+                extraButtons: facts.buttons.filter((b) => b !== button && b.alias).map((b) => ({ dtSpec: b.alias, controller: b.controller, pin: b.pin, flags: b.flags })),
+            }
+            : {}),
+        ...(facts.connectors.filter((c) => Object.keys(c.pins).length > 0).length > 0
+            ? { connectors: facts.connectors.filter((c) => Object.keys(c.pins).length > 0).map((c) => ({ nodelabel: c.nodelabel, compatible: c.compatible, pins: c.pins })) }
+            : {}),
+    };
+    // prune empty arrays
+    for (const k of ['extraLeds', 'extraButtons'])
+        if (rec[k]?.length === 0)
+            delete rec[k];
+    const hasFacts = Boolean(rec.console || rec.led || rec.button || rec.connectors);
+    return { record: rec, hasFacts };
+}
+/** Probe-method pin for one identifier (CONFIG_BOARD stems + soc quals). */
+function variantPinFor(identifier, socIndex) {
+    const parts = identifier.split('/');
+    const underscored = identifier.replace(/\//g, '_');
+    const entry = socIndex.boardNames.find((n) => identifier === n || identifier.startsWith(n + '/'));
+    return {
+        boardConfigs: [...new Set([...(entry ? [entry] : []), underscored])]
+            .map((n) => n.replace(/[^A-Za-z0-9]/g, '_').toUpperCase()),
+        ...(parts[1] ? { soc: parts[1] } : {}),
+        ...(parts.length > 2 ? { quals: parts.slice(2) } : {}),
+    };
+}
+/**
+ * Walk `<zephyrBase>/boards` and extract one record per board variant.
+ * Reader failures degrade to the base record (identifier/name/vendor/dts +
+ * probe methods) — a board whose DTS defeats the reader still resolves, it
+ * just carries no pin facts.
+ */
+export function walkBoardCatalog(zephyrBase) {
+    const boardsRoot = path.join(zephyrBase, 'boards');
+    if (!fs.existsSync(boardsRoot)) {
+        throw new Error(`no boards/ directory at ${boardsRoot} — not a Zephyr tree?`);
+    }
+    const records = [];
+    let variants = 0, withFacts = 0, failures = 0;
+    const vendors = fs.readdirSync(boardsRoot, { withFileTypes: true })
+        .filter((d) => d.isDirectory());
+    for (const vendorDir of vendors) {
+        const boardDirs = fs.readdirSync(path.join(boardsRoot, vendorDir.name), { withFileTypes: true })
+            .filter((d) => d.isDirectory());
+        for (const boardDir of boardDirs) {
+            const dir = path.join(boardsRoot, vendorDir.name, boardDir.name);
+            const files = fs.readdirSync(dir);
+            const socIndex = boardYmlSocIndex(dir);
+            const seenIds = new Set();
+            for (const f of files) {
+                if (!f.endsWith('.yaml') || f === 'board.yml')
+                    continue;
+                const raw = yamlField(path.join(dir, f), 'identifier');
+                if (!raw)
+                    continue;
+                // Qualify: bare identifiers take the soc segment from board.yml —
+                // their own entry's soc in multi-board dirs, the sole soc in
+                // single-board dirs.
+                const identifier = raw.includes('/')
+                    ? raw
+                    : (() => {
+                        const soc = socIndex.byName.get(raw)
+                            ?? (socIndex.uniqueSocs.length === 1 ? socIndex.uniqueSocs[0] : null);
+                        return soc ? `${raw}/${soc}` : null;
+                    })();
+                if (!identifier || seenIds.has(identifier))
+                    continue;
+                variants++;
+                seenIds.add(identifier);
+                const dtsBase = f.replace(/\.yaml$/, '');
+                const dtsFile = path.join(dir, dtsBase + '.dts');
+                if (!fs.existsSync(dtsFile))
+                    continue;
+                // Per-variant: runner args are selected by the variant's own
+                // CONFIG_BOARD guard, so this must run per yaml, not per dir.
+                const probeMethods = boardProbeMethods(dir, variantPinFor(identifier, socIndex));
+                const base = {
+                    identifier,
+                    name: yamlField(path.join(dir, f), 'name') ?? identifier,
+                    vendor: vendorDir.name,
+                    dts: dtsBase + '.dts',
+                    ...(probeMethods ? { probeMethods } : {}),
+                };
+                try {
+                    const facts = readBoardDts(dtsFile, { zephyrBoardsRoot: boardsRoot });
+                    const { record, hasFacts } = composeRecord(base, facts);
+                    if (hasFacts)
+                        withFacts++;
+                    records.push(record);
+                }
+                catch (err) {
+                    failures++;
+                    if (failures <= 5)
+                        console.error(`reader failed on ${identifier}: ${err.message}`);
+                    records.push(base);
+                }
+            }
+            // Synthesis pass: board.yml-driven dirs ship NO per-variant yamls —
+            // nucleo_n657x0_q's `sb` target exists only as a board.yml entry.
+            // Emit every declared target the yaml flow did not already cover.
+            for (const t of boardYmlTargets(dir)) {
+                if (seenIds.has(t.identifier))
+                    continue;
+                seenIds.add(t.identifier);
+                const dtsFile = [
+                    path.join(dir, t.identifier.replace(/\//g, '_') + '.dts'),
+                    path.join(dir, t.boardName + '.dts'),
+                ].find((p) => fs.existsSync(p));
+                if (!dtsFile)
+                    continue;
+                variants++;
+                const probeMethods = boardProbeMethods(dir, variantPinFor(t.identifier, socIndex));
+                const base = {
+                    identifier: t.identifier,
+                    name: t.fullName ?? t.identifier,
+                    vendor: t.vendor ?? vendorDir.name,
+                    dts: path.basename(dtsFile),
+                    ...(probeMethods ? { probeMethods } : {}),
+                };
+                try {
+                    const facts = readBoardDts(dtsFile, { zephyrBoardsRoot: boardsRoot });
+                    const { record, hasFacts } = composeRecord(base, facts);
+                    if (hasFacts)
+                        withFacts++;
+                    records.push(record);
+                }
+                catch (err) {
+                    failures++;
+                    if (failures <= 5)
+                        console.error(`reader failed on ${t.identifier}: ${err.message}`);
+                    records.push(base);
+                }
+            }
+        }
+    }
+    return {
+        boards: Object.fromEntries(records.map((r) => [r.identifier, r])),
+        provenance: {
+            zephyrBase: path.resolve(zephyrBase),
+            version: zephyrVersionOf(zephyrBase),
+            ...(gitHeadOf(zephyrBase) ? { gitHead: gitHeadOf(zephyrBase) } : {}),
+            boardsMtimeMs: fs.statSync(boardsRoot).mtimeMs,
+            generatedAt: new Date().toISOString(),
+            variants: records.length,
+        },
+        stats: { variants, withFacts, failures },
+    };
+}