prettier-plugin-sfmc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jörn Berkefeld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# prettier-plugin-sfmc
+
+Unified Prettier plugin for **Salesforce Marketing Cloud** — formats **AMPscript** (`.ampscript`, `.amp`, `.html`) and registers **SSJS** (`.ssjs`) files with Prettier's built-in JavaScript formatter.
+
+## Installation
+
+```bash
+npm install prettier-plugin-sfmc --save-dev
+```
+
+Requires Prettier 3.7+.
+
+## Quick Start
+
+Prettier auto-discovers plugins installed in `node_modules`. No config needed for `.ampscript`, `.amp`, and `.ssjs` files.
+
+For `.html` files containing AMPscript, the plugin's parser handles AMPscript regions while delegating HTML to Prettier's built-in HTML formatter. SSJS `<script runat="server">` blocks are formatted as JavaScript by Prettier's HTML pipeline automatically.
+
+To use explicitly in `.prettierrc`:
+
+```json
+{
+    "plugins": ["prettier-plugin-sfmc"]
+}
+```
+
+## Options
+
+All options use the `ampscript` prefix — they control AMPscript formatting behavior.
+
+| Option                               | Type                                                                         | Default         | Description                                    |
+| ------------------------------------ | ---------------------------------------------------------------------------- | --------------- | ---------------------------------------------- |
+| [`ampscriptSpacing`](docs/options/ampscript-spacing.md)                   | boolean                                                                      | `true`          | Spacing in inline expressions: `%%= V(@x) =%%` |
+| [`ampscriptEnforceVariableCasing`](docs/options/ampscript-enforce-variable-casing.md)     | boolean                                                                      | `true`          | Normalize variable casing to first occurrence  |
+| [`ampscriptRemoveUnnecessaryBrackets`](docs/options/ampscript-remove-unnecessary-brackets.md) | boolean                                                                      | `true`          | Remove needless parentheses                    |
+| [`ampscriptQuoteStyle`](docs/options/ampscript-quote-style.md)                | `"single"` \| `"double"`                                                     | `"single"`      | String quote style                             |
+| [`ampscriptKeywordCase`](docs/options/ampscript-keyword-case.md)               | `"lower"` \| `"upper"` \| `"preserve"`                                       | `"lower"`       | Keyword casing                                 |
+| [`ampscriptFunctionCase`](docs/options/ampscript-function-case.md)              | `"upper-camel"` \| `"lower-camel"` \| `"upper"` \| `"lower"` \| `"preserve"` | `"upper-camel"` | Function name casing                           |
+| [`ampscriptBlockLineBreaks`](docs/options/ampscript-block-line-breaks.md)           | boolean                                                                      | `true`          | Line breaks before/after `%%[ ]%%` blocks      |
+| [`ampscriptVarDeclarationStyle`](docs/options/ampscript-var-declaration-style.md)       | `"auto"` \| `"single-line"` \| `"multi-line"`                                | `"auto"`        | Var declaration formatting                     |
+
+### Example `.prettierrc`
+
+```json
+{
+    "plugins": ["prettier-plugin-sfmc"],
+    "ampscriptKeywordCase": "upper",
+    "ampscriptFunctionCase": "upper-camel",
+    "ampscriptQuoteStyle": "single"
+}
+```
+
+## Supported File Types
+
+| Extension    | Parser             | What happens                                    |
+| ------------ | ------------------ | ----------------------------------------------- |
+| `.ampscript` | `ampscript-parse`  | Full AMPscript formatting                       |
+| `.amp`       | `ampscript-parse`  | Full AMPscript formatting                       |
+| `.html`      | `ampscript-parse`  | AMPscript formatted; HTML delegated to Prettier |
+| `.ssjs`      | `babel` (built-in) | Standard JavaScript formatting                  |
+
+## HTML Embedding
+
+When formatting `.html` files, the plugin:
+
+1. Parses AMPscript regions (`%%[ ]%%`, `%%= =%%`, `<script language="ampscript">`)
+2. Delegates HTML content to Prettier's built-in HTML formatter
+3. Prettier's HTML formatter handles `<script runat="server">` SSJS blocks as JavaScript
+
+This means a single plugin handles all SFMC formatting in HTML email templates.
+
+## Migration from `prettier-plugin-ampscript` / `prettier-plugin-ssjs`
+
+Both plugins have been merged into this single package:
+
+1. Replace `prettier-plugin-ampscript` and `prettier-plugin-ssjs` with `prettier-plugin-sfmc`
+2. Update the `plugins` array in `.prettierrc` if explicitly configured
+3. All `ampscript*` option names are unchanged
+
+## License
+
+MIT

