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

package/src/plugin.ts

@@ -32,6 +32,7 @@ const configs = {
 			'@n8n/community-nodes/no-forbidden-lifecycle-scripts': 'error',
 			'@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/icon-validation': 'error',
 			'@n8n/community-nodes/options-sorted-alphabetically': 'warn',
 			'@n8n/community-nodes/resource-operation-pattern': 'warn',
@@ -43,6 +44,7 @@ const configs = {
 			'@n8n/community-nodes/require-continue-on-fail': 'error',
 			'@n8n/community-nodes/require-node-api-error': 'error',
 			'@n8n/community-nodes/require-node-description-fields': 'error',
+			'@n8n/community-nodes/valid-credential-references': 'error',
 			'@n8n/community-nodes/valid-peer-dependencies': 'error',
 			'@n8n/community-nodes/webhook-lifecycle-complete': 'error',
 		},
@@ -63,6 +65,7 @@ const configs = {
 			'@n8n/community-nodes/no-forbidden-lifecycle-scripts': 'error',
 			'@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/icon-validation': 'error',
 			'@n8n/community-nodes/options-sorted-alphabetically': 'warn',
 			'@n8n/community-nodes/credential-documentation-url': 'error',
@@ -74,6 +77,7 @@ const configs = {
 			'@n8n/community-nodes/require-continue-on-fail': 'error',
 			'@n8n/community-nodes/require-node-api-error': 'error',
 			'@n8n/community-nodes/require-node-description-fields': 'error',
+			'@n8n/community-nodes/valid-credential-references': 'error',
 			'@n8n/community-nodes/valid-peer-dependencies': 'error',
 			'@n8n/community-nodes/webhook-lifecycle-complete': 'error',
 		},

package/src/rules/index.ts

@@ -14,6 +14,7 @@ import { NoHttpRequestWithManualAuthRule } from './no-http-request-with-manual-a
 import { NoOverridesFieldRule } from './no-overrides-field.js';
 import { NoRestrictedGlobalsRule } from './no-restricted-globals.js';
 import { NoRestrictedImportsRule } from './no-restricted-imports.js';
+import { NoRuntimeDependenciesRule } from './no-runtime-dependencies.js';
 import { NodeClassDescriptionIconMissingRule } from './node-class-description-icon-missing.js';
 import { NodeConnectionTypeLiteralRule } from './node-connection-type-literal.js';
 import { NodeUsableAsToolRule } from './node-usable-as-tool.js';
@@ -24,6 +25,7 @@ import { RequireContinueOnFailRule } from './require-continue-on-fail.js';
 import { RequireNodeApiErrorRule } from './require-node-api-error.js';
 import { RequireNodeDescriptionFieldsRule } from './require-node-description-fields.js';
 import { ResourceOperationPatternRule } from './resource-operation-pattern.js';
+import { ValidCredentialReferencesRule } from './valid-credential-references.js';
 import { ValidPeerDependenciesRule } from './valid-peer-dependencies.js';
 import { WebhookLifecycleCompleteRule } from './webhook-lifecycle-complete.js';
 
@@ -41,6 +43,7 @@ export const rules = {
 	'no-forbidden-lifecycle-scripts': NoForbiddenLifecycleScriptsRule,
 	'no-http-request-with-manual-auth': NoHttpRequestWithManualAuthRule,
 	'no-overrides-field': NoOverridesFieldRule,
+	'no-runtime-dependencies': NoRuntimeDependenciesRule,
 	'icon-validation': IconValidationRule,
 	'resource-operation-pattern': ResourceOperationPatternRule,
 	'credential-documentation-url': CredentialDocumentationUrlRule,
@@ -52,6 +55,7 @@ export const rules = {
 	'require-continue-on-fail': RequireContinueOnFailRule,
 	'require-node-api-error': RequireNodeApiErrorRule,
 	'require-node-description-fields': RequireNodeDescriptionFieldsRule,
+	'valid-credential-references': ValidCredentialReferencesRule,
 	'valid-peer-dependencies': ValidPeerDependenciesRule,
 	'webhook-lifecycle-complete': WebhookLifecycleCompleteRule,
 } satisfies Record<string, AnyRuleModule>;

package/src/rules/no-runtime-dependencies.test.ts

@@ -0,0 +1,50 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { NoRuntimeDependenciesRule } from './no-runtime-dependencies.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('no-runtime-dependencies', NoRuntimeDependenciesRule, {
+	valid: [
+		{
+			name: 'no dependencies field',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+		},
+		{
+			name: 'empty dependencies object is allowed',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "dependencies": {} }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "dependencies": { "axios": "1.0.0" } }',
+		},
+		{
+			name: 'nested "dependencies" key inside another field is allowed',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "config": { "dependencies": { "axios": "1.0.0" } } }',
+		},
+	],
+	invalid: [
+		{
+			name: 'single runtime dependency is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "dependencies": { "axios": "1.0.0" } }',
+			errors: [{ messageId: 'runtimeDependenciesForbidden' }],
+		},
+		{
+			name: 'multiple runtime dependencies are forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "dependencies": { "axios": "1.0.0", "lodash": "^4.0.0" } }',
+			errors: [{ messageId: 'runtimeDependenciesForbidden' }],
+		},
+		{
+			name: 'real-world package with bundled deps is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-sinch", "dependencies": { "axios": "1.7.0", "fast-xml-parser": "4.4.0", "minimatch": "9.0.5" } }',
+			errors: [{ messageId: 'runtimeDependenciesForbidden' }],
+		},
+	],
+});

