eslint-plugin-sfmc 4.2.0 → 4.3.0

package/docs/rules/ssjs/http-property-value.md

@@ -0,0 +1,71 @@
+# `sfmc/ssjs-http-property-value`
+
+Flags literal assignments to writable `Script.Util.HttpRequest` / `Script.Util.HttpGet`
+instance properties whose value violates the property's documented, runtime-confirmed
+constraint (allowed enum, integer-ness, or minimum).
+
+Several request properties only accept a fixed set of values. Assigning something outside
+that set throws or silently misbehaves in the SFMC SSJS engine:
+
+| Property | Allowed values |
+|---|---|
+| `method` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
+| `emptyContentHandling` | `0`, `1`, `2` |
+| `retries` | non-negative integer |
+| `timeout` | non-negative integer |
+
+The allowed values live in [`ssjs-data`](../../../..) (`SCRIPT_UTIL_REQUEST_PROPERTIES` /
+`SCRIPT_UTIL_HTTPGET_PROPERTIES` → `valueConstraint`), so this rule and the VS Code /
+Cursor diagnostic (`ssjs/invalid-http-property-value`) share one source of truth.
+
+## Detection
+
+The rule tracks data flow, so it only fires on a genuine request object:
+
+1. A **request** variable is one assigned from `new Script.Util.HttpRequest(...)` or
+   `Script.Util.HttpGet(...)`.
+2. An assignment `<requestVar>.<prop> = <literal>` where `<prop>` has a `valueConstraint`
+   and the right-hand side is a **literal** (string, number, or a negative numeric like
+   `-2.45`) is validated against the constraint.
+
+Only literal values are checked. Variable / expression assignments cannot be verified
+statically and are left alone to avoid false positives.
+
+## Examples
+
+### ❌ Incorrect
+
+```js
+var req = new Script.Util.HttpRequest("https://api.example.com/data");
+
+req.emptyContentHandling = 5;   // ← allowed: 0 | 1 | 2
+req.retries = -2.45;            // ← must be a non-negative integer
+req.method = 'POT';             // ← allowed: GET | POST | PUT | PATCH | DELETE
+```
+
+### ✅ Correct
+
+```js
+var req = new Script.Util.HttpRequest("https://api.example.com/data");
+
+req.emptyContentHandling = 1;
+req.retries = 3;
+req.method = 'POST';
+```
+
+## Fix (suggestions)
+
+For enum violations the rule offers a suggestion per allowed value (e.g. replace `'POT'`
+with `'GET'`, `'POST'`, …). Numeric violations are reported without an automatic
+replacement, since there is no single unambiguous valid value.
+
+The same diagnostic and quick-fix are available in the VS Code / Cursor extension
+(`ssjs/invalid-http-property-value`).
+
+## Rule details
+
+- **Type:** `problem`
+- **Fixable:** No (offers suggestions)
+- **Recommended:** Yes (`error`)
+- **Strict:** Yes (`error`)
+- **MCN:** Off (SSJS is not supported on Marketing Cloud Next)

package/docs/rules/ssjs/no-unavailable-method.md

@@ -21,7 +21,8 @@ return wrong results:
   - `lastIndexOf` always returns `-1`.
 
 This rule detects both categories and offers a lightbulb suggestion to insert a polyfill
-at the end of the file.
+at the top of the file (after a leading `/* global … */` directive when present), matching
+the language-server quick-fix so both tools place polyfills consistently.
 
 ## Covered methods
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "eslint-plugin-sfmc",
-    "version": "4.2.0",
+    "version": "4.3.0",
     "description": "ESLint plugin for Salesforce Marketing Cloud Engagement+Next - AMPscript, Server-Side JavaScript (SSJS) and Handlebars",
     "type": "module",
     "main": "src/index.js",
@@ -42,7 +42,7 @@
         "eslint-plugin-mso-email": "^2.0.0",
         "handlebars-data": "^0.3.0",
         "mso-conditional-parser": "^2.0.1",
