@typecad/cuttlefish 1.0.0-alpha.10 → 1.0.0-alpha.12

package/dist/config-loader.js

@@ -12,6 +12,13 @@ import ts from "typescript";
 import { safeValidateConfig } from "./config-schema.js";
 /** The filename we search for when walking up directories. */
 const CONFIG_FILENAME = "cuttlefish.config.ts";
+/** Top-level keys recognized by CuttlefishConfigSchema — used to warn about
+ *  misspelled keys that the AST extraction would otherwise drop silently. */
+const KNOWN_TOP_LEVEL_KEYS = new Set([
+    "entry", "target", "mcu", "board", "contract", "framework", "psram",
+    "output", "frameworkData", "include", "exclude", "test", "toolchain",
+    "console", "native", "zephyr", "display",
+]);
 /**
  * Search upward from `startDir` for a file named `cuttlefish.config.ts`.
  * Returns the absolute path on success, `undefined` if none is found.
@@ -30,15 +37,21 @@ export function findConfigFile(startDir) {
     }
     return undefined;
 }
-// ---------------------------------------------------------------------------
-// AST helpers — extract scalar values from a TS object literal
-// ---------------------------------------------------------------------------
 function unwrapTypeCast(node) {
     let curr = node;
-    while (ts.isAsExpression(curr) || ts.isTypeAssertionExpression(curr)) {
-        curr = curr.expression;
+    for (;;) {
+        if (ts.isAsExpression(curr) || ts.isTypeAssertionExpression(curr) || ts.isParenthesizedExpression(curr)) {
+            curr = curr.expression;
+            continue;
+        }
+        // satisfies is TS ≥4.9 — guard for older typings, then cast for .expression.
+        const isSatisfies = ts.isSatisfiesExpression;
+        if (typeof isSatisfies === "function" && isSatisfies(curr)) {
+            curr = curr.expression;
+            continue;
+        }
+        return curr;
     }
-    return curr;
 }
 function getStringLiteral(node) {
     const unwrapped = unwrapTypeCast(node);
@@ -55,20 +68,51 @@ function getScalarValue(node) {
     if (ts.isNumericLiteral(unwrapped)) {
         return Number(unwrapped.text);
     }
+    // Negative (and explicitly positive) number literals parse as
+    // PrefixUnaryExpression — `reset: -1` used to be silently dropped.
+    if (ts.isPrefixUnaryExpression(unwrapped)
+        && (unwrapped.operator === ts.SyntaxKind.MinusToken || unwrapped.operator === ts.SyntaxKind.PlusToken)
+        && ts.isNumericLiteral(unwrapped.operand)) {
+        const magnitude = Number(unwrapped.operand.text);
+        return unwrapped.operator === ts.SyntaxKind.MinusToken ? -magnitude : magnitude;
+    }
     if (unwrapped.kind === ts.SyntaxKind.TrueKeyword)
         return true;
     if (unwrapped.kind === ts.SyntaxKind.FalseKeyword)
         return false;
     return undefined;
 }
+/** True for `null` / `undefined` literals — inline literals, but not values
+ *  the config shape supports; callers warn with an accurate message instead
+ *  of the "variables/ternaries" text. */
+function isNullishLiteral(node) {
+    const kind = unwrapTypeCast(node).kind;
+    return kind === ts.SyntaxKind.NullKeyword || kind === ts.SyntaxKind.UndefinedKeyword;
+}
 /**
  * Walk an object literal and collect all scalar (string / number / boolean)
  * property values into a flat dot-path map — exactly like board-resolver.ts.
  */
