Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

14.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    verify.ts
 * @brief   Re-prove an EIR system's types, without looking at the TypeScript.
 *
 * @details tsc's types are not sound — structural typing, method bivariance and
 *          `any` all leak through generics — so a pass has to prove, on the IR,
 *          that every value is the type it claims.
 *
 *          It reads only EIR, never the AST. That is the point: re-running the
 *          frontend's own reasoning would agree with the frontend's own bugs,
 *          and the failure this catches is a frontend that lowered something
 *          wrong, not a source file that was outside the subset.
 */
import { resourceMethodBit } from '../../sdk/src/ecs/resourceShapes';
import {
    MATH_FNS,
    type CompShape, type EirFn, type EirSystem, type EirType, type Expr, type Local, type Place, type Stmt,
    typeName,
} from './eir';

export interface VerifyError {
    readonly system: string;
    readonly message: string;
}

class Verifier {
    private readonly byId = new Map<number, Local>();
    /** Row loops entered, so a `continue` can be asked whether it has a target. */
    private loopDepth = 0;
    readonly errors: VerifyError[] = [];

    constructor(
        private readonly sys: EirSystem,
        private readonly comps: ReadonlyMap<string, CompShape>,
        private readonly fns: ReadonlyMap<string, EirFn>,
    ) {
        for (const l of [...sys.params, ...sys.locals]) {
            if (this.byId.has(l.id)) this.fail(`local %${l.id} ('${l.name}') is declared twice`);
            this.byId.set(l.id, l);
        }
    }

    private fail(message: string): void {
        this.errors.push({ system: this.sys.name, message });
    }

    private local(id: number): Local | null {
        const l = this.byId.get(id);
        if (!l) { this.fail(`local %${id} is used but never declared`); return null; }
        return l;
    }

    /** What a place is rooted in, which is what says whether writing is allowed. */
    private rootType(p: Place): EirType | null {
        return p.p === 'local' ? this.local(p.id)?.type ?? null : this.rootType(p.base);
    }

    /** The type a place reads as, or null when it does not resolve. */
    placeType(p: Place): EirType | null {
        if (p.p === 'local') return this.local(p.id)?.type ?? null;
        const base = this.placeType(p.base);
        if (!base) return null;
        if (base.k !== 'comp' && base.k !== 'res') {
            this.fail(`a ${typeName(base)} has no field '${p.path.join('.')}'`);
            return null;
        }
        const shape = this.comps.get(base.name);
        if (!shape) { this.fail(`no declared shape for '${base.name}'`); return null; }
        const f = shape.fields.get(p.path.join('.'));
        if (!f) { this.fail(`'${base.name}' has no field '${p.path.join('.')}'`); return null; }
        return f.type;
    }

