graphql-buddy 0.0.0 → 0.1.0

package/src/api/commands/validate.test.ts

@@ -4,32 +4,133 @@ import { describe, expect, it } from 'vitest';
 
 import * as validate from './validate';
 
+const schemaFixture = (name: string) => ({
+  files: [`**/*.graphql`],
+  base: nodePath.resolve(__dirname, `../../../test_fixtures/schema/${name}`),
+});
+
+/**
+ * Each documents fixture is self-contained: `<case>/schema` holds the schema
+ * the documents are validated against and `<case>/documents` holds the
+ * operations and fragments under test.
+ */
+const documentsFixture = (
+  name: string,
+  options: { pathAliases?: Map<string, string> } = {},
+) => {
+  const base = nodePath.resolve(
+    __dirname,
+    `../../../test_fixtures/documents/${name}`,
+  );
+  return {
+    schema: {
+      files: [`**/*.graphql`],
+      base: nodePath.join(base, `schema`),
+    },
+    operations: {
+      files: [`*.graphql`],
+      base: nodePath.join(base, `documents`),
+      pathAliases: options.pathAliases,
+    },
+  };
+};
+
 describe(`validate`, () => {
-  it(`creates a validation stamp when validation passes.`, async () => {
-    await expect(
-      validate.validate({
-        schema: {
-          files: [`*.graphql`],
-          base: nodePath.resolve(
-            __dirname,
-            `../../../test_fixtures/multiple_files`,
-          ),
-        },
-      }),
-    ).resolves.toStrictEqual(expect.any(String));
+  describe(`schema`, () => {
+    it(`creates a validation stamp when validation passes.`, async () => {
+      await expect(
+        validate.validate({ schema: schemaFixture(`multiple_files`) }),
+      ).resolves.toStrictEqual(expect.any(String));
+    });
+
+    it(`throws for invalid schema.`, async () => {
+      await expect(
+        validate.validate({ schema: schemaFixture(`missing_scalar`) }),
+      ).rejects.toThrowError(`Unknown type "DateTime"`);
+    });
   });
 
-  it(`throws for invalid schema.`, async () => {
-    await expect(
-      validate.validate({
-        schema: {
-          files: [`*.graphql`],
-          base: nodePath.resolve(
-            __dirname,
-            `../../../test_fixtures/missing_scalar`,
-          ),
-        },
-      }),
-    ).rejects.toThrowError(`Unknown type "DateTime"`);
+  describe(`documents`, () => {
+    it(`validates operations against the schema, resolving imported fragments.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`imported_fragment`)),
+      ).resolves.toStrictEqual(expect.any(String));
+    });
+
+    it(`resolves nested #import chains.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`nested_imports`)),
+      ).resolves.toStrictEqual(expect.any(String));
+    });
+
+    it(`resolves #import paths through path aliases.`, async () => {
+      await expect(
+        validate.validate(
+          documentsFixture(`aliased_import`, {
+            pathAliases: new Map([[`@fragments/*`, `fragments/*`]]),
+          }),
+        ),
+      ).resolves.toStrictEqual(expect.any(String));
+    });
+
+    it(`allows fragment-only files that nothing imports.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`fragment_library`)),
+      ).resolves.toStrictEqual(expect.any(String));
+    });
+
+    it(`still validates field selections inside fragment-only files.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`invalid_fragment`)),
+      ).rejects.toThrowError(`Cannot query field "thisFieldDoesNotExist"`);
+    });
+
+    it(`throws for operations that reference unknown fields.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`unknown_field`)),
+      ).rejects.toThrowError(`Cannot query field "thisFieldDoesNotExist"`);
+    });
+
+    it(`throws for operations files that contain type-system definitions.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`mixed_sdl`)),
+      ).rejects.toThrowError(`The "Bogus" definition is not executable.`);
+    });
+
+    it(`throws for #import of a file that does not exist.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`broken_import`)),
+      ).rejects.toThrowError(`Cannot find module './DoesNotExist.graphql'`);
+    });
+
+    it(`throws for unused variables.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`unused_variable`)),
+      ).rejects.toThrowError(`Variable "$id" is never used`);
+    });
+
+    it(`throws for missing required arguments.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`missing_argument`)),
+      ).rejects.toThrowError(
+        `Field "foo" argument "id" of type "ID!" is required`,
+      );
+    });
+
+    it(`throws for anonymous operations that share a document with named ones.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`anonymous_operation`)),
+      ).rejects.toThrowError(
+        `This anonymous operation must be the only defined operation.`,
+      );
+    });
+
+    // Documents are validated one file at a time, so an operation name reused
+    // across files is not detected. This pins that (documented) behavior.
+    it(`allows duplicate operation names across separate files.`, async () => {
+      await expect(
+        validate.validate(documentsFixture(`duplicate_names`)),
+      ).resolves.toStrictEqual(expect.any(String));
+    });
   });
 });

