eslint-plugin-sfmc 0.1.0

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

@@ -0,0 +1,83 @@
+# `sfmc/ssjs-no-unsupported-syntax`
+
+> Disallow ES6+ syntax features not supported by the SFMC SSJS engine.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `error` in `recommended` and `strict` |
+| **Fixable** | **Auto-fix** for `let`/`const`; **Suggestion** for `??` |
+
+## Why This Rule Exists
+
+SFMC executes Server-Side JavaScript using JINT, a .NET-based engine that implements ECMAScript 3 with some ES5 additions. Modern JavaScript syntax introduced in ES6 and later — including `let`, `const`, template literals, arrow functions, destructuring, classes, `async/await`, optional chaining, and nullish coalescing — is not available and causes runtime errors. Code that works in a browser or Node.js will silently fail or produce cryptic errors in SFMC.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` |
+| `allow` | Array of feature names to suppress | `[]` |
+
+#### Known feature names for `allow`
+
+`LetDeclaration`, `ConstDeclaration`, `ArrowFunction`, `TemplateLiteral`, `DestructuringAssignment`, `SpreadOperator`, `ClassDeclaration`, `AsyncFunction`, `OptionalChaining`, `NullishCoalescing`, `ForOfStatement`, `GeneratorFunction`, `Symbol`, `Proxy`, `WeakMap`, `WeakSet`, `BigInt`
+
+### Default behavior (no `allow`)
+
+**Not allowed:**
+
+```js
+const greeting = `Hello, ${name}`;
+let count = 0;
+const double = (x) => x * 2;
+const value = obj?.prop ?? "default";
+```
+
+**Allowed:**
+
+```js
+var greeting = "Hello, " + name;
+var count = 0;
+function double(x) { return x * 2; }
+var value = (obj && obj.prop !== null && obj.prop !== undefined) ? obj.prop : "default";
+```
+
+### With `allow: ["LetDeclaration", "ConstDeclaration"]`
+
+`let` and `const` are no longer flagged, but all other unsupported syntax is still reported.
+
+## Fix
+
+**Auto-fix** for `let` and `const` declarations. Applied by:
+
+- `eslint --fix` on the command line
+- **Fix this issue** / **Fix all auto-fixable problems** in VS Code (requires the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint))
+- On save via `editor.codeActionsOnSave: { "source.fixAll.eslint": "explicit" }`
+
+What the auto-fix does: replaces the `let` or `const` keyword with `var`, leaving the rest of the declaration unchanged.
+
+---
+
+**Suggestion** for nullish coalescing (`??`). Applied by:
+
+- Click the **lightbulb** / press `Ctrl+.` on the flagged code in VS Code (requires the ESLint extension)
+- `eslint --fix` does **not** apply suggestions (`--fix-type suggestion` filters fixable rules by rule category, it does **not** apply `hasSuggestions` suggestions)
+
+What the suggestion does: replaces `??` with `||`. Note that `||` has different semantics — it also treats `0`, `""`, and `false` as falsy, unlike `??` which only replaces `null` and `undefined`.
+
+## Configuration Example
+
+```js
+// eslint.config.js
+rules: {
+  'sfmc/ssjs-no-unsupported-syntax': ['error', { allow: ['LetDeclaration'] }]
+}
+```
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/ssjs-no-unsupported-syntax': 'off' }
+```

package/docs/rules/ssjs/platform-function-arity.md

