@n8n/eslint-plugin-community-nodes 0.13.0 → 0.15.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.13.0",
+  "version": "0.15.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-workflow": "2.18.0",
-    "@n8n/vitest-config": "1.9.0"
+    "@n8n/vitest-config": "1.10.0",
+    "n8n-workflow": "2.20.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,6 +31,8 @@ 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/no-runtime-dependencies': 'error',
 			'@n8n/community-nodes/icon-validation': 'error',
 			'@n8n/community-nodes/options-sorted-alphabetically': 'warn',
 			'@n8n/community-nodes/resource-operation-pattern': 'warn',
@@ -40,7 +42,11 @@ const configs = {
 			'@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-credential-references': 'error',
+			'@n8n/community-nodes/valid-peer-dependencies': 'error',
+			'@n8n/community-nodes/webhook-lifecycle-complete': 'error',
 		},
 	},
 	recommendedWithoutN8nCloudSupport: {
@@ -58,6 +64,8 @@ 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/no-runtime-dependencies': 'error',
 			'@n8n/community-nodes/icon-validation': 'error',
 			'@n8n/community-nodes/options-sorted-alphabetically': 'warn',
 			'@n8n/community-nodes/credential-documentation-url': 'error',
@@ -67,7 +75,11 @@ const configs = {
 			'@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-credential-references': '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,8 +11,10 @@ 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 { NoRuntimeDependenciesRule } from './no-runtime-dependencies.js';
 import { NodeClassDescriptionIconMissingRule } from './node-class-description-icon-missing.js';
 import { NodeConnectionTypeLiteralRule } from './node-connection-type-literal.js';
 import { NodeUsableAsToolRule } from './node-usable-as-tool.js';
@@ -20,8 +22,12 @@ import { OptionsSortedAlphabeticallyRule } from './options-sorted-alphabetically
 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 { ValidCredentialReferencesRule } from './valid-credential-references.js';
+import { ValidPeerDependenciesRule } from './valid-peer-dependencies.js';
+import { WebhookLifecycleCompleteRule } from './webhook-lifecycle-complete.js';
 
 export const rules = {
 	'ai-node-package-json': AiNodePackageJsonRule,
@@ -36,6 +42,8 @@ export const rules = {
 	'no-credential-reuse': NoCredentialReuseRule,
 	'no-forbidden-lifecycle-scripts': NoForbiddenLifecycleScriptsRule,
 	'no-http-request-with-manual-auth': NoHttpRequestWithManualAuthRule,
+	'no-overrides-field': NoOverridesFieldRule,
+	'no-runtime-dependencies': NoRuntimeDependenciesRule,
 	'icon-validation': IconValidationRule,
 	'resource-operation-pattern': ResourceOperationPatternRule,
 	'credential-documentation-url': CredentialDocumentationUrlRule,
@@ -45,5 +53,9 @@ export const rules = {
 	'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-credential-references': ValidCredentialReferencesRule,
+	'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/no-runtime-dependencies.test.ts

@@ -0,0 +1,50 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { NoRuntimeDependenciesRule } from './no-runtime-dependencies.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('no-runtime-dependencies', NoRuntimeDependenciesRule, {
+	valid: [
+		{
+			name: 'no dependencies field',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+		},
+		{
+			name: 'empty dependencies object is allowed',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "dependencies": {} }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "dependencies": { "axios": "1.0.0" } }',
+		},
+		{
+			name: 'nested "dependencies" key inside another field is allowed',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "config": { "dependencies": { "axios": "1.0.0" } } }',
+		},
+	],
+	invalid: [
+		{
+			name: 'single runtime dependency is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "dependencies": { "axios": "1.0.0" } }',
+			errors: [{ messageId: 'runtimeDependenciesForbidden' }],
+		},
+		{
+			name: 'multiple runtime dependencies are forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "dependencies": { "axios": "1.0.0", "lodash": "^4.0.0" } }',
+			errors: [{ messageId: 'runtimeDependenciesForbidden' }],
+		},
+		{
+			name: 'real-world package with bundled deps is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-sinch", "dependencies": { "axios": "1.7.0", "fast-xml-parser": "4.4.0", "minimatch": "9.0.5" } }',
+			errors: [{ messageId: 'runtimeDependenciesForbidden' }],
+		},
+	],
+});

package/src/rules/no-runtime-dependencies.ts

@@ -0,0 +1,50 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty } from '../utils/index.js';
+
+export const NoRuntimeDependenciesRule = createRule({
+	name: 'no-runtime-dependencies',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow non-empty "dependencies" in community node package.json',
+		},
+		messages: {
+			runtimeDependenciesForbidden:
+				'The "dependencies" field must be empty or absent in community node packages. Runtime dependencies get bundled into the n8n instance and can conflict with other nodes or the n8n runtime itself. Move shared libraries to "peerDependencies" or bundle them into your build artifact.',
+		},
+		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 depsProp = findJsonProperty(node, 'dependencies');
+				if (!depsProp) {
+					return;
+				}
+
+				if (
+					depsProp.value.type !== AST_NODE_TYPES.ObjectExpression ||
+					depsProp.value.properties.length === 0
+				) {
+					return;
+				}
+
+				context.report({
+					node: depsProp,
+					messageId: 'runtimeDependenciesForbidden',
+				});
+			},
+		};
+	},
+});

