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

package/dist/ir/build-ir.js

@@ -8,7 +8,7 @@ import { buildFunctionReturnTypeMap } from "./type-resolution.js";
 import { resolveBoardConstants, tryResolveBoardDefFile } from "./board-resolver.js";
 import { analyzePeripheralUsage, createEmptyPeripheralUsage } from "./peripheral-usage.js";
 import { runProgramValidations } from "./validation-orchestrator.js";
-import { registerFieldMap, hoistedNestedFunctions, hoistedNestedClasses, hoistedNestedEnums, hoistedNestedInterfaces, hoistedNestedTypeAliases, activeNamespaceNames, activeEnumNames, activeStringEnumNames, peripheralAliasMap, pinAliasMap, mcuPinReverseMap, topLevelClassNames, topLevelInterfaceNames, classTypeNames, topLevelClasses, requiredIncludes, resetBuildState, getCurrentBoardConstants, setCurrentBoardConstants, contextStorage, CompilationContext, registeredCallbacks, getContext, discriminatedUnionVariantNames, restParamFunctions, topLevelAliasReceivers } from "./build-ir-state.js";
+import { registerFieldMap, hoistedNestedFunctions, hoistedNestedClasses, hoistedNestedEnums, hoistedNestedInterfaces, hoistedNestedTypeAliases, activeNamespaceNames, activeEnumNames, activeStringEnumNames, peripheralAliasMap, pinAliasMap, mcuPinForwardMap, mcuPinReverseMap, topLevelClassNames, topLevelInterfaceNames, classTypeNames, topLevelClasses, requiredIncludes, resetBuildState, getCurrentBoardConstants, setCurrentBoardConstants, contextStorage, CompilationContext, registeredCallbacks, getContext, discriminatedUnionVariantNames, restParamFunctions, topLevelAliasReceivers } from "./build-ir-state.js";
 import { pinShadowVarName, takeShadowDeclarations, resetPinStateTracking, markShadowUpdatingOps } from "./pin-state-tracking.js";
 import { collectPointerVars, expressionStatementToIR, lowerStatement, variableStatementToIR, prescanArrayUsage, lowerStatementList } from "./statement-to-ir.js";
 import { registerUIModuleImport, registerElementValue } from "./transformers/ui-call-resolver.js";
@@ -497,10 +497,31 @@ export function buildProgramIR(fileName, sourceText, boardPackage, prebuiltClass
                             halInstances.set(name, { className: "Pin", fieldValues: fields });
                             continue;
                         }
