Add support for concrete-typed named fragments

In previous commits I added support to genqlient for interfaces and
inline fragments.  This means the only query structures that remain are
named fragments and their spreads, e.g.
```
fragment MyFragment on MyType { myField }
query MyQuery { getMyType { ...MyFragment } }
```
Other than mere completionism, these are potentially useful for code
sharing: you can spread the same fragment multiple places; and then
genqlient can notice that and generate the same type for each.  (They
can even be shared between different queries in the same package.)

In this commit I add support for named fragments of concrete
(object/struct, not interface) type, spread into either concrete or
abstract scope.  For genqlient's purposes, these are a new "root"
type-name, just like each operation, and are then embedded into the
appropriate struct.  (Using embeds allows their fields to be referenced
as fields of the containing type, if convenient.  Further design
considerations are discussed in DESIGN.md.)

This requires new code in two main places (plus miscellaneous glue),
both nontrivial but neither particularly complex:
- We need to actually traverse both structures and generate the types
  (in `convert.go`).
- We need to decide which fragments from this package to send to the
  server, both for good hyigene and because GraphQL requires we send
  only ones this query uses (in `generate.go`).
- We need a little new wiring for options -- because fragments can be
  shared between queries they get their own toplevel options, rather
  than inheriting the query's options.

Finally, this required slightly subtler changes to how we do
unmarshaling (in `types.go` and `unmarshal.go.tmpl`).  Basically,
because embedded fields' methods, including `UnmarshalJSON`, get
promoted to the parent type, and because the JSON library ignores their
fields when shadowed by those of the parent type, we need a little bit
of special logic in each such parent type to do its own unmarshal and
then delegate to each embed.  This is similar (and much simpler) to
what we did for interfaces, although it required some changes to the
"method-hiding" trick (used for both).  It's only really necessary in
certain specific cases (namely when an embedded type has an
`UnmarshalJSON` method or a field with the same name as the embedder),
but it's easier to just generate it always.  This is all described in
more detail inline.

This does not support fragments of abstract type, which have their own
complexities.  I'll address those, which are now the only remaining
piece of #8, in a future commit.

Issue: #8

Test plan:
make check

Reviewers: marksandstrom, miguel, adam

generate/convert.go

@@ -330,7 +330,12 @@ func (g *generator) convertSelectionSet(
 			}
 			fields = append(fields, field)
 		case *ast.FragmentSpread:
-			return nil, errorf(selection.Position, "not implemented: %T", selection)
+			maybeField, err := g.convertFragmentSpread(selection, containingTypedef)
+			if err != nil {
+				return nil, err
+			} else if maybeField != nil {
+				fields = append(fields, maybeField)
+			}
 		case *ast.InlineFragment:
 			// (Note this will return nil, nil if the fragment doesn't apply to
 			// this type.)