package/docs/options/ampscript-block-line-breaks.md

@@ -0,0 +1,64 @@
+# `ampscriptBlockLineBreaks`
+
+> Enforce blank lines before and after `%%[ … ]%%` block expressions.
+
+| | |
+|---|---|
+| **Type** | `boolean` |
+| **Default** | `true` |
+| **Applied by** | `prettier --write` · VS Code format-on-save (requires the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)) |
+
+## What It Controls
+
+Adds an empty line before and after every AMPscript block (`%%[ … ]%%`) to visually separate logic from surrounding HTML or text content. Inline expressions (`%%= … =%%`) are never affected. Set to `false` when blocks are embedded in contexts — such as attribute values or tightly formatted output sections — where extra blank lines would break the template layout.
+
+## Settings
+
+| Value | Effect |
+|-------|--------|
+| `true` (default) | Blank line inserted before and after every `%%[ ]%%` block |
+| `false` | No blank lines added; blocks formatted flush with surrounding content |
+
+### `true` (default)
+
+**Input:**
+
+```html
+<p>Hello</p>%%[
+var @name
+set @name = "Alice"
+]%%<p>%%=v(@name)=%%</p>
+```
+
+**Output:**
+
+```html
+<p>Hello</p>
+
+%%[
+  var @name
+  set @name = "Alice"
+]%%
+
+<p>%%= v(@name) =%%</p>
+```
+
+### `false`
+
+**Output:**
+
+```html
+<p>Hello</p>%%[
+  var @name
+  set @name = "Alice"
+]%%<p>%%= v(@name) =%%</p>
+```
+
+## Configuration Example
+
+```json
+{
+    "plugins": ["prettier-plugin-sfmc"],
+    "ampscriptBlockLineBreaks": false
+}
+```

package/docs/options/ampscript-enforce-variable-casing.md

@@ -0,0 +1,63 @@
+# `ampscriptEnforceVariableCasing`
+
+> Normalize all occurrences of a variable to the casing of its first appearance in the file.
+
+| | |
+|---|---|
+| **Type** | `boolean` |
+| **Default** | `true` |
+| **Applied by** | `prettier --write` · VS Code format-on-save (requires the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)) |
+
+## What It Controls
+
+AMPscript variables are case-insensitive at runtime — `@firstName`, `@FirstName`, and `@FIRSTNAME` all refer to the same variable. This option enforces a consistent casing across all references to the same variable within a file. When `true`, the casing of the first declaration (or first use if there is no `var`) is treated as canonical, and all subsequent occurrences are normalised to match it.
+
+## Settings
+
+| Value | Effect |
+|-------|--------|
+| `true` (default) | All occurrences of a variable adopt the casing of its first appearance |
+| `false` | Variable casing is preserved as-is |
+
+### `true` (default)
+
+**Input:**
+
+```ampscript
+%%[
+  var @firstName
+  set @FirstName = "Alice"
+  output(v(@FIRSTNAME))
+]%%
+```
+
+**Output:**
+
+```ampscript
+%%[
+  var @firstName
+  set @firstName = "Alice"
+  output(v(@firstName))
+]%%
+```
+
+### `false`
+
+**Input / Output** (casing preserved):
+
+```ampscript
+%%[
+  var @firstName
+  set @FirstName = "Alice"
+  output(v(@FIRSTNAME))
+]%%
+```
+
+## Configuration Example
+
+```json
+{
+    "plugins": ["prettier-plugin-sfmc"],
+    "ampscriptEnforceVariableCasing": false
+}
+```

