BytesRef: Show "Invalid UTF-8" label and string-before-bytes in DebuggerDisplay, #1024

Address NightOwl888's review on #1171. The prior DebuggerDisplay used
Utf8ToStringWithFallback, which silently substitutes U+FFFD for malformed
input — indistinguishable from a real U+FFFD in the data. Switch to a
private DebuggerDisplay property that uses TryUtf8ToString, shows the
literal "Invalid UTF-8" on decode failure, and puts the decoded string
before the raw bytes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: paulirwin

src/Lucene.Net.Tests/Util/TestBytesRef.cs

@@ -3,6 +3,8 @@
 using NUnit.Framework;
 using System;
 using System.Collections.Generic;
+using System.Diagnostics;
+using System.Reflection;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using Assert = Lucene.Net.TestFramework.Assert;
@@ -612,5 +614,64 @@ public static void Test_CopyChars_UnpairedSurrogates()
         }
 
         #endregion
+
+        #region DebuggerDisplay
+
+        private static string GetDebuggerDisplay(BytesRef br)
+        {
+            var prop = typeof(BytesRef).GetProperty("DebuggerDisplay", BindingFlags.Instance | BindingFlags.NonPublic);
+            Assert.IsNotNull(prop, "BytesRef.DebuggerDisplay private property not found");
+            return (string)prop.GetValue(br);
+        }
+
+        [Test]
+        [LuceneNetSpecific]
+        public static void Test_DebuggerDisplayAttribute_ReferencesExistingMember()
+        {
+            // Guards against typos/renames in the [DebuggerDisplay] expression.
+            var attr = typeof(BytesRef).GetCustomAttribute<DebuggerDisplayAttribute>();
+            Assert.IsNotNull(attr);
+            Assert.AreEqual("{DebuggerDisplay,nq}", attr.Value);
+
+            var prop = typeof(BytesRef).GetProperty("DebuggerDisplay", BindingFlags.Instance | BindingFlags.NonPublic);
+            Assert.IsNotNull(prop);
+        }
+
+        [Test]
+        [LuceneNetSpecific]
+        public static void Test_DebuggerDisplay_ValidUtf8_ShowsStringThenBytes()
+        {
+            var br = new BytesRef("abc");
+            Assert.AreEqual("abc [61 62 63]", GetDebuggerDisplay(br));
+        }
+
+        [Test]
+        [LuceneNetSpecific]
+        public static void Test_DebuggerDisplay_InvalidUtf8_ShowsInvalidLabel()
+        {
+            // 0xC3 starts a 2-byte UTF-8 sequence but the continuation byte is missing.
+            var br = new BytesRef(new byte[] { 0xC3 });
+            Assert.AreEqual("Invalid UTF-8 [c3]", GetDebuggerDisplay(br));
+        }
+
+        [Test]
+        [LuceneNetSpecific]
+        public static void Test_DebuggerDisplay_EmbeddedFFFD_IsNotMistakenForInvalid()
+        {
+            // U+FFFD encoded as legitimate UTF-8 (EF BF BD) must round-trip, not be reported as invalid.
+            var br = new BytesRef("\uFFFD");
+            Assert.AreEqual("\uFFFD [ef bf bd]", GetDebuggerDisplay(br));
+        }
+
+        [Test]
+        [LuceneNetSpecific]
+        public static void Test_DebuggerDisplay_RespectsOffsetAndLength()
+        {
+            var bytes = new[] { (byte)'a', (byte)'b', (byte)'c', (byte)'d' };
+            var br = new BytesRef(bytes, 1, 2); // "bc"
+            Assert.AreEqual("bc [62 63]", GetDebuggerDisplay(br));
+        }
+
+        #endregion
     }
 }

src/Lucene.Net/Util/BytesRef.cs

@@ -45,7 +45,7 @@ namespace Lucene.Net.Util
     [Serializable]
 #endif
     // LUCENENET specific: Not implementing ICloneable per Microsoft's recommendation
-    [DebuggerDisplay("{ToString()} {Utf8ToStringWithFallback()}")]
+    [DebuggerDisplay("{DebuggerDisplay,nq}")]
     public sealed class BytesRef : IComparable<BytesRef>, IComparable, IEquatable<BytesRef> // LUCENENET specific - implemented IComparable for FieldComparator, IEquatable<BytesRef>
     {
         /// <summary>
@@ -317,6 +317,11 @@ public bool TryUtf8ToString([NotNullWhen(true)] out string? result)
         }
         #nullable restore
 
+        // LUCENENET specific: "Invalid UTF-8" disambiguates a decode failure from a legitimate U+FFFD in the data.
+        [SuppressMessage("CodeQuality", "IDE0051:Remove unused private members", Justification = "Referenced by DebuggerDisplay attribute")]
+        private string DebuggerDisplay
+            => $"{(TryUtf8ToString(out var s) ? s : "Invalid UTF-8")} {ToString()}";
+
         /// <summary>
         /// Returns hex encoded bytes, eg [0x6c 0x75 0x63 0x65 0x6e 0x65] </summary>
         public override string ToString()