@n8n/eslint-plugin-community-nodes 0.2.0

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

@@ -0,0 +1,86 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+import { getModulePath, isDirectRequireCall, isRequireMemberCall } from '../utils/index.js';
+
+const allowedModules = [
+	'n8n-workflow',
+	'lodash',
+	'moment',
+	'p-limit',
+	'luxon',
+	'zod',
+	'crypto',
+	'node:crypto',
+];
+
+const isModuleAllowed = (modulePath: string): boolean => {
+	if (modulePath.startsWith('./') || modulePath.startsWith('../')) return true;
+
+	const moduleName = modulePath.startsWith('@')
+		? modulePath.split('/').slice(0, 2).join('/')
+		: modulePath.split('/')[0];
+	if (!moduleName) return true;
+	return allowedModules.includes(moduleName);
+};
+
+export const NoRestrictedImportsRule = ESLintUtils.RuleCreator.withoutDocs({
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow usage of restricted imports in community nodes.',
+		},
+		messages: {
+			restrictedImport:
+				"Import of '{{ modulePath }}' is not allowed. n8n Cloud does not allow community nodes with dependencies.",
+			restrictedRequire:
+				"Require of '{{ modulePath }}' is not allowed. n8n Cloud does not allow community nodes with dependencies.",
+			restrictedDynamicImport:
+				"Dynamic import of '{{ modulePath }}' is not allowed. n8n Cloud does not allow community nodes with dependencies.",
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		return {
+			ImportDeclaration(node) {
+				const modulePath = getModulePath(node.source);
+				if (modulePath && !isModuleAllowed(modulePath)) {
+					context.report({
+						node,
+						messageId: 'restrictedImport',
+						data: {
+							modulePath,
+						},
+					});
+				}
+			},
+
+			ImportExpression(node) {
+				const modulePath = getModulePath(node.source);
+				if (modulePath && !isModuleAllowed(modulePath)) {
+					context.report({
+						node,
+						messageId: 'restrictedDynamicImport',
+						data: {
+							modulePath,
+						},
+					});
+				}
+			},
+
+			CallExpression(node) {
+				if (isDirectRequireCall(node) || isRequireMemberCall(node)) {
+					const modulePath = getModulePath(node.arguments[0] ?? null);
+					if (modulePath && !isModuleAllowed(modulePath)) {
+						context.report({
+							node,
+							messageId: 'restrictedRequire',
+							data: {
+								modulePath,
+							},
+						});
+					}
+				}
+			},
+		};
+	},
+});

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

@@ -0,0 +1,80 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { NodeUsableAsToolRule } from './node-usable-as-tool.js';
+
+const ruleTester = new RuleTester();
+
+function createNodeCode(
+	usableAsTool?: boolean | 'missing',
+	hasDescription: boolean = true,
+): string {
+	let usableAsToolProperty = '';
+	if (usableAsTool === true) {
+		usableAsToolProperty = ',\n\t\tusableAsTool: true';
+	} else if (usableAsTool === false) {
+		usableAsToolProperty = ',\n\t\tusableAsTool: false';
+	}
+
+	if (!hasDescription) {
+		return `
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	displayName = 'Test Node';
+}`;
+	}
+
+	return `
+import type { INodeType, INodeTypeDescription } 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: ['main'],
+		outputs: ['main'],
+		properties: []${usableAsToolProperty},
+	};
+}`;
+}
+
+function createNonNodeClass(): string {
+	return `
+export class RegularClass {
+	someProperty = 'value';
+}`;
+}
+
+ruleTester.run('node-usable-as-tool', NodeUsableAsToolRule, {
+	valid: [
+		{
+			name: 'node with usableAsTool set to true',
+			code: createNodeCode(true),
+		},
+		{
+			name: 'class that does not implement INodeType',
+			code: createNonNodeClass(),
+		},
+		{
+			name: 'node with usableAsTool set to false',
+			code: createNodeCode(false),
+		},
+		{
+			name: 'node without description property',
+			code: createNodeCode(undefined, false),
+		},
+	],
+	invalid: [
+		{
+			name: 'node missing usableAsTool property',
+			code: createNodeCode('missing'),
+			errors: [{ messageId: 'missingUsableAsTool' }],
+			output: createNodeCode(true),
+		},
+	],
+});

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

