eslint-plugin-sfmc 0.1.0

package/docs/rules/amp/no-js-line-comment.md

@@ -0,0 +1,54 @@
+# `sfmc/amp-no-js-line-comment`
+
+> Disallow JavaScript-style single-line comments (`// ...`) inside AMPscript regions.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `warn` in `recommended`, `error` in `strict` |
+| **Fixable** | **Auto-fix** (`eslint --fix`) |
+
+## Why This Rule Exists
+
+AMPscript only supports block comments (`/* ... */`). JavaScript-style single-line comments (`// comment`) are silently ignored by the SFMC compiler, but they cause crashes in ESLint (the `spaced-comment` rule throws an unhandled error), break Prettier formatting, and can confuse the language server.
+
+Note: `://` in URLs (e.g. `"https://example.com"`) inside string literals is not flagged because string contents are not parsed as code.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"warn"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```ampscript
+%%[
+  // ---------------Language---------------
+  set @Opco = AttributeValue("OwningEntity__c")
+]%%
+```
+
+**Allowed:**
+
+```ampscript
+%%[
+  /* ---------------Language--------------- */
+  set @Opco = AttributeValue("OwningEntity__c")
+]%%
+```
+
+## Fix
+
+This rule provides an **auto-fix**: `// comment text` is replaced with `/* comment text */`.
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-no-js-line-comment': 'off' }
+```

package/docs/rules/amp/no-loop-counter-assign.md

@@ -0,0 +1,52 @@
+# `sfmc/amp-no-loop-counter-assign`
+
+> Disallow assigning to the `for` loop counter variable inside the loop body.
+
+| | |
+|---|---|
+| **Type** | `suggestion` |
+| **Default severity** | `warn` in `recommended`; `error` in `strict` |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+AMPscript documentation explicitly states that modifying the counter variable inside a `FOR … TO … DO` loop is not allowed and causes validation or runtime errors. The counter (`@i` in `FOR @i = 1 TO @n DO`) is managed by the runtime; attempting to reassign it produces undefined behavior.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"warn"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```ampscript
+%%[
+  for @i = 1 to 10 do
+    set @i = Add(@i, 1)
+  next @i
+]%%
+```
+
+**Allowed:**
+
+```ampscript
+%%[
+  var @step
+  for @i = 1 to 10 do
+    set @step = Add(@i, 1)
+    output(v(@step))
+  next @i
+]%%
+```
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-no-loop-counter-assign': 'off' }
+```

package/docs/rules/amp/no-nested-ampscript-delimiter.md

