Merge pull request #1414 from Workiva/newOverrideDirectives

grantnelson-wf · web-flow · commit c4be02f51115 · 2026-02-24T09:35:59.000-07:00
[go1.21] Adding `new` / `replace` optional override directives
diff --git a/build/build.go b/build/build.go
@@ -124,13 +124,26 @@ func ImportDir(dir string, mode build.ImportMode, installSuffix string, buildTag
 // overrideInfo is used by parseAndAugment methods to manage
 // directives and how the overlay and original are merged.
 type overrideInfo struct {
+	// replace indicates that the original code is expected to exist.
+	// If the original code is not present, then error to let us know
+	// the original code has been removed or renamed.
+	// This will be set to false once the original code has been found.
+	replace bool
+
+	// new indicates that the override code is expected to be new.
+	// If the original code is present, then error to let us know
+	// that we are overriding something that we did not expect to replace.
+	// This lets us know of new or renamed code in the original that happens
+	// to collide with our overrides.
+	new bool
+
 	// keepOriginal indicates that the original code should be kept
 	// but the identifier will be prefixed by `_gopherjs_original_foo`.
 	// If false the original code is removed.
 	keepOriginal bool
 
-	// purgeMethods indicates that this info is for a type and
-	// if a method has this type as a receiver should also be removed.
+	// purgeMethods indicates that this info is for a type and if a method has
+	// this type as a receiver then the method should also be removed.
 	// If the method is defined in the overlays and therefore has its
 	// own overrides, this will be ignored.
 	purgeMethods bool
@@ -165,8 +178,11 @@ type overrideInfo struct {
 //     to match the overridden function signature. This allows the receiver,
 //     type parameters, parameter, and return values to be modified as needed.
 //   - Otherwise for identifiers that exist in the original and the overrides,
-//     the original is removed.
+//     the original is removed. Use `gopherjs:replace` to ensure that the
+//     original existed so that a replace is made.
 //   - New identifiers that don't exist in original package get added.
+//     Use `gopherjs:new` to ensure that the identifier is new and there was
+//     no original code for it.
 func parseAndAugment(xctx XContext, pkg *PackageData, isTest bool, fileSet *token.FileSet) ([]*ast.File, []incjs.File, error) {
 	jsFiles, overlayFiles := parseOverlayFiles(xctx, pkg, isTest, fileSet)
 
@@ -186,8 +202,13 @@ func parseAndAugment(xctx XContext, pkg *PackageData, isTest bool, fileSet *toke
 	}
 
 	if len(overrides) > 0 {
+		found := make(map[string]struct{}, len(overrides))
 		for _, file := range originalFiles {
-			augmentOriginalFile(file, overrides)
+			augmentOriginalFile(file, overrides, found)
+		}
+		err := checkOverrides(overrides, found, pkg.ImportPath)
+		if err != nil {
+			return nil, nil, err
 		}
 	}
 
@@ -284,12 +305,17 @@ func parserOriginalFiles(pkg *PackageData, fileSet *token.FileSet) ([]*ast.File,
 func augmentOverlayFile(file *ast.File, overrides map[string]overrideInfo) {
 	anyChange := false
 	for i, decl := range file.Decls {
+		replaceDecl := astutil.DirectiveReplace(decl)
+		newDecl := astutil.DirectiveNew(decl)
 		purgeDecl := astutil.Purge(decl)
+
 		switch d := decl.(type) {
 		case *ast.FuncDecl:
 			k := astutil.FuncKey(d)
 			oi := overrideInfo{
 				keepOriginal: astutil.KeepOriginal(d),
+				replace:      replaceDecl,
+				new:          newDecl,
 			}
 			if astutil.OverrideSignature(d) {
 				oi.overrideSignature = d
@@ -299,14 +325,21 @@ func augmentOverlayFile(file *ast.File, overrides map[string]overrideInfo) {
 		case *ast.GenDecl:
 			for j, spec := range d.Specs {
 				purgeSpec := purgeDecl || astutil.Purge(spec)
+				replaceSpec := replaceDecl || astutil.DirectiveReplace(spec)
+				newSpec := newDecl || astutil.DirectiveNew(spec)
 				switch s := spec.(type) {
 				case *ast.TypeSpec:
 					overrides[s.Name.Name] = overrideInfo{
 						purgeMethods: purgeSpec,
+						replace:      replaceSpec,
+						new:          newSpec,
 					}
 				case *ast.ValueSpec:
 					for _, name := range s.Names {
-						overrides[name.Name] = overrideInfo{}
+						overrides[name.Name] = overrideInfo{
+							replace: replaceSpec,
+							new:     newSpec,
+						}
 					}
 				}
 				if purgeSpec {
@@ -346,12 +379,14 @@ func augmentOriginalImports(importPath string, file *ast.File) {
 // augmentOriginalFile is the part of parseAndAugment that processes an
 // original file AST to augment the source code using the overrides from
 // the overlay files.
-func augmentOriginalFile(file *ast.File, overrides map[string]overrideInfo) {
+func augmentOriginalFile(file *ast.File, overrides map[string]overrideInfo, found map[string]struct{}) {
 	anyChange := false
 	for i, decl := range file.Decls {
 		switch d := decl.(type) {
 		case *ast.FuncDecl:
-			if info, ok := overrides[astutil.FuncKey(d)]; ok {
+			funcKey := astutil.FuncKey(d)
+			if info, ok := overrides[funcKey]; ok {
+				found[funcKey] = struct{}{}
 				anyChange = true
 				removeFunc := true
 				if info.keepOriginal {
@@ -373,6 +408,7 @@ func augmentOriginalFile(file *ast.File, overrides map[string]overrideInfo) {
 			} else if recvKey := astutil.FuncReceiverKey(d); len(recvKey) > 0 {
 				// check if the receiver has been purged, if so, remove the method too.
 				if info, ok := overrides[recvKey]; ok && info.purgeMethods {
+					found[recvKey] = struct{}{}
 					anyChange = true
 					file.Decls[i] = nil
 				}
@@ -382,6 +418,7 @@ func augmentOriginalFile(file *ast.File, overrides map[string]overrideInfo) {
 				switch s := spec.(type) {
 				case *ast.TypeSpec:
 					if _, ok := overrides[s.Name.Name]; ok {
+						found[s.Name.Name] = struct{}{}
 						anyChange = true
 						d.Specs[j] = nil
 					}
@@ -395,6 +432,7 @@ func augmentOriginalFile(file *ast.File, overrides map[string]overrideInfo) {
 						// to be run, add the call into the overlay.
 						for k, name := range s.Names {
 							if _, ok := overrides[name.Name]; ok {
+								found[name.Name] = struct{}{}
 								anyChange = true
 								s.Names[k] = nil
 								s.Values[k] = nil
@@ -410,6 +448,7 @@ func augmentOriginalFile(file *ast.File, overrides map[string]overrideInfo) {
 						nameRemoved := false
 						for _, name := range s.Names {
 							if _, ok := overrides[name.Name]; ok {
+								found[name.Name] = struct{}{}
 								nameRemoved = true
 								name.Name = `_`
 							}
@@ -438,6 +477,29 @@ func augmentOriginalFile(file *ast.File, overrides map[string]overrideInfo) {
 	}
 }
 
+// checkOverrides performs a final check of the overrides to ensure that
+// all overrides that were expected to be found were found and all overrides
+// that were not expected to be found were not found.
+func checkOverrides(overrides map[string]overrideInfo, found map[string]struct{}, pkgPath string) error {
+	el := errlist.ErrorList{}
+	for name, info := range overrides {
+		_, wasFound := found[name]
+		switch {
+		case wasFound && info.new:
+			el = el.Append(fmt.Errorf("gopherjs: original code for %s.%s was found, but override had `new` directive", pkgPath, name))
+		case !wasFound && info.replace:
+			el = el.Append(fmt.Errorf("gopherjs: original code for %s.%s was not found, but override had `replace` directive", pkgPath, name))
+		case !wasFound && info.keepOriginal:
+			el = el.Append(fmt.Errorf("gopherjs: original code for %s.%s was not found, but override had `keep-original` directive", pkgPath, name))
+		case !wasFound && info.purgeMethods:
+			el = el.Append(fmt.Errorf("gopherjs: original code for %s.%s was not found, but override had `purge` directive", pkgPath, name))
+		case !wasFound && info.overrideSignature != nil:
+			el = el.Append(fmt.Errorf("gopherjs: original code for %s.%s was not found, but override had `override-signature` directive", pkgPath, name))
+		}
+	}
+	return el.ErrOrNil()
+}
+
 // isOnlyImports determines if this file is empty except for imports.
 func isOnlyImports(file *ast.File) bool {
 	for _, decl := range file.Decls {
diff --git a/build/build_test.go b/build/build_test.go
@@ -724,7 +724,11 @@ func TestOriginalAugmentation(t *testing.T) {
 			fileSrc := f.Parse("test.go", pkgName+test.src)
 
 			augmentOriginalImports(importPath, fileSrc)
-			augmentOriginalFile(fileSrc, test.info)
+			found := make(map[string]struct{})
+			augmentOriginalFile(fileSrc, test.info, found)
+			if err := checkOverrides(test.info, found, importPath); err != nil {
+				t.Errorf("check overrides: %v", err)
+			}
 			pruneImports(fileSrc)
 
 			got := srctesting.Format(t, f.FileSet, fileSrc)
diff --git a/compiler/astutil/astutil.go b/compiler/astutil/astutil.go
@@ -133,6 +133,28 @@ func FuncReceiverKey(d *ast.FuncDecl) string {
 	}
 }
 
+// DirectiveReplace returns true if gopherjs:replace directive is present
+// on a struct, interface, type, variable, constant, or function.
+//
+// `//gopherjs:replace` is a GopherJS-specific directive, which can be
+// applied in native overlays and will instruct the augmentation logic to
+// ensure that the original code is present and has not been removed nor renamed,
+// otherwise an error will be raised.
+func DirectiveReplace(d ast.Node) bool {
+	return hasDirective(d, `replace`)
+}
+
+// DirectiveNew returns true if gopherjs:new directive is
+// present on a struct, interface, type, variable, constant, or function.
+//
+// `//gopherjs:new` is a GopherJS-specific directive, which can be
+// applied in native overlays and will instruct the augmentation logic to
+// ensure that the original code is not present so that this code does not
+// override any original code, otherwise an error will be raised.
+func DirectiveNew(d ast.Node) bool {
+	return hasDirective(d, `new`)
+}
+
 // KeepOriginal returns true if gopherjs:keep-original directive is present
 // before a function decl.
 //
@@ -141,6 +163,9 @@ func FuncReceiverKey(d *ast.FuncDecl) string {
 // logic to expose the original function such that it can be called. For a
 // function in the original called `foo`, it will be accessible by the name
 // `_gopherjs_original_foo`.
+//
+// This will also ensure that the original function exists and hasn't been
+// removed or renamed, otherwise an error will be raised.
 func KeepOriginal(d *ast.FuncDecl) bool {
 	return hasDirective(d, `keep-original`)
 }
@@ -156,6 +181,9 @@ func KeepOriginal(d *ast.FuncDecl) bool {
 // fully supported). It should be used with caution since it may remove needed
 // dependencies. If a type is purged, all methods using that type as
 // a receiver will also be purged.
+//
+// This will also ensure that the original code exists and hasn't been
+// removed or renamed, otherwise an error will be raised.
 func Purge(d ast.Node) bool {
 	return hasDirective(d, `purge`)
 }
@@ -167,13 +195,17 @@ func Purge(d ast.Node) bool {
 // be applied in native overlays and will instruct the augmentation logic to
 // replace the original function signature which has the same FuncKey with the
 // signature defined in the native overlays.
+//
 // This directive can be used to remove generics from a function signature or
 // to replace a receiver of a function with another one. The given native
 // overlay function will be removed, so no method body is needed in the overlay.
 //
 // The new signature may not contain types which require a new import since
 // the imports will not be automatically added when needed, only removed.
 // Use a type alias in the overlay to deal manage imports.
+//
+// This will also ensure that the original code exists and hasn't been
+// removed or renamed, otherwise an error will be raised.
 func OverrideSignature(d *ast.FuncDecl) bool {
 	return hasDirective(d, `override-signature`)
 }
diff --git a/compiler/natives/src/internal/bytealg/bytealg.go b/compiler/natives/src/internal/bytealg/bytealg.go
@@ -2,6 +2,7 @@
 
 package bytealg
 
+//gopherjs:replace
 func Equal(a, b []byte) bool {
 	if len(a) != len(b) {
 		return false
@@ -14,6 +15,7 @@ func Equal(a, b []byte) bool {
 	return true
 }
 
+//gopherjs:replace
 func IndexByte(b []byte, c byte) int {
 	for i, x := range b {
 		if x == c {
@@ -23,6 +25,7 @@ func IndexByte(b []byte, c byte) int {
 	return -1
 }
 
+//gopherjs:replace
 func IndexByteString(s string, c byte) int {
 	for i := 0; i < len(s); i++ {
 		if s[i] == c {
@@ -31,3 +34,8 @@ func IndexByteString(s string, c byte) int {
 	}
 	return -1
 }
+
+//gopherjs:replace
+func MakeNoZero(n int) []byte {
+	return make([]byte, n)
+}
diff --git a/doc/pargma.md b/doc/pargma.md
