@suss/contract-graphql 0.33.1 → 0.34.1

package/README.md

@@ -1,48 +1,48 @@
 # @suss/contract-graphql
 
-Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and says where the two disagree.
+Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and reports where the two disagree.
 
-Generate suss `BehavioralSummary[]` from GraphQL files a repository already commits. Two readers ship in this package, one for each side of a GraphQL boundary:
+This package builds suss `BehavioralSummary[]` from the GraphQL files a repository already commits. It has two readers, one for each side of a GraphQL boundary:
 
 | Reader | Input | Summaries |
 |--------|-------|-----------|
 | `suss contract --from graphql` | a plain SDL schema file | one `resolver`-kind summary per root field (the provider side) |
 | `suss contract --from graphql-documents` | `.graphql` / `.gql` operation documents | one `client`-kind summary per operation (the consumer side) |
 
-Either side pairs against the other, and against summaries extracted from code by the Apollo and NestJS packs. Nothing has to be traced through TypeScript first.
+Each side pairs with the other, and with summaries the Apollo and NestJS packs extract from code. Nothing has to be traced through TypeScript first.
 
 ## Reading a schema
 
-`graphqlSdlFileToSummaries` parses the SDL and walks every field on `Query`, `Mutation`, and `Subscription`, including fields added through `extend type Query { ... }`. Each field becomes one summary:
+`graphqlSdlFileToSummaries` parses the SDL and walks every field on `Query`, `Mutation` and `Subscription`, including fields added with `extend type Query { ... }`. Each field becomes one summary:
 
-- `identity.name` is `Type.field`, with a `graphql-resolver` boundary binding that records `transport: "http-graphql"`, `recognition: "graphql"`, and the type and field names. Both defaults are overridable, which is what you want when the same SDL backs several deployments and findings should tell them apart.
+- `identity.name` is `Type.field`, with a `graphql-resolver` boundary binding that records `transport: "http-graphql"`, `recognition: "graphql"`, and the type and field names. You can override both defaults, which helps when the same SDL backs several deployments and the findings should tell them apart.
 - Inputs come from the field's arguments, each with `role: "args"`.
-- Two transitions: a default success returning the field's declared shape, and a `GraphQLError` throw for the `errors[]` path.
-- `metadata.graphql.declaredContract` records the return type, the arguments with a `required` flag per argument, and the framework tag. Its provenance is `"derived"`, because the contract and the transitions come from the same field declaration and comparing one against the other would say nothing.
+- Two transitions: a default success that returns the field's declared shape, and a `GraphQLError` throw for the `errors[]` path.
+- `metadata.graphql.declaredContract` records the return type, the arguments with a `required` flag on each, and the framework tag. Its provenance is `"derived"`, because the contract and the transitions come from the same field declaration, and comparing one with the other would find nothing.
 
-One extra `library`-kind summary contains the SDL text itself, under `metadata.graphql.schemaSdl`. Type definitions belong to the schema rather than to any one field, so every resolver points at that document through a source-document label, and the checker follows the label to resolve a consumer's nested selections against a resolver's return type. That summary binds to no boundary, so pairing records it as taking no part.
+One extra `library`-kind summary contains the SDL text itself, under `metadata.graphql.schemaSdl`. Type definitions belong to the schema as a whole, so every resolver points at that document through a source-document label. The checker follows the label to resolve a consumer's nested selections against a resolver's return type. That summary does not bind to a boundary, so pairing records it as taking no part.
 
-Named types convert to `TypeShape` as follows: `String` and `ID` become `text`, `Int` and `Float` become `number`, `Boolean` becomes `boolean`, and any other named type becomes a `ref` with that name. A list becomes an `array`, and a non-null wrapper is dropped because `TypeShape` treats nullability as the absence of null in a union.
+Named types convert to `TypeShape` like this: `String` and `ID` become `text`, `Int` and `Float` become `number`, `Boolean` becomes `boolean`, and any other named type becomes a `ref` with that name. A list becomes an `array`. A non-null wrapper is dropped, because in a `TypeShape` a value is non-null when its union does not include null.
 
 ## Reading operation documents
 
