add some comments describing the new files

internal/graph/graph.go

@@ -1,5 +1,18 @@
 package graph
 
+// This graph represents the set of files that the linker operates on. Each
+// linker has a separate one of these graphs (there is one linker when code
+// splitting is on, but one linker per entry point when code splitting is off).
+//
+// The input data to the linker constructor must be considered immutable because
+// it's shared between linker invocations and is also stored in the cache for
+// incremental builds.
+//
+// The linker constructor makes a shallow clone of the input data and is careful
+// to pre-clone ahead of time the AST fields that it may modify. The Go language
+// doesn't have any type system features for immutability so this has to be
+// manually enforced. Please be careful.
+
 import (
 	"github.com/evanw/esbuild/internal/ast"
 	"github.com/evanw/esbuild/internal/helpers"

internal/graph/input.go

@@ -1,5 +1,12 @@
 package graph
 
+// The code in this file mainly represents data that passes from the scan phase
+// to the compile phase of the bundler. There is currently one exception: the
+// "meta" member of the JavaScript file representation. That could have been
+// stored separately but is stored together for convenience and to avoid an
+// extra level of indirection. Instead it's kept in a separate type to keep
+// things organized.
+
 import (
 	"github.com/evanw/esbuild/internal/ast"
 	"github.com/evanw/esbuild/internal/config"
@@ -75,8 +82,6 @@ type JSRepr struct {
 	// A JavaScript stub is automatically generated for a CSS file when it's
 	// imported from a JavaScript file.
 	CSSSourceIndex ast.Index32
-
-	DidWrapDependencies bool
 }
 
 func (repr *JSRepr) ImportRecords() *[]ast.ImportRecord {

internal/graph/meta.go

@@ -1,5 +1,8 @@
 package graph
 
+// The code in this file represents data that is required by the compile phase
+// of the bundler but that is not required by the scan phase.
+
 import (
 	"github.com/evanw/esbuild/internal/ast"
 	"github.com/evanw/esbuild/internal/js_ast"
@@ -124,8 +127,13 @@ type JSReprMeta struct {
 	// entry point files have one of these.
 	EntryPointPartIndex ast.Index32
 
+	// This is true if this file is affected by top-level await, either by having
+	// a top-level await inside this file or by having an import/export statement
+	// that transitively imports such a file. It is forbidden to call "require()"
+	// on these files since they are evaluated asynchronously.
 	IsAsyncOrHasAsyncDependency bool
-	Wrap                        WrapKind
+
+	Wrap WrapKind
 
 	// If true, the "__export(exports, { ... })" call will be force-included even
 	// if there are no parts that reference "exports". Otherwise this call will
@@ -139,6 +147,11 @@ type JSReprMeta struct {
 	// because of concurrent map hazards. Instead, it must be done later.
 	NeedsExportSymbolFromRuntime       bool
 	NeedsMarkAsModuleSymbolFromRuntime bool
+
+	// Wrapped files must also ensure that their dependencies are wrapped. This
+	// flag is used during the traversal that enforces this invariant, and is used
+	// to detect when the fixed point has been reached.
+	DidWrapDependencies bool
 }
 
 type ImportData struct {