@n8n/eslint-plugin-community-nodes 0.11.0 → 0.13.0

package/src/rules/require-community-node-keyword.ts

@@ -0,0 +1,78 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty } from '../utils/index.js';
+
+const REQUIRED_KEYWORD = 'n8n-community-node-package';
+
+export const RequireCommunityNodeKeywordRule = createRule({
+	name: 'require-community-node-keyword',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Require the "n8n-community-node-package" keyword in community node package.json',
+		},
+		fixable: 'code',
+		messages: {
+			missingKeyword: `The "keywords" array must include "${REQUIRED_KEYWORD}". This keyword is required for n8n to discover community node packages.`,
+			missingKeywordsArray: `The package.json must have a "keywords" array containing "${REQUIRED_KEYWORD}".`,
+		},
+		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 keywordsProp = findJsonProperty(node, 'keywords');
+
+				if (!keywordsProp) {
+					context.report({
+						node,
+						messageId: 'missingKeywordsArray',
+						fix(fixer) {
+							const lastProp = node.properties[node.properties.length - 1];
+							if (!lastProp) {
+								return fixer.replaceText(node, `{ "keywords": ["${REQUIRED_KEYWORD}"] }`);
+							}
+							return fixer.insertTextAfter(lastProp, `, "keywords": ["${REQUIRED_KEYWORD}"]`);
+						},
+					});
+					return;
+				}
+
+				if (keywordsProp.value.type !== AST_NODE_TYPES.ArrayExpression) {
+					return;
+				}
+
+				const keywordsArray = keywordsProp.value;
+				const hasRequiredKeyword = keywordsArray.elements.some(
+					(element) =>
+						element?.type === AST_NODE_TYPES.Literal && element.value === REQUIRED_KEYWORD,
+				);
+
+				if (!hasRequiredKeyword) {
+					context.report({
+						node: keywordsProp,
+						messageId: 'missingKeyword',
+						fix(fixer) {
+							const lastElement = keywordsArray.elements[keywordsArray.elements.length - 1];
+							if (!lastElement) {
+								return fixer.replaceText(keywordsArray, `["${REQUIRED_KEYWORD}"]`);
+							}
+							return fixer.insertTextAfter(lastElement, `, "${REQUIRED_KEYWORD}"`);
+						},
+					});
+				}
+			},
+		};
+	},
+});

package/src/rules/require-continue-on-fail.test.ts

@@ -0,0 +1,129 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireContinueOnFailRule } from './require-continue-on-fail.js';
+
+const ruleTester = new RuleTester();
+
+function createNodeWithExecute(executeBody: string): string {
+	return `
+import type { INodeType, INodeTypeDescription, IExecuteFunctions, INodeExecutionData } 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: [],
+	};
+
+	async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
+		${executeBody}
+	}
+}`;
+}
+
+ruleTester.run('require-continue-on-fail', RequireContinueOnFailRule, {
+	valid: [
+		{
+			name: 'node with continueOnFail in catch block',
+			code: createNodeWithExecute(`
+				const items = this.getInputData();
+				const returnData: INodeExecutionData[] = [];
+				for (let i = 0; i < items.length; i++) {
+					try {
+						returnData.push({ json: { result: true } });
+					} catch (error) {
+						if (this.continueOnFail()) {
+							returnData.push({ json: { error: error.message } });
+							continue;
+						}
+						throw error;
+					}
+				}
+				return [returnData];
+			`),
+		},
+		{
+			name: 'non-node class with execute method (should be ignored)',
+			code: `
+export class RegularClass {
+	async execute() {
+		return [[]];
+	}
+}`,
+		},
+		{
+			name: 'node class without execute method (should be ignored)',
+			code: `
+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: [],
+	};
+}`,
+		},
+		{
+			name: 'node extending Node base class with continueOnFail',
+			code: `
+import { Node } from 'n8n-workflow';
+
+export class TestNode extends Node {
+	async execute() {
+		try {
+			// do work
+		} catch (error) {
+			if (this.continueOnFail()) {
+				return [[]];
+			}
+			throw error;
+		}
+		return [[]];
+	}
+}`,
+		},
+	],
+	invalid: [
+		{
+			name: 'node with execute but no continueOnFail',
+			code: createNodeWithExecute(`
+				const items = this.getInputData();
+				const returnData: INodeExecutionData[] = [];
+				for (let i = 0; i < items.length; i++) {
+					returnData.push({ json: { result: true } });
+				}
+				return [returnData];
+			`),
+			errors: [{ messageId: 'missingContinueOnFail' }],
+		},
+		{
+			name: 'node with try/catch but no continueOnFail check',
+			code: createNodeWithExecute(`
+				const items = this.getInputData();
+				const returnData: INodeExecutionData[] = [];
+				for (let i = 0; i < items.length; i++) {
+					try {
+						returnData.push({ json: { result: true } });
+					} catch (error) {
+						throw error;
+					}
+				}
+				return [returnData];
+			`),
+			errors: [{ messageId: 'missingContinueOnFail' }],
+		},
+	],
+});

