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

package/docs/rules/no-runtime-dependencies.md

@@ -0,0 +1,58 @@
+# Disallow non-empty "dependencies" in community node package.json (`@n8n/community-nodes/no-runtime-dependencies`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+The `dependencies` field in `package.json` declares packages that are installed alongside the node at runtime. In the context of n8n community nodes this is dangerous:
+
+- Community nodes run inside the shared n8n runtime alongside all other installed nodes. Any package listed in `dependencies` gets installed into that shared environment and can shadow or conflict with versions already used by n8n or other nodes.
+- Unlike application packages, community nodes should not own their runtime environment. Shared libraries must be declared in `peerDependencies` (so the host runtime supplies them) or bundled at build time into the published artifact.
+- A non-empty `dependencies` section is a strong signal that the package was scaffolded from a generic Node.js template without adapting it to the n8n community node model.
+
+## Examples
+
+### Incorrect
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "dependencies": {
+    "axios": "1.0.0"
+  }
+}
+```
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "dependencies": {
+    "axios": "1.7.0",
+    "fast-xml-parser": "4.4.0",
+    "minimatch": "9.0.5"
+  }
+}
+```
+
+### Correct
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  }
+}
+```
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "dependencies": {},
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  }
+}
+```

package/docs/rules/no-template-placeholders.md

@@ -0,0 +1,51 @@
+# Disallow unresolved template placeholders in package.json (`@n8n/community-nodes/no-template-placeholders`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Community node packages are typically scaffolded from a starter template that contains
+placeholder values such as `<PACKAGE_NAME>`, `<USERNAME>`, or `{{ authorName }}`. When
+these placeholders survive into a published `package.json`, the package metadata is
+broken — the name is invalid, the repository link is dead, etc.
+
+This rule scans every string value in `package.json` and reports any value containing
+an unresolved placeholder pattern. It catches:
+
+- Angle bracket placeholders: `<...>`
+- Mustache placeholders: `{{...}}`
+
+The rule applies to **all** string fields, including custom ones — not just the well-known
+fields like `name`, `description`, `homepage`, or `repository.url`.
+
+## Examples
+
+### Incorrect
+
+```json
+{
+  "name": "n8n-nodes-<PACKAGE_NAME>",
+  "description": "An n8n community node for {{service}}",
+  "homepage": "https://github.com/<USERNAME>/n8n-nodes-example#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/<USERNAME>/n8n-nodes-example.git"
+  }
+}
+```
+
+### Correct
+
+```json
+{
+  "name": "n8n-nodes-acme",
+  "description": "An n8n community node for the Acme API",
+  "homepage": "https://github.com/acme/n8n-nodes-acme#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/acme/n8n-nodes-acme.git"
+  }
+}
+```

package/docs/rules/node-operation-error-itemindex.md

