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

package/docs/rules/cred-class-name-suffix.md

@@ -0,0 +1,46 @@
+# Credential class names must be suffixed with `Api` (`@n8n/community-nodes/cred-class-name-suffix`)
+
+💼 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
+
+Credential classes (those implementing `ICredentialType` in `*.credentials.ts` files) must have a class name ending in `Api`. This is the n8n convention so credentials are easily recognisable in code, in import statements, and across the credential registry.
+
+For OAuth2 credentials extending the OAuth2 base, see the sibling rule `cred-class-oauth2-naming` which enforces the more specific `OAuth2Api` suffix.
+
+## Opt-out
+
+For legitimate exceptions (for example credentials representing custom auth headers where the `Api` suffix would be misleading), disable the rule for the specific class with a standard ESLint comment:
+
+```typescript
+// eslint-disable-next-line @n8n/community-nodes/cred-class-name-suffix
+export class CustomAuthHeader implements ICredentialType {
+  // ...
+}
+```
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class MyService implements ICredentialType {
+  name = 'myServiceApi';
+  displayName = 'My Service API';
+  properties: INodeProperties[] = [];
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class MyServiceApi implements ICredentialType {
+  name = 'myServiceApi';
+  displayName = 'My Service API';
+  properties: INodeProperties[] = [];
+}
+```

package/docs/rules/cred-class-oauth2-naming.md

@@ -0,0 +1,68 @@
+# OAuth2 credentials must include `OAuth2` in the class name, `name`, and `displayName` (`@n8n/community-nodes/cred-class-oauth2-naming`)
+
+💼 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
+
+OAuth2 credentials must consistently identify themselves as OAuth2 across all three naming surfaces. This makes them easy to distinguish from other auth flavours (API key, basic auth) in code, in import statements, and in the credentials picker.
+
+A credential class is considered an OAuth2 credential if **any** of the following are true:
+
+- The class name contains `OAuth2` (e.g. `GoogleOAuth2Api`).
+- The class TypeScript-extends a base whose name contains `OAuth2` (e.g. `class GoogleOAuth2Api extends OAuth2Api`).
+- The `extends` class field references an `OAuth2` credential (e.g. `extends = ['oAuth2Api']`).
+- The `name` or `displayName` field contains `OAuth2`.
+
+When a credential is detected as OAuth2, all of the following must contain `OAuth2`:
+
+- Class name (must end with `OAuth2Api`).
+- `name` class field.
+- `displayName` class field.
+
+The class name is auto-fixable; `name` and `displayName` must be updated manually because their casing convention varies.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+// Class name detected as OAuth2 but `name` and `displayName` lack OAuth2.
+export class GoogleOAuth2Api implements ICredentialType {
+	name = 'googleApi';
+	displayName = 'Google API';
+	properties: INodeProperties[] = [];
+}
+```
+
+```typescript
+// Extends OAuth2 base, but neither class name, `name`, nor `displayName` reflect that.
+export class GoogleApi implements ICredentialType {
+	name = 'googleApi';
+	displayName = 'Google API';
+	extends = ['oAuth2Api'];
+	properties: INodeProperties[] = [];
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class GoogleOAuth2Api implements ICredentialType {
+	name = 'googleOAuth2Api';
+	displayName = 'Google OAuth2 API';
+	extends = ['oAuth2Api'];
+	properties: INodeProperties[] = [];
+}
+```
+
+## Migrated from
+
+This rule consolidates three rules from the legacy `eslint-plugin-n8n-nodes-base` plugin into a single conceptual check:
+
+- `cred-class-name-missing-oauth2-suffix`
+- `cred-class-field-name-missing-oauth2`
+- `cred-class-field-display-name-missing-oauth2`

package/docs/rules/n8n-object-validation.md

@@ -0,0 +1,93 @@
+# Validate the structure of the "n8n" object in community node package.json (required keys, types, and dist/ paths) (`@n8n/community-nodes/n8n-object-validation`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Every community node package declares its nodes and credentials inside the
+top-level `n8n` object in `package.json`. n8n loads packages by reading this
+object: it looks up `n8n.n8nNodesApiVersion` to pick the correct loader, and it
+loads each path in `n8n.nodes` and `n8n.credentials` as compiled JavaScript
+relative to the package root. If any of those fields are missing, mistyped, or
+point at TypeScript sources instead of compiled output, the package fails to
+register at install time and the failure is opaque to the user.
+
+This rule enforces the structural contract:
+
+- `package.json` must contain an `n8n` object.
+- `n8n.n8nNodesApiVersion` must be present and a positive integer. It must live
+  inside `n8n`, not at the root.
+- `n8n.nodes` must be a non-empty array of strings, each starting with `dist/`.
+- `n8n.credentials`, if present, must be an array of strings, each starting
+  with `dist/`.
+
+The `dist/` prefix is required because community nodes ship compiled
+JavaScript; n8n cannot load TypeScript sources at runtime. Variants such as
+`./dist/...` or `DIST/...` are rejected to keep the convention consistent with
+the templates published by `@n8n/node-cli` and `@n8n/create-node`.
+
+## Examples
+
+### Incorrect
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "version": "1.0.0"
+}
+```
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "n8nNodesApiVersion": 1,
+  "n8n": {
+    "nodes": ["dist/nodes/Foo/Foo.node.js"]
+  }
+}
+```
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "n8n": {
+    "n8nNodesApiVersion": "1",
+    "nodes": ["nodes/Foo/Foo.node.js"]
+  }
+}
+```
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "nodes": []
+  }
+}
+```
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "nodes": ["./dist/nodes/Foo/Foo.node.js"]
+  }
+}
+```
+
+### Correct
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "nodes": ["dist/nodes/Foo/Foo.node.js"],
+    "credentials": ["dist/credentials/Foo.credentials.js"]
+  }
+}
+```

