eslint-plugin-mso-conditionals 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# eslint-plugin-mso-conditionals
+
+ESLint plugin for validating **MSO (Outlook) conditional comments** in HTML email.
+
+Extracts `<!--[if mso]>` … `<![endif]-->` blocks from HTML files and lints them for valid syntax and matched pairs using a custom processor and AST parser.
+
+## Installation
+
+```bash
+npm install eslint-plugin-mso-conditionals --save-dev
+```
+
+Requires ESLint 9+ (flat config) and Node.js 18+.
+
+## Quick Start
+
+```js
+// eslint.config.js
+import msoConditionals from 'eslint-plugin-mso-conditionals';
+
+export default [
+  ...msoConditionals.configs.recommended,
+];
+```
+
+This lints MSO conditional comments inside `**/*.html`, `**/*.amp`, and `**/*.ampscript` files.
+
+## VS Code Setup
+
+To see `eslint(mso-conditionals/...)` diagnostics inline in VS Code, the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) must be configured to validate HTML files:
+
+```json
+{
+  "eslint.validate": ["html", "javascript"]
+}
+```
+
+The [MSO Conditional Comments](https://marketplace.visualstudio.com/items?itemName=joernberkefeld.mso-conditionals) VS Code extension provides the same diagnostics without requiring ESLint. Use this plugin when you want linting in CI or in editors other than VS Code.
+
+## Rules
+
+| Rule | Default | Description |
+|---|---|---|
+| [`mso-conditionals/valid-mso-condition`](docs/rules/valid-mso-condition.md) | `error` | Validate MSO condition syntax — correct keyword, operator, and version |
+| [`mso-conditionals/matching-mso-endif`](docs/rules/matching-mso-endif.md) | `error` | Ensure every opener has a matching `[endif]` and vice versa |
+
+## Processor
+
+| Processor | Files | Purpose |
+|---|---|---|
+| `mso-conditionals/html` | `**/*.html`, `**/*.amp`, `**/*.ampscript` | Extracts MSO conditional comment strings for linting |
+
+The processor emits a virtual `.mso` file per source file containing one MSO comment per line, preserving line offsets so reported locations map back to the original file.
+
+## Config
+
+### `msoConditionals.configs.recommended`
+
+An array of two flat config objects:
+
+1. **Processor config** — registers `mso-conditionals/html` on HTML/AMP files.
+2. **Rules config** — applies `valid-mso-condition` and `matching-mso-endif` at `error` severity on the extracted `.mso` virtual files.
+
+Spread it in your config:
+
+```js
+export default [
+  ...msoConditionals.configs.recommended,
+  // your other rules...
+];
+```
+
+To adjust severity, override individual rules after spreading:
+
+```js
+export default [
+  ...msoConditionals.configs.recommended,
+  {
+    rules: {
+      'mso-conditionals/matching-mso-endif': 'warn',
+    },
+  },
+];
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,70 @@
+{
+    "name": "eslint-plugin-mso-conditionals",
+    "version": "1.0.0",
+    "description": "ESLint plugin for validating MSO (Outlook) conditional comments in HTML email",
+    "type": "module",
+    "main": "src/index.js",
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "files": [
+        "src",
+        "LICENSE"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/JoernBerkefeld/eslint-plugin-mso-conditionals.git"
+    },
+    "bugs": {
+        "url": "https://github.com/JoernBerkefeld/eslint-plugin-mso-conditionals/issues"
+    },
+    "homepage": "https://github.com/JoernBerkefeld/eslint-plugin-mso-conditionals#readme",
+    "author": "Joern Berkefeld",
+    "license": "MIT",
+    "keywords": [
+        "eslint",
+        "eslintplugin",
+        "mso",
+        "outlook",
+        "email",
+        "conditional-comments",
+        "html-email"
+    ],
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "peerDependencies": {
+        "eslint": ">=9.0.0"
+    },
+    "dependencies": {
+        "mso-conditional-parser": "^1.0.0"
+    },
+    "scripts": {
+        "test": "node --test tests/rules.test.mjs",
+        "lint": "eslint src tests",
+        "lint:fix": "eslint --fix src tests",
+        "prepare": "husky || true",
+        "format": "prettier --write .",
+        "format:check": "prettier --check ."
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "eslint": "^10.1.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",
+        "husky": "^9.1.7",
+        "lint-staged": "^17.0.5",
+        "prettier": "^3.8.2"
+    },
+    "lint-staged": {
+        "*.{js,mjs,cjs}": [
+            "eslint --fix"
+        ]
+    },
+    "volta": {
+        "node": "22.15.0"
+    }
+}

package/src/index.js

@@ -0,0 +1,58 @@
+/**
+ * eslint-plugin-mso-conditionals
+ *
+ * ESLint plugin for validating MSO (Outlook) conditional comments in HTML email.
+ * Provides a processor that extracts MSO comments from HTML and a custom parser
+ * that turns them into an AST, enabling rules to validate their syntax and structure.
+ */
+
+import msoEslintParser from './mso-eslint-parser.js';
+import processor from './processor.js';
+import validMsoCondition from './rules/valid-mso-condition.js';
+import matchingMsoEndif from './rules/matching-mso-endif.js';
+
+const plugin = {
+    meta: {
+        name: 'eslint-plugin-mso-conditionals',
+        version: '1.0.0',
+    },
+
+    rules: {
+        'valid-mso-condition': validMsoCondition,
+        'matching-mso-endif': matchingMsoEndif,
+    },
+
+    processors: {
+        html: processor,
+    },
+
+    configs: {},
+};
+
+Object.assign(plugin.configs, {
+    /**
+     * Recommended config for HTML files containing MSO conditional comments.
+     * Returns an array of two config objects (processor + rules), following the
+     * same flat-config pattern as eslint-plugin-sfmc's `configs.embedded`.
+     */
+    recommended: [
+        {
+            name: 'mso-conditionals/html-processor',
+            plugins: { 'mso-conditionals': plugin },
+            files: ['**/*.html', '**/*.amp', '**/*.ampscript'],
+            processor: 'mso-conditionals/html',
+        },
+        {
+            name: 'mso-conditionals/mso-rules',
+            plugins: { 'mso-conditionals': plugin },
+            files: ['**/*.html/*.mso', '**/*.amp/*.mso', '**/*.ampscript/*.mso'],
+            languageOptions: { parser: msoEslintParser },
+            rules: {
+                'mso-conditionals/valid-mso-condition': 'error',
+                'mso-conditionals/matching-mso-endif': 'error',
+            },
+        },
+    ],
+});
+
+export default plugin;

package/src/mso-eslint-parser.js

@@ -0,0 +1,92 @@
+/**
+ * ESLint-compatible parser for virtual `.mso` files produced by the processor.
+ *
+ * Receives a text where each non-empty line contains one raw MSO comment
+ * string (opener or closer). Produces a minimal ESLint `Program` AST with
+ * one `MsoComment` node per line, carrying both the raw text and the parsed
+ * result from `mso-conditional-parser`.
+ *
+ * Exports `visitorKeys` so ESLint's traversal engine knows the tree shape.
+ */
+
+import { parseMsoComment, parseMsoEndComment } from 'mso-conditional-parser';
+
+/**
+ * Visitor keys for all node types in the MSO AST.
+ * MsoComment has no child nodes — it is a leaf.
+ *
+ * @type {Record<string, string[]>}
+ */
+export const visitorKeys = {
+    Program: ['body'],
+    MsoComment: [],
+};
+
+/**
+ * Builds a line/column offset table for the given text.
+ *
+ * @param {string} text - Source text.
+ * @returns {number[]} Array where index i holds the character offset of line i.
+ */
+function buildLineStarts(text) {
+    const starts = [0];
+    for (const match of text.matchAll(/\n/g)) {
+        starts.push(match.index + 1);
+    }
+
+    return starts;
+}
+
+/**
+ * Parses a virtual `.mso` file into an ESLint-compatible Program AST.
+ *
+ * @param {string} text - Text of the virtual `.mso` file.
+ * @param {{ loc?: boolean, range?: boolean, tokens?: boolean, comment?: boolean }} _options - ESLint parse options (unused but required by interface).
+ * @returns {{ type: 'Program', body: object[], tokens: [], comments: [], range: number[], loc: object, visitorKeys: Record<string, string[]> }} ESLint-compatible Program AST.
+ */
+export function parse(text, _options) {
+    const lineStarts = buildLineStarts(text);
+    const lines = text.split('\n');
+    const body = [];
+
+    for (const [lineIndex, line] of lines.entries()) {
+        const raw = line.trim();
+        if (!raw) {
+            continue;
+        }
+
+        const lineStart = lineStarts[lineIndex] ?? text.length;
+        const start = lineStart;
+        const end = lineStart + line.length;
+
+        const parsed = parseMsoComment(raw) ?? parseMsoEndComment(raw);
+
+        body.push({
+            type: 'MsoComment',
+            raw,
+            parsed,
+            range: [start, end],
+            loc: {
+                start: { line: lineIndex + 1, column: 0 },
+                end: { line: lineIndex + 1, column: line.length },
+            },
+        });
+    }
+
+    const programEnd = text.length;
+
+    return {
+        type: 'Program',
+        body,
+        tokens: [],
+        comments: [],
+        range: [0, programEnd],
+        loc: {
+            start: { line: 1, column: 0 },
+            end: { line: lines.length, column: 0 },
+        },
+        visitorKeys,
+    };
+}
+
+export default { parse, visitorKeys };

package/src/processor.js

@@ -0,0 +1,86 @@
+/**
+ * ESLint processor that extracts MSO conditional comments from HTML files.
+ *
+ * Scans HTML for all MSO comment patterns (openers and closers) and
+ * extracts them into a single virtual `.mso` file. Padding newlines
+ * preserve original line numbers so ESLint reports errors at the correct
+ * positions in the source file.
+ *
+ * Pattern overview:
+ *   Openers: <!--[if …]>  <!--[if …]><!--  <![if …]>
+ *   Closers: <![endif]-->  <!--<![endif]-->  <![endif]>
+ */
+
+/**
+ * Regex that matches any MSO comment (opener or closer) on a single line.
+ * Named capture groups:
+ *   comment — the full raw comment string
+ */
+const MSO_COMMENT_RE =
+    /<!--\[if\s[^\]]*\]>(?:<!--)?|<!\[if\s[^\]]*\]>|(?:<!--)?<!\[endif\]-->|<!\[endif\]>/g;
+
+/**
+ * Counts newline characters before a given position in text.
+ *
+ * @param {string} text - The source text.
+ * @param {number} pos - The character offset.
+ * @returns {number} Number of newlines before pos.
+ */
+function countNewlinesBefore(text, pos) {
+    let count = 0;
+    for (let index = 0; index < pos; index++) {
+        if (text[index] === '\n') {
+            count++;
+        }
+    }
+
+    return count;
+}
+
+/**
+ * Preprocesses an HTML file by extracting all MSO comments into a single
+ * virtual `.mso` file, preserving line offsets.
+ *
+ * @param {string} text - Full source text of the HTML file.
+ * @param {string} filename - Original filename.
+ * @returns {{text: string, filename: string}[]} Array of virtual file objects.
+ */
+export function preprocess(text, filename) {
+    const lines = [];
+    let maxLine = 0;
+
+    MSO_COMMENT_RE.lastIndex = 0;
+    let match;
+    while ((match = MSO_COMMENT_RE.exec(text)) !== null) {
+        const line = countNewlinesBefore(text, match.index);
+        lines.push({ line, text: match[0] });
+        if (line > maxLine) {
+            maxLine = line;
+        }
+    }
+
+    if (lines.length === 0) {
+        return [text];
+    }
+
+    // Build a single virtual file: place each comment at its original line number
+    // using padding newlines so that column/line errors map back correctly.
+    const rows = Array.from({ length: maxLine + 1 }, () => '');
+    for (const entry of lines) {
+        rows[entry.line] = entry.text;
+    }
+
+    return [{ text: rows.join('\n'), filename: `${filename}/mso-comments.mso` }];
+}
+
+/**
+ * Postprocesses messages from linting the virtual `.mso` file.
+ *
+ * @param {import('eslint').Linter.LintMessage[][]} messages - Nested message arrays.
+ * @returns {import('eslint').Linter.LintMessage[]} Flat array of lint messages.
+ */
+export function postprocess(messages) {
+    return messages.flat();
+}
+
+export default { preprocess, postprocess, supportsAutofix: false };

package/src/rules/matching-mso-endif.js

@@ -0,0 +1,60 @@
+/**
+ * Rule: matching-mso-endif
+ *
+ * Validates that every MSO conditional comment opener has a matching
+ * closer ([endif]) and that no [endif] appears without an opening comment.
+ *
+ * Uses a stack to track nested conditionals across the entire virtual
+ * .mso file (one file per source HTML file). Reports unclosed openers
+ * at Program:exit.
+ */
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Ensure every MSO conditional comment opener has a matching closing [endif]',
+            recommended: true,
+        },
+        messages: {
+            unclosedConditional: 'MSO conditional "{{raw}}" is never closed with [endif]',
+            unmatchedEndif: 'Found [endif] with no matching MSO conditional opener',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        /** @type {object[]} */
+        const stack = [];
+
+        return {
+            MsoComment(node) {
+                if (!node.parsed) {
+                    return;
+                }
+
+                if (node.parsed.isClosing) {
+                    if (stack.length === 0) {
+                        context.report({ node, messageId: 'unmatchedEndif' });
+                    } else {
+                        stack.pop();
+                    }
+                } else {
+                    // opener
+                    stack.push(node);
+                }
+            },
+
+            'Program:exit'() {
+                for (const opener of stack) {
+                    context.report({
+                        node: opener,
+                        messageId: 'unclosedConditional',
+                        data: { raw: opener.raw },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/valid-mso-condition.js

@@ -0,0 +1,50 @@
+/**
+ * Rule: valid-mso-condition
+ *
+ * Validates that every MSO conditional comment opener uses correct syntax:
+ * - known keyword (mso, not mos)
+ * - valid comparison operator (gte, gt, lte, lt, eq)
+ * - valid version number (9, 10, 11, 12, 14, 15, 16 — no 13)
+ * - operator has a version number when required
+ */
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Ensure MSO conditional comments use valid syntax (correct keyword, operator, and version number)',
+            recommended: true,
+        },
+        messages: {
+            invalidCondition: 'Invalid MSO conditional comment: {{error}}. Found: "{{raw}}"',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            MsoComment(node) {
+                if (!node.parsed) {
+                    return;
+                }
+
+                // Closers have no condition to validate
+                if (node.parsed.isClosing) {
+                    return;
+                }
+
+                if (!node.parsed.isValid) {
+                    context.report({
+                        node,
+                        messageId: 'invalidCondition',
+                        data: {
+                            error: node.parsed.error ?? 'unknown error',
+                            raw: node.raw,
+                        },
+                    });
+                }
+            },
+        };
+    },
+};