package/src/api/commands/validate.ts

@@ -3,12 +3,18 @@ import * as stringifyObject from 'stringify-object';
 import * as shared from '../shared';
 
 export type ValidateOptions = {
-  schema: shared.LoadSchemaOptions;
+  schema: shared.GraphqlFiles;
+
+  // Optional GraphQL operation documents (queries, mutations, subscriptions,
+  // and fragments) to validate against the loaded schema. When omitted, only
+  // the schema itself is validated.
+  operations?: shared.GraphqlFiles | null;
 };
 
 /**
  * Validates that the provided GraphQL schema contain valid syntax and have no
- * unknown symbols.
+ * unknown symbols. When operations are provided, additionally validates that
+ * every operation is valid against that schema.
  *
  * @param options - Validate options.
  *
@@ -22,28 +28,46 @@ export const validate = async (options: ValidateOptions): Promise<string> => {
   // accurate data in our validation stamp. For example, normalization expands
   // globs and resolves absolute paths. These are critical steps to ensure the
   // validation stamp describes without ambiguity which schema were loaded.
-  const normalizedSchemaOptions = await shared.normalizeLoadSchemaOptions(
+  const normalizedSchemaOptions = await shared.normalizeGraphqlFiles(
     options.schema,
   );
 
-  await shared.loadSchema(normalizedSchemaOptions);
+  const schema = await shared.loadSchema(normalizedSchemaOptions);
+
+  if (options.operations == null) {
+    return createValidationStamp({ schema: normalizedSchemaOptions });
+  }
+
+  const normalizedOperationsOptions = await shared.normalizeGraphqlFiles(
+    options.operations,
+  );
+  shared.validateDocuments({
+    schema,
+    documents: await shared.loadDocuments(normalizedOperationsOptions),
+  });
 
   return createValidationStamp({
-    ...options,
     schema: normalizedSchemaOptions,
+    operations: normalizedOperationsOptions,
   });
 };
 
-const createValidationStamp = (
-  options: Omit<ValidateOptions, `schema`> & {
-    schema: shared.NormalizedLoadSchemaOptions;
-  },
-): string =>
+const createValidationStamp = (options: {
+  schema: shared.NormalizedGraphqlFiles;
+  operations?: shared.NormalizedGraphqlFiles;
+}): string =>
   stringifyObject.default(
-    { options, outcome: { valid: true } },
+    {
+      options: {
+        schema: options.schema,
+        operations: options.operations,
+      },
+      outcome: { valid: true },
+    },
     {
       indent: `  `,
       filter: (container, property) =>
-        !(container === options.schema && property === `normalized`),
+        !(container === options.schema && property === `normalized`) &&
+        !(container === options.operations && property === `normalized`),
     },
   );

package/src/api/shared/GraphqlFiles.ts

@@ -0,0 +1,61 @@
+import * as nodePath from 'node:path';
+
+import * as glob from 'glob';
+
+export type GraphqlFiles = UnsafeGraphqlFiles | NormalizedGraphqlFiles;
+
+export type UnsafeGraphqlFiles = {
+  normalized?: false | null;
+
+  // Relative paths will be resolved using `base`.
+  //
+  // Also accepts glob patterns.
+  files: Array<string>;
+
+  // Directory from which `files` are resolved.
+  //
+  // Defaults to `process.cwd()`.
+  base?: string | null;
+
+  // See @graphql-tools/import#PathAliases
+  //
+  // Note that relative paths will be resolved relative to `base` to maintain
+  // parity with `files`.
+  pathAliases?: Map<string, string> | null;
+};
+
+export type NormalizedGraphqlFiles = {
+  normalized: true;
+
+  // Absolute paths.
+  files: Array<string>;
+
+  // See @graphql-tools/import#PathAliases
+  pathAliases: Map<string, string>;
+};
+
+export const normalizeGraphqlFiles = async (
+  graphqlFiles: GraphqlFiles,
+): Promise<NormalizedGraphqlFiles> => {
+  if (graphqlFiles.normalized) {
+    return graphqlFiles;
+  }
+
+  const base = graphqlFiles.base ?? process.cwd();
+  const files = await glob.glob(
+    graphqlFiles.files.map((file) => nodePath.resolve(base, file)),
+  );
+
+  const pathAliases = new Map<string, string>();
+  if (graphqlFiles.pathAliases != null) {
+    for (const [alias, source] of graphqlFiles.pathAliases.entries()) {
+      pathAliases.set(alias, nodePath.resolve(base, source));
+    }
+  }
+
+  return {
+    normalized: true,
+    files,
+    pathAliases,
+  };
+};

package/src/api/shared/index.ts

@@ -1 +1,4 @@
+export * from './GraphqlFiles';
+export * from './loadDocuments';
 export * from './loadSchema';
+export * from './validateDocuments';

package/src/api/shared/loadDocuments.ts

@@ -0,0 +1,48 @@
+import * as nodeFs from 'node:fs/promises';
+
+import * as graphqlFileLoader from '@graphql-tools/graphql-file-loader';
+import * as graphqlLoad from '@graphql-tools/load';
+
+import type * as graphqlUtils from '@graphql-tools/utils';
+
+import * as graphqlFilesModule from './GraphqlFiles';
+
+/**
+ * Loads, validates, and parses graphql documents.
+ *
+ * @param graphqlFiles - Operation or fragment files to process.
+ *
+ * @returns The parsed GraphQL documents (or throws an error if parsing fails).
+ */
+export const loadDocuments = async (
+  graphqlFiles: graphqlFilesModule.GraphqlFiles,
+): Promise<Array<graphqlUtils.Source>> => {
+  const { files, pathAliases } =
+    await graphqlFilesModule.normalizeGraphqlFiles(graphqlFiles);
+
+  // @graphql-tools/graphql-file-loader silently skips input files which are not
+  // found. I suspect this is so that it can delegate missing inputs to other
+  // loaders. For our purposes, this is undesirable because we want to inform
+  // clients if expected inputs are missing. For that reason, we manually
+  // validate that the files exist first.
+  for (const file of files) {
+    try {
+      await nodeFs.access(file, nodeFs.constants.F_OK);
+    } catch {
+      throw new Error(`File does not exist: ${file}`);
+    }
+  }
+
+  return await graphqlLoad.loadDocuments(files, {
+    loaders: [new graphqlFileLoader.GraphQLFileLoader()],
+    // By default @graphql-tools/load strips type definitions out of executable
+    // documents, so SDL that lands in an operations file (or a schema file
+    // caught by an operations glob) would silently vanish. Keeping every
+    // definition lets `ExecutableDefinitionsRule` reject it during validation
+    // instead.
+    filterKinds: [],
+    pathAliases: {
+      mappings: Object.fromEntries(pathAliases.entries()),
+    },
+  });
+};