-        "ssjs-data": "^0.16.0"
+        "ssjs-data": "^0.18.0"
     },
     "peerDependencies": {
         "eslint": ">=9.0.0"

package/src/index.js

@@ -58,6 +58,7 @@ import ssjsArgumentTypes from './rules/ssjs/ssjs-argument-types.js';
 import ssjsCoreMethodArity from './rules/ssjs/ssjs-core-method-arity.js';
 import ssjsNoClrHeaderAccess from './rules/ssjs/no-clr-header-access.js';
 import ssjsRequireStringClrContent from './rules/ssjs/require-string-clr-content.js';
+import ssjsHttpPropertyValue from './rules/ssjs/http-property-value.js';
 
 // ── Handlebars (MCN) rules ──────────────────────────────────────────────────────
 
@@ -139,6 +140,7 @@ const plugin = {
         'ssjs-core-method-arity': ssjsCoreMethodArity,
         'ssjs-no-clr-header-access': ssjsNoClrHeaderAccess,
         'ssjs-require-string-clr-content': ssjsRequireStringClrContent,
+        'ssjs-http-property-value': ssjsHttpPropertyValue,
 
         // Handlebars (MCN) rules (hbs- prefix)
         'hbs-no-unknown-helper': hbsNoUnknownHelper,
@@ -184,6 +186,7 @@ const ssjsMcnRules = {
     'sfmc/ssjs-core-method-arity': 'off',
     'sfmc/ssjs-no-clr-header-access': 'off',
     'sfmc/ssjs-require-string-clr-content': 'off',
+    'sfmc/ssjs-http-property-value': 'off',
     'no-cond-assign': 'off',
 };
 
@@ -254,6 +257,7 @@ const ssjsRecommendedRules = {
     'sfmc/ssjs-core-method-arity': 'warn',
     'sfmc/ssjs-no-clr-header-access': 'error',
     'sfmc/ssjs-require-string-clr-content': 'error',
+    'sfmc/ssjs-http-property-value': 'error',
     'no-cond-assign': 'error',
 };
 
@@ -277,6 +281,7 @@ const ssjsStrictRules = {
     'sfmc/ssjs-core-method-arity': 'error',
     'sfmc/ssjs-no-clr-header-access': 'error',
     'sfmc/ssjs-require-string-clr-content': 'error',
+    'sfmc/ssjs-http-property-value': 'error',
     'no-cond-assign': 'error',
 };
 

package/src/rules/ssjs/http-property-value.js

@@ -0,0 +1,232 @@
+/**
+ * Rule: ssjs-http-property-value
+ *
+ * Flags literal assignments to writable `Script.Util.HttpRequest` /
+ * `Script.Util.HttpGet` instance properties whose value violates the property's
+ * documented, runtime-confirmed constraint (allowed enum, integer-ness, or
+ * minimum). Examples that throw or misbehave at runtime:
+ *
+ *     req.emptyContentHandling = 5;   // allowed: 0 | 1 | 2
+ *     req.retries = -2.45;            // must be a non-negative integer
+ *     req.method = 'POT';             // allowed: GET | POST | PUT | PATCH | DELETE
+ *
+ * Constraints live in ssjs-data (`SCRIPT_UTIL_REQUEST_PROPERTIES` /
+ * `SCRIPT_UTIL_HTTPGET_PROPERTIES` -> `valueConstraint`) so the LSP diagnostic
+ * (`ssjs/invalid-http-property-value`) and this rule share one source of truth.
+ * Only **literal** right-hand sides are checked; variables / expressions cannot
+ * be statically verified and are left alone to avoid false positives.
+ */
+
+import { SCRIPT_UTIL_REQUEST_PROPERTIES, SCRIPT_UTIL_HTTPGET_PROPERTIES } from 'ssjs-data';
+
+/**
+ * Map of property name => valueConstraint, built once from ssjs-data. When both
+ * request and get define the same property, the constraints are identical.
+ *
+ * @returns {Map<string, object>} property name -> valueConstraint
+ */
+function buildConstraintLookup() {
+    const lookup = new Map();
+    for (const property of [...SCRIPT_UTIL_REQUEST_PROPERTIES, ...SCRIPT_UTIL_HTTPGET_PROPERTIES]) {
+        if (property && property.valueConstraint && !lookup.has(property.name)) {
+            lookup.set(property.name, property.valueConstraint);
+        }
+    }
+    return lookup;
+}
+
+const constraintLookup = buildConstraintLookup();
+
+/**
+ * Returns true when the node is `Script.Util.HttpRequest` or
+ * `Script.Util.HttpGet` (a MemberExpression, optionally the callee of `new`).
+ *
+ * @param {import('eslint').Rule.Node} node - MemberExpression to test
+ * @returns {boolean} Whether it references a Script.Util HTTP constructor
+ */
+function isHttpConstructorMember(node) {
+    return (
+        node.type === 'MemberExpression' &&
+        node.property.type === 'Identifier' &&
+        (node.property.name === 'HttpRequest' || node.property.name === 'HttpGet') &&
+        node.object.type === 'MemberExpression' &&
+        node.object.property.type === 'Identifier' &&
+        node.object.property.name === 'Util' &&
+        node.object.object.type === 'Identifier' &&
+        node.object.object.name === 'Script'
+    );
+}
+
+/**
+ * Returns true when the node constructs a Script.Util HTTP request, i.e.
+ * `new Script.Util.HttpRequest(...)` or `Script.Util.HttpGet(...)`.
+ *
+ * @param {import('eslint').Rule.Node} node - init expression of a declarator
+ * @returns {boolean} Whether the expression yields an HTTP request instance
+ */
+function isHttpRequestInit(node) {
+    if (!node) {
+        return false;
+    }
+    if (node.type === 'NewExpression' || node.type === 'CallExpression') {
+        return isHttpConstructorMember(node.callee);
+    }
+    return false;
+}
+
+/**
+ * Extracts the literal value from a RHS node, or null when it is not a plain
+ * literal (string / number / boolean, incl. a negative numeric like `-2.45`).
+ *
+ * @param {import('eslint').Rule.Node} node - the assignment right-hand side
+ * @returns {{value: string|number|boolean}|null} parsed value wrapper or null
+ */
+function parseLiteral(node) {
+    if (node.type === 'Literal' && typeof node.value !== 'object' && node.value !== null) {
+        return { value: node.value };
+    }
+    // Unary minus / plus on a numeric literal, e.g. -2.45.
+    if (
+        node.type === 'UnaryExpression' &&
+        (node.operator === '-' || node.operator === '+') &&
+        node.argument.type === 'Literal' &&
+        typeof node.argument.value === 'number'
+    ) {
+        const n = node.operator === '-' ? -node.argument.value : node.argument.value;
+        return { value: n };
+    }
+    return null;
+}
+
+/**
+ * Validates a value against a constraint. Returns a human-readable violation
+ * fragment (e.g. `must be one of "GET", "POST"`) or null when the value is ok.
+ *
+ * @param {string|number|boolean} value - the parsed literal value
+ * @param {object} constraint - the valueConstraint from ssjs-data
+ * @returns {string|null} violation description or null when valid
+ */
+function checkConstraint(value, constraint) {
+    if (Array.isArray(constraint.enum)) {
+        if (!constraint.enum.includes(value)) {
+            const allowed = constraint.enum
+                .map((v) => (typeof v === 'string' ? `"${v}"` : String(v)))
+                .join(', ');
+            return `must be one of ${allowed}`;
+        }
+        return null;
+    }
+    if (constraint.numeric) {
+        if (typeof value !== 'number') {
+            return 'must be a number';
+        }
+        if (constraint.numeric === 'integer' && !Number.isSafeInteger(value)) {
+            return 'must be an integer';
+        }
+        if (typeof constraint.min === 'number' && value < constraint.min) {
+            return `must be >= ${constraint.min}`;
+        }
+        return null;
+    }
+    return null;
+}
+
+/**
+ * Builds source-ready replacement suggestions for a violation. Enum -> each
+ * allowed value (quoted for strings) with its optional `enumLabels` meaning.
+ * Numeric -> nothing (no single fix).
+ *
+ * @param {object} constraint - the valueConstraint from ssjs-data
+ * @returns {{code: string, label?: string}[]} replacement snippets to offer as suggestions
+ */
+function buildSuggestions(constraint) {
+    if (Array.isArray(constraint.enum)) {
+        const labels = constraint.enumLabels;
+        return constraint.enum.map((v) => ({
+            code: typeof v === 'string' ? `'${v}'` : String(v),
+            label: labels ? labels[String(v)] : undefined,
+        }));
+    }
+    return [];
+}
+
+export default {
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description:
+                'Disallow invalid literal values assigned to Script.Util.HttpRequest/HttpGet properties (e.g. method, emptyContentHandling, retries) based on their documented allowed values',
+        },
+        messages: {
+            invalidValue: 'Invalid value for {{ prop }}: it {{ violation }}.',
+            replaceWith: 'Replace with {{ value }}',
+            replaceWithLabel: 'Replace with {{ value }} ({{ label }})',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        const requestVariables = new Set();
+        const pending = [];
+
+        return {
+            VariableDeclarator(node) {
+                if (node.id.type === 'Identifier' && isHttpRequestInit(node.init)) {
+                    requestVariables.add(node.id.name);
+                }
+            },
+
+            AssignmentExpression(node) {
+                if (
+                    node.operator !== '=' ||
+                    node.left.type !== 'MemberExpression' ||
+                    node.left.computed ||
+                    node.left.object.type !== 'Identifier' ||
+                    !requestVariables.has(node.left.object.name) ||
+                    node.left.property.type !== 'Identifier'
+                ) {
+                    return;
+                }
+                const propertyName = node.left.property.name;
+                const constraint = constraintLookup.get(propertyName);
+                if (!constraint) {
+                    return;
+                }
+                const parsed = parseLiteral(node.right);
+                if (!parsed) {
+                    return;
+                }
+                const violation = checkConstraint(parsed.value, constraint);
+                if (!violation) {
+                    return;
+                }
+                pending.push({ rhs: node.right, propName: propertyName, violation, constraint });
+            },
+
+            'Program:exit'() {
+                for (const { rhs, propName, violation, constraint } of pending) {
+                    const suggest = buildSuggestions(constraint).map(({ code, label }) =>
+                        label
+                            ? {
+                                  messageId: 'replaceWithLabel',
+                                  data: { value: code, label },
+                                  fix: (fixer) => fixer.replaceText(rhs, code),
+                              }
+                            : {
+                                  messageId: 'replaceWith',
+                                  data: { value: code },
+                                  fix: (fixer) => fixer.replaceText(rhs, code),
+                              },
+                    );
+                    context.report({
+                        node: rhs,
+                        messageId: 'invalidValue',
+                        data: { prop: propName, violation },
+                        suggest,
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/ssjs/no-unavailable-method.js

@@ -7,7 +7,7 @@
  * Two catalogs from ssjs-data feed this rule:
  *
  * 1. POLYFILLABLE_METHODS — a shipped ES3-safe polyfill exists. The report
- *    carries a suggestion that inserts the polyfill at the end of the file.
+ *    carries a suggestion that inserts the polyfill at the top of the file.
  * 2. KNOWN_UNSUPPORTED — no polyfill is feasible. The report has no fix; the
  *    message carries the ssjs-data `suggestion` (e.g. use Platform.Function.X).
  *
@@ -15,8 +15,9 @@
  * - category 'broken': method exists natively but returns incorrect results.
  *
  * No auto-fix is applied because prototype assignments are not hoisted —
- * the suggestion inserts the polyfill at the end of the file, and users
- * should verify placement before the first call (or load via Content Block).
+ * the suggestion inserts the polyfill at the top of the file (after a leading
+ * `/* global *\/` directive when present), and users should verify placement
+ * before the first call (or load via Content Block).
  */
 
 import {
@@ -58,7 +59,7 @@ export default {
             broken:
                 "'{{owner}}.{{method}}' exists in SFMC SSJS but produces incorrect results. " +
                 'Add a polyfill to get the correct behavior.',
-            addPolyfill: "Insert '{{owner}}.{{method}}' polyfill at end of file",
+            addPolyfill: "Insert '{{owner}}.{{method}}' polyfill at top of file",
             unavailableNoPolyfill:
                 "'{{owner}}.{{method}}' is not available in SFMC SSJS (ECMAScript 3). {{suggestion}}",
             brokenNoPolyfill:
@@ -99,8 +100,21 @@ export default {
         function buildSuggestFix(entry) {
             return function fix(fixer) {
                 const source = context.sourceCode;
-                const end = source.ast.range[1];
-                return fixer.insertTextAfterRange([end, end], '\n\n' + entry.polyfill);
+                // Insert the polyfill at the TOP of the file so it is defined
+                // before any call site (SSJS does not hoist prototype
+                // assignments). This mirrors the LSP quick-fix. When a leading
+                // `/* global ... */` ESLint directive is the first comment,
+                // insert right after it so the directive stays at the very top.
+                const leadingGlobal = source
+                    .getAllComments()
+                    .find(
+                        (c) =>
+                            c.type === 'Block' && c.range[0] === 0 && /^\s*global\b/.test(c.value),
+                    );
+                if (leadingGlobal) {
+                    return fixer.insertTextAfterRange(leadingGlobal.range, '\n\n' + entry.polyfill);
+                }
+                return fixer.insertTextBeforeRange([0, 0], entry.polyfill + '\n\n');
             };
         }