@triflare/fx 2.0.0 → 2.1.0-beta.2

package/README.md

@@ -16,6 +16,7 @@ Code PenguinMod projects with text.
 - [Highlights](#highlights)
 - [Overview](#overview)
 - [Usage](#usage)
+- [Formatting](#formatting)
 - [Vendoring Extensions](#vendoring-extensions)
 - [Installation](#installation)
 - [Feedback and Contributing](#feedback-and-contributing)
@@ -54,8 +55,34 @@ $ fx build
   extensions: (none)
 ```
 
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:1f825081f9f722158035083df5b16f42120cc5fbd7d56eb25c770f3c64e339b2 -->
+
+## Formatting
+
+Run `fx fmt` to format every `.tfx` source in the current directory, or pass a file or directory:
+
+```bash
+fx fmt
+fx fmt src/main.tfx
+fx fmt src/ --check
+cat src/main.tfx | fx fmt --stdin
+fx fmt src/main.tfx --stdout
+fx fmt --check --json
+```
+
+- `--check` leaves files untouched and exits with status 1 if formatting is needed (0 if already formatted).
+- `--stdin` reads source from standard input and writes formatted source to standard output; it takes no file argument. With `--check`, it checks the input instead.
+- `--stdout` writes formatted source for a single file to standard output without changing the file. It cannot be combined with `--check`.
+- `--json` returns a structured result, including formatted code for `--stdin` and `--stdout` output.
+
+Formatting is idempotent: running it twice produces no further changes. It preserves comments, declaration order, and project data, normalizes whitespace and line endings, and does not compile the project. Files with parse errors are left untouched.
+
 ## Vendoring Extensions
 
+<!-- /coderabbit-ai-generated:v1 -->
+
 Extension URLs are mutable and can disappear, so Fx can commit a verified copy of every extension instead. Declare them under `vendor:` in `fx.yml`; order is load order:
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@triflare/fx",
-  "version": "2.0.0",
+  "version": "2.1.0-beta.2",
   "description": "Code PenguinMod projects with text.",
   "type": "module",
   "license": "Apache-2.0",
@@ -15,12 +15,14 @@
   "exports": {
     ".": "./src/index.js",
     "./catalog": "./src/catalog.js",
-    "./language": "./src/language.js"
+    "./language": "./src/language.js",
+    "./lint": "./src/lint/analyze.js"
   },
   "files": [
     "bin",
     "src",
     "vendor/pm-packager-dist",
+    "vendor/tempvars",
     "product.yml",
     "README.md"
   ],
@@ -48,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": {
@@ -55,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.0.0"
+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/catalog.js

@@ -610,6 +610,109 @@ const CORE_CATALOG = {
     kind: "boolean",
     fields: { VALUE: ["is penguinmod?", null] },
   },
+
+  // ------------------------------------------------- temporary variables
+  // The Fx fork of Temporary Variables (`fxTempVars`). Entries are marked
+  // `requiresExtension` so the compiler can refuse to emit blocks whose
+  // extension is not loaded, and so the linter can point at the feature.
+  "tempvars.setThread": {
+    opcode: "fxTempVars_setThreadVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: {
+      VAR: { type: "string", default: "variable" },
+      STRING: { type: "string", default: "0" },
+    },
+  },
+  "tempvars.changeThread": {
+    opcode: "fxTempVars_changeThreadVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: {
+      VAR: { type: "string", default: "variable" },
+      NUM: { type: "number", default: "1" },
+    },
+  },
+  "tempvars.thread": {
+    opcode: "fxTempVars_getThreadVariable",
+    kind: "reporter",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: { VAR: { type: "string", default: "variable" } },
+  },
+  "tempvars.threadExists": {
+    opcode: "fxTempVars_threadVariableExists",
+    kind: "boolean",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: { VAR: { type: "string", default: "variable" } },
+  },
+  "tempvars.forEachThread": {
+    opcode: "fxTempVars_forEachThreadVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: {
+      VAR: { type: "string", default: "thread variable" },
+      NUM: { type: "number", default: "10" },
+      SUBSTACK: SUBSTACK,
+    },
+  },
+  "tempvars.threads": {
+    opcode: "fxTempVars_listThreadVariables",
+    kind: "reporter",
+    extension: "fxTempVars",
+    requiresExtension: true,
+  },
+  "tempvars.setRuntime": {
+    opcode: "fxTempVars_setRuntimeVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: {
+      VAR: { type: "string", default: "variable" },
+      STRING: { type: "string", default: "0" },
+    },
+  },
+  "tempvars.changeRuntime": {
+    opcode: "fxTempVars_changeRuntimeVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: {
+      VAR: { type: "string", default: "variable" },
+      // Upstream declares NUM as a string input; keep it so block JSON matches.
+      NUM: { type: "string", default: "1" },
+    },
+  },
+  "tempvars.runtime": {
+    opcode: "fxTempVars_getRuntimeVariable",
+    kind: "reporter",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: { VAR: { type: "string", default: "variable" } },
+  },
+  "tempvars.runtimeExists": {
+    opcode: "fxTempVars_runtimeVariableExists",
+    kind: "boolean",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: { VAR: { type: "string", default: "variable" } },
+  },
+  "tempvars.deleteRuntime": {
+    opcode: "fxTempVars_deleteRuntimeVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: { VAR: { type: "string", default: "variable" } },
+  },
+  "tempvars.deleteAllRuntime": {
+    opcode: "fxTempVars_deleteAllRuntimeVariables",
+    extension: "fxTempVars",
+    requiresExtension: true,
+  },
+  "tempvars.runtimes": {
+    opcode: "fxTempVars_listRuntimeVariables",
+    kind: "reporter",
+    extension: "fxTempVars",
+    requiresExtension: true,
+  },
 };
 
 /**

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

@@ -0,0 +1,163 @@
+import path from "node:path";
+import {
+  disableFeature,
+  enableFeature,
+  featureEnabled,
+  getFeature,
+  updateFeature,
+} from "../../features.js";
+import { loadVendorConfig, requireConfigPath } from "./vendor/helpers.js";
+import { UsageError } from "../errors.js";
+
+const ACTIONS = ["enable", "disable", "update"];
+
+export const featureCommand = {
+  name: "feature",
+  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]"],
+  options: [
+    {
+      flags: "--force",
+      description: "Replace an installed copy that was edited (enable)",
+    },
+    { flags: "--dry-run", description: "Preview update without writing files" },
+  ],
+  examples: [
+    "fx feature temporaryvariables enable",
+    "fx feature temporaryvariables update --dry-run",
+    "fx feature temporaryvariables disable",
+  ],
+  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(", ")}` },
+      );
+
+    if (action === "enable") {
+      const loaded = loadVendorConfig(configPath);
+      const result = enableFeature({
+        configPath,
+        configDir,
+        name,
+        vendorDir: loaded.vendorDir,
+        force: Boolean(options.force),
+      });
+      if (result.changed)
+        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 {
+        feature: result.name,
+        action,
+        file: result.file,
+        changed: result.changed,
+      };
+    }
+
+    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,
+      });
+      const result = disableFeature({ configPath, configDir, name });
+      if (result.fileRemoved)
+        reporter.success(
+          `Disabled ${result.feature.title} (${result.file}) and deleted its copy`,
+        );
+      else
+        reporter.success(`Disabled ${result.feature.title} (${result.file})`);
+      if (result.filePreserved)
+        reporter.info(
+          `Kept ${result.file}: it is not the copy Fx installs, so it may be user-owned`,
+        );
+      return {
+        feature: result.name,
+        action,
+        file: result.file,
+        fileRemoved: result.fileRemoved,
+        filePreserved: result.filePreserved,
+      };
+    }
+
+    const result = updateFeature({
+      configPath,
+      configDir,
+      name,
+      dryRun: Boolean(options.dryRun),
+    });
+    if (!result.changed) {
+      reporter.info(`${result.feature.title} is already up to date`);
+      return {
+        feature: result.name,
+        action,
+        file: result.file,
+        changed: false,
+      };
+    }
+    reporter.text(result.diff);
+    if (result.dryRun)
+      reporter.info(`Dry run: ${result.file} would be replaced`);
+    else reporter.success(`Updated ${result.feature.title} (${result.file})`);
+    return {
+      feature: result.name,
+      action,
+      file: result.file,
+      changed: true,
+      dryRun: result.dryRun,
+    };
+  },
+};