    exprType(e: Expr): EirType | null {
        switch (e.e) {
            case 'const':
                if ((typeof e.value === 'boolean') !== (e.type.k === 'bool')) {
                    this.fail(`constant ${String(e.value)} is declared ${typeName(e.type)}`);
                }
                return e.type;
            case 'read': {
                const t = this.placeType(e.place);
                if (t && t.k !== e.type.k) {
                    this.fail(`a read declared ${typeName(e.type)} resolves to ${typeName(t)}`);
                }
                return t;
            }
            case 'svc': {
                const base = this.placeType(e.base);
                if (base && base.k !== 'res') {
                    this.fail(`'${e.method}(…)' called on a ${typeName(base)}`);
                    return null;
                }
                // Re-asked of the shape rather than trusted from the frontend:
                // an undeclared method has no bit, and reading a bit that was
                // never mirrored answers zero instead of failing.
                if (base && !resourceMethodBit(base.name, e.method, e.key)) {
                    this.fail(`'${base.name}.${e.method}(${JSON.stringify(e.key)})' is not a declared service question`);
                }
                if (e.type.k !== 'bool') this.fail(`'${e.method}(…)' is declared ${typeName(e.type)}, not bool`);
                return e.type;
            }
            case 'neg': {
                const t = this.exprType(e.v);
                if (t && t.k !== 'f64') this.fail(`negation of a ${typeName(t)}`);
                return t;
            }
            case 'not': {
                const t = this.exprType(e.v);
                if (t && t.k !== 'bool') this.fail(`'!' applied to a ${typeName(t)}`);
                return e.type;
            }
            case 'logic': {
                for (const t of [this.exprType(e.l), this.exprType(e.r)]) {
                    if (t && t.k !== 'bool') this.fail(`operator '${e.op}' applied to a ${typeName(t)}`);
                }
                return e.type;
            }
            case 'bin': {
                for (const t of [this.exprType(e.l), this.exprType(e.r)]) {
                    if (t && t.k !== 'f64') this.fail(`operator '${e.op}' applied to a ${typeName(t)}`);
                }
                return e.type;
            }
            case 'select': {
                const c = this.exprType(e.cond);
                if (c && c.k !== 'bool') this.fail(`a ternary condition is a ${typeName(c)}`);
                const t = this.exprType(e.then);
                const f = this.exprType(e.otherwise);
                if (t && f && t.k !== f.k) this.fail(`ternary arms are ${typeName(t)} and ${typeName(f)}`);
                return e.type;
            }
            case 'call': {
                if (e.target.k === 'math') {
                    const arity = (MATH_FNS as Record<string, number | undefined>)[e.target.fn];
                    if (arity === undefined) this.fail(`'${e.target.fn}' is not an intrinsic`);
                    else if (arity !== e.args.length) {
                        this.fail(`${e.target.fn} called with ${e.args.length} argument(s), not ${arity}`);
                    }
                    for (const a of e.args) {
                        const t = this.exprType(a);
                        if (t && t.k !== 'f64') this.fail(`${e.target.fn} applied to a ${typeName(t)}`);
                    }
                    return e.type;
                }
                const def = this.fns.get(e.target.name);
                if (!def) { this.fail(`no function '${e.target.name}'`); return e.type; }
                if (def.params.length !== e.args.length) {
                    this.fail(`${def.name} called with ${e.args.length} argument(s), not ${def.params.length}`);
                }
                e.args.forEach((a, i) => {
                    const t = this.exprType(a);
                    const want = def.params[i]?.type;
                    if (t && want && t.k !== want.k) {
                        this.fail(`${def.name} argument ${i} is ${typeName(t)}, not ${typeName(want)}`);
                    }
                });
                if (def.ret.k !== e.type.k) this.fail(`${def.name} returns ${typeName(def.ret)}, read as ${typeName(e.type)}`);
                return e.type;
            }
        }
    }

