annotations.go

package annot8

import (
	"fmt"
	"go/ast"
	"go/parser"
	"go/token"
	"log/slog"
	"path/filepath"
	"strconv"
	"strings"
)

// Annotation represents parsed swagger annotations
type Annotation struct {
	Summary     string
	Description string
	Tags        []string
	Accept      []string
	Produce     []string
	Security    []string
	Parameters  []ParamAnnotation
	Success     *SuccessResponse
	Failures    []ErrorResponse
}

type SuccessResponse struct {
	StatusCode  int
	DataType    string
	Description string
	IsWrapped   bool // true if {data} marker was used
}

type ParamAnnotation struct {
	Name        string
	In          string
	Type        string
	Required    bool
	Description string
}

type ErrorResponse struct {
	StatusCode  int
	Type        string
	Description string
}

// AnnotationParsingError represents errors encountered while parsing annotation lines.
// It contains one or more error messages for malformed annotation directives.
type AnnotationParsingError struct {
	Messages []string
}

func (e *AnnotationParsingError) Error() string {
	return "annotation parsing errors: " + strings.Join(e.Messages, "; ")
}

// ParseAnnotations reads the AST for the provided Go source file (or the
// project's TypeIndex cache) and extracts comment block annotations for the
// function named by `functionName`.
//
// Behavior notes:
//   - Returns nil, nil if no suitable file or comments are found (not an error).
//   - Uses a local AST file cache to avoid repeated parsing of the same file.
//   - Accepts fully-qualified function names (e.g. "menu.handler.List") and
//     extracts the simple function name before matching the AST node.

