@triflare/fx 2.1.0-beta.1 → 2.1.0-beta.2

package/src/features.js

@@ -12,7 +12,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseConfig } from "./config.js";
-import { addFeatureEntry, removeFeatureEntry } from "./config-edit.js";
+import {
+  addFeatureEntry,
+  readFxValue,
+  removeFeatureEntry,
+  setFxScalar,
+} from "./config-edit.js";
 import { loadExtensions } from "./extensions.js";
 import { formatDiff } from "./vendor.js";
 
@@ -40,15 +45,29 @@ export const FEATURES = {
   },
 };
 
+/**
+ * Built-in language/compiler features. These have no extension source and no
+ * vendored copy: they live behind a single `fx.<name>` setting, so they are
+ * enabled and disabled without touching `features:`.
+ */
+export const CORE_FEATURES = {
+  tests: {
+    name: "tests",
+    title: "Testing",
+    summary: "Write project tests and run them with `fx test`.",
+    core: true,
+  },
+};
+
 /** List feature names for help and error messages. */
 export function featureNames() {
-  return Object.keys(FEATURES).sort();
+  return [...Object.keys(FEATURES), ...Object.keys(CORE_FEATURES)].sort();
 }
 
 /** Resolve one feature by name. */
 export function getFeature(name) {
   const key = String(name ?? "");
-  const feature = FEATURES[key];
+  const feature = FEATURES[key] ?? CORE_FEATURES[key];
   if (!feature)
     throw new FeatureError(
       `Unknown feature ${JSON.stringify(key)}. Available features: ${featureNames().join(", ")}.`,
@@ -158,6 +177,39 @@ function readFeatureEntries(configPath) {
  * @param {boolean} [options.force] replace a modified copy
  * @returns {{feature: object, name: string, file: string, path: string, changed: boolean, configChanged: boolean}}
  */
+/** True when a feature's setting is enabled in the project config. */
+function coreFeatureEnabled(configPath, feature) {
+  if (!configPath || !fs.existsSync(configPath)) return false;
+  return Boolean(readFxValue(configPath, feature.name));
+}
+
+/**
+ * Whether a feature is currently enabled in a project.
+ * @param {{configPath?: string, name: string}} options
+ */
+export function featureEnabled({ configPath, name } = {}) {
+  const feature = getFeature(name);
+  if (feature.core) return coreFeatureEnabled(configPath, feature);
+  if (!configPath || !fs.existsSync(configPath)) return false;
+  return Boolean(
+    readFeatureEntries(configPath).find((entry) => entry.name === feature.name),
+  );
+}
+
+/**
+ * Enable a feature in a project.
+ *
+ * Extension features copy their source into the project; core features only
+ * record `fx.<name>: true` in `fx.yml`.
+ *
+ * @param {object} options
+ * @param {string} options.configPath
+ * @param {string} options.configDir
+ * @param {string} options.name
+ * @param {string} [options.vendorDir]
+ * @param {boolean} [options.force] replace a modified copy
+ * @returns {{feature: object, name: string, file: string|null, path: string|null, changed: boolean, configChanged: boolean}}
+ */
 export function enableFeature({
   configPath,
   configDir,
@@ -166,6 +218,18 @@ export function enableFeature({
   force = false,
 } = {}) {
   const feature = getFeature(name);
+  if (feature.core) {
+    const changed = !coreFeatureEnabled(configPath, feature);
+    if (changed) setFxScalar(configPath, feature.name, true);
+    return {
+      feature,
+      name: feature.name,
+      file: null,
+      path: null,
+      changed,
+      configChanged: changed,
+    };
+  }
   const dir = assertInside(
     configDir,
     path.resolve(configDir, String(vendorDir || "extensions")),
@@ -212,6 +276,24 @@ export function enableFeature({
  */
 export function disableFeature({ configPath, configDir, name } = {}) {
   const feature = getFeature(name);
+  if (feature.core) {
+    if (!coreFeatureEnabled(configPath, feature))
+      return {
+        feature,
+        name: feature.name,
+        file: null,
+        changed: false,
+        warning: null,
+      };
+    setFxScalar(configPath, feature.name, false);
+    return {
+      feature,
+      name: feature.name,
+      file: null,
+      changed: true,
+      warning: `${feature.title} will become a core feature in a future version.`,
+    };
+  }
   const entry = readFeatureEntries(configPath).find(
     (candidate) => candidate.name === feature.name,
   );
@@ -259,6 +341,10 @@ export function updateFeature({
   dryRun = false,
 } = {}) {
   const feature = getFeature(name);
+  if (feature.core)
+    throw new FeatureError(
+      `${feature.title} is built into Fx, so there is no vendored source or lock entry to update.`,
+    );
   const entry = readFeatureEntries(configPath).find(
     (candidate) => candidate.name === feature.name,
   );

package/src/formatter.js

@@ -81,6 +81,10 @@ function renderExpression(node, minimum = 0, parentOperator) {
       return `${node.name}(${node.args
         .map((arg) => renderExpression(arg))
         .join(", ")})`;
+    case "Member":
+      // Member access binds tighter than every operator, so its object is
+      // rendered without parentheses, as in `state.list("items").length`.
+      return `${renderExpression(node.object)}.${node.property}`;
     case "ArrayLiteral":
       return `[${node.items.map((item) => renderExpression(item)).join(", ")}]`;
     case "Unary": {
@@ -131,6 +135,7 @@ function category(node) {
     case "FunctionDecl":
       return "function";
     case "HatDecl":
+    case "TestDecl":
       return "script";
     default:
       return "statement";
@@ -353,6 +358,17 @@ class Formatter {
         this.renderNodeBody(node, indent);
         this.out.push(`${pad}}`);
         return;
+      case "TestDecl":
+        this.out.push(`${pad}test ${stringLiteral(node.name)} {`);
+        this.renderNodeBody(node, indent);
+        this.out.push(`${pad}}`);
+        return;
+      case "Expect":
+        this.out.push(
+          `${pad}expect ${renderExpression(node.value)}` +
+            `${node.message ? `, ${stringLiteral(node.message)}` : ""};`,
+        );
+        return;
       case "If":
         this.renderIf(node, indent);
         return;
@@ -475,7 +491,11 @@ class Formatter {
   format() {
     const units = [];
     if (this.program.stage) units.push(this.program.stage);
-    units.push(...this.program.sprites, ...this.program.topItems);
+    units.push(
+      ...this.program.sprites,
+      ...this.program.topItems,
+      ...this.program.tests,
+    );
     // Preserve the order declarations had in this file; only separate them.
     units.sort((a, b) => this.tokenIndexOf(a.loc) - this.tokenIndexOf(b.loc));
     this.renderBody(units, 0, this.tokens.length - 1);

package/src/index.js

@@ -61,6 +61,27 @@ export {
   writeLock,
 } from "./vendor.js";
 export { formatDevUrls, injectDevClient, startDevServer } from "./dev.js";
+export {
+  DEFAULT_TEST_PATTERN,
+  discoverTests,
+  globToRegExp,
+  isTestFile,
+  matchesTestPattern,
+} from "./test/discover.js";
+export { parseTestFile, parseTests } from "./test/parse.js";
+export {
+  TEST_EXIT,
+  TestError,
+  formatFailure,
+  runTests,
+} from "./test/runner.js";
+export {
+  REPORTER_NAMES,
+  createTestReporter,
+  jsonReport,
+  junitReport,
+} from "./test/reporters.js";
+export { createVm, loadProject, loadVmModules } from "./vm.js";
 export * from "./catalog.js";
 export * from "./config.js";
 export { FxError, LexError, ParseError, CompileError } from "./errors.js";

package/src/lint/analyze.js

@@ -14,6 +14,7 @@ import { ParseError } from "../errors.js";
 import { tokenizeWithComments } from "../lexer.js";
 import { mergePrograms } from "../merge.js";
 import { parse } from "../parser.js";
+import { DEFAULT_TEST_PATTERN, isTestPath } from "../test/pattern.js";
 import { DEFAULT_LINT, resolveRuleSeverities } from "./config.js";
 import { RULES, ruleById } from "./rules.js";
 
@@ -1193,6 +1194,7 @@ export function sortDiagnostics(diagnostics) {
  *   configPath?: string|null,
  *   configDir?: string|null,
  *   rootDir?: string|null,
+ *   testPattern?: string|null,
  *   extensionCatalog?: Record<string, object>,
  *   declaredExtensions?: string[],
  *   lintConfig?: object,
@@ -1211,6 +1213,9 @@ export function lintSources({
   sources = [],
   config = null,
   configPath = null,
+  configDir = null,
+  rootDir = null,
+  testPattern = DEFAULT_TEST_PATTERN,
   extensionCatalog = {},
   declaredExtensions = [],
   lintConfig = DEFAULT_LINT,
@@ -1252,12 +1257,27 @@ export function lintSources({
     }
   }
 
+  // A source that declares tests, or whose path matches the configured
+  // test-file pattern, is a test file. Test files are never part of the
+  // project program — `mergePrograms` rejects them by design — so they are
+  // left out of the cross-file merge and the project rules. Editors lint every
+  // `.tfx` file in a project, test files included, and must not report the
+  // merge error on each test declaration. Pattern matching also keeps a
+  // helper-only test file (no `test` declarations) from leaking its top-level
+  // variables into project scope.
+  const testRoot = rootDir ?? configDir ?? null;
+  const projectParsed = parsed.filter(
+    ({ file, ast }) =>
+      (ast.tests ?? []).length === 0 &&
+      !isTestPath(file, testRoot, testPattern),
+  );
+
   // Partial sprites are resolved by the project merge, which throws when the
   // feature is off or a base declaration is missing. Report those first.
   const partialSprites = Boolean(config?.fx?.partialSprites);
   let partialBlocked = false;
   if (!partialSprites) {
-    for (const { ast } of parsed) {
+    for (const { ast } of projectParsed) {
       for (const sprite of ast.sprites) {
         if (!sprite.partial) continue;
         partialBlocked = true;
@@ -1271,7 +1291,7 @@ export function lintSources({
     }
   }
   const groups = new Map();
-  for (const { ast } of parsed) {
+  for (const { ast } of projectParsed) {
     for (const sprite of ast.sprites) {
       const group = groups.get(sprite.name) ?? { base: false, fragment: null };
       if (sprite.partial) group.fragment ??= sprite;
@@ -1290,10 +1310,10 @@ export function lintSources({
   }
 
   let program = null;
-  if (!partialBlocked) {
+  if (!partialBlocked && projectParsed.length > 0) {
     try {
       program = mergePrograms(
-        parsed.map(({ file, ast }) => ({ ast, file })),
+        projectParsed.map(({ file, ast }) => ({ ast, file })),
         { partialSprites },
       );
     } catch (error) {
@@ -1305,7 +1325,7 @@ export function lintSources({
     }
   }
   if (program) analyzer.analyzeProgram(program);
-  else for (const { ast } of parsed) analyzer.analyzeProgram(ast);
+  else for (const { ast } of projectParsed) analyzer.analyzeProgram(ast);
 
   // Diagnostics from filesystem-backed project checks (assets, fx.lock).
   for (const diagnostic of extraDiagnostics) {

package/src/lint/config-file.js

@@ -22,6 +22,7 @@ function extensionName(source) {
  *   config: {fx: {partialSprites: boolean}},
  *   lintConfig: object,
  *   declaredExtensions: string[],
+ *   testPattern: string|null,
  *   projectName: string|null,
  *   error?: string,
  * }}
@@ -35,6 +36,7 @@ export function parseProjectConfigText(text) {
       config: null,
       lintConfig: null,
       declaredExtensions: [],
+      testPattern: null,
       projectName: null,
       error: error instanceof Error ? error.message : String(error),
     };
@@ -44,6 +46,7 @@ export function parseProjectConfigText(text) {
       config: null,
       lintConfig: null,
       declaredExtensions: [],
+      testPattern: null,
       projectName: null,
       error: "fx.yml must contain a mapping at the top level",
     };
@@ -68,6 +71,7 @@ export function parseProjectConfigText(text) {
       config: null,
       lintConfig: null,
       declaredExtensions: [],
+      testPattern: null,
       projectName: typeof project.name === "string" ? project.name : null,
       error: error instanceof Error ? error.message : String(error),
     };
@@ -88,10 +92,20 @@ export function parseProjectConfigText(text) {
     }
   }
 
+  const testPattern =
+    fx.tests &&
+    typeof fx.tests === "object" &&
+    !Array.isArray(fx.tests) &&
+    typeof fx.tests.pattern === "string" &&
+    fx.tests.pattern.trim()
+      ? fx.tests.pattern.trim()
+      : null;
+
   return {
     config: { fx: { partialSprites: Boolean(fx.partialSprites) } },
     lintConfig,
     declaredExtensions: [...declaredExtensions],
+    testPattern,
     projectName: typeof project.name === "string" ? project.name : null,
   };
 }

package/src/merge.js

@@ -43,6 +43,13 @@ export function mergePrograms(
   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(

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,12 +117,38 @@ 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) {
@@ -207,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":
@@ -233,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");
@@ -474,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;
@@ -607,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",

package/src/project.js

@@ -9,6 +9,7 @@ import fs from "node:fs";
 import path from "node:path";
 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);
       }
     }

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 };
+}