@n8n/eslint-plugin-community-nodes 0.21.0 → 0.23.0

package/src/rules/node-class-description-name-camelcase.ts

@@ -0,0 +1,114 @@
+import { TSESTree } from '@typescript-eslint/utils';
+
+import {
+	isNodeTypeClass,
+	findClassProperty,
+	findObjectProperty,
+	getStringLiteralValue,
+	isFileType,
+	createRule,
+} from '../utils/index.js';
+
+// `description.name` must be camelCase: a lowercase letter followed by
+// letters/digits, with no separators.
+const CAMEL_CASE_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
+
+/**
+ * Converts an arbitrary node name to camelCase by splitting on any
+ * non-alphanumeric separators, upper-casing the first character of each
+ * subsequent segment, and lower-casing the very first character.
+ * Examples: `My Node` -> `myNode`, `my-node` -> `myNode`, `GitHub` -> `gitHub`.
+ */
+function toCamelCase(value: string): string {
+	const segments = value.split(/[^a-zA-Z0-9]+/).filter(Boolean);
+	if (segments.length === 0) {
+		return value;
+	}
+
+	const joined = segments
+		.map((segment, index) =>
+			index === 0 ? segment : segment.charAt(0).toUpperCase() + segment.slice(1),
+		)
+		.join('');
+
+	return joined.charAt(0).toLowerCase() + joined.slice(1);
+}
+
+// Serialize a value as a string literal using the original quote character,
+// escaping any characters that would otherwise break the literal so the
+// autofix never emits invalid code.
+function toStringLiteral(value: string, quote: string): string {
+	const escaped = value
+		.replace(/\\/g, '\\\\')
+		.replace(/\n/g, '\\n')
+		.replace(/\r/g, '\\r')
+		.split(quote)
+		.join(`\\${quote}`);
+	return `${quote}${escaped}${quote}`;
+}
+
+export const NodeClassDescriptionNameCamelCaseRule = createRule({
+	name: 'node-class-description-name-camelcase',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Node class `description.name` must be camelCase',
+		},
+		messages: {
+			notCamelCase: "Node `description.name` '{{value}}' must be camelCase",
+		},
+		fixable: 'code',
+		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?.type !== TSESTree.AST_NODE_TYPES.ObjectExpression) {
+					return;
+				}
+
+				const nameProperty = findObjectProperty(descriptionProperty.value, 'name');
+				if (!nameProperty) {
+					return;
+				}
+
+				const nameValue = getStringLiteralValue(nameProperty.value);
+				if (nameValue === null) {
+					return;
+				}
+
+				if (CAMEL_CASE_PATTERN.test(nameValue)) {
+					return;
+				}
+
+				const valueNode = nameProperty.value;
+				const fixedValue = toCamelCase(nameValue);
+				// Only offer an autofix when it actually yields a valid camelCase
+				// value (e.g. names starting with a digit cannot be repaired).
+				const canFix = fixedValue !== nameValue && CAMEL_CASE_PATTERN.test(fixedValue);
+
+				context.report({
+					node: valueNode,
+					messageId: 'notCamelCase',
+					data: { value: nameValue },
+					fix: canFix
+						? (fixer) => {
+								const quote = context.sourceCode.getText(valueNode).charAt(0);
+								return fixer.replaceText(valueNode, toStringLiteral(fixedValue, quote));
+							}
+						: undefined,
+				});
+			},
+		};
+	},
+});

package/src/rules/require-mit-license.test.ts

@@ -0,0 +1,67 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireMitLicenseRule } from './require-mit-license.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('require-mit-license', RequireMitLicenseRule, {
+	valid: [
+		{
+			name: 'license is MIT',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "license": "MIT" }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "name": "n8n-nodes-example", "license": "Apache-2.0" }',
+		},
+		{
+			name: 'nested objects are not checked',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "license": "MIT", "config": { "license": "Apache-2.0" } }',
+		},
+		{
+			name: 'objects inside arrays are not flagged',
+			filename: 'package.json',
+			code: `{
+				"name": "n8n-nodes-example",
+				"license": "MIT",
+				"contributors": [
+					{ "name": "Alice" },
+					{ "name": "Bob" }
+				]
+			}`,
+		},
+	],
+	invalid: [
+		{
+			name: 'missing license field',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+			output: '{ "name": "n8n-nodes-example", "version": "1.0.0", "license": "MIT" }',
+			errors: [{ messageId: 'missingLicense' }],
+		},
+		{
+			name: 'empty package.json object',
+			filename: 'package.json',
+			code: '{}',
+			output: '{ "license": "MIT" }',
+			errors: [{ messageId: 'missingLicense' }],
+		},
+		{
+			name: 'wrong license value',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "license": "Apache-2.0" }',
+			output: '{ "name": "n8n-nodes-example", "license": "MIT" }',
+			errors: [{ messageId: 'wrongLicense' }],
+		},
+		{
+			name: 'case-mismatched license value',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "license": "mit" }',
+			output: '{ "name": "n8n-nodes-example", "license": "MIT" }',
+			errors: [{ messageId: 'wrongLicense' }],
+		},
+	],
+});