package/src/cli/commands/fmt.js

@@ -0,0 +1,173 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { sourceExtension } from "../../brand.js";
+import { formatSource } from "../../formatter.js";
+import { discoverSources } from "../../project.js";
+import { resolveInput } from "../context.js";
+import { outcome } from "../define-command.js";
+import { EXIT, UsageError, errorToJson, formatError } from "../errors.js";
+import { plural } from "../format.js";
+
+const EXTENSION = sourceExtension();
+
+function displayPath(cwd, file) {
+  const relativePath = path.relative(cwd, file);
+  return relativePath.startsWith("..") || path.isAbsolute(relativePath)
+    ? file
+    : relativePath;
+}
+
+function readStdin() {
+  if (process.stdin.isTTY)
+    throw new UsageError("--stdin expects source on standard input", {
+      hint: "pipe a file into standard input, such as: cat src/main.tfx",
+    });
+  return fs.readFileSync(0, "utf8");
+}
+
+export const fmtCommand = {
+  name: "fmt",
+  aliases: ["format"],
+  group: "Core Commands:",
+  summary: "Format sources into canonical style",
+  description: `Rewrite a file, or every ${EXTENSION} file in a directory
+(defaults to the working directory), in the canonical source format.
+Formatting is idempotent, preserves comments and project data, and never
+compiles a project, so it cannot change generated behavior.`,
+  arguments: [`[input${EXTENSION}|dir]`],
+  options: [
+    {
+      flags: "--check",
+      description: "Do not write files; exit 1 if formatting is needed",
+    },
+    { flags: "--stdin", description: "Format source read from stdin" },
+    {
+      flags: "--stdout",
+      description: "Write formatted source to stdout instead of files",
+    },
+  ],
+  examples: [
+    "fx fmt",
+    "fx fmt src/main.tfx",
+    "fx fmt --check",
+    "fx fmt --stdin",
+    "fx fmt src/main.tfx --stdout",
+  ],
+  async run({ args, cwd, options, reporter, product }) {
+    if (options.stdin) {
+      // Commander fills a missing optional argument with null.
+      if (args[0] != null)
+        throw new UsageError("--stdin does not take a file argument", {
+          hint: `run "${product.command} fmt --stdin" with piped input`,
+        });
+      const source = readStdin();
+      const code = formatSource(source, "<stdin>");
+      const changed = code !== source;
+
+      if (options.check) {
+        if (changed) reporter.error("stdin is not formatted");
+        else reporter.success("stdin is formatted");
+        return outcome({
+          exitCode: changed ? EXIT.FAILURE : EXIT.OK,
+          data: { file: "<stdin>", changed, checked: true },
+        });
+      }
+
+      const data = { file: "<stdin>", changed, checked: false };
+      if (reporter.json) data.code = code;
+      else reporter.raw(code);
+      return outcome({ data });
+    }
+
+    const target = resolveInput(args[0], cwd);
+    const files = target.file ? [target.file] : discoverSources(target.dir);
+    if (files.length === 0)
+      throw new UsageError(`No ${EXTENSION} files found under ${target.dir}`);
+    if (options.stdout && options.check)
+      throw new UsageError("--stdout cannot be combined with --check");
+    if (options.stdout && !target.file)
+      throw new UsageError(
+        "--stdout requires a single file; pass one or use --stdin",
+      );
+
+    const results = [];
+    let changed = 0;
+    let parseErrors = 0;
+    let stdoutCode = null;
+
+    for (const file of files) {
+      const source = fs.readFileSync(file, "utf8");
+      let code;
+      try {
+        code = formatSource(source, file);
+      } catch (error) {
+        parseErrors += 1;
+        results.push({
+          file: displayPath(cwd, file),
+          status: "error",
+          changed: false,
+          error: errorToJson(error),
+        });
+        reporter.error(formatError(error));
+        continue;
+      }
+
+      const differs = code !== source;
+      if (differs) changed += 1;
+      results.push({
+        file: displayPath(cwd, file),
+        status: differs
+          ? options.check
+            ? "unformatted"
+            : "formatted"
+          : "unchanged",
+        changed: differs,
+      });
+
+      if (options.stdout) {
+        if (!options.check) {
+          stdoutCode = code;
+          reporter.raw(code);
+        }
+      } else if (differs && !options.check) {
+        fs.writeFileSync(file, code);
+        reporter.bullet(displayPath(cwd, file));
+      } else if (differs) {
+        reporter.bullet(displayPath(cwd, file));
+      }
+    }
+
+    const data = {
+      checked: Boolean(options.check),
+      files: results,
+      changed,
+      unchanged: results.length - changed - parseErrors,
+      parseErrors,
+    };
+    if (options.stdout && reporter.json) data.code = stdoutCode;
+
+    if (!options.stdout) {
+      if (options.check) {
+        if (changed > 0)
+          reporter.error(`${plural(changed, "file")} would be reformatted`);
+        else if (parseErrors === 0)
+          reporter.success(
+            `Checked ${plural(files.length, "file")}: all formatted`,
+          );
+      } else if (changed > 0) {
+        reporter.success(`Formatted ${plural(changed, "file")}`);
+      } else if (parseErrors === 0) {
+        reporter.success(
+          `All ${plural(files.length, "file")} already formatted`,
+        );
+      }
+    }
+
+    const exitCode =
+      parseErrors > 0 || (options.check && changed > 0)
+        ? EXIT.FAILURE
+        : EXIT.OK;
+    return outcome({ exitCode, data });
+  },
+};

package/src/cli/commands/index.js

@@ -5,9 +5,13 @@ import { checkCommand } from "./check.js";
 import { decompileCommand } from "./decompile.js";
 import { devCommand } from "./dev.js";
 import { registerExtension } from "./extension.js";
+import { featureCommand } from "./feature.js";
+import { fmtCommand } from "./fmt.js";
 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";
 
@@ -17,7 +21,11 @@ const TOP_LEVEL = [
   packageCommand,
   decompileCommand,
   checkCommand,
+  lintCommand,
+  fmtCommand,
   catalogCommand,
+  featureCommand,
+  testCommand,
   initCommand,
   completionCommand,
 ];