mustardscript 0.1.0

package/dist/lib/runtime.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const { callNative } = require('./errors.js');
+const {
+  getAbortSignal,
+  settleCapabilityInvocation,
+  throwIfAborted,
+  withCancellationSignal,
+} = require('./cancellation.js');
+const {
+  createExecutionPolicy,
+  encodeSnapshotPolicy,
+  snapshotIdentity,
+  snapshotToken,
+} = require('./policy.js');
+const {
+  encodeResumePayloadCancel,
+  encodeResumePayloadError,
+  encodeResumePayloadValue,
+  encodeStartOptions,
+} = require('./structured.js');
+
+function createMustardClass({ native, materializeStep, parseStep }) {
+  function compileProgram(code) {
+    return callNative(native.compileProgram, code);
+  }
+
+  return class Mustard {
+    constructor(code, options = {}) {
+      this._program = compileProgram(code);
+      this._inputNames = options.inputs ?? [];
+    }
+
+    static validateProgram(code) {
+      compileProgram(code);
+    }
+
+    async run(options = {}) {
+      const signal = getAbortSignal(options, 'run options');
+      throwIfAborted(signal);
+      const { hostHandlers, policy, snapshotKey } = createExecutionPolicy(options);
+      let step = parseStep(
+        withCancellationSignal(
+          native,
+          native.startProgram,
+          [this._program, encodeStartOptions(options.inputs, policy)],
+          signal,
+        ),
+      );
+      while (step.type === 'suspended') {
+        const capability = hostHandlers[step.capability];
+        if (typeof capability !== 'function') {
+          throw new Error(`Missing capability: ${step.capability}`);
+        }
+        const outcome = await settleCapabilityInvocation(capability, step.args, signal);
+        const snapshotId = snapshotIdentity(step.snapshot);
+        const policyJson = encodeSnapshotPolicy(policy, {
+          snapshotId,
+          snapshotKey,
+          snapshotToken: snapshotToken(step.snapshot, snapshotKey, snapshotId),
+        });
+        if (outcome.type === 'cancelled') {
+          step = parseStep(
+            callNative(native.resumeProgram, step.snapshot, encodeResumePayloadCancel(), policyJson),
+          );
+          continue;
+        }
+        const payload =
+          outcome.type === 'value'
+            ? encodeResumePayloadValue(outcome.value)
+            : encodeResumePayloadError(outcome.error);
+        step = parseStep(
+          withCancellationSignal(native, native.resumeProgram, [step.snapshot, payload, policyJson], signal),
+        );
+      }
+      return step.value;
+    }
+
+    start(options = {}) {
+      const signal = getAbortSignal(options, 'start options');
+      throwIfAborted(signal);
+      const { policy, snapshotKey } = createExecutionPolicy(options);
+      const step = parseStep(
+        withCancellationSignal(
+          native,
+          native.startProgram,
+          [this._program, encodeStartOptions(options.inputs, policy)],
+          signal,
+        ),
+      );
+      return materializeStep(step, policy, snapshotKey);
+    }
+
+    dump() {
+      return Buffer.from(this._program);
+    }
+
+    static load(buffer) {
+      const instance = Object.create(Mustard.prototype);
+      instance._program = Buffer.from(buffer);
+      instance._inputNames = [];
+      return instance;
+    }
+  };
+}
+
+module.exports = {
+  createMustardClass,
+};

package/dist/lib/structured.js

