@mirascript/mirascript 0.1.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@mirascript/mirascript",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "An expression based scripting language.",
+  "main": "./dist/index.js",
+  "bin": "./dist/cli/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@mirascript/dev": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./subtle": {
+      "@mirascript/dev": "./src/subtle.ts",
+      "default": "./dist/subtle.js"
+    },
+    "./cli": {
+      "@mirascript/dev": "./src/cli/index.ts",
+      "default": "./dist/cli/index.js"
+    }
+  },
+  "imports": {
+    "#compiler/worker": {
+      "@mirascript/dev": "./src/compiler/worker.ts",
+      "default": "./dist/compiler/worker.js"
+    },
+    "#compiler-bundle": {
+      "node": "@mirascript/napi",
+      "default": "@mirascript/wasm"
+    }
+  },
+  "dependencies": {
+    "@commander-js/extra-typings": "^14.0.0",
+    "ansi-styles": "^6.2.3",
+    "commander": "^14.0.1",
+    "js-base64": "^3.7.8",
+    "@mirascript/wasm": "~0.1.0",
+    "@mirascript/napi": "~0.1.0"
+  },
+  "devDependencies": {
+    "@types/sinon": "^17.0.4",
+    "ava": "^6.4.1",
+    "c8": "^10.1.3",
+    "sinon": "^21.0.0"
+  },
+  "scripts": {
+    "watch": "pnpm build:ts --watch",
+    "build:ts": "pnpm clean && tsc",
+    "build": "pnpm build:ts --emitDeclarationOnly && node ./esbuild.config.js",
+    "mirascript": "node ./dist/cli/index.js",
+    "clean": "rimraf dist",
+    "test": "c8 ava"
+  }
+}

package/src/cli/execute.ts

@@ -0,0 +1,32 @@
+/* eslint-disable no-console */
+import styles from 'ansi-styles';
+import { compile } from '../index.js';
+import { createVmContext, VmFunction, type VmValue } from '../vm/index.js';
+import { debug_print } from '../vm/lib/global/debug.js';
+import { print } from './print.js';
+
+/** 执行脚本 */
+export async function execute(script: string, template: boolean, variables: Record<string, VmValue>): Promise<void> {
+    try {
+        const f = await compile(script, { input_mode: template ? 'Template' : 'Script' });
+        const r = f(
+            createVmContext({
+                debug_print: VmFunction((...values) => {
+                    console.log(
+                        '\u001B[46;30m MiraScript \u001B[0m',
+                        ...values.map((v) => (typeof v == 'string' ? v : print(v))),
+                    );
+                }, debug_print),
+                ...variables,
+            }),
+        );
+        if (template) {
+            console.log(r);
+        } else {
+            console.log(print(r));
+        }
+    } catch (ex) {
+        console.error(styles.red.open + (ex as Error).message + styles.red.close);
+        process.exitCode = 2;
+    }
+}

package/src/cli/index.ts

