@typecad/cuttlefish 0.1.0-alpha.1

package/dist/api/shared/ir-core.d.ts

@@ -0,0 +1,363 @@
+import type { HALOpIR } from './hal-op-ir.js';
+import type { SourceSpan } from './types.js';
+/**
+ * The C++ type carried on every IR declaration field. Stored as a string at
+ * the IR level (so construction sites read naturally: `cppType: "int"`), but
+ * every *consumer* parses it once via `parseCppType` and inspects the resulting
+ * `CppTypeIR` structurally (by `kind`) instead of re-parsing with
+ * startsWith/endsWith/slice. See `cpp-type-ir.ts`.
+ *
+ * Keeping the field a string preserves readable IR construction; the structural
+ * value is realized at inspection sites, which is where the historical ad-hoc
+ * string parsing was concentrated.
+ */
+export type CppType = string;
+export interface ParameterIR {
+    name: string;
+    cppType: string;
+    defaultValue?: ExpressionIR;
+    isRest: boolean;
+    /** Ownership kind inferred from type annotation (Shared<T>, Mutable<T>, Owned<T>). */
+    ownershipKind?: 'owned' | 'shared' | 'mutable';
+}
+export type ExpressionIR = {
+    kind: "number";
+    value: number;
+    cppType?: "int" | "float" | "double";
+} | {
+    kind: "string";
+    value: string;
+} | {
+    kind: "boolean";
+    value: boolean;
+} | {
+    kind: "identifier";
+    value: string;
+} | {
+    kind: "raw";
+    value: string;
+    newClassName?: string;
+} | {
+    kind: "await";
+    value: ExpressionIR;
+} | {
+    kind: "ternary";
+    condition: ExpressionIR;
+    whenTrue: ExpressionIR;
+    whenFalse: ExpressionIR;
+} | {
+    kind: "array";
+    elementType: string;
+    elements: ExpressionIR[];
+} | {
+    kind: "string_concat";
+    parts: ExpressionIR[];
+} | {
+    kind: "template_string";
+    expression: ExpressionIR;
+} | {
+    kind: "object";
+    fields: {
+        name: string;
+        value: ExpressionIR;
+    }[];
+    cppType?: CppType;
+} | {
+    kind: "instanceof";
+    object: ExpressionIR;
+    className: string;
+} | {
+    kind: "spread_array";
+    elementType: string;
+    spreadExpr: ExpressionIR;
+    additionalElements: ExpressionIR[];
+}
+/** Binary expression: left OP right (e.g. `val + 100`, `a && b`). */
+ | {
+    kind: "binary";
+    left: ExpressionIR;
+    operator: string;
+    right: ExpressionIR;
+}
+/** Unary expression: OP operand (prefix) or operand OP (postfix). */
+ | {
+    kind: "unary";
+    operator: string;
+    operand: ExpressionIR;
+    postfix?: boolean;
+}
+/**
+ * Property access: `object.property`.
+ * Produced by `expressionToIR` for all property-read expressions so that
+ * the emitter can recognise and translate TypeCAD metadata paths like
+ * `Board.definition.mcu` without regex post-processing.
+ */
+ | {
+    kind: "property-access";
+    object: ExpressionIR;
+    property: string;
+    isStatic?: boolean;
+    isEnum?: boolean;
+    isNamespace?: boolean;
+    isPointer?: boolean;
+}
+/**
+ * A callback function (arrow function or function expression) passed as an argument.
+ * Used for interrupt handlers and other callback contexts.
+ * The emitter generates a standalone function and passes its name.
+ * debounceMs: Optional debounce delay in milliseconds (set by .debounce() chain).
+ * isInterruptHandler: True when this callback is an ISR (affects safety validation).
+ */
+ | {
+    kind: "callback";
+    params: string[];
+    statements: StatementIR[];
+    sourceSpan: SourceSpan;
+    debounceMs?: number;
+    isInterruptHandler?: boolean;
+}
+/** Arrow function or lambda expression: (params) => expression | { statements } */
+ | {
+    kind: "lambda";
+    params: ParameterIR[];
+    body: StatementIR[];
+    returnType: CppType;
+    isExpressionBody: boolean;
+}
+/** A general method call with structured argument IR (preserves callbacks/lambdas). */
+ | {
+    kind: "method-call";
+    callee: string;
+    args: ExpressionIR[];
+    isStatic?: boolean;
+    isNamespace?: boolean;
+    isPointer?: boolean;
+    restElementType?: string;
+    cppType?: string;
+}
+/** Array element access: `object[index]`. */
+ | {
+    kind: "element-access";
+    object: ExpressionIR;
+    index: ExpressionIR;
+    elementType?: string;
+}
+/** Tuple element access: `std::get<N>(object)` for std::tuple types. */
+ | {
+    kind: "tuple-access";
+    object: ExpressionIR;
+    index: number;
+}
+/** Parenthesized expression: preserves explicit grouping from TS source (e.g. `(2+3)*4`). */
+ | {
+    kind: "paren";
+    inner: ExpressionIR;
+}
+/**
+ * HAL operation used as an expression (returns a value).
+ * The framework strategy resolves the operation to a C++ expression string.
+ */
+ | {
+    kind: "hal-expr";
+    operation: HALOpIR;
+};
+export interface CallExpressionIR {
+    kind: "call";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    callee: string;
+    args: ExpressionIR[];
+    /** True when this call was originally written as `await call()` in the TS source. */
+    isAwaited?: boolean;
+}
+export interface VariableDeclarationIR {
+    kind: "var_decl";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    name: string;
+    storage: "var" | "let" | "const";
+    cppType: string;
+    initializer?: ExpressionIR;
+    /** True when the variable should be marked as volatile in C++ (prevents compiler optimization). */
+    isVolatile?: boolean;
+    /** Ownership kind inferred from type annotation (Shared<T>, Mutable<T>, Owned<T>). */
+    ownershipKind?: 'owned' | 'shared' | 'mutable';
+}
+export interface AssignmentIR {
+    kind: "assign";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    target: string;
+    operator: "=" | "+=" | "-=" | "*=" | "/=" | "%=" | "&=" | "|=" | "^=" | "<<=" | ">>=";
+    value: ExpressionIR;
+}
+export interface UpdateIR {
+    kind: "update";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    target: string;
+    operator: "++" | "--";
+    prefix: boolean;
+}
+export interface ReturnIR {
+    kind: "return";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    value?: ExpressionIR;
+    /**
+     * The C++ return type of the enclosing function, when known at IR-build
+     * time. Used by the renderer to lower `return null`/`return undefined` to a
+     * value-initialized `return {};` when the function returns a struct (a
+     * `nullptr`/`CUTTLEFISH_UNDEFINED` literal cannot convert to a struct type).
+     * Demo #14 Finding A.
+     */
+    functionReturnType?: CppType;
+}
+export interface WhileIR {
+    kind: "while";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    condition: ExpressionIR;
+    body: StatementIR[];
+}
+export interface IfIR {
+    kind: "if";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    condition: ExpressionIR;
+    thenBranch: StatementIR[];
+    elseBranch?: StatementIR[];
+}
+export interface ForIR {
+    kind: "for";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    initializer?: StatementIR;
+    condition?: ExpressionIR;
+    increment?: StatementIR;
+    body: StatementIR[];
+}
+export interface ForOfIR {
+    kind: "for_of";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    variable: StatementIR;
+    iterable: ExpressionIR;
+    body: StatementIR[];
+}
+export interface ForInIR {
+    kind: "for_in";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    variable: StatementIR;
+    object: ExpressionIR;
+    /** Field/key names of the iterated object, used to generate a key array for C++ emission */
+    keys?: string[];
+    body: StatementIR[];
+}
+export interface BreakIR {
+    kind: "break";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    label?: string;
+}
+export interface ContinueIR {
+    kind: "continue";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    label?: string;
+}
+export interface DoWhileIR {
+    kind: "do_while";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    condition: ExpressionIR;
+    body: StatementIR[];
+}
+export interface SwitchIR {
+    kind: "switch";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    expression: ExpressionIR;
+    cases: CaseIR[];
+}
+export interface CaseIR {
+    kind: "case";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    value?: ExpressionIR;
+    body: StatementIR[];
+}
+export interface TryIR {
+    kind: "try";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    tryBlock: StatementIR[];
+    catchParam?: string;
+    catchBlock?: StatementIR[];
+    finallyBlock?: StatementIR[];
+}
+export interface ThrowIR {
+    kind: "throw";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    value: ExpressionIR;
+}
+export interface LabeledIR {
+    kind: "labeled";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    label: string;
+    body: StatementIR[];
+}
+export interface BlockIR {
+    kind: "block";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    body: StatementIR[];
+}
+export interface HALOpStatementIR {
+    kind: "hal-op";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    /** The semantic hardware operation to emit. */
+    operation: HALOpIR;
+    /** When true, the operation returns a value that should be captured. */
+    returns_value: boolean;
+}
+export interface YieldIR {
+    kind: "yield";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    value?: ExpressionIR;
+    isDelegate?: boolean;
+}
+export interface SuperCallIR {
+    kind: "super_call";
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    args: ExpressionIR[];
+}
+export type StatementIR = CallExpressionIR | SuperCallIR | VariableDeclarationIR | AssignmentIR | UpdateIR | ReturnIR | WhileIR | DoWhileIR | IfIR | ForIR | ForOfIR | ForInIR | BreakIR | ContinueIR | SwitchIR | TryIR | ThrowIR | LabeledIR | BlockIR | HALOpStatementIR | YieldIR;

