Mistakes Cuttlefish Catches

Cuttlefish runs about 20 checks in sequence during every build. Each one produces a diagnostic with a severity (error, warning, or info), a message, and usually a suggested fix. The orchestrator is runProgramValidations().

Pin capability validation

Each pin on a board has a defined set of capabilities. The validator checks every HAL method call against the board definition:

import { A0 } from '@typecad/board-arduino-uno';

const pin = A0.asOutput();
pin.pwm();  // ERROR: A0 does not support PWM on Arduino Uno

The diagnostic includes the pin name, the requested capability, and suggests which pins do support it.

Peripheral pin conflicts

Many pins serve dual roles. On Arduino Uno:

• D13 is both a digital pin and SPI clock (SCK)
• A4 is both analog input and I2C data (SDA)
• D0/D1 are used by Serial (UART0)

Using a pin for GPIO while its peripheral is active produces a conflict diagnostic.

Pin alias conflicts

The same physical pin can be referenced by different names:

import { A4, SDA } from '@typecad/board-arduino-uno';

const analog = A4.asInput();
const i2c = SDA;  // WARNING: A4 and SDA are the same physical pin

PWM timer sharing

On AVR, PWM pins share hardware timers. The validator detects when multiple PWM pins share the same timer:

// D9 and D10 both use Timer1 on ATmega328P
const led1 = D9.asOutput();
const led2 = D10.asOutput();
led1.pwm(128);
led2.pwm(64);
// INFO: "D9, D10 share timer1 on Arduino Uno. Duty cycle can differ per pin,
//        but timer-wide PWM settings are shared across that group."

Timer0 PWM timing conflict

Timer0 drives millis() and micros() on AVR. Using PWM on D5 or D6 (Timer0-backed pins) can interfere with timing:

D5.asOutput().pwm(128);
// INFO: D5 uses Timer0 which also drives millis()/micros().
//        PWM frequency changes may affect timing accuracy.

The timer ID is detected from the board definition’s .timer field or by parsing AVR OC register naming (OC0A → timer0).

Interrupt (ISR) safety

The validator scans interrupt-handler callbacks for operations that are unsafe in interrupt context. Detection covers user-written lambdas (D2.onFalling(() => {...})) as well as HAL-authoring callback() directives — Cuttlefish tracks which callbacks are bound to interrupts across the whole program:

Platforms can customize this list via PlatformStrategy.isrUnsafeOperations().

Example

D2.asInputPullUp().onFalling(() => {
  delay(100);               // warning: delay() blocks the CPU
  Serial.println(" ISR!");  // info: Serial.println() may not work correctly
  I2C0.write(0x50, buf);    // warning: I2C0.write - I2C operations can cause lockups
});

Duplicate handler detection

Attaching multiple handlers to the same pin is also flagged:

D2.asInputPullUp().onFalling(() => { /* handler 1 */ });
D2.asInputPullUp().onFalling(() => { /* handler 2 */ });
// WARNING: Duplicate interrupt handler on pin D2

Automatic volatile inference

The classic embedded bug: a global flag set in an interrupt and polled in loop() becomes an infinite loop under -Os because the compiler caches it in a register. Cuttlefish knows which callbacks are interrupts and which globals they write — so it auto-marks shared variables volatile without any annotation:

let flag = false;

function setup() {
  D2.asInput().onFalling(() => { flag = true; });
}

function loop() {
  if (flag) { /* ... */ flag = false; }
}
// INFO: 'flag' is written in an interrupt handler and read in main code
//       — emitted as `volatile` to prevent register caching.

The emitted C++ declares volatile bool flag = false; automatically. This eliminates a class of bugs the C++ compiler cannot detect — “this function runs in interrupt context” is a call-graph property, not a function property.

Reentrancy detection

If a function is called from both an interrupt and main-thread code, an interrupt firing mid-execution can corrupt local state:

function process() { /* ... */ }

function setup() {
  D2.asInput().onFalling(() => { process(); });  // called from interrupt
}

function loop() {
  process();  // also called from main — reentrancy risk
}
// WARNING: 'process' is called from both an interrupt handler and main-thread code.

Heap allocation detection

Cuttlefish detects new expressions in any position — assignments, returns, call arguments, nested sub-expressions — not just variable declarations:

