New rule 'no-unguarded-host-mutation' (#165)

Shinoni · lesya7 · web-flow · commit e963a3ec7b62 · 2024-10-16T13:12:32.000-07:00
* new 'no-unguarded-host-mutation' ESLint rule

* Make the rule generic

* Add 'recommended' to the LWC category

* Removing a reference to 'hydration'

---------

Co-authored-by: lturanscaia &lt;lturanscaia@salesforce.com&gt;
diff --git a/README.md b/README.md
@@ -86,6 +86,7 @@ To choose from three configuration settings, install the [`eslint-config-lwc`](h
 | [lwc/no-unsupported-ssr-properties](./docs/rules/no-unsupported-ssr-properties.md)                                   | disallow access of unsupported properties in SSR                   |         |
 | [lwc/no-node-env-in-ssr](./docs/rules/no-node-env-in-ssr.md)                                                         | disallow usage of process.env.NODE_ENV in SSR                      |         |
 | [lwc/valid-graphql-wire-adapter-callback-parameters](./docs/rules/valid-graphql-wire-adapter-callback-parameters.md) | ensure graphql wire adapters are using 'errors' instead of 'error' |         |
+| [lwc/no-host-mutation-in-connected-callback](./docs/rules/no-host-mutation-in-connected-callback.md)                 | disallow the host element mutation in 'connectedCallback'          |         |
 
 ### Best practices
 
diff --git a/docs/rules/no-host-mutation-in-connected-callback.md b/docs/rules/no-host-mutation-in-connected-callback.md
@@ -0,0 +1,50 @@
+# Avoiding host element mutation in connected callback
+
+To ensure consistent behavior in Lightning Web Components (LWC), it is important to avoid mutating the host element within the `connectedCallback` method. Mutations can lead to unpredictable outcomes and inconsistencies in component behavior.
+
+## Rule details
+
+To prevent issues with component lifecycle consistency, avoid mutating the host element in `connectedCallback`. This includes:
+
+-   `this.setAttribute`
+-   `this.classList.add`
+
+Example of **incorrect** code:
+
+```html
+<template>
+    <x-child></x-child>
+</template>
+```
+
+```js
+import { LightningElement, api } from 'lwc';
+
+export default class ExampleComponent extends LightningElement {
+    @api condition;
+
+    connectedCallback() {
+        this.classList.add(`conditional-class-${this.condition}`);
+        this.setAttribute('data-some-attribute', 'value');
+    }
+}
+```
+
+Example of **correct** code:
+
+```html
+<template>
+    <div class="{theClassMyChildNeeds}">
+        <x-child></x-child>
+    </div>
+</template>
+```
+
+```js
+export default class Cmp extends LightningElement {
+    @api fromOutside;
+    get theClassMyChildNeeds() {
+        return `my-child-needs-${this.fromOutside}`;
+    }
+}
+```
diff --git a/lib/index.js b/lib/index.js
@@ -32,6 +32,7 @@ const rules = {
     'no-restricted-browser-globals-during-ssr': require('./rules/no-restricted-browser-globals-during-ssr'),
     'no-unsupported-ssr-properties': require('./rules/no-unsupported-ssr-properties'),
     'no-node-env-in-ssr': require('./rules/no-node-env-in-ssr'),
+    'no-host-mutation-in-connected-callback': require('./rules/no-host-mutation-in-connected-callback'),
 };
 
 module.exports = {
diff --git a/lib/rules/no-host-mutation-in-connected-callback.js b/lib/rules/no-host-mutation-in-connected-callback.js
@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2024, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+'use strict';
+
+const { docUrl } = require('../util/doc-url');
+
+module.exports = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow mutations to the host element in connectedCallback',
+            category: 'LWC',
+            recommended: true,
+            url: docUrl('docs/rules/no-host-mutation-in-connected-callback'),
+        },
+        messages: {
+            noHostMutation: 'Mutations to the host element in connectedCallback are not allowed.',
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            MethodDefinition(node) {
+                if (isConnectedCallback(node)) {
+                    const bodyStatements = node.value.body.body;
+
+                    for (const statement of bodyStatements) {
+                        if (isMutationStatement(statement)) {
+                            context.report({
+                                node: statement,
+                                messageId: 'noHostMutation',
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+};
+
+function isConnectedCallback(node) {
+    return node.key.name === 'connectedCallback' && node.value.body.type === 'BlockStatement';
+}
+
+function isMutationStatement(statement) {
+    return (
+        statement.type === 'ExpressionStatement' &&
+        statement.expression.type === 'CallExpression' &&
+        isMutatingHostElement(statement.expression)
+    );
+}
+
+function isMutatingHostElement(expression) {
+    const callee = expression.callee;
+
+    return (
+        callee.type === 'MemberExpression' &&
+        (callee.property.name === 'setAttribute' ||
+            (callee.object &&
+                callee.object.property &&
+                callee.object.property.name === 'classList' &&
+                callee.property.name === 'add'))
+    );
+}
diff --git a/test/lib/rules/no-host-mutation-in-connected-callback.js b/test/lib/rules/no-host-mutation-in-connected-callback.js
@@ -0,0 +1,127 @@
+/*
+ * Copyright (c) 2024, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+'use strict';
+
+const { testRule, testTypeScript } = require('../shared');
+
+testRule('no-host-mutation-in-connected-callback', {
+    valid: [
+        {
+            code: `
+                import { LightningElement } from 'lwc';
+                export default class Cmp extends LightningElement {
+                    @api fromOutside;
+                    get theClassMyChildNeeds() {
+                        return \`my-child-needs-\${this.fromOutside}\`;
+                    }
+                }
+            `,
+        },
+        {
+            code: `
+                import { LightningElement } from 'lwc';
+                export default class Cmp extends LightningElement {
+                    @api fromOutside;
+                    get customAttributes() {
+                        return { class: \`my-child-\${this.fromOutside}\` };
+                    }
+                }
+            `,
+        },
+    ],
+    invalid: [
+        {
+            code: `
+                import { LightningElement } from 'lwc';
+                export default class Cmp extends LightningElement {
+                    connectedCallback() {
+                        this.setAttribute('class', \`my-child-\${this.fromOutside}\`);
+                    }
+                }
+            `,
+            errors: [
+                {
+                    message: 'Mutations to the host element in connectedCallback are not allowed.',
+                },
+            ],
+        },
+        {
+            code: `
+                import { LightningElement } from 'lwc';
+                export default class Cmp extends LightningElement {
+                    connectedCallback() {
+                        this.classList.add(\`my-child-needs-\${this.fromOutside}\`);
+                    }
+                }
+            `,
+            errors: [
+                {
+                    message: 'Mutations to the host element in connectedCallback are not allowed.',
+                },
+            ],
+        },
+    ],
+});
+
+testTypeScript('no-host-mutation-in-connected-callback', {
+    valid: [
+        {
+            code: `
+                import { LightningElement } from 'lwc';
+                export default class Cmp extends LightningElement {
+                    @api fromOutside: string;
+                    get theClassMyChildNeeds(): string {
+                        return \`my-child-needs-\${this.fromOutside}\`;
+                    }
+                }
+            `,
+        },
+        {
+            code: `
+                import { LightningElement } from 'lwc';
+                export default class Cmp extends LightningElement {
+                    @api fromOutside: string;
+                    get customAttributes(): { class: string } {
+                        return { class: \`my-child-\${this.fromOutside}\` };
+                    }
+                }
+            `,
+        },
+    ],
+    invalid: [
+        {
+            code: `
+                import { LightningElement } from 'lwc';
+                export default class Cmp extends LightningElement {
+                    connectedCallback() {
+                        this.setAttribute('class', \`my-child-\${this.fromOutside}\`);
+                    }
+                }
+            `,
+            errors: [
+                {
+                    message: 'Mutations to the host element in connectedCallback are not allowed.',
+                },
+            ],
+        },
+        {
+            code: `
+                import { LightningElement } from 'lwc';
+                export default class Cmp extends LightningElement {
+                    connectedCallback() {
+                        this.classList.add(\`my-child-needs-\${this.fromOutside}\`);
+                    }
+                }
+            `,
+            errors: [
+                {
+                    message: 'Mutations to the host element in connectedCallback are not allowed.',
+                },
+            ],
+        },
+    ],
+});
