@n8n/eslint-plugin-community-nodes 0.6.0 → 0.8.0

package/src/rules/ai-node-package-json.ts

@@ -0,0 +1,100 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty } from '../utils/index.js';
+
+export const AiNodePackageJsonRule = createRule({
+	name: 'ai-node-package-json',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Enforce consistency between n8n.aiNodeSdkVersion and ai-node-sdk peer dependency in community node packages',
+		},
+		messages: {
+			missingPeerDep:
+				'Package declares "n8n.aiNodeSdkVersion" but is missing "ai-node-sdk" in peerDependencies. Add "ai-node-sdk": "*" to peerDependencies.',
+			missingSdkVersion:
+				'Package has "ai-node-sdk" in peerDependencies but is missing "aiNodeSdkVersion" in the "n8n" section of package.json.',
+			invalidSdkVersion: '"n8n.aiNodeSdkVersion" must be a positive integer, got {{ value }}.',
+			wrongLocation:
+				'"aiNodeSdkVersion" must be inside the "n8n" section, not at the root level of package.json.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				// Only process the root object, not nested ones
+				if (node.parent?.type === AST_NODE_TYPES.Property) {
+					return;
+				}
+
+				const n8nProp = findJsonProperty(node, 'n8n');
+				const n8nObject =
+					n8nProp?.value.type === AST_NODE_TYPES.ObjectExpression ? n8nProp.value : null;
+
+				const aiNodeSdkVersionProp = n8nObject
+					? findJsonProperty(n8nObject, 'aiNodeSdkVersion')
+					: null;
+
+				const rootAiNodeSdkVersionProp = findJsonProperty(node, 'aiNodeSdkVersion');
+				const peerDependenciesProp = findJsonProperty(node, 'peerDependencies');
+
+				const hasAiNodeSdkVersion = aiNodeSdkVersionProp !== null;
+				const hasAiNodeSdkPeerDep =
+					peerDependenciesProp?.value.type === AST_NODE_TYPES.ObjectExpression &&
+					findJsonProperty(peerDependenciesProp.value, 'ai-node-sdk') !== null;
+
+				// Catch aiNodeSdkVersion placed at root level instead of inside n8n
+				if (rootAiNodeSdkVersionProp) {
+					context.report({
+						node: rootAiNodeSdkVersionProp,
+						messageId: 'wrongLocation',
+					});
+				}
+
+				// Validate aiNodeSdkVersion is a positive integer when present
+				if (hasAiNodeSdkVersion) {
+					const valueNode = aiNodeSdkVersionProp.value;
+					if (valueNode.type !== AST_NODE_TYPES.Literal || !isPositiveInteger(valueNode.value)) {
+						context.report({
+							node: aiNodeSdkVersionProp,
+							messageId: 'invalidSdkVersion',
+							data: {
+								value: String(
+									valueNode.type === AST_NODE_TYPES.Literal ? valueNode.value : 'non-literal',
+								),
+							},
+						});
+					}
+				}
+
+				// If aiNodeSdkVersion is declared, ai-node-sdk must be in peerDependencies
+				if (hasAiNodeSdkVersion && !hasAiNodeSdkPeerDep) {
+					context.report({
+						node: aiNodeSdkVersionProp,
+						messageId: 'missingPeerDep',
+					});
+				}
+
+				// If ai-node-sdk is in peerDependencies, aiNodeSdkVersion must be declared
+				if (hasAiNodeSdkPeerDep && !hasAiNodeSdkVersion) {
+					context.report({
+						node: peerDependenciesProp,
+						messageId: 'missingSdkVersion',
+					});
+				}
+			},
+		};
+	},
+});
+
+function isPositiveInteger(value: unknown): boolean {
+	return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}

package/src/rules/index.ts

@@ -1,5 +1,6 @@
 import type { AnyRuleModule } from '@typescript-eslint/utils/ts-eslint';
 
+import { AiNodePackageJsonRule } from './ai-node-package-json.js';
 import { CredentialDocumentationUrlRule } from './credential-documentation-url.js';
 import { CredentialPasswordFieldRule } from './credential-password-field.js';
 import { CredentialTestRequiredRule } from './credential-test-required.js';
