@n8n/eslint-plugin-community-nodes 0.14.0 → 0.16.0

package/src/rules/no-builder-hint-leakage.ts

@@ -0,0 +1,112 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+import type { TSESTree } from '@typescript-eslint/utils';
+
+import { createRule } from '../utils/index.js';
+
+const WIRE_EXPRESSION_RE = /={{/;
+const CONNECTION_NAME_GROUP =
+	'agent|chain|document|embedding|languageModel|memory|outputParser|retriever|reranker|textSplitter|tool|vectorStore';
+const CONNECTION_NAME_RE = new RegExp(`\\bai_(${CONNECTION_NAME_GROUP})\\b`, 'g');
+// Strings that are *exactly* a connection name are structured data values,
+// not prose, so they're allowed (e.g. `connectionType: 'ai_languageModel'`).
+const EXACT_CONNECTION_NAME_RE = new RegExp(`^ai_(${CONNECTION_NAME_GROUP})$`);
+
+type Options = [{ scope?: 'builderHint' | 'all' }];
+type MessageIds = 'wireExpression' | 'connectionTypeLiteral';
+
+function isPropertyKey(node: TSESTree.Node): boolean {
+	const parent = node.parent;
+	return parent?.type === AST_NODE_TYPES.Property && parent.key === node;
+}
+
+function isInsideBuilderHintValue(node: TSESTree.Node): boolean {
+	let current: TSESTree.Node | undefined = node;
+	let parent = current.parent;
+	while (parent) {
+		if (
+			parent.type === AST_NODE_TYPES.Property &&
+			parent.value === current &&
+			((parent.key.type === AST_NODE_TYPES.Identifier && parent.key.name === 'builderHint') ||
+				(parent.key.type === AST_NODE_TYPES.Literal && parent.key.value === 'builderHint'))
+		) {
+			return true;
+		}
+		current = parent;
+		parent = current.parent;
+	}
+	return false;
+}
+
+export const NoBuilderHintLeakageRule = createRule<Options, MessageIds>({
+	name: 'no-builder-hint-leakage',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Disallow wire-format expression syntax (={{...}}) and NodeConnectionType string literals in builderHint texts and AI-builder prompts. Use expr() and SDK-canonical references instead.',
+		},
+		messages: {
+			wireExpression:
+				'Wire-format expression syntax leaks into {{ ctx }}. Use the expr() SDK helper instead.',
+			connectionTypeLiteral:
+				'NodeConnectionType literal "{{ value }}" leaks wire format into {{ ctx }}. Refer to the SDK helper instead (e.g. languageModel(), tool(), memory()).',
+		},
+		schema: [
+			{
+				type: 'object',
+				description:
+					'Configures where the rule scans for forbidden patterns. Default `builderHint` only checks string values inside builderHint property values; `all` checks every string in the file (used for AI-builder prompts).',
+				properties: {
+					scope: {
+						type: 'string',
+						enum: ['builderHint', 'all'],
+						description:
+							'`builderHint` (default): only flag strings inside builderHint property values. `all`: flag every string literal/template in the file.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+	},
+	defaultOptions: [{}],
+	create(context, [options]) {
+		const scope = options.scope ?? 'builderHint';
+		const ctx = scope === 'all' ? 'AI-builder prompt' : 'builderHint';
+
+		function reportFor(node: TSESTree.Node, str: string): void {
+			if (WIRE_EXPRESSION_RE.test(str)) {
+				context.report({ node, messageId: 'wireExpression', data: { ctx } });
+			}
+			if (EXACT_CONNECTION_NAME_RE.test(str)) return;
+			CONNECTION_NAME_RE.lastIndex = 0;
+			let match: RegExpExecArray | null;
+			while ((match = CONNECTION_NAME_RE.exec(str)) !== null) {
+				context.report({
+					node,
+					messageId: 'connectionTypeLiteral',
+					data: { value: match[0], ctx },
+				});
+			}
+		}
+
+		function shouldCheck(node: TSESTree.Node): boolean {
+			if (isPropertyKey(node)) return false;
+			if (scope === 'all') return true;
+			return isInsideBuilderHintValue(node);
+		}
+
+		return {
+			Literal(node) {
+				if (typeof node.value !== 'string') return;
+				if (!shouldCheck(node)) return;
+				reportFor(node, node.value);
+			},
+			TemplateLiteral(node) {
+				if (!shouldCheck(node)) return;
+				for (const quasi of node.quasis) {
+					reportFor(quasi, quasi.value.cooked ?? quasi.value.raw);
+				}
+			},
+		};
+	},
+});

package/src/rules/no-overrides-field.ts

@@ -12,7 +12,7 @@ export const NoOverridesFieldRule = createRule({
 		},
 		messages: {
 			overridesForbidden:
-				'The "overrides" field is not allowed in community node packages. Dependency overrides can introduce incompatible versions of shared libraries into the n8n runtime and cause conflicts with other nodes.',
+				'The "overrides" field is not allowed in community node packages. Each community package installs into an isolated dependency tree, so overrides do not affect other nodes or n8n core — in practice they are copy-pasted boilerplate with no useful effect. Use the helpers on the execute context (this.helpers.httpRequest, etc.) instead; most community nodes do not need third-party runtime libraries.',
 		},
 		schema: [],
 	},

package/src/rules/no-runtime-dependencies.test.ts

@@ -0,0 +1,50 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { NoRuntimeDependenciesRule } from './no-runtime-dependencies.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('no-runtime-dependencies', NoRuntimeDependenciesRule, {
+	valid: [
+		{
+			name: 'no dependencies field',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+		},
+		{
+			name: 'empty dependencies object is allowed',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "dependencies": {} }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "dependencies": { "axios": "1.0.0" } }',
+		},
+		{
+			name: 'nested "dependencies" key inside another field is allowed',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "config": { "dependencies": { "axios": "1.0.0" } } }',
+		},
+	],
+	invalid: [
+		{
+			name: 'single runtime dependency is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "dependencies": { "axios": "1.0.0" } }',
+			errors: [{ messageId: 'runtimeDependenciesForbidden' }],
+		},
+		{
+			name: 'multiple runtime dependencies are forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "dependencies": { "axios": "1.0.0", "lodash": "^4.0.0" } }',
+			errors: [{ messageId: 'runtimeDependenciesForbidden' }],
+		},
+		{
+			name: 'real-world package with bundled deps is forbidden',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-sinch", "dependencies": { "axios": "1.7.0", "fast-xml-parser": "4.4.0", "minimatch": "9.0.5" } }',
+			errors: [{ messageId: 'runtimeDependenciesForbidden' }],
+		},
+	],
+});

