pkg/config/configtest: move package cfgtest from chainlink/v2

Author: jmank88

go.mod

@@ -25,6 +25,7 @@ require (
 	github.com/jmoiron/sqlx v1.4.0
 	github.com/jonboulle/clockwork v0.4.0
 	github.com/jpillora/backoff v1.0.0
+	github.com/kylelemons/godebug v1.1.0
 	github.com/lib/pq v1.10.9
 	github.com/linkedin/goavro/v2 v2.12.0
 	github.com/marcboeker/go-duckdb v1.8.3

go.sum

@@ -229,6 +229,8 @@ github.com/kr/pty v1.1.8/go.mod h1:O1sed60cT9XZ5uDucP5qwvh+TE3NnUj51EiZO/lmSfw=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/leodido/go-urn v1.2.0 h1:hpXL4XnriNwQ/ABnpepYM/1vCLWNDfUNts8dX3xTG6Y=
 github.com/leodido/go-urn v1.2.0/go.mod h1:+8+nEpDfqqsY+g338gtMEUOtuK+4dEMhiQEgxpxOKII=
 github.com/lib/pq v1.0.0/go.mod h1:5WUZQaWbwv1U+lTReE5YruASi9Al49XbQIvNi/34Woo=

pkg/config/configdoc/configdoc.go

@@ -0,0 +1,213 @@
+package configdoc
+
+import (
+	"fmt"
+	"strings"
+
+	"go.uber.org/multierr"
+
+	"github.com/smartcontractkit/chainlink-common/pkg/config"
+)
+
+// Generate returns MarkDown documentation generated from the TOML string.
+// TODO doc more; advanced; extended on root level only
+func Generate(toml, header, example string, extendedDescriptions map[string]string) (string, error) {
+	items, err := parseTOMLDocs(toml, extendedDescriptions)
+	var sb strings.Builder
+
+	sb.WriteString(header)
+	sb.WriteString(`
+## Example
+
+`)
+	sb.WriteString("```toml\n")
+	sb.WriteString(example)
+	sb.WriteString("```\n\n")
+
+	for _, item := range items {
+		sb.WriteString(item.String())
+		sb.WriteString("\n\n")
+	}
+
+	return sb.String(), err
+}
+
+const (
+	fieldDefault = "# Default"
+	fieldExample = "# Example"
+
+	tokenAdvanced = "**ADVANCED**"
+)
+
+func advancedWarning(msg string) string {
+	return fmt.Sprintf(":warning: **_ADVANCED_**: _%s_\n", msg)
+}
+
+// lines holds a set of contiguous lines
+type lines []string
+
+func (d lines) String() string {
+	return strings.Join(d, "\n")
+}
+
+type table struct {
+	name     string
+	codes    lines
+	adv      bool
+	desc     lines
+	extended string
+}
+
+func newTable(line string, desc lines, extendedDescriptions map[string]string) *table {
+	t := &table{
+		name:  strings.Trim(line, "[]"),
+		codes: []string{line},
+		desc:  desc,
+	}
+	if len(desc) > 0 {
+		if strings.HasPrefix(strings.TrimSpace(desc[0]), tokenAdvanced) {
+			t.adv = true
+			t.desc = t.desc[1:]
+		} else if extended, ok := extendedDescriptions[t.name]; ok {
+			t.extended = extended
+		}
+	}
+	return t
+}
+
+func newArrayOfTables(line string, desc lines, extendedDescriptions map[string]string) *table {
+	t := &table{
+		name:  strings.Trim(strings.Trim(line, fieldExample), "[]"),
+		codes: []string{line},
+		desc:  desc,
+	}
+	if len(desc) > 0 {
+		if strings.HasPrefix(strings.TrimSpace(desc[0]), tokenAdvanced) {
+			t.adv = true
+			t.desc = t.desc[1:]
+		} else if extended, ok := extendedDescriptions[t.name]; ok {
+			t.extended = extended
+		}
+	}
+	return t
+}
+
+func (t table) advanced() string {
+	if t.adv {
+		return advancedWarning("Do not change these settings unless you know what you are doing.")
+	}
+	return ""
+}
+
+func (t table) code() string {
+	if t.extended == "" {
+		return fmt.Sprint("```toml\n", t.codes, "\n```\n")
+	}
+	return ""
+}
+
+// String prints a table as an H2, followed by a code block and description.
+func (t *table) String() string {
+	return fmt.Sprint("## ", t.name, "\n",
+		t.advanced(),
+		t.code(),
+		t.desc,
+		t.extended)
+}
+
+type keyval struct {
+	name string
+	code string
+	adv  bool
+	desc lines
+}
+
+func newKeyval(line string, desc lines) keyval {
+	line = strings.TrimSpace(line)
+	kv := keyval{
+		name: line[:strings.Index(line, " ")],
+		code: line,
+		desc: desc,
+	}
+	if len(desc) > 0 && strings.HasPrefix(strings.TrimSpace(desc[0]), tokenAdvanced) {
+		kv.adv = true
+		kv.desc = kv.desc[1:]
+	}
+	return kv
+}
+
+func (k keyval) advanced() string {
+	if k.adv {
+		return advancedWarning("Do not change this setting unless you know what you are doing.")
+	}
+	return ""
+}
+
+// String prints a keyval as an H3, followed by a code block and description.
+func (k keyval) String() string {
+	name := k.name
+	if i := strings.LastIndex(name, "."); i > -1 {
+		name = name[i+1:]
+	}
+	return fmt.Sprint("### ", name, "\n",
+		k.advanced(),
+		"```toml\n",
+		k.code,
+		"\n```\n",
+		k.desc)
+}
+
+func parseTOMLDocs(s string, extendedDescriptions map[string]string) (items []fmt.Stringer, err error) {
+	defer func() { _, err = config.MultiErrorList(err) }()
+	globalTable := table{name: "Global"}
+	currentTable := &globalTable
+	items = append(items, currentTable)
+	var desc lines
+	for _, line := range strings.Split(s, "\n") {
+		if strings.HasPrefix(line, "#") {
+			// comment
+			desc = append(desc, strings.TrimSpace(line[1:]))
+		} else if strings.TrimSpace(line) == "" {
+			// empty
+			if len(desc) > 0 {
+				items = append(items, desc)
+				desc = nil
+			}
+		} else if strings.HasPrefix(line, "[[") {
+			currentTable = newArrayOfTables(line, desc, extendedDescriptions)
+			items = append(items, currentTable)
+			desc = nil
+		} else if strings.HasPrefix(line, "[") {
+			currentTable = newTable(line, desc, extendedDescriptions)
+			items = append(items, currentTable)
+			desc = nil
+		} else {
+			kv := newKeyval(line, desc)
+			shortName := kv.name
+			if currentTable != &globalTable {
+				// update to full name
+				kv.name = currentTable.name + "." + kv.name
+			}
+			if len(kv.desc) == 0 {
+				err = multierr.Append(err, fmt.Errorf("%s: missing description", kv.name)) //TODO errors.Join
+			} else if !strings.HasPrefix(kv.desc[0], shortName) {
+				err = multierr.Append(err, fmt.Errorf("%s: description does not begin with %q", kv.name, shortName))
+			}
+			if !strings.HasSuffix(line, fieldDefault) && !strings.HasSuffix(line, fieldExample) {
+				err = multierr.Append(err, fmt.Errorf(`%s: is not one of %v`, kv.name, []string{fieldDefault, fieldExample}))
+			}
+
+			items = append(items, kv)
+			currentTable.codes = append(currentTable.codes, kv.code)
+			desc = nil
+		}
+	}
+	if len(globalTable.codes) == 0 {
+		// drop it
+		items = items[1:]
+	}
+	if len(desc) > 0 {
+		items = append(items, desc)
+	}
+	return
+}

pkg/config/configtest/configtest.go

@@ -0,0 +1,139 @@
+package configtest
+
+import (
+	"encoding"
+	"fmt"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/kylelemons/godebug/diff"
+	"github.com/pelletier/go-toml/v2"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/multierr"
+
+	"github.com/smartcontractkit/chainlink-common/pkg/config"
+)
+
+// AssertFieldsNotNil recursively checks s for nil fields. s must be a struct.
+func AssertFieldsNotNil(t *testing.T, s interface{}) {
+	t.Helper()
+	err := assertValNotNil(t, "", reflect.ValueOf(s))
+	_, err = config.MultiErrorList(err)
+	assert.NoError(t, err)
+}
+
+// assertFieldsNotNil recursively checks the struct s for nil fields.
+func assertFieldsNotNil(t *testing.T, prefix string, s reflect.Value) (err error) {
+	t.Helper()
+	require.Equal(t, reflect.Struct, s.Kind())
+
+	typ := s.Type()
+	for i := 0; i < s.NumField(); i++ {
+		f := s.Field(i)
+		key := prefix
+		if tf := typ.Field(i); !tf.Anonymous {
+			if key != "" {
+				key += "."
+			}
+			key += tf.Name
+		}
+		err = multierr.Combine(err, assertValNotNil(t, key, f)) //TODO errors.Join
+	}
+	return
+}
+
+// assertValuesNotNil recursively checks the map m for nil values.
+func assertValuesNotNil(t *testing.T, prefix string, m reflect.Value) (err error) {
+	t.Helper()
+	require.Equal(t, reflect.Map, m.Kind())
+	if prefix != "" {
+		prefix += "."
+	}
+
+	mi := m.MapRange()
+	for mi.Next() {
+		key := prefix + mi.Key().String()
+		err = multierr.Combine(err, assertValNotNil(t, key, mi.Value()))
+	}
+	return
+}
+
+// assertElementsNotNil recursively checks the slice s for nil values.
+func assertElementsNotNil(t *testing.T, prefix string, s reflect.Value) (err error) {
+	t.Helper()
+	require.Equal(t, reflect.Slice, s.Kind())
+
+	for i := 0; i < s.Len(); i++ {
+		err = multierr.Combine(err, assertValNotNil(t, prefix, s.Index(i)))
+	}
+	return
+}
+
+var (
+	textUnmarshaler     encoding.TextUnmarshaler
+	textUnmarshalerType = reflect.TypeOf(&textUnmarshaler).Elem()
+)
+
+// assertValNotNil recursively checks that val is not nil. val must be a struct, map, slice, or point to one.
+func assertValNotNil(t *testing.T, key string, val reflect.Value) error {
+	t.Helper()
+	k := val.Kind()
+	switch k { //nolint:exhaustive
+	case reflect.Ptr:
+		if val.IsNil() {
+			return fmt.Errorf("%s: nil", key)
+		}
+	}
+	if k == reflect.Ptr {
+		if val.Type().Implements(textUnmarshalerType) {
+			return nil // skip values unmarshaled from strings
+		}
+		val = val.Elem()
+	}
+	switch val.Kind() {
+	case reflect.Struct:
+		if val.Type().Implements(textUnmarshalerType) {
+			return nil // skip values unmarshaled from strings
+		}
+		return assertFieldsNotNil(t, key, val)
+	case reflect.Map:
+		if val.IsNil() {
+			return nil // not actually a problem
+		}
+		return assertValuesNotNil(t, key, val)
+	case reflect.Slice:
+		if val.IsNil() {
+			return nil // not actually a problem
+		}
+		return assertElementsNotNil(t, key, val)
+	default:
+		return nil
+	}
+}
+
+// AssertDocsTOMLComplete ensures that docsTOML decodes to C, without any unknown fields and without leaving any nil.
+func AssertDocsTOMLComplete[C any](t *testing.T, docsTOML string) {
+	t.Helper()
+	var c C
+	err := config.DecodeTOML(strings.NewReader(docsTOML), &c)
+	if err != nil && strings.Contains(err.Error(), "undecoded keys: ") {
+		t.Errorf("Docs contain extra fields: %v", err)
+	} else {
+		require.NoError(t, err)
+	}
+	AssertFieldsNotNil(t, c)
+}
+
+// TestFullMarshal ensures that c has no nil fields, and that it encodes to expTOML.
+func TestFullMarshal[C any](t *testing.T, c C, expTOML string) {
+	t.Helper()
+	AssertFieldsNotNil(t, c)
+
+	b, err := toml.Marshal(c)
+	require.NoError(t, err)
+	s := string(b)
+	t.Log(s)
+	assert.Equal(t, expTOML, s, diff.Diff(expTOML, s))
+}