Add support for evaluating JEXL-based filter expressions.

This allows us to filter entries based on which Firefox version they apply to.

Uses mozjexl extended with the version compare method from addons-moz-compare.

Author: Trikolon

package-lock.json

@@ -21,6 +21,8 @@
     "vite": "^7.0.0"
   },
   "dependencies": {
-    "lit": "^3.3.0"
+    "addons-moz-compare": "^1.3.0",
+    "lit": "^3.3.0",
+    "mozjexl": "^1.1.6"
   }
 }

package.json

@@ -0,0 +1,7 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+declare module "addons-moz-compare" {
+  export function mozCompare(a: string, b: string): boolean;
+}

src/filter-expression/addons-moz-compare.d.ts

@@ -0,0 +1,64 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import mozjexl from "mozjexl";
+import { mozCompare } from "addons-moz-compare";
+
+const jexl = new mozjexl.Jexl();
+jexl.addTransforms({
+  versionCompare: (value: unknown, ...args: unknown[]) => {
+    // Ensure we have two string arguments for version comparison
+    if (args.length < 1) {
+      throw new Error("versionCompare requires two arguments");
+    }
+    const a = String(value);
+    const b = String(args[0]);
+    return mozCompare(a, b);
+  },
+});
+
+/**
+ * Evaluates a JEXL-based filter expression.
+ * @param expression The filter expression to evaluate.
+ * @param context The context to evaluate the expression in.
+ * @returns The result of the evaluation.
+ */
+export function evaluateFilterExpression(expression: string, context: Record<string, unknown>) {
+  return jexl.eval(expression, context);
+}
+
+/**
+ * Evaluates a given JEXL filter expression against a Gecko / Firefox version
+ * number.
+ * @param version The version number to check.
+ * @param filterExpression The filter expression to evaluate.
+ * @returns True if the version number matches the filter expression, false
+ * otherwise.
+ */
+export async function versionNumberMatchesFilterExpression(
+  version: string,
+  filterExpression: string | undefined,
+): Promise<boolean> {
+  // An empty filter expression always matches.
+  if (!filterExpression?.length) {
+    return true;
+  }
+
+  const context = {
+    env: {
+      version,
+    },
+  };
+  const result = await evaluateFilterExpression(filterExpression, context);
+  console.debug(
+    "Evaluating filter expression",
+    filterExpression,
+    "for version",
+    version,
+    "result",
+    result,
+  );
+
+  return result === true;
+}

src/filter-expression/filter-expression.ts

@@ -0,0 +1,61 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+// Provides basic type definitions for mozjexl.
+// Only the properties that are used in this project are defined.
+
+declare module "mozjexl" {
+  /**
+   * A transform function that can be used in JEXL expressions. Transform
+   * functions receive the value to be transformed as the first argument,
+   * followed by any additional arguments passed to the transform.
+   */
+  export type TransformFunction = (
+    value: unknown,
+    ...args: unknown[]
+  ) => unknown | Promise<unknown>;
+
+  /**
+   * A map of transform names to their corresponding transform functions.
+   */
+  export interface Transforms {
+    [key: string]: TransformFunction;
+  }
+
+  /**
+   * The context object passed to JEXL expressions, containing variables
+   * accessible during evaluation.
+   */
+  export interface JexlContext {
+    [key: string]: unknown;
+  }
+
+  /**
+   * The main JEXL class for parsing and evaluating expressions.
+   */
+  export class Jexl {
+    constructor();
+    /**
+     * Adds multiple transform functions at once.
+     * @param map A map of transform names to transform functions
+     */
+    addTransforms(map: Transforms): void;
+
+    /**
+     * Evaluates a JEXL expression within an optional context.
+     * @param expression The JEXL expression to be evaluated
+     * @param context A mapping of variables to values, which will be made
+     * accessible to the JEXL expression
+     * @returns A Promise that resolves with the result of the evaluation
+     */
+    eval(expression: string, context?: JexlContext): Promise<unknown>;
+  }
+
+  // The default export is an instance of Jexl
+  const mozjexl: Jexl & {
+    Jexl: typeof Jexl;
+  };
+
+  export default mozjexl;
+}