parser

func GetPackages(projectRoot string) ([]string, error)

{
	absRoot, err := filepath.Abs(projectRoot)
	if err != nil {
		return nil, err
	}

	cfg := &packages.Config{
		Mode: packages.NeedFiles,
		Dir:  absRoot,
	}

	pkgs, err := packages.Load(cfg, "./...")
	if err != nil {
		return nil, err
	}

	var packageDirs []string
	for _, pkg := range pkgs {
		if len(pkg.GoFiles) > 0 {
			dir := filepath.Dir(pkg.GoFiles[0])

			// We intentionally skip the root directory to focus on subpackages
			if dir == absRoot {
				continue
			}
			packageDirs = append(packageDirs, dir)
		}
	}

	return packageDirs, nil
}

func ParseEntitiesInPackage(projectRoot string, pkgPath string, relPath string) ([]EntityInfo, []ImportInfo, error)

{
	fset := token.NewFileSet()
	pkgs, err := parser.ParseDir(fset, pkgPath, nil, parser.ParseComments)
	if err != nil {
		return nil, nil, err
	}

	var entities []EntityInfo
	var imports []ImportInfo
	var methodsByType = make(map[string][]EntityInfo)
	var interfaces = make(map[string]EntityInfo)
	var entityIndex = make(map[string]EntityInfo)

	extractors := map[string]EntityExtractor{
		"function":  FunctionExtractor{},
		"method":    MethodExtractor{},
		"struct":    StructExtractor{},
		"interface": InterfaceExtractor{},
		"type":      TypeExtractor{},
	}

	for pkgName, pkg := range pkgs {
		for filename, file := range pkg.Files {
			content, err := os.ReadFile(filename)
			if err != nil {
				return nil, nil, err
			}

			// Process file imports
			for _, imp := range file.Imports {
				path := strings.Trim(imp.Path.Value, "\"")
				name := ""
				if imp.Name != nil {
					name = imp.Name.Name
				}

				importURL := strings.ReplaceAll(path, "/", "-")
				doc := ""
				comment := ""

				if imp.Doc != nil {
					doc = imp.Doc.Text()
				}
				if imp.Comment != nil {
					comment = imp.Comment.Text()
				}

				imports = append(imports, ImportInfo{
					Path:    path,
					Alias:   name,
					URL:     importURL,
					Doc:     doc,
					Comment: comment,
					Package: pkgName,
					File:    filename,
				})
			}

			// Process declarations
			for _, decl := range file.Decls {
				switch d := decl.(type) {
				case *ast.FuncDecl:
					if d.Recv != nil {
						exs, err := extractors["method"].Extract(d, fset, pkgName, content)
						if err == nil && len(exs) > 0 {
							receiverType := formatExpr(d.Recv.List[0].Type)
							methodsByType[receiverType] = append(methodsByType[receiverType], exs[0])
						}
					} else {
						exs, err := extractors["function"].Extract(d, fset, pkgName, content)
						if err == nil && len(exs) > 0 {
							entities = append(entities, exs[0])
							entityIndex[pkgName+"."+exs[0].Name] = exs[0]
						}
					}
				case *ast.GenDecl:
					if d.Tok == token.TYPE {
						structs, _ := extractors["struct"].Extract(d, fset, pkgName, content)
						for _, s := range structs {
							entities = append(entities, s)
							entityIndex[pkgName+"."+s.Name] = s
						}

						ifaces, _ := extractors["interface"].Extract(d, fset, pkgName, content)
						for _, i := range ifaces {
							entities = append(entities, i)
							interfaces[i.Name] = i
							entityIndex[pkgName+"."+i.Name] = i
						}

						types, _ := extractors["type"].Extract(d, fset, pkgName, content)
						for _, t := range types {
							entities = append(entities, t)
							entityIndex[pkgName+"."+t.Name] = t
						}
					}
				}
			}
		}
	}

	// Link methods and calculate relationships between entities
	for i, entity := range entities {
		entity.References = findReferences(entity, entityIndex)

		if entity.Type == "struct" {
			receiverName := entity.Name

			if methods, ok := methodsByType[receiverName]; ok {
				entity.Methods = append(entity.Methods, methods...)
			}
			if methods, ok := methodsByType["*"+receiverName]; ok {
				entity.Methods = append(entity.Methods, methods...)
			}

			for j, method := range entity.Methods {
				entity.Methods[j].References = findReferences(method, entityIndex)
			}

			entity.Implements = findImplementedInterfaces(entity, interfaces)
		}

		entities[i] = entity
	}

	return entities, imports, nil
}

