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

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

@@ -0,0 +1,82 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireCommunityNodeKeywordRule } from './require-community-node-keyword.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('require-community-node-keyword', RequireCommunityNodeKeywordRule, {
+	valid: [
+		{
+			name: 'keywords array contains required keyword',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": ["n8n-community-node-package"] }',
+		},
+		{
+			name: 'keywords array contains required keyword among others',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": ["n8n", "automation", "n8n-community-node-package", "workflow"] }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "name": "n8n-nodes-example" }',
+		},
+		{
+			name: 'nested objects are not checked',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": ["n8n-community-node-package"], "config": { "nested": "value" } }',
+		},
+		{
+			name: 'objects inside arrays (e.g. contributors) are not flagged',
+			filename: 'package.json',
+			code: `{
+				"name": "n8n-nodes-example",
+				"keywords": ["n8n-community-node-package"],
+				"contributors": [
+					{ "name": "Alice", "email": "alice@example.com" },
+					{ "name": "Bob", "email": "bob@example.com" }
+				]
+			}`,
+		},
+	],
+	invalid: [
+		{
+			name: 'missing keywords array entirely',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+			output:
+				'{ "name": "n8n-nodes-example", "version": "1.0.0", "keywords": ["n8n-community-node-package"] }',
+			errors: [{ messageId: 'missingKeywordsArray' }],
+		},
+		{
+			name: 'empty keywords array',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": [] }',
+			output: '{ "name": "n8n-nodes-example", "keywords": ["n8n-community-node-package"] }',
+			errors: [{ messageId: 'missingKeyword' }],
+		},
+		{
+			name: 'keywords array without the required keyword',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": ["n8n", "automation"] }',
+			output:
+				'{ "name": "n8n-nodes-example", "keywords": ["n8n", "automation", "n8n-community-node-package"] }',
+			errors: [{ messageId: 'missingKeyword' }],
+		},
+		{
+			name: 'keywords array with similar but incorrect keyword',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "keywords": ["n8n-community-node"] }',
+			output:
+				'{ "name": "n8n-nodes-example", "keywords": ["n8n-community-node", "n8n-community-node-package"] }',
+			errors: [{ messageId: 'missingKeyword' }],
+		},
+		{
+			name: 'empty package.json object',
+			filename: 'package.json',
+			code: '{}',
+			output: '{ "keywords": ["n8n-community-node-package"] }',
+			errors: [{ messageId: 'missingKeywordsArray' }],
+		},
+	],
+});

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-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(', ') },
+					});
+				}
+			},
+		};
+	},
+});