Add staticcheck tool

2026-06-06 01:17:29 +00:00
parent 6fb63c8c90
commit ad58cd78ff
315 changed files with 56337 additions and 4 deletions
@@ -8,14 +8,15 @@ GOVET       := go vet
 GOIMPORTS   := go tool goimports
 DEADCODE    := go tool deadcode
 GOVULNCHECK := go tool govulncheck
+STATICCHECK := go tool staticcheck
 BIOME       := biome

 BUILDFLAGS := -buildvcs=true
 PLATFORMS  := linux/amd64

 .PHONY: all build build-all buildinfo check clean deadcode deps fmt help \
-        imports install lint run test tidy tools uninstall verify vet \
-	vulncheck $(CMDS)
+        imports install lint run staticcheck test tidy tools uninstall \
+	verify vet vulncheck $(CMDS)

 ## Build all binaries (default target)
 all: build
@@ -67,7 +68,7 @@ test:
 	$(GO) test -cover -race ./...

 ## Run all linters (fmt, vet, imports, deadcode, vulncheck)
-lint: fmt vet imports deadcode vulncheck biome
+lint: fmt vet imports deadcode vulncheck staticcheck biome

 ## Format code using go fmt
 fmt:
@@ -75,7 +76,8 @@ fmt:

 ## Fix imports and format using goimports
 imports:
-	$(GOIMPORTS) -w -local "$(MODULE)" .
+	find . -type f -name '*.go' -not -path './vendor/*' | \
+	xargs $(GOIMPORTS) -w -local "$(MODULE)"

 ## Run go vet
 vet:
@@ -96,6 +98,10 @@ check: lint
 tidy:
 	$(GO) mod tidy

+## Run staticcheck
+staticcheck:
+	$(STATICCHECK) ./...
+
 ## Download dependencies
 deps:
 	$(GO) mod download
@@ -109,6 +115,7 @@ tools:
 	go get -tool golang.org/x/tools/cmd/deadcode@latest
 	go get -tool golang.org/x/tools/cmd/goimports@latest
 	go get -tool golang.org/x/vuln/cmd/govulncheck@latest
+	go get -tool honnef.co/go/tools/cmd/staticcheck@latest

 ## Run the specified CMD binary (use ARGS="..." to pass arguments)
 # trap '' INT prevents colorize-logs from exiting immediately on Ctrl-C,
