@swf2es/runtime 0.0.0-stage → 0.1.1

package/src/avm2/classes.ts

@@ -0,0 +1,235 @@
+// Classes as OP_newclass makes them: a class object and its instances'
+// traits from the module's descriptor, with its hooks, its prototype
+// object and its methods bound to the scope chain it is made in; and the
+// Vector.<T> classes applying Vector to a type makes.
+
+import type { Abc, AsObject, ClassDesc, Method, Scope, Value } from "./descriptors.js";
+import { firstDefinition } from "./domain.js";
+import { installMethod } from "./method-factories.js";
+import { formatClassName, type Multiname, NS_Public, qualifiedName } from "./names.js";
+import { invalidate } from "./property-cache.js";
+import type { Runtime } from "./runtime.js";
+import { BIND_Set, boundKey, methodKey, Traits, VALUE_TESTS } from "./traits.js";
+
+/**
+ * As OP_newclass: a class from its module's descriptor, extending `base`,
+ * its methods bound to the scope chain here. Object, Class and Function
+ * use the traits the runtime made for them before they existed.
+ */
+export function newClass(
+  rt: Runtime,
+  desc: ClassDesc,
+  base: AsObject | null,
+  scope: Scope,
+): AsObject {
+  const error = desc.instance.error ?? desc.static.error;
+  if (error) {
+    throw rt.error("VerifyError", error);
+  }
+
+  const abc = desc.abc as Abc;
+  const name = abc.names[desc.name] as Multiname;
+  const qualified = qualifiedName(name);
+  // As MethodEnv::newclass: a class with a base needs one (#1009), and
+  // one whose traits are the base's it linked to, which avmplus finds as
+  // a type (#1108). Compared by definition, as avmplus compares traits: a
+  // class made twice is one class. Where the base is the class its name
+  // finds by name, but not the one it finds as a type, as for a child's
+  // class it found by name after its parent defined the name too,
+  // avmshell rejects the class sooner, as corrupt (#1107). Only a class
+  // that exists is compared: the check runs no script.
+  if (desc.base && (base === null || base === undefined)) {
+    throw rt.error("TypeError", 1009);
+  }
+
+  if (rt.children && base) {
+    const baseName = abc.names[desc.base] as Multiname;
+    const script = rt.findScript(baseName, true);
+    const expected = script?.global ? rt.getProperty(script.global, baseName) : undefined;
+    if (expected?.$it && expected.$desc !== base.$desc) {
+      const byName = rt.findScript(baseName);
+      const named = byName?.global ? rt.getProperty(byName.global, baseName) : undefined;
+      throw rt.error("VerifyError", named === base ? 1107 : 1108);
+    }
+  }
+
+  // A builtin or a player's class, whose hook and type tests are its own,
+  // is the first definition of its name, as avmplus' natives belong to
+  // their ABC; a top-level one is public. A class only named as one, as a
+  // file's own internal Boolean is, is a class like any other.
+  const ns = name.namespaces[0];
+  const own =
+    (ns?.kind === NS_Public || !!ns?.uri) &&
+    firstDefinition(name.domain ?? rt.root, name)?.abc === abc;
+  const baseTraits: Traits | null = base ? base.$it : null;
+  let itraits: Traits;
+  if (own && qualified === "Object") {
+    itraits = rt.objectTraits;
+  } else if (own && qualified === "Class") {
+    itraits = rt.classTraits;
+  } else if (own && qualified === "Function") {
+    itraits = rt.functionTraits;
+  } else {
+    itraits = new Traits(qualified, baseTraits);
+    itraits.testsValues = own && VALUE_TESTS.has(qualified);
+  }
+
+  itraits.describe(desc.instance);
+  const hooks = own ? rt.classHooks[qualified] : undefined;
+  itraits.hooks = hooks ?? null;
+  itraits.dynamic = !desc.sealed;
+  itraits.final = desc.final;
+  itraits.isInterface = desc.interface;
+  itraits.ctor = desc.ctor ?? null;
+  itraits.metadata = desc.meta ?? null;
+  itraits.refusesNames = !!hooks?.refusesNames;
+  // As ClassClosure::checkForRestrictedInheritance.
+  itraits.restricted = !!hooks?.restricted;
+  itraits.uninstantiable =
+    !!baseTraits &&
+    (baseTraits.uninstantiable || (baseTraits.restricted && baseTraits.abc !== abc));
+  itraits.abc = abc;
+
+  // A class's allocation, bound to the runtime; its subclasses inherit it.
+  const create = hooks?.create;
+  if (create) {
+    itraits.create = (traits) => create(traits, rt);
+  }
+
+  if (hooks?.properties) {
+    itraits.properties = hooks.properties;
+  }
+
+  if (hooks?.getIndex) {
+    itraits.getIndex = hooks.getIndex;
+    itraits.setIndex = hooks.setIndex;
+    itraits.hasIndex = hooks.hasIndex;
+    itraits.index = hooks.index;
+  }
+
+  for (const i of desc.interfaces) {
+    const mn = abc.names[i] as Multiname;
+    const iface = rt.resolveName(mn);
+    if (iface) {
+      itraits.interfaces.add(iface.$it);
+      for (const t of iface.$it.interfaces) {
+        itraits.interfaces.add(t);
+      }
+    } else {
+      // Its script is the one running, and has not made it yet.
+      if (!itraits.pendingInterfaces) {
+        itraits.pendingInterfaces = [];
+      }
+
+      itraits.pendingInterfaces.push(() => rt.resolveName(mn)?.$it ?? null);
+    }
+  }
+
+  // The class object: Class's instance, with its own statics.
+  // Class is dynamic, so its instances are: String.fromCharCode = ... is legal.
+  const straits = new Traits(`${qualified}$`, rt.classTraits);
+  straits.dynamic = true;
+  straits.final = true;
+  straits.describe(desc.static);
+  const cls = straits.instance();
+  cls.$it = itraits;
+  cls.$desc = desc;
+  cls.$base = base;
+  itraits.cls = cls;
+  straits.cls = cls;
+
+  // Its prototype object: an Object whose prototype is the base class's.
+  // A class object's own $p comes from Class's instance prototype, which
+  // it inherits: class objects made before Class see it once Class exists.
+  // Date's, RegExp's and Array's are instances of their own class, as avmplus has them.
+  const prototype = hooks?.prototype ? hooks.prototype(rt, cls) : rt.objectTraits.instance();
+  prototype.$p = base ? base.$prototype : null;
+  cls.$prototype = prototype;
+  itraits.proto.$p = prototype;
+  prototype.$d.set("constructor", cls);
+  prototype.$dontEnum = new Set(["constructor"]);
+
+  const iscope = rt.scope(scope, [cls], 0);
+  for (const [d, factory, id, , params] of desc.static.methods) {
+    installMethod(rt, straits.methodHome(3), d, withId(factory(scope, base), id), factory, params);
+  }
+
+  for (const [d, factory, id, , params] of desc.instance.methods) {
+    installMethod(rt, itraits.methodHome(3), d, withId(factory(iscope, base), id), factory, params);
+  }
+
+  // Playerglobal can declare an accessor whose setter has no ABC body.
+  // Install it here so both direct bound calls and dynamic property writes reach it.
+  if (hooks?.setOnlySlots) {
+    for (const [name, slot] of Object.entries(hooks.setOnlySlots)) {
+      const binding = itraits.find(rt.publicName(name));
+      const d = (binding >> 3) + 1;
+      if ((binding & 7) === BIND_Set && itraits.proto[methodKey(d)] == null) {
+        const set = function (this: AsObject, value: Value) {
+          this[slot] = value;
+        };
+        itraits.proto[methodKey(d)] = set;
+        itraits.proto[boundKey(d)] = set;
+      }
+    }
+  }
+
+  // Calls through an interface read one name whatever the class; set
+  // here, before any instance exists, so that the prototype keeps its shape.
+  const aliases = desc.aliases;
+  if (aliases) {
+    const proto = itraits.proto;
+    for (let i = 0; i < aliases.length; i += 2) {
+      itraits.methodHome(1)[aliases[i] as string] = proto[boundKey(aliases[i + 1] as number)];
+    }
+  }
+
+  // Caches keep the methods and what the hooks decide.
+  invalidate();
+  const init = desc.init(iscope, base);
+  itraits.proto.$init = init;
+  // Its entry for `new` and `super()` of the class where the compiler
+  // coerced the arguments, as for bound calls (installMethod).
+  itraits.proto.$binit = (init as Method & { $bound?: Method }).$bound ?? init;
+  // A class constructClass only allocates and initializes, which compiled
+  // code constructs itself (see the codegen's constructSlot).
+  cls.$new = !hooks?.construct && !desc.interface && !itraits.uninstantiable;
+  // Its static initializer may name the class as a type, as avmplus
+  // resolves from traits, before initproperty has stored it anywhere.
+  rt.defining.set(qualified, cls);
+  try {
+    desc.cinit(scope, base).call(cls);
+  } finally {
+    rt.defining.delete(qualified);
+  }
+
+  hooks?.created?.(rt, cls);
+  return cls;
+}
+
+/**
+ * Vector.<T> for a T other than int, uint and Number: Vector$object's
+ * class, typed, whose name names T as avmplus does, a builtin Vector as
+ * Vector.<int>, and whose superclass is Vector.<*>, Vector$object.
+ */
+export function specializeVector(rt: Runtime, base: AsObject, param: AsObject): AsObject {
+  const itraits = new Traits(`__AS3__.vec::Vector.<${formatClassName(param.$it.name)}>`, base.$it);
+  itraits.dynamic = base.$it.dynamic;
+  itraits.refusesNames = base.$it.refusesNames;
+  itraits.hooks = base.$it.hooks;
+  const cls = Object.create(Object.getPrototypeOf(base));
+  cls.$d = null;
+  cls.$it = itraits;
+  cls.$desc = base.$desc;
+  cls.$base = base;
+  cls.$prototype = base.$prototype;
+  cls.$param = rt.refOf(param);
+  itraits.cls = cls;
+  return cls;
+}
+
+/** `f`, a method, with its method id, which a closure of it keeps. */
+export function withId(f: Method, id: number): Method {
+  (f as Method & { $id?: number }).$id = id;
+  return f;
+}

