@valancex/mesh-compiler 0.7.0 → 0.9.0

package/README.md

@@ -32,6 +32,7 @@ The [Using MESH from JavaScript](https://github.com/ValanceX/Mesh/blob/main/docs
 - **`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`.
 - **`compile(input)`** takes `check`'s input, with `model` required, and returns a promise of `{ diagnostics, template? }`. `diagnostics` is the document `check` returns for the same input. `template` is the `template-v1` document ([`schemas/template-v1.schema.json`](https://github.com/ValanceX/Mesh/blob/main/schemas/template-v1.schema.json)), present exactly when the diagnostics have no error; warnings don't stop it. A template is data to store and pass to the runtime, not to interpret. The `Template` type describes it.
 - **`checkProgram({ model, root, templates })`** checks a program of templates: the manifest's text, the root component, and the templates' texts in order. It returns a promise of the runtime diagnostics document ([`schemas/runtime-diagnostics-v1.schema.json`](https://github.com/ValanceX/Mesh/blob/main/schemas/runtime-diagnostics-v1.schema.json)), empty when the program is valid: exactly what `mesh check-program --format json` prints, and what the runtime's render reports for the same program. The `RuntimeDiagnosticsDocument` type describes it.
+- **`compileProgram({ model, root, components })`** compiles a program's components (each `{ component, source, path }`, in order) against one manifest (`model: { manifest, path }`), checks the program they make with `checkProgram`, and returns a promise of `{ components, assembly?, program? }`. `components` holds each component's diagnostics document, as `compile` returns it; `assembly` is `checkProgram`'s document, present when no component had an error; `program` is `{ model, root, templates }`, the parts `checkProgram` and the runtime take (the templates as text), present when nothing had an error. A component that is not listed has no template, so it is a primitive. The `CompileProgramInput` and `CompileProgramResult` types describe it.
 - **`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.

package/dist/index.d.ts

@@ -2,8 +2,9 @@
  * 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; compile it, and get the template
- * `mesh compile` writes too; or check a program of templates, as
- * `mesh check-program` does.
+ * `mesh compile` writes too; check a program of templates, as `mesh
+ * check-program` does; or compile a whole program's components, and get
+ * the program's parts for the runtime.
  *
  * ```js
  * import { check } from "@valancex/mesh-compiler";
@@ -23,9 +24,11 @@
  */
 import type { CheckInput, CompileInput, CompileResult, ModuleSource, ProgramInput } from "./engine.js";
 import type { DiagnosticsDocument } from "./document.js";
+import type { CompileProgramInput, CompileProgramResult } from "./program.js";
 import type { RuntimeDiagnosticsDocument } from "./runtime-document.js";
 export type { Diagnostic, DiagnosticsDocument, Position, Severity, Span, Suggestion, } from "./document.js";
 export type { CheckInput, CompileInput, CompileResult, ModuleSource, ProgramInput } from "./engine.js";
+export type { CompileProgramInput, CompileProgramResult, ProgramComponent } from "./program.js";
 export type { ModelPosition, ModelSpan, RuntimeDiagnostic, RuntimeDiagnosticsDocument, RuntimeLocation, SourceOffset, SourceSpan, } from "./runtime-document.js";
 export type { Offset, Template, TemplateChild, TemplateElement, TemplateExpression, TemplateSpan, } from "./template.js";
 export { MeshInternalError, MeshVersionError } from "./engine.js";
@@ -63,6 +66,25 @@ export declare function compile(input: CompileInput): Promise<CompileResult>;
  * It produces nothing else. It rejects as `check` does.
  */
 export declare function checkProgram(input: ProgramInput): Promise<RuntimeDiagnosticsDocument>;
+/**
+ * Compiles a program's components against one manifest, checks the program
+ * they make, and returns the program's parts: the input `checkProgram` and
+ * the runtime's `render` take, with the templates as text, so a host passes
+ * the result on as it is.
+ *
+ * Each of `input.components` is compiled as {@link compile} compiles it, and
+ * `components` in the result holds each one's diagnostics document, in
+ * order, whether it has errors or not (warnings don't stop a template). Only
+ * when none has an error are the templates checked as a program, by
+ * {@link checkProgram}, whose document is `assembly`. `program` is present
+ * exactly when neither found an error. This adds no rule of its own, and
+ * needs no module but the compiler's: in a browser, call {@link init} first,
+ * as for any check.
+ *
+ * It takes the sources it is given and finds none: a component that isn't
+ * listed has no template, and is a primitive. It rejects as `check` does.
+ */
+export declare function compileProgram(input: CompileProgramInput): Promise<CompileProgramResult>;
 /**
  * Loads the WebAssembly module from `source`: a URL (or a string resolved
  * against the page), its bytes, or a compiled `WebAssembly.Module`, and

package/dist/index.js

@@ -2,8 +2,9 @@
  * 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; compile it, and get the template
- * `mesh compile` writes too; or check a program of templates, as
- * `mesh check-program` does.
+ * `mesh compile` writes too; check a program of templates, as `mesh
+ * check-program` does; or compile a whole program's components, and get
+ * the program's parts for the runtime.
  *
  * ```js
  * import { check } from "@valancex/mesh-compiler";
@@ -22,6 +23,7 @@
  * @packageDocumentation
  */
 import { check as checkWith, checkProgram as checkProgramWith, compile as compileWith, init as initWith, } from "./engine.js";
+import { compileProgram as compileProgramWith } from "./program.js";
 export { MeshInternalError, MeshVersionError } from "./engine.js";
 export { version } from "./version.js";
 /**
@@ -63,6 +65,27 @@ export function compile(input) {
 export function checkProgram(input) {
     return checkProgramWith(input);
 }
+/**
+ * Compiles a program's components against one manifest, checks the program
+ * they make, and returns the program's parts: the input `checkProgram` and
+ * the runtime's `render` take, with the templates as text, so a host passes
+ * the result on as it is.
+ *
+ * Each of `input.components` is compiled as {@link compile} compiles it, and
+ * `components` in the result holds each one's diagnostics document, in
+ * order, whether it has errors or not (warnings don't stop a template). Only
+ * when none has an error are the templates checked as a program, by
+ * {@link checkProgram}, whose document is `assembly`. `program` is present
+ * exactly when neither found an error. This adds no rule of its own, and
+ * needs no module but the compiler's: in a browser, call {@link init} first,
+ * as for any check.
+ *
+ * It takes the sources it is given and finds none: a component that isn't
+ * listed has no template, and is a primitive. It rejects as `check` does.
+ */
+export function compileProgram(input) {
+    return compileProgramWith(input);
+}
 /**
  * Loads the WebAssembly module from `source`: a URL (or a string resolved
  * against the page), its bytes, or a compiled `WebAssembly.Module`, and

package/dist/program.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Compiling a program: the components' templates, and the program's parts.
+ *
+ * A program has no document of its own (spec §9, "Programs"): a host gives the
+ * compiler's program check and the runtime its parts, the root's name and the
+ * templates' texts, with the manifest's text. This composes the operations
+ * that already exist, in the one order a host needs them: `compile` for each
+ * component, then `checkProgram` for the templates it made. It adds no rule
+ * and no check of its own, and it reads nothing but its input.
+ *
+ * Not API on its own: `compileProgram` is the package's.
+ */
+import type { DiagnosticsDocument } from "./document.js";
+import type { ProgramInput } from "./engine.js";
+import type { RuntimeDiagnosticsDocument } from "./runtime-document.js";
+/** One component's MPRX, to be compiled into the program as that component's template. */
+export interface ProgramComponent {
+    /** The component whose template the source is. Always explicit. */
+    component: string;
+    /** The MPRX source text. */
+    source: string;
+    /** An opaque identifier for the source, used only to name it in diagnostics. Never read. */
+    path: string;
+}
+/** One program compile's inputs. */
+export interface CompileProgramInput {
+    /** The model: the manifest every template is compiled against, which is also the program's own. */
+    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 root component: the one the program renders. */
+    root: string;
+    /**
+     * The components that have a template in the program, in order. A component that is not listed has no template, and so is a primitive
+     * (spec §9, "Composite or primitive"): nothing here finds components, so a composite's template is listed or it is absent.
+     */
+    components: readonly ProgramComponent[];
+}
+/** What a program compile gives. */
+export interface CompileProgramResult {
+    /** What `compile` returned for each component's source, in the order of the input's `components`: its diagnostics document. */
+    components: ReadonlyArray<{
+        component: string;
+        diagnostics: DiagnosticsDocument;
+    }>;
+    /**
+     * What `checkProgram` returned for the templates, as it would for the same parts. Present exactly when no component had an error, since only
+     * then are there templates to check.
+     */
+    assembly?: RuntimeDiagnosticsDocument;
+    /**
+     * The program, as `checkProgram` and the runtime take it: the model's text, the root, and the templates as text, in the order of the input's
+     * `components`. Present exactly when no component had an error and the program check found none.
+     */
+    program?: ProgramInput;
+}
+/** Compiles a program. See the package's `compileProgram`. */
+export declare function compileProgram(input: CompileProgramInput): Promise<CompileProgramResult>;

package/dist/program.js

@@ -0,0 +1,67 @@
+/**
+ * Compiling a program: the components' templates, and the program's parts.
+ *
+ * A program has no document of its own (spec §9, "Programs"): a host gives the
+ * compiler's program check and the runtime its parts, the root's name and the
+ * templates' texts, with the manifest's text. This composes the operations
+ * that already exist, in the one order a host needs them: `compile` for each
+ * component, then `checkProgram` for the templates it made. It adds no rule
+ * and no check of its own, and it reads nothing but its input.
+ *
+ * Not API on its own: `compileProgram` is the package's.
+ */
+import { checkProgram, compile } from "./engine.js";
+function validate(input) {
+    if (typeof input !== "object" || input === null) {
+        throw new TypeError("compileProgram() takes an object: { model, root, components }");
+    }
+    const model = input.model;
+    if (typeof model !== "object" || model === null) {
+        throw new TypeError("model must be an object: { manifest, path }");
+    }
+    const strings = [
+        ["model.manifest", model.manifest],
+        ["model.path", model.path],
+        ["root", input.root],
+    ];
+    if (!Array.isArray(input.components)) {
+        throw new TypeError("components must be an array of { component, source, path }");
+    }
+    input.components.forEach((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            throw new TypeError(`components[${index}] must be an object: { component, source, path }`);
+        }
+        const written = entry;
+        strings.push([`components[${index}].component`, written["component"]], [`components[${index}].source`, written["source"]], [`components[${index}].path`, written["path"]]);
+    });
+    for (const [name, value] of strings) {
+        if (typeof value !== "string") {
+            throw new TypeError(`${name} must be a string`);
+        }
+    }
+}
+/** Compiles a program. See the package's `compileProgram`. */
+export async function compileProgram(input) {
+    validate(input);
+    const { manifest, path } = input.model;
+    const compiled = [];
+    // Every component is compiled, so that one run reports every component's errors, not the first's.
+    for (const entry of input.components) {
+        compiled.push(await compile({ source: entry.source, path: entry.path, model: { manifest, path, component: entry.component } }));
+    }
+    const components = compiled.map((result, index) => ({
+        component: input.components[index].component,
+        diagnostics: result.diagnostics,
+    }));
+    const templates = [];
+    for (const result of compiled) {
+        if (result.template === undefined) {
+            return { components };
+        }
+        // The text the runtime and the program check take: the template as the compiler returned it, written out as JSON.
+        templates.push(JSON.stringify(result.template));
+    }
+    const parts = { model: manifest, root: input.root, templates };
+    const assembly = await checkProgram(parts);
+    return assembly.diagnostics.length === 0 ? { components, assembly, program: parts } : { components, assembly };
+}

package/dist/version.d.ts

@@ -3,4 +3,4 @@
  * (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.7.0";
+export declare const version = "0.9.0";

package/dist/version.js

@@ -3,4 +3,4 @@
  * (outline v0.4 I10). `crates/mesh-cli/tests/packages.rs` pins it to
  * `package.json` and to the Rust workspace.
  */
-export const version = "0.7.0";
+export const version = "0.9.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valancex/mesh-compiler",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "The MESH compiler, built for WebAssembly: checks MPRX against a component manifest and returns its diagnostics.",
   "type": "module",
   "license": "MIT",