feat(editor): Improve manual description in nodes as tools (#15373)

packages/workflow/src/NodeHelpers.ts

@@ -40,6 +40,7 @@ import type {
 import { validateFilterParameter } from './NodeParameters/FilterParameter';
 import {
 	isFilterValue,
+	isINodePropertyOptionsList,
 	isResourceLocatorValue,
 	isResourceMapperValue,
 	isValidResourceLocatorParameterValue,
@@ -1569,6 +1570,91 @@ export function isNodeWithWorkflowSelector(node: INode) {
 	return [EXECUTE_WORKFLOW_NODE_TYPE, WORKFLOW_TOOL_LANGCHAIN_NODE_TYPE].includes(node.type);
 }
 
+/**
+ * Generates a human-readable description for a node based on its parameters and type definition.
+ *
+ * This function creates a descriptive string that represents what the node does,
+ * based on its resource, operation, and node type information. The description is
+ * formatted in one of the following ways:
+ *
+ * 1. "{action} in {displayName}" if the operation has a defined action
+ * 2. "{operation} {resource} in {displayName}" if resource and operation exist
+ * 3. The node type's description field as a fallback
+ */
+export function makeDescription(
+	nodeParameters: INodeParameters,
+	nodeTypeDescription: INodeTypeDescription,
+): string {
+	let description = '';
+	const resource = nodeParameters.resource as string;
+	const operation = nodeParameters.operation as string;
+	const nodeTypeOperation = nodeTypeDescription.properties.find(
+		(p) => p.name === 'operation' && p.displayOptions?.show?.resource?.includes(resource),
+	);
+
+	if (nodeTypeOperation?.options && isINodePropertyOptionsList(nodeTypeOperation.options)) {
+		const foundOperation = nodeTypeOperation.options.find((option) => option.value === operation);
+		if (foundOperation?.action) {
+			description = `${foundOperation.action} in ${nodeTypeDescription.defaults.name}`;
+			return description;
+		}
+	}
+
+	if (!description && resource && operation) {
+		description = `${operation} ${resource} in ${nodeTypeDescription.defaults.name}`;
+	} else {
+		description = nodeTypeDescription.description;
+	}
+
+	return description;
+}
+
+/**
+ * Determines whether a tool description should be updated and returns the new description if needed.
+ * Returns undefined if no update is needed.
+ */
+
+export const getUpdatedToolDescription = (
+	currentNodeType: INodeTypeDescription | null,
+	newParameters: INodeParameters | null,
+	currentParameters?: INodeParameters,
+) => {
+	if (!currentNodeType) return;
+
+	if (newParameters?.descriptionType === 'manual' && currentParameters) {
+		const previousDescription = makeDescription(currentParameters, currentNodeType);
+		const newDescription = makeDescription(newParameters, currentNodeType);
+
+		if (
+			newParameters.toolDescription === previousDescription ||
+			!newParameters.toolDescription?.toString().trim() ||
+			newParameters.toolDescription === currentNodeType.description
+		) {
+			return newDescription;
+		}
+	}
+
+	return;
+};
+
+/**
+ * Generates a tool description for a given node based on its parameters and type.
+ */
+export function getToolDescriptionForNode(node: INode, nodeType: INodeType): string {
+	let toolDescription;
+	if (
+		node.parameters.descriptionType === 'auto' ||
+		!node?.parameters.toolDescription?.toString().trim()
+	) {
+		toolDescription = makeDescription(node.parameters, nodeType.description);
+	} else if (node?.parameters.toolDescription) {
+		toolDescription = node.parameters.toolDescription;
+	} else {
+		toolDescription = nodeType.description.description;
+	}
+	return toolDescription as string;
+}
+
 /**
  * Attempts to retrieve the ID of a subworkflow from a execute workflow node.
  */

packages/workflow/test/NodeHelpers.test.ts

@@ -1,3 +1,4 @@
+import type { INodeType } from '@/index';
 import {
 	NodeConnectionTypes,
 	type NodeConnectionType,
@@ -14,6 +15,9 @@ import {
 	isTriggerNode,
 	isExecutable,
 	displayParameter,
+	makeDescription,
+	getUpdatedToolDescription,
+	getToolDescriptionForNode,
 } from '@/NodeHelpers';
 import type { Workflow } from '@/Workflow';
 
@@ -4774,4 +4778,472 @@ describe('NodeHelpers', () => {
 			});
 		}
 	});
+
+	describe('makeDescription', () => {
+		let mockNodeTypeDescription: INodeTypeDescription;
+
+		beforeEach(() => {
+			// Arrange a basic mock node type description
+			mockNodeTypeDescription = {
+				displayName: 'Test Node',
+				name: 'testNode',
+				icon: 'fa:test',
+				group: ['transform'],
+				version: 1,
+				description: 'This is a test node',
+				defaults: {
+					name: 'Test Node',
+				},
+				inputs: ['main'],
+				outputs: ['main'],
+				properties: [],
+			};
+		});
+
+		test('should return action-based description when action is available', () => {
+			// Arrange
+			const nodeParameters: INodeParameters = {
+				resource: 'user',
+				operation: 'create',
+			};
+
+			mockNodeTypeDescription.properties = [
+				{
+					displayName: 'Operation',
+					name: 'operation',
+					type: 'options',
+					displayOptions: {
+						show: {
+							resource: ['user'],
+						},
+					},
+					options: [
+						{
+							name: 'Create',
+							value: 'create',
+							action: 'Create a new user',
+						},
+					],
+					default: 'create',
+				},
+			];
+
+			// Act
+			const result = makeDescription(nodeParameters, mockNodeTypeDescription);
+
+			// Assert
+			expect(result).toBe('Create a new user in Test Node');
+		});
+
+		test('should return resource-operation-based description when action is not available', () => {
+			// Arrange
+			const nodeParameters: INodeParameters = {
+				resource: 'user',
+				operation: 'create',
+			};
+
+			mockNodeTypeDescription.properties = [
+				{
+					displayName: 'Operation',
+					name: 'operation',
+					type: 'options',
+					displayOptions: {
+						show: {
+							resource: ['user'],
+						},
+					},
+					options: [
+						{
+							name: 'Create',
+							value: 'create',
+							// No action property
+						},
+					],
+					default: 'create',
+				},
+			];
+
+			// Act
+			const result = makeDescription(nodeParameters, mockNodeTypeDescription);
+
+			// Assert
+			expect(result).toBe('create user in Test Node');
+		});
+
+		test('should return default description when resource or operation is missing', () => {
+			// Arrange
+			const nodeParameters: INodeParameters = {
+				// No resource or operation
+			};
+
+			// Act
+			const result = makeDescription(nodeParameters, mockNodeTypeDescription);
+
+			// Assert
+			expect(result).toBe('This is a test node');
+		});
+
+		test('should handle case where nodeTypeOperation is not found', () => {
+			// Arrange
+			const nodeParameters: INodeParameters = {
+				resource: 'user',
+				operation: 'create',
+			};
+
+			mockNodeTypeDescription.properties = [
+				// No matching operation property
+			];
+
+			// Act
+			const result = makeDescription(nodeParameters, mockNodeTypeDescription);
+
+			// Assert
+			expect(result).toBe('create user in Test Node');
+		});
+
+		test('should handle case where options are not a list of INodePropertyOptions', () => {
+			// Arrange
+			const nodeParameters: INodeParameters = {
+				resource: 'user',
+				operation: 'create',
+			};
+
+			mockNodeTypeDescription.properties = [
+				{
+					displayName: 'Operation',
+					name: 'operation',
+					type: 'options',
+					displayOptions: {
+						show: {
+							resource: ['user'],
+						},
+					},
+					// Options are not INodePropertyOptions[]
+					options: [
+						//@ts-expect-error
+						{},
+					],
+					default: 'create',
+				},
+			];
+
+			// Act
+			const result = makeDescription(nodeParameters, mockNodeTypeDescription);
+
+			// Assert
+			expect(result).toBe('create user in Test Node');
+		});
+	});
+
+	describe('getUpdatedToolDescription', () => {
+		let mockNodeTypeDescription: INodeTypeDescription;
+
+		beforeEach(() => {
+			// Arrange a basic mock node type description
+			mockNodeTypeDescription = {
+				displayName: 'Test Node',
+				name: 'testNode',
+				icon: 'fa:test',
+				group: ['transform'],
+				version: 1,
+				description: 'This is a test node',
+				defaults: {
+					name: 'Test Node',
+				},
+				inputs: ['main'],
+				outputs: ['main'],
+				properties: [],
+				usableAsTool: true,
+			};
+		});
+
+		test('should return undefined when descriptionType is not manual', () => {
+			// Arrange
+			const newParameters: INodeParameters = {
+				descriptionType: 'automatic',
+				resource: 'user',
+				operation: 'create',
+			};
+			const currentParameters: INodeParameters = {
+				descriptionType: 'automatic',
+				resource: 'user',
+				operation: 'create',
+			};
+
+			// Act
+			const result = getUpdatedToolDescription(
+				mockNodeTypeDescription,
+				newParameters,
+				currentParameters,
+			);
+
+			// Assert
+			expect(result).toBeUndefined();
+		});
+
+		test('should return new description when toolDescription matches previous description', () => {
+			// Arrange
+			mockNodeTypeDescription.properties = [
+				{
+					displayName: 'Operation',
+					name: 'operation',
+					type: 'options',
+					displayOptions: {
+						show: {
+							resource: ['user'],
+						},
+					},
+					options: [
+						{
+							name: 'Create',
+							value: 'create',
+							action: 'Create a new user',
+						},
+					],
+					default: 'create',
+				},
+			];
+
+			const currentParameters: INodeParameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'create',
+			};
+
+			const newParameters: INodeParameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'update',
+				toolDescription: 'Create a new user in Test Node', // Matches the previous description
+			};
+
+			// Act
+			const result = getUpdatedToolDescription(
+				mockNodeTypeDescription,
+				newParameters,
+				currentParameters,
+			);
+
+			// Assert
+			expect(result).toBe('update user in Test Node');
+		});
+
+		test('should return new description when toolDescription matches node type description', () => {
+			// Arrange
+			const currentParameters: INodeParameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'create',
+			};
+
+			const newParameters: INodeParameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'update',
+				toolDescription: 'This is a test node', // Matches the node type description
+			};
+
+			// Act
+			const result = getUpdatedToolDescription(
+				mockNodeTypeDescription,
+				newParameters,
+				currentParameters,
+			);
+
+			// Assert
+			expect(result).toBe('update user in Test Node');
+		});
+
+		test('should return undefined when toolDescription is custom', () => {
+			// Arrange
+			const currentParameters: INodeParameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'create',
+			};
+
+			const newParameters: INodeParameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'update',
+				toolDescription: 'My custom description', // Custom description
+			};
+
+			// Act
+			const result = getUpdatedToolDescription(
+				mockNodeTypeDescription,
+				newParameters,
+				currentParameters,
+			);
+
+			// Assert
+			expect(result).toBeUndefined();
+		});
+
+		test('should return undefined for null inputs', () => {
+			// Act
+			const result = getUpdatedToolDescription(null, null);
+
+			// Assert
+			expect(result).toBeUndefined();
+		});
+
+		test('should return new description when toolDescription is empty or whitespace', () => {
+			// Arrange
+			const currentParameters: INodeParameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'create',
+			};
+
+			const newParameters: INodeParameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'update',
+				toolDescription: '   ', // Empty/whitespace description
+			};
+
+			// Act
+			const result = getUpdatedToolDescription(
+				mockNodeTypeDescription,
+				newParameters,
+				currentParameters,
+			);
+
+			// Assert
+			expect(result).toBe('update user in Test Node');
+		});
+	});
+
+	describe('getToolDescriptionForNode', () => {
+		let mockNode: INode;
+		let mockNodeType: INodeType;
+
+		beforeEach(() => {
+			// Arrange a basic mock node
+			mockNode = {
+				id: 'test-node-id',
+				name: 'Test Node',
+				typeVersion: 1,
+				type: 'test-node-type',
+				position: [0, 0],
+				parameters: {},
+			};
+
+			// Arrange a basic mock node type
+			mockNodeType = {
+				description: {
+					displayName: 'Test Node Type',
+					name: 'testNodeType',
+					icon: 'fa:test',
+					group: ['transform'],
+					version: 1,
+					description: 'This is the default node description',
+					defaults: {
+						name: 'Test Node Type',
+					},
+					inputs: ['main'],
+					outputs: ['main'],
+					properties: [],
+				},
+			} as INodeType;
+		});
+
+		test('should use generated description when descriptionType is auto', () => {
+			// Arrange
+			mockNode.parameters = {
+				descriptionType: 'auto',
+				resource: 'user',
+				operation: 'create',
+			};
+
+			mockNodeType.description.properties = [
+				{
+					displayName: 'Operation',
+					name: 'operation',
+					type: 'options',
+					displayOptions: {
+						show: {
+							resource: ['user'],
+						},
+					},
+					options: [
+						{
+							name: 'Create',
+							value: 'create',
+							action: 'Create a new user',
+						},
+					],
+					default: 'create',
+				},
+			];
+
+			// Act
+			const result = getToolDescriptionForNode(mockNode, mockNodeType);
+
+			// Assert
+			expect(result).toBe('Create a new user in Test Node Type');
+		});
+
+		test('should use generated description when toolDescription is empty', () => {
+			// Arrange
+			mockNode.parameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'create',
+				toolDescription: '',
+			};
+
+			// Act
+			const result = getToolDescriptionForNode(mockNode, mockNodeType);
+
+			// Assert
+			expect(result).toBe('create user in Test Node Type');
+		});
+
+		test('should use generated description when toolDescription is only whitespace', () => {
+			// Arrange
+			mockNode.parameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'create',
+				toolDescription: '   ',
+			};
+
+			// Act
+			const result = getToolDescriptionForNode(mockNode, mockNodeType);
+
+			// Assert
+			expect(result).toBe('create user in Test Node Type');
+		});
+
+		test('should use custom toolDescription when it exists', () => {
+			// Arrange
+			mockNode.parameters = {
+				descriptionType: 'manual',
+				resource: 'user',
+				operation: 'create',
+				toolDescription: 'My custom description',
+			};
+
+			// Act
+			const result = getToolDescriptionForNode(mockNode, mockNodeType);
+
+			// Assert
+			expect(result).toBe('My custom description');
+		});
+
+		test('should fall back to node type description when toolDescription is undefined', () => {
+			// Arrange
+			mockNode.parameters = {
+				descriptionType: 'manual',
+			};
+
+			// Act
+			const result = getToolDescriptionForNode(mockNode, mockNodeType);
+
+			// Assert
+			expect(result).toBe('This is the default node description');
+		});
+	});
 });