@suss/contract-graphql 0.0.2 → 0.1.1

package/dist/index.cjs

@@ -30,19 +30,420 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  graphqlDocumentFilesToSummaries: () => graphqlDocumentFilesToSummaries,
+  graphqlDocumentsPathToSummaries: () => graphqlDocumentsPathToSummaries,
+  graphqlDocumentsToSummaries: () => graphqlDocumentsToSummaries,
   graphqlSdlFileToSummaries: () => graphqlSdlFileToSummaries,
   graphqlSdlToSummaries: () => graphqlSdlToSummaries,
   loadSdlFile: () => loadSdlFile
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_fs = __toESM(require("fs"), 1);
+var import_node_fs2 = __toESM(require("fs"), 1);
+var import_graphql3 = require("graphql");
+var import_behavioral_ir2 = require("@suss/behavioral-ir");
+
+// src/typeShape.ts
 var import_graphql = require("graphql");
+var SCALAR_SHAPES = {
+  String: { type: "text" },
+  ID: { type: "text" },
+  Int: { type: "number" },
+  Float: { type: "number" },
+  Boolean: { type: "boolean" }
+};
+function typeNodeToShape(node) {
+  if (node.kind === import_graphql.Kind.NON_NULL_TYPE) {
+    return typeNodeToShape(node.type);
+  }
+  if (node.kind === import_graphql.Kind.LIST_TYPE) {
+    return { type: "array", items: typeNodeToShape(node.type) };
+  }
+  return scalarOrRef(node);
+}
+function scalarOrRef(node) {
+  const name = node.name.value;
+  return SCALAR_SHAPES[name] ?? { type: "ref", name };
+}
+
+// src/documents.ts
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_graphql2 = require("graphql");
 var import_behavioral_ir = require("@suss/behavioral-ir");