-`graphqlDocumentsPathToSummaries` accepts a single file or a directory walked recursively for `.graphql` and `.gql` files (`node_modules` is skipped). Each query, mutation, and subscription definition becomes one summary:
+`graphqlDocumentsPathToSummaries` accepts a single file, or a directory that it searches recursively for `.graphql` and `.gql` files, skipping `node_modules`. Each query, mutation and subscription definition becomes one summary:
 
-- A `graphql-operation` boundary binding with the operation type and, when the operation is named, its name. The default recognition tag is `"graphql-documents"`, so findings distinguish these from operations traced at a call site.
-- Inputs from the operation's variable definitions, each with `role: "variable"`, the same role the TypeScript adapter stamps on `$variables` it recovers from a tagged template literal.
-- The full document text at `metadata.graphql.document`, the same place the TypeScript adapter puts documents it finds in code, so the checker's GraphQL pairing pass reads both alike.
-- A response shape approximated from the selection set. Field names become record properties and leaves become `unknown`, since a document does not declare field types. A field selected twice, once directly and once through a fragment, merges into one property the way a server would merge it.
+- A `graphql-operation` boundary binding with the operation type and, when the operation is named, its name. The default recognition tag is `"graphql-documents"`, so findings can tell these apart from operations found at a call site.
+- Inputs from the operation's variable definitions, each with `role: "variable"`. That is the same role the TypeScript adapter gives the `$variables` it finds in a tagged template literal.
+- The full document text at `metadata.graphql.document`, the same place the TypeScript adapter puts documents it finds in code, so the checker's GraphQL pairing pass reads both the same way.
+- A response shape estimated from the selection set. Field names become record properties and leaves become `unknown`, since a document does not declare field types. A field selected twice, once directly and once through a fragment, merges into one property, the way a server would merge it.
 
-Fragment spreads are resolved against every fragment definition in the read set and inlined into the stored document, so the pairing pass sees the selected fields directly. A spread the reader cannot expand stays in the document as written and becomes a gap on the summary rather than an error: the fragment may be missing from the read set, part of a cycle, or defined in more than one file. In the ambiguous case the first definition in read order wins and the gap says which files competed.
+Fragment spreads are resolved against every fragment definition in the files read, and inlined into the stored document, so the pairing pass sees the selected fields directly. A spread the reader cannot expand stays in the document as written, and becomes a gap on the summary instead of an error. The fragment may be missing from the files read, part of a cycle, or defined in more than one file. When it is defined more than once, the first definition in read order wins, and the gap lists which files had one.
 
-An anonymous operation is named after its path relative to the directory you passed, plus its operation type, so the name is the same on every machine that checks the repo out. Repeated names get a `#2` suffix, because transition ids are built from the name and a repeated id would make two operations look like one.
+An anonymous operation is named after its path relative to the directory you passed, plus its operation type, so the name is the same on every machine that checks out the repo. A repeated name gets a `#2` suffix, because transition ids are built from the name, and a repeated id would make two operations look like one.
 
 ## What neither reader does
 
-- **Non-root resolvers.** A schema reader summary is emitted for `Query`, `Mutation`, and `Subscription` fields. A field resolver on `Order.customer` is not a boundary summary today.
+- **Non-root resolvers.** The schema reader only produces summaries for `Query`, `Mutation` and `Subscription` fields. A field resolver on `Order.customer` does not get a boundary summary today.
 - **Directives, unions and interface resolution, and custom scalars** beyond the `ref` fallback are not modeled.
