@typecad/framework-arduino 0.1.0-alpha.1

package/src/index.ts

@@ -0,0 +1,37 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — Arduino framework strategy
+//
+// Provides the ArduinoStrategy implementation for Arduino framework code
+// generation. This is the main entry point for the framework-arduino package.
+// ---------------------------------------------------------------------------
+
+// Export the main strategy class
+export { ArduinoStrategy } from './strategy.js';
+
+// Export as FrameworkStrategy for consistency with framework package naming
+export { ArduinoStrategy as FrameworkStrategy } from './strategy.js';
+
+// Arduino compile/upload/monitor
+export {
+  flattenGeneratedModulesIntoSketch,
+  compileArduinoSketch,
+  uploadArduinoSketch,
+  monitorArduinoSketch,
+} from './arduino-compile.js';
+
+// Toolchain object for the framework registry
+import { flattenGeneratedModulesIntoSketch, compileArduinoSketch, uploadArduinoSketch, monitorArduinoSketch } from './arduino-compile.js';
+export const Toolchain = {
+  prepare: flattenGeneratedModulesIntoSketch,
+  compile: (options: any) => compileArduinoSketch(options.sourcePath, options.buildTarget, {
+    extraFlags: options.extraFlags,
+    defines: options.defines,
+  }),
+  upload: (options: any) => uploadArduinoSketch(options.outputDir, options.buildTarget, options.port),
+  monitor: (options: any) => monitorArduinoSketch(options.port, options.baud),
+};
+
+// Library discovery — consumed by the transpiler's dynamic module loader
+export { isArduinoLibraryImport as isFrameworkLibraryImport, getArduinoLibraryHeaderName as getFrameworkLibraryHeaderName } from './arduino-libs.js';
+export { tryGenerateArduinoLibDecl as tryGenerateLibDecl } from './arduino-libs.js';
+export { buildArduinoClassNameMap as buildClassNameMap } from './arduino-class-map.js';

package/src/lib-declaration.ts

@@ -0,0 +1,493 @@
+// ---------------------------------------------------------------------------
+// @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 { type ArduinoLibrary, isArduinoLibraryImport, findArduinoLibrary, findLibraryHeader } from "./lib-discovery.js";
+import { type CppParseResult, parseCppClass } from "./cpp-parser.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * 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;
+}
+
+// ---------------------------------------------------------------------------
+// Project root detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the project root by looking for package.json or tsconfig.json.
+ */
+function findProjectRoot(fromFile: string): string | undefined {
+  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: CppParseResult,
+  moduleDocstring?: string,
+): string {
+  const lines: string[] = [];
+  
+  // 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: ArduinoLibrary,
+  fromFile: string
+): GeneratedArduinoLib | undefined {
+  // 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: string,
+  fromFile: string
+): string | undefined {
+  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: string): string | undefined {
+  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: string): Map<string, string> {
+  const result = new Map<string, string>();
+  
+  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: CppParseResult,
+  libraryName: string,
+  library?: ArduinoLibrary
+): string {
+  const lines: string[] = [];
+  
+  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<string>();
+        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");
+}