eslint-plugin-sfmc 2.6.1 → 4.0.0

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/no-mcn-unsupported.js

@@ -0,0 +1,164 @@
+import { getHelper, bindingLookup } from 'handlebars-data';
+
+import { simpleHelperName, isInvocation, BINDING_PATTERN } from './_shared.js';
+
+/**
+ * Flags Handlebars helpers and `{!$...}` data bindings that are not available in
+ * the targeted Marketing Cloud Next API version.
+ *
+ * Each helper/binding 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 AMPscript and SSJS MCN rules):
+ *   - Not set / null: flag every helper/binding whose `mcnSince` is null/unset.
+ *     Any item 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`.
+ *
+ * The MCN Handlebars catalog currently has no null-`mcnSince` items, so with no
+ * `apiVersion` set nothing is flagged; e.g. `apiVersion: 65` flags the helpers
+ * introduced in 67, and `apiVersion: 40` flags every helper and binding.
+ */
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Disallow Handlebars helpers and bindings not available in the targeted Marketing Cloud Next API version',
+            recommended: true,
+        },
+        messages: {
+            helperNotSupported: "'{{name}}' is not supported in Marketing Cloud Next Handlebars.",
+            helperTooNew:
+                "'{{name}}' was introduced in Marketing Cloud Next API version {{since}}, which is newer than the targeted version {{target}}.",
+            bindingNotSupported: "'{{token}}' is not supported in Marketing Cloud Next Handlebars.",
+            bindingTooNew:
+                "'{{token}}' 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 and bindings newer than this are flagged.',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+
+    create(context) {
+        const options = context.options[0] ?? {};
+        const apiVersion = typeof options.apiVersion === 'number' ? options.apiVersion : null;
+
+        /**
+         * Returns true when an item's `mcnSince` fails the target: it is null
+         * (never supported) or newer than the targeted API version.
+         *
+         * @param {number | null | undefined} since - The item's `mcnSince`.
+         * @returns {boolean} True when the item must be flagged.
+         */
+        function isUnsupported(since) {
+            if (since === null || since === undefined) {
+                return true;
+            }
+            return apiVersion !== null && since > apiVersion;
+        }
+
+        /**
+         * Reports a helper when it is unavailable for the target.
+         *
+         * @param {object} node - The AST node.
+         * @param {string | null} helperName - The simple helper name, when any.
+         * @returns {void}
+         */
+        function checkHelper(node, helperName) {
+            if (!helperName) {
+                return;
+            }
+            const helper = getHelper(helperName);
+            if (!helper) {
+                return;
+            }
+            const since = helper.mcnSince ?? null;
+            if (!isUnsupported(since)) {
+                return;
+            }
+            if (since === null) {
+                context.report({
+                    node,
+                    messageId: 'helperNotSupported',
+                    data: { name: helper.name },
+                });
+            } else {
+                context.report({
+                    node,
+                    messageId: 'helperTooNew',
+                    data: {
+                        name: helper.name,
+                        since: String(since),
+                        target: String(apiVersion),
+                    },
+                });
+            }
+        }
+
+        /**
+         * Checks an inline mustache or subexpression helper invocation.
+         *
+         * @param {object} node - The AST node.
+         * @returns {void}
+         */
+        function checkInline(node) {
+            if (isInvocation(node)) {
+                checkHelper(node, simpleHelperName(node.path));
+            }
+        }
+
+        return {
+            MustacheStatement: checkInline,
+            SubExpression: checkInline,
+            HbsBlockStatement(node) {
+                checkHelper(node, simpleHelperName(node.path));
+            },
+            'Program:exit'() {
+                const sourceCode = context.sourceCode ?? context.getSourceCode();
+                const text = sourceCode.getText();
+                BINDING_PATTERN.lastIndex = 0;
+                let match;
+                while ((match = BINDING_PATTERN.exec(text)) !== null) {
+                    const bindingName = match[1];
+                    const binding = bindingLookup.get(bindingName.toLowerCase());
+                    // Unknown bindings are handled by hbs-no-unknown-binding.
+                    if (!binding) {
+                        continue;
+                    }
+                    const since = binding.mcnSince ?? null;
+                    if (!isUnsupported(since)) {
+                        continue;
+                    }
+                    const token = match[0];
+                    const start = match.index;
+                    const end = start + token.length;
+                    const loc = {
+                        start: sourceCode.getLocFromIndex(start),
+                        end: sourceCode.getLocFromIndex(end),
+                    };
+                    if (since === null) {
+                        context.report({ loc, messageId: 'bindingNotSupported', data: { token } });
+                    } else {
+                        context.report({
+                            loc,
+                            messageId: 'bindingTooNew',
+                            data: { token, since: String(since), target: String(apiVersion) },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

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 } });
+                    }
+                }
+            },
+        };
+    },
+};

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

