@typecad/cuttlefish 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/api/shared/framework-manifest.d.ts

@@ -0,0 +1,581 @@
+import { z } from 'zod';
+declare const HAL_CATEGORIES: readonly ["gpio", "pwm", "adc", "dac", "interrupts", "tone", "timing", "power", "i2c", "spi", "uart", "pulse", "shift", "board", "wdt", "wifi", "http", "mqtt", "display"];
+export type HalCategory = typeof HAL_CATEGORIES[number];
+export declare const FrameworkManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    frameworkId: z.ZodString;
+    packageName: z.ZodString;
+    canonical: z.ZodDefault<z.ZodBoolean>;
+    displayName: z.ZodString;
+    description: z.ZodString;
+    basedOn: z.ZodOptional<z.ZodString>;
+    implementationMode: z.ZodEnum<["from-scratch", "extends-canonical", "extends-other"]>;
+    inheritsStrategyId: z.ZodOptional<z.ZodString>;
+    entrypoint: z.ZodObject<{
+        entrypointFunctionName: z.ZodString;
+        requiresLoopFunction: z.ZodBoolean;
+        sourceExtension: z.ZodEnum<["ino", "cc", "cpp", "h"]>;
+        overrideBaseName: z.ZodOptional<z.ZodString>;
+        outputSubdirectory: z.ZodOptional<z.ZodString>;
+        generateHeaderFile: z.ZodBoolean;
+        customBridgeShim: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sourceExtension: "cpp" | "ino" | "cc" | "h";
+        entrypointFunctionName: string;
+        requiresLoopFunction: boolean;
+        generateHeaderFile: boolean;
+        overrideBaseName?: string | undefined;
+        outputSubdirectory?: string | undefined;
+        customBridgeShim?: string | undefined;
+    }, {
+        sourceExtension: "cpp" | "ino" | "cc" | "h";
+        entrypointFunctionName: string;
+        requiresLoopFunction: boolean;
+        generateHeaderFile: boolean;
+        overrideBaseName?: string | undefined;
+        outputSubdirectory?: string | undefined;
+        customBridgeShim?: string | undefined;
+    }>;
+    profile: z.ZodObject<{
+        targets: z.ZodArray<z.ZodString, "many">;
+        forcedIncludes: z.ZodArray<z.ZodString, "many">;
+        symbolAliases: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        forcedIncludes: string[];
+        symbolAliases: Record<string, string>;
+        targets: string[];
+    }, {
+        forcedIncludes: string[];
+        symbolAliases: Record<string, string>;
+        targets: string[];
+    }>;
+    hal: z.ZodObject<{
+        [x: string]: z.ZodObject<{
+            supported: z.ZodBoolean;
+            unsupportedReason: z.ZodOptional<z.ZodString>;
+            ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+            partialCoverage: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        }, {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            unsupportedReason?: string | undefined;
+            partialCoverage?: boolean | undefined;
+        }>;
+    } & {
+        raw: z.ZodDefault<z.ZodObject<{
+            supported: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            supported: boolean;
+        }, {
+            supported: boolean;
+        }>>;
+    }, "strip", z.ZodObject<{
+        supported: z.ZodBoolean;
+        unsupportedReason: z.ZodOptional<z.ZodString>;
+        ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+        partialCoverage: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        partialCoverage: boolean;
+        unsupportedReason?: string | undefined;
+    }, {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        unsupportedReason?: string | undefined;
+        partialCoverage?: boolean | undefined;
+    }>, z.objectOutputType<{
+        [x: string]: z.ZodObject<{
+            supported: z.ZodBoolean;
+            unsupportedReason: z.ZodOptional<z.ZodString>;
+            ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+            partialCoverage: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        }, {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            unsupportedReason?: string | undefined;
+            partialCoverage?: boolean | undefined;
+        }>;
+    } & {
+        raw: z.ZodDefault<z.ZodObject<{
+            supported: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            supported: boolean;
+        }, {
+            supported: boolean;
+        }>>;
+    }, z.ZodObject<{
+        supported: z.ZodBoolean;
+        unsupportedReason: z.ZodOptional<z.ZodString>;
+        ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+        partialCoverage: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        partialCoverage: boolean;
+        unsupportedReason?: string | undefined;
+    }, {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        unsupportedReason?: string | undefined;
+        partialCoverage?: boolean | undefined;
+    }>, "strip">, z.objectInputType<{
+        [x: string]: z.ZodObject<{
+            supported: z.ZodBoolean;
+            unsupportedReason: z.ZodOptional<z.ZodString>;
+            ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+            partialCoverage: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        }, {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            unsupportedReason?: string | undefined;
+            partialCoverage?: boolean | undefined;
+        }>;
+    } & {
+        raw: z.ZodDefault<z.ZodObject<{
+            supported: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            supported: boolean;
+        }, {
+            supported: boolean;
+        }>>;
+    }, z.ZodObject<{
+        supported: z.ZodBoolean;
+        unsupportedReason: z.ZodOptional<z.ZodString>;
+        ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+        partialCoverage: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        partialCoverage: boolean;
+        unsupportedReason?: string | undefined;
+    }, {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        unsupportedReason?: string | undefined;
+        partialCoverage?: boolean | undefined;
+    }>, "strip">>;
+    polyfills: z.ZodObject<{
+        emitted: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            domain: z.ZodString;
+            notes: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            domain: string;
+            notes?: string | undefined;
+        }, {
+            id: string;
+            domain: string;
+            notes?: string | undefined;
+        }>, "many">;
+        suppressed: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            reason: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            reason: string;
+        }, {
+            id: string;
+            reason: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        emitted: {
+            id: string;
+            domain: string;
+            notes?: string | undefined;
+        }[];
+        suppressed: {
+            id: string;
+            reason: string;
+        }[];
+    }, {
+        emitted: {
+            id: string;
+            domain: string;
+            notes?: string | undefined;
+        }[];
+        suppressed: {
+            id: string;
+            reason: string;
+        }[];
+    }>;
+    toolchain: z.ZodObject<{
+        backend: z.ZodString;
+        operations: z.ZodObject<{
+            prepare: z.ZodBoolean;
+            compile: z.ZodBoolean;
+            upload: z.ZodBoolean;
+            monitor: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            prepare: boolean;
+            compile: boolean;
+            upload: boolean;
+            monitor: boolean;
+        }, {
+            prepare: boolean;
+            compile: boolean;
+            upload: boolean;
+            monitor: boolean;
+        }>;
+        reexportedFrom: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        backend: string;
+        operations: {
+            prepare: boolean;
+            compile: boolean;
+            upload: boolean;
+            monitor: boolean;
+        };
+        reexportedFrom?: string | undefined;
+    }, {
+        backend: string;
+        operations: {
+            prepare: boolean;
+            compile: boolean;
+            upload: boolean;
+            monitor: boolean;
+        };
+        reexportedFrom?: string | undefined;
+    }>;
+    libraryResolution: z.ZodOptional<z.ZodObject<{
+        isFrameworkLibraryImport: z.ZodBoolean;
+        getFrameworkLibraryHeaderName: z.ZodBoolean;
+        buildClassNameMap: z.ZodBoolean;
+        tryGenerateLibDecl: z.ZodBoolean;
+        reexportedFrom: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        isFrameworkLibraryImport: boolean;
+        getFrameworkLibraryHeaderName: boolean;
+        buildClassNameMap: boolean;
+        tryGenerateLibDecl: boolean;
+        reexportedFrom?: string | undefined;
+    }, {
+        isFrameworkLibraryImport: boolean;
+        getFrameworkLibraryHeaderName: boolean;
+        buildClassNameMap: boolean;
+        tryGenerateLibDecl: boolean;
+        reexportedFrom?: string | undefined;
+    }>>;
+    typeEmission: z.ZodObject<{
+        normalizeCppType: z.ZodBoolean;
+        mathHeader: z.ZodEnum<["none", "<math.h>", "<Arduino.h>"]>;
+        needsStdString: z.ZodBoolean;
+        needsStdVector: z.ZodBoolean;
+        needsIostream: z.ZodBoolean;
+        needsStdFunction: z.ZodBoolean;
+        stdlibSupport: z.ZodObject<{
+            hasVector: z.ZodBoolean;
+            hasString: z.ZodBoolean;
+            hasIostream: z.ZodBoolean;
+            hasExceptions: z.ZodBoolean;
+            hasRTTI: z.ZodBoolean;
+            recommendedArrayImpl: z.ZodEnum<["std_vector", "static_array"]>;
+            recommendedStringImpl: z.ZodEnum<["std_string", "static_string"]>;
+        }, "strip", z.ZodTypeAny, {
+            hasVector: boolean;
+            hasString: boolean;
+            hasIostream: boolean;
+            hasExceptions: boolean;
+            hasRTTI: boolean;
+            recommendedArrayImpl: "std_vector" | "static_array";
+            recommendedStringImpl: "std_string" | "static_string";
+        }, {
+            hasVector: boolean;
+            hasString: boolean;
+            hasIostream: boolean;
+            hasExceptions: boolean;
+            hasRTTI: boolean;
+            recommendedArrayImpl: "std_vector" | "static_array";
+            recommendedStringImpl: "std_string" | "static_string";
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        needsIostream: boolean;
+        needsStdString: boolean;
+        needsStdVector: boolean;
+        needsStdFunction: boolean;
+        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        normalizeCppType: boolean;
+        stdlibSupport: {
+            hasVector: boolean;
+            hasString: boolean;
+            hasIostream: boolean;
+            hasExceptions: boolean;
+            hasRTTI: boolean;
+            recommendedArrayImpl: "std_vector" | "static_array";
+            recommendedStringImpl: "std_string" | "static_string";
+        };
+    }, {
+        needsIostream: boolean;
+        needsStdString: boolean;
+        needsStdVector: boolean;
+        needsStdFunction: boolean;
+        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        normalizeCppType: boolean;
+        stdlibSupport: {
+            hasVector: boolean;
+            hasString: boolean;
+            hasIostream: boolean;
+            hasExceptions: boolean;
+            hasRTTI: boolean;
+            recommendedArrayImpl: "std_vector" | "static_array";
+            recommendedStringImpl: "std_string" | "static_string";
+        };
+    }>;
+    ambientTypes: z.ZodArray<z.ZodString, "many">;
+    conformance: z.ZodObject<{
+        hardwareTestGroups: z.ZodArray<z.ZodString, "many">;
+        halResolutionTests: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        hardwareTestGroups: string[];
+        halResolutionTests: string[];
+    }, {
+        hardwareTestGroups: string[];
+        halResolutionTests: string[];
+    }>;
+    doctor: z.ZodOptional<z.ZodObject<{
+        available: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        available: boolean;
+    }, {
+        available: boolean;
+    }>>;
+    licenses: z.ZodOptional<z.ZodObject<{
+        available: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        available: boolean;
+    }, {
+        available: boolean;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    hal: {
+        [x: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        };
+        raw?: unknown;
+    } & {
+        [k: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        };
+    };
+    packageName: string;
+    schemaVersion: 1;
+    frameworkId: string;
+    canonical: boolean;
+    displayName: string;
+    description: string;
+    implementationMode: "from-scratch" | "extends-canonical" | "extends-other";
+    entrypoint: {
+        sourceExtension: "cpp" | "ino" | "cc" | "h";
+        entrypointFunctionName: string;
+        requiresLoopFunction: boolean;
+        generateHeaderFile: boolean;
+        overrideBaseName?: string | undefined;
+        outputSubdirectory?: string | undefined;
+        customBridgeShim?: string | undefined;
+    };
+    profile: {
+        forcedIncludes: string[];
+        symbolAliases: Record<string, string>;
+        targets: string[];
+    };
+    polyfills: {
+        emitted: {
+            id: string;
+            domain: string;
+            notes?: string | undefined;
+        }[];
+        suppressed: {
+            id: string;
+            reason: string;
+        }[];
+    };
+    toolchain: {
+        backend: string;
+        operations: {
+            prepare: boolean;
+            compile: boolean;
+            upload: boolean;
+            monitor: boolean;
+        };
+        reexportedFrom?: string | undefined;
+    };
+    typeEmission: {
+        needsIostream: boolean;
+        needsStdString: boolean;
+        needsStdVector: boolean;
+        needsStdFunction: boolean;
+        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        normalizeCppType: boolean;
+        stdlibSupport: {
+            hasVector: boolean;
+            hasString: boolean;
+            hasIostream: boolean;
+            hasExceptions: boolean;
+            hasRTTI: boolean;
+            recommendedArrayImpl: "std_vector" | "static_array";
+            recommendedStringImpl: "std_string" | "static_string";
+        };
+    };
+    ambientTypes: string[];
+    conformance: {
+        hardwareTestGroups: string[];
+        halResolutionTests: string[];
+    };
+    doctor?: {
+        available: boolean;
+    } | undefined;
+    licenses?: {
+        available: boolean;
+    } | undefined;
+    basedOn?: string | undefined;
+    inheritsStrategyId?: string | undefined;
+    libraryResolution?: {
+        isFrameworkLibraryImport: boolean;
+        getFrameworkLibraryHeaderName: boolean;
+        buildClassNameMap: boolean;
+        tryGenerateLibDecl: boolean;
+        reexportedFrom?: string | undefined;
+    } | undefined;
+}, {
+    hal: {
+        [x: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            unsupportedReason?: string | undefined;
+            partialCoverage?: boolean | undefined;
+        };
+        raw?: unknown;
+    } & {
+        [k: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            unsupportedReason?: string | undefined;
+            partialCoverage?: boolean | undefined;
+        };
+    };
+    packageName: string;
+    schemaVersion: 1;
+    frameworkId: string;
+    displayName: string;
+    description: string;
+    implementationMode: "from-scratch" | "extends-canonical" | "extends-other";
+    entrypoint: {
+        sourceExtension: "cpp" | "ino" | "cc" | "h";
+        entrypointFunctionName: string;
+        requiresLoopFunction: boolean;
+        generateHeaderFile: boolean;
+        overrideBaseName?: string | undefined;
+        outputSubdirectory?: string | undefined;
+        customBridgeShim?: string | undefined;
+    };
+    profile: {
+        forcedIncludes: string[];
+        symbolAliases: Record<string, string>;
+        targets: string[];
+    };
+    polyfills: {
+        emitted: {
+            id: string;
+            domain: string;
+            notes?: string | undefined;
+        }[];
+        suppressed: {
+            id: string;
+            reason: string;
+        }[];
+    };
+    toolchain: {
+        backend: string;
+        operations: {
+            prepare: boolean;
+            compile: boolean;
+            upload: boolean;
+            monitor: boolean;
+        };
+        reexportedFrom?: string | undefined;
+    };
+    typeEmission: {
+        needsIostream: boolean;
+        needsStdString: boolean;
+        needsStdVector: boolean;
+        needsStdFunction: boolean;
+        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        normalizeCppType: boolean;
+        stdlibSupport: {
+            hasVector: boolean;
+            hasString: boolean;
+            hasIostream: boolean;
+            hasExceptions: boolean;
+            hasRTTI: boolean;
+            recommendedArrayImpl: "std_vector" | "static_array";
+            recommendedStringImpl: "std_string" | "static_string";
+        };
+    };
+    ambientTypes: string[];
+    conformance: {
+        hardwareTestGroups: string[];
+        halResolutionTests: string[];
+    };
+    doctor?: {
+        available: boolean;
+    } | undefined;
+    licenses?: {
+        available: boolean;
+    } | undefined;
+    canonical?: boolean | undefined;
+    basedOn?: string | undefined;
+    inheritsStrategyId?: string | undefined;
+    libraryResolution?: {
+        isFrameworkLibraryImport: boolean;
+        getFrameworkLibraryHeaderName: boolean;
+        buildClassNameMap: boolean;
+        tryGenerateLibDecl: boolean;
+        reexportedFrom?: string | undefined;
+    } | undefined;
+}>;
+export type FrameworkManifest = z.infer<typeof FrameworkManifestSchema>;
+/**
+ * Authoritative map of HAL op kinds that are lowered via the polyfill system
+ * rather than via `resolveHALOperation`. Keyed by op kind; value is the
+ * polyfill id that backs it.
+ *
+ * The manifest validator uses this to verify `polyfill`-declared ops: if a
+ * manifest declares `timing.set_interval: 'polyfill'`, the framework's
+ * `polyfills.emitted` list must include the polyfill id named here.
+ *
+ * Keep in sync with the transpiler's lowering routes — when a new op kind
+ * starts being routed via a polyfill instead of the HAL resolver, add it
+ * here. The set is intentionally small and stable: polyfill-routed ops are
+ * the exception, not the rule.
+ */
+export declare const POLYFILL_BACKED_OPS: Readonly<Record<string, string>>;
+/**
+ * Validates and returns a FrameworkManifest. Frameworks call this from their
+ * `framework.manifest.ts` to get both static type-checking (the parameter type
+ * is the inferred FrameworkManifest) and runtime validation (zod parse).
+ * Bad manifests throw at module-load time.
+ */
+export declare function defineFrameworkManifest(input: unknown): FrameworkManifest;
+export { HAL_CATEGORIES };