@typecad/cuttlefish 0.1.0-alpha.1

package/dist/framework-package.js

@@ -0,0 +1,58 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import { setLoadedFramework } from "./framework-registry.js";
+import { registerPlatformStrategy } from "./platform/registry.js";
+const require = createRequire(import.meta.url);
+function resolveFrameworkPackage(packageName, fromDir = process.cwd()) {
+    try {
+        const resolved = require.resolve(packageName, { paths: [path.resolve(fromDir)] });
+        return resolved;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Extract toolchain operations from a loaded framework module.
+ * Frameworks export a `Toolchain` object implementing FrameworkToolchain.
+ */
+function extractToolchain(mod) {
+    if (mod.Toolchain && typeof mod.Toolchain === "object") {
+        return mod.Toolchain;
+    }
+    return undefined;
+}
+/**
+ * Load a framework package and populate the LoadedFramework registry.
+ *
+ * The loaded module is expected to export at minimum `FrameworkStrategy`.
+ * Optional exports include `Toolchain`, `SYMBOL_KINDS`, library resolver,
+ * class name map builder, and lib declaration generator.
+ *
+ * Returns the raw module for backward compatibility.
+ */
+export function loadFrameworkPackage(packageName, fromDir = process.cwd()) {
+    const packagePath = resolveFrameworkPackage(packageName, fromDir);
+    if (!packagePath) {
+        throw new Error(`Unable to resolve framework package '${packageName}' from '${fromDir}'. ` +
+            `Install it or pass a different framework package name in your TypeCAD config.`);
+    }
+    const mod = require(packagePath);
+    // Populate the registry with the loaded framework components
+    if (mod.FrameworkStrategy) {
+        const strategy = new mod.FrameworkStrategy();
+        const framework = {
+            strategy,
+            toolchain: extractToolchain(mod),
+            libraryResolver: typeof mod.isFrameworkLibraryImport === "function" ? {
+                isFrameworkLibraryImport: mod.isFrameworkLibraryImport,
+                getFrameworkLibraryHeaderName: mod.getFrameworkLibraryHeaderName,
+            } : undefined,
+            classNameMapBuilder: typeof mod.buildClassNameMap === "function" ? mod.buildClassNameMap : undefined,
+            libDeclGenerator: typeof mod.tryGenerateLibDecl === "function" ? mod.tryGenerateLibDecl : undefined,
+        };
+        setLoadedFramework(framework);
+        registerPlatformStrategy(strategy);
+    }
+    return mod;
+}

package/dist/framework-registry.d.ts

@@ -0,0 +1,39 @@
+import type { PlatformStrategy } from "./api/shared/index.js";
+import type { CompileResult, UploadResult, ToolchainOptions } from "./api/shared/index.js";
+/**
+ * Components loaded from a framework package.
+ */
+export interface LoadedFramework {
+    /** The platform strategy (e.g. ArduinoStrategy, NativeAVRStrategy) */
+    strategy: PlatformStrategy;
+    /** Optional toolchain for compile/upload/monitor (framework-specific) */
+    toolchain?: FrameworkToolchain;
+    /** Framework library import resolution (e.g., Arduino library detection) */
+    libraryResolver?: FrameworkLibraryResolver;
+    /** Framework class name mapping for library imports */
+    classNameMapBuilder?: (imports: any[]) => Map<string, string>;
+    /** Framework library .d.ts declaration generation */
+    libDeclGenerator?: (modulePath: string, file: string) => string | undefined;
+}
+/**
+ * Resolves framework-specific library imports (e.g., Arduino libraries).
+ */
+export interface FrameworkLibraryResolver {
+    isFrameworkLibraryImport(moduleSpecifier: string): boolean;
+    getFrameworkLibraryHeaderName(moduleSpecifier: string): string | undefined;
+}
+/**
+ * Toolchain operations that a framework package may provide.
+ * Uses a generic options bag so each framework reads what it needs
+ * and ignores the rest.
+ */
+export interface FrameworkToolchain {
+    prepare?(outputDir: string, entryPoint: string): void;
+    compile(options: ToolchainOptions): CompileResult;
+    upload?(options: ToolchainOptions): UploadResult;
+    monitor?(options: ToolchainOptions): void;
+}
+export declare function setLoadedFramework(framework: LoadedFramework): void;
+export declare function getLoadedFramework(): LoadedFramework;
+export declare function hasLoadedFramework(): boolean;
+export declare function clearLoadedFramework(): void;

package/dist/framework-registry.js

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// Framework Registry
+//
+// Holds the dynamically loaded framework package components so that CLI
+// modules can access framework-specific strategy and toolchain without
+// static import coupling.
+//
+// Replaces the former FrameworkApi singleton (CP5 decoupling). After moving
+// polyfills, snprintf, and debug codegen into the CLI (CP1-CP3), the only
+// remaining framework services are the strategy and toolchain.
+//
+// The registry is populated once per transpilation and cleared between runs.
+// ---------------------------------------------------------------------------
+// ── Singleton state ────────────────────────────────────────────────────────
+let _framework;
+export function setLoadedFramework(framework) {
+    _framework = framework;
+}
+export function getLoadedFramework() {
+    if (!_framework) {
+        throw new Error("Framework not loaded. Ensure a framework package is loaded before transpilation.");
+    }
+    return _framework;
+}
+export function hasLoadedFramework() {
+    return _framework !== undefined;
+}
+export function clearLoadedFramework() {
+    _framework = undefined;
+}

package/dist/incremental-cache.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Incremental transpilation cache for persistent file change detection.
+ *
+ * NOTE: This module is currently UNUSED. The transpile pipeline does not import
+ * it because incremental builds were unsound: the pipeline wiped the cache and
+ * the output directory before loading, and even on a partial rebuild it built
+ * raw IR only for changed files, so cross-module metadata (enums, class field
+ * types, accessors, function return types) was incomplete for unchanged graph
+ * files. Re-enabling incremental builds safely requires rehydrating cached
+ * IR/metadata for EVERY file in the graph before the aggregation passes in
+ * transpile.ts, not just the changed ones.
+ *
+ * This module enables incremental builds by:
+ * 1. Tracking file content hashes across sessions
+ * 2. Detecting which files have changed
+ * 3. Building dependency graphs to identify transitive changes
+ * 4. Caching transpilation results for unchanged files
+ */
+/**
+ * Result of checking if a file needs retranspilation
+ */
+interface FileChangeStatus {
+    filePath: string;
+    /** Whether the file needs retranspilation */
+    needsRetranspile: boolean;
+    /** Reason for retranspilation */
+    reason: "changed" | "new" | "dependency-changed" | "cache-miss" | "output-missing" | "none";
+}
+/**
+ * Options for incremental cache
+ */
+interface IncrementalCacheOptions {
+    /** Path to the cache file (default: .cuttlefish-cache.json in project root) */
+    cachePath?: string;
+    /** Project root directory */
+    rootDir: string;
+    /** Whether to enable incremental builds (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Incremental transpilation cache manager
+ */
+export declare class IncrementalCache {
+    private cachePath;
+    private rootDir;
+    private enabled;
+    private cache;
+    private dirty;
+    constructor(options: IncrementalCacheOptions);
+    /**
+     * Load cache from disk, or create empty cache
+     */
+    private load;
+    /**
+     * Create an empty cache structure
+     */
+    private createEmptyCache;
+    /**
+     * Save cache to disk (if dirty)
+     */
+    save(): void;
+    /**
+     * Check if a file has changed since last cache
+     */
+    hasFileChanged(filePath: string): boolean;
+    /**
+     * Check if a file's outputs still exist
+     */
+    outputsExist(filePath: string): boolean;
+    /**
+     * Get files that need retranspilation based on changes
+     */
+    getFilesNeedingRetranspile(filePaths: string[]): FileChangeStatus[];
+    /**
+     * Update cache entry for a file
+     */
+    updateFile(filePath: string, content: string, dependencies: string[], outputs: string[]): void;
+    /**
+     * Remove a file from the cache
+     */
+    removeFile(filePath: string): void;
+    /**
+     * Get cached outputs for a file (if valid)
+     */
+    getCachedOutputs(filePath: string): string[] | null;
+    /**
+     * Clear the entire cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        fileCount: number;
+        cachePath: string;
+        createdAt: number;
+        updatedAt: number;
+    };
+    /**
+     * Check if incremental caching is enabled
+     */
+    isEnabled(): boolean;
+}
+/**
+ * Initialize the global incremental cache
+ */
+export declare function initIncrementalCache(options: IncrementalCacheOptions): IncrementalCache;
+/**
+ * Get the global incremental cache (must be initialized first)
+ */
+export declare function getIncrementalCache(): IncrementalCache | null;
+/**
+ * Save and clear the global incremental cache
+ */
+export declare function saveAndClearIncrementalCache(): void;
+export {};

package/dist/incremental-cache.js

@@ -0,0 +1,335 @@
+/**
+ * Incremental transpilation cache for persistent file change detection.
+ *
+ * NOTE: This module is currently UNUSED. The transpile pipeline does not import
+ * it because incremental builds were unsound: the pipeline wiped the cache and
+ * the output directory before loading, and even on a partial rebuild it built
+ * raw IR only for changed files, so cross-module metadata (enums, class field
+ * types, accessors, function return types) was incomplete for unchanged graph
+ * files. Re-enabling incremental builds safely requires rehydrating cached
+ * IR/metadata for EVERY file in the graph before the aggregation passes in
+ * transpile.ts, not just the changed ones.
+ *
+ * This module enables incremental builds by:
+ * 1. Tracking file content hashes across sessions
+ * 2. Detecting which files have changed
+ * 3. Building dependency graphs to identify transitive changes
+ * 4. Caching transpilation results for unchanged files
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Cache file version - increment when format changes
+ */
+const CACHE_VERSION = 1;
+function computeToolchainFingerprint() {
+    const candidates = [
+        path.join(__dirname, "transpile.js"),
+        path.join(__dirname, "transpile.ts"),
+        path.join(__dirname, "emit", "cpp-emitter.js"),
+        path.join(__dirname, "emit", "cpp-emitter.ts"),
+        path.join(__dirname, "ir", "build-ir.js"),
+        path.join(__dirname, "ir", "build-ir.ts"),
+        path.join(__dirname, "ir", "ownership-analysis.js"),
+        path.join(__dirname, "ir", "ownership-analysis.ts"),
+        path.join(__dirname, "ir", "validation-orchestrator.js"),
+        path.join(__dirname, "ir", "validation-orchestrator.ts"),
+    ];
+    const signature = candidates
+        .filter((filePath) => fs.existsSync(filePath))
+        .map((filePath) => {
+        const stat = fs.statSync(filePath);
+        return `${path.basename(filePath)}:${stat.size}:${stat.mtimeMs}`;
+    })
+        .join("|");
+    return crypto.createHash("sha256").update(signature).digest("hex").slice(0, 16);
+}
+/**
+ * Compute a hash of file content
+ */
+function computeFileHash(content) {
+    return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+/**
+ * Default cache file name
+ */
+const DEFAULT_CACHE_NAME = ".cuttlefish-cache.json";
+/**
+ * Incremental transpilation cache manager
+ */
+export class IncrementalCache {
+    constructor(options) {
+        this.dirty = false;
+        this.rootDir = path.resolve(options.rootDir);
+        this.cachePath = options.cachePath ?? path.join(this.rootDir, DEFAULT_CACHE_NAME);
+        this.enabled = options.enabled ?? true;
+        this.cache = this.load();
+    }
+    /**
+     * Load cache from disk, or create empty cache
+     */
+    load() {
+        if (!this.enabled) {
+            return this.createEmptyCache();
+        }
+        try {
+            if (fs.existsSync(this.cachePath)) {
+                const content = fs.readFileSync(this.cachePath, "utf8");
+                const data = JSON.parse(content);
+                const currentToolchainFingerprint = computeToolchainFingerprint();
+                // Validate cache version and root
+                if (data.version === CACHE_VERSION &&
+                    data.toolchainFingerprint === currentToolchainFingerprint &&
+                    path.resolve(data.rootDir) === this.rootDir) {
+                    return data;
+                }
+            }
+        }
+        catch (error) {
+            if (process.env.CUTTLEFISH_DEBUG)
+                console.error("[incremental-cache] Corrupted cache file:", error);
+        }
+        return this.createEmptyCache();
+    }
+    /**
+     * Create an empty cache structure
+     */
+    createEmptyCache() {
+        return {
+            version: CACHE_VERSION,
+            toolchainFingerprint: computeToolchainFingerprint(),
+            rootDir: this.rootDir,
+            files: {},
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+        };
+    }
+    /**
+     * Save cache to disk (if dirty)
+     */
+    save() {
+        if (!this.enabled || !this.dirty) {
+            return;
+        }
+        this.cache.updatedAt = Date.now();
+        try {
+            // Ensure directory exists
+            const dir = path.dirname(this.cachePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(this.cachePath, JSON.stringify(this.cache, null, 2), "utf8");
+            this.dirty = false;
+        }
+        catch (error) {
+            if (process.env.CUTTLEFISH_DEBUG)
+                console.error("[incremental-cache] Failed to save cache:", error);
+        }
+    }
+    /**
+     * Check if a file has changed since last cache
+     */
+    hasFileChanged(filePath) {
+        const resolved = path.resolve(filePath);
+        const entry = this.cache.files[resolved];
+        if (!entry) {
+            return true; // New file
+        }
+        // Quick check: mtime and size
+        try {
+            const stat = fs.statSync(resolved);
+            if (stat.mtimeMs !== entry.mtime || stat.size !== entry.size) {
+                // Content might have changed, verify with hash
+                const content = fs.readFileSync(resolved, "utf8");
+                const hash = computeFileHash(content);
+                return hash !== entry.hash;
+            }
+        }
+        catch {
+            return true; // File doesn't exist or error
+        }
+        return false;
+    }
+    /**
+     * Check if a file's outputs still exist
+     */
+    outputsExist(filePath) {
+        const resolved = path.resolve(filePath);
+        const entry = this.cache.files[resolved];
+        if (!entry || !entry.outputs.length) {
+            return false;
+        }
+        return entry.outputs.every((output) => fs.existsSync(output));
+    }
+    /**
+     * Get files that need retranspilation based on changes
+     */
+    getFilesNeedingRetranspile(filePaths) {
+        const results = [];
+        const changedFiles = new Set();
+        const dependents = new Set();
+        // First pass: identify directly changed files
+        for (const filePath of filePaths) {
+            const resolved = path.resolve(filePath);
+            const entry = this.cache.files[resolved];
+            if (!entry) {
+                changedFiles.add(resolved);
+                results.push({
+                    filePath: resolved,
+                    needsRetranspile: true,
+                    reason: "new",
+                });
+            }
+            else if (this.hasFileChanged(resolved)) {
+                changedFiles.add(resolved);
+                results.push({
+                    filePath: resolved,
+                    needsRetranspile: true,
+                    reason: "changed",
+                });
+            }
+            else if (!this.outputsExist(resolved)) {
+                changedFiles.add(resolved);
+                results.push({
+                    filePath: resolved,
+                    needsRetranspile: true,
+                    reason: "output-missing",
+                });
+            }
+            else {
+                results.push({
+                    filePath: resolved,
+                    needsRetranspile: false,
+                    reason: "none",
+                });
+            }
+        }
+        // Build reverse dependency map (who depends on whom)
+        const reverseDeps = new Map();
+        for (const [filePath, entry] of Object.entries(this.cache.files)) {
+            for (const dep of entry.dependencies) {
+                if (!reverseDeps.has(dep)) {
+                    reverseDeps.set(dep, new Set());
+                }
+                reverseDeps.get(dep).add(filePath);
+            }
+        }
+        // Second pass: find transitive dependents of changed files
+        const toProcess = [...changedFiles];
+        while (toProcess.length > 0) {
+            const changed = toProcess.pop();
+            const dependentsOfChanged = reverseDeps.get(changed);
+            if (dependentsOfChanged) {
+                for (const dependent of dependentsOfChanged) {
+                    if (!changedFiles.has(dependent) && filePaths.includes(dependent)) {
+                        dependents.add(dependent);
+                        toProcess.push(dependent);
+                    }
+                }
+            }
+        }
+        // Update results for dependents
+        for (const result of results) {
+            if (dependents.has(result.filePath)) {
+                result.needsRetranspile = true;
+                result.reason = "dependency-changed";
+            }
+        }
+        return results;
+    }
+    /**
+     * Update cache entry for a file
+     */
+    updateFile(filePath, content, dependencies, outputs) {
+        const resolved = path.resolve(filePath);
+        try {
+            const stat = fs.statSync(resolved);
+            const hash = computeFileHash(content);
+            this.cache.files[resolved] = {
+                hash,
+                mtime: stat.mtimeMs,
+                size: stat.size,
+                dependencies: dependencies.map((d) => path.resolve(d)),
+                outputs: outputs.map((o) => path.resolve(o)),
+            };
+            this.dirty = true;
+        }
+        catch {
+            // File doesn't exist, skip caching
+        }
+    }
+    /**
+     * Remove a file from the cache
+     */
+    removeFile(filePath) {
+        const resolved = path.resolve(filePath);
+        if (this.cache.files[resolved]) {
+            delete this.cache.files[resolved];
+            this.dirty = true;
+        }
+    }
+    /**
+     * Get cached outputs for a file (if valid)
+     */
+    getCachedOutputs(filePath) {
+        const resolved = path.resolve(filePath);
+        const entry = this.cache.files[resolved];
+        if (!entry || this.hasFileChanged(resolved) || !this.outputsExist(resolved)) {
+            return null;
+        }
+        return entry.outputs;
+    }
+    /**
+     * Clear the entire cache
+     */
+    clear() {
+        this.cache = this.createEmptyCache();
+        this.dirty = true;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return {
+            fileCount: Object.keys(this.cache.files).length,
+            cachePath: this.cachePath,
+            createdAt: this.cache.createdAt,
+            updatedAt: this.cache.updatedAt,
+        };
+    }
+    /**
+     * Check if incremental caching is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+}
+/**
+ * Global incremental cache instance (lazy-initialized)
+ */
+let globalCache = null;
+/**
+ * Initialize the global incremental cache
+ */
+export function initIncrementalCache(options) {
+    globalCache = new IncrementalCache(options);
+    return globalCache;
+}
+/**
+ * Get the global incremental cache (must be initialized first)
+ */
+export function getIncrementalCache() {
+    return globalCache;
+}
+/**
+ * Save and clear the global incremental cache
+ */
+export function saveAndClearIncrementalCache() {
+    if (globalCache) {
+        globalCache.save();
+        globalCache = null;
+    }
+}

package/dist/ir/adc-range-validation.d.ts

@@ -0,0 +1,11 @@
+import type { ProgramIR } from '../api/index.js';
+import type { BoardConstants } from '../api/shared/index.js';
+import type { Diagnostic } from '../types.js';
+/**
+ * Validate ADC range comparisons in a program.
+ *
+ * @param program - The program IR to validate
+ * @param boardConstants - Board constants containing ADC resolution
+ * @returns Array of diagnostics for ADC range issues
+ */
+export declare function validateADCRange(program: ProgramIR, boardConstants: BoardConstants | undefined): Diagnostic[];