package/docs/options/ampscript-function-case.md

@@ -0,0 +1,82 @@
+# `ampscriptFunctionCase`
+
+> Control the casing of AMPscript function names.
+
+| | |
+|---|---|
+| **Type** | `"upper-camel"` \| `"lower-camel"` \| `"upper"` \| `"lower"` \| `"preserve"` |
+| **Default** | `"upper-camel"` |
+| **Applied by** | `prettier --write` · VS Code format-on-save (requires the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)) |
+
+## What It Controls
+
+Normalises the casing of every known AMPscript function name. AMPscript function names are case-insensitive at runtime; this option chooses a consistent form for the formatted output. The `"upper-camel"` value uses the canonical PascalCase form as published in the Salesforce documentation (e.g. `Lookup`, `ContentBlockByKey`, `AttributeValue`).
+
+## Settings
+
+| Value | Effect |
+|-------|--------|
+| `"upper-camel"` (default) | Canonical PascalCase: `Lookup`, `ContentBlockByKey` |
+| `"lower-camel"` | camelCase: `lookup`, `contentBlockByKey` |
+| `"upper"` | ALL CAPS: `LOOKUP`, `CONTENTBLOCKBYKEY` |
+| `"lower"` | all lowercase: `lookup`, `contentblockbykey` |
+| `"preserve"` | Function casing is left exactly as written |
+
+### `"upper-camel"` (default)
+
+**Input:**
+
+```ampscript
+%%[
+  var @result
+  set @result = LOOKUP("MyDE", "Value", "Key", @key)
+  set @html = contentblockbykey("my-block")
+]%%
+```
+
+**Output:**
+
+```ampscript
+%%[
+  var @result
+  set @result = Lookup("MyDE", "Value", "Key", @key)
+  set @html = ContentBlockByKey("my-block")
+]%%
+```
+
+### `"upper"`
+
+**Output:**
+
+```ampscript
+%%[
+  var @result
+  set @result = LOOKUP("MyDE", "Value", "Key", @key)
+  set @html = CONTENTBLOCKBYKEY("my-block")
+]%%
+```
+
+### `"lower"`
+
+**Output:**
+
+```ampscript
+%%[
+  var @result
+  set @result = lookup("MyDE", "Value", "Key", @key)
+  set @html = contentblockbykey("my-block")
+]%%
+```
+
+### `"preserve"`
+
+Function names are emitted exactly as they appeared in the source.
+
+## Configuration Example
+
+```json
+{
+    "plugins": ["prettier-plugin-sfmc"],
+    "ampscriptFunctionCase": "upper-camel"
+}
+```

package/docs/options/ampscript-keyword-case.md

@@ -0,0 +1,74 @@
+# `ampscriptKeywordCase`
+
+> Control the casing of AMPscript keywords.
+
+| | |
+|---|---|
+| **Type** | `"lower"` \| `"upper"` \| `"preserve"` |
+| **Default** | `"lower"` |
+| **Applied by** | `prettier --write` · VS Code format-on-save (requires the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)) |
+
+## What It Controls
+
+Normalises the casing of AMPscript control-flow keywords: `if`, `then`, `elseif`, `else`, `endif`, `for`, `to`, `downto`, `do`, `next`, `var`, `set`, `and`, `or`, `not`, `true`, `false`. AMPscript keywords are case-insensitive at runtime; this option picks a single style for the formatted output.
+
+## Settings
+
+| Value | Effect |
+|-------|--------|
+| `"lower"` (default) | `if`, `set`, `var`, `for`, `then`, `endif`, … |
+| `"upper"` | `IF`, `SET`, `VAR`, `FOR`, `THEN`, `ENDIF`, … |
+| `"preserve"` | Keyword casing is left exactly as written |
+
+### `"lower"` (default)
+
+**Input:**
+
+```ampscript
+%%[
+  VAR @name
+  SET @name = "Alice"
+  IF @name == "Alice" THEN
+    output(v(@name))
+  ENDIF
+]%%
+```
+
+**Output:**
+
+```ampscript
+%%[
+  var @name
+  set @name = "Alice"
+  if @name == "Alice" then
+    output(v(@name))
+  endif
+]%%
+```
+
+### `"upper"`
+
+**Output:**
+
+```ampscript
+%%[
+  VAR @name
+  SET @name = "Alice"
+  IF @name == "Alice" THEN
+    output(v(@name))
+  ENDIF
+]%%
+```
+
+### `"preserve"`
+
+Keywords are emitted exactly as they appeared in the source.
+
+## Configuration Example
+
+```json
+{
+    "plugins": ["prettier-plugin-sfmc"],
+    "ampscriptKeywordCase": "upper"
+}
+```

