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

package/src/rules/cred-class-oauth2-naming.ts

@@ -0,0 +1,118 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+import {
+	createRule,
+	findClassProperty,
+	getStringLiteralValue,
+	isCredentialTypeClass,
+	isFileType,
+} from '../utils/index.js';
+
+const OAUTH2_PATTERN = /oauth2/i;
+
+function containsOAuth2(value: string): boolean {
+	return OAUTH2_PATTERN.test(value);
+}
+
+function getExtendsArrayValues(node: TSESTree.PropertyDefinition): string[] {
+	if (node.value?.type !== AST_NODE_TYPES.ArrayExpression) return [];
+	const values: string[] = [];
+	for (const element of node.value.elements) {
+		const value = element ? getStringLiteralValue(element) : null;
+		if (value !== null) values.push(value);
+	}
+	return values;
+}
+
+function suggestOAuth2ApiName(className: string): string {
+	if (className.endsWith('Api')) {
+		return `${className.slice(0, -'Api'.length)}OAuth2Api`;
+	}
+	return `${className}OAuth2Api`;
+}
+
+export const CredClassOAuth2NamingRule = createRule({
+	name: 'cred-class-oauth2-naming',
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'OAuth2 credentials must include `OAuth2` in the class name, `name`, and `displayName`',
+		},
+		messages: {
+			classNameMissingOAuth2: "OAuth2 credential class name '{{name}}' must end with 'OAuth2Api'",
+			nameMissingOAuth2: "OAuth2 credential `name` field '{{value}}' must contain 'OAuth2'",
+			displayNameMissingOAuth2:
+				"OAuth2 credential `displayName` field '{{value}}' must contain 'OAuth2'",
+		},
+		schema: [],
+		fixable: 'code',
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!isFileType(context.filename, '.credentials.ts')) {
+			return {};
+		}
+
+		return {
+			ClassDeclaration(node) {
+				if (!isCredentialTypeClass(node)) return;
+				if (!node.id) return;
+
+				const className = node.id.name;
+				const superClassName =
+					node.superClass?.type === AST_NODE_TYPES.Identifier ? node.superClass.name : null;
+
+				const nameProperty = findClassProperty(node, 'name');
+				const nameValue = nameProperty?.value ? getStringLiteralValue(nameProperty.value) : null;
+
+				const displayNameProperty = findClassProperty(node, 'displayName');
+				const displayNameValue = displayNameProperty?.value
+					? getStringLiteralValue(displayNameProperty.value)
+					: null;
+
+				const extendsProperty = findClassProperty(node, 'extends');
+				const extendsValues = extendsProperty ? getExtendsArrayValues(extendsProperty) : [];
+
+				const isOAuth2Credential =
+					containsOAuth2(className) ||
+					(superClassName !== null && containsOAuth2(superClassName)) ||
+					extendsValues.some(containsOAuth2) ||
+					(nameValue !== null && containsOAuth2(nameValue)) ||
+					(displayNameValue !== null && containsOAuth2(displayNameValue));
+
+				if (!isOAuth2Credential) return;
+
+				if (!className.endsWith('OAuth2Api')) {
+					const fixedClassName = suggestOAuth2ApiName(className);
+
+					context.report({
+						node: node.id,
+						messageId: 'classNameMissingOAuth2',
+						data: { name: className },
+						fix(fixer) {
+							return fixer.replaceText(node.id!, fixedClassName);
+						},
+					});
+				}
+
+				if (nameValue !== null && !containsOAuth2(nameValue)) {
+					context.report({
+						node: nameProperty!.value!,
+						messageId: 'nameMissingOAuth2',
+						data: { value: nameValue },
+					});
+				}
+
+				if (displayNameValue !== null && !containsOAuth2(displayNameValue)) {
+					context.report({
+						node: displayNameProperty!.value!,
+						messageId: 'displayNameMissingOAuth2',
+						data: { value: displayNameValue },
+					});
+				}
+			},
+		};
+	},
+});

package/src/rules/index.ts

@@ -2,11 +2,15 @@ import type { AnyRuleModule } from '@typescript-eslint/utils/ts-eslint';
 
 import { AiNodePackageJsonRule } from './ai-node-package-json.js';
 import { CredClassFieldIconMissingRule } from './cred-class-field-icon-missing.js';
+import { CredClassNameSuffixRule } from './cred-class-name-suffix.js';
+import { CredClassOAuth2NamingRule } from './cred-class-oauth2-naming.js';
 import { CredentialDocumentationUrlRule } from './credential-documentation-url.js';
 import { CredentialPasswordFieldRule } from './credential-password-field.js';
 import { CredentialTestRequiredRule } from './credential-test-required.js';
 import { IconValidationRule } from './icon-validation.js';
 import { MissingPairedItemRule } from './missing-paired-item.js';
