Guard generics support behind an experiment flag.

nevkontakte · nevkontakte · commit 18c10ff50d4c · 2024-03-23T19:53:03.000Z
This commit adds support for GOPHERJS_EXPERIMENT environment variable
that can be used to enable experimental functionality in the compiler.

Experiment flags can be easily added or removed by updating fields of
the internal/experiments.Flags struct. For now, only boolean flags are
supported, but it should be easy enough to extend if needed.

Users need to have GOPHERJS_EXPERIMENT=generics set in their environment
to enable support. Adding the flag will allow us to merge generics
support into the main branch before it's fully production-ready without
creating unnecessary confusion for the users.
diff --git a/circle.yml b/circle.yml
@@ -74,6 +74,8 @@ orbs:
 jobs:
   build:
     executor: gopherjs
+    environment:
+      GOPHERJS_EXPERIMENT: generics
     steps:
     - setup_and_install_gopherjs
     - run:
@@ -129,6 +131,8 @@ jobs:
   gopherjs_tests:
     executor: gopherjs
     parallelism: 4
+    environment:
+      GOPHERJS_EXPERIMENT: generics
     steps:
     - setup_and_install_gopherjs
     - run:
@@ -155,6 +159,8 @@ jobs:
 
   gorepo_tests:
     executor: gopherjs
+    environment:
+      GOPHERJS_EXPERIMENT: generics
     parallelism: 4
     steps:
     - setup_environment
@@ -170,6 +176,8 @@ jobs:
     executor:
       name: win/default
       shell: powershell.exe
+    environment:
+      GOPHERJS_EXPERIMENT: generics
     steps:
       - checkout
       - run:
@@ -204,6 +212,8 @@ jobs:
   darwin_smoke:
     macos:
       xcode: 13.4.1 # Mac OS 12.6.1, see https://circleci.com/docs/using-macos/
+    environment:
+      GOPHERJS_EXPERIMENT: generics
     steps:
       - checkout
       - setup_environment
diff --git a/compiler/internal/typeparams/utils.go b/compiler/internal/typeparams/utils.go
@@ -1,6 +1,10 @@
 package typeparams
 
-import "go/types"
+import (
+	"errors"
+	"fmt"
+	"go/types"
+)
 
 // SignatureTypeParams returns receiver type params for methods, or function
 // type params for standalone functions, or nil for non-generic functions and
@@ -14,3 +18,31 @@ func SignatureTypeParams(sig *types.Signature) *types.TypeParamList {
 		return nil
 	}
 }