package/docs/options/ampscript-quote-style.md

@@ -0,0 +1,69 @@
+# `ampscriptQuoteStyle`
+
+> Select whether strings should be wrapped in single or double quotes.
+
+| | |
+|---|---|
+| **Type** | `"single"` \| `"double"` |
+| **Default** | `"single"` |
+| **Applied by** | `prettier --write` · VS Code format-on-save (requires the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)) |
+
+## What It Controls
+
+Normalises all AMPscript string literals to use a single consistent quote character. This applies to function arguments, `set` values, and any other string expression throughout the file.
+
+## Settings
+
+| Value | Effect |
+|-------|--------|
+| `"single"` (default) | All strings use single quotes: `'value'` |
+| `"double"` | All strings use double quotes: `"value"` |
+
+### `"single"` (default)
+
+**Input:**
+
+```ampscript
+%%[
+  var @name
+  set @name = Lookup("MyDE", "Name", "Key", "abc")
+]%%
+```
+
+**Output:**
+
+```ampscript
+%%[
+  var @name
+  set @name = Lookup('MyDE', 'Name', 'Key', 'abc')
+]%%
+```
+
+### `"double"`
+
+**Input:**
+
+```ampscript
+%%[
+  var @name
+  set @name = Lookup('MyDE', 'Name', 'Key', 'abc')
+]%%
+```
+
+**Output:**
+
+```ampscript
+%%[
+  var @name
+  set @name = Lookup("MyDE", "Name", "Key", "abc")
+]%%
+```
+
+## Configuration Example
+
+```json
+{
+    "plugins": ["prettier-plugin-sfmc"],
+    "ampscriptQuoteStyle": "double"
+}
+```

package/docs/options/ampscript-remove-unnecessary-brackets.md

@@ -0,0 +1,63 @@
+# `ampscriptRemoveUnnecessaryBrackets`
+
+> Automatically remove parentheses that add no grouping value.
+
+| | |
+|---|---|
+| **Type** | `boolean` |
+| **Default** | `true` |
+| **Applied by** | `prettier --write` · VS Code format-on-save (requires the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)) |
+
+## What It Controls
+
+Removes redundant parentheses around simple expressions where they contribute no grouping semantics. For example, `(@name)` used as a function argument or assignment value is simplified to `@name`. Parentheses that are genuinely required for operator precedence are always preserved.
+
+## Settings
+
+| Value | Effect |
+|-------|--------|
+| `true` (default) | Redundant parentheses are stripped |
+| `false` | Parentheses are preserved exactly as written |
+
+### `true` (default)
+
+**Input:**
+
+```ampscript
+%%[
+  var @result
+  set @result = (Lookup("MyDE", "Value", "Key", (@key)))
+  output(v((@result)))
+]%%
+```
+
+**Output:**
+
+```ampscript
+%%[
+  var @result
+  set @result = Lookup("MyDE", "Value", "Key", @key)
+  output(v(@result))
+]%%
+```
+
+### `false`
+
+**Input / Output** (parentheses preserved):
+
+```ampscript
+%%[
+  var @result
+  set @result = (Lookup("MyDE", "Value", "Key", (@key)))
+  output(v((@result)))
+]%%
+```
+
+## Configuration Example
+
+```json
+{
+    "plugins": ["prettier-plugin-sfmc"],
+    "ampscriptRemoveUnnecessaryBrackets": false
+}
+```