+import { N8nObjectValidationRule } from './n8n-object-validation.js';
+import { NoBuilderHintLeakageRule } from './no-builder-hint-leakage.js';
 import { NoCredentialReuseRule } from './no-credential-reuse.js';
 import { NoDeprecatedWorkflowFunctionsRule } from './no-deprecated-workflow-functions.js';
 import { NoForbiddenLifecycleScriptsRule } from './no-forbidden-lifecycle-scripts.js';
@@ -14,8 +18,11 @@ import { NoHttpRequestWithManualAuthRule } from './no-http-request-with-manual-a
 import { NoOverridesFieldRule } from './no-overrides-field.js';
 import { NoRestrictedGlobalsRule } from './no-restricted-globals.js';
 import { NoRestrictedImportsRule } from './no-restricted-imports.js';
+import { NoRuntimeDependenciesRule } from './no-runtime-dependencies.js';
+import { NoTemplatePlaceholdersRule } from './no-template-placeholders.js';
 import { NodeClassDescriptionIconMissingRule } from './node-class-description-icon-missing.js';
 import { NodeConnectionTypeLiteralRule } from './node-connection-type-literal.js';
+import { NodeOperationErrorItemIndexRule } from './node-operation-error-itemindex.js';
 import { NodeUsableAsToolRule } from './node-usable-as-tool.js';
 import { OptionsSortedAlphabeticallyRule } from './options-sorted-alphabetically.js';
 import { PackageNameConventionRule } from './package-name-convention.js';
@@ -24,6 +31,7 @@ import { RequireContinueOnFailRule } from './require-continue-on-fail.js';
 import { RequireNodeApiErrorRule } from './require-node-api-error.js';
 import { RequireNodeDescriptionFieldsRule } from './require-node-description-fields.js';
 import { ResourceOperationPatternRule } from './resource-operation-pattern.js';
+import { ValidCredentialReferencesRule } from './valid-credential-references.js';
 import { ValidPeerDependenciesRule } from './valid-peer-dependencies.js';
 import { WebhookLifecycleCompleteRule } from './webhook-lifecycle-complete.js';
 
@@ -41,17 +49,25 @@ export const rules = {
 	'no-forbidden-lifecycle-scripts': NoForbiddenLifecycleScriptsRule,
 	'no-http-request-with-manual-auth': NoHttpRequestWithManualAuthRule,
 	'no-overrides-field': NoOverridesFieldRule,
+	'no-runtime-dependencies': NoRuntimeDependenciesRule,
+	'no-template-placeholders': NoTemplatePlaceholdersRule,
 	'icon-validation': IconValidationRule,
 	'resource-operation-pattern': ResourceOperationPatternRule,
 	'credential-documentation-url': CredentialDocumentationUrlRule,
 	'node-class-description-icon-missing': NodeClassDescriptionIconMissingRule,
 	'cred-class-field-icon-missing': CredClassFieldIconMissingRule,
+	'cred-class-name-suffix': CredClassNameSuffixRule,
+	'cred-class-oauth2-naming': CredClassOAuth2NamingRule,
 	'node-connection-type-literal': NodeConnectionTypeLiteralRule,
+	'node-operation-error-itemindex': NodeOperationErrorItemIndexRule,
 	'missing-paired-item': MissingPairedItemRule,
+	'no-builder-hint-leakage': NoBuilderHintLeakageRule,
+	'n8n-object-validation': N8nObjectValidationRule,
 	'require-community-node-keyword': RequireCommunityNodeKeywordRule,
 	'require-continue-on-fail': RequireContinueOnFailRule,
 	'require-node-api-error': RequireNodeApiErrorRule,
 	'require-node-description-fields': RequireNodeDescriptionFieldsRule,
+	'valid-credential-references': ValidCredentialReferencesRule,
 	'valid-peer-dependencies': ValidPeerDependenciesRule,
 	'webhook-lifecycle-complete': WebhookLifecycleCompleteRule,
 } satisfies Record<string, AnyRuleModule>;

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