func findImplementedInterfaces(entity EntityInfo, interfaces map[string]EntityInfo) []ImplementationInfo

{
	var implemented []ImplementationInfo

	for ifaceName, ifaceInfo := range interfaces {
		if implementsInterface(entity, ifaceInfo) {
			implemented = append(implemented, ImplementationInfo{
				InterfaceName: ifaceName,
				Package:       ifaceInfo.Package,
			})
		}
	}

	return implemented
}

func implementsInterface(entity EntityInfo, iface EntityInfo) bool

{
	methodSet := make(map[string]EntityInfo)
	for _, method := range entity.Methods {
		methodSet[method.Name] = method
	}

	for _, ifaceMethod := range iface.Methods {
		if method, ok := methodSet[ifaceMethod.Name]; !ok {
			return false
		} else {
			if !methodsMatch(ifaceMethod, method) {
				return false
			}
		}
	}

	return true
}

func methodsMatch(ifaceMethod, structMethod EntityInfo) bool

{
	if len(ifaceMethod.Parameters) != len(structMethod.Parameters) ||
		len(ifaceMethod.Returns) != len(structMethod.Returns) {
		return false
	}

	for i, param := range ifaceMethod.Parameters {
		if param != structMethod.Parameters[i] {
			return false
		}
	}

	for i, ret := range ifaceMethod.Returns {
		if ret != structMethod.Returns[i] {
			return false
		}
	}

	return true
}

func extractMethods(interfaceType *ast.InterfaceType) []EntityInfo

{
	var methods []EntityInfo
	for _, field := range interfaceType.Methods.List {
		if funcType, ok := field.Type.(*ast.FuncType); ok {
			methodInfo := EntityInfo{
				Name:       field.Names[0].Name,
				Parameters: extractParameters(funcType.Params),
				Returns:    extractParameters(funcType.Results),
			}
			methods = append(methods, methodInfo)
		}
	}
	return methods
}

func extractFields(structType *ast.StructType) []FieldInfo

{
	var fields []FieldInfo
	for _, field := range structType.Fields.List {
		typeStr := formatExpr(field.Type)
		for _, name := range field.Names {
			fieldInfo := FieldInfo{
				Name: name.Name,
				Type: typeStr,
				Tag:  extractTag(field),
			}
			fields = append(fields, fieldInfo)
		}
	}
	return fields
}

func extractDescriptionData(doc string) DescriptionData

{
	lines := strings.Split(doc, "\n")

	var descLines []string
	var exampleLines []string
	var notesLines []string
	var deprecationNoteLines []string
	var returnsLines []string

	var description string
	var example string
	var notes string
	var deprecationNote string
	var returns string

	isExample := false
	isNotes := false
	isDeprecationNote := false
	isReturns := false

	for _, line := range lines {
		trimmedLine := strings.TrimSpace(line)
		if strings.HasPrefix(trimmedLine, "Example:") {
			isExample = true
			isNotes = false
			isDeprecationNote = false
			isReturns = false
			continue
		}
		if strings.HasPrefix(trimmedLine, "Notes:") {
			isNotes = true
			isExample = false
			isDeprecationNote = false
			isReturns = false
			continue
		}
		if strings.HasPrefix(trimmedLine, "Deprecated:") {
			isDeprecationNote = true
			isExample = false
			isNotes = false
			isReturns = false
			continue
		}
		if strings.HasPrefix(trimmedLine, "Returns:") {
			isReturns = true
			isExample = false
			isNotes = false
			isDeprecationNote = false
			continue
		}

		if isExample {
			exampleLines = append(exampleLines, line)
		} else if isNotes {
			notesLines = append(notesLines, trimmedLine)
		} else if isDeprecationNote {
			deprecationNoteLines = append(deprecationNoteLines, trimmedLine)
		} else if isReturns {
			returnsLines = append(returnsLines, trimmedLine)
		} else {
			descLines = append(descLines, trimmedLine)
		}
	}

	descriptionRaw := strings.Join(descLines, "\n")
	description = markdownToHTML(descriptionRaw)

	example = strings.Join(exampleLines, "\n")
	example = formatExample(example)

	notesRaw := strings.Join(notesLines, "\n")
	notes = markdownToHTML(notesRaw)

	deprecationNoteRaw := strings.Join(deprecationNoteLines, "\n")
	deprecationNote = markdownToHTML(deprecationNoteRaw)

	returnsRaw := strings.Join(returnsLines, "\n")
	returns = markdownToHTML(returnsRaw)

	return DescriptionData{
		Description:     description,
		Example:         example,
		Notes:           notes,
		DeprecationNote: deprecationNote,
		Returns:         returns,

		DescriptionRaw:     descriptionRaw,
		DeprecationNoteRaw: deprecationNoteRaw,
	}
}

