eslint-plugin-sfmc 2.1.1 → 2.3.0

package/README.md

@@ -100,6 +100,7 @@ export default [
 | ------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------ |
 | [`sfmc/amp-no-unknown-function`](docs/rules/amp/no-unknown-function.md)                     | `error` | Disallow calls to unknown AMPscript functions                |
 | [`sfmc/amp-function-arity`](docs/rules/amp/function-arity.md)                               | `error` | Enforce correct argument counts                              |
+| [`sfmc/amp-arg-types`](docs/rules/amp/arg-types.md)                                         | `error` | Check that literal arguments match expected parameter types and allowed values |
 | [`sfmc/amp-set-requires-target`](docs/rules/amp/set-requires-target.md)                     | `error` | Require `set` to have a target variable                      |
 | [`sfmc/amp-no-smart-quotes`](docs/rules/amp/no-smart-quotes.md)                             | `error` | Disallow smart/curly quotes in strings                       |
 | [`sfmc/amp-no-var-redeclaration`](docs/rules/amp/no-var-redeclaration.md)                   | `warn`  | Disallow re-declaring a variable with `var`                  |

package/docs/rules/amp/arg-types.md

@@ -0,0 +1,61 @@
+# `sfmc/amp-arg-types`
+
+> Check that literal arguments match the expected parameter types and allowed values for AMPscript functions.
+
+| | |
+|---|---|
+| **Type** | `suggestion` |
+| **Default severity** | `error` in `recommended` and `strict` |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+Some AMPscript function parameters only accept a fixed set of keyword values. For example, the second argument of `DatePart` must be one of `year`, `Y`, `month`, `M`, `monthName`, `day`, `D`, `hour`, `H`, `minute`, or `MI`. Passing any other value is a bug that surfaces only at send/render time.
+
+The Salesforce catalog records these allowed values as an `enum` on the parameter. This rule checks every static literal argument — strings, numbers, and booleans — against the parameter's `enum` (case-insensitive) and reports a mismatch. Variables and expressions are skipped because their value cannot be determined statically.
+
+This rule is the AMPscript counterpart of [`sfmc/ssjs-arg-types`](../ssjs/arg-types.md) and may be expanded later to cover additional argument-type checks.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"error"` |
+
+This rule has no configuration options.
+
+### Examples
+
+**Not allowed:**
+
+```ampscript
+%%[
+  /* 'decade' is not a valid datePart */
+  set @x = DatePart('2026-01-15', 'decade')
+
+  /* a number is not a valid datePart either */
+  set @y = DatePart('2026-01-15', 5)
+]%%
+```
+
+**Allowed:**
+
+```ampscript
+%%[
+  /* exact-case enum value */
+  set @x = DatePart('2026-01-15', 'Y')
+
+  /* case-insensitive match */
+  set @y = DatePart('2026-01-15', 'year')
+
+  /* variable argument — not statically checkable, skipped */
+  set @z = DatePart(@d, @part)
+]%%
+```
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/amp-arg-types': 'off' }
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "eslint-plugin-sfmc",
-    "version": "2.1.1",
+    "version": "2.3.0",
     "description": "ESLint plugin for Salesforce Marketing Cloud — AMPscript and Server-Side JavaScript (SSJS)",
     "type": "module",
     "main": "src/index.js",
@@ -32,9 +32,9 @@
         "sfmc"
     ],
     "dependencies": {
-        "ampscript-data": "^2.0.1",
+        "ampscript-data": "^2.0.3",
         "ampscript-parser": "^0.1.3",
-        "ssjs-data": "^0.4.0"
+        "ssjs-data": "^0.5.0"
     },
     "peerDependencies": {
         "eslint": ">=9.0.0"

package/src/index.js

@@ -23,6 +23,7 @@ import ampNoLoopCounterAssign from './rules/amp/no-loop-counter-assign.js';
 import ampNoInlineStatement from './rules/amp/no-inline-statement.js';
 import ampRequireVariableDeclaration from './rules/amp/require-variable-declaration.js';
 import ampFunctionArity from './rules/amp/function-arity.js';
+import ampArgTypes from './rules/amp/arg-types.js';
 import ampNoEmailExcludedFunction from './rules/amp/no-email-excluded-function.js';
 import ampNoDeprecatedFunction from './rules/amp/no-deprecated-function.js';
 import ampNamingConvention from './rules/amp/naming-convention.js';
@@ -82,6 +83,7 @@ const plugin = {
         'amp-no-inline-statement': ampNoInlineStatement,
         'amp-require-variable-declaration': ampRequireVariableDeclaration,
         'amp-function-arity': ampFunctionArity,
+        'amp-arg-types': ampArgTypes,
         'amp-no-email-excluded-function': ampNoEmailExcludedFunction,
         'amp-no-deprecated-function': ampNoDeprecatedFunction,
         'amp-naming-convention': ampNamingConvention,
@@ -160,6 +162,7 @@ const ampRecommendedRules = {
     'sfmc/amp-no-loop-counter-assign': 'warn',
     'sfmc/amp-no-inline-statement': 'warn',
     'sfmc/amp-function-arity': 'error',
+    'sfmc/amp-arg-types': 'error',
     'sfmc/amp-no-deprecated-function': 'warn',
     'sfmc/amp-naming-convention': 'warn',
     'sfmc/amp-no-empty-then': 'warn',
@@ -181,6 +184,7 @@ const ampStrictRules = {
     'sfmc/amp-no-inline-statement': 'error',
     'sfmc/amp-require-variable-declaration': 'warn',
     'sfmc/amp-function-arity': 'error',
+    'sfmc/amp-arg-types': 'error',
     'sfmc/amp-no-email-excluded-function': ['error', { context: 'email' }],
     'sfmc/amp-no-deprecated-function': 'error',
     'sfmc/amp-naming-convention': ['error', { format: 'camelCase' }],

package/src/rules/amp/arg-types.js

@@ -0,0 +1,91 @@
+/**
+ * Rule: arg-types
+ *
+ * Validates literal arguments passed to AMPscript functions against the
+ * constraints declared in the ampscript-data catalog. Currently it checks
+ * parameters that declare an `enum` of allowed values: a static literal
+ * argument (string, number, or boolean) must be one of those values
+ * (case-insensitive). Variables and expressions are skipped because their
+ * value cannot be determined statically.
+ *
+ * This rule is the AMPscript counterpart of `ssjs-arg-types` and may be
+ * expanded later to cover additional argument-type checks.
+ *
+ * Example: DatePart('2026-01-15', 'decade') — 'decade' is not a valid datePart.
+ */
+
+import { functionLookup } from 'ampscript-data';
+
+// AMPscript AST node types that represent a static, statically-resolvable literal.
+const STATIC_LITERAL_TYPES = new Set(['StringLiteral', 'NumberLiteral', 'BooleanLiteral']);
+
+/**
+ * Returns the comparable string value of a static AMPscript literal node
+ * (string, number, or boolean), or null when the argument is not a static
+ * literal (e.g. a variable or expression) and cannot be validated against an
+ * enum.
+ *
+ * @param {object} arg - AMPscript argument AST node.
+ * @returns {string | null} The literal value as a string, or null.
+ */
+function staticLiteralValue(arg) {
+    if (!arg || !STATIC_LITERAL_TYPES.has(arg.type)) {
+        return null;
+    }
+    return String(arg.value);
+}
+
+export default {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description:
+                'Check that literal arguments match the expected parameter types and allowed values for AMPscript functions',
+            recommended: true,
+        },
+        messages: {
+            invalidEnumValue:
+                "Argument '{{param}}' of '{{name}}' must be one of: {{allowed}}. Received '{{actual}}'.",
+        },
+        schema: [],
+    },
+
+    create(context) {
+        return {
+            FunctionCall(node) {
+                const entry = functionLookup.get(node.name.toLowerCase());
+                if (!entry || !Array.isArray(entry.params)) {
+                    return;
+                }
+
+                for (const [i, arg] of node.arguments.entries()) {
+                    const param = entry.params[i];
+                    if (!param || !Array.isArray(param.enum) || param.enum.length === 0) {
+                        continue;
+                    }
+                    // Only validate static literals (string, number, boolean);
+                    // variables/expressions cannot be resolved statically.
+                    const actual = staticLiteralValue(arg);
+                    if (actual === null) {
+                        continue;
+                    }
+                    const isAllowed = param.enum.some(
+                        (v) => String(v).toLowerCase() === actual.toLowerCase(),
+                    );
+                    if (!isAllowed) {
+                        context.report({
+                            node: arg,
+                            messageId: 'invalidEnumValue',
+                            data: {
+                                name: entry.name,
+                                param: param.name,
+                                allowed: param.enum.join(', '),
+                                actual,
+                            },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};