Big refactor to separate operation-traversal from code-generation

[benjaminjkraft]

Summary:

I've felt for a while that types.go is way too confusing, and as I
started to implement some of the more complex cases of generating
interface-types, the cracks were really starting to show. Luckily, I
also finally realized how to fix it: we need to separate the process of
traversing the GraphQL operation and schema to decide what types to
generate from the process of actually generating those types. This
requires an extra set of intermediate data structures, but I think it
makes things quite a lot easier to understand -- and, importantly, it
means that the code-generation doesn't need to go in the order we
traverse the query/schema.

So in this commit, I did that huge refactor. It's probably best to just
review types.go and traverse.go as if they were new; the old code was
quite hard to understand and the new code will hopefully make a lot more
sense. (And to that end, review comments about what could be organized
better or needs more documentation are very much in order, even for code
that is mostly unchanged.)

This does introduce one bug, sort of, which is that rather than
generating broken code for list-of-interface fields, we generate no code
at all. (A TODO in unmarshal.go describes why.) I'll fix this when I
add support for those fields. (It's all behind the AllowBrokenFeatures
flag, anyway.) Otherwise, the only changes to generated code are that a
few methods are ordered differently, because we now generate the
implements-interface methods with the interface, rather than the
implementations, as it's much simpler that way. (In GraphQL, unlike Go,
we know the list of all possible implementations of each interface, so
this is possible.)

Test plan:

golangci-lint run ./... && go test ./...

[dnerdy]

I think having an intermediate data structure makes a lot of sense; I found it pretty easy to follow the new code. The feedback I have is pretty superficial:

• The file name traverse.go made sense once I understood what the code was doing, but it wasn't clear on the initial read that that was the file I needed to go to. Most of the functions in the file have a name that starts with "convert". Naming the file convert.go or something similar could help with discovery.
• Similarly, comments.go is related to genqlient directives, which happen to be powered by comments, but it wasn't clear to me at first that that's the place I should look for the directive code.
• Finally (and not at all related to this diff), I was surprised to see that template execution uses runtime.Caller(0) to locate a template. I think this only works when using go run; i.e. this would break if the user only has is a genqlient executable. Using //go:embed would work in both cases: https://pkg.go.dev/embed.

[dnerdy]

What do you think about naming this "TypeName" instead of "Reference". "Reference" sounds like this should always be a pointer.

[benjaminjkraft]

The problem is it's not always a type-name either since it might be []*MyStruct. (Or, for goOpaqueType, even map[string]interface{}.) But maybe that's at least closer.

[benjaminjkraft]

* The file name `traverse.go` ...
* Similarly, `comments.go` ...

Good ideas, will do!

* Finally (and not at all related to this diff), I was surprised to see that template execution uses `runtime.Caller(0)` to locate a template. I think this only works when using `go run`; i.e. this would break if the user only has is a genqlient executable. Using `//go:embed` would work in both cases: https://pkg.go.dev/embed.

I believe it works as long as the executable was compiled on the same machine (and the genqlient checkout used to do so has not been moved, etc.) although I haven't tried that. I agree embedding would be a better long-term solution, but we need to either use a third-party package or wait until we drop support for Go 1.13-1.15 (and we definitely can't drop 1.15 yet); see #9.