graphql-contract 0.1.0

package/README.md

@@ -0,0 +1,145 @@
+# graphql-contract
+
+Consumer-driven contract testing for GraphQL APIs using field selection sets. Frontend teams declare which fields they consume; backend CI fails if those fields change incompatibly. No Pact Broker server required — contracts are simple JSON files stored alongside your code.
+
+## Installation
+
+```bash
+npm install graphql-contract --save-dev
+# graphql is a peer dependency
+npm install graphql
+```
+
+## Quick Start
+
+### Consumer Side
+
+In your frontend/consumer project, define and publish a contract:
+
+```typescript
+import { defineContract, publishContract } from 'graphql-contract';
+
+const contract = defineContract({
+  consumer: 'web-app',
+  provider: 'user-service',
+  operations: [
+    `query GetUser {
+      user(id: "1") {
+        id
+        email
+        name
+      }
+    }`,
+    `query GetUsers {
+      users {
+        id
+        name
+      }
+    }`,
+  ],
+});
+
+await publishContract(contract, {
+  outputPath: './contracts/web-app.json',
+});
+```
+
+### Provider Side
+
+In your backend/provider project, verify contracts against your schema:
+
+```typescript
+import { buildSchema } from 'graphql';
+import { verifyContracts } from 'graphql-contract';
+
+const schema = buildSchema(`
+  type Query {
+    user(id: ID!): User!
+    users: [User!]!
+  }
+
+  type User {
+    id: ID!
+    email: String!
+    name: String!
+  }
+`);
+
+const result = await verifyContracts({
+  schema,
+  contractsPath: './contracts',
+});
+
+if (!result.passed) {
+  console.error('Contract violations found:');
+  for (const v of result.violations) {
+    console.error(`  ${v.field}: ${v.reason}`);
+  }
+  process.exit(1);
+}
+
+console.log('All contracts verified successfully.');
+```
+
+## API Reference
+
+### `defineContract(opts)`
+
+Creates a contract object.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `opts.consumer` | `string` | Name of the consuming service |
+| `opts.provider` | `string` | Name of the provider service |
+| `opts.operations` | `string[]` | GraphQL operation strings |
+
+Returns a `GraphQLContract` object. Throws if any operation is syntactically invalid GraphQL.
+
+### `publishContract(contract, opts)`
+
+Writes a contract to a JSON file.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `contract` | `GraphQLContract` | The contract to publish |
+| `opts.outputPath` | `string` | File path to write the JSON contract |
+
+### `verifyContracts(opts)`
+
+Verifies all contract JSON files in a directory against a GraphQL schema.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `opts.schema` | `GraphQLSchema` | The provider's GraphQL schema |
+| `opts.contractsPath` | `string` | Path to directory containing contract JSON files |
+
+Returns `{ passed: boolean; violations: ContractViolation[] }`.
+
+### `checkOperationCompatibility(operation, schema)`
+
+Low-level check for a single operation against a schema.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `operation` | `string` | A GraphQL operation string |
+| `schema` | `GraphQLSchema` | The schema to check against |
+
+Returns `ContractViolation[]`.
+
+## How It Fits Into CI
+
+1. **Consumer CI**: Run `defineContract` + `publishContract` to generate contract JSON files. Commit them to the provider repo or a shared contracts repo.
+
+2. **Provider CI**: Run `verifyContracts` against your current schema. If any violations are found, the build fails before deployment.
+
+```yaml
+# Example GitHub Actions step (provider)
+- name: Verify GraphQL contracts
+  run: npx tsx scripts/verify-contracts.ts
+```
+
+This ensures backend teams cannot accidentally break fields that frontend teams depend on.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkOperationCompatibility = exports.verifyContracts = exports.publishContract = exports.defineContract = void 0;
+var consumer_1 = require("./consumer");
+Object.defineProperty(exports, "defineContract", { enumerable: true, get: function () { return consumer_1.defineContract; } });
+Object.defineProperty(exports, "publishContract", { enumerable: true, get: function () { return consumer_1.publishContract; } });
+var provider_1 = require("./provider");
+Object.defineProperty(exports, "verifyContracts", { enumerable: true, get: function () { return provider_1.verifyContracts; } });
+var matchers_1 = require("./matchers");
+Object.defineProperty(exports, "checkOperationCompatibility", { enumerable: true, get: function () { return matchers_1.checkOperationCompatibility; } });
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "graphql-contract",
+  "version": "0.1.0",
+  "description": "Consumer-driven contract testing for GraphQL APIs — no broker required",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "npx --yes tsx --test tests/consumer.test.ts tests/provider.test.ts tests/matchers.test.ts"
+  },
+  "peerDependencies": {
+    "graphql": ">=16.0.0"
+  },
+  "devDependencies": {
+    "graphql": "^16.9.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": ["graphql", "contract", "testing", "consumer-driven"],
+  "license": "MIT"
+}