package/src/rules/no-runtime-dependencies.ts

@@ -0,0 +1,50 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty } from '../utils/index.js';
+
+export const NoRuntimeDependenciesRule = createRule({
+	name: 'no-runtime-dependencies',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow non-empty "dependencies" in community node package.json',
+		},
+		messages: {
+			runtimeDependenciesForbidden:
+				'The "dependencies" field must be empty or absent in community node packages. Runtime dependencies get bundled into the n8n instance and can conflict with other nodes or the n8n runtime itself. Move shared libraries to "peerDependencies" or bundle them into your build artifact.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				if (node.parent?.type !== AST_NODE_TYPES.ExpressionStatement) {
+					return;
+				}
+
+				const depsProp = findJsonProperty(node, 'dependencies');
+				if (!depsProp) {
+					return;
+				}
+
+				if (
+					depsProp.value.type !== AST_NODE_TYPES.ObjectExpression ||
+					depsProp.value.properties.length === 0
+				) {
+					return;
+				}
+
+				context.report({
+					node: depsProp,
+					messageId: 'runtimeDependenciesForbidden',
+				});
+			},
+		};
+	},
+});

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

@@ -0,0 +1,230 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { afterEach, beforeEach, describe, vi } from 'vitest';
+
+import { ValidCredentialReferencesRule } from './valid-credential-references.js';
+import * as fileUtils from '../utils/file-utils.js';
+
+vi.mock('../utils/file-utils.js', async () => {
+	const actual = await vi.importActual('../utils/file-utils.js');
+	return {
+		...actual,
+		readPackageJsonCredentials: vi.fn(),
+		findPackageJson: vi.fn(),
+	};
+});
+
+const mockReadPackageJsonCredentials = vi.mocked(fileUtils.readPackageJsonCredentials);
+const mockFindPackageJson = vi.mocked(fileUtils.findPackageJson);
+
+const ruleTester = new RuleTester();
+
+const nodeFilePath = '/tmp/TestNode.node.ts';
+
+function createNodeCode(
+	credentials: Array<string | { name: string; required?: boolean }> = [],
+): string {
+	const credentialsArray =
+		credentials.length > 0
+			? credentials
+					.map((cred) => {
+						if (typeof cred === 'string') {
+							return `'${cred}'`;
+						} else {
+							const required =
+								cred.required !== undefined ? `,\n\t\t\t\trequired: ${cred.required}` : '';
+							return `{\n\t\t\t\tname: '${cred.name}'${required},\n\t\t\t}`;
+						}
+					})
+					.join(',\n\t\t\t')
+			: '';
+
+	const credentialsProperty =
+		credentials.length > 0 ? `credentials: [\n\t\t\t${credentialsArray}\n\t\t],` : '';
+
+	return `
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description: INodeTypeDescription = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		group: ['output'],
+		version: 1,
+		inputs: ['main'],
+		outputs: ['main'],
+		${credentialsProperty}
+		properties: [],
+	};
+}`;
+}
+
+/** Same as createNodeCode but uses double quotes for the credential name — matches fixer output */
+function createExpectedNodeCode(
+	credentials: Array<string | { name: string; required?: boolean }> = [],
+): string {
+	const credentialsArray =
+		credentials.length > 0
+			? credentials
+					.map((cred) => {
+						if (typeof cred === 'string') {
+							return `"${cred}"`;
+						} else {
+							const required =
+								cred.required !== undefined ? `,\n\t\t\t\trequired: ${cred.required}` : '';
+							return `{\n\t\t\t\tname: "${cred.name}"${required},\n\t\t\t}`;
+						}
+					})
+					.join(',\n\t\t\t')
+			: '';
+
+	const credentialsProperty =
+		credentials.length > 0 ? `credentials: [\n\t\t\t${credentialsArray}\n\t\t],` : '';
+
+	return `
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description: INodeTypeDescription = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		group: ['output'],
+		version: 1,
+		inputs: ['main'],
+		outputs: ['main'],
+		${credentialsProperty}
+		properties: [],
+	};
+}`;
+}
+
+function createNonNodeClass(): string {
+	return `
+export class RegularClass {
+	credentials = [
+		{ name: 'ExternalApi', required: true }
+	];
+}`;
+}
+
+function createNonINodeTypeClass(): string {
+	return `
+export class NotANode {
+	description = {
+		displayName: 'Not A Node',
+		credentials: [
+			{ name: 'ExternalApi', required: true }
+		]
+	};
+}`;
+}
+
+mockFindPackageJson.mockReturnValue('/tmp/package.json');
+mockReadPackageJsonCredentials.mockReturnValue(new Set(['myApiCredential', 'oauthApi']));
+
+ruleTester.run('valid-credential-references', ValidCredentialReferencesRule, {
+	valid: [
+		{
+			name: 'node referencing a credential that exists (object form)',
+			filename: nodeFilePath,
+			code: createNodeCode([{ name: 'myApiCredential', required: true }]),
+		},
+		{
+			name: 'node referencing a credential that exists (string form)',
+			filename: nodeFilePath,
+			code: createNodeCode(['myApiCredential']),
+		},
+		{
+			name: 'node referencing multiple credentials that all exist',
+			filename: nodeFilePath,
+			code: createNodeCode(['myApiCredential', { name: 'oauthApi', required: false }]),
+		},
+		{
+			name: 'node without credentials array',
+			filename: nodeFilePath,
+			code: createNodeCode(),
+		},
+		{
+			name: 'non-node file ignored',
+			filename: '/tmp/regular-file.ts',
+			code: createNonNodeClass(),
+		},
+		{
+			name: 'non-INodeType class ignored',
+			filename: nodeFilePath,
+			code: createNonINodeTypeClass(),
+		},
+	],
+	invalid: [
+		{
+			name: 'credential name does not exist in package (object form)',
+			filename: nodeFilePath,
+			code: createNodeCode([{ name: 'brokenReference', required: true }]),
+			errors: [
+				{
+					messageId: 'credentialNotFound',
+					data: { credentialName: 'brokenReference' },
+				},
+			],
+		},
+		{
+			name: 'credential name does not exist in package (string form)',
+			filename: nodeFilePath,
+			code: createNodeCode(['unknownCredential']),
+			errors: [
+				{
+					messageId: 'credentialNotFound',
+					data: { credentialName: 'unknownCredential' },
+				},
+			],
+		},
+		{
+			name: 'credential name is a typo close to an existing credential — suggestion provided',
+			filename: nodeFilePath,
+			code: createNodeCode([{ name: 'myApiCredentail', required: true }]),
+			errors: [
+				{
+					messageId: 'credentialNotFound',
+					data: { credentialName: 'myApiCredentail' },
+					suggestions: [
+						{
+							messageId: 'didYouMean',
+							data: { suggestedName: 'myApiCredential' },
+							output: createExpectedNodeCode([{ name: 'myApiCredential', required: true }]),
+						},
+					],
+				},
+			],
+		},
+		{
+			name: 'mix of valid and invalid credentials — only invalid reported',
+			filename: nodeFilePath,
+			code: createNodeCode(['myApiCredential', { name: 'brokenRef', required: true }]),
+			errors: [
+				{
+					messageId: 'credentialNotFound',
+					data: { credentialName: 'brokenRef' },
+				},
+			],
+		},
+	],
+});
+
+describe('valid-credential-references — no package.json found', () => {
+	beforeEach(() => {
+		mockFindPackageJson.mockReturnValue(null);
+	});
+	afterEach(() => {
+		mockFindPackageJson.mockReturnValue('/tmp/package.json');
+	});
+
+	ruleTester.run('valid-credential-references (no package.json)', ValidCredentialReferencesRule, {
+		valid: [
+			{
+				name: 'check is skipped when package.json cannot be found',
+				filename: nodeFilePath,
+				code: createNodeCode([{ name: 'anyCredential', required: true }]),
+			},
+		],
+		invalid: [],
+	});
+});

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

