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

package/dist/library/install.js

@@ -0,0 +1,80 @@
+// ---------------------------------------------------------------------------
+// Library installation — `cuttlefish library install <pkg...>`.
+//
+// Finds the nearest project package.json (walking up from the cwd) and runs
+// npm install against it. The Windows spawn handling mirrors the typecad
+// binary's package command: npm.cmd must go through cmd.exe, and a resolved
+// .cmd/.bat cannot be exec'd directly.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+const IS_WIN = process.platform === "win32";
+const IS_CMD_EXT = /\.(?:cmd|bat)$/i;
+/** Walk up from `fromDir` to the nearest package.json. */
+export function findProjectPackageJson(fromDir = process.cwd()) {
+    let dir = path.resolve(fromDir);
+    const root = path.parse(dir).root;
+    for (;;) {
+        const candidate = path.join(dir, "package.json");
+        if (fs.existsSync(candidate))
+            return candidate;
+        if (dir === root)
+            return null;
+        dir = path.dirname(dir);
+    }
+}
+/** Installed version spec for a dependency name, or undefined. */
+export function installedDependencyVersion(packageJsonPath, name) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        for (const section of ["dependencies", "devDependencies", "optionalDependencies"]) {
+            const deps = pkg[section];
+            if (deps && typeof deps === "object" && typeof deps[name] === "string") {
+                return deps[name];
+            }
+        }
+    }
+    catch {
+        // unreadable manifest — treat as not installed
+    }
+    return undefined;
+}
+function resolveNpmExecutable() {
+    const isWin = IS_WIN;
+    const cmd = isWin ? "npm.cmd" : "npm";
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, cmd);
+        try {
+            if (fs.statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            // keep scanning
+        }
+    }
+    return undefined;
+}
+/**
+ * Install npm packages into the project owning `cwd`. Returns the directory
+ * the install ran in. Throws with npm's stderr on failure.
+ */
+export function npmInstall(packageNames, cwd) {
+    const resolved = resolveNpmExecutable();
+    if (IS_WIN && (!resolved || IS_CMD_EXT.test(resolved))) {
+        execFileSync("cmd.exe", ["/d", "/s", "/c", "npm", "install", ...packageNames], {
+            cwd,
+            stdio: "pipe",
+            timeout: 300_000,
+        });
+    }
+    else {
+        execFileSync(resolved ?? "npm", ["install", ...packageNames], {
+            cwd,
+            stdio: "pipe",
+            timeout: 300_000,
+        });
+    }
+}

package/dist/library/registry-search.d.ts

@@ -0,0 +1,34 @@
+/** Fields of an npm search result this module consumes. */
+export interface NpmSearchPackage {
+    name: string;
+    version: string;
+    description?: string;
+    keywords?: string[];
+    links?: {
+        npm?: string;
+    };
+    publisher?: {
+        username?: string;
+    };
+    date?: string;
+}
+/** One shaped search result. */
+export interface LibrarySearchResult {
+    name: string;
+    version: string;
+    description: string | null;
+    /** Category id derived from the package's keywords, or null. */
+    category: string | null;
+    npmUrl: string;
+    published: string | null;
+}
+/**
+ * Build the `text=` query for the registry search endpoint. Exported for tests.
+ */
+export declare function buildLibrarySearchQuery(text?: string, categoryId?: string): string;
+/**
+ * Search npm for cuttlefish library packages. `size` caps results (registry
+ * max is 250). Throws on HTTP failure — the CLI surfaces the message.
+ */
+export declare function searchLibraryPackages(text?: string, categoryId?: string, size?: number): Promise<LibrarySearchResult[]>;
+export declare function shapeResult(pkg: NpmSearchPackage): LibrarySearchResult;

package/dist/library/registry-search.js

