@componentonce/compiler-esbuild 0.1.0-beta.0 → 0.1.0-beta.1

package/README.md

@@ -1,31 +1,119 @@
 # @componentonce/compiler-esbuild
 
-Optional trusted compiler/evaluator tooling for ComponentOnce.
+Optional trusted compiler, packager, and evaluator tooling for ComponentOnce.
 
-This package is not part of the core runtime ABI and owns no storage or transport.
+This package is not part of the core runtime ABI. It owns no storage or transport.
 
-## Generic modules
+## CLI: source file to self-describing package
 
-compileTrustedModule compiles JavaScript/TypeScript into an immutable CommonJS artifact. It adds no runtime externals implicitly. Any imported host module must be declared explicitly through externalModules and injected when instantiateTrustedBundle executes the trusted artifact.
+Install the renderer adapter you use plus this compiler, then:
 
-This is suitable for ordinary DOM/HTML modules and other non-React implementations.
+```sh
+componentonce build ./src/amount-card.tsx \
+  --renderer react \
+  --out ./dist/amount-card.componentonce.json
+```
 
-## React convenience
+The default renderer is `react`, so this is also valid:
 
-compileTrustedReactModule wraps the generic compiler with automatic JSX transformation and allows the React module specifiers as host externals:
+```sh
+componentonce build ./src/amount-card.tsx
+```
 
-- react
-- react/jsx-runtime
-- react/jsx-dev-runtime
+Useful options:
 
-React is still never bundled. The host injects its own React singleton at instantiation. Additional host SDK imports use additionalExternalModules.
+```text
+--renderer <id>    Renderer id recorded in the package
+-o, --out <file>   Output JSON package
+--export <name>    Definition export name (default: definition)
+--external <name>  Additional host module kept external and loaded for trusted build discovery
+```
 
-## Artifact and trust model
+React builds automatically externalize `react`, the JSX runtimes, and `@componentonce/react`. DOM builds automatically externalize `@componentonce/dom`. Relative imports are bundled from the entry file directory; undeclared package imports still fail rather than being silently pulled from the compiler process.
 
-Artifacts contain deterministic bundle text, byte length, SHA-256 hash/integrity, normalized diagnostics, exact referenced externals, and esbuild metafile data.
+The source module normally exports one definition:
 
