@n8n/eslint-plugin-community-nodes 0.26.0 → 0.28.0

package/src/rules/no-silent-error-swallowing.ts

@@ -0,0 +1,127 @@
+import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+
+import {
+	createRule,
+	findClassProperty,
+	isNodeTypeClass,
+	WEBHOOK_LIFECYCLE_METHODS,
+} from '../utils/index.js';
+
+const LIFECYCLE_METHODS: readonly string[] = WEBHOOK_LIFECYCLE_METHODS;
+
+/** Returns the static name of a non-computed object property key, or null. */
+function getPropertyName(property: TSESTree.Property): string | null {
+	if (property.computed) return null;
+	if (property.key.type === AST_NODE_TYPES.Identifier) return property.key.name;
+	if (property.key.type === AST_NODE_TYPES.Literal) return String(property.key.value);
+	return null;
+}
+
+function isFunctionNode(node: TSESTree.Node): boolean {
+	return (
+		node.type === AST_NODE_TYPES.FunctionDeclaration ||
+		node.type === AST_NODE_TYPES.FunctionExpression ||
+		node.type === AST_NODE_TYPES.ArrowFunctionExpression
+	);
+}
+
+/** Walks up to the function that lexically encloses `node`, or null at module scope. */
+function getEnclosingFunction(node: TSESTree.Node): TSESTree.Node | null {
+	let current = node.parent;
+	while (current) {
+		if (isFunctionNode(current)) return current;
+		current = current.parent;
+	}
+	return null;
+}
+
+/** A bare `return;` or `return true/false;` with no other work in the block. */
+function isSilentReturn(statement: TSESTree.Statement): boolean {
+	if (statement.type !== AST_NODE_TYPES.ReturnStatement) return false;
+	const argument = statement.argument;
+	if (argument === null) return true;
+	return argument.type === AST_NODE_TYPES.Literal && typeof argument.value === 'boolean';
+}
+
+export const NoSilentErrorSwallowingRule = createRule({
+	name: 'no-silent-error-swallowing',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Disallow webhook lifecycle methods (checkExists, create, delete) from silently swallowing errors in catch blocks',
+		},
+		messages: {
+			emptyCatch:
+				'Empty catch block in webhook lifecycle method `{{method}}` silently swallows the error. Log the error or rethrow it so failures surface instead of being hidden.',
+			silentReturn:
+				'Catch block in webhook lifecycle method `{{method}}` swallows the error and only returns without logging. Log the error (or rethrow) so failures surface instead of being hidden.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		// Maps each lifecycle method's function node to its method name. Populated
+		// when the enclosing class is visited (before its `catch` clauses), so a
+		// `catch` is only flagged when its *nearest* enclosing function is a
+		// lifecycle method — catches inside nested callbacks are left alone.
+		const lifecycleMethodByFn = new WeakMap<TSESTree.Node, string>();
+
+		return {
+			ClassDeclaration(node) {
+				if (!isNodeTypeClass(node)) return;
+
+				const webhookMethodsProperty = findClassProperty(node, 'webhookMethods');
+				if (webhookMethodsProperty?.value?.type !== AST_NODE_TYPES.ObjectExpression) return;
+
+				for (const groupProperty of webhookMethodsProperty.value.properties) {
+					if (groupProperty.type !== AST_NODE_TYPES.Property) continue;
+					if (groupProperty.value.type !== AST_NODE_TYPES.ObjectExpression) continue;
+
+					for (const methodProperty of groupProperty.value.properties) {
+						if (methodProperty.type !== AST_NODE_TYPES.Property) continue;
+
+						const methodName = getPropertyName(methodProperty);
+						if (methodName === null || !LIFECYCLE_METHODS.includes(methodName)) continue;
+
+						const fn = methodProperty.value;
+						if (
+							fn.type === AST_NODE_TYPES.FunctionExpression ||
+							fn.type === AST_NODE_TYPES.ArrowFunctionExpression
+						) {
+							lifecycleMethodByFn.set(fn, methodName);
+						}
+					}
+				}
+			},
+
+			CatchClause(node) {
+				const enclosingFn = getEnclosingFunction(node);
+				if (enclosingFn === null) return;
+
+				const methodName = lifecycleMethodByFn.get(enclosingFn);
+				if (methodName === undefined) return;
+
+				const statements = node.body.body;
+
+				if (statements.length === 0) {
+					context.report({
+						node: node.body,
+						messageId: 'emptyCatch',
+						data: { method: methodName },
+					});
+					return;
+				}
+
+				const onlyStatement = statements.length === 1 ? statements[0] : undefined;
+				if (onlyStatement && isSilentReturn(onlyStatement)) {
+					context.report({
+						node: onlyStatement,
+						messageId: 'silentReturn',
+						data: { method: methodName },
+					});
+				}
+			},
+		};
+	},
+});