package/src/api/shared/loadSchema.ts

@@ -1,38 +1,24 @@
 import * as nodeFs from 'node:fs/promises';
-import * as nodePath from 'node:path';
 
 import * as graphqlFileLoader from '@graphql-tools/graphql-file-loader';
 import * as graphqlLoad from '@graphql-tools/load';
-import * as glob from 'glob';
 
 import type * as graphql from 'graphql';
 
-export type LoadSchemaOptions = {
-  normalized?: false | null;
-
-  // Relative paths will be resolved using `base`.
-  //
-  // Also accepts glob patterns.
-  files: Array<string>;
-
-  // Directory from which `files` are resolved.
-  //
-  // Defaults to `process.cwd()`.
-  base?: string | null;
-
-  // See @graphql-tools/import#PathAliases
-  //
-  // Note that relative paths will be resolved relative to `base` to maintain
-  // parity with `files`.
-  pathAliases?: Map<string, string> | null;
-};
+import * as graphqlFilesModule from './GraphqlFiles';
 
+/**
+ * Loads, validates, and parses graphql schema.
+ *
+ * @param graphqlFiles - Schema files to process.
+ *
+ * @returns The parsed GraphQL schema (or throws an error if parsing fails).
+ */
 export const loadSchema = async (
-  options: LoadSchemaOptions | NormalizedLoadSchemaOptions,
+  graphqlFiles: graphqlFilesModule.GraphqlFiles,
 ): Promise<graphql.GraphQLSchema> => {
-  const { files, pathAliases } = options.normalized
-    ? options
-    : await normalizeLoadSchemaOptions(options);
+  const { files, pathAliases } =
+    await graphqlFilesModule.normalizeGraphqlFiles(graphqlFiles);
 
   // @graphql-tools/graphql-file-loader silently skips input files which are not
   // found. I suspect this is so that it can delegate missing inputs to other
@@ -54,35 +40,3 @@ export const loadSchema = async (
     },
   });
 };
