@n8n/eslint-plugin-community-nodes 0.18.0 → 0.20.0

package/docs/rules/cred-class-name-field-conventions.md

@@ -0,0 +1,38 @@
+# Credential `name` field must end with `Api` and start with a lowercase letter (`@n8n/community-nodes/cred-class-name-field-conventions`)
+
+💼 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
+
+The `name` field of a credential class (those implementing `ICredentialType` in `*.credentials.ts` files) is the internal identifier referenced by nodes and stored in the credential registry. n8n convention requires this identifier to:
+
+- End with `Api` (e.g. `githubApi`), so credentials are easily recognisable across the codebase.
+- Start with a lowercase letter (camelCase), since it is an identifier value rather than a class name.
+
+Both checks are automatically fixable.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class GithubApi implements ICredentialType {
+  name = 'Github';
+  displayName = 'GitHub API';
+  properties: INodeProperties[] = [];
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class GithubApi implements ICredentialType {
+  name = 'githubApi';
+  displayName = 'GitHub API';
+  properties: INodeProperties[] = [];
+}
+```

package/docs/rules/no-builder-hint-leakage.md

@@ -0,0 +1,38 @@
+# Disallow wire-format expression syntax (={{...}}) and NodeConnectionType string literals in builderHint texts and AI-builder prompts. Use expr() and SDK-canonical references instead (`@n8n/community-nodes/no-builder-hint-leakage`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+`builderHint` texts and AI-builder prompts are authored as human-facing guidance, but they sometimes leak n8n's internal wire format:
+
+- Raw expression syntax such as `={{ $json.foo }}`, which only makes sense inside the execution engine.
+- `NodeConnectionType` string literals such as `ai_languageModel` or `ai_tool`, which are structured connection identifiers rather than prose.
+
+When these leak into hints and prompts, they confuse the builder experience and the AI assistant. Use the `expr()` SDK helper for expressions and the SDK-canonical reference helpers (e.g. `languageModel()`, `tool()`, `memory()`) instead.
+
+## Options
+
+This rule accepts an options object:
+
+- `scope` (`'builderHint' | 'all'`, default `'builderHint'`) — `builderHint` only scans string values inside `builderHint` property values. `all` scans every string in the file, intended for AI-builder prompt files.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+const node = {
+  builderHint: 'Set the model with ={{ $json.model }} and connect an ai_languageModel.',
+};
+```
+
+### ✅ Correct
+
+```typescript
+const node = {
+  builderHint: 'Set the model with expr($json.model) and connect a languageModel().',
+};
+```

package/docs/rules/package-name-convention.md

@@ -10,6 +10,8 @@
 
 Validates that your package name follows the correct n8n community node naming convention. Package names must start with `n8n-nodes-` and can optionally be scoped.
 
+The rule also requires a `name` field to be present and rejects the default placeholder (`n8n-nodes-<...>`) that ships with the node starter template, so packages are not published with a missing or unfilled name.
+
 ## Examples
 
 ### ❌ Incorrect
@@ -32,6 +34,18 @@ Validates that your package name follows the correct n8n community node naming c
 }
 ```
 
+```json
+{
+  "name": "n8n-nodes-<...>"
+}
+```
+
+```json
+{
+  "version": "1.0.0"
+}
+```
+
 ### ✅ Correct
 
 ```json

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@n8n/eslint-plugin-community-nodes",
   "type": "module",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "main": "./dist/plugin.js",
   "types": "./dist/plugin.d.ts",
   "exports": {
@@ -11,6 +11,7 @@
     }
   },
   "dependencies": {
+    "@typescript-eslint/typescript-estree": "^8.35.0",
     "@typescript-eslint/utils": "^8.35.0",
     "fastest-levenshtein": "1.0.16"
   },
@@ -22,9 +23,9 @@
     "rimraf": "6.0.1",
     "typescript": "6.0.2",
     "vitest": "^4.1.1",
