@suss/contract-graphql 0.24.4 → 0.26.0

package/dist/index.cjs

@@ -31,6 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   SCALAR_SHAPES: () => SCALAR_SHAPES,
+  describesOperations: () => describesOperations,
+  describesTypes: () => describesTypes,
   graphqlDocumentFilesToSummaries: () => graphqlDocumentFilesToSummaries,
   graphqlDocumentsPathToSummaries: () => graphqlDocumentsPathToSummaries,
   graphqlDocumentsToSummaries: () => graphqlDocumentsToSummaries,
@@ -65,6 +67,51 @@ function scalarOrRef(node) {
   const name = node.name.value;
   return SCALAR_SHAPES[name] ?? { type: "ref", name };
 }
+function typeDefinitionsIn(doc) {
+  const definitions = {};
+  for (const node of doc.definitions) {
+    if (node.kind !== import_graphql.Kind.OBJECT_TYPE_DEFINITION && node.kind !== import_graphql.Kind.OBJECT_TYPE_EXTENSION && node.kind !== import_graphql.Kind.INTERFACE_TYPE_DEFINITION && node.kind !== import_graphql.Kind.INPUT_OBJECT_TYPE_DEFINITION) {
+      continue;
+    }
+    const properties = {
+      ...definitions[node.name.value]?.type === "record" ? definitions[node.name.value].properties : {}
+    };
+    for (const field of node.fields ?? []) {
+      properties[field.name.value] = typeNodeToShape(field.type);
+    }
+    definitions[node.name.value] = { type: "record", properties };
+  }
+  return definitions;
+}
+var SCHEMA_KINDS = /* @__PURE__ */ new Set([
+  import_graphql.Kind.SCHEMA_DEFINITION,
+  import_graphql.Kind.SCHEMA_EXTENSION,
+  import_graphql.Kind.OBJECT_TYPE_DEFINITION,
+  import_graphql.Kind.OBJECT_TYPE_EXTENSION,
+  import_graphql.Kind.INTERFACE_TYPE_DEFINITION,
+  import_graphql.Kind.INTERFACE_TYPE_EXTENSION,
+  import_graphql.Kind.INPUT_OBJECT_TYPE_DEFINITION,
+  import_graphql.Kind.INPUT_OBJECT_TYPE_EXTENSION,
+  import_graphql.Kind.ENUM_TYPE_DEFINITION,
+  import_graphql.Kind.ENUM_TYPE_EXTENSION,
+  import_graphql.Kind.UNION_TYPE_DEFINITION,
+  import_graphql.Kind.UNION_TYPE_EXTENSION,
+  import_graphql.Kind.SCALAR_TYPE_DEFINITION,
+  import_graphql.Kind.SCALAR_TYPE_EXTENSION
+]);
+function describesTypes(text) {
+  return definitionKinds(text).some((kind) => SCHEMA_KINDS.has(kind));
+}
+function describesOperations(text) {
+  return definitionKinds(text).includes(import_graphql.Kind.OPERATION_DEFINITION);
+}
+function definitionKinds(text) {
+  try {
+    return (0, import_graphql.parse)(text).definitions.map((definition) => definition.kind);
+  } catch {
+    return [];
+  }
+}
 
 // src/documents.ts
 var import_node_fs = __toESM(require("fs"), 1);
@@ -456,9 +503,10 @@ function graphqlSdlToSummaries(sdl, options = {}) {
   if (rootFields.length === 0) {
     return [];
   }
+  const definitions = typeDefinitionsIn(doc);
   const out = [buildSchemaDocumentSummary(settings)];
   for (const { rootType, field } of rootFields) {
-    out.push(buildResolverSummary(rootType, field, settings));
+    out.push(buildResolverSummary(rootType, field, settings, definitions));
   }
   return out;
 }