package/docs/options/ampscript-spacing.md

@@ -0,0 +1,54 @@
+# `ampscriptSpacing`
+
+> Enforce consistent spacing around operators and inside inline expressions.
+
+| | |
+|---|---|
+| **Type** | `boolean` |
+| **Default** | `true` |
+| **Applied by** | `prettier --write` · VS Code format-on-save (requires the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)) |
+
+## What It Controls
+
+Controls whether spaces are emitted inside inline expressions (`%%= … =%%`) — between the `=%%` / `%%=` delimiters and the expression content — and around binary operators inside expressions. When `true`, the output is spaced for readability. When `false`, delimiters are printed flush against the content.
+
+## Settings
+
+| Value | Effect |
+|-------|--------|
+| `true` (default) | Prints `%%= V(@name) =%%` — spaces inside delimiters and around operators |
+| `false` | Prints `%%=V(@name)=%%` — no spaces inside delimiters |
+
+### `true` (default)
+
+**Input:**
+
+```ampscript
+%%=V(@firstName)=%%
+%%=Lookup("MyDE","Value","Key",@key)=%%
+```
+
+**Output:**
+
+```ampscript
+%%= V(@firstName) =%%
+%%= Lookup("MyDE", "Value", "Key", @key) =%%
+```
+
+### `false`
+
+**Input / Output:**
+
+```ampscript
+%%=V(@firstName)=%%
+%%=Lookup("MyDE","Value","Key",@key)=%%
+```
+
+## Configuration Example
+
+```json
+{
+    "plugins": ["prettier-plugin-sfmc"],
+    "ampscriptSpacing": false
+}
+```

package/docs/options/ampscript-var-declaration-style.md

@@ -0,0 +1,86 @@
+# `ampscriptVarDeclarationStyle`
+
+> Control how `var` declarations with multiple variables are formatted.
+
+| | |
+|---|---|
+| **Type** | `"auto"` \| `"single-line"` \| `"multi-line"` |
+| **Default** | `"auto"` |
+| **Applied by** | `prettier --write` · VS Code format-on-save (requires the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)) |
+
+## What It Controls
+
+Determines whether multiple variables in a single `var` statement are kept on one line, split to one variable per line, or left to Prettier's `printWidth` heuristic. AMPscript allows both `var @a, @b, @c` (all on one line) and separate `var` statements for each variable.
+
+## Settings
+
+| Value | Effect |
+|-------|--------|
+| `"auto"` (default) | Single line when it fits within `printWidth`; one-per-line when it doesn't |
+| `"single-line"` | Always `var @a, @b, @c` on one line regardless of width |
+| `"multi-line"` | Always one variable per `var` statement |
+
+### `"auto"` (default)
+
+**Input:**
+
+```ampscript
+%%[
+  var @firstName, @lastName, @email, @address, @city, @postalCode
+]%%
+```
+
+**Output (when line is short enough for `printWidth`):**
+
+```ampscript
+%%[
+  var @firstName, @lastName, @email
+]%%
+```
+
+**Output (when line exceeds `printWidth`):**
+
+```ampscript
+%%[
+  var @firstName
+  var @lastName
+  var @email
+  var @address
+  var @city
+  var @postalCode
+]%%
+```
+
+### `"single-line"`
+
+**Output:**
+
+```ampscript
+%%[
+  var @firstName, @lastName, @email, @address, @city, @postalCode
+]%%
+```
+
+### `"multi-line"`
+
+**Output:**
+
+```ampscript
+%%[
+  var @firstName
+  var @lastName
+  var @email
+  var @address
+  var @city
+  var @postalCode
+]%%
+```
+
+## Configuration Example
+
+```json
+{
+    "plugins": ["prettier-plugin-sfmc"],
+    "ampscriptVarDeclarationStyle": "multi-line"
+}
+```