package/src/rules/require-mit-license.ts

@@ -0,0 +1,65 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty, getStringLiteralValue } from '../utils/index.js';
+
+const REQUIRED_LICENSE = 'MIT';
+
+export const RequireMitLicenseRule = createRule({
+	name: 'require-mit-license',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require the "license" field in community node package.json to be "MIT"',
+		},
+		fixable: 'code',
+		messages: {
+			missingLicense: `The package.json must have a "license" field set to "${REQUIRED_LICENSE}".`,
+			wrongLicense: `The "license" field must be "${REQUIRED_LICENSE}".`,
+		},
+		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 licenseProp = findJsonProperty(node, 'license');
+
+				if (!licenseProp) {
+					context.report({
+						node,
+						messageId: 'missingLicense',
+						fix(fixer) {
+							const lastProp = node.properties[node.properties.length - 1];
+							if (!lastProp) {
+								return fixer.replaceText(node, `{ "license": "${REQUIRED_LICENSE}" }`);
+							}
+							return fixer.insertTextAfter(lastProp, `, "license": "${REQUIRED_LICENSE}"`);
+						},
+					});
+					return;
+				}
+
+				if (getStringLiteralValue(licenseProp.value) === REQUIRED_LICENSE) {
+					return;
+				}
+
+				context.report({
+					node: licenseProp.value,
+					messageId: 'wrongLicense',
+					fix(fixer) {
+						return fixer.replaceText(licenseProp.value, `"${REQUIRED_LICENSE}"`);
+					},
+				});
+			},
+		};
+	},
+});

package/src/rules/require-param-default.test.ts