-- **Schema validation.** An SDL file that fails to parse comes back as an empty array rather than an error, and the documents reader skips a file it cannot parse so one bad file does not lose the rest.
-- **Cross-checking documents against a schema.** The documents reader never resolves a selected field's type; that pairing happens later in the checker, against the schema document summary.
+- **Schema validation.** An SDL file that fails to parse comes back as an empty array, with no error. The documents reader skips a file it cannot parse, so one bad file does not lose the rest.
+- **Checking documents against a schema.** The documents reader never resolves a selected field's type. The checker does that pairing later, against the schema document summary.
 
 ## Worked example
 
@@ -65,7 +65,7 @@ suss contract --from graphql-documents src/queries -o summaries/operations.json
 suss check summaries/schema.json summaries/operations.json
 ```
 
-Or programmatically:
+Or from code:
 
 ```ts
 import {
@@ -79,7 +79,7 @@ const consumer = graphqlDocumentsPathToSummaries("src/queries");
 
 ## Where it fits in suss
 
-Depends only on `@suss/behavioral-ir` (for the IR types it produces) and `graphql` (for parsing and printing). It does not extract from source code and is independent of the language adapters. `@suss/contract-appsync` reuses this package's SDL loader and type conversion for AppSync schemas declared in CloudFormation.
+The package depends only on `@suss/behavioral-ir`, for the IR types it produces, and `graphql`, for parsing and printing. It does not extract from source code and does not use the language adapters. `@suss/contract-appsync` reuses this package's SDL loader and type conversion for AppSync schemas declared in CloudFormation.
 
 ## More
 

package/dist/index.cjs

@@ -287,8 +287,8 @@ function buildVariableInputs(op) {
     type: "parameter",
     name: variable.variable.name.value,
     position: index,
-    // Same role the TypeScript adapter stamps on operation-header
-    // `$variables`, so downstream consumers treat both alike.
+    // The TypeScript adapter gives an operation's `$variables` the same
+    // role, so the checker treats both alike.
     role: "variable",
     shape: typeNodeToShape(variable.type)
   }));
