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

package/src/rules/n8n-object-validation.ts

@@ -0,0 +1,200 @@
+import type { TSESLint, TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import { createRule, findJsonProperty, getTopLevelObjectInJson } from '../utils/index.js';
+
+type MessageIds =
+	| 'missingN8nObject'
+	| 'wrongLocationApiVersion'
+	| 'missingNodesApiVersion'
+	| 'invalidNodesApiVersion'
+	| 'missingN8nNodes'
+	| 'n8nNodesNotArray'
+	| 'emptyN8nNodes'
+	| 'n8nCredentialsNotArray'
+	| 'nodePathNotString'
+	| 'nodePathNotInDist'
+	| 'credentialPathNotString'
+	| 'credentialPathNotInDist'
+	| 'invalidStrict';
+
+type Context = TSESLint.RuleContext<MessageIds, []>;
+
+export const N8nObjectValidationRule = createRule<[], MessageIds>({
+	name: 'n8n-object-validation',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Validate the structure of the "n8n" object in community node package.json (required keys, types, and dist/ paths)',
+		},
+		messages: {
+			missingN8nObject:
+				'Community node package.json must contain an "n8n" object describing the package.',
+			wrongLocationApiVersion:
+				'"n8nNodesApiVersion" must be inside the "n8n" section, not at the root level of package.json.',
+			missingNodesApiVersion:
+				'The "n8n" object must declare "n8nNodesApiVersion" (a positive integer).',
+			invalidNodesApiVersion:
+				'"n8n.n8nNodesApiVersion" must be a positive integer, got {{ value }}.',
+			missingN8nNodes: 'The "n8n" object must declare "nodes" as an array of "dist/" paths.',
+			n8nNodesNotArray: '"n8n.nodes" must be an array of "dist/" paths.',
+			emptyN8nNodes: '"n8n.nodes" must contain at least one path.',
+			n8nCredentialsNotArray: '"n8n.credentials" must be an array of "dist/" paths.',
+			nodePathNotString: 'Each entry in "n8n.nodes" must be a string starting with "dist/".',
+			nodePathNotInDist:
+				'Path "{{ path }}" in "n8n.nodes" must start with "dist/" (compiled output).',
+			credentialPathNotString:
+				'Each entry in "n8n.credentials" must be a string starting with "dist/".',
+			credentialPathNotInDist:
+				'Path "{{ path }}" in "n8n.credentials" must start with "dist/" (compiled output).',
+			invalidStrict: '"n8n.strict" must be a boolean, got {{ value }}.',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!context.filename.endsWith('package.json')) {
+			return {};
+		}
+
+		return {
+			ObjectExpression(node: TSESTree.ObjectExpression) {
+				const root = getTopLevelObjectInJson(node);
+				if (!root) return;
+
+				// Catch n8nNodesApiVersion accidentally placed at root level.
+				const rootApiVersionProp = findJsonProperty(root, 'n8nNodesApiVersion');
+				if (rootApiVersionProp) {
+					context.report({
+						node: rootApiVersionProp,
+						messageId: 'wrongLocationApiVersion',
+					});
+				}
+
+				const n8nProp = findJsonProperty(root, 'n8n');
+				if (!n8nProp) {
+					context.report({
+						node: root,
+						messageId: 'missingN8nObject',
+					});
+					return;
+				}
+
+				if (n8nProp.value.type !== AST_NODE_TYPES.ObjectExpression) {
+					context.report({
+						node: n8nProp,
+						messageId: 'missingN8nObject',
+					});
+					return;
+				}
+
+				const n8nObject = n8nProp.value;
+
+				validateApiVersion(context, n8nObject);
+				validateNodes(context, n8nObject);
+				validateCredentials(context, n8nObject);
+				validateStrict(context, n8nObject);
+			},
+		};
+	},
+});
+
+function validateApiVersion(context: Context, n8nObject: TSESTree.ObjectExpression): void {
+	const apiVersionProp = findJsonProperty(n8nObject, 'n8nNodesApiVersion');
+	if (!apiVersionProp) {
+		context.report({ node: n8nObject, messageId: 'missingNodesApiVersion' });
+		return;
+	}
+
+	const valueNode = apiVersionProp.value;
+	if (valueNode.type !== AST_NODE_TYPES.Literal || !isPositiveInteger(valueNode.value)) {
+		context.report({
+			node: apiVersionProp,
+			messageId: 'invalidNodesApiVersion',
+			data: {
+				value: String(valueNode.type === AST_NODE_TYPES.Literal ? valueNode.value : 'non-literal'),
+			},
+		});
+	}
+}
+
+function validateStrict(context: Context, n8nObject: TSESTree.ObjectExpression): void {
+	const strictProp = findJsonProperty(n8nObject, 'strict');
+	if (!strictProp) return; // optional
+
+	const valueNode = strictProp.value;
+	if (valueNode.type !== AST_NODE_TYPES.Literal || typeof valueNode.value !== 'boolean') {
+		context.report({
+			node: strictProp,
+			messageId: 'invalidStrict',
+			data: {
+				value: String(valueNode.type === AST_NODE_TYPES.Literal ? valueNode.value : 'non-literal'),
+			},
+		});
+	}
+}
+
+function validateNodes(context: Context, n8nObject: TSESTree.ObjectExpression): void {
+	const nodesProp = findJsonProperty(n8nObject, 'nodes');
+	if (!nodesProp) {
+		context.report({ node: n8nObject, messageId: 'missingN8nNodes' });
+		return;
+	}
+
+	if (nodesProp.value.type !== AST_NODE_TYPES.ArrayExpression) {
+		context.report({ node: nodesProp, messageId: 'n8nNodesNotArray' });
+		return;
+	}
+
+	const elements = nodesProp.value.elements;
+	if (elements.length === 0) {
+		context.report({ node: nodesProp, messageId: 'emptyN8nNodes' });
+		return;
+	}
+
+	validatePathArray(context, elements, 'nodePathNotString', 'nodePathNotInDist');
+}
+
+function validateCredentials(context: Context, n8nObject: TSESTree.ObjectExpression): void {
+	const credentialsProp = findJsonProperty(n8nObject, 'credentials');
+	if (!credentialsProp) return; // optional
+
+	if (credentialsProp.value.type !== AST_NODE_TYPES.ArrayExpression) {
+		context.report({ node: credentialsProp, messageId: 'n8nCredentialsNotArray' });
+		return;
+	}
+
+	validatePathArray(
+		context,
+		credentialsProp.value.elements,
+		'credentialPathNotString',
+		'credentialPathNotInDist',
+	);
+}
+
+function validatePathArray(
+	context: Context,
+	elements: TSESTree.ArrayExpression['elements'],
+	notStringMessageId: 'nodePathNotString' | 'credentialPathNotString',
+	notInDistMessageId: 'nodePathNotInDist' | 'credentialPathNotInDist',
+): void {
+	for (const element of elements) {
+		if (!element) continue;
+		if (element.type !== AST_NODE_TYPES.Literal || typeof element.value !== 'string') {
+			context.report({ node: element, messageId: notStringMessageId });
+			continue;
+		}
+		if (!element.value.startsWith('dist/')) {
+			context.report({
+				node: element,
+				messageId: notInDistMessageId,
+				data: { path: element.value },
+			});
+		}
+	}
+}
+
+function isPositiveInteger(value: unknown): boolean {
+	return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}

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

