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

package/docs/rules/missing-paired-item.md

@@ -0,0 +1,70 @@
+# Require pairedItem on INodeExecutionData objects in execute() methods to preserve item linking (`@n8n/community-nodes/missing-paired-item`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Every `INodeExecutionData` object returned from `execute()` should include a `pairedItem` property. Without it, downstream nodes cannot trace data lineage and expressions like `$('NodeName').item` will silently fail.
+
+The rule detects object literals with a `json` property but no `pairedItem` inside `execute()` methods of `INodeType` classes.
+
+## Examples
+
+### Incorrect
+
+```typescript
+class MyNode implements INodeType {
+  async execute() {
+    const items = this.getInputData();
+    // Missing pairedItem
+    return [items.map((item) => ({ json: item.json }))];
+  }
+}
+```
+
+```typescript
+class MyNode implements INodeType {
+  async execute() {
+    const returnData: INodeExecutionData[] = [];
+    // Missing pairedItem
+    returnData.push({ json: { result: true } });
+    return [returnData];
+  }
+}
+```
+
+### Correct
+
+```typescript
+class MyNode implements INodeType {
+  async execute() {
+    const items = this.getInputData();
+    return [items.map((item, index) => ({ json: item.json, pairedItem: { item: index } }))];
+  }
+}
+```
+
+```typescript
+class MyNode implements INodeType {
+  async execute() {
+    const returnData: INodeExecutionData[] = [];
+    returnData.push({ json: { result: true }, pairedItem: { item: 0 } });
+    return [returnData];
+  }
+}
+```
+
+## When to Disable
+
+If your node intentionally does not support item linking (e.g. it aggregates all input items into a single output), you can suppress this rule:
+
+```typescript
+// eslint-disable-next-line @n8n/community-nodes/missing-paired-item
+returnData.push({ json: aggregatedResult });
+```
+
+## Further Reading
+
+- [n8n Paired Items Documentation](https://docs.n8n.io/integrations/creating-nodes/build/reference/paired-items/)

package/docs/rules/no-forbidden-lifecycle-scripts.md

@@ -0,0 +1,46 @@
+# Ban lifecycle scripts (prepare, preinstall, postinstall, etc.) in community node packages (`@n8n/community-nodes/no-forbidden-lifecycle-scripts`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+npm lifecycle scripts (`prepare`, `preinstall`, `install`, `postinstall`, `prepublish`, `preprepare`, `postprepare`) run automatically — without user confirmation — during `npm install`. In the context of n8n community nodes, this means arbitrary code executes on the n8n instance the moment a community node is installed.
+
+n8n community nodes are distributed as pre-built npm packages. Unlike regular npm libraries, there is no legitimate reason for a community node to hook into install-time lifecycle events — the package should already contain compiled code ready to use. A `prepare` or `postinstall` script in a community node is either a misconfiguration (the author forgot to remove a build step meant for development) or a supply-chain attack vector.
+
+## Examples
+
+### Incorrect
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "scripts": {
+    "prepare": "npm run build"
+  }
+}
+```
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "scripts": {
+    "build": "tsc",
+    "postinstall": "node setup.js"
+  }
+}
+```
+
+### Correct
+
+```json
+{
+  "name": "n8n-nodes-example",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  }
+}
+```

package/docs/rules/require-continue-on-fail.md

