@triflare/fx 2.0.0 → 2.1.0-beta.1

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

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";
 
@@ -49,6 +50,7 @@ export function loadProjectConfig({ cwd = process.cwd(), searchDir, options }) {
       fx: null,
       package: null,
       vendor: [],
+      features: [],
       vendorDir: "extensions",
       path: null,
     };
@@ -166,6 +168,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;

package/src/compiler.js

@@ -137,6 +137,7 @@ export class Compiler {
     this.loadAsset = loadAsset || null;
     this.catalog = catalog ? { ...CATALOG, ...catalog } : CATALOG;
     this.extensionUrls = extensionUrls;
+    this.requiredExtensions = new Map();
     this.file = file;
     /** @type {string[]} Non-fatal problems worth surfacing to the user. */
     this.warnings = [];
@@ -252,6 +253,8 @@ export class Compiler {
     // can only be given their mutation once every stack is complete.
     for (const ctx of contexts) this.applyDynamicNextMutations(ctx);
 
+    this.validateRequiredExtensions();
+
     return { project: this.assembleProject(contexts), assets: this.assets };
   }
 
@@ -335,6 +338,11 @@ export class Compiler {
   }
 
   declareTargetVar(ctx, decl) {
+    if (decl.name.startsWith("$"))
+      this.fail(
+        `Names starting with "$" are reserved for temporary variables; rename ${JSON.stringify(decl.name)}.`,
+        decl.loc,
+      );
     const global = ctx.isStage;
     if (global && this.globals.has(decl.name)) {
       const first = this.globals.get(decl.name);
@@ -380,6 +388,11 @@ export class Compiler {
   }
 
   declareTargetList(ctx, decl) {
+    if (decl.name.startsWith("$"))
+      this.fail(
+        `Names starting with "$" are reserved for temporary variables; rename ${JSON.stringify(decl.name)}.`,
+        decl.loc,
+      );
     if (ctx.isStage && this.globals.has(decl.name)) {
       const first = this.globals.get(decl.name);
       const where = this.where(first.loc);
@@ -421,6 +434,13 @@ export class Compiler {
         decl.loc,
       );
     }
+    for (const param of decl.params) {
+      if (param.name.startsWith("$"))
+        this.fail(
+          `Names starting with "$" are reserved for temporary variables; rename parameter ${JSON.stringify(param.name)}.`,
+          decl.loc,
+        );
+    }
     const argIds = decl.params.map((_, i) => `arg${i}`);
     const proccode = decl.params.length
       ? `${decl.name} ${decl.params.map((param) => (param.boolean ? "%b" : "%s")).join(" ")}`
@@ -785,6 +805,8 @@ export class Compiler {
         return this.compileForever(ctx, node);
       case "Return":
         return this.compileReturn(ctx, node);
+      case "TempVarDecl":
+        return this.compileTempVarDecl(ctx, node);
       default:
         this.fail(`Unsupported statement ${node.type}`, node.loc);
     }
@@ -824,6 +846,13 @@ export class Compiler {
   }
 
   compileAssign(ctx, node) {
+    const sigil = /^(\$\$?)([A-Za-z_][A-Za-z0-9_]*)$/.exec(node.name);
+    if (sigil) return this.compileSigilAssign(ctx, node, sigil);
+    if (node.name.startsWith("$"))
+      this.fail(
+        `Invalid temporary variable reference ${JSON.stringify(node.name)}`,
+        node.loc,
+      );
     const resolved = ctx.resolveValue(node.name);
     if (!resolved || resolved.kind !== "var") {
       this.fail(`Unknown variable ${JSON.stringify(node.name)}`, node.loc);
@@ -880,6 +909,64 @@ export class Compiler {
     return id;
   }
 
+  compileTempVarDecl(ctx, node) {
+    if (node.name.startsWith("$"))
+      this.fail(
+        'Temporary variable names cannot start with "$"; use a plain name.',
+        node.loc,
+      );
+    const name =
+      node.kind === "runtime" ? "tempvars.setRuntime" : "tempvars.setThread";
+    const entry = this.catalog[name];
+    if (!entry)
+      this.fail(
+        "Temporary variables are not available in this Fx build",
+        node.loc,
+      );
+    return this.emitCatalogCall(
+      ctx,
+      {
+        name,
+        segments: name.split("."),
+        args: [
+          { type: "String", value: node.name, loc: node.loc },
+          node.init ?? { type: "String", value: "0", loc: node.loc },
+        ],
+        loc: node.loc,
+      },
+      entry,
+      null,
+    ).id;
+  }
+
+  compileSigilAssign(ctx, node, sigil) {
+    if (node.op !== "=" && node.op !== "+=")
+      this.fail(
+        `Temporary variables only support "=" and "+="; ${JSON.stringify(node.op)} is not available.`,
+        node.loc,
+      );
+    const kind = sigil[1] === "$$" ? "Runtime" : "Thread";
+    const action = node.op === "=" ? "set" : "change";
+    const name = `tempvars.${action}${kind}`;
+    const entry = this.catalog[name];
+    if (!entry)
+      this.fail(
+        "Temporary variables are not available in this Fx build",
+        node.loc,
+      );
+    return this.emitCatalogCall(
+      ctx,
+      {
+        name,
+        segments: name.split("."),
+        args: [{ type: "String", value: sigil[2], loc: node.loc }, node.value],
+        loc: node.loc,
+      },
+      entry,
+      null,
+    ).id;
+  }
+
   compileIf(ctx, node) {
     const id = this.addBlock(ctx, {
       opcode: node.else ? "control_if_else" : "control_if",
@@ -976,6 +1063,11 @@ export class Compiler {
   emitCatalogCall(ctx, node, entry, parentId) {
     if (entry.kind === "hat")
       this.fail(`${node.name} is an event and cannot be called`, node.loc);
+    if (entry.requiresExtension) {
+      const id = entry.extension || extensionForOpcode(entry.opcode);
+      if (id && !this.requiredExtensions.has(id))
+        this.requiredExtensions.set(id, node.loc);
+    }
     const id = this.addBlock(ctx, { opcode: entry.opcode, parent: parentId });
     const fieldNames = Object.keys(entry.fields || {});
     const inputNames = Object.keys(entry.inputs || {});
@@ -1282,6 +1374,33 @@ export class Compiler {
   }
 
   emitIdentifier(ctx, node) {
+    const sigil = /^(\$\$?)([A-Za-z_][A-Za-z0-9_]*)$/.exec(node.name);
+    if (sigil) {
+      const name = sigil[1] === "$$" ? "tempvars.runtime" : "tempvars.thread";
+      const entry = this.catalog[name];
+      if (!entry)
+        this.fail(
+          "Temporary variables are not available in this Fx build",
+          node.loc,
+        );
+      const result = this.emitCatalogCall(
+        ctx,
+        {
+          name,
+          segments: name.split("."),
+          args: [{ type: "String", value: sigil[2], loc: node.loc }],
+          loc: node.loc,
+        },
+        entry,
+        null,
+      );
+      return { k: "block", id: result.id, kind: "reporter" };
+    }
+    if (node.name.startsWith("$"))
+      this.fail(
+        `Invalid temporary variable reference ${JSON.stringify(node.name)}`,
+        node.loc,
+      );
     if (node.segments.length > 1)
       this.fail(
         `Unexpected dotted name ${JSON.stringify(node.name)}`,
@@ -1537,6 +1656,20 @@ export class Compiler {
 
   // ------------------------------------------------------------ assembly
 
+  validateRequiredExtensions() {
+    for (const [id, loc] of this.requiredExtensions) {
+      if (this.extensionUrls[id]) continue;
+      const feature = id === "fxTempVars" ? "temporaryvariables" : null;
+      const hint = feature
+        ? ` Run "fx feature ${feature} enable" to install it.`
+        : "";
+      this.fail(
+        `This project uses blocks from extension ${JSON.stringify(id)}, which is not loaded.${hint}`,
+        loc,
+      );
+    }
+  }
+
   assembleProject(contexts) {
     const targets = [];
     const extensions = new Set();

package/src/config-edit.js

@@ -615,3 +615,122 @@ export function removeVendorEntry(configPath, name) {
   writeDocument(configPath, lines.join(""));
   return { removed: source ?? key };
 }
+
+// -------------------------------------------------------------- feature edits
+
+/**
+ * Add or replace a `features:` entry without reformatting the rest of fx.yml.
+ *
+ * @param {string} configPath
+ * @param {string} name
+ * @param {string} file
+ * @returns {{added: boolean, updated: boolean}}
+ */
+export function addFeatureEntry(configPath, name, file) {
+  const text = fs.readFileSync(configPath, "utf8");
+  const lines = splitLines(text);
+  const eol = eolOf(text);
+  const key = String(name);
+  let added = false;
+  let updated = false;
+  const entryLine = (indent) =>
+    `${indent}${quoteKey(key)}: ${quote(file)}${eol}`;
+
+  const bounds = topLevelBounds(lines, "features");
+  if (!bounds) {
+    if (lines.length > 0 && !lines[lines.length - 1].endsWith("\n"))
+      lines[lines.length - 1] += eol;
+    lines.push(`features:${eol}`, entryLine("  "));
+    added = true;
+  } else if (bounds.inline) {
+    const mapping = parseValue(bounds.inline) || {};
+    updated = Object.hasOwn(mapping, key);
+    added = !updated;
+    mapping[key] = file;
+    const dumped = yaml
+      .dump({ features: mapping }, { lineWidth: -1, noRefs: true })
+      .split("\n")
+      .filter((line, index, all) => !(index === all.length - 1 && line === ""))
+      .map((line) => `${line}${eol}`);
+    if (bounds.comment) dumped[0] = `features: ${bounds.comment}${eol}`;
+    replaceRange(lines, bounds.index, bounds.index + 1, dumped);
+  } else {
+    const spans = mappingEntrySpans(lines, bounds.index, bounds.end);
+    const existing = spans.find((span) => span.key === key);
+    if (existing) {
+      replaceRange(lines, existing.index, existing.end, [
+        entryLine(existing.indent),
+      ]);
+      updated = true;
+    } else {
+      const indent = childIndent(lines, bounds.index, bounds.end);
+      insertAt(lines, bounds.end, [entryLine(indent)], eol);
+      added = true;
+    }
+  }
+
+  if (added || updated) writeDocument(configPath, lines.join(""));
+  return { added, updated };
+}
+
+/**
+ * Remove a `features:` entry.
+ * @param {string} configPath
+ * @param {string} name
+ * @returns {{removed: string|null}}
+ */
+export function removeFeatureEntry(configPath, name) {
+  const text = fs.readFileSync(configPath, "utf8");
+  const lines = splitLines(text);
+  const eol = eolOf(text);
+  const key = String(name);
+  const bounds = topLevelBounds(lines, "features");
+  if (!bounds) return { removed: null };
+
+  if (bounds.inline) {
+    const mapping = parseValue(bounds.inline);
+    if (!mapping || typeof mapping !== "object" || Array.isArray(mapping))
+      return { removed: null };
+    if (!Object.hasOwn(mapping, key)) return { removed: null };
+    const source = mapping[key];
+    delete mapping[key];
+    const rest = Object.keys(mapping).length
+      ? ` ${JSON.stringify(mapping)}`
+      : " {}";
+    const comment = bounds.comment ? ` ${bounds.comment}` : "";
+    const line = lines[bounds.index];
+    lines[bounds.index] = `features:${rest}${comment}${
+      /\r?\n$/.test(line) ? ending(line) : eol
+    }`;
+    writeDocument(configPath, lines.join(""));
+    return { removed: source == null ? null : String(source) };
+  }
+
+  const spans = mappingEntrySpans(lines, bounds.index, bounds.end);
+  const existing = spans.find((span) => span.key === key);
+  if (!existing) return { removed: null };
+
+  let source = null;
+  try {
+    const parsed = yaml.load(
+      [
+        content(lines[bounds.index]),
+        ...lines.slice(existing.index, existing.end),
+      ].join("\n"),
+    );
+    const entry = parsed?.features?.[key];
+    source =
+      typeof entry === "string" ? entry : (entry?.file ?? entry?.path ?? null);
+  } catch {
+    // The entry is removed either way.
+  }
+
+  replaceRange(lines, existing.index, existing.end, []);
+  const end = bounds.end - (existing.end - existing.index);
+  const remaining = mappingEntrySpans(lines, bounds.index, end);
+  if (remaining.length === 0) {
+    replaceRange(lines, bounds.index, end, [`features: {}${eol}`]);
+  }
+  writeDocument(configPath, lines.join(""));
+  return { removed: source ?? key };
+}