-instantiateTrustedBundle deliberately uses new Function with a narrow injected require map. It is for trusted internal code and is not a security sandbox.
+```tsx
+import {
+  createReactRequirement,
+  defineReactComponent,
+} from "@componentonce/react";
 
-Storage is host-owned: compiled text/bytes can live in a database-backed file object, local disk, object storage, or any other adapter.
+export const definition = defineReactComponent<Props, HostContext, Payload>({
+  manifest: {
+    id: "example/amount-card",
+    version: "1.0.0",
+    requirements: [createReactRequirement("19.3.0")],
+  },
+  component({ props, context, payload }) {
+    return <strong>{props.label}: {context.formatAmount(payload.amount)}</strong>;
+  },
+});
+```
+
+The high-level builder evaluates trusted source once during build to discover the exported manifest. The resulting package stores that manifest next to the bundle, so catalogs can inspect identity, version, and requirements without executing the component.
+
+## Programmatic packaging
+
+```ts
+import * as React from "react";
+import * as jsxRuntime from "react/jsx-runtime";
+import * as ComponentOnceReact from "@componentonce/react";
+import {
+  buildTrustedReactPackage,
+  serializeTrustedComponentPackage,
+} from "@componentonce/compiler-esbuild";
+
+const componentPackage = await buildTrustedReactPackage({
+  source,
+  sourceFileName: "amount-card.tsx",
+  resolveDir: sourceDirectory,
+  externals: {
+    react: React,
+    "react/jsx-runtime": jsxRuntime,
+    "@componentonce/react": ComponentOnceReact,
+  },
+});
+
+await store.put(
+  componentPackage.manifest.id,
+  serializeTrustedComponentPackage(componentPackage),
+);
+```
+
+At runtime:
+
+```ts
+import {
+  instantiateTrustedComponentPackage,
+  parseTrustedComponentPackage,
+} from "@componentonce/compiler-esbuild";
+
+const componentPackage = parseTrustedComponentPackage(await store.get(...));
+
+console.log(componentPackage.manifest); // no component execution
+
+const definition = instantiateTrustedComponentPackage(componentPackage, {
+  externals: {
+    react: React,
+    "react/jsx-runtime": jsxRuntime,
+    "@componentonce/react": ComponentOnceReact,
+  },
+});
+```
+
+Instantiation verifies that the definition inside the executable bundle still has the same manifest as the package envelope.
+
+## Low-level compilation
+
+`compileTrustedModule` compiles JavaScript/TypeScript into an immutable CommonJS artifact. Caller-declared package imports remain external. Relative imports can be bundled when `resolveDir` is supplied.
+
+`compileTrustedReactModule` adds automatic JSX transformation and React/JSX host externals while still never bundling React.
+
+Artifacts contain deterministic bundle text, byte length, SHA-256 hash/integrity, normalized diagnostics, exact external imports, and esbuild metafile data.
+
+## Trust model
+
+`instantiateTrustedBundle` deliberately uses `new Function` with a narrow injected require map. It is for trusted internal code and is not a security sandbox.
 
 esbuild transpiles TypeScript syntax but does not perform semantic type checking; hosts that need that guarantee should run their TypeScript checker separately.

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** Run the ComponentOnce command line interface with ordinary process arguments. */
+export declare function runComponentOnceCli(args: readonly string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA2BA,oFAAoF;AACpF,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwDhF"}

package/dist/cli.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { basename, dirname, extname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { buildTrustedDefinitionPackage, buildTrustedReactPackage, serializeTrustedComponentPackage, } from "./package.js";
+const REACT_HOST_EXTERNALS = [
+    "react",
+    "react/jsx-runtime",
+    "react/jsx-dev-runtime",
+    "@componentonce/react",
+];
+const DOM_HOST_EXTERNALS = ["@componentonce/dom"];
+/** Run the ComponentOnce command line interface with ordinary process arguments. */
+export async function runComponentOnceCli(args) {
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(usage());
+        return;
+    }
+    if (args[0] !== "build") {
+        throw new Error("Unknown command \"" + String(args[0]) + "\".\n\n" + usage());
+    }
+    const options = parseBuildArgs(args.slice(1));
+    const entryPath = resolve(options.entry);
+    const source = await readFile(entryPath, "utf8");
+    const sourceDir = dirname(entryPath);
+    const externalNames = uniqueStrings([
+        ...(options.renderer === "react" ? REACT_HOST_EXTERNALS : []),
+        ...(options.renderer === "dom" ? DOM_HOST_EXTERNALS : []),
+        ...options.externalModules,
+    ]);
+    const externals = await loadExternals(externalNames, sourceDir);
+    const componentPackage = options.renderer === "react"
+        ? await buildTrustedReactPackage({
+            source,
+            sourceFileName: basename(entryPath),
+            resolveDir: sourceDir,
+            externals,
+            ...(options.definitionExport === undefined
+                ? {}
+                : { definitionExport: options.definitionExport }),
+        })
+        : await buildTrustedDefinitionPackage({
+            source,
+            sourceFileName: basename(entryPath),
+            resolveDir: sourceDir,
+            renderer: options.renderer,
+            externals,
+            ...(options.definitionExport === undefined
+                ? {}
+                : { definitionExport: options.definitionExport }),
+        });
+    const outPath = resolve(options.out);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, serializeTrustedComponentPackage(componentPackage) + "\n", "utf8");
+    process.stdout.write("Built " +
+        componentPackage.manifest.id +
+        "@" +
+        componentPackage.manifest.version +
+        " (" +
+        componentPackage.renderer +
+        ") -> " +
+        outPath +
+        "\n");
+}
+function parseBuildArgs(args) {
+    const entry = args[0];
+    if (entry === undefined || entry.startsWith("-")) {
+        throw new Error("componentonce build requires an entry source file.\n\n" + usage());
+    }
+    let renderer = "react";
+    let out;
+    let definitionExport;
+    const externalModules = [];
+    for (let index = 1; index < args.length; index += 1) {
+        const arg = args[index];
+        switch (arg) {
+            case "--renderer": {
+                renderer = requireOptionValue(args, ++index, "--renderer");
+                break;
+            }
+            case "--out":
+            case "-o": {
+                out = requireOptionValue(args, ++index, String(arg));
+                break;
+            }
+            case "--export": {
+                definitionExport = requireOptionValue(args, ++index, "--export");
+                break;
+            }
+            case "--external": {
+                externalModules.push(requireOptionValue(args, ++index, "--external"));
+                break;
+            }
+            default:
+                throw new Error("Unknown build option \"" + String(arg) + "\".\n\n" + usage());
+        }
+    }
+    return {
+        entry,
+        renderer,
+        out: out ?? defaultOutputPath(entry),
+        ...(definitionExport === undefined ? {} : { definitionExport }),
+        externalModules,
+    };
+}
+function requireOptionValue(args, index, option) {
+    const value = args[index];
+    if (value === undefined || value.startsWith("-")) {
+        throw new Error(option + " requires a value.");
+    }
+    return value;
+}
+function defaultOutputPath(entry) {
+    const extension = extname(entry);
+    const base = extension === "" ? entry : entry.slice(0, -extension.length);
+    return base + ".componentonce.json";
+}
+async function loadExternals(specifiers, sourceDir) {
+    const resolver = createRequire(pathToFileURL(resolve(sourceDir, "__componentonce_resolve__.mjs")));
+    const externals = {};
+    for (const specifier of specifiers) {
+        externals[specifier] = await loadExternal(specifier, resolver);
+    }
+    return externals;
+}
+async function loadExternal(specifier, resolver) {
+    try {
+        return resolver(specifier);
+    }
+    catch (error) {
+        if (!canRetryAsEsm(error))
+            throw error;
+        return import(specifier);
+    }
+}
+function canRetryAsEsm(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    const code = error.code;
+    return code === "ERR_REQUIRE_ESM" || code === "ERR_PACKAGE_PATH_NOT_EXPORTED";
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function usage() {
+    return [
+        "ComponentOnce trusted component builder",
+        "",
+        "Usage:",
+        "  componentonce build <entry> [options]",
+        "",
+        "Options:",
+        "  --renderer <id>    Renderer id recorded in the package (default: react)",
+        "  -o, --out <file>   Output JSON package (default: <entry>.componentonce.json)",
+        "  --export <name>    Definition export name (default: definition)",
+        "  --external <name>  Host module to keep external and load for trusted build-time discovery",
+        "  -h, --help         Show this help",
+        "",
+        "React builds automatically externalize react, JSX runtimes, and @componentonce/react.",
+        "DOM builds automatically externalize @componentonce/dom.",
+        "Relative imports are bundled from the entry file directory.",
+        "",
+    ].join("\n");
+}
+runComponentOnceCli(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write("componentonce: " + message + "\n");
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/compiler.d.ts

@@ -0,0 +1,141 @@
+import { type Metafile } from "esbuild";
+/** Stable identifier for the trusted CommonJS bundle contract emitted by this package. */
+export declare const COMPONENTONCE_TRUSTED_BUNDLE_FORMAT: "componentonce.trusted-cjs.v1";
+/** Source syntaxes accepted by the trusted compiler. */
+export type ComponentOnceSourceLoader = "js" | "jsx" | "ts" | "tsx";
+/** JSX transform mode forwarded to esbuild by the generic compiler. */
+export type ComponentOnceJsxMode = "transform" | "preserve" | "automatic";
+/** Input for compiling one trusted JavaScript or TypeScript module. */
+export interface ComponentOnceCompileInput {
+    /** TypeScript, TSX, JavaScript, or JSX module source. */
+    readonly source: string;
+    /** Stable diagnostic/source-map name. */
+    readonly sourceFileName?: string;
+    /** Explicit source syntax, otherwise inferred from sourceFileName. */
+    readonly loader?: ComponentOnceSourceLoader;
+    /** Directory used to resolve and bundle relative imports from the in-memory entry source. */
+    readonly resolveDir?: string;
+    /** Exact import specifiers the host will inject during instantiation. */
+    readonly externalModules?: readonly string[];
+    /** JSX transform mode; generic compilation defaults to transform. */
+    readonly jsx?: ComponentOnceJsxMode;
+}
+/** React convenience compiler input; React externals are supplied by the wrapper. */
+export interface ComponentOnceReactCompileInput {
+    readonly source: string;
+    readonly sourceFileName?: string;
+    readonly loader?: ComponentOnceSourceLoader;
+    /** Directory used to resolve and bundle relative imports from the in-memory entry source. */
+    readonly resolveDir?: string;
+    /** Additional non-React host externals. */
+    readonly additionalExternalModules?: readonly string[];
+}
+/** Source location attached to a normalized compiler diagnostic. */
+export interface ComponentOnceDiagnosticLocation {
+    /** Source file name supplied to the compiler. */
+    readonly file: string;
+    /** One-based source line. */
+    readonly line: number;
+    /** Zero-based source column. */
+    readonly column: number;
+    /** Length of the highlighted source range. */
+    readonly length: number;
+    /** Full source line associated with the diagnostic. */
+    readonly lineText: string;
+}
+/** Secondary explanatory note attached to a compiler diagnostic. */
+export interface ComponentOnceDiagnosticNote {
+    /** Human-readable note. */
+    readonly text: string;
+    /** Source location when esbuild can identify one. */
+    readonly location?: ComponentOnceDiagnosticLocation;
+}
+/** Storage-neutral compiler warning or error. */
+export interface ComponentOnceDiagnostic {
+    /** Diagnostic severity. */
+    readonly kind: "error" | "warning";
+    /** Human-readable diagnostic text. */
+    readonly text: string;
+    /** Primary source location when available. */
+    readonly location?: ComponentOnceDiagnosticLocation;
+    /** Supporting notes supplied by esbuild. */
+    readonly notes: readonly ComponentOnceDiagnosticNote[];
+}
+/** Read-only esbuild metadata describing the emitted bundle and its external imports. */
+export type ComponentOnceBundleMetafile = Readonly<Metafile>;
+/** Immutable, storage-neutral output of the trusted module compiler. */
+export interface ComponentOnceTrustedBundleArtifact {
+    /** Bundle contract understood by `instantiateTrustedBundle`. */
+    readonly format: typeof COMPONENTONCE_TRUSTED_BUNDLE_FORMAT;
+    /** Executable CommonJS bundle text. */
+    readonly code: string;
+    /** UTF-8 byte length of `code`. */
+    readonly byteLength: number;
+    /** Lowercase hexadecimal SHA-256 digest of `code`. */
+    readonly sha256: string;
+    /** Subresource-integrity-style SHA-256 value for `code`. */
+    readonly integrity: string;
+    /** Exact external module specifiers referenced by the emitted bundle. */
+    readonly externalModules: readonly string[];
+    /** Normalized non-fatal compiler diagnostics. */
+    readonly diagnostics: readonly ComponentOnceDiagnostic[];
+    /** esbuild metadata for dependency and output inspection. */
+    readonly metafile: ComponentOnceBundleMetafile;
+}
+/** Compilation failure with stable, normalized esbuild diagnostics. */
+export declare class ComponentOnceCompileError extends Error {
+    /** Compiler errors that caused the build to fail. */
+    readonly diagnostics: readonly ComponentOnceDiagnostic[];
+    constructor(diagnostics: readonly ComponentOnceDiagnostic[]);
+}
+/** Exact host-owned module values exposed to a trusted bundle's local `require`. */
+export type ComponentOnceHostExternals = Readonly<Record<string, unknown>>;
+/** JavaScript text, UTF-8 bytes, or an in-memory artifact accepted by the trusted evaluator. */
+export type ComponentOnceTrustedBundleSource = string | Uint8Array | ComponentOnceTrustedBundleArtifact;
+/** Options controlling explicit external injection and optional integrity verification. */
+export interface InstantiateTrustedBundleOptions {
+    /** Exact external values, including the host's React and JSX runtime instances. */
+    readonly externals: ComponentOnceHostExternals;
+    /** Expected integrity for separately loaded text/bytes; artifacts verify their own value by default. */
+    readonly expectedIntegrity?: string;
+    /** Debugger-only source name appended to the evaluated bundle. */
+    readonly sourceName?: string;
+}
+/** Deterministic error raised when a bundle requests an external the host did not inject. */
+export declare class ComponentOnceMissingExternalError extends Error {
+    /** Exact module specifier requested by the bundle. */
+    readonly specifier: string;
+    /** Sorted external specifiers supplied by the host. */
+    readonly availableExternals: readonly string[];
+    constructor(specifier: string, availableExternals: readonly string[]);
+}
+/** Error raised when loaded bundle content does not match its expected SHA-256 integrity. */
+export declare class ComponentOnceIntegrityError extends Error {
+    /** Expected subresource-integrity-style SHA-256 value. */
+    readonly expectedIntegrity: string;
+    /** Actual subresource-integrity-style SHA-256 value. */
+    readonly actualIntegrity: string;
+    constructor(expectedIntegrity: string, actualIntegrity: string);
+}
+/**
+ * Compile one trusted module into a deterministic CommonJS artifact.
+ *
+ * Only caller-declared imports remain external. This generic path does not add React or any other
+ * runtime implicitly; every external must be injected explicitly by the host at instantiation.
+ */
+export declare function compileTrustedModule(input: ComponentOnceCompileInput): Promise<ComponentOnceTrustedBundleArtifact>;
+/** Compile a trusted React module while keeping the host React singleton external. */
+export declare function compileTrustedReactModule(input: ComponentOnceReactCompileInput): Promise<ComponentOnceTrustedBundleArtifact>;
+/** Calculate a subresource-integrity-style SHA-256 value for bundle text or UTF-8 bytes. */
+export declare function calculateTrustedBundleIntegrity(source: string | Uint8Array): string;
+/** Throw when bundle text or bytes do not match an expected SHA-256 integrity value. */
+export declare function assertTrustedBundleIntegrity(source: string | Uint8Array, expectedIntegrity: string): void;
+/**
+ * Execute a trusted bundle with a deliberately narrow CommonJS environment.
+ *
+ * This API uses `new Function` and is only for trusted internal code. It is not a sandbox: evaluated
+ * code retains access to JavaScript globals. The only available `require` values are provided by
+ * `options.externals`, so React is always the exact instance selected by the host.
+ */
+export declare function instantiateTrustedBundle<TExports = Record<string, unknown>>(source: ComponentOnceTrustedBundleSource, options: InstantiateTrustedBundleOptions): TExports;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"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"}