openapi.go

//go:build ignore

// This file reads the openapi.yaml files for the SRA config APIs and appends
// the specific field documentation to the terraform generated document
// files. It expects the openapi.yaml files to be in the ./openapi
// directory and the generated docs to be in ./docs

package main

import (
	"bufio"
	"errors"
	"fmt"
	"io"
	"log"
	"os"
	"path/filepath"
	"regexp"
	"strings"

	"gopkg.in/yaml.v3"
)

func main() {
	log.SetOutput(os.Stderr)
	log.Println("Starting doc generation")
	ParseOpenAPI()
}

// The list of files that we will append documentation to. This is a map of
// filepath to ObjectName in the yaml file.
var typeMap = map[string]string{
	"docs/data-sources/group_policy_list.md":             "GroupPolicy",
	"docs/data-sources/jump_client_installer_list.md":    "JumpClientInstaller",
	"docs/data-sources/jump_group_list.md":               "JumpGroup",
	"docs/data-sources/jump_item_role_list.md":           "JumpItemRole",
	"docs/data-sources/jump_policy_list.md":              "JumpPolicy",
	"docs/data-sources/jumpoint_list.md":                 "Jumpoint",
	"docs/data-sources/protocol_tunnel_jump_list.md":     "ProtocolTunnelJumpItem",
	"docs/data-sources/remote_rdp_list.md":               "RemoteRdpJumpItem",
	"docs/data-sources/remote_vnc_list.md":               "RemoteVncJumpItem",
	"docs/data-sources/session_policy_list.md":           "SessionPolicy",
	"docs/data-sources/shell_jump_list.md":               "ShellJumpItem",
	"docs/data-sources/single_vault_ssh_account_list.md": "VaultSSHAccount",
	"docs/data-sources/vault_account_group_list.md":      "VaultAccountGroup",
	"docs/data-sources/vault_account_list.md":            "VaultAccount",
	"docs/data-sources/vault_account_policy_list.md":     "VaultAccountPolicy",
	"docs/data-sources/web_jump_list.md":                 "WebJumpItem",
	// "docs/data-sources/vault_secret.md" -> Fully defined in the schema

	"docs/resources/jump_client_installer.md":           "JumpClientInstaller",
	"docs/resources/jump_group.md":                      "JumpGroup",
	"docs/resources/jumpoint.md":                        "Jumpoint",
	"docs/resources/protocol_tunnel_jump.md":            "ProtocolTunnelJumpItem",
	"docs/resources/remote_rdp.md":                      "RemoteRdpJumpItem",
	"docs/resources/remote_vnc.md":                      "RemoteVncJumpItem",
	"docs/resources/shell_jump.md":                      "ShellJumpItem",
	"docs/resources/vault_account_group.md":             "VaultAccountGroup",
	"docs/resources/vault_account_policy.md":            "VaultAccountPolicy",
	"docs/resources/vault_ssh_account.md":               "VaultSSHAccount",
	"docs/resources/vault_username_password_account.md": "VaultUsernamePasswordAccount",
	"docs/resources/vault_token_account.md":             "VaultTokenAccount",
	"docs/resources/web_jump.md":                        "WebJumpItem",
}

// Regex matching the generated attribute lines: - `attribute` (Type)
var propertyName = regexp.MustCompile("^- `([a-z_]+)` (\\([A-Z][a-z]+\\))")

// These types are here to help parse the relevant parts of the yaml files
// We are specifically interested in the components -> schemas section,
// as that is where the object definitions live
type SubMap map[string]map[string]interface{}

type Component struct {
	Schema SubMap `yaml:"schemas"`
}

type Data struct {
	Components Component `yaml:"components"`
}

const (
	// Root folder for the generated docs
	root = "docs"
	// Line that triggers the start of the attributes section for resources
	resourceTrigger = "<!-- schema generated by tfplugindocs -->"
	// Prefix for a resource doc file's path
	resourcePath = "docs/resources"
	// Line that triggers the start of the attributes section for data sources
	datasourceTrigger = "### Nested Schema for"
	// Prefix for a data source doc file's path
	datasourcePath = "docs/data-sources"
)

