@n8n/eslint-plugin-community-nodes 0.12.0 → 0.14.0

package/docs/rules/valid-peer-dependencies.md

@@ -0,0 +1,72 @@
+# Require community node package.json peerDependencies to contain only "n8n-workflow": "*" (and optionally "ai-node-sdk") (`@n8n/community-nodes/valid-peer-dependencies`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Community node packages must declare their n8n integration via `peerDependencies` so that they resolve against the host n8n installation rather than bundling their own copy. The only permitted entries are:
+
+- `n8n-workflow` — required, must be exactly `"*"` (no pinned or ranged versions)
+- `ai-node-sdk` — optional, present only for AI nodes (its shape is validated by [`ai-node-package-json`](ai-node-package-json.md))
+
+Any other entry (notably `n8n-core`) is flagged because it causes duplicate or incompatible copies of n8n internals to be loaded at runtime.
+
+The rule checks:
+
+- `peerDependencies` is present in `package.json`
+- `n8n-workflow` is listed with value `"*"`
+- No other packages (besides `ai-node-sdk`) appear in `peerDependencies`
+
+## Examples
+
+### ❌ Incorrect
+
+```json
+{
+  "name": "n8n-nodes-example"
+}
+```
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "peerDependencies": {
+    "n8n-workflow": "^1.0.0"
+  }
+}
+```
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "peerDependencies": {
+    "n8n-workflow": "*",
+    "n8n-core": "*"
+  }
+}
+```
+
+### ✅ Correct
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  }
+}
+```
+
+```json
+{
+  "name": "n8n-nodes-my-ai-node",
+  "peerDependencies": {
+    "n8n-workflow": "*",
+    "ai-node-sdk": "*"
+  }
+}
+```

package/docs/rules/webhook-lifecycle-complete.md

@@ -0,0 +1,88 @@
+# Require webhook trigger nodes to implement the complete webhookMethods lifecycle (checkExists, create, delete) (`@n8n/community-nodes/webhook-lifecycle-complete`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Webhook-based trigger nodes must implement a complete webhook lifecycle so that
+n8n can register, verify, and clean up webhooks on the third-party service.
+Missing any of the three methods results in leaked webhooks, duplicated
+registrations, or workflows that silently stop firing.
+
+This rule applies to node classes that:
+
+- declare a non-empty `webhooks` array in their `description`, or
+- define a `webhookMethods` class property.
+
+For every webhook group inside `webhookMethods` (typically `default`), the
+methods `checkExists`, `create`, and `delete` must all be implemented.
+
+Polling triggers (trigger nodes without a `webhooks` array and without
+`webhookMethods`) are intentionally out of scope.
+
+## Examples
+
+### ❌ Incorrect
+
+Webhook trigger without any lifecycle methods:
+
+```typescript
+export class MyTrigger implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Trigger',
+    name: 'myTrigger',
+    group: ['trigger'],
+    version: 1,
+    description: 'Trigger on events',
+    defaults: { name: 'My Trigger' },
+    inputs: [],
+    outputs: ['main'],
+    webhooks: [
+      { name: 'default', httpMethod: 'POST', responseMode: 'onReceived', path: 'webhook' },
+    ],
+    properties: [],
+  };
+}
+```
+
+Webhook trigger with an incomplete `webhookMethods.default`:
+
+```typescript
+export class MyTrigger implements INodeType {
+  description: INodeTypeDescription = { /* ... */ };
+
+  webhookMethods = {
+    default: {
+      async create(this: IHookFunctions): Promise<boolean> { /* ... */ return true; },
+      // Missing checkExists and delete
+    },
+  };
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class MyTrigger implements INodeType {
+  description: INodeTypeDescription = { /* ... */ };
+
+  webhookMethods = {
+    default: {
+      async checkExists(this: IHookFunctions): Promise<boolean> {
+        // Return true if the webhook is already registered on the third-party service.
+        return true;
+      },
+      async create(this: IHookFunctions): Promise<boolean> {
+        // Register the webhook with the third-party service and persist any IDs.
+        return true;
+      },
+      async delete(this: IHookFunctions): Promise<boolean> {
+        // Remove the webhook from the third-party service.
+        return true;
+      },
+    },
+  };
+}
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@n8n/eslint-plugin-community-nodes",
   "type": "module",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "main": "./dist/plugin.js",
   "types": "./dist/plugin.d.ts",
   "exports": {
@@ -23,8 +23,8 @@
     "typescript": "6.0.2",
     "vitest": "^4.1.1",
     "@n8n/typescript-config": "1.4.0",
-    "@n8n/vitest-config": "1.9.0",
-    "n8n-workflow": "2.17.0"
+    "n8n-workflow": "2.19.0",
+    "@n8n/vitest-config": "1.10.0"
   },
   "peerDependencies": {
     "eslint": ">= 9",
@@ -54,14 +54,14 @@
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
-    "build:docs": "eslint-doc-generator",
+    "build:docs": "pnpm build && eslint-doc-generator",
     "clean": "rimraf dist .turbo",
     "dev": "pnpm watch",
     "format": "biome format --write .",
     "format:check": "biome ci .",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
-    "lint:docs": "eslint-doc-generator --check",
+    "lint:docs": "pnpm build && eslint-doc-generator --check",
     "test": "vitest run",
     "test:unit": "vitest run",
     "test:dev": "vitest",

package/src/plugin.ts

@@ -31,15 +31,20 @@ const configs = {
 			'@n8n/community-nodes/no-credential-reuse': 'error',
 			'@n8n/community-nodes/no-forbidden-lifecycle-scripts': 'error',
 			'@n8n/community-nodes/no-http-request-with-manual-auth': 'error',
+			'@n8n/community-nodes/no-overrides-field': 'error',
 			'@n8n/community-nodes/icon-validation': 'error',
 			'@n8n/community-nodes/options-sorted-alphabetically': 'warn',
 			'@n8n/community-nodes/resource-operation-pattern': 'warn',
 			'@n8n/community-nodes/credential-documentation-url': 'error',
-			'@n8n/community-nodes/node-class-description-icon-missing': 'error',
 			'@n8n/community-nodes/cred-class-field-icon-missing': 'error',
 			'@n8n/community-nodes/node-connection-type-literal': 'error',
 			'@n8n/community-nodes/missing-paired-item': 'error',
+			'@n8n/community-nodes/require-community-node-keyword': 'warn',
 			'@n8n/community-nodes/require-continue-on-fail': 'error',
+			'@n8n/community-nodes/require-node-api-error': 'error',
+			'@n8n/community-nodes/require-node-description-fields': 'error',
+			'@n8n/community-nodes/valid-peer-dependencies': 'error',
+			'@n8n/community-nodes/webhook-lifecycle-complete': 'error',
 		},
 	},
 	recommendedWithoutN8nCloudSupport: {
@@ -57,15 +62,20 @@ const configs = {
 			'@n8n/community-nodes/no-credential-reuse': 'error',
 			'@n8n/community-nodes/no-forbidden-lifecycle-scripts': 'error',
 			'@n8n/community-nodes/no-http-request-with-manual-auth': 'error',
+			'@n8n/community-nodes/no-overrides-field': 'error',
 			'@n8n/community-nodes/icon-validation': 'error',
 			'@n8n/community-nodes/options-sorted-alphabetically': 'warn',
 			'@n8n/community-nodes/credential-documentation-url': 'error',
 			'@n8n/community-nodes/resource-operation-pattern': 'warn',
-			'@n8n/community-nodes/node-class-description-icon-missing': 'error',
 			'@n8n/community-nodes/cred-class-field-icon-missing': 'error',
 			'@n8n/community-nodes/node-connection-type-literal': 'error',
 			'@n8n/community-nodes/missing-paired-item': 'error',
+			'@n8n/community-nodes/require-community-node-keyword': 'warn',
 			'@n8n/community-nodes/require-continue-on-fail': 'error',
+			'@n8n/community-nodes/require-node-api-error': 'error',
+			'@n8n/community-nodes/require-node-description-fields': 'error',
+			'@n8n/community-nodes/valid-peer-dependencies': 'error',
+			'@n8n/community-nodes/webhook-lifecycle-complete': 'error',
 		},
 	},
 } satisfies Record<string, Linter.Config>;