@@ -0,0 +1,69 @@
+# `sfmc/amp-no-nested-ampscript-delimiter`
+
+> Disallow `%%[` or `%%=` delimiters inside an already-open AMPscript region.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `error` in `recommended` and `strict` |
+| **Fixable** | **Auto-fix** (`eslint --fix`) |
+
+## Why This Rule Exists
+
+AMPscript delimiters (`%%[`, `]%%`, `%%=`, `=%%`) are used in HTML context to mark the start and end of AMPscript regions. Inside an already-open region — whether a `%%[...]%%` block, a `%%=...=%%` inline expression, or a `<script language="ampscript">` tag — these delimiters are not needed and indicate a structural mistake.
+
+Two sub-cases:
+
+- `%%[` or `%%=` inside a `<script language="ampscript">` block — redundant because the script tag already establishes AMPscript context for its entire body.
+- `%%[` nested inside an already-open `%%[...]%%` block — double-opening without a corresponding close.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed — delimiter inside script tag:**
+
+```html
+<script runat="server" language="ampscript">
+  %%[ set @x = "redundant delimiter" ]%%
+</script>
+```
+
+**Not allowed — nested block delimiter:**
+
+```ampscript
+%%[
+  %%[ set @inner = "nested" ]%%
+]%%
+```
+
+**Allowed:**
+
+```html
+<script runat="server" language="ampscript">
+  set @x = "no delimiter needed here"
+</script>
+```
+
+```ampscript
+%%[
+  set @x = "correct"
+]%%
+```
+
+## Fix
+
+This rule provides an **auto-fix** that removes the redundant delimiter pair (`%%[`/`]%%` or `%%=`/`=%%`), leaving only the inner code.
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-no-nested-ampscript-delimiter': 'off' }
+```

package/docs/rules/amp/no-nested-script-tag.md

@@ -0,0 +1,58 @@
+# `sfmc/amp-no-nested-script-tag`
+
+> Disallow nested `<script language="ampscript">` tags inside an already-open AMPscript script block.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `error` in `recommended` and `strict` |
+| **Fixable** | **Auto-fix** (`eslint --fix`) |
+
+## Why This Rule Exists
+
+Each `<script runat="server" language="ampscript">` block must be closed with `</script>` before a new one can be opened. A nested opening tag is structurally invalid and almost always indicates a missing `</script>` closing tag. The SFMC compiler may silently ignore the nested tag, leading to code that appears to work but is structured incorrectly.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```html
+<script runat="server" language="ampscript">
+  set @a = "outer"
+
+<script runat="server" language="ampscript">
+  set @b = "inner - this tag is nested!"
+</script>
+</script>
+```
+
+**Allowed:**
+
+```html
+<script runat="server" language="ampscript">
+  set @a = "outer"
+</script>
+
+<script runat="server" language="ampscript">
+  set @b = "second block - valid"
+</script>
+```
+
+## Fix
+
+This rule provides an **auto-fix**: inserts `</script>` immediately before the nested opening tag, converting the nested block into a valid sequential block.
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-no-nested-script-tag': 'off' }
+```

package/docs/rules/amp/no-smart-quotes.md

@@ -0,0 +1,60 @@
+# `sfmc/amp-no-smart-quotes`
+
+> Disallow smart/curly quotes in string literals.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `error` in `recommended` and `strict` |
+| **Fixable** | **Auto-fix** (`eslint --fix`) |
+
+## Why This Rule Exists
+
+AMPscript's parser only recognises straight ASCII single (`'`) and double (`"`) quotes as string delimiters. Smart (curly) quotes — such as `"`, `"`, `'`, `'` — are commonly introduced by word processors, rich-text editors, or copy-pasting from documentation. When these characters appear inside a string literal the AMPscript engine produces a parse error or treats the content as malformed, causing the email or page to fail silently or crash.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```ampscript
+%%[
+  var @name
+  set @name = "John"
+  set @name = 'Jane'
+]%%
+```
+
+**Allowed:**
+
+```ampscript
+%%[
+  var @name
+  set @name = "John"
+  set @name = 'Jane'
+]%%
+```
+
+## 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` or `--fix-type suggestion` to filter by rule category)
+- **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: replaces every smart quote inside the string content with its ASCII equivalent (`'` for single-flavour curly quotes, `"` for double-flavour). If the replacement would introduce the existing outer delimiter, the outer quotes are switched (e.g. `"…"` becomes `'…'`). If both quote types would appear after replacement, no automatic fix is applied.
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-no-smart-quotes': 'off' }
+```

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

@@ -0,0 +1,50 @@
+# `sfmc/amp-no-unknown-function`
+
+> Disallow calls to function names not in the known AMPscript catalog.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `error` in `recommended` and `strict` |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+AMPscript does not support user-defined functions. Every function call must match a name in Salesforce's published catalog. Calling an unknown name causes a runtime error (or is silently ignored depending on the execution context), making the code unreliable. This rule catches typos and invented names before deployment.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```ampscript
+%%[
+  var @result
+  set @result = CustomLookup("MyDE", "Key", @key)
+]%%
+```
+
+**Allowed:**
+
+```ampscript
+%%[
+  var @result
+  set @result = Lookup("MyDE", "Value", "Key", @key)
+]%%
+```
+
+## When to Disable
+
+Only disable this rule if you are intentionally using a proprietary or undocumented SFMC extension that is not in the public catalog.
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-no-unknown-function': 'off' }
+```

