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

package/docs/rules/no-unsafe-connection-type-cast.md

@@ -0,0 +1,58 @@
+# Disallow type-erasing casts (`as never`, `as any`, `as unknown`) on node description `inputs`/`outputs` (`@n8n/community-nodes/no-unsafe-connection-type-cast`)
+
+💼 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
+
+A cast such as `inputs: ['main'] as never` compiles, so nothing in CI objects to it. It also switches off the check that makes `inputs` and `outputs` trustworthy. TypeScript stops verifying the value against `INodeTypeDescription`, and the [`node-connection-type-literal`](node-connection-type-literal.md) rule stops seeing the array, because the cast wraps it. A malformed connection declaration then reaches review and build with no automated signal at all. Removing the cast restores both checks.
+
+There is no legitimate reason to erase the type here. Dynamic connection lists are already allowed as expression strings, and correct static lists type-check on their own:
+
+```typescript
+inputs: `={{ (${configureInputs})($parameter) }}`,
+```
+
+The rule flags `as never`, `as any` and `as unknown`, including inside a chain like `as unknown as NodeConnectionType[]`, where the intermediate `unknown` is what defeats the checker. Expressions that keep the value structurally checked are left alone: `as const`, `satisfies T` and a plain `as NodeConnectionType[]`.
+
+A `satisfies` around a cast does not restore the check, so `['main'] as never satisfies NodeConnectionType[]` is still reported. The suggestion removes the cast and keeps the `satisfies`.
+
+Removing the cast is offered as a suggestion rather than an autofix, because it may surface a real type error that was being suppressed. That error is the point: it is the bug the cast was hiding.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'myNode',
+    inputs: ['main'] as never,
+    outputs: ['main'] as never,
+    properties: [],
+  };
+}
+```
+
+### ✅ Correct
+
+```typescript
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+import { NodeConnectionTypes } from 'n8n-workflow';
+
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'myNode',
+    inputs: [NodeConnectionTypes.Main],
+    outputs: [NodeConnectionTypes.Main],
+    properties: [],
+  };
+}
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@n8n/eslint-plugin-community-nodes",
   "type": "module",
-  "version": "0.30.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.10.0",
-    "@n8n/vitest-config": "1.21.0",
-    "n8n-workflow": "2.37.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-overrides-field.test.ts

@@ -46,5 +46,22 @@ ruleTester.run('no-overrides-field', NoOverridesFieldRule, {
 			code: '{ "name": "n8n-nodes-sinch", "overrides": { "axios": "1.7.0", "fast-xml-parser": "4.4.0", "minimatch": "9.0.5", "@langchain/core": "0.3.0", "qs": "6.13.0" } }',
 			errors: [{ messageId: 'overridesForbidden' }],
 		},
+		// CE-2377: `resolutions` is the Yarn equivalent of npm's `overrides` — it
+		// forces/replaces a transitive dependency to a maintainer-controlled
+		// version or an arbitrary tarball/git URL that never appears in the node's
+		// readable source. Community node vetting must flag it for the same
+		// supply-chain reason it flags `overrides`, but the rule ignores it today.
+		{
+			name: 'resolutions as object is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "resolutions": { "axios": "1.0.0" } }',
+			errors: [{ messageId: 'overridesForbidden' }],
+		},
+		{
+			name: 'resolutions pinning a transitive dep to an arbitrary tarball is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "resolutions": { "minimatch": "https://example.com/evil.tgz" } }',
+			errors: [{ messageId: 'overridesForbidden' }],
+		},
 	],
 });

package/src/rules/no-overrides-field.ts

@@ -12,7 +12,7 @@ export const NoOverridesFieldRule = createRule({
 		},
 		messages: {
 			overridesForbidden:
-				'The "overrides" field is not allowed in community node packages. Each community package installs into an isolated dependency tree, so overrides do not affect other nodes or n8n core — in practice they are copy-pasted boilerplate with no useful effect. Use the helpers on the execute context (this.helpers.httpRequest, etc.) instead; most community nodes do not need third-party runtime libraries.',
+				'The "overrides"/"resolutions" fields are not allowed in community node packages. Each community package installs into an isolated dependency tree, so overrides do not affect other nodes or n8n core — in practice they are copy-pasted boilerplate with no useful effect, and can silently force a transitive dependency to an arbitrary version or tarball. Use the helpers on the execute context (this.helpers.httpRequest, etc.) instead; most community nodes do not need third-party runtime libraries.',
 		},
 		schema: [],
 	},
@@ -28,15 +28,18 @@ export const NoOverridesFieldRule = createRule({
 					return;
 				}
 
-				const overridesProp = findJsonProperty(node, 'overrides');
-				if (!overridesProp) {
-					return;
+				// `resolutions` is the Yarn equivalent of npm's `overrides`; both force
+				// a transitive dependency to an arbitrary version/tarball, so treat them
+				// the same way.
+				for (const field of ['overrides', 'resolutions']) {
+					const prop = findJsonProperty(node, field);
+					if (prop) {
+						context.report({
+							node: prop,
+							messageId: 'overridesForbidden',
+						});
+					}
 				}
-
-				context.report({
-					node: overridesProp,
-					messageId: 'overridesForbidden',
-				});
 			},
 		};
 	},