@n8n/eslint-plugin-community-nodes 0.19.0 → 0.21.0

package/src/rules/node-registration-complete.ts

@@ -0,0 +1,79 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+import * as path from 'node:path';
+
+import {
+	createRule,
+	findJsonProperty,
+	findNodeSourceFilesOnDisk,
+	readPackageJsonNodes,
+} from '../utils/index.js';
+
+export const NodeRegistrationCompleteRule = createRule({
+	name: 'node-registration-complete',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Ensure every `.node.ts` file in the `nodes/` directory is registered in the "n8n.nodes" array of package.json',
+		},
+		messages: {
+			nodeNotRegistered:
+				'The node file "{{ nodeFile }}" is not registered in the "n8n.nodes" array of package.json. Add it so n8n can discover the node.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				// Only inspect the root object of the package.json file.
+				if (node.parent?.type !== AST_NODE_TYPES.ExpressionStatement) {
+					return;
+				}
+
+				const nodeFilesOnDisk = findNodeSourceFilesOnDisk(context.filename);
+				if (nodeFilesOnDisk.length === 0) {
+					return;
+				}
+
+				const registered = new Set(
+					readPackageJsonNodes(context.filename).map((filePath) => path.resolve(filePath)),
+				);
+
+				const packageDir = path.dirname(context.filename);
+				const reportTarget = resolveReportTarget(node);
+
+				for (const nodeFile of nodeFilesOnDisk) {
+					if (registered.has(path.resolve(nodeFile))) {
+						continue;
+					}
+
+					context.report({
+						node: reportTarget,
+						messageId: 'nodeNotRegistered',
+						data: { nodeFile: path.relative(packageDir, nodeFile) },
+					});
+				}
+			},
+		};
+	},
+});
+
+/**
+ * Reports against the most specific available node: the `n8n.nodes` array, the
+ * `n8n` object, or the package.json root object as a fallback.
+ */
+function resolveReportTarget(root: TSESTree.ObjectExpression): TSESTree.Node {
+	const n8nProperty = findJsonProperty(root, 'n8n');
+	if (n8nProperty?.value.type !== AST_NODE_TYPES.ObjectExpression) {
+		return n8nProperty ?? root;
+	}
+
+	const nodesProperty = findJsonProperty(n8nProperty.value, 'nodes');
+	return nodesProperty ?? n8nProperty;
+}

package/src/rules/require-version.test.ts

@@ -0,0 +1,90 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireVersionRule } from './require-version.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('require-version', RequireVersionRule, {
+	valid: [
+		{
+			name: 'version is a valid semver string',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+		},
+		{
+			name: 'version with pre-release and build metadata',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.2.3-beta.1+build.5" }',
+		},
+		{
+			name: 'zero version is valid',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "0.1.0" }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "name": "n8n-nodes-example" }',
+		},
+		{
+			name: 'nested objects with missing version are not checked',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0", "config": { "nested": "value" } }',
+		},
+		{
+			name: 'objects inside arrays (e.g. contributors) are not flagged',
+			filename: 'package.json',
+			code: `{
+				"name": "n8n-nodes-example",
+				"version": "1.0.0",
+				"contributors": [
+					{ "name": "Alice", "email": "alice@example.com" }
+				]
+			}`,
+		},
+	],
+	invalid: [
+		{
+			name: 'version field is missing entirely',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "description": "Example" }',
+			errors: [{ messageId: 'missingVersion' }],
+		},
+		{
+			name: 'empty package.json object',
+			filename: 'package.json',
+			code: '{}',
+			errors: [{ messageId: 'missingVersion' }],
+		},
+		{
+			name: 'version is an empty string',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "" }',
+			errors: [{ messageId: 'invalidVersion' }],
+		},
+		{
+			name: 'version is not a valid semver',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0" }',
+			errors: [{ messageId: 'invalidVersion' }],
+		},
+		{
+			name: 'version has a leading "v"',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "v1.0.0" }',
+			errors: [{ messageId: 'invalidVersion' }],
+		},
+		{
+			name: 'version is a range, not an exact version',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "^1.0.0" }',
+			errors: [{ messageId: 'invalidVersion' }],
+		},
+		{
+			name: 'version is a number, not a string',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": 1 }',
+			errors: [{ messageId: 'invalidVersion' }],
+		},
+	],
+});

