markdown_internal_test.go

// Copyright © 2022-2024 Obol Labs Inc. Licensed under the terms of a Business Source License 1.1

package cmd

import (
	"bytes"
	"context"
	"flag"
	"fmt"
	"go/ast"
	"os"
	"sort"
	"strings"
	"testing"
	"text/template"

	"github.com/stretchr/testify/require"
	"golang.org/x/tools/go/packages"

	"github.com/obolnetwork/charon/app"
	"github.com/obolnetwork/charon/app/promauto"
)

var update = flag.Bool("update-markdown", false, "Updates the reference markdown docs")

//go:generate go test . -run=TestConfigReference -update-markdown

// TestConfigReference ensures that docs/configuration.md contains the latest output of `charon run --help`.
// Running this test with the --update-markdown flag will generate the contents, fixing the test if broken.
func TestConfigReference(t *testing.T) {
	cmd := newRootCmd(newRunCmd(func(context.Context, app.Config) error {
		return nil
	}, false))

	var buf bytes.Buffer
	cmd.SetOut(&buf)
	cmd.SetArgs(slice("run", "--help"))

	require.NoError(t, cmd.Execute())

	file := "../docs/configuration.md"

	content, err := os.ReadFile(file)
	require.NoError(t, err)

	if *update {
		var (
			output   []string
			skipping bool
		)
		for _, line := range strings.Split(string(content), "\n") {
			if strings.Contains(line, "Code above generated by") {
				skipping = false
			}

			if skipping {
				continue
			}

			output = append(output, line)

			if strings.Contains(line, "Code below generated by") {
				skipping = true
				output = append(output, "````")
				output = append(output, strings.Split(buf.String(), "\n")...)
				output = append(output, "````")
			}
		}

		err = os.WriteFile(file, []byte(strings.Join(output, "\n")), 0o644)
		require.NoError(t, err)

		return
	}

	require.Containsf(t, string(content), buf.String(),
		"docs/configuration.md doesn't contain latest `charon run --help` output.\n"+
			"To fix, run: go test github.com/obolnetwork/charon/cmd -update-markdown")
}

const metricsMD = `# Prometheus Metrics

This document contains all the prometheus metrics exposed by a charon node.

All metrics contain the following labels, so they are omitted from the table below:
- 'cluster_hash': The cluster lock hash uniquely identifying the cluster.
- 'clustter_name': The cluster lock name.
- 'cluster_network': The cluster network name; goerli, mainnet, etc.
- 'cluster_peer': The name of this node in the cluster. It is determined from the operator ENR.

The 'cluster_*' labels uniquely identify a specific node's metrics which is required
when storing metrics from multiple nodes or clusters in one Prometheus instance.

| Name | Type | Help | Labels |
|---|---|---|---|
{{ range . }}| '{{ .FQName }}' | {{ .Type }} | {{ .Help }} | '{{ Join .Labels ", " }}' |
{{ end }}`

//go:generate go test . -run=TestMetricReference -update-markdown

func TestMetricReference(t *testing.T) {
	var metas []promauto.Meta
	for _, meta := range promauto.GetMetasForT(t) {
		if meta.Namespace == "go" {
			continue
		} else if meta.Namespace == "promauto" {
			continue
		}
		metas = append(metas, meta)
	}
	sort.Slice(metas, func(i, j int) bool {
		return metas[i].FQName() < metas[j].FQName()
	})

	funcs := template.FuncMap{"Join": strings.Join}

	tpl, err := template.New("").Funcs(funcs).Parse(metricsMD)
	require.NoError(t, err)

	writeMarkdown(t, "../docs/metrics.md", tpl, metas)
}

const reasonsMD = `# Duty Failure Reasons

This document enumerates and explains various duty failure reasons instrumented by the tracker component in charon.

These reasons are logged and reported via the 'core_tracker_failed_duty_reasons_total'
prometheus counter when the tracker component detects duty failures.

By understanding these failure reasons, operators can better monitor, troubleshoot, and
maintain system performance.

{{ range . }}
### Failure Reason: '{{ .Code }}'
  - *Summary*: {{ .Short }}
  - *Details*: {{ .Long }}
{{ end }}`

//go:generate go test . -run=TestTrackerReasonReference -update-markdown

func TestTrackerReasonReference(t *testing.T) {
	pkgs, err := packages.Load(
		&packages.Config{Mode: packages.NeedFiles | packages.NeedSyntax | packages.NeedTypes},
		"github.com/obolnetwork/charon/core/tracker")
	require.NoError(t, err)

	fset := pkgs[0].Fset

	var file *ast.File
	for _, f := range pkgs[0].Syntax {
		filename := fset.Position(f.FileStart).Filename
		if strings.HasSuffix(filename, "reason.go") {
			file = f
		}
	}

	require.NotNilf(t, file, "couldn't find reason.go")

	var reasons []reason
	for _, decl := range file.Decls {
		genDecl, ok := decl.(*ast.GenDecl)
		if !ok {
			continue
		}

		for _, spec := range genDecl.Specs {
			valSpec, ok := spec.(*ast.ValueSpec)
			if !ok || len(valSpec.Names) != 1 {
				continue
			} else if !strings.HasPrefix(valSpec.Names[0].Name, "reason") {
				continue
			}

			reasons = append(reasons, parseReason(valSpec.Values[0]))
		}
	}

	sort.Slice(reasons, func(i, j int) bool {
		return reasons[i].Code < reasons[j].Code
	})

	tpl, err := template.New("").Parse(reasonsMD)
	require.NoError(t, err)

	writeMarkdown(t, "../docs/reasons.md", tpl, reasons)
}

func writeMarkdown(t *testing.T, file string, tpl *template.Template, data any) {
	t.Helper()

	var buf bytes.Buffer
	err := tpl.Execute(&buf, data)
	require.NoError(t, err)

	result := strings.ReplaceAll(buf.String(), "'", "`")
	result = strings.ReplaceAll(result, "``", "")

	if *update {
		err := os.WriteFile(file, []byte(result), 0o644)
		require.NoError(t, err)

		return
	}

	content, err := os.ReadFile(file)
	require.NoError(t, err)

	//nolint:testifylint // don't remove fmt.Sprintf, it's not unnecessary
	require.Equal(t, string(content), result,
		fmt.Sprintf("%s doesn't contain latest metrics.\n"+
			"To fix, run: go test github.com/obolnetwork/charon/cmd -update-markdown", file))
}

type reason struct {
	Code  string
	Short string
	Long  string
}

func parseReason(expr ast.Expr) reason {
	compLit := expr.(*ast.CompositeLit)

	var resp reason
	for _, elt := range compLit.Elts {
		kv := elt.(*ast.KeyValueExpr)

		val := strings.Trim(kv.Value.(*ast.BasicLit).Value, `"`)

		name := kv.Key.(*ast.Ident).Name
		switch name {
		case "Code":
			resp.Code = val
		case "Short":
			resp.Short = val
		case "Long":
			resp.Long = val
		}
	}

	return resp
}