-    "@n8n/typescript-config": "1.4.0",
-    "@n8n/vitest-config": "1.12.0",
-    "n8n-workflow": "2.23.0"
+    "@n8n/typescript-config": "1.5.0",
+    "@n8n/vitest-config": "1.14.0",
+    "n8n-workflow": "2.26.0"
   },
   "peerDependencies": {
     "eslint": "9.29.0",
@@ -54,12 +55,13 @@
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
+    "build:unchecked": "tsc --project tsconfig.build.json --noCheck",
     "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": "eslint src && pnpm lint:docs",
     "lint:fix": "eslint src --fix",
     "lint:docs": "pnpm build && eslint-doc-generator --check",
     "test": "vitest run",

package/src/plugin.ts

@@ -40,6 +40,7 @@ const configs = {
 			'@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-field-conventions': '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',
@@ -80,6 +81,7 @@ const configs = {
 			'@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-field-conventions': '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',

package/src/rules/cred-class-name-field-conventions.test.ts

@@ -0,0 +1,121 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { CredClassNameFieldConventionsRule } from './cred-class-name-field-conventions.js';
+
+const ruleTester = new RuleTester();
+
+const credFilePath = '/tmp/TestCredential.credentials.ts';
+const nonCredFilePath = '/tmp/SomeHelper.ts';
+
+function createCredentialCode(name: string): string {
+	return `
+import type { ICredentialType, INodeProperties } from 'n8n-workflow';
+
+export class TestApi implements ICredentialType {
+	name = '${name}';
+	displayName = 'Test API';
+	properties: INodeProperties[] = [];
+}`;
+}
+
+function createRegularClass(name: string): string {
+	return `
+export class SomeHelper {
+	name = '${name}';
+}`;
+}
+
+// Embeds the raw literal text (including its quotes) verbatim, so tests can
+// exercise names containing quote characters that need escaping.
+function createCredentialCodeWithLiteral(literal: string): string {
+	return `
+import type { ICredentialType, INodeProperties } from 'n8n-workflow';
+
+export class TestApi implements ICredentialType {
+	name = ${literal};
+	displayName = 'Test API';
+	properties: INodeProperties[] = [];
+}`;
+}
+
+ruleTester.run('cred-class-name-field-conventions', CredClassNameFieldConventionsRule, {
+	valid: [
+		{
+			name: 'name field with Api suffix and lowercase first char',
+			filename: credFilePath,
+			code: createCredentialCode('githubApi'),
+		},
+		{
+			name: 'OAuth2 name field is also valid',
+			filename: credFilePath,
+			code: createCredentialCode('githubOAuth2Api'),
+		},
+		{
+			name: 'class not implementing ICredentialType is ignored',
+			filename: credFilePath,
+			code: createRegularClass('Github'),
+		},
+		{
+			name: 'non-.credentials.ts file is ignored',
+			filename: nonCredFilePath,
+			code: createCredentialCode('Github'),
+		},
+	],
+	invalid: [
+		{
+			name: 'name field missing Api suffix',
+			filename: credFilePath,
+			code: createCredentialCode('github'),
+			errors: [{ messageId: 'missingSuffix', data: { value: 'github' } }],
+			output: createCredentialCode('githubApi'),
+		},
+		{
+			name: 'name field with uppercase first char',
+			filename: credFilePath,
+			code: createCredentialCode('GithubApi'),
+			errors: [{ messageId: 'uppercaseFirstChar', data: { value: 'GithubApi' } }],
+			output: createCredentialCode('githubApi'),
+		},
+		{
+			name: 'name field with both uppercase first char and missing suffix',
+			filename: credFilePath,
+			code: createCredentialCode('Github'),
+			errors: [
+				{ messageId: 'uppercaseFirstChar', data: { value: 'Github' } },
+				{ messageId: 'missingSuffix', data: { value: 'Github' } },
+			],
+			output: createCredentialCode('githubApi'),
+		},
+		{
+			name: 'name field ending in Ap',
+			filename: credFilePath,
+			code: createCredentialCode('githubAp'),
+			errors: [{ messageId: 'missingSuffix', data: { value: 'githubAp' } }],
+			output: createCredentialCode('githubApi'),
+		},
+		{
+			name: 'name field ending in A',
+			filename: credFilePath,
+			code: createCredentialCode('githubA'),
+			errors: [{ messageId: 'missingSuffix', data: { value: 'githubA' } }],
+			output: createCredentialCode('githubApi'),
+		},
+		{
+			name: 'autofix escapes single quotes in the name value',
+			filename: credFilePath,
+			code: createCredentialCodeWithLiteral("'git\\'hub'"),
+			errors: [{ messageId: 'missingSuffix', data: { value: "git'hub" } }],
+			output: createCredentialCodeWithLiteral("'git\\'hubApi'"),
+		},
+		{
+			name: 'autofix preserves double quotes and escapes them in the name value',
+			filename: credFilePath,
+			code: createCredentialCodeWithLiteral('"Git\\"hub"'),
+			errors: [
+				{ messageId: 'uppercaseFirstChar', data: { value: 'Git"hub' } },
+				{ messageId: 'missingSuffix', data: { value: 'Git"hub' } },
+			],
+			output: createCredentialCodeWithLiteral('"git\\"hubApi"'),
+		},
+	],
+});

package/src/rules/cred-class-name-field-conventions.ts

@@ -0,0 +1,102 @@
+import {
+	createRule,
+	findClassProperty,
+	getStringLiteralValue,
+	isCredentialTypeClass,
+	isFileType,
+} from '../utils/index.js';
+
+function lowercaseFirstChar(name: string): string {
+	return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+function addApiSuffix(name: string): string {
+	if (name.endsWith('Api')) return name;
+	if (name.endsWith('Ap')) return `${name}i`;
+	if (name.endsWith('A')) return `${name}pi`;
+	return `${name}Api`;
+}
+
+// Serialize a value as a string literal using the original quote character,
+// escaping any characters that would otherwise break the literal so the
+// autofix never emits invalid code (e.g. names containing quotes).
+function toStringLiteral(value: string, quote: string): string {
+	const escaped = value
+		.replace(/\\/g, '\\\\')
+		.replace(/\n/g, '\\n')
+		.replace(/\r/g, '\\r')
+		.split(quote)
+		.join(`\\${quote}`);
+	return `${quote}${escaped}${quote}`;
+}
+
+export const CredClassNameFieldConventionsRule = createRule({
+	name: 'cred-class-name-field-conventions',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Credential `name` field must end with `Api` and start with a lowercase letter',
+		},
+		messages: {
+			missingSuffix: "Credential `name` field '{{value}}' must end with 'Api'",
+			uppercaseFirstChar: "Credential `name` field '{{value}}' must start with a lowercase letter",
+		},
+		fixable: 'code',
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!isFileType(context.filename, '.credentials.ts')) {
+			return {};
+		}
+
+		return {
+			ClassDeclaration(node) {
+				if (!isCredentialTypeClass(node)) {
+					return;
+				}
+
+				const nameProperty = findClassProperty(node, 'name');
+				if (!nameProperty?.value) {
+					return;
+				}
+
+				const nameValue = getStringLiteralValue(nameProperty.value);
+				if (nameValue === null) {
+					return;
+				}
+
+				const startsLowercase = !/^[A-Z]/.test(nameValue);
+				const endsWithApi = nameValue.endsWith('Api');
+				if (startsLowercase && endsWithApi) {
+					return;
+				}
+
+				// Compute the fully-corrected value once so each fix yields the
+				// same result in a single pass, regardless of which one applies.
+				const fixedValue = addApiSuffix(lowercaseFirstChar(nameValue));
+				const valueNode = nameProperty.value;
+				const quote = context.sourceCode.getText(valueNode).charAt(0);
+				const replacement = toStringLiteral(fixedValue, quote);
+
+				if (!startsLowercase) {
+					context.report({
+						node: valueNode,
+						messageId: 'uppercaseFirstChar',
+						data: { value: nameValue },
+						fix: (fixer) => fixer.replaceText(valueNode, replacement),
+					});
+				}
+
+				if (!endsWithApi) {
+					context.report({
+						node: valueNode,
+						messageId: 'missingSuffix',
+						data: { value: nameValue },
+						fix: (fixer) => fixer.replaceText(valueNode, replacement),
+					});
+				}
+			},
+		};
+	},
+});

package/src/rules/credential-password-field.ts

@@ -1,4 +1,4 @@
-import { TSESTree } from '@typescript-eslint/types';
+import { TSESTree } from '@typescript-eslint/utils';
 import type { ReportFixFunction } from '@typescript-eslint/utils/ts-eslint';
 
 import {

package/src/rules/index.ts

@@ -2,6 +2,7 @@ import type { AnyRuleModule } from '@typescript-eslint/utils/ts-eslint';
 
 import { AiNodePackageJsonRule } from './ai-node-package-json.js';
 import { CredClassFieldIconMissingRule } from './cred-class-field-icon-missing.js';
+import { CredClassNameFieldConventionsRule } from './cred-class-name-field-conventions.js';
 import { CredClassNameSuffixRule } from './cred-class-name-suffix.js';
 import { CredClassOAuth2NamingRule } from './cred-class-oauth2-naming.js';
 import { CredentialDocumentationUrlRule } from './credential-documentation-url.js';
@@ -57,6 +58,7 @@ export const rules = {
 	'credential-documentation-url': CredentialDocumentationUrlRule,
 	'node-class-description-icon-missing': NodeClassDescriptionIconMissingRule,
 	'cred-class-field-icon-missing': CredClassFieldIconMissingRule,
+	'cred-class-name-field-conventions': CredClassNameFieldConventionsRule,
 	'cred-class-name-suffix': CredClassNameSuffixRule,
 	'cred-class-oauth2-naming': CredClassOAuth2NamingRule,
 	'node-connection-type-literal': NodeConnectionTypeLiteralRule,

package/src/rules/no-credential-reuse.ts

@@ -1,4 +1,4 @@
-import { TSESTree } from '@typescript-eslint/types';
+import { TSESTree } from '@typescript-eslint/utils';
 import type { ReportSuggestionArray } from '@typescript-eslint/utils/ts-eslint';
 
 import {

package/src/rules/no-restricted-globals.ts

@@ -1,4 +1,4 @@
-import { TSESTree } from '@typescript-eslint/types';
+import { TSESTree } from '@typescript-eslint/utils';
 import type { TSESLint } from '@typescript-eslint/utils';
 
 import { createRule } from '../utils/index.js';

package/src/rules/no-template-placeholders.test.ts

@@ -37,6 +37,24 @@ ruleTester.run('no-template-placeholders', NoTemplatePlaceholdersRule, {
 			filename: 'package.json',
 			code: '{ "name": "n8n-nodes-example", "private": false, "engines": { "node": ">=18" } }',
 		},
+		{
+			name: 'npm person string with email in author is not flagged',
+			filename: 'package.json',
+			code: '{ "author": "Jane Doe <jane@example.com>" }',
+		},
+		{
+			name: 'npm person string with email and url in author is not flagged',
+			filename: 'package.json',
+			code: '{ "author": "Jane Doe <jane@example.com> (https://example.com)" }',
+		},
+		{
+			name: 'npm person strings in contributors and maintainers are not flagged',
+			filename: 'package.json',
+			code: `{
+				"contributors": ["Jane Doe <jane@example.com> (https://example.com)"],
+				"maintainers": ["John Roe <john.roe+n8n@example.org>"]
+			}`,
+		},
 	],
 	invalid: [
 		{

package/src/rules/no-template-placeholders.ts

@@ -3,7 +3,9 @@ import { AST_NODE_TYPES } from '@typescript-eslint/utils';
 
 import { createRule } from '../utils/index.js';
 
-const ANGLE_PLACEHOLDER = /<[^<>\n]+?>/;
+// Excludes `@` so that emails inside npm "person" strings
+// (e.g. `"author": "Jane Doe <jane@example.com>"`) are not flagged.
+const ANGLE_PLACEHOLDER = /<[^<>\n@]+?>/;
 const MUSTACHE_PLACEHOLDER = /\{\{[^{}\n]+?\}\}/;
 
 function findPlaceholder(value: string): { pattern: string; type: 'angle' | 'mustache' } | null {

package/src/rules/node-usable-as-tool.ts

@@ -1,4 +1,4 @@
-import { TSESTree } from '@typescript-eslint/types';
+import { TSESTree } from '@typescript-eslint/utils';
 
 import {
 	isNodeTypeClass,

package/src/rules/package-name-convention.test.ts

@@ -26,11 +26,6 @@ ruleTester.run('package-name-convention', PackageNameConventionRule, {
 			filename: 'package.json',
 			code: '{ "name": "@author/n8n-nodes-service", "version": "1.0.0" }',
 		},
-		{
-			name: 'object without name property',
-			filename: 'package.json',
-			code: '{ "version": "1.0.0", "description": "test" }',
-		},
 		{
 			name: 'non-package.json file ignored',
 			filename: 'some-config.json',
@@ -185,5 +180,37 @@ ruleTester.run('package-name-convention', PackageNameConventionRule, {
 				},
 			],
 		},
+		{
+			name: 'missing name property',
+			filename: 'package.json',
+			code: '{ "version": "1.0.0", "description": "test" }',
+			errors: [
+				{
+					messageId: 'missingName',
+				},
+			],
+		},
+		{
+			name: 'default placeholder name',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-<...>", "version": "1.0.0" }',
+			errors: [
+				{
+					messageId: 'defaultPlaceholderName',
+					data: { packageName: 'n8n-nodes-<...>' },
+				},
+			],
+		},
+		{
+			name: 'name containing default placeholder',
+			filename: 'package.json',
+			code: '{ "name": "@company/n8n-nodes-<...>", "version": "1.0.0" }',
+			errors: [
+				{
+					messageId: 'defaultPlaceholderName',
+					data: { packageName: '@company/n8n-nodes-<...>' },
+				},
+			],
+		},
 	],
 });

package/src/rules/package-name-convention.ts

@@ -15,6 +15,10 @@ export const PackageNameConventionRule = createRule({
 			renameTo: "Rename to '{{suggestedName}}'",
 			invalidPackageName:
 				'Package name "{{ packageName }}" must follow the convention "n8n-nodes-[PACKAGE-NAME]" or "@[AUTHOR]/n8n-nodes-[PACKAGE-NAME]"',
+			missingName:
+				'Package name is missing. Add a "name" field following the convention "n8n-nodes-[PACKAGE-NAME]" or "@[AUTHOR]/n8n-nodes-[PACKAGE-NAME]"',
+			defaultPlaceholderName:
+				'Package name "{{ packageName }}" still contains the default placeholder. Replace "<...>" with your package name',
 		},
 		schema: [],
 		hasSuggestions: true,
@@ -34,6 +38,10 @@ export const PackageNameConventionRule = createRule({
 				const nameProperty = findJsonProperty(node, 'name');
 
 				if (!nameProperty) {
+					context.report({
+						node,
+						messageId: 'missingName',
+					});
 					return;
 				}
 
@@ -44,6 +52,17 @@ export const PackageNameConventionRule = createRule({
 				const packageName = nameProperty.value.value;
 				const packageNameStr = typeof packageName === 'string' ? packageName : null;
 
+				if (packageNameStr && isDefaultPlaceholderName(packageNameStr)) {
+					context.report({
+						node: nameProperty,
+						messageId: 'defaultPlaceholderName',
+						data: {
+							packageName: packageNameStr,
+						},
+					});
+					return;
+				}
+
 				if (!packageNameStr || !isValidPackageName(packageNameStr)) {
 					const suggestions: ReportSuggestionArray<'invalidPackageName' | 'renameTo'> = [];
 
@@ -75,6 +94,10 @@ export const PackageNameConventionRule = createRule({
 	},
 });
 
+function isDefaultPlaceholderName(name: string): boolean {
+	return name.includes('<...>');
+}
+
 function isValidPackageName(name: string): boolean {
 	const unscoped = /^n8n-nodes-.+$/;
 	const scoped = /^@.+\/n8n-nodes-.+$/;

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

@@ -1,5 +1,4 @@
-import { DefinitionType } from '@typescript-eslint/scope-manager';
-import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES, TSESLint, type TSESTree } from '@typescript-eslint/utils';
 
 import { isFileType } from '../utils/index.js';
 import { createRule } from '../utils/rule-creator.js';
@@ -68,7 +67,9 @@ export const RequireNodeApiErrorRule = createRule({
 					const scope = context.sourceCode.getScope(node);
 					const ref = scope.references.find((r) => r.identifier === argument);
 					const isCatchParam =
-						ref?.resolved?.defs.some((def) => def.type === DefinitionType.CatchClause) ?? false;
+						ref?.resolved?.defs.some(
+							(def) => def.type === TSESLint.Scope.DefinitionType.CatchClause,
+						) ?? false;
 
 					if (isCatchParam) {
 						context.report({ node, messageId: 'useNodeApiError' });

package/src/rules/valid-credential-references.ts

@@ -1,4 +1,4 @@
-import { TSESTree } from '@typescript-eslint/types';
+import { TSESTree } from '@typescript-eslint/utils';
 import type { ReportSuggestionArray } from '@typescript-eslint/utils/ts-eslint';
 
 import {