Restore concrete FileRange overloads on FileContext for binary compat (#2319)

* Restore concrete `FileRange` overloads on `FileContext`

#2306 widened the parameters of `FileContext.GetText` and `GetTextLines`
from the concrete `FileRange` class to the `IFileRange` interface so that
`$Context.CurrentFile.GetText($Context.SelectedRange)` would resolve (since
`SelectedRange` is typed as `IFileRange`). That fixed the script-side call,
but it dropped the old concrete-typed method slots from the assembly.

Downstream modules that compile against PSES, most notably
SeeminglyScience/EditorServicesCommandSuite, bind to the published metadata
at build time. A precompiled caller of the old `GetText(FileRange)` signature
would throw `MissingMethodException` at runtime even though it recompiles
cleanly, so this was a binary-breaking change.

Restore `GetText(FileRange)` and `GetTextLines(FileRange)` alongside the
`IFileRange` overloads. Each casts to `IFileRange` and delegates to the
widened implementation, so old binaries keep resolving and behavior is
unchanged. The added tests declare their argument as the concrete `FileRange`
so overload resolution actually exercises the compatibility shims.

Drafted by Copilot (Claude Opus 4.8).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Document public API binary-compatibility rules for Copilot

I missed that #2306 was binary-breaking until after it merged, so add a
"Public API & Binary Compatibility" section to the Copilot instructions to
catch the next one at review time.

The key context the agent was missing: the public types under
`Microsoft.PowerShell.EditorServices` aren't only reached through PowerShell
script. Downstream modules compile against the shipped assemblies, and
SeeminglyScience/EditorServicesCommandSuite in particular references the
extension API surface (`FileContext`, `IFileRange`, `ILspCurrentFileContext`,
`IEditorScriptFile`, ...) directly from C#. So widening or renaming an
existing `public` member is source-compatible at most but binary-breaking.

The section spells out the failure mode (`MissingMethodException`), the
fix (add an overload that delegates rather than editing the signature in
place), and the expectation to bind a regression test to the old concrete
signature.

Drafted by Copilot (Claude Opus 4.8).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: andyleejordan

.github/copilot-instructions.md

@@ -92,6 +92,36 @@ Handlers live under `Services/<Feature>/Handlers/` and follow a consistent patte
 - Roslynator analyzers are enabled for formatting and code quality.
 - Use `Microsoft.Extensions.Logging` (`ILogger<T>` via `ILoggerFactory`) for all logging.
 
+### Public API & Binary Compatibility
+
+The public types under `Microsoft.PowerShell.EditorServices` are not consumed only
+through PowerShell script. Downstream modules **compile against the shipped PSES
+assemblies** and bind to that metadata at build time. The most prominent example is
+[`SeeminglyScience/EditorServicesCommandSuite`](https://github.com/SeeminglyScience/EditorServicesCommandSuite),
+which references the extension API surface (`FileContext`, `EditorContext`, the
+`IFileRange`/`FilePosition` types, `ILspCurrentFileContext`, `IEditorScriptFile`,
+etc.) directly from C#.
+
+Because of that, treat any change to an existing `public` member as potentially
+**binary breaking**, and review for it explicitly before merging:
+
+- Changing the **type of a parameter** (even widening a concrete class to an
+  interface it implements, e.g. `FileRange` -> `IFileRange`), the **return type**,
+  the **parameter count/order**, or **renaming/removing** a public member is
+  source-compatible at most but **binary-breaking**. The method's signature/metadata
+  token changes, so a precompiled caller throws `MissingMethodException` at runtime
+  even though it would recompile cleanly.
+- When you need a wider or different signature, **add an overload** instead of
+  editing the existing one. Keep the original signature in place and have it delegate
+  to the new implementation so existing binaries keep resolving. Cast as needed to
+  pick the new overload from the old body (e.g. `Foo((IFileRange)range)`).
+- Add a regression test that binds to the **old, concrete signature** (declare the
+  argument as the original parameter type, not the widened one) so overload
+  resolution to the compatibility shim is actually exercised.
+- If a breaking change is genuinely unavoidable, call it out in the PR description
+  as a binary breaking change so maintainers can weigh it and coordinate a
+  downstream release.
+
 ### Testing
 
 - **Framework:** xUnit with `Xunit.SkippableFact` for conditionally skipped tests.

src/PowerShellEditorServices/Extensions/FileContext.cs

@@ -112,6 +112,18 @@ public string GetText(IFileRange bufferRange)
                     GetTextLines(bufferRange));
         }
 
