eslint-plugin-sfmc 0.1.0

package/src/rules/ssjs/no-unknown-wsproxy-method.js

@@ -0,0 +1,71 @@
+/**
+ * Rule: no-unknown-wsproxy-method
+ *
+ * Flags calls to WSProxy instances where the method name does not
+ * exist in the known SFMC WSProxy method catalog.
+ */
+
+import { wsproxyMethodNames } from 'ssjs-data';
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow calls to unknown WSProxy methods',
+        },
+        messages: {
+            unknownMethod: "'{{name}}' is not a recognized WSProxy method.",
+        },
+        schema: [],
+    },
+
+    create(context) {
+        const wsproxyVariables = new Set();
+
+        return {
+            VariableDeclaration(node) {
+                for (const decl of node.declarations) {
+                    if (
+                        decl.id &&
+                        decl.id.type === 'Identifier' &&
+                        decl.init &&
+                        decl.init.type === 'NewExpression' &&
+                        decl.init.callee.type === 'Identifier' &&
+                        decl.init.callee.name === 'WSProxy'
+                    ) {
+                        wsproxyVariables.add(decl.id.name);
+                    }
+                }
+            },
+
+            AssignmentExpression(node) {
+                if (
+                    node.left.type === 'Identifier' &&
+                    node.right.type === 'NewExpression' &&
+                    node.right.callee.type === 'Identifier' &&
+                    node.right.callee.name === 'WSProxy'
+                ) {
+                    wsproxyVariables.add(node.left.name);
+                }
+            },
+
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== 'MemberExpression') return;
+                if (callee.object.type !== 'Identifier') return;
+                if (callee.property.type !== 'Identifier') return;
+
+                if (!wsproxyVariables.has(callee.object.name)) return;
+
+                const methodName = callee.property.name;
+                if (!wsproxyMethodNames.has(methodName.toLowerCase())) {
+                    context.report({
+                        node: callee.property,
+                        messageId: 'unknownMethod',
+                        data: { name: methodName },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/ssjs/no-unsupported-syntax.js

@@ -0,0 +1,122 @@
+/**
+ * Rule: no-unsupported-syntax
+ *
+ * Flags ES6+ syntax features that are not supported by SFMC's legacy
+ * ECMAScript engine. These features cause runtime errors in SFMC.
+ *
+ * Auto-fix: let/const declarations are rewritten to var (safe, 1:1 swap per
+ * Mateusz Dąbrowski's SSJS style guide).
+ *
+ * Suggestions:
+ *   - nullish coalescing (??) → replace with ||
+ *   - direct object literal return → extract to variable
+ */
+
+import { unsupportedByNodeType } from 'ssjs-data';
+
+// Features that can be safely auto-fixed without changing semantics.
+const AUTO_FIX = {
+    LetDeclaration: (node) => (fixer) =>
+        // "let" is 3 chars; the keyword starts at node.range[0].
+        fixer.replaceTextRange([node.range[0], node.range[0] + 3], 'var'),
+    ConstDeclaration: (node) => (fixer) =>
+        // "const" is 5 chars.
+        fixer.replaceTextRange([node.range[0], node.range[0] + 5], 'var'),
+};
+
+export default {
+    meta: {
+        type: 'problem',
+        fixable: 'code',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow ES6+ syntax features not supported by the SFMC SSJS engine',
+        },
+        messages: {
+            unsupported: '{{label}} are not supported in SFMC SSJS. {{suggestion}}',
+            suggestLogicalOr:
+                "Replace ?? with || (note: semantics differ for falsy values like 0, '', and false)",
+            suggestVarReturn:
+                'Assign the object to a variable, then return the variable',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allow: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        uniqueItems: true,
+                        description:
+                            "Feature names to allow (e.g. ['LetDeclaration', 'ConstDeclaration']).",
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+
+    create(context) {
+        const options = context.options[0] || {};
+        const allowed = new Set(options.allow || []);
+
+        const listeners = {};
+
+        for (const [nodeType, entries] of unsupportedByNodeType) {
+            listeners[nodeType] = function (node) {
+                for (const entry of entries) {
+                    if (allowed.has(entry.feature)) continue;
+                    if (entry.test && !entry.test(node)) continue;
+
+                    const report = {
+                        node,
+                        messageId: 'unsupported',
+                        data: {
+                            label: entry.label,
+                            suggestion: entry.suggestion,
+                        },
+                    };
+
+                    if (entry.feature in AUTO_FIX) {
+                        report.fix = AUTO_FIX[entry.feature](node);
+                    } else if (entry.feature === 'NullishCoalescing') {
+                        report.suggest = [
+                            {
+                                messageId: 'suggestLogicalOr',
+                                fix(fixer) {
+                                    const src = context.sourceCode.getText();
+                                    const between = src.slice(
+                                        node.left.range[1],
+                                        node.right.range[0],
+                                    );
+                                    const offset = between.indexOf('??');
+                                    if (offset === -1) return null;
+                                    const start = node.left.range[1] + offset;
+                                    return fixer.replaceTextRange([start, start + 2], '||');
+                                },
+                            },
+                        ];
+                    } else if (entry.feature === 'DirectObjectReturn') {
+                        report.suggest = [
+                            {
+                                messageId: 'suggestVarReturn',
+                                fix(fixer) {
+                                    const objText = context.sourceCode.getText(node.argument);
+                                    const indent = ' '.repeat(node.loc.start.column);
+                                    return fixer.replaceText(
+                                        node,
+                                        `var _result = ${objText};\n${indent}return _result;`,
+                                    );
+                                },
+                            },
+                        ];
+                    }
+
+                    context.report(report);
+                }
+            };
+        }
+
+        return listeners;
+    },
+};

package/src/rules/ssjs/platform-function-arity.js

@@ -0,0 +1,70 @@
+/**
+ * Rule: platform-function-arity
+ *
+ * Enforces correct argument counts for Platform.Function.* calls
+ * using arity metadata from ssjs-data.
+ */
+
+import { platformFunctionLookup } from 'ssjs-data';
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Enforce correct argument counts for Platform.Function methods',
+        },
+        messages: {
+            tooFewArgs:
+                "'Platform.Function.{{name}}' requires at least {{min}} argument(s) but was called with {{actual}}.",
+            tooManyArgs:
+                "'Platform.Function.{{name}}' accepts at most {{max}} argument(s) but was called with {{actual}}.",
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== 'MemberExpression') return;
+
+                if (
+                    callee.object.type === 'MemberExpression' &&
+                    callee.object.object.type === 'Identifier' &&
+                    callee.object.object.name === 'Platform' &&
+                    callee.object.property.type === 'Identifier' &&
+                    callee.object.property.name === 'Function' &&
+                    callee.property.type === 'Identifier'
+                ) {
+                    const methodName = callee.property.name;
+                    const entry = platformFunctionLookup.get(methodName.toLowerCase());
+                    if (!entry) return;
+
+                    const actual = node.arguments.length;
+
+                    if (actual < entry.minArgs) {
+                        context.report({
+                            node: callee.property,
+                            messageId: 'tooFewArgs',
+                            data: {
+                                name: entry.name,
+                                min: String(entry.minArgs),
+                                actual: String(actual),
+                            },
+                        });
+                    } else if (actual > entry.maxArgs) {
+                        context.report({
+                            node: callee.property,
+                            messageId: 'tooManyArgs',
+                            data: {
+                                name: entry.name,
+                                max: String(entry.maxArgs),
+                                actual: String(actual),
+                            },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/src/rules/ssjs/prefer-parsejson-safe-arg.js

@@ -0,0 +1,94 @@
+/**
+ * Rule: prefer-parsejson-safe-arg
+ *
+ * Platform.Function.ParseJSON() throws a 500 if the argument is undefined or
+ * not a string. Concatenating an empty string (someVar + '') is a common SFMC
+ * pattern to guard against this.
+ *
+ * Auto-fix: wraps the argument with `(arg + '')`.
+ */
+
+export default {
+    meta: {
+        type: 'problem',
+        fixable: 'code',
+        docs: {
+            description:
+                "Require concatenating an empty string to Platform.Function.ParseJSON() arguments to prevent 500 errors",
+        },
+        messages: {
+            unsafeArg:
+                "Platform.Function.ParseJSON() may throw a 500 if the argument is undefined. " +
+                "Concatenate an empty string to be safe: ParseJSON({{argText}} + '').",
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (!isParseJSONCall(node)) return;
+                if (node.arguments.length === 0) return;
+
+                const arg = node.arguments[0];
+
+                if (isAlreadySafe(arg)) return;
+
+                context.report({
+                    node: arg,
+                    messageId: 'unsafeArg',
+                    data: { argText: context.sourceCode.getText(arg) },
+                    fix(fixer) {
+                        const argText = context.sourceCode.getText(arg);
+                        return fixer.replaceText(arg, `${argText} + ''`);
+                    },
+                });
+            },
+        };
+    },
+};
+
+function isParseJSONCall(node) {
+    const callee = node.callee;
+
+    // ParseJSON(...)
+    if (callee.type === 'Identifier' && callee.name === 'ParseJSON') {
+        return true;
+    }
+
+    // Platform.Function.ParseJSON(...)
+    if (
+        callee.type === 'MemberExpression' &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'ParseJSON' &&
+        callee.object.type === 'MemberExpression' &&
+        callee.object.property.type === 'Identifier' &&
+        callee.object.property.name === 'Function' &&
+        callee.object.object.type === 'Identifier' &&
+        callee.object.object.name === 'Platform'
+    ) {
+        return true;
+    }
+
+    return false;
+}
+
+function isAlreadySafe(arg) {
+    // arg + ''  or  '' + arg
+    if (arg.type === 'BinaryExpression' && arg.operator === '+') {
+        if (isEmptyString(arg.left) || isEmptyString(arg.right)) {
+            return true;
+        }
+    }
+
+    // String literal passed directly — already a string
+    if (arg.type === 'Literal' && typeof arg.value === 'string') {
+        return true;
+    }
+
+    return false;
+}
+
+function isEmptyString(node) {
+    return node.type === 'Literal' && node.value === '';
+}

package/src/rules/ssjs/prefer-platform-load-version.js

@@ -0,0 +1,96 @@
+/**
+ * Rule: prefer-platform-load-version
+ *
+ * Warns when Platform.Load("Core", version) uses a version string other
+ * than the recommended "1.1.5". Older versions like "1" or "1.1.1" miss
+ * bug-fixes and features available in the latest Core library release.
+ */
+
+const DEFAULT_VERSION = '1.1.5';
+
+export default {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce a minimum version string in Platform.Load() calls',
+        },
+        fixable: 'code',
+        messages: {
+            outdatedVersion:
+                'Platform.Load("Core", "{{actual}}") should use version "{{expected}}" to get the latest bug-fixes. Update the second argument.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    version: {
+                        type: 'string',
+                        description: 'The recommended Core library version string.',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+
+    create(context) {
+        const options = context.options[0] || {};
+        const expectedVersion = options.version || DEFAULT_VERSION;
+
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (
+                    callee.type !== 'MemberExpression' ||
+                    callee.object.type !== 'Identifier' ||
+                    callee.object.name !== 'Platform' ||
+                    callee.property.type !== 'Identifier' ||
+                    callee.property.name !== 'Load'
+                ) {
+                    return;
+                }
+
+                const arguments_ = node.arguments;
+                if (
+                    arguments_.length === 0 ||
+                    arguments_[0].type !== 'Literal' ||
+                    typeof arguments_[0].value !== 'string' ||
+                    arguments_[0].value.toLowerCase() !== 'core'
+                ) {
+                    return;
+                }
+
+                if (arguments_.length < 2) {
+                    context.report({
+                        node,
+                        messageId: 'outdatedVersion',
+                        data: { actual: '(none)', expected: expectedVersion },
+                        fix(fixer) {
+                            return fixer.insertTextAfter(
+                                arguments_[0],
+                                `, "${expectedVersion}"`,
+                            );
+                        },
+                    });
+                    return;
+                }
+
+                const versionArgument = arguments_[1];
+                if (
+                    versionArgument.type === 'Literal' &&
+                    typeof versionArgument.value === 'string' &&
+                    versionArgument.value !== expectedVersion
+                ) {
+                    context.report({
+                        node: versionArgument,
+                        messageId: 'outdatedVersion',
+                        data: { actual: versionArgument.value, expected: expectedVersion },
+                        fix(fixer) {
+                            return fixer.replaceText(versionArgument, `"${expectedVersion}"`);
+                        },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/ssjs/require-hasownproperty.js

@@ -0,0 +1,142 @@
+/**
+ * Rule: require-hasownproperty
+ *
+ * In for-in loops, require a hasOwnProperty guard to avoid iterating
+ * over inherited properties (like _type) that SSJS objects may have.
+ *
+ * Suggestion: wraps the existing loop body in an
+ * `if (obj.hasOwnProperty(key)) { ... }` guard.
+ */
+
+export default {
+    meta: {
+        type: 'suggestion',
+        hasSuggestions: true,
+        docs: {
+            description: 'Require hasOwnProperty guard in for-in loops',
+        },
+        messages: {
+            missingGuard:
+                'Add a hasOwnProperty check inside for-in loops to avoid iterating over inherited properties.',
+            suggestAddGuard:
+                'Wrap the loop body in an `if ({{obj}}.hasOwnProperty({{key}})) { ... }` guard',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            ForInStatement(node) {
+                const body = node.body;
+
+                const stmts = body.type === 'BlockStatement' ? body.body : [body];
+
+                if (stmts.length === 0) return;
+
+                const hasGuard = stmts.some((stmt) => containsHasOwnProperty(stmt));
+
+                if (!hasGuard) {
+                    const keyName = getKeyName(node.left);
+                    const objText = context.sourceCode.getText(node.right);
+
+                    context.report({
+                        node,
+                        messageId: 'missingGuard',
+                        suggest:
+                            keyName
+                                ? [
+                                      {
+                                          messageId: 'suggestAddGuard',
+                                          data: { obj: objText, key: keyName },
+                                          fix(fixer) {
+                                              if (body.type === 'BlockStatement') {
+                                                  // Wrap the inner content of the existing block.
+                                                  const inner = context.sourceCode
+                                                      .getText(body)
+                                                      .slice(1, -1);
+                                                  return fixer.replaceText(
+                                                      body,
+                                                      `{ if (${objText}.hasOwnProperty(${keyName})) {${inner}} }`,
+                                                  );
+                                              }
+                                              // Single-statement body — create a new block with guard.
+                                              const stmtText =
+                                                  context.sourceCode.getText(body);
+                                              return fixer.replaceText(
+                                                  body,
+                                                  `{ if (${objText}.hasOwnProperty(${keyName})) { ${stmtText} } }`,
+                                              );
+                                          },
+                                      },
+                                  ]
+                                : [],
+                    });
+                }
+            },
+        };
+    },
+};
+
+function containsHasOwnProperty(node) {
+    if (!node) return false;
+
+    if (node.type === 'IfStatement' && node.test && hasOwnPropertyTest(node.test)) {
+        return true;
+    }
+
+    if (node.type === 'IfStatement') {
+        return (
+            hasOwnPropertyTest(node.test) ||
+            containsHasOwnProperty(node.consequent) ||
+            containsHasOwnProperty(node.alternate)
+        );
+    }
+
+    if (node.type === 'BlockStatement') {
+        return node.body.some((child) => containsHasOwnProperty(child));
+    }
+
+    if (node.type === 'ExpressionStatement') {
+        return containsHasOwnProperty(node.expression);
+    }
+
+    return false;
+}
+
+function hasOwnPropertyTest(node) {
+    if (!node) return false;
+
+    if (
+        node.type === 'CallExpression' &&
+        node.callee.type === 'MemberExpression' &&
+        node.callee.property.type === 'Identifier' &&
+        node.callee.property.name === 'hasOwnProperty'
+    ) {
+        return true;
+    }
+
+    if (node.type === 'LogicalExpression') {
+        return hasOwnPropertyTest(node.left) || hasOwnPropertyTest(node.right);
+    }
+
+    if (node.type === 'UnaryExpression') {
+        return hasOwnPropertyTest(node.argument);
+    }
+
+    return false;
+}
+
+/**
+ * Extracts the loop key variable name from a for-in left-hand side.
+ * Handles both `for (var k in obj)` and `for (k in obj)`.
+ */
+function getKeyName(left) {
+    if (left.type === 'VariableDeclaration' && left.declarations.length > 0) {
+        const id = left.declarations[0].id;
+        return id.type === 'Identifier' ? id.name : null;
+    }
+    if (left.type === 'Identifier') {
+        return left.name;
+    }
+    return null;
+}