@@ -0,0 +1,73 @@
+/* c8 ignore start */
+/* eslint-disable no-console */
+import { readFile, stat } from 'node:fs/promises';
+import { program } from '@commander-js/extra-typings';
+import { execute } from './execute.js';
+import pkg from '../../package.json' with { type: 'json' };
+import { compileSync } from '../compiler/index.js';
+import type { VmValue } from '../vm/index.js';
+
+program.name(pkg.name.split('/').pop()!).version(pkg.version).description(pkg.description);
+
+program
+    .option(
+        '-v, --variable <key=value>',
+        '设置全局变量，可以多次使用',
+        (v, p) => {
+            p = { ...p };
+            const i = v.indexOf('=');
+            if (i < 0) {
+                p[v] = true;
+            } else {
+                const key = v.slice(0, i).trim();
+                const value = v.slice(i + 1).trim();
+                try {
+                    const pv = compileSync(`return (${value});`)();
+                    p[key] = pv ?? value;
+                } catch {
+                    p[key] = value;
+                }
+            }
+            return p;
+        },
+        {} as Record<string, VmValue>,
+    )
+    .option('-t, --template', '使用模板模式')
+    .option('--no-template', '使用脚本模式')
+    .option('-e, --eval <script>', '要执行的脚本')
+    .argument('[script]', '要执行的脚本文件路径（如果提供了 -e 则忽略此参数）')
+    .action(async (script, opt) => {
+        if (opt.eval != null) {
+            await execute(opt.eval, !!opt.template, opt.variable);
+            return;
+        }
+        if (script) {
+            try {
+                const s = await stat(script);
+                if (!s.isFile()) {
+                    console.error(`脚本路径不是文件: ${script}`);
+                    process.exitCode = 2;
+                    return;
+                }
+            } catch (ex) {
+                if ((ex as NodeJS.ErrnoException).code === 'ENOENT') {
+                    console.error(`脚本文件不存在: ${script}`);
+                    process.exitCode = 2;
+                } else if ((ex as NodeJS.ErrnoException).code === 'EACCES') {
+                    console.error(`权限不足: ${(ex as NodeJS.ErrnoException).message}`);
+                    process.exitCode = 3;
+                } else {
+                    console.error(`无法访问脚本文件: ${(ex as NodeJS.ErrnoException).message}`);
+                    process.exitCode = 1;
+                }
+                return;
+            }
+            const context = await readFile(script, 'utf8');
+            const template = opt.template ?? script.endsWith('.miratpl');
+            await execute(context, template, opt.variable);
+            return;
+        }
+        program.help({ error: true });
+    });
+
+await program.parseAsync();

package/src/cli/print.ts

@@ -0,0 +1,41 @@
+import styles from 'ansi-styles';
+import { serialize, type SerializeOptions } from '../subtle.js';
+import type { VmAny, VmRecord } from '../vm/index.js';
+
+const options: Partial<SerializeOptions> = {
+    maxDepth: 3,
+    serializeNil: () => styles.gray.open + 'nil' + styles.gray.close,
+    serializeBoolean: (v) => styles.blue.open + (v ? 'true' : 'false') + styles.blue.close,
+    serializeNumber: (v) =>
+        styles.yellow.open +
+        (Number.isNaN(v) ? 'nan' : Number.isFinite(v) ? v.toString() : v > 0 ? 'inf' : '-inf') +
+        styles.yellow.close,
+    serializeStringQuote: (v, open) => {
+        const q = styles.dim.open + v + styles.dim.close;
+        if (open) {
+            return styles.green.open + q;
+        } else {
+            return q + styles.green.close;
+        }
+    },
+    serializeStringEscape: (v) => styles.bold.open + v + styles.bold.close,
+    serializeFunction: (v) => styles.cyan.open + `<function ${v.name || 'anonymous'}>` + styles.cyan.close,
+    serializePropName: (v) => styles.whiteBright.open + String(v) + styles.whiteBright.close,
+    serializeModule: (v, depth, options) => {
+        return (
+            styles.magenta.open +
+            `<module ${v.name || 'anonymous'}>` +
+            styles.magenta.close +
+            ' ' +
+            options.serializeRecord(v.value as VmRecord, depth, options)
+        );
+    },
+};
+
+/** 序列化值 */
+export function print(value: VmAny, depth = 3): string {
+    if (value === undefined) {
+        return styles.gray.open + '<uninitialized>' + styles.gray.close;
+    }
+    return serialize(value, { ...options, maxDepth: depth });
+}

package/src/compiler/compile-bytecode.ts

