@triflare/fx 2.0.0 → 2.1.0-beta.2

package/src/merge.js

@@ -0,0 +1,116 @@
+/**
+ * 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.tests && ast.tests.length > 0)
+      throw new ParseError(
+        `Test ${JSON.stringify(ast.tests[0].name)} is declared in a project source. ` +
+          `Move test declarations to a test file (for example ` +
+          `test/score.test.tfx); ordinary builds never compile test files.`,
+        errorInfo(ast.tests[0].loc),
+      );
+    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

@@ -97,6 +97,7 @@ class Parser {
     const sprites = [];
     let stage = null;
     const topItems = [];
+    const tests = [];
 
     while (this.peek().type !== "eof") {
       if (
@@ -116,29 +117,68 @@ class Parser {
       ) {
         if (stage) this.fail("A project may only declare one stage");
         stage = this.parseStage();
+      } else if (
+        this.atIdent("test") &&
+        this.peek(1).type === "string" &&
+        this.peek(2).type === "punct" &&
+        this.peek(2).value === "{"
+      ) {
+        tests.push(this.parseTestDecl());
       } else {
         topItems.push(this.parseBodyItem());
       }
     }
 
-    return { type: "Program", stage, sprites, topItems };
+    return { type: "Program", stage, sprites, topItems, tests };
+  }
+
+  /** `test "name" { ... }` — only valid in test files. */
+  parseTestDecl() {
+    const tok = this.expect("test");
+    const name = this.expectType("string", "a test name string").value;
+    const body = this.parseBlockBody();
+    return { type: "TestDecl", name, body, loc: tok };
+  }
+
+  /** `expect <expression>[, "message"];` */
+  parseExpect() {
+    const tok = this.expect("expect");
+    const value = this.parseExpression();
+    let message = null;
+    if (this.eat(","))
+      message = this.expectType("string", "an assertion message string").value;
+    this.expect(";");
+    return { type: "Expect", value, message, loc: tok };
   }
 
   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 +186,7 @@ class Parser {
       items.push(this.parseBodyItem());
     }
     this.expect("}");
