feat: automatically generate context ignore paths

gen/docs/docs_gen.go

@@ -0,0 +1,44 @@
+// gen/docs generates the .env.example and config.gen.md
+// files for the configuration of Tinyauth. Run via:
+//
+// The generator reads the Tinyauth configuration package and using reflection it generates the
+// example files. The .env.example is used in this repo while the config.gen.md is used in the
+// documentaton alongside some warnings that are added later.
+package main
+
+import (
+	"log/slog"
+	"reflect"
+)
+
+func main() {
+	slog.Info("generating example env file")
+	generateExampleEnv()
+	slog.Info("generating config reference markdown file")
+	generateMarkdown()
+}
+
+func walkAndBuild[T any](parent reflect.Type, parentValue reflect.Value,
+	parentPath string, entries *[]T,
+	buildEntry func(child reflect.StructField, childValue reflect.Value, parentPath string, entries *[]T),
+	buildMap func(child reflect.StructField, parentPath string, entries *[]T),
+	buildChildPath func(parentPath string, childName string) string,
+) {
+	for i := 0; i < parent.NumField(); i++ {
+		field := parent.Field(i)
+		fieldType := field.Type
+		fieldValue := parentValue.Field(i)
+
+		switch fieldType.Kind() {
+		case reflect.Struct:
+			childPath := buildChildPath(parentPath, field.Name)
+			walkAndBuild[T](fieldType, fieldValue, childPath, entries, buildEntry, buildMap, buildChildPath)
+		case reflect.Map:
+			buildMap(field, parentPath, entries)
+		case reflect.Bool, reflect.String, reflect.Slice, reflect.Int:
+			buildEntry(field, fieldValue, parentPath, entries)
+		default:
+			slog.Info("unknown type", "type", fieldType.Kind())
+		}
+	}
+}

gen/docs/gen_env.go

@@ -0,0 +1,133 @@
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io/fs"
+	"log/slog"
+	"os"
+	"reflect"
+	"strings"
+
+	"github.com/tinyauthapp/tinyauth/internal/model"
+)
+
+type EnvEntry struct {
+	Name        string
+	Description string
+	Value       any
+}
+
+func generateExampleEnv() {
+	cfg := model.NewDefaultConfiguration()
+	entries := make([]EnvEntry, 0)
+
+	root := reflect.TypeOf(cfg).Elem()
+	rootValue := reflect.ValueOf(cfg).Elem()
+	rootPath := "TINYAUTH_"
+
+	walkAndBuild(root, rootValue, rootPath, &entries, buildEnvEntry, buildEnvMapEntry, buildEnvChildPath)
+	compiled := compileEnv(entries)
+
+	err := os.Remove(".env.example")
+	if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		slog.Error("failed to remove example env file", "error", err)
+		os.Exit(1)
+	}
+
+	err = os.WriteFile(".env.example", compiled, 0644)
+	if err != nil {
+		slog.Error("failed to write example env file", "error", err)
+		os.Exit(1)
+	}
+}
+
+func buildEnvEntry(child reflect.StructField, childValue reflect.Value, parentPath string, entries *[]EnvEntry) {
+	desc := child.Tag.Get("description")
+	tag := child.Tag.Get("yaml")
+
+	if tag == "-" {
+		return
+	}
+
+	value := childValue.Interface()
+
+	entry := EnvEntry{
+		Name:        parentPath + strings.ToUpper(child.Name),
+		Description: desc,
+	}
+
+	switch childValue.Kind() {
+	case reflect.Slice:
+		sl, ok := value.([]string)
+		if !ok {
+			slog.Error("invalid default value", "value", value)
+			return
+		}
+		entry.Value = strings.Join(sl, ",")
+	case reflect.String:
+		st, ok := value.(string)
+		if !ok {
+			slog.Error("invalid default value", "value", value)
+			return
+		}
+		if st != "" {
+			entry.Value = fmt.Sprintf(`"%s"`, st)
+		} else {
+			entry.Value = ""
+		}
+	default:
+		entry.Value = value
+	}
+	*entries = append(*entries, entry)
+}
+
+func buildEnvMapEntry(child reflect.StructField, parentPath string, entries *[]EnvEntry) {
+	fieldType := child.Type
+
+	if fieldType.Key().Kind() != reflect.String {
+		slog.Info("unsupported map key type", "type", fieldType.Key().Kind())
+		return
+	}
+
+	mapPath := parentPath + strings.ToUpper(child.Name) + "_name_"
+	valueType := fieldType.Elem()
+
+	if valueType.Kind() == reflect.Struct {
+		zeroValue := reflect.New(valueType).Elem()
+		walkAndBuild(valueType, zeroValue, mapPath, entries, buildEnvEntry, buildEnvMapEntry, buildEnvChildPath)
+	}
+}
+
+func buildEnvChildPath(parent string, child string) string {
+	return parent + strings.ToUpper(child) + "_"
+}
+
+func compileEnv(entries []EnvEntry) []byte {
+	buffer := bytes.Buffer{}
+
+	buffer.WriteString("# This file is automatically generated by gen/gen_env.go. Do not edit manually.\n\n")
+	buffer.WriteString("# Tinyauth example configuration\n\n")
+
+	previousSection := ""
+
+	for _, entry := range entries {
+		if strings.Count(entry.Name, "_") > 1 {
+			section := strings.Split(strings.TrimPrefix(entry.Name, "TINYAUTH_"), "_")[0]
+			if section != previousSection {
+				buffer.WriteString("\n# " + strings.ToLower(section) + " config\n\n")
+				previousSection = section
+			}
+		}
+		buffer.WriteString("# ")
+		buffer.WriteString(entry.Description)
+		buffer.WriteString("\n")
+		buffer.WriteString(entry.Name)
+		buffer.WriteString("=")
+		fmt.Fprintf(&buffer, "%v", entry.Value)
+		buffer.WriteString("\n")
+	}
+
+	return buffer.Bytes()
+}

