Refactor import-loading to simplify the type-generation code (#101)

## Summary:
genqlient has some code (`imports.go`) dedicated to tracking which
imports we need and avoiding conflicts, as well as converting a
(restricted) Go expression like `map[string]github.com/me/mypkg.MyType`
to an import (`github.com/me/mypkg`) and a type-reference
(`map[string]mypkg.MyType`) to be used in the context of that import,
and at least making some attempt to track conflicts.  (Right now the
conflict-avoidance is not very smart, and not very well tested, but it
comes up rarely anyway.)  Sadly, that code was a bit cumbersome to use,
because you had to first register the imports (typically from
`convert.go`), then use them (often from the template).

In this commit I refactor the order we write things in order to allow a
significant simplification of how we import; in particular we no longer
have to guess in advance what imports which template will need; it can
just do `{{ref <expr>}}` as before, and it just works.  To do this, I:
- changed the importer to have only one API, which adds the import if
  needed, and returns the reference either way
- added a check that we don't add imports after they're written
- reorganized the toplevel templates a bit to make sure that check never
  fires; we now generate all the types and operations, then write the
  imports and glue it all together
This removes a bunch of silly code, and should simplify the process of
adding custom (un)marshalers (#38).

While I was at it, I put the documentation of what expressions we
support in a more visible place, and added a type-assertion that your
custom context type implements context.Context (if applicable).

## Test plan:
make check


Author: benjaminjkraft

Reviewers: StevenACoffman, dnerdy, aberkan, jvoll, mahtabsabet, MiguelCastillo

Required Reviewers: 

Approved By: StevenACoffman, dnerdy

Checks: ⌛ Test (1.17), ⌛ Test (1.16), ⌛ Test (1.15), ⌛ Test (1.14), ⌛ Lint, ⌛ Test (1.17), ⌛ Test (1.16), ⌛ Test (1.15), ⌛ Test (1.14), ⌛ Lint

Pull Request URL: https://github.com/Khan/genqlient/pull/101

generate/imports.go

@@ -9,15 +9,12 @@ import (
 )
 
 func (g *generator) addImportFor(pkgPath string) (alias string) {
-	if existingAlias, ok := g.imports[pkgPath]; ok {
-		return existingAlias
-	}
-
 	pkgName := pkgPath[strings.LastIndex(pkgPath, "/")+1:]
 	alias = pkgName
 	suffix := 2
 	for g.usedAliases[alias] {
 		alias = pkgName + strconv.Itoa(suffix)
+		suffix++
 	}
 
 	g.imports[pkgPath] = alias
@@ -25,44 +22,33 @@ func (g *generator) addImportFor(pkgPath string) (alias string) {
 	return alias
 }
 
-// addRef adds any imports necessary to refer to the given name, and returns a
-// reference alias.Name for it.
-func (g *generator) addRef(fullyQualifiedName string) (qualifiedName string, err error) {
-	return g.getRef(fullyQualifiedName, true)
-}
-
-// ref returns a reference alias.Name for the given import, if its package was
-// already added (e.g. via addRef), and an error if not.
-func (g *generator) ref(fullyQualifiedName string) (qualifiedName string, err error) {
-	return g.getRef(fullyQualifiedName, false)
-}
-
 var _sliceOrMapPrefixRegexp = regexp.MustCompile(`^(\*|\[\d*\]|map\[string\])*`)
 
-func (g *generator) getRef(fullyQualifiedName string, addImport bool) (qualifiedName string, err error) {
-	// Ideally, we want to allow a reference to basically an arbitrary symbol.
-	// But that's very hard, because it might be quite complicated, like
-	//	struct{ F []map[mypkg.K]otherpkg.V }
-	// Now in practice, using an unnamed struct is not a great idea, but we do
-	// want to allow as much as we can that encoding/json knows how to work
-	// with, since you would reasonably expect us to accept, say,
-	// map[string][]interface{}.  So we allow:
-	// - any named type (mypkg.T)
-	// - any predeclared basic type (string, int, etc.)
-	// - interface{}
-	// - for any allowed type T, *T, []T, [N]T, and map[string]T
-	// which effectively excludes:
-	// - unnamed struct types
-	// - map[K]V where K is a named type wrapping string
-	// - any nonstandard spelling of those (interface {/* hi */},
-	//	 map[  string      ]T)
-	// TODO: document that somewhere visible
-
+// ref takes a Go fully-qualified name, ensures that any necessary symbols are
+// imported, and returns an appropriate reference.
+//
+// Ideally, we want to allow a reference to basically an arbitrary symbol.
+// But that's very hard, because it might be quite complicated, like
+//	struct{ F []map[mypkg.K]otherpkg.V }
+// Now in practice, using an unnamed struct is not a great idea, but we do
+// want to allow as much as we can that encoding/json knows how to work
+// with, since you would reasonably expect us to accept, say,
+// map[string][]interface{}.  So we allow:
+// - any named type (mypkg.T)
+// - any predeclared basic type (string, int, etc.)
+// - interface{}
+// - for any allowed type T, *T, []T, [N]T, and map[string]T
+// which effectively excludes:
+// - unnamed struct types
+// - map[K]V where K is a named type wrapping string
+// - any nonstandard spelling of those (interface {/* hi */},
+//	 map[  string      ]T)
+// (This is documented in docs/genqlient.yaml)
+func (g *generator) ref(fullyQualifiedName string) (qualifiedName string, err error) {
 	errorMsg := `invalid type-name "%v" (%v); expected a builtin, ` +
 		`path/to/package.Name, interface{}, or a slice, map, or pointer of those`
 
 	if strings.Contains(fullyQualifiedName, " ") {
-		// TODO: pass in pos here and below
 		return "", errorf(nil, errorMsg, fullyQualifiedName, "contains spaces")
 	}
 
@@ -80,22 +66,20 @@ func (g *generator) getRef(fullyQualifiedName string, addImport bool) (qualified
 
 	pkgPath := nameToImport[:i]
 	localName := nameToImport[i+1:]
-	var alias string
-	if addImport {
-		alias = g.addImportFor(pkgPath)
-	} else {
-		var ok bool
-		alias, ok = g.imports[pkgPath]
-		if !ok {
-			// This is an internal error, not a user error.
-			return "", errorf(nil, `no alias defined for package "%v"`, pkgPath)
+	alias, ok := g.imports[pkgPath]
+	if !ok {
+		if g.importsLocked {
+			return "", errorf(nil,
+				`genqlient internal error: imports locked but package "%v" has not been imported`, pkgPath)
 		}
+		alias = g.addImportFor(pkgPath)
 	}
 	return prefix + alias + "." + localName, nil
 }
 
 // Returns the import-clause to use in the generated code.
 func (g *generator) Imports() string {
+	g.importsLocked = true
 	if len(g.imports) == 0 {
 		return ""
 	}