@@ -0,0 +1,70 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+import {
+	isNodeTypeClass,
+	findClassProperty,
+	findObjectProperty,
+	getBooleanLiteralValue,
+} from '../utils/index.js';
+
+export const NodeUsableAsToolRule = ESLintUtils.RuleCreator.withoutDocs({
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Ensure node classes have usableAsTool property',
+		},
+		messages: {
+			missingUsableAsTool:
+				'Node class should have usableAsTool property. When in doubt, set it to true.',
+		},
+		fixable: 'code',
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		return {
+			ClassDeclaration(node) {
+				if (!isNodeTypeClass(node)) {
+					return;
+				}
+
+				const descriptionProperty = findClassProperty(node, 'description');
+				if (!descriptionProperty) {
+					return;
+				}
+
+				const descriptionValue = descriptionProperty.value;
+				if (descriptionValue?.type !== 'ObjectExpression') {
+					return;
+				}
+
+				const usableAsToolProperty = findObjectProperty(descriptionValue, 'usableAsTool');
+
+				if (!usableAsToolProperty) {
+					context.report({
+						node,
+						messageId: 'missingUsableAsTool',
+						fix(fixer) {
+							if (descriptionValue?.type === 'ObjectExpression') {
+								const properties = descriptionValue.properties;
+								if (properties.length === 0) {
+									const openBrace = descriptionValue.range![0] + 1;
+									return fixer.insertTextAfterRange(
+										[openBrace, openBrace],
+										'\n\t\tusableAsTool: true,',
+									);
+								} else {
+									const lastProperty = properties.at(-1);
+									if (lastProperty) {
+										return fixer.insertTextAfter(lastProperty, ',\n\t\tusableAsTool: true');
+									}
+								}
+							}
+
+							return null;
+						},
+					});
+				}
+			},
+		};
+	},
+});

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

@@ -0,0 +1,112 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { PackageNameConventionRule } from './package-name-convention.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('package-name-convention', PackageNameConventionRule, {
+	valid: [
+		{
+			name: 'valid unscoped package name',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+		},
+		{
+			name: 'valid unscoped package name with dashes',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-my-service", "version": "1.0.0" }',
+		},
+		{
+			name: 'valid scoped package name',
+			filename: 'package.json',
+			code: '{ "name": "@mycompany/n8n-nodes-example", "version": "1.0.0" }',
+		},
+		{
+			name: 'valid scoped package name with dashes',
+			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',
+			code: '{ "name": "my-config", "type": "config" }',
+		},
+		{
+			name: 'nested name fields should be ignored - only top-level name matters',
+			filename: 'package.json',
+			code: `{
+				"name": "n8n-nodes-example",
+				"version": "1.0.0",
+				"dependencies": {
+					"name": "invalid-nested-name"
+				},
+				"scripts": {
+					"name": "another-invalid-name"
+				},
+				"author": {
+					"name": "John Doe"
+				}
+			}`,
+		},
+		{
+			name: 'deeply nested name fields should be ignored',
+			filename: 'package.json',
+			code: `{
+				"name": "@author/n8n-nodes-service",
+				"version": "1.0.0",
+				"config": {
+					"nested": {
+						"deeply": {
+							"name": "very-invalid-name"
+						}
+					}
+				},
+				"repository": {
+					"type": "git",
+					"url": "https://github.com/user/repo",
+					"directory": {
+						"name": "bad-name"
+					}
+				}
+			}`,
+		},
+	],
+	invalid: [
+		{
+			name: 'invalid package name - generic',
+			filename: 'package.json',
+			code: '{ "name": "my-package", "version": "1.0.0" }',
+			errors: [{ messageId: 'invalidPackageName', data: { packageName: 'my-package' } }],
+		},
+		{
+			name: 'invalid package name - missing nodes',
+			filename: 'package.json',
+			code: '{ "name": "n8n-example", "version": "1.0.0" }',
+			errors: [{ messageId: 'invalidPackageName', data: { packageName: 'n8n-example' } }],
+		},
+		{
+			name: 'invalid scoped package name',
+			filename: 'package.json',
+			code: '{ "name": "@company/example-nodes", "version": "1.0.0" }',
+			errors: [
+				{ messageId: 'invalidPackageName', data: { packageName: '@company/example-nodes' } },
+			],
+		},
+		{
+			name: 'invalid package name - wrong order',
+			filename: 'package.json',
+			code: '{ "name": "nodes-n8n-example", "version": "1.0.0" }',
+			errors: [{ messageId: 'invalidPackageName', data: { packageName: 'nodes-n8n-example' } }],
+		},
+		{
+			name: 'empty package name',
+			filename: 'package.json',
+			code: '{ "name": "", "version": "1.0.0" }',
+			errors: [{ messageId: 'invalidPackageName', data: { packageName: '' } }],
+		},
+	],
+});

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

@@ -0,0 +1,63 @@
+import { ESLintUtils, TSESTree, AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+export const PackageNameConventionRule = ESLintUtils.RuleCreator.withoutDocs({
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Enforce correct package naming convention for n8n community nodes',
+		},
+		messages: {
+			invalidPackageName:
+				'Package name "{{ packageName }}" must follow the convention "n8n-nodes-[PACKAGE-NAME]" or "@[AUTHOR]/n8n-nodes-[PACKAGE-NAME]"',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				if (node.parent?.type === AST_NODE_TYPES.Property) {
+					return;
+				}
+
+				const nameProperty = node.properties.find(
+					(property) =>
+						property.type === AST_NODE_TYPES.Property &&
+						property.key.type === AST_NODE_TYPES.Literal &&
+						property.key.value === 'name',
+				);
+
+				if (!nameProperty || nameProperty.type !== AST_NODE_TYPES.Property) {
+					return;
+				}
+
+				if (nameProperty.value.type !== AST_NODE_TYPES.Literal) {
+					return;
+				}
+
+				const packageName = nameProperty.value.value;
+				const packageNameStr = typeof packageName === 'string' ? packageName : null;
+
+				if (!packageNameStr || !isValidPackageName(packageNameStr)) {
+					context.report({
+						node: nameProperty,
+						messageId: 'invalidPackageName',
+						data: {
+							packageName: packageNameStr ?? 'undefined',
+						},
+					});
+				}
+			},
+		};
+	},
+});
+
+function isValidPackageName(name: string): boolean {
+	const unscoped = /^n8n-nodes-.+$/;
+	const scoped = /^@.+\/n8n-nodes-.+$/;
+	return unscoped.test(name) || scoped.test(name);
+}

