fix: report every math-delimiter problem with its line number

Previously the checker returned a single MathDelimiterError enum for
the whole document, stopping at the first problem, and misreported an
unclosed inline "$" as INVALID_NEWLINE_INSIDE_INLINE whenever a
newline appeared before end of input.

math_delimiter_checker/check_markdown now return
list[MathDelimiterProblem], each carrying a 1-based line number, and
resync after an error to keep scanning for further independent
problems instead of stopping at the first. The newline-inside-inline
check is removed entirely: an unclosed "$ ... $" is always reported as
MISSING_CLOSING_SINGLE_DOLLAR regardless of embedded newlines, and (as
a consequence) a multi-line "$ ... $" that does eventually close is no
longer flagged as an error. PASSED is dropped from the enum since "no
problem" is now represented by an empty list.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: m-messer

in2lambda/validation/__init__.py

@@ -6,32 +6,35 @@
 delimiters - before the markdown is converted.
 """
 
-from in2lambda.validation.delimiters import MathDelimiterError, math_delimiter_checker
+from in2lambda.validation.delimiters import (
+    MathDelimiterError,
+    MathDelimiterProblem,
+    math_delimiter_checker,
+)
 
-__all__ = ["MathDelimiterError", "math_delimiter_checker", "check_markdown"]
+__all__ = [
+    "MathDelimiterError",
+    "MathDelimiterProblem",
+    "math_delimiter_checker",
+    "check_markdown",
+]
 
 
-def check_markdown(md_content: str) -> list[MathDelimiterError]:
+def check_markdown(md_content: str) -> list[MathDelimiterProblem]:
     """Run every markdown check and return the problems found.
 
     Args:
         md_content: The markdown text to validate.
 
     Returns:
-        A list of :class:`MathDelimiterError` members, one per problem found.
+        A list of :class:`MathDelimiterProblem`, one per problem found.
         An empty list means the markdown passed every check.
 
     Examples:
         >>> from in2lambda.validation import check_markdown
         >>> check_markdown("Inline $x = y$ is fine.")
         []
         >>> check_markdown("Unbalanced $x = y")
-        [<MathDelimiterError.MISSING_CLOSING_SINGLE_DOLLAR: 'unclosed inline $ ... $'>]
+        [MathDelimiterProblem(line=1, error=<MathDelimiterError.MISSING_CLOSING_SINGLE_DOLLAR: 'unclosed inline $ ... $'>)]
     """
-    problems: list[MathDelimiterError] = []
-
-    result = math_delimiter_checker(md_content)
-    if result is not MathDelimiterError.PASSED:
-        problems.append(result)
-
-    return problems
+    return math_delimiter_checker(md_content)

in2lambda/validation/delimiters.py

@@ -6,18 +6,17 @@
 delimiter mistake it finds.
 """
 
+from dataclasses import dataclass
 from enum import Enum
 
 
 class MathDelimiterError(Enum):
-    """Outcome of :func:`math_delimiter_checker`.
+    """A specific delimiter mistake found by :func:`math_delimiter_checker`.
 
