parsanol 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ribose Inc.
+
+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,39 @@
+# parsanol-ts
+
+The PARG artifact runtime for TypeScript: load a checksum-verified
+`.parg` artifact, parse through the parsanol wasm engine, apply the
+artifact's bindings, and materialize schema-driven models.
+
+The engine is the vendored parsanol wasm build (`vendor/parsanol-wasm/`,
+nodejs target) — **no grammar code lives here**; the baked artifact is
+the contract.
+
+## Usage
+
+```ts
+import { PargRuntime } from "parsanol";
+
+// PARG_ARTIFACT_DIR (or an explicit dir) holds the baked artifacts.
+const rt = PargRuntime.load("iso", undefined, process.env.PARG_ARTIFACT_DIR);
+
+const bound = rt.parseAndBind("ISO 5537:2025");   // bound capture map
+const shape = rt.parseShape("ISO 5537:2025");     // parsanol-shape tree
+const text = rt.renderString("ISO 5537:2025");    // F6 render
+```
+
+Construction throws unless the artifact's embedded checksum verifies.
+
+## Vendored engine freshness
+
+`vendor/parsanol-wasm/BUILT_FROM` records the parsanol-rs commit the
+wasm was built from; `scripts/check-wasm-freshness.sh` fails when
+parsanol-rs has moved. Refresh with `npm run refresh-wasm`.
+
+## Conformance
+
+`PargRuntime` parses with the same wasm binary the Rust and Ruby
+engines validate against, so artifact-level conformance is inherited:
+any baked artifact that passes its embedded tests on the other engines
+passes here identically. Run the runtime tests with
+`PARG_ARTIFACT_DIR=<artifacts> npm test` (the artifact-gated case
+skips when no artifacts dir is set).

package/dist/runtime.d.ts

@@ -0,0 +1,86 @@
+type PargArtifactJs = any;
+/** A field requirement from the binding-requirements schema. */
+export interface FieldRequirement {
+    type: string;
+    card: string;
+    preprocess?: string;
+}
+/** The binding-requirements schema record for one entry. */
+export interface EntrySchema {
+    root: string;
+    fields: Record<string, FieldRequirement>;
+    examples: {
+        input: string;
+        captures: Record<string, unknown>;
+    }[];
+}
+export type Schema = Record<string, EntrySchema>;
+/**
+ * A loaded, checksum-verified PG artifact with its schema.
+ * Construction throws when the checksum does not verify.
+ */
+export declare class PargRuntime {
+    readonly artifact: PargArtifactJs;
+    readonly schema: Schema;
+    readonly renderSpec: Record<string, RenderSegment[]>;
+    readonly entry: string;
+    readonly defaultEntry: string | null;
+    readonly envelope: Record<string, unknown>;
+    constructor(artifactJson: string, entry?: string);
+    /** Load an artifact JSON file and verify its checksum. */
+    static fromFile(path: string, entry?: string): PargRuntime;
+    /** The artifacts directory: PARG_ARTIFACT_DIR when set. */
+    static artifactsDir(): string | null;
+    /** Load `<dir>/<grammar>.json`; throws when no artifacts dir is set. */
+    static load(grammar: string, entry?: string, dir?: string): PargRuntime;
+    /** Parse with the native wasm engine; returns the parsanol-shape tree. */
+    parseShape(input: string): unknown;
+    /** Apply the entry's bindings to a parsanol-shape tree. */
+    applyBindings(shape: unknown): Record<string, unknown>;
+    /** Parse and bind in one step. */
+    parseAndBind(input: string): Record<string, unknown> | null;
+    /**
+     * Schema-driven materialization: the schema (from the artifact, not
+     * hand-written model code) declares the fields a data model must
+     * implement; the bound captures populate a structurally-typed object.
+     * Card `1*`/`*` fields become arrays; `0..1` fields become nullable.
+     */
+    materialize(input: string): Materialized | null;
+    /** Render the identifier string from a bound map (F6). */
+    render(bound: Record<string, unknown>, variant?: string): string;
+    /** Parse, bind, and render in one step. */
+    renderString(input: string, variant?: string): string | null;
+    /** Evaluate a named derive spec against a bound map (F6). */
+    derive(name: string, bound: Record<string, unknown>): string;
+    /** Parse, bind, and evaluate a derive spec in one step. */
+    deriveString(input: string, name: string): string | null;
+    /** Run the artifact's embedded tests; empty list means green. */
+    runTests(): string[];
+}
+/** F6 v1 derive evaluator: {field} interpolates from the bound map. */
+export declare function deriveTemplate(derive: Record<string, string>, name: string, bound: Record<string, unknown>): string;
+export type RenderSegment = {
+    type: "field";
+    field: string;
+} | {
+    type: "literal";
+    text: string;
+} | {
+    type: "cond";
+    field: string;
+    then: RenderSegment[];
+};
+/** F6 v1 generic renderer: field / literal / cond-presence segments. */
+export declare function renderSegments(segments: RenderSegment[] | null, bound: Record<string, unknown>): string;
+/** A schema-materialized identifier: typed fields plus provenance. */
+export interface Materialized {
+    entry: string;
+    attributes: Record<string, unknown>;
+}
+/**
+ * Schema-driven materialization independent of any wasm handle —
+ * the same function the model layer will build on (T2 codegen emits the
+ * static view of exactly these fields).
+ */
+export declare function materializeFromSchema(schema: EntrySchema, bound: Record<string, unknown>): Materialized;
+export {};

