@triflare/fx 1.0.3 → 2.1.0-beta.1

package/src/lint/config-file.js

@@ -0,0 +1,97 @@
+/**
+ * Browser-safe `fx.yml` reader for editor tooling.
+ *
+ * The full config loader (`src/config.js`) needs `node:fs` to search for the
+ * file, so editors that only have the file's text use this instead. It reads
+ * the settings lint diagnostics depend on — `fx.partialSprites`, `fx.lint` and
+ * the declared extension names — and ignores everything else.
+ */
+
+import * as yaml from "js-yaml";
+import { normalizeLintConfig } from "./config.js";
+
+/** Extension name from a vendor path such as `extensions/signals.js`. */
+function extensionName(source) {
+  const base = String(source).split(/[\\/]/).pop() ?? "";
+  return base.replace(/\.js$/i, "");
+}
+
+/**
+ * @param {string} text raw `fx.yml`/`fx.yaml` contents
+ * @returns {{
+ *   config: {fx: {partialSprites: boolean}},
+ *   lintConfig: object,
+ *   declaredExtensions: string[],
+ *   projectName: string|null,
+ *   error?: string,
+ * }}
+ */
+export function parseProjectConfigText(text) {
+  let raw;
+  try {
+    raw = yaml.load(text) ?? {};
+  } catch (error) {
+    return {
+      config: null,
+      lintConfig: null,
+      declaredExtensions: [],
+      projectName: null,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return {
+      config: null,
+      lintConfig: null,
+      declaredExtensions: [],
+      projectName: null,
+      error: "fx.yml must contain a mapping at the top level",
+    };
+  }
+
+  const fx =
+    raw.fx && typeof raw.fx === "object" && !Array.isArray(raw.fx)
+      ? raw.fx
+      : {};
+  const project =
+    raw.project &&
+    typeof raw.project === "object" &&
+    !Array.isArray(raw.project)
+      ? raw.project
+      : {};
+
+  let lintConfig;
+  try {
+    lintConfig = normalizeLintConfig(fx.lint ?? {});
+  } catch (error) {
+    return {
+      config: null,
+      lintConfig: null,
+      declaredExtensions: [],
+      projectName: typeof project.name === "string" ? project.name : null,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  const declaredExtensions = new Set();
+  if (
+    raw.vendor &&
+    typeof raw.vendor === "object" &&
+    !Array.isArray(raw.vendor)
+  ) {
+    for (const name of Object.keys(raw.vendor)) declaredExtensions.add(name);
+  }
+  if (Array.isArray(project.extensions)) {
+    for (const source of project.extensions) {
+      const name = extensionName(source);
+      if (name) declaredExtensions.add(name);
+    }
+  }
+
+  return {
+    config: { fx: { partialSprites: Boolean(fx.partialSprites) } },
+    lintConfig,
+    declaredExtensions: [...declaredExtensions],
+    projectName: typeof project.name === "string" ? project.name : null,
+  };
+}

package/src/lint/config.js

@@ -0,0 +1,174 @@
+/**
+ * `fx.lint` configuration and rule selection.
+ *
+ * Keeping this separate from the engine lets `src/config.js` validate the
+ * `lint:` block without importing the analyzer (and its vendor/extension
+ * dependencies), so configuration loading stays side-effect free.
+ */
+
+import {
+  META_RULE_IDS,
+  PRESET_NAMES,
+  PRESETS,
+  RULES,
+  ruleById,
+} from "./rules.js";
+
+/** Default lint settings when `fx.yml` has no `lint:` block. */
+export const DEFAULT_LINT = {
+  extends: "recommended",
+  rules: {},
+};
+
+const SEVERITY_ALIASES = {
+  error: "error",
+  warn: "warning",
+  warning: "warning",
+  off: "off",
+  none: "off",
+};
+
+/**
+ * Normalize a severity string.
+ * @param {unknown} value
+ * @returns {'error'|'warning'|'off'|null}
+ */
+export function normalizeSeverity(value) {
+  if (typeof value !== "string") return null;
+  return SEVERITY_ALIASES[value.trim().toLowerCase()] ?? null;
+}
+
+/**
+ * Validate and normalize an `fx.lint` mapping.
+ *
+ * @param {unknown} raw
+ * @param {(message: string) => Error} [makeError]
+ * @returns {{extends: string, rules: Record<string, 'error'|'warning'|'off'>}}
+ */
+export function normalizeLintConfig(
+  raw = {},
+  makeError = (message) => new Error(message),
+) {
+  const lint = { extends: DEFAULT_LINT.extends, rules: {} };
+  if (raw == null) return lint;
+  if (typeof raw !== "object" || Array.isArray(raw))
+    throw makeError("fx.lint must be a mapping");
+
+  const unknownKeys = Object.keys(raw).filter(
+    (key) => !["extends", "rules"].includes(key),
+  );
+  if (unknownKeys.length)
+    throw makeError(
+      `unknown fx.lint setting(s): ${unknownKeys
+        .map((key) => `"${key}"`)
+        .join(", ")}`,
+    );
+
+  if (raw.extends != null) {
+    if (typeof raw.extends !== "string")
+      throw makeError("fx.lint.extends must be a preset name");
+    const preset = raw.extends.trim().toLowerCase();
+    if (!PRESET_NAMES.includes(preset))
+      throw makeError(
+        `unknown lint preset ${JSON.stringify(raw.extends)}; ` +
+          `expected one of: ${PRESET_NAMES.join(", ")}`,
+      );
+    lint.extends = preset;
+  }
+
+  if (raw.rules != null) {
+    if (typeof raw.rules !== "object" || Array.isArray(raw.rules))
+      throw makeError("fx.lint.rules must be a mapping of rule ID to severity");
+    for (const [rawId, rawSeverity] of Object.entries(raw.rules)) {
+      const rule = ruleById(rawId);
+      if (!rule)
+        throw makeError(
+          `unknown lint rule ${JSON.stringify(rawId)} in fx.lint.rules`,
+        );
+      if (META_RULE_IDS.includes(rule.id))
+        throw makeError(`fx.lint.rules cannot configure ${rule.id}`);
+      const severity = normalizeSeverity(rawSeverity);
+      if (!severity)
+        throw makeError(
+          `fx.lint.rules.${rawId} must be one of: error, warn, off`,
+        );
+      lint.rules[rule.id] = severity;
+    }
+  }
+
+  return lint;
+}
+
+/**
+ * The preset a run actually uses: `strict` raises a weaker configured preset
+ * but never downgrades a stronger one such as `all`.
+ *
+ * @param {ReturnType<typeof normalizeLintConfig>} [lint]
+ * @param {boolean} [strict]
+ * @returns {string}
+ */
+export function effectivePreset(lint = DEFAULT_LINT, strict = false) {
+  const configured = PRESET_NAMES.includes(lint?.extends)
+    ? lint.extends
+    : DEFAULT_LINT.extends;
+  if (!strict) return configured;
+  return PRESET_NAMES.indexOf(configured) >= PRESET_NAMES.indexOf("strict")
+    ? configured
+    : "strict";
+}
+
+/**
+ * Resolve every rule's effective severity for a lint run.
+ *
+ * Presets only decide which rules start enabled; overrides can enable a rule
+ * outside the preset or turn one off. `strict` escalates the preset even when
+ * `fx.yml` asks for something lower, without downgrading a stronger preset.
+ *
+ * @param {ReturnType<typeof normalizeLintConfig>} [lint]
+ * @param {{strict?: boolean, overrides?: Record<string, string>}} [options]
+ * @returns {Map<string, 'error'|'warning'|'off'>}
+ */
+export function resolveRuleSeverities(
+  lint = DEFAULT_LINT,
+  { strict = false, overrides = {} } = {},
+) {
+  const presetName = effectivePreset(lint, strict);
+  const enabled = new Set(PRESETS[presetName] ?? PRESETS.recommended);
+  const severities = new Map();
+  for (const id of Object.keys(RULES)) {
+    if (META_RULE_IDS.includes(id)) continue;
+    severities.set(id, enabled.has(id) ? RULES[id].severity : "off");
+  }
+
+  const apply = (rawOverrides) => {
+    for (const [rawId, rawSeverity] of Object.entries(rawOverrides || {})) {
+      const rule = ruleById(rawId);
+      if (!rule) continue;
+      const severity = normalizeSeverity(rawSeverity);
+      if (!severity) continue;
+      severities.set(rule.id, severity);
+    }
+  };
+  apply(lint.rules);
+  apply(overrides);
+  return severities;
+}
+
+/**
+ * Parse a `--rule` value: `FX201`, `FX201=error`, `FX201:off` or a preset
+ * escalation such as `strict`. Unknown rules are reported by the caller so a
+ * typo does not silently do nothing.
+ *
+ * @param {string} value
+ * @returns {{id: string, severity?: string}}
+ */
+export function parseRuleOption(value) {
+  const text = String(value).trim();
+  const match = text.match(/^([^=:]+)\s*[=:]\s*(.+)$/);
+  if (match)
+    return {
+      id: match[1].trim(),
+      severity: normalizeSeverity(match[2]) ?? match[2].trim(),
+    };
+  return { id: text };
+}