package/src/rules/index.ts

@@ -11,6 +11,7 @@ import { NoCredentialReuseRule } from './no-credential-reuse.js';
 import { NoDeprecatedWorkflowFunctionsRule } from './no-deprecated-workflow-functions.js';
 import { NoForbiddenLifecycleScriptsRule } from './no-forbidden-lifecycle-scripts.js';
 import { NoHttpRequestWithManualAuthRule } from './no-http-request-with-manual-auth.js';
+import { NoOverridesFieldRule } from './no-overrides-field.js';
 import { NoRestrictedGlobalsRule } from './no-restricted-globals.js';
 import { NoRestrictedImportsRule } from './no-restricted-imports.js';
 import { NodeClassDescriptionIconMissingRule } from './node-class-description-icon-missing.js';
@@ -18,8 +19,13 @@ import { NodeConnectionTypeLiteralRule } from './node-connection-type-literal.js
 import { NodeUsableAsToolRule } from './node-usable-as-tool.js';
 import { OptionsSortedAlphabeticallyRule } from './options-sorted-alphabetically.js';
 import { PackageNameConventionRule } from './package-name-convention.js';
+import { RequireCommunityNodeKeywordRule } from './require-community-node-keyword.js';
 import { RequireContinueOnFailRule } from './require-continue-on-fail.js';