package/dist/api/shared/ir-core.js

@@ -0,0 +1,8 @@
+// ---------------------------------------------------------------------------
+// IR: Core expression and statement types
+//
+// Contains ExpressionIR and StatementIR (and all supporting interfaces).
+// These two union types are mutually recursive (callbacks embed statements,
+// statements embed expressions) so they must live in the same file.
+// ---------------------------------------------------------------------------
+export {};

package/dist/api/shared/ir-declarations.d.ts

@@ -0,0 +1,201 @@
+import type { SourceSpan } from './types.js';
+import type { CppType, ExpressionIR, ParameterIR, StatementIR } from './ir-core.js';
+export interface FunctionIR {
+    originalName: string;
+    isAsync: boolean;
+    returnType: CppType;
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    parameters: ParameterIR[];
+    statements: StatementIR[];
+    /** Generic type parameters (e.g. `["T"]` for `function clamp<T>(...)`). */
+    typeParameters?: string[];
+    /** C++ static_assert expressions for constrained type parameters (e.g. `"T" → "std::is_arithmetic_v<T>"`). */
+    typeParameterConstraints?: Map<string, string>;
+    /** True when the return type is a readonly mapped type — emitter adds `const`. */
+    isReadonlyReturnType?: boolean;
+    /** True when this is a generator function (function*). */
+    isGenerator?: boolean;
+    /** True when the function is exported (has `export` keyword). */
+    isExported?: boolean;
+}
+export interface StructDefIR {
+    name: string;
+    fields: {
+        name: string;
+        cppType: CppType;
+    }[];
+}
+export interface EnumIR {
+    name: string;
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    members: {
+        name: string;
+        value?: number | string;
+    }[];
+    isConst: boolean;
+}
+/**
+ * A "string enum" is a TypeScript enum whose members are all initialized to
+ * string literals, e.g. `enum Color { Red = "RED", Green = "GREEN" }`.
+ *
+ * String enums are lowered to a `namespace` of `constexpr const char*`
+ * constants so that member access (`Color::Red`) yields a `const char*`.
+ * This makes `===` comparisons against string literals and string
+ * concatenation behave like TypeScript without requiring reverse-mapping
+ * helpers or `std::to_string`.
+ *
+ * A mixed enum (some numeric, some string members) is NOT a string enum —
+ * it is emitted as a numeric `enum class` as before.
+ */
+export declare function isStringEnum(enumDef: {
+    members: {
+        value?: number | string;
+    }[];
+}): boolean;
+export interface ClassFieldIR {
+    name: string;
+    cppType: CppType;
+    visibility: "public" | "private" | "protected";
+    initializer?: ExpressionIR;
+    isStatic?: boolean;
+}
+export interface ClassConstructorIR {
+    parameters: ParameterIR[];
+    statements: StatementIR[];
+}
+export interface ClassMethodIR {
+    name: string;
+    returnType: CppType;
+    parameters: ParameterIR[];
+    statements: StatementIR[];
+    visibility: "public" | "private" | "protected";
+    isStatic: boolean;
+    isAbstract: boolean;
+    isOverride?: boolean;
+    /** Generic type parameters (e.g. `["T"]` for `method<T>(...)`). */
+    typeParameters?: string[];
+    /** True when this is a generator method. */
+    isGenerator?: boolean;
+}
+export interface ClassGetterIR {
+    name: string;
+    returnType: CppType;
+    statements: StatementIR[];
+    visibility: "public" | "private" | "protected";
+    isStatic: boolean;
+}
+export interface ClassSetterIR {
+    name: string;
+    parameter: ParameterIR;
+    statements: StatementIR[];
+    visibility: "public" | "private" | "protected";
+    isStatic: boolean;
+}
+export interface ClassIR {
+    name: string;
+    extendsClass?: string;
+    implementsInterfaces?: string[];
+    isAbstract: boolean;
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    fields: ClassFieldIR[];
+    methods: ClassMethodIR[];
+    getters: ClassGetterIR[];
+    setters: ClassSetterIR[];
+    constructor?: ClassConstructorIR;
+    typeParameters?: string[];
+    decorators?: string[];
+}
+export interface InterfaceIR {
+    name: string;
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    extendsInterfaces?: string[];
+    fields: {
+        name: string;
+        cppType: CppType;
+        isOptional: boolean;
+    }[];
+    methods: {
+        name: string;
+        returnType: CppType;
+        parameters: ParameterIR[];
+    }[];
+    /** Namespace scope for hoisted interfaces (e.g. "test_complex_types__types"). */
+    parentScope?: string;
+    /** Index signature (e.g., `[key: string]: number`). */
+    indexSignature?: {
+        keyType: string;
+        valueType: CppType;
+    };
+}
+export interface VariantStructIR {
+    name: string;
+    fields: {
+        name: string;
+        cppType: string;
+    }[];
+}
+export interface TypeAliasIR {
+    name: string;
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    cppType: string;
+    structFields?: {
+        name: string;
+        cppType: string;
+    }[];
+    variantStructs?: VariantStructIR[];
+    typeParameters?: string[];
+}
+export interface NamespaceIR {
+    name: string;
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    enums: EnumIR[];
+    classes: ClassIR[];
+    interfaces: InterfaceIR[];
+    typeAliases: TypeAliasIR[];
+    functions: FunctionIR[];
+    constants: {
+        name: string;
+        cppType: CppType;
+        value: ExpressionIR;
+        storage?: "const" | "let" | "var";
+    }[];
+    /** Reassignment statements inside the namespace (e.g. x = 5). */
+    assignments?: {
+        target: string;
+        value: ExpressionIR;
+    }[];
+    children?: NamespaceIR[];
+}
+export interface RegisterBitFieldIR {
+    /** Field name */
+    name: string;
+    /** High bit index (inclusive) */
+    hi: number;
+    /** Low bit index (inclusive) */
+    lo: number;
+    /** Width in bits (hi - lo + 1) */
+    width: number;
+}
+export interface RegisterClassIR {
+    /** Register class name (e.g. "USART1") */
+    name: string;
+    /** MMIO register address (e.g. 0x40011000) */
+    address: number;
+    /** Bit field descriptors */
+    bitFields: RegisterBitFieldIR[];
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+}

