eslint-plugin-sfmc 2.6.1 → 4.0.0

package/docs/rules/ssjs/no-mcn-unsupported.md

@@ -0,0 +1,68 @@
+# `sfmc/ssjs-no-mcn-unsupported`
+
+> Disallow all Server-Side JavaScript API usage, which is unavailable in Marketing Cloud Next.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `error` in all `-next` configs; `off` otherwise |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+Server-Side JavaScript is not available in Marketing Cloud Next (MCN) at all. When targeting MCN, every SSJS API usage must be rewritten in AMPscript or Handlebars. This rule flags all SSJS API surface usage:
+
+| Construct | Example |
+|---|---|
+| Any `Platform.*` call (incl. `Platform.Load`) | `Platform.Function.LookupRows(…)` |
+| Any `HTTP.*` call | `HTTP.Get(…)` |
+| Core Library instance calls | `de.Rows.Retrieve()` (tracked from `DataExtension.Init(…)`) |
+| WSProxy instance calls | `api.retrieve(…)` |
+| WSProxy construction | `new Script.Util.WSProxy()` |
+
+Unlike [`sfmc/ssjs-no-unknown-function`](no-unknown-function.md), which only flags method names not in the catalog, this rule flags **every** SFMC API call — the whole SSJS block must be migrated.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` in `-next` configs |
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiVersion` | `number` | — | Accepted for parity with the AMPscript and Handlebars MCN rules; currently has **no effect** because no MCN API version supports SSJS. |
+
+## Examples
+
+```js
+// eslint.config.js
+rules: {
+  'sfmc/ssjs-no-mcn-unsupported': 'error'
+}
+```
+
+Or use the built-in `recommended-next` / `strict-next` / `embedded-next` configs, which apply this rule automatically (and disable the other SSJS quality rules, since the entire block must be migrated).
+
+**Flagged (every API call):**
+
+```js
+Platform.Load('Core', '1.1.1');
+Platform.Function.LookupRows('MyDE', 'Status', 'Active');
+
+var de = DataExtension.Init('CustomerData');
+de.Rows.Retrieve();
+
+var api = new Script.Util.WSProxy();
+api.retrieve({ ObjectType: 'DataExtension' }, ['CustomerKey'], {});
+```
+
+## When to Disable
+
+Disable this rule when you are not targeting Marketing Cloud Next (the default `engagement` configs already leave it `off`).
+
+```js
+// eslint.config.js
+rules: { 'sfmc/ssjs-no-mcn-unsupported': 'off' }
+```

package/docs/rules/ssjs/no-unknown-function.md

@@ -2,7 +2,7 @@
 
 Flags calls to SFMC API methods that do not exist in the catalog. This single rule replaces the seven narrow `no-unknown-*` rules from earlier versions of the plugin.
 
-When targeting **Marketing Cloud Next**, SSJS is not supported at all. Set `target: 'next'` to flag every SSJS API call as an error, signalling that the SSJS block must be removed or rewritten in AMPscript.
+This rule only reports **unknown** method names. When targeting Marketing Cloud Next, SSJS is not supported at all — every SSJS API call is flagged by the dedicated [`sfmc/ssjs-no-mcn-unsupported`](no-mcn-unsupported.md) rule instead.
 
 ## Covered namespaces
 
@@ -19,14 +19,10 @@ When targeting **Marketing Cloud Next**, SSJS is not supported at all. Set `targ
 
 ## Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `target` | `'engagement'` \| `'next'` | — | Target platform. Set to `'next'` to flag every SSJS API call (all of `Platform.*`, `HTTP.*`, Core Library, and WSProxy) as unsupported in Marketing Cloud Next. |
+This rule takes no options.
 
 ## Examples
 
-### Standard usage (Marketing Cloud Engagement)
-
 #### ❌ Incorrect
 
 ```js
