@triflare/fx 1.0.3 → 2.1.0-beta.1

package/src/merge.js

@@ -0,0 +1,109 @@
+/**
+ * Multi-file project merge.
+ *
+ * Kept separate from `project.js` because merging is pure: it needs no
+ * filesystem access, so editor tooling (including the browser VS Code
+ * extension host) can reuse it without pulling in `node:fs`.
+ */
+import { ParseError } from "./errors.js";
+
+/** @param {object} loc */
+function errorInfo(loc) {
+  return {
+    file: loc && loc.file,
+    line: loc && loc.line,
+    column: loc && loc.column,
+  };
+}
+
+/**
+ * Merge parsed programs into a single project AST.
+ *
+ * - At most one `stage { }` declaration is allowed across all files.
+ * - Top-level statements from every file become stage content.
+ * - At most one plain `sprite "Name" { }` declaration is allowed per name.
+ *   Additional `partial sprite "Name" { }` fragments are appended to it.
+ * - Partial sprites only merge when `partialSprites` is enabled.
+ *
+ * Bodies are composed base-first, then fragments in build order, so costume
+ * order and local variable initializers stay predictable regardless of which
+ * file happens to sort first.
+ *
+ * @param {Array<{ast: object, file: string}>} entries
+ * @param {{partialSprites?: boolean, configName?: string}} [options]
+ * @returns {object} a `Program` node
+ */
+export function mergePrograms(
+  entries,
+  { partialSprites = false, configName = "fx.yml" } = {},
+) {
+  let stage = null;
+  const topItems = [];
+  /** @type {Map<string, {name: string, loc: object, base: object|null, fragments: object[], files: string[]}>} */
+  const groups = new Map();
+
+  for (const { ast, file } of entries) {
+    if (ast.stage) {
+      if (stage) {
+        throw new ParseError(
+          "A project may only declare one stage",
+          errorInfo(ast.stage.loc),
+        );
+      }
+      stage = ast.stage;
+    }
+    topItems.push(...ast.topItems);
+    for (const sprite of ast.sprites) {
+      if (sprite.partial && !partialSprites) {
+        throw new ParseError(
+          `partial sprite ${JSON.stringify(sprite.name)} is disabled; ` +
+            `set "fx.partialSprites: true" in ${configName} to enable it`,
+          errorInfo(sprite.loc),
+        );
+      }
+
+      let group = groups.get(sprite.name);
+      if (!group) {
+        group = {
+          name: sprite.name,
+          loc: sprite.loc,
+          base: null,
+          fragments: [],
+          files: [],
+        };
+        groups.set(sprite.name, group);
+      }
+      group.files.push(file);
+
+      if (sprite.partial) {
+        group.fragments.push({ decl: sprite, file });
+      } else if (group.base) {
+        throw new ParseError(
+          `Duplicate sprite ${JSON.stringify(sprite.name)} ` +
+            `(declared in ${group.base.file} and ${file}); ` +
+            `use \`partial sprite ${JSON.stringify(sprite.name)}\` to split it across files`,
+          errorInfo(sprite.loc),
+        );
+      } else {
+        group.base = { decl: sprite, file };
+      }
+    }
+  }
+
+  const sprites = [...groups.values()].map((group) => {
+    const base = group.base ? [group.base.decl] : [];
+    const fragments = group.fragments.map(({ decl }) => decl);
+    const [first] = base.length ? base : fragments;
+    return {
+      type: "SpriteDecl",
+      name: group.name,
+      body: [...base, ...fragments].flatMap((decl) => decl.body),
+      loc: first.loc,
+      open: first.open ?? null,
+      partial: false,
+      files: group.files,
+    };
+  });
+
+  return { type: "Program", stage, sprites, topItems };
+}

package/src/parser.js