-    ``PASSED`` means no problem was found; every other member describes a
-    specific delimiter mistake. The value is a short human-readable message
-    suitable for showing on the command line.
+    The value is a short human-readable message suitable for showing on the
+    command line.
     """
 
-    PASSED = "ok"
     MISSING_NEWLINE_BEFORE_OPENING_DISPLAY = "opening $$ must start its own line"
     MISSING_NEWLINE_AFTER_OPENING_DISPLAY = "opening $$ must be followed by a newline"
     DOUBLE_DOLLAR_INSTEAD_OF_CLOSING_SINGLE = "inline $ ... $ closed with $$"
@@ -26,40 +25,58 @@ class MathDelimiterError(Enum):
     )
     MISSING_NEWLINE_BEFORE_CLOSING_DISPLAY = "closing $$ must start its own line"
     MISSING_NEWLINE_AFTER_CLOSING_DISPLAY = "closing $$ must be followed by a newline"
-    INVALID_NEWLINE_INSIDE_INLINE = "newline inside an inline $ ... $ expression"
     MISSING_CLOSING_SINGLE_DOLLAR = "unclosed inline $ ... $"
     MISSING_CLOSING_DOUBLE_DOLLAR = "unclosed display $$ ... $$"
 
 
-def math_delimiter_checker(md_content: str) -> MathDelimiterError:
-    r"""Scan markdown for the first math-delimiter mistake.
+@dataclass(frozen=True)
+class MathDelimiterProblem:
+    """A single delimiter mistake and the (1-based) line it was found on."""
+
+    line: int
+    error: MathDelimiterError
+
+    def __str__(self) -> str:
+        return f"line {self.line}: {self.error.value}"
+
+
+def math_delimiter_checker(md_content: str) -> list[MathDelimiterProblem]:
+    r"""Scan markdown for every math-delimiter mistake.
 
     ``\$`` is treated as a literal dollar sign, not a delimiter.
 
     Args:
         md_content: The markdown text to check.
 
     Returns:
-        ``MathDelimiterError.PASSED`` if the delimiters are well formed,
-        otherwise the member describing the first problem found.
+        A list of :class:`MathDelimiterProblem`, one per mistake found, in
+        the order they occur. An empty list means the delimiters are well
+        formed.
 
     Examples:
         >>> from in2lambda.validation.delimiters import math_delimiter_checker
         >>> math_delimiter_checker("An inline $x = y$ expression.")
-        <MathDelimiterError.PASSED: 'ok'>
+        []
         >>> math_delimiter_checker("Display:\n$$\nx = y\n$$")
-        <MathDelimiterError.PASSED: 'ok'>
+        []
         >>> math_delimiter_checker("This costs \\$5, no math here.")
-        <MathDelimiterError.PASSED: 'ok'>
-        >>> math_delimiter_checker("Broken $x = y")
-        <MathDelimiterError.MISSING_CLOSING_SINGLE_DOLLAR: 'unclosed inline $ ... $'>
+        []
         >>> math_delimiter_checker("Run `echo $PATH` now.")
-        <MathDelimiterError.PASSED: 'ok'>
+        []
+        >>> math_delimiter_checker("Broken $x = y")
+        [MathDelimiterProblem(line=1, error=<MathDelimiterError.MISSING_CLOSING_SINGLE_DOLLAR: 'unclosed inline $ ... $'>)]
     """
+    problems: list[MathDelimiterProblem] = []
+
+    def report(error: MathDelimiterError) -> None:
+        problems.append(MathDelimiterProblem(md_content.count("\n", 0, idx) + 1, error))
+
     # False once we are inside a math expression and awaiting its closing delimiter.
     expect_open_delimiter = True
     # While inside an expression, whether it opened with a single "$" (inline) or "$$" (display).
     expect_single_dollar = True
+    # Line on which the currently open (unclosed) expression started.
+    open_line = 1
 
     # Backtick code spans/fences are not markdown math and must not be scanned for
     # "$" delimiters, e.g. a shell variable like `echo $PATH` or a fenced snippet.
@@ -109,52 +126,71 @@ def math_delimiter_checker(md_content: str) -> MathDelimiterError:
         if character == "$" and prev_character != "\\":
             if expect_open_delimiter:
                 expect_open_delimiter = False
+                open_line = md_content.count("\n", 0, idx) + 1
 
                 if next_character == "$":
                     next_next_character = (
                         md_content[idx + 2] if idx + 2 < len(md_content) else None
                     )
                     # "$$" must sit alone on its own line.
                     if prev_character != "\n" and prev_character is not None:
-                        return MathDelimiterError.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY
-                    if next_next_character != "\n":
-                        return MathDelimiterError.MISSING_NEWLINE_AFTER_OPENING_DISPLAY
-
-                    expect_single_dollar = False
+                        report(
+                            MathDelimiterError.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY
+                        )
+                        expect_open_delimiter, expect_single_dollar = True, True
+                    elif next_next_character != "\n":
+                        report(MathDelimiterError.MISSING_NEWLINE_AFTER_OPENING_DISPLAY)
+                        expect_open_delimiter, expect_single_dollar = True, True
+                    else:
+                        expect_single_dollar = False
                     idx += 1  # Skip the second "$"; the loop increments idx again.
                 else:
                     expect_single_dollar = True
             else:
                 expect_open_delimiter = True
 
                 if expect_single_dollar and next_character == "$":
-                    return MathDelimiterError.DOUBLE_DOLLAR_INSTEAD_OF_CLOSING_SINGLE
+                    report(MathDelimiterError.DOUBLE_DOLLAR_INSTEAD_OF_CLOSING_SINGLE)
+                    expect_open_delimiter, expect_single_dollar = True, True
 
                 elif not expect_single_dollar:
                     if next_character != "$":
