feat: add support for requires in protographic

connect/src/wg/cosmo/node/v1/node_pb.ts

@@ -2095,6 +2095,13 @@ export class EntityMapping extends Message<EntityMapping> {
    */
   response = "";
 
+  /**
+   * Mappings for required fields
+   *
+   * @generated from field: repeated wg.cosmo.node.v1.RequiredFieldMapping required_field_mappings = 7;
+   */
+  requiredFieldMappings: RequiredFieldMapping[] = [];
+
   constructor(data?: PartialMessage<EntityMapping>) {
     super();
     proto3.util.initPartial(data, this);
@@ -2109,6 +2116,7 @@ export class EntityMapping extends Message<EntityMapping> {
     { no: 4, name: "rpc", kind: "scalar", T: 9 /* ScalarType.STRING */ },
     { no: 5, name: "request", kind: "scalar", T: 9 /* ScalarType.STRING */ },
     { no: 6, name: "response", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 7, name: "required_field_mappings", kind: "message", T: RequiredFieldMapping, repeated: true },
   ]);
 
   static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): EntityMapping {
@@ -2128,6 +2136,69 @@ export class EntityMapping extends Message<EntityMapping> {
   }
 }
 
+/**
+ * Defines mapping for required fields
+ *
+ * @generated from message wg.cosmo.node.v1.RequiredFieldMapping
+ */
+export class RequiredFieldMapping extends Message<RequiredFieldMapping> {
+  /**
+   * @generated from field: wg.cosmo.node.v1.FieldMapping field_mapping = 1;
+   */
+  fieldMapping?: FieldMapping;
+
+  /**
+   * Mapped gRPC method name
+   *
+   * @generated from field: string rpc = 2;
+   */
+  rpc = "";
+
+  /**
+   * gRPC request message type name
+   *
+   * @generated from field: string request = 3;
+   */
+  request = "";
+
+  /**
+   * gRPC response message type name
+   *
+   * @generated from field: string response = 4;
+   */
+  response = "";
+
+  constructor(data?: PartialMessage<RequiredFieldMapping>) {
+    super();
+    proto3.util.initPartial(data, this);
+  }
+
+  static readonly runtime: typeof proto3 = proto3;
+  static readonly typeName = "wg.cosmo.node.v1.RequiredFieldMapping";
+  static readonly fields: FieldList = proto3.util.newFieldList(() => [
+    { no: 1, name: "field_mapping", kind: "message", T: FieldMapping },
+    { no: 2, name: "rpc", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 3, name: "request", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 4, name: "response", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+  ]);
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): RequiredFieldMapping {
+    return new RequiredFieldMapping().fromBinary(bytes, options);
+  }
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): RequiredFieldMapping {
+    return new RequiredFieldMapping().fromJson(jsonValue, options);
+  }
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): RequiredFieldMapping {
+    return new RequiredFieldMapping().fromJsonString(jsonString, options);
+  }
+
+  static equals(a: RequiredFieldMapping | PlainMessage<RequiredFieldMapping> | undefined, b: RequiredFieldMapping | PlainMessage<RequiredFieldMapping> | undefined): boolean {
+    return proto3.util.equals(RequiredFieldMapping, a, b);
+  }
+}
+
 /**
  * Defines mapping between GraphQL type fields and gRPC message fields
  *

proto/wg/cosmo/node/v1/node.proto

@@ -316,6 +316,19 @@ message EntityMapping {
   string request = 5;
   // gRPC response message type name
   string response = 6;
+  // Mappings for required fields
+  repeated RequiredFieldMapping required_field_mappings = 7;
+}
+
+// Defines mapping for required fields
+message RequiredFieldMapping {
+  FieldMapping field_mapping = 1;
+  // Mapped gRPC method name
+  string rpc = 2;
+  // gRPC request message type name
+  string request = 3;
+  // gRPC response message type name
+  string response = 4;
 }
 
 // Defines mapping between GraphQL type fields and gRPC message fields

protographic/src/abstract-selection-rewriter.ts

@@ -0,0 +1,193 @@
+/**
+ * @file abstract-selection-rewriter.ts
+ *
+ * This module provides functionality to normalize GraphQL field set selections
+ * when dealing with abstract types (interfaces). It ensures that fields selected
+ * at the interface level are properly distributed into each inline fragment,
+ * maintaining correct selection semantics for proto mapping generation.
+ */
+
+import {
+  ASTVisitor,
+  DocumentNode,
+  GraphQLSchema,
+  GraphQLObjectType,
+  visit,
+  SelectionSetNode,
+  isInterfaceType,
+  Kind,
+  FieldNode,
+  ASTNode,
+  GraphQLField,
+  GraphQLType,
+  getNamedType,
+} from 'graphql';
+import { VisitContext } from './types';
+
+/**
+ * Rewrites GraphQL selection sets to normalize abstract type selections.
+ *
+ * When a field returns an interface type, selections can be made both at the
+ * interface level and within inline fragments for concrete types. This class
+ * normalizes such selections by moving interface-level fields into each inline
+ * fragment, ensuring consistent selection structure for downstream processing.
+ *
+ * @example
+ * Input selection:
+ * ```graphql
+ * media {
+ *   id          # interface-level field
+ *   ... on Book { title }
+ *   ... on Movie { duration }
+ * }
+ * ```
+ *
+ * Output after normalization:
+ * ```graphql
+ * media {
+ *   ... on Book { id title }
+ *   ... on Movie { id duration }
+ * }
+ * ```
+ */
+export class AbstractSelectionRewriter {
+  private readonly visitor: ASTVisitor;
+  private readonly fieldSetDoc: DocumentNode;
+  public readonly schema: GraphQLSchema;
+  private currentType: GraphQLObjectType;
+
+  /**
+   * Creates a new AbstractSelectionRewriter instance.
+   *
+   * @param fieldSetDoc - The parsed GraphQL document containing the field set to rewrite
+   * @param schema - The GraphQL schema used for type resolution
+   * @param objectType - The root object type where the field set originates
+   */
+  constructor(fieldSetDoc: DocumentNode, schema: GraphQLSchema, objectType: GraphQLObjectType) {
+    this.fieldSetDoc = fieldSetDoc;
+    this.schema = schema;
+    this.currentType = objectType;
+    this.visitor = this.createASTVisitor();
+  }
+
+  /**
+   * Creates the AST visitor that processes selection sets during traversal.
+   *
+   * @returns An ASTVisitor configured to handle SelectionSet nodes
+   */
+  private createASTVisitor(): ASTVisitor {
+    return {
+      SelectionSet: {
+        enter: (node, key, parent, path, ancestors) => {
+          this.onEnterSelectionSet({ node, key, parent, path, ancestors });
+        },
+      },
+    };
+  }
+
+  /**
+   * Executes the normalization process on the field set document.
+   *
+   * This method traverses the AST and rewrites any selection sets that target
+   * interface types, distributing interface-level fields into inline fragments.
+   * The modification is performed in-place on the provided document.
+   */
+  public normalize(): void {
+    visit(this.fieldSetDoc, this.visitor);
+  }
+
+  /**
+   * Handles the entry into a SelectionSet node during AST traversal.
+   *
+   * If the selection set's parent field returns an interface type, this method:
+   * 1. Extracts all direct field selections (interface-level fields)
+   * 2. Removes them from the selection set, leaving only inline fragments
+   * 3. Prepends the interface-level fields to each inline fragment's selections
+   *    (unless the fragment already contains that field)
+   *
+   * @param ctx - The visitor context containing the current node and its position in the AST
+   */
+  private onEnterSelectionSet(ctx: VisitContext<SelectionSetNode>): void {
+    if (!ctx.parent) return;
+    if (!this.isFieldNode(ctx.parent)) return;
+
+    const currentType = this.findNamedTypeForField(ctx.parent.name.value);
+    if (!currentType) return;
+
+    // Only process selection sets for interface types
+    if (!isInterfaceType(currentType)) {
+      return;
+    }
+
+    const fields = ctx.node.selections.filter((s) => s.kind === Kind.FIELD);
+    const inlineFragments = ctx.node.selections.filter((s) => s.kind === Kind.INLINE_FRAGMENT);
+
+    // Remove the interface-level fields from the selection set, keeping only inline fragments
+    ctx.node.selections = [...inlineFragments];
+
+    // Distribute interface-level fields into each inline fragment
+    for (const fragment of inlineFragments) {
+      const normalizedFields = fragment.selectionSet.selections.filter((s) => s.kind === Kind.FIELD) ?? [];
+
+      for (const field of fields) {
+        // Skip if the fragment already has this field to avoid duplicates
+        if (this.hasField(normalizedFields, field.name.value)) {
+          continue;
+        }
+
+        normalizedFields.unshift(field);
+      }
+
+      fragment.selectionSet.selections = [...normalizedFields];
+    }
+  }
+
+  /**
+   * Checks if a field with the given name exists in the provided field array.
+   *
+   * @param fields - Array of FieldNode objects to search
+   * @param fieldName - The name of the field to look for
+   * @returns true if a field with the given name exists, false otherwise
+   */
+  private hasField(fields: FieldNode[], fieldName: string): boolean {
+    return fields.some((f) => f.name.value === fieldName);
+  }
+
+  /**
+   * Type guard to check if an AST node is a FieldNode.
+   *
+   * @param node - The AST node or array of nodes to check
+   * @returns true if the node is a FieldNode, false otherwise
+   */
+  private isFieldNode(node: ASTNode | ReadonlyArray<ASTNode>): node is FieldNode {
+    if (Array.isArray(node)) return false;
+    return (node as ASTNode).kind === Kind.FIELD;
+  }
+
+  /**
+   * Retrieves the field definition for a given field name from the current type.
+   *
+   * @param fieldName - The name of the field to look up
+   * @returns The GraphQL field definition, or undefined if not found
+   */
+  private fieldDefinition(fieldName: string): GraphQLField<any, any, any> | undefined {
+    return this.currentType.getFields()[fieldName];
+  }
+
+  /**
+   * Finds the named (unwrapped) type for a field by its name.
+   *
+   * This method looks up the field in the current type's fields and returns
+   * the named type (stripping away any List or NonNull wrappers).
+   *
+   * @param fieldName - The name of the field to look up
+   * @returns The named GraphQL type, or undefined if the field doesn't exist
+   */
+  private findNamedTypeForField(fieldName: string): GraphQLType | undefined {
+    const fields = this.currentType.getFields();
+    const field = fields[fieldName];
+    if (!field) return undefined;
+
+    return getNamedType(field.type);
+  }
+}