@@ -0,0 +1,227 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireParamDefaultRule } from './require-param-default.js';
+
+const ruleTester = new RuleTester();
+
+function createNodeCode(properties: string): string {
+	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: [],
+				outputs: [],
+				properties: [
+					${properties}
+				],
+			};
+		}
+	`;
+}
+
+ruleTester.run('require-param-default', RequireParamDefaultRule, {
+	valid: [
+		{
+			name: 'class that does not implement INodeType',
+			filename: '/tmp/TestNode.node.ts',
+			code: `
+				export class NotANode {
+					description = {
+						properties: [{ displayName: 'Field', name: 'field', type: 'string' }],
+					};
+				}
+			`,
+		},
+		{
+			name: 'param-shaped object outside description (e.g. in a method) is ignored',
+			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',
+						properties: [],
+					};
+
+					methods = {
+						loadOptions: {
+							async getThings() {
+								const config = { displayName: 'X', name: 'x', type: 'string' };
+								return [config];
+							},
+						},
+					};
+				}
+			`,
+		},
+		{
+			name: 'non .node.ts file is ignored',
+			filename: '/tmp/helper.ts',
+			code: `
+				export class TestNode {
+					description = {
+						properties: [{ displayName: 'Field', name: 'field', type: 'string' }],
+					};
+				}
+			`,
+		},
+		{
+			name: 'string parameter with default',
+			filename: '/tmp/TestNode.node.ts',
+			code: createNodeCode(`
+				{
+					displayName: 'Field',
+					name: 'field',
+					type: 'string',
+					default: '',
+				},
+			`),
+		},
+		{
+			name: 'options parameter with default',
+			filename: '/tmp/TestNode.node.ts',
+			code: createNodeCode(`
+				{
+					displayName: 'Operation',
+					name: 'operation',
+					type: 'options',
+					options: [{ name: 'Create', value: 'create' }],
+					default: 'create',
+				},
+			`),
+		},
+		{
+			name: 'notice parameter with empty default',
+			filename: '/tmp/TestNode.node.ts',
+			code: createNodeCode(`
+				{
+					displayName: 'Some notice',
+					name: 'notice',
+					type: 'notice',
+					default: '',
+				},
+			`),
+		},
+		{
+			name: 'options-array entries (name/value, no displayName) are not parameters',
+			filename: '/tmp/TestNode.node.ts',
+			code: createNodeCode(`
+				{
+					displayName: 'Operation',
+					name: 'operation',
+					type: 'options',
+					options: [{ name: 'Create', value: 'create', type: 'whatever' }],
+					default: 'create',
+				},
+			`),
+		},
+		{
+			name: 'object with name and type but no displayName is not a parameter',
+			filename: '/tmp/TestNode.node.ts',
+			code: createNodeCode(`
+				{
+					displayName: 'Routing',
+					name: 'routing',
+					type: 'string',
+					default: '',
+					routing: { request: { method: 'GET', name: 'x', type: 'y' } },
+				},
+			`),
+		},
+		{
+			name: 'nested collection options all have defaults',
+			filename: '/tmp/TestNode.node.ts',
+			code: createNodeCode(`
+				{
+					displayName: 'Additional Fields',
+					name: 'additionalFields',
+					type: 'collection',
+					default: {},
+					options: [
+						{
+							displayName: 'Limit',
+							name: 'limit',
+							type: 'number',
+							default: 50,
+						},
+					],
+				},
+			`),
+		},
+	],
+	invalid: [
+		{
+			name: 'string parameter missing default',
+			filename: '/tmp/TestNode.node.ts',
+			code: createNodeCode(`
+				{
+					displayName: 'Field',
+					name: 'field',
+					type: 'string',
+				},
+			`),
+			errors: [{ messageId: 'missingDefault', data: { name: 'field' } }],
+		},
+		{
+			name: 'notice parameter missing default',
+			filename: '/tmp/TestNode.node.ts',
+			code: createNodeCode(`
+				{
+					displayName: 'Some notice',
+					name: 'notice',
+					type: 'notice',
+				},
+			`),
+			errors: [{ messageId: 'missingDefault', data: { name: 'notice' } }],
+		},
+		{
+			name: 'nested collection option missing default',
+			filename: '/tmp/TestNode.node.ts',
+			code: createNodeCode(`
+				{
+					displayName: 'Additional Fields',
+					name: 'additionalFields',
+					type: 'collection',
+					default: {},
+					options: [
+						{
+							displayName: 'Limit',
+							name: 'limit',
+							type: 'number',
+						},
+					],
+				},
+			`),
+			errors: [{ messageId: 'missingDefault', data: { name: 'limit' } }],
+		},
+		{
+			name: 'multiple parameters missing defaults',
+			filename: '/tmp/TestNode.node.ts',
+			code: createNodeCode(`
+				{
+					displayName: 'First',
+					name: 'first',
+					type: 'string',
+				},
+				{
+					displayName: 'Second',
+					name: 'second',
+					type: 'boolean',
+				},
+			`),
+			errors: [
+				{ messageId: 'missingDefault', data: { name: 'first' } },
+				{ messageId: 'missingDefault', data: { name: 'second' } },
+			],
+		},
+	],
+});

package/src/rules/require-param-default.ts

@@ -0,0 +1,89 @@
+/**
+ * Requires every node parameter to declare a `default` property.
+ *
+ * A parameter is detected structurally: an object literal inside a node's
+ * `description` with `displayName`, `name`, and `type` all set to string
+ * literals — the shape every `INodeProperties` entry has. This avoids
+ * hardcoding the `NodePropertyTypes` union (which would silently go stale as
+ * new types are added) and naturally excludes `options`-array entries, which
+ * carry `name`/`value` but no `displayName`/`type`.
+ *
+ * Without a `default`, n8n cannot reliably initialise the parameter's value,
+ * which leads to inconsistent runtime behaviour in the editor and on execution.
+ */
+
+import { simpleTraverse } from '@typescript-eslint/typescript-estree';
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import {
+	createRule,
+	findClassProperty,
+	findObjectProperty,
+	getStringLiteralValue,
+	isFileType,
+	isNodeTypeClass,
+} from '../utils/index.js';
+
+/** Property keys an `INodeProperties` parameter always carries as string literals. */
+const REQUIRED_PARAM_KEYS = ['displayName', 'name', 'type'] as const;
+
+/** Returns true when the object literal has the shape of a node parameter. */
+function isNodeParameter(node: TSESTree.ObjectExpression): boolean {
+	return REQUIRED_PARAM_KEYS.every((key) => {
+		const property = findObjectProperty(node, key);
+		return property !== null && getStringLiteralValue(property.value) !== null;
+	});
+}
+
+export const RequireParamDefaultRule = createRule({
+	name: 'require-param-default',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require every node parameter to declare a default value.',
+		},
+		messages: {
+			missingDefault:
+				"Node parameter '{{ name }}' is missing a `default` value. Add a `default` property so the parameter initialises consistently.",
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!isFileType(context.filename, '.node.ts')) {
+			return {};
+		}
+
+		const reportIfMissingDefault = (node: TSESTree.ObjectExpression): void => {
+			if (!isNodeParameter(node) || findObjectProperty(node, 'default') !== null) {
+				return;
+			}
+			const nameProperty = findObjectProperty(node, 'name');
+			context.report({
+				node,
+				messageId: 'missingDefault',
+				data: { name: getStringLiteralValue(nameProperty?.value ?? null) ?? '' },
+			});
+		};
+
+		return {
+			// Scope to an INodeType class's `description`, then walk only that
+			// subtree, so helper classes and object literals elsewhere in the file
+			// (e.g. in method bodies) that share the parameter shape are ignored.
+			ClassDeclaration(node) {
+				if (!isNodeTypeClass(node)) return;
+				const description = findClassProperty(node, 'description');
+				if (description?.value?.type !== AST_NODE_TYPES.ObjectExpression) return;
+
+				simpleTraverse(description.value, {
+					enter(child) {
+						if (child.type === AST_NODE_TYPES.ObjectExpression) {
+							reportIfMissingDefault(child);
+						}
+					},
+				});
+			},
+		};
+	},
+});