package/src/rules/require-version.ts

@@ -0,0 +1,62 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty } from '../utils/index.js';
+
+// Official SemVer 2.0.0 regex (https://semver.org/), anchored.
+const SEMVER_REGEX =
+	/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+export const RequireVersionRule = createRule({
+	name: 'require-version',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require a valid "version" field in community node package.json',
+		},
+		messages: {
+			missingVersion:
+				'The package.json must have a "version" field. npm requires a valid semantic version (e.g. "1.0.0") to publish the package.',
+			invalidVersion:
+				'The "version" field must be a valid semantic version string (e.g. "1.0.0"), got {{ value }}.',
+		},
+		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 versionProp = findJsonProperty(node, 'version');
+
+				if (!versionProp) {
+					context.report({
+						node,
+						messageId: 'missingVersion',
+					});
+					return;
+				}
+
+				const valueNode = versionProp.value;
+				const value = valueNode.type === AST_NODE_TYPES.Literal ? valueNode.value : null;
+
+				if (typeof value !== 'string' || !SEMVER_REGEX.test(value)) {
+					const rawValue =
+						valueNode.type === AST_NODE_TYPES.Literal ? String(valueNode.raw) : 'non-literal';
+					context.report({
+						node: versionProp,
+						messageId: 'invalidVersion',
+						data: { value: rawValue },
+					});
+				}
+			},
+		};
+	},
+});

package/src/rules/valid-author.test.ts

@@ -0,0 +1,108 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { ValidAuthorRule } from './valid-author.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('valid-author', ValidAuthorRule, {
+	valid: [
+		{
+			name: 'author object with non-empty name and email',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "author": { "name": "Jane Doe", "email": "jane@example.com" } }',
+		},
+		{
+			name: 'author object with extra fields',
+			filename: 'package.json',
+			code: '{ "author": { "name": "Jane Doe", "email": "jane@example.com", "url": "https://example.com" } }',
+		},
+		{
+			name: 'author shorthand string with name and email',
+			filename: 'package.json',
+			code: '{ "author": "Jane Doe <jane@example.com>" }',
+		},
+		{
+			name: 'author shorthand string with name, email and url',
+			filename: 'package.json',
+			code: '{ "author": "Jane Doe <jane@example.com> (https://example.com)" }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "name": "n8n-nodes-example" }',
+		},
+		{
+			name: 'nested objects are not checked',
+			filename: 'package.json',
+			code: '{ "author": { "name": "Jane Doe", "email": "jane@example.com" }, "config": { "nested": "value" } }',
+		},
+	],
+	invalid: [
+		{
+			name: 'missing author field entirely',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+			errors: [{ messageId: 'authorMissing' }],
+		},
+		{
+			name: 'empty package.json object',
+			filename: 'package.json',
+			code: '{}',
+			errors: [{ messageId: 'authorMissing' }],
+		},
+		{
+			name: 'author object missing email',
+			filename: 'package.json',
+			code: '{ "author": { "name": "Jane Doe" } }',
+			errors: [{ messageId: 'authorEmailMissing' }],
+		},
+		{
+			name: 'author object missing name',
+			filename: 'package.json',
+			code: '{ "author": { "email": "jane@example.com" } }',
+			errors: [{ messageId: 'authorNameMissing' }],
+		},
+		{
+			name: 'author object with empty name and email strings',
+			filename: 'package.json',
+			code: '{ "author": { "name": "", "email": "  " } }',
+			errors: [{ messageId: 'authorNameMissing' }, { messageId: 'authorEmailMissing' }],
+		},
+		{
+			name: 'author object with non-string name',
+			filename: 'package.json',
+			code: '{ "author": { "name": 123, "email": "jane@example.com" } }',
+			errors: [{ messageId: 'authorNameMissing' }],
+		},
+		{
+			name: 'author shorthand string with name only',
+			filename: 'package.json',
+			code: '{ "author": "Jane Doe" }',
+			errors: [{ messageId: 'authorEmailMissing' }],
+		},
+		{
+			name: 'author shorthand string with email only',
+			filename: 'package.json',
+			code: '{ "author": "<jane@example.com>" }',
+			errors: [{ messageId: 'authorNameMissing' }],
+		},
+		{
+			name: 'author shorthand string with empty email angle brackets',
+			filename: 'package.json',
+			code: '{ "author": "Jane Doe <>" }',
+			errors: [{ messageId: 'authorEmailMissing' }],
+		},
+		{
+			name: 'empty author string',
+			filename: 'package.json',
+			code: '{ "author": "" }',
+			errors: [{ messageId: 'authorNameMissing' }, { messageId: 'authorEmailMissing' }],
+		},
+		{
+			name: 'author as empty array',
+			filename: 'package.json',
+			code: '{ "author": [] }',
+			errors: [{ messageId: 'authorMissing' }],
+		},
+	],
+});

