@triflare/fx 1.0.3 → 2.1.0-beta.1

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

@@ -0,0 +1,45 @@
+import { completeCommand, completionCommand } from "./completion.js";
+import { buildCommand } from "./build.js";
+import { catalogCommand } from "./catalog.js";
+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 { registerVendor } from "./vendor/index.js";
+import { defineCommand } from "../define-command.js";
+
+const TOP_LEVEL = [
+  buildCommand,
+  devCommand,
+  packageCommand,
+  decompileCommand,
+  checkCommand,
+  lintCommand,
+  fmtCommand,
+  catalogCommand,
+  featureCommand,
+  initCommand,
+  completionCommand,
+];
+
+/**
+ * Register every command on the root program.
+ *
+ * @param {import("commander").Command} program
+ * @param {{state: object, product: object}} options
+ */
+export function registerCommands(program, options) {
+  program.commandsGroup("Core Commands:");
+  for (const spec of TOP_LEVEL) defineCommand(program, spec, options);
+  registerVendor(program, options);
+  registerSprite(program, options);
+  defineCommand(program, completeCommand, options);
+  registerExtension(program, options);
+  return program;
+}

package/src/cli/commands/init.js

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import path from "node:path";
+import { normalizePackageTarget } from "../../config.js";
+import { UsageError } from "../errors.js";
+import {
+  initFiles,
+  STAGE_SIZES,
+  TARGETS,
+  TEMPLATES,
+} from "../templates/index.js";
+
+const TEMPLATE_VALUES = new Set(TEMPLATES.map((entry) => entry.value));
+const TARGET_VALUES = new Set(TARGETS.map((entry) => entry.value));
+
+function parseSize(value) {
+  const match = /^(\d+)x(\d+)$/i.exec(String(value).trim());
+  if (!match)
+    throw new UsageError(
+      `--size must look like 480x360, received ${JSON.stringify(value)}`,
+    );
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+
+function sizeValue(width, height) {
+  return `${width}x${height}`;
+}
+
+export const initCommand = {
+  name: "init",
+  aliases: ["i"],
+  group: "Core Commands:",
+  summary: "Create a new project",
+  description: `Scaffold a project config, a source file, and optional starter
+assets. On a terminal this opens a short wizard; use --yes for defaults.`,
+  arguments: ["[dir]"],
+  options: [
+    { flags: "--name <name>", description: "Project name" },
+    {
+      flags: "--template <template>",
+      description: "Template: cat, empty, or blank",
+    },
+    {
+      flags: "--target <target>",
+      description: "Package target: none, html, or zip",
+    },
+    {
+      flags: "--size <WxH>",
+      description: "Stage size (default 480x360)",
+    },
+    { flags: "--force", description: "Overwrite existing files" },
+  ],
+  examples: [
+    "fx init",
+    "fx init examples/demo --yes",
+    "fx init --template blank --target zip",
+  ],
+  async run({ args, options, cwd, reporter, prompts, product, yes }) {
+    const directory = path.resolve(cwd, args[0] || ".");
+    const defaultName = `My ${product.name} Project`;
+    const interactive = prompts.enabled && !yes;
+
+    if (interactive) prompts.intro("Create a new project");
+
+    const name =
+      options.name ??
+      (interactive
+        ? await prompts.text({
+            message: "Project name",
+            defaultValue: defaultName,
+          })
+        : defaultName);
+
+    let template = options.template ?? "cat";
+    if (!TEMPLATE_VALUES.has(template))
+      throw new UsageError(
+        `--template must be one of: ${[...TEMPLATE_VALUES].join(", ")}`,
+      );
+    if (interactive && options.template === undefined)
+      template = await prompts.select({
+        message: "Template",
+        options: TEMPLATES,
+        initialValue: template,
+      });
+
+    let size = options.size ?? "480x360";
+    if (interactive && options.size === undefined)
+      size = await prompts.select({
+        message: "Stage size",
+        options: STAGE_SIZES,
+        initialValue: "480x360",
+      });
+    const { width, height } = parseSize(size);
+
+    let target = options.target ?? "html";
+    if (!TARGET_VALUES.has(target)) {
+      try {
+        target = normalizePackageTarget(target);
+      } catch {
+        throw new UsageError(
+          `--target must be one of: ${[...TARGET_VALUES].join(", ")}`,
+        );
+      }
+    }
+    if (interactive && options.target === undefined)
+      target = await prompts.select({
+        message: "Package target",
+        options: TARGETS,
+        initialValue: target,
+      });
+
+    const files = initFiles({
+      product,
+      name,
+      template,
+      width,
+      height,
+      target,
+    });
+    const conflicts = Object.keys(files).filter((relative) =>
+      fs.existsSync(path.join(directory, relative)),
+    );
+
+    let force = Boolean(options.force);
+    if (conflicts.length > 0 && !force) {
+      if (interactive) {
+        const overwrite = await prompts.confirm({
+          message: `Overwrite ${conflicts.length} existing file(s)?`,
+          initialValue: false,
+        });
+        force = Boolean(overwrite);
+      }
+      if (!force)
+        reporter.warn(
+          `Skipping ${conflicts.length} existing file(s); pass --force to overwrite`,
+        );
+    }
+
+    const written = [];
+    for (const relative of Object.keys(files).sort()) {
+      const destination = path.join(directory, relative);
+      if (fs.existsSync(destination) && !force) {
+        written.push({ path: relative, status: "skipped" });
+        continue;
+      }
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      fs.writeFileSync(destination, files[relative]);
+      written.push({ path: relative, status: "written" });
+      reporter.bullet(relative);
+    }
+
+    const count = written.filter((entry) => entry.status === "written").length;
+    reporter.success(
+      `Created ${count} file(s) in ${path.relative(cwd, directory) || "."}`,
+    );
+    if (interactive)
+      prompts.outro(
+        `Run "${product.command} build" or "${product.command} dev" next.`,
+      );
+
+    return {
+      directory,
+      name,
+      template,
+      target,
+      size: sizeValue(width, height),
+      files: written,
+    };
+  },
+};

package/src/cli/commands/lint.js

@@ -0,0 +1,270 @@
+import fs from "node:fs";
+import path from "node:path";
+import { sourceExtension } from "../../brand.js";
+import { discoverSources } from "../../project.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,
+      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),
+        ),
+      },
+    });
+  },
+};