-                        // A-pins: A0-A19 → Pin instance with board-specific offset and MCU port name (fallback)
+                        // A-pins: A0, A1, … → resolve through the board manifest's analog
+                        // pin list first (A-ordered on every board package: A<n> →
+                        // pins.analog[n] → the MCU port name → pin number). Only when the
+                        // list is absent (bare Arduino-style boards) fall back to the
+                        // analogOffset convention (A0 = 14) — on port-named boards that
+                        // fallback resolves A1 to a random GPIO (Black Pill PA15, a
+                        // non-analog pin, was the first to surface it via a capability
+                        // error).
                         const aMatch = name.match(/^A(\d+)$/);
                         if (aMatch) {
-                            const pinNum = String(analogOffset + parseInt(aMatch[1]));
+                            let pinNum;
+                            // The flattener stores the manifest's analog pin list as a
+                            // comma-joined string under `pins.analog`.
+                            const analogList = boardConstants.get("pins.analog");
+                            if (typeof analogList === "string") {
+                                const analogName = analogList.split(",")[parseInt(aMatch[1], 10)];
+                                if (analogName) {
+                                    const byName = mcuPinForwardMap.get(analogName);
+                                    if (byName !== undefined)
+                                        pinNum = String(byName);
+                                }
+                            }
+                            if (pinNum === undefined) {
+                                pinNum = String(analogOffset + parseInt(aMatch[1]));
+                            }
                             const fields = new Map([["_pin", pinNum]]);
                             const portName = mcuPinReverseMap.get(pinNum);
                             if (portName)

package/dist/library/catalog.d.ts

@@ -0,0 +1,35 @@
+/** The one keyword every cuttlefish library package must carry. */
+export declare const LIBRARY_MARKER_KEYWORD = "cuttlefish-library";
+/** Prefix for category keywords (`cuttlefish-<id>`). */
+export declare const CATEGORY_KEYWORD_PREFIX = "cuttlefish-";
+export interface LibraryCategory {
+    /** Stable id used in --category flags, keywords, and docs. */
+    id: string;
+    /** Human label for prompts and tables. */
+    label: string;
+    /** One-line scope description. */
+    description: string;
+    /** Example parts the category covers (prompt/README guidance). */
+    examples: string;
+}
+/**
+ * The category taxonomy. Shared by search (query building + result shaping),
+ * init (scaffold choices + keywords), validate (keyword consistency), and the
+ * website's Library Packages page (rendered from the same list).
+ */
+export declare const LIBRARY_CATEGORIES: readonly LibraryCategory[];
+/** Look up a category by id (case-insensitive). */
+export declare function libraryCategory(id: string): LibraryCategory | undefined;
+/** The npm keyword for a category (`cuttlefish-<id>`). */
+export declare function categoryKeyword(id: string): string;
+/**
+ * Derive the category of an npm search result from its keywords. A package may
+ * carry several category keywords; the first match in taxonomy order wins so
+ * results are stable.
+ */
+export declare function categoryFromKeywords(keywords: readonly string[] | undefined): string | null;
+/**
+ * The keywords a library package should carry: the marker plus its category
+ * keyword. Used by `library init` and checked by `library validate`.
+ */
+export declare function requiredLibraryKeywords(categoryId: string): string[];

package/dist/library/catalog.js

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// Cuttlefish library catalog — the category taxonomy and npm keyword
+// conventions behind `cuttlefish library search/init/validate`.
+//
+// The catalog has no registry service: npm keywords ARE the catalog. Every
+// library package carries the marker keyword LIBRARY_MARKER_KEYWORD plus one
+// category keyword (e.g. 'cuttlefish-led'). npm's search endpoint ANDs
+// `keywords:` terms, so queries compose:
+//
+//   keywords:cuttlefish-library                     → every library
+//   keywords:cuttlefish-library keywords:cuttlefish-led → the led category
+//   keywords:cuttlefish-library ws2812              → free-text within libraries
+// ---------------------------------------------------------------------------
+/** The one keyword every cuttlefish library package must carry. */
+export const LIBRARY_MARKER_KEYWORD = "cuttlefish-library";
+/** Prefix for category keywords (`cuttlefish-<id>`). */
+export const CATEGORY_KEYWORD_PREFIX = "cuttlefish-";
+/**
+ * The category taxonomy. Shared by search (query building + result shaping),
+ * init (scaffold choices + keywords), validate (keyword consistency), and the
+ * website's Library Packages page (rendered from the same list).
+ */
+export const LIBRARY_CATEGORIES = [
+    { id: "led", label: "LEDs", description: "LEDs, addressable strips, LED drivers", examples: "WS2812-class pixels, LED drivers, bar graphs" },
+    { id: "display", label: "Displays", description: "Panels and panel drivers", examples: "TFT, OLED, e-ink" },
+    { id: "sensor", label: "Sensors", description: "Measurement parts", examples: "environmental, motion, IMU, light, distance" },
+    { id: "actuator", label: "Actuators", description: "Things that move or switch", examples: "motors, servos, steppers, relays" },
+    { id: "comms", label: "Communications", description: "Radios and networking beyond built-in WiFi/BLE", examples: "LoRa, GSM, satellite, CAN add-ons" },
+    { id: "storage", label: "Storage", description: "Persistent storage parts", examples: "SD cards, flash chips, FRAM" },
+    { id: "audio", label: "Audio", description: "Sound input and output", examples: "microphones, amplifiers, codecs" },
+    { id: "power", label: "Power", description: "Power management and monitoring", examples: "PMICs, battery gauges, chargers" },
+    { id: "input", label: "Input", description: "Add-on human input", examples: "keypads, rotary encoders, add-on touch" },
+    { id: "io", label: "I/O Expanders", description: "Extra I/O and simple drivers", examples: "port expanders, matrix drivers, 7-segment" },
+    { id: "timing", label: "Timing", description: "Clocks and time sources", examples: "RTCs, precision clocks, GPS time" },
+    { id: "utility", label: "Utility", description: "Pure-code helpers with no hardware of their own", examples: "formats, algorithms, protocol codecs" },
+];
+/** Look up a category by id (case-insensitive). */
+export function libraryCategory(id) {
+    const lower = id.toLowerCase();
+    return LIBRARY_CATEGORIES.find((c) => c.id === lower);
+}
+/** The npm keyword for a category (`cuttlefish-<id>`). */
+export function categoryKeyword(id) {
+    return `${CATEGORY_KEYWORD_PREFIX}${id.toLowerCase()}`;
+}
+/**
+ * Derive the category of an npm search result from its keywords. A package may
+ * carry several category keywords; the first match in taxonomy order wins so
+ * results are stable.
+ */
+export function categoryFromKeywords(keywords) {
+    if (!keywords || keywords.length === 0)
+        return null;
+    const set = new Set(keywords.map((k) => k.toLowerCase()));
+    for (const category of LIBRARY_CATEGORIES) {
+        if (set.has(categoryKeyword(category.id)))
+            return category.id;
+    }
+    return null;
+}
+/**
+ * The keywords a library package should carry: the marker plus its category
+ * keyword. Used by `library init` and checked by `library validate`.
+ */
+export function requiredLibraryKeywords(categoryId) {
+    return [LIBRARY_MARKER_KEYWORD, categoryKeyword(categoryId)];
+}

package/dist/library/cli.d.ts

@@ -0,0 +1,2 @@
+import type { LibraryCommandOptions } from "../types.js";
+export declare function runLibraryCommand(options: LibraryCommandOptions): Promise<void>;

package/dist/library/cli.js

@@ -0,0 +1,168 @@
+// ---------------------------------------------------------------------------
+// `cuttlefish library <subcommand>` — CLI glue for the library manager.
+// Subcommands: search, install, init, validate. The catalog modules own the
+// logic; this module owns argument interpretation and presentation.
+// ---------------------------------------------------------------------------
+import chalk from "chalk";
+import path from "node:path";
+import { LIBRARY_CATEGORIES, libraryCategory } from "./catalog.js";
+import { searchLibraryPackages } from "./registry-search.js";
+import { findProjectPackageJson, installedDependencyVersion, npmInstall } from "./install.js";
+import { runLibraryInit } from "./init.js";
+import { validateLibraryPackage, printValidationReport } from "./validate.js";
+function requireCategory(category, command) {
+    if (category === undefined)
+        return undefined;
+    if (!libraryCategory(category)) {
+        throw new Error(`Unknown category '${category}' for 'library ${command}'. Known categories: ` +
+            LIBRARY_CATEGORIES.map((c) => c.id).join(", ") +
+            ".");
+    }
+    return category.toLowerCase();
+}
+function stripVersionPrefix(v) {
+    return v.replace(/^[^0-9]*/, "");
+}
+async function runSearch(options) {
+    const category = requireCategory(options.category, "search");
+    const text = options.positionals.join(" ");
+    let results;
+    try {
+        results = await searchLibraryPackages(text || undefined, category);
+    }
+    catch (e) {
+        throw new Error(`Failed to search npm: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (options.json) {
+        const pkgPath = findProjectPackageJson();
+        console.log(JSON.stringify(results.map((r) => ({
+            name: r.name,
+            version: r.version,
+            description: r.description,
+            category: r.category,
+            npmUrl: r.npmUrl,
+            installed: pkgPath ? installedDependencyVersion(pkgPath, r.name) !== undefined : false,
+        })), null, 2));
+        return;
+    }
+    const header = category
+        ? `cuttlefish libraries — category: ${libraryCategory(category).label}`
+        : "cuttlefish libraries";
+    console.log(chalk.green("+") + " " + chalk.white.bold(header) + chalk.gray(`  (npm keyword: cuttlefish-library${category ? ` + cuttlefish-${category}` : ""})`));
+    console.log();
+    if (results.length === 0) {
+        console.log(chalk.yellow("No matching library packages on npm yet."));
+        console.log(`  Scaffold the first one: ${chalk.cyan("cuttlefish library init")}`);
+        return;
+    }
+    const pkgPath = findProjectPackageJson();
+    for (const r of results) {
+        const cat = r.category ? libraryCategory(r.category) : undefined;
+        const installedSpec = pkgPath ? installedDependencyVersion(pkgPath, r.name) : undefined;
+        const state = installedSpec
+            ? stripVersionPrefix(installedSpec) === r.version
+                ? chalk.gray(" (installed)")
+                : chalk.yellow(` (installed v${stripVersionPrefix(installedSpec)}, latest v${r.version})`)
+            : "";
+        console.log(`  ${chalk.white.bold(r.name)} ${chalk.dim(`v${r.version}`)}${state}`);
+        if (cat) {
+            console.log(`    ${chalk.cyan(`[${cat.label}]`)} ${r.description ?? ""}`);
+        }
+        else {
+            console.log(`    ${r.description ?? ""}`);
+        }
+    }
+    console.log();
+    console.log(chalk.gray(`  Install with: cuttlefish library install <name>`));
+}
+function runInstall(options) {
+    const names = options.positionals;
+    if (names.length === 0) {
+        throw new Error("Usage: cuttlefish library install <package...>");
+    }
+    const pkgPath = findProjectPackageJson();
+    if (!pkgPath) {
+        throw new Error("No package.json found in this directory or any parent — run inside a cuttlefish project.");
+    }
+    const pkgDir = path.dirname(pkgPath);
+    if (options.json) {
+        const before = Object.fromEntries(names.map((n) => [n, installedDependencyVersion(pkgPath, n) ?? null]));
+        try {
+            npmInstall(names, pkgDir);
+        }
+        catch (e) {
+            const err = e;
+            const detail = err.stderr?.toString().trim() || (e instanceof Error ? e.message : String(e));
+            throw new Error(`Failed to install packages: ${detail}`);
+        }
+        console.log(JSON.stringify({ installed: names, projectRoot: pkgDir, previous: before }, null, 2));
+        return;
+    }
+    console.log(chalk.green("+") + ` Installing ${names.join(", ")}...`);
+    try {
+        npmInstall(names, pkgDir);
+    }
+    catch (e) {
+        const err = e;
+        const detail = err.stderr?.toString().trim() || (e instanceof Error ? e.message : String(e));
+        throw new Error(`Failed to install packages: ${detail}`);
+    }
+    for (const name of names) {
+        console.log(chalk.green("+") + ` ${name}`);
+        console.log(chalk.gray(`  https://www.npmjs.com/package/${name}`));
+    }
+    console.log(chalk.green("✔") + " Done");
+}
+async function runInit(options) {
+    if (options.category !== undefined) {
+        requireCategory(options.category, "init");
+    }
+    await runLibraryInit({
+        name: options.positionals[0],
+        framework: options.framework,
+        category: options.category,
+        targets: options.targets,
+        dir: options.dir,
+        yes: options.yes,
+    });
+}
+function runValidate(options) {
+    const dir = options.positionals[0] ?? process.cwd();
+    const report = validateLibraryPackage(dir);
+    if (options.json) {
+        console.log(JSON.stringify({
+            valid: report.valid,
+            dir: report.dir,
+            errors: report.errors,
+            warnings: report.warnings,
+            autosarFindings: report.autosarFindings,
+        }, null, 2));
+    }
+    else {
+        console.log(chalk.white.bold(`cuttlefish library validate`) + chalk.gray(`  ${report.dir}`));
+        console.log();
+        const code = printValidationReport(report);
+        if (code !== 0) {
+            process.exitCode = code;
+        }
+    }
+    if (!report.valid && options.json) {
+        process.exitCode = 1;
+    }
+}
+export async function runLibraryCommand(options) {
+    switch (options.subcommand) {
+        case "search":
+            await runSearch(options);
+            return;
+        case "install":
+            runInstall(options);
+            return;
+        case "init":
+            await runInit(options);
+            return;
+        case "validate":
+            runValidate(options);
+            return;
+    }
+}

package/dist/library/init.d.ts

@@ -0,0 +1,25 @@
+export interface LibraryInitOptions {
+    /** Full package name (e.g. '@acme/esp32-led-ring' or 'my-lib'). */
+    name?: string;
+    /** Framework id from FRAMEWORK_CATALOG ('zephyr', 'arduino', ...). */
+    framework?: string;
+    /** Category id from LIBRARY_CATEGORIES. */
+    category?: string;
+    /** Comma-separated board-target prefixes (e.g. 'esp32s3_devkitc'). */
+    targets?: string;
+    /** Directory to scaffold into (default: ./<package basename>). */
+    dir?: string;
+    /** Skip prompts; take defaults for anything not provided by flags. */
+    yes?: boolean;
+}
+export interface LibraryInitResult {
+    packageDir: string;
+    packageName: string;
+    /** The library id (slug of the package basename). */
+    id: string;
+}
+/** Slug of a package basename: lowercase, runs of non-alphanumerics → '-'. */
+export declare function libraryIdFromPackageName(packageName: string): string;
+/** '__tc_my_lib' for id 'my-lib' — a valid C++ identifier prefix. */
+export declare function tokenBaseFromId(id: string): string;
+export declare function runLibraryInit(options: LibraryInitOptions): Promise<LibraryInitResult>;