@@ -0,0 +1,79 @@
+import { isHelper, helperNames } from 'handlebars-data';
+
+import { simpleHelperName, isInvocation, closestMatch } from './_shared.js';
+
+/**
+ * Flags Handlebars helper invocations whose name is not part of the Marketing
+ * Cloud Next catalog. The MCN engine is locked down and cannot register custom
+ * helpers, so any unknown helper is reported.
+ *
+ * Mirrors the `handlebars/unknown-helper` diagnostic emitted by
+ * sfmc-language-lsp. A bare `{{foo}}` mustache with no arguments is treated as a
+ * data binding (not a helper) and is not flagged here.
+ */
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Disallow Handlebars helper invocations that are not part of the Marketing Cloud Next catalog',
+            recommended: true,
+        },
+        messages: {
+            unknownHelper:
+                "Unknown Handlebars {{kind}} '{{name}}'. It is not part of the Marketing Cloud Next catalog, and the MCN engine cannot register custom helpers.",
+            unknownHelperSuggest:
+                "Unknown Handlebars {{kind}} '{{name}}'. It is not part of the Marketing Cloud Next catalog, and the MCN engine cannot register custom helpers. Did you mean '{{suggestion}}'?",
+        },
+        schema: [],
+    },
+
+    create(context) {
+        /**
+         * Reports an unknown helper, attaching a "did you mean" suggestion when
+         * a close catalog match exists.
+         *
+         * @param {object} node - The offending AST node.
+         * @param {string} name - The unknown helper name.
+         * @param {boolean} isBlock - True when the node is a block helper.
+         * @returns {void}
+         */
+        function reportUnknown(node, name, isBlock) {
+            const kind = isBlock ? 'block helper' : 'helper';
+            const suggestion = closestMatch(name, helperNames);
+            if (suggestion) {
+                context.report({
+                    node,
+                    messageId: 'unknownHelperSuggest',
+                    data: { kind, name, suggestion },
+                });
+            } else {
+                context.report({ node, messageId: 'unknownHelper', data: { kind, name } });
+            }
+        }
+
+        /**
+         * Checks an inline mustache or subexpression invocation.
+         *
+         * @param {object} node - The AST node.
+         * @returns {void}
+         */
+        function checkInline(node) {
+            const helperName = simpleHelperName(node.path);
+            if (helperName && isInvocation(node) && !isHelper(helperName)) {
+                reportUnknown(node, helperName, false);
+            }
+        }
+
+        return {
+            MustacheStatement: checkInline,
+            SubExpression: checkInline,
+            HbsBlockStatement(node) {
+                const helperName = simpleHelperName(node.path);
+                if (helperName && !isHelper(helperName)) {
+                    reportUnknown(node, helperName, true);
+                }
+            },
+        };
+    },
+};

package/src/rules/hbs/no-unsupported-construct.js

@@ -0,0 +1,70 @@
+import { unsupportedByNodeType } from 'handlebars-data';
+
+import { simpleHelperName } from './_shared.js';
+
+/**
+ * Flags Handlebars constructs that the locked-down Marketing Cloud Next engine
+ * cannot support: partials, partial blocks, decorators, inline partials, and the
+ * handlebars.js-only `{{log}}` debugging helper.
+ *
+ * Mirrors the `handlebars/unsupported-construct` diagnostic emitted by
+ * sfmc-language-lsp.
+ */
+
+/** AST node types that may carry an unsupported construct. */
+const NODE_TYPES = unsupportedByNodeType.keys().toArray();
+
+// The handlebars-data messages contain literal `{{> ...}}`, `{{log}}`, etc. as
+// examples. ESLint treats `{{...}}` in a message template as an interpolation
+// placeholder, so the literal text is passed through a single `{{text}}`
+// placeholder instead of being baked into the template.
+/** messageId per construct id → passthrough template, declared statically. */
+const MESSAGES = Object.fromEntries(
+    unsupportedByNodeType
+        .values()
+        .toArray()
+        .flat()
+        .map((entry) => [entry.id, '{{text}}']),
+);
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Disallow Handlebars constructs unsupported by the Marketing Cloud Next engine (partials, decorators, log)',
+            recommended: true,
+        },
+        messages: MESSAGES,
+        schema: [],
+    },
+
+    create(context) {
+        /**
+         * Reports the first unsupported-construct entry matching a node.
+         *
+         * @param {object} node - The Handlebars AST node.
+         * @returns {void}
+         */
+        function check(node) {
+            const candidates = unsupportedByNodeType.get(node.type);
+            if (!candidates) {
+                return;
+            }
+            const helperName = simpleHelperName(node.path);
+            for (const entry of candidates) {
+                if (entry.helperName !== null && entry.helperName !== helperName) {
+                    continue;
+                }
+                context.report({ node, messageId: entry.id, data: { text: entry.message } });
+                return;
+            }
+        }
+
+        const visitors = {};
+        for (const nodeType of NODE_TYPES) {
+            visitors[nodeType] = check;
+        }
+        return visitors;
+    },
+};

