avorion-docgen/class.go

package main

import (
	_ "embed"
	"fmt"
	"os"
	"path/filepath"
	"strings"
	"text/template"

	logger "git.site.quack-lab.dev/dave/cylogger"
	"github.com/PuerkitoBio/goquery"
)

//go:embed class.tmpl
var templatestr string
var classTemplate *template.Template

var fns = template.FuncMap{
	"plus1": func(x int) int {
		return x + 1
	},
}

func init() {
	log := logger.Default.WithPrefix("init")
	log.Info("Initializing template")
	var err error
	classTemplate, err = template.New("class").Funcs(fns).Parse(templatestr)
	if err != nil {
		logger.Error("Error parsing template: %v", err)
		return
	}
	log.Info("Template initialized successfully")
}

type (
	Class struct {
		ClassName    string
		Fields       []Field
		Methods      []Method
		Constructors []Constructor
	}
	Field struct {
		Name    string
		Type    string
		Comment string
	}
	Method struct {
		Name    string
		Params  []Param
		Returns []Return
		Comment string
	}
	Param struct {
		Name    string
		Type    string
		Comment string
	}
	Return struct {
		Type    string
		Comment string
	}
	Constructor struct {
		Params  []Param
		Comment string
	}
)

func (c *Class) GetOutFile(root string) (*os.File, error) {
	log := logger.Default.WithPrefix("GetOutFile")
	log.Debug("Getting output file for class: %s", c.ClassName)

	if c.ClassName == "" {
		log.Error("ClassName is empty")
		return nil, fmt.Errorf("ClassName is empty")
	}

	filename := fmt.Sprintf("%s.lua", c.ClassName)
	log.Trace("Original filename: %s", filename)

	filename = strings.ReplaceAll(filename, " ", "")
	filename = strings.ReplaceAll(filename, "-", "")
	filename = strings.ReplaceAll(filename, ",", "")
	filename = strings.ReplaceAll(filename, ":", "")
	log.Trace("Cleaned filename: %s", filename)

	filePath := filepath.Join(root, filename)
	filePath = filepath.Clean(filePath)
	log.Debug("Full file path: %s", filePath)

	f, err := os.Create(filePath)
	if err != nil {
		log.Error("Error creating file: %v", err)
		return nil, err
	}

	log.Info("Successfully created output file: %s", filePath)
	return f, nil
}

func (c *Class) Write(root string, tmpl *template.Template) error {
	log := logger.Default.WithPrefix("Write")
	log.Info("Writing class %s to output", c.ClassName)

	outfile, err := c.GetOutFile(root)
	if err != nil {
		log.Error("Error creating output file %v: %v", c.ClassName, err)
		return fmt.Errorf("error creating output file %v: %v", c.ClassName, err)
	}

	log.Debug("Executing template for class: %s", c.ClassName)
	err = tmpl.Execute(outfile, c)
	if err != nil {
		log.Error("Error writing output file %v: %v", c.ClassName, err)
		return fmt.Errorf("error writing output file %v: %v", c.ClassName, err)
	}

	log.Info("Successfully wrote class %s to output", c.ClassName)
	return nil
}

func ParseClass(file string) (*Class, error) {
	log := logger.Default.WithPrefix(file)
	log.Info("Starting to parse file")

	res := Class{
		Fields:       []Field{},
		Methods:      []Method{},
		Constructors: []Constructor{},
	}

	log.Debug("Opening file: %s", file)
	filehandle, err := os.Open(file)
	if err != nil {
		log.Error("Error opening file: %v", err)
		return nil, fmt.Errorf("error opening file: %w", err)
	}

	log.Debug("Creating goquery document from file")
	doc, err := goquery.NewDocumentFromReader(filehandle)
	if err != nil {
		log.Error("Error parsing file: %v", err)
		return nil, fmt.Errorf("error parsing file: %w", err)
	}

	log.Debug("Looking for class name")
	class := doc.Find("div.floatright > h1")
	if class.Length() == 0 {
		log.Error("No class found in document")
		return nil, fmt.Errorf("no class found")
	}
	res.ClassName = strings.TrimSpace(class.Text())
	log.Info("Found class: %s", res.ClassName)

	log.Debug("Parsing constructors")
	res.Constructors, err = getConstructors(doc, log)
	if err != nil {
		log.Error("Error getting constructors: %v", err)
		return nil, fmt.Errorf("error getting constructors: %w", err)
	}
	log.Debug("Found %d constructors", len(res.Constructors))

	log.Debug("Parsing fields")
	res.Fields, err = getFields(doc, log)
	if err != nil {
		log.Error("Error getting fields: %v", err)
		return nil, fmt.Errorf("error getting fields: %w", err)
	}
	log.Debug("Found %d fields", len(res.Fields))

	log.Debug("Parsing methods")
	res.Methods, err = getMethods(doc, log)
	if err != nil {
		log.Error("Error getting methods: %v", err)
		return nil, fmt.Errorf("error getting methods: %w", err)
	}
	log.Debug("Found %d methods", len(res.Methods))

	log.Info("Parsing complete for class: %s", res.ClassName)
	logger.Dump("Final parsed class", res)
	return &res, nil
}