@@ -0,0 +1,50 @@
+// ---------------------------------------------------------------------------
+// npm registry search for cuttlefish library packages — the discovery client
+// behind `cuttlefish library search`.
+//
+// Ports the concept from the typecad binary's `typecad package` command: the
+// npm registry's search endpoint is the catalog, keywords are the taxonomy.
+// The marker keyword (cuttlefish-library) is always part of the query; a
+// category narrows it; free text ANDs on top. The endpoint ANDs `keywords:`
+// terms, so the composition needs no client-side filtering.
+// ---------------------------------------------------------------------------
+import { LIBRARY_MARKER_KEYWORD, categoryKeyword, categoryFromKeywords } from "./catalog.js";
+const REGISTRY_SEARCH_ENDPOINT = "https://registry.npmjs.org/-/v1/search";
+/**
+ * Build the `text=` query for the registry search endpoint. Exported for tests.
+ */
+export function buildLibrarySearchQuery(text, categoryId) {
+    const terms = [`keywords:${LIBRARY_MARKER_KEYWORD}`];
+    if (categoryId) {
+        terms.push(`keywords:${categoryKeyword(categoryId)}`);
+    }
+    const freeText = text?.trim();
+    if (freeText) {
+        // Free text terms are space-separated; the registry ANDs them.
+        terms.push(freeText);
+    }
+    return terms.join(" ");
+}
+/**
+ * Search npm for cuttlefish library packages. `size` caps results (registry
+ * max is 250). Throws on HTTP failure — the CLI surfaces the message.
+ */
+export async function searchLibraryPackages(text, categoryId, size = 250) {
+    const url = `${REGISTRY_SEARCH_ENDPOINT}?text=${encodeURIComponent(buildLibrarySearchQuery(text, categoryId))}&size=${size}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`npm registry returned ${res.status}: ${res.statusText}`);
+    }
+    const data = (await res.json());
+    return data.objects.map((o) => shapeResult(o.package));
+}
+export function shapeResult(pkg) {
+    return {
+        name: pkg.name,
+        version: pkg.version,
+        description: pkg.description ?? null,
+        category: categoryFromKeywords(pkg.keywords),
+        npmUrl: pkg.links?.npm ?? `https://www.npmjs.com/package/${pkg.name}`,
+        published: pkg.date ?? null,
+    };
+}

package/dist/library/validate.d.ts

@@ -0,0 +1,17 @@
+import { type SelfCheckFinding } from "../emit/compliance/index.js";
+export interface LibraryValidationFinding {
+    severity: "error" | "warning";
+    message: string;
+}
+export interface LibraryValidationReport {
+    valid: boolean;
+    /** The package directory that was validated. */
+    dir: string;
+    errors: string[];
+    warnings: string[];
+    /** Unrecorded AUTOSAR violations in the shim sources (strict mode). */
+    autosarFindings: SelfCheckFinding[];
+}
+export declare function validateLibraryPackage(dir: string): LibraryValidationReport;
+/** Render the human-readable report. Returns the process exit code (0/1). */
+export declare function printValidationReport(report: LibraryValidationReport): number;

package/dist/library/validate.js

