@valancex/mesh-compiler 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @valancex/mesh-compiler
+
+The [MESH](https://github.com/ValanceX/Mesh) compiler, built for WebAssembly. Check MPRX, with or without a component manifest, and get back exactly the diagnostics `mesh check --format json` prints for the same inputs.
+
+It's the Rust compiler itself, compiled to WebAssembly, not a reimplementation: this package adds no rule of its own. It returns diagnostics only.
+
+```js
+import { check } from "@valancex/mesh-compiler";
+
+const document = await check({
+  source: generated,          // the MPRX text
+  path: "card.mprx",          // an identifier you choose; never read
+  model: {                    // optional: check what the file means, too
+    manifest: manifestText,   // the manifest's JSON text
+    path: "components.json",  // an identifier you choose; never read
+    component: "user-card",   // whose template `source` is: always explicit
+  },
+});
+
+for (const diagnostic of document.diagnostics) {
+  console.log(diagnostic.code, diagnostic.message);
+  // source.slice(diagnostic.span.start.utf16, diagnostic.span.end.utf16) is the text it points at.
+}
+```
+
+The [Using MESH from JavaScript](https://github.com/ValanceX/Mesh/blob/main/docs/guides/using-mesh-from-javascript.md) guide builds a generate-check-repair loop with it.
+
+## The API
+
+- **`check(input)`** returns a promise of the diagnostics document, the one [`schemas/diagnostics-v1.schema.json`](https://github.com/ValanceX/Mesh/blob/main/schemas/diagnostics-v1.schema.json) describes. Anything wrong with your MPRX or your manifest is a diagnostic in it, never an exception. Diagnostics about the manifest carry the manifest's `path`. Each position has a `byte` offset, a 1-based `line` and `column`, and, for JavaScript, `utf16` (an offset into your string) and `utf16Column`.
+- **`init(module)`** loads the WebAssembly module: a URL, its bytes, or a compiled `WebAssembly.Module`. In Node you don't need it; the package loads its own. In a browser, call it once before the first check, with the URL of `@valancex/mesh-compiler/mesh.wasm` as your setup serves it. Automatic loading by bundlers isn't part of this package's contract.
+- **`version`**: the package's version.
+- **`MeshVersionError`**: the WebAssembly module isn't this version's. No check runs against it.
+- **`MeshInternalError`**: the compiler itself failed (a bug). The failed compiler instance is discarded, and the next check uses a fresh one.
+- A `TypeError` for arguments of the wrong type.
+
+Paths are identifiers: the package never touches the file system. Strings are passed as UTF-8, so a lone surrogate in a JavaScript string becomes U+FFFD, as with any UTF-8 encoding.
+
+## Support
+
+Node 22 and 24, and browsers with WebAssembly. ESM only, with TypeScript declarations.
+
+## License
+
+MIT

package/dist/document.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The diagnostics document, as `schemas/diagnostics-v1.schema.json`
+ * describes it: what `mesh check --format json` prints, and what
+ * {@link check} returns. A later version may add properties; ignore any
+ * you don't know.
+ */
+export interface DiagnosticsDocument {
+    /** The version of the document's shape. */
+    version: 1;
+    /** Every diagnostic, in the order MESH reports them. */
+    diagnostics: Diagnostic[];
+}
+/** Only errors fail a check. */
+export type Severity = "error" | "warning";
+export interface Diagnostic {
+    severity: Severity;
+    /** The stable code, such as `"unknown-reference"`. Match on this, not on `message`. */
+    code: string;
+    /** The human-readable message. It may change between versions. */
+    message: string;
+    /** The path the span points into: the source's, or the manifest's for a `manifest-*` code. */
+    path: string;
+    span: Span;
+    /** Replacements that would probably fix the problem, best first. Usually empty. */
+    suggestions: Suggestion[];
+}
+export interface Suggestion {
+    replacement: string;
+    span: Span;
+}
+/** `end` is just past the span's last character. */
+export interface Span {
+    start: Position;
+    end: Position;
+}
+export interface Position {
+    /** A 0-based offset into the text's UTF-8 bytes; a byte-order mark counts. */
+    byte: number;
+    /** The 1-based line. */
+    line: number;
+    /** The 1-based column, in characters; a byte-order mark and a line's `\r` aren't columns. */
+    column: number;
+    /** The same place as `byte`, in UTF-16 code units: `source.slice(start.utf16, end.utf16)` is the span's text. */
+    utf16: number;
+    /** The 1-based column in UTF-16 code units, with `column`'s rules. */
+    utf16Column: number;
+}

package/dist/document.js

@@ -0,0 +1 @@
+export {};

package/dist/engine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The internal engine behind the public API: loading the WebAssembly
+ * module, checking its version, keeping one instance, moving bytes in and
+ * out of it, and discarding it after a failure.
+ *
+ * Deliberately boring (outline v0.4 I6): nothing here knows MPRX, the
+ * manifest, positions or diagnostics. It transfers UTF-8 in and the
+ * diagnostics document out, and checks only that what came out is a
+ * document at all. Not public API (D11): the package's `exports` map
+ * doesn't expose this file.
+ */
+import type { DiagnosticsDocument } from "./document.js";
+/**
+ * A failure at the boundary with the compiler: a trap (a Rust panic, or
+ * running out of memory), or a result that isn't a diagnostics document.
+ * It is never how a check reports a problem with its input; those are
+ * diagnostics. The failed compiler instance is discarded, and the next
+ * check uses a fresh one.
+ */
+export declare class MeshInternalError extends Error {
+    name: string;
+}
+/**
+ * The WebAssembly module isn't the version this package was built for, or
+ * isn't a MESH module at all. No check runs against it.
+ */
+export declare class MeshVersionError extends Error {
+    name: string;
+}
+/** What {@link init} accepts: where the module is, its bytes, or the module. */
+export type ModuleSource = URL | string | BufferSource | WebAssembly.Module;
+/** One check's inputs. */
+export interface CheckInput {
+    /** The MPRX source text. */
+    source: string;
+    /** An opaque identifier for the source, used only to name it in diagnostics. Never read. */
+    path: string;
+    /** The model to check against. Without one, only syntax and structure are checked. */
+    model?: {
+        /** The manifest's text. */
+        manifest: string;
+        /** An opaque identifier for the manifest, used only to name it in diagnostics. Never read. */
+        path: string;
+        /** The component whose template the source is. Always explicit. */
+        component: string;
+    };
+}
+/**
+ * Loads the module from `source` and checks its version. In Node, the
+ * package loads its own module on the first check, so this is only
+ * needed to use another copy; in a browser, it's needed once, before the
+ * first check. If it fails, nothing is kept.
+ */
+export declare function init(source: ModuleSource): Promise<void>;
+/** Checks `input`. See the package's `check`. */
+export declare function check(input: CheckInput): Promise<DiagnosticsDocument>;
+/**
+ * The instance in use, if any, for the package's own memory and failure
+ * tests. Not API.
+ */
+export declare function instanceForTests(): Record<string, unknown> | undefined;

package/dist/engine.js

@@ -0,0 +1,228 @@
+/**
+ * The internal engine behind the public API: loading the WebAssembly
+ * module, checking its version, keeping one instance, moving bytes in and
+ * out of it, and discarding it after a failure.
+ *
+ * Deliberately boring (outline v0.4 I6): nothing here knows MPRX, the
+ * manifest, positions or diagnostics. It transfers UTF-8 in and the
+ * diagnostics document out, and checks only that what came out is a
+ * document at all. Not public API (D11): the package's `exports` map
+ * doesn't expose this file.
+ */
+import { version } from "./version.js";
+/**
+ * A failure at the boundary with the compiler: a trap (a Rust panic, or
+ * running out of memory), or a result that isn't a diagnostics document.
+ * It is never how a check reports a problem with its input; those are
+ * diagnostics. The failed compiler instance is discarded, and the next
+ * check uses a fresh one.
+ */
+export class MeshInternalError extends Error {
+    name = "MeshInternalError";
+}
+/**
+ * The WebAssembly module isn't the version this package was built for, or
+ * isn't a MESH module at all. No check runs against it.
+ */
+export class MeshVersionError extends Error {
+    name = "MeshVersionError";
+}
+const CHECK_EXPORTS = [
+    "mesh_alloc",
+    "mesh_free",
+    "mesh_check",
+    "mesh_result_ptr",
+    "mesh_result_len",
+    "mesh_result_clear",
+];
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+/** The compiled module, once loaded. */
+let compiled;
+/** The instance in use. Dropped after any boundary failure. */
+let instance;
+/** Checks run one at a time, in call order. */
+let queue = Promise.resolve();
+function isNode() {
+    return typeof process !== "undefined" && typeof process.versions?.node === "string";
+}
+async function bytesOf(location) {
+    if (location.protocol === "file:" && isNode()) {
+        const { readFile } = await import("node:fs/promises");
+        return readFile(location);
+    }
+    const response = await fetch(location);
+    if (!response.ok) {
+        throw new Error(`could not fetch the MESH module from ${location.href}: ${response.status}`);
+    }
+    return response.arrayBuffer();
+}
+async function compile(source) {
+    if (source instanceof WebAssembly.Module) {
+        return source;
+    }
+    if (typeof source === "string" || source instanceof URL) {
+        const base = typeof location === "undefined" ? undefined : location.href;
+        return WebAssembly.compile(await bytesOf(new URL(source, base)));
+    }
+    return WebAssembly.compile(source);
+}
+/** Instantiates `module` and checks it's a MESH module of this version (I10). */
+async function instantiate(module) {
+    let exports;
+    try {
+        exports = (await WebAssembly.instantiate(module, {})).exports;
+    }
+    catch (cause) {
+        throw new MeshVersionError("this WebAssembly module isn't a MESH module", { cause });
+    }
+    const { memory, mesh_version_ptr, mesh_version_len } = exports;
+    if (!(memory instanceof WebAssembly.Memory) ||
+        typeof mesh_version_ptr !== "function" ||
+        typeof mesh_version_len !== "function") {
+        throw new MeshVersionError("this WebAssembly module isn't a MESH module: it has no version");
+    }
+    let found;
+    try {
+        const ptr = mesh_version_ptr();
+        const len = mesh_version_len();
+        found = decoder.decode(new Uint8Array(memory.buffer, ptr, len));
+    }
+    catch (cause) {
+        throw new MeshVersionError("this WebAssembly module's version can't be read", { cause });
+    }
+    if (found !== version) {
+        throw new MeshVersionError(`this package is @valancex/mesh-compiler ${version}, but its WebAssembly module is ${found}`);
+    }
+    for (const name of CHECK_EXPORTS) {
+        if (typeof exports[name] !== "function") {
+            throw new MeshVersionError(`this WebAssembly module ${found} has no ${name}`);
+        }
+    }
+    // A plain copy of the exports (theirs is frozen), which the package's
+    // failure tests can instrument.
+    return { ...exports };
+}
+/**
+ * Loads the module from `source` and checks its version. In Node, the
+ * package loads its own module on the first check, so this is only
+ * needed to use another copy; in a browser, it's needed once, before the
+ * first check. If it fails, nothing is kept.
+ */
+export function init(source) {
+    const run = queue.then(async () => {
+        compiled = undefined;
+        instance = undefined;
+        const module = await compile(source);
+        instance = await instantiate(module);
+        compiled = module;
+    });
+    queue = run.catch(() => undefined);
+    return run;
+}
+async function current() {
+    if (instance) {
+        return instance;
+    }
+    if (!compiled) {
+        if (!isNode()) {
+            throw new Error("@valancex/mesh-compiler: call init() with the URL of mesh.wasm before the first check");
+        }
+        const module = await compile(new URL("./mesh.wasm", import.meta.url));
+        instance = await instantiate(module);
+        compiled = module;
+        return instance;
+    }
+    instance = await instantiate(compiled);
+    return instance;
+}
+/** Copies `bytes` into a new buffer in the module; returns its address. */
+function put(exports, bytes) {
+    const ptr = exports.mesh_alloc(bytes.length);
+    // Read `memory.buffer` after allocating: growing memory replaces it.
+    new Uint8Array(exports.memory.buffer, ptr, bytes.length).set(bytes);
+    return ptr;
+}
+function isDocument(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "version" in value &&
+        Array.isArray(value.diagnostics));
+}
+/** One check on `exports`. Any exception means the instance failed. */
+function transfer(exports, input) {
+    const model = input.model;
+    const texts = [
+        input.source,
+        input.path,
+        model?.manifest ?? "",
+        model?.path ?? "",
+        model?.component ?? "",
+    ].map((text) => encoder.encode(text));
+    const buffers = texts.map((bytes) => ({ ptr: put(exports, bytes), len: bytes.length }));
+    const status = exports.mesh_check(...buffers.flatMap(({ ptr, len }) => [ptr, len]), model ? 1 : 0);
+    for (const { ptr, len } of buffers) {
+        exports.mesh_free(ptr, len);
+    }
+    if (status !== 0) {
+        throw new MeshInternalError(`the compiler refused its input (status ${status})`);
+    }
+    const bytes = new Uint8Array(exports.memory.buffer, exports.mesh_result_ptr(), exports.mesh_result_len()).slice();
+    exports.mesh_result_clear();
+    const document = JSON.parse(decoder.decode(bytes));
+    if (!isDocument(document)) {
+        throw new MeshInternalError("the compiler's result isn't a diagnostics document");
+    }
+    return document;
+}
+function validate(input) {
+    if (typeof input !== "object" || input === null) {
+        throw new TypeError("check() takes an object: { source, path, model? }");
+    }
+    const strings = [
+        ["source", input.source],
+        ["path", input.path],
+    ];
+    if (input.model !== undefined) {
+        const model = input.model;
+        if (typeof model !== "object" || model === null) {
+            throw new TypeError("model must be an object: { manifest, path, component }");
+        }
+        strings.push(["model.manifest", model.manifest], ["model.path", model.path], ["model.component", model.component]);
+    }
+    for (const [name, value] of strings) {
+        if (typeof value !== "string") {
+            throw new TypeError(`${name} must be a string`);
+        }
+    }
+}
+async function checkNow(input) {
+    validate(input);
+    const exports = await current();
+    try {
+        return transfer(exports, input);
+    }
+    catch (cause) {
+        // The instance may be half-updated: never call it again (outline D6).
+        if (instance === exports) {
+            instance = undefined;
+        }
+        if (cause instanceof MeshInternalError) {
+            throw cause;
+        }
+        throw new MeshInternalError("the compiler failed", { cause });
+    }
+}
+/** Checks `input`. See the package's `check`. */
+export function check(input) {
+    const run = queue.then(() => checkNow(input));
+    queue = run.catch(() => undefined);
+    return run;
+}
+/**
+ * The instance in use, if any, for the package's own memory and failure
+ * tests. Not API.
+ */
+export function instanceForTests() {
+    return instance;
+}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The MESH compiler, in WebAssembly: check MPRX against a component
+ * manifest, and get back exactly the diagnostics `mesh check --format
+ * json` prints for the same inputs.
+ *
+ * ```js
+ * import { check } from "@valancex/mesh-compiler";
+ *
+ * const document = await check({
+ *   source: generated,
+ *   path: "card.mprx",
+ *   model: { manifest, path: "components.json", component: "user-card" },
+ * });
+ * for (const diagnostic of document.diagnostics) { ... }
+ * ```
+ *
+ * Paths are identifiers you choose; nothing reads them. The compiler runs
+ * entirely in WebAssembly, and this package adds no rule of its own.
+ *
+ * @packageDocumentation
+ */
+import type { CheckInput, ModuleSource } from "./engine.js";
+import type { DiagnosticsDocument } from "./document.js";
+export type { Diagnostic, DiagnosticsDocument, Position, Severity, Span, Suggestion, } from "./document.js";
+export type { CheckInput, ModuleSource } from "./engine.js";
+export { MeshInternalError, MeshVersionError } from "./engine.js";
+export { version } from "./version.js";
+/**
+ * Checks `input.source`, as the template of `input.model.component` when a
+ * model is given, and returns the diagnostics document. A problem with the
+ * input is a diagnostic in the document, never an exception.
+ *
+ * It rejects with a `TypeError` for arguments of the wrong type, with
+ * `MeshVersionError` if the WebAssembly module isn't this version's, and
+ * with `MeshInternalError` if the compiler itself fails. In a browser,
+ * call {@link init} first.
+ */
+export declare function check(input: CheckInput): Promise<DiagnosticsDocument>;
+/**
+ * Loads the WebAssembly module from `source`: a URL (or a string resolved
+ * against the page), its bytes, or a compiled `WebAssembly.Module`, and
+ * checks its version. Needed once in a browser, before the first check;
+ * in Node the package loads its own module. The module is
+ * `@valancex/mesh-compiler/mesh.wasm`.
+ */
+export declare function init(source: ModuleSource): Promise<void>;

package/dist/index.js

@@ -0,0 +1,47 @@
+/**
+ * The MESH compiler, in WebAssembly: check MPRX against a component
+ * manifest, and get back exactly the diagnostics `mesh check --format
+ * json` prints for the same inputs.
+ *
+ * ```js
+ * import { check } from "@valancex/mesh-compiler";
+ *
+ * const document = await check({
+ *   source: generated,
+ *   path: "card.mprx",
+ *   model: { manifest, path: "components.json", component: "user-card" },
+ * });
+ * for (const diagnostic of document.diagnostics) { ... }
+ * ```
+ *
+ * Paths are identifiers you choose; nothing reads them. The compiler runs
+ * entirely in WebAssembly, and this package adds no rule of its own.
+ *
+ * @packageDocumentation
+ */
+import { check as checkWith, init as initWith } from "./engine.js";
+export { MeshInternalError, MeshVersionError } from "./engine.js";
+export { version } from "./version.js";
+/**
+ * Checks `input.source`, as the template of `input.model.component` when a
+ * model is given, and returns the diagnostics document. A problem with the
+ * input is a diagnostic in the document, never an exception.
+ *
+ * It rejects with a `TypeError` for arguments of the wrong type, with
+ * `MeshVersionError` if the WebAssembly module isn't this version's, and
+ * with `MeshInternalError` if the compiler itself fails. In a browser,
+ * call {@link init} first.
+ */
+export function check(input) {
+    return checkWith(input);
+}
+/**
+ * Loads the WebAssembly module from `source`: a URL (or a string resolved
+ * against the page), its bytes, or a compiled `WebAssembly.Module`, and
+ * checks its version. Needed once in a browser, before the first check;
+ * in Node the package loads its own module. The module is
+ * `@valancex/mesh-compiler/mesh.wasm`.
+ */
+export function init(source) {
+    return initWith(source);
+}

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The package's version, which must equal the WebAssembly module's
+ * (outline v0.4 I10). `crates/mesh-cli/tests/packages.rs` pins it to
+ * `package.json` and to the Rust workspace.
+ */
+export declare const version = "0.4.0";

package/dist/version.js

@@ -0,0 +1,6 @@
+/**
+ * The package's version, which must equal the WebAssembly module's
+ * (outline v0.4 I10). `crates/mesh-cli/tests/packages.rs` pins it to
+ * `package.json` and to the Rust workspace.
+ */
+export const version = "0.4.0";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@valancex/mesh-compiler",
+  "version": "0.4.0",
+  "description": "The MESH compiler, built for WebAssembly: checks MPRX against a component manifest and returns its diagnostics.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jack Miller <jackmiller0899@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ValanceX/Mesh.git",
+    "directory": "packages/mesh-compiler"
+  },
+  "keywords": [
+    "mesh",
+    "mprx",
+    "valancex",
+    "compiler",
+    "webassembly"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./mesh.wasm": "./dist/mesh.wasm",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "dist/mesh.wasm"
+  ],
+  "scripts": {
+    "build:wasm": "node scripts/build-wasm.mjs",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test --test-concurrency=1 \"test/*.test.mjs\""
+  }
+}