@typecad/cuttlefish 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/safety/specifiers.js

@@ -0,0 +1,14 @@
+// Import specifiers that activate the safety engine. The safety engine was
+// merged into @typecad/cuttlefish from the former @typecad/safety package;
+// both specifiers keep working. Detection is purely by name — the module is
+// never resolved or parsed (the graph builder skips it), so the legacy
+// specifier does not require the frozen npm package to be installed.
+/** The canonical specifier for the safety authoring surface. */
+export const SAFETY_SPECIFIER = "@typecad/cuttlefish/safety";
+/** The legacy specifier from when safety was a standalone package. */
+export const LEGACY_SAFETY_SPECIFIER = "@typecad/safety";
+/** True iff an import specifier refers to the safety authoring surface. */
+export function isSafetyImportSpecifier(moduleSpecifier) {
+    return (moduleSpecifier === SAFETY_SPECIFIER ||
+        moduleSpecifier === LEGACY_SAFETY_SPECIFIER);
+}

package/dist/safety-hook.d.ts

@@ -1,8 +1,9 @@
 import type { HALOpIR, ProgramIR, RuntimePolyfillIR, Diagnostic } from "./api/shared/index.js";
 /** Context handed to transformIR. */
 export interface SafetyTransformContext {
-    /** True iff the entry file imports `safe` from @typecad/safety. The pass
-     *  uses this as a fast no-op guard. */
+    /** True iff the entry file imports `safe` from the safety authoring
+     *  surface (@typecad/cuttlefish/safety, or legacy @typecad/safety). The
+     *  pass uses this as a fast no-op guard. */
     readonly safetyInUse: boolean;
     /** Build target (e.g. "esp32", "avr"). Strategies still resolve the
      *  underlying pinMode/digitalRead symbols; the safety package is target-
@@ -30,7 +31,7 @@ export interface TranspilerSafetyHook {
     } | undefined;
     /** Lower a safe.* TS call to a HAL op. Called from an extension point in
      *  tryResolveSemanticCall (hal-plugins.ts) when the callee resolves to the
-     *  @typecad/safety package. Returns undefined if not a safety call. */
+     *  safety authoring surface. Returns undefined if not a safety call. */
     resolveSemanticCall?(callee: string, args: readonly unknown[]): HALOpIR | undefined;
     /** Provide safety runtime polyfills (mode table + voter). Called from
      *  buildEmitterContext so the polyfills participate in tree-shaking.
@@ -48,12 +49,12 @@ export interface TranspilerSafetyHook {
      *  that the caller writes to a sidecar JSON file. */
     collectSafetyMetadata?(program: ProgramIR, ctx: SafetyTransformContext): SafetyMetadata[];
 }
-/** Set the safety hook. Called by transpile.ts after dynamically loading
- *  @typecad/safety/engine. Passing null clears it. */
+/** Set the safety hook. Called by transpile.ts after loading the safety
+ *  engine. Passing null clears it. */
 export declare function setSafetyHook(hook: TranspilerSafetyHook | null): void;
-/** Get the current safety hook, or null if @typecad/safety is not loaded. */
+/** Get the current safety hook, or null if the safety engine is not loaded. */
 export declare function getSafetyHook(): TranspilerSafetyHook | null;
-/** Returns true if the safety hook is registered (i.e. @typecad/safety loaded). */
+/** Returns true if the safety hook is registered (i.e. safety engine loaded). */
 export declare function hasSafetyHook(): boolean;
 /** Get the safety hook, throwing if it's not set. Use only inside
  *  `if (hasSafetyHook())` guards. */

package/dist/safety-hook.js

@@ -1,25 +1,24 @@
 // ---------------------------------------------------------------------------
-// Safety hook — the contract cuttlefish core uses to talk to the optional
-// @typecad/safety package. Modeled on ui-hook.ts.
+// Safety hook — the contract cuttlefish core uses to talk to the safety
+// engine. Modeled on ui-hook.ts.
 //
-// @typecad/safety is an optional peer dependency. When it is installed and
-// imported by a sketch, transpile.ts calls loadSafetyEngine() which dynamic-
-// imports @typecad/safety/engine and calls registerSafetyEngine() to push an
-// implementation of this interface into the registry. When absent, every
-// hasSafetyHook() guard returns false and cuttlefish behaves as before.
+// The engine lives in this package (src/safety/engine.ts); transpile.ts calls
+// loadSafetyEngine() at the start of each run, which registers an
+// implementation of this interface. The seam is kept so the degradation paths
+// (resetSafetyEngine / __simulateSafetyAbsentForTest) stay testable.
 // ---------------------------------------------------------------------------
 // ── Module-level hook state ────────────────────────────────────────────────
 let safetyHook = null;