@@ -0,0 +1,202 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { N8nObjectValidationRule } from './n8n-object-validation.js';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('n8n-object-validation', N8nObjectValidationRule, {
+	valid: [
+		{
+			name: 'minimal valid n8n object with one node path',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/nodes/Foo/Foo.node.js"] } }',
+		},
+		{
+			name: 'valid n8n object with credentials',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/nodes/Foo/Foo.node.js"], "credentials": ["dist/credentials/Foo.credentials.js"] } }',
+		},
+		{
+			name: 'empty credentials array is allowed',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"], "credentials": [] } }',
+		},
+		{
+			name: 'higher integer api version is allowed',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 2, "nodes": ["dist/x.js"] } }',
+		},
+		{
+			name: 'non-package.json file is ignored',
+			filename: 'some-config.json',
+			code: '{ "n8n": null }',
+		},
+		{
+			name: 'nested "n8n" key inside another field is allowed (only root is validated)',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"] }, "config": { "n8n": "ignored" } }',
+		},
+		{
+			name: 'objects nested inside arrays are not treated as the package root',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"] }, "contributors": [{ "name": "Jane" }, { "name": "John" }] }',
+		},
+		{
+			name: 'strict is true',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"], "strict": true } }',
+		},
+		{
+			name: 'strict is false',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"], "strict": false } }',
+		},
+		{
+			name: 'strict is omitted (optional field)',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"] } }',
+		},
+	],
+	invalid: [
+		{
+			name: 'missing n8n object entirely',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "version": "1.0.0" }',
+			errors: [{ messageId: 'missingN8nObject' }],
+		},
+		{
+			name: 'n8n value is not an object',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": "not-an-object" }',
+			errors: [{ messageId: 'missingN8nObject' }],
+		},
+		{
+			name: 'missing n8nNodesApiVersion',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "nodes": ["dist/x.js"] } }',
+			errors: [{ messageId: 'missingNodesApiVersion' }],
+		},
+		{
+			name: 'n8nNodesApiVersion is a string',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": "1", "nodes": ["dist/x.js"] } }',
+			errors: [{ messageId: 'invalidNodesApiVersion', data: { value: '1' } }],
+		},
+		{
+			name: 'n8nNodesApiVersion is zero',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 0, "nodes": ["dist/x.js"] } }',
+			errors: [{ messageId: 'invalidNodesApiVersion', data: { value: '0' } }],
+		},
+		{
+			name: 'n8nNodesApiVersion is a float',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1.5, "nodes": ["dist/x.js"] } }',
+			errors: [{ messageId: 'invalidNodesApiVersion', data: { value: '1.5' } }],
+		},
+		{
+			name: 'n8nNodesApiVersion is negative',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": -1, "nodes": ["dist/x.js"] } }',
+			errors: [{ messageId: 'invalidNodesApiVersion' }],
+		},
+		{
+			name: 'n8nNodesApiVersion at root level instead of inside n8n',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8nNodesApiVersion": 1, "n8n": { "nodes": ["dist/x.js"] } }',
+			errors: [{ messageId: 'wrongLocationApiVersion' }, { messageId: 'missingNodesApiVersion' }],
+		},
+		{
+			name: 'missing nodes array',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1 } }',
+			errors: [{ messageId: 'missingN8nNodes' }],
+		},
+		{
+			name: 'nodes is not an array',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": "dist/x.js" } }',
+			errors: [{ messageId: 'n8nNodesNotArray' }],
+		},
+		{
+			name: 'nodes is empty array',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": [] } }',
+			errors: [{ messageId: 'emptyN8nNodes' }],
+		},
+		{
+			name: 'node path does not start with dist/',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["nodes/Foo/Foo.node.js"] } }',
+			errors: [{ messageId: 'nodePathNotInDist', data: { path: 'nodes/Foo/Foo.node.js' } }],
+		},
+		{
+			name: 'node path uses ./dist/ prefix instead of dist/',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["./dist/x.js"] } }',
+			errors: [{ messageId: 'nodePathNotInDist', data: { path: './dist/x.js' } }],
+		},
+		{
+			name: 'node path with wrong casing',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["DIST/x.js"] } }',
+			errors: [{ messageId: 'nodePathNotInDist', data: { path: 'DIST/x.js' } }],
+		},
+		{
+			name: 'node path is not a string',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": [123] } }',
+			errors: [{ messageId: 'nodePathNotString' }],
+		},
+		{
+			name: 'multiple bad node paths each report',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/ok.js", "bad/one.js", "./dist/two.js"] } }',
+			errors: [
+				{ messageId: 'nodePathNotInDist', data: { path: 'bad/one.js' } },
+				{ messageId: 'nodePathNotInDist', data: { path: './dist/two.js' } },
+			],
+		},
+		{
+			name: 'credentials is not an array',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"], "credentials": "dist/c.js" } }',
+			errors: [{ messageId: 'n8nCredentialsNotArray' }],
+		},
+		{
+			name: 'credential path does not start with dist/',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"], "credentials": ["credentials/Foo.credentials.js"] } }',
+			errors: [
+				{
+					messageId: 'credentialPathNotInDist',
+					data: { path: 'credentials/Foo.credentials.js' },
+				},
+			],
+		},
+		{
+			name: 'credential path is not a string',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"], "credentials": [true] } }',
+			errors: [{ messageId: 'credentialPathNotString' }],
+		},
+		{
+			name: 'strict is a string',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"], "strict": "true" } }',
+			errors: [{ messageId: 'invalidStrict', data: { value: 'true' } }],
+		},
+		{
+			name: 'strict is a number',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"], "strict": 1 } }',
+			errors: [{ messageId: 'invalidStrict', data: { value: '1' } }],
+		},
+		{
+			name: 'strict is null',
+			filename: 'package.json',
+			code: '{ "name": "n8n-nodes-example", "n8n": { "n8nNodesApiVersion": 1, "nodes": ["dist/x.js"], "strict": null } }',
+			errors: [{ messageId: 'invalidStrict', data: { value: 'null' } }],
+		},
+	],
+});

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