fix(codegen): mask stale generated outputs from the loader instead of unlinking them

Root cause of the check-generate CI failures on this PR, found by running
`go generate ./...` locally: base and master pass, every commit of this
branch failed deterministically (the "different type each run" in CI was
map-iteration order picking which missing type to report first — the
failure itself was 100% reproducible).

The old upfront `syscall.Unlink` of the exec + model outputs was not
redundant — it was LOAD-BEARING for every config that autobinds the
package its models are generated into (all codegen/testserver fixtures,
the federation examples):

  1. old: unlink first → stale models file GONE at schema-load time →
     autobind finds nothing → modelgen generates all types → OK.
  2. this branch (before this commit): stale models file VISIBLE at
     load → autobind binds the previously-generated types as if they
     were user-written models → modelgen SKIPS them → the freshly
     written models file loses them → the exec build reload fails with
     "unable to find type: <pkg>.<Type>".

But the unlink is also exactly what #2345/#3505 are about: delete-then-
interrupted leaves the user with no generated file at all. Both
properties need to hold, so replace the destructive unlink with a
NON-destructive loader mask:

  - internal/code.Packages gains an Overlay (packages.Config.Overlay)
    threaded into every Load, plus MaskFile/UnmaskFile.
  - api.generate masks each existing output (exec + model) with a
    package-clause-only stub read from the file's own package clause
    (empty bytes would be a parse error and break loading the rest of
    the package). Missing/unparseable files are left alone — nothing
    stale to bind, matching the old unlink's no-op there.
  - config.Config owns the overlay map (MaskGeneratedFile) because
    LoadSchema RECREATES c.Packages mid-generation — an overlay set
    only on the first instance would silently vanish. The map is shared
    by reference with every instance the Config creates.
  - templates.write unmasks each file once its new contents are on disk
    (including the unchanged-content short-circuit path): from that
    moment disk is truth, and the exec build's reload right after
    modelgen must see the just-generated types, not the stub.

Disk state is now only ever changed by the atomic rename — kill
generation at any instant and the previous outputs are intact — while
the loader sees the same "outputs don't exist yet" world the old unlink
provided.

Verified:
  - `go generate ./...` (the exact check-generate CI command): failed
    with 22 "unable to find type" errors before, exits 0 with this
    commit, run twice back-to-back with a clean tree both times
    (regenerated output identical to committed).
  - The deterministic single-package repro (codegen/testserver/
    followschema: `rm -f resolver.go && go run testdata/gqlgen.go
    -config gqlgen.yml -stub stub.go` on a clean tree) fails without
    this commit and passes with it; models-gen.go regenerates at full
    436 lines instead of being emptied to a bare package clause.
  - api, codegen/templates, internal/code, codegen/config suites green;
    gofmt/vet/golines/gci clean.

No standalone regression test is added: a minimal self-autobind fixture
does NOT reproduce (the trigger needs the testserver fixtures' richer
interface/implementor topology), and the check-generate CI step already
runs the full corpus — it is the deterministic gate that caught this.

Author: webel-crew

api/generate.go

@@ -2,6 +2,9 @@ package api
 
 import (
 	"fmt"
+	"go/parser"
+	"go/token"
+	"os"
 	"path/filepath"
 	"regexp"
 	"strings"
@@ -26,6 +29,32 @@ var (
 	) // regex to grab the version number from a url
 )
 