@@ -13,6 +14,7 @@ import { PackageNameConventionRule } from './package-name-convention.js';
 import { ResourceOperationPatternRule } from './resource-operation-pattern.js';
 
 export const rules = {
+	'ai-node-package-json': AiNodePackageJsonRule,
 	'no-restricted-globals': NoRestrictedGlobalsRule,
 	'no-restricted-imports': NoRestrictedImportsRule,
 	'credential-password-field': CredentialPasswordFieldRule,

package/src/rules/no-restricted-imports.test.ts

@@ -128,7 +128,8 @@ ruleTester.run('no-restricted-imports', NoRestrictedImportsRule, {
 			code: `
 import fs from "fs";
 import path from "path";
-import { WorkflowExecuteMode } from "n8n-workflow";`,
+import { WorkflowExecuteMode } from "n8n-workflow";
+import { supplyModel } from "@n8n/ai-node-sdk";`,
 			errors: [
 				{ messageId: 'restrictedImport', data: { modulePath: 'fs' } },
 				{ messageId: 'restrictedImport', data: { modulePath: 'path' } },

package/src/rules/no-restricted-imports.ts

@@ -7,6 +7,7 @@ import {
 
 const allowedModules = [
 	'n8n-workflow',
+	'ai-node-sdk',
 	'lodash',
 	'moment',
 	'p-limit',
@@ -14,6 +15,7 @@ const allowedModules = [
 	'zod',
 	'crypto',
 	'node:crypto',
+	'@n8n/ai-node-sdk',
 ];
 
 const isModuleAllowed = (modulePath: string): boolean => {

package/src/rules/node-usable-as-tool.test.ts

@@ -51,6 +51,33 @@ export class RegularClass {
 }`;
 }
 
+function createNodeCodeWithOutputsInputs(
+	outputs: string,
+	inputs: string,
+	includeUsableAsTool = false,
+): string {
+	const usableAsToolLine = includeUsableAsTool ? '\n\t\tusableAsTool: true,' : '';
+	return `
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+import { NodeConnectionTypes } 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: ${inputs},
+		outputs: ${outputs},
+		properties: [],${usableAsToolLine}
+	};
+}`;
+}
+
 ruleTester.run('node-usable-as-tool', NodeUsableAsToolRule, {
 	valid: [
 		{
@@ -69,6 +96,21 @@ ruleTester.run('node-usable-as-tool', NodeUsableAsToolRule, {
 			name: 'node without description property',
 			code: createNodeCode(undefined, false),
 		},
+		{
+			name: 'AI-only node: NodeConnectionTypes non-Main output and empty inputs skips usableAsTool check',
+			code: createNodeCodeWithOutputsInputs('[NodeConnectionTypes.AiAgent]', '[]'),
+		},
+		{
+			name: 'AI-only node: multiple non-Main NodeConnectionTypes outputs and empty inputs skips usableAsTool check',
+			code: createNodeCodeWithOutputsInputs(
+				'[NodeConnectionTypes.AiAgent, NodeConnectionTypes.AiTool]',
+				'[]',
+			),
+		},
+		{
+			name: 'AI-only node: non-main string literal output and empty inputs skips usableAsTool check',
+			code: createNodeCodeWithOutputsInputs("['ai_agent']", '[]'),
+		},
 	],
 	invalid: [
 		{
@@ -77,5 +119,29 @@ ruleTester.run('node-usable-as-tool', NodeUsableAsToolRule, {
 			errors: [{ messageId: 'missingUsableAsTool' }],
 			output: createNodeCode(true),
 		},
+		{
+			name: 'NodeConnectionTypes.Main output with empty inputs does not skip check',
+			code: createNodeCodeWithOutputsInputs('[NodeConnectionTypes.Main]', '[]'),
+			errors: [{ messageId: 'missingUsableAsTool' }],
+			output: createNodeCodeWithOutputsInputs('[NodeConnectionTypes.Main]', '[]', true),
+		},
+		{
+			name: 'main string literal output with empty inputs does not skip check',
+			code: createNodeCodeWithOutputsInputs("['main']", '[]'),
+			errors: [{ messageId: 'missingUsableAsTool' }],
+			output: createNodeCodeWithOutputsInputs("['main']", '[]', true),
+		},
+		{
+			name: 'non-Main output with non-empty inputs does not skip check',
+			code: createNodeCodeWithOutputsInputs('[NodeConnectionTypes.AiAgent]', "['main']"),
+			errors: [{ messageId: 'missingUsableAsTool' }],
+			output: createNodeCodeWithOutputsInputs('[NodeConnectionTypes.AiAgent]', "['main']", true),
+		},
+		{
+			name: 'non-main string literal output with non-empty inputs does not skip check',
+			code: createNodeCodeWithOutputsInputs("['ai_agent']", "['main']"),
+			errors: [{ messageId: 'missingUsableAsTool' }],
+			output: createNodeCodeWithOutputsInputs("['ai_agent']", "['main']", true),
+		},
 	],
 });

package/src/rules/node-usable-as-tool.ts

@@ -40,6 +40,28 @@ export const NodeUsableAsToolRule = createRule({
 				}
 
 				const usableAsToolProperty = findObjectProperty(descriptionValue, 'usableAsTool');
+				const outputsProperty = findObjectProperty(descriptionValue, 'outputs');
+				const inputsProperty = findObjectProperty(descriptionValue, 'inputs');
+				if (
+					outputsProperty?.value?.type === TSESTree.AST_NODE_TYPES.ArrayExpression &&
+					inputsProperty?.value?.type === TSESTree.AST_NODE_TYPES.ArrayExpression
+				) {
+					const isAiOutput = outputsProperty?.value?.elements?.some((element) => {
+						const isAiOutputEnum =
+							element?.type === TSESTree.AST_NODE_TYPES.MemberExpression &&
+							element?.object?.type === TSESTree.AST_NODE_TYPES.Identifier &&
+							element?.object?.name === 'NodeConnectionTypes' &&
+							element?.property?.type === TSESTree.AST_NODE_TYPES.Identifier &&
+							element?.property?.name !== 'Main';
+						const isAiOutputLiteral =
+							element?.type === TSESTree.AST_NODE_TYPES.Literal && element?.value !== 'main';
+						return isAiOutputEnum || isAiOutputLiteral;
+					});
+					const isEmptyInputs = inputsProperty?.value?.elements?.length === 0;
+					if (isAiOutput && isEmptyInputs) {
+						return;
+					}
+				}
 
 				if (!usableAsToolProperty) {
 					context.report({

package/src/rules/package-name-convention.ts

@@ -2,7 +2,7 @@ import type { TSESTree } from '@typescript-eslint/utils';
 import { AST_NODE_TYPES } from '@typescript-eslint/utils';
 import type { ReportSuggestionArray } from '@typescript-eslint/utils/ts-eslint';
 
-import { createRule } from '../utils/index.js';
+import { createRule, findJsonProperty } from '../utils/index.js';
 
 export const PackageNameConventionRule = createRule({
 	name: 'package-name-convention',
@@ -31,14 +31,9 @@ export const PackageNameConventionRule = createRule({
 					return;
 				}
 
-				const nameProperty = node.properties.find(
-					(property) =>
-						property.type === AST_NODE_TYPES.Property &&
-						property.key.type === AST_NODE_TYPES.Literal &&
-						property.key.value === 'name',
-				);
+				const nameProperty = findJsonProperty(node, 'name');
 
-				if (!nameProperty || nameProperty.type !== AST_NODE_TYPES.Property) {
+				if (!nameProperty) {
 					return;
 				}
 

package/src/utils/ast-utils.ts

@@ -89,6 +89,19 @@ export function getBooleanLiteralValue(node: TSESTree.Node | null): boolean | nu
 	return typeof value === 'boolean' ? value : null;
 }
 
+export function findJsonProperty(
+	obj: TSESTree.ObjectExpression,
+	propertyName: string,
+): TSESTree.Property | null {
+	const property = obj.properties.find(
+		(prop) =>
+			prop.type === AST_NODE_TYPES.Property &&
+			prop.key.type === AST_NODE_TYPES.Literal &&
+			prop.key.value === propertyName,
+	);
+	return property?.type === AST_NODE_TYPES.Property ? property : null;
+}
+
 export function findArrayLiteralProperty(
 	obj: TSESTree.ObjectExpression,
 	propertyName: string,