package/src/rules/resource-operation-pattern.test.ts

@@ -0,0 +1,216 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { ResourceOperationPatternRule } from './resource-operation-pattern.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('resource-operation-pattern', ResourceOperationPatternRule, {
+	valid: [
+		{
+			name: 'node with resources and operations (good pattern)',
+			filename: '/tmp/TestNode.node.ts',
+			code: `
+				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'],
+						properties: [
+							{
+								displayName: 'Resource',
+								name: 'resource',
+								type: 'options',
+								options: [
+									{ name: 'User', value: 'user' },
+									{ name: 'Project', value: 'project' }
+								],
+								default: 'user'
+							},
+							{
+								displayName: 'Operation',
+								name: 'operation',
+								type: 'options',
+								options: [
+									{ name: 'Get', value: 'get' },
+									{ name: 'Create', value: 'create' },
+									{ name: 'Update', value: 'update' },
+									{ name: 'Delete', value: 'delete' }
+								],
+								default: 'get'
+							}
+						]
+					};
+				}
+			`,
+		},
+		{
+			name: 'node without operations property',
+			filename: '/tmp/TestNode.node.ts',
+			code: `
+				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'],
+						properties: [
+							{
+								displayName: 'API Key',
+								name: 'apiKey',
+								type: 'string',
+								default: ''
+							}
+						]
+					};
+				}
+			`,
+		},
+		{
+			name: 'non-node class ignored',
+			filename: '/tmp/TestNode.node.ts',
+			code: `
+				export class NotANode {
+					description = {
+						properties: [
+							{
+								displayName: 'Operation',
+								name: 'operation',
+								type: 'options',
+								options: [
+									{ name: 'Get', value: 'get' },
+									{ name: 'Create', value: 'create' }
+								],
+								default: 'get'
+							}
+						]
+					};
+				}
+			`,
+		},
+		{
+			name: 'node with exactly 5 operations without resources (allowed)',
+			filename: '/tmp/TestNode.node.ts',
+			code: `
+				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'],
+						properties: [
+							{
+								displayName: 'Operation',
+								name: 'operation',
+								type: 'options',
+								options: [
+									{ name: 'Get', value: 'get' },
+									{ name: 'Create', value: 'create' },
+									{ name: 'Update', value: 'update' },
+									{ name: 'Delete', value: 'delete' },
+									{ name: 'List', value: 'list' }
+								],
+								default: 'get'
+							}
+						]
+					};
+				}
+			`,
+		},
+	],
+	invalid: [
+		{
+			name: 'node with exactly 6 operations without resources (error)',
+			filename: '/tmp/TestNode.node.ts',
+			code: `
+				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'],
+						properties: [
+							{
+								displayName: 'Operation',
+								name: 'operation',
+								type: 'options',
+								options: [
+									{ name: 'Get', value: 'get' },
+									{ name: 'Create', value: 'create' },
+									{ name: 'Update', value: 'update' },
+									{ name: 'Delete', value: 'delete' },
+									{ name: 'List', value: 'list' },
+									{ name: 'Search', value: 'search' }
+								],
+								default: 'get'
+							}
+						]
+					};
+				}
+			`,
+			errors: [
+				{
+					messageId: 'tooManyOperationsWithoutResources',
+					data: { operationCount: '6' },
+				},
+			],
+		},
+		{
+			name: 'node with many operations without resources (error)',
+			filename: '/tmp/TestNode.node.ts',
+			code: `
+				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'],
+						properties: [
+							{
+								displayName: 'Operation',
+								name: 'operation',
+								type: 'options',
+								options: [
+									{ name: 'Get User', value: 'getUser' },
+									{ name: 'Create User', value: 'createUser' },
+									{ name: 'Update User', value: 'updateUser' },
+									{ name: 'Delete User', value: 'deleteUser' },
+									{ name: 'List Users', value: 'listUsers' },
+									{ name: 'Get Project', value: 'getProject' },
+									{ name: 'Create Project', value: 'createProject' },
+									{ name: 'Update Project', value: 'updateProject' }
+								],
+								default: 'getUser'
+							}
+						]
+					};
+				}
+			`,
+			errors: [
+				{
+					messageId: 'tooManyOperationsWithoutResources',
+					data: { operationCount: '8' },
+				},
+			],
+		},
+	],
+});