package/dist/api/shared/ir-declarations.js

@@ -0,0 +1,26 @@
+// ---------------------------------------------------------------------------
+// IR: Declaration types
+//
+// Contains IR types for top-level declarations: functions, classes,
+// interfaces, enums, structs, namespaces, type aliases, and register-mapped
+// structs. These all depend on ExpressionIR/StatementIR from ir-core.ts
+// but do not create circular references.
+// ---------------------------------------------------------------------------
+/**
+ * A "string enum" is a TypeScript enum whose members are all initialized to
+ * string literals, e.g. `enum Color { Red = "RED", Green = "GREEN" }`.
+ *
+ * String enums are lowered to a `namespace` of `constexpr const char*`
+ * constants so that member access (`Color::Red`) yields a `const char*`.
+ * This makes `===` comparisons against string literals and string
+ * concatenation behave like TypeScript without requiring reverse-mapping
+ * helpers or `std::to_string`.
+ *
+ * A mixed enum (some numeric, some string members) is NOT a string enum —
+ * it is emitted as a numeric `enum class` as before.
+ */
+export function isStringEnum(enumDef) {
+    if (enumDef.members.length === 0)
+        return false;
+    return enumDef.members.every(m => typeof m.value === "string");
+}

package/dist/api/shared/ir.d.ts