package/dist/runtime.js

@@ -0,0 +1,182 @@
+//! The PARG artifact runtime for TypeScript: checksum-verified artifact
+//! load, native wasm parse, bindings application, and schema-driven
+//! materialization. The engine is the vendored parsanol wasm build
+//! (PargArtifactJs) — no grammar code lives in this package; the baked
+//! artifact is the contract.
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+/** Walk up from this module to the package root (which holds package.json). */
+const packageRootCache = (() => {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (; !existsSync(join(dir, "package.json")); dir = dirname(dir)) {
+        if (dir === dirname(dir))
+            throw new Error("package.json not found above the parg runtime");
+    }
+    return dir;
+})();
+function packageRoot() {
+    return packageRootCache;
+}
+// The vendored wasm glue is CommonJS and lives outside the compiled tree,
+// so resolve it against the package root at runtime. Loading is deferred
+// to the first artifact construction: importing this module costs
+// nothing, and the ~1.5 MB wasm compiles only when parsing is real.
+const require = createRequire(import.meta.url);
+let wasmModule = null;
+function wasm() {
+    if (wasmModule === null) {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        wasmModule = require(join(packageRoot(), "vendor", "parsanol-wasm", "parsanol.cjs"));
+    }
+    return wasmModule;
+}
+/**
+ * A loaded, checksum-verified PG artifact with its schema.
+ * Construction throws when the checksum does not verify.
+ */
+export class PargRuntime {
+    artifact;
+    schema;
+    renderSpec;
+    entry;
+    defaultEntry;
+    envelope;
+    constructor(artifactJson, entry) {
+        const parsed = JSON.parse(artifactJson);
+        this.envelope = parsed;
+        this.artifact = new (wasm().PargArtifactJs)(artifactJson);
+        this.schema = JSON.parse(this.artifact.schema());
+        this.renderSpec =
+            parsed["render"] ?? {};
+        // The compiler bakes default_entry: JSON key order is not preserved
+        // across engines, so the sorted entry list cannot rederive it.
+        this.defaultEntry = parsed["default_entry"] ?? null;
+        this.entry = entry ?? this.defaultEntry ?? this.artifact.entryNames()[0];
+    }
+    /** Load an artifact JSON file and verify its checksum. */
+    static fromFile(path, entry) {
+        return new PargRuntime(readFileSync(path, "utf8"), entry);
+    }
+    /** The artifacts directory: PARG_ARTIFACT_DIR when set. */
+    static artifactsDir() {
+        return process.env.PARG_ARTIFACT_DIR ?? null;
+    }
+    /** Load `<dir>/<grammar>.json`; throws when no artifacts dir is set. */
+    static load(grammar, entry, dir) {
+        const base = dir ?? PargRuntime.artifactsDir();
+        if (!base) {
+            throw new Error("no artifacts directory: set PARG_ARTIFACT_DIR or pass dir");
+        }
+        return PargRuntime.fromFile(join(base, `${grammar}.json`), entry);
+    }
+    /** Parse with the native wasm engine; returns the parsanol-shape tree. */
+    parseShape(input) {
+        return JSON.parse(this.artifact.parseShape(this.entry, input));
+    }
+    /** Apply the entry's bindings to a parsanol-shape tree. */
+    applyBindings(shape) {
+        return JSON.parse(this.artifact.applyBindings(this.entry, JSON.stringify(shape)));
+    }
+    /** Parse and bind in one step. */
+    parseAndBind(input) {
+        try {
+            return JSON.parse(this.artifact.parseAndBind(this.entry, input));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Schema-driven materialization: the schema (from the artifact, not
+     * hand-written model code) declares the fields a data model must
+     * implement; the bound captures populate a structurally-typed object.
+     * Card `1*`/`*` fields become arrays; `0..1` fields become nullable.
+     */
+    materialize(input) {
+        const bound = this.parseAndBind(input);
+        if (bound === null)
+            return null;
+        const schema = this.schema[this.entry];
+        if (!schema)
+            throw new Error(`artifact has no schema for entry ${this.entry}`);
+        return materializeFromSchema(schema, bound);
+    }
+    /** Render the identifier string from a bound map (F6). */
+    render(bound, variant = "default") {
+        return renderSegments((this.renderSpec[variant] ?? null), bound);
+    }
+    /** Parse, bind, and render in one step. */
+    renderString(input, variant = "default") {
+        const bound = this.parseAndBind(input);
+        return bound === null ? null : this.render(bound, variant);
+    }
+    /** Evaluate a named derive spec against a bound map (F6). */
+    derive(name, bound) {
+        return deriveTemplate((this.envelope["derive"] ?? {}), name, bound);
+    }
+    /** Parse, bind, and evaluate a derive spec in one step. */
+    deriveString(input, name) {
+        const bound = this.parseAndBind(input);
+        return bound === null ? null : this.derive(name, bound);
+    }
+    /** Run the artifact's embedded tests; empty list means green. */
+    runTests() {
+        return JSON.parse(this.artifact.runTests());
+    }
+}
+/** F6 v1 derive evaluator: {field} interpolates from the bound map. */
+export function deriveTemplate(derive, name, bound) {
+    const template = derive[name];
+    if (template === undefined)
+        throw new Error(`derive spec ${name} not declared`);
+    return template.replace(/\{(\w+)\}/g, (_, field) => {
+        const value = bound[field];
+        return value === undefined || value === null ? "" : String(value);
+    });
+}
+/** F6 v1 generic renderer: field / literal / cond-presence segments. */
+export function renderSegments(segments, bound) {
+    let out = "";
+    for (const segment of segments ?? []) {
+        if (segment.type === "field") {
+            const value = bound[segment.field];
+            out += value === undefined || value === null ? "" : String(value);
+        }
+        else if (segment.type === "literal") {
+            out += segment.text;
+        }
+        else if (segment.type === "cond") {
+            const value = bound[segment.field];
+            if (value !== undefined && value !== null)
+                out += renderSegments(segment.then, bound);
+        }
+    }
+    return out;
+}
+/**
+ * Schema-driven materialization independent of any wasm handle —
+ * the same function the model layer will build on (T2 codegen emits the
+ * static view of exactly these fields).
+ */
+export function materializeFromSchema(schema, bound) {
+    const attributes = {};
+    for (const [path, requirements] of Object.entries(schema.fields)) {
+        const leaf = path.includes("[]")
+            ? (path.split("].").pop() ?? path)
+            : path;
+        const value = bound[leaf];
+        if (requirements.card.endsWith("*")) {
+            const list = Array.isArray(value) ? value : value === undefined ? [] : [value];
+            attributes[leaf] = list;
+        }
+        else if (requirements.card === "0..1") {
+            attributes[leaf] = value === undefined ? null : value;
+        }
+        else {
+            attributes[leaf] = value;
+        }
+    }
+    return { entry: schema.root, attributes };
+}

package/dist/suite.d.ts

@@ -0,0 +1,20 @@
+import { PargRuntime } from "./runtime.js";
+export type TestKind = "accept" | "reject" | "example";
+export interface SuiteTest {
+    kind: TestKind;
+    input: string;
+    expect?: Record<string, string>;
+}
+export interface Suite {
+    name: string;
+    entry?: string;
+    tests: SuiteTest[];
+}
+/** Parse one *.pgtest file (same grammar as Parsanol::PG::Suite#read_file). */
+export declare function readSuite(text: string, name: string): Suite;
+/** Load every *.pgtest file in a directory. */
+export declare function loadSuites(dir: string): Suite[];
+/** Run a suite against a runtime; returns failure descriptions. */
+export declare function runSuite(runtime: PargRuntime, suite: Suite): string[];
+/** The default suites directory: PARG_SUITES_DIR when set. */
+export declare function suitesDir(): string | null;

package/dist/suite.js

@@ -0,0 +1,86 @@
+//! T3: external *.pgtest suites run through the wasm runtime. The suite
+//! syntax matches the Ruby loader (Parsanol::PG::Suite): a
+//! `suite <name> [for <entry>] { ... }` header with accept / reject /
+//! example lines. Green means Ruby and TypeScript agree on the contract.
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+const LINE = /^\s*(accept|reject|example)\s+"((?:[^"\\]|\\.)*)"(?:\s*\{([^}]*)\})?\s*$/;
+const HEADER = /suite\s+(\w+)(?:\s+for\s+entry\s+(\w+))?\s*\{/;
+/** Parse one *.pgtest file (same grammar as Parsanol::PG::Suite#read_file). */
+export function readSuite(text, name) {
+    const body = text.replace(/^#[^\n]*\n/gm, "");
+    const header = HEADER.exec(body);
+    if (!header) {
+        throw new Error(`${name}: expected 'suite <name> [for <entry>] { ... }'`);
+    }
+    const tests = [];
+    for (const line of body.slice((header.index ?? 0) + header[0].length).split("\n")) {
+        if (line.trim() === "}")
+            break;
+        const match = LINE.exec(line);
+        if (!match)
+            continue;
+        const kind = match[1];
+        const rawInput = match[2] ?? "";
+        const input = JSON.parse(`"${rawInput}"`);
+        const expect = {};
+        if (match[3]) {
+            for (const pair of match[3].split(",")) {
+                const kv = /(\w+)\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(pair);
+                const key = kv?.[1];
+                const raw = kv?.[2];
+                if (key && raw !== undefined)
+                    expect[key] = JSON.parse(`"${raw}"`);
+            }
+        }
+        tests.push(kind === "example" ? { kind, input, expect } : { kind, input });
+    }
+    const entry = header[2];
+    return entry === undefined
+        ? { name: header[1] ?? "suite", tests }
+        : { name: header[1] ?? "suite", entry, tests };
+}
+/** Load every *.pgtest file in a directory. */
+export function loadSuites(dir) {
+    return readdirSync(dir)
+        .filter((file) => file.endsWith(".pgtest"))
+        .map((file) => readSuite(readFileSync(join(dir, file), "utf8"), file.replace(/\.pgtest$/, "")));
+}
+/** Run a suite against a runtime; returns failure descriptions. */
+export function runSuite(runtime, suite) {
+    const failures = [];
+    const entry = suite.entry ?? runtime.entry;
+    for (const test of suite.tests) {
+        // The wasm runtime throws on parse failure; that is the reject signal.
+        let bound = null;
+        try {
+            bound = runtime.artifact.parseAndBind(entry, test.input);
+        }
+        catch {
+            bound = null;
+        }
+        if (test.kind === "reject") {
+            if (bound !== null) {
+                failures.push(`test ${JSON.stringify(test.input)}: expected the input to be rejected`);
+            }
+            continue;
+        }
+        if (bound === null) {
+            failures.push(`test ${JSON.stringify(test.input)}: expected the input to parse`);
+            continue;
+        }
+        if (test.kind === "example") {
+            const parsed = JSON.parse(bound);
+            for (const [key, value] of Object.entries(test.expect ?? {})) {
+                if (parsed[key] !== value) {
+                    failures.push(`test ${JSON.stringify(test.input)}: expected captures ${key}: ${JSON.stringify(value)}, got ${JSON.stringify(parsed[key])}`);
+                }
+            }
+        }
+    }
+    return failures;
+}
+/** The default suites directory: PARG_SUITES_DIR when set. */
+export function suitesDir() {
+    return process.env.PARG_SUITES_DIR ?? null;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "parsanol",
+  "version": "0.10.0",
+  "description": "PARG artifact runtime for TypeScript — checksum-verified artifact load, wasm parse, bindings, schema-driven materialization",
+  "type": "module",
+  "main": "dist/runtime.js",
+  "types": "dist/runtime.d.ts",
+  "exports": {
+    ".": "./dist/runtime.js",
+    "./suite": "./dist/suite.js"
+  },
+  "files": [
+    "dist/",
+    "vendor/parsanol-wasm/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && npx tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js",
+    "refresh-wasm": "bash scripts/refresh-wasm.sh",
+    "prepublishOnly": "npm run build",
+    "bench": "node bench/bench.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/parsanol/parsanol-ts.git"
+  },
+  "keywords": [
+    "parser",
+    "peg",
+    "parg",
+    "wasm",
+    "rust"
+  ],
+  "private": false,
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2"
+  }
+}

package/vendor/parsanol-wasm/BUILT_FROM

@@ -0,0 +1,2 @@
+30443e55ac136632bce660152740f2fe2d70c19a
+built with: wasm-pack build --target=nodejs --features wasm (from parsanol-rs/parsanol)

package/vendor/parsanol-wasm/parsanol.cjs

@@ -0,0 +1,528 @@
+/* @ts-self-types="./parsanol.d.ts" */
+
+/**
+ * A verified PARG artifact exposed to JavaScript: checksum-verified load,
+ * native parse, bindings application, embedded-suite runs and the
+ * binding-requirements schema (PN 2/4).
+ */
+class PargArtifactJs {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        PargArtifactJsFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_pargartifactjs_free(ptr, 0);
+    }
+    /**
+     * Apply an entry's bindings to a parsanol-shape tree (JSON text).
+     * @param {string} entry
+     * @param {string} shape_json
+     * @returns {string}
+     */
+    applyBindings(entry, shape_json) {
+        const ptr0 = passStringToWasm0(entry, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(shape_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.pargartifactjs_applyBindings(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * Declared entry point names, sorted.
+     * @returns {string[]}
+     */
+    entryNames() {
+        const ret = wasm.pargartifactjs_entryNames(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+    /**
+     * Load and checksum-verify an artifact envelope.
+     * @param {string} artifact_json
+     */
+    constructor(artifact_json) {
+        const ptr0 = passStringToWasm0(artifact_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.pargartifactjs_new(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0] >>> 0;
+        PargArtifactJsFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * Parse and bind in one step.
+     * @param {string} entry
+     * @param {string} input
+     * @returns {string}
+     */
+    parseAndBind(entry, input) {
+        const ptr0 = passStringToWasm0(entry, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(input, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.pargartifactjs_parseAndBind(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * Parse an entry with the native engine; returns the parsanol-shape
+     * tree as JSON text.
+     * @param {string} entry
+     * @param {string} input
+     * @returns {string}
+     */
+    parseShape(entry, input) {
+        const ptr0 = passStringToWasm0(entry, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(input, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.pargartifactjs_parseShape(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * Run the artifact's embedded tests; returns the failure list as
+     * JSON (empty array means green).
+     * @returns {string}
+     */
+    runTests() {
+        const ret = wasm.pargartifactjs_runTests(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * The binding-requirements schema as JSON text.
+     * @returns {string}
+     */
+    schema() {
+        const ret = wasm.pargartifactjs_schema(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * The binding-requirements schema as TypeScript source.
+     * @returns {string}
+     */
+    schemaTypescript() {
+        const ret = wasm.pargartifactjs_schemaTypescript(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+}
+if (Symbol.dispose) PargArtifactJs.prototype[Symbol.dispose] = PargArtifactJs.prototype.free;
+exports.PargArtifactJs = PargArtifactJs;
+
+/**
+ * WASM parser instance
+ *
+ * Create with `new WasmParser(grammarJson)` and parse with `parse(input)`.
+ */
+class WasmParser {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(WasmParser.prototype);
+        obj.__wbg_ptr = ptr;
+        WasmParserFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        WasmParserFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_wasmparser_free(ptr, 0);
+    }
+    /**
+     * Create a new parser from a PARG artifact envelope and entry name.
+     *
+     * The artifact's canonical checksum is verified before any parsing;
+     * a mismatched or corrupt artifact is rejected (PN 2).
+     *
+     * # Arguments
+     * * `artifact_json` - JSON text of the PARG artifact envelope
+     * * `entry` - entry point name declared in the artifact
+     * @param {string} artifact_json
+     * @param {string} entry
+     * @returns {WasmParser}
+     */
+    static fromArtifact(artifact_json, entry) {
+        const ptr0 = passStringToWasm0(artifact_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(entry, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmparser_fromArtifact(ptr0, len0, ptr1, len1);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return WasmParser.__wrap(ret[0]);
+    }
+    /**
+     * Create a new parser from grammar JSON
+     *
+     * # Arguments
+     * * `grammar_json` - JSON string representing the grammar
+     *
+     * # Returns
+     * A new WasmParser instance
+     *
+     * # Throws
+     * If the grammar JSON is invalid
+     * @param {string} grammar_json
+     */
+    constructor(grammar_json) {
+        const ptr0 = passStringToWasm0(grammar_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmparser_new(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0] >>> 0;
+        WasmParserFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * Parse input and return JavaScript AST
+     *
+     * # Arguments
+     * * `input` - The input string to parse
+     *
+     * # Returns
+     * A JavaScript object representing the parsed AST
+     *
+     * # Throws
+     * If parsing fails
+     * @param {string} input
+     * @returns {any}
+     */
+    parse(input) {
+        const ptr0 = passStringToWasm0(input, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmparser_parse(this.__wbg_ptr, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * Parse and return flat array (for Opal compatibility)
+     *
+     * # Arguments
+     * * `input` - The input string to parse
+     *
+     * # Returns
+     * A Uint32Array containing the flattened AST
+     *
+     * # Throws
+     * If parsing fails
+     * @param {string} input
+     * @returns {BigUint64Array}
+     */
+    parse_flat(input) {
+        const ptr0 = passStringToWasm0(input, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmparser_parse_flat(this.__wbg_ptr, ptr0, len0);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v2 = getArrayU64FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 8, 8);
+        return v2;
+    }
+    /**
+     * Parse and return JSON string
+     *
+     * # Arguments
+     * * `input` - The input string to parse
+     *
+     * # Returns
+     * A JSON string representing the parsed AST
+     *
+     * # Throws
+     * If parsing fails
+     * @param {string} input
+     * @returns {string}
+     */
+    parse_json(input) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const ptr0 = passStringToWasm0(input, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.wasmparser_parse_json(this.__wbg_ptr, ptr0, len0);
+            var ptr2 = ret[0];
+            var len2 = ret[1];
+            if (ret[3]) {
+                ptr2 = 0; len2 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) WasmParser.prototype[Symbol.dispose] = WasmParser.prototype.free;
+exports.WasmParser = WasmParser;
+
+/**
+ * Initialize function for WASM
+ */
+function init() {
+    wasm.init();
+}
+exports.init = init;
+
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg___wbindgen_string_get_395e606bd0ee4427: function(arg0, arg1) {
+            const obj = arg1;
+            const ret = typeof(obj) === 'string' ? obj : undefined;
+            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_throw_6ddd609b62940d55: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_error_a6fa202b58aa1cd3: function(arg0, arg1) {
+            let deferred0_0;
+            let deferred0_1;
+            try {
+                deferred0_0 = arg0;
+                deferred0_1 = arg1;
+                console.error(getStringFromWasm0(arg0, arg1));
+            } finally {
+                wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
+            }
+        },
+        __wbg_getRandomValues_3f44b700395062e5: function() { return handleError(function (arg0, arg1) {
+            globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
+        }, arguments); },
+        __wbg_new_227d7c05414eb861: function() {
+            const ret = new Error();
+            return ret;
+        },
+        __wbg_new_a70fbab9066b301f: function() {
+            const ret = new Array();
+            return ret;
+        },
+        __wbg_new_ab79df5bd7c26067: function() {
+            const ret = new Object();
+            return ret;
+        },
+        __wbg_push_e87b0e732085a946: function(arg0, arg1) {
+            const ret = arg0.push(arg1);
+            return ret;
+        },
+        __wbg_set_7eaa4f96924fd6b3: function() { return handleError(function (arg0, arg1, arg2) {
+            const ret = Reflect.set(arg0, arg1, arg2);
+            return ret;
+        }, arguments); },
+        __wbg_stack_3b0d974bbf31e44f: function(arg0, arg1) {
+            const ret = arg1.stack;
+            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg_stringify_5ae93966a84901ac: function() { return handleError(function (arg0) {
+            const ret = JSON.stringify(arg0);
+            return ret;
+        }, arguments); },
+        __wbindgen_cast_0000000000000001: function(arg0) {
+            // Cast intrinsic for `F64 -> Externref`.
+            const ret = arg0;
+            return ret;
+        },
+        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
+            // Cast intrinsic for `Ref(String) -> Externref`.
+            const ret = getStringFromWasm0(arg0, arg1);
+            return ret;
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        "./parsanol_bg.js": import0,
+    };
+}
+
+const PargArtifactJsFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_pargartifactjs_free(ptr >>> 0, 1));
+const WasmParserFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmparser_free(ptr >>> 0, 1));
+
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
+function getArrayJsValueFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    const mem = getDataViewMemory0();
+    const result = [];
+    for (let i = ptr; i < ptr + 4 * len; i += 4) {
+        result.push(wasm.__wbindgen_externrefs.get(mem.getUint32(i, true)));
+    }
+    wasm.__externref_drop_slice(ptr, len);
+    return result;
+}
+
+function getArrayU64FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getBigUint64ArrayMemory0().subarray(ptr / 8, ptr / 8 + len);
+}
+
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
+let cachedBigUint64ArrayMemory0 = null;
+function getBigUint64ArrayMemory0() {
+    if (cachedBigUint64ArrayMemory0 === null || cachedBigUint64ArrayMemory0.byteLength === 0) {
+        cachedBigUint64ArrayMemory0 = new BigUint64Array(wasm.memory.buffer);
+    }
+    return cachedBigUint64ArrayMemory0;
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+function decodeText(ptr, len) {
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+const wasmPath = `${__dirname}/parsanol_bg.wasm`;
+const wasmBytes = require('fs').readFileSync(wasmPath);
+const wasmModule = new WebAssembly.Module(wasmBytes);
+let wasm = new WebAssembly.Instance(wasmModule, __wbg_get_imports()).exports;
+wasm.__wbindgen_start();

package/vendor/parsanol-wasm/parsanol.d.ts

@@ -0,0 +1,124 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * A verified PARG artifact exposed to JavaScript: checksum-verified load,
+ * native parse, bindings application, embedded-suite runs and the
+ * binding-requirements schema (PN 2/4).
+ */
+export class PargArtifactJs {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Apply an entry's bindings to a parsanol-shape tree (JSON text).
+     */
+    applyBindings(entry: string, shape_json: string): string;
+    /**
+     * Declared entry point names, sorted.
+     */
+    entryNames(): string[];
+    /**
+     * Load and checksum-verify an artifact envelope.
+     */
+    constructor(artifact_json: string);
+    /**
+     * Parse and bind in one step.
+     */
+    parseAndBind(entry: string, input: string): string;
+    /**
+     * Parse an entry with the native engine; returns the parsanol-shape
+     * tree as JSON text.
+     */
+    parseShape(entry: string, input: string): string;
+    /**
+     * Run the artifact's embedded tests; returns the failure list as
+     * JSON (empty array means green).
+     */
+    runTests(): string;
+    /**
+     * The binding-requirements schema as JSON text.
+     */
+    schema(): string;
+    /**
+     * The binding-requirements schema as TypeScript source.
+     */
+    schemaTypescript(): string;
+}
+
+/**
+ * WASM parser instance
+ *
+ * Create with `new WasmParser(grammarJson)` and parse with `parse(input)`.
+ */
+export class WasmParser {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Create a new parser from a PARG artifact envelope and entry name.
+     *
+     * The artifact's canonical checksum is verified before any parsing;
+     * a mismatched or corrupt artifact is rejected (PN 2).
+     *
+     * # Arguments
+     * * `artifact_json` - JSON text of the PARG artifact envelope
+     * * `entry` - entry point name declared in the artifact
+     */
+    static fromArtifact(artifact_json: string, entry: string): WasmParser;
+    /**
+     * Create a new parser from grammar JSON
+     *
+     * # Arguments
+     * * `grammar_json` - JSON string representing the grammar
+     *
+     * # Returns
+     * A new WasmParser instance
+     *
+     * # Throws
+     * If the grammar JSON is invalid
+     */
+    constructor(grammar_json: string);
+    /**
+     * Parse input and return JavaScript AST
+     *
+     * # Arguments
+     * * `input` - The input string to parse
+     *
+     * # Returns
+     * A JavaScript object representing the parsed AST
+     *
+     * # Throws
+     * If parsing fails
+     */
+    parse(input: string): any;
+    /**
+     * Parse and return flat array (for Opal compatibility)
+     *
+     * # Arguments
+     * * `input` - The input string to parse
+     *
+     * # Returns
+     * A Uint32Array containing the flattened AST
+     *
+     * # Throws
+     * If parsing fails
+     */
+    parse_flat(input: string): BigUint64Array;
+    /**
+     * Parse and return JSON string
+     *
+     * # Arguments
+     * * `input` - The input string to parse
+     *
+     * # Returns
+     * A JSON string representing the parsed AST
+     *
+     * # Throws
+     * If parsing fails
+     */
+    parse_json(input: string): string;
+}
+
+/**
+ * Initialize function for WASM
+ */
+export function init(): void;

package/vendor/parsanol-wasm/parsanol_bg.wasm.d.ts

@@ -0,0 +1,51 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const __wbg_pargartifactjs_free: (a: number, b: number) => void;
+export const __wbg_wasmparser_free: (a: number, b: number) => void;
+export const pargartifactjs_applyBindings: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+export const pargartifactjs_entryNames: (a: number) => [number, number];
+export const pargartifactjs_new: (a: number, b: number) => [number, number, number];
+export const pargartifactjs_parseAndBind: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+export const pargartifactjs_parseShape: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+export const pargartifactjs_runTests: (a: number) => [number, number, number];
+export const pargartifactjs_schema: (a: number) => [number, number, number];
+export const pargartifactjs_schemaTypescript: (a: number) => [number, number, number];
+export const parsanol_c_last_error: () => number;
+export const parsanol_c_parse: (a: bigint, b: number, c: number, d: number) => number;
+export const parsanol_c_parse_len: (a: bigint, b: number, c: number, d: number, e: number) => number;
+export const parsanol_c_register: (a: number) => bigint;
+export const parsanol_c_release: (a: bigint) => void;
+export const parsanol_grammar_atom_count: (a: number) => number;
+export const parsanol_grammar_free: (a: number) => void;
+export const parsanol_grammar_new: (a: number) => number;
+export const parsanol_grammar_new_with_error: (a: number, b: number) => number;
+export const parsanol_grammar_root: (a: number) => number;
+export const parsanol_parg_error: (a: number, b: number) => number;
+export const parsanol_parg_free: (a: number) => void;
+export const parsanol_parg_parse: (a: number, b: number) => number;
+export const parsanol_parse: (a: number, b: number, c: number) => number;
+export const parsanol_parse_end_pos: (a: number, b: number) => number;
+export const parsanol_parse_simple: (a: number, b: number) => number;
+export const parsanol_result_ast_json: (a: number) => number;
+export const parsanol_result_end_pos: (a: number) => number;
+export const parsanol_result_error: (a: number) => number;
+export const parsanol_result_free: (a: number) => void;
+export const parsanol_result_success: (a: number) => number;
+export const parsanol_version: () => number;
+export const wasmparser_fromArtifact: (a: number, b: number, c: number, d: number) => [number, number, number];
+export const wasmparser_new: (a: number, b: number) => [number, number, number];
+export const wasmparser_parse: (a: number, b: number, c: number) => [number, number, number];
+export const wasmparser_parse_flat: (a: number, b: number, c: number) => [number, number, number, number];
+export const wasmparser_parse_json: (a: number, b: number, c: number) => [number, number, number, number];
+export const init: () => void;
+export const parsanol_string_free: (a: number) => void;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __wbindgen_exn_store: (a: number) => void;
+export const __externref_table_alloc: () => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __externref_table_dealloc: (a: number) => void;
+export const __externref_drop_slice: (a: number, b: number) => void;
+export const __wbindgen_start: () => void;