package/docs/rules/no-overrides-field.md

@@ -6,13 +6,13 @@
 
 ## Rule Details
 
-The `overrides` field in `package.json` lets a package force specific versions of its (transitive) dependencies. In the context of n8n community nodes this is dangerous:
+The `overrides` field in `package.json` forces specific versions of (transitive) dependencies. n8n installs each community package into an isolated `node_modules` tree (peer deps stripped before install, `require()` walks up from each node's compiled file), so an override in one node only affects that node's own resolution — it does **not** bleed into other nodes or into n8n core. The rule bans the field anyway because:
 
-- Community nodes are installed into a shared n8n runtime alongside other nodes. Overriding a shared library (e.g. `axios`, `@langchain/core`, `minimatch`) can silently substitute an incompatible version for every other node that depends on it, causing hard-to-diagnose runtime failures.
-- Community nodes are distributed as pre-built packages with their dependencies already bundled or declared as `peerDependencies`. Any version pinning that the node actually needs should happen during development, not at install time on the user's n8n instance.
-- `overrides` is frequently copy-pasted from an unrelated internal project and is almost never intentional in a community node.
+- **Almost always unintentional.** In practice, `overrides` blocks in community nodes are copy-pasted boilerplate from unrelated projects, sometimes alongside an empty `dependencies` so the override is a literal no-op.
+- **No useful effect today.** Because of isolation, a maintainer who believes their override coordinates versions across nodes is wrong about what it does. The block is dead weight at best, actively misleading at worst.
+- **Future-proofing.** If the install layout ever moves toward hoisting or partial sharing, today's "harmless" overrides start affecting other nodes' resolution. Banning the field now keeps that change safe to make.
 
-If you have a genuine compatibility need, bundle the dependency into the published artifact or declare it via `peerDependencies` instead.
+Most community nodes do not need third-party runtime libraries at all. n8n core already provides HTTP requests (`this.helpers.httpRequest`, `this.helpers.httpRequestWithAuthentication`), credential resolution, binary data helpers, and other common building blocks via the execute context — these should be the default. `dependencies` and `peerDependencies` are restricted by [`no-runtime-dependencies`](no-runtime-dependencies.md) and [`valid-peer-dependencies`](valid-peer-dependencies.md) respectively, so neither is a workaround for `overrides`.
 
 ## Examples
 

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@n8n/eslint-plugin-community-nodes",
   "type": "module",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "main": "./dist/plugin.js",
   "types": "./dist/plugin.d.ts",
   "exports": {
@@ -24,7 +24,7 @@
     "vitest": "^4.1.1",
     "@n8n/typescript-config": "1.4.0",
     "@n8n/vitest-config": "1.10.0",
-    "n8n-workflow": "2.20.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',
@@ -33,13 +34,18 @@ const configs = {
 			'@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',
@@ -57,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',
@@ -66,13 +73,18 @@ const configs = {
 			'@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',

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);
+					},
+				});
+			},
+		};
+	},
+});