@@ -0,0 +1,105 @@
+import { TSESTree } from '@typescript-eslint/types';
+import type { ReportSuggestionArray } from '@typescript-eslint/utils/ts-eslint';
+
+import {
+	isNodeTypeClass,
+	findClassProperty,
+	findArrayLiteralProperty,
+	extractCredentialNameFromArray,
+	findPackageJson,
+	readPackageJsonCredentials,
+	isFileType,
+	findSimilarStrings,
+	createRule,
+} from '../utils/index.js';
+
+export const ValidCredentialReferencesRule = createRule({
+	name: 'valid-credential-references',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Ensure credentials referenced in node descriptions exist as credential classes in the package',
+		},
+		messages: {
+			credentialNotFound:
+				'Credential "{{ credentialName }}" does not exist in this package. Check for typos or ensure the credential class is declared and listed in package.json.',
+			didYouMean: "Did you mean '{{ suggestedName }}'?",
+		},
+		schema: [],
+		hasSuggestions: true,
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!isFileType(context.filename, '.node.ts')) {
+			return {};
+		}
+
+		let packageCredentials: Set<string> | null = null;
+
+		const loadPackageCredentials = (): Set<string> => {
+			if (packageCredentials !== null) {
+				return packageCredentials;
+			}
+
+			const packageJsonPath = findPackageJson(context.filename);
+			if (!packageJsonPath) {
+				packageCredentials = new Set();
+				return packageCredentials;
+			}
+
+			packageCredentials = readPackageJsonCredentials(packageJsonPath);
+			return packageCredentials;
+		};
+
+		return {
+			ClassDeclaration(node) {
+				if (!isNodeTypeClass(node)) {
+					return;
+				}
+
+				const descriptionProperty = findClassProperty(node, 'description');
+				if (
+					!descriptionProperty?.value ||
+					descriptionProperty.value.type !== TSESTree.AST_NODE_TYPES.ObjectExpression
+				) {
+					return;
+				}
+
+				const credentialsArray = findArrayLiteralProperty(descriptionProperty.value, 'credentials');
+				if (!credentialsArray) {
+					return;
+				}
+
+				const knownCredentials = loadPackageCredentials();
+				if (knownCredentials.size === 0) {
+					return;
+				}
+
+				credentialsArray.elements.forEach((element) => {
+					const credentialInfo = extractCredentialNameFromArray(element);
+					if (!credentialInfo || knownCredentials.has(credentialInfo.name)) {
+						return;
+					}
+
+					const similar = findSimilarStrings(credentialInfo.name, knownCredentials);
+					const suggestions: ReportSuggestionArray<'credentialNotFound' | 'didYouMean'> =
+						similar.map((suggestedName) => ({
+							messageId: 'didYouMean' as const,
+							data: { suggestedName },
+							fix(fixer) {
+								return fixer.replaceText(credentialInfo.node, `"${suggestedName}"`);
+							},
+						}));
+
+					context.report({
+						node: credentialInfo.node,
+						messageId: 'credentialNotFound',
+						data: { credentialName: credentialInfo.name },
+						suggest: suggestions,
+					});
+				});
+			},
+		};
+	},
+});