-function walkObjectLiteral(obj, prefix, out) {
+/** Property key text for Identifier/StringLiteral names, else undefined
+ *  (SpreadAssignment has no name; computed keys are not static text). */
+function propertyKeyName(prop) {
+    const name = prop.name;
+    if (!name)
+        return undefined;
+    return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+}
+function describePropertyKey(prop) {
+    return propertyKeyName(prop) ?? "<unnamed>";
+}
+function walkObjectLiteral(obj, prefix, out, warn) {
     for (const prop of obj.properties) {
-        if (!ts.isPropertyAssignment(prop))
+        if (!ts.isPropertyAssignment(prop)) {
+            if (warn) {
+                const label = prefix ? `${prefix}.${describePropertyKey(prop)}` : describePropertyKey(prop);
+                warn(`'${label}' uses ${ts.SyntaxKind[prop.kind]} syntax (shorthand/spread/method) — only property assignments are supported, ignored.`);
+            }
             continue;
+        }
         const key = ts.isIdentifier(prop.name)
             ? prop.name.text
             : ts.isStringLiteral(prop.name)
@@ -78,13 +122,26 @@ function walkObjectLiteral(obj, prefix, out) {
             continue;
         const fullKey = prefix ? `${prefix}.${key}` : key;
         if (ts.isObjectLiteralExpression(prop.initializer)) {
-            walkObjectLiteral(prop.initializer, fullKey, out);
+            walkObjectLiteral(prop.initializer, fullKey, out, warn);
+        }
+        else if (ts.isArrayLiteralExpression(prop.initializer)) {
+            // Arrays are extracted by the dedicated array extractors
+            // (output.extraFlags, zephyr.cmakeArgs, native.libraries, …), not the
+            // flat scalar walk — skip here without warning.
         }
         else {
             const value = getScalarValue(prop.initializer);
             if (value !== undefined) {
                 out.set(fullKey, value);
             }
+            else if (warn) {
+                // Message text must stay byte-identical to extractObjectAsRecord's —
+                // sections walked by both (native, display) rely on the warn-site
+                // dedup to print one warning per dropped value, not two.
+                warn(isNullishLiteral(prop.initializer)
+                    ? `'${fullKey}' is a null/undefined literal — not a supported config value, ignored.`
+                    : `'${fullKey}' is not an inline literal (variables, ternaries, and template substitutions are not evaluated) — ignored.`);
+            }
         }
     }
 }
@@ -124,20 +181,18 @@ function navigateToObjectProperty(obj, path) {
     }
     return undefined;
 }
-function extractStringArray(obj, path) {
+function extractStringArray(obj, path, warn) {
+    const label = path.join(".");
     const leaf = navigateToObjectProperty(obj, path);
-    if (!leaf || !ts.isArrayLiteralExpression(leaf))
+    if (!leaf || !ts.isArrayLiteralExpression(leaf)) {
+        if (leaf && warn)
+            warn(`'${label}' is not an inline array literal — ignored.`);
         return undefined;
-    const result = [];
-    for (const elem of leaf.elements) {
-        const s = getStringLiteral(elem);
-        if (s === undefined)
-            return undefined;
-        result.push(s);
     }
-    return result;
+    return extractStringArrayFromArrayLiteral(leaf, warn, label);
 }
-function extractStringRecord(obj, path) {
+function extractStringRecord(obj, path, warn) {
+    const label = path.join(".");
     const leaf = navigateToObjectProperty(obj, path);
     if (!leaf || !ts.isObjectLiteralExpression(leaf))
         return undefined;
@@ -153,8 +208,11 @@ function extractStringRecord(obj, path) {
         if (!key)
             continue;
         const value = getStringLiteral(prop.initializer);
-        if (value === undefined)
+        if (value === undefined) {
+            if (warn)
+                warn(`'${label}.${key}' is not a string literal — the whole record is ignored.`);
             return undefined;
+        }
         result[key] = value;
     }
     if (Object.keys(result).length === 0)
@@ -165,11 +223,18 @@ function extractStringRecord(obj, path) {
  * Recursively extract an object literal as Record<string, unknown>.
  * Handles strings, numbers, booleans, string arrays, and nested objects.
  */
-function extractObjectAsRecord(obj) {
+function extractObjectAsRecord(obj, warn, prefix = "") {
     const result = {};
     for (const prop of obj.properties) {
-        if (!ts.isPropertyAssignment(prop))
+        if (!ts.isPropertyAssignment(prop)) {
+            if (warn) {
+                // Byte-identical to walkObjectLiteral's message for the same property
+                // so the warn-site dedup collapses the double walk into one warning.
+                const label = prefix ? `${prefix}.${describePropertyKey(prop)}` : describePropertyKey(prop);
+                warn(`'${label}' uses ${ts.SyntaxKind[prop.kind]} syntax (shorthand/spread/method) — only property assignments are supported, ignored.`);
+            }
             continue;
+        }
         const key = ts.isIdentifier(prop.name)
             ? prop.name.text
             : ts.isStringLiteral(prop.name)
@@ -177,29 +242,40 @@ function extractObjectAsRecord(obj) {
                 : undefined;
         if (!key)
             continue;
+        const fullKey = prefix ? `${prefix}.${key}` : key;
         const init = prop.initializer;
         if (ts.isObjectLiteralExpression(init)) {
-            result[key] = extractObjectAsRecord(init);
+            result[key] = extractObjectAsRecord(init, warn, fullKey);
         }
         else if (ts.isArrayLiteralExpression(init)) {
-            const arr = extractStringArrayFromArrayLiteral(init);
+            const arr = extractStringArrayFromArrayLiteral(init, warn, fullKey);
             if (arr)
                 result[key] = arr;
         }
         else {
             const scalar = getScalarValue(init);
-            if (scalar !== undefined)
+            if (scalar !== undefined) {
                 result[key] = scalar;
+            }
+            else if (warn) {
+                // Keep byte-identical to walkObjectLiteral's message (see above).
+                warn(isNullishLiteral(init)
+                    ? `'${fullKey}' is a null/undefined literal — not a supported config value, ignored.`
+                    : `'${fullKey}' is not an inline literal (variables, ternaries, and template substitutions are not evaluated) — ignored.`);
+            }
         }
     }
     return result;
 }
-function extractStringArrayFromArrayLiteral(node) {
+function extractStringArrayFromArrayLiteral(node, warn, label = "array") {
     const result = [];
     for (const elem of node.elements) {
         const s = getStringLiteral(elem);
-        if (s === undefined)
+        if (s === undefined) {
+            if (warn)
+                warn(`'${label}' has a non-string-literal element — the whole array is ignored.`);
             return undefined;
+        }
         result.push(s);
     }
     return result;
@@ -207,7 +283,7 @@ function extractStringArrayFromArrayLiteral(node) {
 /**
  * Extract a top-level config section as a generic Record<string, unknown>.
  */
-function extractFrameworkSection(obj, sectionName) {
+function extractFrameworkSection(obj, sectionName, warn) {
     for (const prop of obj.properties) {
         if (!ts.isPropertyAssignment(prop))
             continue;
@@ -218,9 +294,12 @@ function extractFrameworkSection(obj, sectionName) {
                 : undefined;
         if (key !== sectionName)
             continue;
-        if (!ts.isObjectLiteralExpression(prop.initializer))
+        if (!ts.isObjectLiteralExpression(prop.initializer)) {
+            if (warn)
+                warn(`'${sectionName}' section is not an inline object literal — ignored.`);
             return undefined;
-        return extractObjectAsRecord(prop.initializer);
+        }
+        return extractObjectAsRecord(prop.initializer, warn, sectionName);
     }
     return undefined;
 }
@@ -251,11 +330,14 @@ export function parseConfigFile(configPath) {
         }
         // export default config;  (ExportAssignment with an identifier)
         if (ts.isExportAssignment(stmt) && !stmt.isExportEquals) {
-            if (ts.isIdentifier(stmt.expression)) {
-                defaultExportName = stmt.expression.text;
+            // Unwrap `export default { ... } satisfies CuttlefishConfig` /
+            // `as const` / parenthesized forms down to the underlying expression.
+            const expr = unwrapTypeCast(stmt.expression);
+            if (ts.isIdentifier(expr)) {
+                defaultExportName = expr.text;
             }
-            else if (ts.isObjectLiteralExpression(stmt.expression)) {
-                inlineDefaultObject = stmt.expression;
+            else if (ts.isObjectLiteralExpression(expr)) {
+                inlineDefaultObject = expr;
             }
         }
     }
@@ -263,16 +345,43 @@ export function parseConfigFile(configPath) {
     let configObject = inlineDefaultObject;
     if (!configObject && defaultExportName) {
         const decl = variableDecls.get(defaultExportName);
-        if (decl?.initializer && ts.isObjectLiteralExpression(decl.initializer)) {
-            configObject = decl.initializer;
+        if (decl?.initializer) {
+            // `const config = { ... } satisfies CuttlefishConfig` parses the
+            // initializer as a SatisfiesExpression — unwrap to the object literal
+            // so the whole config isn't silently ignored.
+            const init = unwrapTypeCast(decl.initializer);
+            if (ts.isObjectLiteralExpression(init)) {
+                configObject = init;
+            }
         }
     }
     if (!configObject) {
         return undefined;
     }
+    // Collect drop warnings (values the AST-only parser can't evaluate) and
+    // print them once after parsing — silent drops here used to surface much
+    // later as missing -l flags / reverted defaults with no diagnostic.
+    const dropWarnings = [];
+    const seenWarnings = new Set();
+    const warn = (message) => {
+        const line = `${path.basename(configPath)}: ${message}`;
+        if (!seenWarnings.has(line)) {
+            seenWarnings.add(line);
+            dropWarnings.push(line);
+        }
+    };
+    // Typos in top-level keys (e.g. `output.optmize`) were dropped before
+    // schema validation, so the strict schema never saw them — check the raw
+    // source keys against the known set directly.
+    for (const prop of configObject.properties) {
+        const key = propertyKeyName(prop);
+        if (key && !KNOWN_TOP_LEVEL_KEYS.has(key)) {
+            warn(`unknown top-level key '${key}' — misspelled or unsupported.`);
+        }
+    }
     // Walk the object literal into a flat map.
     const flat = new Map();
-    walkObjectLiteral(configObject, "", flat);
+    walkObjectLiteral(configObject, "", flat, warn);
     // Map flat keys to the resolved config shape.
     const resolved = { configPath };
     const entry = flat.get("entry");
@@ -298,8 +407,11 @@ export function parseConfigFile(configPath) {
     if (typeof framework === "string")
         resolved.framework = framework;
     const psram = flat.get("psram");
-    if (psram === "opi" || psram === "quad")
+    if (typeof psram === "string") {
+        // Assign any string (including "") so the schema's PsramType enum rejects
+        // typos ('octal') with a validation error instead of silently dropping it.
         resolved.psram = psram;
+    }
     const outputFramework = flat.get("output.framework");
     if (typeof outputFramework === "string")
         resolved.outputFramework = outputFramework;
@@ -319,19 +431,19 @@ export function parseConfigFile(configPath) {
         };
     }
     // Extract structured fields that the flat walker cannot handle.
-    const outputExtraFlags = extractStringArray(configObject, ["output", "extraFlags"]);
+    const outputExtraFlags = extractStringArray(configObject, ["output", "extraFlags"], warn);
     if (outputExtraFlags)
         resolved.outputExtraFlags = outputExtraFlags;
-    const outputDefines = extractStringRecord(configObject, ["output", "defines"]);
+    const outputDefines = extractStringRecord(configObject, ["output", "defines"], warn);
     if (outputDefines)
         resolved.outputDefines = outputDefines;
-    const nativeSection = extractFrameworkSection(configObject, "native");
+    const nativeSection = extractFrameworkSection(configObject, "native", warn);
     if (nativeSection) {
         resolved.frameworkConfig = nativeSection;
     }
     // Parse zephyr-specific config section.
-    const zephyrKconfig = extractStringRecord(configObject, ["zephyr", "kconfig"]);
-    const zephyrCmakeArgs = extractStringArray(configObject, ["zephyr", "cmakeArgs"]);
+    const zephyrKconfig = extractStringRecord(configObject, ["zephyr", "kconfig"], warn);
+    const zephyrCmakeArgs = extractStringArray(configObject, ["zephyr", "cmakeArgs"], warn);
     const zephyrRunner = flat.get("zephyr.runner");
     if (zephyrKconfig || zephyrCmakeArgs || typeof zephyrRunner === "string") {
         resolved.zephyrConfig = {
@@ -341,7 +453,10 @@ export function parseConfigFile(configPath) {
         };
     }
     // Parse display profile config (nested object with profile name, wiring, touch)
-    const displaySection = extractFrameworkSection(configObject, "display");
+    const displaySection = extractFrameworkSection(configObject, "display", warn);
+    // extractObjectAsRecord walks literals into a loose record; the shape is
+    // checked downstream (schema passthrough + display-profile resolution), so
+    // bridge it to the declared DisplayConfig type at this single boundary.
     if (displaySection)
         resolved.display = displaySection;
     // Validate the parsed config against the Zod schema.
@@ -359,7 +474,9 @@ export function parseConfigFile(configPath) {
         structuredForValidation.entry = resolved.entry;
     if (resolved.framework)
         structuredForValidation.framework = resolved.framework;
-    if (resolved.psram)
+    // `!== undefined` (not truthiness) so an empty-string psram reaches the
+    // PsramType enum and fails validation instead of vanishing.
+    if (resolved.psram !== undefined)
         structuredForValidation.psram = resolved.psram;
     if (resolved.outputFramework || resolved.outputOptimize || resolved.outputOutDir || resolved.outputExtraFlags || resolved.outputDefines) {
         structuredForValidation.output = {
@@ -374,6 +491,10 @@ export function parseConfigFile(configPath) {
         structuredForValidation.console = resolved.console;
     if (resolved.zephyrConfig)
         structuredForValidation.zephyr = resolved.zephyrConfig;
+    if (resolved.frameworkConfig)
+        structuredForValidation.native = resolved.frameworkConfig;
+    if (resolved.display)
+        structuredForValidation.display = resolved.display;
     if (resolved.buildTarget) {
         structuredForValidation.frameworkData = { buildTarget: resolved.buildTarget };
     }
@@ -382,6 +503,12 @@ export function parseConfigFile(configPath) {
         const errorMsg = validation.errors.map(e => `  - ${e}`).join("\n");
         throw new Error(`Configuration validation failed for ${configPath}:\n${errorMsg}`);
     }
+    if (dropWarnings.length > 0) {
+        console.warn(`⚠ ${configPath}: some values were ignored (the parser only evaluates inline literals):`);
+        for (const w of dropWarnings) {
+            console.warn(`  ${w}`);
+        }
+    }
     return resolved;
 }
 /**
@@ -440,6 +567,23 @@ export function generateVirtualTypeDeclaration(config, platformDeclarations) {
         "  type Shared<T = unknown> = T;",
         "  type Mutable<T = unknown> = T;",
         "",
+        "  // SafeVariable: SEU-resistant storage. The transpiler lowers SafeVariable<number>",
+        "  // to a C++ template with inverted-redundancy storage. Declared as an interface",
+        "  // (not a type alias) so the TS type checker recognizes method calls.",
+        "  // Arithmetic T only (integral or floating-point); string is rejected by a",
+        "  // static_assert in the emitted C++ template.",
+        "  interface SafeVariable<T = number> { set(value: T): void; get(): T; valid(): boolean; hasFault(): boolean; }",
+        "  // SafeInt: chainable bounds-checked signed-integer arithmetic. The transpiler",
+        "  // lowers SafeInt<number> to SafeInt<int32_t> (a C++ template with sticky-fault",
+        "  // overflow detection). Signed integer T only — unsigned/bool/float/string are",
+        "  // rejected by a static_assert in the emitted C++ template.",
+        "  interface SafeInt<T = number> {",
+        "    add(delta: T): SafeInt<T>; sub(delta: T): SafeInt<T>;",
+        "    mul(factor: T): SafeInt<T>; divide(d: T): SafeInt<T>; mod(d: T): SafeInt<T>;",
+        "    negate(): SafeInt<T>; absValue(): SafeInt<T>;",
+        "    get(): T; hasFault(): boolean; valid(): boolean; reset(newValue: T): void;",
+        "  }",
+        "",
         "  // C-style explicit number types recognized by the transpiler",
         "  type uint8_t = number;",
         "  type int8_t = number;",
@@ -480,9 +624,9 @@ export function generateVirtualTypeDeclaration(config, platformDeclarations) {
         "",
         "declare module '@typecad/board' {",
         `  ${boardExport}`,
-        "  export type Owned<T = any> = T;",
-        "  export type Shared<T = any> = T;",
-        "  export type Mutable<T = any> = T;",
+        "  export type Owned<T = unknown> = T;",
+        "  export type Shared<T = unknown> = T;",
+        "  export type Mutable<T = unknown> = T;",
         "}",
         "",
         "export {};",