@typecad/framework-arduino 0.1.0-alpha.1

package/dist/lib-declaration.d.ts

@@ -0,0 +1,35 @@
+import { type ArduinoLibrary } from "./lib-discovery.js";
+import { type CppParseResult } from "./cpp-parser.js";
+/**
+ * Result of generating a .d.ts file for an Arduino library.
+ */
+export interface GeneratedArduinoLib {
+    /** Path to the generated .d.ts file */
+    declPath: string;
+    /** The actual header file name (e.g., "Microfire_SHT3x.h") */
+    headerName: string;
+}
+/**
+ * Generate a .d.ts file for an Arduino library.
+ * Returns the path to the generated file and header info, or undefined if generation failed.
+ */
+export declare function generateArduinoLibDecl(library: ArduinoLibrary, fromFile: string): GeneratedArduinoLib | undefined;
+/**
+ * Try to generate .d.ts for a missing Arduino library import.
+ * Returns the path to the generated declaration file, or undefined if not found.
+ */
+export declare function tryGenerateArduinoLibDecl(moduleSpecifier: string, fromFile: string): string | undefined;
+/**
+ * Try to get the actual header file name for an Arduino library import.
+ * Returns the header file name (e.g., "Microfire_SHT3x.h") or undefined if not found.
+ */
+export declare function getArduinoLibraryHeaderName(moduleSpecifier: string): string | undefined;
+/**
+ * Get fully qualified class names for an Arduino library.
+ * Returns a map of simple class name to fully qualified name (e.g., "SHT3x" -> "Microfire::SHT3x").
+ */
+export declare function getArduinoLibraryClassNames(moduleSpecifier: string): Map<string, string>;
+/**
+ * Generate usage documentation for an Arduino library.
+ */
+export declare function generateUsageDocumentation(parsed: CppParseResult, libraryName: string, library?: ArduinoLibrary): string;

package/dist/lib-declaration.js

