eslint-plugin-sfmc 4.6.0 → 4.7.0

package/README.md

@@ -140,6 +140,7 @@ export default [...sfmc.configs['recommended-next'], ...sfmc.configs['embedded-n
 | [`sfmc/ssjs-require-hasownproperty`](docs/rules/ssjs/require-hasownproperty.md)             | `warn`                   | Require `hasOwnProperty` guard in for-in loops                           |
 | [`sfmc/ssjs-prefer-platform-load-version`](docs/rules/ssjs/prefer-platform-load-version.md) | `warn`                   | Enforce a minimum `Platform.Load` version string                         |
 | [`sfmc/ssjs-no-unavailable-method`](docs/rules/ssjs/no-unavailable-method.md)               | `warn`                   | Flag Array/String methods unavailable or broken in SFMC's ES3 engine     |
+| [`sfmc/ssjs-no-nonfunctional-method`](docs/rules/ssjs/no-nonfunctional-method.md)           | `warn`                   | Flag Core Library methods that never take effect at runtime              |
 | [`sfmc/ssjs-prefer-parsejson-safe-arg`](docs/rules/ssjs/prefer-parsejson-safe-arg.md)       | `warn`                   | Require string coercion on `ParseJSON` argument                          |
 | [`sfmc/ssjs-no-switch-default`](docs/rules/ssjs/no-switch-default.md)                       | `warn`                   | Disallow `default` clause in `switch` statements                         |
 | [`sfmc/ssjs-no-treatascontent-injection`](docs/rules/ssjs/no-treatascontent-injection.md)   | `warn`                   | Flag dynamic string concatenation in `TreatAsContent` calls              |

package/docs/rules/ssjs/no-nonfunctional-method.md

@@ -0,0 +1,70 @@
+# `sfmc/ssjs-no-nonfunctional-method`
+
+> Warn when calling a Core Library method that resolves at runtime but has no known working invocation.
+
+| | |
+|---|---|
+| **Type** | `problem` |
+| **Default severity** | `warn` in `recommended` and `strict` |
+| **Fixable** | — |
+
+## Why This Rule Exists
+
+A few Core Library methods **exist** and **resolve** at runtime — the namespace or instance exposes them as callables — but exhaustive live testing has found **no working invocation**: every attempted call fails (returns the string `"Error"` or throws), and the documented success path could not be reproduced.
+
+Because these methods DO exist, they remain in completions and in the generated `.d.ts` (unlike nonexistent members). This rule warns at the **call site** so you know the call will not work at runtime, using the `nonFunctionalAtRuntime` flag from the ssjs-data catalog.
+
+## Coverage
+
+Both **static** and **instance** call styles are covered, mirroring `sfmc/ssjs-core-method-arity`:
+
+| Style | Example |
+|---|---|
+| Instance | `var fd = FilterDefinition.Init("x"); fd.Update({});` |
+| Static single-name | `FilterDefinition.Update({});` |
+| Static multi-part | `DataExtension.Rows.Add(rowObj);` |
+
+Flagged methods today: `FilterDefinition.Update`, `FilterDefinition.Remove`.
+
+## Settings
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| severity | `"error"` \| `"warn"` \| `"off"` | `"warn"` |
+
+This rule has no configuration options.
+
+## Examples
+
+**Not allowed:**
+
+```js
+Platform.Load("core", "1.1.5");
+
+var fd = FilterDefinition.Init("my-filter");
+
+/* FilterDefinition.Update has no known working invocation at runtime */
+fd.Update({ Name: "renamed" });
+
+/* FilterDefinition.Remove has no known working invocation at runtime */
+fd.Remove();
+```
+
+**Allowed:**
+
+```js
+Platform.Load("core", "1.1.5");
+
+var fd = FilterDefinition.Init("my-filter");
+
+/* Add, Init, Retrieve are working invocations */
+fd.Retrieve();
+fd.Add(filterDefinitionObj);
+```
+
+## When to Disable
+
+```js
+// eslint.config.js
+rules: { 'sfmc/ssjs-no-nonfunctional-method': 'off' }
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "eslint-plugin-sfmc",
-    "version": "4.6.0",
+    "version": "4.7.0",
     "description": "ESLint plugin for Salesforce Marketing Cloud Engagement+Next - AMPscript, Server-Side JavaScript (SSJS) and Handlebars",
     "type": "module",
     "main": "src/index.js",
@@ -42,7 +42,7 @@
         "eslint-plugin-mso-email": "^2.0.0",
         "handlebars-data": "^0.3.0",
         "mso-conditional-parser": "^2.0.1",
-        "ssjs-data": "^0.22.0"
+        "ssjs-data": "^1.0.0"
     },
     "peerDependencies": {
         "eslint": ">=9.0.0"

package/src/index.js

@@ -57,6 +57,7 @@ import ssjsNoSwitchDefault from './rules/ssjs/no-switch-default.js';
 import ssjsNoTreatAsContentInjection from './rules/ssjs/no-treatascontent-injection.js';
 import ssjsArgumentTypes from './rules/ssjs/ssjs-argument-types.js';
 import ssjsCoreMethodArity from './rules/ssjs/ssjs-core-method-arity.js';
+import ssjsNoNonfunctionalMethod from './rules/ssjs/ssjs-no-nonfunctional-method.js';
 import ssjsNoClrHeaderAccess from './rules/ssjs/no-clr-header-access.js';
 import ssjsRequireStringClrContent from './rules/ssjs/require-string-clr-content.js';
 import ssjsHttpPropertyValue from './rules/ssjs/http-property-value.js';
@@ -140,6 +141,7 @@ const plugin = {
         'ssjs-no-treatascontent-injection': ssjsNoTreatAsContentInjection,
         'ssjs-arg-types': ssjsArgumentTypes,
         'ssjs-core-method-arity': ssjsCoreMethodArity,
+        'ssjs-no-nonfunctional-method': ssjsNoNonfunctionalMethod,
         'ssjs-no-clr-header-access': ssjsNoClrHeaderAccess,
         'ssjs-require-string-clr-content': ssjsRequireStringClrContent,
         'ssjs-http-property-value': ssjsHttpPropertyValue,
@@ -187,6 +189,7 @@ const ssjsMcnRules = {
     'sfmc/ssjs-no-treatascontent-injection': 'off',
     'sfmc/ssjs-arg-types': 'off',
     'sfmc/ssjs-core-method-arity': 'off',
+    'sfmc/ssjs-no-nonfunctional-method': 'off',
     'sfmc/ssjs-no-clr-header-access': 'off',
     'sfmc/ssjs-require-string-clr-content': 'off',
     'sfmc/ssjs-http-property-value': 'off',
@@ -259,6 +262,7 @@ const ssjsRecommendedRules = {
     'sfmc/ssjs-no-treatascontent-injection': 'warn',
     'sfmc/ssjs-arg-types': 'warn',
     'sfmc/ssjs-core-method-arity': 'warn',
+    'sfmc/ssjs-no-nonfunctional-method': 'warn',
     'sfmc/ssjs-no-clr-header-access': 'error',
     'sfmc/ssjs-require-string-clr-content': 'error',
     'sfmc/ssjs-http-property-value': 'error',
@@ -284,6 +288,7 @@ const ssjsStrictRules = {
     'sfmc/ssjs-no-treatascontent-injection': 'error',
     'sfmc/ssjs-arg-types': 'warn',
     'sfmc/ssjs-core-method-arity': 'error',
+    'sfmc/ssjs-no-nonfunctional-method': 'warn',
     'sfmc/ssjs-no-clr-header-access': 'error',
     'sfmc/ssjs-require-string-clr-content': 'error',
     'sfmc/ssjs-http-property-value': 'error',

package/src/rules/ssjs/ssjs-no-nonfunctional-method.js

@@ -0,0 +1,222 @@
+/**
+ * Rule: ssjs-no-nonfunctional-method
+ *
+ * Warns when a Core Library method that RESOLVES at runtime but has NO known
+ * working invocation (ssjs-data `nonFunctionalAtRuntime`) is called. Unlike a
+ * nonexistent member, these methods DO exist (the namespace/instance exposes them
+ * as callables), so they remain in completions and the generated `.d.ts` — but
+ * every tested call fails, so the call site is flagged.
+ *
+ * Mirrors the receiver-resolution structure of ssjs-core-method-arity:
+ *
+ *   var fd = FilterDefinition.Init("x");
+ *   fd.Update({...});                  // instance → warn
+ *   DataExtension.Rows.Add(rowObj);    // static multi-part
+ */
+
+import { coreObjectNames, coreNonFunctionalMethodLookup } from 'ssjs-data';
+
+/**
+ * Extract a short factual pointer from an entry's officialDocsNote (first
+ * sentence) for the warning message. Returns an empty string when absent.
+ *
+ * @param {object} entry - ssjs-data method entry
+ * @returns {string} A short note, or empty string
+ */
+function shortNote(entry) {
+    if (!entry || typeof entry.officialDocsNote !== 'string') {
+        return '';
+    }
+    const trimmed = entry.officialDocsNote.trim();
+    if (trimmed === '') {
+        return '';
+    }
+    const sentenceEnd = trimmed.indexOf('. ');
+    return sentenceEnd === -1 ? trimmed : trimmed.slice(0, sentenceEnd + 1);
+}
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Warn when calling a Core Library method that resolves at runtime but has no known working invocation',
+        },
+        hasSuggestions: false,
+        messages: {
+            nonFunctional:
+                "'{{call}}' exists in SFMC SSJS but has no known working invocation at runtime (every tested call fails). {{note}}",
+        },
+        schema: [],
+    },
+
+    create(context) {
+        const coreVariables = new Map(); // varName → className
+
+        function checkNonFunctional(entry, callName, reportNode) {
+            if (!entry) {
+                return;
+            }
+            context.report({
+                node: reportNode,
+                messageId: 'nonFunctional',
+                data: { call: callName, note: shortNote(entry) },
+            });
+        }
+
+        return {
+            VariableDeclaration(node) {
+                for (const declaration of node.declarations) {
+                    if (
+                        !declaration.init ||
+                        !declaration.id ||
+                        declaration.id.type !== 'Identifier'
+                    ) {
+                        continue;
+                    }
+                    const coreType = getCoreInitType(declaration.init);
+                    if (coreType) {
+                        coreVariables.set(declaration.id.name, coreType);
+                    }
+                }
+            },
+
+            AssignmentExpression(node) {
+                if (node.left.type !== 'Identifier') {
+                    return;
+                }
+                const coreType = getCoreInitType(node.right);
+                if (coreType) {
+                    coreVariables.set(node.left.name, coreType);
+                }
+            },
+
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== 'MemberExpression') {
+                    return;
+                }
+                if (callee.property.type !== 'Identifier') {
+                    return;
+                }
+                const methodName = callee.property.name;
+
+                if (callee.object.type === 'Identifier') {
+                    const objectName = callee.object.name;
+
+                    // Core Library instance method: fd.Update(...)
+                    const coreType = coreVariables.get(objectName);
+                    if (coreType) {
+                        const classLookup = coreNonFunctionalMethodLookup.get(
+                            coreType.toLowerCase(),
+                        );
+                        if (classLookup) {
+                            const entry = classLookup.get(methodName.toLowerCase());
+                            checkNonFunctional(entry, `${coreType}.${methodName}`, callee.property);
+                        }
+                        return;
+                    }
+
+                    // Static single-name: FilterDefinition.Update(...) directly
+                    if (coreObjectNames.has(objectName)) {
+                        const classLookup = coreNonFunctionalMethodLookup.get(
+                            objectName.toLowerCase(),
+                        );
+                        if (classLookup) {
+                            const entry = classLookup.get(methodName.toLowerCase());
+                            checkNonFunctional(
+                                entry,
+                                `${objectName}.${methodName}`,
+                                callee.property,
+                            );
+                        }
+                        return;
+                    }
+                }
+
+                // Static multi-part: DataExtension.Rows.Add(...)
+                const objectPath = getMemberPath(callee.object);
+                if (objectPath && coreObjectNames.has(objectPath)) {
+                    const classLookup = coreNonFunctionalMethodLookup.get(objectPath.toLowerCase());
+                    if (classLookup) {
+                        const entry = classLookup.get(methodName.toLowerCase());
+                        checkNonFunctional(entry, `${objectPath}.${methodName}`, callee.property);
+                    }
+                    return;
+                }
+
+                // Instance sub-path: de.Rows.Add(...) where `de` is a tracked
+                // Init(...) instance. Substitute the instance's core type for the
+                // leftmost identifier and resolve the class key.
+                if (objectPath) {
+                    const segments = objectPath.split('.');
+                    const rootCoreType = coreVariables.get(segments[0]);
+                    if (rootCoreType) {
+                        const resolvedPath = [rootCoreType, ...segments.slice(1)].join('.');
+                        const classLookup = coreNonFunctionalMethodLookup.get(
+                            resolvedPath.toLowerCase(),
+                        );
+                        if (classLookup) {
+                            const entry = classLookup.get(methodName.toLowerCase());
+                            checkNonFunctional(
+                                entry,
+                                `${resolvedPath}.${methodName}`,
+                                callee.property,
+                            );
+                        }
+                    }
+                }
+            },
+        };
+    },
+};
+
+/**
+ * Resolve the Core class name for a `Class.Init(...)` / `A.B.Init(...)` call.
+ *
+ * @param {object} node - the init expression node
+ * @returns {string|null} The resolved core class name, or null
+ */
+function getCoreInitType(node) {
+    if (!node || node.type !== 'CallExpression') {
+        return null;
+    }
+    const callee = node.callee;
+    if (callee.type !== 'MemberExpression') {
+        return null;
+    }
+    if (callee.property.type !== 'Identifier' || callee.property.name !== 'Init') {
+        return null;
+    }
+    if (callee.object.type === 'Identifier' && coreObjectNames.has(callee.object.name)) {
+        return callee.object.name;
+    }
+    if (
+        callee.object.type === 'MemberExpression' &&
+        callee.object.object.type === 'Identifier' &&
+        callee.object.property.type === 'Identifier'
+    ) {
+        const fullName = `${callee.object.object.name}.${callee.object.property.name}`;
+        if (coreObjectNames.has(fullName)) {
+            return fullName;
+        }
+    }
+    return null;
+}
+
+/**
+ * Build a dotted member path string from a MemberExpression / Identifier.
+ *
+ * @param {object} node - the object node
+ * @returns {string|null} The dotted path, or null
+ */
+function getMemberPath(node) {
+    if (node.type === 'Identifier') {
+        return node.name;
+    }
+    if (node.type === 'MemberExpression' && node.property.type === 'Identifier') {
+        const object = getMemberPath(node.object);
+        return object ? `${object}.${node.property.name}` : null;
+    }
+    return null;
+}