@@ -0,0 +1,81 @@
+# Require { itemIndex } in NodeOperationError / NodeApiError options inside item loops (`@n8n/community-nodes/node-operation-error-itemindex`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+When throwing `NodeOperationError` or `NodeApiError` inside the item-processing loop of an `execute()` method, the options object (third argument) must contain an `itemIndex` property. Without it, n8n cannot associate the error with the specific item that caused it, which breaks per-item error reporting and `continueOnFail` behaviour.
+
+The rule only fires inside **item loops** — `for` or `for...of` statements that iterate over the result of `this.getInputData()`. Errors thrown outside such loops (e.g. in webhook handlers, trigger setup, or credential testing helpers) are not flagged.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = { /* ... */ };
+
+  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
+    const items = this.getInputData();
+    const returnData: INodeExecutionData[] = [];
+
+    for (let i = 0; i < items.length; i++) {
+      try {
+        // ...
+      } catch (error) {
+        // Missing { itemIndex } — n8n cannot map this error back to item i
+        throw new NodeOperationError(this.getNode(), error);
+      }
+    }
+
+    return [returnData];
+  }
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = { /* ... */ };
+
+  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
+    const items = this.getInputData();
+    const returnData: INodeExecutionData[] = [];
+
+    for (let i = 0; i < items.length; i++) {
+      try {
+        // ...
+      } catch (error) {
+        throw new NodeOperationError(this.getNode(), error, { itemIndex: i });
+      }
+    }
+
+    return [returnData];
+  }
+}
+```
+
+Using `for...of` with a named loop variable:
+
+```typescript
+async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
+  const items = this.getInputData();
+  const returnData: INodeExecutionData[] = [];
+  let itemIndex = 0;
+
+  for (const item of items) {
+    try {
+      // ...
+    } catch (error) {
+      throw new NodeApiError(this.getNode(), error, { itemIndex });
+    }
+    itemIndex++;
+  }
+
+  return [returnData];
+}
+```

package/docs/rules/valid-credential-references.md

@@ -0,0 +1,78 @@
+# Ensure credentials referenced in node descriptions exist as credential classes in the package (`@n8n/community-nodes/valid-credential-references`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+For each entry in `description.credentials[]`, this rule verifies that the referenced `name` matches the `name` class field of a credential class declared in the same package (as listed in `package.json` under `n8n.credentials`).
+
+This catches typos and broken references. When `cred-class-name-suffix` is also enabled, this rule naturally enforces the naming convention in the common case while still allowing legitimately named credentials such as `httpHeaderAuth` or `webhookAuth`.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+// MyApiCredential.credentials.ts
+export class MyApiCredential implements ICredentialType {
+  name = 'myApiCredential';
+  // ...
+}
+
+// package.json: "n8n": { "credentials": ["dist/credentials/MyApiCredential.credentials.js"] }
+
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    credentials: [
+      {
+        name: 'myApiCredentail', // Typo — no credential with this name exists
+        required: true,
+      },
+    ],
+    // ...
+  };
+}
+```
+
+### ✅ Correct
+
+```typescript
+// MyApiCredential.credentials.ts
+export class MyApiCredential implements ICredentialType {
+  name = 'myApiCredential';
+  // ...
+}
+
+// package.json: "n8n": { "credentials": ["dist/credentials/MyApiCredential.credentials.js"] }
+
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    credentials: [
+      {
+        name: 'myApiCredential', // Matches the credential class name property
+        required: true,
+      },
+    ],
+    // ...
+  };
+}
+```
+
+## Setup
+
+Declare your credential files in `package.json` so the rule can resolve credential class names:
+
+```json
+{
+  "name": "n8n-nodes-my-service",
+  "n8n": {
+    "credentials": [
+      "dist/credentials/MyApiCredential.credentials.js"
+    ]
+  }
+}
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@n8n/eslint-plugin-community-nodes",
   "type": "module",
-  "version": "0.14.0",
+  "version": "0.16.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.19.0",
-    "@n8n/vitest-config": "1.10.0"
+    "@n8n/vitest-config": "1.10.0",
+    "n8n-workflow": "2.21.0"
   },
   "peerDependencies": {
     "eslint": ">= 9",

package/src/plugin.ts

@@ -24,6 +24,7 @@ const configs = {
 			'@n8n/community-nodes/no-restricted-globals': 'error',
 			'@n8n/community-nodes/no-restricted-imports': 'error',
 			'@n8n/community-nodes/credential-password-field': 'error',
+			'@n8n/community-nodes/n8n-object-validation': 'error',
 			'@n8n/community-nodes/no-deprecated-workflow-functions': 'error',
 			'@n8n/community-nodes/node-usable-as-tool': 'error',
 			'@n8n/community-nodes/package-name-convention': 'error',
@@ -32,17 +33,24 @@ const configs = {
 			'@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/no-template-placeholders': '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/cred-class-field-icon-missing': 'error',
+			'@n8n/community-nodes/cred-class-name-suffix': 'error',
+			'@n8n/community-nodes/cred-class-oauth2-naming': 'error',
 			'@n8n/community-nodes/node-connection-type-literal': 'error',
 			'@n8n/community-nodes/missing-paired-item': 'error',
+			'@n8n/community-nodes/no-builder-hint-leakage': 'error',
+			'@n8n/community-nodes/node-operation-error-itemindex': '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',
 		},
@@ -55,6 +63,7 @@ const configs = {
 		rules: {
 			'@n8n/community-nodes/ai-node-package-json': 'error',
 			'@n8n/community-nodes/credential-password-field': 'error',
+			'@n8n/community-nodes/n8n-object-validation': 'error',
 			'@n8n/community-nodes/no-deprecated-workflow-functions': 'error',
 			'@n8n/community-nodes/node-usable-as-tool': 'error',
 			'@n8n/community-nodes/package-name-convention': 'error',
@@ -63,17 +72,24 @@ const configs = {
 			'@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/no-template-placeholders': '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/cred-class-field-icon-missing': 'error',
+			'@n8n/community-nodes/cred-class-name-suffix': 'error',
+			'@n8n/community-nodes/cred-class-oauth2-naming': 'error',
 			'@n8n/community-nodes/node-connection-type-literal': 'error',
 			'@n8n/community-nodes/missing-paired-item': 'error',
+			'@n8n/community-nodes/no-builder-hint-leakage': 'error',
+			'@n8n/community-nodes/node-operation-error-itemindex': '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',
 		},

package/src/rules/cred-class-name-suffix.test.ts

@@ -0,0 +1,74 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { CredClassNameSuffixRule } from './cred-class-name-suffix.js';
+
+const ruleTester = new RuleTester();
+
+const credFilePath = '/tmp/TestCredential.credentials.ts';
+const nonCredFilePath = '/tmp/SomeHelper.ts';
+
+function createCredentialCode(className: string): string {
+	return `
+import type { ICredentialType, INodeProperties } from 'n8n-workflow';
+
+export class ${className} implements ICredentialType {
+	name = 'testApi';
+	displayName = 'Test API';
+	properties: INodeProperties[] = [];
+}`;
+}
+
+function createRegularClass(className: string): string {
+	return `
+export class ${className} {
+	name = 'test';
+}`;
+}
+
+ruleTester.run('cred-class-name-suffix', CredClassNameSuffixRule, {
+	valid: [
+		{
+			name: 'credential class with Api suffix',
+			filename: credFilePath,
+			code: createCredentialCode('TestApi'),
+		},
+		{
+			name: 'credential class with OAuth2Api suffix',
+			filename: credFilePath,
+			code: createCredentialCode('TestOAuth2Api'),
+		},
+		{
+			name: 'class not implementing ICredentialType is ignored',
+			filename: credFilePath,
+			code: createRegularClass('SomeHelper'),
+		},
+		{
+			name: 'non-.credentials.ts file is ignored',
+			filename: nonCredFilePath,
+			code: createCredentialCode('TestCredential'),
+		},
+	],
+	invalid: [
+		{
+			name: 'credential class missing Api suffix',
+			filename: credFilePath,
+			code: createCredentialCode('TestCredential'),
+			errors: [{ messageId: 'missingSuffix', data: { name: 'TestCredential' } }],
+			output: createCredentialCode('TestCredentialApi'),
+		},
+		{
+			name: 'credential class name ending in Ap',
+			filename: credFilePath,
+			code: createCredentialCode('TestAp'),
+			errors: [{ messageId: 'missingSuffix', data: { name: 'TestAp' } }],
+			output: createCredentialCode('TestApi'),
+		},
+		{
+			name: 'credential class name ending in A',
+			filename: credFilePath,
+			code: createCredentialCode('TestA'),
+			errors: [{ messageId: 'missingSuffix', data: { name: 'TestA' } }],
+			output: createCredentialCode('TestApi'),
+		},
+	],
+});

package/src/rules/cred-class-name-suffix.ts

@@ -0,0 +1,57 @@
+import { isCredentialTypeClass, isFileType, createRule } from '../utils/index.js';
+
+function addApiSuffix(name: string): string {
+	if (name.endsWith('Ap')) return `${name}i`;
+	if (name.endsWith('A')) return `${name}pi`;
+	return `${name}Api`;
+}
+
+export const CredClassNameSuffixRule = createRule({
+	name: 'cred-class-name-suffix',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Credential class names must be suffixed with `Api`',
+		},
+		messages: {
+			missingSuffix: "Credential class name '{{name}}' must end with 'Api'",
+		},
+		fixable: 'code',
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!isFileType(context.filename, '.credentials.ts')) {
+			return {};
+		}
+
+		return {
+			ClassDeclaration(node) {
+				if (!isCredentialTypeClass(node)) {
+					return;
+				}
+
+				const classNameNode = node.id;
+				if (!classNameNode) {
+					return;
+				}
+
+				const className = classNameNode.name;
+				if (className.endsWith('Api')) {
+					return;
+				}
+
+				const fixedName = addApiSuffix(className);
+
+				context.report({
+					node: classNameNode,
+					messageId: 'missingSuffix',
+					data: { name: className },
+					fix(fixer) {
+						return fixer.replaceText(classNameNode, fixedName);
+					},
+				});
+			},
+		};
+	},
+});

package/src/rules/cred-class-oauth2-naming.test.ts

@@ -0,0 +1,197 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { CredClassOAuth2NamingRule } from './cred-class-oauth2-naming.js';
+
+const ruleTester = new RuleTester();
+
+const credFilePath = '/tmp/TestCredential.credentials.ts';
+const nonCredFilePath = '/tmp/SomeHelper.ts';
+
+type CredentialFields = {
+	className: string;
+	name?: string;
+	displayName?: string;
+	extendsValues?: string[];
+	superClass?: string;
+};
+
+function createCredentialCode(fields: CredentialFields): string {
+	const { className, name, displayName, extendsValues, superClass } = fields;
+
+	const heritage = superClass ? ` extends ${superClass}` : '';
+	const lines: string[] = [];
+	if (name !== undefined) lines.push(`\tname = '${name}';`);
+	if (displayName !== undefined) lines.push(`\tdisplayName = '${displayName}';`);
+	if (extendsValues !== undefined) {
+		const arr = extendsValues.map((v) => `'${v}'`).join(', ');
+		lines.push(`\textends = [${arr}];`);
+	}
+	lines.push('\tproperties: INodeProperties[] = [];');
+
+	return `
+import type { ICredentialType, INodeProperties } from 'n8n-workflow';
+
+export class ${className}${heritage} implements ICredentialType {
+${lines.join('\n')}
+}`;
+}
+
+function createRegularClass(): string {
+	return `
+export class SomeHelper {
+	name = 'helper';
+}`;
+}
+
+ruleTester.run('cred-class-oauth2-naming', CredClassOAuth2NamingRule, {
+	valid: [
+		{
+			name: 'non-OAuth2 credential is ignored',
+			filename: credFilePath,
+			code: createCredentialCode({
+				className: 'GoogleApi',
+				name: 'googleApi',
+				displayName: 'Google API',
+			}),
+		},
+		{
+			name: 'OAuth2 credential with all naming correct',
+			filename: credFilePath,
+			code: createCredentialCode({
+				className: 'GoogleOAuth2Api',
+				name: 'googleOAuth2Api',
+				displayName: 'Google OAuth2 API',
+			}),
+		},
+		{
+			name: 'OAuth2 credential detected via extends array, all naming correct',
+			filename: credFilePath,
+			code: createCredentialCode({
+				className: 'GoogleOAuth2Api',
+				name: 'googleOAuth2Api',
+				displayName: 'Google OAuth2 API',
+				extendsValues: ['oAuth2Api'],
+			}),
+		},
+		{
+			name: 'OAuth2 credential detected via TS superClass, all naming correct',
+			filename: credFilePath,
+			code: createCredentialCode({
+				className: 'GoogleOAuth2Api',
+				name: 'googleOAuth2Api',
+				displayName: 'Google OAuth2 API',
+				superClass: 'OAuth2Api',
+			}),
+		},
+		{
+			name: 'class not implementing ICredentialType is ignored',
+			filename: credFilePath,
+			code: createRegularClass(),
+		},
+		{
+			name: 'non-.credentials.ts file is ignored',
+			filename: nonCredFilePath,
+			code: createCredentialCode({
+				className: 'GoogleApi',
+				name: 'googleOAuth2Api',
+				displayName: 'Google OAuth2 API',
+			}),
+		},
+	],
+	invalid: [
+		{
+			name: 'class name missing OAuth2 (detected via name field), with Api suffix',
+			filename: credFilePath,
+			code: createCredentialCode({
+				className: 'GoogleApi',
+				name: 'googleOAuth2Api',
+				displayName: 'Google OAuth2 API',
+			}),
+			errors: [{ messageId: 'classNameMissingOAuth2', data: { name: 'GoogleApi' } }],
+			output: createCredentialCode({
+				className: 'GoogleOAuth2Api',
+				name: 'googleOAuth2Api',
+				displayName: 'Google OAuth2 API',
+			}),
+		},
+		{
+			name: 'class name missing OAuth2 (detected via displayName), no Api suffix',
+			filename: credFilePath,
+			code: createCredentialCode({
+				className: 'Google',
+				name: 'googleOAuth2Api',
+				displayName: 'Google OAuth2 API',
+			}),
+			errors: [{ messageId: 'classNameMissingOAuth2', data: { name: 'Google' } }],
+			output: createCredentialCode({
+				className: 'GoogleOAuth2Api',
+				name: 'googleOAuth2Api',
+				displayName: 'Google OAuth2 API',
+			}),
+		},
+		{
+			name: 'name field missing OAuth2 (detected via class name)',
+			filename: credFilePath,
+			code: createCredentialCode({
+				className: 'GoogleOAuth2Api',
+				name: 'googleApi',
+				displayName: 'Google OAuth2 API',
+			}),
+			errors: [{ messageId: 'nameMissingOAuth2', data: { value: 'googleApi' } }],
+			output: null,
+		},
+		{
+			name: 'displayName missing OAuth2 (detected via class name)',
+			filename: credFilePath,
+			code: createCredentialCode({
+				className: 'GoogleOAuth2Api',
+				name: 'googleOAuth2Api',
+				displayName: 'Google API',
+			}),
+			errors: [{ messageId: 'displayNameMissingOAuth2', data: { value: 'Google API' } }],
+			output: null,
+		},
+		{
+			name: 'all three missing OAuth2, detected via extends array',
+			filename: credFilePath,
+			code: createCredentialCode({
+				className: 'GoogleApi',
+				name: 'googleApi',
+				displayName: 'Google API',
+				extendsValues: ['oAuth2Api'],
+			}),
+			errors: [
+				{ messageId: 'classNameMissingOAuth2', data: { name: 'GoogleApi' } },
+				{ messageId: 'nameMissingOAuth2', data: { value: 'googleApi' } },
+				{ messageId: 'displayNameMissingOAuth2', data: { value: 'Google API' } },
+			],
+			output: createCredentialCode({
+				className: 'GoogleOAuth2Api',
+				name: 'googleApi',
+				displayName: 'Google API',
+				extendsValues: ['oAuth2Api'],
+			}),
+		},
+		{
+			name: 'all three missing OAuth2, detected via TS superClass extends',
+			filename: credFilePath,
+			code: createCredentialCode({
+				className: 'GoogleApi',
+				name: 'googleApi',
+				displayName: 'Google API',
+				superClass: 'OAuth2Api',
+			}),
+			errors: [
+				{ messageId: 'classNameMissingOAuth2', data: { name: 'GoogleApi' } },
+				{ messageId: 'nameMissingOAuth2', data: { value: 'googleApi' } },
+				{ messageId: 'displayNameMissingOAuth2', data: { value: 'Google API' } },
+			],
+			output: createCredentialCode({
+				className: 'GoogleOAuth2Api',
+				name: 'googleApi',
+				displayName: 'Google API',
+				superClass: 'OAuth2Api',
+			}),
+		},
+	],
+});