From e55d92153749dd445a8e934773743e1fb125ee73 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Fri, 17 Mar 2023 09:28:16 -0500 Subject: [PATCH] chore: Typescript generator TODOs resolved, adding explainations (#6633) * chore: Explain usage of eslint comments * Conform comment * Fix wording * Linting --- scripts/apitypings/main.go | 32 +++++++++++++++++++++++++++----- site/src/api/typesGenerated.ts | 26 +++++++++++++++----------- 2 files changed, 42 insertions(+), 16 deletions(-) diff --git a/scripts/apitypings/main.go b/scripts/apitypings/main.go index 5ebc744e2b..e39d15e171 100644 --- a/scripts/apitypings/main.go +++ b/scripts/apitypings/main.go @@ -633,6 +633,8 @@ func (g *Generator) typescriptType(ty types.Type) (TypescriptType, error) { } case *types.Struct: // This handles anonymous structs. This should never happen really. + // If you require this, either change your datastructures, or implement + // anonymous structs here. // Such as: // type Name struct { // Embedded struct { @@ -643,7 +645,8 @@ func (g *Generator) typescriptType(ty types.Type) (TypescriptType, error) { ValueType: "any", AboveTypeLine: fmt.Sprintf("%s\n%s", indentedComment("Embedded anonymous struct, please fix by naming it"), - indentedComment("eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed"), + // Linter needs to be disabled here, or else it will complain about the "any" type. + indentedComment("eslint-disable-next-line @typescript-eslint/no-explicit-any -- Anonymously embedded struct"), ), }, nil case *types.Map: @@ -766,9 +769,14 @@ func (g *Generator) typescriptType(ty types.Type) (TypescriptType, error) { // If it's a struct, just use the name of the struct type if _, ok := n.Underlying().(*types.Struct); ok { + // External structs cannot be introspected, as we only parse the codersdk package. + // You can handle your type manually in the switch list above, otherwise "any" will be used. + // An easy way to fix this is to pull your external type into `codersdk` package, then it will + // be known by the generator. return TypescriptType{ValueType: "any", AboveTypeLine: fmt.Sprintf("%s\n%s", indentedComment(fmt.Sprintf("Named type %q unknown, using \"any\"", n.String())), - indentedComment("eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed"), + // Linter needs to be disabled here, or else it will complain about the "any" type. + indentedComment("eslint-disable-next-line @typescript-eslint/no-explicit-any -- External type"), )}, nil } @@ -789,14 +797,28 @@ func (g *Generator) typescriptType(ty types.Type) (TypescriptType, error) { resp.Optional = true return resp, nil case *types.Interface: - // only handle the empty interface for now + // only handle the empty interface (interface{}) for now intf := ty if intf.Empty() { + // This field is 'interface{}'. We can't infer any type from 'interface{}' + // so just use "any" as the type. return TypescriptType{ - ValueType: "any", - AboveTypeLine: indentedComment("eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed"), + ValueType: "any", + AboveTypeLine: fmt.Sprintf("%s\n%s", + indentedComment("Empty interface{} type, cannot resolve the type."), + // Linter needs to be disabled here, or else it will complain about the "any" type. + indentedComment("eslint-disable-next-line @typescript-eslint/no-explicit-any -- interface{}"), + ), }, nil } + // All complex interfaces should be named. So if we get here, that means + // we are using anonymous interfaces. Which is just weird and not supported. + // Example: + // type Foo struct { + // Bar interface { + // Baz() string + // } + // } return TypescriptType{}, xerrors.New("only empty interface types are supported") case *types.TypeParam: _, ok := ty.Underlying().(*types.Interface) diff --git a/site/src/api/typesGenerated.ts b/site/src/api/typesGenerated.ts index 0d3caf300b..7b2c7f7ba2 100644 --- a/site/src/api/typesGenerated.ts +++ b/site/src/api/typesGenerated.ts @@ -53,9 +53,11 @@ export type AuditDiff = Record // From codersdk/audit.go export interface AuditDiffField { - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // Empty interface{} type, cannot resolve the type. + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- interface{} readonly old?: any - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // Empty interface{} type, cannot resolve the type. + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- interface{} readonly new?: any readonly secret: boolean } @@ -67,7 +69,7 @@ export interface AuditLog { readonly time: string readonly organization_id: string // Named type "net/netip.Addr" unknown, using "any" - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- External type readonly ip: any readonly user_agent: string readonly resource_type: ResourceType @@ -357,13 +359,13 @@ export interface DeploymentValues { readonly disable_password_auth?: boolean readonly support?: SupportConfig // Named type "github.com/coder/coder/cli/clibase.Struct[[]github.com/coder/coder/codersdk.GitAuthConfig]" unknown, using "any" - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- External type readonly git_auth?: any readonly config_ssh?: SSHConfig readonly config?: string readonly write_config?: boolean // Named type "github.com/coder/coder/cli/clibase.HostPort" unknown, using "any" - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- External type readonly address?: any } @@ -442,7 +444,8 @@ export interface License { readonly id: number readonly uuid: string readonly uploaded_at: string - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // Empty interface{} type, cannot resolve the type. + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- interface{} readonly claims: Record } @@ -578,7 +581,7 @@ export interface PatchGroupRequest { export interface PprofConfig { readonly enable: boolean // Named type "github.com/coder/coder/cli/clibase.HostPort" unknown, using "any" - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- External type readonly address: any } @@ -586,7 +589,7 @@ export interface PprofConfig { export interface PrometheusConfig { readonly enable: boolean // Named type "github.com/coder/coder/cli/clibase.HostPort" unknown, using "any" - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- External type readonly address: any } @@ -683,7 +686,8 @@ export interface SSHConfigResponse { // From codersdk/serversentevents.go export interface ServerSentEvent { readonly type: ServerSentEventType - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // Empty interface{} type, cannot resolve the type. + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- interface{} readonly data: any } @@ -705,7 +709,7 @@ export interface SessionCountDeploymentStats { // From codersdk/deployment.go export interface SupportConfig { // Named type "github.com/coder/coder/cli/clibase.Struct[[]github.com/coder/coder/codersdk.LinkConfig]" unknown, using "any" - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- External type readonly links: any } @@ -718,7 +722,7 @@ export interface SwaggerConfig { export interface TLSConfig { readonly enable: boolean // Named type "github.com/coder/coder/cli/clibase.HostPort" unknown, using "any" - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO explain why this is needed + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- External type readonly address: any readonly redirect_http: boolean readonly cert_file: string[]