fix(core): document BCL shadowing, fix StringBuilder allocations

- Add XML doc remarks to Replace/Contains extensions explaining
  intentional BCL shadowing (instance methods win at runtime; extensions
  exist for BuiltinRegistry discovery and internal use)
- Fix inconsistent System.Text.StringBuilder qualification in Casefold
- Add initial capacity hint to Expandtabs and Replace 3-arg StringBuilder
- Add Axiom 1 UTF-16 design rationale comments to StringHelpers.Iterate/Reversed

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

Author: antonsynd

src/Sharpy.Core/StringExtensions.Interfaces.cs

@@ -11,6 +11,14 @@ public static partial class StringExtensions
         /// Return true if <paramref name="substring"/> is found within this string.
         /// Used for <c>"x" in s</c> codegen.
         /// </summary>
+        /// <remarks>
+        /// This extension shadows <see cref="string.Contains(string)"/> by design.
+        /// C# instance methods take precedence over extensions, so generated code calling
+        /// <c>s.Contains(x)</c> always invokes the BCL method at runtime. This overload
+        /// exists so that BuiltinRegistry can discover it via reflection and register
+        /// <c>str.contains</c> for type-checking. The ordinal semantics here match
+        /// Python's byte-level containment check.
+        /// </remarks>
         public static bool Contains(this string s, string substring)
         {
             return s.IndexOf(substring, StringComparison.Ordinal) >= 0;

src/Sharpy.Core/StringExtensions.cs

@@ -116,7 +116,7 @@ public static string Swapcase(this string s)
         /// </summary>
         public static string Casefold(this string s)
         {
-            var sb = new System.Text.StringBuilder(s.Length);
+            var sb = new StringBuilder(s.Length);
             foreach (var c in s)
             {
                 sb.Append(CaseFoldChar(c));
@@ -265,7 +265,7 @@ public static string Removesuffix(this string s, string suffix)
         /// </summary>
         public static string Expandtabs(this string s, int tabsize = 8)
         {
-            var result = new StringBuilder();
+            var result = new StringBuilder(s.Length);
             int column = 0;
 
             foreach (char c in s)
@@ -300,6 +300,16 @@ public static string Expandtabs(this string s, int tabsize = 8)
         /// by <paramref name="new_"/>.
         /// Python: <c>str.replace(old, new)</c>
         /// </summary>
+        /// <remarks>
+        /// This extension shadows <see cref="string.Replace(string, string)"/> by design.
+        /// C# instance methods take precedence over extensions, so generated code calling
+        /// <c>s.Replace(old, new_)</c> always invokes the BCL method at runtime. This
+        /// overload exists for two reasons: (1) BuiltinRegistry discovers it via reflection
+        /// to register <c>str.replace</c> for type-checking, and (2) the 3-arg overload
+        /// calls it directly (as a static call) when <c>count &lt; 0</c> to get Python
+        /// empty-string replacement semantics (BCL throws on empty <paramref name="old"/>
+        /// in netstandard2.0).
+        /// </remarks>
         public static string Replace(this string s, string old, string new_)
         {
             if (old.Length == 0)
@@ -336,7 +346,8 @@ public static string Replace(this string s, string old, string new_, int count)
 
             if (old.Length == 0)
             {
-                var sb = new StringBuilder();
+                int insertions = count < s.Length + 1 ? count : s.Length + 1;
+                var sb = new StringBuilder(new_.Length * insertions + s.Length);
                 int replacements = 0;
                 if (replacements < count)
                 {

src/Sharpy.Core/StringHelpers.cs

@@ -66,6 +66,11 @@ public static string GetItem(string s, int index)
         /// Python iterates strings yielding single-char strings, not chars.
         /// Used for <c>for c in s:</c> codegen.
         /// </summary>
+        /// <remarks>
+        /// Iterates by UTF-16 code unit, not Unicode code point. Surrogate pairs
+        /// (e.g., emoji) yield two separate single-char strings. This follows
+        /// Axiom 1 (.NET UTF-16 semantics take precedence over Python code-point iteration).
+        /// </remarks>
         public static IEnumerable<string> Iterate(string s)
         {
             for (int i = 0; i < s.Length; i++)
@@ -78,6 +83,10 @@ public static IEnumerable<string> Iterate(string s)
         /// Yields single-character strings in reverse order.
         /// Used for <c>reversed(s)</c> codegen.
         /// </summary>
+        /// <remarks>
+        /// Iterates by UTF-16 code unit, not Unicode code point. See
+        /// <see cref="Iterate"/> remarks for Axiom 1 rationale.
+        /// </remarks>
         public static IEnumerable<string> Reversed(string s)
         {
             for (int i = s.Length - 1; i >= 0; i--)