fix: make generated outputs deterministic and normalize paths

* fix: normalize paths and ignore generated outputs

* fix: make generated outputs deterministic

---------

Co-authored-by: Aayush Pratap Singh <aayush@bhooyam.com>

Author: aayushprsingh

internal/cli/diff.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 
+	"github.com/glincker/stacklit/internal/config"
 	"github.com/glincker/stacklit/internal/git"
 	"github.com/glincker/stacklit/internal/schema"
 	"github.com/glincker/stacklit/internal/walker"
@@ -32,8 +33,9 @@ func newDiffCmd() *cobra.Command {
 				return fmt.Errorf("stacklit.json has no merkle_hash; run 'stacklit generate' to rebuild")
 			}
 
-			// 2. Walk current source files
-			files, err := walker.Walk(".", nil)
+			// 2. Walk current source files, excluding Stacklit's own generated outputs.
+			cfg := config.Load(".")
+			files, err := walker.Walk(".", cfg.ScanIgnore())
 			if err != nil {
 				return fmt.Errorf("failed to walk source files: %w", err)
 			}

internal/config/config.go

@@ -72,3 +72,16 @@ func Load(root string) *Config {
 
 	return cfg
 }
+
+// ScanIgnore returns ignore patterns plus Stacklit output files so generated artifacts
+// never feed back into the next scan.
+func (c *Config) ScanIgnore() []string {
+	ignore := append([]string{}, c.Ignore...)
+	for _, out := range []string{c.Output.JSON, c.Output.Mermaid, c.Output.HTML} {
+		if out == "" {
+			continue
+		}
+		ignore = append(ignore, filepath.ToSlash(out))
+	}
+	return ignore
+}

internal/config/config_test.go

@@ -54,3 +54,22 @@ func TestLoadMalformed(t *testing.T) {
 		t.Errorf("expected default max_depth=4 after malformed file, got %d", cfg.MaxDepth)
 	}
 }
+
+func TestScanIgnoreIncludesOutputs(t *testing.T) {
+	cfg := DefaultConfig()
+	cfg.Ignore = []string{"custom/"}
+	cfg.Output.JSON = "out\\stacklit.json"
+	cfg.Output.Mermaid = "docs\\DEPENDENCIES.md"
+	cfg.Output.HTML = "stacklit.html"
+
+	got := cfg.ScanIgnore()
+	want := []string{"custom/", "out/stacklit.json", "docs/DEPENDENCIES.md", "stacklit.html"}
+	if len(got) != len(want) {
+		t.Fatalf("expected %d ignore patterns, got %d: %v", len(want), len(got), got)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("expected ignore[%d]=%q, got %q (all=%v)", i, want[i], got[i], got)
+		}
+	}
+}

internal/engine/engine.go

@@ -166,7 +166,7 @@ func Run(opts Options) (*Result, error) {
 	}
 
 	// 3. Walk the filesystem, honouring extra ignore patterns from config.
-	files, err := walker.Walk(root, cfg.Ignore)
+	files, err := walker.Walk(root, cfg.ScanIgnore())
 	if err != nil {
 		return nil, fmt.Errorf("walking %s: %w", root, err)
 	}
@@ -452,17 +452,20 @@ func assembleIndex(
 			}
 		}
 