-/** Set the safety hook. Called by transpile.ts after dynamically loading
- *  @typecad/safety/engine. Passing null clears it. */
+/** Set the safety hook. Called by transpile.ts after loading the safety
+ *  engine. Passing null clears it. */
 export function setSafetyHook(hook) {
     safetyHook = hook;
 }
-/** Get the current safety hook, or null if @typecad/safety is not loaded. */
+/** Get the current safety hook, or null if the safety engine is not loaded. */
 export function getSafetyHook() {
     return safetyHook;
 }
-/** Returns true if the safety hook is registered (i.e. @typecad/safety loaded). */
+/** Returns true if the safety hook is registered (i.e. safety engine loaded). */
 export function hasSafetyHook() {
     return safetyHook !== null;
 }
@@ -27,8 +26,8 @@ export function hasSafetyHook() {
  *  `if (hasSafetyHook())` guards. */
 export function requireSafetyHook() {
     if (!safetyHook) {
-        throw new Error("Safety hook is not registered. This code path requires @typecad/safety " +
-            "to be installed and loaded. This should not happen — the hook is set " +
+        throw new Error("Safety hook is not registered. This code path requires the safety " +
+            "engine to be loaded. This should not happen — the hook is set " +
             "at the start of transpileFile() when safety is detected.");
     }
     return safetyHook;

package/dist/testing.d.ts

@@ -19,11 +19,8 @@ export { transpileFile } from "./transpile.js";
 export { resetUIEngine, __simulateUIAbsentForTest } from "./ui/ui-bridge.js";
 export { resetSafetyEngine, __simulateSafetyAbsentForTest } from "./safety/safety-bridge.js";
 export { setSafetyHook, hasSafetyHook } from "./safety-hook.js";
-export { scaffoldProject, normalizeProjectName, KNOWN_BOARDS, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, runInitWizard, } from "./create/index.js";
-export type { InitProjectOptions } from "./create/index.js";
-export { scaffoldBoardPackages, parseBoardSpec, safeParseBoardSpec, stripJsonc, } from "./create/index.js";
-export type { BoardSpec, ScaffoldBoardResult } from "./create/index.js";
-export { BoardGenerators } from "./create/index.js";
+export { scaffoldProject, normalizeProjectName, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterProgram, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, runCreateWizard, } from "./create/index.js";
+export type { CreateProjectOptions } from "./create/index.js";
 export { buildCallGraph, getReachableSymbols } from "./ir/call-graph.js";
 export { detectEntryPoints, detectExportedEntryPoints } from "./ir/entry-points.js";
 export { analyzeReachability, getReachabilityStats } from "./ir/reachability.js";
@@ -37,6 +34,8 @@ export type { ESLintError } from "./eslint-check.js";
 export { checkLintCache, recordLintSuccess, invalidateLint, computeLintFingerprint, resolveEslintConfigPath, } from "./lint-cache.js";
 export type { LintFingerprint, GateCacheResult } from "./lint-cache.js";
 export { runSemanticGates } from "./orchestrator/type-checker.js";
+export { readGeneratedBoardConstants } from "./ir/board-resolver.js";
+export { pinEntryIndexForNumber } from "./ir/pin-capability-validation.js";
 export { canonicalize, buildSemanticFacts, } from "./orchestrator/semantic-facts.js";
 export type { CanonicalType, SemanticFacts, FactStore, ValueCategory, Lifetime, Nullable, SemanticOrigin, AnalysisResult, BindingResolver, } from "./orchestrator/semantic-facts.js";
 export { verifyFacts } from "./orchestrator/semantic-facts-verifier.js";
@@ -46,7 +45,7 @@ export { parseCommandLine } from "./utils/cli.js";
 export { parseHeader, stripPreprocessorBlocks } from "./libdef/header-parser.js";
 export { BaseClassResolver, buildClassIndex } from "./libdef/base-class-resolver.js";
 export type { ResolveResult } from "./libdef/base-class-resolver.js";
-export { generateDecl, generateDeclsForDirectory, generateComponentDeclsForProject } from "./libdef/cpp-to-decl.js";
+export { generateDecl, generateDeclsForDirectory } from "./libdef/cpp-to-decl.js";
 export { renderExprAsText } from "./ir/render-expr.js";
 export { contextStorage, CompilationContext } from "./ir/build-ir-state.js";
 export type { ExpressionIR } from "./api/index.js";

package/dist/testing.js

@@ -23,10 +23,7 @@ export { resetUIEngine, __simulateUIAbsentForTest } from "./ui/ui-bridge.js";
 export { resetSafetyEngine, __simulateSafetyAbsentForTest } from "./safety/safety-bridge.js";
 export { setSafetyHook, hasSafetyHook } from "./safety-hook.js";
 // ── Project scaffolding ──────────────────────────────────────────────────────
-export { scaffoldProject, normalizeProjectName, KNOWN_BOARDS, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, runInitWizard, } from "./create/index.js";
-// ── Board codegen (`cuttlefish board add`) ───────────────────────────────────
-export { scaffoldBoardPackages, parseBoardSpec, safeParseBoardSpec, stripJsonc, } from "./create/index.js";
-export { BoardGenerators } from "./create/index.js";
+export { scaffoldProject, normalizeProjectName, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterProgram, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, runCreateWizard, } from "./create/index.js";
 // ── Tree-shaking & reachability ──────────────────────────────────────────────
 export { buildCallGraph, getReachableSymbols } from "./ir/call-graph.js";
 export { detectEntryPoints, detectExportedEntryPoints } from "./ir/entry-points.js";
@@ -43,6 +40,9 @@ export { runEslintCheck } from "./eslint-check.js";
 export { checkLintCache, recordLintSuccess, invalidateLint, computeLintFingerprint, resolveEslintConfigPath, } from "./lint-cache.js";
 // ── Semantic gates (TypeChecker-based) ──────────────────────────────────────
 export { runSemanticGates } from "./orchestrator/type-checker.js";
+// ── Board constants / pin capability internals ──────────────────────────────
+export { readGeneratedBoardConstants } from "./ir/board-resolver.js";
+export { pinEntryIndexForNumber } from "./ir/pin-capability-validation.js";
 export { canonicalize, buildSemanticFacts, } from "./orchestrator/semantic-facts.js";
 export { verifyFacts } from "./orchestrator/semantic-facts-verifier.js";
 // ── Watch & CLI utilities ───────────────────────────────────────────────────
@@ -50,7 +50,7 @@ export { discoverWatchDirs, isRelevantChange } from "./watch.js";
 export { parseCommandLine } from "./utils/cli.js";
 export { parseHeader, stripPreprocessorBlocks } from "./libdef/header-parser.js";
 export { BaseClassResolver, buildClassIndex } from "./libdef/base-class-resolver.js";
-export { generateDecl, generateDeclsForDirectory, generateComponentDeclsForProject } from "./libdef/cpp-to-decl.js";
+export { generateDecl, generateDeclsForDirectory } from "./libdef/cpp-to-decl.js";
 // ── IR rendering internals (for fail-closed regression tests) ───────────────
 export { renderExprAsText } from "./ir/render-expr.js";
 export { contextStorage, CompilationContext } from "./ir/build-ir-state.js";

package/dist/transpile/resolution.d.ts

@@ -18,7 +18,7 @@ export interface TranspileGraphResult {
     /** `.ui.html` modules discovered during graph build, keyed by resolved path. */
     uiModules: Set<string>;
 }
-export declare function resolveImport(fromFile: string, moduleSpecifier: string, boardPackage?: string): {
+export declare function resolveImport(fromFile: string, moduleSpecifier: string, boardTarget?: string): {
     sourcePath: string;
     npmPackage?: ResolvedNpmPackage;
     uiModule?: boolean;

package/dist/transpile/resolution.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { findGeneratedBoard } from "../ir/board-resolver.js";
 function resolveLocalImport(fromFile, moduleSpecifier) {
     if (!moduleSpecifier.startsWith(".")) {
         return undefined;
@@ -179,13 +180,19 @@ function resolveNpmPackageImport(fromFile, moduleSpecifier) {
         moduleKey,
     };
 }
-export function resolveImport(fromFile, moduleSpecifier, boardPackage) {
+export function resolveImport(fromFile, moduleSpecifier, boardTarget) {
     let effectiveSpecifier = moduleSpecifier;
-    // The `@typecad/board` virtual import resolves to the configured board package.
-    // (Case-insensitive so the documented mixed-case form is treated identically.)
-    if (moduleSpecifier.toLowerCase() === "@typecad/board" && boardPackage) {
-        effectiveSpecifier = boardPackage;
+    // The `@typecad/board` virtual import resolves to the project-local
+    // generated board module (.cuttlefish/board.ts) when one exists — the
+    // config's board target materialized by boardgen. Falls through to the
+    // package-based path otherwise (transition; board packages are going away).
+    if (moduleSpecifier.toLowerCase() === "@typecad/board") {
+        const generated = findGeneratedBoard(fromFile);
+        if (generated) {
+            return { sourcePath: generated.boardTs };
+        }
     }
+    void boardTarget;
     const localResolved = resolveLocalImport(fromFile, effectiveSpecifier);
     if (localResolved) {
         // .ui.html files resolve as UI modules, not TypeScript sources. Only set
@@ -271,12 +278,14 @@ export function detectNativeCppModule(fromFile, moduleSpecifier) {
 export function isCuttlefishSDKPath(filePath) {
     const normalized = filePath.replace(/\\/g, "/");
     return (/\/code\/core\//.test(normalized) ||
-        /\/code\/board-/.test(normalized) ||
-        /\/packages\/board-/.test(normalized) ||
         /\/packages\/expect\//.test(normalized) ||
         /\/packages\/cuttlefish\//.test(normalized) ||
-        /\/node_modules\/@typecad\/board-/.test(normalized) ||
         /\/node_modules\/@typecad\/core\//.test(normalized) ||
         /\/node_modules\/@typecad\/expect\//.test(normalized) ||
-        /\/node_modules\/@typecad\/cuttlefish\//.test(normalized));
+        /\/node_modules\/@typecad\/cuttlefish\//.test(normalized) ||
+        // The generated project-local board module: like @typecad/hal, its source
+        // exists for pin resolution (halInstances / board constants), never for
+        // C++ emission — transpiling it would treat LED/PA5 as cross-module
+        // imports instead of compile-time pin facts.
+        /\/\.cuttlefish\/board\.ts$/.test(normalized));
 }

package/dist/transpile/test-pins.d.ts

@@ -0,0 +1,18 @@
+export interface TestPinsFile {
+    pins?: Record<string, string | string[]>;
+    facts?: Record<string, number>;
+}
+/** Read and parse a project's test-pins.json. Returns undefined when absent. */
+export declare function readTestPinsFile(projectDir: string): TestPinsFile | undefined;
+/**
+ * Build the generated module's source: role consts re-exported from the
+ * board package. Used by the editor-support generator
+ * (.cuttlefish/test-pins.ts — see config-loader's generateVirtualTypeDeclaration)
+ * so the language server resolves the '@typecad/test-pins' specifier.
+ * Hardware runs do NOT transpile this module: the @typecad/expect
+ * preprocessor substitutes role identifiers in test sources with the
+ * board's real pin symbols before the transpiler runs (the HAL resolves
+ * pins through board-package metadata, not through transpiled modules).
+ * Returns undefined when the board declares no usable roles.
+ */
+export declare function buildTestPinsModuleContent(boardTarget: string, data: TestPinsFile): string | undefined;

package/dist/transpile/test-pins.js

@@ -0,0 +1,142 @@
+// ---------------------------------------------------------------------------
+// @typecad/test-pins — board test-pin role data
+//
+// Boards describe their testable pins declaratively in a `test-pins.json`
+// shipped next to their package.json. Test suites import stable role names
+// from the '@typecad/test-pins' virtual module:
+//
+//   import { GPIO_OUT, PWM_PIN } from '@typecad/test-pins';
+//
+// At hardware-test time the @typecad/expect preprocessor substitutes each
+// role identifier in the test source with the board's real pin symbol (and
+// each fact with its numeric literal), rewriting the import to
+// '@typecad/board' — the exact lowering path hand-written per-board tests
+// use. This module provides the schema, the JSON reader, and the
+// editor-support generator (config-loader writes .cuttlefish/test-pins.ts
+// so the language server resolves the specifier).
+//
+// Schema (all fields optional — a board only declares what it can test;
+// suites gate themselves on role availability via `@typecad-requires-roles`):
+//
+//   {
+//     "pins": {
+//       "gpioOut": "PB5",            -> GPIO_OUT
+//       "gpioIn": "PB0",             -> GPIO_IN
+//       "pwm": "PB6",                -> PWM_PIN
+//       "pwmAlt": "PB7",             -> PWM_ALT
+//       "cs": "PA4",                 -> CS_PIN
+//       "interrupt": "PA0",          -> INT_PIN
+//       "led": "PC13",               -> LED_PIN
+//       "button": "PA0"              -> BUTTON_PIN
+//     },
+//     "facts": {
+//       "adcMax": 4095                -> ADC_MAX
+//     },
+//     "usb": {                        -> port discovery (host side only):
+//       "vid": "2FE3",                multi-board test rigs match the
+//       "pid": "0001",                console/upload port by USB identity
+//       "serial": "…" (optional)      instead of tracking COM/tty numbers;
+//     }                               Zephyr CDC boards all enumerate at
+//   }                                 the default 2FE3:0001 — run one CDC
+//                                       board at a time (see the expect
+//                                       README's "USB port discovery")
+//   }
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+/** Pin role -> exported const name. Single source for generator + env typing. */
+const PIN_ROLES = {
+    gpioOut: "GPIO_OUT",
+    gpioIn: "GPIO_IN",
+    pwm: "PWM_PIN",
+    pwmAlt: "PWM_ALT",
+    adcPin: "ADC_PIN",
+    adcPinAlt: "ADC_PIN_ALT",
+    cs: "CS_PIN",
+    interrupt: "INT_PIN",
+    led: "LED_PIN",
+    button: "BUTTON_PIN",
+    // Bus selector roles carry a quoted instance name ('I2C0'), not a pin
+    // symbol — they export as string literals and substitute inline the same
+    // way (the value text already includes the quotes).
+    i2cBus: "I2C_BUS",
+};
+/** Fact role -> exported const name. */
+const FACT_ROLES = {
+    adcMax: "ADC_MAX",
+};
+const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Read and parse a project's test-pins.json. Returns undefined when absent. */
+export function readTestPinsFile(projectDir) {
+    const jsonPath = path.join(projectDir, "test-pins.json");
+    if (!fs.existsSync(jsonPath))
+        return undefined;
+    try {
+        return JSON.parse(fs.readFileSync(jsonPath, "utf8"));
+    }
+    catch (e) {
+        console.error(`[test-pins] Failed to parse ${jsonPath}: ${e.message}`);
+        return undefined;
+    }
+}
+/**
+ * Build the generated module's source: role consts re-exported from the
+ * board package. Used by the editor-support generator
+ * (.cuttlefish/test-pins.ts — see config-loader's generateVirtualTypeDeclaration)
+ * so the language server resolves the '@typecad/test-pins' specifier.
+ * Hardware runs do NOT transpile this module: the @typecad/expect
+ * preprocessor substitutes role identifiers in test sources with the
+ * board's real pin symbols before the transpiler runs (the HAL resolves
+ * pins through board-package metadata, not through transpiled modules).
+ * Returns undefined when the board declares no usable roles.
+ */
+export function buildTestPinsModuleContent(boardTarget, data) {
+    const lines = [
+        `// Generated from ${boardTarget}/test-pins.json by the '@typecad/test-pins'`,
+        `// resolver. Do not edit — regenerated on every transpile.`,
+        `import {`,
+    ];
+    const importedPins = [];
+    const exports = [];
+    for (const [role, constName] of Object.entries(PIN_ROLES)) {
+        const value = data.pins?.[role];
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            const names = value.filter((n) => typeof n === "string" && IDENTIFIER_RE.test(n));
+            if (names.length === 0)
+                continue;
+            importedPins.push(...names);
+            exports.push(`export const ${constName} = [${names.join(", ")}];`);
+        }
+        else if (typeof value === "string" && IDENTIFIER_RE.test(value)) {
+            importedPins.push(value);
+            exports.push(`export const ${constName} = ${value};`);
+        }
+        else if (typeof value === "string" && /^'[^']*'$/.test(value)) {
+            // Quoted selector text (a bus instance name) — export as-is; no board
+            // pin import needed.
+            exports.push(`export const ${constName} = ${value};`);
+        }
+        else {
+            console.error(`[test-pins] Ignoring invalid pin role '${role}' in test-pins.json`);
+        }
+    }
+    for (const [role, constName] of Object.entries(FACT_ROLES)) {
+        const value = data.facts?.[role];
+        if (typeof value !== "number" || !Number.isFinite(value))
+            continue;
+        exports.push(`export const ${constName} = ${value};`);
+    }
+    if (importedPins.length === 0 && exports.length === 0)
+        return undefined;
+    for (const name of [...new Set(importedPins)].sort()) {
+        lines.push(`  ${name},`);
+    }
+    // Pin symbols live in the generated board module (the .cuttlefish sibling).
+    lines.push(`} from './board.js';`);
+    lines.push("");
+    lines.push(...exports);
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/transpile.d.ts

@@ -1,6 +1,5 @@
-import { GenerateLibdefOptions, GeneratedOutputs, TranspileOptions } from "./types.js";
+import { GeneratedOutputs, TranspileOptions } from "./types.js";
 import { loadFrameworkPackage } from "./framework-package.js";
 export { loadFrameworkPackage };
 export { getLoadedFramework, hasLoadedFramework } from "./framework-registry.js";
 export declare function transpileFile(options: TranspileOptions): Promise<GeneratedOutputs>;
-export declare function generateLibraryDefinitions(options: GenerateLibdefOptions): string[];