chore: new generator

Author: ldez

.golangci.yml

@@ -166,6 +166,11 @@ linters:
         linters: [gosec]
         text: "G115: integer overflow conversion uint64 -> int"
 
+      # The files created during the tests don't need to be secured.
+      - path: scripts/website/expand_templates/linters_test.go
+        linters: [gosec]
+        text: "G306: Expect WriteFile permissions to be 0600 or less"
+
 formatters:
   enable:
     - gofmt

scripts/website/expand_templates/.gitignore

@@ -0,0 +1,3 @@
+ConfigurationFile.md
+FormattersSettings.md
+LintersSettings.md

scripts/website/expand_templates/linters.go

@@ -20,22 +20,14 @@ import (
 
 const listItemPrefix = "list-item-"
 
-func getExampleSnippets() (*SettingSnippets, error) {
-	reference, err := os.ReadFile(".golangci.reference.yml")
-	if err != nil {
-		return nil, fmt.Errorf("can't read .golangci.reference.yml: %w", err)
-	}
-
-	snippets, err := extractExampleSnippets(reference)
-	if err != nil {
-		return nil, fmt.Errorf("can't extract example snippets from .golangci.reference.yml: %w", err)
-	}
-
-	return snippets, nil
-}
+const (
+	keyLinters    = "linters"
+	keyFormatters = "formatters"
+	keySettings   = "settings"
+)
 
-func getLintersListMarkdown(enabled bool) string {
-	linters, err := readJSONFile[[]*types.LinterWrapper](filepath.Join("assets", "linters-info.json"))
+func getLintersListMarkdown(enabled bool, src string) string {
+	linters, err := readJSONFile[[]*types.LinterWrapper](src)
 	if err != nil {
 		panic(err)
 	}
@@ -172,14 +164,63 @@ func spanWithID(id, title, icon string) string {
 }
 
 type SettingSnippets struct {
-	ConfigurationFile string
-	LintersSettings   string
+	ConfigurationFile  string
+	LintersSettings    string
+	FormattersSettings string
 }
 
-func extractExampleSnippets(example []byte) (*SettingSnippets, error) {
-	var data yaml.Node
-	err := yaml.Unmarshal(example, &data)
+func marshallSnippet(node *yaml.Node) (string, error) {
+	builder := &strings.Builder{}
+
+	if node.Value != "" {
+		_, _ = fmt.Fprintf(builder, "### %s\n\n", node.Value)
+	}
+	_, _ = fmt.Fprintln(builder, "```yaml")
+
+	encoder := yaml.NewEncoder(builder)
+	encoder.SetIndent(2)
+
+	err := encoder.Encode(node)
+	if err != nil {
+		return "", err
+	}
+
+	_, _ = fmt.Fprintln(builder, "```")
+	_, _ = fmt.Fprintln(builder)
+
+	return builder.String(), nil
+}
+
+type ExampleSnippetsExtractor struct {
+	referencePath string
+	assetsPath    string
+}
+
+func NewExampleSnippetsExtractor() *ExampleSnippetsExtractor {
+	return &ExampleSnippetsExtractor{
+		// TODO(ldez) replace .golangci.next.reference.yml by .golangci.reference.yml
+		referencePath: ".golangci.next.reference.yml",
+		assetsPath:    "assets",
+	}
+}
+
+func (e *ExampleSnippetsExtractor) GetExampleSnippets() (*SettingSnippets, error) {
+	reference, err := os.ReadFile(e.referencePath)
+	if err != nil {
+		return nil, fmt.Errorf("can't read .golangci.reference.yml: %w", err)
+	}
+
+	snippets, err := e.extractExampleSnippets(reference)
 	if err != nil {
+		return nil, fmt.Errorf("can't extract example snippets from .golangci.reference.yml: %w", err)
+	}
+
+	return snippets, nil
+}
+
+func (e *ExampleSnippetsExtractor) extractExampleSnippets(example []byte) (*SettingSnippets, error) {
+	var data yaml.Node
+	if err := yaml.Unmarshal(example, &data); err != nil {
 		return nil, err
 	}
 
@@ -205,7 +246,7 @@ func extractExampleSnippets(example []byte) (*SettingSnippets, error) {
 
 	for j, node := range root.Content {
 		switch node.Value {
-		case "run", "output", "linters", "linters-settings", "issues", "severity": // TODO(ldez) documentation
+		case "run", "output", keyLinters, keyFormatters, "issues", "severity":
 		default:
 			continue
 		}
@@ -233,20 +274,43 @@ func extractExampleSnippets(example []byte) (*SettingSnippets, error) {
 
 		globalNode.Content = append(globalNode.Content, node, newNode)
 
-		if node.Value == "linters-settings" { // TODO(ldez) documentation
-			snippets.LintersSettings, err = getLintersSettingSections(node, nextNode)
-			if err != nil {
-				return nil, err
+		if node.Value == keyLinters || node.Value == keyFormatters {
+			for i := 0; i < len(nextNode.Content); i++ {
+				if nextNode.Content[i].Value != keySettings {
+					continue
+				}
+
+				settingSections, err := e.getSettingSections(node, nextNode.Content[i+1])
+				if err != nil {
+					return nil, err
+				}
+
+				switch node.Value {
+				case keyLinters:
+					snippets.LintersSettings = settingSections
+
+				case keyFormatters:
+					snippets.FormattersSettings = settingSections
+				}
+
+				nextNode.Content[i+1].Content = []*yaml.Node{
+					{
+						HeadComment: fmt.Sprintf(`See the dedicated "%s.%s" documentation section.`, node.Value, nextNode.Content[i].Value),
+						Kind:        node.Kind,
+						Style:       node.Style,
+						Tag:         node.Tag,
+						Value:       "option",
+					},
+					{
+						Kind:  node.Kind,
+						Style: node.Style,
+						Tag:   node.Tag,
+						Value: "value",
+					},
+				}
+
+				i++
 			}
-
-			_, _ = builder.WriteString(
-				// TODO(ldez) documentation
-				fmt.Sprintf(
-					"### `%s` configuration\n\nSee the dedicated [linters-settings](/usage/linters) documentation section.\n\n",
-					node.Value,
-				),
-			)
-			continue
 		}
 
 		nodeSection := &yaml.Node{
@@ -275,8 +339,8 @@ func extractExampleSnippets(example []byte) (*SettingSnippets, error) {
 	return &snippets, nil
 }
 
-func getLintersSettingSections(node, nextNode *yaml.Node) (string, error) {
-	linters, err := readJSONFile[[]*types.LinterWrapper](filepath.Join("assets", "linters-info.json"))
+func (e *ExampleSnippetsExtractor) getSettingSections(node, nextNode *yaml.Node) (string, error) {
+	linters, err := readJSONFile[[]*types.LinterWrapper](filepath.Join(e.assetsPath, fmt.Sprintf("%s-info.json", node.Value)))
 	if err != nil {
 		return "", err
 	}
@@ -331,25 +395,3 @@ func getLintersSettingSections(node, nextNode *yaml.Node) (string, error) {
 
 	return builder.String(), nil
 }
-
-func marshallSnippet(node *yaml.Node) (string, error) {
-	builder := &strings.Builder{}
-
-	if node.Value != "" {
-		_, _ = fmt.Fprintf(builder, "### %s\n\n", node.Value)
-	}
-	_, _ = fmt.Fprintln(builder, "```yaml")
-
-	encoder := yaml.NewEncoder(builder)
-	encoder.SetIndent(2)
-
-	err := encoder.Encode(node)
-	if err != nil {
-		return "", err
-	}
-
-	_, _ = fmt.Fprintln(builder, "```")
-	_, _ = fmt.Fprintln(builder)
-
-	return builder.String(), nil
-}

scripts/website/expand_templates/linters_test.go

@@ -0,0 +1,32 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func Test_ExampleSnippetsExtractor_GetExampleSnippets(t *testing.T) {
+	t.Skip("only for debugging purpose")
+
+	e := &ExampleSnippetsExtractor{
+		referencePath: "../../../.golangci.next.reference.yml",
+		assetsPath:    filepath.Join("..", "..", "..", "assets"),
+	}
+
+	m, err := e.GetExampleSnippets()
+	require.NoError(t, err)
+
+	t.Log(m)
+
+	err = os.WriteFile("./ConfigurationFile.md", []byte(m.ConfigurationFile), 0644)
+	require.NoError(t, err)
+
+	err = os.WriteFile("./LintersSettings.md", []byte(m.LintersSettings), 0644)
+	require.NoError(t, err)
+
+	err = os.WriteFile("./FormattersSettings.md", []byte(m.FormattersSettings), 0644)
+	require.NoError(t, err)
+}

scripts/website/expand_templates/main.go

@@ -90,7 +90,7 @@ func processDoc(path string, replacements map[string]string, madeReplacements ma
 }
 
 func buildTemplateContext() (map[string]string, error) {
-	snippets, err := getExampleSnippets()
+	snippets, err := NewExampleSnippetsExtractor().GetExampleSnippets()
 	if err != nil {
 		return nil, err
 	}
@@ -123,10 +123,12 @@ func buildTemplateContext() (map[string]string, error) {
 	return map[string]string{
 		"CustomGCLReference":              pluginReference,
 		"LintersExample":                  snippets.LintersSettings,
+		"FormattersExample":               snippets.FormattersSettings,
 		"ConfigurationExample":            snippets.ConfigurationFile,
 		"LintersCommandOutputEnabledOnly": helps.Enable,
-		"EnabledByDefaultLinters":         getLintersListMarkdown(true),
-		"DisabledByDefaultLinters":        getLintersListMarkdown(false),
+		"EnabledByDefaultLinters":         getLintersListMarkdown(true, filepath.Join("assets", "linters-info.json")),
+		"DisabledByDefaultLinters":        getLintersListMarkdown(false, filepath.Join("assets", "linters-info.json")),
+		"Formatters":                      getLintersListMarkdown(false, filepath.Join("assets", "formatters-info.json")),
 		"ExclusionPresets":                exclusions,
 		"ThanksList":                      getThanksList(),
 		"RunHelpText":                     helps.Help,