+import { RequireNodeApiErrorRule } from './require-node-api-error.js';
+import { RequireNodeDescriptionFieldsRule } from './require-node-description-fields.js';
 import { ResourceOperationPatternRule } from './resource-operation-pattern.js';
+import { ValidPeerDependenciesRule } from './valid-peer-dependencies.js';
+import { WebhookLifecycleCompleteRule } from './webhook-lifecycle-complete.js';
 
 export const rules = {
 	'ai-node-package-json': AiNodePackageJsonRule,
@@ -34,6 +40,7 @@ export const rules = {
 	'no-credential-reuse': NoCredentialReuseRule,
 	'no-forbidden-lifecycle-scripts': NoForbiddenLifecycleScriptsRule,
 	'no-http-request-with-manual-auth': NoHttpRequestWithManualAuthRule,
+	'no-overrides-field': NoOverridesFieldRule,
 	'icon-validation': IconValidationRule,
 	'resource-operation-pattern': ResourceOperationPatternRule,
 	'credential-documentation-url': CredentialDocumentationUrlRule,
@@ -41,5 +48,10 @@ export const rules = {
 	'cred-class-field-icon-missing': CredClassFieldIconMissingRule,
 	'node-connection-type-literal': NodeConnectionTypeLiteralRule,
 	'missing-paired-item': MissingPairedItemRule,
+	'require-community-node-keyword': RequireCommunityNodeKeywordRule,
 	'require-continue-on-fail': RequireContinueOnFailRule,
+	'require-node-api-error': RequireNodeApiErrorRule,
+	'require-node-description-fields': RequireNodeDescriptionFieldsRule,
+	'valid-peer-dependencies': ValidPeerDependenciesRule,
+	'webhook-lifecycle-complete': WebhookLifecycleCompleteRule,
 } satisfies Record<string, AnyRuleModule>;

package/src/rules/no-overrides-field.test.ts

@@ -0,0 +1,50 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { NoOverridesFieldRule } from './no-overrides-field.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('no-overrides-field', NoOverridesFieldRule, {
+	valid: [
+		{
+			name: 'no overrides field',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+		},
+		{
+			name: 'package.json with dependencies but no overrides',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*" } }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "overrides": { "axios": "1.0.0" } }',
+		},
+		{
+			name: 'nested "overrides" key inside another field is allowed',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "config": { "overrides": { "axios": "1.0.0" } } }',
+		},
+	],
+	invalid: [
+		{
+			name: 'overrides as object is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "overrides": { "axios": "1.0.0" } }',
+			errors: [{ messageId: 'overridesForbidden' }],
+		},
+		{
+			name: 'empty overrides object is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "overrides": {} }',
+			errors: [{ messageId: 'overridesForbidden' }],
+		},
+		{
+			name: 'real-world overrides (CNOC-404 Sinch) is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-sinch", "overrides": { "axios": "1.7.0", "fast-xml-parser": "4.4.0", "minimatch": "9.0.5", "@langchain/core": "0.3.0", "qs": "6.13.0" } }',
+			errors: [{ messageId: 'overridesForbidden' }],
+		},
+	],
+});

package/src/rules/no-overrides-field.ts

@@ -0,0 +1,43 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty } from '../utils/index.js';
+
+export const NoOverridesFieldRule = createRule({
+	name: 'no-overrides-field',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Ban the "overrides" field in community node package.json',
+		},
+		messages: {
+			overridesForbidden:
+				'The "overrides" field is not allowed in community node packages. Dependency overrides can introduce incompatible versions of shared libraries into the n8n runtime and cause conflicts with other nodes.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				if (node.parent?.type !== AST_NODE_TYPES.ExpressionStatement) {
+					return;
+				}
+
+				const overridesProp = findJsonProperty(node, 'overrides');
+				if (!overridesProp) {
+					return;
+				}
+
+				context.report({
+					node: overridesProp,
+					messageId: 'overridesForbidden',
+				});
+			},
+		};
+	},
+});

package/src/rules/node-class-description-icon-missing.ts

@@ -8,12 +8,18 @@ import {
 	createRule,
 } from '../utils/index.js';
 
