eslint-plugin-sfmc 2.6.1 → 4.0.0

package/src/rules/amp/no-mcn-unsupported.js

@@ -0,0 +1,102 @@
+import { functionNames, functionLookup, getMcnApiVersion } from 'ampscript-data';
+
+/**
+ * Flags AMPscript functions that cannot be used when targeting Marketing Cloud
+ * Next, and functions that work in MCN AMPscript but have no Handlebars
+ * equivalent (so they block a Handlebars migration).
+ *
+ * Each function carries an `mcnSince` value = the MCN API version it first
+ * became available in, or `null`/unset when it was never supported in MCN.
+ *
+ * `apiVersion` semantics (shared with the SSJS and Handlebars MCN rules):
+ *   - Not set / null: flag every function whose `mcnSince` is null/unset. Any
+ *     function supported at some point in MCN (numeric `mcnSince`) passes.
+ *   - Set to N: flag everything the null case flags, PLUS everything whose
+ *     `mcnSince` is greater than N (too new for the target). Pass iff
+ *     `mcnSince != null && mcnSince <= N`.
+ *
+ * Unknown-function reporting stays in `amp-no-unknown-function`; this rule only
+ * evaluates functions that exist in the AMPscript catalog.
+ */
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Disallow AMPscript functions that are not available in the targeted Marketing Cloud Next API version',
+            recommended: true,
+        },
+        messages: {
+            notSupportedInMcn: "'{{name}}' is not supported in Marketing Cloud Next.",
+            tooNewForTarget:
+                "'{{name}}' was introduced in Marketing Cloud Next API version {{since}}, which is newer than the targeted version {{target}}.",
+            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: [
+            {
+                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). Functions newer than this are flagged.',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+
+    create(context) {
+        const options = context.options[0] ?? {};
+        const apiVersion = typeof options.apiVersion === 'number' ? options.apiVersion : null;
+
+        return {
+            FunctionCall(node) {
+                const lower = node.name.toLowerCase();
+
+                // Unknown functions are handled by amp-no-unknown-function.
+                if (!functionNames.has(lower)) {
+                    return;
+                }
+
+                const since = getMcnApiVersion(lower);
+
+                // Never supported in MCN → always flag.
+                if (since === null) {
+                    context.report({
+                        node,
+                        messageId: 'notSupportedInMcn',
+                        data: { name: node.name },
+                    });
+                    return;
+                }
+
+                // Supported in MCN but newer than the targeted API version.
+                if (apiVersion !== null && since > apiVersion) {
+                    context.report({
+                        node,
+                        messageId: 'tooNewForTarget',
+                        data: {
+                            name: node.name,
+                            since: String(since),
+                            target: String(apiVersion),
+                        },
+                    });
+                    return;
+                }
+
+                // Works in MCN AMPscript but has no Handlebars counterpart, so it
+                // cannot be migrated to a Handlebars helper.
+                if (functionLookup.get(lower)?.mcnHandlebarsGap === true) {
+                    context.report({
+                        node,
+                        messageId: 'noHandlebarsEquivalent',
+                        data: { name: node.name },
+                    });
+                }
+            },
+        };
+    },
+};

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

@@ -1,12 +1,16 @@
 // The processor extracts each AMPscript region into its own virtual .amp file,
 // including the outer delimiters (%%[...]/%%] or <script>...</script>).
-// Any %%[ or %%= found INSIDE the outer delimiters is nested and invalid.
-const DELIMITER_RE = /%%\[|%%=/g;
+// Any %%[ or %%= found INSIDE an already-open block is nested and invalid.
+//
+// A raw .amp file may contain several *sibling* blocks (e.g. one %%[...]%% block
+// followed by another). Those are not nested. To distinguish nesting from
+// siblings we scan every open/close token in document order and track depth:
+// an opener is only nested when depth > 0.
+const TOKEN_RE = /%%\[|%%=|\]%%|=%%/g;
 const SCRIPT_TAG_RE = /^[\n]*<script\b/i;
-const BLOCK_OPEN_RE = /^[\n]*(%%\[)/;
-const INLINE_OPEN_RE = /^[\n]*(%%=)/;
-const BLOCK_CLOSE_SUFFIX = ']%%';
-const INLINE_CLOSE_SUFFIX = '=%%';
+
+const OPEN_TOKENS = new Set(['%%[', '%%=']);
+const CLOSE_FOR_OPEN = { '%%[': ']%%', '%%=': '=%%' };
 
 export default {
     meta: {
@@ -25,76 +29,64 @@ export default {
     },
 
     create(context) {
+        const sourceCode = context.sourceCode;
+
+        const reportNested = (text, match, isScriptBlock) => {
+            const delimiter = match[0];
+            const start = match.index;
+            const end = start + delimiter.length;
+            const closeToken = CLOSE_FOR_OPEN[delimiter];
+            const closeIndex = text.indexOf(closeToken, end);
+
+            context.report({
+                loc: {
+                    start: sourceCode.getLocFromIndex(start),
+                    end: sourceCode.getLocFromIndex(end),
+                },
+                messageId: isScriptBlock ? 'nestedDelimiterInScript' : 'nestedDelimiter',
+                data: { delimiter },
+                fix:
+                    closeIndex === -1
+                        ? (fixer) => fixer.removeRange([start, end])
+                        : (fixer) => [
+                              fixer.removeRange([closeIndex, closeIndex + closeToken.length]),
+                              fixer.removeRange([start, end]),
+                          ],
+            });
+        };
+
         return {
             Program() {
-                const sourceCode = context.sourceCode;
                 const text = sourceCode.getText();
                 const isScriptBlock = SCRIPT_TAG_RE.test(text);
 
-                // For %%[...]%% and %%=...=%% blocks the processor includes the outer
-                // delimiters. Record their positions so we can skip the outermost ones.
-                let outerOpenStart = -1;
-                let outerCloseStart = -1;
-                let outerCloseSuffix = BLOCK_CLOSE_SUFFIX;
-
-                if (!isScriptBlock) {
-                    const blockOpenMatch = BLOCK_OPEN_RE.exec(text);
-                    const inlineOpenMatch = INLINE_OPEN_RE.exec(text);
-
-                    if (blockOpenMatch) {
-                        outerOpenStart = blockOpenMatch.index + blockOpenMatch[0].length - 3;
-                        outerCloseSuffix = BLOCK_CLOSE_SUFFIX;
-                    } else if (inlineOpenMatch) {
-                        outerOpenStart = inlineOpenMatch.index + inlineOpenMatch[0].length - 3;
-                        outerCloseSuffix = INLINE_CLOSE_SUFFIX;
-                    }
-
-                    // The outer close is the last occurrence of the matching close token
-                    const lastClose = text.lastIndexOf(outerCloseSuffix);
-                    if (lastClose !== -1) {
-                        outerCloseStart = lastClose;
+                if (isScriptBlock) {
+                    // Inside a <script language="ampscript"> block the whole body is
+                    // already AMPscript; every %%[ / %%= delimiter is redundant.
+                    TOKEN_RE.lastIndex = 0;
+                    let match;
+                    while ((match = TOKEN_RE.exec(text)) !== null) {
+                        if (OPEN_TOKENS.has(match[0])) {
+                            reportNested(text, match, true);
+                        }
                     }
+                    return;
                 }
 
-                DELIMITER_RE.lastIndex = 0;
+                // Depth-based scan for raw %%[...]%% / %%=...=%% content. Sibling blocks
+                // return depth to 0 between them, so their openers are not flagged.
+                let depth = 0;
+                TOKEN_RE.lastIndex = 0;
                 let match;
-                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;
+                while ((match = TOKEN_RE.exec(text)) !== null) {
+                    if (OPEN_TOKENS.has(match[0])) {
+                        if (depth > 0) {
+                            reportNested(text, match, false);
+                        }
+                        depth++;
+                    } else {
+                        depth = Math.max(0, depth - 1);
                     }
-
-                    const closeToken = delimiter === '%%[' ? ']%%' : '=%%';
-
-                    // Find the matching close token for the fix (first occurrence after this open)
-                    let closeIndex = text.indexOf(closeToken, end);
-                    // Don't use the outer ]%% as the fix target for an inner %%[
-                    if (!isScriptBlock && closeIndex === outerCloseStart) {
-                        closeIndex = -1;
-                    }
-
-                    context.report({
-                        loc: {
-                            start: sourceCode.getLocFromIndex(start),
-                            end: sourceCode.getLocFromIndex(end),
-                        },
-                        messageId: isScriptBlock ? 'nestedDelimiterInScript' : 'nestedDelimiter',
-                        data: { delimiter },
-                        fix:
-                            closeIndex === -1
-                                ? (fixer) => fixer.removeRange([start, end])
-                                : (fixer) => [
-                                      fixer.removeRange([
-                                          closeIndex,
-                                          closeIndex + closeToken.length,
-                                      ]),
-                                      fixer.removeRange([start, end]),
-                                  ],
-                    });
                 }
             },
         };

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}]/gu;
 
 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 {
@@ -30,7 +30,7 @@ export default {
         fixable: 'code',
         docs: {
             description:
-                'Disallow smart/curly quotes in string literals (AMPscript requires ASCII quotes)',
+                'Disallow smart/curly quotes in AMPscript (AMPscript requires ASCII quotes)',
             recommended: true,
         },
         messages: {
@@ -41,36 +41,30 @@ export default {
     },
 
     create(context) {
+        const sourceCode = context.sourceCode;
+
         return {
-            StringLiteral(node) {
-                if (SMART_QUOTE_RE.test(node.value)) {
-                    for (const [char, kind] of Object.entries(SMART_QUOTES)) {
-                        if (node.value.includes(char)) {
-                            context.report({
-                                node,
-                                messageId: 'smartQuote',
-                                data: { kind },
-                                fix(fixer) {
-                                    const fixed = node.value.replaceAll(
-                                        /[\u2018\u2019\u201C\u201D\u201A\u201E\u2039\u203A]/g,
-                                        (c) => SMART_TO_ASCII[c],
-                                    );
-                                    const q = node.quote;
-                                    // If the replacement introduces the outer delimiter, try switching quotes.
-                                    if (fixed.includes(q)) {
-                                        const other = q === '"' ? "'" : '"';
-                                        if (!fixed.includes(other)) {
-                                            return fixer.replaceText(node, other + fixed + other);
-                                        }
-                                        // Both quote chars present — cannot safely auto-fix.
-                                        return null;
-                                    }
-                                    return fixer.replaceText(node, q + fixed + q);
-                                },
-                            });
-                            return;
-                        }
-                    }
+            // The AMPscript parser tokenizes string literals as RAW + IDENTIFIER
+            // tokens rather than a StringLiteral node, so a node listener never
+            // matches. Scan the virtual .amp region's raw text instead — the whole
+            // extracted file is AMPscript, mirroring the LSP smart-quote check.
+            Program() {
+                const text = sourceCode.getText();
+                SMART_QUOTE_RE.lastIndex = 0;
+                let match;
+                while ((match = SMART_QUOTE_RE.exec(text)) !== null) {
+                    const char = match[0];
+                    const start = match.index;
+                    const end = start + char.length;
+                    context.report({
+                        loc: {
+                            start: sourceCode.getLocFromIndex(start),
+                            end: sourceCode.getLocFromIndex(end),
+                        },
+                        messageId: 'smartQuote',
+                        data: { kind: SMART_QUOTES[char] },
+                        fix: (fixer) => fixer.replaceTextRange([start, end], SMART_TO_ASCII[char]),
+                    });
                 }
             },
         };

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

@@ -1,4 +1,4 @@
-import { functionNames, isMcnSupported } from 'ampscript-data';
+import { functionNames } from 'ampscript-data';
 
 export default {
     meta: {
@@ -11,28 +11,11 @@ export default {
         messages: {
             unknownFunction:
                 "'{{name}}' is not a recognized AMPscript function. AMPscript does not support custom functions.",
-            notSupportedInMcn: "'{{name}}' is not supported in Marketing Cloud Next.",
         },
-        schema: [
-            {
-                type: 'object',
-                properties: {
-                    target: {
-                        type: 'string',
-                        enum: ['engagement', 'next'],
-                        description:
-                            "Target platform. Set to 'next' to additionally flag functions not available in Marketing Cloud Next.",
-                    },
-                },
-                additionalProperties: false,
-            },
-        ],
+        schema: [],
     },
 
     create(context) {
-        const options = context.options[0] ?? {};
-        const targetNext = options.target === 'next';
-
         return {
             FunctionCall(node) {
                 const lower = node.name.toLowerCase();
@@ -43,15 +26,6 @@ export default {
                         messageId: 'unknownFunction',
                         data: { name: node.name },
                     });
-                    return;
-                }
-
-                if (targetNext && !isMcnSupported(lower)) {
-                    context.report({
-                        node,
-                        messageId: 'notSupportedInMcn',
-                        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;
+}