// TODO: Implement parsing comments for return values
// Something like "---returns (something) -> comment"
// Where "-> comment" is only shown if there's a comment
// And "---returns" only if there's a return type
// This is NOT a luals annotation because we can not use annotations on @overload
// But just a regular plain Lua comment
// TODO: Implement parsing comments for classes and constructors
func getConstructors(doc *goquery.Document, log *logger.Logger) ([]Constructor, error) {
	log.Debug("Starting constructor parsing")
	res := []Constructor{}

	codeblocks := doc.Find("div.floatright > div.codecontainer")
	log.Trace("Found %d code blocks", codeblocks.Length())
	if codeblocks.Length() == 0 {
		log.Error("No codeblocks found")
		return res, fmt.Errorf("no codeblocks found")
	}

	// The first code block should be the constructor
	// So far I have not found any classes with overloaded constructors...
	// So I can not handle that case yet
	constructorBlock := codeblocks.Eq(0)
	log.Debug("Processing first code block as constructor")

	constructor := constructorBlock.Find("div.function")
	paramTypes := constructor.Find("span.type")
	paramNames := constructor.Find("span.parameter")

	log.Trace("Found %d parameter types and %d parameter names", paramTypes.Length(), paramNames.Length())

	resConstructor := Constructor{}
	paramTypes.Each(func(i int, s *goquery.Selection) {
		pname := strings.TrimSpace(paramNames.Eq(i).Text())
		ptype := strings.TrimSpace(paramTypes.Eq(i).Text())
		ptype = MapType(ptype)

		log.Trace("Parameter %d: name='%s', type='%s'", i, pname, ptype)

		resConstructor.Params = append(resConstructor.Params, Param{
			Name:    pname,
			Type:    ptype,
			Comment: "",
		})
	})

	constructorDetails := constructorBlock.Children().Eq(1)
	constructorParameterDetails := constructorDetails.Find("span.parameter")
	log.Trace("Found %d constructor parameter details", constructorParameterDetails.Length())

	constructorParameterDetails.Each(func(i int, s *goquery.Selection) {
		param := strings.TrimSpace(s.Text())
		parameterParent := s.Parent()
		parameterDescription := parameterParent.Text()
		parameterDescription = strings.ReplaceAll(parameterDescription, fmt.Sprintf("\n%s\n", param), "")
		parameterDescription = strings.TrimSpace(parameterDescription)

		log.Trace("Parameter %d comment: '%s'", i, parameterDescription)
		resConstructor.Params[i].Comment = parameterDescription
	})

	constructorBlock.Find("div:not(.function):not(.indented) > p:not(:has(*))").Each(func(i int, s *goquery.Selection) {
		comment := strings.TrimSpace(s.Text())
		log.Trace("Constructor comment line %d: '%s'", i, comment)
		resConstructor.Comment += comment + "\n"
		resConstructor.Comment = strings.TrimSpace(resConstructor.Comment)
	})

	log.Trace("Final constructor: %+v", resConstructor)
	log.Debug("Constructor parsing complete")
	return append(res, resConstructor), nil
}

func getFields(doc *goquery.Document, log *logger.Logger) ([]Field, error) {
	log.Debug("Starting field parsing")
	res := []Field{}

	properties := doc.Find("div.floatright > div.codecontainer#Properties")
	log.Trace("Found properties container: %d elements", properties.Length())

	properties.ChildrenFiltered("div").Each(func(i int, s *goquery.Selection) {
		property := Field{}
		property.Name = strings.TrimSpace(s.Find("span.property").Text())
		property.Type = strings.TrimSpace(s.Find("span.type").Text())
		property.Type = MapType(property.Type)
		comment := s.Find("td[align='right']").Text()
		if comment != "" {
			property.Comment = strings.TrimSpace(comment)
		}

		log.Trace("Field %d: name='%s', type='%s', comment='%s'", i, property.Name, property.Type, property.Comment)
		res = append(res, property)
	})

	log.Debug("Found %d fields", len(res))
	return res, nil
}

// TODO: Implement parsing return value types and comments
func getMethods(doc *goquery.Document, log *logger.Logger) ([]Method, error) {
	log.Debug("Starting method parsing")
	res := []Method{}

	codeblocks := doc.Find("div.floatright > div.codecontainer")
	log.Trace("Found %d code blocks for method parsing", codeblocks.Length())

	codeblocks.ChildrenFiltered("div.function").Each(func(i int, s *goquery.Selection) {
		method := Method{}
		method.Name = strings.TrimSpace(s.AttrOr("id", ""))
		method.Comment = strings.TrimSpace(s.Find("span.comment").Text())

		log.Trace("Processing method %d: name='%s', comment='%s'", i, method.Name, method.Comment)

		types := s.Find("span.type")
		parameters := s.Find("span.parameter")
		log.Trace("Method %s has %d types and %d parameters", method.Name, types.Length(), parameters.Length())

		types.Each(func(i int, s *goquery.Selection) {
			param := Param{}
			param.Name = strings.TrimSpace(parameters.Eq(i).Text())
			if IsReservedKeyword(param.Name) {
				log.Trace("Parameter name '%s' is reserved keyword, prefixing with __", param.Name)
				param.Name = fmt.Sprintf("__%s", param.Name)
			}
			param.Type = strings.TrimSpace(types.Eq(i).Text())
			param.Type = MapType(param.Type)

			log.Trace("Method %s parameter %d: name='%s', type='%s'", method.Name, i, param.Name, param.Type)
			method.Params = append(method.Params, param)
		})

		log.Trace("Method %s has %d parameters", method.Name, len(method.Params))
		res = append(res, method)
	})

	log.Debug("Found %d methods", len(res))
	return res, nil
}