func formatExample(example string) string

{
	lines := strings.Split(example, "\n")

	for len(lines) > 0 && strings.TrimSpace(lines[0]) == "" {
		lines = lines[1:]
	}

	for len(lines) > 0 && strings.TrimSpace(lines[len(lines)-1]) == "" {
		lines = lines[:len(lines)-1]
	}

	if len(lines) == 0 {
		return ""
	}

	minIndent := -1
	for _, line := range lines {
		if strings.TrimSpace(line) == "" {
			continue
		}
		indent := len(line) - len(strings.TrimLeft(line, " \t"))
		if minIndent == -1 || indent < minIndent {
			minIndent = indent
		}
	}

	if minIndent <= 0 {
		return strings.Join(lines, "\n")
	}

	dedentedLines := make([]string, len(lines))
	for i, line := range lines {
		if len(line) >= minIndent {
			dedentedLines[i] = line[minIndent:]
		} else {
			dedentedLines[i] = strings.TrimLeft(line, " \t")
		}
	}

	return strings.Join(dedentedLines, "\n")
}

func extractParameters(fieldList *ast.FieldList) []string

{
	var params []string
	if fieldList != nil {
		for _, param := range fieldList.List {
			typeStr := formatExpr(param.Type)
			for _, name := range param.Names {
				params = append(params, name.Name+" "+typeStr)
			}
			if len(param.Names) == 0 {
				params = append(params, typeStr)
			}
		}
	}
	return params
}

func extractBody(node ast.Node, fset *token.FileSet, fileContent []byte) string

{
	if node == nil {
		return ""
	}

	// Try to slice directly from the original file content for accuracy
	if len(fileContent) > 0 {
		start := fset.Position(node.Pos()).Offset
		end := fset.Position(node.End()).Offset
		if start >= 0 && end <= len(fileContent) && start < end {
			return string(fileContent[start:end])
		}
	}

	var buf strings.Builder
	if err := format.Node(&buf, fset, node); err != nil {
		return ""
	}
	return buf.String()
}

func findReferences(entity EntityInfo, entityIndex map[string]EntityInfo) []ReferenceInfo

{
	var references []ReferenceInfo

	for _, param := range entity.Parameters {
		parts := strings.Fields(param)
		if len(parts) == 0 {
			continue
		}
		paramType := parts[len(parts)-1]
		if refEntity, found := entityIndex[entity.Package+"."+paramType]; found {
			references = append(references, ReferenceInfo{
				Name:        paramType,
				Package:     refEntity.Package,
				PackageURL:  refEntity.PackageURL,
				PackagePath: refEntity.PackagePath,
			})
		}
	}

	for _, ret := range entity.Returns {
		parts := strings.Fields(ret)
		if len(parts) == 0 {
			continue
		}
		retType := parts[len(parts)-1]
		if refEntity, found := entityIndex[entity.Package+"."+retType]; found {
			references = append(references, ReferenceInfo{
				Name:        retType,
				Package:     refEntity.Package,
				PackageURL:  refEntity.PackageURL,
				PackagePath: refEntity.PackagePath,
			})
		}
	}

	for _, field := range entity.Fields {
		if refEntity, found := entityIndex[entity.Package+"."+field.Type]; found {
			references = append(references, ReferenceInfo{
				Name:        field.Type,
				Package:     refEntity.Package,
				PackageURL:  refEntity.PackageURL,
				PackagePath: refEntity.PackagePath,
			})
		}
	}

	return references
}