fix: detect CRLF-only string differences and report clear error message (#74)

* fix: detect CRLF-only string differences and report clear error message

When two strings differ only in line endings (CRLF vs LF), the diff
normalization produces zero hunks, resulting in a confusing empty diff.
Now sameAs detects this case early and fails with a descriptive message
indicating which side uses CRLF vs LF.

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

* fix: make all CRLF detection branches explicit and tested

Split the catch-all else branch into two specific cases:
- standalone \r characters (neither string contains \r\n)
- mixed CRLF/LF line endings (both strings contain \r\n)

Each branch now has a descriptive message and a dedicated test.

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: morisil

CLAUDE.md

@@ -13,6 +13,10 @@ Both developers and AI agents are expected to add entries as they encounter surp
 
 ## Known gotchas
 
+## Testing conventions
+
+- Tests use `// given`, `// when`, `// then` comments to structure test cases. Use existing test cases as a reference.
+
 ## Anti-patterns to avoid
 
 - Do not add content to this file that is already discoverable by reading the source or build scripts — that inflates context without adding signal, reducing AI agent task success rates (see [arxiv 2602.11988](https://arxiv.org/abs/2602.11988)).

src/commonMain/kotlin/SameAs.kt

@@ -34,6 +34,20 @@ public infix fun String?.sameAs(expected: String) {
         fail("The string is null, but expected to be: $expected")
     }
 
+    // Detect strings that differ only in line endings (CRLF vs LF).
+    // The diff normalizes \r away, which would produce zero hunks — confusing the developer.
+    if (this.replace("\r", "") == expected.replace("\r", "")) {
+        val expectedCrlf = "\r\n" in expected
+        val actualCrlf = "\r\n" in this
+        val detail = when {
+            expectedCrlf && !actualCrlf -> "expected uses CRLF (\\r\\n), actual uses LF (\\n)"
+            !expectedCrlf && actualCrlf -> "expected uses LF (\\n), actual uses CRLF (\\r\\n)"
+            !expectedCrlf && !actualCrlf -> "strings contain standalone carriage return (\\r) characters"
+            else -> "strings have mixed CRLF (\\r\\n) and LF (\\n) line endings"
+        }
+        fail("Strings differ only in line endings: $detail")
+    }
+
     val diff = generateUnifiedDiff(expected, this)
     fail(diff)
 }

src/commonTest/kotlin/SameAsTest.kt

@@ -1137,6 +1137,70 @@ class SameAsTest {
         "line1\nline2\n" sameAs "line1\nline2\n"
     }
 
+    @Test
+    fun `should fail with clear message when actual uses CRLF and expected uses LF`() {
+        // given
+        val expected = "line1\nline2\n"
+        val actual = "line1\r\nline2\r\n"
+
+        // when
+        val error = assertFailsWith<AssertionError> {
+            actual sameAs expected
+        }
+
+        // then
+        error.message sameAs
+            "Strings differ only in line endings: expected uses LF (\\n), actual uses CRLF (\\r\\n)"
+    }
+
+    @Test
+    fun `should fail with clear message when expected uses CRLF and actual uses LF`() {
+        // given
+        val expected = "line1\r\nline2\r\n"
+        val actual = "line1\nline2\n"
+
+        // when
+        val error = assertFailsWith<AssertionError> {
+            actual sameAs expected
+        }
+
+        // then
+        error.message sameAs
+            "Strings differ only in line endings: expected uses CRLF (\\r\\n), actual uses LF (\\n)"
+    }
+
+    @Test
+    fun `should fail with clear message when strings contain standalone carriage returns`() {
+        // given
+        val expected = "ab"
+        val actual = "a\rb"
+
+        // when
+        val error = assertFailsWith<AssertionError> {
+            actual sameAs expected
+        }
+
+        // then
+        error.message sameAs
+            "Strings differ only in line endings: strings contain standalone carriage return (\\r) characters"
+    }
+
+    @Test
+    fun `should fail with clear message when strings have mixed CRLF and LF line endings`() {
+        // given
+        val expected = "line1\r\nline2\nline3\n"
+        val actual = "line1\nline2\r\nline3\n"
+
+        // when
+        val error = assertFailsWith<AssertionError> {
+            actual sameAs expected
+        }
+
+        // then
+        error.message sameAs
+            "Strings differ only in line endings: strings have mixed CRLF (\\r\\n) and LF (\\n) line endings"
+    }
+
     @Test
     fun `should fail and report difference with control characters`() {
         // given