@@ -0,0 +1,45 @@
+# `sfmc/ssjs-platform-function-arity`
+
+> Enforce correct argument counts for `Platform.Function.*` calls.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `error` in `recommended` and `strict` |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+`Platform.Function` methods have documented required and optional argument counts. Passing too few arguments causes a runtime error; passing too many may silently truncate or fail. This rule validates every `Platform.Function.*` call against the known min/max argument counts.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```js
+Platform.Load("core", "1.1.5");
+/* Lookup requires at least 4 arguments */
+var val = Platform.Function.Lookup("MyDE", "Value");
+```
+
+**Allowed:**
+
+```js
+Platform.Load("core", "1.1.5");
+var val = Platform.Function.Lookup("MyDE", "Value", "Key", keyValue);
+```
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/ssjs-platform-function-arity': 'off' }
+```

package/docs/rules/ssjs/prefer-parsejson-safe-arg.md

@@ -0,0 +1,42 @@
+# ssjs-prefer-parsejson-safe-arg
+
+Require concatenating an empty string to `Platform.Function.ParseJSON()` arguments.
+
+## Why
+
+`Platform.Function.ParseJSON()` throws a 500 error at runtime if its argument is `undefined` or not a string. This commonly happens when the value comes from a lookup, request parameter, or variable that may be empty.
+
+Concatenating an empty string (`+ ''`) is a widely-used SFMC pattern that safely coerces the argument to a string:
+
+```js
+// Unsafe -- throws 500 if someVar is undefined
+Platform.Function.ParseJSON(someVar);
+
+// Safe
+Platform.Function.ParseJSON(someVar + '');
+```
+
+## Rule details
+
+This rule flags any call to `ParseJSON` (or `Platform.Function.ParseJSON`) where the first argument is not already concatenated with an empty string literal.
+
+**Auto-fix:** The rule wraps the argument with `+ ''`.
+
+### Valid
+
+```js
+Platform.Function.ParseJSON(someVar + '');
+Platform.Function.ParseJSON('' + someVar);
+Platform.Function.ParseJSON('{"key": "value"}');
+```
+
+### Invalid
+
+```js
+Platform.Function.ParseJSON(someVar);
+Platform.Function.ParseJSON(getData());
+```
+
+## Settings
+
+This rule has no options.

package/docs/rules/ssjs/prefer-platform-load-version.md

@@ -0,0 +1,68 @@
+# `sfmc/ssjs-prefer-platform-load-version`
+
+> Enforce a minimum version string in `Platform.Load()` calls.
+
+| | |
+|---|---|
+| **Type** | `suggestion` |
+| **Default severity** | `warn` in `recommended`; `error` in `strict` (not in `recommended` table — enabled in `strict`) |
+| **Fixable** | **Auto-fix** (`eslint --fix`) |
+
+## Why This Rule Exists
+
+`Platform.Load("core", "1")` or `"1.1.1"` loads an older version of the Core library that is missing bug fixes present in `"1.1.5"`. Using the latest stable version is documented as best practice in Mateusz Dąbrowski's SSJS style guide. This rule flags any version string other than the configured target and also flags calls where the version argument is missing entirely.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"warn"` |
+| `version` | Any version string | `"1.1.5"` |
+
+### Default behavior (enforce `"1.1.5"`)
+
+**Not allowed:**
+
+```js
+Platform.Load("core", "1");
+Platform.Load("core", "1.1.1");
+Platform.Load("core");   /* missing version argument */
+```
+
+**Allowed:**
+
+```js
+Platform.Load("core", "1.1.5");
+```
+
+### With `version: "1.1.6"` (custom minimum)
+
+Flags anything that is not `"1.1.6"`, including `"1.1.5"`.
+
+## Fix
+
+This rule provides an **auto-fix**. Applied by:
+
+- `eslint --fix` on the command line (because `meta.type` is `"suggestion"`, you can also target it specifically with `--fix-type suggestion`)
+- **Fix this issue** / **Fix all auto-fixable problems** in VS Code (requires the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint))
+- On save via `editor.codeActionsOnSave: { "source.fixAll.eslint": "explicit" }`
+
+What the fix does:
+- When the version argument is present but wrong: replaces the version string literal with the required version.
+- When the version argument is missing entirely: inserts `, "1.1.5"` after the `"core"` argument.
+
+## Configuration Example
+
+```js
+// eslint.config.js
+rules: {
+  'sfmc/ssjs-prefer-platform-load-version': ['warn', { version: '1.1.5' }]
+}
+```
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/ssjs-prefer-platform-load-version': 'off' }
+```

package/docs/rules/ssjs/require-hasownproperty.md

@@ -0,0 +1,57 @@
+# `sfmc/ssjs-require-hasownproperty`
+
+> Require a `hasOwnProperty` guard in `for…in` loops.
+
+| | |
+|---|---|
+| **Type** | `suggestion` |
+| **Default severity** | `warn` in `recommended`; `error` in `strict` |
+| **Fixable** | **Suggestion** (manual, via VS Code lightbulb) |
+
+## Why This Rule Exists
+
+In SFMC's SSJS runtime, objects frequently carry inherited properties such as `_type` that are visible in `for…in` iterations. Without a `hasOwnProperty` guard, these prototype properties are processed alongside the object's own data, leading to unexpected behaviour or errors. This is an amplified version of the general JavaScript best practice that applies specifically to SFMC because Core library objects are particularly prone to having non-enumerable inherited properties exposed.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"warn"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```js
+for (var key in myObject) {
+    write(key + ": " + myObject[key]);
+}
+```
+
+**Allowed:**
+
+```js
+for (var key in myObject) {
+    if (myObject.hasOwnProperty(key)) {
+        write(key + ": " + myObject[key]);
+    }
+}
+```
+
+## Fix
+
+This rule provides a **suggestion** (not applied automatically). To apply it:
+
+- Click the **lightbulb** / press `Ctrl+.` on the flagged code in VS Code (requires the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint))
+- `eslint --fix` does **not** apply suggestions (`--fix-type suggestion` filters fixable rules by rule category, it does **not** apply `hasSuggestions` suggestions)
+
+What the suggestion does: wraps the entire loop body in an `if (obj.hasOwnProperty(key)) { … }` guard. When the body is already a block statement, the existing content is preserved inside the new `if`; when it is a single statement, a new block is created around it.
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/ssjs-require-hasownproperty': 'off' }
+```