package/src/avm2/definitions.ts

@@ -0,0 +1,93 @@
+// Definitions by qualified name, "pkg::Name" or "Name", as a host and
+// ApplicationDomain look them up: a SWF's SymbolClass, a player's own
+// classes, and getDefinition.
+
+import type { Abc, AsObject, Value } from "./descriptors.js";
+import type { Domain } from "./domain.js";
+import { CONSTANT_Qname, Multiname, NS_Public, namespace, publicNs, qname } from "./names.js";
+import type { Runtime } from "./runtime.js";
+
+/**
+ * The class `qualified` names, "pkg::Name" or "Name", its defining script
+ * run; a ReferenceError if no script defines it. What a SWF's SymbolClass
+ * and a player's lookups by name go through, at every version.
+ */
+export function classNamed(rt: Runtime, qualified: string, domain: Domain | null): AsObject {
+  return classIn(rt, qualified, domain, (domain ?? rt.root).named, null);
+}
+
+/**
+ * The class `qualified` names in `domain` as code finds it, at user code's
+ * version, as avmshell's Domain.getClass does: a name of the other series'
+ * or the VM's own is a ReferenceError.
+ */
+export function classNamedByCode(rt: Runtime, qualified: string, domain: Domain): AsObject {
+  return classIn(rt, qualified, domain, domain.namedByCode, rt.userVersions);
+}
+
+/** The class `qualified` names, at `versions` or every version, kept in `named` once found. */
+function classIn(
+  rt: Runtime,
+  qualified: string,
+  domain: Domain | null,
+  named: Map<string, AsObject>,
+  versions: readonly number[] | null,
+): AsObject {
+  const known = named.get(qualified);
+  if (known) {
+    return known;
+  }
+
+  const cls = rt.resolveName(qualifiedNameIn(rt, qualified, domain, versions));
+  // A script still running its initializer may not have made the class yet.
+  if (cls) {
+    named.set(qualified, cls);
+  }
+
+  return cls;
+}
+
+/**
+ * What `qualified` names in `domain`, as Flash's
+ * ApplicationDomain.getDefinition finds it: a name no script defines is
+ * refused by its local name, and a script whose initializer threw runs
+ * again, its error coming through each time, where a name's lookup by
+ * code keeps it as run, as avmplus does. Seen at user code's version, as
+ * avmplus' public namespace is the caller's: a name of the other series'
+ * or the VM's own is not defined, as it is not to the code itself.
+ */
+export function definitionNamed(rt: Runtime, qualified: string, domain: Domain): Value {
+  const mn = qualifiedNameIn(rt, qualified, domain, rt.userVersions);
+  const script = rt.findScript(mn);
+  if (!script) {
+    throw rt.error("ReferenceError", 1065, mn.name);
+  }
+
+  return rt.getProperty(rt.initScript(script, true), mn);
+}
+
+/** The module whose script defines `qualified` for `domain`, or null: by it a player keys what SymbolClass binds. */
+export function definingAbc(rt: Runtime, qualified: string, domain: Domain): Abc | null {
+  return rt.findScript(qualifiedNameIn(rt, qualified, domain, null))?.abc ?? null;
+}
+
+/**
+ * The public name "pkg::Name" or "Name" stands for, looked up in `domain`:
+ * at `versions`, user code's as code finds a name, or with null at every
+ * version, as the host reaches names.
+ */
+function qualifiedNameIn(
+  rt: Runtime,
+  qualified: string,
+  domain: Domain | null,
+  versions: readonly number[] | null,
+): Multiname {
+  const i = qualified.lastIndexOf("::");
+  const ns = i < 0 ? publicNs : namespace(NS_Public, qualified.slice(0, i));
+  const local = i < 0 ? qualified : qualified.slice(i + 2);
+  const mn = versions
+    ? new Multiname(CONSTANT_Qname, [ns], versions, local, false)
+    : qname(ns, local);
+  mn.domain = domain === rt.root ? null : domain;
+  return mn;
+}

