# Safe (non-breaking) changes — existing clients are unaffected:
# ✅ Adding a new optional field to an existing type
type User {
  id: ID!
  name: String!
  bio: String    # NEW: optional field, existing queries still valid
}

# ✅ Adding a new type
type Address { street: String! city: String! }

# ✅ Adding a new optional argument to a field
type Query {
  users(first: Int, after: String, sortBy: UserSortField): [User!]!
  #                               ^^^^^^^^^^^^^^^^^^^^^ new optional arg
}

# ✅ Marking a field @deprecated (it still executes)
type User {
  email: String @deprecated(reason: "Use primaryEmail. Removal: 2027-Q1.")
  primaryEmail: EmailAddress!
}

# Breaking changes — existing clients will fail silently or loudly:

# ❌ Removing a field — any client selecting it receives null with no warning
type User {
  # removed: legacyId: String
}

# ❌ Changing nullable to non-null — clients checking for null will misbehave
type User {
  phone: String     # was nullable
  phone: String!    # ❌ BREAKING: if phone is missing, null propagates up the tree
}

# ❌ Changing a field's type
type Order {
  total: Float!     # was Float
  total: Int!       # ❌ BREAKING: clients expecting decimal precision receive integers
}

# ❌ Adding a required argument (non-null, no default)
type Query {
  users(first: Int!): [User!]!  # ❌ existing clients sending 'users' without 'first' will fail
}

# ❌ Removing an enum value
enum OrderStatus {
  PENDING
  CONFIRMED
  # removed: PROCESSING  ← mobile clients with compiled switch statements will have unhandled case
}

# ❌ Vague deprecation — provides no migration path or deadline
type User {
  email: String @deprecated(reason: "Use the new field")
}

# ✅ Complete deprecation — migration target + sunset deadline
type User {
  email: String @deprecated(reason: "Use `primaryEmail: EmailAddress!` instead. Removal planned: 2027-Q1. See https://wiki/graphql/email-migration.")
  primaryEmail: EmailAddress!
}

// ✅ Machine-readable deprecation metadata via schema directives
// If your team needs programmatic access to deprecation metadata:
const schema = buildSchema(`
  directive @sunsetOn(date: String!, reason: String) on FIELD_DEFINITION

  type User {
    email: String
      @deprecated(reason: "Use primaryEmail. Removal: 2027-Q1.")
      @sunsetOn(date: "2027-01-01", reason: "Migrated to EmailAddress scalar")
    primaryEmail: EmailAddress!
  }
`);

# In every subgraph CI pipeline, on every PR:

# Check if the schema change breaks any registered client operations
rover graph check my-graph@production \
  --schema ./schema.graphql \
  --name users-subgraph

# v0.20+ runs in under 10 seconds
# Outputs:
# ✅ No breaking changes detected
# 🔄 Deprecated field usage: User.email used by 847 operations
# ❌ BREAKING: Field 'User.legacyId' removed — 12 operations still using it

# --severity flag (v0.20+): set minimum severity to fail CI
rover graph check my-graph@production \
  --schema ./schema.graphql \
  --name users-subgraph \
  --severity BREAKING  # Only fail on BREAKING changes, not on DANGEROUS

# graphql-inspector can also run as a pre-commit hook:
npx graphql-inspector diff schema-old.graphql schema-new.graphql \
  --failOn BREAKING

# JSON diff output for GitHub PR checks:
npx graphql-inspector diff schema-old.graphql schema-new.graphql \
  --format json > schema-diff.json

type User {
  email: String @deprecated(reason: "Use `primaryEmail: EmailAddress!`. Removal: 2027-Q1. Migration: https://wiki/graphql/email-migration")
  primaryEmail: EmailAddress!
}

# GraphOS field insights — shows exact operation count and last-used date
rover graph field-usage my-graph \
  --field "User.email"

# Output:
# User.email
#   Total requests (last 30d): 23,847
#   Last requested: 2026-09-10
#   Affected operations: [GetUserProfile, UpdateNotifications, ...12 more]

# Confirm zero usage before removing
rover graph check my-graph@production --schema ./schema-without-email.graphql
# Must output: "✅ No operations affected by this change"

# Then deploy the schema without the field