class Sensor { constructor() {} }

function setup() {
  this.sensor = new Sensor();  // detected in assignment
  process(new Sensor());       // detected in call argument
  return new Sensor();         // detected in return
}

Severity scales with the target:

• AVR/megaAVR — warning: the heap is ~1.5–1.8 KB on a Uno; heavy or churning allocation risks fragmentation. new Array<E>(n) is an error (it would need std::vector, which AVR cannot host).
• ESP32 and others — info: these targets have more RAM and a real heap, but allocations inside loop() churn the heap over time. The diagnostic suggests PSRAM for large buffers.

Memory budget validation

On AVR, the 2 KB SRAM is shared by globals, heap, and stack with no memory protection — a collision corrupts memory silently. Cuttlefish compares its static memory estimate against the board’s SRAM budget:

// 900 int32_t values = 3600 bytes on a 2048-byte SRAM target
const buf: int32_t[] = [/* ... 900 zeros ... */];
// WARNING: Estimated SRAM usage is 176% of the 2.0 KB budget
//          (statics 3.53 KB + stack ~0.03 KB = ~3.56 KB).
//          This exceeds available SRAM and will likely corrupt memory at runtime.

The estimate accounts for global variables, struct sizes, string literals, unsized arrays (element count recovered from the initializer), and call-stack depth. The board’s SRAM size is resolved from the board definition or an architecture-specific fallback.

ADC range validation

Reads beyond the board’s ADC resolution are flagged:

import { A0 } from '@typecad/board-arduino-uno';

const value = A0.asInput().readAnalog();
if (value > 1023) { /* ... */ }
// WARNING: Arduino Uno ADC is 10-bit (0-1023). Values above 1023 are unreachable.

Validation is board-data-driven — returns no diagnostic when board data is missing.

Ownership analysis

The ownership validator implements Rust-inspired rules for transpile-time validation. It is opt-in — if no ownership types appear in the program, only const-suggestion checks run.

Use-after-move

let buf: Owned = new Buffer(64);
let other = buf;       // ownership transferred
buf.read();            // ERROR: 'buf' was moved and cannot be used again
// Hint: const buf_ref: Shared = buf; // add this before the move

Assign to immutable borrow

const ref: Shared = data;
ref = newData;         // ERROR: Cannot assign to 'ref' — it is an immutable borrow
// Hint: Change to Mutable if reassignment is needed

Owned copy warning

let buf: Owned = new Buffer(64);
let copy = buf;        // INFO: Non-primitive Owned creates a C++ copy
// Hint: const copy: Shared = buf; // borrow by reference instead

Return local reference

function getData(): Shared {
  const local: Owned = new Buffer(64);
  return local;        // ERROR: Returning borrow of local variable — dangling reference
}

Const promotion

When the whole-program reassignment analysis proves a let is never written after initialization, Cuttlefish automatically emits it as const in C++ — enabling ROM placement and constant folding:

let x = 42;            // INFO: 'x' is never reassigned — emitted as `const`
// Emitted: const int x = 42;

This is information the C++ compiler cannot recover across translation units. The inverse demotion (const → non-const when a member is mutated) also applies automatically.

Borrow mismatch

function process(data: Mutable) { /* ... */ }
const readonly: Shared = buffer;
process(readonly);     // ERROR: Cannot pass Shared to Mutable parameter

Peripheral ownership

When you opt into bus ownership by calling take(), all subsequent bus access must occur within a taken section:

Double take

I2C0.take();
I2C0.take();           // ERROR: Double-take — I2C0 is already owned
// Hint: Call 'I2C0.release()' before taking it again

Unowned release

I2C0.release();        // WARNING: I2C0.release() called but bus was not taken
// Hint: Ensure you call 'I2C0.take()' before releasing

Unowned access

I2C0.take();
I2C0.release();
I2C0.write(0x50, data); // ERROR: Unowned access — I2C0 used without being taken
// Hint: Call 'const bus = I2C0.take();' and use the returned object

Leak detection

SPI0.take();
// ... end of program
// WARNING: SPI0 was taken but never released
// Hint: Call 'SPI0.release()' when finished

Bus names recognized: I2C0/I2C1, SPI0/SPI1, UART0, Wire, Serial.