@@ -354,7 +359,9 @@ func (g *generator) convertSelectionSet(
 		// GraphQL (and, effectively, JSON) requires that all fields with the
 		// same alias (JSON-name) must be the same (i.e. refer to the same
 		// field), so that's how we deduplicate.
-		if fieldNames[field.JSONName] {
+		// It's fine to have duplicate embeds (i.e. via named fragments), even
+		// ones with complicated overlaps, since they are separate types to us.
+		if field.JSONName != "" && fieldNames[field.JSONName] {
 			// GraphQL (and, effectively, JSON) forbids you from having two
 			// fields with the same alias (JSON-name) that refer to different
 			// GraphQL fields.  But it does allow you to have the same field
@@ -444,6 +451,73 @@ func (g *generator) convertInlineFragment(
 		containingTypedef, queryOptions)
 }
 
+// convertFragmentSpread converts a single GraphQL fragment-spread
+// (`...MyFragment`) into a Go struct-field.  It assumes that
+// convertNamedFragment has already been called on the fragment-definition.  If
+// the fragment does not apply to this type, returns nil.
+//
+// containingTypedef is as described in convertInlineFragment, above.
+func (g *generator) convertFragmentSpread(
+	fragmentSpread *ast.FragmentSpread,
+	containingTypedef *ast.Definition,
+) (*goStructField, error) {
+	if !fragmentMatches(containingTypedef, fragmentSpread.Definition.Definition) {
+		return nil, nil
+	}
+
+	typ, ok := g.typeMap[fragmentSpread.Name]
+	if !ok {
+		// If we haven't yet, convert the fragment itself.  Note that fragments
+		// aren't allowed to have cycles, so this won't recurse forever.
+		var err error
+		typ, err = g.convertNamedFragment(fragmentSpread.Definition)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	return &goStructField{GoName: "" /* i.e. embedded */, GoType: typ}, nil
+}
+
+// convertNamedFragment converts a single GraphQL named fragment-definition
+// (`fragment MyFragment on MyType { ... }`) into a Go struct.
+func (g *generator) convertNamedFragment(fragment *ast.FragmentDefinition) (goType, error) {
+	typ := g.schema.Types[fragment.TypeCondition]
+	if !g.Config.AllowBrokenFeatures &&
+		(typ.Kind == ast.Interface || typ.Kind == ast.Union) {
+		return nil, errorf(fragment.Position, "not implemented: abstract-typed fragments")
+	}
+
+	description, directive, err := g.parsePrecedingComment(fragment, fragment.Position)
+	if err != nil {
+		return nil, err
+	}
+
+	// If the user included a comment, use that.  Else make up something
+	// generic; there's not much to say though.
+	if description == "" {
+		description = fmt.Sprintf(
+			"%v includes the GraphQL fields of %v requested by the fragment %v.",
+			fragment.Name, fragment.TypeCondition, fragment.Name)
+	}
+
+	fields, err := g.convertSelectionSet(
+		newPrefixList(fragment.Name), fragment.SelectionSet, typ, directive)
+	if err != nil {
+		return nil, err
+	}
+
+	goType := &goStructType{
+		GoName:      fragment.Name,
+		Description: description,
+		GraphQLName: fragment.TypeCondition,
+		Fields:      fields,
+		Incomplete:  false,
+	}
+	g.typeMap[fragment.Name] = goType
+	return goType, nil
+}
+
 // convertField converts a single GraphQL operation-field into a Go
 // struct-field (and its type).
 //

generate/generate.go

@@ -34,6 +34,11 @@ type generator struct {
 	templateCache map[string]*template.Template
 	// Schema we are generating code against
 	schema *ast.Schema
+	// Named fragments (map by name), so we can look them up from spreads.
+	// TODO(benkraft): In theory we shouldn't need this, we can just use
+	// ast.FragmentSpread.Definition, but for some reason it doesn't seem to be
+	// set consistently, even post-validation.
+	fragments map[string]*ast.FragmentDefinition
 }
 
 // JSON tags in operation are for ExportOperations (see Config for details).
@@ -66,14 +71,23 @@ type argument struct {
 	Options     *GenqlientDirective
 }
 
-func newGenerator(config *Config, schema *ast.Schema) *generator {
+func newGenerator(
+	config *Config,
+	schema *ast.Schema,
+	fragments ast.FragmentDefinitionList,
+) *generator {
 	g := generator{
 		Config:        config,
 		typeMap:       map[string]goType{},
 		imports:       map[string]string{},
 		usedAliases:   map[string]bool{},
 		templateCache: map[string]*template.Template{},
 		schema:        schema,
+		fragments:     make(map[string]*ast.FragmentDefinition, len(fragments)),
+	}
+
+	for _, fragment := range fragments {
+		g.fragments[fragment.Name] = fragment
 	}
 
 	if g.Config.ClientGetter == "" {
@@ -139,6 +153,38 @@ func (g *generator) getArgument(
 	}, nil
 }
 
+// usedFragmentNames returns the named-fragments used by (i.e. spread into)
+// this operation.
+func (g *generator) usedFragments(op *ast.OperationDefinition) ast.FragmentDefinitionList {
+	var retval, queue ast.FragmentDefinitionList
+	seen := map[string]bool{}
+
+	var observers validator.Events
+	// Fragment-spreads are easy to find; just ask for them!
+	observers.OnFragmentSpread(func(_ *validator.Walker, fragmentSpread *ast.FragmentSpread) {
+		if seen[fragmentSpread.Name] {
+			return
+		}
+		def := g.fragments[fragmentSpread.Name]
+		seen[fragmentSpread.Name] = true
+		retval = append(retval, def)
+		queue = append(queue, def)
+	})
+
+	doc := ast.QueryDocument{Operations: ast.OperationList{op}}
+	validator.Walk(g.schema, &doc, &observers)
+	// Well, easy-ish: we also have to look recursively.
+	// Note GraphQL guarantees there are no cycles among fragments:
+	// https://spec.graphql.org/draft/#sec-Fragment-spreads-must-not-form-cycles
+	for len(queue) > 0 {
+		doc = ast.QueryDocument{Fragments: ast.FragmentDefinitionList{queue[0]}}
+		validator.Walk(g.schema, &doc, &observers) // traversal is the same
+		queue = queue[1:]
+	}
+
+	return retval
+}
+
 // Preprocess each query to make any changes that genqlient needs.
 //
 // At present, the only change is that we add __typename, if not already
@@ -151,9 +197,11 @@ func (g *generator) preprocessQueryDocument(doc *ast.QueryDocument) {
 	// __typename field.  There are four places we might find a selection-set:
 	// at the toplevel of a query, on a field, or in an inline or named
 	// fragment.  The toplevel of a query must be an object type, so we don't
-	// need to consider that.
-	// TODO(benkraft): Once we support fragments, figure out whether we need to
-	// traverse inline/named fragments here too.
+	// need to consider that.  And fragments must (if used at all) be spread
+	// into some parent selection-set, so we'll add __typename there (if
+	// needed).  Note this does mean abstract-typed fragments spread into
+	// object-typed scope will *not* have access to `__typename`, but they
+	// indeed don't need it, since we do know the type in that context.
 	observers.OnField(func(_ *validator.Walker, field *ast.Field) {
 		// We are interested in a field from the query like
 		//	field { subField ... }
@@ -207,14 +255,19 @@ func (g *generator) preprocessQueryDocument(doc *ast.QueryDocument) {
 	validator.Walk(g.schema, doc, &observers)
 }
 
+// addOperation adds to g.Operations the information needed to generate a
+// genqlient entrypoint function for the given operation.  It also adds to
+// g.typeMap any types referenced by the operation, except for types belonging
+// to named fragments, which are added separately by Generate via
+// convertFragment.
 func (g *generator) addOperation(op *ast.OperationDefinition) error {
 	if op.Name == "" {
 		return errorf(op.Position, "operations must have operation-names")
 	}
 
 	queryDoc := &ast.QueryDocument{
 		Operations: ast.OperationList{op},
-		// TODO: handle fragments
+		Fragments:  g.usedFragments(op),
 	}
 	g.preprocessQueryDocument(queryDoc)
 
@@ -297,15 +350,10 @@ func Generate(config *Config) (map[string][]byte, error) {
 			strings.Join(config.Operations, ", "))
 	}
 
-	if len(document.Fragments) > 0 && !config.AllowBrokenFeatures {
-		return nil, errorf(document.Fragments[0].Position,
-			"genqlient does not yet support fragments")
-	}
-
-	// Step 2: For each operation, convert it into data structures representing
-	// Go types (defined in types.go).  The bulk of this logic is in
-	// convert.go.
-	g := newGenerator(config, schema)
+	// Step 2: For each operation and fragment, convert it into data structures
+	// representing Go types (defined in types.go).  The bulk of this logic is
+	// in convert.go.
+	g := newGenerator(config, schema, document.Fragments)
 	for _, op := range document.Operations {
 		if err = g.addOperation(op); err != nil {
 			return nil, err

generate/genqlient_directive.go

@@ -153,6 +153,15 @@ func (dir *GenqlientDirective) validate(node interface{}) error {
 		// Anything else is valid on the entire operation; it will just apply
 		// to whatever it is relevant to.
 		return nil
+	case *ast.FragmentDefinition:
+		if dir.Bind != "" {
+			// TODO(benkraft): Implement this if people find it useful.
+			return errorf(dir.pos, "bind is not implemented for named fragments")
+		}
+
+		// Like operations, anything else will just apply to the entire
+		// fragment.
+		return nil
 	case *ast.VariableDefinition:
 		if dir.Omitempty != nil && node.Type.NonNull {
 			return errorf(dir.pos, "omitempty may only be used on optional arguments")
@@ -164,7 +173,7 @@ func (dir *GenqlientDirective) validate(node interface{}) error {
 		}
 		return nil
 	default:
-		return errorf(dir.pos, "invalid directive location: %T", node)
+		return errorf(dir.pos, "invalid @genqlient directive location: %T", node)
 	}
 }
 

generate/testdata/queries/ComplexNamedFragments.graphql

@@ -0,0 +1,39 @@
+fragment QueryFragment on Query {
+  ...InnerQueryFragment
+}
+
+fragment InnerQueryFragment on Query {
+  randomItem {
+    id name
+    ...VideoFields
+  }
+  randomLeaf {
+    ...VideoFields
+    ...MoreVideoFields
+  }
+  otherLeaf: randomLeaf {
+    ... on Video {
+      ...MoreVideoFields
+    }
+  }
+}
+
+fragment VideoFields on Video {
+  id name url duration thumbnail { id }
+}
+
+# @genqlient(pointer: true)
+fragment MoreVideoFields on Video {
+  id
+  parent {
+    name url
+    # @genqlient(pointer: false)
+    children {
+      ...VideoFields
+    }
+  }
+}
+
+query ComplexNamedFragments {
+  ... on Query { ...QueryFragment }
+}

generate/testdata/queries/SimpleNamedFragment.graphql

@@ -0,0 +1,13 @@
+fragment VideoFields on Video {
+  id name url duration thumbnail { id }
+}
+
+query SimpleNamedFragment {
+  randomItem {
+    id name
+    ...VideoFields
+  }
+  randomLeaf {
+    ...VideoFields
+  }
+}