@swf2es/codegen 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Compiles ABC and AVM1 bytecode to ES modules.
+ *
+ * The compiler itself is AssemblyScript (assembly/), built to codegen.wasm.
+ * This wrapper instantiates it and gives its exports their types. The same wasm runs as the browser JIT
+ * (a module per ABC as its SWF loads) and as the ahead-of-time compiler,
+ * so both produce identical output. See docs/architecture/overview.md.
+ */
+import { AIR_API_VERSION, API_VERSION } from "@swf2es/format";
+/** Bumped whenever generated code or the runtime ABI it calls changes. */
+export declare const COMPILER_VERSION = "0.0.0";
+export { AIR_API_VERSION, API_VERSION };
+/** The ABCs added to a compiler, by their indices: each one's hash, and whether it was added as a library. */
+export interface AddedAbcs {
+    readonly hashes: readonly string[];
+    readonly builtins: readonly boolean[];
+}
+/**
+ * The log's entries made while only the first `count` ABCs, the libraries,
+ * were added, as a key names them: by the SHA-256 of libraryLog's text,
+ * taken once, since they are the same in every later module's context.
+ */
+export interface LibraryDigest {
+    count: number;
+    digest: string;
+}
+/** The text whose SHA-256 is a LibraryDigest's, for ABC `index`, any added after the first `count`. */
+export declare function libraryLog(codegen: Codegen, index: number, count: number): string;
+/**
+ * The text of ABC `index`'s module cache key, whose UTF-8's SHA-256 is the
+ * key: what the module depends on, the compiler's identity, the API
+ * version, every ABC its domain sees, by hash and whether it is a library,
+ * those added after it included, its own place among them, and the
+ * compiler's log about them (see Codegen.context), the libraries' part by
+ * its digest once taken. The player's module cache and the swf2es command
+ * both key by it, so that the command's modules are the cache's. Null
+ * where there is no context.
+ */
+export declare function moduleKey(codegen: Codegen, index: number, abcs: AddedAbcs, libraries: LibraryDigest | null): string | null;
+/**
+ * A SWF's AVM1 action blocks, as format's readActions lists them: the SWF's
+ * version and each block's range in its decompressed bytes.
+ */
+export interface ActionBlocks {
+    readonly version: number;
+    readonly blocks: readonly {
+        readonly offset: number;
+        readonly length: number;
+    }[];
+}
+/** What a SWF's action blocks compile to: one module, and each block's entry in it. */
+export interface CompiledActions {
+    module: string;
+    /** By block index: the block's entry in the module, as it compiles alone. */
+    entries: string[];
+    /** By key, each unit in the module's units, as it compiles alone. */
+    units: Map<string, ModuleUnit>;
+}
+/**
+ * Where control goes on in a unit, as V.far is called: an offset in the
+ * SWF's decompressed bytes, where the region it goes on in ends, where its
+ * actions' bytes end, and whether it runs as a SWF 5's function. The
+ * module's units are keyed by these, joined with commas.
+ */
+export interface ActionUnit {
+    readonly at: number;
+    readonly end: number;
+    readonly bound: number;
+    readonly five: boolean;
+}
+/**
+ * A unit's code, and what it depends on: it runs as well for any region
+ * that ends at or past `high` whose actions' bytes end at or past `reach`,
+ * -1 for only the one it was compiled for.
+ */
+export interface CompiledUnit {
+    code: string;
+    high: number;
+    reach: number;
+}
+/** A unit of a module's units, and what it was compiled for. */
+export interface ModuleUnit extends CompiledUnit {
+    unit: ActionUnit;
+}
+/**
+ * The text of the module cache key of a SWF's AVM1 module, whose UTF-8's
+ * SHA-256 is the key: the compiler's identity, the SWF's version, which
+ * picks the operations its code calls, and `hash`, the SHA-256 of the
+ * SWF's decompressed bytes, which hold its blocks. An AVM1 module links to
+ * nothing, so nothing else goes in.
+ */
+export declare function actionsKey(codegen: Codegen, hash: string, version: number): string;
+/**
+ * A definition an application domain has found by name, or as a type,
+ * which is not the first one from the root down, as the runtime reports it:
+ * what the domain's later ABCs compile against (see Codegen.found).
+ */
+export interface FoundDefinition {
+    /** The application domain that found it. */
+    domain: number;
+    /** The name's namespace: its kind (0 public, 1 package-internal, ...) and URI. */
+    nsKind: number;
+    uri: string;
+    name: string;
+    /** The ABC that defines it, by its position among those added. */
+    abc: number;
+    /** Found as a type (avmplus' cached traits), else by name (cached scripts). */
+    asType: boolean;
+}
+export interface AbcVersion {
+    major: number;
+    minor: number;
+}
+/** What an ABC compiles to: its module, the module's source map, and each compiled method body's entry in it. */
+export interface Compiled {
+    module: string;
+    /** JSON: the module's lines mapped to the AS3 lines debugline names. */
+    sourceMap: string;
+    /** By method body index: the body's entry in the module's F, as the JIT compiles it alone. */
+    entries: Map<number, string>;
+}
+/**
+ * What ABC `index`'s module depends on in the domain beyond the ABCs'
+ * bytes (see Codegen.context).
+ */
+export interface ModuleContext {
+    /** The ABCs its application domain sees, by their positions among those added, in load order. */
+    abcs: number[];
+    /** Its own place in `abcs`. */
+    own: number;
+    /**
+     * The domain's log about those ABCs, in order: the lazy answers fixed so
+     * far and the findings recorded, each with how many of `abcs` there were.
+     */
+    log: string;
+}
+/** A module compiled, and what compiling it fixed in the domain, to replay in its place (Codegen.replay); null where it cannot be. */
+export interface LoggedModule {
+    module: string;
+    log: string | null;
+}
+/**
+ * The compiler. ABCs are added to a domain in the order the SWF loads them
+ * (the builtins first), and the last one added compiles, whole or a method
+ * at a time, to code that is byte for byte the same either way.
+ */
+export interface Codegen {
+    /**
+     * The identity of this codegen.wasm, a hash of its bytes that its build
+     * stamps it with; null for one built without it.
+     */
+    readonly identity: string | null;
+    /** The version at the start of an ABC block, or null if it is too short. */
+    abcVersion(abc: Uint8Array): AbcVersion | null;
+    /**
+     * Start a domain whose user ABCs have API version `apiVersion`: Flash
+     * Player's, API_VERSION, by default, or AIR's, AIR_API_VERSION; one
+     * that is neither series' (checkApiVersion) is a RangeError.
+     */
+    reset(apiVersion?: number): void;
+    /** The API version of the last reset. */
+    readonly apiVersion: number;
+    /**
+     * Add an ABC, loaded into application domain `appDomain` (0, the root, by
+     * default), linking it against what that domain sees of those before it;
+     * 0, or the VerifyError it was rejected with (then it is not added).
+     * Throws for an application domain never made, or dropped.
+     */
+    add(abc: Uint8Array, builtin?: boolean, appDomain?: number): number;
+    /** A new application domain, a child of `parent`: its number. Throws for a `parent` never made, or dropped. */
+    childDomain(parent: number): number;
+    /**
+     * Drop application domain `appDomain` and its descendants once nothing
+     * can run their code: no other sees their ABCs, which compile no more,
+     * and compact reuses the memory they took. The indices of the ABCs added
+     * after them do not change, and neither does what those compile to.
+     * Nothing, if `epoch` is given and the domain was reset since.
+     */
+    dropDomain(appDomain: number, epoch?: number): void;
+    /**
+     * How many times `reset` has started a domain: a host that keeps the
+     * number a domain had passes it to dropDomain, which then drops nothing
+     * if the domain was reset since, as when another player took the Codegen
+     * over and its numbers are another domain's.
+     */
+    readonly epoch: number;
+    /**
+     * Rebuild the domain without the ABCs of dropped and evicted domains, if
+     * memory would otherwise grow and they hold enough to keep it from
+     * growing: whether it did. A rebuild links every live ABC again, tens of
+     * milliseconds for a large application, so a host calls this when it has
+     * time, as when idle; nothing else does.
+     */
+    compact(): boolean;
+    /**
+     * What the ABCs hold of codegen's memory, roughly, in bytes: the live
+     * ones', and the dropped and evicted domains' that compact would free;
+     * and the size of codegen's memory, which never shrinks.
+     */
+    usage(): {
+        live: number;
+        dead: number;
+        memory: number;
+    };
+    /**
+     * Evict application domain `appDomain` and its descendants while the host
+     * has no use for them, as once their ABCs are compiled: as dropped, but
+     * reviveDomain makes one live again. compact reuses what they took
+     * meanwhile, all but their findings, what was first resolved of them,
+     * and their ABCs' places.
+     */
+    evictDomain(appDomain: number): void;
+    /** Whether application domain `appDomain` is live: made, and neither evicted nor dropped. */
+    isLive(appDomain: number): boolean;
+    /**
+     * Make evicted application domain `appDomain` live again, with its evicted
+     * ancestors, the first of them a child of a live domain: given all their
+     * ABCs again by their indices, as they were added, their ABCs link as
+     * they did, by one rebuild at most, and what they found holds. Throws if
+     * they cannot be.
+     */
+    reviveDomain(appDomain: number, abcs: Map<number, Uint8Array>): void;
+    /** Record a definition an application domain has found; it holds for the ABCs added after. */
+    found(definition: FoundDefinition): void;
+    /**
+     * ABC `index` compiled whole, the last added by default, against every ABC
+     * added so far, later ones included, so a SWF's DoABCs may all be added
+     * before any compiles; `hashes` are the ABCs' hashes in load order, as
+     * the cache key names them.
+     */
+    compile(hashes?: string[], index?: number): Compiled;
+    /**
+     * ABC `index`'s module alone, as `compile` writes it, for a host that
+     * loads it and needs neither its source map nor its entries: writing
+     * those too would add a large ABC's worth to codegen's memory, which
+     * never shrinks.
+     */
+    compileModule(hashes?: string[], index?: number): string;
+    /**
+     * An opt-in JIT module's tables and lazy factories. Its default export
+     * takes (rt, jit); jit(body, bindings) returns that body's factory.
+     * Verification still runs now to fix scopes against the current domain.
+     * This module is not an AOT module and must not enter the module cache.
+     */
+    compileLazyModule(hashes?: string[], index?: number): string;
+    /**
+     * Method bodies of ABC `index` (the last added by default) compiled
+     * alone, as the optional lazy JIT compiles each on first factory use;
+     * a native, unverified or unknown one is left out. Each is byte for byte
+     * its entry in the whole module.
+     */
+    compileMethods(bodies: number[], index?: number): Map<number, string>;
+    /**
+     * What ABC `index`'s module depends on beyond the ABCs' bytes, for a
+     * cache key: besides the ABCs its domain sees, what the domain has
+     * fixed of what resolves lazily, which a later ABC in an ancestor would
+     * change were it first asked now. Its log only of the entries made with
+     * more than `after` ABCs added, and `upTo` at most unless negative. Null
+     * for an ABC never added.
+     */
+    context(index?: number, after?: number, upTo?: number): ModuleContext | null;
+    /**
+     * A string that changes whenever a context might: a host that took one
+     * and finds this the same since need not take it again.
+     */
+    revision(): string;
+    /** compileModule, with what the compile fixed in the domain (see replay). */
+    compileModuleLogged(hashes?: string[], index?: number): LoggedModule;
+    /**
+     * Fix in the domain what compiling ABC `index` did, from the log
+     * compileModuleLogged gave with its module, in place of compiling it:
+     * the domain is then as the compile would have left it, if its context
+     * is the one that compile had. False if the log is malformed or an
+     * entry fails, after doing those before it.
+     */
+    replay(log: string, index?: number): boolean;
+    /**
+     * A SWF's AVM1 action blocks compiled to one module, `bytes` the SWF's
+     * decompressed bytes, which the blocks' ranges are of (format's
+     * `Swf.bytes`), with each block's entry in it. Needs no domain: AVM1 code
+     * links to nothing.
+     */
+    compileActions(bytes: Uint8Array, actions: ActionBlocks): CompiledActions;
+    /** compileActions' module alone. */
+    compileActionsModule(bytes: Uint8Array, actions: ActionBlocks): string;
+    /**
+     * Blocks of a SWF compiled alone, by index, as a JIT may compile each
+     * when it first runs: each byte for byte its entry in the SWF's module.
+     * An index with no block is left out.
+     */
+    compileActionBlocks(bytes: Uint8Array, actions: ActionBlocks, blocks: number[]): Map<number, string>;
+    /**
+     * A unit of a SWF compiled alone, as V.far asks for it when control first
+     * goes on there: byte for byte its entry in the module's units.
+     */
+    compileActionUnit(bytes: Uint8Array, actions: ActionBlocks, unit: ActionUnit): CompiledUnit;
+    /**
+     * Let go of the copy of a SWF compileActionBlocks and compileActionUnit
+     * keep, as the host lets the SWF go; it is let go too once `bytes` are
+     * collected, and when blocks or units of other SWFs are asked for since.
+     */
+    releaseActions(bytes: Uint8Array): void;
+    /** How many SWFs compileActionBlocks and compileActionUnit keep a copy of, and how many times they have copied one in. */
+    heldActions(): {
+        held: number;
+        copies: number;
+    };
+}
+/**
+ * Instantiate the compiler from a compiled codegen.wasm module. Loading the
+ * bytes is left to the caller (fetch in browsers, fs in node), which keeps
+ * this package free of I/O. The file ships as `@swf2es/codegen/codegen.wasm`.
+ */
+export declare function createCodegen(module: WebAssembly.Module): Promise<Codegen>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}