@@ -0,0 +1,175 @@
+// ---------------------------------------------------------------------------
+// `cuttlefish library validate` — the standalone library-package validator.
+//
+// Before this, manifest errors only surfaced at import time inside a
+// transpile. This runs the same checks (and more) on a package directory:
+// manifest schema, file existence, include/gateToken consistency, npm
+// keyword consistency, and an AUTOSAR --strict pass over the shim bytes —
+// the same self-check the generated application runs over them.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import { ComplianceContext, runSelfCheck } from "../emit/compliance/index.js";
+import { LIBRARY_MARKER_KEYWORD, libraryCategory } from "./catalog.js";
+function readJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+export function validateLibraryPackage(dir) {
+    const errors = [];
+    const warnings = [];
+    const root = path.resolve(dir);
+    const fail = (message) => {
+        errors.push(message);
+    };
+    // ── Manifest ───────────────────────────────────────────────────────────
+    const manifestPath = path.join(root, "cuttlefish.library.json");
+    let manifest;
+    if (!fs.existsSync(manifestPath)) {
+        fail("cuttlefish.library.json not found — is this a library package directory?");
+    }
+    else {
+        try {
+            manifest = readJson(manifestPath);
+        }
+        catch (e) {
+            fail(`cuttlefish.library.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (manifest) {
+        for (const field of ["id", "module", "framework", "include", "gateToken"]) {
+            if (typeof manifest[field] !== "string" || manifest[field].length === 0) {
+                fail(`Manifest field '${field}' must be a non-empty string.`);
+            }
+        }
+        if (!Array.isArray(manifest.shims) || manifest.shims.length === 0) {
+            fail("Manifest 'shims' must be a non-empty array.");
+        }
+        const include = typeof manifest.include === "string" ? manifest.include : "";
+        const gateToken = typeof manifest.gateToken === "string" ? manifest.gateToken : "";
+        if (include.length > 0 && gateToken.length > 0 && !include.includes(gateToken)) {
+            fail(`The gate token '${gateToken}' does not appear in the include '${include}' — ` +
+                `the include line is the only guaranteed emission, so contributions would never gate on.`);
+        }
+        // ── Shim files ───────────────────────────────────────────────────────
+        if (Array.isArray(manifest.shims)) {
+            for (const entry of manifest.shims) {
+                if (typeof entry !== "object" ||
+                    entry === null ||
+                    typeof entry.path !== "string" ||
+                    typeof entry.outName !== "string") {
+                    fail("Every 'shims' entry needs string 'path' and 'outName' fields.");
+                    continue;
+                }
+                const shimPath = path.join(root, entry.path);
+                if (!fs.existsSync(shimPath)) {
+                    fail(`Shim file listed in the manifest is missing: ${entry.path}`);
+                }
+            }
+        }
+        // ── Overlay fragment ─────────────────────────────────────────────────
+        if (typeof manifest.overlay === "string" && manifest.overlay.length > 0) {
+            const overlayPath = path.join(root, manifest.overlay);
+            if (!fs.existsSync(overlayPath)) {
+                fail(`Overlay fragment listed in the manifest is missing: ${manifest.overlay}`);
+            }
+        }
+    }
+    // ── package.json consistency ───────────────────────────────────────────
+    const pkgJsonPath = path.join(root, "package.json");
+    let pkgName;
+    let pkgKeywords = [];
+    if (!fs.existsSync(pkgJsonPath)) {
+        warnings.push("No package.json — nothing published, so keyword checks are skipped.");
+    }
+    else {
+        try {
+            const pkg = readJson(pkgJsonPath);
+            if (typeof pkg.name === "string") {
+                pkgName = pkg.name;
+            }
+            if (Array.isArray(pkg.keywords)) {
+                pkgKeywords = pkg.keywords.filter((k) => typeof k === "string");
+            }
+            if (Array.isArray(pkg.files) && !pkg.files.includes("cuttlefish.library.json")) {
+                fail("package.json 'files' must include 'cuttlefish.library.json' or the manifest will not ship.");
+            }
+        }
+        catch (e) {
+            fail(`package.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (pkgKeywords.length > 0 && !pkgKeywords.map((k) => k.toLowerCase()).includes(LIBRARY_MARKER_KEYWORD)) {
+        fail(`package.json keywords must include the marker '${LIBRARY_MARKER_KEYWORD}' — it is what library search scans for.`);
+    }
+    const categoryKeywords = pkgKeywords.filter((k) => k.startsWith("cuttlefish-") && k !== LIBRARY_MARKER_KEYWORD);
+    if (pkgKeywords.length > 0 && categoryKeywords.length === 0) {
+        warnings.push(`No category keyword in package.json — add one of ${LIBRARY_MARKER_KEYWORD}'s siblings (e.g. cuttlefish-led) so the library is browsable by category.`);
+    }
+    for (const kw of categoryKeywords) {
+        const id = kw.slice("cuttlefish-".length);
+        if (!libraryCategory(id)) {
+            warnings.push(`Keyword '${kw}' is not a known category keyword (cuttlefish-<id>).`);
+        }
+    }
+    if (categoryKeywords.length > 1) {
+        warnings.push(`Multiple category keywords (${categoryKeywords.join(", ")}) — search results show the first taxonomy match only.`);
+    }
+    if (manifest && pkgName !== undefined && typeof manifest.module === "string" && manifest.module !== pkgName) {
+        fail(`Manifest 'module' (${manifest.module}) must equal the package.json name (${pkgName}) — ` +
+            `the import specifier users write resolves against the package name.`);
+    }
+    // ── AUTOSAR strict over the shim bytes ─────────────────────────────────
+    const autosarFindings = [];
+    if (manifest && Array.isArray(manifest.shims)) {
+        const headerLines = [];
+        const sourceLines = [];
+        let anyReadable = false;
+        for (const entry of manifest.shims) {
+            if (typeof entry !== "object" || entry === null)
+                continue;
+            const rel = entry.path;
+            if (typeof rel !== "string")
+                continue;
+            const abs = path.join(root, rel);
+            if (!fs.existsSync(abs))
+                continue;
+            anyReadable = true;
+            const content = fs.readFileSync(abs, "utf8").split("\n");
+            if (abs.endsWith(".h") || abs.endsWith(".hpp")) {
+                headerLines.push(...content, "");
+            }
+            else {
+                sourceLines.push(...content, "");
+            }
+        }
+        if (anyReadable) {
+            const ctx = new ComplianceContext("strict");
+            autosarFindings.push(...runSelfCheck(ctx, sourceLines, headerLines));
+        }
+    }
+    for (const finding of autosarFindings) {
+        fail(`AUTOSAR ${finding.ruleId} (${finding.file} line ${finding.line}): ${finding.snippet}`);
+    }
+    return {
+        valid: errors.length === 0,
+        dir: root,
+        errors,
+        warnings,
+        autosarFindings,
+    };
+}
+/** Render the human-readable report. Returns the process exit code (0/1). */
+export function printValidationReport(report) {
+    for (const warning of report.warnings) {
+        console.log(`  ! ${warning}`);
+    }
+    for (const error of report.errors) {
+        console.log(`  x ${error}`);
+    }
+    if (report.valid) {
+        console.log(`  Valid library package${report.warnings.length > 0 ? ` (${report.warnings.length} warning${report.warnings.length === 1 ? "" : "s"})` : ""}.`);
+        return 0;
+    }
+    console.log(`  ${report.errors.length} error${report.errors.length === 1 ? "" : "s"}.`);
+    return 1;
+}

package/dist/library-packages.d.ts

@@ -0,0 +1,95 @@
+import type { LibraryDefinition } from "./types.js";
+/** A native source file a library contributes to the emitted sources. */
+export interface CuttlefishLibraryShim {
+    /** Path of the shim file, relative to the library package root. */
+    path: string;
+    /** File name the shim is written as, in the emitted source directory. */
+    outName: string;
+}
+/** The parsed `cuttlefish.library.json` manifest. */
+export interface CuttlefishLibraryManifest {
+    /** Stable library id (diagnostics / sidecar records). */
+    id: string;
+    /** The import specifier this library resolves (e.g. '@typecad/zephyr-esp32s3-rgb'). */
+    module: string;
+    /** The framework (strategy id) this library requires, e.g. 'zephyr'. */
+    framework: string;
+    /** Build-target prefixes this library supports (matched against buildTarget). */
+    targets?: string[];
+    /** C++ include directive content for the import, e.g. '"__tc_rgbled.h"'. */
+    include: string;
+    /** Token whose presence in emitted sources gates the library's artifacts. */
+    gateToken: string;
+    /** Native shim files written into the emitted source directory. */
+    shims: CuttlefishLibraryShim[];
+    /** CONFIG_ lines contributed to the framework's prj.conf. */
+    kconfig?: string[];
+    /** Path of a devicetree overlay fragment, relative to the package root. */
+    overlay?: string;
+}
+/** A registered library: manifest + resolved package root. */
+export interface RegisteredCuttlefishLibrary {
+    manifest: CuttlefishLibraryManifest;
+    packageRoot: string;
+}
+/** One record of the `libraries.json` sidecar (build-time contribution set). */
+export interface LibrarySidecarEntry {
+    id: string;
+    module: string;
+    framework: string;
+    gateToken: string;
+    kconfig: string[];
+    /** Absolute path of the overlay fragment, or null. */
+    overlay: string | null;
+    /** Shim file names written into the emitted source directory. */
+    shims: string[];
+}
+/** Sidecar file name — written next to the emitted sources. */
+export declare const LIBRARY_SIDECAR_NAME = "libraries.json";
+/** Clear all registrations. Called once per transpilation, before graph build. */
+export declare function resetCuttlefishLibraries(): void;
+/** All libraries registered during this transpilation (import-driven). */
+export declare function getRegisteredCuttlefishLibraries(): RegisteredCuttlefishLibrary[];
+/**
+ * Whether the specifier resolves to a library registered in this
+ * transpilation. Library packages are exempt from the @typecad/* "SDK
+ * imports are type-level only" include skip — their import IS the include
+ * of the shim header.
+ */
+export declare function isRegisteredCuttlefishLibrary(moduleSpecifier: string): boolean;
+/**
+ * Resolve the package root for a bare npm specifier from the importing file,
+ * then register the package as a cuttlefish library if it ships a
+ * `cuttlefish.library.json`. Returns true when the specifier resolved to a
+ * registered library (the import must then be skipped by the graph builder).
+ */
+export declare function registerCuttlefishLibraryFromSpecifier(fromFile: string, moduleSpecifier: string): boolean;
+/** Libdef entries for the registry: import → shim include. */
+export declare function cuttlefishLibraryLibdefs(): LibraryDefinition[];
+/**
+ * Validate registered libraries against the loaded framework (and, when
+ * known, the build target). Throws with an actionable message when a library
+ * cannot work in this project — far earlier and clearer than the native
+ * compiler would.
+ */
+export declare function validateCuttlefishLibraries(frameworkId: string, buildTarget?: string): void;
+/**
+ * Emit the library artifacts for the libraries actually used in this
+ * transpilation, and write the `libraries.json` sidecar:
+ *
+ *   1. scan the emitted sources for each library's gate token;
+ *   2. write (write-if-changed) the shims of every gated library into the
+ *      emitted source directory — the framework scaffold's CMake/sketch
+ *      regen picks the sources up automatically;
+ *   3. delete shim files recorded in the previous sidecar that are no longer
+ *      used, so removing an import removes its native code;
+ *   4. persist the sidecar (even when empty — that clears stale state).
+ */
+export declare function writeCuttlefishLibraryArtifacts(outDir: string, srcDir: string): void;
+/**
+ * Read the `libraries.json` sidecar for build-time consumers (framework
+ * toolchains). Tolerant of a missing or corrupt file (returns []).
+ */
+export declare function readCuttlefishLibrarySidecar(outDir: string): LibrarySidecarEntry[];
+/** Re-exported for transpile.ts libdef injection convenience. */
+export declare function libraryDefinitionKey(module: string): string;