@@ -54,32 +50,9 @@ var de = DataExtension.Init('CustomerData');
 de.Rows.Retrieve();
 ```
 
-### MCN target (`target: 'next'`)
-
-SSJS is not supported in Marketing Cloud Next. Configuring `target: 'next'` flags every SFMC API call within SSJS files, indicating they must be rewritten or removed.
-
-```js
-// eslint.config.js
-rules: {
-  'sfmc/ssjs-no-unknown-function': ['error', { target: 'next' }]
-}
-```
-
-Or use the built-in `recommended-next` / `strict-next` / `embedded-next` configs which apply this automatically (and disable all other SSJS quality rules, since the entire SSJS block must be migrated).
-
-#### ❌ Flagged (with `target: 'next'`)
-
-```js
-// All SFMC API calls are flagged — SSJS is not available in MCN
-Platform.Function.LookupRows('MyDE', 'Status', 'Active');
-
-var de = DataExtension.Init('CustomerData');
-de.Rows.Retrieve();
-```
-
 ## When to use
 
-Enable this rule to catch typos, outdated method names, and unsupported API calls before they cause runtime failures. Use `target: 'next'` when migrating content to Marketing Cloud Next.
+Enable this rule to catch typos and outdated method names before they cause runtime failures. When migrating content to Marketing Cloud Next, use [`sfmc/ssjs-no-mcn-unsupported`](no-mcn-unsupported.md) (applied automatically by the `recommended-next` / `strict-next` / `embedded-next` configs).
 
 ## Rule details
 
@@ -87,4 +60,4 @@ Enable this rule to catch typos, outdated method names, and unsupported API call
 - **Fixable:** No
 - **Recommended:** Yes (`engagement` mode)
 - **Strict:** Yes (`engagement` mode)
-- **`recommended-next` / `strict-next` / `embedded-next`:** Yes (`next` mode — all other SSJS rules disabled)
+- **`recommended-next` / `strict-next` / `embedded-next`:** Off (superseded by `ssjs-no-mcn-unsupported`)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "eslint-plugin-sfmc",
-    "version": "2.6.1",
+    "version": "4.0.0",
     "description": "ESLint plugin for Salesforce Marketing Cloud — AMPscript and Server-Side JavaScript (SSJS)",
     "type": "module",
     "main": "src/index.js",
@@ -32,9 +32,11 @@
         "sfmc"
     ],
     "dependencies": {
-        "ampscript-data": "^2.0.3",
-        "ampscript-parser": "^0.1.3",
-        "ssjs-data": "^0.11.0"
+        "@handlebars/parser": "^2.2.2",
+        "ampscript-data": "^3.0.0",
+        "ampscript-parser": "^0.2.0",
+        "handlebars-data": "^0.3.0",
+        "ssjs-data": "^0.14.0"
     },
     "peerDependencies": {
         "eslint": ">=9.0.0"
@@ -52,19 +54,19 @@
     },
     "license": "MIT",
     "engines": {
-        "node": ">=18.0.0"
+        "node": ">=22.0.0"
     },
     "devDependencies": {
         "@eslint/js": "^10.0.1",
-        "eslint": "^10.1.0",
+        "eslint": "^10.6.0",
         "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-jsdoc": "^62.0.0",
-        "eslint-plugin-prettier": "^5.5.0",
-        "eslint-plugin-unicorn": "^64.0.0",
-        "globals": "^17.4.0",
+        "eslint-plugin-jsdoc": "^63.0.10",
+        "eslint-plugin-prettier": "^5.5.6",
+        "eslint-plugin-unicorn": "^70.0.0",
+        "globals": "^17.7.0",
         "husky": "^9.1.7",
-        "lint-staged": "^17.0.5",
-        "prettier": "^3.8.2"
+        "lint-staged": "^17.0.8",
+        "prettier": "^3.9.4"
     },
     "lint-staged": {
         "*.{js,mjs,cjs}": [

package/src/ampscript-parser.js

@@ -91,7 +91,7 @@ function annotateNode(node, lineStarts, comments) {
     }
 
     // Rename colliding ESTree types to Amp-prefixed equivalents
-    if (node.type && NODE_RENAME[node.type]) {
+    if (node.type && Object.hasOwn(NODE_RENAME, node.type)) {
         node.type = NODE_RENAME[node.type];
     }
 

package/src/ampscript-processor.js

@@ -24,6 +24,22 @@ function countNewlinesBefore(text, pos) {
     return count;
 }
 
+/**
+ * Scans forward for the closing `=%%` of an inline AMPscript expression.
+ *
+ * @param {string} text - Full document text.
+ * @param {number} from - Index to start scanning from (just past the opening `%%=`).
+ * @returns {number} Index just past the closing `=%%`, or -1 when not found.
+ */
+function findInlineExpressionEnd(text, from) {
+    for (let index = from; index < text.length; index++) {
+        if (text[index] === '=' && text[index + 1] === '%' && text[index + 2] === '%') {
+            return index + 3;
+        }
+    }
+    return -1;
+}
+
 export function preprocess(text, filename) {
     const blocks = [];
     let index = 0;
@@ -91,28 +107,18 @@ export function preprocess(text, filename) {
 
         // %%= ... =%%
         if (text[index] === '%' && text[index + 1] === '%' && text[index + 2] === '=') {
-            const exprStart = index;
-            index += 3;
-            let found = false;
-
-            while (index < text.length) {
-                if (text[index] === '=' && text[index + 1] === '%' && text[index + 2] === '%') {
-                    index += 3;
-                    found = true;
-                    break;
-                }
-                index++;
-            }
-
-            if (!found) {
+            const expressionStart = index;
+            const expressionEnd = findInlineExpressionEnd(text, index + 3);
+            if (expressionEnd === -1) {
                 continue;
             }
+            index = expressionEnd;
 
             // Wrap in %%[ ]%% so the AMPscript parser receives valid block syntax.
             // %%[ is 3 chars, same as %%= — column offsets for inner code are preserved.
-            const innerCode = text.slice(exprStart + 3, index - 3);
+            const innerCode = text.slice(expressionStart + 3, index - 3);
             const wrappedBlock = `%%[${innerCode}]%%`;
-            const padding = '\n'.repeat(countNewlinesBefore(text, exprStart));
+            const padding = '\n'.repeat(countNewlinesBefore(text, expressionStart));
 
             blocks.push({
                 text: padding + wrappedBlock,

package/src/handlebars-parser.js

@@ -0,0 +1,195 @@
+/**
+ * ESLint-compatible parser for Marketing Cloud Next Handlebars.
+ *
+ * Wraps the `@handlebars/parser` package and adds the metadata ESLint needs:
+ *   - `range: [start, end]` on every node (derived from the parser's
+ *     1-based-line / 0-based-column `loc` via a line-start table)
+ *   - `loc: { start: {line,column}, end: {line,column} }` (kept from the parser,
+ *     whose convention already matches ESLint: 1-based line, 0-based column)
+ *   - Root node typed as "Program" with `body`, `tokens`, `comments`
+ *   - `visitorKeys` so ESLint knows how to traverse Handlebars node types
+ *
+ * AMPscript regions inside the source must be blanked out before this parser
+ * runs (the processor does this) so Handlebars never sees `%%[ ... ]%%` syntax.
+ */
+
+import { parse as hbsParse } from '@handlebars/parser';
+
+// ── Node renaming for ESTree collisions ───────────────────────────────────
+//
+// `BlockStatement` is also an ESTree node type, so ESLint's built-in scope
+// analysis (eslint-scope) tries to open a lexical scope for it and crashes on
+// the Handlebars shape. Likewise, a Handlebars `BlockStatement` contains nested
+// `Program` nodes (its `program`/`inverse` bodies); eslint-scope treats every
+// `Program` as a global scope and asserts when they nest. Rename both to
+// Hbs-prefixed types so the JS analyzer leaves them alone — only the single
+// synthetic root keeps the real `Program` type. The hbs rules and visitorKeys
+// reference the renamed types.
+
+const NODE_RENAME = {
+    BlockStatement: 'HbsBlockStatement',
+    Program: 'HbsProgram',
+};
+
+// ── Visitor keys for all Handlebars AST node types ────────────────────────
+
+export const visitorKeys = {
+    Program: ['body'],
+    HbsProgram: ['body'],
+    MustacheStatement: ['path', 'params', 'hash'],
+    HbsBlockStatement: ['path', 'params', 'hash', 'program', 'inverse'],
+    PartialStatement: ['name', 'params', 'hash'],
+    PartialBlockStatement: ['name', 'params', 'hash', 'program'],
+    DecoratorBlock: ['path', 'params', 'hash', 'program'],
+    Decorator: ['path', 'params', 'hash'],
+    ContentStatement: [],
+    CommentStatement: [],
+    SubExpression: ['path', 'params', 'hash'],
+    PathExpression: [],
+    StringLiteral: [],
+    NumberLiteral: [],
+    BooleanLiteral: [],
+    UndefinedLiteral: [],
+    NullLiteral: [],
+    Hash: ['pairs'],
+    HashPair: ['value'],
+};
+
+// ── line/column → offset mapping ──────────────────────────────────────────
+
+function buildLineTable(text) {
+    const starts = [0];
+    for (let index = 0; index < text.length; index++) {
+        if (text[index] === '\n') {
+            starts.push(index + 1);
+        } else if (text[index] === '\r') {
+            if (text[index + 1] === '\n') {
+                starts.push(index + 2);
+                index++;
+            } else {
+                starts.push(index + 1);
+            }
+        }
+    }
+    return starts;
+}
+
+function locToOffset(position, lineStarts, textLength) {
+    if (!position || typeof position.line !== 'number') {
+        return 0;
+    }
+    const lineIndex = Math.max(0, position.line - 1);
+    const base = lineIndex < lineStarts.length ? lineStarts[lineIndex] : textLength;
+    const offset = base + Math.max(0, position.column);
+    return Math.min(offset, textLength);
+}
+
+// ── AST annotation ────────────────────────────────────────────────────────
+
+function annotateNode(node, lineStarts, textLength, fallback) {
+    if (!node || typeof node !== 'object') {
+        return;
+    }
+
+    // Rename colliding ESTree types so ESLint's JS scope analysis ignores them.
+    if (node.type && Object.hasOwn(NODE_RENAME, node.type)) {
+        node.type = NODE_RENAME[node.type];
+    }
+
+    // ESLint requires every traversed node to expose a numeric `range` and a
+    // matching `loc`. `@handlebars/parser` attaches `loc` to most nodes but a
+    // few (e.g. Hash, HashPair) can omit it — inherit the parent's span so the
+    // traverser never sees an undefined range.
+    let span = fallback;
+    if (node.loc && node.loc.start && node.loc.end) {
+        const start = locToOffset(node.loc.start, lineStarts, textLength);
+        const end = locToOffset(node.loc.end, lineStarts, textLength);
+        node.range = [start, end];
+        node.start = start;
+        node.end = end;
+        node.loc = {
+            start: { line: node.loc.start.line, column: node.loc.start.column },
+            end: { line: node.loc.end.line, column: node.loc.end.column },
+        };
+        span = { range: node.range, loc: node.loc };
+    } else if (fallback) {
+        node.range = [...fallback.range];
+        node.start = fallback.range[0];
+        node.end = fallback.range[1];
+        node.loc = {
+            start: { ...fallback.loc.start },
+            end: { ...fallback.loc.end },
+        };
+    }
+
+    const keys = visitorKeys[node.type];
+    if (!keys) {
+        return;
+    }
+
+    for (const key of keys) {
+        const child = node[key];
+        if (Array.isArray(child)) {
+            for (const item of child) {
+                if (item && typeof item === 'object') {
+                    annotateNode(item, lineStarts, textLength, span);
+                }
+            }
+        } else if (child && typeof child === 'object') {
+            annotateNode(child, lineStarts, textLength, span);
+        }
+    }
+}
+
+// ── Public ESLint parser interface ────────────────────────────────────────
+
+export function parseForESLint(code) {
+    const lineStarts = buildLineTable(code);
+
+    let handlebarsAst;
+    try {
+        handlebarsAst = hbsParse(code);
+    } catch (ex) {
+        const loc = ex && ex.hash && ex.hash.loc;
+        const rawMessage = (ex && ex.message) || 'Handlebars syntax error.';
+        const messageLines = rawMessage.split('\n').filter((line) => line.trim().length > 0);
+        const error = new SyntaxError(messageLines.at(-1) || rawMessage);
+        error.lineNumber = loc ? Math.max(1, loc.first_line) : 1;
+        error.column = loc ? Math.max(1, loc.first_column + 1) : 1;
+        throw error;
+    }
+
+    const ast = {
+        type: 'Program',
+        body: handlebarsAst.body || [],
+        start: 0,
+        end: code.length,
+        range: [0, code.length],
+        loc: {
+            start: { line: 1, column: 0 },
+            end: handlebarsAst.loc
+                ? { line: handlebarsAst.loc.end.line, column: handlebarsAst.loc.end.column }
+                : {
+                      line: lineStarts.length,
+                      column: code.length - lineStarts.at(-1),
+                  },
+        },
+        tokens: [],
+        comments: [],
+    };
+
+    for (const child of ast.body) {
+        annotateNode(child, lineStarts, code.length);
+    }
+
+    return {
+        ast,
+        visitorKeys,
+        services: {},
+        scopeManager: null,
+    };
+}
+
+export function parse(code) {
+    return parseForESLint(code).ast;
+}