@@ -508,7 +556,7 @@ function collectRootFields(doc) {
 function isRootType(name) {
   return ROOT_TYPES.includes(name);
 }
-function buildResolverSummary(rootType, field, settings) {
+function buildResolverSummary(rootType, field, settings, definitions) {
   const { source, recognition, transport } = settings;
   const fieldName = field.name.value;
   const ownerKey = `${rootType}.${fieldName}`;
@@ -531,6 +579,10 @@ function buildResolverSummary(rootType, field, settings) {
     },
     inputs: buildInputs(field),
     transitions: buildTransitions2(ownerKey, field),
+    // The record behind each named type this field mentions, so a reader
+    // comparing the field against an implementation has structure on
+    // both sides rather than a name on one.
+    ...Object.keys(definitions).length > 0 ? { definitions } : {},
     gaps: [],
     confidence: { source: "derived", level: "high" },
     // Declared contract: checker pairs against any other source
@@ -628,6 +680,8 @@ function buildTransitions2(ownerKey, field) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SCALAR_SHAPES,
+  describesOperations,
+  describesTypes,
   graphqlDocumentFilesToSummaries,
   graphqlDocumentsPathToSummaries,
   graphqlDocumentsToSummaries,

package/dist/index.d.cts

@@ -52,6 +52,10 @@ declare function graphqlDocumentsPathToSummaries(specPath: string, options?: Gra
  * its own spelling can build on this table instead of restating it.
  */
 declare const SCALAR_SHAPES: Record<string, TypeShape>;
+/** Whether a document declares types. A document that does is a schema. */
+declare function describesTypes(text: string): boolean;
+/** Whether a document has an operation to read, rather than fragments alone. */
+declare function describesOperations(text: string): boolean;
 
 interface GraphqlContractOptions {
     /**
@@ -95,4 +99,4 @@ declare function graphqlSdlFileToSummaries(filepath: string, options?: GraphqlCo
  */
 declare function loadSdlFile(filepath: string): string | null;
 
-export { type GraphqlContractOptions, type GraphqlDocumentsOptions, SCALAR_SHAPES, graphqlDocumentFilesToSummaries, graphqlDocumentsPathToSummaries, graphqlDocumentsToSummaries, graphqlSdlFileToSummaries, graphqlSdlToSummaries, loadSdlFile };
+export { type GraphqlContractOptions, type GraphqlDocumentsOptions, SCALAR_SHAPES, describesOperations, describesTypes, graphqlDocumentFilesToSummaries, graphqlDocumentsPathToSummaries, graphqlDocumentsToSummaries, graphqlSdlFileToSummaries, graphqlSdlToSummaries, loadSdlFile };

package/dist/index.d.ts

@@ -52,6 +52,10 @@ declare function graphqlDocumentsPathToSummaries(specPath: string, options?: Gra
  * its own spelling can build on this table instead of restating it.
  */
 declare const SCALAR_SHAPES: Record<string, TypeShape>;
+/** Whether a document declares types. A document that does is a schema. */
+declare function describesTypes(text: string): boolean;
+/** Whether a document has an operation to read, rather than fragments alone. */
+declare function describesOperations(text: string): boolean;
 
 interface GraphqlContractOptions {
     /**
@@ -95,4 +99,4 @@ declare function graphqlSdlFileToSummaries(filepath: string, options?: GraphqlCo
  */
 declare function loadSdlFile(filepath: string): string | null;
 
-export { type GraphqlContractOptions, type GraphqlDocumentsOptions, SCALAR_SHAPES, graphqlDocumentFilesToSummaries, graphqlDocumentsPathToSummaries, graphqlDocumentsToSummaries, graphqlSdlFileToSummaries, graphqlSdlToSummaries, loadSdlFile };
+export { type GraphqlContractOptions, type GraphqlDocumentsOptions, SCALAR_SHAPES, describesOperations, describesTypes, graphqlDocumentFilesToSummaries, graphqlDocumentsPathToSummaries, graphqlDocumentsToSummaries, graphqlSdlFileToSummaries, graphqlSdlToSummaries, loadSdlFile };

package/dist/index.js

@@ -11,7 +11,10 @@ import {
 } from "@suss/behavioral-ir";
 
 // src/typeShape.ts
-import { Kind } from "graphql";
+import {
+  parse as graphqlParse,
+  Kind
+} from "graphql";
 var SCALAR_SHAPES = {
   String: { type: "text" },
   ID: { type: "text" },
@@ -32,6 +35,51 @@ function scalarOrRef(node) {
   const name = node.name.value;
   return SCALAR_SHAPES[name] ?? { type: "ref", name };
 }
+function typeDefinitionsIn(doc) {
+  const definitions = {};
+  for (const node of doc.definitions) {
+    if (node.kind !== Kind.OBJECT_TYPE_DEFINITION && node.kind !== Kind.OBJECT_TYPE_EXTENSION && node.kind !== Kind.INTERFACE_TYPE_DEFINITION && node.kind !== Kind.INPUT_OBJECT_TYPE_DEFINITION) {
+      continue;
+    }
+    const properties = {
+      ...definitions[node.name.value]?.type === "record" ? definitions[node.name.value].properties : {}
+    };
+    for (const field of node.fields ?? []) {
+      properties[field.name.value] = typeNodeToShape(field.type);
+    }
+    definitions[node.name.value] = { type: "record", properties };
+  }
+  return definitions;
+}
+var SCHEMA_KINDS = /* @__PURE__ */ new Set([
+  Kind.SCHEMA_DEFINITION,
+  Kind.SCHEMA_EXTENSION,
+  Kind.OBJECT_TYPE_DEFINITION,
+  Kind.OBJECT_TYPE_EXTENSION,
+  Kind.INTERFACE_TYPE_DEFINITION,
+  Kind.INTERFACE_TYPE_EXTENSION,
+  Kind.INPUT_OBJECT_TYPE_DEFINITION,
+  Kind.INPUT_OBJECT_TYPE_EXTENSION,
+  Kind.ENUM_TYPE_DEFINITION,
+  Kind.ENUM_TYPE_EXTENSION,
+  Kind.UNION_TYPE_DEFINITION,
+  Kind.UNION_TYPE_EXTENSION,
+  Kind.SCALAR_TYPE_DEFINITION,
+  Kind.SCALAR_TYPE_EXTENSION
+]);
+function describesTypes(text) {
+  return definitionKinds(text).some((kind) => SCHEMA_KINDS.has(kind));
+}
+function describesOperations(text) {
+  return definitionKinds(text).includes(Kind.OPERATION_DEFINITION);
+}
+function definitionKinds(text) {
+  try {
+    return graphqlParse(text).definitions.map((definition) => definition.kind);
+  } catch {
+    return [];
+  }
+}
 
 // src/documents.ts
 import fs from "fs";
@@ -430,9 +478,10 @@ function graphqlSdlToSummaries(sdl, options = {}) {
   if (rootFields.length === 0) {
     return [];
   }
+  const definitions = typeDefinitionsIn(doc);
   const out = [buildSchemaDocumentSummary(settings)];
   for (const { rootType, field } of rootFields) {
-    out.push(buildResolverSummary(rootType, field, settings));
+    out.push(buildResolverSummary(rootType, field, settings, definitions));
   }
   return out;
 }
@@ -482,7 +531,7 @@ function collectRootFields(doc) {
 function isRootType(name) {
   return ROOT_TYPES.includes(name);
 }
-function buildResolverSummary(rootType, field, settings) {
+function buildResolverSummary(rootType, field, settings, definitions) {
   const { source, recognition, transport } = settings;
   const fieldName = field.name.value;
   const ownerKey = `${rootType}.${fieldName}`;
@@ -505,6 +554,10 @@ function buildResolverSummary(rootType, field, settings) {
     },
     inputs: buildInputs(field),
     transitions: buildTransitions2(ownerKey, field),
+    // The record behind each named type this field mentions, so a reader
+    // comparing the field against an implementation has structure on
+    // both sides rather than a name on one.
+    ...Object.keys(definitions).length > 0 ? { definitions } : {},
     gaps: [],
     confidence: { source: "derived", level: "high" },
     // Declared contract: checker pairs against any other source
@@ -601,6 +654,8 @@ function buildTransitions2(ownerKey, field) {
 }
 export {
   SCALAR_SHAPES,
+  describesOperations,
+  describesTypes,
   graphqlDocumentFilesToSummaries,
   graphqlDocumentsPathToSummaries,
   graphqlDocumentsToSummaries,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-graphql",
-  "version": "0.24.4",
+  "version": "0.26.0",
   "type": "module",
   "description": "Turn a GraphQL schema or a committed operation document into a suss contract and check it against the resolvers and clients on either side.",
   "keywords": [
@@ -47,7 +47,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.24.4",
+    "@suss/behavioral-ir": "0.26.0",
     "graphql": "^16.8.0"
   },
   "devDependencies": {