driverge-mcp 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mehmet Topuz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+<p align="center">
+  <img src="assets/Driverge-lockup.svg" alt="Driverge" width="360">
+</p>
+<p align="center"><em>Datasheet PDF → embedded C/C++ driver, from any MCP client.</em></p>
+
+<p align="center">
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue">
+  <img alt="status" src="https://img.shields.io/badge/status-pre--release-orange">
+  <img alt="mcp" src="https://img.shields.io/badge/MCP-server-black">
+</p>
+
+> 🚧 **Pre-release** — under active development; not yet published to npm. The
+> `npx driverge-mcp` command below is the intended install; until it's published,
+> [run from source](#run-from-source-pre-release).
+
+---
+
+## What is Driverge?
+
+**Driverge is a client-agnostic [MCP](https://modelcontextprotocol.io) server**
+that turns an IC datasheet PDF into an embedded C/C++ driver. It plugs into any
+MCP-capable host — Claude Desktop, Claude Code (VS Code), Cursor, and others.
+
+Its guiding principle: **deterministic code parses and validates; the host AI
+reasons.** Driverge itself contains **no internal LLM and needs no API keys** — a
+TypeScript pipeline extracts a *validated, structured JSON* model of the chip, and
+the host AI you're already talking to fills in the reasoning-heavy parts (init
+sequence, vendor quirks, docs). Your datasheet never leaves your machine.
+
+## What it does
+
+1. **Analyze** a datasheet PDF → detect format, manufacturer, and interface kind
+   (register-map vs. command-set), then extract registers / bit-fields (or
+   commands + CRC) and the bus protocol into a **frozen JSON contract**, gated by
+   a validator.
+2. **Generate** a driver for a target platform: a deterministic **thin-HAL
+   skeleton** — register/bit-field constants, the 5-function HAL seam, function
+   stubs — with every reasoning gap marked `TODO(driverge)` plus a `fill_in_brief`
+   telling the host AI exactly what to complete.
+3. **Validate** the completed driver: thin-HAL purity, no leftover TODOs, register
+   references exist, bit-field masks match the JSON.
+
+### Supported targets
+
+Every target specializes the same portable **[thin-HAL](https://en.wikipedia.org/wiki/Hardware_abstraction_layer)**
+seam — the driver core is identical across platforms; only the seam implementation
+changes.
+
+| Target | Bus binding | Language | Status |
+|---|---|---|---|
+| **Portable (thin-HAL)** | user-implemented `hal_i2c_*` / `hal_spi_*` / `hal_delay_ms` | C | ✅ |
+| **ESP32** | ESP-IDF `i2c_master_*` | C | ✅ |
+| **STM32** | CubeHAL `HAL_I2C_Mem_Read/Write` | C | ✅ |
+| **Arduino** | `Wire` / `SPI` | C++ | planned |
+
+- **Offline & private** — the datasheet is parsed locally; nothing is uploaded.
+- **Deterministic** — the same PDF yields the same JSON and the same skeleton.
+- **Cross-platform** — one parsed model, many target bindings.
+
+> ⚠️ **Generated code is a strong draft, not a certified driver.** Init sequences,
+> compensation formulas, and timing quirks are completed by the host AI and
+> **must be reviewed** before use on hardware. Not safety-certified.
+
+## Installation
+
+**Prerequisites:** Node.js LTS (≥ 18).
+
+Once published, add Driverge to your MCP client (no build step —
+[npx](https://docs.npmjs.com/cli/commands/npx) fetches and runs it):
+
+**Claude Desktop** — `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "driverge": { "command": "npx", "args": ["-y", "driverge-mcp"] }
+  }
+}
+```
+
+**Claude Code (VS Code)** — `.mcp.json` in your workspace root:
+```json
+{
+  "mcpServers": {
+    "driverge": { "command": "npx", "args": ["-y", "driverge-mcp"] }
+  }
+}
+```
+
+**Cursor** — `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "driverge": { "command": "npx", "args": ["-y", "driverge-mcp"] }
+  }
+}
+```
+
+Other clients (Codex, Gemini CLI, …) take the same `command` + `args` pair in
+their own MCP config.
+
+### Run from source (pre-release)
+
+Until the npm package is published:
+
+```bash
+git clone https://github.com/MehmetTopuz/driverge-mcp.git
+cd driverge-mcp
+npm install
+npm run build
+```
+
+Then point your client at the built entry point:
+```json
+{
+  "mcpServers": {
+    "driverge": { "command": "node", "args": ["/absolute/path/to/dist/server.js"] }
+  }
+}
+```
+
+## Usage
+
+Give your MCP client a datasheet and ask it to build a driver. The typical flow:
+
+1. **`analyze_datasheet`** — `{ "pdf_path": "/abs/path/bme280.pdf" }` → returns a
+   compact summary and a `ref` handle; the full JSON is available as a resource.
+2. **`generate_driver`** — `{ "ref": "…", "target": "portable" }` → returns the
+   driver files + a `fill_in_brief`. (`out_dir` also writes them to disk.)
+3. The host AI completes the `TODO(driverge)` markers using the brief and the
+   `driverge://datasheet/<ref>` resource.
+4. **`validate_driver`** — `{ "ref": "…", "files": [...] }` → static checks; loop
+   until it passes.
+
+Reusing the same `ref` with a different `target` re-renders with **no re-parse**.
+
+### Worked example — BME280 → portable driver
+
+> "Analyze the datasheet at `C:/ds/bme280.pdf` with driverge, then generate a
+> portable driver."
+
+Driverge parses the BME280 memory map (14 registers, bit-fields, I²C address),
+validates it, and emits `bme280.h` / `bme280.c` — register `#define`s, bit-field
+`MASK`/`SHIFT` macros, the thin-HAL seam, and `bme280_init/read_register/
+write_register` stubs. The host AI then fills the init sequence and compensation
+docs from the datasheet prose.
+
+### MCP surface
+
+| Kind | Name | Purpose |
+|---|---|---|
+| Tool | `analyze_datasheet` | PDF → validated JSON, cached under a `ref` |
+| Tool | `generate_driver` | `ref` + `target` → driver skeleton + `fill_in_brief` |
+| Tool | `validate_driver` | static-lint a completed driver against its `ref` |
+| Tool | `validate_datasheet` | re-run the L5 validator over a `ref` or JSON |
+| Resource | `driverge://datasheet/<ref>` | full parsed JSON for an analyzed datasheet |
+| Resource | `driverge://schema` | the frozen datasheet JSON-Schema contract |
+| Prompt | `generate-driver` | guided analyze → generate → fill → validate flow |
+
+## Roadmap
+
+- **v0.x** — one reference sensor (BME280), portable thin-HAL core, MCP surface,
+  multiple clients. *(current)*
+- **v0.y** — native targets: ESP32 ✅, STM32 ✅, Arduino (next).
+- **v1.0** — multi-manufacturer coverage and a stable, versioned JSON schema.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the commit convention, and
+the test-driven workflow. Issues and PRs welcome.
+
+## Security & disclaimer
+
+Generated drivers are drafts intended for human review, not certified firmware —
+see [SECURITY.md](SECURITY.md). Driverge runs locally and does not transmit your
+datasheets.
+
+## License
+
+[MIT](LICENSE) © Mehmet Topuz

package/dist/codegen/esp32.d.ts

@@ -0,0 +1,4 @@
+import type { DatasheetJson } from "../schema/types.js";
+import type { DriverArtifact } from "./types.js";
+/** Portable core + an ESP-IDF seam implementation for the same part. */
+export declare function generateEsp32Driver(json: DatasheetJson): DriverArtifact;

package/dist/codegen/esp32.js

@@ -0,0 +1,78 @@
+// ESP32 (ESP-IDF) target. Per platform-code-generation-targets, a native target
+// does NOT replace the thin HAL — it *pre-fills* the seam. So the ESP32 driver is
+// the exact portable core (unchanged, still platform-agnostic) PLUS a
+// <part>_hal_esp32.c that implements hal_i2c_*/hal_delay_ms with the ESP-IDF v5
+// i2c_master driver. The user drops all three files into an ESP-IDF component;
+// only the board's bus/pin bring-up stays a TODO(driverge).
+import { prefixOf, slug } from "./ident.js";
+import { generatePortableDriver } from "./portable.js";
+function halImpl(name, prefix) {
+    const content = [
+        "/*",
+        ` * ${prefix} — ESP-IDF (i2c_master) HAL seam implementation (generated by Driverge).`,
+        " *",
+        " * Drop this beside the portable core; it fills the thin-HAL seam with the",
+        " * ESP-IDF v5 i2c_master driver. In your app: create an I2C master bus with",
+        ` * i2c_new_master_bus() for your SDA/SCL pins, then call ${name}_esp32_bind()`,
+        " * once before using the driver. The driver core stays byte-for-byte portable.",
+        " */",
+        `#include "${name}.h"`,
+        "#include <string.h>",
+        '#include "driver/i2c_master.h"',
+        '#include "freertos/FreeRTOS.h"',
+        '#include "freertos/task.h"',
+        "",
+        `#ifndef ${prefix}_I2C_TIMEOUT_MS`,
+        `#define ${prefix}_I2C_TIMEOUT_MS 1000`,
+        "#endif",
+        "",
+        `static i2c_master_dev_handle_t s_${name}_dev;`,
+        "",
+        `/* Add the device (at ${prefix}_I2C_ADDR) to an existing I2C master bus and keep`,
+        " * the handle for the hal_* calls. Call once after i2c_new_master_bus(). */",
+        `esp_err_t ${name}_esp32_bind(i2c_master_bus_handle_t bus, uint32_t scl_speed_hz) {`,
+        "    i2c_device_config_t cfg = {",
+        "        .dev_addr_length = I2C_ADDR_BIT_LEN_7,",
+        `        .device_address = ${prefix}_I2C_ADDR,`,
+        "        .scl_speed_hz = scl_speed_hz,",
+        "    };",
+        `    return i2c_master_bus_add_device(bus, &cfg, &s_${name}_dev);`,
+        "}",
+        "",
+        "void hal_i2c_write(uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len) {",
+        "    uint8_t buf[33];",
+        "    (void)addr; /* the device handle already encodes the bus address */",
+        "    if ((size_t)len + 1u > sizeof buf) {",
+        "        return;",
+        "    }",
+        "    buf[0] = reg;",
+        "    memcpy(&buf[1], data, len);",
+        `    i2c_master_transmit(s_${name}_dev, buf, (size_t)len + 1u, ${prefix}_I2C_TIMEOUT_MS);`,
+        "}",
+        "",
+        "void hal_i2c_read(uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len) {",
+        "    (void)addr;",
+        `    i2c_master_transmit_receive(s_${name}_dev, &reg, 1, data, len, ${prefix}_I2C_TIMEOUT_MS);`,
+        "}",
+        "",
+        "void hal_delay_ms(uint32_t ms) {",
+        "    vTaskDelay(pdMS_TO_TICKS(ms));",
+        "}",
+        "",
+    ].join("\n");
+    return { path: `${name}_hal_esp32.c`, content };
+}
+/** Portable core + an ESP-IDF seam implementation for the same part. */
+export function generateEsp32Driver(json) {
+    const name = slug(json.metadata.part);
+    const prefix = prefixOf(json.metadata.part);
+    const base = generatePortableDriver(json);
+    return {
+        files: [...base.files, halImpl(name, prefix)],
+        fill_in_brief: {
+            ...base.fill_in_brief,
+            hal_setup_todo: `Bring up the ESP-IDF I2C master bus (i2c_new_master_bus with your SDA/SCL GPIOs and port), then call ${name}_esp32_bind(bus, 400000) before the first driver call. Tune ${prefix}_I2C_TIMEOUT_MS if needed.`,
+        },
+    };
+}
+//# sourceMappingURL=esp32.js.map

package/dist/codegen/esp32.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esp32.js","sourceRoot":"","sources":["../../src/codegen/esp32.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,kFAAkF;AAClF,sEAAsE;AACtE,gFAAgF;AAChF,+EAA+E;AAC/E,4DAA4D;AAG5D,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAGvD,SAAS,OAAO,CAAC,IAAY,EAAE,MAAc;IAC3C,MAAM,OAAO,GAAG;QACd,IAAI;QACJ,MAAM,MAAM,0EAA0E;QACtF,IAAI;QACJ,4EAA4E;QAC5E,6EAA6E;QAC7E,4DAA4D,IAAI,eAAe;QAC/E,gFAAgF;QAChF,KAAK;QACL,aAAa,IAAI,KAAK;QACtB,qBAAqB;QACrB,gCAAgC;QAChC,gCAAgC;QAChC,4BAA4B;QAC5B,EAAE;QACF,WAAW,MAAM,iBAAiB;QAClC,WAAW,MAAM,sBAAsB;QACvC,QAAQ;QACR,EAAE;QACF,oCAAoC,IAAI,OAAO;QAC/C,EAAE;QACF,yBAAyB,MAAM,mDAAmD;QAClF,6EAA6E;QAC7E,aAAa,IAAI,mEAAmE;QACpF,iCAAiC;QACjC,gDAAgD;QAChD,6BAA6B,MAAM,YAAY;QAC/C,uCAAuC;QACvC,QAAQ;QACR,sDAAsD,IAAI,QAAQ;QAClE,GAAG;QACH,EAAE;QACF,8EAA8E;QAC9E,sBAAsB;QACtB,yEAAyE;QACzE,0CAA0C;QAC1C,iBAAiB;QACjB,OAAO;QACP,mBAAmB;QACnB,iCAAiC;QACjC,6BAA6B,IAAI,gCAAgC,MAAM,mBAAmB;QAC1F,GAAG;QACH,EAAE;QACF,6EAA6E;QAC7E,iBAAiB;QACjB,qCAAqC,IAAI,6BAA6B,MAAM,mBAAmB;QAC/F,GAAG;QACH,EAAE;QACF,kCAAkC;QAClC,oCAAoC;QACpC,GAAG;QACH,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,cAAc,EAAE,OAAO,EAAE,CAAC;AAClD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,mBAAmB,CAAC,IAAmB;IACrD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAE1C,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,aAAa,EAAE;YACb,GAAG,IAAI,CAAC,aAAa;YACrB,cAAc,EAAE,wGAAwG,IAAI,+DAA+D,MAAM,4BAA4B;SAC9N;KACF,CAAC;AACJ,CAAC"}

package/dist/codegen/ident.d.ts

@@ -0,0 +1,10 @@
+export declare const HEX_ONLY: RegExp;
+/** Lower-snake identifier safe for filenames/symbols; "device" when empty. */
+export declare function slug(part: string): string;
+/** UPPER token safe for a macro fragment. */
+export declare function macro(s: string): string;
+/** 8-bit mask for a [msb:lsb] field. */
+export declare function fieldMask(msb: number, lsb: number): number;
+export declare function hex2(n: number): string;
+/** Macro prefix for a part, e.g. "BME280". */
+export declare function prefixOf(part: string): string;

package/dist/codegen/ident.js

@@ -0,0 +1,31 @@
+// Shared naming/geometry helpers so codegen and the driver lint agree on exactly
+// how a part name and its fields become C identifiers and mask values.
+export const HEX_ONLY = /^0x[0-9a-f]+$/i;
+/** Lower-snake identifier safe for filenames/symbols; "device" when empty. */
+export function slug(part) {
+    const s = part
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return s || "device";
+}
+/** UPPER token safe for a macro fragment. */
+export function macro(s) {
+    return s
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+/** 8-bit mask for a [msb:lsb] field. */
+export function fieldMask(msb, lsb) {
+    const width = msb - lsb + 1;
+    return (((1 << width) - 1) << lsb) & 0xff;
+}
+export function hex2(n) {
+    return `0x${n.toString(16).toUpperCase().padStart(2, "0")}`;
+}
+/** Macro prefix for a part, e.g. "BME280". */
+export function prefixOf(part) {
+    return macro(slug(part));
+}
+//# sourceMappingURL=ident.js.map

package/dist/codegen/ident.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ident.js","sourceRoot":"","sources":["../../src/codegen/ident.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,uEAAuE;AAEvE,MAAM,CAAC,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AAEzC,8EAA8E;AAC9E,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,MAAM,CAAC,GAAG,IAAI;SACX,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC3B,OAAO,CAAC,IAAI,QAAQ,CAAC;AACvB,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,OAAO,CAAC;SACL,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,GAAW;IAChD,MAAM,KAAK,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;IAC5B,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,CAAS;IAC5B,OAAO,KAAK,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3B,CAAC"}

package/dist/codegen/index.d.ts

@@ -0,0 +1,15 @@
+import type { DatasheetJson } from "../schema/types.js";
+import type { CodegenTarget, DriverArtifact } from "./types.js";
+export * from "./types.js";
+export { generatePortableDriver } from "./portable.js";
+export { generateEsp32Driver } from "./esp32.js";
+export { generateStm32Driver } from "./stm32.js";
+export { lintDriver } from "./lint.js";
+export { slug, prefixOf } from "./ident.js";
+/** arduino lands in a later session; portable + esp32 + stm32 render today. */
+export declare class UnsupportedTargetError extends Error {
+    readonly target: string;
+    constructor(target: string);
+}
+/** Render a driver for a target, dispatching to the right generator. */
+export declare function generateDriver(json: DatasheetJson, target: CodegenTarget): DriverArtifact;

package/dist/codegen/index.js

@@ -0,0 +1,30 @@
+// Public surface of the codegen layer.
+import { generateEsp32Driver } from "./esp32.js";
+import { generatePortableDriver } from "./portable.js";
+import { generateStm32Driver } from "./stm32.js";
+export * from "./types.js";
+export { generatePortableDriver } from "./portable.js";
+export { generateEsp32Driver } from "./esp32.js";
+export { generateStm32Driver } from "./stm32.js";
+export { lintDriver } from "./lint.js";
+export { slug, prefixOf } from "./ident.js";
+/** arduino lands in a later session; portable + esp32 + stm32 render today. */
+export class UnsupportedTargetError extends Error {
+    target;
+    constructor(target) {
+        super(`codegen target "${target}" is not available yet — supported targets: portable, esp32, stm32`);
+        this.target = target;
+        this.name = "UnsupportedTargetError";
+    }
+}
+/** Render a driver for a target, dispatching to the right generator. */
+export function generateDriver(json, target) {
+    if (target === "portable")
+        return generatePortableDriver(json);
+    if (target === "esp32")
+        return generateEsp32Driver(json);
+    if (target === "stm32")
+        return generateStm32Driver(json);
+    throw new UnsupportedTargetError(target);
+}
+//# sourceMappingURL=index.js.map

package/dist/codegen/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/codegen/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AAGvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjD,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5C,+EAA+E;AAC/E,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACnB;IAA5B,YAA4B,MAAc;QACxC,KAAK,CACH,mBAAmB,MAAM,oEAAoE,CAC9F,CAAC;QAHwB,WAAM,GAAN,MAAM,CAAQ;QAIxC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,UAAU,cAAc,CAC5B,IAAmB,EACnB,MAAqB;IAErB,IAAI,MAAM,KAAK,UAAU;QAAE,OAAO,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC/D,IAAI,MAAM,KAAK,OAAO;QAAE,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,MAAM,KAAK,OAAO;QAAE,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACzD,MAAM,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/dist/codegen/lint.d.ts

@@ -0,0 +1,4 @@
+import type { DatasheetJson, ValidationResult } from "../schema/types.js";
+import type { GeneratedFile } from "./types.js";
+/** Static validation of a completed driver against its source datasheet JSON. */
+export declare function lintDriver(files: GeneratedFile[], json: DatasheetJson): ValidationResult;

package/dist/codegen/lint.js

@@ -0,0 +1,112 @@
+// validate_driver — static lint over the COMPLETED driver files (see wiki:
+// mcp-tool-usage-flow, thin-hal-non-negotiable). Complements the generated
+// skeleton: it confirms the host AI finished its work (no leftover TODOs), stayed
+// on the thin-HAL seam, didn't hallucinate registers/commands, and didn't corrupt
+// the deterministic bit-field masks. Pure/text-based — no compiler needed.
+import { fieldMask, hex2, macro, prefixOf } from "./ident.js";
+// Vendor peripheral APIs that must NEVER appear in a portable/thin-HAL driver —
+// all bus access goes through the hal_* seam instead.
+const FORBIDDEN = [
+    { re: /\bHAL_(?:I2C|SPI|UART)_\w+/, api: "STM32 CubeHAL" },
+    { re: /\bLL_(?:I2C|SPI)_\w+/, api: "STM32 LL" },
+    { re: /\bi2c_master_\w+|\bspi_device_\w+|\bi2c_cmd_\w+/, api: "ESP-IDF" },
+    { re: /\bWire\.\w+|\bSPI\.(?:transfer|begin)\w*/, api: "Arduino" },
+];
+// Allowed thin-HAL seam functions (families).
+const HAL_ALLOWED = /^hal_(?:i2c_(?:read|write)|spi_(?:read|write)|delay_ms)$/;
+function balanced(text, open, close) {
+    let depth = 0;
+    for (const ch of text) {
+        if (ch === open)
+            depth++;
+        else if (ch === close) {
+            depth--;
+            if (depth < 0)
+                return false;
+        }
+    }
+    return depth === 0;
+}
+/** Static validation of a completed driver against its source datasheet JSON. */
+export function lintDriver(files, json) {
+    const errors = [];
+    const warnings = [];
+    const prefix = prefixOf(json.metadata.part);
+    const all = files.map((f) => `/* ${f.path} */\n${f.content}`).join("\n\n");
+    // Comments carry the TODO markers and prose; strip them before code-shape checks.
+    const strip = (s) => s.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
+    const code = strip(all);
+    // Thin-HAL purity applies to the driver CORE, not the seam implementation:
+    // a native target's <part>_hal_<target>.c is *where* platform calls belong.
+    const isHalImpl = (p) => /_hal_[a-z0-9]+\.(?:c|cpp)$/i.test(p);
+    const coreCode = strip(files.filter((f) => !isHalImpl(f.path)).map((f) => f.content).join("\n"));
+    // 1. No leftover TODO(driverge) — the host AI must complete every marker.
+    const todos = all.match(/TODO\(driverge\)/g);
+    if (todos) {
+        errors.push(`${todos.length} unfinished TODO(driverge) marker(s) remain`);
+    }
+    // 2. Parse-sanity: balanced braces/parens (over comment-stripped code).
+    if (!balanced(code, "{", "}"))
+        errors.push("unbalanced braces { }");
+    if (!balanced(code, "(", ")"))
+        errors.push("unbalanced parentheses ( )");
+    // 3. Thin-HAL purity — no vendor peripheral APIs in the core; only the hal_* seam.
+    for (const { re, api } of FORBIDDEN) {
+        if (re.test(coreCode))
+            errors.push(`direct ${api} call — bus access must go through the hal_* seam`);
+    }
+    for (const m of coreCode.matchAll(/\bhal_[a-z0-9_]+/g)) {
+        if (!HAL_ALLOWED.test(m[0])) {
+            errors.push(`unknown HAL function "${m[0]}" — thin HAL is hal_i2c_*/hal_spi_*/hal_delay_ms only`);
+        }
+    }
+    // 4. Register/command reference existence: any PREFIX_REG_* / PREFIX_CMD_* used
+    //    in code must be defined (in the header) — catches hallucinated symbols.
+    const defined = new Set();
+    for (const m of all.matchAll(/#define\s+([A-Z0-9_]+)/g))
+        defined.add(m[1]);
+    const refRe = new RegExp(`\\b${prefix}_(?:REG|CMD)_[A-Z0-9_]+`, "g");
+    const referenced = new Set();
+    for (const m of code.matchAll(refRe))
+        referenced.add(m[0]);
+    for (const ref of referenced) {
+        if (!defined.has(ref))
+            errors.push(`undefined register/command constant "${ref}"`);
+    }
+    // 5. Bit-field mask/shift consistency with the JSON geometry.
+    if (json.interface.kind === "register_map") {
+        checkMasks(json.interface.registers, prefix, all, errors);
+    }
+    else {
+        checkCommandCodes(json.interface.commands, prefix, all, warnings);
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+function checkMasks(registers, prefix, text, errors) {
+    for (const r of registers) {
+        for (const f of r.bitFields) {
+            const base = `${prefix}_${macro(r.name)}_${macro(f.name)}`;
+            const maskDef = new RegExp(`#define\\s+${base}_MASK\\s+(0x[0-9a-fA-F]+)`).exec(text);
+            if (maskDef) {
+                const got = Number.parseInt(maskDef[1], 16);
+                const want = fieldMask(f.msb, f.lsb);
+                if (got !== want) {
+                    errors.push(`${base}_MASK is ${maskDef[1]} but ${r.name}.${f.name} [${f.msb}:${f.lsb}] implies ${hex2(want)}`);
+                }
+            }
+            const shiftDef = new RegExp(`#define\\s+${base}_SHIFT\\s+(\\d+)`).exec(text);
+            if (shiftDef && Number(shiftDef[1]) !== f.lsb) {
+                errors.push(`${base}_SHIFT is ${shiftDef[1]} but ${r.name}.${f.name} lsb is ${f.lsb}`);
+            }
+        }
+    }
+}
+function checkCommandCodes(commands, prefix, text, warnings) {
+    for (const c of commands) {
+        const def = new RegExp(`#define\\s+${prefix}_CMD_${macro(c.name)}\\s+(0x[0-9a-fA-F]+)`).exec(text);
+        if (def && def[1].toUpperCase() !== c.code.toUpperCase()) {
+            warnings.push(`${prefix}_CMD_${macro(c.name)} is ${def[1]} but JSON code is ${c.code}`);
+        }
+    }
+}
+//# sourceMappingURL=lint.js.map

package/dist/codegen/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../src/codegen/lint.ts"],"names":[],"mappings":"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"}

package/dist/codegen/portable.d.ts

@@ -0,0 +1,4 @@
+import type { DatasheetJson } from "../schema/types.js";
+import type { DriverArtifact } from "./types.js";
+/** Render the portable thin-HAL driver skeleton for a validated datasheet. */
+export declare function generatePortableDriver(json: DatasheetJson): DriverArtifact;