package/src/rules/ssjs/cache-loop-length.js

@@ -34,23 +34,23 @@ export default {
                     return;
                 }
 
-                let lengthExpr = null;
+                let lengthExpression = null;
                 if (containsMemberLength(test.right)) {
-                    lengthExpr = test.right;
+                    lengthExpression = test.right;
                 } else if (containsMemberLength(test.left)) {
-                    lengthExpr = test.left;
+                    lengthExpression = test.left;
                 }
 
-                if (!lengthExpr) {
+                if (!lengthExpression) {
                     return;
                 }
 
-                const fix = buildCacheFix(node, lengthExpr, context);
+                const fix = buildCacheFix(node, lengthExpression, context);
 
                 context.report({
                     node: test,
                     messageId: 'cacheLength',
-                    ...(fix ? { fix } : {}),
+                    ...(fix && { fix }),
                 });
             },
         };
@@ -61,17 +61,14 @@ function containsMemberLength(node) {
     if (!node) {
         return false;
     }
-    if (
+    return (
         node.type === 'MemberExpression' &&
         node.property.type === 'Identifier' &&
         node.property.name === 'length'
-    ) {
-        return true;
-    }
-    return false;
+    );
 }
 
-function buildCacheFix(forNode, lengthExpr, context) {
+function buildCacheFix(forNode, lengthExpression, context) {
     const init = forNode.init;
     // Only fix when init is a VariableDeclaration so we can safely
     // append a new declarator without restructuring the loop header.
@@ -79,14 +76,14 @@ function buildCacheFix(forNode, lengthExpr, context) {
         return null;
     }
 
-    const objText = context.sourceCode.getText(lengthExpr.object);
-    const lenVar = '_len';
+    const objectText = context.sourceCode.getText(lengthExpression.object);
+    const lengthVariable = '_len';
 
     return function fix(fixer) {
-        const lastDecl = init.declarations.at(-1);
+        const lastDeclaration = init.declarations.at(-1);
         return [
-            fixer.insertTextAfter(lastDecl, `, ${lenVar} = ${objText}.length`),
-            fixer.replaceText(lengthExpr, lenVar),
+            fixer.insertTextAfter(lastDeclaration, `, ${lengthVariable} = ${objectText}.length`),
+            fixer.replaceText(lengthExpression, lengthVariable),
         ];
     };
 }

package/src/rules/ssjs/no-deprecated-function.js

@@ -62,20 +62,20 @@ export default {
 
         return {
             VariableDeclaration(node) {
-                for (const decl of node.declarations) {
+                for (const declaration of node.declarations) {
                     if (
-                        decl.init &&
-                        decl.id &&
-                        decl.id.type === 'Identifier' &&
-                        isContentAreaObjInit(decl.init)
+                        declaration.init &&
+                        declaration.id &&
+                        declaration.id.type === 'Identifier' &&
+                        isContentAreaObjectInit(declaration.init)
                     ) {
-                        contentAreaVariables.add(decl.id.name);
+                        contentAreaVariables.add(declaration.id.name);
                     }
                 }
             },
 
             AssignmentExpression(node) {
-                if (node.left.type === 'Identifier' && isContentAreaObjInit(node.right)) {
+                if (node.left.type === 'Identifier' && isContentAreaObjectInit(node.right)) {
                     contentAreaVariables.add(node.left.name);
                 }
             },
@@ -166,7 +166,7 @@ export default {
  * @param {import('eslint').Rule.Node} node - AST node to inspect
  * @returns {boolean} true when the node is a ContentAreaObj.Init call
  */
-function isContentAreaObjInit(node) {
+function isContentAreaObjectInit(node) {
     if (!node || node.type !== 'CallExpression') {
         return false;
     }

package/src/rules/ssjs/no-hardcoded-credentials.js

@@ -29,9 +29,7 @@ export default {
             CallExpression(node) {
                 const callee = node.callee;
 
-                let functionName = null;
-
-                if (
+                const functionName =
                     callee.type === 'MemberExpression' &&
                     callee.object.type === 'MemberExpression' &&
                     callee.object.object.type === 'Identifier' &&
@@ -39,9 +37,8 @@ export default {
                     callee.object.property.type === 'Identifier' &&
                     callee.object.property.name === 'Function' &&
                     callee.property.type === 'Identifier'
-                ) {
-                    functionName = callee.property.name;
-                }
+                        ? callee.property.name
+                        : null;
 
                 if (!functionName || !ENCRYPT_FUNCTIONS.has(functionName.toLowerCase())) {
                     return;