func ParseAnnotations(filePath, functionName string) (*Annotation, error) {
	normalizedFilePath := filepath.ToSlash(filePath)
	if strings.Contains(normalizedFilePath, "\\") {
		normalizedFilePath = strings.ReplaceAll(normalizedFilePath, "\\", "/")
	}
	if filePath == "" || filePath == "<autogenerated>" ||
		strings.Contains(normalizedFilePath, "/go/pkg/mod/") ||
		!strings.HasSuffix(filePath, ".go") {
		return nil, nil
	}

	ensureTypeIndex() // Ensure typeIndex is initialized

	// Look up the AST in TypeIndex using normalized paths
	astFile := typeIndex.LookupFile(normalizedFilePath)

	// If no AST file found in TypeIndex, attempt to parse it manually.
	// This ensures that tests using local filenames or temporary files still work.
	if astFile == nil {
		slog.Debug("[annot8] ParseAnnotations: file not found in TypeIndex, attempting manual parse", "filePath", normalizedFilePath)
		fset := token.NewFileSet()
		var err error
		// Parse only comments as we only need those for annotations
		astFile, err = parser.ParseFile(fset, normalizedFilePath, nil, parser.ParseComments)
		if err != nil {
			slog.Warn("[annot8] ParseAnnotations: failed to parse file manually", "filePath", normalizedFilePath, "error", err)
			return nil, nil // Cannot proceed without AST
		}
	}

	// Update filePath and normalizedFilePath if we found a match via case-insensitive lookup
	// (though LookupFile doesn't return the path, we can assume it found it if astFile != nil and it was from index)
	normalizedFilePath = filepath.ToSlash(filePath)
	if strings.Contains(normalizedFilePath, "\\") {
		normalizedFilePath = strings.ReplaceAll(normalizedFilePath, "\\", "/")
	}

	// If a qualified function name was provided (e.g. "menu.handler_addons.List")
	// and the resolved file doesn't look like the intended one, try to find
	// a better match using the project's TypeIndex. This helps disambiguate
	// identical simple function names (like "List") that exist across
	// different packages/files (for example, menu and subscription both having
	// handler_addons.go with a List method).
	if strings.Contains(functionName, ".") && typeIndex != nil {
		slog.Debug(
			"[annot8] ParseAnnotations: starting TypeIndex disambiguation",
			"filePath",
			filePath,
			"functionName",
			functionName,
		)
		parts := strings.Split(functionName, ".")
		// We expect buildUniqueFunctionName to emit packageDir.fileName.funcName
		if len(parts) >= 3 {
			fileName := parts[len(parts)-2]
			packageDir := parts[len(parts)-3]
			// If current astFile/filePath does not already look like the qualified one,
			// search the TypeIndex for a matching file path and use its parsed AST.
			if astFile == nil ||
				(!strings.Contains(normalizedFilePath, "/"+fileName+".go") && !strings.Contains(normalizedFilePath, "/"+packageDir+"/")) {
				for p, f := range typeIndex.files {
					normalizedCandidate := filepath.ToSlash(p)
					if strings.HasSuffix(normalizedCandidate, "/"+fileName+".go") &&
						strings.Contains(normalizedCandidate, "/"+packageDir+"/") {
						astFile = f
						filePath = p
						normalizedFilePath = filepath.ToSlash(filePath)
						normalizedFilePath = normalizedCandidate
						slog.Debug(
							"[annot8] ParseAnnotations: selected AST from TypeIndex",
							"selected",
							p,
							"targetFileName",
							fileName,
							"packageDir",
							packageDir,
						)
						break
					}
				}
			}
		} else if len(parts) == 2 {
			// Possible formats: package.func or file.func - try to match by file or package
			cand := parts[0]
			if astFile == nil || (!strings.Contains(normalizedFilePath, "/"+cand+".go") && !strings.Contains(normalizedFilePath, "/"+cand+"/")) {
				for p, f := range typeIndex.files {
					normalizedCandidate := filepath.ToSlash(p)
					if strings.HasSuffix(normalizedCandidate, "/"+cand+".go") || strings.Contains(normalizedCandidate, "/"+cand+"/") {
						astFile = f
						filePath = p
						normalizedFilePath = filepath.ToSlash(filePath)
						normalizedFilePath = normalizedCandidate
						slog.Debug("[annot8] ParseAnnotations: selected AST from TypeIndex", "selected", p, "candidate", cand)
						break
					}
				}
			}
		}
	} else {
		slog.Debug("[annot8] ParseAnnotations: no TypeIndex disambiguation performed", "filePath", filePath, "functionName", functionName)
	}

	// Find the function and its comment
	var comment string

	// Extract actual function name from qualified name (e.g., "menu.List" -> "List")
	actualFunctionName := functionName
	if dotIndex := strings.LastIndex(functionName, "."); dotIndex != -1 {
		actualFunctionName = functionName[dotIndex+1:]
	}

	slog.Debug(
		"[annot8] ParseAnnotations: locating function comments",
		"filePath",
		filePath,
		"qualified",
		functionName,
		"actual",
		actualFunctionName,
	)

	for _, decl := range astFile.Decls {
		if funcDecl, ok := decl.(*ast.FuncDecl); ok {
			if funcDecl.Name.Name == actualFunctionName {
				if funcDecl.Doc != nil {
					comment = funcDecl.Doc.Text()
					slog.Debug(
						"[annot8] ParseAnnotations: comment block found",
						"file",
						filePath,
						"function",
						actualFunctionName,
					)
					break
				}
				// found function but no doc comments
				slog.Debug(
					"[annot8] ParseAnnotations: function found but missing comments",
					"file",
					filePath,
					"function",
					actualFunctionName,
				)
			}
		}
	}

	if comment == "" {
		slog.Debug(
			"[annot8] ParseAnnotations: no annotation comment found",
			"file",
			filePath,
			"function",
			actualFunctionName,
		)
		return nil, nil
	}

	annotation, err := parseAnnotationComment(comment)
	if err != nil {
		slog.Warn("[annot8] ParseAnnotations: parsing errors", "error", err)
	}

	return annotation, nil
}

// parseAnnotationComment analyses a block of comment text and builds an
// Annotation structure by scanning for known tokens such as @Summary,
// @Param, @Success, and @Failure. It accumulates parsing errors and
// returns them as an AnnotationParsingError when malformed lines are
// encountered.
func parseAnnotationComment(comment string) (*Annotation, error) {
	var errs []string
	annotation := &Annotation{}
	lines := strings.Split(comment, "\n")

	for _, line := range lines {
		line = strings.TrimSpace(line)
		if line == "" {
			continue
		}

		switch {
		case strings.HasPrefix(line, "@Summary "):
			annotation.Summary = strings.TrimPrefix(line, "@Summary ")
		case strings.HasPrefix(line, "@Description "):
			annotation.Description = strings.TrimPrefix(line, "@Description ")
		case strings.HasPrefix(line, "@Tags "):
			tags := strings.TrimPrefix(line, "@Tags ")
			annotation.Tags = strings.Split(tags, ",")
			for i := range annotation.Tags {
				annotation.Tags[i] = strings.TrimSpace(annotation.Tags[i])
			}

		case strings.HasPrefix(line, "@Accept"):
			accept := strings.TrimSpace(strings.TrimPrefix(line, "@Accept"))
			if accept == "" {
				accept = "application/json"
			}
			annotation.Accept = append(annotation.Accept, accept)

		case strings.HasPrefix(line, "@Produce"):
			produce := strings.TrimSpace(strings.TrimPrefix(line, "@Produce"))
			if produce == "" {
				produce = "application/json"
			}
			annotation.Produce = append(annotation.Produce, produce)

		case strings.HasPrefix(line, "@Security"):
			security := strings.TrimSpace(strings.TrimPrefix(line, "@Security"))
			annotation.Security = append(annotation.Security, security)

		case strings.HasPrefix(line, "@Param "):
			param, err := parseParamAnnotation(line)
			if err != nil {
				errs = append(errs, err.Error())
			} else {
				annotation.Parameters = append(annotation.Parameters, *param)
			}

		case strings.HasPrefix(line, "@Success "):
			succ, err := parseSuccessAnnotation(line)
			if err != nil {
				errs = append(errs, err.Error())
			} else {
				annotation.Success = succ
			}

		case strings.HasPrefix(line, "@Failure "):
			fail, err := parseFailureAnnotation(line)
			if err != nil {
				errs = append(errs, err.Error())
			} else {
				annotation.Failures = append(annotation.Failures, *fail)
			}
		}
	}

	if len(errs) > 0 {
		return annotation, &AnnotationParsingError{Messages: errs}
	}
	return annotation, nil
}

