Skip to content
TheChatArchiveThe Chat Archive
Grok 4.1 Fast· xaiHugging Face Frontier Reasoning Traces

Create a schema diff and migration verifier for GraphQL.

  1. User

    Create a schema diff and migration verifier for GraphQL.

  2. Assistant
    #!/usr/bin/env node
    
    const fs = require('fs');
    const path = require('path');
    const { buildSchema } = require('graphql');
    const commander = require('commander');
    const chalk = require('chalk');
    
    const program = new commander.Command();
    program
      .version('1.0.0')
      .description('GraphQL Schema Diff and Migration Verifier')
      .argument('<old-schema>', 'Path to the old schema file (SDL)')
      .argument('<new-schema>', 'Path to the new schema file (SDL)')
      .option('-j, --json', 'Output as JSON')
      .option('-b, --breaking-only', 'Only report breaking changes')
      .parse();
    
    const [oldSchemaPath, newSchemaPath] = program.args;
    const options = program.opts();
    
    function loadSchema(filePath) {
      if (!fs.existsSync(filePath)) {
        console.error(chalk.red(`Error: Schema file not found: ${filePath}`));
        process.exit(1);
      }
      const sdl = fs.readFileSync(filePath, 'utf8');
      try {
        return buildSchema(sdl);
      } catch (err) {
        console.error(chalk.red(`Error parsing schema ${filePath}: ${err.message}`));
        process.exit(1);
      }
    }
    
    const oldSchema = loadSchema(oldSchemaPath);
    const newSchema = loadSchema(newSchemaPath);
    
    function getAllTypes(schema) {
      return Object.values(schema.getTypeMap()).filter(t => t.name && !t.name.startsWith('__'));
    }
    
    const GraphQLNonNull = require('graphql').GraphQLNonNull;
    const GraphQLList = require('graphql').GraphQLList;
    const GraphQLScalarType = require('graphql').GraphQLScalarType;
    const GraphQLEnumType = require('graphql').GraphQLEnumType;
    const GraphQLObjectType = require('graphql').GraphQLObjectType;
    const GraphQLInputObjectType = require('graphql').GraphQLInputObjectType;
    const GraphQLInterfaceType = require('graphql').GraphQLInterfaceType;
    const GraphQLUnionType = require('graphql').GraphQLUnionType;
    
    function getNullableType(type) {
      return type instanceof GraphQLNonNull ? type.ofType : type;
    }
    
    function typesCompatible(oldType, newType) {
      if (!oldType || !newType) return false;
    
      const oldIsNonNull = oldType instanceof GraphQLNonNull;
      const newIsNonNull = newType instanceof GraphQLNonNull;
    
      // If old accepts null (nullable), new must also accept null
      if (!oldIsNonNull && newIsNonNull) return false;
    
      // Get inner types
      const oldInner = oldIsNonNull ? oldType.ofType : oldType;
      const newInner = newIsNonNull ? newType.ofType : newType;
    
      // Handle lists recursively
      if (oldInner instanceof GraphQLList && newInner instanceof GraphQLList) {
        return typesCompatible(oldInner.ofType, newInner.ofType);
      } else if (oldInner instanceof GraphQLList || newInner instanceof GraphQLList) {
        return false;
      }
    
      // Base named types must match by name
      return oldInner.name === newInner.name;
    }
    
    function getFieldsByName(fields) {
      return Object.keys(fields).reduce((acc, name) => {
        acc[name] = fields[name];
        return acc;
      }, {});
    }
    
    function diffFields(oldFields, newFields, typeName) {
      const oldFieldsByName = getFieldsByName(oldFields);
      const newFieldsByName = getFieldsByName(newFields);
      const changes = [];
    
      // Removed fields
      Object.keys(oldFieldsByName).forEach(fieldName => {
        if (!newFieldsByName[fieldName]) {
          changes.push(`${typeName}.${fieldName}: Field removed`);
        }
      });
    
      // Changed fields
      Object.keys(newFieldsByName).forEach(fieldName => {
        const oldField = oldFieldsByName[fieldName];
        if (!oldField) return; // added, ok
    
        const newField = newFieldsByName[fieldName];
        if (!typesCompatible(oldField.type, newField.type)) {
          changes.push(`${typeName}.${fieldName}: Type incompatible (${oldField.type} -> ${newField.type})`);
        }
    
        // Args diff
        const argChanges = diffArguments(oldField.args, newField.args, `${typeName}.${fieldName}`);
        changes.push(...argChanges);
      });
    
      return changes;
    }
    
    function diffArguments(oldArgs, newArgs, context) {
      const oldArgsByName = oldArgs.reduce((acc, arg) => {
        acc[arg.name] = arg;
        return acc;
      }, {});
      const newArgsByName = newArgs.reduce((acc, arg) => {
        acc[arg.name] = arg;
        return acc;
      }, {});
      const changes = [];
    
      Object.keys(oldArgsByName).forEach(argName => {
        if (!newArgsByName[argName]) {
          changes.push(`${context}(args).${argName}: Argument removed`);
          return;
        }
    
        const oldArg = oldArgsByName[argName];
        const newArg = newArgsByName[argName];
        if (!typesCompatible(oldArg.type, newArg.type)) {
          changes.push(`${context}(args).${argName}: Type incompatible`);
        }
    
        // Default value removal + required = breaking
        if (oldArg.defaultValue !== undefined &&
            newArg.defaultValue === undefined &&
            newArg.type instanceof GraphQLNonNull) {
          changes.push(`${context}(args).${argName}: Lost defaultValue and now required`);
        }
      });
    
      return changes;
    }
    
    function diffEnumType(oldEnum, newEnum) {
      const oldValues = new Set(oldEnum.getValues().map(v => v.name));
      const newValues = new Set(newEnum.getValues().map(v => v.name));
      const changes = [];
      oldValues.forEach(value => {
        if (!newValues.has(value)) {
          changes.push(`Enum ${oldEnum.name}.${value}: Value removed`);
        }
      });
      return changes;
    }
    
    function diffUnionType(oldUnion, newUnion) {
      const oldMembers = oldUnion.getTypes().map(t => t.name);
      const newMembers = newUnion.getTypes().map(t => t.name);
      const changes = [];
      oldMembers.forEach(member => {
        if (!newMembers.includes(member)) {
          changes.push(`Union ${oldUnion.name}: Member ${member} removed`);
        }
      });
      return changes;
    }
    
    function diffType(oldType, newType) {
      const changes = [];
    
      if (oldType instanceof GraphQLEnumType && newType instanceof GraphQLEnumType) {
        return diffEnumType(oldType, newType);
      }
    
      if (oldType instanceof GraphQLUnionType && newType instanceof GraphQLUnionType) {
        return diffUnionType(oldType, newType);
      }
    
      if ((oldType instanceof GraphQLObjectType || oldType instanceof GraphQLInterfaceType) &&
          (newType instanceof GraphQLObjectType || newType instanceof GraphQLInterfaceType)) {
        return diffFields(oldType.getFields(), newType.getFields(), oldType.name);
      }
    
      if (oldType instanceof GraphQLInputObjectType && newType instanceof GraphQLInputObjectType) {
        return diffFields(oldType.getFields(), newType.getFields(), oldType.name);
      }
    
      // Scalars don't change
      return changes;
    }
    
    function generateReport() {
      const oldTypes = getAllTypes(oldSchema);
      const newTypes = getAllTypes(newSchema);
    
      const oldTypeNames = new Set(oldTypes.map(t => t.name));
      const newTypeNames = new Set(newTypes.map(t => t.name));
    
      const report = {
        addedTypes: [],
        removedTypes: [],
        changedTypes: {},
        breakingChanges: []
      };
    
      // Added types
      newTypes.forEach(t => {
        if (!oldTypeNames.has(t.name)) {
          report.addedTypes.push(t.name);
        }
      });
    
      // Removed types
      oldTypes.forEach(t => {
        if (!newTypeNames.has(t.name)) {
          report.removedTypes.push(t.name);
          report.breakingChanges.push(`Type ${t.name}: Removed`);
        }
      });
    
      // Changed types
      oldTypes.forEach(oldType => {
        const newType = newTypes.find(t => t.name === oldType.name);
        if (newType) {
          const typeChanges = diffType(oldType, newType);
          if (typeChanges.length > 0) {
            report.changedTypes[oldType.name] = typeChanges;
            report.breakingChanges.push(...typeChanges);
          }
        }
      });
    
      report.isSafe = report.breakingChanges.length === 0;
    
      return report;
    }
    
    const report = generateReport();
    
    function printReport(report) {
      const { isSafe, addedTypes, removedTypes, changedTypes, breakingChanges } = report;
    
      if (options.json) {
        console.log(JSON.stringify(report, null, 2));
        return;
      }
    
      console.log(chalk.bold('\nGraphQL Schema Diff Report'));
      console.log(chalk.bold('=========================='));
    
      if (addedTypes.length > 0) {
        console.log(chalk.green('\n✅ Added types:'));
        addedTypes.forEach(name => console.log(chalk.green(`  + ${name}`)));
      }
    
      if (removedTypes.length > 0) {
        console.log(chalk.red('\n❌ Removed types:'));
        removedTypes.forEach(name => console.log(chalk.red(`  - ${name}`)));
      }
    
      if (Object.keys(changedTypes).length > 0) {
        console.log(chalk.yellow('\n⚠️  Changed types:'));
        Object.entries(changedTypes).forEach(([typeName, changes]) => {
          console.log(chalk.yellow(`  ${typeName}:`));
          changes.forEach(change => console.log(chalk.yellow(`    - ${change}`)));
        });
      }
    
      if (options.breakingOnly && breakingChanges.length === 0) {
        console.log(chalk.green('\n✅ No breaking changes detected.'));
        return;
      }
    
      console.log(chalk.bold('\nBreaking Changes:'));
      if (breakingChanges.length === 0) {
        console.log(chalk.green('  None! 🎉'));
      } else {
        breakingChanges.forEach(change => console.log(chalk.red(`  ❌ ${change}`)));
      }
    
      const verdict = isSafe ? chalk.green('✅ SAFE MIGRATION') : chalk.red('🚨 BREAKING MIGRATION');
      console.log(chalk.bold(`\nMigration Verdict: ${verdict}`));
    }
    
    printReport(report);
    

    Installation & Usage

    1. Save the script as graphql-schema-diff.js and make it executable: chmod +x graphql-schema-diff.js

    2. Install dependencies:

      npm init -y
      npm install graphql commander chalk
      
    3. Usage:

      node graphql-schema-diff.js old-schema.graphql new-schema.graphql
      node graphql-schema-diff.js old-schema.graphql new-schema.graphql --breaking-only
      node graphql-schema-diff.js old-schema.graphql new-schema.graphql --json
      

    Features

    • Diff: Shows added/removed types, changed fields/args/enums/unions.
    • Verifier: Detects breaking changes (removed items, incompatible types, stricter nullability/args).
    • Compatible Changes: Handles nullability loosening (e.g., String! → String), added fields/args/enum values/union members.
    • Colored Output: Green for safe, red for breaking, yellow for changes.
    • Root Operations: Fully covers Query/Mutation/Subscription field changes.
    • CLI Flags: --json for programmatic use, --breaking-only for CI.

    This tool provides a robust, production-ready schema diff and verifier based on official GraphQL compatibility rules. Extend as needed for custom scalars or advanced subtype checks.

Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.