@swf2es/cli 0.0.0-stage → 0.1.0

package/src/aot.ts

@@ -0,0 +1,239 @@
+// Ahead-of-time compilation: a SWF's ABCs compiled as the player compiles
+// them for a SWF it loads as its main movie, so that each module is byte
+// for byte what the browser would compile (the JIT/AOT invariant in
+// docs/architecture/overview.md). The steps are Code's in packages/player, in the
+// same order: the libraries added to the root domain, each compiled as it
+// is added, then the SWF's DoABCs all added to a child of the root before
+// any of them compiles. An AVM1 SWF's action blocks compile to one module
+// of their own (compileActionsAhead), which needs no library.
+import { createHash } from "node:crypto";
+import {
+  AIR_API_VERSION,
+  API_VERSION,
+  actionsKey,
+  type Codegen,
+  type LibraryDigest,
+  libraryLog,
+  moduleKey,
+} from "@swf2es/codegen";
+import { type ActionList, isAs3, readActions, readDoAbc, readSwf, tags } from "@swf2es/format";
+import { avm2 } from "@swf2es/runtime";
+
+export { AIR_API_VERSION, API_VERSION };
+
+export interface AbcInput {
+  /** DoABC2's name, "" for a DoABC or a bare ABC. */
+  name: string;
+  /** DoABC2's lazy flag: its scripts run on first use, not when it loads. */
+  lazy: boolean;
+  abc: Uint8Array;
+}
+
+export interface Input {
+  kind: "swf" | "abc";
+  /** The SWF's version, 0 for a bare ABC. */
+  version: number;
+  abcs: AbcInput[];
+  /** An AVM1 SWF's action blocks; null for an AS3 SWF or an ABC. */
+  avm1: Avm1Input | null;
+}
+
+export interface Avm1Input {
+  /** The SWF's decompressed bytes, which the blocks' ranges are of. */
+  bytes: Uint8Array;
+  actions: ActionList;
+}
+
+/** An AVM1 SWF's module. */
+export interface ActionsModule {
+  /** The ES module's source. */
+  module: string;
+  /** SHA-256 of the SWF's decompressed bytes, as the key names it. */
+  hash: string;
+  /**
+   * The SHA-256 of its key, codegen's actionsKey, as the player's module
+   * cache is to look it up; null for a compiler without an identity.
+   */
+  key: string | null;
+  /** How many blocks it has an entry for. */
+  blocks: number;
+}
+
+export interface Module {
+  name: string;
+  /** SHA-256 of the ABC, as the player and the cache key name it. */
+  hash: string;
+  lazy: boolean;
+  /** The ES module's source. */
+  module: string;
+  /**
+   * What compiling it fixed in the compiler's domain, which the player
+   * replays in its place (Codegen.compileModuleLogged); null where it
+   * cannot be.
+   */
+  log: string | null;
+  /**
+   * The SHA-256 of its key, as the player's module cache looks it up when
+   * it loads the SWF as its main movie (codegen's moduleKey); null for a
+   * compiler without an identity, or a module without a log.
+   */
+  key: string | null;
+}
+
+const SIGNATURES = new Set(["FWS", "CWS", "ZWS"]);
+
+/** Input the command cannot compile, with why. */
+export class InputError extends Error {}
+
+/**
+ * The ABCs of a SWF, in tag order as the player links them, or a bare ABC
+ * as one; for an AVM1 SWF its action blocks instead, as the player runs
+ * its code as AVM1 and never compiles its DoABCs.
+ */
+export function readInput(bytes: Uint8Array): Input {
+  const signature = String.fromCharCode(...bytes.subarray(0, 3));
+  if (!SIGNATURES.has(signature)) {
+    // ABC headers name a minor and major version: 46 for Flash, 47 for AIR float.
+    if (bytes.length < 4 || (bytes[2] !== 46 && bytes[2] !== 47) || bytes[3] !== 0) {
+      throw new InputError("neither a SWF nor an ABC");
+    }
+
+    return { kind: "abc", version: 0, abcs: [{ name: "", lazy: false, abc: bytes }], avm1: null };
+  }
+
+  let swf: ReturnType<typeof readSwf>;
+  try {
+    swf = readSwf(bytes);
+  } catch (e) {
+    throw new InputError(`a truncated or corrupt SWF (${(e as Error).message})`);
+  }
+
+  const version = swf.header.version;
+  if (!isAs3(swf)) {
+    return {
+      kind: "swf",
+      version,
+      abcs: [],
+      avm1: { bytes: swf.bytes, actions: readActions(swf) },
+    };
+  }
+
+  // A DoABC cut short would reach codegen as a malformed ABC and read as
+  // the code's error; a SWF cut elsewhere the player plays, as far as it goes.
+  const last = swf.tags.at(-1);
+  if (swf.truncated && (last?.code === tags.DoABC || last?.code === tags.DoABC2)) {
+    throw new InputError("a truncated SWF: the file ends inside a DoABC tag");
+  }
+
+  const abcs: AbcInput[] = [];
+  for (const t of swf.tags) {
+    if (t.code === tags.DoABC || t.code === tags.DoABC2) {
+      abcs.push(readDoAbc(swf.bytes, t));
+    }
+  }
+
+  return { kind: "swf", version, abcs, avm1: null };
+}
+
+export function sha256(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export class RejectedError extends Error {
+  constructor(
+    readonly what: string,
+    readonly verifyError: number,
+    /** A library's, not the input's. */
+    readonly library: boolean,
+  ) {
+    super(`${what} was rejected: VerifyError #${verifyError}`);
+  }
+}
+
+/**
+ * The libraries' modules, those asked for by `keepLibraries`, and the
+ * ABCs' modules, in order, compiled at `apiVersion`: Flash Player's, or
+ * AIR_API_VERSION for a host that plays them as AIR does (the player's
+ * `air`), whose keys are its alone. The libraries compile whether kept or
+ * not: the player compiles each, and what a compile resolves of an ABC is
+ * what later ABCs compile against.
+ */
+export function compileAhead(
+  codegen: Codegen,
+  libraries: { name: string; abc: Uint8Array }[],
+  abcs: AbcInput[],
+  keepLibraries = false,
+  apiVersion = API_VERSION,
+): { libraries: Module[]; libraryInputs: { name: string; abc: Uint8Array }[]; abcs: Module[] } {
+  codegen.reset(apiVersion);
+  if (
+    abcs.some(({ abc }) => {
+      const version = codegen.abcVersion(abc);
+      return version?.major === 47 && version.minor >= 16;
+    }) &&
+    !avm2.hasFloatLibrary(libraries.map((lib) => lib.abc))
+  ) {
+    libraries = [...libraries, { name: "float", abc: avm2.floatLibrary }];
+  }
+
+  const hashes: string[] = [];
+  const builtins: boolean[] = [];
+  const add = (what: string, abc: Uint8Array, builtin: boolean, domain: number) => {
+    const error = codegen.add(abc, builtin, domain);
+    if (error) {
+      throw new RejectedError(what, error, builtin);
+    }
+
+    hashes.push(sha256(abc));
+    builtins.push(builtin);
+    return hashes.length - 1;
+  };
+  // Keyed before it compiles, as the player keys it before it asks its cache.
+  const compile = (index: number, libraryDigest: LibraryDigest | null) => {
+    const keyText =
+      codegen.identity === null
+        ? null
+        : moduleKey(codegen, index, { hashes, builtins }, libraryDigest);
+    const { module, log } = codegen.compileModuleLogged(hashes, index);
+    const key = keyText === null || log === null ? null : sha256Text(keyText);
+    return { hash: hashes[index], module, log, key };
+  };
+
+  const libraryModules: Module[] = [];
+  for (const { name, abc } of libraries) {
+    const index = add(`library ${name}`, abc, true, 0);
+    const compiled = compile(index, null);
+    if (keepLibraries) {
+      libraryModules.push({ name, lazy: false, ...compiled });
+    }
+  }
+
+  // The main movie's application domain, a child of the root's, as the player's mainDomain.
+  const domain = codegen.childDomain(0);
+  const indices = abcs.map(({ name, abc }, i) =>
+    add(`ABC ${i}${name ? ` (${name})` : ""}`, abc, false, domain),
+  );
+  // The libraries' part of the log, by its digest, as the player's keys name it once a SWF is added.
+  const count = libraries.length;
+  const digest: LibraryDigest | null =
+    indices.length > 0
+      ? { count, digest: sha256Text(libraryLog(codegen, indices[0], count)) }
+      : null;
+  const modules = abcs.map(({ name, lazy }, i) => ({ name, lazy, ...compile(indices[i], digest) }));
+
+  return { libraries: libraryModules, libraryInputs: libraries, abcs: modules };
+}
+
+/** An AVM1 SWF's action blocks' module, as the player is to compile it, and its key. */
+export function compileActionsAhead(codegen: Codegen, input: Avm1Input): ActionsModule {
+  const { bytes, actions } = input;
+  const hash = sha256(bytes);
+  const key =
+    codegen.identity === null ? null : sha256Text(actionsKey(codegen, hash, actions.version));
+  const module = codegen.compileActionsModule(bytes, actions);
+  return { module, hash, key, blocks: actions.blocks.length };
+}
+
+function sha256Text(text: string): string {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}

package/src/args.ts

@@ -0,0 +1,53 @@
+// What every command shares of its command line: the options all take,
+// and a mistake in it reported as a usage error.
+import { COMPILER_VERSION } from "@swf2es/codegen";
+import { usageError } from "./output.js";
+
+export interface Command {
+  name: string;
+  /** One line for the list of commands. */
+  summary: string;
+  usage: string;
+  main(argv: string[]): Promise<void>;
+}
+
+/** The options every command takes, which parseArgs' options spread. */
+export const COMMON_OPTIONS = {
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" },
+} as const;
+
+export const COMMON_USAGE = `  -h, --help           show this
+  -v, --version        print the compiler's version`;
+
+export function printVersion(): void {
+  console.log(`swf2es ${COMPILER_VERSION}`);
+}
+
+/**
+ * `command`'s arguments as `parse` reads them, a mistake in them a usage
+ * error; null once -h or -v has been answered, and the command is done.
+ */
+export function parse<T extends { values: { help?: boolean; version?: boolean } }>(
+  command: Command,
+  read: () => T,
+): T | null {
+  let parsed: T;
+  try {
+    parsed = read();
+  } catch (e) {
+    usageError((e as Error).message, command.name);
+  }
+
+  if (parsed.values.help) {
+    console.log(command.usage);
+    return null;
+  }
+
+  if (parsed.values.version) {
+    printVersion();
+    return null;
+  }
+
+  return parsed;
+}

package/src/commands/compile.ts

@@ -0,0 +1,286 @@
+// swf2es compile: a SWF's or an ABC's modules, ahead of time, as the player
+// compiles them for its main movie, with a manifest; an AVM1 SWF's one
+// module of its action blocks.
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { parseArgs } from "node:util";
+import { COMPILER_VERSION, createCodegen } from "@swf2es/codegen";
+import { airLibrary, builtinLibrary, playerglobalLibrary } from "@swf2es/player/libraries";
+import {
+  AIR_API_VERSION,
+  API_VERSION,
+  type Avm1Input,
+  compileActionsAhead,
+  compileAhead,
+  InputError,
+  type Module,
+  RejectedError,
+  readInput,
+  sha256,
+} from "../aot.js";
+import { COMMON_OPTIONS, COMMON_USAGE, type Command, parse } from "../args.js";
+import { codegenModule, read, readLibraries, writing } from "../files.js";
+import { fail, usageError } from "../output.js";
+
+const USAGE = `usage: swf2es compile <file.swf|file.abc> [options]
+       swf2es <file.swf|file.abc> [options]
+
+Compiles the ABCs of a SWF (its DoABC and DoABC2 tags, in order), or a bare
+ABC, to ES modules as the player compiles them for a SWF it loads as its
+main movie, byte for byte. Writes a .js file per ABC, a .log file of what
+its compile fixed, which the player replays in its place, and a
+manifest.json naming them, their ABCs' hashes, the keys the player's
+module cache looks them up by, and the compiler. An AVM1 SWF (one whose
+FileAttributes has no ActionScript 3 flag) compiles to one module of its
+action blocks, avm1.js, which takes no library.
+
+options:
+  -o, --out <dir>      where to write (default: <file name>.swf2es)
+  --lib <file.abc>     a library the code links against, loaded into the
+                       root domain in the order given; repeat for each.
+                       Default: what the player loads, which swf2es ships:
+                       avmplus' builtin.abc and the player's playerglobal,
+                       and with --air AIR's library after them
+  --emit-libraries     write the libraries' modules too
+  --air                compile for a player that plays the SWF as AIR does
+                       (its \`air\` option), AIR's API defined; a player
+                       in the other mode looks none of the modules up.
+                       Refused for an AVM1 SWF, which has no API versions
+  -q, --quiet          print nothing but errors
+${COMMON_USAGE}
+
+exit status: 0 on success, 2 for a mistake in the command line, 1 for
+anything else (an unreadable or rejected input or library, or an output
+that cannot be written)`;
+
+const OPTIONS = {
+  out: { type: "string", short: "o" },
+  lib: { type: "string", multiple: true },
+  "emit-libraries": { type: "boolean" },
+  air: { type: "boolean" },
+  quiet: { type: "boolean", short: "q" },
+  ...COMMON_OPTIONS,
+} as const;
+
+/**
+ * manifest.json's format: 2 added each module's log, key and lengths, and
+ * named the compiler by its stamped identity rather than its file's hash.
+ * An AVM1 SWF's `avm1` entry, which a reader of the ABCs' entries need not
+ * know, came later without a new version.
+ */
+const MANIFEST_VERSION = 2;
+
+/** What a previous run wrote to `out`, as its manifest names it, so that no stale module stays beside a new manifest. */
+async function removeModules(out: string): Promise<void> {
+  let old: { libraries?: unknown; abcs?: unknown; avm1?: unknown } | null;
+  try {
+    old = JSON.parse(await readFile(join(out, "manifest.json"), "utf8"));
+  } catch {
+    return;
+  }
+
+  const entries = [old?.libraries, old?.abcs, [old?.avm1]].flatMap((list) =>
+    Array.isArray(list) ? list : [],
+  );
+  // Only names this command writes: a manifest edited by hand names nothing else to delete.
+  for (const entry of entries) {
+    const name = (entry as { module?: unknown } | null)?.module;
+    if (typeof name === "string" && /^((abc|lib)-\d+|avm1)\.js$/.test(name)) {
+      for (const file of [name, name.replace(/\.js$/, ".log")]) {
+        await writing(join(out, file), () => rm(join(out, file), { force: true }));
+      }
+    }
+  }
+}
+
+/**
+ * The libraries the player loads, as @swf2es/web gives them, AIR's after
+ * the rest for an AIR player; the manifest's names tell swf2es's
+ * playerglobal from Flash Player's.
+ */
+function playerLibraries(air = false): { name: string; abc: Uint8Array }[] {
+  const libraries = [
+    { name: "builtin", abc: builtinLibrary },
+    { name: "playerglobal-swf2es", abc: playerglobalLibrary },
+  ];
+  return air ? [...libraries, { name: "air", abc: airLibrary }] : libraries;
+}
+
+export const compile: Command = {
+  name: "compile",
+  summary: "compile a SWF's or an ABC's modules ahead of time, with a manifest",
+  usage: USAGE,
+  async main(argv) {
+    const parsed = parse(compile, () =>
+      parseArgs({ args: argv, allowPositionals: true, options: OPTIONS }),
+    );
+    if (!parsed) {
+      return;
+    }
+
+    const { values, positionals } = parsed;
+    if (positionals.length !== 1) {
+      usageError(`expected one input file, got ${positionals.length}`, "compile");
+    }
+
+    const file = positionals[0];
+    const bytes = await read(file, "input");
+    let input: ReturnType<typeof readInput>;
+    try {
+      input = readInput(bytes);
+    } catch (e) {
+      fail(e instanceof InputError ? `${file}: ${e.message}` : String((e as Error).stack ?? e));
+    }
+
+    const out = values.out ?? `${basename(file, extname(file))}.swf2es`;
+    if (input.avm1) {
+      // AVM1 has no API versions: its module is the same for every player.
+      if (values.air) {
+        usageError(`${file} is an AVM1 SWF, which --air does not apply to`, "compile");
+      }
+
+      await compileAvm1(file, bytes, input.avm1, out, values.quiet ?? false);
+      return;
+    }
+
+    const libs = values.lib ? await readLibraries(values.lib) : playerLibraries(values.air);
+    if (input.abcs.length === 0) {
+      fail(`${file}: no DoABC or DoABC2 tag, so no ActionScript 3 to compile`);
+    }
+
+    const codegen = await createCodegen(await codegenModule());
+    const started = performance.now();
+    let compiled: ReturnType<typeof compileAhead>;
+    try {
+      compiled = compileAhead(
+        codegen,
+        libs,
+        input.abcs,
+        values["emit-libraries"],
+        values.air ? AIR_API_VERSION : API_VERSION,
+      );
+    } catch (e) {
+      if (!(e instanceof RejectedError)) {
+        fail(String((e as Error).stack ?? e));
+      }
+
+      fail(e.library ? e.message : `${file}: ${e.message}`);
+    }
+
+    const ms = performance.now() - started;
+    await writing(out, () => mkdir(out, { recursive: true }));
+    await removeModules(out);
+    let size = 0;
+    const write = async (file: string, text: string) => {
+      await writing(join(out, file), () => writeFile(join(out, file), text));
+      size += Buffer.byteLength(text);
+      return file;
+    };
+    // A module, its log beside it, and what a host's precompiled module cache
+    // looks it up by and checks it with: the key and the two's lengths.
+    const entry = async (name: string, m: Module) => {
+      const module = await write(`${name}.js`, m.module);
+      if (m.log === null || m.key === null) {
+        return { module };
+      }
+
+      const log = await write(`${name}.log`, m.log);
+      return { module, log, key: m.key, lengths: [m.module.length, m.log.length] };
+    };
+
+    // The compiler is named by the identity stamped into its binary, which
+    // the keys name too, so that a host can tell what another build wrote;
+    // an ABC by its hash, as its module names it, with the ABCs it was
+    // linked against.
+    const manifest = {
+      manifestVersion: MANIFEST_VERSION,
+      compiler: { name: "swf2es", version: COMPILER_VERSION, identity: codegen.identity },
+      // The version the modules were compiled at, which their keys name too.
+      apiVersion: codegen.apiVersion,
+      input: {
+        file: basename(file),
+        kind: input.kind,
+        version: input.version,
+        sha256: sha256(bytes),
+      },
+      libraries: await Promise.all(
+        compiled.libraryInputs.map(async ({ name, abc }, i) => {
+          const m = compiled.libraries[i];
+          const lib = { name, sha256: sha256(abc) };
+          return m ? { ...lib, ...(await entry(`lib-${i}`, m)) } : lib;
+        }),
+      ),
+      abcs: await Promise.all(
+        compiled.abcs.map(async (m, i) => ({
+          name: m.name,
+          sha256: m.hash,
+          lazy: m.lazy,
+          ...(await entry(`abc-${i}`, m)),
+        })),
+      ),
+    };
+    const manifestPath = join(out, "manifest.json");
+    await writing(manifestPath, () =>
+      writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`),
+    );
+    if (!values.quiet) {
+      const count = compiled.abcs.length + compiled.libraries.length;
+      console.log(
+        `${file}: ${count} module${count === 1 ? "" : "s"}, ${size} bytes, ` +
+          `compiled in ${Math.round(ms)} ms, in ${out}`,
+      );
+    }
+  },
+};
+
+/**
+ * An AVM1 SWF's module, avm1.js, and its manifest: the module's key, as
+ * the player's module cache is to look it up, the SHA-256 of the SWF's
+ * decompressed bytes it names, its length and how many blocks it has.
+ */
+async function compileAvm1(
+  file: string,
+  bytes: Uint8Array,
+  avm1: Avm1Input,
+  out: string,
+  quiet: boolean,
+): Promise<void> {
+  const codegen = await createCodegen(await codegenModule());
+  const started = performance.now();
+  const compiled = compileActionsAhead(codegen, avm1);
+  const ms = performance.now() - started;
+  await writing(out, () => mkdir(out, { recursive: true }));
+  await removeModules(out);
+  const module = "avm1.js";
+  await writing(join(out, module), () => writeFile(join(out, module), compiled.module));
+  const manifest = {
+    manifestVersion: MANIFEST_VERSION,
+    compiler: { name: "swf2es", version: COMPILER_VERSION, identity: codegen.identity },
+    apiVersion: API_VERSION,
+    input: {
+      file: basename(file),
+      kind: "swf",
+      version: avm1.actions.version,
+      sha256: sha256(bytes),
+    },
+    libraries: [],
+    abcs: [],
+    avm1: {
+      module,
+      sha256: compiled.hash,
+      blocks: compiled.blocks,
+      ...(compiled.key === null ? {} : { key: compiled.key, length: compiled.module.length }),
+    },
+  };
+  const manifestPath = join(out, "manifest.json");
+  await writing(manifestPath, () =>
+    writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`),
+  );
+  if (!quiet) {
+    const size = Buffer.byteLength(compiled.module);
+    const blocks = `${compiled.blocks} AVM1 block${compiled.blocks === 1 ? "" : "s"}`;
+    console.log(
+      `${file}: ${blocks}, 1 module, ${size} bytes, compiled in ${Math.round(ms)} ms, in ${out}`,
+    );
+  }
+}

package/src/commands/help.ts

@@ -0,0 +1,60 @@
+// swf2es help: the commands, or one command's usage.
+import { parseArgs } from "node:util";
+import { COMMON_OPTIONS, COMMON_USAGE, type Command, parse } from "../args.js";
+import { usageError } from "../output.js";
+import { compile } from "./compile.js";
+import { run } from "./run.js";
+
+export const help: Command = {
+  name: "help",
+  summary: "show the commands, or a command's usage",
+  usage: `usage: swf2es help [command]
+
+Shows the commands, or how to run one.
+
+options:
+${COMMON_USAGE}`,
+  async main(argv) {
+    const parsed = parse(help, () =>
+      parseArgs({ args: argv, allowPositionals: true, options: COMMON_OPTIONS }),
+    );
+    if (!parsed) {
+      return;
+    }
+
+    const { positionals } = parsed;
+    if (positionals.length > 1) {
+      usageError(`expected one command at most, got ${positionals.length}`);
+    }
+
+    if (positionals.length === 0) {
+      console.log(usage());
+      return;
+    }
+
+    const command = commands.get(positionals[0]);
+    if (!command) {
+      usageError(`no command ${positionals[0]}`);
+    }
+
+    console.log(command.usage);
+  },
+};
+
+export const commands = new Map<string, Command>([compile, run, help].map((c) => [c.name, c]));
+
+/** The command's own usage: its commands, and the bare form compile keeps. */
+export function usage(): string {
+  const width = Math.max(...[...commands.keys()].map((n) => n.length));
+  const list = [...commands.values()].map((c) => `  ${c.name.padEnd(width)}  ${c.summary}`);
+  return `usage: swf2es <command> [options]
+       swf2es <file.swf|file.abc> [options]   (as swf2es compile)
+
+commands:
+${list.join("\n")}
+
+options:
+${COMMON_USAGE}
+
+Run swf2es help <command> for a command's options.`;
+}