prettier-plugin-sfmc 0.2.0 → 0.4.0

package/README.md

@@ -36,7 +36,7 @@ All options use the `ampscript` prefix — they control AMPscript formatting beh
 | [`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      |
+| [`ampscriptBlockLineBreaks`](docs/options/ampscript-block-line-breaks.md)                     | boolean                                                                      | `false`         | Optional line breaks around `%%[ ]%%` when not already at a line boundary |
 | [`ampscriptVarDeclarationStyle`](docs/options/ampscript-var-declaration-style.md)             | `"auto"` \| `"single-line"` \| `"multi-line"`                                | `"multi-line"`  | Var declaration formatting                     |
 
 ### Example `.prettierrc`
@@ -60,41 +60,40 @@ All options use the `ampscript` prefix — they control AMPscript formatting beh
 | `.ssjs`      | `babel` (built-in) | Standard JavaScript formatting                  |
 | `.sql`       | `sql`              | SQL via composed `prettier-plugin-sql`          |
 
-## Core Prettier defaults (AMPscript, HTML, SQL)
+## Core Prettier defaults (AMPscript, HTML, SQL, JavaScript / SSJS)
 
-This plugin exports [Prettier `defaultOptions`](https://prettier.io/docs/plugins#defaultoptions). Prettier merges them when **this plugin’s printer** is active (AMPscript / embedded AMPscript in HTML, and SQL via the composed `sql` printer). They affect layout choices such as `tabWidth` and `printWidth` for those formats.
+This plugin exports [Prettier `defaultOptions`](https://prettier.io/docs/plugins#defaultoptions). Prettier merges them from whichever plugin **owns the active printer** for the file being formatted. This package supplies printers for **AMPscript**, **SQL** (via composed `prettier-plugin-sql`), and the shared **`estree`** printer (the same implementation Prettier ships for JavaScript). User plugins are loaded **after** built-ins, so this plugin becomes the effective `estree` printer—meaning **`.ssjs`** files (typically `parser: "babel"`) pick up the table below **without** copying these keys into `.prettierrc`.
 
 | Option | Default | Rationale |
 | ------ | ------- | --------- |
 | `useTabs` | `false` | SFMC often normalizes tabs away on save; spaces keep layout stable. |
 | `tabWidth` | `4` | Readable indentation (override in config if you prefer 2). |
 | `printWidth` | `100` | Fits typical editor panes better than Prettier’s 80. |
-| `singleQuote` | `true` | Matches common JS style and `ampscriptQuoteStyle: 'single'` for AMPscript-related output where the core quote option applies. |
-| `trailingComma` | `'none'` | Avoids trailing commas in stacks where they can be problematic (notably SSJS — see below). |
+| `singleQuote` | `true` | Common JS style; aligns with `ampscriptQuoteStyle: 'single'` where the core quote option applies. |
+| `trailingComma` | `'none'` | Avoids trailing commas that can break SSJS in some SFMC contexts. |
 
 String delimiters inside AMPscript blocks still follow `ampscriptQuoteStyle`. See [Prettier options](https://prettier.io/docs/options) for every standard flag.
 
-### SSJS (`.ssjs`)
+**Overrides:** Add options to `.prettierrc` or [overrides](https://prettier.io/docs/configuration#configuration-overrides) only when you want to **diverge** (for example `tabWidth: 2` for the whole project, or different rules per file glob).
 
-`.ssjs` files use Prettier’s built-in **JavaScript** printer, not this plugin’s printer, so the `defaultOptions` above are **not** applied automatically to SSJS. Use `.prettierrc` (or [overrides](https://prettier.io/docs/configuration#configuration-overrides) on `*.ssjs`) if you want the same style, for example:
-
-```json
-{
-  "plugins": ["prettier-plugin-sfmc"],
-  "singleQuote": true,
-  "trailingComma": "none",
-  "tabWidth": 4,
-  "printWidth": 100
-}
-```
-
-To keep **AMPscript-only** indentation at 2 spaces while using different values for SSJS, use `overrides` keyed by file pattern.
+**Scope:** With this plugin enabled, any file Prettier formats using the **`estree`** printer uses these defaults—not only `.ssjs`. If another plugin in your config also registers `printers.estree`, plugin **order** matters (the last one wins).
 
 ## SQL (Transact-SQL / SFMC)
 
 `.sql` formatting is provided by [prettier-plugin-sql](https://github.com/un-ts/prettier/tree/master/packages/sql) (npm: [prettier-plugin-sql](https://www.npmjs.com/package/prettier-plugin-sql)). You only need `prettier` and `prettier-plugin-sfmc`; do not add a second entry in `plugins` for SQL.
 
-**Defaults chosen for SFMC-style T-SQL:** `language` `tsql`, `formatter` `sql-formatter`, `keywordCase` / `functionCase` `upper`, `identifierCase` / `dataTypeCase` `preserve`. Override any of these in `.prettierrc` or under `overrides` with `files: "*.sql"` if needed.
+**Defaults for SFMC-style T-SQL** (from composed [prettier-plugin-sql](https://www.npmjs.com/package/prettier-plugin-sql)):
+
+| Option | Default | Other values | Rationale |
+| ------ | ------- | ------------ | --------- |
+| `language` | `tsql` | n/a | Must stay `tsql` for SFMC T-SQL. Other dialects are not supported for SFMC SQL; changing this can break formatting or behaviour. |
+| `formatter` | `sql-formatter` | n/a | Must stay `sql-formatter` for SFMC SQL. Other formatters are not supported in this context; changing this can break. |
+| `keywordCase` | `upper` | `preserve`, `lower` | Casing for reserved keywords. |
+| `functionCase` | `upper` | `preserve`, `lower` | Casing for function names. |
+| `identifierCase` | `preserve` | `upper`, `lower` | Unquoted identifiers only (upstream treats this as experimental). |
+| `dataTypeCase` | `preserve` | `upper`, `lower` | Casing for data type names. |
+
+Do **not** override `language` or `formatter` for SFMC. You may override the **casing** options in `.prettierrc` or under `overrides` with `files: "*.sql"` if you want different keyword/function/identifier/data-type casing.
 
 Core layout still follows [Prettier options](https://prettier.io/docs/options). SQL-specific knobs (`expressionWidth`, `linesBetweenQueries`, etc.) are documented in the upstream package README.
 

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

@@ -1,25 +1,31 @@
 # `ampscriptBlockLineBreaks`
 
-> Enforce blank lines before and after `%%[ … ]%%` block expressions.
+> Optionally insert line breaks before and after `%%[ … ]%%` block expressions when they are **not** already at a line boundary in the source.
 
 | | |
 |---|---|
 | **Type** | `boolean` |
-| **Default** | `true` |
+| **Default** | `false` |
 | **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.
+When set to `true`, Prettier may add a **single** mandatory line break before the opening delimiter and/or after the closing delimiter so the block is not glued to other text on the same line (for example `</p>%%[` or `]%%<p>`).
+
+Breaks are **not** added when the opening is already at the start of a logical line (beginning of file after optional UTF-8 BOM, optional spaces/tabs only before `%%[`, or immediately after `\n` / `\r\n` / `\r`), or when the closing is already at the end of a logical line (only horizontal whitespace until the next line break or end of file). That keeps formatting **idempotent** on repeated save instead of growing extra blank lines.
+
+Inline expressions (`%%= … =%%`) are never affected.
+
+The default is `false` so SMS and other line-break–sensitive templates are not altered unless you opt in.
 
 ## Settings
 
 | Value | Effect |
 |-------|--------|
-| `true` (default) | Blank line inserted before and after every `%%[ ]%%` block |
-| `false` | No blank lines added; blocks formatted flush with surrounding content |
+| `false` (default) | No extra outer line breaks from this option; inner block layout still normalizes |
+| `true` | Add outer line breaks only where the block is not already isolated on its own line |
 
-### `true` (default)
+### `true` — inline-adjacent block
 
 **Input:**
 
@@ -30,35 +36,26 @@ set @name = "Alice"
 ]%%<p>%%=v(@name)=%%</p>
 ```
 
-**Output:**
-
-```html
-<p>Hello</p>
+**Output** (illustrative; exact HTML wrapping may include normal Prettier line breaks):
 
-%%[
-  var @name
-  set @name = "Alice"
-]%%
+- A line break is inserted so `%%[` is not on the same line as `</p>`.
+- A line break is inserted so `]%%` is not on the same line as `<p>`.
 
-<p>%%= v(@name) =%%</p>
-```
+### `true` — already line-isolated (no extra outer breaks)
 
-### `false`
+If the source already has `%%[` at the beginning of a line (after optional BOM / spaces / tabs) and `]%%` at the end of a line (before optional spaces and `\n` or EOF), enabling this option does **not** add further outer breaks, so the document does not grow on every format.
 
-**Output:**
+### `false` (default)
 
-```html
-<p>Hello</p>%%[
-  var @name
-  set @name = "Alice"
-]%%<p>%%= v(@name) =%%</p>
-```
+**Output:** blocks stay flush with surrounding content except for whatever the HTML / AMPscript printers do for normal indentation and line wrapping.
 
 ## Configuration Example
 
+Opt in when you want blocks separated from inline HTML only where needed:
+
 ```json
 {
     "plugins": ["prettier-plugin-sfmc"],
-    "ampscriptBlockLineBreaks": false
+    "ampscriptBlockLineBreaks": true
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "prettier-plugin-sfmc",
-    "version": "0.2.0",
+    "version": "0.4.0",
     "description": "Prettier plugin for Salesforce Marketing Cloud — AMPscript, SSJS, and SQL formatting",
     "type": "module",
     "main": "src/index.js",
@@ -27,6 +27,7 @@
         "test": "node ./scripts/run-jest.mjs",
         "lint": "eslint .",
         "lint:fix": "eslint --fix .",
+        "prepare": "husky || true",
         "format": "prettier --write .",
         "format:check": "prettier --check ."
     },
@@ -59,6 +60,7 @@
         "eslint-plugin-prettier": "^5.5.0",
         "eslint-plugin-unicorn": "^64.0.0",
         "globals": "^17.4.0",
+        "husky": "^9.1.7",
         "jest": "^29.0.0",
         "prettier": "^3.8.1"
     },

package/src/ampscript-block-boundaries.js

@@ -0,0 +1,88 @@
+/**
+ * Detect whether AMPscript block delimiters already sit on their own logical
+ * lines in the original source (LF, CRLF, or CR). Used to avoid Prettier
+ * hardlines that would accumulate on repeated format.
+ *
+ * @param {string} ch
+ */
+function isHorizontalSpaceOrBom(ch) {
+    return ch === ' ' || ch === '\t' || ch === '\uFEFF';
+}
+
+/**
+ * True if `index` is the first non–BOM/horizontal-ws column of a line
+ * (BOF, or only BOM/ws before index, or newline before index after skipping ws).
+ *
+ * @param {string} text
+ * @param {number} index
+ */
+function isIndexAtLineStart(text, index) {
+    if (index <= 0) {
+        return true;
+    }
+
+    let i = index - 1;
+    while (i >= 0 && isHorizontalSpaceOrBom(text[i])) {
+        i--;
+    }
+
+    if (i < 0) {
+        return true;
+    }
+
+    const ch = text[i];
+    return ch === '\n' || ch === '\r';
+}
+
+/**
+ * True if everything from `index` to EOF is horizontal ws/BOM, or the first
+ * non-ws character begins a new line.
+ *
+ * @param {string} text
+ * @param {number} index
+ */
+function isIndexAtLineEnd(text, index) {
+    const len = text.length;
+    let j = index;
+
+    while (j < len && isHorizontalSpaceOrBom(text[j])) {
+        j++;
+    }
+
+    if (j >= len) {
+        return true;
+    }
+
+    const ch = text[j];
+    return ch === '\n' || ch === '\r';
+}
+
+/**
+ * When ampscriptBlockLineBreaks is enabled, add a leading hardline only if
+ * the block opening is not already at the start of a line in the source.
+ *
+ * @param {string | undefined} originalText
+ * @param {number | undefined} blockStart
+ */
+export function needsLeadingBlockBreak(originalText, blockStart) {
+    if (typeof originalText !== 'string' || blockStart == null || blockStart < 0) {
+        return false;
+    }
+
+    return !isIndexAtLineStart(originalText, blockStart);
+}
+
+/**
+ * When ampscriptBlockLineBreaks is enabled, add a trailing hardline only if
+ * the block closing is not already at the end of a line in the source.
+ *
+ * @param {string | undefined} originalText
+ * @param {number | undefined} blockEnd
+ */
+export function needsTrailingBlockBreak(originalText, blockEnd) {
+    if (typeof originalText !== 'string' || blockEnd == null || blockEnd < 0) {
+        return false;
+    }
+
+    return !isIndexAtLineEnd(originalText, blockEnd);
+}

package/src/index.js

@@ -4,6 +4,7 @@
  * A unified Prettier plugin for Salesforce Marketing Cloud.
  * Handles AMPscript formatting (.ampscript, .amp, .html), SSJS file
  * registration (.ssjs), and SQL (.sql) via composed prettier-plugin-sql.
+ * Re-exports Prettier’s `estree` printer so `defaultOptions` apply to JS/SSJS.
  *
  * Exports: languages, parsers, printers, options, defaultOptions
  * Following the Prettier v3 plugin API (ESM).
@@ -11,6 +12,7 @@
 
 import { parse } from 'ampscript-parser';
 import sqlPlugin from 'prettier-plugin-sql';
+import { printers as prettierEstreePrinters } from 'prettier/plugins/estree';
 import { printAmpscriptNode, collectVariableMap } from './printer.js';
 import * as prettier from 'prettier';
 
@@ -96,6 +98,7 @@ export const parsers = {
 
 export const printers = {
     ...sqlPlugin.printers,
+    estree: prettierEstreePrinters.estree,
     'ampscript-ast': {
         print(path, options, print) {
             const node = path.node;
@@ -330,11 +333,12 @@ const sfmcOptions = {
     ampscriptBlockLineBreaks: {
         type: 'boolean',
         category: 'AMPscript',
-        default: true,
+        default: false,
         description:
-            'Enforce line breaks before and after %%[ ... ]%% blocks. ' +
+            'When true, insert line breaks before and after %%[ ... ]%% blocks only when the ' +
+            'opening/closing delimiters are not already at a line boundary in the source. ' +
             'Inline expressions (%%= ... =%%) are never affected. ' +
-            'Set to false when blocks are embedded in contexts where extra line breaks are unwanted.',
+            'Default is false to avoid surprising line breaks in SMS and similar contexts.',
     },
     ampscriptVarDeclarationStyle: {
         type: 'choice',

package/src/printer.js

@@ -8,6 +8,7 @@
 
 import * as prettier from 'prettier';
 import { FUNCTION_CANONICAL_MAP, AMPSCRIPT_KEYWORDS } from 'ampscript-data';
+import { needsLeadingBlockBreak, needsTrailingBlockBreak } from './ampscript-block-boundaries.js';
 
 const { group, indent, join, line, softline, hardline } = prettier.doc.builders;
 
@@ -203,7 +204,7 @@ function printAmpscriptNode(path, options, print) {
     const variableStyle = options.ampscriptVarDeclarationStyle || 'multi-line';
     const keywordCase = options.ampscriptKeywordCase || 'lower';
     const functionCase = options.ampscriptFunctionCase || 'upper-camel';
-    const blockLineBreaks = options.ampscriptBlockLineBreaks !== false;
+    const blockLineBreaks = options.ampscriptBlockLineBreaks === true;
 
     function resolveVariable(variableName) {
         if (!enforceCasing) {
@@ -295,8 +296,21 @@ function printAmpscriptNode(path, options, print) {
                 blockClose,
             ]);
             if (blockLineBreaks) {
-                return [hardline, blockDocument, hardline];
+                const originalText = options.originalText;
+                const parts = [];
+                if (needsLeadingBlockBreak(originalText, node.start)) {
+                    parts.push(hardline);
+                }
+
+                parts.push(blockDocument);
+
+                if (needsTrailingBlockBreak(originalText, node.end)) {
+                    parts.push(hardline);
+                }
+
+                return parts.length === 1 ? parts[0] : parts;
             }
+
             return blockDocument;
         }