@@ -0,0 +1,84 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { NoBuilderHintLeakageRule } from './no-builder-hint-leakage.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('no-builder-hint-leakage', NoBuilderHintLeakageRule, {
+	valid: [
+		{
+			name: 'builderHint with no forbidden patterns',
+			code: 'const x = { builderHint: { propertyHint: "use expr() to embed expressions" } };',
+		},
+		{
+			name: 'builderHint using expr() form in example',
+			code: 'const x = { builderHint: { propertyHint: "e.g. expr(\'{{ $json.field }}\')" } };',
+		},
+		{
+			name: 'connection-type names as keys are allowed (wire-format structural data)',
+			code: 'const x = { builderHint: { inputs: { ai_languageModel: { required: true } } } };',
+		},
+		{
+			name: 'wire-format ={{ ... }} outside builderHint is fine in default scope',
+			code: "const inputs = '={{ $parameter.foo }}';",
+		},
+		{
+			name: 'connection-type literal outside builderHint is fine in default scope',
+			code: "const requires = ['ai_languageModel'];",
+		},
+		{
+			name: 'with scope=all, connection-type as key is still allowed',
+			code: "const inputs = { ai_languageModel: 'required' };",
+			options: [{ scope: 'all' }],
+		},
+		{
+			name: 'with scope=all, exact connection-type as value is allowed (structured data)',
+			code: "const config = { connectionType: 'ai_languageModel' };",
+			options: [{ scope: 'all' }],
+		},
+		{
+			name: 'with scope=all, connection-type in array of literals is allowed',
+			code: "const required = ['ai_tool', 'ai_memory'];",
+			options: [{ scope: 'all' }],
+		},
+	],
+	invalid: [
+		{
+			name: 'wire-format ={{ ... }} inside builderHint message',
+			code: 'const x = { builderHint: { propertyHint: "e.g. ={{ $json.field }}" } };',
+			errors: [{ messageId: 'wireExpression' }],
+		},
+		{
+			name: 'wire-format ={{ ... }} inside template literal in builderHint',
+			code: 'const x = { builderHint: { propertyHint: `e.g. ={{ $json.field }}` } };',
+			errors: [{ messageId: 'wireExpression' }],
+		},
+		{
+			name: 'connection-type literal inside builderHint message',
+			code: 'const x = { builderHint: { searchHint: "requires ai_languageModel" } };',
+			errors: [{ messageId: 'connectionTypeLiteral' }],
+		},
+		{
+			name: 'multiple connection-type literals in one string',
+			code: 'const x = { builderHint: { propertyHint: "needs ai_languageModel and ai_tool" } };',
+			errors: [{ messageId: 'connectionTypeLiteral' }, { messageId: 'connectionTypeLiteral' }],
+		},
+		{
+			name: 'wire-format inside nested builderHint structure',
+			code: 'const x = { description: { builderHint: { tip: { message: "={{ $json.x }}" } } } };',
+			errors: [{ messageId: 'wireExpression' }],
+		},
+		{
+			name: 'with scope=all, wire-format anywhere is flagged',
+			code: 'const prompt = "use ={{ $json.foo }} pattern";',
+			options: [{ scope: 'all' }],
+			errors: [{ messageId: 'wireExpression' }],
+		},
+		{
+			name: 'with scope=all, connection-type literal in any string is flagged',
+			code: 'const prompt = "Connect via ai_tool to AI Agent";',
+			options: [{ scope: 'all' }],
+			errors: [{ messageId: 'connectionTypeLiteral' }],
+		},
+	],
+});

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-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 },
+				});
+			},
+		};
+	},
+});