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

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

@@ -0,0 +1,212 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { WebhookLifecycleCompleteRule } from './webhook-lifecycle-complete.js';
+
+const ruleTester = new RuleTester();
+
+function createTriggerNode(options: {
+	group?: string;
+	hasWebhooks?: boolean;
+	webhookMethods?: string | null;
+}): string {
+	const { group = 'trigger', hasWebhooks = true, webhookMethods } = options;
+	const webhooksProp = hasWebhooks
+		? "webhooks: [{ name: 'default', httpMethod: 'POST', responseMode: 'onReceived', path: 'webhook' }],"
+		: '';
+	const methodsProp = webhookMethods === null ? '' : `\n\twebhookMethods = ${webhookMethods};`;
+
+	return `
+import type { INodeType, INodeTypeDescription, IHookFunctions } from 'n8n-workflow';
+
+export class TestTrigger implements INodeType {
+	description: INodeTypeDescription = {
+		displayName: 'Test Trigger',
+		name: 'testTrigger',
+		group: ['${group}'],
+		version: 1,
+		description: 'A test trigger',
+		defaults: { name: 'Test Trigger' },
+		inputs: [],
+		outputs: ['main'],
+		${webhooksProp}
+		properties: [],
+	};${methodsProp}
+}`;
+}
+
+const completeWebhookMethods = `{
+	default: {
+		async checkExists(this: IHookFunctions): Promise<boolean> { return true; },
+		async create(this: IHookFunctions): Promise<boolean> { return true; },
+		async delete(this: IHookFunctions): Promise<boolean> { return true; },
+	},
+}`;
+
+ruleTester.run('webhook-lifecycle-complete', WebhookLifecycleCompleteRule, {
+	valid: [
+		{
+			name: 'trigger node with all three webhook lifecycle methods',
+			code: createTriggerNode({ webhookMethods: completeWebhookMethods }),
+		},
+		{
+			name: 'non-trigger node without webhookMethods',
+			code: createTriggerNode({
+				group: 'transform',
+				hasWebhooks: false,
+				webhookMethods: null,
+			}),
+		},
+		{
+			name: 'polling trigger without webhooks array and without webhookMethods',
+			code: createTriggerNode({ hasWebhooks: false, webhookMethods: null }),
+		},
+		{
+			name: 'non-INodeType class with webhookMethods (should be ignored)',
+			code: `
+export class RegularClass {
+	webhookMethods = {
+		default: {
+			async checkExists() { return true; },
+		},
+	};
+}`,
+		},
+		{
+			name: 'trigger with multiple webhook groups, all complete',
+			code: createTriggerNode({
+				webhookMethods: `{
+					default: {
+						async checkExists() { return true; },
+						async create() { return true; },
+						async delete() { return true; },
+					},
+					setup: {
+						async checkExists() { return true; },
+						async create() { return true; },
+						async delete() { return true; },
+					},
+				}`,
+			}),
+		},
+		{
+			name: 'webhook lifecycle defined via arrow functions',
+			code: createTriggerNode({
+				webhookMethods: `{
+					default: {
+						checkExists: async () => true,
+						create: async () => true,
+						delete: async () => true,
+					},
+				}`,
+			}),
+		},
+	],
+	invalid: [
+		{
+			name: 'trigger node missing webhookMethods entirely',
+			code: createTriggerNode({ webhookMethods: null }),
+			errors: [{ messageId: 'missingWebhookMethods' }],
+		},
+		{
+			name: 'trigger node with empty webhookMethods group (all three missing)',
+			code: createTriggerNode({
+				webhookMethods: `{
+					default: {},
+				}`,
+			}),
+			errors: [
+				{
+					messageId: 'missingLifecycleMethod',
+					data: {
+						group: 'default',
+						missing: '`checkExists`, `create`, `delete`',
+					},
+				},
+			],
+		},
+		{
+			name: 'trigger node missing only delete',
+			code: createTriggerNode({
+				webhookMethods: `{
+					default: {
+						async checkExists() { return true; },
+						async create() { return true; },
+					},
+				}`,
+			}),
+			errors: [
+				{
+					messageId: 'missingLifecycleMethod',
+					data: { group: 'default', missing: '`delete`' },
+				},
+			],
+		},
+		{
+			name: 'trigger node missing checkExists and create',
+			code: createTriggerNode({
+				webhookMethods: `{
+					default: {
+						async delete() { return true; },
+					},
+				}`,
+			}),
+			errors: [
+				{
+					messageId: 'missingLifecycleMethod',
+					data: { group: 'default', missing: '`checkExists`, `create`' },
+				},
+			],
+		},
+		{
+			name: 'non-trigger node with incomplete webhookMethods (still flagged)',
+			code: createTriggerNode({
+				group: 'transform',
+				hasWebhooks: false,
+				webhookMethods: `{
+					default: {
+						async create() { return true; },
+					},
+				}`,
+			}),
+			errors: [
+				{
+					messageId: 'missingLifecycleMethod',
+					data: { group: 'default', missing: '`checkExists`, `delete`' },
+				},
+			],
+		},
+		{
+			name: 'webhook trigger (detected via webhooks array) missing webhookMethods',
+			code: createTriggerNode({
+				group: 'transform',
+				hasWebhooks: true,
+				webhookMethods: null,
+			}),
+			errors: [{ messageId: 'missingWebhookMethods' }],
+		},
+		{
+			name: 'multiple webhook groups each missing methods',
+			code: createTriggerNode({
+				webhookMethods: `{
+					default: {
+						async checkExists() { return true; },
+					},
+					setup: {
+						async create() { return true; },
+						async delete() { return true; },
+					},
+				}`,
+			}),
+			errors: [
+				{
+					messageId: 'missingLifecycleMethod',
+					data: { group: 'default', missing: '`create`, `delete`' },
+				},
+				{
+					messageId: 'missingLifecycleMethod',
+					data: { group: 'setup', missing: '`checkExists`' },
+				},
+			],
+		},
+	],
+});

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