package/src/avm2/descriptors.ts

@@ -0,0 +1,137 @@
+// What a compiled module is built against: the values it handles, and the
+// descriptors of its traits, classes and scripts it gives the runtime
+// (docs/architecture/compiler.md, "Modules and the bootstrap").
+
+import type { Domain, Script } from "./domain.js";
+import type { Multiname, Namespace, TypeName } from "./names.js";
+import type { ClassRef, VectorRef } from "./traits.js";
+
+// biome-ignore lint/suspicious/noExplicitAny: AS3 values are untyped
+export type Value = any;
+// biome-ignore lint/suspicious/noExplicitAny: AS3 objects are untyped
+export type AsObject = any;
+// biome-ignore lint/complexity/noBannedTypes: methods take their receiver as this
+export type Method = Function;
+
+/** Not a property: distinct from undefined, which a property can hold. */
+export const NOT_FOUND = Symbol("not found");
+
+/** A scope chain: its objects, outermost first, and a bit per with scope in w. */
+export type Scope = Value[] & { w: number };
+
+/** A method factory: the method's function, once its scope chain is known. */
+export type Factory = (scope: Scope, sup: AsObject | null) => Method;
+
+/** A reference to a type: null for *, a builtin's name, or a class by name. */
+export type TypeRef = null | string | ClassRef | VectorRef;
+
+/** A metadata entry as the ABC has it: its name, and its keys and values alternating, a key "" where it has none. */
+export type Metadata = [string, string[]];
+
+/** A method's signature: its return type, its parameter types, and how many of them are required. */
+export type Signature = [TypeRef, TypeRef[], number];
+
+export interface TraitsDesc {
+  /** The VerifyError resolving the traits gave, if they did not resolve. */
+  error?: number;
+  slots: number;
+  defaults: [number, Value, TypeRef][];
+  bindings: [Namespace, number, string, number][];
+  /** Each by dispatch id: its factory, its method id in its ABC, and its signature. */
+  methods: [number, Factory, number, TypeRef, TypeRef[], number][];
+  /**
+   * Its own traits' metadata: the trait's kind as the ABC has it, its slot
+   * id for a slot, its dispatch id for a method or an accessor pair (the
+   * setter's one past the getter's), and the entries.
+   */
+  meta?: [number, number, Metadata[]][];
+  /**
+   * What sets a new object's slots, the base's included, by name, highest
+   * first, when it has any: constants it writes itself, any other initial
+   * value from `values`, by slot.
+   */
+  fill?: SlotFill;
+}
+
+/** Sets the slots of a new object `o`; `values` holds their initial values by slot. */
+export type SlotFill = (o: AsObject, values: Value[]) => void;
+
+export interface ClassDesc {
+  name: number;
+  base: number;
+  interfaces: number[];
+  final: boolean;
+  interface: boolean;
+  sealed: boolean;
+  protectedNs: number;
+  instance: TraitsDesc;
+  static: TraitsDesc;
+  init: Factory;
+  cinit: Factory;
+  /** The constructor's parameter types and how many are required, when it has any. */
+  ctor?: [TypeRef[], number];
+  /** The class's own metadata, from the trait that defines it. */
+  meta?: Metadata[];
+  /**
+   * For each method of its interfaces that it does not inherit an alias
+   * of, the name calls through the interface use and the dispatch id of
+   * the class's method, flat: the prototype's alias of its entry for
+   * bound calls (newClass).
+   */
+  aliases?: (string | number)[];
+  /** The module, set when it loads. */
+  abc?: Abc;
+}
+
+export interface ScriptDesc {
+  traits: TraitsDesc;
+  init: Factory;
+}
+
+export interface AbcDesc {
+  /** The hash of the module's ABC, and of the ABCs loaded before it, in order, that it was compiled against. */
+  hash: string;
+  linked: string[];
+  names: (Multiname | TypeName | null)[];
+  classes: ClassDesc[];
+  scripts: ScriptDesc[];
+  activations: (TraitsDesc | null)[];
+}
+
+/** A loaded module: what `rt.abc` returns, and methods reach as A. */
+export interface Abc extends AbcDesc {
+  scriptStates: Script[];
+  /** The domain it was loaded into, and its position among the ABCs loaded there. */
+  domain: Domain;
+  index: number;
+}
+
+/**
+ * What an ABC loaded into a domain compiles in: what the compiler needs to
+ * bind its names as the runtime will find them (see RuntimeOptions.compileAbc).
+ */
+export interface CompileUnit {
+  /** The hashes of the ABCs it is compiled after, its domain's chain, as its module names them. */
+  linked: string[];
+  /** Its domain and the domain's ancestors, by number, from the domain up to the root, 0. */
+  domains: number[];
+  /**
+   * What the domain finds, by name or as a type, that is not the first
+   * definition from the root down, as its caches hold it.
+   */
+  found: FoundDefinition[];
+}
+
+/** A definition a domain finds (see CompileUnit.found). */
+export interface FoundDefinition {
+  /** The name's namespace, by kind (NS_Public...) and URI, and the name. */
+  nsKind: number;
+  uri: string;
+  name: string;
+  /** The ABC that defines it: its domain's number, its position among the ABCs loaded there, and its hash. */
+  domain: number;
+  index: number;
+  hash: string;
+  /** Found as a type, as avmplus finds traits, else by name, as it finds scripts. */
+  asType: boolean;
+}