-		// Cap type defs to maxExports per module.
+		// Cap type defs to maxExports per module in a deterministic order.
 		typeDefs := mod.TypeDefs
 		if maxExports > 0 && len(typeDefs) > maxExports {
+			keys := make([]string, 0, len(typeDefs))
+			for k := range typeDefs {
+				keys = append(keys, k)
+			}
+			sort.Strings(keys)
 			trimmed := make(map[string]string, maxExports)
-			i := 0
-			for k, v := range typeDefs {
-				trimmed[k] = v
-				i++
+			for i, k := range keys {
 				if i >= maxExports {
 					break
 				}
+				trimmed[k] = typeDefs[k]
 			}
 			typeDefs = trimmed
 		}

internal/renderer/html.go

@@ -1,6 +1,7 @@
 package renderer
 
 import (
+	"bytes"
 	"encoding/json"
 	"os"
 	"strings"
@@ -18,5 +19,9 @@ func WriteHTML(idx *schema.Index, path string) error {
 	}
 	html := strings.Replace(assets.TemplateHTML, "{{STACKLIT_DATA}}", string(dataJSON), 1)
 	html = strings.Replace(html, "{{LANG_ICONS_JS}}", assets.LangIconsJS, 1)
-	return os.WriteFile(path, []byte(html), 0644)
+	data := []byte(html)
+	if existing, err := os.ReadFile(path); err == nil && bytes.Equal(existing, data) {
+		return nil
+	}
+	return os.WriteFile(path, data, 0644)
 }

internal/renderer/json.go

@@ -1,6 +1,7 @@
 package renderer
 
 import (
+	"bytes"
 	"encoding/json"
 	"os"
 	"time"
@@ -17,11 +18,16 @@ func WriteJSON(idx *schema.Index, path string) error {
 	idx.Schema = schemaURL
 	idx.GeneratedAt = time.Now().UTC().Format(time.RFC3339)
 	idx.StacklitVersion = version
+	preserveGeneratedAtIfUnchanged(idx, path)
 
 	data, err := json.MarshalIndent(idx, "", "  ")
 	if err != nil {
 		return err
 	}
 
+	if existing, err := os.ReadFile(path); err == nil && bytes.Equal(existing, data) {
+		return nil
+	}
+
 	return os.WriteFile(path, data, 0644)
 }

internal/renderer/mermaid.go

@@ -1,8 +1,10 @@
 package renderer
 
 import (
+	"bytes"
 	"fmt"
 	"os"
+	"sort"
 	"strings"
 	"time"
 	"unicode"
@@ -82,8 +84,13 @@ func WriteMermaid(idx *schema.Index, path string) error {
 		}
 	}
 
-	// Write classDef entries for used languages.
+	// Write classDef entries for used languages in deterministic order.
+	langs := make([]string, 0, len(usedLangs))
 	for lang := range usedLangs {
+		langs = append(langs, lang)
+	}
+	sort.Strings(langs)
+	for _, lang := range langs {
 		colors := langColors[lang]
 		sb.WriteString(fmt.Sprintf("  classDef %s fill:%s,color:%s,stroke:%s\n",
 			lang, colors[0], colors[1], colors[0]))
@@ -92,8 +99,14 @@ func WriteMermaid(idx *schema.Index, path string) error {
 	// Determine primary language for node class assignment.
 	primaryLang := strings.ToLower(idx.Tech.PrimaryLanguage)
 
-	// Write node definitions.
-	for name, mod := range idx.Modules {
+	// Write node definitions in deterministic order.
+	moduleNames := make([]string, 0, len(idx.Modules))
+	for name := range idx.Modules {
+		moduleNames = append(moduleNames, name)
+	}
+	sort.Strings(moduleNames)
+	for _, name := range moduleNames {
+		mod := idx.Modules[name]
 		id := sanitizeMermaidID(name)
 		label := truncate(mod.Purpose, 40)
 		nodeClass := primaryLang
@@ -115,5 +128,9 @@ func WriteMermaid(idx *schema.Index, path string) error {
 	}
 
 	sb.WriteString("```\n")
-	return os.WriteFile(path, []byte(sb.String()), 0644)
+	data := []byte(sb.String())
+	if existing, err := os.ReadFile(path); err == nil && bytes.Equal(existing, data) {
+		return nil
+	}
+	return os.WriteFile(path, data, 0644)
 }

internal/renderer/stable.go

@@ -0,0 +1,40 @@
+package renderer
+
+import (
+	"encoding/json"
+	"os"
+
+	"github.com/glincker/stacklit/internal/schema"
+)
+
+func normalizedIndexJSON(idx *schema.Index) ([]byte, error) {
+	clone := *idx
+	clone.GeneratedAt = ""
+	return json.Marshal(clone)
+}
+
+// preserveGeneratedAtIfUnchanged keeps the previous GeneratedAt value when the
+// semantic index content is unchanged. This avoids needless output churn across
+// repeated runs, especially on Windows where unchanged locked files should not
+// trigger rewrite attempts.
+func preserveGeneratedAtIfUnchanged(idx *schema.Index, path string) {
+	existingBytes, err := os.ReadFile(path)
+	if err != nil {
+		return
+	}
+	var existing schema.Index
+	if err := json.Unmarshal(existingBytes, &existing); err != nil {
+		return
+	}
+	currentNorm, err := normalizedIndexJSON(idx)
+	if err != nil {
+		return
+	}
+	existingNorm, err := normalizedIndexJSON(&existing)
+	if err != nil {
+		return
+	}
+	if string(currentNorm) == string(existingNorm) {
+		idx.GeneratedAt = existing.GeneratedAt
+	}
+}

internal/walker/walker.go

@@ -99,6 +99,9 @@ func Walk(root string, extraIgnore []string) ([]string, error) {
 			return relErr
 		}
 
+		// Normalize path separators so generated output and ignore matching stay stable across OSes.
+		rel = filepath.ToSlash(rel)
+
 		// Skip the root itself.
 		if rel == "." {
 			return nil

internal/walker/walker_test.go

@@ -35,8 +35,8 @@ func TestWalkSourceFiles(t *testing.T) {
 	// Must include Go source files.
 	wantIncluded := []string{
 		"main.go",
-		filepath.Join("internal", "handler.go"),
-		filepath.Join("internal", "handler_test.go"),
+		filepath.ToSlash(filepath.Join("internal", "handler.go")),
+		filepath.ToSlash(filepath.Join("internal", "handler_test.go")),
 	}
 	for _, want := range wantIncluded {
 		if !fileSet[want] {
@@ -46,8 +46,8 @@ func TestWalkSourceFiles(t *testing.T) {
 
 	// Must exclude gitignored directories.
 	wantExcluded := []string{
-		filepath.Join("vendor", "lib.go"),
-		filepath.Join("node_modules", "pkg.js"),
+		filepath.ToSlash(filepath.Join("vendor", "lib.go")),
+		filepath.ToSlash(filepath.Join("node_modules", "pkg.js")),
 	}
 	for _, exclude := range wantExcluded {
 		if fileSet[exclude] {
@@ -124,7 +124,7 @@ func TestWalkAlwaysIgnoresDirs(t *testing.T) {
 	}
 
 	for _, d := range ignoredDirs {
-		p := filepath.Join(d, "file.go")
+		p := filepath.ToSlash(filepath.Join(d, "file.go"))
 		if fileSet[p] {
 			t.Errorf("expected %q inside always-ignore dir to be excluded", p)
 		}