package/src/rules/require-files-array.test.ts

@@ -0,0 +1,57 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireFilesArrayRule } from './require-files-array.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('require-files-array', RequireFilesArrayRule, {
+	valid: [
+		{
+			name: 'files array with entries',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "files": ["dist"] }',
+		},
+		{
+			name: 'files array with multiple entries',
+			filename: 'package.json',
+			code: '{ "files": ["dist", "credentials"] }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "name": "n8n-nodes-example" }',
+		},
+	],
+	invalid: [
+		{
+			name: 'missing files field entirely',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+			errors: [{ messageId: 'filesMissing' }],
+		},
+		{
+			name: 'empty package.json object',
+			filename: 'package.json',
+			code: '{}',
+			errors: [{ messageId: 'filesMissing' }],
+		},
+		{
+			name: 'files as empty array',
+			filename: 'package.json',
+			code: '{ "files": [] }',
+			errors: [{ messageId: 'filesEmpty' }],
+		},
+		{
+			name: 'files as string instead of array',
+			filename: 'package.json',
+			code: '{ "files": "dist" }',
+			errors: [{ messageId: 'filesEmpty' }],
+		},
+		{
+			name: 'files as non-array value',
+			filename: 'package.json',
+			code: '{ "files": null }',
+			errors: [{ messageId: 'filesEmpty' }],
+		},
+	],
+});

package/src/rules/require-files-array.ts

@@ -0,0 +1,50 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty, getTopLevelObjectInJson } from '../utils/index.js';
+
+export const RequireFilesArrayRule = createRule({
+	name: 'require-files-array',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require a non-empty "files" array in package.json',
+		},
+		messages: {
+			filesMissing:
+				'package.json must have a "files" field with a non-empty array of files to publish.',
+			filesEmpty: 'The "files" field must be a non-empty array.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				const root = getTopLevelObjectInJson(node);
+				if (!root) {
+					return;
+				}
+
+				const filesProp = findJsonProperty(root, 'files');
+				if (!filesProp) {
+					context.report({ node: root, messageId: 'filesMissing' });
+					return;
+				}
+
+				const filesValue = filesProp.value;
+
+				if (
+					filesValue.type !== AST_NODE_TYPES.ArrayExpression ||
+					filesValue.elements.length === 0
+				) {
+					context.report({ node: filesProp, messageId: 'filesEmpty' });
+				}
+			},
+		};
+	},
+});

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