package/src/rules/no-runtime-dependencies.ts

@@ -0,0 +1,50 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty } from '../utils/index.js';
+
+export const NoRuntimeDependenciesRule = createRule({
+	name: 'no-runtime-dependencies',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow non-empty "dependencies" in community node package.json',
+		},
+		messages: {
+			runtimeDependenciesForbidden:
+				'The "dependencies" field must be empty or absent in community node packages. Runtime dependencies get bundled into the n8n instance and can conflict with other nodes or the n8n runtime itself. Move shared libraries to "peerDependencies" or bundle them into your build artifact.',
+		},
+		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 depsProp = findJsonProperty(node, 'dependencies');
+				if (!depsProp) {
+					return;
+				}
+
+				if (
+					depsProp.value.type !== AST_NODE_TYPES.ObjectExpression ||
+					depsProp.value.properties.length === 0
+				) {
+					return;
+				}
+
+				context.report({
+					node: depsProp,
+					messageId: 'runtimeDependenciesForbidden',
+				});
+			},
+		};
+	},
+});

package/src/rules/no-template-placeholders.test.ts

@@ -0,0 +1,135 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { NoTemplatePlaceholdersRule } from './no-template-placeholders.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('no-template-placeholders', NoTemplatePlaceholdersRule, {
+	valid: [
+		{
+			name: 'package.json with no placeholders',
+			filename: 'package.json',
+			code: `{
+				"name": "n8n-nodes-example",
+				"version": "1.0.0",
+				"description": "An example community node",
+				"homepage": "https://example.com",
+				"repository": { "type": "git", "url": "git+https://github.com/acme/n8n-nodes-example.git" }
+			}`,
+		},
+		{
+			name: 'angle brackets that do not look like placeholders are ignored',
+			filename: 'package.json',
+			code: '{ "description": "Compares a < b values" }',
+		},
+		{
+			name: 'single curly braces are ignored',
+			filename: 'package.json',
+			code: '{ "description": "Use { key: value } syntax" }',
+		},
+		{
+			name: 'non-package.json file is ignored even if it has placeholders',
+			filename: 'tsconfig.json',
+			code: '{ "name": "<PACKAGE_NAME>" }',
+		},
+		{
+			name: 'numeric and boolean values are not flagged',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "private": false, "engines": { "node": ">=18" } }',
+		},
+	],
+	invalid: [
+		{
+			name: 'angle bracket placeholder in name',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-<PACKAGE_NAME>" }',
+			errors: [
+				{
+					messageId: 'unresolvedPlaceholder',
+					data: { pattern: '<PACKAGE_NAME>' },
+				},
+			],
+		},
+		{
+			name: 'angle bracket placeholder in description',
+			filename: 'package.json',
+			code: '{ "description": "An n8n community node for <SERVICE>" }',
+			errors: [
+				{
+					messageId: 'unresolvedPlaceholder',
+					data: { pattern: '<SERVICE>' },
+				},
+			],
+		},
+		{
+			name: 'angle bracket placeholder in repository url',
+			filename: 'package.json',
+			code: '{ "repository": { "type": "git", "url": "git+https://github.com/<USERNAME>/n8n-nodes-example.git" } }',
+			errors: [
+				{
+					messageId: 'unresolvedPlaceholder',
+					data: { pattern: '<USERNAME>' },
+				},
+			],
+		},
+		{
+			name: 'angle bracket placeholder in homepage',
+			filename: 'package.json',
+			code: '{ "homepage": "https://github.com/<USERNAME>/n8n-nodes-example#readme" }',
+			errors: [
+				{
+					messageId: 'unresolvedPlaceholder',
+					data: { pattern: '<USERNAME>' },
+				},
+			],
+		},
+		{
+			name: 'mustache placeholder in author',
+			filename: 'package.json',
+			code: '{ "author": "{{ authorName }}" }',
+			errors: [
+				{
+					messageId: 'unresolvedPlaceholder',
+					data: { pattern: '{{ authorName }}' },
+				},
+			],
+		},
+		{
+			name: 'mustache placeholder inside larger string',
+			filename: 'package.json',
+			code: '{ "description": "Node by {{author}} for service" }',
+			errors: [
+				{
+					messageId: 'unresolvedPlaceholder',
+					data: { pattern: '{{author}}' },
+				},
+			],
+		},
+		{
+			name: 'placeholder in custom field',
+			filename: 'package.json',
+			code: '{ "n8n": { "n8nNodesApiVersion": 1, "credentials": ["<CREDENTIAL>"] } }',
+			errors: [
+				{
+					messageId: 'unresolvedPlaceholder',
+					data: { pattern: '<CREDENTIAL>' },
+				},
+			],
+		},
+		{
+			name: 'multiple placeholders in different fields are all reported',
+			filename: 'package.json',
+			code: '{ "name": "<NAME>", "description": "{{description}}" }',
+			errors: [
+				{
+					messageId: 'unresolvedPlaceholder',
+					data: { pattern: '<NAME>' },
+				},
+				{
+					messageId: 'unresolvedPlaceholder',
+					data: { pattern: '{{description}}' },
+				},
+			],
+		},
+	],
+});

