From ff790e1c0631db0144b0752fbf3890cb622432e9 Mon Sep 17 00:00:00 2001 From: Ben Kraft Date: Sun, 7 May 2023 12:15:13 -0700 Subject: [PATCH] Add an option to handle enums with ugly casing (#270) There are a bunch of places in genqlient where we just kind of hope you don't have ridiculous casing conflicts in your schema. Apparently with enum values there are actual schemas that have this problem! Now we have an option to disable. I ended up putting it all under `casing` instead of in `bindings` so we can clearly document the list of algorithms we support, and so we can have an `all_enums` value if you're working with a schema with a lot of this; in the future we may want to add similar behavior for types/fields, add more possible algorithms (e.g. to make things unexported), etc. I added tests for the new feature, although the way the tests are set up it wasn't convenient to do so for a schema where this is actually required. I also added a check for case conflicts that points you to this option. (I don't want to do it automatically for reasons described in the issue; mainly it just seemed a bit too magical.) Fixes #265. --- docs/CHANGELOG.md | 1 + docs/genqlient.yaml | 21 ++++ generate/config.go | 58 ++++++++++ generate/config_test.go | 47 +++++--- generate/convert.go | 17 ++- generate/generate_test.go | 12 +++ generate/names.go | 13 +++ .../errors/ConflictingEnumValues.graphql | 1 + .../ConflictingEnumValues.schema.graphql | 9 ++ .../invalid-config/InvalidCasing.yaml | 3 + generate/testdata/queries/schema.graphql | 2 +- ...nerateErrors-ConflictingEnumValues-graphql | 1 + ...RawCasingAll-testdata-queries-generated.go | 100 ++++++++++++++++++ ...singSpecific-testdata-queries-generated.go | 100 ++++++++++++++++++ .../TestInvalidConfigs-InvalidCasing.yaml | 1 + generate/types.go | 6 +- 16 files changed, 375 insertions(+), 17 deletions(-) create mode 100644 generate/testdata/errors/ConflictingEnumValues.graphql create mode 100644 generate/testdata/errors/ConflictingEnumValues.schema.graphql create mode 100644 generate/testdata/invalid-config/InvalidCasing.yaml create mode 100644 generate/testdata/snapshots/TestGenerateErrors-ConflictingEnumValues-graphql create mode 100644 generate/testdata/snapshots/TestGenerateWithConfig-EnumRawCasingAll-testdata-queries-generated.go create mode 100644 generate/testdata/snapshots/TestGenerateWithConfig-EnumRawCasingSpecific-testdata-queries-generated.go create mode 100644 generate/testdata/snapshots/TestInvalidConfigs-InvalidCasing.yaml diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index d12cde4..a2733cf 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -25,6 +25,7 @@ When releasing a new version: ### New features: - The new `optional: generic` allows using a generic type to represent optionality. See the [documentation](genqlient.yaml) for details. +- For schemas with enum values that differ only in casing, it's now possible to disable smart-casing in genqlient.yaml; see the [documentation](genqlient.yaml) for `casing` for details. ### Bug fixes: diff --git a/docs/genqlient.yaml b/docs/genqlient.yaml index 5e5601b..1281321 100644 --- a/docs/genqlient.yaml +++ b/docs/genqlient.yaml @@ -227,3 +227,24 @@ bindings: # Explicit entries in bindings take precedence over all package bindings. package_bindings: - package: github.com/you/yourpkg/models + +# Configuration for genqlient's smart-casing. +# +# By default genqlient tries to convert GraphQL type names to Go style +# automatically. Sometimes it doesn't do a great job; this suite of options +# lets you configure its algorithm as makes sense for your schema. +# +# Options below support the following values: +# - default: use genqlient's default algorithm, which tries to convert GraphQL +# names to exported Go names. This is usually best for GraphQL schemas using +# idiomatic GraphQL types. +# - raw: map the GraphQL type exactly; don't try to convert it to Go style. +# This is usually best for schemas with casing conflicts, e.g. enums with +# values which differ only in casing. +casing: + # Use the given casing-style (see above) for all GraphQL enum values. + all_enums: raw + # Use the given casing-style (see above) for the enum values in the given + # GraphQL types (takes precedence over all_enum_values). + enums: + MyEnum: raw diff --git a/generate/config.go b/generate/config.go index 31db2d6..65bc53c 100644 --- a/generate/config.go +++ b/generate/config.go @@ -31,6 +31,7 @@ type Config struct { ClientGetter string `yaml:"client_getter"` Bindings map[string]*TypeBinding `yaml:"bindings"` PackageBindings []*PackageBinding `yaml:"package_bindings"` + Casing Casing `yaml:"casing"` Optional string `yaml:"optional"` OptionalGenericType string `yaml:"optional_generic_type"` StructReferences bool `yaml:"use_struct_references"` @@ -68,6 +69,59 @@ type PackageBinding struct { Package string `yaml:"package"` } +// CasingAlgorithm represents a way that genqlient can handle casing, and is +// documented further in the [genqlient.yaml docs]. +// +// [genqlient.yaml docs]: https://github.com/Khan/genqlient/blob/main/docs/genqlient.yaml +type CasingAlgorithm string + +const ( + CasingDefault CasingAlgorithm = "default" + CasingRaw CasingAlgorithm = "raw" +) + +func (algo CasingAlgorithm) validate() error { + switch algo { + case CasingDefault, CasingRaw: + return nil + default: + return errorf(nil, "unknown casing algorithm: %s", algo) + } +} + +// Casing wraps the casing-related options, and is documented further in +// the [genqlient.yaml docs]. +// +// [genqlient.yaml docs]: https://github.com/Khan/genqlient/blob/main/docs/genqlient.yaml +type Casing struct { + AllEnums CasingAlgorithm `yaml:"all_enums"` + Enums map[string]CasingAlgorithm `yaml:"enums"` +} + +func (casing *Casing) validate() error { + if casing.AllEnums != "" { + if err := casing.AllEnums.validate(); err != nil { + return err + } + } + for _, algo := range casing.Enums { + if err := algo.validate(); err != nil { + return err + } + } + return nil +} + +func (casing *Casing) forEnum(graphQLTypeName string) CasingAlgorithm { + if specificConfig, ok := casing.Enums[graphQLTypeName]; ok { + return specificConfig + } + if casing.AllEnums != "" { + return casing.AllEnums + } + return CasingDefault +} + // pathJoin is like filepath.Join but 1) it only takes two argsuments, // and b) if the second argument is an absolute path the first argument // is ignored (similar to how python's os.path.join() works). @@ -172,6 +226,10 @@ func (c *Config) ValidateAndFillDefaults(baseDir string) error { } } + if err := c.Casing.validate(); err != nil { + return err + } + return nil } diff --git a/generate/config_test.go b/generate/config_test.go index 3568a72..5e0b53e 100644 --- a/generate/config_test.go +++ b/generate/config_test.go @@ -2,12 +2,19 @@ package generate import ( "os" + "path/filepath" "testing" + "github.com/Khan/genqlient/internal/testutil" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) +const ( + findConfigDir = "testdata/find-config" + invalidConfigDir = "testdata/invalid-config" +) + func TestFindCfg(t *testing.T) { cwd, err := os.Getwd() require.NoError(t, err) @@ -18,15 +25,15 @@ func TestFindCfg(t *testing.T) { expectedErr error }{ "yaml in parent directory": { - startDir: cwd + "/testdata/find-config/parent/child", - expectedCfg: cwd + "/testdata/find-config/parent/genqlient.yaml", + startDir: filepath.Join(cwd, findConfigDir, "parent", "child"), + expectedCfg: filepath.Join(cwd, findConfigDir, "parent", "genqlient.yaml"), }, "yaml in current directory": { - startDir: cwd + "/testdata/find-config/current", - expectedCfg: cwd + "/testdata/find-config/current/genqlient.yaml", + startDir: filepath.Join(cwd, findConfigDir, "current"), + expectedCfg: filepath.Join(cwd, findConfigDir, "current", "genqlient.yaml"), }, "no yaml": { - startDir: cwd + "/testdata/find-config/none/child", + startDir: filepath.Join(cwd, findConfigDir, "none", "child"), expectedErr: os.ErrNotExist, }, } @@ -56,23 +63,23 @@ func TestFindCfgInDir(t *testing.T) { found bool }{ "yaml": { - startDir: cwd + "/testdata/find-config/filenames/yaml", + startDir: filepath.Join(cwd, findConfigDir, "filenames", "yaml"), found: true, }, "yml": { - startDir: cwd + "/testdata/find-config/filenames/yml", + startDir: filepath.Join(cwd, findConfigDir, "filenames", "yml"), found: true, }, ".yaml": { - startDir: cwd + "/testdata/find-config/filenames/dotyaml", + startDir: filepath.Join(cwd, findConfigDir, "filenames", "dotyaml"), found: true, }, ".yml": { - startDir: cwd + "/testdata/find-config/filenames/dotyml", + startDir: filepath.Join(cwd, findConfigDir, "filenames", "dotyml"), found: true, }, "none": { - startDir: cwd + "/testdata/find-config/filenames/none", + startDir: filepath.Join(cwd, findConfigDir, "filenames", "none"), found: false, }, } @@ -94,15 +101,31 @@ func TestAbsoluteAndRelativePathsInConfigFiles(t *testing.T) { require.NoError(t, err) config, err := ReadAndValidateConfig( - cwd + "/testdata/find-config/current/genqlient.yaml") + filepath.Join(cwd, findConfigDir, "current", "genqlient.yaml")) require.NoError(t, err) require.Equal(t, 1, len(config.Schema)) require.Equal( t, - cwd+"/testdata/find-config/current/schema.graphql", + filepath.Join(cwd, findConfigDir, "current", "schema.graphql"), config.Schema[0], ) require.Equal(t, 1, len(config.Operations)) require.Equal(t, "/tmp/genqlient.graphql", config.Operations[0]) } + +func TestInvalidConfigs(t *testing.T) { + files, err := os.ReadDir(invalidConfigDir) + if err != nil { + t.Fatal(err) + } + + for _, file := range files { + t.Run(file.Name(), func(t *testing.T) { + filename := filepath.Join(invalidConfigDir, file.Name()) + _, err := ReadAndValidateConfig(filename) + require.Error(t, err) + testutil.Cupaloy.SnapshotT(t, err.Error()) + }) + } +} diff --git a/generate/convert.go b/generate/convert.go index 41eb123..3d2e7ac 100644 --- a/generate/convert.go +++ b/generate/convert.go @@ -516,8 +516,23 @@ func (g *generator) convertDefinition( Description: def.Description, Values: make([]goEnumValue, len(def.EnumValues)), } + goNames := make(map[string]*goEnumValue, len(def.EnumValues)) for i, val := range def.EnumValues { - goType.Values[i] = goEnumValue{Name: val.Name, Description: val.Description} + goName := g.Config.Casing.enumValueName(name, def, val) + if conflict := goNames[goName]; conflict != nil { + return nil, errorf(val.Position, + "enum values %s and %s have conflicting Go name %s; "+ + "add 'all_enums: raw' or 'enums: %v: raw' "+ + "to 'casing' in genqlient.yaml to fix", + val.Name, conflict.GraphQLName, goName, def.Name) + } + + goType.Values[i] = goEnumValue{ + GoName: goName, + GraphQLName: val.Name, + Description: val.Description, + } + goNames[goName] = &goType.Values[i] } return g.addType(goType, goType.GoName, pos) diff --git a/generate/generate_test.go b/generate/generate_test.go index 8daa3e1..6baab56 100644 --- a/generate/generate_test.go +++ b/generate/generate_test.go @@ -238,6 +238,18 @@ func TestGenerateWithConfig(t *testing.T) { Optional: "generic", OptionalGenericType: "github.com/Khan/genqlient/internal/testutil.Option", }}, + {"EnumRawCasingAll", "", []string{"QueryWithEnums.graphql"}, &Config{ + Generated: "generated.go", + Casing: Casing{ + AllEnums: CasingRaw, + }, + }}, + {"EnumRawCasingSpecific", "", []string{"QueryWithEnums.graphql"}, &Config{ + Generated: "generated.go", + Casing: Casing{ + Enums: map[string]CasingAlgorithm{"Role": CasingRaw}, + }, + }}, } sourceFilename := "SimpleQuery.graphql" diff --git a/generate/names.go b/generate/names.go index 6410bc3..29074e0 100644 --- a/generate/names.go +++ b/generate/names.go @@ -99,6 +99,7 @@ package generate // response object (inline in convertOperation). import ( + "fmt" "strings" "github.com/vektah/gqlparser/v2/ast" @@ -178,3 +179,15 @@ func makeLongTypeName(prefix *prefixList, typeName string) string { typeName = upperFirst(typeName) return joinPrefixList(&prefixList{typeName, prefix}) } + +func (casing *Casing) enumValueName(goTypeName string, enum *ast.Definition, val *ast.EnumValueDefinition) string { + switch algo := casing.forEnum(enum.Name); algo { + case CasingDefault: + return goTypeName + goConstName(val.Name) + case CasingRaw: + return goTypeName + "_" + val.Name + default: + // Should already be caught by validation. + panic(fmt.Sprintf("unknown casing algorithm %s", algo)) + } +} diff --git a/generate/testdata/errors/ConflictingEnumValues.graphql b/generate/testdata/errors/ConflictingEnumValues.graphql new file mode 100644 index 0000000..0aed8f6 --- /dev/null +++ b/generate/testdata/errors/ConflictingEnumValues.graphql @@ -0,0 +1 @@ +query ConflictingEnumValues { f } diff --git a/generate/testdata/errors/ConflictingEnumValues.schema.graphql b/generate/testdata/errors/ConflictingEnumValues.schema.graphql new file mode 100644 index 0000000..d91009e --- /dev/null +++ b/generate/testdata/errors/ConflictingEnumValues.schema.graphql @@ -0,0 +1,9 @@ +enum AnnoyingEnum { + first_value + second_value + FIRST_VALUE +} + +type Query { + f: AnnoyingEnum +} diff --git a/generate/testdata/invalid-config/InvalidCasing.yaml b/generate/testdata/invalid-config/InvalidCasing.yaml new file mode 100644 index 0000000..1f63cee --- /dev/null +++ b/generate/testdata/invalid-config/InvalidCasing.yaml @@ -0,0 +1,3 @@ +casing: + enums: + MyType: bogus diff --git a/generate/testdata/queries/schema.graphql b/generate/testdata/queries/schema.graphql index f6b3a68..6e783de 100644 --- a/generate/testdata/queries/schema.graphql +++ b/generate/testdata/queries/schema.graphql @@ -204,4 +204,4 @@ input IntComparisonExp { _lte: Int _neq: Int _nin: [Int!] -} \ No newline at end of file +} diff --git a/generate/testdata/snapshots/TestGenerateErrors-ConflictingEnumValues-graphql b/generate/testdata/snapshots/TestGenerateErrors-ConflictingEnumValues-graphql new file mode 100644 index 0000000..e478c96 --- /dev/null +++ b/generate/testdata/snapshots/TestGenerateErrors-ConflictingEnumValues-graphql @@ -0,0 +1 @@ +testdata/errors/ConflictingEnumValues.schema.graphql:4: enum values FIRST_VALUE and first_value have conflicting Go name AnnoyingEnumFirstValue; add 'all_enums: raw' or 'enums: AnnoyingEnum: raw' to 'casing' in genqlient.yaml to fix diff --git a/generate/testdata/snapshots/TestGenerateWithConfig-EnumRawCasingAll-testdata-queries-generated.go b/generate/testdata/snapshots/TestGenerateWithConfig-EnumRawCasingAll-testdata-queries-generated.go new file mode 100644 index 0000000..f168b1a --- /dev/null +++ b/generate/testdata/snapshots/TestGenerateWithConfig-EnumRawCasingAll-testdata-queries-generated.go @@ -0,0 +1,100 @@ +// Code generated by github.com/Khan/genqlient, DO NOT EDIT. + +package queries + +import ( + "context" + + "github.com/Khan/genqlient/graphql" +) + +// QueryWithEnumsOtherUser includes the requested fields of the GraphQL type User. +// The GraphQL type's documentation follows. +// +// A User is a user! +type QueryWithEnumsOtherUser struct { + Roles []Role `json:"roles"` +} + +// GetRoles returns QueryWithEnumsOtherUser.Roles, and is useful for accessing the field via an interface. +func (v *QueryWithEnumsOtherUser) GetRoles() []Role { return v.Roles } + +// QueryWithEnumsResponse is returned by QueryWithEnums on success. +type QueryWithEnumsResponse struct { + // user looks up a user by some stuff. + // + // See UserQueryInput for what stuff is supported. + // If query is null, returns the current user. + User QueryWithEnumsUser `json:"user"` + // user looks up a user by some stuff. + // + // See UserQueryInput for what stuff is supported. + // If query is null, returns the current user. + OtherUser QueryWithEnumsOtherUser `json:"otherUser"` +} + +// GetUser returns QueryWithEnumsResponse.User, and is useful for accessing the field via an interface. +func (v *QueryWithEnumsResponse) GetUser() QueryWithEnumsUser { return v.User } + +// GetOtherUser returns QueryWithEnumsResponse.OtherUser, and is useful for accessing the field via an interface. +func (v *QueryWithEnumsResponse) GetOtherUser() QueryWithEnumsOtherUser { return v.OtherUser } + +// QueryWithEnumsUser includes the requested fields of the GraphQL type User. +// The GraphQL type's documentation follows. +// +// A User is a user! +type QueryWithEnumsUser struct { + Roles []Role `json:"roles"` +} + +// GetRoles returns QueryWithEnumsUser.Roles, and is useful for accessing the field via an interface. +func (v *QueryWithEnumsUser) GetRoles() []Role { return v.Roles } + +// Role is a type a user may have. +type Role string + +const ( + // What is a student? + // + // A student is primarily a person enrolled in a school or other educational institution and who is under learning with goals of acquiring knowledge, developing professions and achieving employment at desired field. In the broader sense, a student is anyone who applies themselves to the intensive intellectual engagement with some matter necessary to master it as part of some practical affair in which such mastery is basic or decisive. + // + // (from [Wikipedia](https://en.wikipedia.org/wiki/Student)) + Role_STUDENT Role = "STUDENT" + // Teacher is a teacher, who teaches the students. + Role_TEACHER Role = "TEACHER" +) + +// The query or mutation executed by QueryWithEnums. +const QueryWithEnums_Operation = ` +query QueryWithEnums { + user { + roles + } + otherUser: user { + roles + } +} +` + +func QueryWithEnums( + ctx context.Context, + client graphql.Client, +) (*QueryWithEnumsResponse, error) { + req := &graphql.Request{ + OpName: "QueryWithEnums", + Query: QueryWithEnums_Operation, + } + var err error + + var data QueryWithEnumsResponse + resp := &graphql.Response{Data: &data} + + err = client.MakeRequest( + ctx, + req, + resp, + ) + + return &data, err +} + diff --git a/generate/testdata/snapshots/TestGenerateWithConfig-EnumRawCasingSpecific-testdata-queries-generated.go b/generate/testdata/snapshots/TestGenerateWithConfig-EnumRawCasingSpecific-testdata-queries-generated.go new file mode 100644 index 0000000..f168b1a --- /dev/null +++ b/generate/testdata/snapshots/TestGenerateWithConfig-EnumRawCasingSpecific-testdata-queries-generated.go @@ -0,0 +1,100 @@ +// Code generated by github.com/Khan/genqlient, DO NOT EDIT. + +package queries + +import ( + "context" + + "github.com/Khan/genqlient/graphql" +) + +// QueryWithEnumsOtherUser includes the requested fields of the GraphQL type User. +// The GraphQL type's documentation follows. +// +// A User is a user! +type QueryWithEnumsOtherUser struct { + Roles []Role `json:"roles"` +} + +// GetRoles returns QueryWithEnumsOtherUser.Roles, and is useful for accessing the field via an interface. +func (v *QueryWithEnumsOtherUser) GetRoles() []Role { return v.Roles } + +// QueryWithEnumsResponse is returned by QueryWithEnums on success. +type QueryWithEnumsResponse struct { + // user looks up a user by some stuff. + // + // See UserQueryInput for what stuff is supported. + // If query is null, returns the current user. + User QueryWithEnumsUser `json:"user"` + // user looks up a user by some stuff. + // + // See UserQueryInput for what stuff is supported. + // If query is null, returns the current user. + OtherUser QueryWithEnumsOtherUser `json:"otherUser"` +} + +// GetUser returns QueryWithEnumsResponse.User, and is useful for accessing the field via an interface. +func (v *QueryWithEnumsResponse) GetUser() QueryWithEnumsUser { return v.User } + +// GetOtherUser returns QueryWithEnumsResponse.OtherUser, and is useful for accessing the field via an interface. +func (v *QueryWithEnumsResponse) GetOtherUser() QueryWithEnumsOtherUser { return v.OtherUser } + +// QueryWithEnumsUser includes the requested fields of the GraphQL type User. +// The GraphQL type's documentation follows. +// +// A User is a user! +type QueryWithEnumsUser struct { + Roles []Role `json:"roles"` +} + +// GetRoles returns QueryWithEnumsUser.Roles, and is useful for accessing the field via an interface. +func (v *QueryWithEnumsUser) GetRoles() []Role { return v.Roles } + +// Role is a type a user may have. +type Role string + +const ( + // What is a student? + // + // A student is primarily a person enrolled in a school or other educational institution and who is under learning with goals of acquiring knowledge, developing professions and achieving employment at desired field. In the broader sense, a student is anyone who applies themselves to the intensive intellectual engagement with some matter necessary to master it as part of some practical affair in which such mastery is basic or decisive. + // + // (from [Wikipedia](https://en.wikipedia.org/wiki/Student)) + Role_STUDENT Role = "STUDENT" + // Teacher is a teacher, who teaches the students. + Role_TEACHER Role = "TEACHER" +) + +// The query or mutation executed by QueryWithEnums. +const QueryWithEnums_Operation = ` +query QueryWithEnums { + user { + roles + } + otherUser: user { + roles + } +} +` + +func QueryWithEnums( + ctx context.Context, + client graphql.Client, +) (*QueryWithEnumsResponse, error) { + req := &graphql.Request{ + OpName: "QueryWithEnums", + Query: QueryWithEnums_Operation, + } + var err error + + var data QueryWithEnumsResponse + resp := &graphql.Response{Data: &data} + + err = client.MakeRequest( + ctx, + req, + resp, + ) + + return &data, err +} + diff --git a/generate/testdata/snapshots/TestInvalidConfigs-InvalidCasing.yaml b/generate/testdata/snapshots/TestInvalidConfigs-InvalidCasing.yaml new file mode 100644 index 0000000..2bcb5e0 --- /dev/null +++ b/generate/testdata/snapshots/TestInvalidConfigs-InvalidCasing.yaml @@ -0,0 +1 @@ +invalid config file testdata/invalid-config/InvalidCasing.yaml: unknown casing algorithm: bogus diff --git a/generate/types.go b/generate/types.go index 07c661c..01f619f 100644 --- a/generate/types.go +++ b/generate/types.go @@ -131,7 +131,8 @@ type goEnumType struct { } type goEnumValue struct { - Name string + GoName string + GraphQLName string Description string } @@ -143,8 +144,7 @@ func (typ *goEnumType) WriteDefinition(w io.Writer, g *generator) error { for _, val := range typ.Values { writeDescription(w, val.Description) fmt.Fprintf(w, "%s %s = \"%s\"\n", - typ.GoName+goConstName(val.Name), - typ.GoName, val.Name) + val.GoName, typ.GoName, val.GraphQLName) } fmt.Fprintf(w, ")\n") return nil