@@ -127,18 +127,31 @@ class Parser {
   parseSprite(partial = false, startTok = null) {
     const tok = this.expect("sprite");
     const name = this.expectType("string", "a sprite name string").value;
-    const body = this.parseBlockBody();
-    return { type: "SpriteDecl", name, body, loc: startTok ?? tok, partial };
+    const { body, open } = this.parseBlockBody(true);
+    return {
+      type: "SpriteDecl",
+      name,
+      body,
+      loc: startTok ?? tok,
+      // Tokens are the brace's position, needed to insert declarations into
+      // the body when the brace is not on the declaration line.
+      open,
+      partial,
+    };
   }
 
   parseStage() {
     const tok = this.expect("stage");
-    const body = this.parseBlockBody();
-    return { type: "StageDecl", name: "Stage", body, loc: tok };
+    const { body, open } = this.parseBlockBody(true);
+    return { type: "StageDecl", name: "Stage", body, loc: tok, open };
   }
 
-  parseBlockBody() {
-    this.expect("{");
+  /**
+   * Parse `{ ... }`.
+   * @param {boolean} [withOpen] return `{body, open}` instead of the items only
+   */
+  parseBlockBody(withOpen = false) {
+    const open = this.expect("{");
     const items = [];
     while (!this.atPunct("}")) {
       if (this.peek().type === "eof")
@@ -146,7 +159,7 @@ class Parser {
       items.push(this.parseBodyItem());
     }
     this.expect("}");
-    return items;
+    return withOpen ? { body: items, open } : items;
   }
 
   parseBodyItem() {
@@ -161,6 +174,12 @@ class Parser {
             return this.parseVarDecl(true);
           }
           break;
+        case "thread":
+        case "runtime":
+          if (this.peek(1).type === "ident" && this.peek(1).value === "let") {
+            return this.parseTempVarDecl(tok.value);
+          }
+          break;
         case "list":
           if (this.peek(1).type === "ident") {
             return this.parseListDecl();
@@ -224,6 +243,16 @@ class Parser {
     return { type: "VarDecl", name, init, cloud, loc: tok };
   }
 
+  parseTempVarDecl(kind) {
+    const tok = this.next();
+    this.expect("let");
+    const name = this.expectIdent();
+    let init = null;
+    if (this.eat("=")) init = this.parseExpression();
+    this.expect(";");
+    return { type: "TempVarDecl", kind, name, init, loc: tok };
+  }
+
   parseListDecl() {
     const tok = this.expect("list");
     const name = this.expectIdent();
@@ -248,15 +277,16 @@ class Parser {
       const ptok = this.peek();
       const paramName = this.expectIdent();
       let boolean = false;
+      let type = null;
       // Optional type annotation: `flag: boolean`
       if (this.eat(":")) {
-        const typeName = this.expectIdent();
-        if (typeName === "boolean") boolean = true;
-        else if (typeName !== "number" && typeName !== "string") {
-          this.fail(`Unknown parameter type ${JSON.stringify(typeName)}`, ptok);
+        type = this.expectIdent();
+        if (type === "boolean") boolean = true;
+        else if (type !== "number" && type !== "string") {
+          this.fail(`Unknown parameter type ${JSON.stringify(type)}`, ptok);
         }
       }
-      params.push({ name: paramName, boolean });
+      params.push({ name: paramName, boolean, type });
       if (!this.eat(",")) break;
     }
     this.expect(")");
@@ -603,6 +633,16 @@ class Parser {
  * @param {string} [file]
  */
 export function parse(source, file = "<input>") {
-  const tokens = tokenize(source, file);
+  return parseTokens(tokenize(source, file), source, file);
+}
+
+/**
+ * Parse an existing token stream. Keeping the caller's tokens lets tools such
+ * as the formatter match AST locations back to tokens without re-lexing.
+ * @param {import('./lexer.js').Token[]} tokens
+ * @param {string} source
+ * @param {string} [file]
+ */
+export function parseTokens(tokens, source, file = "<input>") {
   return new Parser(tokens, source, file).parse();
 }

package/src/project.js

@@ -7,8 +7,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { ParseError } from "./errors.js";
 import { configFilename, sourceExtension } from "./brand.js";
+import { mergePrograms as mergeParsed } from "./merge.js";
 
 /** Directories never scanned for `.tfx` sources. */
 const IGNORED_DIRS = new Set([
@@ -58,99 +58,19 @@ export function discoverSources(dir) {
   return found.sort();
 }
 
-/** @param {object} loc */
-function errorInfo(loc) {
-  return {
-    file: loc && loc.file,
-    line: loc && loc.line,
-    column: loc && loc.column,
-  };
-}
-
 /**
  * Merge parsed programs into a single project AST.
  *
- * - At most one `stage { }` declaration is allowed across all files.
- * - Top-level statements from every file become stage content.
- * - At most one plain `sprite "Name" { }` declaration is allowed per name.
- *   Additional `partial sprite "Name" { }` fragments are appended to it.
- * - Partial sprites only merge when `partialSprites` is enabled.
- *
- * Bodies are composed base-first, then fragments in build order, so costume
- * order and local variable initializers stay predictable regardless of which
- * file happens to sort first.
+ * The merge itself is pure (see `merge.js`); this wrapper only injects the
+ * configured config filename so project-facing errors keep the right name.
  *
  * @param {Array<{ast: object, file: string}>} entries
  * @param {{partialSprites?: boolean}} [options]
  * @returns {object} a `Program` node
  */
-export function mergePrograms(entries, { partialSprites = false } = {}) {
-  let stage = null;
-  const topItems = [];
-  /** @type {Map<string, {name: string, loc: object, base: object|null, fragments: object[], files: string[]}>} */
-  const groups = new Map();
-
-  for (const { ast, file } of entries) {
-    if (ast.stage) {
-      if (stage) {
-        throw new ParseError(
-          "A project may only declare one stage",
-          errorInfo(ast.stage.loc),
-        );
-      }
-      stage = ast.stage;
-    }
-    topItems.push(...ast.topItems);
-    for (const sprite of ast.sprites) {
-      if (sprite.partial && !partialSprites) {
-        throw new ParseError(
-          `partial sprite ${JSON.stringify(sprite.name)} is disabled; ` +
-            `set "fx.partialSprites: true" in ${configFilename()} to enable it`,
-          errorInfo(sprite.loc),
-        );
-      }
-
-      let group = groups.get(sprite.name);
-      if (!group) {
-        group = {
-          name: sprite.name,
-          loc: sprite.loc,
-          base: null,
-          fragments: [],
-          files: [],
-        };
-        groups.set(sprite.name, group);
-      }
-      group.files.push(file);
-
-      if (sprite.partial) {
-        group.fragments.push({ decl: sprite, file });
-      } else if (group.base) {
-        throw new ParseError(
-          `Duplicate sprite ${JSON.stringify(sprite.name)} ` +
-            `(declared in ${group.base.file} and ${file}); ` +
-            `use \`partial sprite ${JSON.stringify(sprite.name)}\` to split it across files`,
-          errorInfo(sprite.loc),
-        );
-      } else {
-        group.base = { decl: sprite, file };
-      }
-    }
-  }
-
-  const sprites = [...groups.values()].map((group) => {
-    const base = group.base ? [group.base.decl] : [];
-    const fragments = group.fragments.map(({ decl }) => decl);
-    const [first] = base.length ? base : fragments;
-    return {
-      type: "SpriteDecl",
-      name: group.name,
-      body: [...base, ...fragments].flatMap((decl) => decl.body),
-      loc: first.loc,
-      partial: false,
-      files: group.files,
-    };
+export function mergePrograms(entries, options = {}) {
+  return mergeParsed(entries, {
+    ...options,
+    configName: configFilename(),
   });
-
-  return { type: "Program", stage, sprites, topItems };
 }