GraphQL Inspector Core

@graphql-inspector/core is the library that powers GraphQL Inspector’s CLI: it exposes the same schema-diffing, validation, similarity-detection, and coverage-analysis logic as a set of importable TypeScript functions. Instead of shelling out to a CLI, teams embed it directly in CI scripts, custom tooling, or GraphQL Hive-style platforms to compare two GraphQLSchema objects and get back a structured list of Change objects, each classified as breaking, dangerous, or safe.

Beyond diffing, the package validates operation documents and fragments against a schema (catching deprecated field usage, excessive query depth, alias counts, and token counts), finds similar or duplicated types via string-distance matching, and computes schema coverage from a corpus of real operations. Because every rule is exported individually, consumers can compose custom diff pipelines — for example, running only the considerUsage rule to downgrade a change to non-breaking when analytics show the field is unused in production.

What You Get

• diff(oldSchema, newSchema, rules) — async schema comparison returning typed Change objects with criticality levels (breaking, dangerous, non-breaking)
• A library of composable diff rules (e.g. considerUsage, dangerousBreaking) that can be mixed into the diff pipeline to change how changes are classified
• validate(documents, schema, options) — validates operations and fragments against a schema, with configurable max query depth, alias count, directive count, and token count limits
• similar(schema, typeName, threshold) — finds similar or duplicated types in a schema using string-distance matching, useful for catching accidental type duplication
• coverage(schema, documents) — computes schema coverage (which types/fields are actually exercised) from a set of operation documents
• Fully typed Change subtypes for every kind of schema modification (field added/removed, directive usage changes, enum value changes, etc.) for building custom reporting

Common Use Cases

• Running schema-diff checks in CI to block PRs that introduce breaking GraphQL schema changes
• Building a custom schema registry or gateway (in the style of GraphQL Hive) that needs programmatic breaking-change detection rather than shelling out to a CLI
• Validating client operation documents against the production schema before deploy, including enforcing query complexity/depth limits
• Auditing a schema for duplicate or near-duplicate types during a refactor or federation migration
• Computing schema coverage reports to find dead types and fields based on real traffic or test-suite operations

Under The Hood

Architecture The package’s src/index.ts re-exports four independent subsystems — diff/, validate/, similar/, and coverage/ — each with its own entry point and no shared runtime state. diff/index.ts computes a raw change list via diffSchema() in diff/schema.ts, then runs it through a rules array using Array.reduce, so each Rule function (found in diff/rules/, e.g. considerUsage) receives the previous changes plus the old/new schema and can reclassify or filter them — an explicit middleware-style pipeline rather than a monolithic diff function. validate/index.ts builds a DepGraph (from the dependency-graph package) to resolve fragment dependencies before running GraphQL’s own validate(), layering custom checks (alias-count.ts, query-depth.ts, directive-count.ts, token-count.ts) and an Apollo-directive transform step so @client/@connection usage doesn’t trip false positives. similar/index.ts is a self-contained string-distance matcher over the schema’s type map. This separation means each subsystem could be extracted independently, and the diff rule pipeline is the one abstraction the rest of the ecosystem (the CLI, the GitHub Action) builds directly on top of.

Tech Stack Written entirely in TypeScript and shipped as dual ESM/CJS output (dist/esm, dist/cjs) with generated .d.ts/.d.cts typings, built via bob-the-bundler (bob build/bob prepack) rather than a hand-rolled bundler config. Runtime dependencies are minimal and deliberate: dependency-graph for fragment resolution, object-inspect for readable error output, and tslib for helper de-duplication; graphql itself is a peer dependency (^16.0.0 || ^17.0.0) so consumers control the exact GraphQL version. The package lives inside a pnpm-workspace monorepo alongside the CLI, GitHub Action, and loader packages, versioned and published via Changesets (pnpm changeset publish).

Code Quality The __tests__/ directory contains 22 test files organized to mirror src/ (diff/, validate/, coverage/, utils/), run via Vitest (pnpm test). Types are strict and pervasive — every exported function and every possible schema change has its own named TypeScript interface (FieldRemovedChange, DirectiveUsageEnumAddedChange, etc.) rather than a loosely-typed generic Change shape. Linting runs through @theguild/eslint-config and Prettier via @theguild/prettier-config, enforced pre-commit with Husky + lint-staged, and CI runs on CircleCI. No swallowed errors were observed — validation failures surface as typed GraphQLError arrays rather than thrown exceptions.

What Makes It Unique Most schema-diff tools return a flat boolean (breaking or not) or a plain diff of the SDL text. This package instead assigns every change a CriticalityLevel (Breaking, Dangerous, NonBreaking) and — via the composable rules pipeline — lets consumers reclassify changes using external signal, most notably real production field-usage data through the considerUsage rule, so a technically-breaking removal of an already-dead field doesn’t have to block a release. Bundling diffing, document validation (with complexity/depth/alias limits), duplicate-type detection, and coverage analysis behind one typed API — rather than as separate single-purpose packages — is what lets the same core power both the standalone CLI and hosted registries like GraphQL Hive.