@n8n/eslint-plugin-community-nodes 0.2.0

package/src/rules/resource-operation-pattern.ts

@@ -0,0 +1,97 @@
+import { ESLintUtils, TSESTree } from '@typescript-eslint/utils';
+import {
+	isNodeTypeClass,
+	findClassProperty,
+	findObjectProperty,
+	getStringLiteralValue,
+	isFileType,
+} from '../utils/index.js';
+
+export const ResourceOperationPatternRule = ESLintUtils.RuleCreator.withoutDocs({
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Enforce proper resource/operation pattern for better UX in n8n nodes',
+		},
+		messages: {
+			tooManyOperationsWithoutResources:
+				'Node has {{ operationCount }} operations without resources. Use resources to organize operations when there are more than 5 operations.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!isFileType(context.filename, '.node.ts')) {
+			return {};
+		}
+
+		const analyzeNodeDescription = (descriptionValue: TSESTree.Expression | null): void => {
+			if (!descriptionValue || descriptionValue.type !== 'ObjectExpression') {
+				return;
+			}
+
+			const propertiesProperty = findObjectProperty(descriptionValue, 'properties');
+			if (!propertiesProperty?.value || propertiesProperty.value.type !== 'ArrayExpression') {
+				return;
+			}
+
+			const propertiesArray = propertiesProperty.value;
+			let hasResources = false;
+			let operationCount = 0;
+			let operationNode: TSESTree.Node | null = null;
+
+			for (const property of propertiesArray.elements) {
+				if (!property || property.type !== 'ObjectExpression') {
+					continue;
+				}
+
+				const nameProperty = findObjectProperty(property, 'name');
+				const typeProperty = findObjectProperty(property, 'type');
+
+				const name = nameProperty ? getStringLiteralValue(nameProperty.value) : null;
+				const type = typeProperty ? getStringLiteralValue(typeProperty.value) : null;
+
+				if (!name || !type) {
+					continue;
+				}
+
+				if (name === 'resource' && type === 'options') {
+					hasResources = true;
+				}
+
+				if (name === 'operation' && type === 'options') {
+					operationNode = property;
+					const optionsProperty = findObjectProperty(property, 'options');
+					if (optionsProperty?.value?.type === 'ArrayExpression') {
+						operationCount = optionsProperty.value.elements.length;
+					}
+				}
+			}
+
+			if (operationCount > 5 && !hasResources && operationNode) {
+				context.report({
+					node: operationNode,
+					messageId: 'tooManyOperationsWithoutResources',
+					data: {
+						operationCount: operationCount.toString(),
+					},
+				});
+			}
+		};
+
+		return {
+			ClassDeclaration(node) {
+				if (!isNodeTypeClass(node)) {
+					return;
+				}
+
+				const descriptionProperty = findClassProperty(node, 'description');
+				if (!descriptionProperty) {
+					return;
+				}
+
+				analyzeNodeDescription(descriptionProperty.value);
+			},
+		};
+	},
+});

package/src/utils/ast-utils.ts