package/docs/rules/amp/no-var-redeclaration.md

@@ -0,0 +1,52 @@
+# `sfmc/amp-no-var-redeclaration`
+
+> Disallow re-declaring a variable with `var` after it has already been declared.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `warn` in `recommended`; `error` in `strict` |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+In AMPscript, re-declaring an already-declared variable with `var` silently resets its value to `null`. This is a common source of bugs when code is copy-pasted or blocks are re-ordered — the second `var @x` statement discards any value assigned in between, leading to unexpected empty output or runtime errors downstream.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"warn"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```ampscript
+%%[
+  var @name
+  set @name = "Alice"
+  var @name
+  /* @name is now null */
+  output(concat("Hello ", @name))
+]%%
+```
+
+**Allowed:**
+
+```ampscript
+%%[
+  var @name
+  set @name = "Alice"
+  output(concat("Hello ", @name))
+]%%
+```
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-no-var-redeclaration': 'off' }
+```

package/docs/rules/amp/prefer-attribute-value.md

@@ -0,0 +1,64 @@
+# `sfmc/amp-prefer-attribute-value`
+
+> Prefer `AttributeValue()` over bare personalization strings for safe attribute access.
+
+| | |
+|---|---|
+| **Type** | `suggestion` |
+| **Default severity** | `off` by default |
+| **Fixable** | **Suggestion** (manual, via VS Code lightbulb) |
+
+## Why This Rule Exists
+
+Using a bare identifier such as `FirstName` in a `SET` expression or as a standalone output relies on AMPscript's implicit personalization-string lookup. If the subscriber profile does not contain that attribute the send is aborted with an error. Wrapping the reference in `AttributeValue("FirstName")` instead returns an empty string (or a default value if the second argument is provided) when the attribute is missing, preventing send failures.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"off"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed (when rule is enabled):**
+
+```ampscript
+%%[
+  var @greeting
+  set @greeting = concat("Hello, ", FirstName)
+]%%
+%%=FirstName=%%
+```
+
+**Allowed:**
+
+```ampscript
+%%[
+  var @greeting
+  set @greeting = concat("Hello, ", AttributeValue("FirstName"))
+]%%
+%%=AttributeValue("FirstName")=%%
+
+/* With a default value: */
+%%=AttributeValue("FirstName", "default", "", "Subscriber")=%%
+```
+
+## 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 bare identifier (e.g. `FirstName`) in `AttributeValue("FirstName")`.
+
+## When to Disable
+
+This rule is off by default because bare personalization strings are valid AMPscript. Enable it only if your team wants to enforce the safer `AttributeValue()` pattern across all content.
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-prefer-attribute-value': 'warn' }
+```

package/docs/rules/amp/require-rowcount-check.md

