eslint-plugin-sfmc 0.1.0

package/src/rules/amp/naming-convention.js

@@ -0,0 +1,58 @@
+/**
+ * Enforces a naming convention for @variable names in AMPscript.
+ *
+ * AMPscript variables are case-insensitive, but consistent casing improves
+ * readability and reduces confusion during code reviews.
+ */
+
+const CAMEL_CASE = /^@[a-z][a-zA-Z0-9]*$/;
+const PASCAL_CASE = /^@[A-Z][a-zA-Z0-9]*$/;
+
+export default {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce a consistent naming convention for @variable names',
+            recommended: false,
+        },
+        messages: {
+            badName: "Variable '{{name}}' does not match the required {{format}} format.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    format: {
+                        enum: ['camelCase', 'PascalCase'],
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+
+    create(context) {
+        const format = (context.options[0] && context.options[0].format) || 'camelCase';
+        const pattern = format === 'PascalCase' ? PASCAL_CASE : CAMEL_CASE;
+        const reported = new Set();
+
+        return {
+            Variable(node) {
+                const name = node.value;
+                if (!name.startsWith('@') || name.startsWith('@@')) return;
+
+                const key = name.toLowerCase();
+                if (reported.has(key)) return;
+
+                if (!pattern.test(name)) {
+                    reported.add(key);
+                    context.report({
+                        node,
+                        messageId: 'badName',
+                        data: { name, format },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/amp/no-deprecated-function.js

@@ -0,0 +1,75 @@
+/**
+ * Rule: no-deprecated-function
+ *
+ * Flags usage of deprecated AMPscript functions and suggests their
+ * modern replacements.
+ *
+ * For 1:1 replacements (e.g. InsertDE -> InsertData) an auto-fix is provided.
+ * For ambiguous replacements (e.g. ContentArea -> ContentBlockByKey OR
+ * ContentBlockByName) two manual suggestions are offered instead.
+ */
+
+import { deprecatedFunctionLookup } from 'ampscript-data';
+
+export default {
+    meta: {
+        type: 'suggestion',
+        fixable: 'code',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow deprecated AMPscript functions and suggest replacements',
+        },
+        messages: {
+            deprecated: "'{{name}}' is deprecated. Use {{replacement}} instead. {{reason}}",
+            replaceWith: "Replace '{{name}}' with '{{replacement}}'",
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            FunctionCall(node) {
+                const functionName = node.name || (node.callee && node.callee.name) || '';
+                if (!functionName) return;
+
+                const entry = deprecatedFunctionLookup.get(functionName.toLowerCase());
+                if (!entry) return;
+
+                const report = {
+                    node,
+                    messageId: 'deprecated',
+                    data: {
+                        name: functionName,
+                        replacement: entry.replacement,
+                        reason: entry.reason,
+                    },
+                };
+
+                // Replacement strings that contain " or " have multiple options —
+                // offer them as manual suggestions rather than a single auto-fix.
+                const isMulti = entry.replacement.includes(' or ');
+
+                if (isMulti) {
+                    const options = entry.replacement.split(' or ').map((s) => s.trim());
+                    report.suggest = options.map((opt) => ({
+                        messageId: 'replaceWith',
+                        data: { name: functionName, replacement: opt },
+                        fix: (fixer) =>
+                            fixer.replaceTextRange(
+                                [node.range[0], node.range[0] + functionName.length],
+                                opt,
+                            ),
+                    }));
+                } else {
+                    report.fix = (fixer) =>
+                        fixer.replaceTextRange(
+                            [node.range[0], node.range[0] + functionName.length],
+                            entry.replacement,
+                        );
+                }
+
+                context.report(report);
+            },
+        };
+    },
+};

package/src/rules/amp/no-email-excluded-function.js

@@ -0,0 +1,72 @@
+/**
+ * Rule: no-email-excluded-function
+ *
+ * Flags calls to AMPscript functions that are not available in the email
+ * execution context. These functions only work on CloudPages, landing pages,
+ * and other non-email contexts. Using them in emails causes runtime errors.
+ */
+
+import { isEmailExcluded } from 'ampscript-data';
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow AMPscript functions that are not available in email context',
+        },
+        messages: {
+            emailExcluded:
+                "'{{name}}' is not available in the email execution context. This function only works on CloudPages and landing pages.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    context: {
+                        enum: ['email', 'cloudpage', 'auto'],
+                        default: 'email',
+                        description:
+                            'Set to "email" to flag email-excluded functions, "cloudpage" to skip checking, "auto" to infer from file extension.',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+
+    create(context) {
+        const options = context.options[0] || {};
+        const contextMode = options.context || 'email';
+
+        if (contextMode === 'cloudpage') {
+            return {};
+        }
+
+        if (contextMode === 'auto') {
+            const filename = context.filename || '';
+            const lower = filename.toLowerCase();
+            if (
+                lower.includes('cloudpage') ||
+                lower.includes('landing') ||
+                lower.endsWith('.html')
+            ) {
+                return {};
+            }
+        }
+
+        return {
+            FunctionCall(node) {
+                const functionName = node.name || (node.callee && node.callee.name) || '';
+                if (!functionName) return;
+
+                if (isEmailExcluded(functionName)) {
+                    context.report({
+                        node,
+                        messageId: 'emailExcluded',
+                        data: { name: functionName },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/amp/no-empty-block.js

@@ -0,0 +1,37 @@
+export default {
+    meta: {
+        type: 'suggestion',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow empty AMPscript blocks that produce no output or side effects',
+            recommended: true,
+        },
+        messages: {
+            emptyBlock: 'Empty AMPscript block. Remove it or add content.',
+            removeEmptyBlock: 'Remove the empty AMPscript block',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            Block(node) {
+                const meaningful = (node.statements || []).filter((s) => s.type !== 'Comment');
+                if (meaningful.length === 0) {
+                    context.report({
+                        node,
+                        messageId: 'emptyBlock',
+                        suggest: [
+                            {
+                                messageId: 'removeEmptyBlock',
+                                fix(fixer) {
+                                    return fixer.removeRange(node.range);
+                                },
+                            },
+                        ],
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/amp/no-empty-then.js

@@ -0,0 +1,34 @@
+/**
+ * Flags IF statements whose THEN branch (consequent) is empty.
+ *
+ * An empty consequent is almost always a mistake — either the condition
+ * should be inverted (logic moved to ELSE) or the body was accidentally
+ * deleted.
+ */
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow IF statements with an empty THEN consequent',
+            recommended: true,
+        },
+        messages: {
+            emptyThen: 'IF block has an empty THEN consequent.',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            AmpIfStatement(node) {
+                if (node.consequent && node.consequent.length === 0) {
+                    context.report({
+                        node,
+                        messageId: 'emptyThen',
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/amp/no-html-comment.js

@@ -0,0 +1,57 @@
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+const WRAPPED_BLOCK_COMMENT_RE = /^<!--(\/\*[\s\S]*?\*\/)-->$/;
+
+export default {
+    meta: {
+        type: 'problem',
+        fixable: 'code',
+        docs: {
+            description:
+                'Disallow HTML comment syntax (<!-- ... -->) inside AMPscript regions. Use /* ... */ instead.',
+            recommended: true,
+        },
+        messages: {
+            htmlWrappedComment:
+                'HTML comment wrapper around an AMPscript comment is not valid. Use /* ... */ directly.',
+            htmlComment:
+                'HTML comment syntax is not valid inside AMPscript. Use /* ... */ instead.',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            Program() {
+                const sourceCode = context.sourceCode;
+                const text = sourceCode.getText();
+
+                HTML_COMMENT_RE.lastIndex = 0;
+                let match;
+                while ((match = HTML_COMMENT_RE.exec(text)) !== null) {
+                    const fullMatch = match[0];
+                    const start = match.index;
+                    const end = start + fullMatch.length;
+
+                    const wrappedMatch = WRAPPED_BLOCK_COMMENT_RE.exec(fullMatch);
+                    const isWrapped = wrappedMatch !== null;
+                    const innerBlockComment = isWrapped ? wrappedMatch[1] : null;
+
+                    context.report({
+                        loc: {
+                            start: sourceCode.getLocFromIndex(start),
+                            end: sourceCode.getLocFromIndex(end),
+                        },
+                        messageId: isWrapped ? 'htmlWrappedComment' : 'htmlComment',
+                        fix(fixer) {
+                            if (isWrapped) {
+                                return fixer.replaceTextRange([start, end], innerBlockComment);
+                            }
+                            const inner = fullMatch.slice(4, -3).trim();
+                            return fixer.replaceTextRange([start, end], `/* ${inner} */`);
+                        },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/amp/no-inline-statement.js

@@ -0,0 +1,45 @@
+/**
+ * Inline expressions (%%=...=%%) should contain a single output expression,
+ * not control-flow statements like `if`, `for`, `set`, or `var`.
+ *
+ * These constructs belong in block AMPscript (%%[...]%%).
+ */
+
+const STATEMENT_TYPES = new Set([
+    'AmpIfStatement',
+    'AmpForStatement',
+    'SetStatement',
+    'VarDeclaration',
+]);
+
+export default {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow control-flow statements inside inline expressions (%%=...=%%)',
+            recommended: true,
+        },
+        messages: {
+            inlineStatement:
+                'Inline expressions (%%=...=%%) should contain a single output expression. Move {{kind}} to a block (%%[...]%%).',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            InlineExpression(node) {
+                const expr = node.expression;
+                if (!expr) return;
+
+                if (STATEMENT_TYPES.has(expr.type)) {
+                    context.report({
+                        node: expr,
+                        messageId: 'inlineStatement',
+                        data: { kind: expr.type },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/amp/no-js-line-comment.js

@@ -0,0 +1,54 @@
+// Matches // comments but avoids :// (URL protocol separators).
+// Strings are not a concern here because the processor feeds only AMPscript
+// source to the parser/rules, but the ampscript-parser does not blank string
+// contents before rule execution. To be safe, we skip matches that are clearly
+// inside quoted strings by checking surrounding context via the source text.
+const JS_LINE_COMMENT_RE = /(?<!:)\/\/.*/g;
+
+export default {
+    meta: {
+        type: 'problem',
+        fixable: 'code',
+        docs: {
+            description:
+                'Disallow JavaScript-style single-line comments (// ...) inside AMPscript regions. Use /* ... */ instead.',
+            recommended: true,
+        },
+        messages: {
+            jsLineComment:
+                'Single-line // comments are not valid AMPscript syntax. Use /* ... */ instead.',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            Program() {
+                const sourceCode = context.sourceCode;
+                const text = sourceCode.getText();
+
+                JS_LINE_COMMENT_RE.lastIndex = 0;
+                let match;
+                while ((match = JS_LINE_COMMENT_RE.exec(text)) !== null) {
+                    const start = match.index;
+                    const end = start + match[0].length;
+                    const commentText = match[0].slice(2).trim();
+
+                    context.report({
+                        loc: {
+                            start: sourceCode.getLocFromIndex(start),
+                            end: sourceCode.getLocFromIndex(end),
+                        },
+                        messageId: 'jsLineComment',
+                        fix(fixer) {
+                            return fixer.replaceTextRange(
+                                [start, end],
+                                commentText.length > 0 ? `/* ${commentText} */` : '/**/',
+                            );
+                        },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/amp/no-loop-counter-assign.js

@@ -0,0 +1,71 @@
+/**
+ * Flags `set` statements inside a `for` loop that target the loop counter
+ * variable. Modifying the counter is documented as causing validation or
+ * runtime errors in AMPscript.
+ */
+
+export default {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description:
+                'Disallow assigning to the `for` loop counter variable inside the loop body',
+            recommended: true,
+        },
+        messages: {
+            counterAssign:
+                "Do not assign to loop counter '{{name}}' inside the for loop. AMPscript does not allow modifying the counter variable.",
+        },
+        schema: [],
+    },
+
+    create(context) {
+        const counterStack = [];
+
+        function checkBody(body) {
+            for (const stmt of body) {
+                if (stmt.type === 'SetStatement' && stmt.target) {
+                    const current = counterStack.at(-1);
+                    if (current && stmt.target.value.toLowerCase() === current.toLowerCase()) {
+                        context.report({
+                            node: stmt.target,
+                            messageId: 'counterAssign',
+                            data: { name: stmt.target.value },
+                        });
+                    }
+                }
+                if (stmt.type === 'VarDeclaration') {
+                    const current = counterStack.at(-1);
+                    if (current) {
+                        for (const v of stmt.variables) {
+                            if (v.value.toLowerCase() === current.toLowerCase()) {
+                                context.report({
+                                    node: v,
+                                    messageId: 'counterAssign',
+                                    data: { name: v.value },
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        return {
+            AmpForStatement(node) {
+                if (node.counter) {
+                    counterStack.push(node.counter.value);
+                }
+                if (node.body) {
+                    checkBody(node.body);
+                }
+            },
+
+            'AmpForStatement:exit'(node) {
+                if (node.counter) {
+                    counterStack.pop();
+                }
+            },
+        };
+    },
+};

package/src/rules/amp/no-nested-ampscript-delimiter.js

@@ -0,0 +1,102 @@
+// The processor extracts each AMPscript region into its own virtual .amp file,
+// including the outer delimiters (%%[...]/%%] or <script>...</script>).
+// Any %%[ or %%= found INSIDE the outer delimiters is nested and invalid.
+const DELIMITER_RE = /%%\[|%%=/g;
+const SCRIPT_TAG_RE = /^[\n]*<script\b/i;
+const BLOCK_OPEN_RE = /^[\n]*(%%\[)/;
+const INLINE_OPEN_RE = /^[\n]*(%%=)/;
+const BLOCK_CLOSE_SUFFIX = ']%%';
+const INLINE_CLOSE_SUFFIX = '=%%';
+
+export default {
+    meta: {
+        type: 'problem',
+        fixable: 'code',
+        docs: {
+            description:
+                'Disallow %%[ or %%= delimiters inside an already-open AMPscript region.',
+            recommended: true,
+        },
+        messages: {
+            nestedDelimiterInScript:
+                'AMPscript delimiter {{delimiter}} is not needed inside a <script language="ampscript"> block.',
+            nestedDelimiter:
+                'Nested {{delimiter}} inside an already-open AMPscript block.',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            Program() {
+                const sourceCode = context.sourceCode;
+                const text = sourceCode.getText();
+                const isScriptBlock = SCRIPT_TAG_RE.test(text);
+
+                // For %%[...]%% and %%=...=%% blocks the processor includes the outer
+                // delimiters. Record their positions so we can skip the outermost ones.
+                let outerOpenStart = -1;
+                let outerCloseStart = -1;
+                let outerCloseSuffix = BLOCK_CLOSE_SUFFIX;
+
+                if (!isScriptBlock) {
+                    const blockOpenMatch = BLOCK_OPEN_RE.exec(text);
+                    const inlineOpenMatch = INLINE_OPEN_RE.exec(text);
+
+                    if (blockOpenMatch) {
+                        outerOpenStart = blockOpenMatch.index + blockOpenMatch[0].length - 3;
+                        outerCloseSuffix = BLOCK_CLOSE_SUFFIX;
+                    } else if (inlineOpenMatch) {
+                        outerOpenStart = inlineOpenMatch.index + inlineOpenMatch[0].length - 3;
+                        outerCloseSuffix = INLINE_CLOSE_SUFFIX;
+                    }
+
+                    // The outer close is the last occurrence of the matching close token
+                    const lastClose = text.lastIndexOf(outerCloseSuffix);
+                    if (lastClose !== -1) {
+                        outerCloseStart = lastClose;
+                    }
+                }
+
+                DELIMITER_RE.lastIndex = 0;
+                let match;
+                while ((match = DELIMITER_RE.exec(text)) !== null) {
+                    const delimiter = match[0];
+                    const start = match.index;
+                    const end = start + delimiter.length;
+
+                    // Skip the outermost %%[ opener (it is the block wrapper, not nested)
+                    if (!isScriptBlock && start === outerOpenStart) continue;
+
+                    const closeToken = delimiter === '%%[' ? ']%%' : '=%%';
+
+                    // Find the matching close token for the fix (first occurrence after this open)
+                    let closeIndex = text.indexOf(closeToken, end);
+                    // Don't use the outer ]%% as the fix target for an inner %%[
+                    if (!isScriptBlock && closeIndex === outerCloseStart) {
+                        closeIndex = -1;
+                    }
+
+                    context.report({
+                        loc: {
+                            start: sourceCode.getLocFromIndex(start),
+                            end: sourceCode.getLocFromIndex(end),
+                        },
+                        messageId: isScriptBlock ? 'nestedDelimiterInScript' : 'nestedDelimiter',
+                        data: { delimiter },
+                        fix:
+                            closeIndex === -1
+                                ? (fixer) => fixer.removeRange([start, end])
+                                : (fixer) => [
+                                      fixer.removeRange([
+                                          closeIndex,
+                                          closeIndex + closeToken.length,
+                                      ]),
+                                      fixer.removeRange([start, end]),
+                                  ],
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/amp/no-nested-script-tag.js

@@ -0,0 +1,65 @@
+// The processor extracts each <script language="ampscript">...</script> block
+// as a virtual .amp file, including the opening tag in the emitted text.
+// Therefore, scanning the virtual source for a *second* opening tag catches
+// the case where a developer forgot a closing </script> and started a new block.
+const SCRIPT_OPEN_RE =
+    /<script\b(?=[^>]*\brunat\s*=\s*['"]server['"])(?=[^>]*\blanguage\s*=\s*['"]ampscript['"])[^>]*>/gi;
+
+export default {
+    meta: {
+        type: 'problem',
+        fixable: 'code',
+        docs: {
+            description:
+                'Disallow nested <script language="ampscript"> tags inside an already-open AMPscript script block.',
+            recommended: true,
+        },
+        messages: {
+            nestedScriptTag:
+                'Nested <script language="ampscript"> inside an already-open AMPscript block. Did you forget a </script> closing tag?',
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            Program() {
+                const sourceCode = context.sourceCode;
+                const text = sourceCode.getText();
+
+                // Only relevant when the virtual block starts with a <script> tag.
+                // %%[...]%% blocks cannot contain a nested <script> opening tag in
+                // a way the processor would expose, so skip non-script-tag blocks.
+                SCRIPT_OPEN_RE.lastIndex = 0;
+                if (!SCRIPT_OPEN_RE.test(text)) return;
+
+                // Reset and find all script open tags in this virtual block.
+                SCRIPT_OPEN_RE.lastIndex = 0;
+                const openTags = [];
+                let match;
+                while ((match = SCRIPT_OPEN_RE.exec(text)) !== null) {
+                    openTags.push({ index: match.index, length: match[0].length });
+                }
+
+                // The first tag is the expected outer opener.
+                // Any tag beyond the first is nested (invalid).
+                for (let index = 1; index < openTags.length; index++) {
+                    const tag = openTags[index];
+                    const start = tag.index;
+                    const end = start + tag.length;
+
+                    context.report({
+                        loc: {
+                            start: sourceCode.getLocFromIndex(start),
+                            end: sourceCode.getLocFromIndex(end),
+                        },
+                        messageId: 'nestedScriptTag',
+                        fix(fixer) {
+                            return fixer.replaceTextRange([start, start], '</script>\n');
+                        },
+                    });
+                }
+            },
+        };
+    },
+};