func ParseOpenAPI() {
	praYamlData, rsYamlData := getYamlData()

	err := filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
		log.Printf("📄 Processing doc path %s\n", path)
		if err != nil {
			return err
		}

		if key, processFile := typeMap[path]; processFile {
			log.Printf("📄 Processing doc file %s (%s)\n", path, key)
			newLines := []string{}
			praItem := praYamlData.Components.Schema[key]
			rsItem := rsYamlData.Components.Schema[key]

			triggerLine := ""
			if strings.HasPrefix(path, resourcePath) {
				triggerLine = resourceTrigger
			} else if strings.HasPrefix(path, datasourcePath) {
				triggerLine = datasourceTrigger
			} else {
				log.Printf("Really unexpected file path [%s]\n", path)
				return nil
			}

			{
				docFile := getFileReader(path)
				defer docFile.Close()

				reader := bufio.NewReader(docFile)
				startProcessing := false
				for {
					text, err := reader.ReadString('\n')
					if err != nil {
						if err == io.EOF {
							break
						}
						panic(err)
					}

					if strings.HasPrefix(text, triggerLine) {
						startProcessing = true
					} else if startProcessing && propertyName.MatchString(text) {
						subStr := propertyName.FindStringSubmatch(text)
						log.Printf("  🌈 %+v", subStr)

						praDesc, praErr := extractVal([]string{"properties", subStr[1], "description"}, praItem)
						rsDesc, rsErr := extractVal([]string{"properties", subStr[1], "description"}, rsItem)
						if praErr != nil && rsErr != nil {
							log.Printf("No description key found")
						} else {
							desc := ""
							// Prefer PRA description
							if praDesc != nil {
								desc = *praDesc
							} else {
								desc = *rsDesc
							}

							if praDesc != nil && rsDesc == nil {
								desc = fmt.Sprintf("%s _This field only applies to PRA_", desc)
							} else if praDesc == nil && rsDesc != nil {
								desc = fmt.Sprintf("%s _This field only applies to RS_", desc)
							}

							text = fmt.Sprintf("- `%s` %s %s\n", subStr[1], subStr[2], desc)
							log.Printf("    🍻 %+v", text)
						}
					}

					newLines = append(newLines, text)
				}
			}

			if err := os.WriteFile(path, []byte(strings.Join(newLines, "")), info.Mode()); err != nil {
				panic(err)
			}
			log.Printf("✅ %s (%s)\n", path, key)
		}

		return nil
	})

	if err != nil {
		log.Fatal(err)
		panic(err)
	}
}

func getYamlData() (Data, Data) {
	praYaml, err := os.ReadFile("./openapi/bt-pra-configuration.openapi.yaml")

	if err != nil {
		log.Fatal(err)
		panic(err)
	}

	praYamlData := Data{}
	if err := yaml.Unmarshal(praYaml, &praYamlData); err != nil {
		log.Fatal(err)
		panic(err)
	}

	rsYaml, err := os.ReadFile("./openapi/bt-rs-configuration.openapi.yaml")

	if err != nil {
		log.Fatal(err)
		panic(err)
	}

	rsYamlData := Data{}
	if err := yaml.Unmarshal(rsYaml, &rsYamlData); err != nil {
		log.Fatal(err)
		panic(err)
	}

	return praYamlData, rsYamlData
}

func getFileReader(filePath string) *os.File {
	path, err := filepath.Abs(filePath)
	if err != nil {
		panic(err)
	}
	inFile, err := os.Open(path)
	if err != nil {
		panic(errors.New(err.Error() + `: ` + path))
	}
	return inFile
}

func extractVal(val []string, item map[string]interface{}) (*string, error) {
	final := ""
	currentLevel := item
	ok := true

	for i, v := range val {
		if i == len(val)-1 {
			final, ok = currentLevel[v].(string)
			if !ok {
				log.Printf("🛑 failed to convert string %+v [%v]", currentLevel, v)
				return nil, fmt.Errorf("failed to convert string")
			}
		} else {
			currentLevel, ok = currentLevel[v].(map[string]interface{})
			if !ok {
				log.Printf("🛑 failed to convert map %+v [%v]", currentLevel, v)
				return nil, fmt.Errorf("failed to convert map")
			}
		}
	}

	return &final, nil
}