+// maskGeneratedOutput hides an existing generated output file from the type
+// loader for the duration of this generation run (see the comment at the top
+// of generate). The mask is a package-clause-only stub — NOT empty bytes,
+// which would be a Go parse error and break loading the rest of the package —
+// so the package name is read from the real file's own package clause. A
+// missing/unparseable file needs no mask (there is nothing stale to bind to;
+// generation will (re)create it), matching how the old unlink was a no-op on
+// a missing file.
+func maskGeneratedOutput(cfg *config.Config, filename string) {
+	if filename == "" {
+		return
+	}
+	abs, err := filepath.Abs(filename)
+	if err != nil {
+		return
+	}
+	if _, err := os.Stat(abs); err != nil {
+		return // nothing on disk — nothing stale to mask
+	}
+	f, err := parser.ParseFile(token.NewFileSet(), abs, nil, parser.PackageClauseOnly)
+	if err != nil || f.Name == nil {
+		return // can't determine the package — leave it visible rather than corrupt the load
+	}
+	cfg.MaskGeneratedFile(abs, "package "+f.Name.Name+"\n")
+}
+
 // Generate generates GraphQL code based on the provided config.
 func Generate(cfg *config.Config, option ...Option) error {
 	return generate(cfg, nil, option...)
@@ -54,6 +83,24 @@ func generate(
 	incrementalOpts *codegen.IncrementalOptions,
 	option ...Option,
 ) error {
+	// MASK gqlgen's own previous outputs from the type loader, WITHOUT deleting
+	// them from disk. If a stale generated model file is visible while the
+	// schema loads, autobind finds the previously-generated types in it and
+	// binds them as if they were user-written models — so modelgen skips
+	// (re)generating them, the freshly-written model file comes out (near-)empty,
+	// and the exec build then fails with "unable to find type" (every testserver
+	// config that autobinds its own model package hits this). Before this
+	// change, api.Generate handled that by syscall.Unlink-ing the outputs up
+	// front — but a deleted-then-interrupted generation left the user with NO
+	// generated file at all (#2345, #3505). An overlay gives the loader the
+	// same "these files don't exist yet" view with no destructive disk write:
+	// the real files stay intact until the atomic rename replaces them, and
+	// templates.write unmasks each file once its new contents are on disk.
+	maskGeneratedOutput(cfg, cfg.Exec.Filename)
+	if cfg.Model.IsDefined() {
+		maskGeneratedOutput(cfg, cfg.Model.Filename)
+	}
+
 	plugins := []plugin.Plugin{}
 	if cfg.Model.IsDefined() {
 		plugins = append(plugins, modelgen.New())

codegen/config/config.go

@@ -78,6 +78,13 @@ type Config struct {
 	Sources          []*ast.Source  `yaml:"-"`
 	Packages         *code.Packages `yaml:"-"`
 	Schema           *ast.Schema    `yaml:"-"`
+
+	// packagesOverlay is the loader overlay shared by every Packages instance
+	// this Config creates (LoadSchema recreates c.Packages, so the overlay must
+	// outlive any single instance). Entries mask gqlgen's own stale generated
+	// outputs from autobind during a generation run — see MaskGeneratedFile and
+	// api.Generate. Keyed by absolute file path.
+	packagesOverlay map[string][]byte
 }
 
 // boolOrFalse returns the value of a *bool pointer, or false if nil.
@@ -337,12 +344,29 @@ func CompleteConfig(config *Config) error {
 	return nil
 }
 
+// MaskGeneratedFile registers a loader overlay masking absPath with the given
+// stub contents for every Packages instance this Config creates — including
+// the one LoadSchema recreates — so gqlgen's own stale outputs can be hidden
+// from autobind for the whole generation run (see api.Generate). Held on the
+// Config (not just the current Packages) because LoadSchema rebuilds
+// c.Packages, which would otherwise silently drop masks set before it.
+func (c *Config) MaskGeneratedFile(absPath, contents string) {
+	if c.packagesOverlay == nil {
+		c.packagesOverlay = map[string][]byte{}
+	}
+	c.packagesOverlay[absPath] = []byte(contents)
+	if c.Packages != nil {
+		c.Packages.MaskFile(absPath, contents)
+	}
+}
+
 func (c *Config) Init() error {
 	if c.Packages == nil {
 		c.Packages = code.NewPackages(
 			code.WithBuildTags(c.GoBuildTags...),
 			code.PackagePrefixToCache("github.com/99designs/gqlgen/graphql"),
 			code.WithPreloadNames(templatePackageNames...),
+			code.WithOverlay(c.packagesOverlay),
 		)
 	}
 
@@ -1168,6 +1192,7 @@ func (c *Config) LoadSchema() error {
 			code.WithBuildTags(c.GoBuildTags...),
 			code.PackagePrefixToCache("github.com/99designs/gqlgen/graphql"),
 			code.WithPreloadNames(templatePackageNames...),
+			code.WithOverlay(c.packagesOverlay),
 		)
 	}
 

codegen/templates/templates.go

@@ -737,6 +737,8 @@ func write(filename string, b []byte, packages *code.Packages, opts imports.Prun
 	// Skip write if content is unchanged - preserves mtime for Go build cache
 	existing, readErr := os.ReadFile(filename)
 	if readErr == nil && bytes.Equal(existing, formatted) {
+		// The on-disk file IS the current output — later loads must see it.
+		unmask(packages, filename)
 		return nil
 	}
 
@@ -806,9 +808,22 @@ func write(filename string, b []byte, packages *code.Packages, opts imports.Prun
 		cleanup()
 		return fmt.Errorf("failed to rename temp file: %w", err)
 	}
+	// The new contents are on disk — remove any loader mask api.Generate placed
+	// over this output (see maskGeneratedOutput), so later loads in this same
+	// run (e.g. the exec build reloading the model package after modelgen wrote
+	// it) see the just-generated types instead of the empty stub.
+	unmask(packages, filename)
 	return nil
 }
 
+// unmask lifts api.Generate's loader mask (maskGeneratedOutput) for a just-
+// written (or confirmed-current) output file — from here on, disk is truth.
+func unmask(packages *code.Packages, filename string) {
+	if abs, err := filepath.Abs(filename); err == nil {
+		packages.UnmaskFile(abs)
+	}
+}
+
 // renameWithRetry wraps os.Rename with a few short retries on Windows. Go's
 // os.Rename on Windows already calls MoveFileEx with MOVEFILE_REPLACE_EXISTING
 // — the same underlying API natefinch/atomic's ReplaceFile wraps — so it is

internal/code/packages.go

@@ -29,6 +29,7 @@ type (
 		loadErrors            []error
 		buildFlags            []string
 		packagesToCachePrefix string
+		overlay               map[string][]byte
 
 		numLoadCalls int // stupid test steam. ignore.
 		numNameCalls int // stupid test steam. ignore.
@@ -58,6 +59,18 @@ func PackagePrefixToCache(prefixPath string) func(p *Packages) {
 	}
 }
 
+// WithOverlay option for NewPackages supplies the packages.Config.Overlay map
+// used by every Load: files present in the map are read from it INSTEAD of
+// the file system. The map is held by REFERENCE (not copied) so a caller —
+// config.Config, which recreates its Packages instance during LoadSchema —
+// can keep one overlay alive across recreations, and MaskFile/UnmaskFile
+// mutations remain visible to whichever Packages instance currently holds it.
+func WithOverlay(overlay map[string][]byte) func(p *Packages) {
+	return func(p *Packages) {
+		p.overlay = overlay
+	}
+}
+
 // NewPackages creates a new packages cache
 // It will load all packages in the current module, and any packages that are passed to Load or
 // LoadAll
@@ -69,6 +82,35 @@ func NewPackages(opts ...Option) *Packages {
 	return p
 }
 
+// MaskFile makes every subsequent Load treat the file at absPath as if it
+// contained only the given contents (a package-clause-only stub), WITHOUT
+// touching the file on disk — a packages.Config.Overlay entry. gqlgen uses
+// this to hide its OWN previously-generated outputs (the model file) from the
+// type loader during generation: if a stale models_gen.go is visible while
+// the schema loads, autobind finds the previously-generated types in it and
+// binds them as if they were user-written models, so modelgen skips
+// (re)generating them and the freshly-written model file comes out empty —
+// the types vanish and the exec build fails with "unable to find type".
+// Historically api.Generate prevented that by DELETING the outputs up front
+// (syscall.Unlink), but that is exactly what left users with a missing
+// generated.go when generation was interrupted (#2345, #3505): masking at the
+// loader gives the same load semantics with no destructive disk write.
+func (p *Packages) MaskFile(absPath, contents string) {
+	if p.overlay == nil {
+		p.overlay = map[string][]byte{}
+	}
+	p.overlay[absPath] = []byte(contents)
+}
+
+// UnmaskFile removes a MaskFile entry so subsequent Loads read the real file
+// from disk again — called right after gqlgen atomically writes that file
+// (see codegen/templates.write): once the new contents are on disk, disk is
+// the truth and later reloads (e.g. the exec build after modelgen runs) must
+// see the just-generated types, not the mask.
+func (p *Packages) UnmaskFile(absPath string) {
+	delete(p.overlay, absPath)
+}
+
 func dedupPackages(packages []string) []string {
 	packageMap := make(map[string]struct{})
 	dedupedPackages := make([]string, 0, len(packageMap))
@@ -132,6 +174,7 @@ func (p *Packages) LoadAll(importPaths ...string) []*packages.Package {
 		pkgs, err := packages.Load(&packages.Config{
 			Mode:       mode,
 			BuildFlags: p.buildFlags,
+			Overlay:    p.overlay,
 		}, missing...)
 		if err != nil {
 			p.loadErrors = append(p.loadErrors, err)
@@ -208,6 +251,7 @@ func (p *Packages) LoadWithTypes(importPath string) *packages.Package {
 		pkgs, err := packages.Load(&packages.Config{
 			Mode:       mode,
 			BuildFlags: p.buildFlags,
+			Overlay:    p.overlay,
 		}, importPath)
 		if err != nil {
 			p.loadErrors = append(p.loadErrors, err)