@triflare/fx 2.0.0 → 2.1.0-beta.2

package/src/cli/commands/lint.js

@@ -0,0 +1,274 @@
+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,
+  normalizeLintConfig,
+  parseRuleOption,
+} from "../../lint/config.js";
+import { PRESET_NAMES, ruleById } from "../../lint/rules.js";
+import { loadProjectState, resolveInput } from "../context.js";
+import { outcome } from "../define-command.js";
+import { EXIT, UsageError } from "../errors.js";
+import { plural } from "../format.js";
+
+const EXTENSION = sourceExtension();
+
+/** Repeatable `--rule` values are collected into an array. */
+function collect(value, previous = []) {
+  return [...previous, value];
+}
+
+function displayPath(cwd, file) {
+  const relativePath = path.relative(cwd, file);
+  return relativePath.startsWith("..") || path.isAbsolute(relativePath)
+    ? file
+    : relativePath;
+}
+
+/**
+ * Resolve `--preset` and `--rule` on top of the project's `fx.lint` block.
+ * A bare `--rule FX201` enables the rule at its default severity; `off`
+ * disables it, and `error`/`warn` override the severity.
+ */
+function resolveOptions(options, loaded, product) {
+  const lintConfig = normalizeLintConfig(loaded.fx?.lint ?? {}, (message) => {
+    throw new UsageError(message, {
+      hint: "check the lint block in fx.yml",
+    });
+  });
+
+  if (options.preset != null) {
+    const preset = String(options.preset).trim().toLowerCase();
+    if (!PRESET_NAMES.includes(preset))
+      throw new UsageError(`unknown lint preset: ${options.preset}`, {
+        hint: `use one of: ${PRESET_NAMES.join(", ")}`,
+      });
+    lintConfig.extends = preset;
+  }
+
+  const overrides = {};
+  for (const raw of options.rule ?? []) {
+    const parsed = parseRuleOption(raw);
+    const preset = parsed.id.toLowerCase();
+    if (!parsed.severity && PRESET_NAMES.includes(preset)) {
+      lintConfig.extends = preset;
+      continue;
+    }
+    const rule = ruleById(parsed.id);
+    if (!rule)
+      throw new UsageError(`unknown lint rule: ${parsed.id}`, {
+        hint: `run "${product.command} lint --help" for rule selection`,
+      });
+    if (!parsed.severity) {
+      overrides[rule.id] = rule.severity;
+      continue;
+    }
+    if (!["error", "warning", "off"].includes(parsed.severity))
+      throw new UsageError(
+        `invalid severity for ${rule.id}: ${String(parsed.severity)}`,
+        { hint: "use error, warn or off" },
+      );
+    overrides[rule.id] = parsed.severity;
+  }
+
+  return { lintConfig, overrides };
+}
+
+/** Strip fix internals and display paths relative to the working directory. */
+function toJsonDiagnostic(diagnostic, cwd) {
+  return {
+    ruleId: diagnostic.ruleId,
+    severity: diagnostic.severity,
+    category: diagnostic.category,
+    message: diagnostic.message,
+    file: diagnostic.file ? displayPath(cwd, diagnostic.file) : null,
+    line: diagnostic.line,
+    column: diagnostic.column,
+    endLine: diagnostic.endLine,
+    endColumn: diagnostic.endColumn,
+    explanation: diagnostic.explanation,
+    fixable: diagnostic.fixable,
+  };
+}
+
+function reportDiagnostics(reporter, diagnostics, cwd) {
+  let current = null;
+  for (const diagnostic of diagnostics) {
+    const file = diagnostic.file
+      ? displayPath(cwd, diagnostic.file)
+      : "<input>";
+    if (file !== current) {
+      current = file;
+      reporter.text(reporter.bold(file));
+    }
+    const mark =
+      diagnostic.severity === "error"
+        ? "error"
+        : diagnostic.severity === "warning"
+          ? "warn "
+          : "info ";
+    reporter.text(
+      `  ${mark} ${diagnostic.line}:${diagnostic.column}  ${diagnostic.ruleId}  ${diagnostic.message}`,
+    );
+  }
+}
+
+export const lintCommand = {
+  name: "lint",
+  group: "Core Commands:",
+  summary: "Report source and project problems",
+  description: `Statically analyse a file, or every ${EXTENSION} file in a directory
+(defaults to the working directory), plus the merged project. Rules come from
+the "lint" block under "fx" in fx.yml; --preset and --rule override them.
+
+Exit status is 1 when errors are reported, or when warnings are reported with
+--strict. Linting never changes a file unless --fix is passed.`,
+  arguments: [`[input${EXTENSION}|dir]`],
+  options: [
+    { flags: "--fix", description: "Apply safe, explicit fixes" },
+    {
+      flags: "--strict",
+      description: "Use the strict preset and fail on warnings",
+    },
+    {
+      flags: "--preset <name>",
+      description: `Use a preset: ${PRESET_NAMES.join(", ")}`,
+    },
+    {
+      flags: "--rule <id[=severity]>",
+      description: "Enable, disable or set one rule (repeatable)",
+      parser: collect,
+      defaultValue: [],
+    },
+  ],
+  examples: [
+    "fx lint",
+    "fx lint src/main.tfx",
+    "fx lint --strict",
+    "fx lint --json",
+    "fx lint --rule FX201=off",
+    "fx lint --fix",
+  ],
+  async run({ args, cwd, options, reporter, product }) {
+    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}`);
+
+    const state = await loadProjectState({
+      input: args[0],
+      cwd,
+      options,
+      reporter,
+      includeExtensions: true,
+      migrateLegacy: false,
+    });
+    const { lintConfig, overrides } = resolveOptions(
+      options,
+      state.loaded,
+      product,
+    );
+    const preset = effectivePreset(lintConfig, Boolean(options.strict));
+
+    const lintOptions = {
+      config: state.loaded,
+      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),
+      overrides,
+    };
+
+    // Analyse the whole project so cross-file declarations resolve, but keep
+    // the selected files separate for reporting, counts and --fix writes.
+    // Diagnostics whose file is not a source (assets, fx.yml) stay visible.
+    const projectDir = state.configDir ?? target.dir;
+    const analysisFiles = discoverSources(projectDir);
+    for (const file of files)
+      if (!analysisFiles.includes(file)) analysisFiles.push(file);
+    const analysisSet = new Set(analysisFiles);
+    const selected = new Set(files);
+    const inScope = (diagnostic) =>
+      diagnostic.file == null ||
+      selected.has(diagnostic.file) ||
+      !analysisSet.has(diagnostic.file);
+
+    let sources = analysisFiles.map((file) => ({
+      file,
+      source: fs.readFileSync(file, "utf8"),
+    }));
+    let result = lintSources({ sources, ...lintOptions });
+    let diagnostics = result.diagnostics.filter(inScope);
+    let fixed = 0;
+
+    if (options.fix) {
+      const applied = applyFixes(sources, diagnostics);
+      fixed = applied.fixed;
+      if (fixed > 0) {
+        for (const file of applied.files)
+          fs.writeFileSync(file, applied.sources.get(file));
+        sources = sources.map(({ file, source }) => ({
+          file,
+          source: applied.sources.get(file) ?? source,
+        }));
+        result = lintSources({ sources, ...lintOptions });
+        diagnostics = result.diagnostics.filter(inScope);
+      }
+    }
+
+    const summary = {
+      errors: diagnostics.filter((entry) => entry.severity === "error").length,
+      warnings: diagnostics.filter((entry) => entry.severity === "warning")
+        .length,
+      suppressed: result.summary.suppressed,
+      files: files.length,
+    };
+
+    if (!reporter.json) {
+      reportDiagnostics(reporter, diagnostics, cwd);
+      if (fixed > 0) reporter.info(`Fixed ${plural(fixed, "problem")}.`);
+      const { errors, warnings } = summary;
+      if (errors > 0 || warnings > 0) {
+        const parts = [];
+        if (errors > 0) parts.push(plural(errors, "error"));
+        if (warnings > 0) parts.push(plural(warnings, "warning"));
+        reporter.error(
+          `${parts.join(", ")} in ${plural(files.length, "file")} (${preset} preset)`,
+        );
+      } else {
+        reporter.success(
+          `Linted ${plural(files.length, "file")}: no problems (${preset} preset)`,
+        );
+      }
+    }
+
+    const failsOnWarnings = Boolean(options.strict);
+    const exitCode =
+      summary.errors > 0 || (failsOnWarnings && summary.warnings > 0)
+        ? EXIT.FAILURE
+        : EXIT.OK;
+
+    return outcome({
+      exitCode,
+      data: {
+        preset,
+        strict: failsOnWarnings,
+        fixed,
+        files: files.map((file) => displayPath(cwd, file)),
+        summary,
+        diagnostics: diagnostics.map((diagnostic) =>
+          toJsonDiagnostic(diagnostic, cwd),
+        ),
+      },
+    });
+  },
+};

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

@@ -11,6 +11,7 @@ import path from "node:path";
 import { configFilename, outputDirectory, sourceExtension } from "../brand.js";
 import { loadConfigFrom, parseConfig } from "../config.js";
 import { loadExtensions } from "../extensions.js";
+import { loadFeatureExtensions } from "../features.js";
 import { loadVendorExtensions, migrateProjectExtensions } from "../vendor.js";
 import { UsageError } from "./errors.js";
 
@@ -25,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 };
@@ -49,6 +52,7 @@ export function loadProjectConfig({ cwd = process.cwd(), searchDir, options }) {
       fx: null,
       package: null,
       vendor: [],
+      features: [],
       vendorDir: "extensions",
       path: null,
     };
@@ -166,6 +170,17 @@ export async function loadProjectExtensions({ configDir, loaded, reporter }) {
     for (const warning of vendored.warnings) reporter.warn(warning);
   }
 
+  if (loaded?.features && loaded.features.length > 0) {
+    const featureExtensions = await loadFeatureExtensions({
+      configDir,
+      config: loaded,
+    });
+    Object.assign(catalog, featureExtensions.catalog);
+    Object.assign(extensionUrls, featureExtensions.extensionUrls);
+    unsandboxed.push(...featureExtensions.unsandboxed);
+    for (const warning of featureExtensions.warnings) reporter.warn(warning);
+  }
+
   if (config.extensions && config.extensions.length > 0) {
     warnLegacyExtensions(loaded, reporter);
     const legacy = await loadExtensions(config.extensions, {

package/src/cli/define-command.js

@@ -70,7 +70,14 @@ function configure(command, spec) {
   if (spec.group) command.helpGroup(spec.group);
   for (const argument of spec.arguments ?? []) command.argument(argument);
   for (const option of spec.options ?? []) {
-    if (option.defaultValue === undefined)
+    if (option.parser)
+      command.option(
+        option.flags,
+        option.description,
+        option.parser,
+        option.defaultValue,
+      );
+    else if (option.defaultValue === undefined)
       command.option(option.flags, option.description);
     else command.option(option.flags, option.description, option.defaultValue);
   }

package/src/cli/reporter.js

@@ -151,6 +151,15 @@ export function createReporter({
       stdout.write(`${message}\n`);
     },
 
+    /**
+     * Unmodified product output, such as formatted source. Quiet does not
+     * suppress it because it is the command's result; JSON mode does.
+     */
+    raw(text) {
+      if (json) return;
+      stdout.write(String(text));
+    },
+
     /** Quiet, de-emphasized line for incidental notes. */
     note(message) {
       if (!human) return;