-
-export type NormalizedLoadSchemaOptions = {
-  normalized: true;
-
-  // Absolute paths.
-  files: Array<string>;
-
-  // See @graphql-tools/import#PathAliases
-  pathAliases: Map<string, string>;
-};
-
-export const normalizeLoadSchemaOptions = async (
-  options: LoadSchemaOptions,
-): Promise<NormalizedLoadSchemaOptions> => {
-  const base = options.base ?? process.cwd();
-  const files = await glob.glob(
-    options.files.map((file) => nodePath.resolve(base, file)),
-  );
-
-  const pathAliases = new Map<string, string>();
-  if (options.pathAliases != null) {
-    for (const [alias, source] of options.pathAliases.entries()) {
-      pathAliases.set(alias, nodePath.resolve(base, source));
-    }
-  }
-
-  return {
-    normalized: true,
-    files,
-    pathAliases,
-  };
-};

package/src/api/shared/validateDocuments.ts

@@ -0,0 +1,45 @@
+import * as graphql from 'graphql';
+
+import type * as graphqlUtils from '@graphql-tools/utils';
+
+export type ValidateDocumentsOptions = {
+  schema: graphql.GraphQLSchema;
+  documents: Array<graphqlUtils.Source>;
+};
+
+/**
+ * Validates GraphQL documents against their target schema.
+ *
+ * @param options - Validation options (schema and documents).
+ *
+ * @throws GraphQLError instances when validation fails.
+ */
+export const validateDocuments = (options: ValidateDocumentsOptions): void => {
+  const { schema, documents } = options;
+
+  for (const source of documents) {
+    if (source.document == null) {
+      continue;
+    }
+
+    // Fragment-only documents are fragment "libraries" that operations pull in
+    // via `#import`. Validated in isolation they would trip
+    // `NoUnusedFragmentsRule`, so we drop that single rule for them. Every
+    // other rule, most importantly that each referenced field, argument, and
+    // type actually exists, are still enforced.
+    const definesOperation = source.document.definitions.some(
+      (definition) => definition.kind === graphql.Kind.OPERATION_DEFINITION,
+    );
+
+    const errors = graphql.validate(
+      schema,
+      source.document,
+      graphql.specifiedRules.filter(
+        (rule) => definesOperation || rule !== graphql.NoUnusedFragmentsRule,
+      ),
+    );
+    if (errors.length > 0) {
+      throw errors[0];
+    }
+  }
+};

package/src/cli/commands/validate.ts

@@ -9,7 +9,9 @@ import * as shared from '../shared';
 export const createValidateCommand = () =>
   new commander.Command()
     .name(`validate`)
-    .description(`Checks that all provided GraphQL files form a valid schema.`)
+    .description(
+      `Checks that all provided GraphQL files form a valid schema, and optionally that operations are valid against it.`,
+    )
     .argument(`<schema...>`, `Input GraphQL schema files to validate.`)
     .option(
       `-b, --base <directory>`,
@@ -19,6 +21,10 @@ export const createValidateCommand = () =>
       `-a, --alias <pattern...>`,
       `Path alias options for @graphql-tools/load.`,
     )