@@ -6,6 +6,7 @@ tool (
 	golang.org/x/tools/cmd/deadcode
 	golang.org/x/tools/cmd/goimports
 	golang.org/x/vuln/cmd/govulncheck
+	honnef.co/go/tools/cmd/staticcheck
 )

 require (
@@ -16,10 +17,13 @@ require (
 )

 require (
+	github.com/BurntSushi/toml v1.4.1-0.20240526193622-a339e1f7089c // indirect
+	golang.org/x/exp/typeparams v0.0.0-20231108232855-2478ac86f678 // indirect
 	golang.org/x/mod v0.36.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
 	golang.org/x/sys v0.44.0 // indirect
 	golang.org/x/telemetry v0.0.0-20260508192327-42602be52be6 // indirect
 	golang.org/x/tools v0.45.0 // indirect
 	golang.org/x/vuln v1.3.0 // indirect
+	honnef.co/go/tools v0.7.0 // indirect
 )
@@ -1,3 +1,5 @@
+github.com/BurntSushi/toml v1.4.1-0.20240526193622-a339e1f7089c h1:pxW6RcqyfI9/kWtOwnv/G+AzdKuy2ZrqINhenH4HyNs=
+github.com/BurntSushi/toml v1.4.1-0.20240526193622-a339e1f7089c/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
 github.com/google/go-cmdtest v0.4.1-0.20220921163831-55ab3332a786 h1:rcv+Ippz6RAtvaGgKxc+8FQIpxHgsF+HBzPyYL2cyVU=
 github.com/google/go-cmdtest v0.4.1-0.20220921163831-55ab3332a786/go.mod h1:apVn/GCasLZUVpAJ6oWAuyP7Ne7CEsQbTnc0plM3m+o=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
@@ -10,6 +12,8 @@ github.com/robfig/cron/v3 v3.0.1 h1:WdRxkvbJztn8LMz/QEvLN5sBU+xKpSqwwUO1Pjr4qDs=
 github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
 github.com/sashabaranov/go-openai v1.41.2 h1:vfPRBZNMpnqu8ELsclWcAvF19lDNgh1t6TVfFFOPiSM=
 github.com/sashabaranov/go-openai v1.41.2/go.mod h1:lj5b/K+zjTSFxVLijLSTDZuP7adOgerWeFyZLUhAKRg=
+golang.org/x/exp/typeparams v0.0.0-20231108232855-2478ac86f678 h1:1P7xPZEwZMoBoz0Yze5Nx2/4pxj6nw9ZqHWXqP0iRgQ=
+golang.org/x/exp/typeparams v0.0.0-20231108232855-2478ac86f678/go.mod h1:AbB0pIl9nAr9wVwH+Z2ZpaocVmF5I4GyWCDIsVjR0bk=
 golang.org/x/mod v0.36.0 h1:JJjpVx6myfUsUdAzZuOSTTmRE0PfZeNWzzvKrP7amb4=
 golang.org/x/mod v0.36.0/go.mod h1:moc6ELqsWcOw5Ef3xVprK5ul/MvtVvkIXLziUOICjUQ=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
@@ -30,3 +34,5 @@ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+honnef.co/go/tools v0.7.0 h1:w6WUp1VbkqPEgLz4rkBzH/CSU6HkoqNLp6GstyTx3lU=
+honnef.co/go/tools v0.7.0/go.mod h1:pm29oPxeP3P82ISxZDgIYeOaf9ta6Pi0EWvCFoLG2vc=
@@ -0,0 +1,2 @@
+/toml.test
+/toml-test
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 TOML authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
@@ -0,0 +1,120 @@
+TOML stands for Tom's Obvious, Minimal Language. This Go package provides a
+reflection interface similar to Go's standard library `json` and `xml` packages.
+
+Compatible with TOML version [v1.0.0](https://toml.io/en/v1.0.0).
+
+Documentation: https://godocs.io/github.com/BurntSushi/toml
+
+See the [releases page](https://github.com/BurntSushi/toml/releases) for a
+changelog; this information is also in the git tag annotations (e.g. `git show
+v0.4.0`).
+
+This library requires Go 1.18 or newer; add it to your go.mod with:
+
+    % go get github.com/BurntSushi/toml@latest
+
+It also comes with a TOML validator CLI tool:
+
+    % go install github.com/BurntSushi/toml/cmd/tomlv@latest
+    % tomlv some-toml-file.toml
+
+### Examples
+For the simplest example, consider some TOML file as just a list of keys and
+values:
+
+```toml
+Age = 25
+Cats = [ "Cauchy", "Plato" ]
+Pi = 3.14
+Perfection = [ 6, 28, 496, 8128 ]
+DOB = 1987-07-05T05:45:00Z
+```
+
+Which can be decoded with:
+
+```go
+type Config struct {
+	Age        int
+	Cats       []string
+	Pi         float64
+	Perfection []int
+	DOB        time.Time
+}
+
+var conf Config
+_, err := toml.Decode(tomlData, &conf)
+```
+
+You can also use struct tags if your struct field name doesn't map to a TOML key
+value directly:
+
+```toml
+some_key_NAME = "wat"
+```
+
+```go
+type TOML struct {
+    ObscureKey string `toml:"some_key_NAME"`
+}
+```
+
+Beware that like other decoders **only exported fields** are considered when
+encoding and decoding; private fields are silently ignored.
+
+### Using the `Marshaler` and `encoding.TextUnmarshaler` interfaces
+Here's an example that automatically parses values in a `mail.Address`:
+
+```toml
+contacts = [
+    "Donald Duck <donald@duckburg.com>",
+    "Scrooge McDuck <scrooge@duckburg.com>",
+]
+```
+
+Can be decoded with:
+
+```go
+// Create address type which satisfies the encoding.TextUnmarshaler interface.
+type address struct {
+	*mail.Address
+}
+
+func (a *address) UnmarshalText(text []byte) error {
+	var err error
+	a.Address, err = mail.ParseAddress(string(text))
+	return err
+}
+
+// Decode it.
+func decode() {
+	blob := `
+		contacts = [
+			"Donald Duck <donald@duckburg.com>",
+			"Scrooge McDuck <scrooge@duckburg.com>",
+		]
+	`
+
+	var contacts struct {
+		Contacts []address
+	}
+
+	_, err := toml.Decode(blob, &contacts)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	for _, c := range contacts.Contacts {
+		fmt.Printf("%#v\n", c.Address)
+	}
+
+	// Output:
+	// &mail.Address{Name:"Donald Duck", Address:"donald@duckburg.com"}
+	// &mail.Address{Name:"Scrooge McDuck", Address:"scrooge@duckburg.com"}
+}
+```
+
+To target TOML specifically you can implement `UnmarshalTOML` TOML interface in
+a similar way.
+
+### More complex usage
+See the [`_example/`](/_example) directory for a more complex example.
@@ -0,0 +1,615 @@
+package toml
+
+import (
+	"bytes"
+	"encoding"
+	"encoding/json"
+	"fmt"
+	"io"
+	"io/fs"
+	"math"
+	"os"
+	"reflect"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Unmarshaler is the interface implemented by objects that can unmarshal a
+// TOML description of themselves.
+type Unmarshaler interface {
+	UnmarshalTOML(any) error
+}
+
+// Unmarshal decodes the contents of data in TOML format into a pointer v.
+//
+// See [Decoder] for a description of the decoding process.
+func Unmarshal(data []byte, v any) error {
+	_, err := NewDecoder(bytes.NewReader(data)).Decode(v)
+	return err
+}
+
+// Decode the TOML data in to the pointer v.
+//
+// See [Decoder] for a description of the decoding process.
+func Decode(data string, v any) (MetaData, error) {
+	return NewDecoder(strings.NewReader(data)).Decode(v)
+}
+
+// DecodeFile reads the contents of a file and decodes it with [Decode].
+func DecodeFile(path string, v any) (MetaData, error) {
+	fp, err := os.Open(path)
+	if err != nil {
+		return MetaData{}, err
+	}
+	defer fp.Close()
+	return NewDecoder(fp).Decode(v)
+}
+
+// DecodeFS reads the contents of a file from [fs.FS] and decodes it with
+// [Decode].
+func DecodeFS(fsys fs.FS, path string, v any) (MetaData, error) {
+	fp, err := fsys.Open(path)
+	if err != nil {
+		return MetaData{}, err
+	}
+	defer fp.Close()
+	return NewDecoder(fp).Decode(v)
+}
+
+// Primitive is a TOML value that hasn't been decoded into a Go value.
+//
+// This type can be used for any value, which will cause decoding to be delayed.
+// You can use [PrimitiveDecode] to "manually" decode these values.
+//
+// NOTE: The underlying representation of a `Primitive` value is subject to
+// change. Do not rely on it.
+//
+// NOTE: Primitive values are still parsed, so using them will only avoid the
+// overhead of reflection. They can be useful when you don't know the exact type
+// of TOML data until runtime.
+type Primitive struct {
+	undecoded any
+	context   Key
+}
+
+// The significand precision for float32 and float64 is 24 and 53 bits; this is
+// the range a natural number can be stored in a float without loss of data.
+const (
+	maxSafeFloat32Int = 16777215                // 2^24-1
+	maxSafeFloat64Int = int64(9007199254740991) // 2^53-1
+)
+
+// Decoder decodes TOML data.
+//
+// TOML tables correspond to Go structs or maps; they can be used
+// interchangeably, but structs offer better type safety.
+//
+// TOML table arrays correspond to either a slice of structs or a slice of maps.
+//
+// TOML datetimes correspond to [time.Time]. Local datetimes are parsed in the
+// local timezone.
+//
+// [time.Duration] types are treated as nanoseconds if the TOML value is an
+// integer, or they're parsed with time.ParseDuration() if they're strings.
+//
+// All other TOML types (float, string, int, bool and array) correspond to the
+// obvious Go types.
+//
+// An exception to the above rules is if a type implements the TextUnmarshaler
+// interface, in which case any primitive TOML value (floats, strings, integers,
+// booleans, datetimes) will be converted to a []byte and given to the value's
+// UnmarshalText method. See the Unmarshaler example for a demonstration with
+// email addresses.
+//
+// # Key mapping
+//
+// TOML keys can map to either keys in a Go map or field names in a Go struct.
+// The special `toml` struct tag can be used to map TOML keys to struct fields
+// that don't match the key name exactly (see the example). A case insensitive
+// match to struct names will be tried if an exact match can't be found.
+//
+// The mapping between TOML values and Go values is loose. That is, there may
+// exist TOML values that cannot be placed into your representation, and there
+// may be parts of your representation that do not correspond to TOML values.
+// This loose mapping can be made stricter by using the IsDefined and/or
+// Undecoded methods on the MetaData returned.
+//
+// This decoder does not handle cyclic types. Decode will not terminate if a
+// cyclic type is passed.
+type Decoder struct {
+	r io.Reader
+}
+
+// NewDecoder creates a new Decoder.
+func NewDecoder(r io.Reader) *Decoder {
+	return &Decoder{r: r}
+}
+
+var (
+	unmarshalToml = reflect.TypeOf((*Unmarshaler)(nil)).Elem()
+	unmarshalText = reflect.TypeOf((*encoding.TextUnmarshaler)(nil)).Elem()
+	primitiveType = reflect.TypeOf((*Primitive)(nil)).Elem()
+)
+
+// Decode TOML data in to the pointer `v`.
+func (dec *Decoder) Decode(v any) (MetaData, error) {
+	rv := reflect.ValueOf(v)
+	if rv.Kind() != reflect.Ptr {
+		s := "%q"
+		if reflect.TypeOf(v) == nil {
+			s = "%v"
+		}
+
+		return MetaData{}, fmt.Errorf("toml: cannot decode to non-pointer "+s, reflect.TypeOf(v))
+	}
+	if rv.IsNil() {
+		return MetaData{}, fmt.Errorf("toml: cannot decode to nil value of %q", reflect.TypeOf(v))
+	}
+
+	// Check if this is a supported type: struct, map, any, or something that
+	// implements UnmarshalTOML or UnmarshalText.
+	rv = indirect(rv)
+	rt := rv.Type()
+	if rv.Kind() != reflect.Struct && rv.Kind() != reflect.Map &&
+		!(rv.Kind() == reflect.Interface && rv.NumMethod() == 0) &&
+		!rt.Implements(unmarshalToml) && !rt.Implements(unmarshalText) {
+		return MetaData{}, fmt.Errorf("toml: cannot decode to type %s", rt)
+	}
+
+	// TODO: parser should read from io.Reader? Or at the very least, make it
+	// read from []byte rather than string
+	data, err := io.ReadAll(dec.r)
+	if err != nil {
+		return MetaData{}, err
+	}
+
+	p, err := parse(string(data))
+	if err != nil {
+		return MetaData{}, err
+	}
+
+	md := MetaData{
+		mapping: p.mapping,
+		keyInfo: p.keyInfo,
+		keys:    p.ordered,
+		decoded: make(map[string]struct{}, len(p.ordered)),
+		context: nil,
+		data:    data,
+	}
+	return md, md.unify(p.mapping, rv)
+}
+
+// PrimitiveDecode is just like the other Decode* functions, except it decodes a
+// TOML value that has already been parsed. Valid primitive values can *only* be
+// obtained from values filled by the decoder functions, including this method.
+// (i.e., v may contain more [Primitive] values.)
+//
+// Meta data for primitive values is included in the meta data returned by the
+// Decode* functions with one exception: keys returned by the Undecoded method
+// will only reflect keys that were decoded. Namely, any keys hidden behind a
+// Primitive will be considered undecoded. Executing this method will update the
+// undecoded keys in the meta data. (See the example.)
+func (md *MetaData) PrimitiveDecode(primValue Primitive, v any) error {
+	md.context = primValue.context
+	defer func() { md.context = nil }()
+	return md.unify(primValue.undecoded, rvalue(v))
+}
+
+// unify performs a sort of type unification based on the structure of `rv`,
+// which is the client representation.
+//
+// Any type mismatch produces an error. Finding a type that we don't know
+// how to handle produces an unsupported type error.
+func (md *MetaData) unify(data any, rv reflect.Value) error {
+	// Special case. Look for a `Primitive` value.
+	// TODO: #76 would make this superfluous after implemented.
+	if rv.Type() == primitiveType {
+		// Save the undecoded data and the key context into the primitive
+		// value.
+		context := make(Key, len(md.context))
+		copy(context, md.context)
+		rv.Set(reflect.ValueOf(Primitive{
+			undecoded: data,
+			context:   context,
+		}))
+		return nil
+	}
+
+	rvi := rv.Interface()
+	if v, ok := rvi.(Unmarshaler); ok {
+		err := v.UnmarshalTOML(data)
+		if err != nil {
+			return md.parseErr(err)
+		}
+		return nil
+	}
+	if v, ok := rvi.(encoding.TextUnmarshaler); ok {
+		return md.unifyText(data, v)
+	}
+
+	// TODO:
+	// The behavior here is incorrect whenever a Go type satisfies the
+	// encoding.TextUnmarshaler interface but also corresponds to a TOML hash or
+	// array. In particular, the unmarshaler should only be applied to primitive
+	// TOML values. But at this point, it will be applied to all kinds of values
+	// and produce an incorrect error whenever those values are hashes or arrays
+	// (including arrays of tables).
+
+	k := rv.Kind()
+
+	if k >= reflect.Int && k <= reflect.Uint64 {
+		return md.unifyInt(data, rv)
+	}
+	switch k {
+	case reflect.Struct:
+		return md.unifyStruct(data, rv)
+	case reflect.Map:
+		return md.unifyMap(data, rv)
+	case reflect.Array:
+		return md.unifyArray(data, rv)
+	case reflect.Slice:
+		return md.unifySlice(data, rv)
+	case reflect.String:
+		return md.unifyString(data, rv)
+	case reflect.Bool:
+		return md.unifyBool(data, rv)
+	case reflect.Interface:
+		if rv.NumMethod() > 0 { /// Only empty interfaces are supported.
+			return md.e("unsupported type %s", rv.Type())
+		}
+		return md.unifyAnything(data, rv)
+	case reflect.Float32, reflect.Float64:
+		return md.unifyFloat64(data, rv)
+	}
+	return md.e("unsupported type %s", rv.Kind())
+}
+
+func (md *MetaData) unifyStruct(mapping any, rv reflect.Value) error {
+	tmap, ok := mapping.(map[string]any)
+	if !ok {
+		if mapping == nil {
+			return nil
+		}
+		return md.e("type mismatch for %s: expected table but found %s", rv.Type().String(), fmtType(mapping))
+	}
+
+	for key, datum := range tmap {
+		var f *field
+		fields := cachedTypeFields(rv.Type())
+		for i := range fields {
+			ff := &fields[i]
+			if ff.name == key {
+				f = ff
+				break
+			}
+			if f == nil && strings.EqualFold(ff.name, key) {
+				f = ff
+			}
+		}
+		if f != nil {
+			subv := rv
+			for _, i := range f.index {
+				subv = indirect(subv.Field(i))
+			}
+
+			if isUnifiable(subv) {
+				md.decoded[md.context.add(key).String()] = struct{}{}
+				md.context = append(md.context, key)
+
+				err := md.unify(datum, subv)
+				if err != nil {
+					return err
+				}
+				md.context = md.context[0 : len(md.context)-1]
+			} else if f.name != "" {
+				return md.e("cannot write unexported field %s.%s", rv.Type().String(), f.name)
+			}
+		}
+	}
+	return nil
+}
+
+func (md *MetaData) unifyMap(mapping any, rv reflect.Value) error {
+	keyType := rv.Type().Key().Kind()
+	if keyType != reflect.String && keyType != reflect.Interface {
+		return fmt.Errorf("toml: cannot decode to a map with non-string key type (%s in %q)",
+			keyType, rv.Type())
+	}
+
+	tmap, ok := mapping.(map[string]any)
+	if !ok {
+		if tmap == nil {
+			return nil
+		}
+		return md.badtype("map", mapping)
+	}
+	if rv.IsNil() {
+		rv.Set(reflect.MakeMap(rv.Type()))
+	}
+	for k, v := range tmap {
+		md.decoded[md.context.add(k).String()] = struct{}{}
+		md.context = append(md.context, k)
+
+		rvval := reflect.Indirect(reflect.New(rv.Type().Elem()))
+
+		err := md.unify(v, indirect(rvval))
+		if err != nil {
+			return err
+		}
+		md.context = md.context[0 : len(md.context)-1]
+
+		rvkey := indirect(reflect.New(rv.Type().Key()))
+
+		switch keyType {
+		case reflect.Interface:
+			rvkey.Set(reflect.ValueOf(k))
+		case reflect.String:
+			rvkey.SetString(k)
+		}
+
+		rv.SetMapIndex(rvkey, rvval)
+	}
+	return nil
+}
+
+func (md *MetaData) unifyArray(data any, rv reflect.Value) error {
+	datav := reflect.ValueOf(data)
+	if datav.Kind() != reflect.Slice {
+		if !datav.IsValid() {
+			return nil
+		}
+		return md.badtype("slice", data)
+	}
+	if l := datav.Len(); l != rv.Len() {
+		return md.e("expected array length %d; got TOML array of length %d", rv.Len(), l)
+	}
+	return md.unifySliceArray(datav, rv)
+}
+
+func (md *MetaData) unifySlice(data any, rv reflect.Value) error {
+	datav := reflect.ValueOf(data)
+	if datav.Kind() != reflect.Slice {
+		if !datav.IsValid() {
+			return nil
+		}
+		return md.badtype("slice", data)
+	}
+	n := datav.Len()
+	if rv.IsNil() || rv.Cap() < n {
+		rv.Set(reflect.MakeSlice(rv.Type(), n, n))
+	}
+	rv.SetLen(n)
+	return md.unifySliceArray(datav, rv)
+}
+
+func (md *MetaData) unifySliceArray(data, rv reflect.Value) error {
+	l := data.Len()
+	for i := 0; i < l; i++ {
+		err := md.unify(data.Index(i).Interface(), indirect(rv.Index(i)))
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (md *MetaData) unifyString(data any, rv reflect.Value) error {
+	_, ok := rv.Interface().(json.Number)
+	if ok {
+		if i, ok := data.(int64); ok {
+			rv.SetString(strconv.FormatInt(i, 10))
+		} else if f, ok := data.(float64); ok {
+			rv.SetString(strconv.FormatFloat(f, 'f', -1, 64))
+		} else {
+			return md.badtype("string", data)
+		}
+		return nil
+	}
+
+	if s, ok := data.(string); ok {
+		rv.SetString(s)
+		return nil
+	}
+	return md.badtype("string", data)
+}
+
+func (md *MetaData) unifyFloat64(data any, rv reflect.Value) error {
+	rvk := rv.Kind()
+
+	if num, ok := data.(float64); ok {
+		switch rvk {
+		case reflect.Float32:
+			if num < -math.MaxFloat32 || num > math.MaxFloat32 {
+				return md.parseErr(errParseRange{i: num, size: rvk.String()})
+			}
+			fallthrough
+		case reflect.Float64:
+			rv.SetFloat(num)
+		default:
+			panic("bug")
+		}
+		return nil
+	}
+
+	if num, ok := data.(int64); ok {
+		if (rvk == reflect.Float32 && (num < -maxSafeFloat32Int || num > maxSafeFloat32Int)) ||
+			(rvk == reflect.Float64 && (num < -maxSafeFloat64Int || num > maxSafeFloat64Int)) {
+			return md.parseErr(errUnsafeFloat{i: num, size: rvk.String()})
+		}
+		rv.SetFloat(float64(num))
+		return nil
+	}
+
+	return md.badtype("float", data)
+}
+
+func (md *MetaData) unifyInt(data any, rv reflect.Value) error {
+	_, ok := rv.Interface().(time.Duration)
+	if ok {
+		// Parse as string duration, and fall back to regular integer parsing
+		// (as nanosecond) if this is not a string.
+		if s, ok := data.(string); ok {
+			dur, err := time.ParseDuration(s)
+			if err != nil {
+				return md.parseErr(errParseDuration{s})
+			}
+			rv.SetInt(int64(dur))
+			return nil
+		}
+	}
+
+	num, ok := data.(int64)
+	if !ok {
+		return md.badtype("integer", data)
+	}
+
+	rvk := rv.Kind()
+	switch {
+	case rvk >= reflect.Int && rvk <= reflect.Int64:
+		if (rvk == reflect.Int8 && (num < math.MinInt8 || num > math.MaxInt8)) ||
+			(rvk == reflect.Int16 && (num < math.MinInt16 || num > math.MaxInt16)) ||
+			(rvk == reflect.Int32 && (num < math.MinInt32 || num > math.MaxInt32)) {
+			return md.parseErr(errParseRange{i: num, size: rvk.String()})
+		}
+		rv.SetInt(num)
+	case rvk >= reflect.Uint && rvk <= reflect.Uint64:
+		unum := uint64(num)
+		if rvk == reflect.Uint8 && (num < 0 || unum > math.MaxUint8) ||
+			rvk == reflect.Uint16 && (num < 0 || unum > math.MaxUint16) ||
+			rvk == reflect.Uint32 && (num < 0 || unum > math.MaxUint32) {
+			return md.parseErr(errParseRange{i: num, size: rvk.String()})
+		}
+		rv.SetUint(unum)
+	default:
+		panic("unreachable")
+	}
+	return nil
+}
+
+func (md *MetaData) unifyBool(data any, rv reflect.Value) error {
+	if b, ok := data.(bool); ok {
+		rv.SetBool(b)
+		return nil
+	}
+	return md.badtype("boolean", data)
+}
+
+func (md *MetaData) unifyAnything(data any, rv reflect.Value) error {
+	rv.Set(reflect.ValueOf(data))
+	return nil
+}
+
+func (md *MetaData) unifyText(data any, v encoding.TextUnmarshaler) error {
+	var s string
+	switch sdata := data.(type) {
+	case Marshaler:
+		text, err := sdata.MarshalTOML()
+		if err != nil {
+			return err
+		}
+		s = string(text)
+	case encoding.TextMarshaler:
+		text, err := sdata.MarshalText()
+		if err != nil {
+			return err
+		}
+		s = string(text)
+	case fmt.Stringer:
+		s = sdata.String()
+	case string:
+		s = sdata
+	case bool:
+		s = fmt.Sprintf("%v", sdata)
+	case int64:
+		s = fmt.Sprintf("%d", sdata)
+	case float64:
+		s = fmt.Sprintf("%f", sdata)
+	default:
+		return md.badtype("primitive (string-like)", data)
+	}
+	if err := v.UnmarshalText([]byte(s)); err != nil {
+		return md.parseErr(err)
+	}
+	return nil
+}
+
+func (md *MetaData) badtype(dst string, data any) error {
+	return md.e("incompatible types: TOML value has type %s; destination has type %s", fmtType(data), dst)
+}
+
+func (md *MetaData) parseErr(err error) error {
+	k := md.context.String()
+	d := string(md.data)
+	return ParseError{
+		Message:  err.Error(),
+		err:      err,
+		LastKey:  k,
+		Position: md.keyInfo[k].pos.withCol(d),
+		Line:     md.keyInfo[k].pos.Line,
+		input:    d,
+	}
+}
+
+func (md *MetaData) e(format string, args ...any) error {
+	f := "toml: "
+	if len(md.context) > 0 {
+		f = fmt.Sprintf("toml: (last key %q): ", md.context)
+		p := md.keyInfo[md.context.String()].pos
+		if p.Line > 0 {
+			f = fmt.Sprintf("toml: line %d (last key %q): ", p.Line, md.context)
+		}
+	}
+	return fmt.Errorf(f+format, args...)
+}
+
+// rvalue returns a reflect.Value of `v`. All pointers are resolved.
+func rvalue(v any) reflect.Value {
+	return indirect(reflect.ValueOf(v))
+}
+
+// indirect returns the value pointed to by a pointer.
+//
+// Pointers are followed until the value is not a pointer. New values are
+// allocated for each nil pointer.
+//
+// An exception to this rule is if the value satisfies an interface of interest
+// to us (like encoding.TextUnmarshaler).
+func indirect(v reflect.Value) reflect.Value {
+	if v.Kind() != reflect.Ptr {
+		if v.CanSet() {
+			pv := v.Addr()
+			pvi := pv.Interface()
+			if _, ok := pvi.(encoding.TextUnmarshaler); ok {
+				return pv
+			}
+			if _, ok := pvi.(Unmarshaler); ok {
+				return pv
+			}
+		}
+		return v
+	}
+	if v.IsNil() {
+		v.Set(reflect.New(v.Type().Elem()))
+	}
+	return indirect(reflect.Indirect(v))
+}
+
+func isUnifiable(rv reflect.Value) bool {
+	if rv.CanSet() {
+		return true
+	}
+	rvi := rv.Interface()
+	if _, ok := rvi.(encoding.TextUnmarshaler); ok {
+		return true
+	}
+	if _, ok := rvi.(Unmarshaler); ok {
+		return true
+	}
+	return false
+}
+
+// fmt %T with "interface {}" replaced with "any", which is far more readable.
+func fmtType(t any) string {
+	return strings.ReplaceAll(fmt.Sprintf("%T", t), "interface {}", "any")
+}
@@ -0,0 +1,29 @@
+package toml
+
+import (
+	"encoding"
+	"io"
+)
+
+// TextMarshaler is an alias for encoding.TextMarshaler.
+//
+// Deprecated: use encoding.TextMarshaler
+type TextMarshaler encoding.TextMarshaler
+
+// TextUnmarshaler is an alias for encoding.TextUnmarshaler.
+//
+// Deprecated: use encoding.TextUnmarshaler
+type TextUnmarshaler encoding.TextUnmarshaler
+
+// DecodeReader is an alias for NewDecoder(r).Decode(v).
+//
+// Deprecated: use NewDecoder(reader).Decode(&value).
+func DecodeReader(r io.Reader, v any) (MetaData, error) { return NewDecoder(r).Decode(v) }
+
+// PrimitiveDecode is an alias for MetaData.PrimitiveDecode().
+//
+// Deprecated: use MetaData.PrimitiveDecode.
+func PrimitiveDecode(primValue Primitive, v any) error {
+	md := MetaData{decoded: make(map[string]struct{})}
+	return md.unify(primValue.undecoded, rvalue(v))
+}
@@ -0,0 +1,8 @@
+// Package toml implements decoding and encoding of TOML files.
+//
+// This package supports TOML v1.0.0, as specified at https://toml.io
+//
+// The github.com/BurntSushi/toml/cmd/tomlv package implements a TOML validator,
+// and can be used to verify if TOML document is valid. It can also be used to
+// print the type of each key.
+package toml
@@ -0,0 +1,778 @@
+package toml
+
+import (
+	"bufio"
+	"bytes"
+	"encoding"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"reflect"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/BurntSushi/toml/internal"
+)
+
+type tomlEncodeError struct{ error }
+
+var (
+	errArrayNilElement = errors.New("toml: cannot encode array with nil element")
+	errNonString       = errors.New("toml: cannot encode a map with non-string key type")
+	errNoKey           = errors.New("toml: top-level values must be Go maps or structs")
+	errAnything        = errors.New("") // used in testing
+)
+
+var dblQuotedReplacer = strings.NewReplacer(
+	"\"", "\\\"",
+	"\\", "\\\\",
+	"\x00", `\u0000`,
+	"\x01", `\u0001`,
+	"\x02", `\u0002`,
+	"\x03", `\u0003`,
+	"\x04", `\u0004`,
+	"\x05", `\u0005`,
+	"\x06", `\u0006`,
+	"\x07", `\u0007`,
+	"\b", `\b`,
+	"\t", `\t`,
+	"\n", `\n`,
+	"\x0b", `\u000b`,
+	"\f", `\f`,
+	"\r", `\r`,
+	"\x0e", `\u000e`,
+	"\x0f", `\u000f`,
+	"\x10", `\u0010`,
+	"\x11", `\u0011`,
+	"\x12", `\u0012`,
+	"\x13", `\u0013`,
+	"\x14", `\u0014`,
+	"\x15", `\u0015`,
+	"\x16", `\u0016`,
+	"\x17", `\u0017`,
+	"\x18", `\u0018`,
+	"\x19", `\u0019`,
+	"\x1a", `\u001a`,
+	"\x1b", `\u001b`,
+	"\x1c", `\u001c`,
+	"\x1d", `\u001d`,
+	"\x1e", `\u001e`,
+	"\x1f", `\u001f`,
+	"\x7f", `\u007f`,
+)
+
+var (
+	marshalToml = reflect.TypeOf((*Marshaler)(nil)).Elem()
+	marshalText = reflect.TypeOf((*encoding.TextMarshaler)(nil)).Elem()
+	timeType    = reflect.TypeOf((*time.Time)(nil)).Elem()
+)
+
+// Marshaler is the interface implemented by types that can marshal themselves
+// into valid TOML.
+type Marshaler interface {
+	MarshalTOML() ([]byte, error)
+}
+
+// Marshal returns a TOML representation of the Go value.
+//
+// See [Encoder] for a description of the encoding process.
+func Marshal(v any) ([]byte, error) {
+	buff := new(bytes.Buffer)
+	if err := NewEncoder(buff).Encode(v); err != nil {
+		return nil, err
+	}
+	return buff.Bytes(), nil
+}
+
+// Encoder encodes a Go to a TOML document.
+//
+// The mapping between Go values and TOML values should be precisely the same as
+// for [Decode].
+//
+// time.Time is encoded as a RFC 3339 string, and time.Duration as its string
+// representation.
+//
+// The [Marshaler] and [encoding.TextMarshaler] interfaces are supported to
+// encoding the value as custom TOML.
+//
+// If you want to write arbitrary binary data then you will need to use
+// something like base64 since TOML does not have any binary types.
+//
+// When encoding TOML hashes (Go maps or structs), keys without any sub-hashes
+// are encoded first.
+//
+// Go maps will be sorted alphabetically by key for deterministic output.
+//
+// The toml struct tag can be used to provide the key name; if omitted the
+// struct field name will be used. If the "omitempty" option is present the
+// following value will be skipped:
+//
+//   - arrays, slices, maps, and string with len of 0
+//   - struct with all zero values
+//   - bool false
+//
+// If omitzero is given all int and float types with a value of 0 will be
+// skipped.
+//
+// Encoding Go values without a corresponding TOML representation will return an
+// error. Examples of this includes maps with non-string keys, slices with nil
+// elements, embedded non-struct types, and nested slices containing maps or
+// structs. (e.g. [][]map[string]string is not allowed but []map[string]string
+// is okay, as is []map[string][]string).
+//
+// NOTE: only exported keys are encoded due to the use of reflection. Unexported
+// keys are silently discarded.
+type Encoder struct {
+	Indent     string // string for a single indentation level; default is two spaces.
+	hasWritten bool   // written any output to w yet?
+	w          *bufio.Writer
+}
+
+// NewEncoder create a new Encoder.
+func NewEncoder(w io.Writer) *Encoder {
+	return &Encoder{w: bufio.NewWriter(w), Indent: "  "}
+}
+
+// Encode writes a TOML representation of the Go value to the [Encoder]'s writer.
+//
+// An error is returned if the value given cannot be encoded to a valid TOML
+// document.
+func (enc *Encoder) Encode(v any) error {
+	rv := eindirect(reflect.ValueOf(v))
+	err := enc.safeEncode(Key([]string{}), rv)
+	if err != nil {
+		return err
+	}
+	return enc.w.Flush()
+}
+
+func (enc *Encoder) safeEncode(key Key, rv reflect.Value) (err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			if terr, ok := r.(tomlEncodeError); ok {
+				err = terr.error
+				return
+			}
+			panic(r)
+		}
+	}()
+	enc.encode(key, rv)
+	return nil
+}
+
+func (enc *Encoder) encode(key Key, rv reflect.Value) {
+	// If we can marshal the type to text, then we use that. This prevents the
+	// encoder for handling these types as generic structs (or whatever the
+	// underlying type of a TextMarshaler is).
+	switch {
+	case isMarshaler(rv):
+		enc.writeKeyValue(key, rv, false)
+		return
+	case rv.Type() == primitiveType: // TODO: #76 would make this superfluous after implemented.
+		enc.encode(key, reflect.ValueOf(rv.Interface().(Primitive).undecoded))
+		return
+	}
+
+	k := rv.Kind()
+	switch k {
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32,
+		reflect.Int64,
+		reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32,
+		reflect.Uint64,
+		reflect.Float32, reflect.Float64, reflect.String, reflect.Bool:
+		enc.writeKeyValue(key, rv, false)
+	case reflect.Array, reflect.Slice:
+		if typeEqual(tomlArrayHash, tomlTypeOfGo(rv)) {
+			enc.eArrayOfTables(key, rv)
+		} else {
+			enc.writeKeyValue(key, rv, false)
+		}
+	case reflect.Interface:
+		if rv.IsNil() {
+			return
+		}
+		enc.encode(key, rv.Elem())
+	case reflect.Map:
+		if rv.IsNil() {
+			return
+		}
+		enc.eTable(key, rv)
+	case reflect.Ptr:
+		if rv.IsNil() {
+			return
+		}
+		enc.encode(key, rv.Elem())
+	case reflect.Struct:
+		enc.eTable(key, rv)
+	default:
+		encPanic(fmt.Errorf("unsupported type for key '%s': %s", key, k))
+	}
+}
+
+// eElement encodes any value that can be an array element.
+func (enc *Encoder) eElement(rv reflect.Value) {
+	switch v := rv.Interface().(type) {
+	case time.Time: // Using TextMarshaler adds extra quotes, which we don't want.
+		format := time.RFC3339Nano
+		switch v.Location() {
+		case internal.LocalDatetime:
+			format = "2006-01-02T15:04:05.999999999"
+		case internal.LocalDate:
+			format = "2006-01-02"
+		case internal.LocalTime:
+			format = "15:04:05.999999999"
+		}
+		switch v.Location() {
+		default:
+			enc.wf(v.Format(format))
+		case internal.LocalDatetime, internal.LocalDate, internal.LocalTime:
+			enc.wf(v.In(time.UTC).Format(format))
+		}
+		return
+	case Marshaler:
+		s, err := v.MarshalTOML()
+		if err != nil {
+			encPanic(err)
+		}
+		if s == nil {
+			encPanic(errors.New("MarshalTOML returned nil and no error"))
+		}
+		enc.w.Write(s)
+		return
+	case encoding.TextMarshaler:
+		s, err := v.MarshalText()
+		if err != nil {
+			encPanic(err)
+		}
+		if s == nil {
+			encPanic(errors.New("MarshalText returned nil and no error"))
+		}
+		enc.writeQuoted(string(s))
+		return
+	case time.Duration:
+		enc.writeQuoted(v.String())
+		return
+	case json.Number:
+		n, _ := rv.Interface().(json.Number)
+
+		if n == "" { /// Useful zero value.
+			enc.w.WriteByte('0')
+			return
+		} else if v, err := n.Int64(); err == nil {
+			enc.eElement(reflect.ValueOf(v))
+			return
+		} else if v, err := n.Float64(); err == nil {
+			enc.eElement(reflect.ValueOf(v))
+			return
+		}
+		encPanic(fmt.Errorf("unable to convert %q to int64 or float64", n))
+	}
+
+	switch rv.Kind() {
+	case reflect.Ptr:
+		enc.eElement(rv.Elem())
+		return
+	case reflect.String:
+		enc.writeQuoted(rv.String())
+	case reflect.Bool:
+		enc.wf(strconv.FormatBool(rv.Bool()))
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		enc.wf(strconv.FormatInt(rv.Int(), 10))
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		enc.wf(strconv.FormatUint(rv.Uint(), 10))
+	case reflect.Float32:
+		f := rv.Float()
+		if math.IsNaN(f) {
+			if math.Signbit(f) {
+				enc.wf("-")
+			}
+			enc.wf("nan")
+		} else if math.IsInf(f, 0) {
+			if math.Signbit(f) {
+				enc.wf("-")
+			}
+			enc.wf("inf")
+		} else {
+			enc.wf(floatAddDecimal(strconv.FormatFloat(f, 'f', -1, 32)))
+		}
+	case reflect.Float64:
+		f := rv.Float()
+		if math.IsNaN(f) {
+			if math.Signbit(f) {
+				enc.wf("-")
+			}
+			enc.wf("nan")
+		} else if math.IsInf(f, 0) {
+			if math.Signbit(f) {
+				enc.wf("-")
+			}
+			enc.wf("inf")
+		} else {
+			enc.wf(floatAddDecimal(strconv.FormatFloat(f, 'f', -1, 64)))
+		}
+	case reflect.Array, reflect.Slice:
+		enc.eArrayOrSliceElement(rv)
+	case reflect.Struct:
+		enc.eStruct(nil, rv, true)
+	case reflect.Map:
+		enc.eMap(nil, rv, true)
+	case reflect.Interface:
+		enc.eElement(rv.Elem())
+	default:
+		encPanic(fmt.Errorf("unexpected type: %s", fmtType(rv.Interface())))
+	}
+}
+
+// By the TOML spec, all floats must have a decimal with at least one number on
+// either side.
+func floatAddDecimal(fstr string) string {
+	if !strings.Contains(fstr, ".") {
+		return fstr + ".0"
+	}
+	return fstr
+}
+
+func (enc *Encoder) writeQuoted(s string) {
+	enc.wf("\"%s\"", dblQuotedReplacer.Replace(s))
+}
+
+func (enc *Encoder) eArrayOrSliceElement(rv reflect.Value) {
+	length := rv.Len()
+	enc.wf("[")
+	for i := 0; i < length; i++ {
+		elem := eindirect(rv.Index(i))
+		enc.eElement(elem)
+		if i != length-1 {
+			enc.wf(", ")
+		}
+	}
+	enc.wf("]")
+}
+
+func (enc *Encoder) eArrayOfTables(key Key, rv reflect.Value) {
+	if len(key) == 0 {
+		encPanic(errNoKey)
+	}
+	for i := 0; i < rv.Len(); i++ {
+		trv := eindirect(rv.Index(i))
+		if isNil(trv) {
+			continue
+		}
+		enc.newline()
+		enc.wf("%s[[%s]]", enc.indentStr(key), key)
+		enc.newline()
+		enc.eMapOrStruct(key, trv, false)
+	}
+}
+
+func (enc *Encoder) eTable(key Key, rv reflect.Value) {
+	if len(key) == 1 {
+		// Output an extra newline between top-level tables.
+		// (The newline isn't written if nothing else has been written though.)
+		enc.newline()
+	}
+	if len(key) > 0 {
+		enc.wf("%s[%s]", enc.indentStr(key), key)
+		enc.newline()
+	}
+	enc.eMapOrStruct(key, rv, false)
+}
+
+func (enc *Encoder) eMapOrStruct(key Key, rv reflect.Value, inline bool) {
+	switch rv.Kind() {
+	case reflect.Map:
+		enc.eMap(key, rv, inline)
+	case reflect.Struct:
+		enc.eStruct(key, rv, inline)
+	default:
+		// Should never happen?
+		panic("eTable: unhandled reflect.Value Kind: " + rv.Kind().String())
+	}
+}
+
+func (enc *Encoder) eMap(key Key, rv reflect.Value, inline bool) {
+	rt := rv.Type()
+	if rt.Key().Kind() != reflect.String {
+		encPanic(errNonString)
+	}
+
+	// Sort keys so that we have deterministic output. And write keys directly
+	// underneath this key first, before writing sub-structs or sub-maps.
+	var mapKeysDirect, mapKeysSub []string
+	for _, mapKey := range rv.MapKeys() {
+		k := mapKey.String()
+		if typeIsTable(tomlTypeOfGo(eindirect(rv.MapIndex(mapKey)))) {
+			mapKeysSub = append(mapKeysSub, k)
+		} else {
+			mapKeysDirect = append(mapKeysDirect, k)
+		}
+	}
+
+	var writeMapKeys = func(mapKeys []string, trailC bool) {
+		sort.Strings(mapKeys)
+		for i, mapKey := range mapKeys {
+			val := eindirect(rv.MapIndex(reflect.ValueOf(mapKey)))
+			if isNil(val) {
+				continue
+			}
+
+			if inline {
+				enc.writeKeyValue(Key{mapKey}, val, true)
+				if trailC || i != len(mapKeys)-1 {
+					enc.wf(", ")
+				}
+			} else {
+				enc.encode(key.add(mapKey), val)
+			}
+		}
+	}
+
+	if inline {
+		enc.wf("{")
+	}
+	writeMapKeys(mapKeysDirect, len(mapKeysSub) > 0)
+	writeMapKeys(mapKeysSub, false)
+	if inline {
+		enc.wf("}")
+	}
+}
+
+const is32Bit = (32 << (^uint(0) >> 63)) == 32
+
+func pointerTo(t reflect.Type) reflect.Type {
+	if t.Kind() == reflect.Ptr {
+		return pointerTo(t.Elem())
+	}
+	return t
+}
+
+func (enc *Encoder) eStruct(key Key, rv reflect.Value, inline bool) {
+	// Write keys for fields directly under this key first, because if we write
+	// a field that creates a new table then all keys under it will be in that
+	// table (not the one we're writing here).
+	//
+	// Fields is a [][]int: for fieldsDirect this always has one entry (the
+	// struct index). For fieldsSub it contains two entries: the parent field
+	// index from tv, and the field indexes for the fields of the sub.
+	var (
+		rt                      = rv.Type()
+		fieldsDirect, fieldsSub [][]int
+		addFields               func(rt reflect.Type, rv reflect.Value, start []int)
+	)
+	addFields = func(rt reflect.Type, rv reflect.Value, start []int) {
+		for i := 0; i < rt.NumField(); i++ {
+			f := rt.Field(i)
+			isEmbed := f.Anonymous && pointerTo(f.Type).Kind() == reflect.Struct
+			if f.PkgPath != "" && !isEmbed { /// Skip unexported fields.
+				continue
+			}
+			opts := getOptions(f.Tag)
+			if opts.skip {
+				continue
+			}
+
+			frv := eindirect(rv.Field(i))
+
+			if is32Bit {
+				// Copy so it works correct on 32bit archs; not clear why this
+				// is needed. See #314, and https://www.reddit.com/r/golang/comments/pnx8v4
+				// This also works fine on 64bit, but 32bit archs are somewhat
+				// rare and this is a wee bit faster.
+				copyStart := make([]int, len(start))
+				copy(copyStart, start)
+				start = copyStart
+			}
+
+			// Treat anonymous struct fields with tag names as though they are
+			// not anonymous, like encoding/json does.
+			//
+			// Non-struct anonymous fields use the normal encoding logic.
+			if isEmbed {
+				if getOptions(f.Tag).name == "" && frv.Kind() == reflect.Struct {
+					addFields(frv.Type(), frv, append(start, f.Index...))
+					continue
+				}
+			}
+
+			if typeIsTable(tomlTypeOfGo(frv)) {
+				fieldsSub = append(fieldsSub, append(start, f.Index...))
+			} else {
+				fieldsDirect = append(fieldsDirect, append(start, f.Index...))
+			}
+		}
+	}
+	addFields(rt, rv, nil)
+
+	writeFields := func(fields [][]int) {
+		for _, fieldIndex := range fields {
+			fieldType := rt.FieldByIndex(fieldIndex)
+			fieldVal := rv.FieldByIndex(fieldIndex)
+
+			opts := getOptions(fieldType.Tag)
+			if opts.skip {
+				continue
+			}
+			if opts.omitempty && isEmpty(fieldVal) {
+				continue
+			}
+
+			fieldVal = eindirect(fieldVal)
+
+			if isNil(fieldVal) { /// Don't write anything for nil fields.
+				continue
+			}
+
+			keyName := fieldType.Name
+			if opts.name != "" {
+				keyName = opts.name
+			}
+
+			if opts.omitzero && isZero(fieldVal) {
+				continue
+			}
+
+			if inline {
+				enc.writeKeyValue(Key{keyName}, fieldVal, true)
+				if fieldIndex[0] != len(fields)-1 {
+					enc.wf(", ")
+				}
+			} else {
+				enc.encode(key.add(keyName), fieldVal)
+			}
+		}
+	}
+
+	if inline {
+		enc.wf("{")
+	}
+	writeFields(fieldsDirect)
+	writeFields(fieldsSub)
+	if inline {
+		enc.wf("}")
+	}
+}
+
+// tomlTypeOfGo returns the TOML type name of the Go value's type.
+//
+// It is used to determine whether the types of array elements are mixed (which
+// is forbidden). If the Go value is nil, then it is illegal for it to be an
+// array element, and valueIsNil is returned as true.
+//
+// The type may be `nil`, which means no concrete TOML type could be found.
+func tomlTypeOfGo(rv reflect.Value) tomlType {
+	if isNil(rv) || !rv.IsValid() {
+		return nil
+	}
+
+	if rv.Kind() == reflect.Struct {
+		if rv.Type() == timeType {
+			return tomlDatetime
+		}
+		if isMarshaler(rv) {
+			return tomlString
+		}
+		return tomlHash
+	}
+
+	if isMarshaler(rv) {
+		return tomlString
+	}
+
+	switch rv.Kind() {
+	case reflect.Bool:
+		return tomlBool
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32,
+		reflect.Int64,
+		reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32,
+		reflect.Uint64:
+		return tomlInteger
+	case reflect.Float32, reflect.Float64:
+		return tomlFloat
+	case reflect.Array, reflect.Slice:
+		if isTableArray(rv) {
+			return tomlArrayHash
+		}
+		return tomlArray
+	case reflect.Ptr, reflect.Interface:
+		return tomlTypeOfGo(rv.Elem())
+	case reflect.String:
+		return tomlString
+	case reflect.Map:
+		return tomlHash
+	default:
+		encPanic(errors.New("unsupported type: " + rv.Kind().String()))
+		panic("unreachable")
+	}
+}
+
+func isMarshaler(rv reflect.Value) bool {
+	return rv.Type().Implements(marshalText) || rv.Type().Implements(marshalToml)
+}
+
+// isTableArray reports if all entries in the array or slice are a table.
+func isTableArray(arr reflect.Value) bool {
+	if isNil(arr) || !arr.IsValid() || arr.Len() == 0 {
+		return false
+	}
+
+	ret := true
+	for i := 0; i < arr.Len(); i++ {
+		tt := tomlTypeOfGo(eindirect(arr.Index(i)))
+		// Don't allow nil.
+		if tt == nil {
+			encPanic(errArrayNilElement)
+		}
+
+		if ret && !typeEqual(tomlHash, tt) {
+			ret = false
+		}
+	}
+	return ret
+}
+
+type tagOptions struct {
+	skip      bool // "-"
+	name      string
+	omitempty bool
+	omitzero  bool
+}
+
+func getOptions(tag reflect.StructTag) tagOptions {
+	t := tag.Get("toml")
+	if t == "-" {
+		return tagOptions{skip: true}
+	}
+	var opts tagOptions
+	parts := strings.Split(t, ",")
+	opts.name = parts[0]
+	for _, s := range parts[1:] {
+		switch s {
+		case "omitempty":
+			opts.omitempty = true
+		case "omitzero":
+			opts.omitzero = true
+		}
+	}
+	return opts
+}
+
+func isZero(rv reflect.Value) bool {
+	switch rv.Kind() {
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return rv.Int() == 0
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		return rv.Uint() == 0
+	case reflect.Float32, reflect.Float64:
+		return rv.Float() == 0.0
+	}
+	return false
+}
+
+func isEmpty(rv reflect.Value) bool {
+	switch rv.Kind() {
+	case reflect.Array, reflect.Slice, reflect.Map, reflect.String:
+		return rv.Len() == 0
+	case reflect.Struct:
+		if rv.Type().Comparable() {
+			return reflect.Zero(rv.Type()).Interface() == rv.Interface()
+		}
+		// Need to also check if all the fields are empty, otherwise something
+		// like this with uncomparable types will always return true:
+		//
+		//   type a struct{ field b }
+		//   type b struct{ s []string }
+		//   s := a{field: b{s: []string{"AAA"}}}
+		for i := 0; i < rv.NumField(); i++ {
+			if !isEmpty(rv.Field(i)) {
+				return false
+			}
+		}
+		return true
+	case reflect.Bool:
+		return !rv.Bool()
+	case reflect.Ptr:
+		return rv.IsNil()
+	}
+	return false
+}
+
+func (enc *Encoder) newline() {
+	if enc.hasWritten {
+		enc.wf("\n")
+	}
+}
+
+// Write a key/value pair:
+//
+//	key = <any value>
+//
+// This is also used for "k = v" in inline tables; so something like this will
+// be written in three calls:
+//
+//	┌───────────────────┐
+//	│      ┌───┐  ┌────┐│
+//	v      v   v  v    vv
+//	key = {k = 1, k2 = 2}
+func (enc *Encoder) writeKeyValue(key Key, val reflect.Value, inline bool) {
+	/// Marshaler used on top-level document; call eElement() to just call
+	/// Marshal{TOML,Text}.
+	if len(key) == 0 {
+		enc.eElement(val)
+		return
+	}
+	enc.wf("%s%s = ", enc.indentStr(key), key.maybeQuoted(len(key)-1))
+	enc.eElement(val)
+	if !inline {
+		enc.newline()
+	}
+}
+
+func (enc *Encoder) wf(format string, v ...any) {
+	_, err := fmt.Fprintf(enc.w, format, v...)
+	if err != nil {
+		encPanic(err)
+	}
+	enc.hasWritten = true
+}
+
+func (enc *Encoder) indentStr(key Key) string {
+	return strings.Repeat(enc.Indent, len(key)-1)
+}
+
+func encPanic(err error) {
+	panic(tomlEncodeError{err})
+}
+
+// Resolve any level of pointers to the actual value (e.g. **string → string).
+func eindirect(v reflect.Value) reflect.Value {
+	if v.Kind() != reflect.Ptr && v.Kind() != reflect.Interface {
+		if isMarshaler(v) {
+			return v
+		}
+		if v.CanAddr() { /// Special case for marshalers; see #358.
+			if pv := v.Addr(); isMarshaler(pv) {
+				return pv
+			}
+		}
+		return v
+	}
+
+	if v.IsNil() {
+		return v
+	}
+
+	return eindirect(v.Elem())
+}
+
+func isNil(rv reflect.Value) bool {
+	switch rv.Kind() {
+	case reflect.Interface, reflect.Map, reflect.Ptr, reflect.Slice:
+		return rv.IsNil()
+	default:
+		return false
+	}
+}
@@ -0,0 +1,347 @@
+package toml
+
+import (
+	"fmt"
+	"strings"
+)
+
+// ParseError is returned when there is an error parsing the TOML syntax such as
+// invalid syntax, duplicate keys, etc.
+//
+// In addition to the error message itself, you can also print detailed location
+// information with context by using [ErrorWithPosition]:
+//
+//	toml: error: Key 'fruit' was already created and cannot be used as an array.
+//
+//	At line 4, column 2-7:
+//
+//	      2 | fruit = []
+//	      3 |
+//	      4 | [[fruit]] # Not allowed
+//	            ^^^^^
+//
+// [ErrorWithUsage] can be used to print the above with some more detailed usage
+// guidance:
+//
+//	toml: error: newlines not allowed within inline tables
+//
+//	At line 1, column 18:
+//
+//	      1 | x = [{ key = 42 #
+//	                           ^
+//
+//	Error help:
+//
+//	  Inline tables must always be on a single line:
+//
+//	      table = {key = 42, second = 43}
+//
+//	  It is invalid to split them over multiple lines like so:
+//
+//	      # INVALID
+//	      table = {
+//	          key    = 42,
+//	          second = 43
+//	      }
+//
+//	  Use regular for this:
+//
+//	      [table]
+//	      key    = 42
+//	      second = 43
+type ParseError struct {
+	Message  string   // Short technical message.
+	Usage    string   // Longer message with usage guidance; may be blank.
+	Position Position // Position of the error
+	LastKey  string   // Last parsed key, may be blank.
+
+	// Line the error occurred.
+	//
+	// Deprecated: use [Position].
+	Line int
+
+	err   error
+	input string
+}
+
+// Position of an error.
+type Position struct {
+	Line  int // Line number, starting at 1.
+	Col   int // Error column, starting at 1.
+	Start int // Start of error, as byte offset starting at 0.
+	Len   int // Lenght of the error in bytes.
+}
+
+func (p Position) withCol(tomlFile string) Position {
+	var (
+		pos   int
+		lines = strings.Split(tomlFile, "\n")
+	)
+	for i := range lines {
+		ll := len(lines[i]) + 1 // +1 for the removed newline
+		if pos+ll >= p.Start {
+			p.Col = p.Start - pos + 1
+			if p.Col < 1 { // Should never happen, but just in case.
+				p.Col = 1
+			}
+			break
+		}
+		pos += ll
+	}
+	return p
+}
+
+func (pe ParseError) Error() string {
+	if pe.LastKey == "" {
+		return fmt.Sprintf("toml: line %d: %s", pe.Position.Line, pe.Message)
+	}
+	return fmt.Sprintf("toml: line %d (last key %q): %s",
+		pe.Position.Line, pe.LastKey, pe.Message)
+}
+
+// ErrorWithPosition returns the error with detailed location context.
+//
+// See the documentation on [ParseError].
+func (pe ParseError) ErrorWithPosition() string {
+	if pe.input == "" { // Should never happen, but just in case.
+		return pe.Error()
+	}
+
+	// TODO: don't show control characters as literals? This may not show up
+	// well everywhere.
+
+	var (
+		lines = strings.Split(pe.input, "\n")
+		b     = new(strings.Builder)
+	)
+	if pe.Position.Len == 1 {
+		fmt.Fprintf(b, "toml: error: %s\n\nAt line %d, column %d:\n\n",
+			pe.Message, pe.Position.Line, pe.Position.Col)
+	} else {
+		fmt.Fprintf(b, "toml: error: %s\n\nAt line %d, column %d-%d:\n\n",
+			pe.Message, pe.Position.Line, pe.Position.Col, pe.Position.Col+pe.Position.Len-1)
+	}
+	if pe.Position.Line > 2 {
+		fmt.Fprintf(b, "% 7d | %s\n", pe.Position.Line-2, expandTab(lines[pe.Position.Line-3]))
+	}
+	if pe.Position.Line > 1 {
+		fmt.Fprintf(b, "% 7d | %s\n", pe.Position.Line-1, expandTab(lines[pe.Position.Line-2]))
+	}
+
+	/// Expand tabs, so that the ^^^s are at the correct position, but leave
+	/// "column 10-13" intact. Adjusting this to the visual column would be
+	/// better, but we don't know the tabsize of the user in their editor, which
+	/// can be 8, 4, 2, or something else. We can't know. So leaving it as the
+	/// character index is probably the "most correct".
+	expanded := expandTab(lines[pe.Position.Line-1])
+	diff := len(expanded) - len(lines[pe.Position.Line-1])
+
+	fmt.Fprintf(b, "% 7d | %s\n", pe.Position.Line, expanded)
+	fmt.Fprintf(b, "% 10s%s%s\n", "", strings.Repeat(" ", pe.Position.Col-1+diff), strings.Repeat("^", pe.Position.Len))
+	return b.String()
+}
+
+// ErrorWithUsage returns the error with detailed location context and usage
+// guidance.
+//
+// See the documentation on [ParseError].
+func (pe ParseError) ErrorWithUsage() string {
+	m := pe.ErrorWithPosition()
+	if u, ok := pe.err.(interface{ Usage() string }); ok && u.Usage() != "" {
+		lines := strings.Split(strings.TrimSpace(u.Usage()), "\n")
+		for i := range lines {
+			if lines[i] != "" {
+				lines[i] = "    " + lines[i]
+			}
+		}
+		return m + "Error help:\n\n" + strings.Join(lines, "\n") + "\n"
+	}
+	return m
+}
+
+func expandTab(s string) string {
+	var (
+		b    strings.Builder
+		l    int
+		fill = func(n int) string {
+			b := make([]byte, n)
+			for i := range b {
+				b[i] = ' '
+			}
+			return string(b)
+		}
+	)
+	b.Grow(len(s))
+	for _, r := range s {
+		switch r {
+		case '\t':
+			tw := 8 - l%8
+			b.WriteString(fill(tw))
+			l += tw
+		default:
+			b.WriteRune(r)
+			l += 1
+		}
+	}
+	return b.String()
+}
+
+type (
+	errLexControl       struct{ r rune }
+	errLexEscape        struct{ r rune }
+	errLexUTF8          struct{ b byte }
+	errParseDate        struct{ v string }
+	errLexInlineTableNL struct{}
+	errLexStringNL      struct{}
+	errParseRange       struct {
+		i    any    // int or float
+		size string // "int64", "uint16", etc.
+	}
+	errUnsafeFloat struct {
+		i    interface{} // float32 or float64
+		size string      // "float32" or "float64"
+	}
+	errParseDuration struct{ d string }
+)
+
+func (e errLexControl) Error() string {
+	return fmt.Sprintf("TOML files cannot contain control characters: '0x%02x'", e.r)
+}
+func (e errLexControl) Usage() string { return "" }
+
+func (e errLexEscape) Error() string        { return fmt.Sprintf(`invalid escape in string '\%c'`, e.r) }
+func (e errLexEscape) Usage() string        { return usageEscape }
+func (e errLexUTF8) Error() string          { return fmt.Sprintf("invalid UTF-8 byte: 0x%02x", e.b) }
+func (e errLexUTF8) Usage() string          { return "" }
+func (e errParseDate) Error() string        { return fmt.Sprintf("invalid datetime: %q", e.v) }
+func (e errParseDate) Usage() string        { return usageDate }
+func (e errLexInlineTableNL) Error() string { return "newlines not allowed within inline tables" }
+func (e errLexInlineTableNL) Usage() string { return usageInlineNewline }
+func (e errLexStringNL) Error() string      { return "strings cannot contain newlines" }
+func (e errLexStringNL) Usage() string      { return usageStringNewline }
+func (e errParseRange) Error() string       { return fmt.Sprintf("%v is out of range for %s", e.i, e.size) }
+func (e errParseRange) Usage() string       { return usageIntOverflow }
+func (e errUnsafeFloat) Error() string {
+	return fmt.Sprintf("%v is out of the safe %s range", e.i, e.size)
+}
+func (e errUnsafeFloat) Usage() string   { return usageUnsafeFloat }
+func (e errParseDuration) Error() string { return fmt.Sprintf("invalid duration: %q", e.d) }
+func (e errParseDuration) Usage() string { return usageDuration }
+
+const usageEscape = `
+A '\' inside a "-delimited string is interpreted as an escape character.
+
+The following escape sequences are supported:
+\b, \t, \n, \f, \r, \", \\, \uXXXX, and \UXXXXXXXX
+
+To prevent a '\' from being recognized as an escape character, use either:
+
+- a ' or '''-delimited string; escape characters aren't processed in them; or
+- write two backslashes to get a single backslash: '\\'.
+
+If you're trying to add a Windows path (e.g. "C:\Users\martin") then using '/'
+instead of '\' will usually also work: "C:/Users/martin".
+`
+
+const usageInlineNewline = `
+Inline tables must always be on a single line:
+
+    table = {key = 42, second = 43}
+
+It is invalid to split them over multiple lines like so:
+
+    # INVALID
+    table = {
+        key    = 42,
+        second = 43
+    }
+
+Use regular for this:
+
+    [table]
+    key    = 42
+    second = 43
+`
+
+const usageStringNewline = `
+Strings must always be on a single line, and cannot span more than one line:
+
+    # INVALID
+    string = "Hello,
+    world!"
+
+Instead use """ or ''' to split strings over multiple lines:
+
+    string = """Hello,
+    world!"""
+`
+
+const usageIntOverflow = `
+This number is too large; this may be an error in the TOML, but it can also be a
+bug in the program that uses too small of an integer.
+
+The maximum and minimum values are:
+
+    size   │ lowest         │ highest
+    ───────┼────────────────┼──────────────
+    int8   │ -128           │ 127
+    int16  │ -32,768        │ 32,767
+    int32  │ -2,147,483,648 │ 2,147,483,647
+    int64  │ -9.2 × 10¹⁷    │ 9.2 × 10¹⁷
+    uint8  │ 0              │ 255
+    uint16 │ 0              │ 65,535
+    uint32 │ 0              │ 4,294,967,295
+    uint64 │ 0              │ 1.8 × 10¹⁸
+
+int refers to int32 on 32-bit systems and int64 on 64-bit systems.
+`
+
+const usageUnsafeFloat = `
+This number is outside of the "safe" range for floating point numbers; whole
+(non-fractional) numbers outside the below range can not always be represented
+accurately in a float, leading to some loss of accuracy.
+
+Explicitly mark a number as a fractional unit by adding ".0", which will incur
+some loss of accuracy; for example:
+
+	f = 2_000_000_000.0
+
+Accuracy ranges:
+
+	float32 =            16,777,215
+	float64 = 9,007,199,254,740,991
+`
+
+const usageDuration = `
+A duration must be as "number<unit>", without any spaces. Valid units are:
+
+    ns         nanoseconds (billionth of a second)
+    us, µs     microseconds (millionth of a second)
+    ms         milliseconds (thousands of a second)
+    s          seconds
+    m          minutes
+    h          hours
+
+You can combine multiple units; for example "5m10s" for 5 minutes and 10
+seconds.
+`
+
+const usageDate = `
+A TOML datetime must be in one of the following formats:
+
+    2006-01-02T15:04:05Z07:00   Date and time, with timezone.
+    2006-01-02T15:04:05         Date and time, but without timezone.
+    2006-01-02                  Date without a time or timezone.
+    15:04:05                    Just a time, without any timezone.
+
+Seconds may optionally have a fraction, up to nanosecond precision:
+
+    15:04:05.123
+    15:04:05.856018510
+`
+
+// TOML 1.1:
+// The seconds part in times is optional, and may be omitted:
+//     2006-01-02T15:04Z07:00
+//     2006-01-02T15:04
+//     15:04
@@ -0,0 +1,36 @@
+package internal
+
+import "time"
+
+// Timezones used for local datetime, date, and time TOML types.
+//
+// The exact way times and dates without a timezone should be interpreted is not
+// well-defined in the TOML specification and left to the implementation. These
+// defaults to current local timezone offset of the computer, but this can be
+// changed by changing these variables before decoding.
+//
+// TODO:
+// Ideally we'd like to offer people the ability to configure the used timezone
+// by setting Decoder.Timezone and Encoder.Timezone; however, this is a bit
+// tricky: the reason we use three different variables for this is to support
+// round-tripping – without these specific TZ names we wouldn't know which
+// format to use.
+//
+// There isn't a good way to encode this right now though, and passing this sort
+// of information also ties in to various related issues such as string format
+// encoding, encoding of comments, etc.
+//
+// So, for the time being, just put this in internal until we can write a good
+// comprehensive API for doing all of this.
+//
+// The reason they're exported is because they're referred from in e.g.
+// internal/tag.
+//
+// Note that this behaviour is valid according to the TOML spec as the exact
+// behaviour is left up to implementations.
+var (
+	localOffset   = func() int { _, o := time.Now().Zone(); return o }()
+	LocalDatetime = time.FixedZone("datetime-local", localOffset)
+	LocalDate     = time.FixedZone("date-local", localOffset)
+	LocalTime     = time.FixedZone("time-local", localOffset)
+)
@@ -0,0 +1,148 @@
+package toml
+
+import (
+	"strings"
+)
+
+// MetaData allows access to meta information about TOML data that's not
+// accessible otherwise.
+//
+// It allows checking if a key is defined in the TOML data, whether any keys
+// were undecoded, and the TOML type of a key.
+type MetaData struct {
+	context Key // Used only during decoding.
+
+	keyInfo map[string]keyInfo
+	mapping map[string]any
+	keys    []Key
+	decoded map[string]struct{}
+	data    []byte // Input file; for errors.
+}
+
+// IsDefined reports if the key exists in the TOML data.
+//
+// The key should be specified hierarchically, for example to access the TOML
+// key "a.b.c" you would use IsDefined("a", "b", "c"). Keys are case sensitive.
+//
+// Returns false for an empty key.
+func (md *MetaData) IsDefined(key ...string) bool {
+	if len(key) == 0 {
+		return false
+	}
+
+	var (
+		hash      map[string]any
+		ok        bool
+		hashOrVal any = md.mapping
+	)
+	for _, k := range key {
+		if hash, ok = hashOrVal.(map[string]any); !ok {
+			return false
+		}
+		if hashOrVal, ok = hash[k]; !ok {
+			return false
+		}
+	}
+	return true
+}
+
+// Type returns a string representation of the type of the key specified.
+//
+// Type will return the empty string if given an empty key or a key that does
+// not exist. Keys are case sensitive.
+func (md *MetaData) Type(key ...string) string {
+	if ki, ok := md.keyInfo[Key(key).String()]; ok {
+		return ki.tomlType.typeString()
+	}
+	return ""
+}
+
+// Keys returns a slice of every key in the TOML data, including key groups.
+//
+// Each key is itself a slice, where the first element is the top of the
+// hierarchy and the last is the most specific. The list will have the same
+// order as the keys appeared in the TOML data.
+//
+// All keys returned are non-empty.
+func (md *MetaData) Keys() []Key {
+	return md.keys
+}
+
+// Undecoded returns all keys that have not been decoded in the order in which
+// they appear in the original TOML document.
+//
+// This includes keys that haven't been decoded because of a [Primitive] value.
+// Once the Primitive value is decoded, the keys will be considered decoded.
+//
+// Also note that decoding into an empty interface will result in no decoding,
+// and so no keys will be considered decoded.
+//
+// In this sense, the Undecoded keys correspond to keys in the TOML document
+// that do not have a concrete type in your representation.
+func (md *MetaData) Undecoded() []Key {
+	undecoded := make([]Key, 0, len(md.keys))
+	for _, key := range md.keys {
+		if _, ok := md.decoded[key.String()]; !ok {
+			undecoded = append(undecoded, key)
+		}
+	}
+	return undecoded
+}
+
+// Key represents any TOML key, including key groups. Use [MetaData.Keys] to get
+// values of this type.
+type Key []string
+
+func (k Key) String() string {
+	// This is called quite often, so it's a bit funky to make it faster.
+	var b strings.Builder
+	b.Grow(len(k) * 25)
+outer:
+	for i, kk := range k {
+		if i > 0 {
+			b.WriteByte('.')
+		}
+		if kk == "" {
+			b.WriteString(`""`)
+		} else {
+			for _, r := range kk {
+				// "Inline" isBareKeyChar
+				if !((r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '_' || r == '-') {
+					b.WriteByte('"')
+					b.WriteString(dblQuotedReplacer.Replace(kk))
+					b.WriteByte('"')
+					continue outer
+				}
+			}
+			b.WriteString(kk)
+		}
+	}
+	return b.String()
+}
+
+func (k Key) maybeQuoted(i int) string {
+	if k[i] == "" {
+		return `""`
+	}
+	for _, r := range k[i] {
+		if (r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '_' || r == '-' {
+			continue
+		}
+		return `"` + dblQuotedReplacer.Replace(k[i]) + `"`
+	}
+	return k[i]
+}
+
+// Like append(), but only increase the cap by 1.
+func (k Key) add(piece string) Key {
+	if cap(k) > len(k) {
+		return append(k, piece)
+	}
+	newKey := make(Key, len(k)+1)
+	copy(newKey, k)
+	newKey[len(k)] = piece
+	return newKey
+}
+
+func (k Key) parent() Key  { return k[:len(k)-1] } // all except the last piece.
+func (k Key) last() string { return k[len(k)-1] }  // last piece of this key.
@@ -0,0 +1,846 @@
+package toml
+
+import (
+	"fmt"
+	"math"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"github.com/BurntSushi/toml/internal"
+)
+
+type parser struct {
+	lx         *lexer
+	context    Key      // Full key for the current hash in scope.
+	currentKey string   // Base key name for everything except hashes.
+	pos        Position // Current position in the TOML file.
+	tomlNext   bool
+
+	ordered []Key // List of keys in the order that they appear in the TOML data.
+
+	keyInfo   map[string]keyInfo  // Map keyname → info about the TOML key.
+	mapping   map[string]any      // Map keyname → key value.
+	implicits map[string]struct{} // Record implicit keys (e.g. "key.group.names").
+}
+
+type keyInfo struct {
+	pos      Position
+	tomlType tomlType
+}
+
+func parse(data string) (p *parser, err error) {
+	_, tomlNext := os.LookupEnv("BURNTSUSHI_TOML_110")
+
+	defer func() {
+		if r := recover(); r != nil {
+			if pErr, ok := r.(ParseError); ok {
+				pErr.input = data
+				err = pErr
+				return
+			}
+			panic(r)
+		}
+	}()
+
+	// Read over BOM; do this here as the lexer calls utf8.DecodeRuneInString()
+	// which mangles stuff. UTF-16 BOM isn't strictly valid, but some tools add
+	// it anyway.
+	if strings.HasPrefix(data, "\xff\xfe") || strings.HasPrefix(data, "\xfe\xff") { // UTF-16
+		data = data[2:]
+		//lint:ignore S1017 https://github.com/dominikh/go-tools/issues/1447
+	} else if strings.HasPrefix(data, "\xef\xbb\xbf") { // UTF-8
+		data = data[3:]
+	}
+
+	// Examine first few bytes for NULL bytes; this probably means it's a UTF-16
+	// file (second byte in surrogate pair being NULL). Again, do this here to
+	// avoid having to deal with UTF-8/16 stuff in the lexer.
+	ex := 6
+	if len(data) < 6 {
+		ex = len(data)
+	}
+	if i := strings.IndexRune(data[:ex], 0); i > -1 {
+		return nil, ParseError{
+			Message:  "files cannot contain NULL bytes; probably using UTF-16; TOML files must be UTF-8",
+			Position: Position{Line: 1, Col: 1, Start: i, Len: 1},
+			Line:     1,
+			input:    data,
+		}
+	}
+
+	p = &parser{
+		keyInfo:   make(map[string]keyInfo),
+		mapping:   make(map[string]any),
+		lx:        lex(data, tomlNext),
+		ordered:   make([]Key, 0),
+		implicits: make(map[string]struct{}),
+		tomlNext:  tomlNext,
+	}
+	for {
+		item := p.next()
+		if item.typ == itemEOF {
+			break
+		}
+		p.topLevel(item)
+	}
+
+	return p, nil
+}
+
+func (p *parser) panicErr(it item, err error) {
+	panic(ParseError{
+		Message:  err.Error(),
+		err:      err,
+		Position: it.pos.withCol(p.lx.input),
+		Line:     it.pos.Len,
+		LastKey:  p.current(),
+	})
+}
+
+func (p *parser) panicItemf(it item, format string, v ...any) {
+	panic(ParseError{
+		Message:  fmt.Sprintf(format, v...),
+		Position: it.pos.withCol(p.lx.input),
+		Line:     it.pos.Len,
+		LastKey:  p.current(),
+	})
+}
+
+func (p *parser) panicf(format string, v ...any) {
+	panic(ParseError{
+		Message:  fmt.Sprintf(format, v...),
+		Position: p.pos.withCol(p.lx.input),
+		Line:     p.pos.Line,
+		LastKey:  p.current(),
+	})
+}
+
+func (p *parser) next() item {
+	it := p.lx.nextItem()
+	//fmt.Printf("ITEM %-18s line %-3d │ %q\n", it.typ, it.pos.Line, it.val)
+	if it.typ == itemError {
+		if it.err != nil {
+			panic(ParseError{
+				Message:  it.err.Error(),
+				err:      it.err,
+				Position: it.pos.withCol(p.lx.input),
+				Line:     it.pos.Line,
+				LastKey:  p.current(),
+			})
+		}
+
+		p.panicItemf(it, "%s", it.val)
+	}
+	return it
+}
+
+func (p *parser) nextPos() item {
+	it := p.next()
+	p.pos = it.pos
+	return it
+}
+
+func (p *parser) bug(format string, v ...any) {
+	panic(fmt.Sprintf("BUG: "+format+"\n\n", v...))
+}
+
+func (p *parser) expect(typ itemType) item {
+	it := p.next()
+	p.assertEqual(typ, it.typ)
+	return it
+}
+
+func (p *parser) assertEqual(expected, got itemType) {
+	if expected != got {
+		p.bug("Expected '%s' but got '%s'.", expected, got)
+	}
+}
+
+func (p *parser) topLevel(item item) {
+	switch item.typ {
+	case itemCommentStart: // # ..
+		p.expect(itemText)
+	case itemTableStart: // [ .. ]
+		name := p.nextPos()
+
+		var key Key
+		for ; name.typ != itemTableEnd && name.typ != itemEOF; name = p.next() {
+			key = append(key, p.keyString(name))
+		}
+		p.assertEqual(itemTableEnd, name.typ)
+
+		p.addContext(key, false)
+		p.setType("", tomlHash, item.pos)
+		p.ordered = append(p.ordered, key)
+	case itemArrayTableStart: // [[ .. ]]
+		name := p.nextPos()
+
+		var key Key
+		for ; name.typ != itemArrayTableEnd && name.typ != itemEOF; name = p.next() {
+			key = append(key, p.keyString(name))
+		}
+		p.assertEqual(itemArrayTableEnd, name.typ)
+
+		p.addContext(key, true)
+		p.setType("", tomlArrayHash, item.pos)
+		p.ordered = append(p.ordered, key)
+	case itemKeyStart: // key = ..
+		outerContext := p.context
+		/// Read all the key parts (e.g. 'a' and 'b' in 'a.b')
+		k := p.nextPos()
+		var key Key
+		for ; k.typ != itemKeyEnd && k.typ != itemEOF; k = p.next() {
+			key = append(key, p.keyString(k))
+		}
+		p.assertEqual(itemKeyEnd, k.typ)
+
+		/// The current key is the last part.
+		p.currentKey = key.last()
+
+		/// All the other parts (if any) are the context; need to set each part
+		/// as implicit.
+		context := key.parent()
+		for i := range context {
+			p.addImplicitContext(append(p.context, context[i:i+1]...))
+		}
+		p.ordered = append(p.ordered, p.context.add(p.currentKey))
+
+		/// Set value.
+		vItem := p.next()
+		val, typ := p.value(vItem, false)
+		p.setValue(p.currentKey, val)
+		p.setType(p.currentKey, typ, vItem.pos)
+
+		/// Remove the context we added (preserving any context from [tbl] lines).
+		p.context = outerContext
+		p.currentKey = ""
+	default:
+		p.bug("Unexpected type at top level: %s", item.typ)
+	}
+}
+
+// Gets a string for a key (or part of a key in a table name).
+func (p *parser) keyString(it item) string {
+	switch it.typ {
+	case itemText:
+		return it.val
+	case itemString, itemStringEsc, itemMultilineString,
+		itemRawString, itemRawMultilineString:
+		s, _ := p.value(it, false)
+		return s.(string)
+	default:
+		p.bug("Unexpected key type: %s", it.typ)
+	}
+	panic("unreachable")
+}
+
+var datetimeRepl = strings.NewReplacer(
+	"z", "Z",
+	"t", "T",
+	" ", "T")
+
+// value translates an expected value from the lexer into a Go value wrapped
+// as an empty interface.
+func (p *parser) value(it item, parentIsArray bool) (any, tomlType) {
+	switch it.typ {
+	case itemString:
+		return it.val, p.typeOfPrimitive(it)
+	case itemStringEsc:
+		return p.replaceEscapes(it, it.val), p.typeOfPrimitive(it)
+	case itemMultilineString:
+		return p.replaceEscapes(it, p.stripEscapedNewlines(stripFirstNewline(it.val))), p.typeOfPrimitive(it)
+	case itemRawString:
+		return it.val, p.typeOfPrimitive(it)
+	case itemRawMultilineString:
+		return stripFirstNewline(it.val), p.typeOfPrimitive(it)
+	case itemInteger:
+		return p.valueInteger(it)
+	case itemFloat:
+		return p.valueFloat(it)
+	case itemBool:
+		switch it.val {
+		case "true":
+			return true, p.typeOfPrimitive(it)
+		case "false":
+			return false, p.typeOfPrimitive(it)
+		default:
+			p.bug("Expected boolean value, but got '%s'.", it.val)
+		}
+	case itemDatetime:
+		return p.valueDatetime(it)
+	case itemArray:
+		return p.valueArray(it)
+	case itemInlineTableStart:
+		return p.valueInlineTable(it, parentIsArray)
+	default:
+		p.bug("Unexpected value type: %s", it.typ)
+	}
+	panic("unreachable")
+}
+
+func (p *parser) valueInteger(it item) (any, tomlType) {
+	if !numUnderscoresOK(it.val) {
+		p.panicItemf(it, "Invalid integer %q: underscores must be surrounded by digits", it.val)
+	}
+	if numHasLeadingZero(it.val) {
+		p.panicItemf(it, "Invalid integer %q: cannot have leading zeroes", it.val)
+	}
+
+	num, err := strconv.ParseInt(it.val, 0, 64)
+	if err != nil {
+		// Distinguish integer values. Normally, it'd be a bug if the lexer
+		// provides an invalid integer, but it's possible that the number is
+		// out of range of valid values (which the lexer cannot determine).
+		// So mark the former as a bug but the latter as a legitimate user
+		// error.
+		if e, ok := err.(*strconv.NumError); ok && e.Err == strconv.ErrRange {
+			p.panicErr(it, errParseRange{i: it.val, size: "int64"})
+		} else {
+			p.bug("Expected integer value, but got '%s'.", it.val)
+		}
+	}
+	return num, p.typeOfPrimitive(it)
+}
+
+func (p *parser) valueFloat(it item) (any, tomlType) {
+	parts := strings.FieldsFunc(it.val, func(r rune) bool {
+		switch r {
+		case '.', 'e', 'E':
+			return true
+		}
+		return false
+	})
+	for _, part := range parts {
+		if !numUnderscoresOK(part) {
+			p.panicItemf(it, "Invalid float %q: underscores must be surrounded by digits", it.val)
+		}
+	}
+	if len(parts) > 0 && numHasLeadingZero(parts[0]) {
+		p.panicItemf(it, "Invalid float %q: cannot have leading zeroes", it.val)
+	}
+	if !numPeriodsOK(it.val) {
+		// As a special case, numbers like '123.' or '1.e2',
+		// which are valid as far as Go/strconv are concerned,
+		// must be rejected because TOML says that a fractional
+		// part consists of '.' followed by 1+ digits.
+		p.panicItemf(it, "Invalid float %q: '.' must be followed by one or more digits", it.val)
+	}
+	val := strings.Replace(it.val, "_", "", -1)
+	signbit := false
+	if val == "+nan" || val == "-nan" {
+		signbit = val == "-nan"
+		val = "nan"
+	}
+	num, err := strconv.ParseFloat(val, 64)
+	if err != nil {
+		if e, ok := err.(*strconv.NumError); ok && e.Err == strconv.ErrRange {
+			p.panicErr(it, errParseRange{i: it.val, size: "float64"})
+		} else {
+			p.panicItemf(it, "Invalid float value: %q", it.val)
+		}
+	}
+	if signbit {
+		num = math.Copysign(num, -1)
+	}
+	return num, p.typeOfPrimitive(it)
+}
+
+var dtTypes = []struct {
+	fmt  string
+	zone *time.Location
+	next bool
+}{
+	{time.RFC3339Nano, time.Local, false},
+	{"2006-01-02T15:04:05.999999999", internal.LocalDatetime, false},
+	{"2006-01-02", internal.LocalDate, false},
+	{"15:04:05.999999999", internal.LocalTime, false},
+
+	// tomlNext
+	{"2006-01-02T15:04Z07:00", time.Local, true},
+	{"2006-01-02T15:04", internal.LocalDatetime, true},
+	{"15:04", internal.LocalTime, true},
+}
+
+func (p *parser) valueDatetime(it item) (any, tomlType) {
+	it.val = datetimeRepl.Replace(it.val)
+	var (
+		t   time.Time
+		ok  bool
+		err error
+	)
+	for _, dt := range dtTypes {
+		if dt.next && !p.tomlNext {
+			continue
+		}
+		t, err = time.ParseInLocation(dt.fmt, it.val, dt.zone)
+		if err == nil {
+			if missingLeadingZero(it.val, dt.fmt) {
+				p.panicErr(it, errParseDate{it.val})
+			}
+			ok = true
+			break
+		}
+	}
+	if !ok {
+		p.panicErr(it, errParseDate{it.val})
+	}
+	return t, p.typeOfPrimitive(it)
+}
+
+// Go's time.Parse() will accept numbers without a leading zero; there isn't any
+// way to require it. https://github.com/golang/go/issues/29911
+//
+// Depend on the fact that the separators (- and :) should always be at the same
+// location.
+func missingLeadingZero(d, l string) bool {
+	for i, c := range []byte(l) {
+		if c == '.' || c == 'Z' {
+			return false
+		}
+		if (c < '0' || c > '9') && d[i] != c {
+			return true
+		}
+	}
+	return false
+}
+
+func (p *parser) valueArray(it item) (any, tomlType) {
+	p.setType(p.currentKey, tomlArray, it.pos)
+
+	var (
+		// Initialize to a non-nil slice to make it consistent with how S = []
+		// decodes into a non-nil slice inside something like struct { S
+		// []string }. See #338
+		array = make([]any, 0, 2)
+	)
+	for it = p.next(); it.typ != itemArrayEnd; it = p.next() {
+		if it.typ == itemCommentStart {
+			p.expect(itemText)
+			continue
+		}
+
+		val, typ := p.value(it, true)
+		array = append(array, val)
+
+		// XXX: type isn't used here, we need it to record the accurate type
+		// information.
+		//
+		// Not entirely sure how to best store this; could use "key[0]",
+		// "key[1]" notation, or maybe store it on the Array type?
+		_ = typ
+	}
+	return array, tomlArray
+}
+
+func (p *parser) valueInlineTable(it item, parentIsArray bool) (any, tomlType) {
+	var (
+		topHash      = make(map[string]any)
+		outerContext = p.context
+		outerKey     = p.currentKey
+	)
+
+	p.context = append(p.context, p.currentKey)
+	prevContext := p.context
+	p.currentKey = ""
+
+	p.addImplicit(p.context)
+	p.addContext(p.context, parentIsArray)
+
+	/// Loop over all table key/value pairs.
+	for it := p.next(); it.typ != itemInlineTableEnd; it = p.next() {
+		if it.typ == itemCommentStart {
+			p.expect(itemText)
+			continue
+		}
+
+		/// Read all key parts.
+		k := p.nextPos()
+		var key Key
+		for ; k.typ != itemKeyEnd && k.typ != itemEOF; k = p.next() {
+			key = append(key, p.keyString(k))
+		}
+		p.assertEqual(itemKeyEnd, k.typ)
+
+		/// The current key is the last part.
+		p.currentKey = key.last()
+
+		/// All the other parts (if any) are the context; need to set each part
+		/// as implicit.
+		context := key.parent()
+		for i := range context {
+			p.addImplicitContext(append(p.context, context[i:i+1]...))
+		}
+		p.ordered = append(p.ordered, p.context.add(p.currentKey))
+
+		/// Set the value.
+		val, typ := p.value(p.next(), false)
+		p.setValue(p.currentKey, val)
+		p.setType(p.currentKey, typ, it.pos)
+
+		hash := topHash
+		for _, c := range context {
+			h, ok := hash[c]
+			if !ok {
+				h = make(map[string]any)
+				hash[c] = h
+			}
+			hash, ok = h.(map[string]any)
+			if !ok {
+				p.panicf("%q is not a table", p.context)
+			}
+		}
+		hash[p.currentKey] = val
+
+		/// Restore context.
+		p.context = prevContext
+	}
+	p.context = outerContext
+	p.currentKey = outerKey
+	return topHash, tomlHash
+}
+
+// numHasLeadingZero checks if this number has leading zeroes, allowing for '0',
+// +/- signs, and base prefixes.
+func numHasLeadingZero(s string) bool {
+	if len(s) > 1 && s[0] == '0' && !(s[1] == 'b' || s[1] == 'o' || s[1] == 'x') { // Allow 0b, 0o, 0x
+		return true
+	}
+	if len(s) > 2 && (s[0] == '-' || s[0] == '+') && s[1] == '0' {
+		return true
+	}
+	return false
+}
+
+// numUnderscoresOK checks whether each underscore in s is surrounded by
+// characters that are not underscores.
+func numUnderscoresOK(s string) bool {
+	switch s {
+	case "nan", "+nan", "-nan", "inf", "-inf", "+inf":
+		return true
+	}
+	accept := false
+	for _, r := range s {
+		if r == '_' {
+			if !accept {
+				return false
+			}
+		}
+
+		// isHexis a superset of all the permissable characters surrounding an
+		// underscore.
+		accept = isHex(r)
+	}
+	return accept
+}
+
+// numPeriodsOK checks whether every period in s is followed by a digit.
+func numPeriodsOK(s string) bool {
+	period := false
+	for _, r := range s {
+		if period && !isDigit(r) {
+			return false
+		}
+		period = r == '.'
+	}
+	return !period
+}
+
+// Set the current context of the parser, where the context is either a hash or
+// an array of hashes, depending on the value of the `array` parameter.
+//
+// Establishing the context also makes sure that the key isn't a duplicate, and
+// will create implicit hashes automatically.
+func (p *parser) addContext(key Key, array bool) {
+	/// Always start at the top level and drill down for our context.
+	hashContext := p.mapping
+	keyContext := make(Key, 0, len(key)-1)
+
+	/// We only need implicit hashes for the parents.
+	for _, k := range key.parent() {
+		_, ok := hashContext[k]
+		keyContext = append(keyContext, k)
+
+		// No key? Make an implicit hash and move on.
+		if !ok {
+			p.addImplicit(keyContext)
+			hashContext[k] = make(map[string]any)
+		}
+
+		// If the hash context is actually an array of tables, then set
+		// the hash context to the last element in that array.
+		//
+		// Otherwise, it better be a table, since this MUST be a key group (by
+		// virtue of it not being the last element in a key).
+		switch t := hashContext[k].(type) {
+		case []map[string]any:
+			hashContext = t[len(t)-1]
+		case map[string]any:
+			hashContext = t
+		default:
+			p.panicf("Key '%s' was already created as a hash.", keyContext)
+		}
+	}
+
+	p.context = keyContext
+	if array {
+		// If this is the first element for this array, then allocate a new
+		// list of tables for it.
+		k := key.last()
+		if _, ok := hashContext[k]; !ok {
+			hashContext[k] = make([]map[string]any, 0, 4)
+		}
+
+		// Add a new table. But make sure the key hasn't already been used
+		// for something else.
+		if hash, ok := hashContext[k].([]map[string]any); ok {
+			hashContext[k] = append(hash, make(map[string]any))
+		} else {
+			p.panicf("Key '%s' was already created and cannot be used as an array.", key)
+		}
+	} else {
+		p.setValue(key.last(), make(map[string]any))
+	}
+	p.context = append(p.context, key.last())
+}
+
+// setValue sets the given key to the given value in the current context.
+// It will make sure that the key hasn't already been defined, account for
+// implicit key groups.
+func (p *parser) setValue(key string, value any) {
+	var (
+		tmpHash    any
+		ok         bool
+		hash       = p.mapping
+		keyContext = make(Key, 0, len(p.context)+1)
+	)
+	for _, k := range p.context {
+		keyContext = append(keyContext, k)
+		if tmpHash, ok = hash[k]; !ok {
+			p.bug("Context for key '%s' has not been established.", keyContext)
+		}
+		switch t := tmpHash.(type) {
+		case []map[string]any:
+			// The context is a table of hashes. Pick the most recent table
+			// defined as the current hash.
+			hash = t[len(t)-1]
+		case map[string]any:
+			hash = t
+		default:
+			p.panicf("Key '%s' has already been defined.", keyContext)
+		}
+	}
+	keyContext = append(keyContext, key)
+
+	if _, ok := hash[key]; ok {
+		// Normally redefining keys isn't allowed, but the key could have been
+		// defined implicitly and it's allowed to be redefined concretely. (See
+		// the `valid/implicit-and-explicit-after.toml` in toml-test)
+		//
+		// But we have to make sure to stop marking it as an implicit. (So that
+		// another redefinition provokes an error.)
+		//
+		// Note that since it has already been defined (as a hash), we don't
+		// want to overwrite it. So our business is done.
+		if p.isArray(keyContext) {
+			p.removeImplicit(keyContext)
+			hash[key] = value
+			return
+		}
+		if p.isImplicit(keyContext) {
+			p.removeImplicit(keyContext)
+			return
+		}
+		// Otherwise, we have a concrete key trying to override a previous key,
+		// which is *always* wrong.
+		p.panicf("Key '%s' has already been defined.", keyContext)
+	}
+
+	hash[key] = value
+}
+
+// setType sets the type of a particular value at a given key. It should be
+// called immediately AFTER setValue.
+//
+// Note that if `key` is empty, then the type given will be applied to the
+// current context (which is either a table or an array of tables).
+func (p *parser) setType(key string, typ tomlType, pos Position) {
+	keyContext := make(Key, 0, len(p.context)+1)
+	keyContext = append(keyContext, p.context...)
+	if len(key) > 0 { // allow type setting for hashes
+		keyContext = append(keyContext, key)
+	}
+	// Special case to make empty keys ("" = 1) work.
+	// Without it it will set "" rather than `""`.
+	// TODO: why is this needed? And why is this only needed here?
+	if len(keyContext) == 0 {
+		keyContext = Key{""}
+	}
+	p.keyInfo[keyContext.String()] = keyInfo{tomlType: typ, pos: pos}
+}
+
+// Implicit keys need to be created when tables are implied in "a.b.c.d = 1" and
+// "[a.b.c]" (the "a", "b", and "c" hashes are never created explicitly).
+func (p *parser) addImplicit(key Key)        { p.implicits[key.String()] = struct{}{} }
+func (p *parser) removeImplicit(key Key)     { delete(p.implicits, key.String()) }
+func (p *parser) isImplicit(key Key) bool    { _, ok := p.implicits[key.String()]; return ok }
+func (p *parser) isArray(key Key) bool       { return p.keyInfo[key.String()].tomlType == tomlArray }
+func (p *parser) addImplicitContext(key Key) { p.addImplicit(key); p.addContext(key, false) }
+
+// current returns the full key name of the current context.
+func (p *parser) current() string {
+	if len(p.currentKey) == 0 {
+		return p.context.String()
+	}
+	if len(p.context) == 0 {
+		return p.currentKey
+	}
+	return fmt.Sprintf("%s.%s", p.context, p.currentKey)
+}
+
+func stripFirstNewline(s string) string {
+	if len(s) > 0 && s[0] == '\n' {
+		return s[1:]
+	}
+	if len(s) > 1 && s[0] == '\r' && s[1] == '\n' {
+		return s[2:]
+	}
+	return s
+}
+
+// stripEscapedNewlines removes whitespace after line-ending backslashes in
+// multiline strings.
+//
+// A line-ending backslash is an unescaped \ followed only by whitespace until
+// the next newline. After a line-ending backslash, all whitespace is removed
+// until the next non-whitespace character.
+func (p *parser) stripEscapedNewlines(s string) string {
+	var (
+		b strings.Builder
+		i int
+	)
+	b.Grow(len(s))
+	for {
+		ix := strings.Index(s[i:], `\`)
+		if ix < 0 {
+			b.WriteString(s)
+			return b.String()
+		}
+		i += ix
+
+		if len(s) > i+1 && s[i+1] == '\\' {
+			// Escaped backslash.
+			i += 2
+			continue
+		}
+		// Scan until the next non-whitespace.
+		j := i + 1
+	whitespaceLoop:
+		for ; j < len(s); j++ {
+			switch s[j] {
+			case ' ', '\t', '\r', '\n':
+			default:
+				break whitespaceLoop
+			}
+		}
+		if j == i+1 {
+			// Not a whitespace escape.
+			i++
+			continue
+		}
+		if !strings.Contains(s[i:j], "\n") {
+			// This is not a line-ending backslash. (It's a bad escape sequence,
+			// but we can let replaceEscapes catch it.)
+			i++
+			continue
+		}
+		b.WriteString(s[:i])
+		s = s[j:]
+		i = 0
+	}
+}
+
+func (p *parser) replaceEscapes(it item, str string) string {
+	var (
+		b    strings.Builder
+		skip = 0
+	)
+	b.Grow(len(str))
+	for i, c := range str {
+		if skip > 0 {
+			skip--
+			continue
+		}
+		if c != '\\' {
+			b.WriteRune(c)
+			continue
+		}
+
+		if i >= len(str) {
+			p.bug("Escape sequence at end of string.")
+			return ""
+		}
+		switch str[i+1] {
+		default:
+			p.bug("Expected valid escape code after \\, but got %q.", str[i+1])
+		case ' ', '\t':
+			p.panicItemf(it, "invalid escape: '\\%c'", str[i+1])
+		case 'b':
+			b.WriteByte(0x08)
+			skip = 1
+		case 't':
+			b.WriteByte(0x09)
+			skip = 1
+		case 'n':
+			b.WriteByte(0x0a)
+			skip = 1
+		case 'f':
+			b.WriteByte(0x0c)
+			skip = 1
+		case 'r':
+			b.WriteByte(0x0d)
+			skip = 1
+		case 'e':
+			if p.tomlNext {
+				b.WriteByte(0x1b)
+				skip = 1
+			}
+		case '"':
+			b.WriteByte(0x22)
+			skip = 1
+		case '\\':
+			b.WriteByte(0x5c)
+			skip = 1
+		// The lexer guarantees the correct number of characters are present;
+		// don't need to check here.
+		case 'x':
+			if p.tomlNext {
+				escaped := p.asciiEscapeToUnicode(it, str[i+2:i+4])
+				b.WriteRune(escaped)
+				skip = 3
+			}
+		case 'u':
+			escaped := p.asciiEscapeToUnicode(it, str[i+2:i+6])
+			b.WriteRune(escaped)
+			skip = 5
+		case 'U':
+			escaped := p.asciiEscapeToUnicode(it, str[i+2:i+10])
+			b.WriteRune(escaped)
+			skip = 9
+		}
+	}
+	return b.String()
+}
+
+func (p *parser) asciiEscapeToUnicode(it item, s string) rune {
+	hex, err := strconv.ParseUint(strings.ToLower(s), 16, 32)
+	if err != nil {
+		p.bug("Could not parse '%s' as a hexadecimal number, but the lexer claims it's OK: %s", s, err)
+	}
+	if !utf8.ValidRune(rune(hex)) {
+		p.panicItemf(it, "Escaped character '\\u%s' is not valid UTF-8.", s)
+	}
+	return rune(hex)
+}
@@ -0,0 +1,238 @@
+package toml
+
+// Struct field handling is adapted from code in encoding/json:
+//
+// Copyright 2010 The Go Authors.  All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the Go distribution.
+
+import (
+	"reflect"
+	"sort"
+	"sync"
+)
+
+// A field represents a single field found in a struct.
+type field struct {
+	name  string       // the name of the field (`toml` tag included)
+	tag   bool         // whether field has a `toml` tag
+	index []int        // represents the depth of an anonymous field
+	typ   reflect.Type // the type of the field
+}
+
+// byName sorts field by name, breaking ties with depth,
+// then breaking ties with "name came from toml tag", then
+// breaking ties with index sequence.
+type byName []field
+
+func (x byName) Len() int      { return len(x) }
+func (x byName) Swap(i, j int) { x[i], x[j] = x[j], x[i] }
+func (x byName) Less(i, j int) bool {
+	if x[i].name != x[j].name {
+		return x[i].name < x[j].name
+	}
+	if len(x[i].index) != len(x[j].index) {
+		return len(x[i].index) < len(x[j].index)
+	}
+	if x[i].tag != x[j].tag {
+		return x[i].tag
+	}
+	return byIndex(x).Less(i, j)
+}
+
+// byIndex sorts field by index sequence.
+type byIndex []field
+
+func (x byIndex) Len() int      { return len(x) }
+func (x byIndex) Swap(i, j int) { x[i], x[j] = x[j], x[i] }
+func (x byIndex) Less(i, j int) bool {
+	for k, xik := range x[i].index {
+		if k >= len(x[j].index) {
+			return false
+		}
+		if xik != x[j].index[k] {
+			return xik < x[j].index[k]
+		}
+	}
+	return len(x[i].index) < len(x[j].index)
+}
+
+// typeFields returns a list of fields that TOML should recognize for the given
+// type. The algorithm is breadth-first search over the set of structs to
+// include - the top struct and then any reachable anonymous structs.
+func typeFields(t reflect.Type) []field {
+	// Anonymous fields to explore at the current level and the next.
+	current := []field{}
+	next := []field{{typ: t}}
+
+	// Count of queued names for current level and the next.
+	var count map[reflect.Type]int
+	var nextCount map[reflect.Type]int
+
+	// Types already visited at an earlier level.
+	visited := map[reflect.Type]bool{}
+
+	// Fields found.
+	var fields []field
+
+	for len(next) > 0 {
+		current, next = next, current[:0]
+		count, nextCount = nextCount, map[reflect.Type]int{}
+
+		for _, f := range current {
+			if visited[f.typ] {
+				continue
+			}
+			visited[f.typ] = true
+
+			// Scan f.typ for fields to include.
+			for i := 0; i < f.typ.NumField(); i++ {
+				sf := f.typ.Field(i)
+				if sf.PkgPath != "" && !sf.Anonymous { // unexported
+					continue
+				}
+				opts := getOptions(sf.Tag)
+				if opts.skip {
+					continue
+				}
+				index := make([]int, len(f.index)+1)
+				copy(index, f.index)
+				index[len(f.index)] = i
+
+				ft := sf.Type
+				if ft.Name() == "" && ft.Kind() == reflect.Ptr {
+					// Follow pointer.
+					ft = ft.Elem()
+				}
+
+				// Record found field and index sequence.
+				if opts.name != "" || !sf.Anonymous || ft.Kind() != reflect.Struct {
+					tagged := opts.name != ""
+					name := opts.name
+					if name == "" {
+						name = sf.Name
+					}
+					fields = append(fields, field{name, tagged, index, ft})
+					if count[f.typ] > 1 {
+						// If there were multiple instances, add a second,
+						// so that the annihilation code will see a duplicate.
+						// It only cares about the distinction between 1 or 2,
+						// so don't bother generating any more copies.
+						fields = append(fields, fields[len(fields)-1])
+					}
+					continue
+				}
+
+				// Record new anonymous struct to explore in next round.
+				nextCount[ft]++
+				if nextCount[ft] == 1 {
+					f := field{name: ft.Name(), index: index, typ: ft}
+					next = append(next, f)
+				}
+			}
+		}
+	}
+
+	sort.Sort(byName(fields))
+
+	// Delete all fields that are hidden by the Go rules for embedded fields,
+	// except that fields with TOML tags are promoted.
+
+	// The fields are sorted in primary order of name, secondary order
+	// of field index length. Loop over names; for each name, delete
+	// hidden fields by choosing the one dominant field that survives.
+	out := fields[:0]
+	for advance, i := 0, 0; i < len(fields); i += advance {
+		// One iteration per name.
+		// Find the sequence of fields with the name of this first field.
+		fi := fields[i]
+		name := fi.name
+		for advance = 1; i+advance < len(fields); advance++ {
+			fj := fields[i+advance]
+			if fj.name != name {
+				break
+			}
+		}
+		if advance == 1 { // Only one field with this name
+			out = append(out, fi)
+			continue
+		}
+		dominant, ok := dominantField(fields[i : i+advance])
+		if ok {
+			out = append(out, dominant)
+		}
+	}
+
+	fields = out
+	sort.Sort(byIndex(fields))
+
+	return fields
+}
+
+// dominantField looks through the fields, all of which are known to
+// have the same name, to find the single field that dominates the
+// others using Go's embedding rules, modified by the presence of
+// TOML tags. If there are multiple top-level fields, the boolean
+// will be false: This condition is an error in Go and we skip all
+// the fields.
+func dominantField(fields []field) (field, bool) {
+	// The fields are sorted in increasing index-length order. The winner
+	// must therefore be one with the shortest index length. Drop all
+	// longer entries, which is easy: just truncate the slice.
+	length := len(fields[0].index)
+	tagged := -1 // Index of first tagged field.
+	for i, f := range fields {
+		if len(f.index) > length {
+			fields = fields[:i]
+			break
+		}
+		if f.tag {
+			if tagged >= 0 {
+				// Multiple tagged fields at the same level: conflict.
+				// Return no field.
+				return field{}, false
+			}
+			tagged = i
+		}
+	}
+	if tagged >= 0 {
+		return fields[tagged], true
+	}
+	// All remaining fields have the same length. If there's more than one,
+	// we have a conflict (two fields named "X" at the same level) and we
+	// return no field.
+	if len(fields) > 1 {
+		return field{}, false
+	}
+	return fields[0], true
+}
+
+var fieldCache struct {
+	sync.RWMutex
+	m map[reflect.Type][]field
+}
+
+// cachedTypeFields is like typeFields but uses a cache to avoid repeated work.
+func cachedTypeFields(t reflect.Type) []field {
+	fieldCache.RLock()
+	f := fieldCache.m[t]
+	fieldCache.RUnlock()
+	if f != nil {
+		return f
+	}
+
+	// Compute fields without lock.
+	// Might duplicate effort but won't hold other computations back.
+	f = typeFields(t)
+	if f == nil {
+		f = []field{}
+	}
+
+	fieldCache.Lock()
+	if fieldCache.m == nil {
+		fieldCache.m = map[reflect.Type][]field{}
+	}
+	fieldCache.m[t] = f
+	fieldCache.Unlock()
+	return f
+}
@@ -0,0 +1,65 @@
+package toml
+
+// tomlType represents any Go type that corresponds to a TOML type.
+// While the first draft of the TOML spec has a simplistic type system that
+// probably doesn't need this level of sophistication, we seem to be militating
+// toward adding real composite types.
+type tomlType interface {
+	typeString() string
+}
+
+// typeEqual accepts any two types and returns true if they are equal.
+func typeEqual(t1, t2 tomlType) bool {
+	if t1 == nil || t2 == nil {
+		return false
+	}
+	return t1.typeString() == t2.typeString()
+}
+
+func typeIsTable(t tomlType) bool {
+	return typeEqual(t, tomlHash) || typeEqual(t, tomlArrayHash)
+}
+
+type tomlBaseType string
+
+func (btype tomlBaseType) typeString() string { return string(btype) }
+func (btype tomlBaseType) String() string     { return btype.typeString() }
+
+var (
+	tomlInteger   tomlBaseType = "Integer"
+	tomlFloat     tomlBaseType = "Float"
+	tomlDatetime  tomlBaseType = "Datetime"
+	tomlString    tomlBaseType = "String"
+	tomlBool      tomlBaseType = "Bool"
+	tomlArray     tomlBaseType = "Array"
+	tomlHash      tomlBaseType = "Hash"
+	tomlArrayHash tomlBaseType = "ArrayHash"
+)
+
+// typeOfPrimitive returns a tomlType of any primitive value in TOML.
+// Primitive values are: Integer, Float, Datetime, String and Bool.
+//
+// Passing a lexer item other than the following will cause a BUG message
+// to occur: itemString, itemBool, itemInteger, itemFloat, itemDatetime.
+func (p *parser) typeOfPrimitive(lexItem item) tomlType {
+	switch lexItem.typ {
+	case itemInteger:
+		return tomlInteger
+	case itemFloat:
+		return tomlFloat
+	case itemDatetime:
+		return tomlDatetime
+	case itemString, itemStringEsc:
+		return tomlString
+	case itemMultilineString:
+		return tomlString
+	case itemRawString:
+		return tomlString
+	case itemRawMultilineString:
+		return tomlString
+	case itemBool:
+		return tomlBool
+	}
+	p.bug("Cannot infer primitive type of lex item '%s'.", lexItem)
+	panic("unreachable")
+}
@@ -0,0 +1,27 @@
+Copyright (c) 2009 The Go Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,182 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package typeparams contains common utilities for writing tools that interact
+// with generic Go code, as introduced with Go 1.18.
+//
+// Many of the types and functions in this package are proxies for the new APIs
+// introduced in the standard library with Go 1.18. For example, the
+// typeparams.Union type is an alias for go/types.Union, and the ForTypeSpec
+// function returns the value of the go/ast.TypeSpec.TypeParams field. At Go
+// versions older than 1.18 these helpers are implemented as stubs, allowing
+// users of this package to write code that handles generic constructs inline,
+// even if the Go version being used to compile does not support generics.
+//
+// Additionally, this package contains common utilities for working with the
+// new generic constructs, to supplement the standard library APIs. Notably,
+// the NormalTerms API computes a minimal representation of the structural
+// restrictions on a type parameter. In the future, these supplemental APIs may
+// be available in the standard library..
+package typeparams
+
+import (
+	"go/ast"
+	"go/token"
+	"go/types"
+)
+
+// Enabled reports whether type parameters are enabled in the current build
+// environment.
+func Enabled() bool {
+	return enabled
+}
+
+// UnpackIndexExpr extracts data from AST nodes that represent index
+// expressions.
+//
+// For an ast.IndexExpr, the resulting indices slice will contain exactly one
+// index expression. For an ast.IndexListExpr (go1.18+), it may have a variable
+// number of index expressions.
+//
+// For nodes that don't represent index expressions, the first return value of
+// UnpackIndexExpr will be nil.
+func UnpackIndexExpr(n ast.Node) (x ast.Expr, lbrack token.Pos, indices []ast.Expr, rbrack token.Pos) {
+	switch e := n.(type) {
+	case *ast.IndexExpr:
+		return e.X, e.Lbrack, []ast.Expr{e.Index}, e.Rbrack
+	case *IndexListExpr:
+		return e.X, e.Lbrack, e.Indices, e.Rbrack
+	}
+	return nil, token.NoPos, nil, token.NoPos
+}
+
+// PackIndexExpr returns an *ast.IndexExpr or *ast.IndexListExpr, depending on
+// the cardinality of indices. Calling PackIndexExpr with len(indices) == 0
+// will panic.
+func PackIndexExpr(x ast.Expr, lbrack token.Pos, indices []ast.Expr, rbrack token.Pos) ast.Expr {
+	switch len(indices) {
+	case 0:
+		panic("empty indices")
+	case 1:
+		return &ast.IndexExpr{
+			X:      x,
+			Lbrack: lbrack,
+			Index:  indices[0],
+			Rbrack: rbrack,
+		}
+	default:
+		return &IndexListExpr{
+			X:       x,
+			Lbrack:  lbrack,
+			Indices: indices,
+			Rbrack:  rbrack,
+		}
+	}
+}
+
+// IsTypeParam reports whether t is a type parameter.
+func IsTypeParam(t types.Type) bool {
+	_, ok := t.(*TypeParam)
+	return ok
+}
+
+// OriginMethod returns the origin method associated with the method fn. For
+// methods on a non-generic receiver base type, this is just fn. However, for
+// methods with a generic receiver, OriginMethod returns the corresponding
+// method in the method set of the origin type.
+//
+// As a special case, if fn is not a method (has no receiver), OriginMethod
+// returns fn.
+func OriginMethod(fn *types.Func) *types.Func {
+	recv := fn.Type().(*types.Signature).Recv()
+	if recv == nil {
+		return fn
+	}
+	base := recv.Type()
+	p, isPtr := base.(*types.Pointer)
+	if isPtr {
+		base = p.Elem()
+	}
+	named, isNamed := base.(*types.Named)
+	if !isNamed {
+		// Receiver is a *types.Interface.
+		return fn
+	}
+	if ForNamed(named).Len() == 0 {
+		// Receiver base has no type parameters, so we can avoid the lookup below.
+		return fn
+	}
+	orig := NamedTypeOrigin(named)
+	gfn, _, _ := types.LookupFieldOrMethod(orig, true, fn.Pkg(), fn.Name())
+	return gfn.(*types.Func)
+}
+
+// GenericAssignableTo is a generalization of types.AssignableTo that
+// implements the following rule for uninstantiated generic types:
+//
+// If V and T are generic named types, then V is considered assignable to T if,
+// for every possible instantation of V[A_1, ..., A_N], the instantiation
+// T[A_1, ..., A_N] is valid and V[A_1, ..., A_N] implements T[A_1, ..., A_N].
+//
+// If T has structural constraints, they must be satisfied by V.
+//
+// For example, consider the following type declarations:
+//
+//	type Interface[T any] interface {
+//		Accept(T)
+//	}
+//
+//	type Container[T any] struct {
+//		Element T
+//	}
+//
+//	func (c Container[T]) Accept(t T) { c.Element = t }
+//
+// In this case, GenericAssignableTo reports that instantiations of Container
+// are assignable to the corresponding instantiation of Interface.
+func GenericAssignableTo(ctxt *Context, V, T types.Type) bool {
+	// If V and T are not both named, or do not have matching non-empty type
+	// parameter lists, fall back on types.AssignableTo.
+
+	VN, Vnamed := V.(*types.Named)
+	TN, Tnamed := T.(*types.Named)
+	if !Vnamed || !Tnamed {
+		return types.AssignableTo(V, T)
+	}
+
+	vtparams := ForNamed(VN)
+	ttparams := ForNamed(TN)
+	if vtparams.Len() == 0 || vtparams.Len() != ttparams.Len() || NamedTypeArgs(VN).Len() != 0 || NamedTypeArgs(TN).Len() != 0 {
+		return types.AssignableTo(V, T)
+	}
+
+	// V and T have the same (non-zero) number of type params. Instantiate both
+	// with the type parameters of V. This must always succeed for V, and will
+	// succeed for T if and only if the type set of each type parameter of V is a
+	// subset of the type set of the corresponding type parameter of T, meaning
+	// that every instantiation of V corresponds to a valid instantiation of T.
+
+	// Minor optimization: ensure we share a context across the two
+	// instantiations below.
+	if ctxt == nil {
+		ctxt = NewContext()
+	}
+
+	var targs []types.Type
+	for i := 0; i < vtparams.Len(); i++ {
+		targs = append(targs, vtparams.At(i))
+	}
+
+	vinst, err := Instantiate(ctxt, V, targs, true)
+	if err != nil {
+		panic("type parameters should satisfy their own constraints")
+	}
+
+	tinst, err := Instantiate(ctxt, T, targs, true)
+	if err != nil {
+		return false
+	}
+
+	return types.AssignableTo(vinst, tinst)
+}
@@ -0,0 +1,200 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package typeparams
+
+import (
+	"errors"
+	"fmt"
+	"go/types"
+	"os"
+	"strings"
+)
+
+const debug = false
+
+// ErrEmptyTypeSet is returned if a type set computation results in a type set
+// with no types.
+var ErrEmptyTypeSet = errors.New("empty type set")
+
+// NormalTerms returns a slice of terms representing the normalized structural
+// type restrictions of a type, if any.
+//
+// For all types whose underlying type is not *types.TypeParam,
+// *types.Interface, or *types.Union, this is just a single term with Tilde()
+// == false and Type() == typ. For types whose underlying type is
+// *types.TypeParam, *types.Interface, and *types.Union, see below.
+//
+// Structural type restrictions of a type parameter are created via
+// non-interface types embedded in its constraint interface (directly, or via a
+// chain of interface embeddings). For example, in the declaration type T[P
+// interface{~int; m()}] int is the structural restriction of the type
+// parameter P is ~int.
+//
+// With interface embedding and unions, the specification of structural type
+// restrictions may be arbitrarily complex. For example, consider the
+// following:
+//
+//	type A interface{ ~string|~[]byte }
+//
+//	type B interface{ int|string }
+//
+//	type C interface { ~string|~int }
+//
+//	type T[P interface{ A|B; C }] int
+//
+// In this example, the structural type restriction of P is ~string|int: A|B
+// expands to ~string|~[]byte|int|string, which reduces to ~string|~[]byte|int,
+// which when intersected with C (~string|~int) yields ~string|int.
+//
+// NormalTerms computes these expansions and reductions, producing a
+// "normalized" form of the embeddings. A structural restriction is normalized
+// if it is a single union containing no interface terms, and is minimal in the
+// sense that removing any term changes the set of types satisfying the
+// constraint. It is left as a proof for the reader that, modulo sorting, there
+// is exactly one such normalized form.
+//
+// Because the minimal representation always takes this form, NormalTerms
+// returns a slice of tilde terms corresponding to the terms of the union in
+// the normalized structural restriction. An error is returned if the type is
+// invalid, exceeds complexity bounds, or has an empty type set. In the latter
+// case, NormalTerms returns ErrEmptyTypeSet.
+//
+// NormalTerms makes no guarantees about the order of terms, except that it
+// is deterministic.
+func NormalTerms(typ types.Type) ([]*Term, error) {
+	if tparam, ok := typ.(*TypeParam); ok {
+		constraint := tparam.Constraint()
+		if constraint == nil {
+			return nil, fmt.Errorf("%s has nil constraint", tparam)
+		}
+		iface, _ := constraint.Underlying().(*types.Interface)
+		if iface == nil {
+			return nil, fmt.Errorf("constraint is %T, not *types.Interface", constraint.Underlying())
+		}
+		typ = iface
+	}
+	tset, err := computeTermSetInternal(typ, make(map[types.Type]*termSet), 0)
+	if err != nil {
+		return nil, err
+	}
+	if tset.terms.isEmpty() {
+		return nil, ErrEmptyTypeSet
+	}
+	if tset.terms.isAll() {
+		return nil, nil
+	}
+	var terms []*Term
+	for _, term := range tset.terms {
+		terms = append(terms, NewTerm(term.tilde, term.typ))
+	}
+	return terms, nil
+}
+
+// A termSet holds the normalized set of terms for a given type.
+//
+// The name termSet is intentionally distinct from 'type set': a type set is
+// all types that implement a type (and includes method restrictions), whereas
+// a term set just represents the structural restrictions on a type.
+type termSet struct {
+	complete bool
+	terms    termlist
+}
+
+func indentf(depth int, format string, args ...interface{}) {
+	fmt.Fprintf(os.Stderr, strings.Repeat(".", depth)+format+"\n", args...)
+}
+
+func computeTermSetInternal(t types.Type, seen map[types.Type]*termSet, depth int) (res *termSet, err error) {
+	if t == nil {
+		panic("nil type")
+	}
+
+	if debug {
+		indentf(depth, "%s", t.String())
+		defer func() {
+			if err != nil {
+				indentf(depth, "=> %s", err)
+			} else {
+				indentf(depth, "=> %s", res.terms.String())
+			}
+		}()
+	}
+
+	const maxTermCount = 100
+	if tset, ok := seen[t]; ok {
+		if !tset.complete {
+			return nil, fmt.Errorf("cycle detected in the declaration of %s", t)
+		}
+		return tset, nil
+	}
+
+	// Mark the current type as seen to avoid infinite recursion.
+	tset := new(termSet)
+	defer func() {
+		tset.complete = true
+	}()
+	seen[t] = tset
+
+	switch u := t.Underlying().(type) {
+	case *types.Interface:
+		// The term set of an interface is the intersection of the term sets of its
+		// embedded types.
+		tset.terms = allTermlist
+		for i := 0; i < u.NumEmbeddeds(); i++ {
+			embedded := u.EmbeddedType(i)
+			if _, ok := embedded.Underlying().(*TypeParam); ok {
+				return nil, fmt.Errorf("invalid embedded type %T", embedded)
+			}
+			tset2, err := computeTermSetInternal(embedded, seen, depth+1)
+			if err != nil {
+				return nil, err
+			}
+			tset.terms = tset.terms.intersect(tset2.terms)
+		}
+	case *Union:
+		// The term set of a union is the union of term sets of its terms.
+		tset.terms = nil
+		for i := 0; i < u.Len(); i++ {
+			t := u.Term(i)
+			var terms termlist
+			switch t.Type().Underlying().(type) {
+			case *types.Interface:
+				tset2, err := computeTermSetInternal(t.Type(), seen, depth+1)
+				if err != nil {
+					return nil, err
+				}
+				terms = tset2.terms
+			case *TypeParam, *Union:
+				// A stand-alone type parameter or union is not permitted as union
+				// term.
+				return nil, fmt.Errorf("invalid union term %T", t)
+			default:
+				if t.Type() == types.Typ[types.Invalid] {
+					continue
+				}
+				terms = termlist{{t.Tilde(), t.Type()}}
+			}
+			tset.terms = tset.terms.union(terms)
+			if len(tset.terms) > maxTermCount {
+				return nil, fmt.Errorf("exceeded max term count %d", maxTermCount)
+			}
+		}
+	case *TypeParam:
+		panic("unreachable")
+	default:
+		// For all other types, the term set is just a single non-tilde term
+		// holding the type itself.
+		if u != types.Typ[types.Invalid] {
+			tset.terms = termlist{{false, t}}
+		}
+	}
+	return tset, nil
+}
+
+// under is a facade for the go/types internal function of the same name. It is
+// used by typeterm.go.
+func under(t types.Type) types.Type {
+	return t.Underlying()
+}
@@ -0,0 +1,172 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Code generated by copytermlist.go DO NOT EDIT.
+
+package typeparams
+
+import (
+	"bytes"
+	"go/types"
+)
+
+// A termlist represents the type set represented by the union
+// t1 ∪ y2 ∪ ... tn of the type sets of the terms t1 to tn.
+// A termlist is in normal form if all terms are disjoint.
+// termlist operations don't require the operands to be in
+// normal form.
+type termlist []*term
+
+// allTermlist represents the set of all types.
+// It is in normal form.
+var allTermlist = termlist{new(term)}
+
+// String prints the termlist exactly (without normalization).
+func (xl termlist) String() string {
+	if len(xl) == 0 {
+		return "∅"
+	}
+	var buf bytes.Buffer
+	for i, x := range xl {
+		if i > 0 {
+			buf.WriteString(" ∪ ")
+		}
+		buf.WriteString(x.String())
+	}
+	return buf.String()
+}
+
+// isEmpty reports whether the termlist xl represents the empty set of types.
+func (xl termlist) isEmpty() bool {
+	// If there's a non-nil term, the entire list is not empty.
+	// If the termlist is in normal form, this requires at most
+	// one iteration.
+	for _, x := range xl {
+		if x != nil {
+			return false
+		}
+	}
+	return true
+}
+
+// isAll reports whether the termlist xl represents the set of all types.
+func (xl termlist) isAll() bool {
+	// If there's a 𝓤 term, the entire list is 𝓤.
+	// If the termlist is in normal form, this requires at most
+	// one iteration.
+	for _, x := range xl {
+		if x != nil && x.typ == nil {
+			return true
+		}
+	}
+	return false
+}
+
+// norm returns the normal form of xl.
+func (xl termlist) norm() termlist {
+	// Quadratic algorithm, but good enough for now.
+	// TODO(gri) fix asymptotic performance
+	used := make([]bool, len(xl))
+	var rl termlist
+	for i, xi := range xl {
+		if xi == nil || used[i] {
+			continue
+		}
+		for j := i + 1; j < len(xl); j++ {
+			xj := xl[j]
+			if xj == nil || used[j] {
+				continue
+			}
+			if u1, u2 := xi.union(xj); u2 == nil {
+				// If we encounter a 𝓤 term, the entire list is 𝓤.
+				// Exit early.
+				// (Note that this is not just an optimization;
+				// if we continue, we may end up with a 𝓤 term
+				// and other terms and the result would not be
+				// in normal form.)
+				if u1.typ == nil {
+					return allTermlist
+				}
+				xi = u1
+				used[j] = true // xj is now unioned into xi - ignore it in future iterations
+			}
+		}
+		rl = append(rl, xi)
+	}
+	return rl
+}
+
+// If the type set represented by xl is specified by a single (non-𝓤) term,
+// singleType returns that type. Otherwise it returns nil.
+func (xl termlist) singleType() types.Type {
+	if nl := xl.norm(); len(nl) == 1 {
+		return nl[0].typ // if nl.isAll() then typ is nil, which is ok
+	}
+	return nil
+}
+
+// union returns the union xl ∪ yl.
+func (xl termlist) union(yl termlist) termlist {
+	return append(xl, yl...).norm()
+}
+
+// intersect returns the intersection xl ∩ yl.
+func (xl termlist) intersect(yl termlist) termlist {
+	if xl.isEmpty() || yl.isEmpty() {
+		return nil
+	}
+
+	// Quadratic algorithm, but good enough for now.
+	// TODO(gri) fix asymptotic performance
+	var rl termlist
+	for _, x := range xl {
+		for _, y := range yl {
+			if r := x.intersect(y); r != nil {
+				rl = append(rl, r)
+			}
+		}
+	}
+	return rl.norm()
+}
+
+// equal reports whether xl and yl represent the same type set.
+func (xl termlist) equal(yl termlist) bool {
+	// TODO(gri) this should be more efficient
+	return xl.subsetOf(yl) && yl.subsetOf(xl)
+}
+
+// includes reports whether t ∈ xl.
+func (xl termlist) includes(t types.Type) bool {
+	for _, x := range xl {
+		if x.includes(t) {
+			return true
+		}
+	}
+	return false
+}
+
+// supersetOf reports whether y ⊆ xl.
+func (xl termlist) supersetOf(y *term) bool {
+	for _, x := range xl {
+		if y.subsetOf(x) {
+			return true
+		}
+	}
+	return false
+}
+
+// subsetOf reports whether xl ⊆ yl.
+func (xl termlist) subsetOf(yl termlist) bool {
+	if yl.isEmpty() {
+		return xl.isEmpty()
+	}
+
+	// each term x of xl must be a subset of yl
+	for _, x := range xl {
+		if !yl.supersetOf(x) {
+			return false // x is not a subset yl
+		}
+	}
+	return true
+}
@@ -0,0 +1,201 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+//go:build !go1.18
+
+package typeparams
+
+import (
+	"go/ast"
+	"go/token"
+	"go/types"
+)
+
+const enabled = false
+
+func unsupported() {
+	panic("type parameters are unsupported at this go version")
+}
+
+// IndexListExpr is a placeholder type, as type parameters are not supported at
+// this Go version. Its methods panic on use.
+type IndexListExpr struct {
+	ast.Expr
+	X       ast.Expr   // expression
+	Lbrack  token.Pos  // position of "["
+	Indices []ast.Expr // index expressions
+	Rbrack  token.Pos  // position of "]"
+}
+
+func (*IndexListExpr) Pos() token.Pos { unsupported(); return token.NoPos }
+func (*IndexListExpr) End() token.Pos { unsupported(); return token.NoPos }
+
+// ForTypeSpec returns an empty field list, as type parameters on not supported
+// at this Go version.
+func ForTypeSpec(*ast.TypeSpec) *ast.FieldList {
+	return nil
+}
+
+// ForFuncType returns an empty field list, as type parameters are not
+// supported at this Go version.
+func ForFuncType(*ast.FuncType) *ast.FieldList {
+	return nil
+}
+
+// TypeParam is a placeholder type, as type parameters are not supported at
+// this Go version. Its methods panic on use.
+type TypeParam struct{ types.Type }
+
+func (*TypeParam) String() string           { unsupported(); return "" }
+func (*TypeParam) Underlying() types.Type   { unsupported(); return nil }
+func (*TypeParam) Index() int               { unsupported(); return 0 }
+func (*TypeParam) Constraint() types.Type   { unsupported(); return nil }
+func (*TypeParam) SetConstraint(types.Type) { unsupported() }
+func (*TypeParam) Obj() *types.TypeName     { unsupported(); return nil }
+
+// TypeParamList is a placeholder for an empty type parameter list.
+type TypeParamList struct{}
+
+func (*TypeParamList) Len() int          { return 0 }
+func (*TypeParamList) At(int) *TypeParam { unsupported(); return nil }
+
+// TypeList is a placeholder for an empty type list.
+type TypeList struct{}
+
+func (*TypeList) Len() int          { return 0 }
+func (*TypeList) At(int) types.Type { unsupported(); return nil }
+
+// NewTypeParam is unsupported at this Go version, and panics.
+func NewTypeParam(name *types.TypeName, constraint types.Type) *TypeParam {
+	unsupported()
+	return nil
+}
+
+// NewSignatureType calls types.NewSignature, panicking if recvTypeParams or
+// typeParams is non-empty.
+func NewSignatureType(recv *types.Var, recvTypeParams, typeParams []*TypeParam, params, results *types.Tuple, variadic bool) *types.Signature {
+	if len(recvTypeParams) != 0 || len(typeParams) != 0 {
+		unsupported()
+	}
+	return types.NewSignature(recv, params, results, variadic)
+}
+
+// ForSignature returns an empty slice.
+func ForSignature(*types.Signature) *TypeParamList {
+	return nil
+}
+
+// RecvTypeParams returns a nil slice.
+func RecvTypeParams(sig *types.Signature) *TypeParamList {
+	return nil
+}
+
+// IsComparable returns false, as no interfaces are type-restricted at this Go
+// version.
+func IsComparable(*types.Interface) bool {
+	return false
+}
+
+// IsMethodSet returns true, as no interfaces are type-restricted at this Go
+// version.
+func IsMethodSet(*types.Interface) bool {
+	return true
+}
+
+// IsImplicit returns false, as no interfaces are implicit at this Go version.
+func IsImplicit(*types.Interface) bool {
+	return false
+}
+
+// MarkImplicit does nothing, because this Go version does not have implicit
+// interfaces.
+func MarkImplicit(*types.Interface) {}
+
+// ForNamed returns an empty type parameter list, as type parameters are not
+// supported at this Go version.
+func ForNamed(*types.Named) *TypeParamList {
+	return nil
+}
+
+// SetForNamed panics if tparams is non-empty.
+func SetForNamed(_ *types.Named, tparams []*TypeParam) {
+	if len(tparams) > 0 {
+		unsupported()
+	}
+}
+
+// NamedTypeArgs returns nil.
+func NamedTypeArgs(*types.Named) *TypeList {
+	return nil
+}
+
+// NamedTypeOrigin is the identity method at this Go version.
+func NamedTypeOrigin(named *types.Named) types.Type {
+	return named
+}
+
+// Term holds information about a structural type restriction.
+type Term struct {
+	tilde bool
+	typ   types.Type
+}
+
+func (m *Term) Tilde() bool      { return m.tilde }
+func (m *Term) Type() types.Type { return m.typ }
+func (m *Term) String() string {
+	pre := ""
+	if m.tilde {
+		pre = "~"
+	}
+	return pre + m.typ.String()
+}
+
+// NewTerm creates a new placeholder term type.
+func NewTerm(tilde bool, typ types.Type) *Term {
+	return &Term{tilde, typ}
+}
+
+// Union is a placeholder type, as type parameters are not supported at this Go
+// version. Its methods panic on use.
+type Union struct{ types.Type }
+
+func (*Union) String() string         { unsupported(); return "" }
+func (*Union) Underlying() types.Type { unsupported(); return nil }
+func (*Union) Len() int               { return 0 }
+func (*Union) Term(i int) *Term       { unsupported(); return nil }
+
+// NewUnion is unsupported at this Go version, and panics.
+func NewUnion(terms []*Term) *Union {
+	unsupported()
+	return nil
+}
+
+// InitInstances is a noop at this Go version.
+func InitInstances(*types.Info) {}
+
+// Instance is a placeholder type, as type parameters are not supported at this
+// Go version.
+type Instance struct {
+	TypeArgs *TypeList
+	Type     types.Type
+}
+
+// GetInstances returns a nil map, as type parameters are not supported at this
+// Go version.
+func GetInstances(info *types.Info) map[*ast.Ident]Instance { return nil }
+
+// Context is a placeholder type, as type parameters are not supported at
+// this Go version.
+type Context struct{}
+
+// NewContext returns a placeholder Context instance.
+func NewContext() *Context {
+	return &Context{}
+}
+
+// Instantiate is unsupported on this Go version, and panics.
+func Instantiate(ctxt *Context, typ types.Type, targs []types.Type, validate bool) (types.Type, error) {
+	unsupported()
+	return nil, nil
+}
@@ -0,0 +1,147 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+//go:build go1.18
+
+package typeparams
+
+import (
+	"go/ast"
+	"go/types"
+)
+
+const enabled = true
+
+// IndexListExpr is an alias for ast.IndexListExpr.
+type IndexListExpr = ast.IndexListExpr
+
+// ForTypeSpec returns n.TypeParams.
+func ForTypeSpec(n *ast.TypeSpec) *ast.FieldList {
+	if n == nil {
+		return nil
+	}
+	return n.TypeParams
+}
+
+// ForFuncType returns n.TypeParams.
+func ForFuncType(n *ast.FuncType) *ast.FieldList {
+	if n == nil {
+		return nil
+	}
+	return n.TypeParams
+}
+
+// TypeParam is an alias for types.TypeParam
+type TypeParam = types.TypeParam
+
+// TypeParamList is an alias for types.TypeParamList
+type TypeParamList = types.TypeParamList
+
+// TypeList is an alias for types.TypeList
+type TypeList = types.TypeList
+
+// NewTypeParam calls types.NewTypeParam.
+func NewTypeParam(name *types.TypeName, constraint types.Type) *TypeParam {
+	return types.NewTypeParam(name, constraint)
+}
+
+// NewSignatureType calls types.NewSignatureType.
+func NewSignatureType(recv *types.Var, recvTypeParams, typeParams []*TypeParam, params, results *types.Tuple, variadic bool) *types.Signature {
+	return types.NewSignatureType(recv, recvTypeParams, typeParams, params, results, variadic)
+}
+
+// ForSignature returns sig.TypeParams()
+func ForSignature(sig *types.Signature) *TypeParamList {
+	return sig.TypeParams()
+}
+
+// RecvTypeParams returns sig.RecvTypeParams().
+func RecvTypeParams(sig *types.Signature) *TypeParamList {
+	return sig.RecvTypeParams()
+}
+
+// IsComparable calls iface.IsComparable().
+func IsComparable(iface *types.Interface) bool {
+	return iface.IsComparable()
+}
+
+// IsMethodSet calls iface.IsMethodSet().
+func IsMethodSet(iface *types.Interface) bool {
+	return iface.IsMethodSet()
+}
+
+// IsImplicit calls iface.IsImplicit().
+func IsImplicit(iface *types.Interface) bool {
+	return iface.IsImplicit()
+}
+
+// MarkImplicit calls iface.MarkImplicit().
+func MarkImplicit(iface *types.Interface) {
+	iface.MarkImplicit()
+}
+
+// ForNamed extracts the (possibly empty) type parameter object list from
+// named.
+func ForNamed(named *types.Named) *TypeParamList {
+	return named.TypeParams()
+}
+
+// SetForNamed sets the type params tparams on n. Each tparam must be of
+// dynamic type *types.TypeParam.
+func SetForNamed(n *types.Named, tparams []*TypeParam) {
+	n.SetTypeParams(tparams)
+}
+
+// NamedTypeArgs returns named.TypeArgs().
+func NamedTypeArgs(named *types.Named) *TypeList {
+	return named.TypeArgs()
+}
+
+// NamedTypeOrigin returns named.Orig().
+func NamedTypeOrigin(named *types.Named) types.Type {
+	return named.Origin()
+}
+
+// Term is an alias for types.Term.
+type Term = types.Term
+
+// NewTerm calls types.NewTerm.
+func NewTerm(tilde bool, typ types.Type) *Term {
+	return types.NewTerm(tilde, typ)
+}
+
+// Union is an alias for types.Union
+type Union = types.Union
+
+// NewUnion calls types.NewUnion.
+func NewUnion(terms []*Term) *Union {
+	return types.NewUnion(terms)
+}
+
+// InitInstances initializes info to record information about type and function
+// instances.
+func InitInstances(info *types.Info) {
+	info.Instances = make(map[*ast.Ident]types.Instance)
+}
+
+// Instance is an alias for types.Instance.
+type Instance = types.Instance
+
+// GetInstances returns info.Instances.
+func GetInstances(info *types.Info) map[*ast.Ident]Instance {
+	return info.Instances
+}
+
+// Context is an alias for types.Context.
+type Context = types.Context
+
+// NewContext calls types.NewContext.
+func NewContext() *Context {
+	return types.NewContext()
+}
+
+// Instantiate calls types.Instantiate.
+func Instantiate(ctxt *Context, typ types.Type, targs []types.Type, validate bool) (types.Type, error) {
+	return types.Instantiate(ctxt, typ, targs, validate)
+}
@@ -0,0 +1,169 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Code generated by copytermlist.go DO NOT EDIT.
+
+package typeparams
+
+import "go/types"
+
+// A term describes elementary type sets:
+//
+//	 ∅:  (*term)(nil)     == ∅                      // set of no types (empty set)
+//	 𝓤:  &term{}          == 𝓤                      // set of all types (𝓤niverse)
+//	 T:  &term{false, T}  == {T}                    // set of type T
+//	~t:  &term{true, t}   == {t' | under(t') == t}  // set of types with underlying type t
+type term struct {
+	tilde bool // valid if typ != nil
+	typ   types.Type
+}
+
+func (x *term) String() string {
+	switch {
+	case x == nil:
+		return "∅"
+	case x.typ == nil:
+		return "𝓤"
+	case x.tilde:
+		return "~" + x.typ.String()
+	default:
+		return x.typ.String()
+	}
+}
+
+// equal reports whether x and y represent the same type set.
+func (x *term) equal(y *term) bool {
+	// easy cases
+	switch {
+	case x == nil || y == nil:
+		return x == y
+	case x.typ == nil || y.typ == nil:
+		return x.typ == y.typ
+	}
+	// ∅ ⊂ x, y ⊂ 𝓤
+
+	return x.tilde == y.tilde && types.Identical(x.typ, y.typ)
+}
+
+// union returns the union x ∪ y: zero, one, or two non-nil terms.
+func (x *term) union(y *term) (_, _ *term) {
+	// easy cases
+	switch {
+	case x == nil && y == nil:
+		return nil, nil // ∅ ∪ ∅ == ∅
+	case x == nil:
+		return y, nil // ∅ ∪ y == y
+	case y == nil:
+		return x, nil // x ∪ ∅ == x
+	case x.typ == nil:
+		return x, nil // 𝓤 ∪ y == 𝓤
+	case y.typ == nil:
+		return y, nil // x ∪ 𝓤 == 𝓤
+	}
+	// ∅ ⊂ x, y ⊂ 𝓤
+
+	if x.disjoint(y) {
+		return x, y // x ∪ y == (x, y) if x ∩ y == ∅
+	}
+	// x.typ == y.typ
+
+	// ~t ∪ ~t == ~t
+	// ~t ∪  T == ~t
+	//  T ∪ ~t == ~t
+	//  T ∪  T ==  T
+	if x.tilde || !y.tilde {
+		return x, nil
+	}
+	return y, nil
+}
+
+// intersect returns the intersection x ∩ y.
+func (x *term) intersect(y *term) *term {
+	// easy cases
+	switch {
+	case x == nil || y == nil:
+		return nil // ∅ ∩ y == ∅ and ∩ ∅ == ∅
+	case x.typ == nil:
+		return y // 𝓤 ∩ y == y
+	case y.typ == nil:
+		return x // x ∩ 𝓤 == x
+	}
+	// ∅ ⊂ x, y ⊂ 𝓤
+
+	if x.disjoint(y) {
+		return nil // x ∩ y == ∅ if x ∩ y == ∅
+	}
+	// x.typ == y.typ
+
+	// ~t ∩ ~t == ~t
+	// ~t ∩  T ==  T
+	//  T ∩ ~t ==  T
+	//  T ∩  T ==  T
+	if !x.tilde || y.tilde {
+		return x
+	}
+	return y
+}
+
+// includes reports whether t ∈ x.
+func (x *term) includes(t types.Type) bool {
+	// easy cases
+	switch {
+	case x == nil:
+		return false // t ∈ ∅ == false
+	case x.typ == nil:
+		return true // t ∈ 𝓤 == true
+	}
+	// ∅ ⊂ x ⊂ 𝓤
+
+	u := t
+	if x.tilde {
+		u = under(u)
+	}
+	return types.Identical(x.typ, u)
+}
+
+// subsetOf reports whether x ⊆ y.
+func (x *term) subsetOf(y *term) bool {
+	// easy cases
+	switch {
+	case x == nil:
+		return true // ∅ ⊆ y == true
+	case y == nil:
+		return false // x ⊆ ∅ == false since x != ∅
+	case y.typ == nil:
+		return true // x ⊆ 𝓤 == true
+	case x.typ == nil:
+		return false // 𝓤 ⊆ y == false since y != 𝓤
+	}
+	// ∅ ⊂ x, y ⊂ 𝓤
+
+	if x.disjoint(y) {
+		return false // x ⊆ y == false if x ∩ y == ∅
+	}
+	// x.typ == y.typ
+
+	// ~t ⊆ ~t == true
+	// ~t ⊆ T == false
+	//  T ⊆ ~t == true
+	//  T ⊆  T == true
+	return !x.tilde || y.tilde
+}
+
+// disjoint reports whether x ∩ y == ∅.
+// x.typ and y.typ must not be nil.
+func (x *term) disjoint(y *term) bool {
+	if debug && (x.typ == nil || y.typ == nil) {
+		panic("invalid argument(s)")
+	}
+	ux := x.typ
+	if y.tilde {
+		ux = under(ux)
+	}
+	uy := y.typ
+	if x.tilde {
+		uy = under(uy)
+	}
+	return !types.Identical(ux, uy)
+}
@@ -0,0 +1,269 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package analysis
+
+import (
+	"flag"
+	"fmt"
+	"go/ast"
+	"go/token"
+	"go/types"
+	"reflect"
+	"time"
+)
+
+// An Analyzer describes an analysis function and its options.
+type Analyzer struct {
+	// The Name of the analyzer must be a valid Go identifier
+	// as it may appear in command-line flags, URLs, and so on.
+	Name string
+
+	// Doc is the documentation for the analyzer.
+	// The part before the first "\n\n" is the title
+	// (no capital or period, max ~60 letters).
+	Doc string
+
+	// URL holds an optional link to a web page with additional
+	// documentation for this analyzer.
+	URL string
+
+	// Flags defines any flags accepted by the analyzer.
+	// The manner in which these flags are exposed to the user
+	// depends on the driver which runs the analyzer.
+	Flags flag.FlagSet
+
+	// Run applies the analyzer to a package.
+	// It returns an error if the analyzer failed.
+	//
+	// On success, the Run function may return a result
+	// computed by the Analyzer; its type must match ResultType.
+	// The driver makes this result available as an input to
+	// another Analyzer that depends directly on this one (see
+	// Requires) when it analyzes the same package.
+	//
+	// To pass analysis results between packages (and thus
+	// potentially between address spaces), use Facts, which are
+	// serializable.
+	Run func(*Pass) (any, error)
+
+	// RunDespiteErrors allows the driver to invoke
+	// the Run method of this analyzer even on a
+	// package that contains parse or type errors.
+	// The [Pass.TypeErrors] field may consequently be non-empty.
+	RunDespiteErrors bool
+
+	// Requires is a set of analyzers that must run successfully
+	// before this one on a given package. This analyzer may inspect
+	// the outputs produced by each analyzer in Requires.
+	// The graph over analyzers implied by Requires edges must be acyclic.
+	//
+	// Requires establishes a "horizontal" dependency between
+	// analysis passes (different analyzers, same package).
+	Requires []*Analyzer
+
+	// ResultType is the type of the optional result of the Run function.
+	ResultType reflect.Type
+
+	// FactTypes indicates that this analyzer imports and exports
+	// Facts of the specified concrete types.
+	// An analyzer that uses facts may assume that its import
+	// dependencies have been similarly analyzed before it runs.
+	// Facts must be pointers.
+	//
+	// FactTypes establishes a "vertical" dependency between
+	// analysis passes (same analyzer, different packages).
+	FactTypes []Fact
+}
+
+func (a *Analyzer) String() string { return a.Name }
+
+// A Pass provides information to the Run function that
+// applies a specific analyzer to a single Go package.
+//
+// It forms the interface between the analysis logic and the driver
+// program, and has both input and an output components.
+//
+// As in a compiler, one pass may depend on the result computed by another.
+//
+// The Run function should not call any of the Pass functions concurrently.
+type Pass struct {
+	Analyzer *Analyzer // the identity of the current analyzer
+
+	// syntax and type information
+	Fset         *token.FileSet // file position information; Run may add new files
+	Files        []*ast.File    // the abstract syntax tree of each file
+	OtherFiles   []string       // names of non-Go files of this package
+	IgnoredFiles []string       // names of ignored source files in this package
+	Pkg          *types.Package // type information about the package
+	TypesInfo    *types.Info    // type information about the syntax trees
+	TypesSizes   types.Sizes    // function for computing sizes of types
+	TypeErrors   []types.Error  // type errors (only if Analyzer.RunDespiteErrors)
+
+	Module *Module // the package's enclosing module (possibly nil in some drivers)
+
+	// Report reports a Diagnostic, a finding about a specific location
+	// in the analyzed source code such as a potential mistake.
+	// It may be called by the Run function.
+	Report func(Diagnostic)
+
+	// ResultOf provides the inputs to this analysis pass, which are
+	// the corresponding results of its prerequisite analyzers.
+	// The map keys are the elements of Analysis.Required,
+	// and the type of each corresponding value is the required
+	// analysis's ResultType.
+	ResultOf map[*Analyzer]any
+
+	// ReadFile returns the contents of the named file.
+	//
+	// The only valid file names are the elements of OtherFiles
+	// and IgnoredFiles, and names returned by
+	// Fset.File(f.FileStart).Name() for each f in Files.
+	//
+	// Analyzers must use this function (if provided) instead of
+	// accessing the file system directly. This allows a driver to
+	// provide a virtualized file tree (including, for example,
+	// unsaved editor buffers) and to track dependencies precisely
+	// to avoid unnecessary recomputation.
+	ReadFile func(filename string) ([]byte, error)
+
+	// -- facts --
+
+	// ImportObjectFact retrieves a fact associated with obj.
+	// Given a value ptr of type *T, where *T satisfies Fact,
+	// ImportObjectFact copies the value to *ptr.
+	//
+	// ImportObjectFact panics if called after the pass is complete.
+	// ImportObjectFact is not concurrency-safe.
+	ImportObjectFact func(obj types.Object, fact Fact) bool
+
+	// ImportPackageFact retrieves a fact associated with package pkg,
+	// which must be this package or one of its dependencies.
+	// See comments for ImportObjectFact.
+	ImportPackageFact func(pkg *types.Package, fact Fact) bool
+
+	// ExportObjectFact associates a fact of type *T with the obj,
+	// replacing any previous fact of that type.
+	//
+	// ExportObjectFact panics if it is called after the pass is
+	// complete, or if obj does not belong to the package being analyzed.
+	// ExportObjectFact is not concurrency-safe.
+	ExportObjectFact func(obj types.Object, fact Fact)
+
+	// ExportPackageFact associates a fact with the current package.
+	// See comments for ExportObjectFact.
+	ExportPackageFact func(fact Fact)
+
+	// AllPackageFacts returns a new slice containing all package
+	// facts of the analysis's FactTypes in unspecified order.
+	// See comments for AllObjectFacts.
+	AllPackageFacts func() []PackageFact
+
+	// AllObjectFacts returns a new slice containing all object
+	// facts of the analysis's FactTypes in unspecified order.
+	//
+	// The result includes all facts exported by packages
+	// whose symbols are referenced by the current package
+	// (by qualified identifiers or field/method selections).
+	// And it includes all facts exported from the current
+	// package by the current analysis pass.
+	AllObjectFacts func() []ObjectFact
+
+	/* Further fields may be added in future. */
+}
+
+// PackageFact is a package together with an associated fact.
+type PackageFact struct {
+	Package *types.Package
+	Fact    Fact
+}
+
+// ObjectFact is an object together with an associated fact.
+type ObjectFact struct {
+	Object types.Object
+	Fact   Fact
+}
+
+// Reportf is a helper function that reports a Diagnostic using the
+// specified position and formatted error message.
+func (pass *Pass) Reportf(pos token.Pos, format string, args ...any) {
+	msg := fmt.Sprintf(format, args...)
+	pass.Report(Diagnostic{Pos: pos, Message: msg})
+}
+
+// The Range interface provides a range. It's equivalent to and satisfied by
+// ast.Node.
+type Range interface {
+	Pos() token.Pos // position of first character belonging to the node
+	End() token.Pos // position of first character immediately after the node
+}
+
+// ReportRangef is a helper function that reports a Diagnostic using the
+// range provided. ast.Node values can be passed in as the range because
+// they satisfy the Range interface.
+func (pass *Pass) ReportRangef(rng Range, format string, args ...any) {
+	msg := fmt.Sprintf(format, args...)
+	pass.Report(Diagnostic{Pos: rng.Pos(), End: rng.End(), Message: msg})
+}
+
+func (pass *Pass) String() string {
+	return fmt.Sprintf("%s@%s", pass.Analyzer.Name, pass.Pkg.Path())
+}
+
+// A Fact is an intermediate fact produced during analysis.
+//
+// Each fact is associated with a named declaration (a types.Object) or
+// with a package as a whole. A single object or package may have
+// multiple associated facts, but only one of any particular fact type.
+//
+// A Fact represents a predicate such as "never returns", but does not
+// represent the subject of the predicate such as "function F" or "package P".
+//
+// Facts may be produced in one analysis pass and consumed by another
+// analysis pass even if these are in different address spaces.
+// If package P imports Q, all facts about Q produced during
+// analysis of that package will be available during later analysis of P.
+// Facts are analogous to type export data in a build system:
+// just as export data enables separate compilation of several passes,
+// facts enable "separate analysis".
+//
+// Each pass (a, p) starts with the set of facts produced by the
+// same analyzer a applied to the packages directly imported by p.
+// The analysis may add facts to the set, and they may be exported in turn.
+// An analysis's Run function may retrieve facts by calling
+// Pass.Import{Object,Package}Fact and update them using
+// Pass.Export{Object,Package}Fact.
+//
+// A fact is logically private to its Analysis. To pass values
+// between different analyzers, use the results mechanism;
+// see Analyzer.Requires, Analyzer.ResultType, and Pass.ResultOf.
+//
+// A Fact type must be a pointer.
+// Facts are encoded and decoded using encoding/gob.
+// A Fact may implement the GobEncoder/GobDecoder interfaces
+// to customize its encoding. Fact encoding should not fail.
+//
+// A Fact should not be modified once exported.
+type Fact interface {
+	AFact() // dummy method to avoid type errors
+}
+
+// A Module describes the module to which a package belongs.
+type Module struct {
+	Path      string       // module path
+	Version   string       // module version ("" if unknown, such as for workspace modules)
+	Replace   *Module      // replaced by this module
+	Time      *time.Time   // time version was created
+	Main      bool         // is this the main module?
+	Indirect  bool         // is this module only an indirect dependency of main module?
+	Dir       string       // directory holding files for this module, if any
+	GoMod     string       // path to go.mod file used when loading this module, if any
+	GoVersion string       // go version used in module (e.g. "go1.22.0")
+	Error     *ModuleError // error loading module
+}
+
+// ModuleError holds errors loading a module.
+type ModuleError struct {
+	Err string // the error itself
+}
@@ -0,0 +1,88 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package analysis
+
+import "go/token"
+
+// A Diagnostic is a message associated with a source location or range.
+//
+// An Analyzer may return a variety of diagnostics; the optional Category,
+// which should be a constant, may be used to classify them.
+// It is primarily intended to make it easy to look up documentation.
+//
+// All Pos values are interpreted relative to Pass.Fset. If End is
+// provided, the diagnostic is specified to apply to the range between
+// Pos and End.
+type Diagnostic struct {
+	Pos      token.Pos
+	End      token.Pos // optional
+	Category string    // optional
+	Message  string
+
+	// URL is the optional location of a web page that provides
+	// additional documentation for this diagnostic.
+	//
+	// If URL is empty but a Category is specified, then the
+	// Analysis driver should treat the URL as "#"+Category.
+	//
+	// The URL may be relative. If so, the base URL is that of the
+	// Analyzer that produced the diagnostic;
+	// see https://pkg.go.dev/net/url#URL.ResolveReference.
+	URL string
+
+	// SuggestedFixes is an optional list of fixes to address the
+	// problem described by the diagnostic. Each one represents an
+	// alternative strategy, and should have a distinct and
+	// descriptive message; at most one may be applied.
+	//
+	// Fixes for different diagnostics should be treated as
+	// independent changes to the same baseline file state,
+	// analogous to a set of git commits all with the same parent.
+	// Combining fixes requires resolving any conflicts that
+	// arise, analogous to a git merge.
+	// Any conflicts that remain may be dealt with, depending on
+	// the tool, by discarding fixes, consulting the user, or
+	// aborting the operation.
+	SuggestedFixes []SuggestedFix
+
+	// Related contains optional secondary positions and messages
+	// related to the primary diagnostic.
+	Related []RelatedInformation
+}
+
+// RelatedInformation contains information related to a diagnostic.
+// For example, a diagnostic that flags duplicated declarations of a
+// variable may include one RelatedInformation per existing
+// declaration.
+type RelatedInformation struct {
+	Pos     token.Pos
+	End     token.Pos // optional
+	Message string
+}
+
+// A SuggestedFix is a code change associated with a Diagnostic that a
+// user can choose to apply to their code. Usually the SuggestedFix is
+// meant to fix the issue flagged by the diagnostic.
+//
+// The TextEdits must not overlap, nor contain edits for other
+// packages. Edits need not be totally ordered, but the order
+// determines how insertions at the same point will be applied.
+type SuggestedFix struct {
+	// A verb phrase describing the fix, to be shown to
+	// a user trying to decide whether to accept it.
+	//
+	// Example: "Remove the surplus argument"
+	Message   string
+	TextEdits []TextEdit
+}
+
+// A TextEdit represents the replacement of the code between Pos and End with the new text.
+// Each TextEdit should apply to a single file. End should not be earlier in the file than Pos.
+type TextEdit struct {
+	// For a pure insertion, End can either be set to Pos or token.NoPos.
+	Pos     token.Pos
+	End     token.Pos
+	NewText []byte
+}
@@ -0,0 +1,317 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package analysis defines the interface between a modular static
+analysis and an analysis driver program.
+
+# Background
+
+A static analysis is a function that inspects a package of Go code and
+reports a set of diagnostics (typically mistakes in the code), and
+perhaps produces other results as well, such as suggested refactorings
+or other facts. An analysis that reports mistakes is informally called a
+"checker". For example, the printf checker reports mistakes in
+fmt.Printf format strings.
+
+A "modular" analysis is one that inspects one package at a time but can
+save information from a lower-level package and use it when inspecting a
+higher-level package, analogous to separate compilation in a toolchain.
+The printf checker is modular: when it discovers that a function such as
+log.Fatalf delegates to fmt.Printf, it records this fact, and checks
+calls to that function too, including calls made from another package.
+
+By implementing a common interface, checkers from a variety of sources
+can be easily selected, incorporated, and reused in a wide range of
+driver programs including command-line tools (such as vet), text editors and
+IDEs, build and test systems (such as go build, Bazel, or Buck), test
+frameworks, code review tools, code-base indexers (such as SourceGraph),
+documentation viewers (such as godoc), batch pipelines for large code
+bases, and so on.
+
+# Analyzer
+
+The primary type in the API is [Analyzer]. An Analyzer statically
+describes an analysis function: its name, documentation, flags,
+relationship to other analyzers, and of course, its logic.
+
+To define an analysis, a user declares a (logically constant) variable
+of type Analyzer. Here is a typical example from one of the analyzers in
+the go/analysis/passes/ subdirectory:
+
+	package unusedresult
+
+	var Analyzer = &analysis.Analyzer{
+		Name: "unusedresult",
+		Doc:  "check for unused results of calls to some functions",
+		Run:  run,
+		...
+	}
+
+	func run(pass *analysis.Pass) (interface{}, error) {
+		...
+	}
+
+An analysis driver is a program such as vet that runs a set of
+analyses and prints the diagnostics that they report.
+The driver program must import the list of Analyzers it needs.
+Typically each Analyzer resides in a separate package.
+To add a new Analyzer to an existing driver, add another item to the list:
+
+	import ( "unusedresult"; "nilness"; "printf" )
+
+	var analyses = []*analysis.Analyzer{
+		unusedresult.Analyzer,
+		nilness.Analyzer,
+		printf.Analyzer,
+	}
+
+A driver may use the name, flags, and documentation to provide on-line
+help that describes the analyses it performs.
+The doc comment contains a brief one-line summary,
+optionally followed by paragraphs of explanation.
+
+The [Analyzer] type has more fields besides those shown above:
+
+	type Analyzer struct {
+		Name             string
+		Doc              string
+		Flags            flag.FlagSet
+		Run              func(*Pass) (interface{}, error)
+		RunDespiteErrors bool
+		ResultType       reflect.Type
+		Requires         []*Analyzer
+		FactTypes        []Fact
+	}
+
+The Flags field declares a set of named (global) flag variables that
+control analysis behavior. Unlike vet, analysis flags are not declared
+directly in the command line FlagSet; it is up to the driver to set the
+flag variables. A driver for a single analysis, a, might expose its flag
+f directly on the command line as -f, whereas a driver for multiple
+analyses might prefix the flag name by the analysis name (-a.f) to avoid
+ambiguity. An IDE might expose the flags through a graphical interface,
+and a batch pipeline might configure them from a config file.
+See the "findcall" analyzer for an example of flags in action.
+
+The RunDespiteErrors flag indicates whether the analysis is equipped to
+handle ill-typed code. If not, the driver will skip the analysis if
+there were parse or type errors.
+The optional ResultType field specifies the type of the result value
+computed by this analysis and made available to other analyses.
+The Requires field specifies a list of analyses upon which
+this one depends and whose results it may access, and it constrains the
+order in which a driver may run analyses.
+The FactTypes field is discussed in the section on Modularity.
+The analysis package provides a Validate function to perform basic
+sanity checks on an Analyzer, such as that its Requires graph is
+acyclic, its fact and result types are unique, and so on.
+
+Finally, the Run field contains a function to be called by the driver to
+execute the analysis on a single package. The driver passes it an
+instance of the Pass type.
+
+# Pass
+
+A [Pass] describes a single unit of work: the application of a particular
+Analyzer to a particular package of Go code.
+The Pass provides information to the Analyzer's Run function about the
+package being analyzed, and provides operations to the Run function for
+reporting diagnostics and other information back to the driver.
+
+	type Pass struct {
+		Fset         *token.FileSet
+		Files        []*ast.File
+		OtherFiles   []string
+		IgnoredFiles []string
+		Pkg          *types.Package
+		TypesInfo    *types.Info
+		ResultOf     map[*Analyzer]interface{}
+		Report       func(Diagnostic)
+		...
+	}
+
+The Fset, Files, Pkg, and TypesInfo fields provide the syntax trees,
+type information, and source positions for a single package of Go code.
+
+The OtherFiles field provides the names of non-Go
+files such as assembly that are part of this package.
+Similarly, the IgnoredFiles field provides the names of Go and non-Go
+source files that are not part of this package with the current build
+configuration but may be part of other build configurations.
+The contents of these files may be read using Pass.ReadFile;
+see the "asmdecl" or "buildtags" analyzers for examples of loading
+non-Go files and reporting diagnostics against them.
+
+The ResultOf field provides the results computed by the analyzers
+required by this one, as expressed in its Analyzer.Requires field. The
+driver runs the required analyzers first and makes their results
+available in this map. Each Analyzer must return a value of the type
+described in its Analyzer.ResultType field.
+For example, the "ctrlflow" analyzer returns a *ctrlflow.CFGs, which
+provides a control-flow graph for each function in the package (see
+golang.org/x/tools/go/cfg); the "inspect" analyzer returns a value that
+enables other Analyzers to traverse the syntax trees of the package more
+efficiently; and the "buildssa" analyzer constructs an SSA-form
+intermediate representation.
+Each of these Analyzers extends the capabilities of later Analyzers
+without adding a dependency to the core API, so an analysis tool pays
+only for the extensions it needs.
+
+The Report function emits a diagnostic, a message associated with a
+source position. For most analyses, diagnostics are their primary
+result.
+For convenience, Pass provides a helper method, Reportf, to report a new
+diagnostic by formatting a string.
+Diagnostic is defined as:
+
+	type Diagnostic struct {
+		Pos      token.Pos
+		Category string // optional
+		Message  string
+	}
+
+The optional Category field is a short identifier that classifies the
+kind of message when an analysis produces several kinds of diagnostic.
+
+The [Diagnostic] struct does not have a field to indicate its severity
+because opinions about the relative importance of Analyzers and their
+diagnostics vary widely among users. The design of this framework does
+not hold each Analyzer responsible for identifying the severity of its
+diagnostics. Instead, we expect that drivers will allow the user to
+customize the filtering and prioritization of diagnostics based on the
+producing Analyzer and optional Category, according to the user's
+preferences.
+
+Most Analyzers inspect typed Go syntax trees, but a few, such as asmdecl
+and buildtag, inspect the raw text of Go source files or even non-Go
+files such as assembly. To report a diagnostic against a line of a
+raw text file, use the following sequence:
+
+	content, err := pass.ReadFile(filename)
+	if err != nil { ... }
+	tf := fset.AddFile(filename, -1, len(content))
+	tf.SetLinesForContent(content)
+	...
+	pass.Reportf(tf.LineStart(line), "oops")
+
+# Modular analysis with Facts
+
+To improve efficiency and scalability, large programs are routinely
+built using separate compilation: units of the program are compiled
+separately, and recompiled only when one of their dependencies changes;
+independent modules may be compiled in parallel. The same technique may
+be applied to static analyses, for the same benefits. Such analyses are
+described as "modular".
+
+A compiler’s type checker is an example of a modular static analysis.
+Many other checkers we would like to apply to Go programs can be
+understood as alternative or non-standard type systems. For example,
+vet's printf checker infers whether a function has the "printf wrapper"
+type, and it applies stricter checks to calls of such functions. In
+addition, it records which functions are printf wrappers for use by
+later analysis passes to identify other printf wrappers by induction.
+A result such as “f is a printf wrapper” that is not interesting by
+itself but serves as a stepping stone to an interesting result (such as
+a diagnostic) is called a [Fact].
+
+The analysis API allows an analysis to define new types of facts, to
+associate facts of these types with objects (named entities) declared
+within the current package, or with the package as a whole, and to query
+for an existing fact of a given type associated with an object or
+package.
+
+An Analyzer that uses facts must declare their types:
+
+	var Analyzer = &analysis.Analyzer{
+		Name:      "printf",
+		FactTypes: []analysis.Fact{new(isWrapper)},
+		...
+	}
+
+	type isWrapper struct{} // => *types.Func f “is a printf wrapper”
+
+The driver program ensures that facts for a pass’s dependencies are
+generated before analyzing the package and is responsible for propagating
+facts from one package to another, possibly across address spaces.
+Consequently, Facts must be serializable. The API requires that drivers
+use the gob encoding, an efficient, robust, self-describing binary
+protocol. A fact type may implement the GobEncoder/GobDecoder interfaces
+if the default encoding is unsuitable. Facts should be stateless.
+Because serialized facts may appear within build outputs, the gob encoding
+of a fact must be deterministic, to avoid spurious cache misses in
+build systems that use content-addressable caches.
+The driver makes a single call to the gob encoder for all facts
+exported by a given analysis pass, so that the topology of
+shared data structures referenced by multiple facts is preserved.
+
+The Pass type has functions to import and export facts,
+associated either with an object or with a package:
+
+	type Pass struct {
+		...
+		ExportObjectFact func(types.Object, Fact)
+		ImportObjectFact func(types.Object, Fact) bool
+
+		ExportPackageFact func(fact Fact)
+		ImportPackageFact func(*types.Package, Fact) bool
+	}
+
+An Analyzer may only export facts associated with the current package or
+its objects, though it may import facts from any package or object that
+is an import dependency of the current package.
+
+Conceptually, ExportObjectFact(obj, fact) inserts fact into a hidden map keyed by
+the pair (obj, TypeOf(fact)), and the ImportObjectFact function
+retrieves the entry from this map and copies its value into the variable
+pointed to by fact. This scheme assumes that the concrete type of fact
+is a pointer; this assumption is checked by the Validate function.
+See the "printf" analyzer for an example of object facts in action.
+
+Some driver implementations (such as those based on Bazel and Blaze) do
+not currently apply analyzers to packages of the standard library.
+Therefore, for best results, analyzer authors should not rely on
+analysis facts being available for standard packages.
+For example, although the printf checker is capable of deducing during
+analysis of the log package that log.Printf is a printf wrapper,
+this fact is built in to the analyzer so that it correctly checks
+calls to log.Printf even when run in a driver that does not apply
+it to standard packages. We would like to remove this limitation in future.
+
+# Testing an Analyzer
+
+The analysistest subpackage provides utilities for testing an Analyzer.
+In a few lines of code, it is possible to run an analyzer on a package
+of testdata files and check that it reported all the expected
+diagnostics and facts (and no more). Expectations are expressed using
+"// want ..." comments in the input code.
+
+# Standalone commands
+
+Analyzers are provided in the form of packages that a driver program is
+expected to import. The vet command imports a set of several analyzers,
+but users may wish to define their own analysis commands that perform
+additional checks. To simplify the task of creating an analysis command,
+either for a single analyzer or for a whole suite, we provide the
+singlechecker and multichecker subpackages.
+
+The singlechecker package provides the main function for a command that
+runs one analyzer. By convention, each analyzer such as
+go/analysis/passes/findcall should be accompanied by a singlechecker-based
+command such as go/analysis/passes/findcall/cmd/findcall, defined in its
+entirety as:
+
+	package main
+
+	import (
+		"golang.org/x/tools/go/analysis/passes/findcall"
+		"golang.org/x/tools/go/analysis/singlechecker"
+	)
+
+	func main() { singlechecker.Main(findcall.Analyzer) }
+
+A tool that provides multiple analyzers can use multichecker in a
+similar way, giving it the list of Analyzers.
+*/
+package analysis
@@ -0,0 +1,278 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package ctrlflow is an analysis that provides a syntactic
+// control-flow graph (CFG) for the body of a function.
+// It records whether a function cannot return.
+// By itself, it does not report any diagnostics.
+package ctrlflow
+
+import (
+	"go/ast"
+	"go/types"
+	"log"
+	"reflect"
+
+	"golang.org/x/tools/go/analysis"
+	"golang.org/x/tools/go/analysis/passes/inspect"
+	"golang.org/x/tools/go/ast/inspector"
+	"golang.org/x/tools/go/cfg"
+	"golang.org/x/tools/go/types/typeutil"
+	"golang.org/x/tools/internal/typesinternal"
+)
+
+var Analyzer = &analysis.Analyzer{
+	Name:       "ctrlflow",
+	Doc:        "build a control-flow graph",
+	URL:        "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/ctrlflow",
+	Run:        run,
+	ResultType: reflect.TypeFor[*CFGs](),
+	FactTypes:  []analysis.Fact{new(noReturn)},
+	Requires:   []*analysis.Analyzer{inspect.Analyzer},
+}
+
+// noReturn is a fact indicating that a function does not return.
+type noReturn struct{}
+
+func (*noReturn) AFact() {}
+
+func (*noReturn) String() string { return "noReturn" }
+
+// A CFGs holds the control-flow graphs
+// for all the functions of the current package.
+type CFGs struct {
+	defs      map[*ast.Ident]types.Object // from Pass.TypesInfo.Defs
+	funcDecls map[*types.Func]*declInfo
+	funcLits  map[*ast.FuncLit]*litInfo
+	noReturn  map[*types.Func]bool // functions lacking a reachable return statement
+	pass      *analysis.Pass       // transient; nil after construction
+}
+
+// NoReturn reports whether the specified control-flow graph cannot return normally.
+//
+// It is defined for at least all function symbols that appear as the static callee of a
+// CallExpr in the current package, even if the callee was imported from a dependency.
+//
+// The result may incorporate interprocedural information based on induction of
+// the "no return" property over the static call graph within the package.
+// For example, if f simply calls g and g always calls os.Exit, then both f and g may
+// be deemed never to return.
+func (c *CFGs) NoReturn(fn *types.Func) bool {
+	return c.noReturn[fn]
+}
+
+// CFGs has two maps: funcDecls for named functions and funcLits for
+// unnamed ones. Unlike funcLits, the funcDecls map is not keyed by its
+// syntax node, *ast.FuncDecl, because callMayReturn needs to do a
+// look-up by *types.Func, and you can get from an *ast.FuncDecl to a
+// *types.Func but not the other way.
+
+type declInfo struct {
+	decl    *ast.FuncDecl
+	cfg     *cfg.CFG // iff decl.Body != nil
+	started bool     // to break cycles
+}
+
+type litInfo struct {
+	cfg      *cfg.CFG
+	noReturn bool // (currently unused)
+}
+
+// FuncDecl returns the control-flow graph for a named function.
+// It returns nil if decl.Body==nil.
+func (c *CFGs) FuncDecl(decl *ast.FuncDecl) *cfg.CFG {
+	if decl.Body == nil {
+		return nil
+	}
+	fn := c.defs[decl.Name].(*types.Func)
+	return c.funcDecls[fn].cfg
+}
+
+// FuncLit returns the control-flow graph for a literal function.
+func (c *CFGs) FuncLit(lit *ast.FuncLit) *cfg.CFG {
+	return c.funcLits[lit].cfg
+}
+
+func run(pass *analysis.Pass) (any, error) {
+	inspect := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
+
+	// Because CFG construction consumes and produces noReturn
+	// facts, CFGs for exported FuncDecls must be built before 'run'
+	// returns; we cannot construct them lazily.
+	// (We could build CFGs for FuncLits lazily,
+	// but the benefit is marginal.)
+
+	// Pass 1. Map types.Funcs to ast.FuncDecls in this package.
+	funcDecls := make(map[*types.Func]*declInfo) // functions and methods
+	funcLits := make(map[*ast.FuncLit]*litInfo)
+
+	var decls []*types.Func // keys(funcDecls), in order
+	var lits []*ast.FuncLit // keys(funcLits), in order
+
+	nodeFilter := []ast.Node{
+		(*ast.FuncDecl)(nil),
+		(*ast.FuncLit)(nil),
+	}
+	inspect.Preorder(nodeFilter, func(n ast.Node) {
+		switch n := n.(type) {
+		case *ast.FuncDecl:
+			// Type information may be incomplete.
+			if fn, ok := pass.TypesInfo.Defs[n.Name].(*types.Func); ok {
+				funcDecls[fn] = &declInfo{decl: n}
+				decls = append(decls, fn)
+			}
+		case *ast.FuncLit:
+			funcLits[n] = new(litInfo)
+			lits = append(lits, n)
+		}
+	})
+
+	c := &CFGs{
+		defs:      pass.TypesInfo.Defs,
+		funcDecls: funcDecls,
+		funcLits:  funcLits,
+		noReturn:  make(map[*types.Func]bool),
+		pass:      pass,
+	}
+
+	// Pass 2. Build CFGs.
+
+	// Build CFGs for named functions.
+	// Cycles in the static call graph are broken
+	// arbitrarily but deterministically.
+	// We create noReturn facts as discovered.
+	for _, fn := range decls {
+		c.buildDecl(fn, funcDecls[fn])
+	}
+
+	// Build CFGs for literal functions.
+	// These aren't relevant to facts (since they aren't named)
+	// but are required for the CFGs.FuncLit API.
+	for _, lit := range lits {
+		li := funcLits[lit]
+		if li.cfg == nil {
+			li.cfg = cfg.New(lit.Body, c.callMayReturn)
+			if li.cfg.NoReturn() {
+				li.noReturn = true
+			}
+		}
+	}
+
+	// All CFGs are now built.
+	c.pass = nil
+
+	return c, nil
+}
+
+// di.cfg may be nil on return.
+func (c *CFGs) buildDecl(fn *types.Func, di *declInfo) {
+	// buildDecl may call itself recursively for the same function,
+	// because cfg.New is passed the callMayReturn method, which
+	// builds the CFG of the callee, leading to recursion.
+	// The buildDecl call tree thus resembles the static call graph.
+	// We mark each node when we start working on it to break cycles.
+
+	if di.started {
+		return // break cycle
+	}
+	di.started = true
+
+	noreturn, known := knownIntrinsic(fn)
+	if !known {
+		if di.decl.Body != nil {
+			di.cfg = cfg.New(di.decl.Body, c.callMayReturn)
+			if di.cfg.NoReturn() {
+				noreturn = true
+			}
+		}
+	}
+	if noreturn {
+		c.pass.ExportObjectFact(fn, new(noReturn))
+		c.noReturn[fn] = true
+	}
+
+	// debugging
+	if false {
+		log.Printf("CFG for %s:\n%s (noreturn=%t)\n", fn, di.cfg.Format(c.pass.Fset), noreturn)
+	}
+}
+
+// callMayReturn reports whether the called function may return.
+// It is passed to the CFG builder.
+func (c *CFGs) callMayReturn(call *ast.CallExpr) (r bool) {
+	if id, ok := call.Fun.(*ast.Ident); ok && c.pass.TypesInfo.Uses[id] == panicBuiltin {
+		return false // panic never returns
+	}
+
+	// Is this a static call? Also includes static functions
+	// parameterized by a type. Such functions may or may not
+	// return depending on the parameter type, but in some
+	// cases the answer is definite. We let ctrlflow figure
+	// that out.
+	fn := typeutil.StaticCallee(c.pass.TypesInfo, call)
+	if fn == nil {
+		return true // callee not statically known; be conservative
+	}
+
+	// Function or method declared in this package?
+	if di, ok := c.funcDecls[fn]; ok {
+		c.buildDecl(fn, di)
+		return !c.noReturn[fn]
+	}
+
+	// Not declared in this package.
+	// Is there a fact from another package?
+	if c.pass.ImportObjectFact(fn, new(noReturn)) {
+		c.noReturn[fn] = true
+		return false
+	}
+
+	return true
+}
+
+var panicBuiltin = types.Universe.Lookup("panic").(*types.Builtin)
+
+// knownIntrinsic reports whether a function intrinsically never
+// returns because it stops execution of the calling thread, or does
+// in fact return, contrary to its apparent body, because it is
+// handled specially by the compiler.
+//
+// It is the base case in the recursion.
+func knownIntrinsic(fn *types.Func) (noreturn, known bool) {
+	// Add functions here as the need arises, but don't allocate memory.
+
+	// Functions known intrinsically never to return.
+	if typesinternal.IsFunctionNamed(fn, "syscall", "Exit", "ExitProcess", "ExitThread") ||
+		typesinternal.IsFunctionNamed(fn, "runtime", "Goexit", "fatalthrow", "fatalpanic", "exit") ||
+		// Following staticcheck (see go/ir/exits.go) we include functions
+		// in several popular logging packages whose no-return status is
+		// beyond the analysis to infer.
+		// TODO(adonovan): make this list extensible.
+		typesinternal.IsMethodNamed(fn, "go.uber.org/zap", "Logger", "Fatal", "Panic") ||
+		typesinternal.IsMethodNamed(fn, "go.uber.org/zap", "SugaredLogger", "Fatal", "Fatalw", "Fatalf", "Panic", "Panicw", "Panicf") ||
+		typesinternal.IsMethodNamed(fn, "github.com/sirupsen/logrus", "Logger", "Exit", "Panic", "Panicf", "Panicln") ||
+		typesinternal.IsMethodNamed(fn, "github.com/sirupsen/logrus", "Entry", "Panicf", "Panicln") ||
+		typesinternal.IsFunctionNamed(fn, "k8s.io/klog", "Exit", "ExitDepth", "Exitf", "Exitln", "Fatal", "FatalDepth", "Fatalf", "Fatalln") ||
+		typesinternal.IsFunctionNamed(fn, "k8s.io/klog/v2", "Exit", "ExitDepth", "Exitf", "Exitln", "Fatal", "FatalDepth", "Fatalf", "Fatalln") {
+		return true, true
+	}
+
+	// Compiler intrinsics known to return, contrary to
+	// what analysis of the function body would conclude.
+	//
+	// Not all such intrinsics must be listed here: ctrlflow
+	// considers any function called for its value--such as
+	// crypto/internal/constanttime.bool2Uint8--to potentially
+	// return; only functions called as a statement, for effects,
+	// are no-return candidates.
+	//
+	// Unfortunately this does sometimes mean peering into internals.
+	// Where possible, use the nearest enclosing public API function.
+	if typesinternal.IsFunctionNamed(fn, "internal/abi", "EscapeNonString") ||
+		typesinternal.IsFunctionNamed(fn, "hash/maphash", "Comparable") {
+		return false, true
+	}
+
+	return // unknown
+}
@@ -0,0 +1,49 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package inspect defines an Analyzer that provides an AST inspector
+// (golang.org/x/tools/go/ast/inspector.Inspector) for the syntax trees
+// of a package. It is only a building block for other analyzers.
+//
+// Example of use in another analysis:
+//
+//	import (
+//		"golang.org/x/tools/go/analysis"
+//		"golang.org/x/tools/go/analysis/passes/inspect"
+//		"golang.org/x/tools/go/ast/inspector"
+//	)
+//
+//	var Analyzer = &analysis.Analyzer{
+//		...
+//		Requires:       []*analysis.Analyzer{inspect.Analyzer},
+//	}
+//
+//	func run(pass *analysis.Pass) (interface{}, error) {
+//		inspect := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
+//		inspect.Preorder(nil, func(n ast.Node) {
+//			...
+//		})
+//		return nil, nil
+//	}
+package inspect
+
+import (
+	"reflect"
+
+	"golang.org/x/tools/go/analysis"
+	"golang.org/x/tools/go/ast/inspector"
+)
+
+var Analyzer = &analysis.Analyzer{
+	Name:             "inspect",
+	Doc:              "optimize AST traversal for later passes",
+	URL:              "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/inspect",
+	Run:              run,
+	RunDespiteErrors: true,
+	ResultType:       reflect.TypeFor[*inspector.Inspector](),
+}
+
+func run(pass *analysis.Pass) (any, error) {
+	return inspector.New(pass.Files), nil
+}
@@ -0,0 +1,137 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package analysis
+
+import (
+	"fmt"
+	"reflect"
+	"strings"
+	"unicode"
+)
+
+// Validate reports an error if any of the analyzers are misconfigured.
+// Checks include:
+// that the name is a valid identifier;
+// that the Doc is not empty;
+// that the Run is non-nil;
+// that the Requires graph is acyclic;
+// that analyzer fact types are unique;
+// that each fact type is a pointer.
+//
+// Analyzer names need not be unique, though this may be confusing.
+func Validate(analyzers []*Analyzer) error {
+	// Map each fact type to its sole generating analyzer.
+	factTypes := make(map[reflect.Type]*Analyzer)
+
+	// Traverse the Requires graph, depth first.
+	const (
+		white = iota
+		grey
+		black
+		finished
+	)
+	color := make(map[*Analyzer]uint8)
+	var visit func(a *Analyzer) error
+	visit = func(a *Analyzer) error {
+		if a == nil {
+			return fmt.Errorf("nil *Analyzer")
+		}
+		if color[a] == white {
+			color[a] = grey
+
+			// names
+			if !validIdent(a.Name) {
+				return fmt.Errorf("invalid analyzer name %q", a)
+			}
+
+			if a.Doc == "" {
+				return fmt.Errorf("analyzer %q is undocumented", a)
+			}
+
+			if a.Run == nil {
+				return fmt.Errorf("analyzer %q has nil Run", a)
+			}
+			// fact types
+			for _, f := range a.FactTypes {
+				if f == nil {
+					return fmt.Errorf("analyzer %s has nil FactType", a)
+				}
+				t := reflect.TypeOf(f)
+				if prev := factTypes[t]; prev != nil {
+					return fmt.Errorf("fact type %s registered by two analyzers: %v, %v",
+						t, a, prev)
+				}
+				if t.Kind() != reflect.Pointer {
+					return fmt.Errorf("%s: fact type %s is not a pointer", a, t)
+				}
+				factTypes[t] = a
+			}
+
+			// recursion
+			for _, req := range a.Requires {
+				if err := visit(req); err != nil {
+					return err
+				}
+			}
+			color[a] = black
+		}
+
+		if color[a] == grey {
+			stack := []*Analyzer{a}
+			inCycle := map[string]bool{}
+			for len(stack) > 0 {
+				current := stack[len(stack)-1]
+				stack = stack[:len(stack)-1]
+				if color[current] == grey && !inCycle[current.Name] {
+					inCycle[current.Name] = true
+					stack = append(stack, current.Requires...)
+				}
+			}
+			return &CycleInRequiresGraphError{AnalyzerNames: inCycle}
+		}
+
+		return nil
+	}
+	for _, a := range analyzers {
+		if err := visit(a); err != nil {
+			return err
+		}
+	}
+
+	// Reject duplicates among analyzers.
+	// Precondition:  color[a] == black.
+	// Postcondition: color[a] == finished.
+	for _, a := range analyzers {
+		if color[a] == finished {
+			return fmt.Errorf("duplicate analyzer: %s", a.Name)
+		}
+		color[a] = finished
+	}
+
+	return nil
+}
+
+func validIdent(name string) bool {
+	for i, r := range name {
+		if !(r == '_' || unicode.IsLetter(r) || i > 0 && unicode.IsDigit(r)) {
+			return false
+		}
+	}
+	return name != ""
+}
+
+type CycleInRequiresGraphError struct {
+	AnalyzerNames map[string]bool
+}
+
+func (e *CycleInRequiresGraphError) Error() string {
+	var b strings.Builder
+	b.WriteString("cycle detected involving the following analyzers:")
+	for n := range e.AnalyzerNames {
+		b.WriteByte(' ')
+		b.WriteString(n)
+	}
+	return b.String()
+}
@@ -0,0 +1,519 @@
+// Copyright 2016 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package cfg
+
+// This file implements the CFG construction pass.
+
+import (
+	"fmt"
+	"go/ast"
+	"go/token"
+)
+
+type builder struct {
+	blocks    []*Block
+	mayReturn func(*ast.CallExpr) bool
+	current   *Block
+	lblocks   map[string]*lblock // labeled blocks
+	targets   *targets           // linked stack of branch targets
+}
+
+func (b *builder) stmt(_s ast.Stmt) {
+	// The label of the current statement.  If non-nil, its _goto
+	// target is always set; its _break and _continue are set only
+	// within the body of switch/typeswitch/select/for/range.
+	// It is effectively an additional default-nil parameter of stmt().
+	var label *lblock
+start:
+	switch s := _s.(type) {
+	case *ast.BadStmt,
+		*ast.SendStmt,
+		*ast.IncDecStmt,
+		*ast.GoStmt,
+		*ast.EmptyStmt,
+		*ast.AssignStmt:
+		// No effect on control flow.
+		b.add(s)
+
+	case *ast.DeferStmt:
+		b.add(s)
+		// Assume conservatively that this behaves like:
+		//    defer func() { recover() }
+		// so any subsequent panic may act like a return.
+		b.current.returns = true
+
+	case *ast.ExprStmt:
+		b.add(s)
+		if call, ok := s.X.(*ast.CallExpr); ok && !b.mayReturn(call) {
+			// Calls to panic, os.Exit, etc, never return.
+			b.current = b.newBlock(KindUnreachable, s)
+		}
+
+	case *ast.DeclStmt:
+		// Treat each var ValueSpec as a separate statement.
+		d := s.Decl.(*ast.GenDecl)
+		if d.Tok == token.VAR {
+			for _, spec := range d.Specs {
+				if spec, ok := spec.(*ast.ValueSpec); ok {
+					b.add(spec)
+				}
+			}
+		}
+
+	case *ast.LabeledStmt:
+		label = b.labeledBlock(s.Label, s)
+		b.jump(label._goto)
+		b.current = label._goto
+		_s = s.Stmt
+		goto start // effectively: tailcall stmt(g, s.Stmt, label)
+
+	case *ast.ReturnStmt:
+		b.current.returns = true
+		b.add(s)
+		b.current = b.newBlock(KindUnreachable, s)
+
+	case *ast.BranchStmt:
+		b.branchStmt(s)
+
+	case *ast.BlockStmt:
+		b.stmtList(s.List)
+
+	case *ast.IfStmt:
+		if s.Init != nil {
+			b.stmt(s.Init)
+		}
+		then := b.newBlock(KindIfThen, s)
+		done := b.newBlock(KindIfDone, s)
+		_else := done
+		if s.Else != nil {
+			_else = b.newBlock(KindIfElse, s)
+		}
+		b.add(s.Cond)
+		b.ifelse(then, _else)
+		b.current = then
+		b.stmt(s.Body)
+		b.jump(done)
+
+		if s.Else != nil {
+			b.current = _else
+			b.stmt(s.Else)
+			b.jump(done)
+		}
+
+		b.current = done
+
+	case *ast.SwitchStmt:
+		b.switchStmt(s, label)
+
+	case *ast.TypeSwitchStmt:
+		b.typeSwitchStmt(s, label)
+
+	case *ast.SelectStmt:
+		b.selectStmt(s, label)
+
+	case *ast.ForStmt:
+		b.forStmt(s, label)
+
+	case *ast.RangeStmt:
+		b.rangeStmt(s, label)
+
+	default:
+		panic(fmt.Sprintf("unexpected statement kind: %T", s))
+	}
+}
+
+func (b *builder) stmtList(list []ast.Stmt) {
+	for _, s := range list {
+		b.stmt(s)
+	}
+}
+
+func (b *builder) branchStmt(s *ast.BranchStmt) {
+	var block *Block
+	switch s.Tok {
+	case token.BREAK:
+		if s.Label != nil {
+			if lb := b.labeledBlock(s.Label, nil); lb != nil {
+				block = lb._break
+			}
+		} else {
+			for t := b.targets; t != nil && block == nil; t = t.tail {
+				block = t._break
+			}
+		}
+
+	case token.CONTINUE:
+		if s.Label != nil {
+			if lb := b.labeledBlock(s.Label, nil); lb != nil {
+				block = lb._continue
+			}
+		} else {
+			for t := b.targets; t != nil && block == nil; t = t.tail {
+				block = t._continue
+			}
+		}
+
+	case token.FALLTHROUGH:
+		for t := b.targets; t != nil && block == nil; t = t.tail {
+			block = t._fallthrough
+		}
+
+	case token.GOTO:
+		if s.Label != nil {
+			block = b.labeledBlock(s.Label, nil)._goto
+		}
+	}
+	if block == nil { // ill-typed (e.g. undefined label)
+		block = b.newBlock(KindUnreachable, s)
+	}
+	b.jump(block)
+	b.current = b.newBlock(KindUnreachable, s)
+}
+
+func (b *builder) switchStmt(s *ast.SwitchStmt, label *lblock) {
+	if s.Init != nil {
+		b.stmt(s.Init)
+	}
+	if s.Tag != nil {
+		b.add(s.Tag)
+	}
+	done := b.newBlock(KindSwitchDone, s)
+	if label != nil {
+		label._break = done
+	}
+	// We pull the default case (if present) down to the end.
+	// But each fallthrough label must point to the next
+	// body block in source order, so we preallocate a
+	// body block (fallthru) for the next case.
+	// Unfortunately this makes for a confusing block order.
+	var defaultBody *[]ast.Stmt
+	var defaultFallthrough *Block
+	var fallthru, defaultBlock *Block
+	ncases := len(s.Body.List)
+	for i, clause := range s.Body.List {
+		body := fallthru
+		if body == nil {
+			body = b.newBlock(KindSwitchCaseBody, clause) // first case only
+		}
+
+		// Preallocate body block for the next case.
+		fallthru = done
+		if i+1 < ncases {
+			fallthru = b.newBlock(KindSwitchCaseBody, s.Body.List[i+1])
+		}
+
+		cc := clause.(*ast.CaseClause)
+		if cc.List == nil {
+			// Default case.
+			defaultBody = &cc.Body
+			defaultFallthrough = fallthru
+			defaultBlock = body
+			continue
+		}
+
+		var nextCond *Block
+		for _, cond := range cc.List {
+			nextCond = b.newBlock(KindSwitchNextCase, cc)
+			b.add(cond) // one half of the tag==cond condition
+			b.ifelse(body, nextCond)
+			b.current = nextCond
+		}
+		b.current = body
+		b.targets = &targets{
+			tail:         b.targets,
+			_break:       done,
+			_fallthrough: fallthru,
+		}
+		b.stmtList(cc.Body)
+		b.targets = b.targets.tail
+		b.jump(done)
+		b.current = nextCond
+	}
+	if defaultBlock != nil {
+		b.jump(defaultBlock)
+		b.current = defaultBlock
+		b.targets = &targets{
+			tail:         b.targets,
+			_break:       done,
+			_fallthrough: defaultFallthrough,
+		}
+		b.stmtList(*defaultBody)
+		b.targets = b.targets.tail
+	}
+	b.jump(done)
+	b.current = done
+}
+
+func (b *builder) typeSwitchStmt(s *ast.TypeSwitchStmt, label *lblock) {
+	if s.Init != nil {
+		b.stmt(s.Init)
+	}
+	if s.Assign != nil {
+		b.add(s.Assign)
+	}
+
+	done := b.newBlock(KindSwitchDone, s)
+	if label != nil {
+		label._break = done
+	}
+	var default_ *ast.CaseClause
+	for _, clause := range s.Body.List {
+		cc := clause.(*ast.CaseClause)
+		if cc.List == nil {
+			default_ = cc
+			continue
+		}
+		body := b.newBlock(KindSwitchCaseBody, cc)
+		var next *Block
+		for _, casetype := range cc.List {
+			next = b.newBlock(KindSwitchNextCase, cc)
+			// casetype is a type, so don't call b.add(casetype).
+			// This block logically contains a type assertion,
+			// x.(casetype), but it's unclear how to represent x.
+			_ = casetype
+			b.ifelse(body, next)
+			b.current = next
+		}
+		b.current = body
+		b.typeCaseBody(cc, done)
+		b.current = next
+	}
+	if default_ != nil {
+		b.typeCaseBody(default_, done)
+	} else {
+		b.jump(done)
+	}
+	b.current = done
+}
+
+func (b *builder) typeCaseBody(cc *ast.CaseClause, done *Block) {
+	b.targets = &targets{
+		tail:   b.targets,
+		_break: done,
+	}
+	b.stmtList(cc.Body)
+	b.targets = b.targets.tail
+	b.jump(done)
+}
+
+func (b *builder) selectStmt(s *ast.SelectStmt, label *lblock) {
+	// First evaluate channel expressions.
+	// TODO(adonovan): fix: evaluate only channel exprs here.
+	for _, clause := range s.Body.List {
+		if comm := clause.(*ast.CommClause).Comm; comm != nil {
+			b.stmt(comm)
+		}
+	}
+
+	done := b.newBlock(KindSelectDone, s)
+	if label != nil {
+		label._break = done
+	}
+
+	var defaultBody *[]ast.Stmt
+	for _, cc := range s.Body.List {
+		clause := cc.(*ast.CommClause)
+		if clause.Comm == nil {
+			defaultBody = &clause.Body
+			continue
+		}
+		body := b.newBlock(KindSelectCaseBody, clause)
+		next := b.newBlock(KindSelectAfterCase, clause)
+		b.ifelse(body, next)
+		b.current = body
+		b.targets = &targets{
+			tail:   b.targets,
+			_break: done,
+		}
+		switch comm := clause.Comm.(type) {
+		case *ast.ExprStmt: // <-ch
+			// nop
+		case *ast.AssignStmt: // x := <-states[state].Chan
+			b.add(comm.Lhs[0])
+		}
+		b.stmtList(clause.Body)
+		b.targets = b.targets.tail
+		b.jump(done)
+		b.current = next
+	}
+	if defaultBody != nil {
+		b.targets = &targets{
+			tail:   b.targets,
+			_break: done,
+		}
+		b.stmtList(*defaultBody)
+		b.targets = b.targets.tail
+		b.jump(done)
+	}
+	b.current = done
+}
+
+func (b *builder) forStmt(s *ast.ForStmt, label *lblock) {
+	//	...init...
+	//      jump loop
+	// loop:
+	//      if cond goto body else done
+	// body:
+	//      ...body...
+	//      jump post
+	// post:				 (target of continue)
+	//      ...post...
+	//      jump loop
+	// done:                                 (target of break)
+	if s.Init != nil {
+		b.stmt(s.Init)
+	}
+	body := b.newBlock(KindForBody, s)
+	done := b.newBlock(KindForDone, s) // target of 'break'
+	loop := body                       // target of back-edge
+	if s.Cond != nil {
+		loop = b.newBlock(KindForLoop, s)
+	}
+	cont := loop // target of 'continue'
+	if s.Post != nil {
+		cont = b.newBlock(KindForPost, s)
+	}
+	if label != nil {
+		label._break = done
+		label._continue = cont
+	}
+	b.jump(loop)
+	b.current = loop
+	if loop != body {
+		b.add(s.Cond)
+		b.ifelse(body, done)
+		b.current = body
+	}
+	b.targets = &targets{
+		tail:      b.targets,
+		_break:    done,
+		_continue: cont,
+	}
+	b.stmt(s.Body)
+	b.targets = b.targets.tail
+	b.jump(cont)
+
+	if s.Post != nil {
+		b.current = cont
+		b.stmt(s.Post)
+		b.jump(loop) // back-edge
+	}
+	b.current = done
+}
+
+func (b *builder) rangeStmt(s *ast.RangeStmt, label *lblock) {
+	b.add(s.X)
+
+	if s.Key != nil {
+		b.add(s.Key)
+	}
+	if s.Value != nil {
+		b.add(s.Value)
+	}
+
+	//      ...
+	// loop:                                   (target of continue)
+	// 	if ... goto body else done
+	// body:
+	//      ...
+	// 	jump loop
+	// done:                                   (target of break)
+
+	loop := b.newBlock(KindRangeLoop, s)
+	b.jump(loop)
+	b.current = loop
+
+	body := b.newBlock(KindRangeBody, s)
+	done := b.newBlock(KindRangeDone, s)
+	b.ifelse(body, done)
+	b.current = body
+
+	if label != nil {
+		label._break = done
+		label._continue = loop
+	}
+	b.targets = &targets{
+		tail:      b.targets,
+		_break:    done,
+		_continue: loop,
+	}
+	b.stmt(s.Body)
+	b.targets = b.targets.tail
+	b.jump(loop) // back-edge
+	b.current = done
+}
+
+// -------- helpers --------
+
+// Destinations associated with unlabeled for/switch/select stmts.
+// We push/pop one of these as we enter/leave each construct and for
+// each BranchStmt we scan for the innermost target of the right type.
+type targets struct {
+	tail         *targets // rest of stack
+	_break       *Block
+	_continue    *Block
+	_fallthrough *Block
+}
+
+// Destinations associated with a labeled block.
+// We populate these as labels are encountered in forward gotos or
+// labeled statements.
+type lblock struct {
+	_goto     *Block
+	_break    *Block
+	_continue *Block
+}
+
+// labeledBlock returns the branch target associated with the
+// specified label, creating it if needed.
+func (b *builder) labeledBlock(label *ast.Ident, stmt *ast.LabeledStmt) *lblock {
+	lb := b.lblocks[label.Name]
+	if lb == nil {
+		lb = &lblock{_goto: b.newBlock(KindLabel, nil)}
+		if b.lblocks == nil {
+			b.lblocks = make(map[string]*lblock)
+		}
+		b.lblocks[label.Name] = lb
+	}
+	// Fill in the label later (in case of forward goto).
+	// Stmt may be set already if labels are duplicated (ill-typed).
+	if stmt != nil && lb._goto.Stmt == nil {
+		lb._goto.Stmt = stmt
+	}
+	return lb
+}
+
+// newBlock appends a new unconnected basic block to b.cfg's block
+// slice and returns it.
+// It does not automatically become the current block.
+// comment is an optional string for more readable debugging output.
+func (b *builder) newBlock(kind BlockKind, stmt ast.Stmt) *Block {
+	block := &Block{
+		Index: int32(len(b.blocks)),
+		Kind:  kind,
+		Stmt:  stmt,
+	}
+	block.Succs = block.succs2[:0]
+	b.blocks = append(b.blocks, block)
+	return block
+}
+
+func (b *builder) add(n ast.Node) {
+	b.current.Nodes = append(b.current.Nodes, n)
+}
+
+// jump adds an edge from the current block to the target block,
+// and sets b.current to nil.
+func (b *builder) jump(target *Block) {
+	b.current.Succs = append(b.current.Succs, target)
+	b.current = nil
+}
+
+// ifelse emits edges from the current block to the t and f blocks,
+// and sets b.current to nil.
+func (b *builder) ifelse(t, f *Block) {
+	b.current.Succs = append(b.current.Succs, t, f)
+	b.current = nil
+}
@@ -0,0 +1,273 @@
+// Copyright 2016 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package cfg constructs a simple control-flow graph (CFG) of the
+// statements and expressions within a single function.
+//
+// Use cfg.New to construct the CFG for a function body.
+//
+// The blocks of the CFG contain all the function's non-control
+// statements.  The CFG does not contain control statements such as If,
+// Switch, Select, and Branch, but does contain their subexpressions;
+// also, each block records the control statement (Block.Stmt) that
+// gave rise to it and its relationship (Block.Kind) to that statement.
+//
+// For example, this source code:
+//
+//	if x := f(); x != nil {
+//		T()
+//	} else {
+//		F()
+//	}
+//
+// produces this CFG:
+//
+//	1:  x := f()		Body
+//	    x != nil
+//	    succs: 2, 3
+//	2:  T()			IfThen
+//	    succs: 4
+//	3:  F()			IfElse
+//	    succs: 4
+//	4:			IfDone
+//
+// The CFG does contain Return statements; even implicit returns are
+// materialized (at the position of the function's closing brace).
+//
+// The CFG does not record conditions associated with conditional branch
+// edges, nor the short-circuit semantics of the && and || operators,
+// nor abnormal control flow caused by panic.  If you need this
+// information, use golang.org/x/tools/go/ssa instead.
+package cfg
+
+import (
+	"bytes"
+	"fmt"
+	"go/ast"
+	"go/format"
+	"go/token"
+)
+
+// A CFG represents the control-flow graph of a single function.
+//
+// The entry point is Blocks[0]; there may be multiple return blocks.
+type CFG struct {
+	Blocks   []*Block // block[0] is entry; order otherwise undefined
+	noreturn bool     // function body lacks a reachable return statement
+}
+
+// NoReturn reports whether the function has no reachable return.
+func (cfg *CFG) NoReturn() bool { return cfg.noreturn }
+
+// A Block represents a basic block: a list of statements and
+// expressions that are always evaluated sequentially.
+//
+// A block may have 0-2 successors: zero for a return block or a block
+// that calls a function such as panic that never returns; one for a
+// normal (jump) block; and two for a conditional (if) block.
+//
+// In a conditional block, the last entry in Nodes is the condition and always
+// an [ast.Expr], Succs[0] is the successor if the condition is true, and
+// Succs[1] is the successor if the condition is false.
+type Block struct {
+	Nodes   []ast.Node // statements, expressions, and ValueSpecs
+	Succs   []*Block   // successor nodes in the graph
+	Index   int32      // index within CFG.Blocks
+	Live    bool       // block is reachable from entry
+	returns bool       // block contains return or defer (which may recover and return)
+	Kind    BlockKind  // block kind
+	Stmt    ast.Stmt   // statement that gave rise to this block (see BlockKind for details)
+
+	succs2 [2]*Block // underlying array for Succs
+}
+
+// A BlockKind identifies the purpose of a block.
+// It also determines the possible types of its Stmt field.
+type BlockKind uint8
+
+const (
+	KindInvalid BlockKind = iota // Stmt=nil
+
+	KindUnreachable     // unreachable block after {Branch,Return}Stmt / no-return call ExprStmt
+	KindBody            // function body BlockStmt
+	KindForBody         // body of ForStmt
+	KindForDone         // block after ForStmt
+	KindForLoop         // head of ForStmt
+	KindForPost         // post condition of ForStmt
+	KindIfDone          // block after IfStmt
+	KindIfElse          // else block of IfStmt
+	KindIfThen          // then block of IfStmt
+	KindLabel           // labeled block of BranchStmt (Stmt may be nil for dangling label)
+	KindRangeBody       // body of RangeStmt
+	KindRangeDone       // block after RangeStmt
+	KindRangeLoop       // head of RangeStmt
+	KindSelectCaseBody  // body of SelectStmt
+	KindSelectDone      // block after SelectStmt
+	KindSelectAfterCase // block after a CommClause
+	KindSwitchCaseBody  // body of CaseClause
+	KindSwitchDone      // block after {Type.}SwitchStmt
+	KindSwitchNextCase  // secondary expression of a multi-expression CaseClause
+)
+
+func (kind BlockKind) String() string {
+	return [...]string{
+		KindInvalid:         "Invalid",
+		KindUnreachable:     "Unreachable",
+		KindBody:            "Body",
+		KindForBody:         "ForBody",
+		KindForDone:         "ForDone",
+		KindForLoop:         "ForLoop",
+		KindForPost:         "ForPost",
+		KindIfDone:          "IfDone",
+		KindIfElse:          "IfElse",
+		KindIfThen:          "IfThen",
+		KindLabel:           "Label",
+		KindRangeBody:       "RangeBody",
+		KindRangeDone:       "RangeDone",
+		KindRangeLoop:       "RangeLoop",
+		KindSelectCaseBody:  "SelectCaseBody",
+		KindSelectDone:      "SelectDone",
+		KindSelectAfterCase: "SelectAfterCase",
+		KindSwitchCaseBody:  "SwitchCaseBody",
+		KindSwitchDone:      "SwitchDone",
+		KindSwitchNextCase:  "SwitchNextCase",
+	}[kind]
+}
+
+// New returns a new control-flow graph for the specified function body,
+// which must be non-nil.
+//
+// The CFG builder calls mayReturn to determine whether a given function
+// call may return.  For example, calls to panic, os.Exit, and log.Fatal
+// do not return, so the builder can remove infeasible graph edges
+// following such calls.  The builder calls mayReturn only for a
+// CallExpr beneath an ExprStmt.
+func New(body *ast.BlockStmt, mayReturn func(*ast.CallExpr) bool) *CFG {
+	b := builder{
+		mayReturn: mayReturn,
+	}
+	b.current = b.newBlock(KindBody, body)
+	b.stmt(body)
+
+	// Compute liveness (reachability from entry point),
+	// breadth-first, marking Block.Live flags.
+	q := make([]*Block, 0, len(b.blocks))
+	q = append(q, b.blocks[0]) // entry point
+	for len(q) > 0 {
+		b := q[len(q)-1]
+		q = q[:len(q)-1]
+
+		if !b.Live {
+			b.Live = true
+			q = append(q, b.Succs...)
+		}
+	}
+
+	// Does control fall off the end of the function's body?
+	// Make implicit return explicit.
+	if b.current != nil && b.current.Live {
+		b.current.returns = true
+		b.add(&ast.ReturnStmt{
+			Return: body.End() - 1,
+		})
+	}
+
+	// Is any return (or defer+recover) block reachable?
+	noreturn := true
+	for _, bl := range b.blocks {
+		if bl.Live && bl.returns {
+			noreturn = false
+			break
+		}
+	}
+
+	return &CFG{Blocks: b.blocks, noreturn: noreturn}
+}
+
+func (b *Block) String() string {
+	return fmt.Sprintf("block %d (%s)", b.Index, b.comment(nil))
+}
+
+func (b *Block) comment(fset *token.FileSet) string {
+	s := b.Kind.String()
+	if fset != nil && b.Stmt != nil {
+		s = fmt.Sprintf("%s@L%d", s, fset.Position(b.Stmt.Pos()).Line)
+	}
+	return s
+}
+
+// Return returns the return statement at the end of this block if present, nil
+// otherwise.
+//
+// When control falls off the end of the function, the ReturnStmt is synthetic
+// and its [ast.Node.End] position may be beyond the end of the file.
+//
+// A function that contains no return statement (explicit or implied)
+// may yet return normally, and may even return a nonzero value. For example:
+//
+//	func() (res any) {
+//		defer func() { res = recover() }()
+//		panic(123)
+//	}
+func (b *Block) Return() (ret *ast.ReturnStmt) {
+	if len(b.Nodes) > 0 {
+		ret, _ = b.Nodes[len(b.Nodes)-1].(*ast.ReturnStmt)
+	}
+	return
+}
+
+// Format formats the control-flow graph for ease of debugging.
+func (g *CFG) Format(fset *token.FileSet) string {
+	var buf bytes.Buffer
+	for _, b := range g.Blocks {
+		fmt.Fprintf(&buf, ".%d: # %s\n", b.Index, b.comment(fset))
+		for _, n := range b.Nodes {
+			fmt.Fprintf(&buf, "\t%s\n", formatNode(fset, n))
+		}
+		if len(b.Succs) > 0 {
+			fmt.Fprintf(&buf, "\tsuccs:")
+			for _, succ := range b.Succs {
+				fmt.Fprintf(&buf, " %d", succ.Index)
+			}
+			buf.WriteByte('\n')
+		}
+		buf.WriteByte('\n')
+	}
+	return buf.String()
+}
+
+// Dot returns the control-flow graph in the [Dot graph description language].
+// Use a command such as 'dot -Tsvg' to render it in a form viewable in a browser.
+// This method is provided as a debugging aid; the details of the
+// output are unspecified and may change.
+//
+// [Dot graph description language]: https://en.wikipedia.org/wiki/DOT_(graph_description_language)
+func (g *CFG) Dot(fset *token.FileSet) string {
+	var buf bytes.Buffer
+	buf.WriteString("digraph CFG {\n")
+	buf.WriteString("  node [shape=box];\n")
+	for _, b := range g.Blocks {
+		// node label
+		var text bytes.Buffer
+		text.WriteString(b.comment(fset))
+		for _, n := range b.Nodes {
+			fmt.Fprintf(&text, "\n%s", formatNode(fset, n))
+		}
+
+		// node and edges
+		fmt.Fprintf(&buf, "  n%d [label=%q];\n", b.Index, &text)
+		for _, succ := range b.Succs {
+			fmt.Fprintf(&buf, "  n%d -> n%d;\n", b.Index, succ.Index)
+		}
+	}
+	buf.WriteString("}\n")
+	return buf.String()
+}
+
+func formatNode(fset *token.FileSet, n ast.Node) string {
+	var buf bytes.Buffer
+	format.Node(&buf, fset, n)
+	// Indent secondary lines by a tab.
+	return string(bytes.Replace(buf.Bytes(), []byte("\n"), []byte("\n\t"), -1))
+}
@@ -0,0 +1,20 @@
+Copyright (c) 2016 Dominik Honnef
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,121 @@
+Staticcheck and its related tools make use of third party projects,
+either by reusing their code, or by statically linking them into
+resulting binaries. These projects are:
+
+* The Go Programming Language - https://golang.org/
+  golang.org/x/mod - https://github.com/golang/mod
+  golang.org/x/tools - https://github.com/golang/tools
+  golang.org/x/sys - https://github.com/golang/sys
+  golang.org/x/xerrors - https://github.com/golang/xerrors
+
+    Copyright (c) 2009 The Go Authors. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are
+    met:
+
+       * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+       * Redistributions in binary form must reproduce the above
+    copyright notice, this list of conditions and the following disclaimer
+    in the documentation and/or other materials provided with the
+    distribution.
+       * Neither the name of Google Inc. nor the names of its
+    contributors may be used to endorse or promote products derived from
+    this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+* github.com/BurntSushi/toml - https://github.com/BurntSushi/toml
+
+    The MIT License (MIT)
+
+    Copyright (c) 2013 TOML authors
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.
+
+* gogrep - https://github.com/mvdan/gogrep
+
+    Copyright (c) 2017, Daniel Martí. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are
+    met:
+
+       * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+       * Redistributions in binary form must reproduce the above
+    copyright notice, this list of conditions and the following disclaimer
+    in the documentation and/or other materials provided with the
+    distribution.
+       * Neither the name of the copyright holder nor the names of its
+    contributors may be used to endorse or promote products derived from
+    this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+* gosmith - https://github.com/dvyukov/gosmith
+
+    Copyright (c) 2014 Dmitry Vyukov. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are
+    met:
+
+       * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+       * Redistributions in binary form must reproduce the above
+    copyright notice, this list of conditions and the following disclaimer
+    in the documentation and/or other materials provided with the
+    distribution.
+       * The name of Dmitry Vyukov may be used to endorse or promote
+    products derived from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,161 @@
+// Package callcheck provides a framework for validating arguments in function calls.
+package callcheck
+
+import (
+	"fmt"
+	"go/ast"
+	"go/constant"
+	"go/types"
+
+	"golang.org/x/tools/go/analysis"
+	"honnef.co/go/tools/analysis/report"
+	"honnef.co/go/tools/go/ir"
+	"honnef.co/go/tools/go/ir/irutil"
+	"honnef.co/go/tools/go/types/typeutil"
+	"honnef.co/go/tools/internal/passes/buildir"
+)
+
+type Call struct {
+	Pass  *analysis.Pass
+	Instr ir.CallInstruction
+	Args  []*Argument
+
+	Parent *ir.Function
+
+	invalids []string
+}
+
+func (c *Call) Invalid(msg string) {
+	c.invalids = append(c.invalids, msg)
+}
+
+type Argument struct {
+	Value    Value
+	invalids []string
+}
+
+type Value struct {
+	Value ir.Value
+}
+
+func (arg *Argument) Invalid(msg string) {
+	arg.invalids = append(arg.invalids, msg)
+}
+
+type Check func(call *Call)
+
+func Analyzer(rules map[string]Check) func(pass *analysis.Pass) (any, error) {
+	return func(pass *analysis.Pass) (any, error) {
+		return checkCalls(pass, rules)
+	}
+}
+
+func checkCalls(pass *analysis.Pass, rules map[string]Check) (any, error) {
+	cb := func(caller *ir.Function, site ir.CallInstruction, callee *ir.Function) {
+		obj, ok := callee.Object().(*types.Func)
+		if !ok {
+			return
+		}
+
+		r, ok := rules[typeutil.FuncName(obj)]
+		if !ok {
+			return
+		}
+		var args []*Argument
+		irargs := site.Common().Args
+		if callee.Signature.Recv() != nil {
+			irargs = irargs[1:]
+		}
+		for _, arg := range irargs {
+			if iarg, ok := arg.(*ir.MakeInterface); ok {
+				arg = iarg.X
+			}
+			args = append(args, &Argument{Value: Value{arg}})
+		}
+		call := &Call{
+			Pass:   pass,
+			Instr:  site,
+			Args:   args,
+			Parent: site.Parent(),
+		}
+		r(call)
+
+		var astcall *ast.CallExpr
+		switch source := site.Source().(type) {
+		case *ast.CallExpr:
+			astcall = source
+		case *ast.DeferStmt:
+			astcall = source.Call
+		case *ast.GoStmt:
+			astcall = source.Call
+		case nil:
+			// TODO(dh): I am not sure this can actually happen. If it
+			// can't, we should remove this case, and also stop
+			// checking for astcall == nil in the code that follows.
+		default:
+			panic(fmt.Sprintf("unhandled case %T", source))
+		}
+
+		for idx, arg := range call.Args {
+			for _, e := range arg.invalids {
+				if astcall != nil {
+					if idx < len(astcall.Args) {
+						report.Report(pass, astcall.Args[idx], e)
+					} else {
+						// this is an instance of fn1(fn2()) where fn2
+						// returns multiple values. Report the error
+						// at the next-best position that we have, the
+						// first argument. An example of a check that
+						// triggers this is checkEncodingBinaryRules.
+						report.Report(pass, astcall.Args[0], e)
+					}
+				} else {
+					report.Report(pass, site, e)
+				}
+			}
+		}
+		for _, e := range call.invalids {
+			report.Report(pass, call.Instr, e)
+		}
+	}
+	for _, fn := range pass.ResultOf[buildir.Analyzer].(*buildir.IR).SrcFuncs {
+		eachCall(fn, cb)
+	}
+	return nil, nil
+}
+
+func eachCall(fn *ir.Function, cb func(caller *ir.Function, site ir.CallInstruction, callee *ir.Function)) {
+	for _, b := range fn.Blocks {
+		for _, instr := range b.Instrs {
+			if site, ok := instr.(ir.CallInstruction); ok {
+				if g := site.Common().StaticCallee(); g != nil {
+					cb(fn, site, g)
+				}
+			}
+		}
+	}
+}
+
+func ExtractConstExpectKind(v Value, kind constant.Kind) *ir.Const {
+	k := extractConst(v.Value)
+	if k == nil || k.Value == nil || k.Value.Kind() != kind {
+		return nil
+	}
+	return k
+}
+
+func ExtractConst(v Value) *ir.Const {
+	return extractConst(v.Value)
+}
+
+func extractConst(v ir.Value) *ir.Const {
+	v = irutil.Flatten(v)
+	switch v := v.(type) {
+	case *ir.Const:
+		return v
+	case *ir.MakeInterface:
+		return extractConst(v.X)
+	default:
+		return nil
+	}
+}
@@ -0,0 +1,589 @@
+// Package code answers structural and type questions about Go code.
+package code
+
+import (
+	"fmt"
+	"go/ast"
+	"go/build/constraint"
+	"go/constant"
+	"go/token"
+	"go/types"
+	"go/version"
+	"path/filepath"
+	"slices"
+	"strings"
+
+	"honnef.co/go/tools/analysis/facts/generated"
+	"honnef.co/go/tools/analysis/facts/purity"
+	"honnef.co/go/tools/analysis/facts/tokenfile"
+	"honnef.co/go/tools/go/ast/astutil"
+	"honnef.co/go/tools/go/types/typeutil"
+	"honnef.co/go/tools/knowledge"
+	"honnef.co/go/tools/pattern"
+
+	"golang.org/x/tools/go/analysis"
+)
+
+type Positioner interface {
+	Pos() token.Pos
+}
+
+func IsOfStringConvertibleByteSlice(pass *analysis.Pass, expr ast.Expr) bool {
+	typ, ok := pass.TypesInfo.TypeOf(expr).Underlying().(*types.Slice)
+	if !ok {
+		return false
+	}
+	elem := types.Unalias(typ.Elem())
+	if version.Compare(LanguageVersion(pass, expr), "go1.18") >= 0 {
+		// Before Go 1.18, one could not directly convert from []T (where 'type T byte')
+		// to string. See also https://github.com/golang/go/issues/23536.
+		elem = elem.Underlying()
+	}
+	return types.Identical(elem, types.Typ[types.Byte])
+}
+
+func IsOfPointerToTypeWithName(pass *analysis.Pass, expr ast.Expr, name string) bool {
+	ptr, ok := types.Unalias(pass.TypesInfo.TypeOf(expr)).(*types.Pointer)
+	if !ok {
+		return false
+	}
+	return typeutil.IsTypeWithName(ptr.Elem(), name)
+}
+
+func IsOfTypeWithName(pass *analysis.Pass, expr ast.Expr, name string) bool {
+	return typeutil.IsTypeWithName(pass.TypesInfo.TypeOf(expr), name)
+}
+
+func IsInTest(pass *analysis.Pass, node Positioner) bool {
+	// FIXME(dh): this doesn't work for global variables with
+	// initializers
+	f := pass.Fset.File(node.Pos())
+	return f != nil && strings.HasSuffix(f.Name(), "_test.go")
+}
+
+// IsMain reports whether the package being processed is a package
+// main.
+func IsMain(pass *analysis.Pass) bool {
+	return pass.Pkg.Name() == "main"
+}
+
+// IsMainLike reports whether the package being processed is a
+// main-like package. A main-like package is a package that is
+// package main, or that is intended to be used by a tool framework
+// such as cobra to implement a command.
+//
+// Note that this function errs on the side of false positives; it may
+// return true for packages that aren't main-like. IsMainLike is
+// intended for analyses that wish to suppress diagnostics for
+// main-like packages to avoid false positives.
+func IsMainLike(pass *analysis.Pass) bool {
+	if pass.Pkg.Name() == "main" {
+		return true
+	}
+	for _, imp := range pass.Pkg.Imports() {
+		if imp.Path() == "github.com/spf13/cobra" {
+			return true
+		}
+	}
+	return false
+}
+
+func SelectorName(pass *analysis.Pass, expr *ast.SelectorExpr) string {
+	info := pass.TypesInfo
+	sel := info.Selections[expr]
+	if sel == nil {
+		if x, ok := expr.X.(*ast.Ident); ok {
+			pkg, ok := info.ObjectOf(x).(*types.PkgName)
+			if !ok {
+				// This shouldn't happen
+				return fmt.Sprintf("%s.%s", x.Name, expr.Sel.Name)
+			}
+			return fmt.Sprintf("%s.%s", pkg.Imported().Path(), expr.Sel.Name)
+		}
+		panic(fmt.Sprintf("unsupported selector: %v", expr))
+	}
+	if v, ok := sel.Obj().(*types.Var); ok && v.IsField() {
+		return fmt.Sprintf("(%s).%s", typeutil.DereferenceR(sel.Recv()), sel.Obj().Name())
+	} else {
+		return fmt.Sprintf("(%s).%s", sel.Recv(), sel.Obj().Name())
+	}
+}
+
+func IsNil(pass *analysis.Pass, expr ast.Expr) bool {
+	return pass.TypesInfo.Types[expr].IsNil()
+}
+
+func BoolConst(pass *analysis.Pass, expr ast.Expr) bool {
+	val := pass.TypesInfo.ObjectOf(expr.(*ast.Ident)).(*types.Const).Val()
+	return constant.BoolVal(val)
+}
+
+func IsBoolConst(pass *analysis.Pass, expr ast.Expr) bool {
+	// We explicitly don't support typed bools because more often than
+	// not, custom bool types are used as binary enums and the explicit
+	// comparison is desired. We err on the side of false negatives and
+	// treat aliases like other custom types.
+
+	ident, ok := expr.(*ast.Ident)
+	if !ok {
+		return false
+	}
+	obj := pass.TypesInfo.ObjectOf(ident)
+	c, ok := obj.(*types.Const)
+	if !ok {
+		return false
+	}
+	basic, ok := c.Type().(*types.Basic)
+	if !ok {
+		return false
+	}
+	if basic.Kind() != types.UntypedBool && basic.Kind() != types.Bool {
+		return false
+	}
+	return true
+}
+
+func ExprToInt(pass *analysis.Pass, expr ast.Expr) (int64, bool) {
+	tv := pass.TypesInfo.Types[expr]
+	if tv.Value == nil {
+		return 0, false
+	}
+	if tv.Value.Kind() != constant.Int {
+		return 0, false
+	}
+	return constant.Int64Val(tv.Value)
+}
+
+func ExprToString(pass *analysis.Pass, expr ast.Expr) (string, bool) {
+	val := pass.TypesInfo.Types[expr].Value
+	if val == nil {
+		return "", false
+	}
+	if val.Kind() != constant.String {
+		return "", false
+	}
+	return constant.StringVal(val), true
+}
+
+func CallName(pass *analysis.Pass, call *ast.CallExpr) string {
+	// See the comment in typeutil.FuncName for why this doesn't require special handling
+	// of aliases.
+
+	fun := astutil.Unparen(call.Fun)
+
+	// Instantiating a function cannot return another generic function, so doing this once is enough
+	switch idx := fun.(type) {
+	case *ast.IndexExpr:
+		fun = idx.X
+	case *ast.IndexListExpr:
+		fun = idx.X
+	}
+
+	// (foo)[T] is not a valid instantiation, so no need to unparen again.
+
+	switch fun := fun.(type) {
+	case *ast.SelectorExpr:
+		fn, ok := pass.TypesInfo.ObjectOf(fun.Sel).(*types.Func)
+		if !ok {
+			return ""
+		}
+		return typeutil.FuncName(fn)
+	case *ast.Ident:
+		obj := pass.TypesInfo.ObjectOf(fun)
+		switch obj := obj.(type) {
+		case *types.Func:
+			return typeutil.FuncName(obj)
+		case *types.Builtin:
+			return obj.Name()
+		default:
+			return ""
+		}
+	default:
+		return ""
+	}
+}
+
+func IsCallTo(pass *analysis.Pass, node ast.Node, name string) bool {
+	// See the comment in typeutil.FuncName for why this doesn't require special handling
+	// of aliases.
+
+	call, ok := node.(*ast.CallExpr)
+	if !ok {
+		return false
+	}
+	return CallName(pass, call) == name
+}
+
+func IsCallToAny(pass *analysis.Pass, node ast.Node, names ...string) bool {
+	// See the comment in typeutil.FuncName for why this doesn't require special handling
+	// of aliases.
+
+	call, ok := node.(*ast.CallExpr)
+	if !ok {
+		return false
+	}
+	q := CallName(pass, call)
+	return slices.Contains(names, q)
+}