@@ -0,0 +1,286 @@
+'use strict';
+
+const { types } = require('node:util');
+
+const HOST_BOUNDARY_MAX_DEPTH = 128;
+const HOST_BOUNDARY_MAX_ARRAY_LENGTH = 1_000_000;
+
+function assertBoundaryDepth(depth, label) {
+  if (depth > HOST_BOUNDARY_MAX_DEPTH) {
+    throw new TypeError(`${label} nesting limit exceeded`);
+  }
+}
+
+function assertBoundaryArrayLength(length, label) {
+  if (length > HOST_BOUNDARY_MAX_ARRAY_LENGTH) {
+    throw new TypeError(
+      `${label} arrays longer than ${HOST_BOUNDARY_MAX_ARRAY_LENGTH} elements cannot cross the host boundary`,
+    );
+  }
+}
+
+function encodeNumber(value) {
+  if (Number.isNaN(value)) {
+    return { Number: 'NaN' };
+  }
+  if (Object.is(value, -0)) {
+    return { Number: 'NegZero' };
+  }
+  if (value === Infinity) {
+    return { Number: 'Infinity' };
+  }
+  if (value === -Infinity) {
+    return { Number: 'NegInfinity' };
+  }
+  return { Number: { Finite: value } };
+}
+
+function isObjectLike(value) {
+  return value !== null && (typeof value === 'object' || typeof value === 'function');
+}
+
+function assertNotProxy(value) {
+  if (isObjectLike(value) && types.isProxy(value)) {
+    throw new TypeError('Proxy values cannot cross the host boundary');
+  }
+}
+
+function isPlainStructuredObject(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  assertNotProxy(value);
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function hasOwnProperty(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function defineEnumerableProperty(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true,
+  });
+}
+
+function isAccessorDescriptor(descriptor) {
+  return hasOwnProperty(descriptor, 'get') || hasOwnProperty(descriptor, 'set');
+}
+
+function enumerateDataProperties(value) {
+  assertNotProxy(value);
+  return Object.entries(Object.getOwnPropertyDescriptors(value)).filter(([, descriptor]) => {
+    if (!descriptor.enumerable) {
+      return false;
+    }
+    if (isAccessorDescriptor(descriptor)) {
+      throw new TypeError('host objects with accessors cannot cross the host boundary');
+    }
+    return true;
+  });
+}
+
+function enterStructuredTraversal(value, traversal) {
+  if (!isObjectLike(value)) {
+    return () => {};
+  }
+  if (traversal.active.has(value)) {
+    throw new TypeError('cyclic values cannot cross the host boundary');
+  }
+  traversal.active.add(value);
+  return () => {
+    traversal.active.delete(value);
+  };
+}
+
+function encodeStructuredArray(value, traversal, depth) {
+  assertNotProxy(value);
+  assertBoundaryArrayLength(value.length, 'host boundary');
+  const leave = enterStructuredTraversal(value, traversal);
+  try {
+    const entries = new Array(value.length);
+    for (let index = 0; index < value.length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (descriptor === undefined) {
+        entries[index] = 'Hole';
+        continue;
+      }
+      if (isAccessorDescriptor(descriptor)) {
+        throw new TypeError('host objects with accessors cannot cross the host boundary');
+      }
+      entries[index] = encodeStructured(descriptor.value, traversal, depth + 1);
+    }
+    return { Array: entries };
+  } finally {
+    leave();
+  }
+}
+
+function encodeStructuredObject(value, traversal, depth) {
+  const leave = enterStructuredTraversal(value, traversal);
+  try {
+    const object = {};
+    for (const [key, descriptor] of enumerateDataProperties(value)) {
+      defineEnumerableProperty(
+        object,
+        key,
+        encodeStructured(descriptor.value, traversal, depth + 1),
+      );
+    }
+    return { Object: object };
+  } finally {
+    leave();
+  }
+}
+
+function encodeStructured(value, traversal = { active: new WeakSet() }, depth = 1) {
+  assertBoundaryDepth(depth, 'host boundary');
+  if (value === undefined) {
+    return 'Undefined';
+  }
+  if (value === null) {
+    return 'Null';
+  }
+  if (typeof value === 'boolean') {
+    return { Bool: value };
+  }
+  if (typeof value === 'number') {
+    return encodeNumber(value);
+  }
+  if (typeof value === 'string') {
+    return { String: value };
+  }
+  if (Array.isArray(value)) {
+    return encodeStructuredArray(value, traversal, depth);
+  }
+  if (typeof value === 'object') {
+    if (!isPlainStructuredObject(value)) {
+      throw new TypeError(
+        'Unsupported host value: only plain objects and arrays can cross the host boundary',
+      );
+    }
+    return encodeStructuredObject(value, traversal, depth);
+  }
+  throw new TypeError('Unsupported host value');
+}
+
+function decodeStructured(value, depth = 1) {
+  assertBoundaryDepth(depth, 'structured host boundary');
+  if (value === 'Undefined') {
+    return undefined;
+  }
+  if (value === 'Null') {
+    return null;
+  }
+  if (value !== null && typeof value === 'object' && hasOwnProperty(value, 'Bool')) {
+    return value.Bool;
+  }
+  if (value !== null && typeof value === 'object' && hasOwnProperty(value, 'String')) {
+    return value.String;
+  }
+  if (value !== null && typeof value === 'object' && hasOwnProperty(value, 'Number')) {
+    const encoded = value.Number;
+    if (encoded === 'NaN') {
+      return NaN;
+    }
+    if (encoded === 'Infinity') {
+      return Infinity;
+    }
+    if (encoded === 'NegInfinity') {
+      return -Infinity;
+    }
+    if (encoded === 'NegZero') {
+      return -0;
+    }
+    return encoded.Finite;
+  }
+  if (value !== null && typeof value === 'object' && hasOwnProperty(value, 'Array')) {
+    assertBoundaryArrayLength(value.Array.length, 'structured host boundary');
+    const array = new Array(value.Array.length);
+    value.Array.forEach((entry, index) => {
+      if (entry !== 'Hole') {
+        array[index] = decodeStructured(entry, depth + 1);
+      }
+    });
+    return array;
+  }
+  if (value !== null && typeof value === 'object' && hasOwnProperty(value, 'Object')) {
+    const object = {};
+    for (const [key, entry] of Object.entries(value.Object)) {
+      defineEnumerableProperty(object, key, decodeStructured(entry, depth + 1));
+    }
+    return object;
+  }
+  throw new TypeError(`Unsupported structured value: ${JSON.stringify(value)}`);
+}
+
+function encodeStartOptions(inputs = {}, policy) {
+  const encodedInputs = {};
+  for (const [key, descriptor] of enumerateDataProperties(inputs)) {
+    defineEnumerableProperty(encodedInputs, key, encodeStructured(descriptor.value));
+  }
+  return JSON.stringify({
+    inputs: encodedInputs,
+    capabilities: policy.capabilities,
+    limits: policy.limits,
+  });
+}
+
+function encodeResumePayloadValue(value) {
+  return JSON.stringify({
+    type: 'value',
+    value: encodeStructured(value),
+  });
+}
+
+function readOwnDataProperty(value, key, label) {
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  if (descriptor === undefined) {
+    return undefined;
+  }
+  if (isAccessorDescriptor(descriptor)) {
+    throw new TypeError(`${label} cannot use accessor-backed ${key} properties`);
+  }
+  return descriptor.value;
+}
+
+function encodeResumePayloadError(error) {
+  const source = error instanceof Error ? error : Object(error);
+  assertNotProxy(source);
+  const name = readOwnDataProperty(source, 'name', 'host errors');
+  const message = readOwnDataProperty(source, 'message', 'host errors');
+  const code = readOwnDataProperty(source, 'code', 'host errors');
+  const details = readOwnDataProperty(source, 'details', 'host errors');
+  return JSON.stringify({
+    type: 'error',
+    error: {
+      name: typeof name === 'string' ? name : 'Error',
+      message: typeof message === 'string' ? message : '',
+      code: typeof code === 'string' ? code : null,
+      details: details === undefined ? null : encodeStructured(details),
+    },
+  });
+}
+
+function encodeResumePayloadCancel() {
+  return JSON.stringify({
+    type: 'cancelled',
+  });
+}
+
+module.exports = {
+  decodeStructured,
+  defineEnumerableProperty,
+  encodeResumePayloadCancel,
+  encodeResumePayloadError,
+  encodeResumePayloadValue,
+  encodeStartOptions,
+  encodeStructured,
+  enumerateDataProperties,
+  hasOwnProperty,
+  isAccessorDescriptor,
+};