package/src/rules/require-node-api-error.test.ts

@@ -0,0 +1,199 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireNodeApiErrorRule } from './require-node-api-error.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('require-node-api-error', RequireNodeApiErrorRule, {
+	valid: [
+		{
+			name: 'throw NodeApiError in catch block',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	throw new NodeApiError(this.getNode(), error as JsonObject);
+}`,
+		},
+		{
+			name: 'throw NodeOperationError in catch block',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	throw new NodeOperationError(this.getNode(), 'Operation failed', { itemIndex: i });
+}`,
+		},
+		{
+			name: 'throw outside catch block (not in scope)',
+			code: `
+function validate(input: string) {
+	if (!input) {
+		throw new Error('Input required');
+	}
+}`,
+		},
+		{
+			name: 'throw new Error outside catch block (not in scope)',
+			code: `
+throw new Error('Something went wrong');`,
+		},
+		{
+			name: 'continueOnFail pattern with NodeApiError',
+			code: `
+try {
+	responseData = await apiRequest.call(this, 'POST', '/tasks', body);
+} catch (error) {
+	if (this.continueOnFail()) {
+		returnData.push({ json: { error: error.message } });
+		continue;
+	}
+	throw new NodeApiError(this.getNode(), error as JsonObject);
+}`,
+		},
+		{
+			name: 'conditional handling then NodeApiError in else',
+			code: `
+try {
+	await ftp.put(data, path);
+} catch (error) {
+	if (error.code === 553) {
+		await ftp.mkdir(dirPath, true);
+		await ftp.put(data, path);
+	} else {
+		throw new NodeApiError(this.getNode(), error as JsonObject);
+	}
+}`,
+		},
+		{
+			name: 'throw wrapped error stored in variable',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	const wrapped = new NodeApiError(this.getNode(), error as JsonObject);
+	throw wrapped;
+}`,
+		},
+		{
+			name: 'shadowed variable with same name as catch param',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	const fn = (error: Error) => {
+		throw error;
+	};
+}`,
+		},
+		{
+			name: 'no throw in catch block',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	console.error(error);
+}`,
+		},
+		{
+			name: 'bare re-throw in credential file (skipped)',
+			filename: '/path/to/MyCredential.credentials.ts',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	throw error;
+}`,
+		},
+		{
+			name: 'bare re-throw in .js file (skipped)',
+			filename: '/path/to/helper.js',
+			code: `
+try {
+	apiRequest();
+} catch (error) {
+	throw error;
+}`,
+		},
+	],
+	invalid: [
+		{
+			name: 'bare re-throw of caught error',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	throw error;
+}`,
+			errors: [{ messageId: 'useNodeApiError' }],
+		},
+		{
+			name: 'throw new Error in catch block',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	throw new Error('Request failed');
+}`,
+			errors: [
+				{
+					messageId: 'useNodeApiErrorInsteadOfGeneric',
+					data: { errorClass: 'Error' },
+				},
+			],
+		},
+		{
+			name: 'bare re-throw after continueOnFail',
+			code: `
+try {
+	responseData = await apiRequest.call(this, 'POST', '/tasks', body);
+} catch (error) {
+	if (this.continueOnFail()) {
+		returnData.push({ json: { error: error.message } });
+		continue;
+	}
+	throw error;
+}`,
+			errors: [{ messageId: 'useNodeApiError' }],
+		},
+		{
+			name: 'throw new TypeError in catch block',
+			code: `
+try {
+	JSON.parse(data);
+} catch (error) {
+	throw new TypeError('Invalid JSON');
+}`,
+			errors: [
+				{
+					messageId: 'useNodeApiErrorInsteadOfGeneric',
+					data: { errorClass: 'TypeError' },
+				},
+			],
+		},
+		{
+			name: 'bare re-throw in nested catch',
+			code: `
+try {
+	try {
+		await apiRequest();
+	} catch (innerError) {
+		throw innerError;
+	}
+} catch (outerError) {
+	throw new NodeApiError(this.getNode(), outerError as JsonObject);
+}`,
+			errors: [{ messageId: 'useNodeApiError' }],
+		},
+		{
+			name: 'throw named variable in catch',
+			code: `
+try {
+	await apiRequest();
+} catch (e) {
+	throw e;
+}`,
+			errors: [{ messageId: 'useNodeApiError' }],
+		},
+	],
+});