@@ -0,0 +1,65 @@
+import type { CompileOptions, ScriptInput } from './types.js';
+import * as wasm from '@mirascript/wasm';
+
+/** 字节码模块 */
+type BcModule = typeof import('@mirascript/wasm') | typeof import('@mirascript/napi');
+
+let module: BcModule;
+let loading: Promise<void> | undefined;
+
+/** 加载模块 */
+export async function loadModule(): Promise<void> {
+    if (module != null) return;
+    if (loading) return loading;
+    const p = (async () => {
+        let mod: BcModule;
+        try {
+            mod = await import('#compiler-bundle');
+            /* c8 ignore next 5 */
+        } catch (ex) {
+            // eslint-disable-next-line no-console
+            console.warn('Failed to load compiler bundle, falling back to @mirascript/wasm');
+            mod = wasm;
+        }
+        await wasm.ready;
+        module = mod;
+    })();
+    void p.finally(() => {
+        if (loading === p) {
+            loading = undefined;
+        }
+    });
+    loading = p;
+    return p;
+}
+
+/** 检查模块加载情况 */
+function checkModule(): void {
+    if (module == null) {
+        throw new Error('MiraScript compiler module is not loaded.');
+    }
+}
+
+/**
+ * 生成 MiraScript 字节码
+ */
+export function compileBytecodeSync(
+    script: ScriptInput,
+    options: CompileOptions,
+): [Uint8Array | undefined, Uint32Array] {
+    checkModule();
+    const result = module.compileSync(script, options);
+    return [result.chunk, result.diagnostics];
+}
+
+/**
+ * 生成 MiraScript 字节码
+ */
+export async function compileBytecode(
+    script: ScriptInput,
+    options: CompileOptions,
+): Promise<[Uint8Array | undefined, Uint32Array]> {
+    await loadModule();
+    const result = 'compile' in module ? await module.compile(script, options) : module.compileSync(script, options);
+    return [result.chunk, result.diagnostics];
+}

package/src/compiler/compile-fast.ts

@@ -0,0 +1,81 @@
+import { wrapScript } from './create-script.js';
+import type { TranspileOptions } from './types.js';
+import type { VmScript } from '../vm/types/index.js';
+import { GlobalFallback } from '../vm/helpers.js';
+import { isFinite } from '../helpers/utils.js';
+
+const REG_NUMBER_FULL = /^\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+// 只识别特殊变量名，其他标识符可能有与关键字冲突等情况，需要编译器处理
+const REG_IDENTIFIER_FAST = /^(?:\$+|@+)[a-zA-Z0-9_]*$/;
+
+// 为避免结果不一致，只对常量进行处理
+
+// 根据目前的 benchmark 结果：
+//   对长度满足 FAST_SCRIPT_MAX_LEN 的代码：
+//       未命中时：产生大约 5% 的损失
+//       命中时：提升性能 12 倍
+//   对长度超过 FAST_SCRIPT_MAX_LEN 的代码（未调用此函数）：未产生可观测的影响
+
+const FAST_SCRIPT_MAX_LEN = 32;
+
+/**
+ * 对短代码进行编译
+ */
+function compileScriptFast(code: string, options: TranspileOptions): VmScript | undefined {
+    if (code.length > FAST_SCRIPT_MAX_LEN) return undefined; // 超过长度限制，直接返回 undefined
+
+    const trimmedCode = code.trim();
+    if (!trimmedCode) {
+        return wrapScript(code, () => null);
+    }
+    switch (trimmedCode) {
+        case 'nil':
+            return wrapScript(code, () => null);
+        case 'true':
+            return wrapScript(code, () => true);
+        case 'false':
+            return wrapScript(code, () => false);
+        case 'nan':
+            return wrapScript(code, () => 0 / 0);
+        case 'inf':
+        case '+inf':
+            return wrapScript(code, () => 1 / 0);
+        case '-inf':
+            return wrapScript(code, () => -1 / 0);
+    }
+    if (REG_IDENTIFIER_FAST.test(trimmedCode)) {
+        // 直接返回标识符
+        const id = trimmedCode;
+        return wrapScript(code, (global = GlobalFallback()) => global.get(id) ?? null);
+    }
+    if (REG_NUMBER_FULL.test(trimmedCode)) {
+        const num = Number(trimmedCode);
+        if (!isFinite(num)) return undefined;
+        // 直接返回数字
+        return wrapScript(code, () => num);
+    }
+    return undefined;
+}
+
+const FAST_TEMPLATE_MAX_LEN = 1024;
+
+/**
+ * 对短代码进行编译
+ */
+function compileTemplateFast(code: string, options: TranspileOptions): VmScript | undefined {
+    if (code.length > FAST_TEMPLATE_MAX_LEN) return undefined; // 超过长度限制，直接返回 undefined
+
+    if (!code.includes('$')) {
+        // 不包含插值的模板
+        return wrapScript(code, () => code);
+    }
+    return undefined;
+}
+
+/**
+ * 对短代码进行编译
+ */
+export function compileFast(code: string, options: TranspileOptions): VmScript | undefined {
+    if (options.sourceMap) return undefined; // 不支持源映射
+    return (options.input_mode === 'Template' ? compileTemplateFast : compileScriptFast)(code, options);
+}