package/dist/native-loader.js

@@ -0,0 +1,227 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function packageRoot(fromDir = __dirname) {
+  return path.basename(fromDir) === 'dist' ? path.dirname(fromDir) : fromDir;
+}
+
+const PREBUILT_TARGETS = Object.freeze([
+  {
+    triple: 'x86_64-pc-windows-msvc',
+    platform: 'win32',
+    arch: 'x64',
+    platformArchABI: 'win32-x64-msvc',
+    packageName: 'mustardscript-win32-x64-msvc',
+    localFile: 'index.win32-x64-msvc.node',
+    os: ['win32'],
+    cpu: ['x64'],
+  },
+  {
+    triple: 'x86_64-apple-darwin',
+    platform: 'darwin',
+    arch: 'x64',
+    platformArchABI: 'darwin-x64',
+    packageName: 'mustardscript-darwin-x64',
+    localFile: 'index.darwin-x64.node',
+    os: ['darwin'],
+    cpu: ['x64'],
+  },
+  {
+    triple: 'aarch64-apple-darwin',
+    platform: 'darwin',
+    arch: 'arm64',
+    platformArchABI: 'darwin-arm64',
+    packageName: 'mustardscript-darwin-arm64',
+    localFile: 'index.darwin-arm64.node',
+    os: ['darwin'],
+    cpu: ['arm64'],
+  },
+  {
+    triple: 'x86_64-unknown-linux-gnu',
+    platform: 'linux',
+    arch: 'x64',
+    platformArchABI: 'linux-x64-gnu',
+    packageName: 'mustardscript-linux-x64-gnu',
+    localFile: 'index.linux-x64-gnu.node',
+    os: ['linux'],
+    cpu: ['x64'],
+    libc: ['glibc'],
+  },
+]);
+
+const TARGETS_BY_RUNTIME = new Map(
+  PREBUILT_TARGETS.map((target) => [`${target.platform}:${target.arch}`, target]),
+);
+
+function isExplicitFilePath(specifier) {
+  return (
+    path.isAbsolute(specifier) ||
+    specifier.startsWith(`.${path.sep}`) ||
+    specifier.startsWith(`..${path.sep}`) ||
+    specifier.startsWith('./') ||
+    specifier.startsWith('../')
+  );
+}
+
+function resolveNativeAddonPath(candidate, label, cwd = process.cwd()) {
+  if (typeof candidate !== 'string' || candidate.trim() === '') {
+    throw new Error(`${label} must be a non-empty file path to a native .node addon`);
+  }
+  if (!isExplicitFilePath(candidate)) {
+    throw new Error(
+      `${label} must be an explicit absolute or relative file path to a native .node addon`,
+    );
+  }
+  const resolved = path.resolve(cwd, candidate);
+  if (path.extname(resolved) !== '.node') {
+    throw new Error(`${label} must point to a native .node addon`);
+  }
+  const stats = fs.statSync(resolved, { throwIfNoEntry: false });
+  if (!stats?.isFile()) {
+    throw new Error(`${label} does not exist: ${resolved}`);
+  }
+  return resolved;
+}
+
+function getCurrentPrebuiltTarget() {
+  return TARGETS_BY_RUNTIME.get(`${process.platform}:${process.arch}`) ?? null;
+}
+
+function getLocalBuildOutputFile() {
+  return getCurrentPrebuiltTarget()?.localFile ?? 'index.node';
+}
+
+function getLocalBinaryFilenames() {
+  return [...new Set([getLocalBuildOutputFile(), 'index.node'])];
+}
+
+function validatePrebuiltPackageManifest(manifest, target, packageJsonPath) {
+  if (manifest?.name !== target.packageName) {
+    throw new Error(
+      `optional prebuilt package at ${packageJsonPath} does not match ${target.packageName}`,
+    );
+  }
+  if (manifest?.main !== target.localFile) {
+    throw new Error(
+      `optional prebuilt package ${target.packageName} must expose its native addon as ${target.localFile}`,
+    );
+  }
+}
+
+function resolvePrebuiltPackage(searchRoot = packageRoot()) {
+  const target = getCurrentPrebuiltTarget();
+  if (!target) {
+    return null;
+  }
+
+  let packageJsonPath;
+  try {
+    packageJsonPath = require.resolve(`${target.packageName}/package.json`, {
+      paths: [searchRoot],
+    });
+  } catch {
+    return null;
+  }
+
+  const packageRoot = path.dirname(packageJsonPath);
+  const manifest = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  validatePrebuiltPackageManifest(manifest, target, packageJsonPath);
+
+  const binaryPath = path.join(packageRoot, target.localFile);
+  const stats = fs.statSync(binaryPath, { throwIfNoEntry: false });
+  if (!stats?.isFile()) {
+    throw new Error(`optional prebuilt package ${target.packageName} is missing ${target.localFile}`);
+  }
+
+  return {
+    ...target,
+    packageJsonPath,
+    packageRoot,
+    binaryPath,
+  };
+}
+
+function localBinaryCandidates(searchRoot = packageRoot()) {
+  const roots = [
+    searchRoot,
+    path.join(searchRoot, 'crates', 'mustard-node'),
+  ];
+  const candidates = [];
+
+  for (const root of roots) {
+    if (!fs.existsSync(root)) {
+      continue;
+    }
+
+    for (const filename of getLocalBinaryFilenames()) {
+      const candidate = path.join(root, filename);
+      const stats = fs.statSync(candidate, { throwIfNoEntry: false });
+      if (stats?.isFile()) {
+        candidates.push(candidate);
+      }
+    }
+  }
+
+  return candidates;
+}
+
+function loadNative(options = {}) {
+  const env = options.env ?? process.env;
+  const searchRoot = options.searchRoot ?? packageRoot();
+  const overrideCwd = options.overrideCwd ?? process.cwd();
+  const loadErrors = [];
+  const overridePath =
+    env.MUSTARDSCRIPT_NATIVE_LIBRARY_PATH ??
+    env.MUSTARD_NATIVE_LIBRARY_PATH ??
+    env.NAPI_RS_NATIVE_LIBRARY_PATH;
+  if (overridePath) {
+    try {
+      return require(resolveNativeAddonPath(overridePath, 'native library override', overrideCwd));
+    } catch (error) {
+      loadErrors.push(error);
+    }
+  }
+
+  for (const candidate of localBinaryCandidates(searchRoot)) {
+    try {
+      return require(candidate);
+    } catch (error) {
+      loadErrors.push(error);
+    }
+  }
+
+  try {
+    const prebuilt = resolvePrebuiltPackage(searchRoot);
+    if (prebuilt) {
+      try {
+        return require(prebuilt.binaryPath);
+      } catch (error) {
+        loadErrors.push(error);
+      }
+    }
+  } catch (error) {
+    loadErrors.push(error);
+  }
+
+  const target = getCurrentPrebuiltTarget();
+  const platformHint = target
+    ? `${target.platformArchABI} via ${target.packageName}`
+    : `${process.platform}-${process.arch}`;
+  throw new AggregateError(
+    loadErrors,
+    `Unable to locate a MustardScript native addon for ${platformHint}. Install a matching optional prebuilt package or allow the source build to run.`,
+  );
+}
+
+module.exports = {
+  PREBUILT_TARGETS,
+  getCurrentPrebuiltTarget,
+  getLocalBinaryFilenames,
+  getLocalBuildOutputFile,
+  localBinaryCandidates,
+  resolveNativeAddonPath,
+  resolvePrebuiltPackage,
+  loadNative,
+};

package/index.d.ts

@@ -0,0 +1,23 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare function cancelCancellationToken(tokenId: string): void
+
+export declare function claimProgressSnapshot(snapshotIdentity: string): boolean
+
+export declare function compileProgram(source: string): Buffer
+
+export declare function createCancellationToken(): string
+
+export declare function inspectSnapshot(snapshot: Buffer, policyJson: string): string
+
+export declare function isProgressSnapshotUsed(snapshotIdentity: string): boolean
+
+export declare function releaseCancellationToken(tokenId: string): void
+
+export declare function releaseProgressSnapshot(snapshotIdentity: string): void
+
+export declare function resumeProgram(snapshot: Buffer, payloadJson: string, policyJson: string, cancellationTokenId?: string | undefined | null): string
+
+export declare function snapshotIdentity(snapshot: Buffer): string
+
+export declare function startProgram(program: Buffer, optionsJson: string, cancellationTokenId?: string | undefined | null): string