@@ -0,0 +1,399 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — Arduino Library Declaration Generator
+//
+// Generates TypeScript .d.ts declarations and usage documentation from
+// parsed Arduino library C++ headers.
+// ---------------------------------------------------------------------------
+import path from "node:path";
+import fs from "node:fs";
+import { isArduinoLibraryImport, findArduinoLibrary, findLibraryHeader } from "./lib-discovery.js";
+import { parseCppClass } from "./cpp-parser.js";
+// ---------------------------------------------------------------------------
+// Project root detection
+// ---------------------------------------------------------------------------
+/**
+ * Find the project root by looking for package.json or tsconfig.json.
+ */
+function findProjectRoot(fromFile) {
+    let currentDir = path.dirname(path.resolve(fromFile));
+    while (currentDir !== path.dirname(currentDir)) {
+        if (fs.existsSync(path.join(currentDir, "package.json")) ||
+            fs.existsSync(path.join(currentDir, "tsconfig.json"))) {
+            return currentDir;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Declaration generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate export-based declaration content for @types packages.
+ */
+function generateExportDeclaration(parsed, moduleDocstring) {
+    const lines = [];
+    // Add header comment explaining auto-generation and manual editing
+    lines.push("/**");
+    if (moduleDocstring) {
+        lines.push(` * ${moduleDocstring}`);
+    }
+    lines.push(" *");
+    lines.push(" * Auto-generated by TypeCAD from Arduino library C++ headers.");
+    lines.push(" * Arduino peripheral types (TwoWire, HardwareSerial, etc.) are mapped to TypeCAD equivalents.");
+    lines.push(" *");
+    lines.push(" * You can manually edit this file to:");
+    lines.push(" *   - Add missing methods or properties");
+    lines.push(" *   - Fix incorrect type mappings");
+    lines.push(" *   - Add JSDoc documentation");
+    lines.push(" *");
+    lines.push(" * To regenerate: delete this file and re-run TypeCAD transpile.");
+    lines.push(" */");
+    lines.push("");
+    // Export constants
+    for (const constant of parsed.constants) {
+        lines.push(`export declare const ${constant.name}: ${constant.type};`);
+    }
+    if (parsed.constants.length > 0 && parsed.classes.length > 0) {
+        lines.push("");
+    }
+    // Export classes
+    for (const cppClass of parsed.classes) {
+        lines.push(`export declare class ${cppClass.name} {`);
+        // Add constructors
+        for (const ctor of cppClass.constructors) {
+            const params = ctor.parameters
+                .filter(p => p.name)
+                .map(p => `${p.name}: ${p.type}`)
+                .join(", ");
+            lines.push(`  constructor(${params});`);
+        }
+        // Add public methods
+        const publicMethods = cppClass.methods.filter(m => m.isPublic);
+        for (const method of publicMethods) {
+            const params = method.parameters
+                .filter(p => p.name)
+                .map(p => `${p.name}: ${p.type}`)
+                .join(", ");
+            lines.push(`  ${method.name}(${params}): ${method.returnType};`);
+        }
+        lines.push("}");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Generate a .d.ts file for an Arduino library.
+ * Returns the path to the generated file and header info, or undefined if generation failed.
+ */
+export function generateArduinoLibDecl(library, fromFile) {
+    // Find the main header file
+    const headerPath = findLibraryHeader(library);
+    if (!headerPath) {
+        console.log(`  No header file found for Arduino library '${library.name}'`);
+        return undefined;
+    }
+    if (!fs.existsSync(headerPath)) {
+        console.log(`  Header file does not exist: ${headerPath}`);
+        return undefined;
+    }
+    const content = fs.readFileSync(headerPath, "utf8");
+    const parsed = parseCppClass(content);
+    if (parsed.classes.length === 0 && parsed.constants.length === 0) {
+        console.log(`  No class definitions found in '${library.name}' header`);
+        return undefined;
+    }
+    // Generate export-based declaration for @types
+    const declaration = generateExportDeclaration(parsed, `Arduino library: ${library.name}`);
+    // Find project root
+    const projectRoot = findProjectRoot(fromFile);
+    if (!projectRoot) {
+        console.log(`  Could not find project root for '${fromFile}'`);
+        return undefined;
+    }
+    // Place declarations in node_modules/@types/LibraryName/
+    // TypeScript automatically looks here for type declarations
+    const typeDir = path.join(projectRoot, "node_modules", "@types", library.name);
+    // Ensure output directory exists
+    if (!fs.existsSync(typeDir)) {
+        fs.mkdirSync(typeDir, { recursive: true });
+    }
+    const declPath = path.join(typeDir, "index.d.ts");
+    // Write the declaration file
+    fs.writeFileSync(declPath, declaration, "utf8");
+    // Also write a minimal package.json for module resolution
+    const packageJson = {
+        name: `@types/${library.name}`,
+        version: "0.0.0",
+        main: "index.d.ts",
+        types: "index.d.ts"
+    };
+    fs.writeFileSync(path.join(typeDir, "package.json"), JSON.stringify(packageJson, null, 2), "utf8");
+    // Extract the actual header file name from the path
+    const headerName = path.basename(headerPath);
+    // Generate usage documentation
+    const usageDoc = generateUsageDocumentation(parsed, library.name, library);
+    fs.writeFileSync(path.join(typeDir, "USAGE.md"), usageDoc, "utf8");
+    return { declPath, headerName };
+}
+/**
+ * Try to generate .d.ts for a missing Arduino library import.
+ * Returns the path to the generated declaration file, or undefined if not found.
+ */
+export function tryGenerateArduinoLibDecl(moduleSpecifier, fromFile) {
+    if (!isArduinoLibraryImport(moduleSpecifier)) {
+        return undefined;
+    }
+    const library = findArduinoLibrary(moduleSpecifier);
+    if (!library) {
+        return undefined;
+    }
+    console.log(`\n  Found Arduino library '${library.name}' at: ${library.path}`);
+    const result = generateArduinoLibDecl(library, fromFile);
+    if (result) {
+        console.log(`  Generated declaration: ${result.declPath}`);
+        console.log(`  Review the generated types and adjust if needed.\n`);
+        return result.declPath;
+    }
+    return undefined;
+}
+/**
+ * Try to get the actual header file name for an Arduino library import.
+ * Returns the header file name (e.g., "Microfire_SHT3x.h") or undefined if not found.
+ */
+export function getArduinoLibraryHeaderName(moduleSpecifier) {
+    if (!isArduinoLibraryImport(moduleSpecifier)) {
+        return undefined;
+    }
+    const library = findArduinoLibrary(moduleSpecifier);
+    if (!library) {
+        return undefined;
+    }
+    const headerPath = findLibraryHeader(library);
+    if (!headerPath) {
+        return undefined;
+    }
+    return path.basename(headerPath);
+}
+/**
+ * Get fully qualified class names for an Arduino library.
+ * Returns a map of simple class name to fully qualified name (e.g., "SHT3x" -> "Microfire::SHT3x").
+ */
+export function getArduinoLibraryClassNames(moduleSpecifier) {
+    const result = new Map();
+    if (!isArduinoLibraryImport(moduleSpecifier)) {
+        return result;
+    }
+    const library = findArduinoLibrary(moduleSpecifier);
+    if (!library) {
+        return result;
+    }
+    const headerPath = findLibraryHeader(library);
+    if (!headerPath || !fs.existsSync(headerPath)) {
+        return result;
+    }
+    const content = fs.readFileSync(headerPath, "utf8");
+    const parsed = parseCppClass(content);
+    for (const cppClass of parsed.classes) {
+        result.set(cppClass.name, cppClass.fullName);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Documentation generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate usage documentation for an Arduino library.
+ */
+export function generateUsageDocumentation(parsed, libraryName, library) {
+    const lines = [];
+    lines.push(`# ${libraryName} - TypeCAD Usage Guide`);
+    lines.push("");
+    if (library?.sentence) {
+        lines.push(`> ${library.sentence}`);
+        lines.push("");
+    }
+    if (library?.author) {
+        lines.push(`**Author:** ${library.author}`);
+        lines.push("");
+    }
+    lines.push("## Overview");
+    lines.push("");
+    lines.push(`This library was auto-discovered from your Arduino installation and TypeCAD`);
+    lines.push(`has generated TypeScript type definitions for it.`);
+    lines.push("");
+    if (parsed.classes.length > 0) {
+        lines.push("## Classes");
+        lines.push("");
+        for (const cppClass of parsed.classes) {
+            lines.push(`### ${cppClass.name}`);
+            lines.push("");
+            // Show C++ fully qualified name if different
+            if (cppClass.fullName !== cppClass.name) {
+                lines.push(`**C++:** \`${cppClass.fullName}\``);
+                lines.push("");
+            }
+            // Constructor
+            if (cppClass.constructors.length > 0) {
+                lines.push("#### Constructor");
+                lines.push("");
+                lines.push("```typescript");
+                lines.push(`import { ${cppClass.name} } from '${libraryName}';`);
+                lines.push("");
+                for (const ctor of cppClass.constructors) {
+                    const params = ctor.parameters
+                        .filter(p => p.name)
+                        .map(p => `${p.name}: ${p.type}`)
+                        .join(", ");
+                    lines.push(`const sensor = new ${cppClass.name}(${params});`);
+                }
+                lines.push("```");
+                lines.push("");
+            }
+            // Methods
+            if (cppClass.methods.length > 0) {
+                lines.push("#### Methods");
+                lines.push("");
+                lines.push("| Method | Parameters | Returns |");
+                lines.push("|--------|------------|---------|");
+                for (const method of cppClass.methods) {
+                    const params = method.parameters
+                        .filter(p => p.name)
+                        .map(p => `${p.name}: ${p.type}`)
+                        .join(", ");
+                    lines.push(`| \`${method.name}()\` | ${params || "none"} | ${method.returnType} |`);
+                }
+                lines.push("");
+                // Usage examples
+                lines.push("#### Example Usage");
+                lines.push("");
+                lines.push("```typescript");
+                lines.push(`import { ${cppClass.name} } from '${libraryName}';`);
+                // Add peripheral imports if needed
+                const peripheralTypes = new Set();
+                for (const method of cppClass.methods) {
+                    for (const param of method.parameters) {
+                        if (param.type === "I2C0" || param.type === "I2C1") {
+                            peripheralTypes.add("I2C0");
+                        }
+                        else if (param.type === "SPI0" || param.type === "SPI1") {
+                            peripheralTypes.add("SPI0");
+                        }
+                        else if (param.type === "UART0" || param.type === "UART1") {
+                            peripheralTypes.add("UART0");
+                        }
+                    }
+                    for (const ctor of cppClass.constructors) {
+                        for (const param of ctor.parameters) {
+                            if (param.type === "I2C0" || param.type === "I2C1") {
+                                peripheralTypes.add("I2C0");
+                            }
+                            else if (param.type === "SPI0" || param.type === "SPI1") {
+                                peripheralTypes.add("SPI0");
+                            }
+                            else if (param.type === "UART0" || param.type === "UART1") {
+                                peripheralTypes.add("UART0");
+                            }
+                        }
+                    }
+                }
+                if (peripheralTypes.size > 0) {
+                    lines.push(`import { ${[...peripheralTypes].join(", ")} } from '@typecad/board';`);
+                }
+                lines.push("");
+                // Constructor example
+                if (cppClass.constructors.length > 0) {
+                    const ctor = cppClass.constructors[0];
+                    const args = ctor.parameters
+                        .filter(p => p.name)
+                        .map(p => {
+                        // Provide example values for common types
+                        if (p.type === "I2C0")
+                            return "I2C0";
+                        if (p.type === "SPI0")
+                            return "SPI0";
+                        if (p.type === "UART0")
+                            return "UART0";
+                        if (p.type === "number")
+                            return "0x44";
+                        if (p.type === "boolean")
+                            return "true";
+                        if (p.type === "string")
+                            return '"example"';
+                        return p.name;
+                    })
+                        .join(", ");
+                    lines.push(`const device = new ${cppClass.name}(${args});`);
+                }
+                else {
+                    lines.push(`const device = new ${cppClass.name}();`);
+                }
+                lines.push("");
+                // Show common method calls
+                const beginMethod = cppClass.methods.find(m => m.name === "begin");
+                if (beginMethod) {
+                    const args = beginMethod.parameters
+                        .filter(p => p.name)
+                        .map(p => {
+                        if (p.type === "I2C0")
+                            return "I2C0";
+                        if (p.type === "SPI0")
+                            return "SPI0";
+                        if (p.type === "UART0")
+                            return "UART0";
+                        if (p.type === "number")
+                            return "0x44";
+                        if (p.type === "boolean")
+                            return "true";
+                        return p.name;
+                    })
+                        .join(", ");
+                    lines.push(`device.begin(${args});`);
+                }
+                const measureMethod = cppClass.methods.find(m => m.name === "measure" || m.name === "read");
+                if (measureMethod) {
+                    lines.push(`device.${measureMethod.name}();`);
+                }
+                const connectedMethod = cppClass.methods.find(m => m.name === "connected" || m.name === "begin");
+                if (connectedMethod && connectedMethod.returnType === "boolean") {
+                    lines.push("");
+                    lines.push(`if (device.${connectedMethod.name}()) {`);
+                    lines.push(`  // Device is ready`);
+                    lines.push(`}`);
+                }
+                lines.push("```");
+                lines.push("");
+            }
+        }
+    }
+    // Type mappings section
+    lines.push("## Type Mappings");
+    lines.push("");
+    lines.push("TypeCAD automatically maps Arduino C++ types to TypeScript equivalents:");
+    lines.push("");
+    lines.push("| Arduino C++ | TypeCAD TypeScript |");
+    lines.push("|-------------|---------------------|");
+    lines.push("| `TwoWire` / `TwoWire*` | `I2C0` |");
+    lines.push("| `SPIClass` / `SPIClass*` | `SPI0` |");
+    lines.push("| `HardwareSerial` / `HardwareSerial*` | `UART0` |");
+    lines.push("| `int`, `uint8_t`, `uint16_t`, etc. | `number` |");
+    lines.push("| `float`, `double` | `number` |");
+    lines.push("| `bool` | `boolean` |");
+    lines.push("| `String`, `const char*` | `string` |");
+    lines.push("");
+    lines.push("## Editing Type Definitions");
+    lines.push("");
+    lines.push("The generated type definitions are best-effort. You can manually edit the");
+    lines.push(`\`node_modules/@types/${libraryName}/index.d.ts\` file to:`);
+    lines.push("");
+    lines.push("- Add missing methods or properties");
+    lines.push("- Fix incorrect type mappings");
+    lines.push("- Add JSDoc documentation");
+    lines.push("");
+    lines.push("To regenerate: delete the file and re-run TypeCAD transpile.");
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/lib-discovery.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Information about an installed Arduino library.
+ */
+export interface ArduinoLibrary {
+    /** Library name (e.g., "BH1750") */
+    name: string;
+    /** Version string */
+    version?: string;
+    /** Path to the library directory */
+    path: string;
+    /** Author information */
+    author?: string;
+    /** Brief description */
+    sentence?: string;
+}
+/**
+ * Clear the library cache (useful for testing or after installing new libraries).
+ */
+export declare function clearLibraryCache(): void;
+/**
+ * Get all installed Arduino libraries using arduino-cli.
+ */
+export declare function getInstalledLibraries(): Map<string, ArduinoLibrary>;
+/**
+ * Find an Arduino library by name.
+ */
+export declare function findArduinoLibrary(name: string): ArduinoLibrary | undefined;
+/**
+ * Find the main header file for an Arduino library.
+ * Arduino libraries typically have a .h file matching the library name.
+ */
+export declare function findLibraryHeader(library: ArduinoLibrary): string | undefined;
+/**
+ * Check if a module specifier looks like an Arduino library import.
+ * Arduino library imports are bare names like "BH1750", "Servo", "Wire"
+ * (not relative paths, not npm packages).
+ */
+export declare function isArduinoLibraryImport(moduleSpecifier: string): boolean;

package/dist/lib-discovery.js

@@ -0,0 +1,189 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — Arduino Library Discovery
+//
+// Handles finding installed Arduino libraries via arduino-cli, locating
+// their headers and sources, and detecting Arduino library imports.
+// ---------------------------------------------------------------------------
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import fs from "node:fs";
+// ---------------------------------------------------------------------------
+// Library cache
+// ---------------------------------------------------------------------------
+let libraryCache = null;
+let cacheTimestamp = 0;
+const CACHE_TTL = 60000; // 1 minute cache
+/**
+ * Clear the library cache (useful for testing or after installing new libraries).
+ */
+export function clearLibraryCache() {
+    libraryCache = null;
+    cacheTimestamp = 0;
+}
+// ---------------------------------------------------------------------------
+// arduino-cli runner
+// ---------------------------------------------------------------------------
+/**
+ * Execute arduino-cli and return parsed JSON output.
+ */
+function runArduinoCli(args) {
+    try {
+        const result = spawnSync("arduino-cli", args, {
+            encoding: "utf8",
+            timeout: 30000,
+        });
+        if (result.status !== 0) {
+            return null;
+        }
+        const output = result.stdout?.trim();
+        if (!output) {
+            return null;
+        }
+        return JSON.parse(output);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Library discovery
+// ---------------------------------------------------------------------------
+/**
+ * Get all installed Arduino libraries using arduino-cli.
+ */
+export function getInstalledLibraries() {
+    // Check cache
+    const now = Date.now();
+    if (libraryCache && (now - cacheTimestamp) < CACHE_TTL) {
+        return libraryCache;
+    }
+    const libraries = new Map();
+    // Run arduino-cli lib list --format json
+    const result = runArduinoCli(["lib", "list", "--format", "json"]);
+    if (!result) {
+        libraryCache = libraries;
+        cacheTimestamp = now;
+        return libraries;
+    }
+    // Handle both formats:
+    // 1. { installed_libraries: [{ library: {...} }] } (newer arduino-cli)
+    // 2. [{ ... }] (older format or different command)
+    let libList = [];
+    if (Array.isArray(result)) {
+        libList = result;
+    }
+    else if (typeof result === "object" && result !== null) {
+        const wrapped = result;
+        if (wrapped.installed_libraries && Array.isArray(wrapped.installed_libraries)) {
+            libList = wrapped.installed_libraries.map(item => item.library);
+        }
+    }
+    for (const lib of libList) {
+        if (!lib.name || !lib.install_dir) {
+            continue;
+        }
+        const library = {
+            name: lib.name,
+            version: lib.version,
+            path: lib.install_dir,
+            author: lib.author,
+            sentence: lib.sentence,
+        };
+        // Store by name (case-insensitive key)
+        libraries.set(lib.name.toLowerCase(), library);
+        // Also store with original casing
+        if (lib.name !== lib.name.toLowerCase()) {
+            libraries.set(lib.name, library);
+        }
+    }
+    libraryCache = libraries;
+    cacheTimestamp = now;
+    return libraries;
+}
+/**
+ * Find an Arduino library by name.
+ */
+export function findArduinoLibrary(name) {
+    const libraries = getInstalledLibraries();
+    // Try exact match first, then case-insensitive
+    return libraries.get(name) || libraries.get(name.toLowerCase());
+}
+/**
+ * Find the main header file for an Arduino library.
+ * Arduino libraries typically have a .h file matching the library name.
+ */
+export function findLibraryHeader(library) {
+    const libName = library.name;
+    const libDir = library.path;
+    if (!fs.existsSync(libDir)) {
+        return undefined;
+    }
+    // Common header locations:
+    // 1. LibraryName.h in root
+    // 2. src/LibraryName.h
+    // 3. Any .h file in root if only one exists
+    const candidates = [
+        path.join(libDir, `${libName}.h`),
+        path.join(libDir, "src", `${libName}.h`),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+    }
+    // Fallback: look for any .h file in the root or src directory
+    const dirs = [libDir, path.join(libDir, "src")];
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        const headers = [];
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.toLowerCase().endsWith(".h")) {
+                headers.push(path.join(dir, entry.name));
+            }
+        }
+        // If there's only one header, use it
+        if (headers.length === 1) {
+            return headers[0];
+        }
+        // If there are multiple, prefer one matching the library name
+        for (const h of headers) {
+            if (path.basename(h, ".h").toLowerCase() === libName.toLowerCase()) {
+                return h;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if a module specifier looks like an Arduino library import.
+ * Arduino library imports are bare names like "BH1750", "Servo", "Wire"
+ * (not relative paths, not npm packages).
+ */
+export function isArduinoLibraryImport(moduleSpecifier) {
+    // Skip relative imports
+    if (moduleSpecifier.startsWith(".")) {
+        return false;
+    }
+    // Skip npm-style imports (scoped or with path separators)
+    if (moduleSpecifier.startsWith("@") || moduleSpecifier.includes("/")) {
+        return false;
+    }
+    // Skip known non-Arduino imports
+    const skipList = new Set([
+        "TypeCAD",
+        "typescript",
+        "node",
+        "fs",
+        "path",
+        "http",
+        "https",
+        "crypto",
+        "os",
+        "util",
+    ]);
+    if (skipList.has(moduleSpecifier.toLowerCase())) {
+        return false;
+    }
+    return true;
+}

package/dist/profile.d.ts

@@ -0,0 +1,8 @@
+import type { ProgramIR, Diagnostic, PlatformContext } from "@typecad/cuttlefish/api/shared";
+export interface ResolvedArduinoProfile {
+    forcedIncludes: string[];
+    symbolAliases: Record<string, string>;
+    shimLines: string[];
+    diagnostics: Diagnostic[];
+}
+export declare function resolveArduinoProfile(program: ProgramIR, platformContext?: PlatformContext): ResolvedArduinoProfile;