@@ -0,0 +1,80 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { RequireHomepageRule } from './require-homepage.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('require-homepage', RequireHomepageRule, {
+	valid: [
+		{
+			name: 'homepage with an https url',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "homepage": "https://example.com" }',
+		},
+		{
+			name: 'homepage with a repository url and path',
+			filename: 'package.json',
+			code: '{ "homepage": "https://github.com/acme/n8n-nodes-example#readme" }',
+		},
+		{
+			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: '{ "homepage": "https://example.com", "config": { "nested": "value" } }',
+		},
+	],
+	invalid: [
+		{
+			name: 'missing homepage field entirely',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+			errors: [{ messageId: 'homepageMissing' }],
+		},
+		{
+			name: 'empty package.json object',
+			filename: 'package.json',
+			code: '{}',
+			errors: [{ messageId: 'homepageMissing' }],
+		},
+		{
+			name: 'empty homepage string',
+			filename: 'package.json',
+			code: '{ "homepage": "" }',
+			errors: [{ messageId: 'homepageInvalid' }],
+		},
+		{
+			name: 'whitespace-only homepage string',
+			filename: 'package.json',
+			code: '{ "homepage": "   " }',
+			errors: [{ messageId: 'homepageInvalid' }],
+		},
+		{
+			name: 'homepage without a protocol',
+			filename: 'package.json',
+			code: '{ "homepage": "example.com" }',
+			errors: [{ messageId: 'homepageInvalid' }],
+		},
+		{
+			name: 'placeholder homepage value',
+			filename: 'package.json',
+			code: '{ "homepage": "TODO" }',
+			errors: [{ messageId: 'homepageInvalid' }],
+		},
+		{
+			name: 'non-string homepage value',
+			filename: 'package.json',
+			code: '{ "homepage": 123 }',
+			errors: [{ messageId: 'homepageInvalid' }],
+		},
+		{
+			name: 'null homepage value',
+			filename: 'package.json',
+			code: '{ "homepage": null }',
+			errors: [{ messageId: 'homepageInvalid' }],
+		},
+	],
+});

package/src/rules/require-homepage.ts

@@ -0,0 +1,59 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty, getTopLevelObjectInJson } from '../utils/index.js';
+
+function isValidUrl(value: string): boolean {
+	try {
+		new URL(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export const RequireHomepageRule = createRule({
+	name: 'require-homepage',
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Require a "homepage" field with a valid URL in package.json',
+		},
+		messages: {
+			homepageMissing: 'package.json must have a "homepage" field.',
+			homepageInvalid: 'The "homepage" field must be a valid URL (e.g. "https://example.com").',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				const root = getTopLevelObjectInJson(node);
+				if (!root) {
+					return;
+				}
+
+				const homepageProp = findJsonProperty(root, 'homepage');
+				if (!homepageProp) {
+					context.report({ node: root, messageId: 'homepageMissing' });
+					return;
+				}
+
+				const homepageValue = homepageProp.value;
+				const isValidHomepage =
+					homepageValue.type === AST_NODE_TYPES.Literal &&
+					typeof homepageValue.value === 'string' &&
+					isValidUrl(homepageValue.value);
+
+				if (!isValidHomepage) {
+					context.report({ node: homepageProp, messageId: 'homepageInvalid' });
+				}
+			},
+		};
+	},
+});

package/src/rules/webhook-lifecycle-complete.ts

@@ -5,11 +5,10 @@ import {
 	findClassProperty,
 	findObjectProperty,
 	isNodeTypeClass,
+	WEBHOOK_LIFECYCLE_METHODS,
+	type WebhookLifecycleMethod,
 } from '../utils/index.js';
 
-const REQUIRED_METHODS = ['checkExists', 'create', 'delete'] as const;
-type RequiredMethod = (typeof REQUIRED_METHODS)[number];
-
 /**
  * Returns true if the description declares webhook endpoints, indicating the
  * node is a webhook-based trigger that needs a complete lifecycle.
@@ -39,8 +38,8 @@ function isMethodProperty(property: TSESTree.ObjectLiteralElement, name: string)
 	);
 }
 
-function findMissingMethods(group: TSESTree.ObjectExpression): RequiredMethod[] {
-	return REQUIRED_METHODS.filter(
+function findMissingMethods(group: TSESTree.ObjectExpression): WebhookLifecycleMethod[] {
+	return WEBHOOK_LIFECYCLE_METHODS.filter(
 		(method) => !group.properties.some((property) => isMethodProperty(property, method)),
 	);
 }

package/src/utils/constants.ts

@@ -0,0 +1,21 @@
+import type { WebhookSetupMethodNames } from 'n8n-workflow';
+
+export type WebhookLifecycleMethod = WebhookSetupMethodNames;
+
+/**
+ * n8n's canonical webhook lifecycle method names (`WebhookSetupMethodNames`) are
+ * a type, so they can't be iterated at lint time. This object mirrors them as a
+ * runtime value; the `satisfies Record<WebhookSetupMethodNames, true>` ties it to
+ * the source of truth — adding, removing, or renaming a method upstream breaks
+ * type-checking here until this list is updated.
+ */
+const LIFECYCLE_METHOD_SET = {
+	checkExists: true,
+	create: true,
+	delete: true,
+} as const satisfies Record<WebhookSetupMethodNames, true>;
+
+/** The webhook trigger lifecycle methods, in the order n8n invokes them. */
+export const WEBHOOK_LIFECYCLE_METHODS = Object.keys(
+	LIFECYCLE_METHOD_SET,
+) as readonly WebhookLifecycleMethod[];

