better document and position the hash base64 encoding (#234)

We now document why we use a custom base64 charset.

The old "b64" name was also too generic, so it might have been misused
for other purposes.

hash.go

@@ -141,6 +141,16 @@ func buildidOf(path string) (string, error) {
 	return string(out), nil
 }
 
+var (
+	// Hashed names are base64-encoded.
+	// Go names can only be letters, numbers, and underscores.
+	// This means we can use base64's URL encoding, minus '-'.
+	// Use the URL encoding, replacing '-' with a duplicate 'z'.
+	// Such a lossy encoding is fine, since we never decode hashes.
+	nameCharset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_z"
+	nameBase64  = base64.NewEncoding(nameCharset)
+)
+
 func hashWith(salt []byte, name string) string {
 	if len(salt) == 0 {
 		panic("hashWith: empty salt")
@@ -154,8 +164,10 @@ func hashWith(salt []byte, name string) string {
 	d.Write(salt)
 	d.Write(opts.Seed)
 	io.WriteString(d, name)
-	sum := b64.EncodeToString(d.Sum(nil))
+	sum := nameBase64.EncodeToString(d.Sum(nil))
 
+	// TODO: Just make the first letter uppercase or lowercase as needed.
+	// This is also not needed for non-names, like import paths.
 	if token.IsExported(name) {
 		return "Z" + sum[:length]
 	}

main.go

@@ -87,8 +87,6 @@ var (
 	fset          = token.NewFileSet()
 	sharedTempDir = os.Getenv("GARBLE_SHARED")
 
-	nameCharset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_z"
-	b64         = base64.NewEncoding(nameCharset)
 	printConfig = printer.Config{Mode: printer.RawFormat}
 
 	// origImporter is a go/types importer which uses the original versions