From 5452cfce30d7b5cbc76bdaca287cea177a0a4672 Mon Sep 17 00:00:00 2001
From: Lukasz Raczylo <lukasz@raczylo.com>
Date: Sat, 20 Jun 2026 00:04:38 +0100
Subject: [PATCH] fix(parser): deterministic order for remaining doc-comment
 tags
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

FormatDocComment emitted leftover tags by ranging a map, so multi-tag comments (@example/@see/@deprecated) rendered in random order run-to-run — nondeterministic output that defeats caching/diffing. Sort the remaining tag names before emitting.
---
 internal/parser/docextract.go | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/internal/parser/docextract.go b/internal/parser/docextract.go
index 7cde3c3..9632bc8 100644
--- a/internal/parser/docextract.go
+++ b/internal/parser/docextract.go
@@ -3,6 +3,7 @@ package parser
 
 import (
 	"regexp"
+	"sort"
 	"strings"
 
 	"github.com/lukaszraczylo/mcp-filepuff/pkg/protocol"
@@ -530,11 +531,16 @@ func FormatDocComment(doc *DocComment) string {
 			written[t] = true
 		}
 
-		for tagName, val := range doc.Tags {
+		remaining := make([]string, 0, len(doc.Tags))
+		for tagName := range doc.Tags {
 			if !written[tagName] {
-				sb.WriteString("@" + tagName + " " + val + "\n")
+				remaining = append(remaining, tagName)
 			}
 		}
+		sort.Strings(remaining) // deterministic output (map order is random)
+		for _, tagName := range remaining {
+			sb.WriteString("@" + tagName + " " + doc.Tags[tagName] + "\n")
+		}
 	}
 
 	return strings.TrimSpace(sb.String())