@@ -0,0 +1,120 @@
+import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+
+import {
+	createRule,
+	findClassProperty,
+	findObjectProperty,
+	isNodeTypeClass,
+} from '../utils/index.js';
+
+const REQUIRED_METHODS = ['checkExists', 'create', 'delete'] as const;
+type RequiredMethod = (typeof REQUIRED_METHODS)[number];
+
+/**
+ * Returns true if the description declares webhook endpoints, indicating the
+ * node is a webhook-based trigger that needs a complete lifecycle.
+ *
+ * Polling triggers (group `['trigger']` without a `webhooks` array) do not
+ * register remote webhooks and are intentionally out of scope.
+ */
+function hasWebhooksDeclared(descriptionValue: TSESTree.ObjectExpression): boolean {
+	const webhooksProperty = findObjectProperty(descriptionValue, 'webhooks');
+	if (webhooksProperty?.value.type !== AST_NODE_TYPES.ArrayExpression) return false;
+	return webhooksProperty.value.elements.length > 0;
+}
+
+/** Returns true when the property defines a (possibly async) method named `name`. */
+function isMethodProperty(property: TSESTree.ObjectLiteralElement, name: string): boolean {
+	if (property.type !== AST_NODE_TYPES.Property) return false;
+	if (property.computed) return false;
+
+	const keyMatches =
+		(property.key.type === AST_NODE_TYPES.Identifier && property.key.name === name) ||
+		(property.key.type === AST_NODE_TYPES.Literal && property.key.value === name);
+	if (!keyMatches) return false;
+
+	return (
+		property.value.type === AST_NODE_TYPES.FunctionExpression ||
+		property.value.type === AST_NODE_TYPES.ArrowFunctionExpression
+	);
+}
+
+function findMissingMethods(group: TSESTree.ObjectExpression): RequiredMethod[] {
+	return REQUIRED_METHODS.filter(
+		(method) => !group.properties.some((property) => isMethodProperty(property, method)),
+	);
+}
+
+export const WebhookLifecycleCompleteRule = createRule({
+	name: 'webhook-lifecycle-complete',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Require webhook trigger nodes to implement the complete webhookMethods lifecycle (checkExists, create, delete)',
+		},
+		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.',
+			missingLifecycleMethod:
+				'Webhook trigger lifecycle is incomplete. `webhookMethods.{{group}}` is missing: {{missing}}. All of `checkExists`, `create`, and `delete` must be implemented.',
+		},
+		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 !== AST_NODE_TYPES.ObjectExpression) return;
+
+				const webhookMethodsProperty = findClassProperty(node, 'webhookMethods');
+
+				if (!hasWebhooksDeclared(descriptionValue) && !webhookMethodsProperty) {
+					return;
+				}
+
+				if (!webhookMethodsProperty?.value) {
+					context.report({
+						node: node.id ?? node,
+						messageId: 'missingWebhookMethods',
+					});
+					return;
+				}
+
+				if (webhookMethodsProperty.value.type !== AST_NODE_TYPES.ObjectExpression) {
+					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;
+
+					const groupName =
+						groupProperty.key.type === AST_NODE_TYPES.Identifier
+							? groupProperty.key.name
+							: groupProperty.key.type === AST_NODE_TYPES.Literal
+								? String(groupProperty.key.value)
+								: 'default';
+
+					const missing = findMissingMethods(groupProperty.value);
+					if (missing.length === 0) continue;
+
+					context.report({
+						node: groupProperty.key,
+						messageId: 'missingLifecycleMethod',
+						data: {
+							group: groupName,
+							missing: missing.map((m) => `\`${m}\``).join(', '),
+						},
+					});
+				}
+			},
+		};
+	},
+});