@@ -0,0 +1,56 @@
+# Require continueOnFail() handling in execute() methods of node classes (`@n8n/community-nodes/require-continue-on-fail`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Ensures that `execute()` methods in node classes include a `this.continueOnFail()` check. Without this, a single item error will abort the entire workflow instead of allowing execution to continue past the failing item.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = { /* ... */ };
+
+  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
+    const items = this.getInputData();
+    const returnData: INodeExecutionData[] = [];
+    for (let i = 0; i < items.length; i++) {
+      // No error handling — one bad item kills the whole workflow
+      const result = await someApiCall(items[i]);
+      returnData.push({ json: result });
+    }
+    return [returnData];
+  }
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = { /* ... */ };
+
+  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
+    const items = this.getInputData();
+    const returnData: INodeExecutionData[] = [];
+    for (let i = 0; i < items.length; i++) {
+      try {
+        const result = await someApiCall(items[i]);
+        returnData.push({ json: result });
+      } catch (error) {
+        if (this.continueOnFail()) {
+          returnData.push({ json: { error: error.message }, pairedItem: { item: i } });
+          continue;
+        }
+        throw error;
+      }
+    }
+    return [returnData];
+  }
+}
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@n8n/eslint-plugin-community-nodes",
   "type": "module",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "main": "./dist/plugin.js",
   "types": "./dist/plugin.d.ts",
   "exports": {
@@ -24,7 +24,7 @@
     "vitest": "^4.1.1",
     "@n8n/typescript-config": "1.4.0",
     "@n8n/vitest-config": "1.9.0",
-    "n8n-workflow": "2.16.0"
+    "n8n-workflow": "2.17.0"
   },
   "peerDependencies": {
     "eslint": ">= 9",

package/src/plugin.ts

@@ -29,6 +29,7 @@ const configs = {
 			'@n8n/community-nodes/package-name-convention': 'error',
 			'@n8n/community-nodes/credential-test-required': 'error',
 			'@n8n/community-nodes/no-credential-reuse': 'error',
+			'@n8n/community-nodes/no-forbidden-lifecycle-scripts': 'error',
 			'@n8n/community-nodes/no-http-request-with-manual-auth': 'error',
 			'@n8n/community-nodes/icon-validation': 'error',
 			'@n8n/community-nodes/options-sorted-alphabetically': 'warn',
@@ -37,6 +38,8 @@ const configs = {
 			'@n8n/community-nodes/node-class-description-icon-missing': 'error',
 			'@n8n/community-nodes/cred-class-field-icon-missing': 'error',
 			'@n8n/community-nodes/node-connection-type-literal': 'error',
+			'@n8n/community-nodes/missing-paired-item': 'error',
+			'@n8n/community-nodes/require-continue-on-fail': 'error',
 		},
 	},
 	recommendedWithoutN8nCloudSupport: {
@@ -52,6 +55,7 @@ const configs = {
 			'@n8n/community-nodes/package-name-convention': 'error',
 			'@n8n/community-nodes/credential-test-required': 'error',
 			'@n8n/community-nodes/no-credential-reuse': 'error',
+			'@n8n/community-nodes/no-forbidden-lifecycle-scripts': 'error',
 			'@n8n/community-nodes/no-http-request-with-manual-auth': 'error',
 			'@n8n/community-nodes/icon-validation': 'error',
 			'@n8n/community-nodes/options-sorted-alphabetically': 'warn',
@@ -60,6 +64,8 @@ const configs = {
 			'@n8n/community-nodes/node-class-description-icon-missing': 'error',
 			'@n8n/community-nodes/cred-class-field-icon-missing': 'error',
 			'@n8n/community-nodes/node-connection-type-literal': 'error',
+			'@n8n/community-nodes/missing-paired-item': 'error',
+			'@n8n/community-nodes/require-continue-on-fail': 'error',
 		},
 	},
 } satisfies Record<string, Linter.Config>;

package/src/rules/index.ts

@@ -6,8 +6,10 @@ import { CredentialDocumentationUrlRule } from './credential-documentation-url.j
 import { CredentialPasswordFieldRule } from './credential-password-field.js';
 import { CredentialTestRequiredRule } from './credential-test-required.js';
 import { IconValidationRule } from './icon-validation.js';
+import { MissingPairedItemRule } from './missing-paired-item.js';
 import { NoCredentialReuseRule } from './no-credential-reuse.js';
 import { NoDeprecatedWorkflowFunctionsRule } from './no-deprecated-workflow-functions.js';
+import { NoForbiddenLifecycleScriptsRule } from './no-forbidden-lifecycle-scripts.js';
 import { NoHttpRequestWithManualAuthRule } from './no-http-request-with-manual-auth.js';
 import { NoRestrictedGlobalsRule } from './no-restricted-globals.js';
 import { NoRestrictedImportsRule } from './no-restricted-imports.js';
@@ -16,6 +18,7 @@ import { NodeConnectionTypeLiteralRule } from './node-connection-type-literal.js
 import { NodeUsableAsToolRule } from './node-usable-as-tool.js';
 import { OptionsSortedAlphabeticallyRule } from './options-sorted-alphabetically.js';
 import { PackageNameConventionRule } from './package-name-convention.js';
+import { RequireContinueOnFailRule } from './require-continue-on-fail.js';
 import { ResourceOperationPatternRule } from './resource-operation-pattern.js';
 
 export const rules = {
@@ -29,6 +32,7 @@ export const rules = {
 	'package-name-convention': PackageNameConventionRule,
 	'credential-test-required': CredentialTestRequiredRule,
 	'no-credential-reuse': NoCredentialReuseRule,
+	'no-forbidden-lifecycle-scripts': NoForbiddenLifecycleScriptsRule,
 	'no-http-request-with-manual-auth': NoHttpRequestWithManualAuthRule,
 	'icon-validation': IconValidationRule,
 	'resource-operation-pattern': ResourceOperationPatternRule,
@@ -36,4 +40,6 @@ export const rules = {
 	'node-class-description-icon-missing': NodeClassDescriptionIconMissingRule,
 	'cred-class-field-icon-missing': CredClassFieldIconMissingRule,
 	'node-connection-type-literal': NodeConnectionTypeLiteralRule,
+	'missing-paired-item': MissingPairedItemRule,
+	'require-continue-on-fail': RequireContinueOnFailRule,
 } satisfies Record<string, AnyRuleModule>;

package/src/rules/missing-paired-item.test.ts

@@ -0,0 +1,229 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { MissingPairedItemRule } from './missing-paired-item.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('missing-paired-item', MissingPairedItemRule, {
+	valid: [
+		{
+			name: 'object with json and pairedItem in execute()',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		return [[{ json: { id: 1 }, pairedItem: { item: 0 } }]];
+	}
+}`,
+		},
+		{
+			name: 'object with json and pairedItem as number shorthand',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		return [[{ json: { id: 1 }, pairedItem: 0 }]];
+	}
+}`,
+		},
+		{
+			name: 'non-node-type class is ignored',
+			filename: 'MyNode.node.ts',
+			code: `
+class Helper {
+	async execute() {
+		return [[{ json: { id: 1 } }]];
+	}
+}`,
+		},
+		{
+			name: 'non-.node.ts file is ignored',
+			filename: 'utils.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		return [[{ json: { id: 1 } }]];
+	}
+}`,
+		},
+		{
+			name: 'object outside execute() is ignored',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async someHelper() {
+		return { json: { id: 1 } };
+	}
+}`,
+		},
+		{
+			name: 'object without json property is ignored',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		const options = { url: 'https://api.example.com', method: 'GET' };
+		return [[{ json: options, pairedItem: { item: 0 } }]];
+	}
+}`,
+		},
+		{
+			name: 'object with unrecognized keys is not INodeExecutionData',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		const config = { json: true, indent: 2, spaces: 4 };
+		return this.process(config);
+	}
+}`,
+		},
+		{
+			name: 'class extending Node base class with pairedItem',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode extends Node {
+	description = {};
+	async execute() {
+		return [[{ json: { id: 1 }, pairedItem: { item: 0 } }]];
+	}
+}`,
+		},
+		{
+			name: 'spread element in object is allowed',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		return [[{ ...baseItem, json: { id: 1 } }]];
+	}
+}`,
+		},
+		{
+			name: 'object inside constructExecutionMetaData is allowed',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		const executionData = this.helpers.constructExecutionMetaData(
+			[{ json: { success: true } }],
+			{ itemData: { item: i } },
+		);
+		return [executionData];
+	}
+}`,
+		},
+		{
+			name: 'object with computed property key is not INodeExecutionData',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		const obj = { json: data, [dynamicKey]: value };
+		return [[obj]];
+	}
+}`,
+		},
+	],
+	invalid: [
+		{
+			name: 'missing pairedItem in return statement',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		return [[{ json: { id: 1 } }]];
+	}
+}`,
+			errors: [{ messageId: 'missingPairedItem' }],
+		},
+		{
+			name: 'missing pairedItem in .map() callback',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		const items = this.getInputData();
+		return [items.map((item, index) => ({ json: item.json }))];
+	}
+}`,
+			errors: [{ messageId: 'missingPairedItem' }],
+		},
+		{
+			name: 'missing pairedItem in .push() call',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		const returnData = [];
+		returnData.push({ json: { result: true } });
+		return [returnData];
+	}
+}`,
+			errors: [{ messageId: 'missingPairedItem' }],
+		},
+		{
+			name: 'multiple objects missing pairedItem',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		const returnData = [];
+		returnData.push({ json: { a: 1 } });
+		returnData.push({ json: { b: 2 } });
+		return [returnData];
+	}
+}`,
+			errors: [{ messageId: 'missingPairedItem' }, { messageId: 'missingPairedItem' }],
+		},
+		{
+			name: 'object with json and binary but no pairedItem',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		return [[{ json: { id: 1 }, binary: { data: binaryData } }]];
+	}
+}`,
+			errors: [{ messageId: 'missingPairedItem' }],
+		},
+		{
+			name: 'object with json and executionStatus but no pairedItem',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode implements INodeType {
+	description = {};
+	async execute() {
+		return [[{ json: { id: 1 }, executionStatus: 'success' }]];
+	}
+}`,
+			errors: [{ messageId: 'missingPairedItem' }],
+		},
+		{
+			name: 'class extending Node base class missing pairedItem',
+			filename: 'MyNode.node.ts',
+			code: `
+class MyNode extends Node {
+	description = {};
+	async execute() {
+		return [[{ json: { id: 1 } }]];
+	}
+}`,
+			errors: [{ messageId: 'missingPairedItem' }],
+		},
+	],
+});