package/docs/rules/ssjs/require-platform-load-order.md

@@ -0,0 +1,46 @@
+# `sfmc/ssjs-require-platform-load-order`
+
+> Require `Platform.Load()` to appear before Core library usage in source order.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `error` in `recommended` and `strict` |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+Even when `Platform.Load("core", "1.1.5")` is present in the file, placing it *after* the first Core library call still causes a runtime crash. SFMC executes the file top-to-bottom; a `DataExtension.Init()` call on line 1 runs before the `Platform.Load` on line 10 has had a chance to initialise the Core library. This rule is complementary to [`ssjs-require-platform-load`](require-platform-load.md) — it specifically checks that the call appears in the correct position.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```js
+var de = DataExtension.Init("MyDE");   /* Core used before Platform.Load */
+Platform.Load("core", "1.1.5");
+```
+
+**Allowed:**
+
+```js
+Platform.Load("core", "1.1.5");
+var de = DataExtension.Init("MyDE");
+```
+
+## When to Disable
+
+Only disable if you have a deliberate top-of-file initialisation pattern that reorders statements at runtime.
+
+```js
+// eslint.config.js
+rules: { 'sfmc/ssjs-require-platform-load-order': 'off' }
+```

package/docs/rules/ssjs/require-platform-load.md

@@ -0,0 +1,57 @@
+# `sfmc/ssjs-require-platform-load`
+
+> Require `Platform.Load("core", ...)` before using Core library objects.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `error` in `recommended` and `strict` |
+| **Fixable** | **Auto-fix** (`eslint --fix`) |
+
+## Why This Rule Exists
+
+SFMC's SSJS runtime requires `Platform.Load("core", "1.1.5")` to be called before any Core library object (`DataExtension`, `Subscriber`, `Email`, `SFMC`, etc.) is used. Without it, calls to `DataExtension.Init()` and similar methods crash at runtime with an object-not-found error. The Platform.Load call initialises the Core library and makes its classes available.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```js
+var de = DataExtension.Init("MyDE");
+var rows = de.Rows.Retrieve();
+```
+
+**Allowed:**
+
+```js
+Platform.Load("core", "1.1.5");
+var de = DataExtension.Init("MyDE");
+var rows = de.Rows.Retrieve();
+```
+
+## Fix
+
+This rule provides an **auto-fix**. Applied by:
+
+- `eslint --fix` on the command line (applies ALL fixable rules regardless of `meta.type`; use `--fix-type problem` to target only problem-type rules)
+- **Fix this issue** / **Fix all auto-fixable problems** in VS Code (requires the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint))
+- On save via `editor.codeActionsOnSave: { "source.fixAll.eslint": "explicit" }`
+
+What the fix does: inserts `Platform.Load("core", "1.1.5");` at the very beginning of the file. The fix is attached to the first reported violation only, so it is inserted exactly once even when multiple Core objects are used.
+
+## When to Disable
+
+Only disable this rule if you are intentionally writing SSJS that does not use Core library objects.
+
+```js
+// eslint.config.js
+rules: { 'sfmc/ssjs-require-platform-load': 'off' }
+```

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "eslint-plugin-sfmc",
+    "version": "0.1.0",
+    "description": "ESLint plugin for Salesforce Marketing Cloud — AMPscript and Server-Side JavaScript (SSJS)",
+    "type": "module",
+    "main": "src/index.js",
+    "exports": {
+        ".": "./src/index.js",
+        "./parser": "./src/ampscript-parser.js"
+    },
+    "files": [
+        "src",
+        "docs",
+        "LICENSE"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/JoernBerkefeld/eslint-plugin-sfmc.git"
+    },
+    "bugs": {
+        "url": "https://github.com/JoernBerkefeld/eslint-plugin-sfmc/issues"
+    },
+    "homepage": "https://github.com/JoernBerkefeld/eslint-plugin-sfmc#readme",
+    "author": "Joern Berkefeld",
+    "keywords": [
+        "eslint",
+        "eslintplugin",
+        "ampscript",
+        "ssjs",
+        "salesforce",
+        "marketing-cloud",
+        "sfmc"
+    ],
+    "dependencies": {
+        "ampscript-data": "^0.1.1",
+        "ampscript-parser": "^0.1.0",
+        "ssjs-data": "^0.1.0"
+    },
+    "peerDependencies": {
+        "eslint": ">=9.0.0"
+    },
+    "scripts": {
+        "test": "node --test tests/rules.test.js"
+    },
+    "license": "MIT",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "devDependencies": {
+        "eslint": "^10.1.0"
+    }
+}

package/src/ampscript-parser.js

@@ -0,0 +1,159 @@
+/**
+ * ESLint-compatible parser for AMPscript.
+ *
+ * Reuses the shared ampscript-parser package for tokenization and statement
+ * parsing, then wraps the resulting AST with ESLint-required metadata:
+ *   - `range: [start, end]` on every node
+ *   - `loc: { start: {line,column}, end: {line,column} }` on every node
+ *   - Root node typed as "Program" with `body`, `tokens`, `comments`
+ *   - `visitorKeys` so ESLint knows how to traverse custom node types
+ */
+
+import { parse as prettierParse } from 'ampscript-parser';
+
+// ── Visitor keys for all AMPscript AST node types ─────────────────────────
+//
+// Node types that collide with ESTree names (IfStatement, ForStatement,
+// ExpressionStatement) are prefixed with "Amp" so ESLint's built-in
+// JavaScript code-path analysis does not try to process them.
+
+const NODE_RENAME = {
+    IfStatement: 'AmpIfStatement',
+    ForStatement: 'AmpForStatement',
+    ExpressionStatement: 'AmpExpressionStatement',
+};
+
+export const visitorKeys = {
+    Program: ['body'],
+    Content: [],
+    Block: ['statements'],
+    InlineExpression: ['expression'],
+    Comment: [],
+    VarDeclaration: ['variables'],
+    SetStatement: ['target', 'value'],
+    AmpIfStatement: ['condition', 'consequent', 'alternates'],
+    ElseIfClause: ['condition', 'body'],
+    ElseClause: ['body'],
+    AmpForStatement: ['counter', 'startExpr', 'endExpr', 'body'],
+    AmpExpressionStatement: ['expression'],
+    FunctionCall: ['arguments'],
+    Variable: [],
+    Identifier: [],
+    StringLiteral: [],
+    NumberLiteral: [],
+    BooleanLiteral: [],
+    BinaryExpression: ['left', 'right'],
+    UnaryExpression: ['argument'],
+    ParenExpression: ['expression'],
+    RawStatement: [],
+    Raw: [],
+    Empty: [],
+};
+
+// ── Offset → line/column 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 offsetToLoc(offset, lineStarts) {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineStarts[mid] <= offset) lo = mid;
+        else hi = mid - 1;
+    }
+    return { line: lo + 1, column: offset - lineStarts[lo] };
+}
+
+// ── AST annotation ────────────────────────────────────────────────────────
+
+function annotateNode(node, lineStarts, comments) {
+    if (!node || typeof node !== 'object') return;
+
+    // Rename colliding ESTree types to Amp-prefixed equivalents
+    if (node.type && NODE_RENAME[node.type]) {
+        node.type = NODE_RENAME[node.type];
+    }
+
+    if (typeof node.start === 'number' && typeof node.end === 'number') {
+        node.range = [node.start, node.end];
+        node.loc = {
+            start: offsetToLoc(node.start, lineStarts),
+            end: offsetToLoc(node.end, lineStarts),
+        };
+    }
+
+    if (node.type === 'Comment') {
+        comments.push(node);
+    }
+
+    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, comments);
+                }
+            }
+        } else if (child && typeof child === 'object') {
+            annotateNode(child, lineStarts, comments);
+        }
+    }
+}
+
+// ── Public ESLint parser interface ────────────────────────────────────────
+
+export function parseForESLint(code) {
+    const prettierAst = prettierParse(code);
+    const lineStarts = buildLineTable(code);
+    const comments = [];
+
+    const ast = {
+        type: 'Program',
+        body: prettierAst.children || [],
+        start: 0,
+        end: code.length,
+        range: [0, code.length],
+        loc: {
+            start: { line: 1, column: 0 },
+            end: offsetToLoc(code.length, lineStarts),
+        },
+        tokens: [],
+        comments: [],
+    };
+
+    for (const child of ast.body) {
+        annotateNode(child, lineStarts, comments);
+    }
+
+    ast.comments = comments;
+
+    return {
+        ast,
+        visitorKeys,
+        services: {},
+        scopeManager: null,
+    };
+}
+
+export function parse(code) {
+    return parseForESLint(code).ast;
+}