protographic/src/index.ts

@@ -92,6 +92,7 @@ export function validateGraphQLSDL(sdl: string): ValidationResult {
 
 export * from './sdl-to-mapping-visitor.js';
 export { GraphQLToProtoTextVisitor } from './sdl-to-proto-visitor.js';
+export { RequiredFieldsVisitor } from './required-fields-visitor.js';
 export { ProtoLockManager } from './proto-lock.js';
 export { SDLValidationVisitor } from './sdl-validation-visitor.js';
 
@@ -149,5 +150,16 @@ export {
   OperationType,
 } from '@wundergraph/cosmo-connect/dist/node/v1/node_pb';
 
+export {
+  CONNECT_FIELD_RESOLVER,
+  CONTEXT,
+  EXTERNAL_DIRECTIVE_NAME,
+  FIELDS,
+  FIELD_ARGS,
+  KEY_DIRECTIVE_NAME,
+  REQUIRES_DIRECTIVE_NAME,
+  RESULT,
+} from './string-constants.js';
+
 // Export protobufjs for AST manipulation
 export { default as protobuf } from 'protobufjs';

protographic/src/naming-conventions.ts

@@ -63,14 +63,51 @@ export function createResponseMessageName(methodName: string): string {
  * Creates an entity lookup method name for an entity type
  */
 export function createEntityLookupMethodName(typeName: string, keyString: string = 'id'): string {
+  const normalizedKey = createMethodSuffixFromEntityKey(keyString);
+  return `Lookup${typeName}${normalizedKey}`;
+}
+
+/**
+ * Creates a key message name for an entity lookup request
+ * @param typeName - The name of the entity type
+ * @param keyString - The key string
+ * @returns The name of the key message
+ */
+export function createEntityLookupRequestKeyMessageName(typeName: string, keyString: string = 'id'): string {
+  const requestName = createRequestMessageName(createEntityLookupMethodName(typeName, keyString));
+  return `${requestName}Key`;
+}
+
+/**
+ * Creates a required fields method name for an entity type
+ * @param typeName - The name of the entity type
+ * @param fieldName - The name of the field that is required
+ * @param keyString - The key string
+ * @returns The name of the required fields method
+ * @example
+ * createRequiredFieldsMethodName('User', 'post', 'id') // => 'RequireUserPostById'
+ * createRequiredFieldsMethodName('User', 'post', 'id name') // => 'RequireUserPostByIdAndName'
+ * createRequiredFieldsMethodName('User', 'post', 'name,id') // => 'RequireUserPostByNameAndId'
+ */
+export function createRequiredFieldsMethodName(typeName: string, fieldName: string, keyString: string = 'id'): string {
+  const normalizedKey = createMethodSuffixFromEntityKey(keyString);
+  return `Require${typeName}${upperFirst(camelCase(fieldName))}${normalizedKey}`;
+}
+
+/**
+ * Creates a method suffix from an entity key string
+ * @param keyString - The key string
+ * @returns The method suffix
+ */
+export function createMethodSuffixFromEntityKey(keyString: string = 'id'): string {
   const normalizedKey = keyString
     .split(/[,\s]+/)
     .filter((field) => field.length > 0)
     .map((field) => upperFirst(camelCase(field)))
     .sort()
     .join('And');
 
-  return `Lookup${typeName}By${normalizedKey}`;
+  return `By${normalizedKey}`;
 }
 
 /**