@@ -0,0 +1,85 @@
+import type { BoardConstants } from './board-resolver.js';
+import type { Diagnostic } from './types.js';
+import type { RegisteredCallback } from '../../ir/build-ir-state.js';
+export type { CppType, ParameterIR, ExpressionIR, CallExpressionIR, SuperCallIR, VariableDeclarationIR, AssignmentIR, UpdateIR, ReturnIR, WhileIR, IfIR, ForIR, ForOfIR, ForInIR, BreakIR, ContinueIR, DoWhileIR, SwitchIR, CaseIR, TryIR, ThrowIR, LabeledIR, BlockIR, HALOpStatementIR, StatementIR, } from './ir-core.js';
+export type { HALOpIR, HALOperationKind, GpioWriteOp, GpioReadOp, GpioToggleOp, GpioSetModeOp, PwmWriteOp, PwmGetFrequencyOp, PwmGetResolutionOp, AdcReadOp, AdcGetResolutionOp, AdcSetReferenceOp, AdcGetReferenceOp, AdcReadVoltageOp, DacWriteOp, InterruptAttachOp, InterruptDetachOp, TonePlayOp, ToneStopOp, TimingDelayOp, TimingDelayMicrosecondsOp, TimingMillisOp, TimingMicrosOp, TimingFreeHeapOp, TimingSetIntervalOp, TimingSetTimeoutOp, TimingClearIntervalOp, TimingClearTimeoutOp, I2cBeginOp, I2cEndOp, I2cSetClockOp, I2cBeginTransmissionOp, I2cWriteOp, I2cEndTransmissionOp, I2cRequestFromOp, I2cAvailableOp, I2cReadOp, I2cRecoverOp, SpiBeginOp, SpiEndOp, SpiTransferOp, SpibeginTransactionOp, SpiEndTransactionOp, SpiSetModeOp, SpiSetBitOrderOp, SpiCsLowOp, SpiCsHighOp, UartBeginOp, UartEndOp, UartPrintOp, UartPrintlnOp, UartPrintfOp, UartWriteOp, UartReadOp, UartPeekOp, UartAvailableOp, UartFlushOp, PulseInOp, PulseInLongOp, ShiftOutOp, ShiftInOp, BoardResolveOp, SnprintfEmitOp, RawCppOp, } from './hal-op-ir.js';
+export type { FunctionIR, StructDefIR, EnumIR, ClassFieldIR, ClassConstructorIR, ClassMethodIR, ClassGetterIR, ClassSetterIR, ClassIR, InterfaceIR, TypeAliasIR, NamespaceIR, RegisterBitFieldIR, RegisterClassIR, } from './ir-declarations.js';
+export interface ImportIR {
+    moduleSpecifier: string;
+    namedImports: string[];
+    /** For default imports: import X from "./module.js" */
+    defaultImportName?: string;
+}
+export interface ReExportIR {
+    moduleSpecifier: string;
+    /** true for `export * from`, array for `export { a, b } from` */
+    exportAll: boolean;
+    namedExports?: string[];
+}
+/**
+ * Tracks which hardware peripherals are used in the program.
+ * This enables compile-time initialization optimization.
+ */
+export interface PeripheralUsageIR {
+    /** ADC is used (analogRead on A0-A5) */
+    adc: boolean;
+    /** PWM is used (analogWrite on D3, D5, D6, D9, D10, D11) */
+    pwm: boolean;
+    /** External interrupts are used (attachInterrupt on D2, D3) */
+    externalInterrupts: boolean;
+    /** Timer0-based timing is used (millis, micros) */
+    timer0: boolean;
+    /** I2C bus is used */
+    i2c: boolean;
+    /** SPI bus is used */
+    spi: boolean;
+    /** UART/Serial is used */
+    uart: boolean;
+    /** Specific PWM pins used (for targeted timer initialization) */
+    pwmPinsUsed: Set<number>;
+    /** Specific ADC channels used */
+    adcChannelsUsed: Set<number>;
+    /** Pins configured as output */
+    outputPins: Set<number>;
+    /** Pins configured as input with pullup */
+    inputPullupPins: Set<number>;
+    /** Pins configured as input (no pullup) */
+    inputPins: Set<number>;
+    /** Pins configured as input with pulldown */
+    inputPulldownPins: Set<number>;
+    /** All pin names explicitly referenced */
+    pinsUsed: Set<string>;
+    /** Specific pins used for external interrupts */
+    interruptPinsUsed: Set<number>;
+}
+import type { StructDefIR, EnumIR, ClassIR, InterfaceIR, NamespaceIR, TypeAliasIR, RegisterClassIR, FunctionIR } from './ir-declarations.js';
+import type { StatementIR } from './ir-core.js';
+export interface ProgramIR {
+    fileName: string;
+    imports: ImportIR[];
+    reExports: ReExportIR[];
+    structs: StructDefIR[];
+    enums: EnumIR[];
+    classes: ClassIR[];
+    interfaces: InterfaceIR[];
+    namespaces: NamespaceIR[];
+    typeAliases: TypeAliasIR[];
+    /** Register-mapped structs (from @register decorator) */
+    registerClasses: RegisterClassIR[];
+    topLevelStatements: StatementIR[];
+    functions: FunctionIR[];
+    boilerplates: Set<string>;
+    diagnostics: Diagnostic[];
+    /** Compile-time constants extracted from the imported board-definition file. */
+    boardConstants?: BoardConstants;
+    /** Tracks which hardware peripherals are used (for optimized initialization) */
+    peripheralUsage?: PeripheralUsageIR;
+    /** Library includes registered by inline evaluators (e.g., "<SPI.h>", "<Wire.h>") */
+    requiredIncludes?: Set<string>;
+    /** The name of the default export, if this module has `export default <name>` */
+    defaultExportName?: string;
+    /** Registered callbacks from the HAL resolver */
+    registeredCallbacks?: RegisteredCallback[];
+    /** Map of function names to their rest parameter element types (e.g., "sum" -> "int") */
+    restParamFunctions?: Map<string, string>;
+}

package/dist/api/shared/ir.js

@@ -0,0 +1,13 @@
+// ---------------------------------------------------------------------------
+// Intermediate Representation (IR) types
+//
+// This file defines the top-level program container (ProgramIR) and
+// re-exports all IR types from the focused sub-modules:
+//
+//   ir-core.ts        — ExpressionIR, StatementIR, and supporting types
+//   ir-declarations.ts — FunctionIR, ClassIR, InterfaceIR, NamespaceIR, etc.
+//
+// Consumers can import from this file as before, or directly from the
+// sub-modules for more precise dependencies.
+// ---------------------------------------------------------------------------
+export {};