gen/docs/gen_md.go

@@ -0,0 +1,128 @@
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io/fs"
+	"log/slog"
+	"os"
+	"reflect"
+	"strings"
+
+	"github.com/tinyauthapp/tinyauth/internal/model"
+)
+
+type MarkdownEntry struct {
+	Env         string
+	Flag        string
+	Description string
+	Default     any
+}
+
+func generateMarkdown() {
+	cfg := model.NewDefaultConfiguration()
+	entries := make([]MarkdownEntry, 0)
+
+	root := reflect.TypeOf(cfg).Elem()
+	rootValue := reflect.ValueOf(cfg).Elem()
+	rootPath := "tinyauth."
+
+	walkAndBuild(root, rootValue, rootPath, &entries, buildMdEntry, buildMdMapEntry, buildMdChildPath)
+	compiled := compileMd(entries)
+
+	err := os.Remove("config.gen.md")
+	if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		slog.Error("failed to remove example env file", "error", err)
+		os.Exit(1)
+	}
+
+	err = os.WriteFile("config.gen.md", compiled, 0644)
+	if err != nil {
+		slog.Error("failed to write example env file", "error", err)
+		os.Exit(1)
+	}
+}
+
+func buildMdEntry(child reflect.StructField, childValue reflect.Value, parentPath string, entries *[]MarkdownEntry) {
+	desc := child.Tag.Get("description")
+	tag := child.Tag.Get("yaml")
+
+	if tag == "-" {
+		return
+	}
+
+	value := childValue.Interface()
+
+	entry := MarkdownEntry{
+		Env:         strings.ToUpper(strings.ReplaceAll(parentPath, ".", "_")) + strings.ToUpper(child.Name),
+		Flag:        fmt.Sprintf("--%s%s", strings.TrimPrefix(parentPath, "tinyauth."), strings.ToLower(child.Name)),
+		Description: desc,
+	}
+
+	switch childValue.Kind() {
+	case reflect.Slice:
+		sl, ok := value.([]string)
+		if !ok {
+			slog.Error("invalid default value", "value", value)
+			return
+		}
+		entry.Default = fmt.Sprintf("`%s`", strings.Join(sl, ","))
+	default:
+		entry.Default = fmt.Sprintf("`%v`", value)
+	}
+	*entries = append(*entries, entry)
+}
+
+func buildMdMapEntry(child reflect.StructField, parentPath string, entries *[]MarkdownEntry) {
+	fieldType := child.Type
+
+	if fieldType.Key().Kind() != reflect.String {
+		slog.Info("unsupported map key type", "type", fieldType.Key().Kind())
+		return
+	}
+
+	tag := child.Tag.Get("yaml")
+
+	if tag == "-" {
+		return
+	}
+
+	mapPath := parentPath + tag + ".[name]."
+	valueType := fieldType.Elem()
+
+	if valueType.Kind() == reflect.Struct {
+		zeroValue := reflect.New(valueType).Elem()
+		walkAndBuild(valueType, zeroValue, mapPath, entries, buildMdEntry, buildMdMapEntry, buildMdChildPath)
+	}
+}
+
+func buildMdChildPath(parent string, child string) string {
+	return parent + strings.ToLower(child) + "."
+}
+
+func compileMd(entries []MarkdownEntry) []byte {
+	buffer := bytes.Buffer{}
+
+	buffer.WriteString("<!--- This file is automatically generated by gen/gen_md.go. Do not edit manually. --->\n\n")
+	buffer.WriteString("# Tinyauth configuration reference\n\n")
+	buffer.WriteString("| Environment | Flag | Description | Default |\n")
+	buffer.WriteString("| - | - | - | - |\n")
+
+	previousSection := ""
+
+	for _, entry := range entries {
+		if strings.Count(entry.Env, "_") > 1 {
+			section := strings.Split(strings.TrimPrefix(entry.Env, "TINYAUTH_"), "_")[0]
+			if section != previousSection {
+				buffer.WriteString("\n## " + strings.ToLower(section) + "\n\n")
+				buffer.WriteString("| Environment | Flag | Description | Default |\n")
+				buffer.WriteString("| - | - | - | - |\n")
+				previousSection = section
+			}
+		}
+		fmt.Fprintf(&buffer, "| `%s` | `%s` | %s | %s |\n", entry.Env, entry.Flag, entry.Description, entry.Default)
+	}
+
+	return buffer.Bytes()
+}