-    return items;
+    return withOpen ? { body: items, open } : items;
   }
 
   parseBodyItem() {
@@ -161,6 +201,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();
@@ -188,6 +234,18 @@ class Parser {
         }
         case "when":
           return this.parseHat();
+        case "expect":
+          // A complete call or assignment stays a normal statement. An
+          // expression continuing after the closing parenthesis is an assertion.
+          if (
+            !(
+              this.peek(1).type === "punct" &&
+              ASSIGN_OPS.has(this.peek(1).value)
+            ) &&
+            !this.isExpectCall()
+          )
+            return this.parseExpect();
+          break;
         case "if":
           return this.parseIf();
         case "repeat":
@@ -214,6 +272,22 @@ class Parser {
     return this.parseSimpleStatement();
   }
 
+  isExpectCall() {
+    if (this.peek(1).type !== "punct" || this.peek(1).value !== "(")
+      return false;
+    let depth = 0;
+    for (let offset = 1; this.peek(offset).type !== "eof"; offset++) {
+      const token = this.peek(offset);
+      if (token.type !== "punct") continue;
+      if (token.value === "(") depth++;
+      if (token.value === ")" && --depth === 0) {
+        const next = this.peek(offset + 1);
+        return next.type === "punct" && [";", "{"].includes(next.value);
+      }
+    }
+    return false;
+  }
+
   parseVarDecl(cloud) {
     const tok = cloud ? this.expect("cloud") : this.expect("let");
     if (cloud) this.expect("let");
@@ -224,6 +298,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 +332,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(")");
@@ -444,6 +529,26 @@ class Parser {
     return { name: segments.join("."), segments, loc: tok };
   }
 
+  /**
+   * Postfix member access on a call result, as in
+   * `state.list("items").length`. Qualified identifiers already absorb their
+   * segments while they are parsed.
+   */
+  parseMemberAccess(expression) {
+    let node = expression;
+    while (this.atPunct(".") && this.peek(1).type === "ident") {
+      this.next();
+      const property = this.next();
+      node = {
+        type: "Member",
+        object: node,
+        property: property.value,
+        loc: property,
+      };
+    }
+    return node;
+  }
+
   parseExpressionList(closing) {
     const list = [];
     if (this.atPunct(closing)) return list;
@@ -577,13 +682,13 @@ class Parser {
       if (this.eat("(")) {
         const args = this.parseExpressionList(")");
         this.expect(")");
-        return {
+        return this.parseMemberAccess({
           type: "Call",
           name: name.name,
           segments: name.segments,
           args,
           loc: tok,
-        };
+        });
       }
       return {
         type: "Identifier",
@@ -603,6 +708,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,9 @@
  */
 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";
+import { DEFAULT_TEST_PATTERN, matchesTestPattern } from "./test/discover.js";
 
 /** Directories never scanned for `.tfx` sources. */
 const IGNORED_DIRS = new Set([
@@ -21,12 +22,18 @@ const IGNORED_DIRS = new Set([
 
 /**
  * Recursively find every `.tfx` file under `dir`, skipping hidden entries and
- * well-known build/dependency directories. Results are deterministic (sorted by
- * path) so builds are reproducible.
+ * well-known build/dependency directories. Test files are skipped so they
+ * never become part of the project target.
+ *
+ * Results are deterministic (sorted by path) so builds are reproducible.
  * @param {string} dir
+ * @param {{testPattern?: string|null}} [options] `null` keeps test files
  * @returns {string[]} absolute file paths
  */
-export function discoverSources(dir) {
+export function discoverSources(
+  dir,
+  { testPattern = DEFAULT_TEST_PATTERN } = {},
+) {
   const root = path.resolve(dir);
   const found = [];
   const extension = sourceExtension().toLowerCase();
@@ -49,6 +56,10 @@ export function discoverSources(dir) {
         entry.isFile() &&
         entry.name.toLowerCase().endsWith(extension)
       ) {
+        if (testPattern) {
+          const relative = path.relative(root, full).split(path.sep).join("/");
+          if (matchesTestPattern(relative, testPattern)) continue;
+        }
         found.push(full);
       }
     }
@@ -58,99 +69,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 };
 }

package/src/test/discover.js

@@ -0,0 +1,82 @@
+/**
+ * Test-file discovery.
+ *
+ * Test files are ordinary `.tfx` sources that match a project glob. They are
+ * never part of the project target, so both `fx test` and the normal build
+ * path use the same matcher.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_TEST_PATTERN, matchesTestPattern } from "./pattern.js";
+
+export {
+  DEFAULT_TEST_PATTERN,
+  globToRegExp,
+  matchesTestPattern,
+} from "./pattern.js";
+
+const IGNORED_DIRS = new Set([
+  "node_modules",
+  "build",
+  "dist",
+  "coverage",
+  ".cache",
+]);
+
+/** Recursively collect test files below `current`, skipping ignored dirs. */
+function walk(root, current, found, pattern, extension) {
+  let entries;
+  try {
+    entries = fs.readdirSync(current, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const full = path.join(current, entry.name);
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRS.has(entry.name)) continue;
+      walk(root, full, found, pattern, extension);
+    } else if (entry.isFile() && entry.name.toLowerCase().endsWith(extension)) {
+      const relative = path.relative(root, full).split(path.sep).join("/");
+      if (matchesTestPattern(relative, pattern)) found.push(full);
+    }
+  }
+}
+
+/**
+ * Find every test file under a directory.
+ *
+ * @param {{dir: string, pattern?: string, extension?: string}} options
+ * @returns {Array<{file: string, relative: string}>} sorted by path
+ */
+export function discoverTests({
+  dir,
+  pattern = DEFAULT_TEST_PATTERN,
+  extension = ".tfx",
+} = {}) {
+  if (!dir) throw new Error("discoverTests needs a directory");
+  const root = path.resolve(dir);
+  const found = [];
+  walk(root, root, found, pattern, String(extension).toLowerCase());
+  found.sort();
+  return found.map((file) => ({
+    file,
+    relative: path.relative(root, file).split(path.sep).join("/"),
+  }));
+}
+
+/**
+ * Whether one explicit path is a test file for a project directory.
+ * @param {string} file
+ * @param {string} dir
+ * @param {string} [pattern]
+ */
+export function isTestFile(file, dir, pattern = DEFAULT_TEST_PATTERN) {
+  const relative = path
+    .relative(path.resolve(dir), path.resolve(file))
+    .split(path.sep)
+    .join("/");
+  return matchesTestPattern(relative, pattern);
+}

package/src/test/parse.js

@@ -0,0 +1,72 @@
+/**
+ * Test-file parsing.
+ *
+ * A test file is a normal `.tfx` source with `test` declarations. Project
+ * declarations (sprites, the stage, hats, project variables) are rejected:
+ * tests reuse the language, not the project structure.
+ */
+import { parse } from "../parser.js";
+import { ParseError } from "../errors.js";
+
+const ALLOWED_TOP_LEVEL = new Set(["VarDecl", "FunctionDecl"]);
+
+/**
+ * @param {string} source
+ * @param {string} file
+ * @returns {{file: string, tests: object[], helpers: object[]}}
+ */
+export function parseTestFile(source, file = "<test>") {
+  const ast = parse(source, file);
+
+  if (ast.stage)
+    throw new ParseError(
+      "Test files cannot declare a stage; tests run against the project build",
+      locationOf(ast.stage),
+    );
+  if (ast.sprites.length > 0)
+    throw new ParseError(
+      `Test files cannot declare sprites (found ${JSON.stringify(ast.sprites[0].name)})`,
+      locationOf(ast.sprites[0]),
+    );
+
+  for (const item of ast.topItems) {
+    if (!ALLOWED_TOP_LEVEL.has(item.type))
+      throw new ParseError(
+        "Test files may only declare tests, shared variables and shared functions",
+        locationOf(item),
+      );
+  }
+
+  return { file, tests: ast.tests, helpers: ast.topItems };
+}
+
+/** Source location of an AST node, defaulting unknown fields to null. */
+function locationOf(node) {
+  const loc = node?.loc ?? {};
+  return { file: loc.file, line: loc.line, column: loc.column };
+}
+
+/**
+ * Parse several test files. Errors are collected so a run can report every
+ * broken file before failing with the language-error exit code.
+ *
+ * @param {Array<{file: string, source: string}>} entries
+ * @returns {{files: Array<{file: string, tests: object[], helpers: object[]}>, diagnostics: object[]}}
+ */
+export function parseTests(entries) {
+  const files = [];
+  const diagnostics = [];
+  for (const entry of entries) {
+    try {
+      files.push(parseTestFile(entry.source, entry.file));
+    } catch (error) {
+      diagnostics.push({
+        file: entry.file,
+        message: error.message,
+        line: error.line ?? null,
+        column: error.column ?? null,
+      });
+    }
+  }
+  return { files, diagnostics };
+}