package/src/rules/valid-author.ts

@@ -0,0 +1,100 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty, getTopLevelObjectInJson } from '../utils/index.js';
+
+/**
+ * Parses an npm "person" shorthand string of the form
+ * `Name <email> (url)` into its name and email parts. Any part may be absent.
+ */
+function parsePersonString(value: string): { name: string; email: string } {
+	const emailMatch = /<([^>]*)>/.exec(value);
+	const email = (emailMatch?.[1] ?? '').trim();
+
+	const ltIndex = value.indexOf('<');
+	const parenIndex = value.indexOf('(');
+	let nameEnd = value.length;
+	if (ltIndex !== -1) nameEnd = Math.min(nameEnd, ltIndex);
+	if (parenIndex !== -1) nameEnd = Math.min(nameEnd, parenIndex);
+	const name = value.slice(0, nameEnd).trim();
+
+	return { name, email };
+}
+
+function isNonEmptyStringLiteral(node: TSESTree.Property | null): boolean {
+	if (!node || node.value.type !== AST_NODE_TYPES.Literal) {
+		return false;
+	}
+	const { value } = node.value;
+	return typeof value === 'string' && value.trim().length > 0;
+}
+
+export const ValidAuthorRule = createRule({
+	name: 'valid-author',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require a non-empty author name and email in package.json',
+		},
+		messages: {
+			authorMissing: 'package.json must have an "author" field with a non-empty name and email.',
+			authorNameMissing: 'The "author" field must include a non-empty name.',
+			authorEmailMissing: 'The "author" field must include a non-empty email.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				const root = getTopLevelObjectInJson(node);
+				if (!root) {
+					return;
+				}
+
+				const authorProp = findJsonProperty(root, 'author');
+				if (!authorProp) {
+					context.report({ node: root, messageId: 'authorMissing' });
+					return;
+				}
+
+				const authorValue = authorProp.value;
+
+				// Shorthand string form: "Name <email> (url)"
+				if (authorValue.type === AST_NODE_TYPES.Literal) {
+					if (typeof authorValue.value !== 'string') {
+						context.report({ node: authorProp, messageId: 'authorMissing' });
+						return;
+					}
+
+					const { name, email } = parsePersonString(authorValue.value);
+					if (name.length === 0) {
+						context.report({ node: authorProp, messageId: 'authorNameMissing' });
+					}
+					if (email.length === 0) {
+						context.report({ node: authorProp, messageId: 'authorEmailMissing' });
+					}
+					return;
+				}
+
+				// Object form: { "name": "...", "email": "..." }
+				if (authorValue.type === AST_NODE_TYPES.ObjectExpression) {
+					if (!isNonEmptyStringLiteral(findJsonProperty(authorValue, 'name'))) {
+						context.report({ node: authorProp, messageId: 'authorNameMissing' });
+					}
+					if (!isNonEmptyStringLiteral(findJsonProperty(authorValue, 'email'))) {
+						context.report({ node: authorProp, messageId: 'authorEmailMissing' });
+					}
+					return;
+				}
+
+				// Any other shape (e.g. array, null) cannot carry a name and email.
+				context.report({ node: authorProp, messageId: 'authorMissing' });
+			},
+		};
+	},
+});

package/src/utils/file-utils.ts