package/src/rules/require-continue-on-fail.ts

@@ -0,0 +1,88 @@
+import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+
+import { isNodeTypeClass } from '../utils/index.js';
+import { createRule } from '../utils/rule-creator.js';
+
+/** Keys that are not child AST nodes (back-references, metadata). */
+const NON_CHILD_KEYS = new Set(['parent', 'loc', 'range', 'start', 'end', 'tokens', 'comments']);
+
+/**
+ * Recursively checks whether any descendant of the given AST node is a
+ * `this.continueOnFail()` call expression.
+ */
+function containsContinueOnFailCall(node: TSESTree.Node): boolean {
+	if (
+		node.type === AST_NODE_TYPES.CallExpression &&
+		node.callee.type === AST_NODE_TYPES.MemberExpression &&
+		node.callee.object.type === AST_NODE_TYPES.ThisExpression &&
+		node.callee.property.type === AST_NODE_TYPES.Identifier &&
+		node.callee.property.name === 'continueOnFail'
+	) {
+		return true;
+	}
+
+	for (const key of Object.keys(node)) {
+		if (NON_CHILD_KEYS.has(key)) continue;
+
+		const value = (node as unknown as Record<string, unknown>)[key];
+
+		if (Array.isArray(value)) {
+			for (const child of value) {
+				if (child && typeof child === 'object' && 'type' in child) {
+					if (containsContinueOnFailCall(child as TSESTree.Node)) {
+						return true;
+					}
+				}
+			}
+		} else if (value && typeof value === 'object' && 'type' in value) {
+			if (containsContinueOnFailCall(value as TSESTree.Node)) {
+				return true;
+			}
+		}
+	}
+
+	return false;
+}
+
+export const RequireContinueOnFailRule = createRule({
+	name: 'require-continue-on-fail',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require continueOnFail() handling in execute() methods of node classes',
+		},
+		messages: {
+			missingContinueOnFail:
+				'execute() method must handle this.continueOnFail() for proper error handling. ' +
+				'Wrap item processing in a try/catch and check this.continueOnFail() in the catch block.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		return {
+			ClassDeclaration(node) {
+				if (!isNodeTypeClass(node)) {
+					return;
+				}
+
+				for (const member of node.body.body) {
+					if (
+						member.type !== AST_NODE_TYPES.MethodDefinition ||
+						member.key.type !== AST_NODE_TYPES.Identifier ||
+						member.key.name !== 'execute'
+					) {
+						continue;
+					}
+
+					if (member.value.body && !containsContinueOnFailCall(member.value.body)) {
+						context.report({
+							node: member.key,
+							messageId: 'missingContinueOnFail',
+						});
+					}
+				}
+			},
+		};
+	},
+});

package/src/rules/require-node-description-fields.test.ts

