51 lines
2.3 KiB
Markdown
51 lines
2.3 KiB
Markdown
# @suaveplan/wasm-compiler-javy
|
|
|
|
TS->WASM compiler closing **Stage-8 gate 2.8**. Thin orchestrator around `Bun.build` (bundle) + an injected WASI-stdio ABI shim + **Javy v8.1.1** (JS->WASM) + `WebAssembly.compile` (ABI validation) + a host-side route-extraction probe + manifest sidecar emit.
|
|
|
|
The produced `.wasm` artifact speaks the WASI-stdio length-prefixed JSON framing protocol shared with `@suaveplan/api-sandbox-wasm-host-bridge`, so any plugin compiled here is deployable through `abiVariant: "wasi-stdio"` without further glue.
|
|
|
|
## Pipeline
|
|
|
|
```text
|
|
pluginEntry ──[1]──> bundled ESM JS ──[2]──> ABI-shimmed JS ──[3]──> .wasm ──[4]──> validate ──[5]──> route extract ──[6]──> manifest
|
|
Bun.build prepend WASI-stdio loop javy build reflect imports/exports {kind:"routes"} probe <basename>.wasm.json
|
|
```
|
|
|
|
## Public surface
|
|
|
|
```ts
|
|
import { compilePluginToWasm } from "@suaveplan/wasm-compiler-javy";
|
|
|
|
const result = await compilePluginToWasm({
|
|
pluginEntry: "/abs/path/to/plugin/src/index.ts",
|
|
outDir: "/tmp/plugin-wasm",
|
|
optimizeFor: "size", // default
|
|
sourcemaps: false, // default
|
|
});
|
|
// result: { wasmPath, metadataPath, sizeBytes, compilationMs, manifest }
|
|
```
|
|
|
|
CLI binary: `suaveplan-wasm-compile <entry> --out-dir <dir> [--optimize-for size|speed] [--sourcemaps]`.
|
|
|
|
## Conformance harness
|
|
|
|
```ts
|
|
import { runWasmCompilerConformance } from "@suaveplan/wasm-compiler-javy/testing";
|
|
```
|
|
|
|
Four invariants: ABI completeness, deterministic output, manifest fidelity, cross-bridge deployability.
|
|
|
|
## Error codes
|
|
|
|
`WASM_COMPILER.{BUNDLE_FAILED, BROWSER_INCOMPAT_DEPENDENCY, JAVY_PLATFORM_MISMATCH, JAVY_INVOCATION_FAILED, ABI_VALIDATION_FAILED, MANIFEST_MISSING_ROUTES}` — 6 codes via `defineCodes`, error class with **public constructor** (rule §19).
|
|
|
|
## OTel instruments
|
|
|
|
- `wasm_compiler.compiles_total{result}` (counter).
|
|
- `wasm_compiler.compile_duration_ms{result}` (histogram).
|
|
- `wasm_compiler.abi_validation_failures_total{missing_export}` (counter).
|
|
|
|
## Platform support
|
|
|
|
Javy binaries are downloaded at install time by the platform-specific wrapper packages: `@suaveplan/javy-cli-{linux-x64,linux-arm64,darwin-x64,darwin-arm64,win32-x64}`. The compiler resolves the matching wrapper via `optionalDependencies` so a single `bun install` stays cross-platform-safe.
|