// parseSuccessAnnotation parses a single @Success annotation line and
// converts it into a SuccessResponse containing status code, data type
// and an optional quoted description.
func parseSuccessAnnotation(line string) (*SuccessResponse, error) {
	slog.Debug("[annot8] parseSuccessAnnotation: called", "line", line)
	// @Success 200 {data} Type "Description"
	content := strings.TrimPrefix(line, "@Success ")
	parts := strings.Fields(content)
	if len(parts) < 2 {
		return nil, fmt.Errorf("invalid @Success annotation: %s", line)
	}

	statusCode, err := strconv.Atoi(parts[0])
	if err != nil {
		return nil, err
	}

	response := &SuccessResponse{StatusCode: statusCode}
	remaining := strings.Join(parts[1:], " ")

	// Extract type from {data} Type or {object} Type
	if strings.Contains(remaining, "{data}") || strings.Contains(remaining, "{object}") {
		if strings.Contains(remaining, "{data}") {
			response.IsWrapped = true
		}
		remaining = strings.Replace(remaining, "{data}", "", 1)
		remaining = strings.Replace(remaining, "{object}", "", 1)
		remaining = strings.TrimSpace(remaining)

		parts := strings.Fields(remaining)
		if len(parts) > 0 {
			response.DataType = parts[0]
		}
	}

	// Extract description from quotes
	if start := strings.Index(remaining, "\""); start != -1 {
		if end := strings.LastIndex(remaining, "\""); end != -1 && end > start {
			response.Description = remaining[start+1 : end]
		}
	}

	return response, nil
}

// parseParamAnnotation parses a single @Param line into a ParamAnnotation
// structure. Expected format is: @Param <name> <in> <type> <required> "desc"
func parseParamAnnotation(line string) (*ParamAnnotation, error) {
	slog.Debug("[annot8] parseParamAnnotation: called", "line", line)
	// @Param name in type required "description"
	content := strings.TrimPrefix(line, "@Param ")
	parts := strings.Fields(content)
	if len(parts) < 4 {
		return nil, fmt.Errorf("invalid @Param annotation: %s", line)
	}

	param := &ParamAnnotation{
		Name:     parts[0],
		In:       parts[1],
		Type:     parts[2],
		Required: parts[3] == "true",
	}

	// Extract description
	if start := strings.Index(content, "\""); start != -1 {
		if end := strings.LastIndex(content, "\""); end != -1 && end > start {
			param.Description = content[start+1 : end]
		}
	}

	return param, nil
}

// parseFailureAnnotation parses @Failure lines into an ErrorResponse. It
// extracts the numeric status code and optional quoted description.
func parseFailureAnnotation(line string) (*ErrorResponse, error) {
	slog.Debug("[annot8] parseFailureAnnotation: called", "line", line)
	// @Failure 400 {object} Type "Description"
	content := strings.TrimPrefix(line, "@Failure ")
	parts := strings.Fields(content)
	if len(parts) < 2 {
		return nil, fmt.Errorf("invalid @Failure annotation: %s", line)
	}

	statusCode, err := strconv.Atoi(parts[0])
	if err != nil {
		return nil, err
	}

	failure := &ErrorResponse{StatusCode: statusCode}

	// Extract description
	if start := strings.Index(content, "\""); start != -1 {
		if end := strings.LastIndex(content, "\""); end != -1 && end > start {
			failure.Description = content[start+1 : end]
		}
	}

	return failure, nil
}