@typecad/cuttlefish 0.1.0-alpha.1

package/dist/libdef/header-parser.js

@@ -0,0 +1,269 @@
+/**
+ * Header parser for gen-decls.
+ *
+ * Parses C++ class declarations from .h files, capturing inheritance
+ * (`class X : public Y`) and stripping #if/#ifdef/#ifndef preprocessor
+ * blocks before parsing. See
+ * docs/superpowers/specs/2026-06-20-gen-decls-inheritance-design.md.
+ */
+/**
+ * Normalizes C++ preprocessor directives so the class parser can see the
+ * declarations. Semantics:
+ *
+ * - Include guards (`#ifndef X` immediately followed by `#define X`, and
+ *   `#pragma once`): directives dropped, all guarded content kept.
+ * - `#if` / `#ifdef` / `#ifndef` ... `#else` / `#elif` ... `#endif`: the
+ *   FIRST branch's content is kept; `#else` / `#elif` branch content is
+ *   dropped; all directives themselves are dropped. This preserves classes
+ *   that real-world headers gate behind target conditionals (e.g.
+ *   Adafruit_SPITFT wraps its whole class in `#if !defined(__AVR_ATtiny85__)`),
+ *   at the cost of possibly emitting declarations from a branch that isn't
+ *   active on the user's target. That's acceptable for .d.ts generation,
+ *   where a slightly wider API surface beats no API surface.
+ */
+export function stripPreprocessorBlocks(content) {
+    const lines = content.split(/\r?\n/);
+    const out = [];
+    // Each entry tracks one open `#if/#ifdef/#ifndef`:
+    //   - `active`: is the CURRENT branch being kept?
+    //   - `satisfied`: has ANY branch at this level already been kept?
+    // A branch is active only if no prior branch was satisfied and all outer
+    // levels are active.
+    const branches = [];
+    // Macro names for open include guards; their content is always kept.
+    const guardMacros = [];
+    const keeping = () => branches.every(b => b.active);
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        const trimmed = raw.trim();
+        const isDirective = trimmed.startsWith("#");
+        const directiveBody = isDirective ? trimmed.slice(1).trim() : "";
+        // Include-guard #endif: closes a guard (outermost open guard).
+        if (/^endif\b/.test(directiveBody) && guardMacros.length > 0 && branches.length === 0) {
+            guardMacros.pop();
+            continue;
+        }
+        // Conditional directives (only meaningful when not inside a guard-only context).
+        if (/^(if|ifdef|ifndef)\b/.test(directiveBody)) {
+            // Is this an include-guard open (#ifndef X followed by #define X)?
+            if (/^ifndef\s+(\w+)/.test(directiveBody) && guardMacros.length === branches.length) {
+                const macro = /^ifndef\s+(\w+)/.exec(directiveBody)[1];
+                let nextNonBlank;
+                for (let j = i + 1; j < lines.length; j++) {
+                    const t = lines[j].trim();
+                    if (t.length > 0) {
+                        nextNonBlank = t.startsWith("#") ? t.slice(1).trim() : t;
+                        break;
+                    }
+                }
+                if (nextNonBlank && new RegExp(`^define\\s+${macro}(\\s|$)`).test(nextNonBlank)) {
+                    guardMacros.push(macro);
+                    continue; // drop the #ifndef
+                }
+            }
+            // Real conditional: first branch is active iff outer levels keep.
+            const active = keeping();
+            branches.push({ active, satisfied: active });
+            continue;
+        }
+        // #elif / #else: switch to a new branch. Active only if outer keeps AND
+        // no prior branch at this level was satisfied.
+        if (/^(elif|else)\b/.test(directiveBody)) {
+            if (branches.length === 0)
+                continue;
+            const outerKeeping = branches.slice(0, -1).every(b => b.active);
+            const top = branches[branches.length - 1];
+            top.active = outerKeeping && !top.satisfied;
+            if (top.active)
+                top.satisfied = true;
+            continue;
+        }
+        if (/^endif\b/.test(directiveBody)) {
+            if (branches.length > 0)
+                branches.pop();
+            continue;
+        }
+        // Guard's own #define — drop it.
+        if (guardMacros.length > branches.length && /^define\s/.test(directiveBody)) {
+            continue;
+        }
+        // `#pragma once` — drop the directive.
+        if (/^pragma\s+once\b/.test(directiveBody)) {
+            continue;
+        }
+        // Non-conditional content: keep if every open branch is keeping.
+        if (keeping()) {
+            out.push(raw);
+        }
+    }
+    return out.join("\n");
+}
+/** Maps C++ types to TypeScript types (mirrors cpp-to-decl's type mapper). */
+function mapCppTypeToTs(cppType) {
+    const trimmed = cppType.trim();
+    const withoutConst = trimmed.replace(/^const\s+/, "");
+    const typeMap = {
+        "int": "number",
+        "unsigned int": "number",
+        "uint8_t": "number",
+        "uint16_t": "number",
+        "uint32_t": "number",
+        "int8_t": "number",
+        "int16_t": "number",
+        "int32_t": "number",
+        "float": "number",
+        "double": "number",
+        "bool": "boolean",
+        "void": "void",
+        "char": "string",
+        "char*": "string",
+        "const char*": "string",
+        "std::string": "string",
+        "String": "string",
+    };
+    if (typeMap[withoutConst])
+        return typeMap[withoutConst];
+    if (withoutConst.endsWith("*"))
+        return "number";
+    if (withoutConst.endsWith("&"))
+        return mapCppTypeToTs(withoutConst.slice(0, -1).trim());
+    return "any";
+}
+/** Extracts parameters from a C++ parameter list string. */
+function parseParameters(paramString) {
+    if (!paramString.trim())
+        return [];
+    const params = [];
+    for (const part of paramString.split(",")) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const withoutDefault = trimmed.split("=")[0].trim();
+        const tokens = withoutDefault.split(/\s+/);
+        if (tokens.length >= 2) {
+            // C++ lets pointer/reference markers attach to either the type
+            // (`char* label`) or the name (`char *label`), and arrays appear as a
+            // trailing `[]` on the name. Peel leading `*`/`&` and trailing `[]`
+            // off the name token back onto the type, so the emitted name is a
+            // valid TS identifier and the type still routes through
+            // mapCppTypeToTs (which maps pointers/refs appropriately).
+            let name = tokens[tokens.length - 1];
+            const typeParts = tokens.slice(0, -1);
+            const prefix = [];
+            while (/^[*&]/.test(name)) {
+                prefix.push(name[0]);
+                name = name.slice(1);
+            }
+            // Trailing array marker on the name → treat as pointer for typing.
+            let arrayMarker = "";
+            if (/\[\]$/.test(name)) {
+                arrayMarker = "*";
+                name = name.replace(/\[\]$/, "");
+            }
+            if (prefix.length > 0 || arrayMarker) {
+                typeParts.push((prefix.join("") + arrayMarker) || "");
+            }
+            params.push({
+                name,
+                type: mapCppTypeToTs(typeParts.join(" ").trim()),
+            });
+        }
+        else if (tokens.length === 1) {
+            params.push({ type: mapCppTypeToTs(tokens[0]), name: "" });
+        }
+    }
+    return params;
+}
+/**
+ * Parses a header source string into ParsedClass[]. Strips #if blocks first,
+ * then finds `class Name [: access Base] { ... }` blocks and extracts public
+ * methods + constructors.
+ */
+export function parseHeader(content) {
+    const cleaned = stripPreprocessorBlocks(content);
+    const classes = [];
+    // class Name [: (public|protected|private) Base [, access Base2 ...]] {
+    // Group 1 = class name, group 2 = optional first base name. Additional
+    // bases after the first are consumed by `(?:\s*,\s*(?:public|protected|private)\s+\w+)*`
+    // but not captured (multiple inheritance beyond the first base is a
+    // documented limitation).
+    const classRegex = /\bclass\s+(\w+)\s*(?::\s*(?:public|protected|private)\s+(\w+)(?:\s*,\s*(?:public|protected|private)\s+\w+)*)?\s*\{/g;
+    let m;
+    while ((m = classRegex.exec(cleaned)) !== null) {
+        // Skip templated classes: a `template<...>` declaration immediately
+        // precedes the class keyword on the preceding non-empty content.
+        const preceding = cleaned.slice(0, m.index).replace(/\s+$/, "");
+        if (/template\s*<[^>]*>\s*$/.test(preceding)) {
+            continue;
+        }
+        const name = m[1];
+        const baseClass = m[2];
+        const bodyStart = m.index + m[0].length;
+        // Find matching closing brace.
+        let depth = 1;
+        let bodyEnd = bodyStart;
+        for (let i = bodyStart; i < cleaned.length && depth > 0; i++) {
+            if (cleaned[i] === "{")
+                depth++;
+            else if (cleaned[i] === "}")
+                depth--;
+            bodyEnd = i;
+        }
+        const body = cleaned.slice(bodyStart, bodyEnd);
+        const cls = {
+            name,
+            methods: [],
+            constructors: [],
+            baseClass,
+            source: "header",
+        };
+        // Split body by access specifiers.
+        const normalized = body.replace(/\s+/g, " ");
+        const segments = [];
+        let isPublic = false;
+        for (const p of normalized.split(/(public:|private:|protected:)/)) {
+            const t = p.trim();
+            if (t === "public:")
+                isPublic = true;
+            else if (t === "private:" || t === "protected:")
+                isPublic = false;
+            else if (t)
+                segments.push({ text: t, isPublic });
+        }
+        for (const seg of segments) {
+            // Methods with a return type: type name(params) [const] {|;
+            const methodRe = /(\w+(?:\s*[*&])?)\s+(\w+)\s*\(([^)]*)\)\s*(?:const\s*)?(?:\{|;)/g;
+            let mm;
+            while ((mm = methodRe.exec(seg.text)) !== null) {
+                const returnType = mm[1].trim();
+                const methName = mm[2].trim();
+                const params = mm[3];
+                if (methName === name) {
+                    cls.constructors.push({ parameters: parseParameters(params) });
+                }
+                else {
+                    cls.methods.push({
+                        name: methName,
+                        returnType: mapCppTypeToTs(returnType),
+                        parameters: parseParameters(params),
+                        isPublic: seg.isPublic,
+                    });
+                }
+            }
+            // Constructors without a return type: ClassName(params) {|;
+            // (the method regex above requires a leading type token, so bare
+            // constructors are missed without this pass).
+            const ctorRe = new RegExp(`\\b(${name})\\s*\\(([^)]*)\\)\\s*(?:\\{|;)`, "g");
+            let cm;
+            while ((cm = ctorRe.exec(seg.text)) !== null) {
+                const params = cm[2];
+                const already = cls.constructors.some(c => c.parameters.length === parseParameters(params).length);
+                if (!already) {
+                    cls.constructors.push({ parameters: parseParameters(params) });
+                }
+            }
+        }
+        classes.push(cls);
+    }
+    return classes;
+}

package/dist/libdef/registry.d.ts

@@ -0,0 +1,10 @@
+import { LibraryDefinition, PlatformContext, TargetProfile } from "../types.js";
+import type { ImportIR } from "../api/index.js";
+interface ResolvedImport {
+    include: string;
+    symbolMap: Record<string, string>;
+}
+export declare function loadLibraryDefinitions(definitionsDir: string): Map<string, LibraryDefinition>;
+export declare function resolveImport(importNode: ImportIR, definitions: Map<string, LibraryDefinition>, target: TargetProfile, platformContext?: PlatformContext, importerFilePath?: string): ResolvedImport;
+export declare function generateLibdefStubs(inputFile: string, imports: ImportIR[], outDir: string): string[];
+export {};

package/dist/libdef/registry.js

@@ -0,0 +1,142 @@
+import fs from "node:fs";
+import path from "node:path";
+import { listFiles, readText } from "../utils/fs.js";
+import { toModuleKey, toPascalCase } from "../utils/strings.js";
+import { getLoadedFramework, hasLoadedFramework } from "../framework-registry.js";
+function toArchitectureFromFqbn(fqbn) {
+    if (!fqbn)
+        return undefined;
+    return fqbn.split(":")[1];
+}
+function getLibraryResolver() {
+    if (hasLoadedFramework()) {
+        const { libraryResolver } = getLoadedFramework();
+        if (libraryResolver)
+            return libraryResolver;
+    }
+    return {
+        isFrameworkLibraryImport: (_s) => false,
+        getFrameworkLibraryHeaderName: (_s) => undefined,
+    };
+}
+export function loadLibraryDefinitions(definitionsDir) {
+    const registry = new Map();
+    const files = listFiles(definitionsDir, ".libdef.json");
+    for (const filePath of files) {
+        let def;
+        try {
+            def = JSON.parse(readText(filePath));
+        }
+        catch (e) {
+            throw new Error(`Failed to parse library definition ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (!def.module || !def.include) {
+            continue;
+        }
+        registry.set(toModuleKey(def.module), def);
+    }
+    return registry;
+}
+function fallbackInclude(moduleSpecifier) {
+    const resolver = getLibraryResolver();
+    if (resolver.isFrameworkLibraryImport(moduleSpecifier)) {
+        const actualHeader = resolver.getFrameworkLibraryHeaderName(moduleSpecifier);
+        if (actualHeader) {
+            return `<${actualHeader}>`;
+        }
+    }
+    // Fallback to PascalCase conversion for other modules
+    const key = toModuleKey(moduleSpecifier);
+    const include = `${toPascalCase(key)}.h`;
+    return `<${include}>`;
+}
+function resolveLocalModuleHeader(moduleSpecifier, importerFilePath) {
+    if (!moduleSpecifier.startsWith(".")) {
+        return undefined;
+    }
+    const basePath = path.resolve(path.dirname(importerFilePath), moduleSpecifier);
+    const candidates = [
+        basePath,
+        `${basePath}.ts`,
+        `${basePath}.tsx`,
+        path.join(basePath, "index.ts"),
+        path.join(basePath, "index.tsx"),
+    ];
+    for (const candidate of candidates) {
+        if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
+            continue;
+        }
+        const extension = path.extname(candidate).toLowerCase();
+        if (extension !== ".ts" && extension !== ".tsx") {
+            continue;
+        }
+        const headerBaseName = path.basename(candidate).replace(/\.[^.]+$/, "");
+        return `"${headerBaseName}.h"`;
+    }
+    return undefined;
+}
+function conditionMatches(condition, target, context) {
+    const architecture = context?.architecture ?? toArchitectureFromFqbn(context?.frameworkData?.fqbn);
+    const fqbn = context?.frameworkData?.fqbn;
+    if (condition.target && condition.target !== target) {
+        return false;
+    }
+    if (condition.architecture && architecture !== condition.architecture.toLowerCase()) {
+        return false;
+    }
+    if (condition.fqbnIncludes && !(fqbn ?? "").toLowerCase().includes(condition.fqbnIncludes.toLowerCase())) {
+        return false;
+    }
+    return true;
+}
+export function resolveImport(importNode, definitions, target, platformContext, importerFilePath) {
+    if (importerFilePath) {
+        const localInclude = resolveLocalModuleHeader(importNode.moduleSpecifier, importerFilePath);
+        if (localInclude) {
+            return {
+                include: localInclude,
+                symbolMap: Object.fromEntries(importNode.namedImports.map((symbol) => [symbol, symbol])),
+            };
+        }
+    }
+    const key = toModuleKey(importNode.moduleSpecifier);
+    const definition = definitions.get(key);
+    if (!definition) {
+        return {
+            include: fallbackInclude(importNode.moduleSpecifier),
+            symbolMap: Object.fromEntries(importNode.namedImports.map((symbol) => [symbol, symbol])),
+        };
+    }
+    const selectedVariant = definition.variants?.find((variant) => conditionMatches(variant.when, target, platformContext));
+    const include = selectedVariant?.include ?? definition.include;
+    const mappedSymbols = selectedVariant?.symbols ?? definition.symbols ?? {};
+    return {
+        include,
+        symbolMap: {
+            ...Object.fromEntries(importNode.namedImports.map((symbol) => [symbol, symbol])),
+            ...mappedSymbols,
+        },
+    };
+}
+export function generateLibdefStubs(inputFile, imports, outDir) {
+    const created = [];
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+    for (const item of imports) {
+        const moduleKey = toModuleKey(item.moduleSpecifier);
+        const libdefPath = path.join(outDir, `${moduleKey}.libdef.json`);
+        if (!fs.existsSync(libdefPath)) {
+            const include = `<${toPascalCase(moduleKey)}.h>`;
+            const libdefContent = {
+                module: moduleKey,
+                include,
+                symbols: Object.fromEntries(item.namedImports.map((symbol) => [symbol, symbol])),
+                source: inputFile,
+            };
+            fs.writeFileSync(libdefPath, JSON.stringify(libdefContent, null, 2) + "\n", "utf8");
+            created.push(libdefPath);
+        }
+    }
+    return created;
+}

package/dist/mapping/peripheral-names.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Peripheral name mapping utilities.
+ *
+ * Delegates peripheral identifier translation (e.g. I2C0 → Wire, SPI0 → SPI)
+ * to the platform strategy. Framework packages implement `mapPeripheralIdentifier()`
+ * to provide their target-specific naming conventions.
+ */
+import type { PlatformStrategy } from "../api/shared/index.js";
+/**
+ * Maps a TypeCAD peripheral identifier to its platform-specific C++ name.
+ *
+ * Delegates to `strategy.mapPeripheralIdentifier()` when available.
+ * Returns `undefined` if the strategy does not recognize the name.
+ */
+export declare function mapPeripheralName(name: string, strategy?: PlatformStrategy): string | undefined;
+/**
+ * Renders a peripheral property access chain to a C++ expression string.
+ *
+ * Handles TypeScript stub properties on peripheral objects that don't exist
+ * directly in C++. Returns `undefined` if the chain is not a recognized
+ * peripheral property.
+ */
+export declare function renderPeripheralProperty(chain: string[], strategy?: PlatformStrategy): string | undefined;

package/dist/mapping/peripheral-names.js

@@ -0,0 +1,63 @@
+/**
+ * Peripheral name mapping utilities.
+ *
+ * Delegates peripheral identifier translation (e.g. I2C0 → Wire, SPI0 → SPI)
+ * to the platform strategy. Framework packages implement `mapPeripheralIdentifier()`
+ * to provide their target-specific naming conventions.
+ */
+// ---------------------------------------------------------------------------
+// Peripheral name mapping
+// ---------------------------------------------------------------------------
+/**
+ * Maps a TypeCAD peripheral identifier to its platform-specific C++ name.
+ *
+ * Delegates to `strategy.mapPeripheralIdentifier()` when available.
+ * Returns `undefined` if the strategy does not recognize the name.
+ */
+export function mapPeripheralName(name, strategy) {
+    if (strategy?.mapPeripheralIdentifier) {
+        const mapped = strategy.mapPeripheralIdentifier(name);
+        if (mapped)
+            return mapped;
+    }
+    // Default fallbacks if strategy doesn't provide a mapping
+    const canonical = name.toUpperCase();
+    if (canonical === "UART0")
+        return "Serial";
+    if (canonical === "I2C0")
+        return "Wire";
+    if (canonical === "SPI0")
+        return "SPI";
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Peripheral property rendering
+// ---------------------------------------------------------------------------
+/**
+ * Renders a peripheral property access chain to a C++ expression string.
+ *
+ * Handles TypeScript stub properties on peripheral objects that don't exist
+ * directly in C++. Returns `undefined` if the chain is not a recognized
+ * peripheral property.
+ */
+export function renderPeripheralProperty(chain, strategy) {
+    if (chain.length !== 2)
+        return undefined;
+    const [peripheral, property] = chain;
+    const cppPeripheral = mapPeripheralName(peripheral, strategy);
+    if (!cppPeripheral)
+        return undefined;
+    if (property === "available") {
+        return `${cppPeripheral}.${property}`;
+    }
+    if (property === "isInitialized" || property === "isConnected") {
+        return "true";
+    }
+    if (property === "busNumber" || property === "uartNumber") {
+        return "0";
+    }
+    if (property === "speed") {
+        return "100000";
+    }
+    return undefined;
+}

package/dist/mapping/source-map.d.ts

@@ -0,0 +1,46 @@
+import { GeneratedSourceMap, MappedDiagnostic, SourceMapEntry } from "../types.js";
+export declare function writeSourceMap(map: GeneratedSourceMap): string;
+export declare function readSourceMap(mapPath: string): GeneratedSourceMap;
+export declare function makeGeneratedMap(generatedFilePath: string, sourceFilePath: string, entries: SourceMapEntry[]): GeneratedSourceMap;
+export declare function mapCppLocationToTs(map: GeneratedSourceMap, cppLine: number, cppColumn: number, message?: string, cppFilePath?: string): MappedDiagnostic;
+export declare function resolveMapPath(mapFileOrGeneratedFile: string): string;
+/**
+ * Resolve source map path for a flattened Arduino sketch
+ * When a sketch is flattened, the source map needs to account for merged files
+ */
+export declare function resolveSourceMapForSketch(sketchPath: string, originalSourceMapPath?: string): string | undefined;
+/**
+ * Index of every per-file source map in a build directory, keyed by the
+ * normalized generated file path (the .cpp/.h each map covers).
+ *
+ * Native (g++) mode compiles every .cpp in the output dir, each with its
+ * own .thcppmap.json. An error can originate in any of them, so we need to
+ * resolve the correct map per error rather than relying on a single entry
+ * map.
+ */
+export type SourceMapIndex = Map<string, GeneratedSourceMap>;
+/**
+ * Load every `*.thcppmap.json` in `buildDir` (non-recursive) into an index
+ * keyed by the normalized `generatedFilePath`. Returns an empty index if the
+ * directory is missing or contains no maps.
+ */
+export declare function buildSourceMapIndex(buildDir: string): SourceMapIndex;
+/**
+ * Map a g++/compiler error back to its TypeScript source span.
+ *
+ * Selects the per-file source map whose `generatedFilePath` matches the
+ * error's `filePath`, then delegates to `mapCppLocationToTs`. If the exact
+ * generated file isn't keyed (e.g. the compiler reported a differently
+ * normalized path, or the error came from a header), falls back to a
+ * directory-wide search across every loaded map.
+ *
+ * Returns a `MappedDiagnostic` whose `mappedTsSpan` is `undefined` when no
+ * map could resolve the location (the caller should treat that as a raw
+ * C++ fallback).
+ */
+export declare function mapCppErrorToTs(index: SourceMapIndex, error: {
+    filePath: string;
+    line: number;
+    column: number;
+    message?: string;
+}): MappedDiagnostic;