package/src/compiler/create-script.ts

@@ -0,0 +1,34 @@
+import { defineProperty } from '../helpers/utils.js';
+import { keys, values } from '../vm/env.js';
+import type { VmScript, VmScriptLike } from '../vm/types/script.js';
+import type { ScriptInput } from './types.js';
+
+const kVmScript = Symbol.for('mirascript.vm.script');
+
+/** 生成 JS 函数 */
+export function wrapScript(source: ScriptInput, script: VmScriptLike): VmScript {
+    /* c8 ignore next 3 */
+    if (kVmScript in script) {
+        return script as VmScriptLike as VmScript;
+    }
+    defineProperty(script, kVmScript, { value: true });
+    if (typeof source === 'string') {
+        defineProperty(script, 'source', { value: source, configurable: true });
+    } else if (source instanceof Uint8Array) {
+        defineProperty(script, 'source', { value: '<buffer>', configurable: true });
+    }
+    return script as VmScript;
+}
+
+/** 生成 JS 函数 */
+export function createScript(source: ScriptInput, code: string): VmScript {
+    let script;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval, @typescript-eslint/no-unsafe-call
+        script = new Function(...keys, code)(...values) as VmScriptLike;
+        /* c8 ignore next 3 */
+    } catch (error) {
+        throw new Error(`Failed to create script`, { cause: error });
+    }
+    return wrapScript(source, script);
+}

package/src/compiler/diagnostic.ts