+/** @deprecated Use `require-node-description-fields` instead. */
 export const NodeClassDescriptionIconMissingRule = createRule({
 	name: 'node-class-description-icon-missing',
 	meta: {
 		type: 'problem',
+		deprecated: {
+			message: 'Use require-node-description-fields instead.',
+			replacedBy: [{ rule: { name: 'require-node-description-fields' } }],
+		},
 		docs: {
-			description: 'Node class description must have an `icon` property defined',
+			description:
+				'Node class description must have an `icon` property defined. Deprecated: use `require-node-description-fields` instead.',
 		},
 		messages: {
 			missingIcon: 'Node class description is missing required `icon` property',

package/src/rules/require-community-node-keyword.test.ts

@@ -0,0 +1,82 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireCommunityNodeKeywordRule } from './require-community-node-keyword.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('require-community-node-keyword', RequireCommunityNodeKeywordRule, {
+	valid: [
+		{
+			name: 'keywords array contains required keyword',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": ["n8n-community-node-package"] }',
+		},
+		{
+			name: 'keywords array contains required keyword among others',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": ["n8n", "automation", "n8n-community-node-package", "workflow"] }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "name": "n8n-nodes-example" }',
+		},
+		{
+			name: 'nested objects are not checked',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": ["n8n-community-node-package"], "config": { "nested": "value" } }',
+		},
+		{
+			name: 'objects inside arrays (e.g. contributors) are not flagged',
+			filename: 'package.json',
+			code: `{
+				"name": "n8n-nodes-example",
+				"keywords": ["n8n-community-node-package"],
+				"contributors": [
+					{ "name": "Alice", "email": "alice@example.com" },
+					{ "name": "Bob", "email": "bob@example.com" }
+				]
+			}`,
+		},
+	],
+	invalid: [
+		{
+			name: 'missing keywords array entirely',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+			output:
+				'{ "name": "n8n-nodes-example", "version": "1.0.0", "keywords": ["n8n-community-node-package"] }',
+			errors: [{ messageId: 'missingKeywordsArray' }],
+		},
+		{
+			name: 'empty keywords array',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": [] }',
+			output: '{ "name": "n8n-nodes-example", "keywords": ["n8n-community-node-package"] }',
+			errors: [{ messageId: 'missingKeyword' }],
+		},
+		{
+			name: 'keywords array without the required keyword',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": ["n8n", "automation"] }',
+			output:
+				'{ "name": "n8n-nodes-example", "keywords": ["n8n", "automation", "n8n-community-node-package"] }',
+			errors: [{ messageId: 'missingKeyword' }],
+		},
+		{
+			name: 'keywords array with similar but incorrect keyword',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": ["n8n-community-node"] }',
+			output:
+				'{ "name": "n8n-nodes-example", "keywords": ["n8n-community-node", "n8n-community-node-package"] }',
+			errors: [{ messageId: 'missingKeyword' }],
+		},
+		{
+			name: 'empty package.json object',
+			filename: 'package.json',
+			code: '{}',
+			output: '{ "keywords": ["n8n-community-node-package"] }',
+			errors: [{ messageId: 'missingKeywordsArray' }],
+		},
+	],
+});

package/src/rules/require-community-node-keyword.ts

@@ -0,0 +1,78 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty } from '../utils/index.js';
+
+const REQUIRED_KEYWORD = 'n8n-community-node-package';
+
+export const RequireCommunityNodeKeywordRule = createRule({
+	name: 'require-community-node-keyword',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Require the "n8n-community-node-package" keyword in community node package.json',
+		},
+		fixable: 'code',
+		messages: {
+			missingKeyword: `The "keywords" array must include "${REQUIRED_KEYWORD}". This keyword is required for n8n to discover community node packages.`,
+			missingKeywordsArray: `The package.json must have a "keywords" array containing "${REQUIRED_KEYWORD}".`,
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				if (node.parent?.type !== AST_NODE_TYPES.ExpressionStatement) {
+					return;
+				}
+
+				const keywordsProp = findJsonProperty(node, 'keywords');
+
+				if (!keywordsProp) {
+					context.report({
+						node,
+						messageId: 'missingKeywordsArray',
+						fix(fixer) {
+							const lastProp = node.properties[node.properties.length - 1];
+							if (!lastProp) {
+								return fixer.replaceText(node, `{ "keywords": ["${REQUIRED_KEYWORD}"] }`);
+							}
+							return fixer.insertTextAfter(lastProp, `, "keywords": ["${REQUIRED_KEYWORD}"]`);
+						},
+					});
+					return;
+				}
+
+				if (keywordsProp.value.type !== AST_NODE_TYPES.ArrayExpression) {
+					return;
+				}
+
+				const keywordsArray = keywordsProp.value;
+				const hasRequiredKeyword = keywordsArray.elements.some(
+					(element) =>
+						element?.type === AST_NODE_TYPES.Literal && element.value === REQUIRED_KEYWORD,
+				);
+
+				if (!hasRequiredKeyword) {
+					context.report({
+						node: keywordsProp,
+						messageId: 'missingKeyword',
+						fix(fixer) {
+							const lastElement = keywordsArray.elements[keywordsArray.elements.length - 1];
+							if (!lastElement) {
+								return fixer.replaceText(keywordsArray, `["${REQUIRED_KEYWORD}"]`);
+							}
+							return fixer.insertTextAfter(lastElement, `, "${REQUIRED_KEYWORD}"`);
+						},
+					});
+				}
+			},
+		};
+	},
+});