eslint-plugin-sfmc 2.6.1 → 3.0.0

package/src/rules/amp/no-loop-counter-assign.js

@@ -23,21 +23,21 @@ export default {
         const counterStack = [];
 
         function checkBody(body) {
-            for (const stmt of body) {
-                if (stmt.type === 'SetStatement' && stmt.target) {
+            for (const statement of body) {
+                if (statement.type === 'SetStatement' && statement.target) {
                     const current = counterStack.at(-1);
-                    if (current && stmt.target.value.toLowerCase() === current.toLowerCase()) {
+                    if (current && statement.target.value.toLowerCase() === current.toLowerCase()) {
                         context.report({
-                            node: stmt.target,
+                            node: statement.target,
                             messageId: 'counterAssign',
-                            data: { name: stmt.target.value },
+                            data: { name: statement.target.value },
                         });
                     }
                 }
-                if (stmt.type === 'VarDeclaration') {
+                if (statement.type === 'VarDeclaration') {
                     const current = counterStack.at(-1);
                     if (current) {
-                        for (const v of stmt.variables) {
+                        for (const v of statement.variables) {
                             if (v.value.toLowerCase() === current.toLowerCase()) {
                                 context.report({
                                     node: v,

package/src/rules/amp/no-nested-ampscript-delimiter.js

@@ -61,13 +61,13 @@ export default {
                 while ((match = DELIMITER_RE.exec(text)) !== null) {
                     const delimiter = match[0];
                     const start = match.index;
-                    const end = start + delimiter.length;
 
                     // Skip the outermost %%[ opener (it is the block wrapper, not nested)
                     if (!isScriptBlock && start === outerOpenStart) {
                         continue;
                     }
 
+                    const end = start + delimiter.length;
                     const closeToken = delimiter === '%%[' ? ']%%' : '=%%';
 
                     // Find the matching close token for the fix (first occurrence after this open)

package/src/rules/amp/no-smart-quotes.js

@@ -1,27 +1,27 @@
-const SMART_QUOTE_RE = /[\u2018\u2019\u201C\u201D\u201A\u201E\u2039\u203A]/;
+const SMART_QUOTE_RE = /[\u{2018}\u{2019}\u{201C}\u{201D}\u{201A}\u{201E}\u{2039}\u{203A}]/u;
 
 const SMART_QUOTES = {
-    '\u2018': 'left single curly quote \u2018',
-    '\u2019': 'right single curly quote \u2019',
-    '\u201C': 'left double curly quote \u201C',
-    '\u201D': 'right double curly quote \u201D',
-    '\u201A': 'single low-9 quote \u201A',
-    '\u201E': 'double low-9 quote \u201E',
-    '\u2039': 'single left angle quote \u2039',
-    '\u203A': 'single right angle quote \u203A',
+    '\u{2018}': 'left single curly quote \u{2018}',
+    '\u{2019}': 'right single curly quote \u{2019}',
+    '\u{201C}': 'left double curly quote \u{201C}',
+    '\u{201D}': 'right double curly quote \u{201D}',
+    '\u{201A}': 'single low-9 quote \u{201A}',
+    '\u{201E}': 'double low-9 quote \u{201E}',
+    '\u{2039}': 'single left angle quote \u{2039}',
+    '\u{203A}': 'single right angle quote \u{203A}',
 };
 
 // Maps each smart-quote char to its nearest ASCII equivalent.
 // Single-flavour smart quotes -> ' ; double-flavour -> "
 const SMART_TO_ASCII = {
-    '\u2018': "'",
-    '\u2019': "'",
-    '\u201A': "'",
-    '\u2039': "'",
-    '\u203A': "'",
-    '\u201C': '"',
-    '\u201D': '"',
-    '\u201E': '"',
+    '\u{2018}': "'",
+    '\u{2019}': "'",
+    '\u{201A}': "'",
+    '\u{2039}': "'",
+    '\u{203A}': "'",
+    '\u{201C}': '"',
+    '\u{201D}': '"',
+    '\u{201E}': '"',
 };
 
 export default {
@@ -52,7 +52,7 @@ export default {
                                 data: { kind },
                                 fix(fixer) {
                                     const fixed = node.value.replaceAll(
-                                        /[\u2018\u2019\u201C\u201D\u201A\u201E\u2039\u203A]/g,
+                                        /[\u{2018}\u{2019}\u{201C}\u{201D}\u{201A}\u{201E}\u{2039}\u{203A}]/gu,
                                         (c) => SMART_TO_ASCII[c],
                                     );
                                     const q = node.quote;

package/src/rules/amp/no-unknown-function.js

@@ -1,4 +1,4 @@
-import { functionNames, isMcnSupported } from 'ampscript-data';
+import { functionNames, functionLookup, isMcnSupported } from 'ampscript-data';
 
 export default {
     meta: {
@@ -12,6 +12,8 @@ export default {
             unknownFunction:
                 "'{{name}}' is not a recognized AMPscript function. AMPscript does not support custom functions.",
             notSupportedInMcn: "'{{name}}' is not supported in Marketing Cloud Next.",
+            noHandlebarsEquivalent:
+                "'{{name}}' is supported by Marketing Cloud Next AMPscript but has no Handlebars for Marketing Cloud Next equivalent. It cannot be migrated to a Handlebars helper.",
         },
         schema: [
             {
@@ -31,7 +33,7 @@ export default {
 
     create(context) {
         const options = context.options[0] ?? {};
-        const targetNext = options.target === 'next';
+        const isTargetNext = options.target === 'next';
 
         return {
             FunctionCall(node) {
@@ -46,12 +48,23 @@ export default {
                     return;
                 }
 
-                if (targetNext && !isMcnSupported(lower)) {
+                if (isTargetNext && !isMcnSupported(lower)) {
                     context.report({
                         node,
                         messageId: 'notSupportedInMcn',
                         data: { name: node.name },
                     });
+                    return;
+                }
+
+                // Category C: the function works in MCN AMPscript but has no
+                // Handlebars counterpart, so it cannot be migrated to Handlebars.
+                if (isTargetNext && functionLookup.get(lower)?.mcnHandlebarsGap === true) {
+                    context.report({
+                        node,
+                        messageId: 'noHandlebarsEquivalent',
+                        data: { name: node.name },
+                    });
                 }
             },
         };

package/src/rules/amp/prefer-attribute-value.js

@@ -39,10 +39,7 @@ function isLikelyPersonalization(node) {
     if (functionNames.has(lower)) {
         return false;
     }
-    if (AMPSCRIPT_KEYWORDS.has(lower)) {
-        return false;
-    }
-    return true;
+    return !AMPSCRIPT_KEYWORDS.has(lower);
 }
 
 export default {
@@ -63,19 +60,19 @@ export default {
     },
 
     create(context) {
-        function reportWithSuggestion(identNode) {
+        function reportWithSuggestion(identifierNode) {
             context.report({
-                node: identNode,
+                node: identifierNode,
                 messageId: 'preferAttributeValue',
-                data: { name: identNode.value },
+                data: { name: identifierNode.value },
                 suggest: [
                     {
                         messageId: 'wrapWithAttributeValue',
-                        data: { name: identNode.value },
+                        data: { name: identifierNode.value },
                         fix(fixer) {
                             return fixer.replaceText(
-                                identNode,
-                                `AttributeValue("${identNode.value}")`,
+                                identifierNode,
+                                `AttributeValue("${identifierNode.value}")`,
                             );
                         },
                     },

package/src/rules/amp/require-rowcount-check.js

@@ -35,12 +35,7 @@ function extractRowCountVariables(node, into) {
         }
     }
 
-    if (node.type === 'BinaryExpression') {
-        extractRowCountVariables(node.left, into);
-        extractRowCountVariables(node.right, into);
-    }
-
-    if (node.type === 'LogicalExpression') {
+    if (node.type === 'BinaryExpression' || node.type === 'LogicalExpression') {
         extractRowCountVariables(node.left, into);
         extractRowCountVariables(node.right, into);
     }
@@ -86,19 +81,21 @@ export default {
             },
 
             AmpForStatement(node) {
-                if (
+                if (!(
                     node.endExpr &&
                     isRowCountCall(node.endExpr) &&
                     node.endExpr.arguments &&
                     node.endExpr.arguments.length > 0
-                ) {
-                    const argument = node.endExpr.arguments[0];
-                    if (argument.type === 'Variable') {
-                        forLoops.push({
-                            varName: argument.value.toLowerCase(),
-                            node,
-                        });
-                    }
+                )) {
+                    return;
+                }
+
+                const argument = node.endExpr.arguments[0];
+                if (argument.type === 'Variable') {
+                    forLoops.push({
+                        varName: argument.value.toLowerCase(),
+                        node,
+                    });
                 }
             },
 

package/src/rules/amp/require-variable-declaration.js

@@ -25,7 +25,7 @@ export default {
 
     create(context) {
         const declared = new Set();
-        const fixedVars = new Set();
+        const fixedVariables = new Set();
 
         return {
             VarDeclaration(node) {
@@ -44,9 +44,9 @@ export default {
                 }
                 const lower = name.toLowerCase();
                 if (!declared.has(lower)) {
-                    const isFirstFix = !fixedVars.has(lower);
+                    const isFirstFix = !fixedVariables.has(lower);
                     if (isFirstFix) {
-                        fixedVars.add(lower);
+                        fixedVariables.add(lower);
                     }
 
                     context.report({

package/src/rules/hbs/_shared.js

@@ -0,0 +1,116 @@
+/**
+ * Shared helpers for the Handlebars (Marketing Cloud Next) ESLint rules.
+ *
+ * Mirrors the logic used by the sfmc-language-lsp MCN Handlebars validator so
+ * that ESLint diagnostics and editor diagnostics stay consistent.
+ */
+
+/** Matches a `{!$namespace.Field}` built-in data binding token. */
+export const BINDING_PATTERN = /\{!\$([A-Za-z0-9_.]+)\}/g;
+
+/**
+ * Returns the bare helper name when a node's path is a simple, single-part
+ * identifier (e.g. `add`), or null when it is a property access (`foo.bar`),
+ * a data variable (`@index`), a literal, or `this`.
+ *
+ * @param {object | undefined} path - The node's path expression.
+ * @returns {string | null} The simple helper name, or null.
+ */
+export function simpleHelperName(path) {
+    if (!path || path.type !== 'PathExpression') {
+        return null;
+    }
+    if (path.data) {
+        return null;
+    }
+    if ((path.depth ?? 0) > 0) {
+        return null;
+    }
+    const parts = path.parts ?? [];
+    if (parts.length !== 1) {
+        return null;
+    }
+    const name = parts[0];
+    if (!name || name === 'this') {
+        return null;
+    }
+    return name;
+}
+
+/**
+ * Returns true when a mustache/subexpression node is a helper invocation rather
+ * than a bare data binding. A `{{foo}}` mustache with no params/hash is a data
+ * binding; a subexpression `(foo ...)` is always an invocation.
+ *
+ * @param {object} node - The AST node.
+ * @returns {boolean} True when the node invokes a helper.
+ */
+export function isInvocation(node) {
+    const hasArguments = (node.params?.length ?? 0) > 0 || (node.hash?.pairs?.length ?? 0) > 0;
+    return node.type === 'SubExpression' || hasArguments;
+}
+
+/**
+ * Compute the Levenshtein edit distance between two strings.
+ *
+ * @param {string} a - First string.
+ * @param {string} b - Second string.
+ * @returns {number} The minimum number of single-character edits.
+ */
+export function levenshtein(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (a.length === 0) {
+        return b.length;
+    }
+    if (b.length === 0) {
+        return a.length;
+    }
+
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    const current = Array.from({ length: b.length + 1 }, () => 0);
+
+    for (let index = 1; index <= a.length; index++) {
+        current[0] = index;
+        for (let index_ = 1; index_ <= b.length; index_++) {
+            const cost = a[index - 1] === b[index_ - 1] ? 0 : 1;
+            current[index_] = Math.min(
+                current[index_ - 1] + 1,
+                previous[index_] + 1,
+                previous[index_ - 1] + cost,
+            );
+        }
+        previous = current.slice();
+    }
+    return previous[b.length];
+}
+
+/**
+ * Return the candidate closest to `word` (case-insensitive) when it is within a
+ * conservative typo threshold, or null when nothing is close enough.
+ *
+ * @param {string} word - The unknown word typed by the user.
+ * @param {Iterable<string>} candidates - Known valid names to match against.
+ * @returns {string | null} The closest candidate (original casing), or null.
+ */
+export function closestMatch(word, candidates) {
+    const lowerWord = word.toLowerCase();
+    const maxDistance = lowerWord.length <= 4 ? 1 : 2;
+
+    let best = null;
+    let bestDistance = Infinity;
+
+    for (const candidate of candidates) {
+        const distance = levenshtein(lowerWord, candidate.toLowerCase());
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+
+    if (best !== null && bestDistance > 0 && bestDistance <= maxDistance) {
+        return best;
+    }
+    return null;
+}

package/src/rules/hbs/helper-arity.js

@@ -0,0 +1,97 @@
+import { getHelper } from 'handlebars-data';
+
+import { simpleHelperName } from './_shared.js';
+
+/**
+ * Enforces correct positional-argument counts for known Marketing Cloud Next
+ * Handlebars helpers, derived from each helper's `params` definition.
+ *
+ * Only positional `params` are checked. Helpers with a variadic trailing param
+ * (e.g. `concat`, `and`, `set`) have no upper bound. Hash (named) arguments are
+ * not counted as positional arguments.
+ */
+
+/**
+ * Computes the required and maximum positional argument counts for a helper.
+ *
+ * @param {object} helper - The helper definition from handlebars-data.
+ * @returns {{required: number, max: number}} Required and max positional counts.
+ */
+function arityOf(helper) {
+    const parameters = helper.params ?? [];
+    const hasVariadic = parameters.some((p) => p.variadic);
+    const required = parameters.filter((p) => !p.optional && !p.variadic).length;
+    const max = hasVariadic ? Infinity : parameters.length;
+    return { required, max };
+}
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Enforce correct argument counts for known Marketing Cloud Next helpers',
+            recommended: true,
+        },
+        messages: {
+            tooFewArgs:
+                "'{{name}}' requires at least {{min}} argument(s) but was called with {{actual}}.",
+            tooManyArgs:
+                "'{{name}}' accepts at most {{max}} argument(s) but was called with {{actual}}.",
+        },
+        schema: [],
+    },
+
+    create(context) {
+        /**
+         * Validates the positional argument count of a helper invocation.
+         *
+         * @param {object} node - The AST node (mustache, subexpression, block).
+         * @returns {void}
+         */
+        function check(node) {
+            const helperName = simpleHelperName(node.path);
+            if (!helperName) {
+                return;
+            }
+            const helper = getHelper(helperName);
+            if (!helper) {
+                return;
+            }
+
+            const actual = node.params?.length ?? 0;
+
+            // A bare `{{foo}}` mustache with no args is a data binding reference,
+            // not an invocation — leave arity validation to actual calls.
+            if (
+                actual === 0 &&
+                node.type !== 'HbsBlockStatement' &&
+                node.type !== 'SubExpression'
+            ) {
+                return;
+            }
+
+            const { required, max } = arityOf(helper);
+            if (actual < required) {
+                context.report({
+                    node,
+                    messageId: 'tooFewArgs',
+                    data: { name: helper.name, min: String(required), actual: String(actual) },
+                });
+                return;
+            }
+            if (actual > max) {
+                context.report({
+                    node,
+                    messageId: 'tooManyArgs',
+                    data: { name: helper.name, max: String(max), actual: String(actual) },
+                });
+            }
+        }
+
+        return {
+            MustacheStatement: check,
+            SubExpression: check,
+            HbsBlockStatement: check,
+        };
+    },
+};

package/src/rules/hbs/helper-too-new-for-target.js

@@ -0,0 +1,94 @@
+import { getHelper } from 'handlebars-data';
+
+import { simpleHelperName, isInvocation } from './_shared.js';
+
+/**
+ * Flags known Handlebars helpers whose introducing Marketing Cloud Next API
+ * version (`mcnSince`) is newer than the API version the template targets.
+ *
+ * For example, `dateAdd` first shipped in MCN API version 67 (Summer '26); using
+ * it while targeting API version 65 (Winter '26) is reported.
+ *
+ * The target API version is configured via the `apiVersion` option. When it is
+ * omitted, no helper is flagged (all helpers are considered available).
+ */
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Disallow Handlebars helpers newer than the targeted Marketing Cloud Next API version',
+            recommended: true,
+        },
+        messages: {
+            helperTooNew:
+                "'{{name}}' was introduced in Marketing Cloud Next API version {{since}}, which is newer than the targeted version {{target}}.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    apiVersion: {
+                        type: 'number',
+                        description:
+                            'The targeted Marketing Cloud Next API version (e.g. 65 = Winter \u{2019}26, 67 = Summer \u{2019}26). Helpers newer than this are flagged.',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+
+    create(context) {
+        const options = context.options[0] ?? {};
+        const apiVersion = typeof options.apiVersion === 'number' ? options.apiVersion : null;
+        if (apiVersion === null) {
+            return {};
+        }
+
+        /**
+         * Reports a helper when its introducing version exceeds the target.
+         *
+         * @param {object} node - The AST node.
+         * @param {string | null} helperName - The simple helper name, when any.
+         * @returns {void}
+         */
+        function check(node, helperName) {
+            if (!helperName) {
+                return;
+            }
+            const helper = getHelper(helperName);
+            if (helper && helper.mcnSince > apiVersion) {
+                context.report({
+                    node,
+                    messageId: 'helperTooNew',
+                    data: {
+                        name: helper.name,
+                        since: String(helper.mcnSince),
+                        target: String(apiVersion),
+                    },
+                });
+            }
+        }
+
+        /**
+         * Checks an inline mustache or subexpression invocation.
+         *
+         * @param {object} node - The AST node.
+         * @returns {void}
+         */
+        function checkInline(node) {
+            if (isInvocation(node)) {
+                check(node, simpleHelperName(node.path));
+            }
+        }
+
+        return {
+            MustacheStatement: checkInline,
+            SubExpression: checkInline,
+            HbsBlockStatement(node) {
+                check(node, simpleHelperName(node.path));
+            },
+        };
+    },
+};

package/src/rules/hbs/no-unknown-binding.js

@@ -0,0 +1,74 @@
+import { isBuiltinBinding, BUILTIN_BINDINGS } from 'handlebars-data';
+
+import { BINDING_PATTERN, closestMatch } from './_shared.js';
+
+/**
+ * Flags `{!$namespace.Field}` built-in data bindings that are not recognized
+ * Marketing Cloud Next data bindings.
+ *
+ * The Handlebars parser treats `{!$...}` tokens as literal content, so this rule
+ * scans the raw source text with a regex pass (mirroring the
+ * `handlebars/unknown-binding` diagnostic emitted by sfmc-language-lsp) rather
+ * than walking the AST.
+ */
+
+/** Proper-cased built-in binding names, used for "did you mean" suggestions. */
+const BINDING_NAME_LIST = BUILTIN_BINDINGS.map((b) => b.name);
+/** Map from lowercase binding name to its `{!$...}` token, for suggestion text. */
+const BINDING_TOKEN_BY_NAME = new Map(BUILTIN_BINDINGS.map((b) => [b.name.toLowerCase(), b.token]));
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Disallow unknown {!$...} built-in data bindings in Marketing Cloud Next Handlebars',
+            recommended: true,
+        },
+        messages: {
+            unknownBinding:
+                "Unknown built-in binding '{{token}}'. It is not a recognized Marketing Cloud Next data binding.",
+            unknownBindingSuggest:
+                "Unknown built-in binding '{{token}}'. It is not a recognized Marketing Cloud Next data binding. Did you mean '{{suggestion}}'?",
+        },
+        schema: [],
+    },
+
+    create(context) {
+        const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+        return {
+            'Program:exit'() {
+                const text = sourceCode.getText();
+                BINDING_PATTERN.lastIndex = 0;
+                let match;
+                while ((match = BINDING_PATTERN.exec(text)) !== null) {
+                    const bindingName = match[1];
+                    if (isBuiltinBinding(bindingName)) {
+                        continue;
+                    }
+                    const token = match[0];
+                    const start = match.index;
+                    const end = start + token.length;
+                    const loc = {
+                        start: sourceCode.getLocFromIndex(start),
+                        end: sourceCode.getLocFromIndex(end),
+                    };
+                    const suggestionName = closestMatch(bindingName, BINDING_NAME_LIST);
+                    const suggestion = suggestionName
+                        ? BINDING_TOKEN_BY_NAME.get(suggestionName.toLowerCase())
+                        : undefined;
+                    if (suggestion) {
+                        context.report({
+                            loc,
+                            messageId: 'unknownBindingSuggest',
+                            data: { token, suggestion },
+                        });
+                    } else {
+                        context.report({ loc, messageId: 'unknownBinding', data: { token } });
+                    }
+                }
+            },
+        };
+    },
+};