rename diff to check and respond with a change report

Author: StarpTech

README.md

@@ -26,7 +26,7 @@
 - Serves a supergraph schema for the GraphQL gateway
 - Validates new schema to be compatible with other running services
 - Validates that all client operations are supported by your schema
-- Produce a diff between your proposed schema and the current registry state to detect breaking changes and more
+- Detect breaking, dangerous and safe changes of schema updates
 - Lightweight authorization concept based on JWT.
 
 [**Read more**](https://principledgraphql.com/integrity#3-track-the-schema-in-a-registry)

docs/api.md

@@ -39,7 +39,7 @@ POST - `/schema/push` Creates a new graph and schema for a service. If you omit
 
 **Notice:** A schema is normalized before it's stored in the database. Whitespaces are stipped.
 
-**Notice:** The schema isn't validated for breaking-changes. Use [schema diff](#produce-a-diff-from-your-schema) to understand the implications of your update.
+**Notice:** The schema isn't validated for breaking-changes. Use a [change report](#creates-a-change-report) to understand the implications of your update.
 
 <details>
 <summary>Example Request</summary>
@@ -114,9 +114,9 @@ PUT - `/schema/deactivate` Deactivates a schema by id. The schema will no longer
 
 ## Validation
 
-### Produce a diff from your schema
+### Creates a change report
 
-POST - `/schema/diff` Returns the schema report between provided and latest schemas.
+POST - `/schema/check` Returns the schema report between provided and latest schemas. It can detect breaking, dangerous and safe changes. This should be executed before a new schema is pushed.
 
 <details>
 <summary>Example Request</summary>
@@ -135,7 +135,7 @@ POST - `/schema/diff` Returns the schema report between provided and latest sche
 
 ### Validate your schema
 
-POST - `/schema/validate` Validate schema between provided and latest schemas.
+POST - `/schema/validate` Validate schema between provided and latest schemas. It only verify if the schema can be composed.
 
 <details>
 <summary>Example Request</summary>

src/registry/index.ts

@@ -3,7 +3,7 @@ import basicAuth from '../core/basic-auth'
 import garbageCollect from './maintanance/garbage-collect'
 import composeSchema from './federation/compose-schema'
 import composeSchemaVersions from './federation/compose-schema-versions'
-import schemaDiff from './schema-validation/schema-diff'
+import schemaCheck from './schema-validation/schema-check'
 import schemaValidation from './schema-validation/schema-validation'
 import listGraphs from './federation/list-graphs'
 import registerSchema from './federation/register-schema'
@@ -42,6 +42,6 @@ export default async function Registry(fastify: FastifyInstance, opts: registryO
   composeSchema(fastify)
   composeSchemaVersions(fastify)
   deactivateSchema(fastify)
-  schemaDiff(fastify)
+  schemaCheck(fastify)
   schemaValidation(fastify)
 }

src/registry/schema-validation/schema-diff.test.ts renamed to src/registry/schema-validation/schema-check.test.ts

@@ -13,7 +13,7 @@ test.before(createTestContext())
 test.beforeEach(createTestPrefix())
 test.after.always('cleanup', cleanTest())
 
-test('Should calculate schema diff', async (t) => {
+test('Should check the schema for changes with the latest registry state', async (t) => {
   const app = build({
     databaseConnectionUrl: t.context.connectionUrl,
   })
@@ -39,7 +39,7 @@ test('Should calculate schema diff', async (t) => {
 
   res = await app.inject({
     method: 'POST',
-    url: '/schema/diff',
+    url: '/schema/check',
     payload: {
       typeDefs: /* GraphQL */ `
         type Query {
@@ -58,16 +58,17 @@ test('Should calculate schema diff', async (t) => {
     res.json(),
     {
       success: true,
-      data: [
-        {
-          criticality: {
+      data: {
+        isBreaking: false,
+        report: [
+          {
             level: 'NON_BREAKING',
+            type: 'FIELD_ADDED',
+            message: "Field 'world' was added to object type 'Query'",
+            path: 'Query.world',
           },
-          type: 'FIELD_ADDED',
-          message: "Field 'world' was added to object type 'Query'",
-          path: 'Query.world',
-        },
-      ],
+        ],
+      },
     },
     'response payload match',
   )
@@ -100,7 +101,7 @@ test('Should detect a breaking change', async (t) => {
 
   res = await app.inject({
     method: 'POST',
-    url: '/schema/diff',
+    url: '/schema/check',
     payload: {
       typeDefs: trimDoc/* GraphQL */ `
         type Query {
@@ -118,18 +119,19 @@ test('Should detect a breaking change', async (t) => {
     res.json(),
     {
       success: true,
-      data: [
-        {
-          criticality: {
-            level: 'BREAKING',
+      data: {
+        isBreaking: true,
+        report: [
+          {
             reason:
               'Removing a field is a breaking change. It is preferable to deprecate the field before removing it.',
+            level: 'BREAKING',
+            type: 'FIELD_REMOVED',
+            message: "Field 'world' was removed from object type 'Query'",
+            path: 'Query.world',
           },
-          type: 'FIELD_REMOVED',
-          message: "Field 'world' was removed from object type 'Query'",
-          path: 'Query.world',
-        },
-      ],
+        ],
+      },
     },
     'response payload match',
   )
@@ -143,7 +145,7 @@ test('Should return 400 because type_def is missing', async (t) => {
 
   let res = await app.inject({
     method: 'POST',
-    url: '/schema/diff',
+    url: '/schema/check',
     payload: {
       serviceName: `${t.context.testPrefix}_foo`,
       graphName: `${t.context.graphName}`,
@@ -187,7 +189,7 @@ test('Should return an empty diff when no other services exists', async (t) => {
 
   res = await app.inject({
     method: 'POST',
-    url: '/schema/diff',
+    url: '/schema/check',
     payload: {
       typeDefs: /* GraphQL */ `
         type Query {
@@ -204,7 +206,10 @@ test('Should return an empty diff when no other services exists', async (t) => {
     res.json(),
     {
       success: true,
-      data: [],
+      data: {
+        isBreaking: false,
+        report: [],
+      },
     },
     'message',
   )

src/registry/schema-validation/schema-diff.ts renamed to src/registry/schema-validation/schema-check.ts

@@ -1,6 +1,6 @@
 import S from 'fluent-json-schema'
 import { FastifyInstance, FastifySchema } from 'fastify'
-import { diff } from '@graphql-inspector/core'
+import { CriticalityLevel, diff } from '@graphql-inspector/core'
 import { composeAndValidateSchema } from '../../core/federation'
 import { SchemaManager } from '../../core/manager/SchemaManager'
 import {
@@ -29,14 +29,20 @@ export const schema: FastifySchema = {
       .prop('success', S.boolean())
       .prop(
         'data',
-        S.array().items(
-          S.object()
-            .required(['criticality', 'type', 'message', 'path'])
-            .prop('criticality', S.object().prop('level', S.string()).prop('reason', S.string()))
-            .prop('type', S.string())
-            .prop('message', S.string())
-            .prop('path', S.string()),
-        ),
+        S.object()
+          .prop('isBreaking', S.boolean())
+          .prop(
+            'report',
+            S.array().items(
+              S.object()
+                .required(['type', 'message', 'level', 'path'])
+                .prop('type', S.string())
+                .prop('message', S.string())
+                .prop('level', S.string())
+                .prop('path', S.string())
+                .prop('reason', S.string()),
+            ),
+          ),
       ),
   },
   body: S.object()
@@ -48,7 +54,7 @@ export const schema: FastifySchema = {
 }
 
 export default function schemaDiff(fastify: FastifyInstance) {
-  fastify.post<RequestContext>('/schema/diff', { schema }, async (req, res) => {
+  fastify.post<RequestContext>('/schema/check', { schema }, async (req, res) => {
     const graphRepository = new GraphRepository(fastify.knex)
 
     const graphExists = await graphRepository.exists({
@@ -111,11 +117,30 @@ export default function schemaDiff(fastify: FastifyInstance) {
       throw SchemaCompositionError(updated.error)
     }
 
-    const result = diff(original.schema, updated.schema)
+    const changes = diff(original.schema, updated.schema)
+
+    const changesReport = []
+    let isBreaking = false
+
+    for (const change of changes) {
+      if (change.criticality.level === CriticalityLevel.Breaking) {
+        isBreaking = true
+      }
+      changesReport.push({
+        type: change.type,
+        message: change.message,
+        level: change.criticality.level,
+        path: change.path,
+        reason: change.criticality.reason,
+      })
+    }
 
     return {
       success: true,
-      data: result,
+      data: {
+        isBreaking,
+        report: changesReport,
+      },
     }
   })
 }