+    .option(
+      `-o, --operations <operations...>`,
+      `GraphQL operation documents to validate against the schema.`,
+    )
     .option(
       `--stamp <file>`,
       `Creates a validation stamp to confirm valid GraphQL schema.`,
@@ -35,18 +41,29 @@ const validate = async (options: {
   schema: Array<string>;
   base?: string;
   alias?: Array<string>;
+  operations?: Array<string>;
   stamp?: string;
   silent: boolean;
 }): Promise<void> => {
-  const { schema, base, alias, stamp, silent } = options;
+  const { schema, base, alias, operations, stamp, silent } = options;
 
-  const validationStamp = await api.validate({
+  const pathAliases = shared.parsePathAliases(alias ?? []);
+
+  const validateOptions: api.ValidateOptions = {
     schema: {
       files: schema,
       base,
-      pathAliases: shared.parsePathAliases(alias ?? []),
+      pathAliases,
     },
-  });
+  };
+  if (operations != null) {
+    validateOptions.operations = {
+      files: operations,
+      base,
+      pathAliases,
+    };
+  }
+  const validationStamp = await api.validate(validateOptions);
 
   if (stamp != null) {
     const destination = nodePath.resolve(base ?? process.cwd(), stamp);

package/src/cli/index.ts

@@ -7,6 +7,8 @@ import * as commands from './commands';
 
 const main = () => {
   process.setUncaughtExceptionCaptureCallback((error) => {
+    process.exitCode = 1;
+
     // When thrown natively, GraphQLError prints like any other error with
     // minimal context, however, when logged with `.toString()` it prints
     // helpful debugging information critical for debugging syntax errors (such

package/test_fixtures/documents/aliased_import/documents/AllFoo.graphql

@@ -0,0 +1,7 @@
+#import "@fragments/FooFields.graphql"
+
+query AllFoo {
+  allFoo {
+    ...FooFields
+  }
+}

package/test_fixtures/documents/aliased_import/documents/fragments/FooFields.graphql

@@ -0,0 +1,4 @@
+fragment FooFields on Foo {
+  id
+  name
+}

package/test_fixtures/documents/aliased_import/schema/schema.graphql

@@ -0,0 +1,20 @@
+type Query {
+  allFoo: [Foo!]!
+  foo(id: ID!): Foo
+}
+
+type Foo {
+  id: ID!
+  name: String
+  bar: Bar
+}
+
+type Bar {
+  baz: Baz
+}
+
+type Baz {
+  dateCreated: DateTime!
+}
+
+scalar DateTime

package/test_fixtures/documents/anonymous_operation/documents/Anonymous.graphql

@@ -0,0 +1,11 @@
+query {
+  allFoo {
+    id
+  }
+}
+
+query Named {
+  allFoo {
+    id
+  }
+}

package/test_fixtures/documents/anonymous_operation/schema/schema.graphql

@@ -0,0 +1,20 @@
+type Query {
+  allFoo: [Foo!]!
+  foo(id: ID!): Foo
+}
+
+type Foo {
+  id: ID!
+  name: String
+  bar: Bar
+}
+
+type Bar {
+  baz: Baz
+}
+
+type Baz {
+  dateCreated: DateTime!
+}
+
+scalar DateTime

package/test_fixtures/documents/broken_import/documents/AllFoo.graphql

@@ -0,0 +1,7 @@
+#import "./DoesNotExist.graphql"
+
+query AllFoo {
+  allFoo {
+    ...FooFields
+  }
+}

package/test_fixtures/documents/broken_import/schema/schema.graphql

@@ -0,0 +1,20 @@
+type Query {
+  allFoo: [Foo!]!
+  foo(id: ID!): Foo
+}
+
+type Foo {
+  id: ID!
+  name: String
+  bar: Bar
+}
+
+type Bar {
+  baz: Baz
+}
+
+type Baz {
+  dateCreated: DateTime!
+}
+
+scalar DateTime

package/test_fixtures/documents/duplicate_names/documents/First.graphql

@@ -0,0 +1,5 @@
+query AllFoo {
+  allFoo {
+    id
+  }
+}

package/test_fixtures/documents/duplicate_names/documents/Second.graphql

@@ -0,0 +1,5 @@
+query AllFoo {
+  allFoo {
+    name
+  }
+}

package/test_fixtures/documents/duplicate_names/schema/schema.graphql

@@ -0,0 +1,20 @@
+type Query {
+  allFoo: [Foo!]!
+  foo(id: ID!): Foo
+}
+
+type Foo {
+  id: ID!
+  name: String
+  bar: Bar
+}
+
+type Bar {
+  baz: Baz
+}
+
+type Baz {
+  dateCreated: DateTime!
+}
+
+scalar DateTime