@@ -0,0 +1,175 @@
+import { DiagnosticCode, wasm } from '@mirascript/wasm';
+import type { ScriptInput } from './types.js';
+import { isSafeInteger } from '../helpers/utils.js';
+
+export { DiagnosticCode };
+
+const diagnosticMessages = new Map<DiagnosticCode, string | undefined>();
+/** 获取 {@link DiagnosticCode} 对应的消息 */
+export function getDiagnosticMessage(code: DiagnosticCode): string | undefined {
+    if (!isSafeInteger(code) || code < 0 || code >= 0xffff) {
+        throw new RangeError(`Invalid DiagnosticCode: ${code}`);
+    }
+    if (diagnosticMessages.has(code)) {
+        return diagnosticMessages.get(code);
+    }
+    const msg = wasm.get_diagnostic_message(code);
+    diagnosticMessages.set(code, msg);
+    return msg;
+}
+
+/**
+ * A range in the editor. This interface is suitable for serialization.
+ */
+export interface IRange {
+    /**
+     * Line number on which the range starts (starts at 1).
+     */
+    readonly startLineNumber: number;
+    /**
+     * Column on which the range starts in line `startLineNumber` (starts at 1).
+     */
+    readonly startColumn: number;
+    /**
+     * Line number on which the range ends.
+     */
+    readonly endLineNumber: number;
+    /**
+     * Column on which the range ends in line `endLineNumber`.
+     */
+    readonly endColumn: number;
+}
+
+/** 源代码诊断信息 */
+interface SourceDiagnosticBase<T extends DiagnosticCode = DiagnosticCode> {
+    /** 代码 */
+    readonly code: T;
+    /** 位置 */
+    readonly range: IRange;
+}
+
+/** 源代码诊断信息 */
+export interface SourceDiagnostic<T extends DiagnosticCode = DiagnosticCode> extends SourceDiagnosticBase<T> {
+    /** 引用 */
+    readonly references: ReadonlyArray<SourceReference<T>>;
+}
+/** 源代码引用信息 */
+export interface SourceReference<T extends DiagnosticCode = DiagnosticCode> extends SourceDiagnosticBase<T> {
+    /** 反向引用 */
+    readonly diagnostic: SourceDiagnostic<T>;
+}
+
+/** 分析诊断信息 */
+export function parseDiagnostics(
+    source: ScriptInput,
+    diagnostics: Uint32Array,
+): {
+    errors: SourceDiagnostic[];
+    warnings: SourceDiagnostic[];
+    infos: SourceDiagnostic[];
+    hints: SourceDiagnostic[];
+    tags: SourceDiagnostic[];
+
+    references: SourceReference[];
+    tagsReferences: SourceReference[];
+} {
+    const parsed = [];
+    const bufLen = diagnostics.length;
+    for (let i = 0; i < bufLen; i += 5) {
+        const startLineNumber = diagnostics[i]!;
+        const startColumn = diagnostics[i + 1]!;
+        const endLineNumber = diagnostics[i + 2]!;
+        const endColumn = diagnostics[i + 3]!;
+        const error = diagnostics[i + 4]! as DiagnosticCode;
+        parsed.push({
+            code: error,
+            range: {
+                startLineNumber,
+                startColumn,
+                endLineNumber,
+                endColumn,
+            },
+        } as Writable<SourceDiagnostic & SourceReference>);
+    }
+
+    const _errors: SourceDiagnostic[] = [];
+    const _warnings: SourceDiagnostic[] = [];
+    const _infos: SourceDiagnostic[] = [];
+    const _hints: SourceDiagnostic[] = [];
+    const _tags: SourceDiagnostic[] = [];
+    const _references: SourceReference[] = [];
+    const _tagsReferences: SourceReference[] = [];
+    for (let i = 0; i < parsed.length; i++) {
+        const diagnostic = parsed[i]!;
+        const { code } = diagnostic;
+        if (code > DiagnosticCode.ErrorStart && code < DiagnosticCode.ErrorEnd) {
+            _errors.push(diagnostic);
+        } else if (code > DiagnosticCode.WarningStart && code < DiagnosticCode.WarningEnd) {
+            _warnings.push(diagnostic);
+        } else if (code > DiagnosticCode.InfoStart && code < DiagnosticCode.InfoEnd) {
+            _infos.push(diagnostic);
+        } else if (code > DiagnosticCode.HintStart && code < DiagnosticCode.HintEnd) {
+            _hints.push(diagnostic);
+        } else if (code > DiagnosticCode.TagStart && code < DiagnosticCode.TagEnd) {
+            _tags.push(diagnostic);
+        } else {
+            continue;
+        }
+        diagnostic.references = [];
+        while (i + 1 < parsed.length) {
+            const ref = parsed[i + 1]!;
+            let isRef = false;
+            if (ref.code > DiagnosticCode.TagRefStart && ref.code < DiagnosticCode.TagRefEnd) {
+                isRef = true;
+                _tagsReferences.push(ref);
+            }
+            if (ref.code > DiagnosticCode.ReferenceStart && ref.code < DiagnosticCode.ReferenceEnd) {
+                isRef = true;
+                _references.push(ref);
+            }
+            if (!isRef) {
+                break;
+            }
+            i++;
+            ref.diagnostic = diagnostic;
+            (diagnostic.references as SourceReference[]).push(ref);
+        }
+    }
+    return {
+        errors: _errors,
+        warnings: _warnings,
+        infos: _infos,
+        hints: _hints,
+        tags: _tags,
+        references: _references,
+        tagsReferences: _tagsReferences,
+    };
+}
+
+/** 生成诊断 range 的字符串 */
+function formatRange(range: {
+    startLineNumber: number;
+    startColumn: number;
+    endLineNumber: number;
+    endColumn: number;
+}): string {
+    if (range.startLineNumber === range.endLineNumber) {
+        if (range.startColumn === range.endColumn) {
+            return `${range.startLineNumber}:${range.startColumn}`;
+        }
+        return `${range.startLineNumber}:${range.startColumn}-${range.endColumn}`;
+    }
+    return `${range.startLineNumber}:${range.startColumn}-${range.endLineNumber}:${range.endColumn}`;
+}
+
+/** 生成诊断消息的字符串 */
+export function formatDiagnostic(diagnostic: SourceDiagnostic): string {
+    const range = formatRange(diagnostic.range);
+    const codeName = DiagnosticCode[diagnostic.code] || `Unknown(${diagnostic.code})`;
+    let message = getDiagnosticMessage(diagnostic.code);
+    for (const ref of diagnostic.references) {
+        const refRange = formatRange(ref.range);
+        message += `\n    (${refRange}): ${getDiagnosticMessage(ref.code)}`;
+    }
+    return `  ${codeName}(${range}): ${message}`;
+}