@@ -0,0 +1,171 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireNodeDescriptionFieldsRule } from './require-node-description-fields.js';
+
+const ruleTester = new RuleTester();
+
+const nodeFilePath = '/tmp/TestNode.node.ts';
+const nonNodeFilePath = '/tmp/SomeHelper.ts';
+
+function createFullNode(): string {
+	return `
+import type { INodeType } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		icon: 'file:testNode.svg',
+		group: ['transform'],
+		version: 1,
+		description: 'Test node description',
+		subtitle: '={{$parameter["operation"]}}',
+		inputs: ['main'],
+		outputs: ['main'],
+		properties: [],
+	};
+}`;
+}
+
+function createNodeMissingSubtitle(): string {
+	return `
+import type { INodeType } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		icon: 'file:testNode.svg',
+		group: ['transform'],
+		version: 1,
+		description: 'Test node description',
+		inputs: ['main'],
+		outputs: ['main'],
+		properties: [],
+	};
+}`;
+}
+
+function createNodeMissingIconAndSubtitle(): string {
+	return `
+import type { INodeType } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		group: ['transform'],
+		version: 1,
+		description: 'Test node description',
+		inputs: ['main'],
+		outputs: ['main'],
+		properties: [],
+	};
+}`;
+}
+
+function createNodeExtendsBase(): string {
+	return `
+export class TestNode extends Node {
+	description = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		icon: 'file:testNode.svg',
+		group: ['transform'],
+		version: 1,
+		description: 'Test node description',
+		subtitle: '={{$parameter["operation"]}}',
+		inputs: ['main'],
+		outputs: ['main'],
+		properties: [],
+	};
+}`;
+}
+
+function createNodeExtendsBaseMissingSubtitle(): string {
+	return `
+export class TestNode extends Node {
+	description = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		icon: 'file:testNode.svg',
+		group: ['transform'],
+		version: 1,
+		description: 'Test node description',
+		inputs: ['main'],
+		outputs: ['main'],
+		properties: [],
+	};
+}`;
+}
+
+function createNodeWithOnlyIconAndSubtitle(): string {
+	return `
+import type { INodeType } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description = {
+		icon: 'file:testNode.svg',
+		subtitle: '={{$parameter["operation"]}}',
+	};
+}`;
+}
+
+function createRegularClass(): string {
+	return `
+export class RegularClass {
+	description = {
+		displayName: 'Test',
+	};
+}`;
+}
+
+ruleTester.run('require-node-description-fields', RequireNodeDescriptionFieldsRule, {
+	valid: [
+		{
+			name: 'node with all required fields',
+			filename: nodeFilePath,
+			code: createFullNode(),
+		},
+		{
+			name: 'class extending Node with all required fields',
+			filename: nodeFilePath,
+			code: createNodeExtendsBase(),
+		},
+		{
+			name: 'node with only icon and subtitle passes (other fields enforced by tsc)',
+			filename: nodeFilePath,
+			code: createNodeWithOnlyIconAndSubtitle(),
+		},
+		{
+			name: 'class not implementing INodeType is ignored',
+			filename: nodeFilePath,
+			code: createRegularClass(),
+		},
+		{
+			name: 'non-.node.ts file is ignored',
+			filename: nonNodeFilePath,
+			code: createNodeMissingSubtitle(),
+		},
+	],
+	invalid: [
+		{
+			name: 'node missing subtitle',
+			filename: nodeFilePath,
+			code: createNodeMissingSubtitle(),
+			errors: [{ messageId: 'missingField', data: { field: 'subtitle' } }],
+		},
+		{
+			name: 'node missing icon and subtitle',
+			filename: nodeFilePath,
+			code: createNodeMissingIconAndSubtitle(),
+			errors: [{ messageId: 'missingFields', data: { fields: '`icon`, `subtitle`' } }],
+		},
+		{
+			name: 'class extending Node missing subtitle',
+			filename: nodeFilePath,
+			code: createNodeExtendsBaseMissingSubtitle(),
+			errors: [{ messageId: 'missingField', data: { field: 'subtitle' } }],
+		},
+	],
+});

package/src/rules/require-node-description-fields.ts

@@ -0,0 +1,77 @@
+import { TSESTree } from '@typescript-eslint/utils';
+
+import {
+	isNodeTypeClass,
+	findClassProperty,
+	findObjectProperty,
+	isFileType,
+	createRule,
+} from '../utils/index.js';
+
+// Fields that are optional in the TypeScript interface but required by
+// community node review standards. TypeScript-required fields (displayName,
+// name, group, version, description, etc.) are already caught by tsc.
+const REQUIRED_FIELDS = ['icon', 'subtitle'] as const;
+
+type RequiredField = (typeof REQUIRED_FIELDS)[number];
+
+export const RequireNodeDescriptionFieldsRule = createRule({
+	name: 'require-node-description-fields',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: `Node class description must define all required fields: ${REQUIRED_FIELDS.join(', ')}`,
+		},
+		messages: {
+			missingField: 'Node class description is missing required `{{field}}` property',
+			missingFields: 'Node class description is missing required properties: {{fields}}',
+		},
+		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 ||
+					descriptionProperty.value.type !== TSESTree.AST_NODE_TYPES.ObjectExpression
+				) {
+					return;
+				}
+
+				const descriptionValue = descriptionProperty.value;
+
+				const missingFields: RequiredField[] = REQUIRED_FIELDS.filter(
+					(field) => !findObjectProperty(descriptionValue, field),
+				);
+
+				if (missingFields.length === 0) {
+					return;
+				}
+
+				if (missingFields.length === 1) {
+					context.report({
+						node: descriptionProperty,
+						messageId: 'missingField',
+						data: { field: missingFields[0] },
+					});
+				} else {
+					context.report({
+						node: descriptionProperty,
+						messageId: 'missingFields',
+						data: { fields: missingFields.map((f) => `\`${f}\``).join(', ') },
+					});
+				}
+			},
+		};
+	},
+});