@@ -0,0 +1,179 @@
+import { TSESTree, AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+function implementsInterface(node: TSESTree.ClassDeclaration, interfaceName: string): boolean {
+	return (
+		node.implements?.some(
+			(impl) =>
+				impl.type === 'TSClassImplements' &&
+				impl.expression.type === 'Identifier' &&
+				impl.expression.name === interfaceName,
+		) ?? false
+	);
+}
+
+export function isNodeTypeClass(node: TSESTree.ClassDeclaration): boolean {
+	if (implementsInterface(node, 'INodeType')) {
+		return true;
+	}
+
+	if (node.superClass?.type === 'Identifier' && node.superClass.name === 'Node') {
+		return true;
+	}
+
+	return false;
+}
+
+export function isCredentialTypeClass(node: TSESTree.ClassDeclaration): boolean {
+	return implementsInterface(node, 'ICredentialType');
+}
+
+export function findClassProperty(
+	node: TSESTree.ClassDeclaration,
+	propertyName: string,
+): TSESTree.PropertyDefinition | null {
+	const property = node.body.body.find(
+		(member) =>
+			member.type === 'PropertyDefinition' &&
+			member.key?.type === 'Identifier' &&
+			member.key.name === propertyName,
+	);
+	return property?.type === 'PropertyDefinition' ? property : null;
+}
+
+export function findObjectProperty(
+	obj: TSESTree.ObjectExpression,
+	propertyName: string,
+): TSESTree.Property | null {
+	const property = obj.properties.find(
+		(prop) =>
+			prop.type === 'Property' && prop.key.type === 'Identifier' && prop.key.name === propertyName,
+	);
+	return property?.type === 'Property' ? property : null;
+}
+
+export function getLiteralValue(node: TSESTree.Node | null): string | boolean | number | null {
+	if (node?.type === 'Literal') {
+		return node.value as string | boolean | number | null;
+	}
+	return null;
+}
+
+export function getStringLiteralValue(node: TSESTree.Node | null): string | null {
+	const value = getLiteralValue(node);
+	return typeof value === 'string' ? value : null;
+}
+
+export function getModulePath(node: TSESTree.Node | null): string | null {
+	const stringValue = getStringLiteralValue(node);
+	if (stringValue) {
+		return stringValue;
+	}
+
+	if (
+		node?.type === 'TemplateLiteral' &&
+		node.expressions.length === 0 &&
+		node.quasis.length === 1
+	) {
+		return node.quasis[0]?.value.cooked ?? null;
+	}
+
+	return null;
+}
+
+export function getBooleanLiteralValue(node: TSESTree.Node | null): boolean | null {
+	const value = getLiteralValue(node);
+	return typeof value === 'boolean' ? value : null;
+}
+
+export function findArrayLiteralProperty(
+	obj: TSESTree.ObjectExpression,
+	propertyName: string,
+): TSESTree.ArrayExpression | null {
+	const property = findObjectProperty(obj, propertyName);
+	if (property?.value.type === 'ArrayExpression') {
+		return property.value;
+	}
+	return null;
+}
+
+export function hasArrayLiteralValue(
+	node: TSESTree.PropertyDefinition,
+	searchValue: string,
+): boolean {
+	if (node.value?.type !== 'ArrayExpression') return false;
+
+	return node.value.elements.some(
+		(element) =>
+			element?.type === 'Literal' &&
+			typeof element.value === 'string' &&
+			element.value === searchValue,
+	);
+}
+
+export function getTopLevelObjectInJson(
+	node: TSESTree.ObjectExpression,
+): TSESTree.ObjectExpression | null {
+	if (node.parent?.type === AST_NODE_TYPES.Property) {
+		return null;
+	}
+	return node;
+}
+
+export function isFileType(filename: string, extension: string): boolean {
+	return filename.endsWith(extension);
+}
+
+export function isDirectRequireCall(node: TSESTree.CallExpression): boolean {
+	return (
+		node.callee.type === 'Identifier' && node.callee.name === 'require' && node.arguments.length > 0
+	);
+}
+
+export function isRequireMemberCall(node: TSESTree.CallExpression): boolean {
+	return (
+		node.callee.type === 'MemberExpression' &&
+		node.callee.object.type === 'Identifier' &&
+		node.callee.object.name === 'require' &&
+		node.arguments.length > 0
+	);
+}
+
+export function extractCredentialInfoFromArray(
+	element: TSESTree.ArrayExpression['elements'][number],
+): { name: string; testedBy?: string; node: TSESTree.Node } | null {
+	if (!element) return null;
+
+	const stringValue = getStringLiteralValue(element);
+	if (stringValue) {
+		return { name: stringValue, node: element };
+	}
+
+	if (element.type === 'ObjectExpression') {
+		const nameProperty = findObjectProperty(element, 'name');
+		const testedByProperty = findObjectProperty(element, 'testedBy');
+
+		if (nameProperty) {
+			const nameValue = getStringLiteralValue(nameProperty.value);
+			const testedByValue = testedByProperty
+				? getStringLiteralValue(testedByProperty.value)
+				: undefined;
+
+			if (nameValue) {
+				return {
+					name: nameValue,
+					testedBy: testedByValue || undefined,
+					node: nameProperty.value,
+				};
+			}
+		}
+	}
+
+	return null;
+}
+
+export function extractCredentialNameFromArray(
+	element: TSESTree.ArrayExpression['elements'][number],
+): { name: string; node: TSESTree.Node } | null {
+	const info = extractCredentialInfoFromArray(element);
+	return info ? { name: info.name, node: info.node } : null;
+}

package/src/utils/file-utils.ts

@@ -0,0 +1,204 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, parse as parsePath } from 'node:path';
+import { parse, simpleTraverse, TSESTree } from '@typescript-eslint/typescript-estree';
+import {
+	isCredentialTypeClass,
+	isNodeTypeClass,
+	findClassProperty,
+	getStringLiteralValue,
+	findArrayLiteralProperty,
+	extractCredentialInfoFromArray,
+} from './ast-utils.js';
+
+export function findPackageJson(startPath: string): string | null {
+	let currentDir = startPath;
+
+	while (parsePath(currentDir).dir !== parsePath(currentDir).root) {
+		const testPath = join(currentDir, 'package.json');
+		if (existsSync(testPath)) {
+			return testPath;
+		}
+
+		currentDir = dirname(currentDir);
+	}
+
+	return null;
+}
+
+function readPackageJsonN8n(packageJsonPath: string): any {
+	try {
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+		return packageJson.n8n || {};
+	} catch {
+		return {};
+	}
+}
+
+function resolveN8nFilePaths(packageJsonPath: string, filePaths: string[]): string[] {
+	const packageDir = dirname(packageJsonPath);
+	const resolvedFiles: string[] = [];
+
+	for (const filePath of filePaths) {
+		const sourcePath = filePath.replace(/^dist\//, '').replace(/\.js$/, '.ts');
+		const fullSourcePath = join(packageDir, sourcePath);
+
+		if (existsSync(fullSourcePath)) {
+			resolvedFiles.push(fullSourcePath);
+		}
+	}
+
+	return resolvedFiles;
+}
+
+export function readPackageJsonCredentials(packageJsonPath: string): Set<string> {
+	const n8nConfig = readPackageJsonN8n(packageJsonPath);
+	const credentialPaths = n8nConfig.credentials || [];
+	const credentialFiles = resolveN8nFilePaths(packageJsonPath, credentialPaths);
+	const credentialNames: string[] = [];
+
+	for (const credentialFile of credentialFiles) {
+		try {
+			const credentialName = extractCredentialNameFromFile(credentialFile);
+			if (credentialName) {
+				credentialNames.push(credentialName);
+			}
+		} catch {
+			// Silently continue if file can't be parsed
+		}
+	}
+
+	return new Set(credentialNames);
+}
+
+export function extractCredentialNameFromFile(credentialFilePath: string): string | null {
+	try {
+		const sourceCode = readFileSync(credentialFilePath, 'utf8');
+		const ast = parse(sourceCode, {
+			jsx: false,
+			range: true,
+		});
+
+		let credentialName: string | null = null;
+
+		simpleTraverse(ast, {
+			enter(node: TSESTree.Node) {
+				if (node.type === 'ClassDeclaration' && isCredentialTypeClass(node)) {
+					const nameProperty = findClassProperty(node, 'name');
+					if (nameProperty) {
+						const nameValue = getStringLiteralValue(nameProperty.value);
+						if (nameValue) {
+							credentialName = nameValue;
+						}
+					}
+				}
+			},
+		});
+
+		return credentialName;
+	} catch {
+		return null;
+	}
+}
+
+export function validateIconPath(
+	iconPath: string,
+	baseDir: string,
+): {
+	isValid: boolean;
+	isFile: boolean;
+	isSvg: boolean;
+	exists: boolean;
+} {
+	const isFile = iconPath.startsWith('file:');
+	const relativePath = iconPath.replace(/^file:/, '');
+	const isSvg = relativePath.endsWith('.svg');
+	const fullPath = join(baseDir, relativePath);
+	const exists = existsSync(fullPath);
+
+	return {
+		isValid: isFile && isSvg && exists,
+		isFile,
+		isSvg,
+		exists,
+	};
+}
+
+export function readPackageJsonNodes(packageJsonPath: string): string[] {
+	const n8nConfig = readPackageJsonN8n(packageJsonPath);
+	const nodePaths = n8nConfig.nodes || [];
+	return resolveN8nFilePaths(packageJsonPath, nodePaths);
+}
+
+export function areAllCredentialUsagesTestedByNodes(
+	credentialName: string,
+	packageDir: string,
+): boolean {
+	const packageJsonPath = join(packageDir, 'package.json');
+	if (!existsSync(packageJsonPath)) {
+		return false;
+	}
+
+	const nodeFiles = readPackageJsonNodes(packageJsonPath);
+	let hasAnyCredentialUsage = false;
+
+	for (const nodeFile of nodeFiles) {
+		const result = checkCredentialUsageInFile(nodeFile, credentialName);
+		if (result.hasUsage) {
+			hasAnyCredentialUsage = true;
+			if (!result.allTestedBy) {
+				return false; // Found usage without testedBy
+			}
+		}
+	}
+
+	return hasAnyCredentialUsage;
+}
+
+function checkCredentialUsageInFile(
+	nodeFile: string,
+	credentialName: string,
+): { hasUsage: boolean; allTestedBy: boolean } {
+	try {
+		const sourceCode = readFileSync(nodeFile, 'utf8');
+		const ast = parse(sourceCode, { jsx: false, range: true });
+
+		let hasUsage = false;
+		let allTestedBy = true;
+
+		simpleTraverse(ast, {
+			enter(node: TSESTree.Node) {
+				if (node.type === 'ClassDeclaration' && isNodeTypeClass(node)) {
+					const descriptionProperty = findClassProperty(node, 'description');
+					if (
+						!descriptionProperty?.value ||
+						descriptionProperty.value.type !== 'ObjectExpression'
+					) {
+						return;
+					}
+
+					const credentialsArray = findArrayLiteralProperty(
+						descriptionProperty.value,
+						'credentials',
+					);
+					if (!credentialsArray) {
+						return;
+					}
+
+					for (const element of credentialsArray.elements) {
+						const credentialInfo = extractCredentialInfoFromArray(element);
+						if (credentialInfo?.name === credentialName) {
+							hasUsage = true;
+							if (!credentialInfo.testedBy) {
+								allTestedBy = false;
+							}
+						}
+					}
+				}
+			},
+		});
+
+		return { hasUsage, allTestedBy };
+	} catch {
+		return { hasUsage: false, allTestedBy: true };
+	}
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './ast-utils.js';
+export * from './file-utils.js';

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"extends": "@n8n/typescript-config/modern/tsconfig.json",
+	"compilerOptions": {
+		"baseUrl": ".",
+		"rootDir": "src",
+		"outDir": "dist",
+		"types": ["vitest/globals"]
+	},
+	"include": ["src/**/*.ts"],
+	"exclude": ["**/*.test.ts"]
+}