@fjall/eslint-plugin 7.0.1 → 7.2.0

package/index.js

@@ -27,6 +27,7 @@ import requireAbortCompositionOnSdkSend from "./require-abort-composition-on-sdk
 import noClassicConnectedAccountAssume from "./no-classic-connected-account-assume.js";
 import noRawDbTransaction from "./no-raw-db-transaction.js";
 import noRawExitCode from "./no-raw-exit-code.js";
+import noReplacementStringExpansion from "./no-replacement-string-expansion.js";
 
 export default {
   rules: {
@@ -60,6 +61,7 @@ export default {
     "require-abort-composition-on-sdk-send": requireAbortCompositionOnSdkSend,
     "no-classic-connected-account-assume": noClassicConnectedAccountAssume,
     "no-raw-db-transaction": noRawDbTransaction,
-    "no-raw-exit-code": noRawExitCode
+    "no-raw-exit-code": noRawExitCode,
+    "no-replacement-string-expansion": noReplacementStringExpansion
   }
 };

package/no-replacement-string-expansion.js

@@ -0,0 +1,125 @@
+/**
+ * ESLint Rule: no-replacement-string-expansion
+ *
+ * Flags `.replace(pattern, X)` / `.replaceAll(pattern, X)` where X is a
+ * runtime-composed string. The JS engine expands `$` sequences in string
+ * replacements — `$&` (whole match), `$'` (suffix), `` $` `` (prefix),
+ * `$1`..`$n` (groups), `$<name>` — so any value not visible to the author at
+ * the call site silently corrupts output the first time the data contains
+ * `$`. The function form performs no expansion and is always safe.
+ *
+ * Flagged shapes (second argument):
+ *   content.replace(re, `${comment}\n# $1`)   // template WITH expressions
+ *   content.replace(re, buildReplacement())   // call result — unknown content
+ *   content.replace(re, options.replacement)  // member — unknown content
+ *   content.replace(re, someParam)            // identifier not resolvable to
+ *                                             // a same-file static string
+ *
+ * Allowed shapes:
+ *   content.replace(re, () => value)          // function form — no expansion
+ *   content.replace(re, (m, g1) => `${g1}x`)  // deliberate backreferences
+ *   content.replace(re, "literal $1")         // static literal — `$` visible
+ *   content.replace(re, `static template`)    // no expressions — static
+ *   const REP = "static"; s.replace(re, REP)  // resolves to a const with a
+ *                                             // static string init
+ *
+ * No autofix: wrapping in `() => value` would break call sites that rely on
+ * deliberate `$n` backreferences — the conversion to `(m, g1) => ...` is a
+ * judgement call.
+ *
+ * Per .claude/rules/robustness-standards.md § "Replacement strings passed to
+ * .replace() must be function-wrapped when runtime-composed".
+ */
+
+function isStaticString(node) {
+  if (!node) return false;
+  if (node.type === "Literal" && typeof node.value === "string") return true;
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) {
+    return true;
+  }
+  return false;
+}
+
+function isFunctionNode(node) {
+  return (
+    node &&
+    (node.type === "ArrowFunctionExpression" ||
+      node.type === "FunctionExpression")
+  );
+}
+
+/** Walk the scope chain upward to find the variable binding for `name`. */
+function resolveVariable(scope, name) {
+  for (let s = scope; s; s = s.upper) {
+    const variable = s.variables.find((v) => v.name === name);
+    if (variable) return variable;
+  }
+  return null;
+}
+
+/**
+ * Returns true iff the identifier resolves in-file to a binding whose value
+ * is statically known to be safe: a `const` initialised with a static string
+ * (author-visible content) or a function (function-form replacer), or a
+ * function declaration.
+ */
+function identifierResolvesToSafeBinding(context, identifier) {
+  const scope = context.sourceCode.getScope(identifier);
+  const variable = resolveVariable(scope, identifier.name);
+  if (!variable || variable.defs.length !== 1) return false;
+
+  const def = variable.defs[0];
+  if (def.type === "FunctionName") return true;
+  if (def.type !== "Variable") return false;
+  if (def.parent.kind !== "const") return false;
+
+  const init = def.node.init;
+  return isStaticString(init) || isFunctionNode(init);
+}
+
+const REPLACE_METHODS = new Set(["replace", "replaceAll"]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow runtime-composed strings as the replacement argument of .replace()/.replaceAll() — `$` sequences expand silently; use the function form.",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      replacementExpansion:
+        "Runtime-composed replacement string — the engine expands `$&`, `$'`, `$`-backtick and `$n` sequences in it, corrupting output when the value contains `$`. Use the function form: `() => value`, or `(match, g1) => ...` if backreferences are intended."
+    },
+    schema: []
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== "MemberExpression") return;
+        if (node.callee.computed) return;
+        if (node.callee.property.type !== "Identifier") return;
+        if (!REPLACE_METHODS.has(node.callee.property.name)) return;
+        if (node.arguments.length !== 2) return;
+
+        const replacement = node.arguments[1];
+        if (isFunctionNode(replacement)) return;
+        if (isStaticString(replacement)) return;
+        if (
+          replacement.type === "Identifier" &&
+          identifierResolvesToSafeBinding(context, replacement)
+        ) {
+          return;
+        }
+
+        context.report({
+          node: replacement,
+          messageId: "replacementExpansion"
+        });
+      }
+    };
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/eslint-plugin",
-  "version": "7.0.1",
+  "version": "7.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",