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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@triflare/fx",
-  "version": "2.1.0-beta.1",
+  "version": "2.1.0-beta.2",
   "description": "Code PenguinMod projects with text.",
   "type": "module",
   "license": "Apache-2.0",
@@ -50,6 +50,7 @@
     "js-yaml": "^5.4.3",
     "jszip": "^3.10.1",
     "quickjs-emscripten": "^0.32.0",
+    "scratch-vm": "github:PenguinMod/PenguinMod-Vm#75ef6994e55270b9c2a2f3cb2edf6a5bf31cdf2a",
     "sha.js": "^2.4.12"
   },
   "devDependencies": {
@@ -57,8 +58,7 @@
     "eslint": "^10.14.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.13.0",
-    "prettier": "^3.9.10",
-    "scratch-vm": "github:PenguinMod/PenguinMod-Vm#75ef6994e55270b9c2a2f3cb2edf6a5bf31cdf2a"
+    "prettier": "^3.9.10"
   },
   "overrides": {
     "minimatch": "^11.0.4",

package/product.yml

@@ -1,7 +1,7 @@
 # Identity
 name: "Triflare Fx"
 command: "fx"
-version: "2.1.0-beta.1"
+version: "2.1.0-beta.2"
 tagline: "Code PenguinMod projects with text."
 author: "Triflare"
 homepage: "https://github.com/triflare/fx"

package/src/build.js

@@ -9,6 +9,7 @@ import { Compiler } from "./compiler.js";
 import { zipSync } from "./sb3.js";
 import { loadConfigFrom, DEFAULT_PROJECT, DEFAULT_FX } from "./config.js";
 import { sourceExtension } from "./brand.js";
+import { DEFAULT_TEST_PATTERN } from "./test/discover.js";
 
 /**
  * @typedef {object} BuildOptions
@@ -30,7 +31,7 @@ import { sourceExtension } from "./brand.js";
  * @param {BuildOptions} options
  * @returns {{dir: string, entries: Array<{file: string, source: string}>}}
  */
-function resolveSources(options) {
+function resolveSources(options, { testPattern = DEFAULT_TEST_PATTERN } = {}) {
   const cwd = process.cwd();
 
   if (Array.isArray(options.sources)) {
@@ -84,7 +85,7 @@ function resolveSources(options) {
   }
 
   const dir = path.resolve(options.dir || cwd);
-  const files = discoverSources(dir);
+  const files = discoverSources(dir, { testPattern });
   if (files.length === 0)
     throw new Error(`No ${sourceExtension()} files found under ${dir}`);
   return {
@@ -101,15 +102,23 @@ function resolveSources(options) {
  * @returns {{project: object, assets: Map<string, Buffer>, sb3: Buffer, config: object, fx: object, ast: object, files: string[], warnings: string[]}}
  */
 export function build(options = {}) {
-  const { dir, entries } = resolveSources(options);
-  if (entries.length === 0)
-    throw new Error("No Triflare Fx sources to compile");
+  // Load the config before scanning, so a project's test glob decides which
+  // files are test files (and therefore excluded from the build).
+  const searchDir =
+    options.configDir ||
+    (options.dir
+      ? path.resolve(options.dir)
+      : options.file
+        ? path.dirname(path.resolve(options.file))
+        : Array.isArray(options.files) && options.files.length > 0
+          ? path.dirname(path.resolve(options.files[0]))
+          : process.cwd());
 
   let projectConfig = options.projectConfig || null;
   let fxConfig = options.fxConfig || null;
   let configPath = null;
   if (!projectConfig && options.useConfigFile !== false) {
-    const loaded = loadConfigFrom(options.configDir || dir);
+    const loaded = loadConfigFrom(searchDir);
     projectConfig = loaded.project;
     fxConfig = loaded.fx;
     configPath = loaded.path;
@@ -117,6 +126,14 @@ export function build(options = {}) {
   if (!projectConfig) projectConfig = { ...DEFAULT_PROJECT };
   if (!fxConfig) fxConfig = { ...DEFAULT_FX };
 
+  const { dir, entries } = resolveSources(options, {
+    testPattern:
+      options.testPattern ??
+      (fxConfig.tests ? fxConfig.tests.pattern : DEFAULT_TEST_PATTERN),
+  });
+  if (entries.length === 0)
+    throw new Error("No Triflare Fx sources to compile");
+
   const asts = entries.map(({ file, source }) => ({
     ast: parse(source, file),
     file,

package/src/cli/commands/check.js

@@ -26,7 +26,9 @@ building an archive.`,
       migrateLegacy: false,
     });
     const { target, loaded } = state;
-    const files = target.file ? [target.file] : discoverSources(target.dir);
+    const files = target.file
+      ? [target.file]
+      : discoverSources(target.dir, { testPattern: loaded.fx?.tests?.pattern });
     if (files.length === 0)
       throw new UsageError(`No ${EXTENSION} files found under ${target.dir}`);
 

package/src/cli/commands/feature.js

@@ -2,6 +2,8 @@ import path from "node:path";
 import {
   disableFeature,
   enableFeature,
+  featureEnabled,
+  getFeature,
   updateFeature,
 } from "../../features.js";
 import { loadVendorConfig, requireConfigPath } from "./vendor/helpers.js";
@@ -14,7 +16,7 @@ export const featureCommand = {
   group: "Core Commands:",
   summary: "Install, update or remove a built-in language feature",
   description: `Features are extension-backed language additions. "enable" copies the\nfeature's file into the project and records it under "features:" in fx.yml;\n"update" replaces that copy with the one bundled in this Fx version; and\n"disable" removes both. The file is committed, so Fx upgrades never change it.`,
-  arguments: ["<name>", "<action>"],
+  arguments: ["<name>", "[action]"],
   options: [
     {
       flags: "--force",
@@ -29,14 +31,37 @@ export const featureCommand = {
   ],
   async run({ args, options, cwd, reporter, prompts, yes, product }) {
     const [name, action] = args;
+    const configPath = requireConfigPath(cwd, product);
+    const configDir = path.dirname(configPath);
+    const feature = getFeature(name);
+
+    if (action == null) {
+      if (!feature.core)
+        throw new UsageError(`Missing an action for ${JSON.stringify(name)}.`, {
+          hint: `use one of: ${ACTIONS.join(", ")}`,
+        });
+      const enabled = featureEnabled({ configPath, name: feature.name });
+      reporter.detail("Feature", feature.title);
+      reporter.detail("Status", enabled ? "enabled" : "disabled");
+      reporter.detail("Setting", `fx.${feature.name}`);
+      reporter.info(
+        enabled
+          ? `Run "fx test" to run the project's tests.`
+          : `Run "fx feature ${feature.name} enable" to enable it.`,
+      );
+      return {
+        feature: feature.name,
+        action: "status",
+        enabled,
+      };
+    }
+
     if (!ACTIONS.includes(action))
       throw new UsageError(
         `Unknown feature action ${JSON.stringify(action)} for ${JSON.stringify(name)}.`,
         { hint: `use one of: ${ACTIONS.join(", ")}` },
       );
 
-    const configPath = requireConfigPath(cwd, product);
-    const configDir = path.dirname(configPath);
     if (action === "enable") {
       const loaded = loadVendorConfig(configPath);
       const result = enableFeature({
@@ -47,8 +72,12 @@ export const featureCommand = {
         force: Boolean(options.force),
       });
       if (result.changed)
-        reporter.success(`${result.feature.title} enabled (${result.file})`);
-      else reporter.info(`${result.feature.title} is already installed`);
+        reporter.success(
+          result.file
+            ? `${result.feature.title} enabled (${result.file})`
+            : `${result.feature.title} enabled`,
+        );
+      else reporter.info(`${result.feature.title} is already enabled`);
       if (result.configChanged)
         reporter.info(`Recorded the feature in ${path.basename(configPath)}`);
       return {
@@ -60,6 +89,26 @@ export const featureCommand = {
     }
 
     if (action === "disable") {
+      if (feature.core) {
+        const result = disableFeature({ configPath, configDir, name });
+        if (!result.changed) {
+          reporter.info(`${result.feature.title} is already disabled`);
+          return {
+            feature: result.name,
+            action,
+            changed: false,
+            warning: null,
+          };
+        }
+        reporter.success(`Disabled ${result.feature.title}`);
+        if (result.warning) reporter.warn(result.warning);
+        return {
+          feature: result.name,
+          action,
+          changed: true,
+          warning: result.warning,
+        };
+      }
       await prompts.confirmDestructive({
         message: `Disable ${name} and delete its installed file?`,
         yes,

package/src/cli/commands/index.js

@@ -11,6 +11,7 @@ import { initCommand } from "./init.js";
 import { lintCommand } from "./lint.js";
 import { packageCommand } from "./package.js";
 import { registerSprite } from "./sprite/index.js";
+import { testCommand } from "./test.js";
 import { registerVendor } from "./vendor/index.js";
 import { defineCommand } from "../define-command.js";
 
@@ -24,6 +25,7 @@ const TOP_LEVEL = [
   fmtCommand,
   catalogCommand,
   featureCommand,
+  testCommand,
   initCommand,
   completionCommand,
 ];

package/src/cli/commands/lint.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { sourceExtension } from "../../brand.js";
 import { discoverSources } from "../../project.js";
+import { DEFAULT_TEST_PATTERN } from "../../test/discover.js";
 import { applyFixes, lintSources } from "../../linter.js";
 import {
   effectivePreset,
@@ -178,6 +179,9 @@ Exit status is 1 when errors are reported, or when warnings are reported with
       configPath: state.loaded.path,
       configDir: state.configDir,
       rootDir: state.configDir ?? cwd,
+      testPattern: state.loaded.fx?.tests
+        ? state.loaded.fx.tests.pattern
+        : DEFAULT_TEST_PATTERN,
       extensionCatalog: state.catalog,
       lintConfig,
       strict: Boolean(options.strict),

package/src/cli/commands/test.js

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import { loadProjectState } from "../context.js";
+import { CliError } from "../errors.js";
+import { outcome } from "../define-command.js";
+import { createTestReporter, REPORTER_NAMES } from "../../test/reporters.js";
+import { runTests, TestError, TEST_EXIT } from "../../test/runner.js";
+
+const WATCH_IGNORED = /(^|\/)(node_modules|build|dist|\.git|doc_build)(\/|$)/;
+
+/** Resolve a `--reporter` value, mapping the global `--json` flag onto it. */
+function reporterName(options) {
+  const name = String(options.reporter ?? "default");
+  if (options.json && name === "default") return "json";
+  if (!REPORTER_NAMES.includes(name))
+    throw new CliError(`Unknown reporter ${JSON.stringify(name)}.`, {
+      code: "TEST_USAGE",
+      exitCode: TEST_EXIT.USAGE,
+      hint: `use one of: ${REPORTER_NAMES.join(", ")}`,
+    });
+  return name;
+}
+
+/** Parse a positive numeric option, reporting usage errors with its label. */
+function validateNumber(value, label) {
+  if (value === undefined) return undefined;
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0)
+    throw new CliError(`${label} must be a positive number`, {
+      code: "TEST_USAGE",
+      exitCode: TEST_EXIT.USAGE,
+    });
+  return number;
+}
+
+/** Wait for the next source or config change. */
+function nextChange(dir, signal) {
+  return new Promise((resolve, reject) => {
+    let watcher;
+    let timer = null;
+    const done = () => {
+      if (timer) clearTimeout(timer);
+      watcher?.close();
+      signal.removeEventListener("abort", done);
+      resolve();
+    };
+    if (signal.aborted) return done();
+    signal.addEventListener("abort", done, { once: true });
+    try {
+      watcher = fs.watch(dir, { recursive: true }, (event, filename) => {
+        if (!filename) return;
+        const name = String(filename).split("\\").join("/");
+        if (WATCH_IGNORED.test(name)) return;
+        if (!/\.(tfx|ya?ml)$/i.test(name)) return;
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(done, 80);
+      });
+    } catch (error) {
+      signal.removeEventListener("abort", done);
+      reject(error);
+    }
+  });
+}
+
+export const testCommand = {
+  name: "test",
+  group: "Core Commands:",
+  summary: "Run project tests in a headless PenguinMod VM",
+  description: `Discover test files (test/**/*.test.tfx by default), build the project
+once, and run every test in a fresh VM. Testing is a language feature: enable
+it with "fx feature tests enable".`,
+  arguments: ["[files...]"],
+  options: [
+    {
+      flags: "-t, --filter <text>",
+      description: "Only run tests whose name or file contains <text>",
+    },
+    { flags: "-w, --watch", description: "Re-run when sources change" },
+    { flags: "--run", description: "Run once and exit (the default)" },
+    {
+      flags: "--reporter <name>",
+      description: `Output format: ${REPORTER_NAMES.join(", ")}`,
+      defaultValue: "default",
+    },
+    { flags: "--seed <number>", description: "Seed the random generator" },
+    {
+      flags: "--timeout <ms>",
+      description: "Per-test timeout in milliseconds",
+    },
+    {
+      flags: "--allow-project-extensions",
+      description: "Trust and load this project's extensions for this run",
+    },
+    {
+      flags: "--allow-external-io",
+      description: "Allow network access (fetch and WebSocket) during tests",
+    },
+  ],
+  examples: [
+    "fx test",
+    "fx test test/score.test.tfx",
+    "fx test --filter score --reporter verbose",
+    "fx test --reporter junit",
+    "fx test --allow-project-extensions",
+  ],
+  jsonEvents: true,
+  async run({ args, options, cwd, reporter, prompts }) {
+    // Commander hands a variadic argument back as one array.
+    const files = (Array.isArray(args[0]) ? args[0] : args).filter(Boolean);
+    const name = reporterName(options);
+    const color =
+      options.color === "always" ||
+      (options.color !== "never" &&
+        options.color !== false &&
+        Boolean(process.stdout.isTTY) &&
+        !process.env.NO_COLOR);
+    const testReporter = createTestReporter({
+      name,
+      stream: process.stdout,
+      color,
+      tty: Boolean(process.stdout.isTTY),
+      dir: cwd,
+    });
+
+    const runOnce = async () => {
+      const state = await loadProjectState({
+        input: undefined,
+        cwd,
+        options,
+        reporter,
+        prompts,
+      });
+      return runTests({
+        dir: state.configDir,
+        files,
+        cwd,
+        filter: options.filter ?? "",
+        loaded: state.loaded,
+        catalog: state.catalog,
+        extensionUrls: state.extensionUrls,
+        seed: validateNumber(options.seed, "--seed"),
+        timeout: validateNumber(options.timeout, "--timeout"),
+        allowProjectExtensions: Boolean(options.allowProjectExtensions),
+        allowExternalIO: Boolean(options.allowExternalIO),
+        onEvent: testReporter.onEvent,
+      });
+    };
+
+    if (!options.watch) {
+      try {
+        const result = await runOnce();
+        return outcome({ data: result, exitCode: result.exitCode });
+      } catch (error) {
+        if (error instanceof TestError)
+          throw new CliError(error.message, {
+            code: "TEST_ERROR",
+            exitCode: error.exitCode,
+            hint: error.hint,
+            cause: error,
+          });
+        throw error;
+      }
+    }
+
+    const controller = new AbortController();
+    let interrupted = false;
+    const onInterrupt = () => {
+      interrupted = true;
+      controller.abort();
+    };
+    process.once("SIGINT", onInterrupt);
+    try {
+      for (;;) {
+        const result = await runOnce();
+        if (interrupted)
+          return outcome({ data: result, exitCode: TEST_EXIT.INTERRUPTED });
+        reporter.info("Watching for changes... (Ctrl+C to stop)");
+        await nextChange(result.dir, controller.signal);
+        if (interrupted)
+          return outcome({ data: result, exitCode: TEST_EXIT.INTERRUPTED });
+      }
+    } finally {
+      controller.abort();
+      process.off("SIGINT", onInterrupt);
+    }
+  },
+};

package/src/cli/context.js

@@ -26,8 +26,10 @@ export function resolveInput(input, cwd = process.cwd()) {
   try {
     stat = fs.statSync(resolved);
   } catch {
+    // Name the absolute path that was checked: relative inputs are resolved
+    // from the working directory, not from the project root.
     throw new UsageError(`input not found: ${input}`, {
-      hint: `check the path, or run from the project directory`,
+      hint: `looked for ${resolved}; check the path, or run from the project directory`,
     });
   }
   return stat.isDirectory() ? { dir: resolved } : { file: resolved };

package/src/config-edit.js

@@ -673,6 +673,84 @@ export function addFeatureEntry(configPath, name, file) {
   return { added, updated };
 }
 
+/** Read a raw `fx.<key>` value without normalising the rest of the config. */
+export function readFxValue(configPath, key) {
+  const raw = yaml.load(fs.readFileSync(configPath, "utf8")) ?? {};
+  if (typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const fx = raw.fx;
+  if (!fx || typeof fx !== "object" || Array.isArray(fx)) return undefined;
+  return fx[key];
+}
+
+/**
+ * Set a scalar `fx.<key>` value while preserving the rest of the file.
+ *
+ * A nested block under the key (for example a hand-written `fx.tests:`
+ * mapping) is replaced by the scalar, so enabling and disabling a feature
+ * always leaves one canonical value behind.
+ *
+ * @param {string} configPath
+ * @param {string} key
+ * @param {string|number|boolean} value
+ * @returns {{changed: boolean}}
+ */
+export function setFxScalar(configPath, key, value) {
+  const text = fs.readFileSync(configPath, "utf8");
+  const lines = splitLines(text);
+  const eol = eolOf(text);
+  const scalar = typeof value === "string" ? quote(value) : String(value);
+  const fx = topLevel(lines, "fx");
+
+  if (!fx) {
+    if (lines.length > 0 && !lines[lines.length - 1].endsWith("\n"))
+      lines[lines.length - 1] += eol;
+    lines.push(`fx:${eol}`, `  ${key}: ${scalar}${eol}`);
+    writeDocument(configPath, lines.join(""));
+    return { changed: true };
+  }
+
+  const { value: rest, comment } = splitComment(fx.rest);
+  if (rest !== "") {
+    if (!rest.startsWith("{") || !rest.endsWith("}"))
+      throw new Error("fx must be a block mapping to edit it");
+    const mapping = parseValue(rest);
+    if (!mapping || typeof mapping !== "object" || Array.isArray(mapping))
+      throw new Error("fx must be a mapping to edit it");
+    if (mapping[key] === value) return { changed: false };
+    mapping[key] = value;
+    const dumped = yaml
+      .dump({ fx: mapping }, { lineWidth: -1, noRefs: true })
+      .split("\n")
+      .filter((line, index, all) => !(index === all.length - 1 && line === ""))
+      .map((line) => `${line}${eol}`);
+    if (comment) dumped[0] = `fx: ${comment}${eol}`;
+    replaceRange(lines, fx.index, fx.index + 1, dumped);
+    writeDocument(configPath, lines.join(""));
+    return { changed: true };
+  }
+
+  const end = sectionEnd(lines, fx.index);
+  const existing = mappingEntrySpans(lines, fx.index, end).find(
+    (span) => span.key === key,
+  );
+  if (existing) {
+    let entryEnd = existing.end;
+    while (
+      entryEnd > existing.index + 1 &&
+      /^(?:[ \t]*#.*|[ \t]*)$/.test(content(lines[entryEnd - 1]))
+    )
+      entryEnd--;
+    replaceRange(lines, existing.index, entryEnd, [
+      `${existing.indent}${quoteKey(key)}: ${scalar}${eol}`,
+    ]);
+  } else {
+    const indent = childIndent(lines, fx.index, end);
+    insertAt(lines, end, [`${indent}${quoteKey(key)}: ${scalar}${eol}`], eol);
+  }
+  writeDocument(configPath, lines.join(""));
+  return { changed: true };
+}
+
 /**
  * Remove a `features:` entry.
  * @param {string} configPath

package/src/config.js

@@ -26,6 +26,19 @@ export const DEFAULT_PROJECT = {
   unsandboxed: [],
 };
 
+/**
+ * Deterministic defaults for `fx test`. Virtual time is derived from
+ * `ticksPerSecond`; `seed` seeds the pseudo-random generator for the run.
+ */
+export const DEFAULT_TESTS = {
+  pattern: "test/**/*.test.tfx",
+  seed: 12345,
+  timeout: 1000,
+  ticksPerSecond: 30,
+  failOnRuntimeError: true,
+  parallel: false,
+};
+
 /**
  * Fx-only settings that never reach PenguinMod's project runtime config.
  * Kept in a separate top-level `fx:` block in fx.yml.
@@ -33,9 +46,72 @@ export const DEFAULT_PROJECT = {
 export const DEFAULT_FX = {
   partialSprites: false,
   vendorDir: "extensions",
+  tests: false,
   lint: { ...DEFAULT_LINT, rules: { ...DEFAULT_LINT.rules } },
 };
 
+/**
+ * Normalize the `fx.tests` setting.
+ *
+ * `true` enables testing with the defaults, `false` (or an absent key)
+ * disables it, and a mapping may override any default. The mapping form is
+ * what `fx feature tests enable` writes and later edits by hand.
+ *
+ * @param {unknown} value
+ * @returns {false | (typeof DEFAULT_TESTS & {enabled: true})}
+ */
+export function normalizeTestConfig(value) {
+  if (value == null || value === false) return false;
+  if (value === true) return { enabled: true, ...DEFAULT_TESTS };
+  if (!isPlainObject(value))
+    throw new Error(
+      `${configFilename()}: fx.tests must be true, false, or a mapping`,
+    );
+
+  const unknown = Object.keys(value).filter(
+    (key) => !Object.hasOwn(DEFAULT_TESTS, key),
+  );
+  if (unknown.length)
+    throw new Error(
+      `${configFilename()}: unknown fx.tests setting(s): ${unknown
+        .map((key) => `"${key}"`)
+        .join(", ")}`,
+    );
+
+  const tests = { enabled: true, ...DEFAULT_TESTS };
+  if (value.pattern != null) {
+    if (typeof value.pattern !== "string" || value.pattern.trim() === "")
+      throw new Error(`${configFilename()}: fx.tests.pattern must be a glob`);
+    tests.pattern = value.pattern.trim();
+  }
+  if (value.seed != null) {
+    const seed = Number(value.seed);
+    if (!Number.isFinite(seed))
+      throw new Error(`${configFilename()}: fx.tests.seed must be a number`);
+    tests.seed = seed;
+  }
+  if (value.timeout != null) {
+    const timeout = Number(value.timeout);
+    if (!Number.isFinite(timeout) || timeout <= 0)
+      throw new Error(
+        `${configFilename()}: fx.tests.timeout must be a positive number of milliseconds`,
+      );
+    tests.timeout = timeout;
+  }
+  if (value.ticksPerSecond != null) {
+    const ticks = Number(value.ticksPerSecond);
+    if (!Number.isFinite(ticks) || ticks <= 0)
+      throw new Error(
+        `${configFilename()}: fx.tests.ticksPerSecond must be positive`,
+      );
+    tests.ticksPerSecond = ticks;
+  }
+  if (value.failOnRuntimeError != null)
+    tests.failOnRuntimeError = Boolean(value.failOnRuntimeError);
+  if (value.parallel != null) tests.parallel = Boolean(value.parallel);
+  return tests;
+}
+
 /** Default directory that receives vendored extension sources. */
 export const DEFAULT_VENDOR_DIR = "extensions";
 
@@ -418,6 +494,7 @@ export function normalizeFx(raw = {}) {
         throw new Error(`${configFilename()}: fx.vendorDir must be a path`);
       fx.vendorDir = raw.vendorDir.trim();
     }
+    if (raw.tests !== undefined) fx.tests = normalizeTestConfig(raw.tests);
     fx.lint = normalizeLintConfig(
       raw.lint,
       (message) => new Error(`${configFilename()}: ${message}`),