+function graphqlDocumentsToSummaries(sources, options = {}) {
+  const recognition = options.recognition ?? "graphql-documents";
+  const transport = options.transport ?? "http-graphql";
+  const parsed = [];
+  for (const source of sources) {
+    const doc = safeParse(source.text);
+    if (doc === null) {
+      continue;
+    }
+    parsed.push({ source, doc });
+  }
+  const fragments = collectFragments(parsed);
+  const takenNames = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const { source, doc } of parsed) {
+    for (const def of doc.definitions) {
+      if (def.kind !== import_graphql2.Kind.OPERATION_DEFINITION) {
+        continue;
+      }
+      const name = distinctName(
+        operationName(def, source.path, options.rootDir),
+        takenNames
+      );
+      out.push(
+        buildOperationSummary(def, name, source.path, fragments, {
+          recognition,
+          transport
+        })
+      );
+    }
+  }
+  return out;
+}
+function operationName(op, file, rootDir) {
+  const declared = op.name?.value;
+  if (declared !== void 0) {
+    return declared;
+  }
+  return `${displayPath(file, rootDir)}:${op.operation}`;
+}
+function displayPath(file, rootDir) {
+  if (rootDir === void 0) {
+    return file;
+  }
+  const relative = import_node_path.default.relative(rootDir, file);
+  if (relative === "" || relative.startsWith("..")) {
+    return file;
+  }
+  return relative.split(import_node_path.default.sep).join("/");
+}
+function distinctName(candidate, taken) {
+  let name = candidate;
+  let suffix = 2;
+  while (taken.has(name)) {
+    name = `${candidate}#${suffix}`;
+    suffix += 1;
+  }
+  taken.add(name);
+  return name;
+}
+function graphqlDocumentFilesToSummaries(filepaths, options = {}) {
+  const sources = [];
+  for (const filepath of filepaths) {
+    let text;
+    try {
+      text = import_node_fs.default.readFileSync(filepath, "utf8");
+    } catch {
+      continue;
+    }
+    sources.push({ path: filepath, text });
+  }
+  return graphqlDocumentsToSummaries(sources, options);
+}
+function graphqlDocumentsPathToSummaries(specPath, options = {}) {
+  const absolute = import_node_path.default.resolve(specPath);
+  if (!import_node_fs.default.existsSync(absolute)) {
+    throw new Error(
+      `No GraphQL documents found at "${specPath}". Pass a .graphql/.gql file or a directory containing them.`
+    );
+  }
+  const stat = import_node_fs.default.statSync(absolute);
+  const isDirectory = stat.isDirectory();
+  const files = isDirectory ? walkForDocuments(absolute) : [absolute];
+  return graphqlDocumentFilesToSummaries(files, {
+    rootDir: isDirectory ? absolute : import_node_path.default.dirname(absolute),
+    ...options
+  });
+}
+function walkForDocuments(dir) {
+  const out = [];
+  const entries = import_node_fs.default.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = import_node_path.default.join(dir, entry.name);
+    if (entry.isFile()) {
+      if (/\.(graphql|gql)$/.test(entry.name)) {
+        out.push(full);
+      }
+    } else if (entry.isDirectory() && entry.name !== "node_modules") {
+      out.push(...walkForDocuments(full));
+    }
+  }
+  return out.sort();
+}
+function collectFragments(parsed) {
+  const definitions = /* @__PURE__ */ new Map();
+  const definingFiles = /* @__PURE__ */ new Map();
+  for (const { source, doc } of parsed) {
+    for (const def of doc.definitions) {
+      if (def.kind !== import_graphql2.Kind.FRAGMENT_DEFINITION) {
+        continue;
+      }
+      const name = def.name.value;
+      if (!definitions.has(name)) {
+        definitions.set(name, def);
+      }
+      definingFiles.set(name, [
+        ...definingFiles.get(name) ?? [],
+        source.path
+      ]);
+    }
+  }
+  const competingFiles = /* @__PURE__ */ new Map();
+  for (const [name, files] of definingFiles) {
+    if (files.length > 1) {
+      competingFiles.set(name, files);
+    }
+  }
+  return { definitions, competingFiles };
+}
+function buildOperationSummary(op, name, file, fragments, config) {
+  const operationType = op.operation;
+  const operationName2 = op.name?.value;
+  const unexpanded = emptyUnexpandedSpreads();
+  const inlined = inlineSpreadsInOperation(op, fragments, unexpanded);
+  const documentText = (0, import_graphql2.print)(documentOf(inlined));
+  const responseShape = selectionSetToShape(inlined.selectionSet);
+  return {
+    kind: "client",
+    location: {
+      file,
+      range: { start: op.loc?.start ?? 0, end: op.loc?.end ?? 0 },
+      exportName: null
+    },
+    identity: {
+      name,
+      exportPath: null,
+      boundaryBinding: (0, import_behavioral_ir.graphqlOperationBinding)({
+        transport: config.transport,
+        recognition: config.recognition,
+        operationType,
+        ...operationName2 !== void 0 ? { operationName: operationName2 } : {}
+      })
+    },
+    inputs: buildVariableInputs(op),
+    transitions: buildTransitions(name, responseShape),
+    gaps: unexpandedSpreadGaps(unexpanded, fragments),
+    confidence: { source: "declared", level: "high" },
+    metadata: {
+      graphql: {
+        document: documentText,
+        ...unexpanded.missing.size > 0 ? { unresolvedFragments: [...unexpanded.missing].sort() } : {}
+      }
+    }
+  };
+}
+function buildVariableInputs(op) {
+  const variables = op.variableDefinitions ?? [];
+  return variables.map((variable, index) => ({
+    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.
+    role: "variable",
+    shape: typeNodeToShape(variable.type)
+  }));
+}
+function buildTransitions(name, responseShape) {
+  return [
+    {
+      id: `${name}:return:success`,
+      conditions: [],
+      output: { type: "return", value: responseShape },
+      effects: [],
+      location: { start: 0, end: 0 },
+      isDefault: true,
+      confidence: { source: "declared", level: "high" },
+      metadata: {
+        source: "graphql:operation.success"
+      }
+    },
+    {
+      id: `${name}:throw:error`,
+      conditions: [
+        {
+          type: "opaque",
+          sourceText: "graphql:operation-error",
+          reason: "externalFunction"
+        }
+      ],
+      output: {
+        type: "throw",
+        exceptionType: "GraphQLError",
+        message: null
+      },
+      effects: [],
+      location: { start: 0, end: 0 },
+      isDefault: false,
+      confidence: { source: "declared", level: "low" },
+      metadata: {
+        source: "graphql:operation.error"
+      }
+    }
+  ];
+}
+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.
+      readingGap(
+        `Fragment spread "...${name}" has no matching fragment definition in the read set; its selections are not part of this summary.`
+      )
+    );
+  }
+  for (const name of [...unexpanded.cyclic].sort()) {
+    gaps.push(
+      readingGap(
+        `Fragment spread "...${name}" is part of a fragment cycle, which no server would execute; the repeated spread was left unexpanded.`
+      )
+    );
+  }
+  for (const name of [...unexpanded.ambiguous].sort()) {
+    const files = fragments.competingFiles.get(name) ?? [];
+    gaps.push(
+      readingGap(
+        `Fragment "${name}" is defined in more than one file (${files.join(", ")}); the first definition was used, so the selections here may not be the ones the build resolves.`
+      )
+    );
+  }
+  return gaps;
+}
+function readingGap(description) {
+  return {
+    type: "unreadOutcome",
+    conditions: [],
+    consequence: "unknown",
+    description
+  };
+}
+function emptyUnexpandedSpreads() {
+  return { missing: /* @__PURE__ */ new Set(), cyclic: /* @__PURE__ */ new Set(), ambiguous: /* @__PURE__ */ new Set() };
+}
+function inlineSpreadsInOperation(op, fragments, unexpanded) {
+  return {
+    ...op,
+    selectionSet: inlineSelectionSet(
+      op.selectionSet,
+      fragments,
+      [],
+      unexpanded
+    )
+  };
+}
+function inlineSelectionSet(selectionSet, fragments, stack, unexpanded) {
+  const out = [];
+  for (const selection of selectionSet.selections) {
+    out.push(...inlineOneSelection(selection, fragments, stack, unexpanded));
+  }
+  return { ...selectionSet, selections: out };
+}
+function inlineOneSelection(selection, fragments, stack, unexpanded) {
+  if (selection.kind === import_graphql2.Kind.FIELD) {
+    if (selection.selectionSet === void 0) {
+      return [selection];
+    }
+    const field = {
+      ...selection,
+      selectionSet: inlineSelectionSet(
+        selection.selectionSet,
+        fragments,
+        stack,
+        unexpanded
+      )
+    };
+    return [field];
+  }
+  if (selection.kind === import_graphql2.Kind.FRAGMENT_SPREAD) {
+    const fragmentName = selection.name.value;
+    if (fragments.competingFiles.has(fragmentName)) {
+      unexpanded.ambiguous.add(fragmentName);
+    }
+    if (stack.includes(fragmentName)) {
+      unexpanded.cyclic.add(fragmentName);
+      return [selection];
+    }
+    const fragment = fragments.definitions.get(fragmentName);
+    if (fragment === void 0) {
+      unexpanded.missing.add(fragmentName);
+      return [selection];
+    }
+    const inlined = inlineSelectionSet(
+      fragment.selectionSet,
+      fragments,
+      [...stack, fragmentName],
+      unexpanded
+    );
+    return [...inlined.selections];
+  }
+  const inlineFragment = {
+    ...selection,
+    selectionSet: inlineSelectionSet(
+      selection.selectionSet,
+      fragments,
+      stack,
+      unexpanded
+    )
+  };
+  return [inlineFragment];
+}
+function documentOf(op) {
+  const definitions = [op];
+  return { kind: import_graphql2.Kind.DOCUMENT, definitions };
+}
+function selectionSetToShape(selectionSet) {
+  const properties = {};
+  mergeSelectionsInto(properties, selectionSet.selections);
+  return { type: "record", properties };
+}
+function mergeSelectionsInto(properties, selections) {
+  for (const selection of selections) {
+    if (selection.kind === import_graphql2.Kind.FIELD) {
+      const key = selection.alias?.value ?? selection.name.value;
+      const selected = selection.selectionSet !== void 0 ? selectionSetToShape(selection.selectionSet) : { type: "unknown" };
+      properties[key] = mergeShapes(properties[key], selected);
+      continue;
+    }
+    if (selection.kind === import_graphql2.Kind.INLINE_FRAGMENT) {
+      mergeSelectionsInto(properties, selection.selectionSet.selections);
+    }
+  }
+}
+function mergeShapes(existing, incoming) {
+  if (existing === void 0) {
+    return incoming;
+  }
+  if (existing.type === "record" && incoming.type === "record") {
+    const properties = { ...existing.properties };
+    for (const [key, shape] of Object.entries(incoming.properties)) {
+      properties[key] = mergeShapes(properties[key], shape);
+    }
+    return { type: "record", properties };
+  }
+  if (existing.type === "record") {
+    return existing;
+  }
+  return incoming;
+}
+function safeParse(text) {
+  try {
+    return (0, import_graphql2.parse)(text);
+  } catch {
+    return null;
+  }
+}
+
+// src/index.ts
 var ROOT_TYPES = ["Query", "Mutation", "Subscription"];
 function graphqlSdlToSummaries(sdl, options = {}) {
   let doc;
   try {
-    doc = (0, import_graphql.parse)(sdl);
+    doc = (0, import_graphql3.parse)(sdl);
   } catch (_err) {
     return [];
   }
@@ -59,7 +460,7 @@ function graphqlSdlToSummaries(sdl, options = {}) {
   return out;
 }
 function graphqlSdlFileToSummaries(filepath, options = {}) {
-  const sdl = import_node_fs.default.readFileSync(filepath, "utf8");
+  const sdl = import_node_fs2.default.readFileSync(filepath, "utf8");
   return graphqlSdlToSummaries(sdl, {
     source: filepath,
     ...options
@@ -67,7 +468,7 @@ function graphqlSdlFileToSummaries(filepath, options = {}) {
 }
 function loadSdlFile(filepath) {
   try {
-    return import_node_fs.default.readFileSync(filepath, "utf8");
+    return import_node_fs2.default.readFileSync(filepath, "utf8");
   } catch {
     return null;
   }
@@ -75,7 +476,7 @@ function loadSdlFile(filepath) {
 function collectRootFields(doc) {
   const fieldsByRoot = /* @__PURE__ */ new Map();
   for (const def of doc.definitions) {
-    const node = def.kind === import_graphql.Kind.OBJECT_TYPE_DEFINITION || def.kind === import_graphql.Kind.OBJECT_TYPE_EXTENSION ? def : null;
+    const node = def.kind === import_graphql3.Kind.OBJECT_TYPE_DEFINITION || def.kind === import_graphql3.Kind.OBJECT_TYPE_EXTENSION ? def : null;
     if (node === null) {
       continue;
     }
@@ -117,7 +518,7 @@ function buildResolverSummary(rootType, field, source, recognition, transport) {
     identity: {
       name: ownerKey,
       exportPath: null,
-      boundaryBinding: (0, import_behavioral_ir.graphqlResolverBinding)({
+      boundaryBinding: (0, import_behavioral_ir2.graphqlResolverBinding)({
         transport,
         recognition,
         typeName: rootType,
@@ -125,7 +526,7 @@ function buildResolverSummary(rootType, field, source, recognition, transport) {
       })
     },
     inputs: buildInputs(field),
-    transitions: buildTransitions(ownerKey, field),
+    transitions: buildTransitions2(ownerKey, field),
     gaps: [],
     confidence: { source: "derived", level: "high" },
     metadata: {
@@ -148,7 +549,7 @@ function buildDeclaredContract(field, recognition) {
     args: (field.arguments ?? []).map((arg) => ({
       name: arg.name.value,
       type: typeNodeToShape(arg.type),
-      required: arg.type.kind === import_graphql.Kind.NON_NULL_TYPE
+      required: arg.type.kind === import_graphql3.Kind.NON_NULL_TYPE
     })),
     provenance: "derived",
     framework: recognition
@@ -164,7 +565,7 @@ function buildInputs(field) {
     shape: typeNodeToShape(arg.type)
   }));
 }
-function buildTransitions(ownerKey, field) {
+function buildTransitions2(ownerKey, field) {
   const returnShape = typeNodeToShape(field.type);
   return [
     {
@@ -203,32 +604,11 @@ function buildTransitions(ownerKey, field) {
     }
   ];
 }
-function typeNodeToShape(node) {
-  if (node.kind === import_graphql.Kind.NON_NULL_TYPE) {
-    return typeNodeToShape(node.type);
-  }
-  if (node.kind === import_graphql.Kind.LIST_TYPE) {
-    return { type: "array", items: typeNodeToShape(node.type) };
-  }
-  return scalarOrRef(node);
-}
-function scalarOrRef(node) {
-  const name = node.name.value;
-  switch (name) {
-    case "String":
-    case "ID":
-      return { type: "text" };
-    case "Int":
-    case "Float":
-      return { type: "number" };
-    case "Boolean":
-      return { type: "boolean" };
-    default:
-      return { type: "ref", name };
-  }
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  graphqlDocumentFilesToSummaries,
+  graphqlDocumentsPathToSummaries,
+  graphqlDocumentsToSummaries,
   graphqlSdlFileToSummaries,
   graphqlSdlToSummaries,
   loadSdlFile

package/dist/index.d.cts

@@ -1,5 +1,51 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 
+interface GraphqlDocumentsOptions {
+    /**
+     * Recognition tag for the operation binding. Defaults to
+     * `"graphql-documents"` so findings distinguish document-derived
+     * operations from call-site-traced ones.
+     */
+    recognition?: string;
+    /**
+     * Transport to record on the boundary binding. Defaults to
+     * `"http-graphql"` to match the schema reader's resolver side.
+     */
+    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.
+     */
+    rootDir?: string;
+}
+/** One parsed source document, tagged with where 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.
+ */
+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.
+ */
+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>`.
+ */
+declare function graphqlDocumentsPathToSummaries(specPath: string, options?: GraphqlDocumentsOptions): BehavioralSummary[];
+
 interface GraphqlContractOptions {
     /**
      * Logical source path recorded on each summary's `location.file`.
@@ -42,4 +88,4 @@ declare function graphqlSdlFileToSummaries(filepath: string, options?: GraphqlCo
  */
 declare function loadSdlFile(filepath: string): string | null;
 
-export { type GraphqlContractOptions, graphqlSdlFileToSummaries, graphqlSdlToSummaries, loadSdlFile };
+export { type GraphqlContractOptions, type GraphqlDocumentsOptions, graphqlDocumentFilesToSummaries, graphqlDocumentsPathToSummaries, graphqlDocumentsToSummaries, graphqlSdlFileToSummaries, graphqlSdlToSummaries, loadSdlFile };

package/dist/index.d.ts

@@ -1,5 +1,51 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 
+interface GraphqlDocumentsOptions {
+    /**
+     * Recognition tag for the operation binding. Defaults to
+     * `"graphql-documents"` so findings distinguish document-derived
+     * operations from call-site-traced ones.
+     */
+    recognition?: string;
+    /**
+     * Transport to record on the boundary binding. Defaults to
+     * `"http-graphql"` to match the schema reader's resolver side.
+     */
+    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.
+     */
+    rootDir?: string;
+}
+/** One parsed source document, tagged with where 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.
+ */
+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.
+ */
+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>`.
+ */
+declare function graphqlDocumentsPathToSummaries(specPath: string, options?: GraphqlDocumentsOptions): BehavioralSummary[];
+
 interface GraphqlContractOptions {
     /**
      * Logical source path recorded on each summary's `location.file`.
@@ -42,4 +88,4 @@ declare function graphqlSdlFileToSummaries(filepath: string, options?: GraphqlCo
  */
 declare function loadSdlFile(filepath: string): string | null;
 
-export { type GraphqlContractOptions, graphqlSdlFileToSummaries, graphqlSdlToSummaries, loadSdlFile };
+export { type GraphqlContractOptions, type GraphqlDocumentsOptions, graphqlDocumentFilesToSummaries, graphqlDocumentsPathToSummaries, graphqlDocumentsToSummaries, graphqlSdlFileToSummaries, graphqlSdlToSummaries, loadSdlFile };

package/dist/index.js

@@ -1,15 +1,417 @@
 // src/index.ts
-import fs from "fs";
+import fs2 from "fs";
 import {
-  Kind,
-  parse
+  Kind as Kind3,
+  parse as parse2
 } from "graphql";
 import { graphqlResolverBinding } from "@suss/behavioral-ir";
+
+// src/typeShape.ts
+import { Kind } from "graphql";
+var SCALAR_SHAPES = {
+  String: { type: "text" },
+  ID: { type: "text" },
+  Int: { type: "number" },
+  Float: { type: "number" },
+  Boolean: { type: "boolean" }
+};
+function typeNodeToShape(node) {
+  if (node.kind === Kind.NON_NULL_TYPE) {
+    return typeNodeToShape(node.type);
+  }
+  if (node.kind === Kind.LIST_TYPE) {
+    return { type: "array", items: typeNodeToShape(node.type) };
+  }
+  return scalarOrRef(node);
+}
+function scalarOrRef(node) {
+  const name = node.name.value;
+  return SCALAR_SHAPES[name] ?? { type: "ref", name };
+}
+
+// src/documents.ts
+import fs from "fs";
+import path from "path";
+import {
+  Kind as Kind2,
+  parse,
+  print
+} from "graphql";
+import { graphqlOperationBinding } from "@suss/behavioral-ir";
+function graphqlDocumentsToSummaries(sources, options = {}) {
+  const recognition = options.recognition ?? "graphql-documents";
+  const transport = options.transport ?? "http-graphql";
+  const parsed = [];
+  for (const source of sources) {
+    const doc = safeParse(source.text);
+    if (doc === null) {
+      continue;
+    }
+    parsed.push({ source, doc });
+  }
+  const fragments = collectFragments(parsed);
+  const takenNames = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const { source, doc } of parsed) {
+    for (const def of doc.definitions) {
+      if (def.kind !== Kind2.OPERATION_DEFINITION) {
+        continue;
+      }
+      const name = distinctName(
+        operationName(def, source.path, options.rootDir),
+        takenNames
+      );
+      out.push(
+        buildOperationSummary(def, name, source.path, fragments, {
+          recognition,
+          transport
+        })
+      );
+    }
+  }
+  return out;
+}
+function operationName(op, file, rootDir) {
+  const declared = op.name?.value;
+  if (declared !== void 0) {
+    return declared;
+  }
+  return `${displayPath(file, rootDir)}:${op.operation}`;
+}
+function displayPath(file, rootDir) {
+  if (rootDir === void 0) {
+    return file;
+  }
+  const relative = path.relative(rootDir, file);
+  if (relative === "" || relative.startsWith("..")) {
+    return file;
+  }
+  return relative.split(path.sep).join("/");
+}
+function distinctName(candidate, taken) {
+  let name = candidate;
+  let suffix = 2;
+  while (taken.has(name)) {
+    name = `${candidate}#${suffix}`;
+    suffix += 1;
+  }
+  taken.add(name);
+  return name;
+}
+function graphqlDocumentFilesToSummaries(filepaths, options = {}) {
+  const sources = [];
+  for (const filepath of filepaths) {
+    let text;
+    try {
+      text = fs.readFileSync(filepath, "utf8");
+    } catch {
+      continue;
+    }
+    sources.push({ path: filepath, text });
+  }
+  return graphqlDocumentsToSummaries(sources, options);
+}
+function graphqlDocumentsPathToSummaries(specPath, options = {}) {
+  const absolute = path.resolve(specPath);
+  if (!fs.existsSync(absolute)) {
+    throw new Error(
+      `No GraphQL documents found at "${specPath}". Pass a .graphql/.gql file or a directory containing them.`
+    );
+  }
+  const stat = fs.statSync(absolute);
+  const isDirectory = stat.isDirectory();
+  const files = isDirectory ? walkForDocuments(absolute) : [absolute];
+  return graphqlDocumentFilesToSummaries(files, {
+    rootDir: isDirectory ? absolute : path.dirname(absolute),
+    ...options
+  });
+}
+function walkForDocuments(dir) {
+  const out = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isFile()) {
+      if (/\.(graphql|gql)$/.test(entry.name)) {
+        out.push(full);
+      }
+    } else if (entry.isDirectory() && entry.name !== "node_modules") {
+      out.push(...walkForDocuments(full));
+    }
+  }
+  return out.sort();
+}
+function collectFragments(parsed) {
+  const definitions = /* @__PURE__ */ new Map();
+  const definingFiles = /* @__PURE__ */ new Map();
+  for (const { source, doc } of parsed) {
+    for (const def of doc.definitions) {
+      if (def.kind !== Kind2.FRAGMENT_DEFINITION) {
+        continue;
+      }
+      const name = def.name.value;
+      if (!definitions.has(name)) {
+        definitions.set(name, def);
+      }
+      definingFiles.set(name, [
+        ...definingFiles.get(name) ?? [],
+        source.path
+      ]);
+    }
+  }
+  const competingFiles = /* @__PURE__ */ new Map();
+  for (const [name, files] of definingFiles) {
+    if (files.length > 1) {
+      competingFiles.set(name, files);
+    }
+  }
+  return { definitions, competingFiles };
+}
+function buildOperationSummary(op, name, file, fragments, config) {
+  const operationType = op.operation;
+  const operationName2 = op.name?.value;
+  const unexpanded = emptyUnexpandedSpreads();
+  const inlined = inlineSpreadsInOperation(op, fragments, unexpanded);
+  const documentText = print(documentOf(inlined));
+  const responseShape = selectionSetToShape(inlined.selectionSet);
+  return {
+    kind: "client",
+    location: {
+      file,
+      range: { start: op.loc?.start ?? 0, end: op.loc?.end ?? 0 },
+      exportName: null
+    },
+    identity: {
+      name,
+      exportPath: null,
+      boundaryBinding: graphqlOperationBinding({
+        transport: config.transport,
+        recognition: config.recognition,
+        operationType,
+        ...operationName2 !== void 0 ? { operationName: operationName2 } : {}
+      })
+    },
+    inputs: buildVariableInputs(op),
+    transitions: buildTransitions(name, responseShape),
+    gaps: unexpandedSpreadGaps(unexpanded, fragments),
+    confidence: { source: "declared", level: "high" },
+    metadata: {
+      graphql: {
+        document: documentText,
+        ...unexpanded.missing.size > 0 ? { unresolvedFragments: [...unexpanded.missing].sort() } : {}
+      }
+    }
+  };
+}
+function buildVariableInputs(op) {
+  const variables = op.variableDefinitions ?? [];
+  return variables.map((variable, index) => ({
+    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.
+    role: "variable",
+    shape: typeNodeToShape(variable.type)
+  }));
+}
+function buildTransitions(name, responseShape) {
+  return [
+    {
+      id: `${name}:return:success`,
+      conditions: [],
+      output: { type: "return", value: responseShape },
+      effects: [],
+      location: { start: 0, end: 0 },
+      isDefault: true,
+      confidence: { source: "declared", level: "high" },
+      metadata: {
+        source: "graphql:operation.success"
+      }
+    },
+    {
+      id: `${name}:throw:error`,
+      conditions: [
+        {
+          type: "opaque",
+          sourceText: "graphql:operation-error",
+          reason: "externalFunction"
+        }
+      ],
+      output: {
+        type: "throw",
+        exceptionType: "GraphQLError",
+        message: null
+      },
+      effects: [],
+      location: { start: 0, end: 0 },
+      isDefault: false,
+      confidence: { source: "declared", level: "low" },
+      metadata: {
+        source: "graphql:operation.error"
+      }
+    }
+  ];
+}
+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.
+      readingGap(
+        `Fragment spread "...${name}" has no matching fragment definition in the read set; its selections are not part of this summary.`
+      )
+    );
+  }
+  for (const name of [...unexpanded.cyclic].sort()) {
+    gaps.push(
+      readingGap(
+        `Fragment spread "...${name}" is part of a fragment cycle, which no server would execute; the repeated spread was left unexpanded.`
+      )
+    );
+  }
+  for (const name of [...unexpanded.ambiguous].sort()) {
+    const files = fragments.competingFiles.get(name) ?? [];
+    gaps.push(
+      readingGap(
+        `Fragment "${name}" is defined in more than one file (${files.join(", ")}); the first definition was used, so the selections here may not be the ones the build resolves.`
+      )
+    );
+  }
+  return gaps;
+}
+function readingGap(description) {
+  return {
+    type: "unreadOutcome",
+    conditions: [],
+    consequence: "unknown",
+    description
+  };
+}
+function emptyUnexpandedSpreads() {
+  return { missing: /* @__PURE__ */ new Set(), cyclic: /* @__PURE__ */ new Set(), ambiguous: /* @__PURE__ */ new Set() };
+}
+function inlineSpreadsInOperation(op, fragments, unexpanded) {
+  return {
+    ...op,
+    selectionSet: inlineSelectionSet(
+      op.selectionSet,
+      fragments,
+      [],
+      unexpanded
+    )
+  };
+}
+function inlineSelectionSet(selectionSet, fragments, stack, unexpanded) {
+  const out = [];
+  for (const selection of selectionSet.selections) {
+    out.push(...inlineOneSelection(selection, fragments, stack, unexpanded));
+  }
+  return { ...selectionSet, selections: out };
+}
+function inlineOneSelection(selection, fragments, stack, unexpanded) {
+  if (selection.kind === Kind2.FIELD) {
+    if (selection.selectionSet === void 0) {
+      return [selection];
+    }
+    const field = {
+      ...selection,
+      selectionSet: inlineSelectionSet(
+        selection.selectionSet,
+        fragments,
+        stack,
+        unexpanded
+      )
+    };
+    return [field];
+  }
+  if (selection.kind === Kind2.FRAGMENT_SPREAD) {
+    const fragmentName = selection.name.value;
+    if (fragments.competingFiles.has(fragmentName)) {
+      unexpanded.ambiguous.add(fragmentName);
+    }
+    if (stack.includes(fragmentName)) {
+      unexpanded.cyclic.add(fragmentName);
+      return [selection];
+    }
+    const fragment = fragments.definitions.get(fragmentName);
+    if (fragment === void 0) {
+      unexpanded.missing.add(fragmentName);
+      return [selection];
+    }
+    const inlined = inlineSelectionSet(
+      fragment.selectionSet,
+      fragments,
+      [...stack, fragmentName],
+      unexpanded
+    );
+    return [...inlined.selections];
+  }
+  const inlineFragment = {
+    ...selection,
+    selectionSet: inlineSelectionSet(
+      selection.selectionSet,
+      fragments,
+      stack,
+      unexpanded
+    )
+  };
+  return [inlineFragment];
+}
+function documentOf(op) {
+  const definitions = [op];
+  return { kind: Kind2.DOCUMENT, definitions };
+}
+function selectionSetToShape(selectionSet) {
+  const properties = {};
+  mergeSelectionsInto(properties, selectionSet.selections);
+  return { type: "record", properties };
+}
+function mergeSelectionsInto(properties, selections) {
+  for (const selection of selections) {
+    if (selection.kind === Kind2.FIELD) {
+      const key = selection.alias?.value ?? selection.name.value;
+      const selected = selection.selectionSet !== void 0 ? selectionSetToShape(selection.selectionSet) : { type: "unknown" };
+      properties[key] = mergeShapes(properties[key], selected);
+      continue;
+    }
+    if (selection.kind === Kind2.INLINE_FRAGMENT) {
+      mergeSelectionsInto(properties, selection.selectionSet.selections);
+    }
+  }
+}
+function mergeShapes(existing, incoming) {
+  if (existing === void 0) {
+    return incoming;
+  }
+  if (existing.type === "record" && incoming.type === "record") {
+    const properties = { ...existing.properties };
+    for (const [key, shape] of Object.entries(incoming.properties)) {
+      properties[key] = mergeShapes(properties[key], shape);
+    }
+    return { type: "record", properties };
+  }
+  if (existing.type === "record") {
+    return existing;
+  }
+  return incoming;
+}
+function safeParse(text) {
+  try {
+    return parse(text);
+  } catch {
+    return null;
+  }
+}
+
+// src/index.ts
 var ROOT_TYPES = ["Query", "Mutation", "Subscription"];
 function graphqlSdlToSummaries(sdl, options = {}) {
   let doc;
   try {
-    doc = parse(sdl);
+    doc = parse2(sdl);
   } catch (_err) {
     return [];
   }
@@ -26,7 +428,7 @@ function graphqlSdlToSummaries(sdl, options = {}) {
   return out;
 }
 function graphqlSdlFileToSummaries(filepath, options = {}) {
-  const sdl = fs.readFileSync(filepath, "utf8");
+  const sdl = fs2.readFileSync(filepath, "utf8");
   return graphqlSdlToSummaries(sdl, {
     source: filepath,
     ...options
@@ -34,7 +436,7 @@ function graphqlSdlFileToSummaries(filepath, options = {}) {
 }
 function loadSdlFile(filepath) {
   try {
-    return fs.readFileSync(filepath, "utf8");
+    return fs2.readFileSync(filepath, "utf8");
   } catch {
     return null;
   }
@@ -42,7 +444,7 @@ function loadSdlFile(filepath) {
 function collectRootFields(doc) {
   const fieldsByRoot = /* @__PURE__ */ new Map();
   for (const def of doc.definitions) {
-    const node = def.kind === Kind.OBJECT_TYPE_DEFINITION || def.kind === Kind.OBJECT_TYPE_EXTENSION ? def : null;
+    const node = def.kind === Kind3.OBJECT_TYPE_DEFINITION || def.kind === Kind3.OBJECT_TYPE_EXTENSION ? def : null;
     if (node === null) {
       continue;
     }
@@ -92,7 +494,7 @@ function buildResolverSummary(rootType, field, source, recognition, transport) {
       })
     },
     inputs: buildInputs(field),
-    transitions: buildTransitions(ownerKey, field),
+    transitions: buildTransitions2(ownerKey, field),
     gaps: [],
     confidence: { source: "derived", level: "high" },
     metadata: {
@@ -115,7 +517,7 @@ function buildDeclaredContract(field, recognition) {
     args: (field.arguments ?? []).map((arg) => ({
       name: arg.name.value,
       type: typeNodeToShape(arg.type),
-      required: arg.type.kind === Kind.NON_NULL_TYPE
+      required: arg.type.kind === Kind3.NON_NULL_TYPE
     })),
     provenance: "derived",
     framework: recognition
@@ -131,7 +533,7 @@ function buildInputs(field) {
     shape: typeNodeToShape(arg.type)
   }));
 }
-function buildTransitions(ownerKey, field) {
+function buildTransitions2(ownerKey, field) {
   const returnShape = typeNodeToShape(field.type);
   return [
     {
@@ -170,31 +572,10 @@ function buildTransitions(ownerKey, field) {
     }
   ];
 }
-function typeNodeToShape(node) {
-  if (node.kind === Kind.NON_NULL_TYPE) {
-    return typeNodeToShape(node.type);
-  }
-  if (node.kind === Kind.LIST_TYPE) {
-    return { type: "array", items: typeNodeToShape(node.type) };
-  }
-  return scalarOrRef(node);
-}
-function scalarOrRef(node) {
-  const name = node.name.value;
-  switch (name) {
-    case "String":
-    case "ID":
-      return { type: "text" };
-    case "Int":
-    case "Float":
-      return { type: "number" };
-    case "Boolean":
-      return { type: "boolean" };
-    default:
-      return { type: "ref", name };
-  }
-}
 export {
+  graphqlDocumentFilesToSummaries,
+  graphqlDocumentsPathToSummaries,
+  graphqlDocumentsToSummaries,
   graphqlSdlFileToSummaries,
   graphqlSdlToSummaries,
   loadSdlFile

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@suss/contract-graphql",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "type": "module",
-  "description": "Generate behavioral summaries from a plain GraphQL SDL file (Query/Mutation/Subscription field definitions become resolver-kind summaries).",
+  "description": "Generate behavioral summaries from GraphQL sources: a plain SDL file (root fields become resolver-kind summaries) or committed .graphql operation documents (each operation becomes a client-kind summary).",
   "keywords": [
     "suss",
     "behavioral-summary",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.0.2",
+    "@suss/behavioral-ir": "0.1.1",
     "graphql": "^16.8.0"
   },
   "devDependencies": {