package/src/rules/webhook-lifecycle-complete.test.ts

@@ -107,6 +107,11 @@ export class RegularClass {
 			code: createTriggerNode({ webhookMethods: null }),
 			errors: [{ messageId: 'missingWebhookMethods' }],
 		},
+		{
+			name: 'trigger node with empty webhookMethods object (no lifecycle groups)',
+			code: createTriggerNode({ webhookMethods: '{}' }),
+			errors: [{ messageId: 'emptyWebhookMethods' }],
+		},
 		{
 			name: 'trigger node with empty webhookMethods group (all three missing)',
 			code: createTriggerNode({

package/src/rules/webhook-lifecycle-complete.ts

@@ -56,6 +56,8 @@ export const WebhookLifecycleCompleteRule = createRule({
 		messages: {
 			missingWebhookMethods:
 				'Webhook trigger node is missing the `webhookMethods` property. Implement `checkExists`, `create`, and `delete` to register, verify, and clean up the webhook on the third-party service.',
+			emptyWebhookMethods:
+				'Webhook trigger node has an empty `webhookMethods` object. Define at least one lifecycle group with `checkExists`, `create`, and `delete` methods.',
 			missingLifecycleMethod:
 				'Webhook trigger lifecycle is incomplete. `webhookMethods.{{group}}` is missing: {{missing}}. All of `checkExists`, `create`, and `delete` must be implemented.',
 		},
@@ -91,6 +93,14 @@ export const WebhookLifecycleCompleteRule = createRule({
 					return;
 				}
 
+				if (webhookMethodsProperty.value.properties.length === 0) {
+					context.report({
+						node: webhookMethodsProperty.key,
+						messageId: 'emptyWebhookMethods',
+					});
+					return;
+				}
+
 				for (const groupProperty of webhookMethodsProperty.value.properties) {
 					if (groupProperty.type !== AST_NODE_TYPES.Property) continue;
 					if (groupProperty.value.type !== AST_NODE_TYPES.ObjectExpression) continue;