package/src/utils/credential-fields.ts

@@ -0,0 +1,57 @@
+import { TSESTree } from '@typescript-eslint/utils';
+
+import { findObjectProperty, getBooleanLiteralValue } from './ast-utils.js';
+
+const SENSITIVE_PATTERNS = [
+	'password',
+	'secret',
+	'token',
+	'cert',
+	'passphrase',
+	'apikey',
+	'secretkey',
+	'privatekey',
+	'authkey',
+];
+
+const NON_SENSITIVE_PATTERNS = ['url', 'pub', 'id'];
+
+/**
+ * Whether a name looks like it holds a secret. A name is sensitive when it
+ * contains a sensitive pattern (or a caller-supplied `extra` one) and none of
+ * the `exclusions`. Exclusions win, so under the default set `tokenUrl` and
+ * `secretId` are not sensitive even though they contain `token`/`secret`.
+ *
+ * - Credential-field masking uses the default exclusions (a field named
+ *   `tokenUrl` is a URL, not a secret to mask).
+ * - Pass `exclusions: []` to match on the raw patterns alone, e.g. when a
+ *   second gate (like a value heuristic) already guards against false positives.
+ * - Pass `extra` to add caller-specific patterns without widening the shared set.
+ */
+export function isSensitiveName(
+	name: string,
+	options: { extra?: string[]; exclusions?: string[] } = {},
+): boolean {
+	const { extra = [], exclusions = NON_SENSITIVE_PATTERNS } = options;
+	const lowerName = name.toLowerCase();
+
+	if (exclusions.some((pattern) => lowerName.includes(pattern))) {
+		return false;
+	}
+
+	return [...SENSITIVE_PATTERNS, ...extra].some((pattern) => lowerName.includes(pattern));
+}
+
+/** Whether the credential field element sets `typeOptions: { password: true }`. */
+export function hasPasswordTypeOption(element: TSESTree.ObjectExpression): boolean {
+	const typeOptionsProperty = findObjectProperty(element, 'typeOptions');
+
+	if (typeOptionsProperty?.value.type !== TSESTree.AST_NODE_TYPES.ObjectExpression) {
+		return false;
+	}
+
+	const passwordProperty = findObjectProperty(typeOptionsProperty.value, 'password');
+	const passwordValue = passwordProperty ? getBooleanLiteralValue(passwordProperty.value) : null;
+
+	return passwordValue === true;
+}

package/src/utils/file-utils.ts

@@ -238,6 +238,29 @@ export function findNodeSourceFilesOnDisk(packageJsonPath: string): string[] {
 	return findFilesRecursively(nodesDir, (fileName) => fileName.endsWith('.node.ts'));
 }
 
+/**
+ * Recursively finds files matching `matches` within the given subdirectories of
+ * the package (relative to its `package.json`). Missing subdirectories are
+ * skipped. Returns absolute paths.
+ */
+export function findFilesInPackageDirs(
+	packageJsonPath: string,
+	dirs: string[],
+	matches: (fileName: string) => boolean,
+): string[] {
+	const packageDir = dirname(packageJsonPath);
+	const results: string[] = [];
+
+	for (const dir of dirs) {
+		const fullPath = safeJoinPath(packageDir, dir);
+		if (existsSync(fullPath)) {
+			results.push(...findFilesRecursively(fullPath, matches));
+		}
+	}
+
+	return results;
+}
+
 export function areAllCredentialUsagesTestedByNodes(
 	credentialName: string,
 	packageDir: string,

package/src/utils/index.ts

@@ -1,3 +1,5 @@
 export * from './ast-utils.js';
+export * from './credential-fields.js';
+export * from './constants.js';
 export * from './file-utils.js';
 export * from './rule-creator.js';