@@ -158,20 +158,17 @@ export function validateIconPath(
 ): {
 	isValid: boolean;
 	isFile: boolean;
-	isSvg: boolean;
 	exists: boolean;
 } {
 	const isFile = iconPath.startsWith('file:');
 	const relativePath = iconPath.replace(/^file:/, '');
-	const isSvg = relativePath.endsWith('.svg');
 	// Should not use safeJoinPath here because iconPath can be outside of the node class folder
 	const fullPath = path.join(baseDir, relativePath);
 	const exists = fileExistsWithCaseSync(fullPath);
 
 	return {
-		isValid: isFile && isSvg && exists,
+		isValid: isFile && exists,
 		isFile,
-		isSvg,
 		exists,
 	};
 }
@@ -182,6 +179,44 @@ export function readPackageJsonNodes(packageJsonPath: string): string[] {
 	return resolveN8nFilePaths(packageJsonPath, nodePaths);
 }
 
+function findFilesRecursively(dir: string, matches: (fileName: string) => boolean): string[] {
+	const results: string[] = [];
+
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return results;
+	}
+
+	for (const entry of entries) {
+		const fullPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			results.push(...findFilesRecursively(fullPath, matches));
+		} else if (entry.isFile() && matches(entry.name)) {
+			results.push(fullPath);
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Finds all `*.node.ts` source files in the package's `nodes/` directory,
+ * returning their absolute paths. Returns an empty array if there is no
+ * `nodes/` directory.
+ */
+export function findNodeSourceFilesOnDisk(packageJsonPath: string): string[] {
+	const packageDir = dirname(packageJsonPath);
+	const nodesDir = safeJoinPath(packageDir, 'nodes');
+
+	if (!existsSync(nodesDir)) {
+		return [];
+	}
+
+	return findFilesRecursively(nodesDir, (fileName) => fileName.endsWith('.node.ts'));
+}
+
 export function areAllCredentialUsagesTestedByNodes(
 	credentialName: string,
 	packageDir: string,
@@ -268,7 +303,9 @@ function fileExistsWithCaseSync(filePath: string): boolean {
 	}
 }
 
-export function findSimilarSvgFiles(targetPath: string, baseDir: string): string[] {
+const ICON_EXTENSIONS = ['.svg', '.png'];
+
+export function findSimilarIconFiles(targetPath: string, baseDir: string): string[] {
 	try {
 		const targetFileName = path.basename(targetPath, path.extname(targetPath));
 		const targetDir = path.dirname(targetPath);
@@ -279,15 +316,25 @@ export function findSimilarSvgFiles(targetPath: string, baseDir: string): string
 			return [];
 		}
 
-		const files = readdirSync(searchDir);
-		const svgFileNames = files
-			.filter((file) => file.endsWith('.svg'))
-			.map((file) => path.basename(file, '.svg'));
+		const files = readdirSync(searchDir).filter((file) =>
+			ICON_EXTENSIONS.includes(path.extname(file).toLowerCase()),
+		);
+
+		// Map icon base names to their actual filenames so suggestions keep their extension.
+		const baseNameToFiles = new Map<string, string[]>();
+		for (const file of files) {
+			const baseName = path.basename(file, path.extname(file));
+			const existing = baseNameToFiles.get(baseName) ?? [];
+			existing.push(file);
+			baseNameToFiles.set(baseName, existing);
+		}
 
-		const candidateNames = new Set(svgFileNames);
+		const candidateNames = new Set(baseNameToFiles.keys());
 		const similarNames = findSimilarStrings(targetFileName, candidateNames);
 
-		return similarNames.map((name) => path.join(targetDir, `${name}.svg`));
+		return similarNames.flatMap((name) =>
+			(baseNameToFiles.get(name) ?? []).map((file) => path.join(targetDir, file)),
+		);
 	} catch {
 		return [];
 	}

package/.turbo/turbo-build.log

@@ -1,4 +0,0 @@
-
-> @n8n/eslint-plugin-community-nodes@0.19.0 build /home/runner/work/n8n/n8n/packages/@n8n/eslint-plugin-community-nodes
-> tsc --project tsconfig.build.json
-