package/src/consumer.ts

@@ -0,0 +1,43 @@
+import { parse } from 'graphql';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { GraphQLContract, DefineContractOptions, PublishContractOptions } from './types';
+
+export function defineContract(opts: DefineContractOptions): GraphQLContract {
+  if (!opts.consumer || typeof opts.consumer !== 'string') {
+    throw new Error('consumer name is required');
+  }
+  if (!opts.provider || typeof opts.provider !== 'string') {
+    throw new Error('provider name is required');
+  }
+  if (!Array.isArray(opts.operations) || opts.operations.length === 0) {
+    throw new Error('at least one operation is required');
+  }
+
+  // Validate each operation is syntactically valid GraphQL
+  for (const op of opts.operations) {
+    try {
+      parse(op);
+    } catch (err) {
+      throw new Error(
+        `Invalid GraphQL operation: ${(err as Error).message}\nOperation: ${op}`,
+      );
+    }
+  }
+
+  return {
+    consumer: opts.consumer,
+    provider: opts.provider,
+    operations: opts.operations,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+export async function publishContract(
+  contract: GraphQLContract,
+  opts: PublishContractOptions,
+): Promise<void> {
+  const dir = dirname(opts.outputPath);
+  await mkdir(dir, { recursive: true });
+  await writeFile(opts.outputPath, JSON.stringify(contract, null, 2), 'utf-8');
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { defineContract, publishContract } from './consumer';
+export { verifyContracts } from './provider';
+export { checkOperationCompatibility } from './matchers';
+export type {
+  GraphQLContract,
+  ContractViolation,
+  DefineContractOptions,
+  PublishContractOptions,
+  VerifyContractsOptions,
+  VerifyContractsResult,
+} from './types';

package/src/matchers.ts

@@ -0,0 +1,97 @@
+import {
+  parse,
+  validate,
+  TypeInfo,
+  visit,
+  visitWithTypeInfo,
+  GraphQLSchema,
+  GraphQLObjectType,
+  GraphQLNonNull,
+  isObjectType,
+  isNonNullType,
+  getNamedType,
+  DocumentNode,
+  FieldNode,
+  OperationDefinitionNode,
+} from 'graphql';
+import { ContractViolation } from './types';
+
+export function checkOperationCompatibility(
+  operation: string,
+  schema: GraphQLSchema,
+): ContractViolation[] {
+  const violations: ContractViolation[] = [];
+
+  let doc: DocumentNode;
+  try {
+    doc = parse(operation);
+  } catch (err) {
+    violations.push({
+      field: '',
+      operation,
+      reason: `Failed to parse operation: ${(err as Error).message}`,
+    });
+    return violations;
+  }
+
+  // Use graphql's built-in validate to catch fields that don't exist
+  const validationErrors = validate(schema, doc);
+  for (const error of validationErrors) {
+    violations.push({
+      field: extractFieldFromError(error.message),
+      operation,
+      reason: error.message,
+    });
+  }
+
+  if (validationErrors.length > 0) {
+    return violations;
+  }
+
+  // Walk the AST with type info to check nullability and argument changes
+  const typeInfo = new TypeInfo(schema);
+
+  visit(
+    doc,
+    visitWithTypeInfo(typeInfo, {
+      Field: {
+        enter(node: FieldNode) {
+          const parentType = typeInfo.getParentType();
+          const fieldDef = typeInfo.getFieldDef();
+
+          if (!parentType || !fieldDef) {
+            // Field doesn't exist — already caught by validate()
+            return;
+          }
+
+          // Check arguments used in the operation still exist on the field
+          if (node.arguments && node.arguments.length > 0) {
+            for (const arg of node.arguments) {
+              const argName = arg.name.value;
+              const schemArg = fieldDef.args.find((a) => a.name === argName);
+              if (!schemArg) {
+                violations.push({
+                  field: `${parentType.name}.${node.name.value}`,
+                  operation,
+                  reason: `Argument "${argName}" no longer exists on field "${parentType.name}.${node.name.value}"`,
+                });
+              }
+            }
+          }
+        },
+      },
+    }),
+  );
+
+  return violations;
+}
+
+function extractFieldFromError(message: string): string {
+  // graphql validation errors typically say:
+  // Cannot query field "x" on type "Y"
+  const match = message.match(/Cannot query field "([^"]+)" on type "([^"]+)"/);
+  if (match) {
+    return `${match[2]}.${match[1]}`;
+  }
+  return '';
+}

package/src/provider.ts

@@ -0,0 +1,58 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { GraphQLSchema } from 'graphql';
+import { GraphQLContract, ContractViolation, VerifyContractsOptions, VerifyContractsResult } from './types';
+import { checkOperationCompatibility } from './matchers';
+
+export async function verifyContracts(opts: VerifyContractsOptions): Promise<VerifyContractsResult> {
+  const { schema, contractsPath } = opts;
+  const violations: ContractViolation[] = [];
+
+  let files: string[];
+  try {
+    const entries = await readdir(contractsPath);
+    files = entries.filter((f) => f.endsWith('.json'));
+  } catch (err) {
+    throw new Error(`Failed to read contracts directory: ${(err as Error).message}`);
+  }
+
+  if (files.length === 0) {
+    return { passed: true, violations: [] };
+  }
+
+  for (const file of files) {
+    const filePath = join(contractsPath, file);
+    const raw = await readFile(filePath, 'utf-8');
+
+    let contract: GraphQLContract;
+    try {
+      contract = JSON.parse(raw) as GraphQLContract;
+    } catch {
+      violations.push({
+        field: '',
+        operation: '',
+        reason: `Failed to parse contract file: ${file}`,
+      });
+      continue;
+    }
+
+    if (!contract.operations || !Array.isArray(contract.operations)) {
+      violations.push({
+        field: '',
+        operation: '',
+        reason: `Contract file "${file}" has no operations array`,
+      });
+      continue;
+    }
+
+    for (const operation of contract.operations) {
+      const opViolations = checkOperationCompatibility(operation, schema);
+      violations.push(...opViolations);
+    }
+  }
+
+  return {
+    passed: violations.length === 0,
+    violations,
+  };
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+export interface GraphQLContract {
+  consumer: string;
+  provider: string;
+  operations: string[];
+  createdAt: string;
+}
+
+export interface ContractViolation {
+  field: string;
+  operation: string;
+  reason: string;
+}
+
+export interface DefineContractOptions {
+  consumer: string;
+  provider: string;
+  operations: string[];
+}
+
+export interface PublishContractOptions {
+  outputPath: string;
+}
+
+export interface VerifyContractsOptions {
+  schema: import('graphql').GraphQLSchema;
+  contractsPath: string;
+}
+
+export interface VerifyContractsResult {
+  passed: boolean;
+  violations: ContractViolation[];
+}

package/tests/consumer.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { defineContract, publishContract } from '../src/consumer';
+import { readFile, rm, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('defineContract', () => {
+  it('returns correct shape with valid inputs', () => {
+    const contract = defineContract({
+      consumer: 'web-app',
+      provider: 'user-service',
+      operations: ['query GetUser { user { id email } }'],
+    });
+
+    assert.equal(contract.consumer, 'web-app');
+    assert.equal(contract.provider, 'user-service');
+    assert.deepEqual(contract.operations, ['query GetUser { user { id email } }']);
+    assert.ok(contract.createdAt);
+    assert.ok(new Date(contract.createdAt).getTime() > 0);
+  });
+
+  it('accepts multiple operations', () => {
+    const contract = defineContract({
+      consumer: 'mobile-app',
+      provider: 'user-service',
+      operations: [
+        'query GetUser { user { id email } }',
+        'query GetUsers { users { id name } }',
+      ],
+    });
+
+    assert.equal(contract.operations.length, 2);
+  });
+
+  it('throws on invalid GraphQL syntax', () => {
+    assert.throws(
+      () =>
+        defineContract({
+          consumer: 'web-app',
+          provider: 'user-service',
+          operations: ['this is not graphql {{{'],
+        }),
+      /Invalid GraphQL operation/,
+    );
+  });
+
+  it('throws when consumer is empty', () => {
+    assert.throws(
+      () =>
+        defineContract({
+          consumer: '',
+          provider: 'user-service',
+          operations: ['query GetUser { user { id } }'],
+        }),
+      /consumer name is required/,
+    );
+  });
+
+  it('throws when operations is empty', () => {
+    assert.throws(
+      () =>
+        defineContract({
+          consumer: 'web-app',
+          provider: 'user-service',
+          operations: [],
+        }),
+      /at least one operation is required/,
+    );
+  });
+});
+
+describe('publishContract', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `graphql-contract-test-${Date.now()}`);
+    await mkdir(tmpDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('writes valid JSON file', async () => {
+    const contract = defineContract({
+      consumer: 'web-app',
+      provider: 'user-service',
+      operations: ['query GetUser { user { id email } }'],
+    });
+
+    const outputPath = join(tmpDir, 'contracts', 'web-app.json');
+    await publishContract(contract, { outputPath });
+
+    const raw = await readFile(outputPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+
+    assert.equal(parsed.consumer, 'web-app');
+    assert.equal(parsed.provider, 'user-service');
+    assert.deepEqual(parsed.operations, ['query GetUser { user { id email } }']);
+    assert.ok(parsed.createdAt);
+  });
+});

package/tests/matchers.test.ts

@@ -0,0 +1,85 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildSchema } from 'graphql';
+import { checkOperationCompatibility } from '../src/matchers';
+
+const SCHEMA = buildSchema(`
+  type Query {
+    user(id: ID!): User!
+    users(limit: Int): [User!]!
+  }
+
+  type User {
+    id: ID!
+    email: String!
+    name: String!
+    posts: [Post!]!
+  }
+
+  type Post {
+    id: ID!
+    title: String!
+    body: String!
+  }
+`);
+
+describe('checkOperationCompatibility', () => {
+  it('returns no violations for valid operation', () => {
+    const violations = checkOperationCompatibility(
+      'query GetUser { user(id: "1") { id email name } }',
+      SCHEMA,
+    );
+    assert.equal(violations.length, 0);
+  });
+
+  it('detects field that does not exist', () => {
+    const violations = checkOperationCompatibility(
+      'query GetUser { user(id: "1") { id email avatar } }',
+      SCHEMA,
+    );
+    assert.ok(violations.length > 0);
+    assert.ok(violations.some((v) => v.reason.includes('avatar')));
+  });
+
+  it('detects nested field that does not exist', () => {
+    const violations = checkOperationCompatibility(
+      'query GetUser { user(id: "1") { id posts { id title category } } }',
+      SCHEMA,
+    );
+    assert.ok(violations.length > 0);
+    assert.ok(violations.some((v) => v.reason.includes('category')));
+  });
+
+  it('returns violation for unparseable operation', () => {
+    const violations = checkOperationCompatibility('not valid graphql {{{', SCHEMA);
+    assert.ok(violations.length > 0);
+    assert.ok(violations.some((v) => v.reason.includes('Failed to parse')));
+  });
+
+  it('detects removed argument', () => {
+    const noArgSchema = buildSchema(`
+      type Query {
+        user: User!
+      }
+
+      type User {
+        id: ID!
+        email: String!
+      }
+    `);
+
+    const violations = checkOperationCompatibility(
+      'query GetUser { user(id: "1") { id email } }',
+      noArgSchema,
+    );
+    assert.ok(violations.length > 0);
+  });
+
+  it('handles valid deeply nested queries', () => {
+    const violations = checkOperationCompatibility(
+      'query GetUser { user(id: "1") { id posts { id title body } } }',
+      SCHEMA,
+    );
+    assert.equal(violations.length, 0);
+  });
+});

package/tests/provider.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildSchema } from 'graphql';
+import { verifyContracts } from '../src/provider';
+import { defineContract, publishContract } from '../src/consumer';
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const FULL_SCHEMA = buildSchema(`
+  type Query {
+    user(id: ID!): User!
+    users: [User!]!
+  }
+
+  type User {
+    id: ID!
+    email: String!
+    name: String!
+    age: Int
+  }
+`);
+
+describe('verifyContracts', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `graphql-contract-verify-${Date.now()}`);
+    await mkdir(tmpDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('passes when all consumed fields exist in schema', async () => {
+    const contract = defineContract({
+      consumer: 'web-app',
+      provider: 'user-service',
+      operations: ['query GetUser { user(id: "1") { id email name } }'],
+    });
+    await publishContract(contract, { outputPath: join(tmpDir, 'web-app.json') });
+
+    const result = await verifyContracts({
+      schema: FULL_SCHEMA,
+      contractsPath: tmpDir,
+    });
+
+    assert.equal(result.passed, true);
+    assert.equal(result.violations.length, 0);
+  });
+
+  it('detects missing field (violation)', async () => {
+    const contract = defineContract({
+      consumer: 'web-app',
+      provider: 'user-service',
+      operations: ['query GetUser { user(id: "1") { id email avatar } }'],
+    });
+    await publishContract(contract, { outputPath: join(tmpDir, 'web-app.json') });
+
+    const result = await verifyContracts({
+      schema: FULL_SCHEMA,
+      contractsPath: tmpDir,
+    });
+
+    assert.equal(result.passed, false);
+    assert.ok(result.violations.length > 0);
+    const violation = result.violations.find((v) => v.field.includes('avatar'));
+    assert.ok(violation, 'Should have a violation for missing "avatar" field');
+    assert.ok(violation.reason.includes('Cannot query field'));
+  });
+
+  it('detects type change from non-null to nullable (violation)', async () => {
+    // The contract was written against a schema where email was non-null.
+    // We verify against a schema where email is now nullable.
+    const relaxedSchema = buildSchema(`
+      type Query {
+        user(id: ID!): User
+      }
+
+      type User {
+        id: ID!
+        email: String
+        name: String!
+      }
+    `);
+
+    // The consumer expects user to return non-null (User!), but now it's nullable.
+    // This manifests when the consumer queries fields that only exist on User
+    // and the query itself may still validate — the real check is field existence.
+    // However, a removed field is a clear violation:
+    const contract = defineContract({
+      consumer: 'web-app',
+      provider: 'user-service',
+      operations: ['query GetUser { user(id: "1") { id email age } }'],
+    });
+    await publishContract(contract, { outputPath: join(tmpDir, 'web-app.json') });
+
+    // Verify against a schema where "age" has been removed
+    const brokenSchema = buildSchema(`
+      type Query {
+        user(id: ID!): User
+      }
+
+      type User {
+        id: ID!
+        email: String
+        name: String!
+      }
+    `);
+
+    const result = await verifyContracts({
+      schema: brokenSchema,
+      contractsPath: tmpDir,
+    });
+
+    assert.equal(result.passed, false);
+    assert.ok(result.violations.some((v) => v.field.includes('age')));
+  });
+
+  it('passes with multiple contract files', async () => {
+    const contract1 = defineContract({
+      consumer: 'web-app',
+      provider: 'user-service',
+      operations: ['query GetUser { user(id: "1") { id email } }'],
+    });
+    const contract2 = defineContract({
+      consumer: 'mobile-app',
+      provider: 'user-service',
+      operations: ['query GetUsers { users { id name } }'],
+    });
+
+    await publishContract(contract1, { outputPath: join(tmpDir, 'web-app.json') });
+    await publishContract(contract2, { outputPath: join(tmpDir, 'mobile-app.json') });
+
+    const result = await verifyContracts({
+      schema: FULL_SCHEMA,
+      contractsPath: tmpDir,
+    });
+
+    assert.equal(result.passed, true);
+    assert.equal(result.violations.length, 0);
+  });
+
+  it('returns passed true for empty contracts directory', async () => {
+    const emptyDir = join(tmpDir, 'empty');
+    await mkdir(emptyDir, { recursive: true });
+
+    const result = await verifyContracts({
+      schema: FULL_SCHEMA,
+      contractsPath: emptyDir,
+    });
+
+    assert.equal(result.passed, true);
+    assert.equal(result.violations.length, 0);
+  });
+
+  it('detects removed argument', async () => {
+    const contract = defineContract({
+      consumer: 'web-app',
+      provider: 'user-service',
+      operations: ['query GetUser { user(id: "1") { id email } }'],
+    });
+    await publishContract(contract, { outputPath: join(tmpDir, 'web-app.json') });
+
+    // Schema where user no longer takes an id argument
+    const noArgSchema = buildSchema(`
+      type Query {
+        user: User!
+      }
+
+      type User {
+        id: ID!
+        email: String!
+      }
+    `);
+
+    const result = await verifyContracts({
+      schema: noArgSchema,
+      contractsPath: tmpDir,
+    });
+
+    assert.equal(result.passed, false);
+    assert.ok(result.violations.length > 0);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "tests"]
+}