    stmt(s: Stmt): void {
        switch (s.s) {
            // A jump out of a row loop that is not in one has no target: C would
            // take it to whatever encloses the emitted code instead.
            case 'continue': case 'break':
                if (this.loopDepth === 0) this.fail(`'${s.s}' outside a row loop`);
                break;
            case 'return':
                if (s.value !== null) this.fail('a system statement returns a value');
                break;
            case 'let': {
                const declared = this.local(s.id)?.type;
                const actual = this.exprType(s.value);
                if (declared && actual && declared.k !== actual.k) {
                    this.fail(`'${this.byId.get(s.id)?.name}' is ${typeName(declared)} but is bound to ${typeName(actual)}`);
                }
                break;
            }
            case 'assign': {
                const target = this.placeType(s.target);
                const value = this.exprType(s.value);
                if (target && value && target.k !== value.k) {
                    this.fail(`assigning ${typeName(value)} into a ${typeName(target)}`);
                }
                // The read-only half of ResMut, proved on the IR: a host writes
                // a resource block back only when the declaration asked for it,
                // so a write through `Res` would be dropped rather than refused.
                const root = this.rootType(s.target);
                if (root && root.k === 'res' && !root.mut) {
                    this.fail(`'${root.name}' is written but the system declared Res, not ResMut`);
                }
                break;
            }
            case 'emit': {
                const ch = this.placeType(s.channel);
                if (ch && ch.k !== 'channel') { this.fail(`emit to a ${typeName(ch)}`); break; }
                if (ch?.channel === 'event') {
                    // One argument per declared field, in declaration order —
                    // re-derived from the shape rather than trusted, because a
                    // short record would leave the host reading the next one.
                    const shape = this.comps.get(ch.name);
                    if (s.record !== 'send') this.fail(`'${s.record}' is not a record an event writer emits`);
                    else if (!shape) this.fail(`event '${ch.name}' has no declared payload`);
                    else if (s.args.length !== shape.fields.size) {
                        this.fail(`send to '${ch.name}' carries ${s.args.length} field(s), not ${shape.fields.size}`);
                    } else {
                        [...shape.fields.values()].forEach((f, i) => {
                            const t = this.exprType(s.args[i]!);
                            if (t && t.k !== f.type.k) {
                                this.fail(`send to '${ch.name}' field ${i} is ${typeName(t)}, not ${typeName(f.type)}`);
                            }
                        });
                    }
                    break;
                }
                if (s.record === 'despawn') {
                    const t = s.args[0] ? this.exprType(s.args[0]) : null;
                    if (s.args.length !== 1) this.fail(`despawn takes 1 argument, not ${s.args.length}`);
                    else if (t && t.k !== 'entity') this.fail(`despawn applied to a ${typeName(t)}`);
                } else {
                    this.fail(`'${s.record}' is not a record the verifier knows`);
                }
                break;
            }
            case 'if': {
                const c = this.exprType(s.cond);
                if (c && c.k !== 'bool') this.fail(`if condition is a ${typeName(c)}`);
                for (const b of [...s.then, ...s.otherwise]) this.stmt(b);
                break;
            }
            case 'rowLoop': {
                const q = this.placeType(s.query);
                if (!q) break;
                // An event reader yields one payload per step, bound like a
                // component so the body reads its fields the same way.
                if (q.k === 'events') {
                    if (s.binds.length !== 1 || s.entity !== null) {
                        this.fail('an event loop binds exactly one payload and no entity');
                        break;
                    }
                    const l = this.local(s.binds[0]!);
                    if (l && (l.type.k !== 'comp' || l.type.name !== q.name)) {
                        this.fail(`event loop binds '${l.name}' as ${typeName(l.type)} for '${q.name}'`);
                    }
                    this.loopDepth++;
                    for (const b of s.body) this.stmt(b);
                    this.loopDepth--;
                    break;
                }
                if (q.k !== 'query') { this.fail(`rowLoop over a ${typeName(q)}`); break; }
                if (q.args.length !== s.binds.length) {
                    this.fail(`rowLoop binds ${s.binds.length} components for a query of ${q.args.length}`);
                }
                s.binds.forEach((id, i) => {
                    const l = this.local(id);
                    const want = q.args[i];
                    if (!l || !want) return;
                    if (l.type.k !== 'comp' || l.type.name !== want.comp) {
                        this.fail(`row binds '${l.name}' as ${typeName(l.type)} for component '${want.comp}'`);
                    }
                    // A component the query did not ask to write must not be a
                    // target — the read-only half of Mut, proved here rather than
                    // trusted from the source.
                    if (!want.mut && this.writesTo(s.body, id)) {
                        this.fail(`'${l.name}' is written but the query asks for '${want.comp}' without Mut`);
                    }
                });
                if (s.entity !== null) {
                    const l = this.local(s.entity);
                    if (l && l.type.k !== 'entity') this.fail(`row entity bound as ${typeName(l.type)}`);
                }
                this.loopDepth++;
                for (const b of s.body) this.stmt(b);
                this.loopDepth--;
                break;
            }
        }
    }

    private writesTo(body: readonly Stmt[], id: number): boolean {
        const rootOf = (p: Place): number => (p.p === 'local' ? p.id : rootOf(p.base));
        for (const s of body) {
            if (s.s === 'assign' && rootOf(s.target) === id) return true;
            if (s.s === 'rowLoop' && this.writesTo(s.body, id)) return true;
            if (s.s === 'if' && (this.writesTo(s.then, id) || this.writesTo(s.otherwise, id))) return true;
        }
        return false;
    }
}

/** Every type claim in `sys`, re-proved. An empty array means it holds. */
export function verifySystem(
    sys: EirSystem,
    comps: ReadonlyMap<string, CompShape>,
    fns: ReadonlyMap<string, EirFn> = new Map(),
): VerifyError[] {
    const v = new Verifier(sys, comps, fns);
    for (const s of sys.body) v.stmt(s);
    return v.errors;
}