@@ -0,0 +1,62 @@
+# `sfmc/amp-require-rowcount-check`
+
+> Require a `RowCount > 0` check before iterating over a `LookupRows` result.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `warn` in `recommended`; `error` in `strict` |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+When `LookupRows` (or `LookupOrderedRows`) returns an empty rowset and you immediately use `FOR @i = 1 TO RowCount(@rows)`, AMPscript evaluates `RowCount(@rows)` as `0`. A `FOR` loop iterating `1 TO 0` triggers a runtime error on some SFMC versions because the loop body attempts to access row index `1` from an empty set. The safe pattern is to guard the loop with `IF RowCount(@rows) > 0 THEN … ENDIF`.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"warn"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```ampscript
+%%[
+  var @rows
+  set @rows = LookupRows("MyDE", "Status", "Active")
+
+  for @i = 1 to RowCount(@rows) do
+    var @email
+    set @email = Field(Row(@rows, @i), "Email")
+    output(v(@email))
+  next @i
+]%%
+```
+
+**Allowed:**
+
+```ampscript
+%%[
+  var @rows
+  set @rows = LookupRows("MyDE", "Status", "Active")
+
+  if RowCount(@rows) > 0 then
+    for @i = 1 to RowCount(@rows) do
+      var @email
+      set @email = Field(Row(@rows, @i), "Email")
+      output(v(@email))
+    next @i
+  endif
+]%%
+```
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-require-rowcount-check': 'off' }
+```

package/docs/rules/amp/require-variable-declaration.md

@@ -0,0 +1,51 @@
+# `sfmc/amp-require-variable-declaration`
+
+> Require variables to be declared with `var` before use in `set` statements.
+
+| | |
+|---|---|
+| **Type** | `suggestion` |
+| **Default severity** | `off` by default |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+AMPscript does not technically require `var` before `set` — you can write `set @x = 1` without a prior declaration. However, the [ampscript.guide](https://ampscript.guide) best-practices documentation recommends always declaring variables with `var` first. This makes code self-documenting, helps catch variable-name typos at lint time, and mirrors the conventions used in official Salesforce examples.
+
+System variables (those starting with `@@`) are not affected.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"off"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed (when rule is enabled):**
+
+```ampscript
+%%[
+  set @name = "Alice"
+]%%
+```
+
+**Allowed:**
+
+```ampscript
+%%[
+  var @name
+  set @name = "Alice"
+]%%
+```
+
+## When to Disable
+
+This rule is off by default because undeclared `set` is valid AMPscript. Enable it for teams that want to enforce a strict declaration-first style.
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-require-variable-declaration': 'warn' }
+```

package/docs/rules/amp/set-requires-target.md

@@ -0,0 +1,47 @@
+# `sfmc/amp-set-requires-target`
+
+> Require `set` statements to have a target variable.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `error` in `recommended` and `strict` |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+The correct form of a `set` statement is `set @variable = expression`. A bare `set = expression` with no target is either a parse error or produces undefined runtime behavior. This always indicates a typo or incomplete code.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```ampscript
+%%[
+  set = Lookup("MyDE", "Value", "Key", @key)
+]%%
+```
+
+**Allowed:**
+
+```ampscript
+%%[
+  var @result
+  set @result = Lookup("MyDE", "Value", "Key", @key)
+]%%
+```
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-set-requires-target': 'off' }
+```

package/docs/rules/ssjs/cache-loop-length.md

@@ -0,0 +1,59 @@
+# `sfmc/ssjs-cache-loop-length`
+
+> Require caching array `.length` in `for` loop conditions.
+
+| | |
+|---|---|
+| **Type** | `suggestion` |
+| **Default severity** | `warn` in `recommended`; `error` in `strict` |
+| **Fixable** | **Suggestion** (manual, via VS Code lightbulb) |
+
+## Why This Rule Exists
+
+SFMC's SSJS engine (JINT) re-evaluates the loop test expression on every iteration. A condition like `i < arr.length` therefore calls the `.length` getter on every pass through the loop. For large arrays this is a measurable performance cost. The recommended pattern (per Mateusz Dąbrowski's SSJS style guide) is to cache the length in a variable in the loop initialiser:
+
+```js
+for (var i = 0, _len = arr.length; i < _len; i++) { … }
+```
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"warn"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```js
+for (var i = 0; i < items.length; i++) {
+    process(items[i]);
+}
+```
+
+**Allowed:**
+
+```js
+for (var i = 0, _len = items.length; i < _len; i++) {
+    process(items[i]);
+}
+```
+
+## 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: appends `, _len = arr.length` to the last declarator in the `for` loop initialiser and replaces `arr.length` in the test condition with `_len`. The suggestion is only offered when the loop `init` is a `var` declaration (the typical case).
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/ssjs-cache-loop-length': 'off' }
+```