fix: escape single quotes in descriptions and deprecation reasons (#2924)

* fix: escape single quotes in descriptions and deprecation reasons

* add added/removed message instead for defaulting to 'undefined'

Author: adambenhassen

.changeset/bright-pumas-dance.md

@@ -0,0 +1,7 @@
+---
+"@graphql-inspector/core": patch
+---
+
+Escape single quotes in diff change messages for descriptions and deprecation reasons
+
+Improve description change messages to show "was added" or "was removed" instead of "changed from 'undefined' to X"

packages/core/__tests__/diff/directive.test.ts

@@ -90,11 +90,11 @@ describe('directive', () => {
     // added
     expect(change.b.criticality.level).toEqual(CriticalityLevel.NonBreaking);
     expect(change.b.type).toEqual('DIRECTIVE_DESCRIPTION_CHANGED');
-    expect(change.b.message).toEqual(`Directive 'b' description changed from 'undefined' to 'Bbb'`);
+    expect(change.b.message).toEqual(`Directive 'b' description 'Bbb' was added`);
     // removed
     expect(change.c.criticality.level).toEqual(CriticalityLevel.NonBreaking);
     expect(change.c.type).toEqual('DIRECTIVE_DESCRIPTION_CHANGED');
-    expect(change.c.message).toEqual(`Directive 'c' description changed from 'Ccc' to 'undefined'`);
+    expect(change.c.message).toEqual(`Directive 'c' description 'Ccc' was removed`);
   });
 
   describe('location', () => {

packages/core/src/diff/changes/argument.ts

@@ -1,6 +1,6 @@
 import { GraphQLArgument, GraphQLField, GraphQLInterfaceType, GraphQLObjectType } from 'graphql';
 import { safeChangeForInputValue } from '../../utils/graphql.js';
-import { safeString } from '../../utils/string.js';
+import { fmt, safeString } from '../../utils/string.js';
 import {
   Change,
   ChangeType,
@@ -13,7 +13,13 @@ import {
 function buildFieldArgumentDescriptionChangedMessage(
   args: FieldArgumentDescriptionChangedChange['meta'],
 ): string {
-  return `Description for argument '${args.argumentName}' on field '${args.typeName}.${args.fieldName}' changed from '${args.oldDescription}' to '${args.newDescription}'`;
+  if (args.oldDescription === null && args.newDescription !== null) {
+    return `Description '${fmt(args.newDescription)}' was added to argument '${args.argumentName}' on field '${args.typeName}.${args.fieldName}'`;
+  }
+  if (args.newDescription === null && args.oldDescription !== null) {
+    return `Description '${fmt(args.oldDescription)}' was removed from argument '${args.argumentName}' on field '${args.typeName}.${args.fieldName}'`;
+  }
+  return `Description for argument '${args.argumentName}' on field '${args.typeName}.${args.fieldName}' changed from '${fmt(args.oldDescription ?? '')}' to '${fmt(args.newDescription ?? '')}'`;
 }
 
 export function fieldArgumentDescriptionChangedFromMeta(

packages/core/src/diff/changes/directive.ts

@@ -1,6 +1,6 @@
 import { DirectiveLocationEnum, GraphQLArgument, GraphQLDirective, isNonNullType } from 'graphql';
 import { safeChangeForInputValue } from '../../utils/graphql.js';
-import { safeString } from '../../utils/string.js';
+import { fmt, safeString } from '../../utils/string.js';
 import {
   Change,
   ChangeType,
@@ -82,9 +82,13 @@ export function directiveAdded(
 function buildDirectiveDescriptionChangedMessage(
   args: DirectiveDescriptionChangedChange['meta'],
 ): string {
-  return `Directive '${args.directiveName}' description changed from '${
-    args.oldDirectiveDescription ?? 'undefined'
-  }' to '${args.newDirectiveDescription ?? 'undefined'}'`;
+  if (args.oldDirectiveDescription === null && args.newDirectiveDescription !== null) {
+    return `Directive '${args.directiveName}' description '${fmt(args.newDirectiveDescription)}' was added`;
+  }
+  if (args.newDirectiveDescription === null && args.oldDirectiveDescription !== null) {
+    return `Directive '${args.directiveName}' description '${fmt(args.oldDirectiveDescription)}' was removed`;
+  }
+  return `Directive '${args.directiveName}' description changed from '${fmt(args.oldDirectiveDescription ?? '')}' to '${fmt(args.newDirectiveDescription ?? '')}'`;
 }
 
 export function directiveDescriptionChangedFromMeta(args: DirectiveDescriptionChangedChange) {
@@ -314,7 +318,19 @@ export function directiveArgumentRemoved(
 function buildDirectiveArgumentDescriptionChangedMessage(
   args: DirectiveArgumentDescriptionChangedChange['meta'],
 ): string {
-  return `Description for argument '${args.directiveArgumentName}' on directive '${args.directiveName}' changed from '${args.oldDirectiveArgumentDescription}' to '${args.newDirectiveArgumentDescription}'`;
+  if (
+    args.oldDirectiveArgumentDescription === null &&
+    args.newDirectiveArgumentDescription !== null
+  ) {
+    return `Description '${fmt(args.newDirectiveArgumentDescription)}' was added to argument '${args.directiveArgumentName}' on directive '${args.directiveName}'`;
+  }
+  if (
+    args.newDirectiveArgumentDescription === null &&
+    args.oldDirectiveArgumentDescription !== null
+  ) {
+    return `Description '${fmt(args.oldDirectiveArgumentDescription)}' was removed from argument '${args.directiveArgumentName}' on directive '${args.directiveName}'`;
+  }
+  return `Description for argument '${args.directiveArgumentName}' on directive '${args.directiveName}' changed from '${fmt(args.oldDirectiveArgumentDescription ?? '')}' to '${fmt(args.newDirectiveArgumentDescription ?? '')}'`;
 }
 
 export function directiveArgumentDescriptionChangedFromMeta(

packages/core/src/diff/changes/enum.ts

@@ -86,11 +86,13 @@ export function enumValueAdded(
 }
 
 function buildEnumValueDescriptionChangedMessage(args: EnumValueDescriptionChangedChange['meta']) {
-  const oldDesc = fmt(args.oldEnumValueDescription ?? 'undefined');
-  const newDesc = fmt(args.newEnumValueDescription ?? 'undefined');
-  return args.oldEnumValueDescription === null
-    ? `Description '${newDesc}' was added to enum value '${args.enumName}.${args.enumValueName}'`
-    : `Description for enum value '${args.enumName}.${args.enumValueName}' changed from '${oldDesc}' to '${newDesc}'`;
+  if (args.oldEnumValueDescription === null && args.newEnumValueDescription !== null) {
+    return `Description '${fmt(args.newEnumValueDescription)}' was added to enum value '${args.enumName}.${args.enumValueName}'`;
+  }
+  if (args.newEnumValueDescription === null && args.oldEnumValueDescription !== null) {
+    return `Description '${fmt(args.oldEnumValueDescription)}' was removed from enum value '${args.enumName}.${args.enumValueName}'`;
+  }
+  return `Description for enum value '${args.enumName}.${args.enumValueName}' changed from '${fmt(args.oldEnumValueDescription ?? '')}' to '${fmt(args.newEnumValueDescription ?? '')}'`;
 }
 
 export function enumValueDescriptionChangedFromMeta(

packages/core/src/diff/changes/field.ts

@@ -8,6 +8,7 @@ import {
   isNonNullType,
 } from 'graphql';
 import { safeChangeForField } from '../../utils/graphql.js';
+import { fmt } from '../../utils/string.js';
 import {
   Change,
   ChangeType,
@@ -97,7 +98,13 @@ export function fieldAdded(
 }
 
 function buildFieldDescriptionChangedMessage(args: FieldDescriptionChangedChange['meta']) {
-  return `Field '${args.typeName}.${args.fieldName}' description changed from '${args.oldDescription}' to '${args.newDescription}'`;
+  if (!args.oldDescription && args.newDescription) {
+    return `Field '${args.typeName}.${args.fieldName}' description '${fmt(args.newDescription)}' was added`;
+  }
+  if (!args.newDescription && args.oldDescription) {
+    return `Field '${args.typeName}.${args.fieldName}' description '${fmt(args.oldDescription)}' was removed`;
+  }
+  return `Field '${args.typeName}.${args.fieldName}' description changed from '${fmt(args.oldDescription)}' to '${fmt(args.newDescription)}'`;
 }
 
 export function fieldDescriptionChangedFromMeta(args: FieldDescriptionChangedChange) {
@@ -129,7 +136,8 @@ export function fieldDescriptionChanged(
 }
 
 function buildFieldDescriptionAddedMessage(args: FieldDescriptionAddedChange['meta']) {
-  return `Field '${args.typeName}.${args.fieldName}' has description '${args.addedDescription}'`;
+  const desc = fmt(args.addedDescription);
+  return `Field '${args.typeName}.${args.fieldName}' has description '${desc}'`;
 }
 
 export function fieldDescriptionAddedFromMeta(args: FieldDescriptionAddedChange) {
@@ -249,7 +257,9 @@ export function fieldDeprecationRemoved(
 function buildFieldDeprecationReasonChangedMessage(
   args: FieldDeprecationReasonChangedChange['meta'],
 ) {
-  return `Deprecation reason on field '${args.typeName}.${args.fieldName}' has changed from '${args.oldDeprecationReason}' to '${args.newDeprecationReason}'`;
+  const oldReason = fmt(args.oldDeprecationReason);
+  const newReason = fmt(args.newDeprecationReason);
+  return `Deprecation reason on field '${args.typeName}.${args.fieldName}' has changed from '${oldReason}' to '${newReason}'`;
 }
 
 export function fieldDeprecationReasonChangedFromMeta(args: FieldDeprecationReasonChangedChange) {
@@ -283,7 +293,8 @@ export function fieldDeprecationReasonChanged(
 }
 
 function buildFieldDeprecationReasonAddedMessage(args: FieldDeprecationReasonAddedChange['meta']) {
-  return `Field '${args.typeName}.${args.fieldName}' has deprecation reason '${args.addedDeprecationReason}'`;
+  const reason = fmt(args.addedDeprecationReason);
+  return `Field '${args.typeName}.${args.fieldName}' has deprecation reason '${reason}'`;
 }
 
 export function fieldDeprecationReasonAddedFromMeta(args: FieldDeprecationReasonAddedChange) {

packages/core/src/diff/changes/input.ts

@@ -1,7 +1,7 @@
 import { GraphQLInputField, GraphQLInputObjectType, isNonNullType } from 'graphql';
 import { safeChangeForInputValue } from '../../utils/graphql.js';
 import { isDeprecated } from '../../utils/is-deprecated.js';
-import { safeString } from '../../utils/string.js';
+import { fmt, safeString } from '../../utils/string.js';
 import {
   Change,
   ChangeType,
@@ -95,7 +95,8 @@ export function inputFieldAdded(
 }
 
 function buildInputFieldDescriptionAddedMessage(args: InputFieldDescriptionAddedChange['meta']) {
-  return `Input field '${args.inputName}.${args.inputFieldName}' has description '${args.addedInputFieldDescription}'`;
+  const desc = fmt(args.addedInputFieldDescription);
+  return `Input field '${args.inputName}.${args.inputFieldName}' has description '${desc}'`;
 }
 
 export function inputFieldDescriptionAddedFromMeta(args: InputFieldDescriptionAddedChange) {
@@ -127,7 +128,8 @@ export function inputFieldDescriptionAdded(
 function buildInputFieldDescriptionRemovedMessage(
   args: InputFieldDescriptionRemovedChange['meta'],
 ) {
-  return `Description '${args.removedDescription}' was removed from input field '${args.inputName}.${args.inputFieldName}'`;
+  const desc = fmt(args.removedDescription);
+  return `Description '${desc}' was removed from input field '${args.inputName}.${args.inputFieldName}'`;
 }
 
 export function inputFieldDescriptionRemovedFromMeta(args: InputFieldDescriptionRemovedChange) {
@@ -159,7 +161,9 @@ export function inputFieldDescriptionRemoved(
 function buildInputFieldDescriptionChangedMessage(
   args: InputFieldDescriptionChangedChange['meta'],
 ) {
-  return `Input field '${args.inputName}.${args.inputFieldName}' description changed from '${args.oldInputFieldDescription}' to '${args.newInputFieldDescription}'`;
+  const oldDesc = fmt(args.oldInputFieldDescription);
+  const newDesc = fmt(args.newInputFieldDescription);
+  return `Input field '${args.inputName}.${args.inputFieldName}' description changed from '${oldDesc}' to '${newDesc}'`;
 }
 
 export function inputFieldDescriptionChangedFromMeta(args: InputFieldDescriptionChangedChange) {

packages/core/src/diff/changes/type.ts

@@ -8,6 +8,7 @@ import {
   type GraphQLNamedType,
 } from 'graphql';
 import { getKind } from '../../utils/graphql.js';
+import { fmt } from '../../utils/string.js';
 import {
   Change,
   ChangeType,
@@ -134,7 +135,9 @@ export function typeKindChanged(
 }
 
 function buildTypeDescriptionChangedMessage(args: TypeDescriptionChangedChange['meta']): string {
-  return `Description '${args.oldTypeDescription}' on type '${args.typeName}' has changed to '${args.newTypeDescription}'`;
+  const oldDesc = fmt(args.oldTypeDescription);
+  const newDesc = fmt(args.newTypeDescription);
+  return `Description '${oldDesc}' on type '${args.typeName}' has changed to '${newDesc}'`;
 }
 
 export function typeDescriptionChangedFromMeta(args: TypeDescriptionChangedChange) {
@@ -164,7 +167,8 @@ export function typeDescriptionChanged(
 }
 
 function buildTypeDescriptionRemoved(args: TypeDescriptionRemovedChange['meta']): string {
-  return `Description '${args.removedTypeDescription}' was removed from object type '${args.typeName}'`;
+  const desc = fmt(args.removedTypeDescription);
+  return `Description '${desc}' was removed from object type '${args.typeName}'`;
 }
 
 export function typeDescriptionRemovedFromMeta(args: TypeDescriptionRemovedChange) {
@@ -192,7 +196,8 @@ export function typeDescriptionRemoved(
 }
 
 function buildTypeDescriptionAddedMessage(args: TypeDescriptionAddedChange['meta']): string {
-  return `Object type '${args.typeName}' has description '${args.addedTypeDescription}'`;
+  const desc = fmt(args.addedTypeDescription);
+  return `Object type '${args.typeName}' has description '${desc}'`;
 }
 
 export function typeDescriptionAddedFromMeta(args: TypeDescriptionAddedChange) {