package/src/rules/missing-paired-item.ts

@@ -0,0 +1,149 @@
+/**
+ * Flags object literals with a `json` property but no `pairedItem` property
+ * inside `execute()` methods of `INodeType` classes.
+ *
+ * Missing `pairedItem` breaks downstream item-referencing expressions like
+ * `$('NodeName').item`. This rule catches the three most common patterns:
+ *
+ * - Object literals in `.map()` callbacks
+ * - Object literals passed to `.push()` calls
+ * - Object literals in return statements (typically `return [[{ json }]]`)
+ *
+ * Only flags object literals directly — variable references are skipped since
+ * their shape cannot be determined without type resolution.
+ */
+
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import {
+	createRule,
+	findObjectProperty,
+	isFileType,
+	isNodeTypeClass,
+	isThisHelpersMethodCall,
+} from '../utils/index.js';
+
+/**
+ * Checks whether the object is inside an array argument to
+ * `this.helpers.constructExecutionMetaData()`, which adds pairedItem
+ * via the second argument's `itemData` property.
+ */
+function isInsideConstructExecutionMetaData(node: TSESTree.ObjectExpression): boolean {
+	// Pattern: constructExecutionMetaData([{ json: ... }], { itemData: ... })
+	// Walk up: ObjectExpression -> ArrayExpression -> CallExpression
+	const parent = node.parent;
+	if (parent?.type !== AST_NODE_TYPES.ArrayExpression) return false;
+
+	const grandparent = parent.parent;
+	if (grandparent?.type !== AST_NODE_TYPES.CallExpression) return false;
+
+	// Check it's the first argument
+	if (grandparent.arguments[0] !== parent) return false;
+
+	return isThisHelpersMethodCall(grandparent, 'constructExecutionMetaData');
+}
+
+export const MissingPairedItemRule = createRule({
+	name: 'missing-paired-item',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Require pairedItem on INodeExecutionData objects in execute() methods to preserve item linking.',
+		},
+		messages: {
+			missingPairedItem:
+				'Missing pairedItem on INodeExecutionData object. Add `pairedItem: { item: index }` to preserve item linking. See https://docs.n8n.io/integrations/creating-nodes/build/reference/paired-items/',
+		},
+		schema: [],
+		hasSuggestions: false,
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!isFileType(context.filename, '.node.ts')) {
+			return {};
+		}
+
+		let inNodeTypeClass = false;
+		let inExecuteMethod = false;
+
+		return {
+			ClassDeclaration(node) {
+				if (isNodeTypeClass(node)) {
+					inNodeTypeClass = true;
+				}
+			},
+
+			'ClassDeclaration:exit'() {
+				inNodeTypeClass = false;
+				inExecuteMethod = false;
+			},
+
+			MethodDefinition(node: TSESTree.MethodDefinition) {
+				if (
+					inNodeTypeClass &&
+					node.key.type === AST_NODE_TYPES.Identifier &&
+					node.key.name === 'execute'
+				) {
+					inExecuteMethod = true;
+				}
+			},
+
+			'MethodDefinition:exit'(node: TSESTree.MethodDefinition) {
+				if (
+					inExecuteMethod &&
+					node.key.type === AST_NODE_TYPES.Identifier &&
+					node.key.name === 'execute'
+				) {
+					inExecuteMethod = false;
+				}
+			},
+
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				if (!inExecuteMethod) return;
+
+				const hasJson = findObjectProperty(node, 'json') !== null;
+				if (!hasJson) return;
+
+				const hasPairedItem = findObjectProperty(node, 'pairedItem') !== null;
+				if (hasPairedItem) return;
+
+				// Skip if inside constructExecutionMetaData() — it adds pairedItem via itemData
+				if (isInsideConstructExecutionMetaData(node)) return;
+
+				// Skip if the object contains spread elements — they may already provide pairedItem
+				const hasSpread = node.properties.some(
+					(prop) => prop.type === AST_NODE_TYPES.SpreadElement,
+				);
+				if (hasSpread) return;
+
+				// Only flag if this looks like an INodeExecutionData object literal —
+				// must have `json` and optionally `binary`/`error`, nothing unexpected.
+				// Objects with many unrelated keys are likely not INodeExecutionData.
+				const knownKeys = new Set([
+					'json',
+					'binary',
+					'error',
+					'pairedItem',
+					'executionStatus',
+					'metadata',
+					'evaluationData',
+					'redaction',
+					'sendMessage',
+					'index',
+				]);
+				const allPropertiesKnown = node.properties.every(
+					(prop) =>
+						prop.type === AST_NODE_TYPES.Property &&
+						prop.key.type === AST_NODE_TYPES.Identifier &&
+						knownKeys.has(prop.key.name),
+				);
+
+				if (!allPropertiesKnown) return;
+
+				context.report({ node, messageId: 'missingPairedItem' });
+			},
+		};
+	},
+});