-                        return (
+                        report(
                             MathDelimiterError.MISSING_CLOSING_DOUBLE_INSTEAD_OF_SINGLE
                         )
-
-                    next_next_character = (
-                        md_content[idx + 2] if idx + 2 < len(md_content) else None
-                    )
-                    if prev_character != "\n" and prev_character is not None:
-                        return MathDelimiterError.MISSING_NEWLINE_BEFORE_CLOSING_DISPLAY
-                    if next_next_character != "\n" and next_next_character is not None:
-                        return MathDelimiterError.MISSING_NEWLINE_AFTER_CLOSING_DISPLAY
-
-                    idx += 1  # Skip the second "$"; the loop increments idx again.
-
-        # A newline may not appear inside an inline "$ ... $" expression.
-        elif character == "\n" and not expect_open_delimiter and expect_single_dollar:
-            return MathDelimiterError.INVALID_NEWLINE_INSIDE_INLINE
+                        expect_open_delimiter, expect_single_dollar = True, True
+                    else:
+                        next_next_character = (
+                            md_content[idx + 2] if idx + 2 < len(md_content) else None
+                        )
+                        if prev_character != "\n" and prev_character is not None:
+                            report(
+                                MathDelimiterError.MISSING_NEWLINE_BEFORE_CLOSING_DISPLAY
+                            )
+                            expect_open_delimiter, expect_single_dollar = True, True
+                        elif (
+                            next_next_character != "\n"
+                            and next_next_character is not None
+                        ):
+                            report(
+                                MathDelimiterError.MISSING_NEWLINE_AFTER_CLOSING_DISPLAY
+                            )
+                            expect_open_delimiter, expect_single_dollar = True, True
+
+                        idx += 1  # Skip the second "$"; the loop increments idx again.
 
         idx += 1
 
-    if expect_open_delimiter:
-        return MathDelimiterError.PASSED
-    elif expect_single_dollar:
-        return MathDelimiterError.MISSING_CLOSING_SINGLE_DOLLAR
-    else:
-        return MathDelimiterError.MISSING_CLOSING_DOUBLE_DOLLAR
+    if not expect_open_delimiter:
+        problems.append(
+            MathDelimiterProblem(
+                open_line,
+                (
+                    MathDelimiterError.MISSING_CLOSING_SINGLE_DOLLAR
+                    if expect_single_dollar
+                    else MathDelimiterError.MISSING_CLOSING_DOUBLE_DOLLAR
+                ),
+            )
+        )
+
+    return problems

tests/test_validation.py

@@ -8,11 +8,13 @@
 
 from in2lambda.validation import (
     MathDelimiterError,
+    MathDelimiterProblem,
     check_markdown,
     math_delimiter_checker,
 )
 
 E = MathDelimiterError
+P = MathDelimiterProblem
 
 VALID = [
     "This is an inline math expression: $x = y$.",
@@ -39,50 +41,117 @@
     "Price \\$50 for $x + y = z$ calculation.",
     "Expression: $cost = \\$100$.",
     "Display:\n$$\ncost = \\$100\n$$",
+    # A "$ ... $" expression may now span a newline before closing.
+    "This is an inline math expression:$x \n= y$.",
+    "This is an inline math expression:$\nx = y$.",
+    "This is an inline math expression:$x = y\n$.",
+    # A "$" inside a code span/fence is not math and must be ignored.
+    "Run `echo $PATH` now.\n",
+    "```bash\necho $HOME\n```\n",
 ]
 
 INVALID = [
-    ("This is an inline math expression: $x = y.", E.MISSING_CLOSING_SINGLE_DOLLAR),
-    ("This is an inline math expression: x = y$.", E.MISSING_CLOSING_SINGLE_DOLLAR),
-    ("This is an inline math expression:$x \n= y$.", E.INVALID_NEWLINE_INSIDE_INLINE),
-    ("This is an inline math expression:$\nx = y$.", E.INVALID_NEWLINE_INSIDE_INLINE),
-    ("This is an inline math expression:$x = y\n$.", E.INVALID_NEWLINE_INSIDE_INLINE),
-    ("Expression $x = y$$.", E.DOUBLE_DOLLAR_INSTEAD_OF_CLOSING_SINGLE),
-    ("Expression $x = y$ and $a = b$ and $c =", E.MISSING_CLOSING_SINGLE_DOLLAR),
-    ("Expression $$$x = y$$$.", E.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY),
+    (
+        "This is an inline math expression: $x = y.",
+        [P(1, E.MISSING_CLOSING_SINGLE_DOLLAR)],
+    ),
+    (
+        "This is an inline math expression: x = y$.",
+        [P(1, E.MISSING_CLOSING_SINGLE_DOLLAR)],
+    ),
+    (
+        "Expression $x = y$$.",
+        [
+            P(1, E.DOUBLE_DOLLAR_INSTEAD_OF_CLOSING_SINGLE),
+            P(1, E.MISSING_CLOSING_SINGLE_DOLLAR),
+        ],
+    ),
+    (
+        "Expression $x = y$ and $a = b$ and $c =",
+        [P(1, E.MISSING_CLOSING_SINGLE_DOLLAR)],
+    ),
+    (
+        "Expression $$$x = y$$$.",
+        [
+            P(1, E.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY),
+            P(1, E.DOUBLE_DOLLAR_INSTEAD_OF_CLOSING_SINGLE),
+            P(1, E.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY),
+        ],
+    ),
     (
         "This is a display math expression:\n$$\nx = y\n",
-        E.MISSING_CLOSING_DOUBLE_DOLLAR,
+        [P(2, E.MISSING_CLOSING_DOUBLE_DOLLAR)],
     ),
     (
         "This is a display math expression:\nx = y\n$$",
-        E.MISSING_NEWLINE_AFTER_OPENING_DISPLAY,
+        [P(3, E.MISSING_NEWLINE_AFTER_OPENING_DISPLAY)],
     ),
     (
         "This is a display math expression:$$\nx = y\n$$.",
-        E.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY,
+        [
+            P(1, E.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY),
+            P(3, E.MISSING_NEWLINE_AFTER_OPENING_DISPLAY),
+        ],
     ),
     (
         "This is a display math expression:\n$$\nx = y\n$$.",
-        E.MISSING_NEWLINE_AFTER_CLOSING_DISPLAY,
+        [P(4, E.MISSING_NEWLINE_AFTER_CLOSING_DISPLAY)],
+    ),
+    (
+        "Expression:\n$$text\nx = y\n$$",
+        [
+            P(2, E.MISSING_NEWLINE_AFTER_OPENING_DISPLAY),
+            P(4, E.MISSING_NEWLINE_AFTER_OPENING_DISPLAY),
+        ],
+    ),
+    (
+        "Expression:\n$$\nx = y\ntext$$",
+        [P(4, E.MISSING_NEWLINE_BEFORE_CLOSING_DISPLAY)],
+    ),
+    (
+        "Expression $$x = y$.",
+        [
+            P(1, E.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY),
+            P(1, E.MISSING_CLOSING_SINGLE_DOLLAR),
+        ],
+    ),
+    (
+        "Expression $x = y$$",
+        [
+            P(1, E.DOUBLE_DOLLAR_INSTEAD_OF_CLOSING_SINGLE),
+            P(1, E.MISSING_CLOSING_SINGLE_DOLLAR),
+        ],
+    ),
+    (
+        "Expression $$x = y$",
+        [
+            P(1, E.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY),
+            P(1, E.MISSING_CLOSING_SINGLE_DOLLAR),
+        ],
+    ),
+    # An unclosed "$" must report MISSING_CLOSING_SINGLE_DOLLAR, not a
+    # newline-related error, however many lines it spans before EOF.
+    ("This $x is unclosed.\n", [P(1, E.MISSING_CLOSING_SINGLE_DOLLAR)]),
+    # Two independent problems on different lines are both reported.
+    (
+        "Expression $x = y$$.\nAnother $a = b$$.\n",
+        [
+            P(1, E.DOUBLE_DOLLAR_INSTEAD_OF_CLOSING_SINGLE),
+            P(2, E.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY),
+        ],
     ),
-    ("Expression:\n$$text\nx = y\n$$", E.MISSING_NEWLINE_AFTER_OPENING_DISPLAY),
-    ("Expression:\n$$\nx = y\ntext$$", E.MISSING_NEWLINE_BEFORE_CLOSING_DISPLAY),
-    ("Expression $$x = y$.", E.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY),
-    ("Expression $x = y$$", E.DOUBLE_DOLLAR_INSTEAD_OF_CLOSING_SINGLE),
-    ("Expression $$x = y$", E.MISSING_NEWLINE_BEFORE_OPENING_DISPLAY),
 ]
 
 
 @pytest.mark.parametrize("content", VALID)
 def test_valid_markdown_passes(content: str) -> None:
-    assert math_delimiter_checker(content) is E.PASSED
+    assert math_delimiter_checker(content) == []
     assert check_markdown(content) == []
 
 
 @pytest.mark.parametrize("content, expected", INVALID)
 def test_invalid_markdown_is_reported(
-    content: str, expected: MathDelimiterError
+    content: str, expected: list[MathDelimiterProblem]
 ) -> None:
-    assert math_delimiter_checker(content) is expected
-    assert check_markdown(content) == [expected]
+    assert math_delimiter_checker(content) == expected
+    assert check_markdown(content) == expected