package/src/rules/trigger-node-conventions.test.ts

@@ -0,0 +1,110 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { TriggerNodeConventionsRule } from './trigger-node-conventions.js';
+
+const ruleTester = new RuleTester();
+
+function createNodeCode(options: {
+	className: string;
+	name: string;
+	displayName: string;
+	inputs: string;
+}): string {
+	const { className, name, displayName, inputs } = options;
+	return `
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+
+export class ${className} implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: '${displayName}',
+    name: '${name}',
+    group: ['trigger'],
+    version: 1,
+    description: 'A test node',
+    defaults: { name: '${displayName}' },
+    inputs: ${inputs},
+    outputs: ['main'],
+    properties: [],
+  };
+}`;
+}
+
+ruleTester.run('trigger-node-conventions', TriggerNodeConventionsRule, {
+	valid: [
+		{
+			name: 'class that does not implement INodeType',
+			filename: 'MyTrigger.node.ts',
+			code: 'export class MyTrigger {}',
+		},
+		{
+			name: 'non-trigger node class is ignored',
+			filename: 'My.node.ts',
+			code: createNodeCode({
+				className: 'My',
+				name: 'my',
+				displayName: 'My Node',
+				inputs: "['main']",
+			}),
+		},
+		{
+			name: 'compliant trigger node',
+			filename: 'MyTrigger.node.ts',
+			code: createNodeCode({
+				className: 'MyTrigger',
+				name: 'myTrigger',
+				displayName: 'My Trigger',
+				inputs: '[]',
+			}),
+		},
+	],
+	invalid: [
+		{
+			name: 'name missing Trigger suffix',
+			filename: 'MyTrigger.node.ts',
+			code: createNodeCode({
+				className: 'MyTrigger',
+				name: 'my',
+				displayName: 'My Trigger',
+				inputs: '[]',
+			}),
+			errors: [{ messageId: 'nameMissingSuffix', data: { value: 'my' } }],
+		},
+		{
+			name: 'displayName missing Trigger',
+			filename: 'MyTrigger.node.ts',
+			code: createNodeCode({
+				className: 'MyTrigger',
+				name: 'myTrigger',
+				displayName: 'My Node',
+				inputs: '[]',
+			}),
+			errors: [{ messageId: 'displayNameMissingTrigger', data: { value: 'My Node' } }],
+		},
+		{
+			name: 'inputs is not empty',
+			filename: 'MyTrigger.node.ts',
+			code: createNodeCode({
+				className: 'MyTrigger',
+				name: 'myTrigger',
+				displayName: 'My Trigger',
+				inputs: "['main']",
+			}),
+			errors: [{ messageId: 'inputsNotEmpty' }],
+		},
+		{
+			name: 'all three violations at once',
+			filename: 'MyTrigger.node.ts',
+			code: createNodeCode({
+				className: 'MyTrigger',
+				name: 'my',
+				displayName: 'My Node',
+				inputs: "['main']",
+			}),
+			errors: [
+				{ messageId: 'displayNameMissingTrigger' },
+				{ messageId: 'nameMissingSuffix' },
+				{ messageId: 'inputsNotEmpty' },
+			],
+		},
+	],
+});