+
+var (
+	errInstantiatesGenerics = errors.New("instantiates generic type or function")
+	errDefinesGenerics      = errors.New("defines generic type or function")
+)
+
+// RequiresGenericsSupport an error if the type-checked code depends on
+// generics support.
+func RequiresGenericsSupport(info *types.Info) error {
+	type withTypeParams interface{ TypeParams() *types.TypeParamList }
+
+	for ident := range info.Instances {
+		// Any instantiation means dependency on generics.
+		return fmt.Errorf("%w: %v", errInstantiatesGenerics, info.ObjectOf(ident))
+	}
+
+	for _, obj := range info.Defs {
+		if obj == nil {
+			continue
+		}
+		typ, ok := obj.Type().(withTypeParams)
+		if ok && typ.TypeParams().Len() > 0 {
+			return fmt.Errorf("%w: %v", errDefinesGenerics, obj)
+		}
+	}
+
+	return nil
+}
diff --git a/compiler/internal/typeparams/utils_test.go b/compiler/internal/typeparams/utils_test.go
@@ -0,0 +1,65 @@
+package typeparams
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/gopherjs/gopherjs/internal/srctesting"
+)
+
+func TestRequiresGenericsSupport(t *testing.T) {
+	t.Run("generic func", func(t *testing.T) {
+		f := srctesting.New(t)
+		src := `package foo
+		func foo[T any](t T) {}`
+		info, _ := f.Check("pkg/foo", f.Parse("foo.go", src))
+
+		err := RequiresGenericsSupport(info)
+		if !errors.Is(err, errDefinesGenerics) {
+			t.Errorf("Got: RequiresGenericsSupport() = %v. Want: %v", err, errDefinesGenerics)
+		}
+	})
+
+	t.Run("generic type", func(t *testing.T) {
+		f := srctesting.New(t)
+		src := `package foo
+		type Foo[T any] struct{t T}`
+		info, _ := f.Check("pkg/foo", f.Parse("foo.go", src))
+
+		err := RequiresGenericsSupport(info)
+		if !errors.Is(err, errDefinesGenerics) {
+			t.Errorf("Got: RequiresGenericsSupport() = %v. Want: %v", err, errDefinesGenerics)
+		}
+	})
+
+	t.Run("imported generic instance", func(t *testing.T) {
+		f := srctesting.New(t)
+		f.Info = nil // Do not combine type checking info from different packages.
+		src1 := `package foo
+		type Foo[T any] struct{t T}`
+		f.Check("pkg/foo", f.Parse("foo.go", src1))
+
+		src2 := `package bar
+		import "pkg/foo"
+		func bar() { _ = foo.Foo[int]{} }`
+		info, _ := f.Check("pkg/bar", f.Parse("bar.go", src2))
+
+		err := RequiresGenericsSupport(info)
+		if !errors.Is(err, errInstantiatesGenerics) {
+			t.Errorf("Got: RequiresGenericsSupport() = %v. Want: %v", err, errInstantiatesGenerics)
+		}
+	})
+
+	t.Run("no generic usage", func(t *testing.T) {
+		f := srctesting.New(t)
+		src := `package foo
+		type Foo struct{}
+		func foo() { _ = Foo{} }`
+		info, _ := f.Check("pkg/foo", f.Parse("foo.go", src))
+
+		err := RequiresGenericsSupport(info)
+		if err != nil {
+			t.Errorf("Got: RequiresGenericsSupport() = %v. Want: nil", err)
+		}
+	})
+}
diff --git a/compiler/package.go b/compiler/package.go
@@ -17,6 +17,7 @@ import (
 	"github.com/gopherjs/gopherjs/compiler/internal/symbol"
 	"github.com/gopherjs/gopherjs/compiler/internal/typeparams"
 	"github.com/gopherjs/gopherjs/compiler/typesutil"
+	"github.com/gopherjs/gopherjs/internal/experiments"
 	"github.com/neelance/astrewrite"
 	"golang.org/x/tools/go/gcexportdata"
 	"golang.org/x/tools/go/types/typeutil"
@@ -182,6 +183,9 @@ func Compile(importPath string, files []*ast.File, fileSet *token.FileSet, impor
 	if err != nil {
 		return nil, err
 	}
+	if genErr := typeparams.RequiresGenericsSupport(typesInfo); genErr != nil && !experiments.Env.Generics {
+		return nil, fmt.Errorf("package %s requires generics support (https://github.com/gopherjs/gopherjs/issues/1013): %w", importPath, genErr)
+	}
 	importContext.Packages[importPath] = typesPkg
 
 	exportData := new(bytes.Buffer)
diff --git a/internal/experiments/experiments.go b/internal/experiments/experiments.go
@@ -0,0 +1,124 @@
+// Package experiments managed the list of experimental feature flags supported
+// by GopherJS.
+//
+// GOPHERJS_EXPERIMENT environment variable can be used to control which features
+// are enabled.
+package experiments
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"reflect"
+	"strconv"
+	"strings"
+)
+
+var (
+	// ErrInvalidDest is a kind of error returned by parseFlags() when the dest
+	// argument does not meet the requirements.
+	ErrInvalidDest = errors.New("invalid flag struct")
+	// ErrInvalidFormat is a kind of error returned by parseFlags() when the raw
+	// flag string format is not valid.
+	ErrInvalidFormat = errors.New("invalid flag string format")
+)
+
+var (
+	// Env contains experiment flag values from the GOPHERJS_EXPERIMENT
+	// environment variable.
+	Env Flags
+)
+
+func init() {
+	if err := parseFlags(os.Getenv("GOPHERJS_EXPERIMENT"), &Env); err != nil {
+		panic(fmt.Errorf("failed to parse GOPHERJS_EXPERIMENT flags: %w", err))
+	}
+}
+
+// Flags contains flags for currently supported experiments.
+type Flags struct {
+	Generics bool `flag:"generics"`
+}
+
+// parseFlags parses the `raw` flags string and populates flag values in the
+// `dest`.
+//
+// `raw` is a comma-separated experiment flag list: `<flag1>,<flag2>,...`. Each
+// flag may be either `<name>` or `<name>=<value>`. Omitting value is equivalent
+// to "<name> = true". Spaces around name and value are trimmed during
+// parsing. Flag name can't be empty. If the same flag is specified multiple
+// times, the last instance takes effect.
+//
+// `dest` must be a pointer to a struct, which fields will be populated with
+// flag values. Mapping between flag names and fields is established with the
+// `flag` field tag. Fields without a flag tag will be left unpopulated.
+// If multiple fields are associated with the same flag result is unspecified.
+//
+// Flags that don't have a corresponding field are silently ignored. This is
+// done to avoid fatal errors when an experiment flag is removed from code, but
+// remains specified in user's environment.
+//
+// Currently only boolean flag values are supported, as defined by
+// `strconv.ParseBool()`.
+func parseFlags(raw string, dest any) error {
+	ptr := reflect.ValueOf(dest)
+	if ptr.Type().Kind() != reflect.Pointer || ptr.Type().Elem().Kind() != reflect.Struct {
+		return fmt.Errorf("%w: must be a pointer to a struct", ErrInvalidDest)
+	}
+	if ptr.IsNil() {
+		return fmt.Errorf("%w: must not be nil", ErrInvalidDest)
+	}
+	fields := fieldMap(ptr.Elem())
+
+	if raw == "" {
+		return nil
+	}
+	entries := strings.Split(raw, ",")
+
+	for _, entry := range entries {
+		entry = strings.TrimSpace(entry)
+		var key, val string
+		if idx := strings.IndexRune(entry, '='); idx != -1 {
+			key = strings.TrimSpace(entry[0:idx])
+			val = strings.TrimSpace(entry[idx+1:])
+		} else {
+			key = entry
+			val = "true"
+		}
+
+		if key == "" {
+			return fmt.Errorf("%w: empty flag name", ErrInvalidFormat)
+		}
+
+		field, ok := fields[key]
+		if !ok {
+			// Unknown field value, possibly an obsolete experiment, ignore it.
+			continue
+		}
+		if field.Type().Kind() != reflect.Bool {
+			return fmt.Errorf("%w: only boolean flags are supported", ErrInvalidDest)
+		}
+		b, err := strconv.ParseBool(val)
+		if err != nil {
+			return fmt.Errorf("%w: can't parse %q as boolean for flag %q", ErrInvalidFormat, val, key)
+		}
+		field.SetBool(b)
+	}
+
+	return nil
+}
+
+// fieldMap returns a map of struct fieldMap keyed by the value of the "flag" tag.
+//
+// `s` must be a struct. Fields without a "flag" tag are ignored. If multiple
+// fieldMap have the same flag, the last field wins.
+func fieldMap(s reflect.Value) map[string]reflect.Value {
+	typ := s.Type()
+	result := map[string]reflect.Value{}
+	for i := 0; i < typ.NumField(); i++ {
+		if val, ok := typ.Field(i).Tag.Lookup("flag"); ok {
+			result[val] = s.Field(i)
+		}
+	}
+	return result
+}
diff --git a/internal/experiments/experiments_test.go b/internal/experiments/experiments_test.go
diff --git a/internal/srctesting/srctesting.go b/internal/srctesting/srctesting.go
