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

package/src/rules/require-node-api-error.test.ts

@@ -0,0 +1,199 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireNodeApiErrorRule } from './require-node-api-error.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('require-node-api-error', RequireNodeApiErrorRule, {
+	valid: [
+		{
+			name: 'throw NodeApiError in catch block',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	throw new NodeApiError(this.getNode(), error as JsonObject);
+}`,
+		},
+		{
+			name: 'throw NodeOperationError in catch block',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	throw new NodeOperationError(this.getNode(), 'Operation failed', { itemIndex: i });
+}`,
+		},
+		{
+			name: 'throw outside catch block (not in scope)',
+			code: `
+function validate(input: string) {
+	if (!input) {
+		throw new Error('Input required');
+	}
+}`,
+		},
+		{
+			name: 'throw new Error outside catch block (not in scope)',
+			code: `
+throw new Error('Something went wrong');`,
+		},
+		{
+			name: 'continueOnFail pattern with NodeApiError',
+			code: `
+try {
+	responseData = await apiRequest.call(this, 'POST', '/tasks', body);
+} catch (error) {
+	if (this.continueOnFail()) {
+		returnData.push({ json: { error: error.message } });
+		continue;
+	}
+	throw new NodeApiError(this.getNode(), error as JsonObject);
+}`,
+		},
+		{
+			name: 'conditional handling then NodeApiError in else',
+			code: `
+try {
+	await ftp.put(data, path);
+} catch (error) {
+	if (error.code === 553) {
+		await ftp.mkdir(dirPath, true);
+		await ftp.put(data, path);
+	} else {
+		throw new NodeApiError(this.getNode(), error as JsonObject);
+	}
+}`,
+		},
+		{
+			name: 'throw wrapped error stored in variable',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	const wrapped = new NodeApiError(this.getNode(), error as JsonObject);
+	throw wrapped;
+}`,
+		},
+		{
+			name: 'shadowed variable with same name as catch param',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	const fn = (error: Error) => {
+		throw error;
+	};
+}`,
+		},
+		{
+			name: 'no throw in catch block',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	console.error(error);
+}`,
+		},
+		{
+			name: 'bare re-throw in credential file (skipped)',
+			filename: '/path/to/MyCredential.credentials.ts',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	throw error;
+}`,
+		},
+		{
+			name: 'bare re-throw in .js file (skipped)',
+			filename: '/path/to/helper.js',
+			code: `
+try {
+	apiRequest();
+} catch (error) {
+	throw error;
+}`,
+		},
+	],
+	invalid: [
+		{
+			name: 'bare re-throw of caught error',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	throw error;
+}`,
+			errors: [{ messageId: 'useNodeApiError' }],
+		},
+		{
+			name: 'throw new Error in catch block',
+			code: `
+try {
+	await apiRequest();
+} catch (error) {
+	throw new Error('Request failed');
+}`,
+			errors: [
+				{
+					messageId: 'useNodeApiErrorInsteadOfGeneric',
+					data: { errorClass: 'Error' },
+				},
+			],
+		},
+		{
+			name: 'bare re-throw after continueOnFail',
+			code: `
+try {
+	responseData = await apiRequest.call(this, 'POST', '/tasks', body);
+} catch (error) {
+	if (this.continueOnFail()) {
+		returnData.push({ json: { error: error.message } });
+		continue;
+	}
+	throw error;
+}`,
+			errors: [{ messageId: 'useNodeApiError' }],
+		},
+		{
+			name: 'throw new TypeError in catch block',
+			code: `
+try {
+	JSON.parse(data);
+} catch (error) {
+	throw new TypeError('Invalid JSON');
+}`,
+			errors: [
+				{
+					messageId: 'useNodeApiErrorInsteadOfGeneric',
+					data: { errorClass: 'TypeError' },
+				},
+			],
+		},
+		{
+			name: 'bare re-throw in nested catch',
+			code: `
+try {
+	try {
+		await apiRequest();
+	} catch (innerError) {
+		throw innerError;
+	}
+} catch (outerError) {
+	throw new NodeApiError(this.getNode(), outerError as JsonObject);
+}`,
+			errors: [{ messageId: 'useNodeApiError' }],
+		},
+		{
+			name: 'throw named variable in catch',
+			code: `
+try {
+	await apiRequest();
+} catch (e) {
+	throw e;
+}`,
+			errors: [{ messageId: 'useNodeApiError' }],
+		},
+	],
+});

package/src/rules/require-node-api-error.ts

@@ -0,0 +1,90 @@
+import { DefinitionType } from '@typescript-eslint/scope-manager';
+import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+
+import { isFileType } from '../utils/index.js';
+import { createRule } from '../utils/rule-creator.js';
+
+const ALLOWED_ERROR_CLASSES = new Set(['NodeApiError', 'NodeOperationError']);
+
+function getThrowCalleeName(argument: TSESTree.Expression): string | null {
+	if (argument.type === AST_NODE_TYPES.NewExpression) {
+		if (argument.callee.type === AST_NODE_TYPES.Identifier) {
+			return argument.callee.name;
+		}
+	}
+	return null;
+}
+
+function isInsideCatchClause(node: TSESTree.Node): boolean {
+	let current: TSESTree.Node | undefined = node.parent;
+	while (current) {
+		if (current.type === AST_NODE_TYPES.CatchClause) {
+			return true;
+		}
+		current = current.parent;
+	}
+	return false;
+}
+
+export const RequireNodeApiErrorRule = createRule({
+	name: 'require-node-api-error',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Require NodeApiError or NodeOperationError for error wrapping in catch blocks. ' +
+				'Raw errors lose HTTP context in the n8n UI.',
+		},
+		messages: {
+			useNodeApiError:
+				'Use `NodeApiError` or `NodeOperationError` instead of re-throwing raw errors. ' +
+				'Example: `throw new NodeApiError(this.getNode(), error as JsonObject)`',
+			useNodeApiErrorInsteadOfGeneric:
+				'Use `NodeApiError` or `NodeOperationError` instead of `{{ errorClass }}`. ' +
+				'Example: `throw new NodeApiError(this.getNode(), error as JsonObject)`',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		const isNodeFile = isFileType(context.filename, '.node.ts');
+		const isHelperFile =
+			context.filename.endsWith('.ts') &&
+			!isNodeFile &&
+			!isFileType(context.filename, '.credentials.ts');
+
+		if (!isNodeFile && !isHelperFile) {
+			return {};
+		}
+
+		return {
+			ThrowStatement(node) {
+				if (!isInsideCatchClause(node)) return;
+				if (!node.argument) return;
+
+				const { argument } = node;
+
+				if (argument.type === AST_NODE_TYPES.Identifier) {
+					const scope = context.sourceCode.getScope(node);
+					const ref = scope.references.find((r) => r.identifier === argument);
+					const isCatchParam =
+						ref?.resolved?.defs.some((def) => def.type === DefinitionType.CatchClause) ?? false;
+
+					if (isCatchParam) {
+						context.report({ node, messageId: 'useNodeApiError' });
+					}
+					return;
+				}
+
+				const calleeName = getThrowCalleeName(argument);
+				if (calleeName !== null && !ALLOWED_ERROR_CLASSES.has(calleeName)) {
+					context.report({
+						node,
+						messageId: 'useNodeApiErrorInsteadOfGeneric',
+						data: { errorClass: calleeName },
+					});
+				}
+			},
+		};
+	},
+});

package/src/rules/valid-peer-dependencies.test.ts

@@ -0,0 +1,130 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { ValidPeerDependenciesRule } from './valid-peer-dependencies.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('valid-peer-dependencies', ValidPeerDependenciesRule, {
+	valid: [
+		{
+			name: 'only n8n-workflow with "*"',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*" } }',
+		},
+		{
+			name: 'n8n-workflow and ai-node-sdk',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*", "ai-node-sdk": "*" } }',
+		},
+		{
+			name: 'n8n-workflow and ai-node-sdk with a version range (ai-node-sdk shape is checked by ai-node-package-json rule)',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*", "ai-node-sdk": "^1.0.0" } }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "peerDependencies": { "n8n-core": "*" } }',
+		},
+		{
+			name: 'nested objects are not checked',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*" }, "config": { "peerDependencies": { "n8n-core": "*" } } }',
+		},
+	],
+	invalid: [
+		{
+			name: 'missing peerDependencies section entirely',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+			output:
+				'{ "name": "n8n-nodes-example", "version": "1.0.0", "peerDependencies": { "n8n-workflow": "*" } }',
+			errors: [{ messageId: 'missingPeerDependencies' }],
+		},
+		{
+			name: 'empty peerDependencies section',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": {} }',
+			output: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*" } }',
+			errors: [{ messageId: 'missingN8nWorkflow' }],
+		},
+		{
+			name: 'peerDependencies missing n8n-workflow but has ai-node-sdk',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "ai-node-sdk": "*" } }',
+			output:
+				'{ "name": "n8n-nodes-example", "peerDependencies": { "ai-node-sdk": "*", "n8n-workflow": "*" } }',
+			errors: [{ messageId: 'missingN8nWorkflow' }],
+		},
+		{
+			name: 'n8n-workflow pinned to a specific version',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "^1.0.0" } }',
+			output: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*" } }',
+			errors: [{ messageId: 'pinnedN8nWorkflow', data: { value: '"^1.0.0"' } }],
+		},
+		{
+			name: 'forbidden n8n-core peer dependency (CNOC-404 Sinch)',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*", "n8n-core": "*" } }',
+			errors: [{ messageId: 'forbiddenPeerDependency', data: { name: 'n8n-core' } }],
+		},
+		{
+			name: 'forbidden arbitrary peer dependency',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*", "lodash": "^4.0.0" } }',
+			errors: [{ messageId: 'forbiddenPeerDependency', data: { name: 'lodash' } }],
+		},
+		{
+			name: 'multiple forbidden peer dependencies reported separately',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*", "n8n-core": "*", "axios": "^1.0.0" } }',
+			errors: [
+				{ messageId: 'forbiddenPeerDependency', data: { name: 'n8n-core' } },
+				{ messageId: 'forbiddenPeerDependency', data: { name: 'axios' } },
+			],
+		},
+		{
+			name: 'completely empty package.json gets peerDependencies inserted',
+			filename: 'package.json',
+			code: '{}',
+			output: '{ "peerDependencies": { "n8n-workflow": "*" } }',
+			errors: [{ messageId: 'missingPeerDependencies' }],
+		},
+		{
+			name: 'n8n-workflow value is a non-literal (object) — not auto-fixable',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": { "version": "*" } } }',
+			errors: [{ messageId: 'pinnedN8nWorkflow', data: { value: 'non-literal' } }],
+		},
+		{
+			name: 'peerDependencies is a string instead of an object',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": "n8n-workflow" }',
+			errors: [{ messageId: 'invalidPeerDependenciesType' }],
+		},
+		{
+			name: 'peerDependencies is an array instead of an object',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": ["n8n-workflow"] }',
+			errors: [{ messageId: 'invalidPeerDependenciesType' }],
+		},
+		{
+			name: 'peerDependencies is null',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": null }',
+			errors: [{ messageId: 'invalidPeerDependenciesType' }],
+		},
+		{
+			name: 'pinned n8n-workflow combined with forbidden entry',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "1.0.0", "n8n-core": "*" } }',
+			output:
+				'{ "name": "n8n-nodes-example", "peerDependencies": { "n8n-workflow": "*", "n8n-core": "*" } }',
+			errors: [
+				{ messageId: 'pinnedN8nWorkflow', data: { value: '"1.0.0"' } },
+				{ messageId: 'forbiddenPeerDependency', data: { name: 'n8n-core' } },
+			],
+		},
+	],
+});

package/src/rules/valid-peer-dependencies.ts

@@ -0,0 +1,116 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty } from '../utils/index.js';
+
+const REQUIRED_DEP = 'n8n-workflow';
+const REQUIRED_VERSION = '*';
+const ALLOWED_DEPS = new Set([REQUIRED_DEP, 'ai-node-sdk']);
+
+export const ValidPeerDependenciesRule = createRule({
+	name: 'valid-peer-dependencies',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Require community node package.json peerDependencies to contain only "n8n-workflow": "*" (and optionally "ai-node-sdk")',
+		},
+		fixable: 'code',
+		messages: {
+			missingPeerDependencies: `The package.json must have a "peerDependencies" section containing "${REQUIRED_DEP}": "${REQUIRED_VERSION}".`,
+			invalidPeerDependenciesType: `"peerDependencies" must be an object mapping package names to version ranges (containing "${REQUIRED_DEP}": "${REQUIRED_VERSION}").`,
+			missingN8nWorkflow: `"peerDependencies" must include "${REQUIRED_DEP}": "${REQUIRED_VERSION}".`,
+			pinnedN8nWorkflow: `"peerDependencies.${REQUIRED_DEP}" must be "${REQUIRED_VERSION}", got {{ value }}.`,
+			forbiddenPeerDependency:
+				'"{{ name }}" is not allowed in "peerDependencies". Only "n8n-workflow" and "ai-node-sdk" are permitted.',
+		},
+		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 peerDepsProp = findJsonProperty(node, 'peerDependencies');
+
+				if (!peerDepsProp) {
+					context.report({
+						node,
+						messageId: 'missingPeerDependencies',
+						fix(fixer) {
+							const insertion = `"peerDependencies": { "${REQUIRED_DEP}": "${REQUIRED_VERSION}" }`;
+							const lastProp = node.properties[node.properties.length - 1];
+							if (!lastProp) {
+								return fixer.replaceText(node, `{ ${insertion} }`);
+							}
+							return fixer.insertTextAfter(lastProp, `, ${insertion}`);
+						},
+					});
+					return;
+				}
+
+				if (peerDepsProp.value.type !== AST_NODE_TYPES.ObjectExpression) {
+					context.report({
+						node: peerDepsProp,
+						messageId: 'invalidPeerDependenciesType',
+					});
+					return;
+				}
+
+				const peerDepsObject = peerDepsProp.value;
+				const workflowEntry = findJsonProperty(peerDepsObject, REQUIRED_DEP);
+
+				if (!workflowEntry) {
+					context.report({
+						node: peerDepsProp,
+						messageId: 'missingN8nWorkflow',
+						fix(fixer) {
+							const insertion = `"${REQUIRED_DEP}": "${REQUIRED_VERSION}"`;
+							const lastProp = peerDepsObject.properties[peerDepsObject.properties.length - 1];
+							if (!lastProp) {
+								return fixer.replaceText(peerDepsObject, `{ ${insertion} }`);
+							}
+							return fixer.insertTextAfter(lastProp, `, ${insertion}`);
+						},
+					});
+				} else if (
+					workflowEntry.value.type !== AST_NODE_TYPES.Literal ||
+					workflowEntry.value.value !== REQUIRED_VERSION
+				) {
+					const valueNode = workflowEntry.value;
+					const rawValue =
+						valueNode.type === AST_NODE_TYPES.Literal ? String(valueNode.raw) : 'non-literal';
+					context.report({
+						node: workflowEntry,
+						messageId: 'pinnedN8nWorkflow',
+						data: { value: rawValue },
+						fix(fixer) {
+							if (valueNode.type !== AST_NODE_TYPES.Literal) return null;
+							return fixer.replaceText(valueNode, `"${REQUIRED_VERSION}"`);
+						},
+					});
+				}
+
+				for (const prop of peerDepsObject.properties) {
+					if (prop.type !== AST_NODE_TYPES.Property) continue;
+					if (prop.key.type !== AST_NODE_TYPES.Literal) continue;
+					const name = prop.key.value;
+					if (typeof name !== 'string') continue;
+					if (ALLOWED_DEPS.has(name)) continue;
+					context.report({
+						node: prop,
+						messageId: 'forbiddenPeerDependency',
+						data: { name },
+					});
+				}
+			},
+		};
+	},
+});