+        /// <summary>
+        /// Gets the file content in the specified range as a string.
+        /// </summary>
+        /// <param name="bufferRange">The buffer range for which content will be extracted.</param>
+        /// <returns>A string with the specified range of content.</returns>
+        /// <remarks>
+        /// This overload preserves binary compatibility with callers compiled
+        /// against the concrete <see cref="FileRange"/> parameter; it delegates
+        /// to the <see cref="GetText(IFileRange)"/> overload.
+        /// </remarks>
+        public string GetText(FileRange bufferRange) => GetText((IFileRange)bufferRange);
+
         /// <summary>
         /// Gets the complete file content as an array of strings.
         /// </summary>
@@ -125,6 +137,18 @@ public string GetText(IFileRange bufferRange)
         /// <returns>An array of strings, each representing a line in the file within the specified range.</returns>
         public string[] GetTextLines(IFileRange fileRange) => scriptFile.GetLinesInRange(fileRange.ToBufferRange());
 
+        /// <summary>
+        /// Gets the file content in the specified range as an array of strings.
+        /// </summary>
+        /// <param name="fileRange">The buffer range for which content will be extracted.</param>
+        /// <returns>An array of strings, each representing a line in the file within the specified range.</returns>
+        /// <remarks>
+        /// This overload preserves binary compatibility with callers compiled
+        /// against the concrete <see cref="FileRange"/> parameter; it delegates
+        /// to the <see cref="GetTextLines(IFileRange)"/> overload.
+        /// </remarks>
+        public string[] GetTextLines(FileRange fileRange) => GetTextLines((IFileRange)fileRange);
+
         #endregion
 
         #region Text Manipulation

test/PowerShellEditorServices.Test/Extensions/FileContextTests.cs

@@ -64,5 +64,36 @@ public void CanGetTextFromConstructedFileRange()
 
             Assert.Equal("Line Three", editorContext.CurrentFile.GetText(range));
         }
+
+        // The concrete FileRange overloads exist to preserve binary compatibility
+        // with callers compiled before GetText/GetTextLines were widened to IFileRange.
+        // Declaring the variable as FileRange (not IFileRange) selects those overloads.
+        [Fact]
+        public void CanGetTextFromConcreteFileRange()
+        {
+            EditorContext editorContext = CreateEditorContext(
+                "Line One\nLine Two\nLine Three",
+                BufferRange.None);
+
+            FileRange range = new(
+                new Microsoft.PowerShell.EditorServices.Extensions.FilePosition(3, 1),
+                new Microsoft.PowerShell.EditorServices.Extensions.FilePosition(3, 11));
+
+            Assert.Equal("Line Three", editorContext.CurrentFile.GetText(range));
+        }
+
+        [Fact]
+        public void CanGetTextLinesFromConcreteFileRange()
+        {
+            EditorContext editorContext = CreateEditorContext(
+                "Line One\nLine Two\nLine Three",
+                BufferRange.None);
+
+            FileRange range = new(
+                new Microsoft.PowerShell.EditorServices.Extensions.FilePosition(1, 1),
+                new Microsoft.PowerShell.EditorServices.Extensions.FilePosition(2, 9));
+
+            Assert.Equal(new[] { "Line One", "Line Two" }, editorContext.CurrentFile.GetTextLines(range));
+        }
     }
 }