@@ -335,9 +335,8 @@ function unexpandedSpreadGaps(unexpanded, fragments) {
   const gaps = [];
   for (const name of [...unexpanded.missing].sort()) {
     gaps.push(
-      // A statement about the reading, not the code: the fragment
-      // likely exists somewhere outside the files handed to this
-      // reader.
+      // The fragment is probably defined in a file this reader was not
+      // given.
       readingGap(
         `Fragment spread "...${name}" has no matching fragment definition in the read set; its selections are not part of this summary.`
       )
@@ -579,17 +578,13 @@ function buildResolverSummary(rootType, field, settings, definitions) {
     },
     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.
+    // Every type record in the document, so a comparison with the
+    // implementation has a structure to compare and not only a type name.
     ...Object.keys(definitions).length > 0 ? { definitions } : {},
     gaps: [],
     confidence: { source: "derived", level: "high" },
-    // Declared contract: checker pairs against any other source
-    // declaring a contract for the same gql:Type.field key. Provenance
-    // is "derived" because both this metadata and the summary's
-    // transitions come from the same SDL field declaration;
-    // self-comparison would be tautological.
+    // Provenance is "derived" because the transitions come from the same
+    // field declaration, so comparing the contract with them finds nothing.
     metadata: (0, import_behavioral_ir2.withGraphqlMetadata)(
       (0, import_behavioral_ir2.withSourceDocumentMetadata)(void 0, { label: source }),
       {

package/dist/index.d.cts

@@ -1,101 +1,109 @@
 import { BehavioralSummary, TypeShape } from '@suss/behavioral-ir';
 
+/**
+ * Reads committed `.graphql` and `.gql` operation documents and writes one
+ * client summary per operation, with no call site to trace. The document
+ * text goes where the TypeScript adapter puts documents it finds in code,
+ * so the checker's GraphQL pairing pass reads both the same way.
+ *
+ * Fragment spreads are inlined from every file read. The README describes
+ * what happens to a spread that cannot be expanded.
+ */
+
 interface GraphqlDocumentsOptions {
     /**
      * Recognition tag for the operation binding. Defaults to
-     * `"graphql-documents"` so findings distinguish document-derived
-     * operations from call-site-traced ones.
+     * `"graphql-documents"`, so findings can tell these operations apart
+     * from operations found at a call site.
      */
     recognition?: string;
     /**
-     * Transport to record on the boundary binding. Defaults to
-     * `"http-graphql"` to match the schema reader's resolver side.
+     * Transport recorded on the boundary binding. Defaults to
+     * `"http-graphql"`, the same as the schema reader.
      */
     transport?: string;
     /**
-     * Directory the document paths hang off. An anonymous operation is
-     * named after its path relative to this root, so the name stays the
-     * same on every machine that checks the repo out. Without it the
-     * path is used as given.
+     * The directory an anonymous operation's name is relative to, so the
+     * name is the same on every machine. Without it the path is used as is.
      */
     rootDir?: string;
 }
-/** One parsed source document, tagged with where it came from. */
+/** One document's text and the path it came from. */
 interface DocumentSource {
     /** Path recorded on each summary's `location.file`. */
     path: string;
-    /** Raw document text. */
     text: string;
 }
 /**
- * Convert in-memory operation documents into summaries. Fragments are
- * resolved across the whole set, so a fragment-only document
- * contributes definitions without producing summaries of its own.
+ * Converts documents already in memory into one summary per operation.
+ * Fragments resolve across the whole set, so a file of fragments alone
+ * contributes definitions but does not produce a summary.
  */
 declare function graphqlDocumentsToSummaries(sources: DocumentSource[], options?: GraphqlDocumentsOptions): BehavioralSummary[];
 /**
- * Read `.graphql` / `.gql` files from disk and convert them to
- * summaries. Unreadable files are skipped, so one bad path does not
- * lose the rest of the set.
+ * Reads `.graphql` and `.gql` files and converts them. A file that cannot
+ * be read is skipped, so one bad path does not lose the rest.
  */
 declare function graphqlDocumentFilesToSummaries(filepaths: string[], options?: GraphqlDocumentsOptions): BehavioralSummary[];
 /**
- * Accept either a single document file or a directory to walk
- * recursively for `.graphql` / `.gql` files. Entry point for the
- * CLI's `suss contract --from graphql-documents <path>`.
+ * Reads one document file, or every `.graphql` and `.gql` file under a
+ * directory, skipping `node_modules`. Throws when nothing exists at the
+ * path. `suss contract --from graphql-documents <path>` calls this.
  */
 declare function graphqlDocumentsPathToSummaries(specPath: string, options?: GraphqlDocumentsOptions): BehavioralSummary[];
 
 /**
- * The five standard GraphQL scalars, mapped to the shapes they read
- * as. Exported so packs whose library exposes the same scalars under
- * its own spelling can build on this table instead of restating it.
+ * The TypeShape for each of the five standard GraphQL scalars. A pack
+ * whose library spells the same scalars its own way can build on this
+ * table instead of copying it.
  */
 declare const SCALAR_SHAPES: Record<string, TypeShape>;
-/** Whether a document declares types. A document that does is a schema. */
+/** True when the document declares a type, which makes it a schema. */
 declare function describesTypes(text: string): boolean;
-/** Whether a document has an operation to read, rather than fragments alone. */
+/** True when the document has at least one operation. A file of fragments has none. */
 declare function describesOperations(text: string): boolean;
 
+/**
+ * Reads a plain GraphQL SDL file and writes one resolver summary for each
+ * field on Query, Mutation and Subscription. @suss/contract-appsync does
+ * the same for AppSync schemas declared in CloudFormation. The README
+ * describes what each summary contains.
+ */
+
 interface GraphqlContractOptions {
     /**
-     * Logical source path recorded on each summary's `location.file`.
-     * Defaults to `"graphql"` so summaries are identifiable even when
-     * the SDL came from a non-file source (in-memory string).
+     * The path recorded on each summary's `location.file`. Defaults to
+     * `"graphql"`, for SDL passed in as a string with no file behind it.
      */
     source?: string;
     /**
      * Recognition tag for the resolver binding. Defaults to `"graphql"`.
-     * Override when the same SDL is used by multiple deployments
-     * (`apollo-prod`, `apollo-staging`) and you want findings to
-     * distinguish them.
+     * When several deployments serve the same SDL, give each its own tag
+     * (`apollo-prod`, `apollo-staging`) so findings tell them apart.
      */
     recognition?: string;
     /**
-     * Transport to record on the boundary binding. Defaults to
-     * `"http-graphql"`: most GraphQL servers run over HTTPS.
+     * Transport recorded on the boundary binding. Defaults to
+     * `"http-graphql"`, since most GraphQL servers are served over HTTP.
      */
     transport?: string;
 }
 /**
- * Convert an SDL string into resolver-kind summaries. Used directly
- * when the caller has the SDL in memory; tests and the file-based
- * entry point share this code path.
+ * Converts SDL text into one resolver summary per root field, plus one
+ * summary for the schema document. Returns an empty array when the SDL
+ * does not parse or has no root fields.
  */
 declare function graphqlSdlToSummaries(sdl: string, options?: GraphqlContractOptions): BehavioralSummary[];
 /**
- * Read an SDL file from disk and convert it to summaries. Convenience
- * wrapper for the CLI's `suss contract --from graphql <file>` path.
+ * Reads an SDL file and converts it, recording the file path as the
+ * source. `suss contract --from graphql <file>` calls this.
  */
 declare function graphqlSdlFileToSummaries(filepath: string, options?: GraphqlContractOptions): BehavioralSummary[];
 /**
- * Read an SDL file from disk and return its text, or `null` when the
- * file can't be read. Shared entry point for callers that need the raw
- * SDL rather than the derived summaries, e.g. @suss/contract-appsync
- * resolving an external schema file referenced by a CloudFormation /
- * SAM template's `DefinitionS3Location` / `SchemaUri`. Reading fails
- * best-effort (missing file, permission error) so the caller can record
- * an unresolved-schema gap instead of throwing.
+ * Reads an SDL file and returns its text, or `null` when the file cannot
+ * be read. @suss/contract-appsync uses it for the schema file a template
+ * points at through `DefinitionS3Location` or `SchemaUri`, and records a
+ * gap on `null` so a missing file does not fail the run.
  */
 declare function loadSdlFile(filepath: string): string | null;
 

package/dist/index.d.ts

@@ -1,101 +1,109 @@
 import { BehavioralSummary, TypeShape } from '@suss/behavioral-ir';
 
+/**
+ * Reads committed `.graphql` and `.gql` operation documents and writes one
+ * client summary per operation, with no call site to trace. The document
+ * text goes where the TypeScript adapter puts documents it finds in code,
+ * so the checker's GraphQL pairing pass reads both the same way.
+ *
+ * Fragment spreads are inlined from every file read. The README describes
+ * what happens to a spread that cannot be expanded.
+ */
+
 interface GraphqlDocumentsOptions {
     /**
      * Recognition tag for the operation binding. Defaults to
-     * `"graphql-documents"` so findings distinguish document-derived
-     * operations from call-site-traced ones.
+     * `"graphql-documents"`, so findings can tell these operations apart
+     * from operations found at a call site.
      */
     recognition?: string;
     /**
-     * Transport to record on the boundary binding. Defaults to
-     * `"http-graphql"` to match the schema reader's resolver side.
+     * Transport recorded on the boundary binding. Defaults to
+     * `"http-graphql"`, the same as the schema reader.
      */
     transport?: string;
     /**
-     * Directory the document paths hang off. An anonymous operation is
-     * named after its path relative to this root, so the name stays the
-     * same on every machine that checks the repo out. Without it the
-     * path is used as given.
+     * The directory an anonymous operation's name is relative to, so the
+     * name is the same on every machine. Without it the path is used as is.
      */
     rootDir?: string;
 }
-/** One parsed source document, tagged with where it came from. */
+/** One document's text and the path it came from. */
 interface DocumentSource {
     /** Path recorded on each summary's `location.file`. */
     path: string;
-    /** Raw document text. */
     text: string;
 }
 /**
- * Convert in-memory operation documents into summaries. Fragments are
- * resolved across the whole set, so a fragment-only document
- * contributes definitions without producing summaries of its own.
+ * Converts documents already in memory into one summary per operation.
+ * Fragments resolve across the whole set, so a file of fragments alone
+ * contributes definitions but does not produce a summary.
  */
 declare function graphqlDocumentsToSummaries(sources: DocumentSource[], options?: GraphqlDocumentsOptions): BehavioralSummary[];
 /**
- * Read `.graphql` / `.gql` files from disk and convert them to
- * summaries. Unreadable files are skipped, so one bad path does not
- * lose the rest of the set.
+ * Reads `.graphql` and `.gql` files and converts them. A file that cannot
+ * be read is skipped, so one bad path does not lose the rest.
  */
 declare function graphqlDocumentFilesToSummaries(filepaths: string[], options?: GraphqlDocumentsOptions): BehavioralSummary[];
 /**
- * Accept either a single document file or a directory to walk
- * recursively for `.graphql` / `.gql` files. Entry point for the
- * CLI's `suss contract --from graphql-documents <path>`.
+ * Reads one document file, or every `.graphql` and `.gql` file under a
+ * directory, skipping `node_modules`. Throws when nothing exists at the
+ * path. `suss contract --from graphql-documents <path>` calls this.
  */
 declare function graphqlDocumentsPathToSummaries(specPath: string, options?: GraphqlDocumentsOptions): BehavioralSummary[];
 
 /**
- * The five standard GraphQL scalars, mapped to the shapes they read
- * as. Exported so packs whose library exposes the same scalars under
- * its own spelling can build on this table instead of restating it.
+ * The TypeShape for each of the five standard GraphQL scalars. A pack
+ * whose library spells the same scalars its own way can build on this
+ * table instead of copying it.
  */
 declare const SCALAR_SHAPES: Record<string, TypeShape>;
-/** Whether a document declares types. A document that does is a schema. */
+/** True when the document declares a type, which makes it a schema. */
 declare function describesTypes(text: string): boolean;
-/** Whether a document has an operation to read, rather than fragments alone. */
+/** True when the document has at least one operation. A file of fragments has none. */
 declare function describesOperations(text: string): boolean;
 
+/**
+ * Reads a plain GraphQL SDL file and writes one resolver summary for each
+ * field on Query, Mutation and Subscription. @suss/contract-appsync does
+ * the same for AppSync schemas declared in CloudFormation. The README
+ * describes what each summary contains.
+ */
+
 interface GraphqlContractOptions {
     /**
-     * Logical source path recorded on each summary's `location.file`.
-     * Defaults to `"graphql"` so summaries are identifiable even when
-     * the SDL came from a non-file source (in-memory string).
+     * The path recorded on each summary's `location.file`. Defaults to
+     * `"graphql"`, for SDL passed in as a string with no file behind it.
      */
     source?: string;
     /**
      * Recognition tag for the resolver binding. Defaults to `"graphql"`.
-     * Override when the same SDL is used by multiple deployments
-     * (`apollo-prod`, `apollo-staging`) and you want findings to
-     * distinguish them.
+     * When several deployments serve the same SDL, give each its own tag
+     * (`apollo-prod`, `apollo-staging`) so findings tell them apart.
      */
     recognition?: string;
     /**
-     * Transport to record on the boundary binding. Defaults to
-     * `"http-graphql"`: most GraphQL servers run over HTTPS.
+     * Transport recorded on the boundary binding. Defaults to
+     * `"http-graphql"`, since most GraphQL servers are served over HTTP.
      */
     transport?: string;
 }
 /**
- * Convert an SDL string into resolver-kind summaries. Used directly
- * when the caller has the SDL in memory; tests and the file-based
- * entry point share this code path.
+ * Converts SDL text into one resolver summary per root field, plus one
+ * summary for the schema document. Returns an empty array when the SDL
+ * does not parse or has no root fields.
  */
 declare function graphqlSdlToSummaries(sdl: string, options?: GraphqlContractOptions): BehavioralSummary[];
 /**
- * Read an SDL file from disk and convert it to summaries. Convenience
- * wrapper for the CLI's `suss contract --from graphql <file>` path.
+ * Reads an SDL file and converts it, recording the file path as the
+ * source. `suss contract --from graphql <file>` calls this.
  */
 declare function graphqlSdlFileToSummaries(filepath: string, options?: GraphqlContractOptions): BehavioralSummary[];
 /**
- * Read an SDL file from disk and return its text, or `null` when the
- * file can't be read. Shared entry point for callers that need the raw
- * SDL rather than the derived summaries, e.g. @suss/contract-appsync
- * resolving an external schema file referenced by a CloudFormation /
- * SAM template's `DefinitionS3Location` / `SchemaUri`. Reading fails
- * best-effort (missing file, permission error) so the caller can record
- * an unresolved-schema gap instead of throwing.
+ * Reads an SDL file and returns its text, or `null` when the file cannot
+ * be read. @suss/contract-appsync uses it for the schema file a template
+ * points at through `DefinitionS3Location` or `SchemaUri`, and records a
+ * gap on `null` so a missing file does not fail the run.
  */
 declare function loadSdlFile(filepath: string): string | null;
 

package/dist/index.js

@@ -262,8 +262,8 @@ function buildVariableInputs(op) {
     type: "parameter",
     name: variable.variable.name.value,
     position: index,
-    // Same role the TypeScript adapter stamps on operation-header
-    // `$variables`, so downstream consumers treat both alike.
+    // The TypeScript adapter gives an operation's `$variables` the same
+    // role, so the checker treats both alike.
     role: "variable",
     shape: typeNodeToShape(variable.type)
   }));
@@ -310,9 +310,8 @@ function unexpandedSpreadGaps(unexpanded, fragments) {
   const gaps = [];
   for (const name of [...unexpanded.missing].sort()) {
     gaps.push(
-      // A statement about the reading, not the code: the fragment
-      // likely exists somewhere outside the files handed to this
-      // reader.
+      // The fragment is probably defined in a file this reader was not
+      // given.
       readingGap(
         `Fragment spread "...${name}" has no matching fragment definition in the read set; its selections are not part of this summary.`
       )
@@ -554,17 +553,13 @@ function buildResolverSummary(rootType, field, settings, definitions) {
     },
     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.
+    // Every type record in the document, so a comparison with the
+    // implementation has a structure to compare and not only a type name.
     ...Object.keys(definitions).length > 0 ? { definitions } : {},
     gaps: [],
     confidence: { source: "derived", level: "high" },
-    // Declared contract: checker pairs against any other source
-    // declaring a contract for the same gql:Type.field key. Provenance
-    // is "derived" because both this metadata and the summary's
-    // transitions come from the same SDL field declaration;
-    // self-comparison would be tautological.
+    // Provenance is "derived" because the transitions come from the same
+    // field declaration, so comparing the contract with them finds nothing.
     metadata: withGraphqlMetadata2(
       withSourceDocumentMetadata(void 0, { label: source }),
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-graphql",
-  "version": "0.33.1",
+  "version": "0.34.1",
   "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": [
@@ -14,7 +14,7 @@
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
-  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/contract/graphql#readme",
+  "homepage": "https://suss.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nimbuscloud-ai/suss.git",
@@ -47,7 +47,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.33.1",
+    "@suss/behavioral-ir": "0.34.1",
     "graphql": "^16.8.0"
   },
   "devDependencies": {