package/src/rules/no-template-placeholders.ts

@@ -0,0 +1,68 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule } from '../utils/index.js';
+
+const ANGLE_PLACEHOLDER = /<[^<>\n]+?>/;
+const MUSTACHE_PLACEHOLDER = /\{\{[^{}\n]+?\}\}/;
+
+function findPlaceholder(value: string): { pattern: string; type: 'angle' | 'mustache' } | null {
+	const angleMatch = ANGLE_PLACEHOLDER.exec(value);
+	if (angleMatch) {
+		return { pattern: angleMatch[0], type: 'angle' };
+	}
+	const mustacheMatch = MUSTACHE_PLACEHOLDER.exec(value);
+	if (mustacheMatch) {
+		return { pattern: mustacheMatch[0], type: 'mustache' };
+	}
+	return null;
+}
+
+export const NoTemplatePlaceholdersRule = createRule({
+	name: 'no-template-placeholders',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow unresolved template placeholders in package.json',
+		},
+		messages: {
+			unresolvedPlaceholder:
+				'String value contains an unresolved template placeholder "{{ pattern }}". Replace it with a real value before publishing.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			Literal(node: TSESTree.Literal) {
+				if (typeof node.value !== 'string') {
+					return;
+				}
+
+				// Skip property keys — only flag values.
+				if (
+					node.parent?.type === AST_NODE_TYPES.Property &&
+					node.parent.key === node &&
+					!node.parent.computed
+				) {
+					return;
+				}
+
+				const placeholder = findPlaceholder(node.value);
+				if (!placeholder) {
+					return;
+				}
+
+				context.report({
+					node,
+					messageId: 'unresolvedPlaceholder',
+					data: { pattern: placeholder.pattern },
+				});
+			},
+		};
+	},
+});