@n8n/eslint-plugin-community-nodes 0.31.0 → 0.32.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@n8n/eslint-plugin-community-nodes",
   "type": "module",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "main": "./dist/plugin.js",
   "types": "./dist/plugin.d.ts",
   "exports": {
@@ -16,7 +16,10 @@
     "fastest-levenshtein": "1.0.16"
   },
   "devDependencies": {
+    "@n8n/typescript-config": "1.11.0",
+    "@n8n/vitest-config": "1.21.0",
     "@types/node": "24.10.1",
+    "n8n-workflow": "2.39.0",
     "@typescript-eslint/rule-tester": "^8.35.0",
     "eslint-doc-generator": "^2.2.2",
     "eslint-plugin-eslint-plugin": "^7.0.0",
@@ -24,10 +27,7 @@
     "@typescript/native": "npm:typescript@7.0.2",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "vite": "^8.0.2",
-    "vitest": "^4.1.9",
-    "@n8n/typescript-config": "1.11.0",
-    "n8n-workflow": "2.38.0",
-    "@n8n/vitest-config": "1.21.0"
+    "vitest": "^4.1.9"
   },
   "peerDependencies": {
     "eslint": "9.29.0",

package/src/plugin.ts

@@ -41,6 +41,7 @@ const configs = {
 			'@n8n/community-nodes/no-runtime-dependencies': 'error',
 			'@n8n/community-nodes/no-silent-error-swallowing': 'error',
 			'@n8n/community-nodes/no-template-placeholders': 'error',
+			'@n8n/community-nodes/no-unsafe-connection-type-cast': 'error',
 			'@n8n/community-nodes/icon-validation': 'error',
 			'@n8n/community-nodes/icon-prefer-themed-variants': 'warn',
 			'@n8n/community-nodes/resource-operation-pattern': 'warn',
@@ -89,6 +90,7 @@ const configs = {
 			'@n8n/community-nodes/no-runtime-dependencies': 'error',
 			'@n8n/community-nodes/no-silent-error-swallowing': 'error',
 			'@n8n/community-nodes/no-template-placeholders': 'error',
+			'@n8n/community-nodes/no-unsafe-connection-type-cast': 'error',
 			'@n8n/community-nodes/icon-validation': 'error',
 			'@n8n/community-nodes/icon-prefer-themed-variants': 'warn',
 			'@n8n/community-nodes/credential-documentation-url': 'error',

package/src/rules/index.ts

@@ -26,6 +26,7 @@ import { NoRestrictedImportsRule } from './no-restricted-imports.js';
 import { NoRuntimeDependenciesRule } from './no-runtime-dependencies.js';
 import { NoSilentErrorSwallowingRule } from './no-silent-error-swallowing.js';
 import { NoTemplatePlaceholdersRule } from './no-template-placeholders.js';
+import { NoUnsafeConnectionTypeCastRule } from './no-unsafe-connection-type-cast.js';
 import { NodeClassDescriptionIconMissingRule } from './node-class-description-icon-missing.js';
 import { NodeConnectionTypeLiteralRule } from './node-connection-type-literal.js';
 import { NodeRegistrationCompleteRule } from './node-registration-complete.js';
@@ -65,6 +66,7 @@ export const rules = {
 	'no-runtime-dependencies': NoRuntimeDependenciesRule,
 	'no-silent-error-swallowing': NoSilentErrorSwallowingRule,
 	'no-template-placeholders': NoTemplatePlaceholdersRule,
+	'no-unsafe-connection-type-cast': NoUnsafeConnectionTypeCastRule,
 	'icon-validation': IconValidationRule,
 	'icon-prefer-themed-variants': IconPreferThemedVariantsRule,
 	'resource-operation-pattern': ResourceOperationPatternRule,

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

@@ -19,6 +19,7 @@ const mockFindPackageJson = vi.mocked(fileUtils.findPackageJson);
 const ruleTester = new RuleTester();
 
 const nodeFilePath = '/tmp/TestNode.node.ts';
+const versionedNodeFilePath = '/tmp/v1/TestNodeV1.node.ts';
 
 function createNodeCode(
 	credentials: Array<string | { name: string; required?: boolean }> = [],
@@ -97,6 +98,36 @@ export class TestNode implements INodeType {
 }`;
 }
 
+/**
+ * Versioned node layout from the node-building docs: each version class
+ * implements `INodeType` and assigns `description` in its constructor, merging
+ * the `baseDescription` that the `VersionedNodeType` entry file passes in.
+ */
+function createVersionedNodeCode(credentialNameLiteral: string): string {
+	return `
+import type { INodeType, INodeTypeBaseDescription, INodeTypeDescription } from 'n8n-workflow';
+
+export class TestNodeV1 implements INodeType {
+	description: INodeTypeDescription;
+
+	constructor(baseDescription: INodeTypeBaseDescription) {
+		this.description = {
+			...baseDescription,
+			version: 1,
+			inputs: ['main'],
+			outputs: ['main'],
+			credentials: [
+				{
+					name: ${credentialNameLiteral},
+					required: true,
+				},
+			],
+			properties: [],
+		};
+	}
+}`;
+}
+
 // Helper function to create non-node class
 function createNonNodeClass(): string {
 	return `
@@ -163,6 +194,29 @@ ruleTester.run('no-credential-reuse', NoCredentialReuseRule, {
 		},
 	],
 	invalid: [
+		{
+			name: 'SECURITY: versioned node assigning description in its constructor uses credential not in package',
+			filename: versionedNodeFilePath,
+			code: createVersionedNodeCode("'ExternalApi'"),
+			errors: [
+				{
+					messageId: 'credentialNotInPackage',
+					data: { credentialName: 'ExternalApi' },
+					suggestions: [
+						{
+							messageId: 'useAvailable',
+							data: { suggestedName: 'myApiCredential' },
+							output: createVersionedNodeCode('"myApiCredential"'),
+						},
+						{
+							messageId: 'useAvailable',
+							data: { suggestedName: 'anotherApiCredential' },
+							output: createVersionedNodeCode('"anotherApiCredential"'),
+						},
+					],
+				},
+			],
+		},
 		{
 			name: 'SECURITY: node using credential not in package (object form)',
 			filename: nodeFilePath,

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

@@ -1,9 +1,8 @@
-import { TSESTree } from '@typescript-eslint/utils';
 import type { ReportSuggestionArray } from '@typescript-eslint/utils/ts-eslint';
 
 import {
 	isNodeTypeClass,
-	findClassProperty,
+	findNodeDescriptionObject,
 	findArrayLiteralProperty,
 	extractCredentialNameFromArray,
 	findPackageJson,
@@ -59,15 +58,12 @@ export const NoCredentialReuseRule = createRule({
 					return;
 				}
 
-				const descriptionProperty = findClassProperty(node, 'description');
-				if (
-					!descriptionProperty?.value ||
-					descriptionProperty.value.type !== TSESTree.AST_NODE_TYPES.ObjectExpression
-				) {
+				const description = findNodeDescriptionObject(node);
+				if (!description) {
 					return;
 				}
 
-				const credentialsArray = findArrayLiteralProperty(descriptionProperty.value, 'credentials');
+				const credentialsArray = findArrayLiteralProperty(description, 'credentials');
 				if (!credentialsArray) {
 					return;
 				}

package/src/rules/no-emoji-in-options.test.ts

@@ -16,6 +16,27 @@ function createNodeCode(body: string): string {
 	`;
 }
 
+/**
+ * Versioned node layout from the node-building docs: the version class assigns
+ * `description` in its constructor instead of as a property initializer.
+ */
+function createVersionedNodeCode(body: string): string {
+	return `
+		import type { INodeType, INodeTypeBaseDescription, INodeTypeDescription } from 'n8n-workflow';
+
+		export class TestNodeV1 implements INodeType {
+			description: INodeTypeDescription;
+
+			constructor(baseDescription: INodeTypeBaseDescription) {
+				this.description = {
+					...baseDescription,
+					${body}
+				};
+			}
+		}
+	`;
+}
+
 ruleTester.run('no-emoji-in-options', NoEmojiInOptionsRule, {
 	valid: [
 		{
@@ -75,6 +96,62 @@ ruleTester.run('no-emoji-in-options', NoEmojiInOptionsRule, {
 		},
 	],
 	invalid: [
+		{
+			name: 'emoji in option name of a versioned node assigning description in its constructor',
+			filename: '/tmp/v1/TestNodeV1.node.ts',
+			code: createVersionedNodeCode(`
+				version: 1,
+				properties: [
+					{
+						displayName: 'Operation',
+						name: 'operation',
+						type: 'options',
+						options: [
+							{ name: '✅ Create', value: 'create' },
+							{ name: 'Delete', value: 'delete' },
+						],
+						default: 'create',
+					},
+				],
+			`),
+			errors: [{ messageId: 'emojiInOption', data: { key: 'name', emoji: '✅' } }],
+		},
+		{
+			name: 'emoji in a description that is cast with `as`',
+			filename: '/tmp/TestNode.node.ts',
+			code: `
+				import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+
+				export class TestNode implements INodeType {
+					description = {
+						displayName: '🚀 Rocket Node',
+						name: 'testNode',
+						properties: [],
+					} as INodeTypeDescription;
+				}
+			`,
+			errors: [{ messageId: 'emojiInOption', data: { key: 'displayName', emoji: '🚀' } }],
+		},
+		{
+			name: 'emoji in a constructor-assigned description that is cast with `as`',
+			filename: '/tmp/v1/TestNodeV1.node.ts',
+			code: `
+				import type { INodeType, INodeTypeBaseDescription, INodeTypeDescription } from 'n8n-workflow';
+
+				export class TestNodeV1 implements INodeType {
+					description: INodeTypeDescription;
+
+					constructor(baseDescription: INodeTypeBaseDescription) {
+						this.description = {
+							...baseDescription,
+							displayName: '🚀 Rocket Node',
+							properties: [],
+						} as INodeTypeDescription;
+					}
+				}
+			`,
+			errors: [{ messageId: 'emojiInOption', data: { key: 'displayName', emoji: '🚀' } }],
+		},
 		{
 			name: 'emoji in node displayName',
 			filename: '/tmp/TestNode.node.ts',

package/src/rules/no-emoji-in-options.ts

@@ -3,7 +3,7 @@ import { AST_NODE_TYPES } from '@typescript-eslint/utils';
 
 import {
 	isNodeTypeClass,
-	findClassProperty,
+	findNodeDescriptionObject,
 	getStringLiteralValue,
 	isFileType,
 	createRule,
@@ -93,12 +93,12 @@ export const NoEmojiInOptionsRule = createRule({
 					return;
 				}
 
-				const descriptionProperty = findClassProperty(node, 'description');
-				if (!descriptionProperty?.value) {
+				const description = findNodeDescriptionObject(node);
+				if (!description) {
 					return;
 				}
 
-				traverse(descriptionProperty.value);
+				traverse(description);
 			},
 		};
 	},

package/src/rules/no-unsafe-connection-type-cast.test.ts

@@ -0,0 +1,306 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { NoUnsafeConnectionTypeCastRule } from './no-unsafe-connection-type-cast.js';
+
+const ruleTester = new RuleTester();
+
+function createNodeCode(inputs: string, outputs: string): string {
+	return `
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+import { NodeConnectionTypes } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description: INodeTypeDescription = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		group: ['input'],
+		version: 1,
+		description: 'A test node',
+		defaults: { name: 'Test Node' },
+		inputs: ${inputs},
+		outputs: ${outputs},
+		properties: [],
+	};
+}`;
+}
+
+/** Lets a test spell the connection key itself, e.g. `'inputs'` or `['inputs']`. */
+function createNodeCodeWithProperty(property: string): string {
+	return `
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+import { NodeConnectionTypes } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description: INodeTypeDescription = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		group: ['input'],
+		version: 1,
+		description: 'A test node',
+		defaults: { name: 'Test Node' },
+		${property},
+		outputs: [NodeConnectionTypes.Main],
+		properties: [],
+	};
+}`;
+}
+
+const MAIN = '[NodeConnectionTypes.Main]';
+
+ruleTester.run('no-unsafe-connection-type-cast', NoUnsafeConnectionTypeCastRule, {
+	valid: [
+		{
+			name: 'class that does not implement INodeType',
+			code: 'export class RegularClass {\n\tsomeProperty = "value";\n}',
+		},
+		{
+			name: 'node without casts',
+			code: createNodeCode(MAIN, MAIN),
+		},
+		{
+			name: 'node with empty inputs and outputs',
+			code: createNodeCode('[]', '[]'),
+		},
+		{
+			name: 'dynamic inputs as a template literal expression',
+			code: createNodeCode('`={{ (() => [NodeConnectionTypes.Main])() }}`', MAIN),
+		},
+		{
+			name: 'as const narrows rather than erases',
+			code: createNodeCode(`${MAIN} as const`, MAIN),
+		},
+		{
+			name: 'satisfies keeps the type checked',
+			code: createNodeCode(`${MAIN} satisfies NodeConnectionType[]`, MAIN),
+		},
+		{
+			name: 'a named type assertion is still checked structurally',
+			code: createNodeCode(`${MAIN} as NodeConnectionType[]`, MAIN),
+		},
+		{
+			name: 'casts elsewhere in the description are untouched',
+			code: createNodeCode(MAIN, MAIN).replace('version: 1,', 'version: 1 as never,'),
+		},
+	],
+	invalid: [
+		{
+			name: 'as never on inputs',
+			code: createNodeCode("['main'] as never", MAIN),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'never', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode("['main']", MAIN),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'as never on outputs',
+			code: createNodeCode(MAIN, "['main'] as never"),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'never', property: 'outputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode(MAIN, "['main']"),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'as never on both inputs and outputs',
+			code: createNodeCode("['main'] as never", "['main'] as never"),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'never', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode("['main']", "['main'] as never"),
+						},
+					],
+				},
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'never', property: 'outputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode("['main'] as never", "['main']"),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'as any',
+			code: createNodeCode("['main'] as any", MAIN),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'any', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode("['main']", MAIN),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'as unknown',
+			code: createNodeCode("['main'] as unknown", MAIN),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'unknown', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode("['main']", MAIN),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'double cast through unknown removes the whole chain',
+			code: createNodeCode("['main'] as unknown as NodeConnectionType[]", MAIN),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'unknown', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode("['main']", MAIN),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'angle-bracket assertion',
+			code: createNodeCode("<never>['main']", MAIN),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'never', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode("['main']", MAIN),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'erasing cast hidden behind an outer satisfies',
+			code: createNodeCode("['main'] as never satisfies NodeConnectionType[]", MAIN),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'never', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode("['main'] satisfies NodeConnectionType[]", MAIN),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'erasing cast wrapped around an inner satisfies',
+			code: createNodeCode("['main'] satisfies NodeConnectionType[] as never", MAIN),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'never', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode("['main'] satisfies NodeConnectionType[]", MAIN),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'cast nested under satisfies, with a second cast outside it',
+			code: createNodeCode("['main'] as never satisfies NodeConnectionType[] as unknown", MAIN),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'unknown', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							// Both casts go, the satisfies between them stays.
+							output: createNodeCode("['main'] satisfies NodeConnectionType[]", MAIN),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'quoted connection key',
+			code: createNodeCodeWithProperty("'inputs': ['main'] as never"),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'never', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCodeWithProperty("'inputs': ['main']"),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'computed connection key',
+			code: createNodeCodeWithProperty("['inputs']: ['main'] as never"),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'never', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCodeWithProperty("['inputs']: ['main']"),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'cast hiding a malformed declaration',
+			code: createNodeCode("'not-an-array' as never", MAIN),
+			errors: [
+				{
+					messageId: 'erasingCast',
+					data: { typeName: 'never', property: 'inputs' },
+					suggestions: [
+						{
+							messageId: 'removeCast',
+							output: createNodeCode("'not-an-array'", MAIN),
+						},
+					],
+				},
+			],
+		},
+	],
+});