@n8n/eslint-plugin-community-nodes 0.21.0 → 0.22.0

package/docs/rules/node-class-description-name-camelcase.md

@@ -0,0 +1,41 @@
+# Node class `description.name` must be camelCase (`@n8n/community-nodes/node-class-description-name-camelcase`)
+
+💼 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 inside a node class `description` (those implementing `INodeType` or extending `Node` in `*.node.ts` files) is the internal identifier used to register and reference the node. n8n convention requires this identifier to be camelCase: it must start with a lowercase letter and contain only letters and digits, with no spaces, hyphens, underscores, or other separators.
+
+The value must match `^[a-z][a-zA-Z0-9]*$`.
+
+The rule is automatically fixable: separators are removed, each subsequent word is upper-cased, and the first character is lower-cased (e.g. `My Node` → `myNode`). Names that cannot be repaired into a valid identifier (for example, those starting with a digit) are reported without an autofix.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'My Node',
+    // ...
+  };
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'myNode',
+    // ...
+  };
+}
+```

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

@@ -1,4 +1,4 @@
-# Require community node package.json peerDependencies to contain only "n8n-workflow": "*" (and optionally "ai-node-sdk") (`@n8n/community-nodes/valid-peer-dependencies`)
+# Require community node package.json peerDependencies to contain only "n8n-workflow": "*" (and optionally "@n8n/ai-node-sdk") (`@n8n/community-nodes/valid-peer-dependencies`)
 
 💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@n8n/eslint-plugin-community-nodes",
   "type": "module",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "main": "./dist/plugin.js",
   "types": "./dist/plugin.d.ts",
   "exports": {
@@ -25,7 +25,7 @@
     "vitest": "^4.1.1",
     "@n8n/typescript-config": "1.6.0",
     "@n8n/vitest-config": "1.15.0",
-    "n8n-workflow": "2.27.0"
+    "n8n-workflow": "2.28.0"
   },
   "peerDependencies": {
     "eslint": "9.29.0",

package/src/plugin.ts

@@ -48,6 +48,7 @@ const configs = {
 			'@n8n/community-nodes/cred-class-oauth2-naming': 'error',
 			'@n8n/community-nodes/cred-filename-against-convention': 'error',
 			'@n8n/community-nodes/node-connection-type-literal': 'error',
+			'@n8n/community-nodes/node-class-description-name-camelcase': 'error',
 			'@n8n/community-nodes/node-filename-against-convention': 'error',
 			'@n8n/community-nodes/missing-paired-item': 'error',
 			'@n8n/community-nodes/no-builder-hint-leakage': 'error',
@@ -97,6 +98,7 @@ const configs = {
 			'@n8n/community-nodes/cred-class-oauth2-naming': 'error',
 			'@n8n/community-nodes/cred-filename-against-convention': 'error',
 			'@n8n/community-nodes/node-connection-type-literal': 'error',
+			'@n8n/community-nodes/node-class-description-name-camelcase': 'error',
 			'@n8n/community-nodes/node-filename-against-convention': 'error',
 			'@n8n/community-nodes/missing-paired-item': 'error',
 			'@n8n/community-nodes/no-builder-hint-leakage': 'error',

package/src/rules/ai-node-package-json.test.ts

@@ -11,6 +11,11 @@ ruleTester.run('ai-node-package-json', AiNodePackageJsonRule, {
 			filename: 'package.json',
 			code: '{ "name": "n8n-nodes-example", "n8n": { "aiNodeSdkVersion": 1 }, "peerDependencies": { "n8n-workflow": "*", "ai-node-sdk": "*" } }',
 		},
+		{
+			name: 'both n8n.aiNodeSdkVersion and scoped @n8n/ai-node-sdk peer dependency present',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "aiNodeSdkVersion": 1 }, "peerDependencies": { "n8n-workflow": "*", "@n8n/ai-node-sdk": "*" } }',
+		},
 		{
 			name: 'neither n8n.aiNodeSdkVersion nor ai-node-sdk present (non-AI package)',
 			filename: 'package.json',

package/src/rules/ai-node-package-json.ts

@@ -13,9 +13,9 @@ export const AiNodePackageJsonRule = createRule({
 		},
 		messages: {
 			missingPeerDep:
-				'Package declares "n8n.aiNodeSdkVersion" but is missing "ai-node-sdk" in peerDependencies. Add "ai-node-sdk": "*" to peerDependencies.',
+				'Package declares "n8n.aiNodeSdkVersion" but is missing "@n8n/ai-node-sdk" in peerDependencies. Add "@n8n/ai-node-sdk": "*" to peerDependencies.',
 			missingSdkVersion:
-				'Package has "ai-node-sdk" in peerDependencies but is missing "aiNodeSdkVersion" in the "n8n" section of package.json.',
+				'Package has "@n8n/ai-node-sdk" in peerDependencies but is missing "aiNodeSdkVersion" in the "n8n" section of package.json.',
 			invalidSdkVersion: '"n8n.aiNodeSdkVersion" must be a positive integer, got {{ value }}.',
 			wrongLocation:
 				'"aiNodeSdkVersion" must be inside the "n8n" section, not at the root level of package.json.',
@@ -49,7 +49,8 @@ export const AiNodePackageJsonRule = createRule({
 				const hasAiNodeSdkVersion = aiNodeSdkVersionProp !== null;
 				const hasAiNodeSdkPeerDep =
 					peerDependenciesProp?.value.type === AST_NODE_TYPES.ObjectExpression &&
-					findJsonProperty(peerDependenciesProp.value, 'ai-node-sdk') !== null;
+					(findJsonProperty(peerDependenciesProp.value, '@n8n/ai-node-sdk') !== null ||
+						findJsonProperty(peerDependenciesProp.value, 'ai-node-sdk') !== null);
 
 				// Catch aiNodeSdkVersion placed at root level instead of inside n8n
 				if (rootAiNodeSdkVersionProp) {

package/src/rules/index.ts

@@ -26,6 +26,7 @@ import { NoRestrictedImportsRule } from './no-restricted-imports.js';
 import { NoRuntimeDependenciesRule } from './no-runtime-dependencies.js';
 import { NoTemplatePlaceholdersRule } from './no-template-placeholders.js';
 import { NodeClassDescriptionIconMissingRule } from './node-class-description-icon-missing.js';
+import { NodeClassDescriptionNameCamelCaseRule } from './node-class-description-name-camelcase.js';
 import { NodeConnectionTypeLiteralRule } from './node-connection-type-literal.js';
 import { NodeFilenameAgainstConventionRule } from './node-filename-against-convention.js';
 import { NodeOperationErrorItemIndexRule } from './node-operation-error-itemindex.js';
@@ -68,6 +69,7 @@ export const rules = {
 	'resource-operation-pattern': ResourceOperationPatternRule,
 	'credential-documentation-url': CredentialDocumentationUrlRule,
 	'node-class-description-icon-missing': NodeClassDescriptionIconMissingRule,
+	'node-class-description-name-camelcase': NodeClassDescriptionNameCamelCaseRule,
 	'cred-class-field-icon-missing': CredClassFieldIconMissingRule,
 	'cred-class-name-field-conventions': CredClassNameFieldConventionsRule,
 	'cred-class-name-suffix': CredClassNameSuffixRule,

package/src/rules/node-class-description-name-camelcase.test.ts

@@ -0,0 +1,121 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { NodeClassDescriptionNameCamelCaseRule } from './node-class-description-name-camelcase.js';
+
+const ruleTester = new RuleTester();
+
+function createNodeCode(name: string): string {
+	return `
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description: INodeTypeDescription = {
+		displayName: 'Test Node',
+		name: '${name}',
+		group: ['input'],
+		version: 1,
+		description: 'A test node',
+		defaults: { name: 'Test Node' },
+		inputs: [],
+		outputs: [],
+		properties: [],
+	};
+}`;
+}
+
+function createNodeCodeWithoutName(): string {
+	return `
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description: INodeTypeDescription = {
+		displayName: 'Test Node',
+		group: ['input'],
+		version: 1,
+		description: 'A test node',
+		defaults: { name: 'Test Node' },
+		inputs: [],
+		outputs: [],
+		properties: [],
+	};
+}`;
+}
+
+function createRegularClass(): string {
+	return `
+export class SomeHelper {
+	name = 'My Helper';
+}`;
+}
+
+ruleTester.run('node-class-description-name-camelcase', NodeClassDescriptionNameCamelCaseRule, {
+	valid: [
+		{
+			name: 'single lowercase word',
+			filename: '/tmp/Github.node.ts',
+			code: createNodeCode('github'),
+		},
+		{
+			name: 'camelCase multi-word name',
+			filename: '/tmp/GoogleSheets.node.ts',
+			code: createNodeCode('googleSheets'),
+		},
+		{
+			name: 'camelCase name with digits',
+			filename: '/tmp/Oauth2.node.ts',
+			code: createNodeCode('myNode2'),
+		},
+		{
+			name: 'class not implementing INodeType is ignored',
+			filename: '/tmp/Github.node.ts',
+			code: createRegularClass(),
+		},
+		{
+			name: 'non-.node.ts file is ignored',
+			filename: '/tmp/Github.ts',
+			code: createNodeCode('My Node'),
+		},
+		{
+			name: 'missing description.name is ignored',
+			filename: '/tmp/Github.node.ts',
+			code: createNodeCodeWithoutName(),
+		},
+	],
+	invalid: [
+		{
+			name: 'PascalCase first letter is lowercased',
+			filename: '/tmp/Github.node.ts',
+			code: createNodeCode('MyNode'),
+			errors: [{ messageId: 'notCamelCase', data: { value: 'MyNode' } }],
+			output: createNodeCode('myNode'),
+		},
+		{
+			name: 'spaces are removed and camelCased',
+			filename: '/tmp/Github.node.ts',
+			code: createNodeCode('My Node'),
+			errors: [{ messageId: 'notCamelCase', data: { value: 'My Node' } }],
+			output: createNodeCode('myNode'),
+		},
+		{
+			name: 'hyphen separators are removed and camelCased',
+			filename: '/tmp/Github.node.ts',
+			code: createNodeCode('my-node'),
+			errors: [{ messageId: 'notCamelCase', data: { value: 'my-node' } }],
+			output: createNodeCode('myNode'),
+		},
+		{
+			name: 'underscore separators are removed and camelCased',
+			filename: '/tmp/Github.node.ts',
+			code: createNodeCode('my_cool_node'),
+			errors: [{ messageId: 'notCamelCase', data: { value: 'my_cool_node' } }],
+			output: createNodeCode('myCoolNode'),
+		},
+		{
+			name: 'names starting with a digit are reported without an autofix',
+			filename: '/tmp/Github.node.ts',
+			code: createNodeCode('123node'),
+			errors: [{ messageId: 'notCamelCase', data: { value: '123node' } }],
+			output: null,
+		},
+	],
+});

package/src/rules/node-class-description-name-camelcase.ts

@@ -0,0 +1,114 @@
+import { TSESTree } from '@typescript-eslint/utils';
+
+import {
+	isNodeTypeClass,
+	findClassProperty,
+	findObjectProperty,
+	getStringLiteralValue,
+	isFileType,
+	createRule,
+} from '../utils/index.js';
+
+// `description.name` must be camelCase: a lowercase letter followed by
+// letters/digits, with no separators.
+const CAMEL_CASE_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
+
+/**
+ * Converts an arbitrary node name to camelCase by splitting on any
+ * non-alphanumeric separators, upper-casing the first character of each
+ * subsequent segment, and lower-casing the very first character.
+ * Examples: `My Node` -> `myNode`, `my-node` -> `myNode`, `GitHub` -> `gitHub`.
+ */
+function toCamelCase(value: string): string {
+	const segments = value.split(/[^a-zA-Z0-9]+/).filter(Boolean);
+	if (segments.length === 0) {
+		return value;
+	}
+
+	const joined = segments
+		.map((segment, index) =>
+			index === 0 ? segment : segment.charAt(0).toUpperCase() + segment.slice(1),
+		)
+		.join('');
+
+	return joined.charAt(0).toLowerCase() + joined.slice(1);
+}
+
+// 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.
+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 NodeClassDescriptionNameCamelCaseRule = createRule({
+	name: 'node-class-description-name-camelcase',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Node class `description.name` must be camelCase',
+		},
+		messages: {
+			notCamelCase: "Node `description.name` '{{value}}' must be camelCase",
+		},
+		fixable: 'code',
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!isFileType(context.filename, '.node.ts')) {
+			return {};
+		}
+
+		return {
+			ClassDeclaration(node) {
+				if (!isNodeTypeClass(node)) {
+					return;
+				}
+
+				const descriptionProperty = findClassProperty(node, 'description');
+				if (descriptionProperty?.value?.type !== TSESTree.AST_NODE_TYPES.ObjectExpression) {
+					return;
+				}
+
+				const nameProperty = findObjectProperty(descriptionProperty.value, 'name');
+				if (!nameProperty) {
+					return;
+				}
+
+				const nameValue = getStringLiteralValue(nameProperty.value);
+				if (nameValue === null) {
+					return;
+				}
+
+				if (CAMEL_CASE_PATTERN.test(nameValue)) {
+					return;
+				}
+
+				const valueNode = nameProperty.value;
+				const fixedValue = toCamelCase(nameValue);
+				// Only offer an autofix when it actually yields a valid camelCase
+				// value (e.g. names starting with a digit cannot be repaired).
+				const canFix = fixedValue !== nameValue && CAMEL_CASE_PATTERN.test(fixedValue);
+
+				context.report({
+					node: valueNode,
+					messageId: 'notCamelCase',
+					data: { value: nameValue },
+					fix: canFix
+						? (fixer) => {
+								const quote = context.sourceCode.getText(valueNode).charAt(0);
+								return fixer.replaceText(valueNode, toStringLiteral(fixedValue, quote));
+							}
+						: undefined,
+				});
+			},
+		};
+	},
+});

package/src/rules/valid-peer-dependencies.test.ts

@@ -11,6 +11,11 @@ ruleTester.run('valid-peer-dependencies', ValidPeerDependenciesRule, {
 			filename: 'package.json',
 			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*" } }',
 		},
+		{
+			name: 'n8n-workflow and scoped @n8n/ai-node-sdk',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*", "@n8n/ai-node-sdk": "*" } }',
+		},
 		{
 			name: 'n8n-workflow and ai-node-sdk',
 			filename: 'package.json',

package/src/rules/valid-peer-dependencies.ts

@@ -5,7 +5,9 @@ import { createRule, findJsonProperty } from '../utils/index.js';
 
 const REQUIRED_DEP = 'n8n-workflow';
 const REQUIRED_VERSION = '*';
-const ALLOWED_DEPS = new Set([REQUIRED_DEP, 'ai-node-sdk']);
+// The published SDK is scoped (@n8n/ai-node-sdk); the unscoped name is kept for
+// backwards compatibility, mirroring no-restricted-imports.
+const ALLOWED_DEPS = new Set([REQUIRED_DEP, '@n8n/ai-node-sdk', 'ai-node-sdk']);
 
 export const ValidPeerDependenciesRule = createRule({
 	name: 'valid-peer-dependencies',
@@ -13,7 +15,7 @@ export const ValidPeerDependenciesRule = createRule({
 		type: 'problem',
 		docs: {
 			description:
-				'Require community node package.json peerDependencies to contain only "n8n-workflow": "*" (and optionally "ai-node-sdk")',
+				'Require community node package.json peerDependencies to contain only "n8n-workflow": "*" (and optionally "@n8n/ai-node-sdk")',
 		},
 		fixable: 'code',
 		messages: {
@@ -22,7 +24,7 @@ export const ValidPeerDependenciesRule = createRule({
 			missingN8nWorkflow: `"peerDependencies" must include "${REQUIRED_DEP}": "${REQUIRED_VERSION}".`,
 			pinnedN8nWorkflow: `"peerDependencies.${REQUIRED_DEP}" must be "${REQUIRED_VERSION}", got {{ value }}.`,
 			forbiddenPeerDependency:
-				'"{{ name }}" is not allowed in "peerDependencies". Only "n8n-workflow" and "ai-node-sdk" are permitted.',
+				'"{{ name }}" is not allowed in "peerDependencies". Only "n8n-workflow" and "@n8n/ai-node-sdk" are permitted.',
 		},
 		schema: [],
 	},