refactor: consolidate equality helpers, fix silent limits, centralize file permissions

- Extract generic EqualPtr[T comparable] into internal/equalutil, replacing
  5 type-specific pointer-equality functions across parser/ and joiner/
- Add depth-limit warnings: RefCollector.Warnings field in fixer/refs.go,
  slog.Warn in internal/jsonpath/eval.go (previously silent data truncation)
- Centralize file permissions in internal/fileutil (OwnerReadWrite 0o600,
  ReadableByAll 0o644), replacing hardcoded literals across 12 production files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: erraggy

builder/builder.go

@@ -8,6 +8,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/erraggy/oastools/internal/fileutil"
 	"github.com/erraggy/oastools/internal/schemautil"
 	"github.com/erraggy/oastools/joiner"
 	"github.com/erraggy/oastools/parser"
@@ -621,9 +622,6 @@ func (b *Builder) MarshalJSON() ([]byte, error) {
 	return json.MarshalIndent(doc, "", "  ")
 }
 
-// outputFileMode is the file permission mode for output files (owner read/write only)
-const outputFileMode = 0600
-
 // WriteFile writes the document to a file.
 // The format is inferred from the file extension (.json for JSON, .yaml/.yml for YAML).
 func (b *Builder) WriteFile(path string) error {
@@ -645,7 +643,7 @@ func (b *Builder) WriteFile(path string) error {
 		return fmt.Errorf("builder: failed to marshal document: %w", err)
 	}
 
-	if err := os.WriteFile(path, data, outputFileMode); err != nil {
+	if err := os.WriteFile(path, data, fileutil.OwnerReadWrite); err != nil {
 		return fmt.Errorf("builder: failed to write file: %w", err)
 	}
 

cmd/oastools/commands/convert.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/erraggy/oastools"
 	"github.com/erraggy/oastools/converter"
+	"github.com/erraggy/oastools/internal/fileutil"
 	"github.com/erraggy/oastools/parser"
 )
 
@@ -203,7 +204,7 @@ func HandleConvert(args []string) error {
 		if err := RejectSymlinkOutput(cleanedOutput); err != nil {
 			return err
 		}
-		if err := os.WriteFile(cleanedOutput, data, 0600); err != nil { //nolint:gosec // G703 - output path is user-provided CLI flag
+		if err := os.WriteFile(cleanedOutput, data, fileutil.OwnerReadWrite); err != nil { //nolint:gosec // G703 - output path is user-provided CLI flag
 			return fmt.Errorf("writing output file: %w", err)
 		}
 		if !flags.Quiet {

cmd/oastools/commands/fix.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/erraggy/oastools"
 	"github.com/erraggy/oastools/fixer"
+	"github.com/erraggy/oastools/internal/fileutil"
 	"github.com/erraggy/oastools/parser"
 )
 
@@ -348,7 +349,7 @@ func HandleFix(args []string) error {
 		if err := RejectSymlinkOutput(cleanedOutput); err != nil {
 			return err
 		}
-		if err := os.WriteFile(cleanedOutput, data, 0600); err != nil { //nolint:gosec // G703 - output path is user-provided CLI flag
+		if err := os.WriteFile(cleanedOutput, data, fileutil.OwnerReadWrite); err != nil { //nolint:gosec // G703 - output path is user-provided CLI flag
 			return fmt.Errorf("writing output file: %w", err)
 		}
 		if !flags.Quiet {

cmd/oastools/commands/join.go

@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/erraggy/oastools"
+	"github.com/erraggy/oastools/internal/fileutil"
 	"github.com/erraggy/oastools/joiner"
 	"github.com/erraggy/oastools/parser"
 )
@@ -389,11 +390,11 @@ func HandleJoin(args []string) error {
 		if symlinkErr := RejectSymlinkOutput(cleanedOutput); symlinkErr != nil {
 			return symlinkErr
 		}
-		if writeErr := os.WriteFile(cleanedOutput, data, 0600); writeErr != nil { //nolint:gosec // G703 - output path is user-provided CLI flag
+		if writeErr := os.WriteFile(cleanedOutput, data, fileutil.OwnerReadWrite); writeErr != nil { //nolint:gosec // G703 - output path is user-provided CLI flag
 			return fmt.Errorf("writing output file: %w", writeErr)
 		}
 		// Ensure correct permissions even if file pre-existed with different permissions
-		if chmodErr := os.Chmod(cleanedOutput, 0600); chmodErr != nil {
+		if chmodErr := os.Chmod(cleanedOutput, fileutil.OwnerReadWrite); chmodErr != nil {
 			return fmt.Errorf("setting output file permissions: %w", chmodErr)
 		}
 		if !flags.Quiet {

cmd/oastools/commands/overlay.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/erraggy/oastools"
+	"github.com/erraggy/oastools/internal/fileutil"
 	"github.com/erraggy/oastools/overlay"
 	"github.com/erraggy/oastools/parser"
 )
@@ -241,7 +242,7 @@ func handleOverlayApply(args []string) error {
 		if err := RejectSymlinkOutput(cleanedOutput); err != nil {
 			return err
 		}
-		if err := os.WriteFile(cleanedOutput, data, 0600); err != nil { //nolint:gosec // G703 - output path is user-provided CLI flag
+		if err := os.WriteFile(cleanedOutput, data, fileutil.OwnerReadWrite); err != nil { //nolint:gosec // G703 - output path is user-provided CLI flag
 			return fmt.Errorf("writing output file: %w", err)
 		}
 		if !flags.Quiet {

fixer/oas2.go

@@ -4,6 +4,7 @@ package fixer
 
 import (
 	"fmt"
+	"log/slog"
 	"sort"
 
 	"github.com/erraggy/oastools/parser"
@@ -187,6 +188,9 @@ func (f *Fixer) pruneUnusedSchemasOAS2(doc *parser.OAS2Document, result *FixResu
 	// Collect all refs in the document
 	collector := NewRefCollector()
 	collector.CollectOAS2(doc)
+	for _, w := range collector.Warnings {
+		slog.Warn("ref collection warning", "detail", w)
+	}
 
 	// Prune unreferenced schemas
 	f.pruneSchemas(doc.Definitions, collector, doc, result)

fixer/oas3.go

@@ -4,6 +4,7 @@ package fixer
 
 import (
 	"fmt"
+	"log/slog"
 
 	"github.com/erraggy/oastools/parser"
 )
@@ -264,6 +265,9 @@ func (f *Fixer) pruneUnusedSchemasOAS3(doc *parser.OAS3Document, result *FixResu
 	// Collect all refs in the document
 	collector := NewRefCollector()
 	collector.CollectOAS3(doc)
+	for _, w := range collector.Warnings {
+		slog.Warn("ref collection warning", "detail", w)
+	}
 
 	// Prune unreferenced schemas
 	f.pruneSchemas(doc.Components.Schemas, collector, doc, result)

fixer/refs.go

@@ -131,6 +131,10 @@ type RefCollector struct {
 
 	// visited tracks processed schemas for circular reference handling.
 	visited map[*parser.Schema]bool
+
+	// Warnings contains non-fatal issues encountered during collection,
+	// such as depth limit truncation.
+	Warnings []string
 }
 
 // NewRefCollector creates a new RefCollector instance.
@@ -648,7 +652,7 @@ func (c *RefCollector) collectRefsFromMap(m map[string]any, path string) {
 // collectRefsFromMapWithDepth is the internal implementation with depth tracking.
 func (c *RefCollector) collectRefsFromMapWithDepth(m map[string]any, path string, depth int) {
 	if depth > maxRefCollectionDepth {
-		// Extremely deep nesting or circular structure - stop to prevent stack overflow
+		c.Warnings = append(c.Warnings, fmt.Sprintf("ref collection truncated at depth %d (path: %s): possible circular structure", depth, path))
 		return
 	}
 

fixer/refs_test.go

@@ -894,6 +894,35 @@ components:
 	assert.False(t, collector.IsPathItemReferenced("UnusedPath"))
 }
 
+// TestRefCollector_DepthLimitWarning tests that exceeding maxRefCollectionDepth
+// produces a warning instead of silently truncating.
+func TestRefCollector_DepthLimitWarning(t *testing.T) {
+	// Build a deeply nested map structure exceeding maxRefCollectionDepth (100).
+	// Use "items" as the nesting key since collectRefsFromMapWithDepth recurses
+	// into recognized OAS keys like "items", "properties", etc.
+	leaf := map[string]any{
+		"$ref": "#/components/schemas/TooDeep",
+	}
+	current := leaf
+	for range maxRefCollectionDepth + 2 {
+		current = map[string]any{
+			"items": current,
+		}
+	}
+
+	collector := NewRefCollector()
+	collector.collectRefsFromMap(current, "$.root")
+
+	// The collector should have recorded at least one warning about truncation.
+	require.NotEmpty(t, collector.Warnings, "expected depth limit warning but got none")
+	assert.Contains(t, collector.Warnings[0], "truncated",
+		"warning should mention truncation")
+
+	// The deeply nested $ref should NOT have been collected (it's beyond the depth limit).
+	_, found := collector.Refs["#/components/schemas/TooDeep"]
+	assert.False(t, found, "refs beyond the depth limit should not be collected")
+}
+
 // TestRefCollector_JSONSchema202012 tests ref collection from JSON Schema Draft 2020-12 keywords
 // like unevaluatedProperties, unevaluatedItems, and contentSchema.
 func TestRefCollector_JSONSchema202012(t *testing.T) {

fixer/stub_missing_refs.go

@@ -6,6 +6,7 @@ package fixer
 
 import (
 	"fmt"
+	"log/slog"
 	"sort"
 	"strings"
 
@@ -59,6 +60,9 @@ func (f *Fixer) stubMissingRefsOAS2(doc *parser.OAS2Document, result *FixResult)
 	// Collect all refs in the document
 	collector := NewRefCollector()
 	collector.CollectOAS2(doc)
+	for _, w := range collector.Warnings {
+		slog.Warn("ref collection warning", "detail", w)
+	}
 
 	// Check schema refs and stub missing ones
 	// Sort refs for deterministic output order
@@ -173,6 +177,9 @@ func (f *Fixer) stubMissingRefsOAS3(doc *parser.OAS3Document, result *FixResult)
 	// Collect all refs in the document
 	collector := NewRefCollector()
 	collector.CollectOAS3(doc)
+	for _, w := range collector.Warnings {
+		slog.Warn("ref collection warning", "detail", w)
+	}
 
 	// Check schema refs and stub missing ones
 	// Sort refs for deterministic output order