Show every region that differs when Should-BeString fails on a big string

[nohwnd]

Supersedes #3003, which scanned for the first differing line. That answers "one thing changed". Comparing a snapshot is "many things changed", and a scan stops at the first one.

Fix #2951
Fix #3006

What it prints

Four lines changed in a package.json:

Expected strings to be the same, but they were different.
Expected length: 236
Actual length:   243
Expected 16 line(s), actual 16 line(s).
2 regions differ.

   1  1 |   {
   2  2 |     "name": "widget",
   3    | -   "version": "1.2.0",
      3 | +   "version": "1.3.0",
   4    | -   "license": "MIT",
      4 | +   "license": "Apache-2.0",
   5  5 |     "main": "index.js",
   6  6 |     "scripts": {
  ...
   9  9 |     },
  10 10 |     "dependencies": {
  11    | -     "left-pad": "^1.3.0"
     11 | +     "left-pad": "^1.3.1"
  12 12 |     },
  13 13 |     "engines": {
  14    | -     "node": ">=18"
     14 | +     "node": ">=20"
  15 15 |     }
  16 16 |   }

Expected line numbers on the left, actual on the right, so it stays readable when lines are added and the two sides stop lining up:

   1  1 |   Describe 'Api' {
      2 | +     BeforeAll {
      3 | +         Start-TestServer
      4 | +     }
      5 | + 
   2  6 |       It 'returns 200' {
  ...
   9    | -         $r.ContentType | Should-BeString 'application/json'
  10 13 |       }
  11 14 |   }

Only the lines that differ are expanded, so a tab or a trailing space is visible without turning the context into escape codes:

  1 1 |   first
  2   | -   indented with spaces
    2 | + ␉indented with a tab
  3   | - no trailing space
    3 | + no trailing space···
  4 4 |   last

The one difference you cannot work out by reading the output gets named instead:

Every line is the same, only the line endings differ.
Expected: 4 CRLF
But was:  4 LF
Use -NormalizeLineEnding to ignore this.

At most five regions are printed, then it says how many are left:

12 regions differ, showing the first 5.
...
  7 more region(s) differ, not shown.

Short strings are untouched. The full text with a caret under the difference is still the most precise thing we can show, and a long single line still gets the excerpt with ellipses.

Two DiffPlex defaults that fail quietly

Both are set in StringDiff.cs and both have tests, because getting them wrong produces no output rather than wrong output.

Setting	Default	Why the default is wrong here
ignoreWhitespace	true	A difference that is only a trailing space is reported as no difference at all.
line chunker	LineChunker	It throws the line endings away, so CRLF against LF comes back as two identical strings. LineEndingsPreservingChunker keeps them.

SideBySideDiffBuilder pairs changed lines and gives positions on both sides, so Pester does not have to do that bookkeeping.

Public surface: one method

Pester.StringDiff.Format(expected, actual, caseSensitive, context, maxRegions) returns the part of the failure message that describes how the two strings differ. That is the whole public API this PR adds.

Every vendored type is internal, so DiffPlex is not part of Pester's compatibility surface and can be updated, trimmed further or swapped out without that being a breaking change. StringDiffResult and Compare are internal too; the unit tests reach them through InternalsVisibleTo.

Vendored, not referenced

Shipping DiffPlex.dll next to Pester.dll puts a second assembly identity in the user's session. Windows PowerShell 5.1 has no load context isolation, so a module that already loaded a different DiffPlex version wins and Pester cannot do anything about it.

• 14 files out of the 29 in the library. ThreeWayDiffer, UnidiffRenderer and InlineDiffBuilder are left behind, and so are five more files that only existed to serve members Pester never calls.
• Apache-2.0, the same licence Pester uses.
• Three mechanical rewrites (namespace, internal, licence header) plus pester.patch, which removes the members Pester does not call. The patch touches two files, removes 99 lines and adds 7.
• src/csharp/Pester/DiffPlex/VENDORING.md records the version and the commit (3cb6415, what the 1.9.0 nuspec says the package was built from), and says what is left out and why.
• Update-VendoredDiffPlex.ps1 rebuilds the whole copy from upstream and -Verify compares the result against what is on disk. Deleting code is what usually turns a vendored copy into a fork nobody can update, so the removals are kept as a patch rather than applied by hand: run it against a newer DiffPlex and either the patch applies or git says which hunk failed.

The licence obligations

Apache-2.0 asks for three things and the second commit adds two of them.

	Where
A copy of the licence with the source	src/csharp/Pester/DiffPlex/LICENSE.txt, unmodified
A copy of the licence with the binary, section 4(a)	ThirdPartyNotices.txt, which build.ps1 now copies into the built module. Pester.dll has DiffPlex compiled into it, and the module previously shipped no licence file at all
Modified files saying they are modified, section 4(b)	a four line header on each of the 19 files, carrying source, author, licence and the change

There is no NOTICE file upstream, so section 4(d) does not apply. The upstream source files carry no copyright header of their own, so there was nothing to retain under 4(c); the header does the attribution instead, naming Matthew Manela as the nuspec does.

Update-VendoredDiffPlex.ps1 -Verify strips the header before comparing, so it still proves every file is upstream apart from the namespace.

Upstream releases about once a year (1.7.2 in 2023-12, 1.8.0 in 2025-05, 1.9.0 in 2025-09), so this is not something we need to track closely.

Cost with embedded symbols, which is how Pester.csproj builds:

	Before	After	Added
Pester.dll net8.0	123 904 B	145 920 B	21.5 KB
Pester.dll net462	117 760 B	139 776 B	21.5 KB

Embedded symbols carry the source text, so the licence headers cost about 5 KB and dropping the unused members gave 3.5 KB back.

The full DiffPlex.dll is 33.3 KB per target framework, so vendoring the part we use is also the smaller option.

Verification

• Full suite on macOS: 2922 passed, 0 failed, 3 skipped.
• src/csharp/PesterTests: 78 passed, 0 failed. 20 of those are new, in StringDiffTests.cs.
• Update-VendoredDiffPlex.ps1 -Verify passes against DiffPlex 3cb6415.
• One differing line in a 10 000 line file takes 2 ms and prints 6 lines.

Note that CI does not currently run src/csharp/PesterTests at all, so the C# tests here only run locally. That is worth fixing separately.

🤖

[github-advanced-security]

PSScriptAnalyzer found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️