fix: treat backslash-escaped punctuation as literal

src/Rules/EscapeRule.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Tempest\Markdown\Rules;
+
+use Tempest\Markdown\Parser;
+use Tempest\Markdown\ProvidesFirstChar;
+use Tempest\Markdown\ProvidesStopChar;
+use Tempest\Markdown\Rule;
+use Tempest\Markdown\Token;
+use Tempest\Markdown\Tokens\TextToken;
+
+/**
+ * A backslash before ASCII punctuation makes that character literal.
+ *
+ * @see https://spec.commonmark.org/0.31.2/#backslash-escapes
+ */
+final class EscapeRule implements Rule, ProvidesFirstChar, ProvidesStopChar
+{
+    private const string PUNCTUATION = '!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~';
+
+    private(set) string $firstChar = '\\';
+    private(set) string $stopChar = '\\';
+
+    public function shouldParse(Parser $parser): bool
+    {
+        $next = $parser->content[$parser->position + 1] ?? '';
+
+        return $next !== '' && str_contains(self::PUNCTUATION, $next);
+    }
+
+    public function parse(Parser $parser): ?Token
+    {
+        $parser->consume();
+        $char = $parser->consume();
+
+        // Written as an entity before a line ending, an escaped backslash
+        // cannot be read back as a hard line break by TextToken.
+        $text = $char === '\\'
+        && str_contains(Parser::NEW_LINE, $parser->current ?? ' ')
+            ? '&#92;'
+            : htmlspecialchars($char, ENT_COMPAT | ENT_HTML5);
+
+        if ($parser->lastToken instanceof TextToken) {
+            $parser->lastToken->append($text);
+
+            return null;
+        }
+
+        return new TextToken($text);
+    }
+}

src/Tokens/BoldAndItalicToken.php

@@ -4,6 +4,7 @@
 
 use Tempest\Markdown\Parser;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\LinkRule;
 use Tempest\Markdown\Rules\SocialHandleRule;
@@ -26,6 +27,7 @@ public function parse(Parser $parser): string
                 new LinkRule(),
                 new SocialHandleRule(),
                 new ImageRule(),
+                new EscapeRule(),
                 new TextRule(),
             ])
             ->parse($this->content);

src/Tokens/BoldToken.php

@@ -4,6 +4,7 @@
 
 use Tempest\Markdown\Parser;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
 use Tempest\Markdown\Rules\LinkRule;
@@ -28,6 +29,7 @@ public function parse(Parser $parser): string
                 new LinkRule(),
                 new SocialHandleRule(),
                 new ImageRule(),
+                new EscapeRule(),
                 new TextRule(),
             ])
             ->parse($this->content);

src/Tokens/DivToken.php

@@ -6,6 +6,7 @@
 use Tempest\Markdown\Rules\BoldAndItalicRule;
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\HeadingRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
@@ -39,6 +40,7 @@ public function parse(Parser $parser): string
                 new ImageRule(),
                 new PreRule(),
                 new CodeRule(),
+                new EscapeRule(),
                 new TextRule(),
             ])
             ->parse($this->content);

src/Tokens/HeadingToken.php

@@ -6,6 +6,7 @@
 use Tempest\Markdown\Rules\BoldAndItalicRule;
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
 use Tempest\Markdown\Rules\LinkRule;
@@ -42,6 +43,7 @@ public function parse(Parser $parser): string
                 new SocialHandleRule(),
                 new ImageRule(),
                 new CodeRule(),
+                new EscapeRule(),
                 new TextRule(),
             ])
             ->parse($this->content);

src/Tokens/HtmlToken.php

@@ -6,6 +6,7 @@
 use Tempest\Markdown\Rules\BoldAndItalicRule;
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
 use Tempest\Markdown\Rules\LinkRule;
@@ -39,6 +40,7 @@ public function parse(Parser $parser): string
                 new SocialHandleRule(),
                 new ImageRule(),
                 new CodeRule(),
+                new EscapeRule(),
                 new TextRule(),
             ])
             ->parse($this->html)

src/Tokens/ItalicToken.php

@@ -5,6 +5,7 @@
 use Tempest\Markdown\Parser;
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\LinkRule;
 use Tempest\Markdown\Rules\SocialHandleRule;
@@ -28,6 +29,7 @@ public function parse(Parser $parser): string
                 new LinkRule(),
                 new SocialHandleRule(),
                 new ImageRule(),
+                new EscapeRule(),
                 new TextRule(),
             ])
             ->parse($this->content);

src/Tokens/LinkToken.php

@@ -6,6 +6,7 @@
 use Tempest\Markdown\Rules\BoldAndItalicRule;
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
 use Tempest\Markdown\Rules\StrikethroughRule;
@@ -35,6 +36,7 @@ public function parse(Parser $parser): string
                     new ItalicRule(),
                     new StrikethroughRule(),
                     new ImageRule(),
+                    new EscapeRule(),
                     new TextRule(),
                 ])
                 ->parse($this->content);

src/Tokens/ListToken.php

@@ -6,6 +6,7 @@
 use Tempest\Markdown\Rules\BoldAndItalicRule;
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
 use Tempest\Markdown\Rules\LinkRule;
@@ -32,6 +33,7 @@ public function parse(Parser $parser): string
             new SocialHandleRule(),
             new ImageRule(),
             new CodeRule(),
+            new EscapeRule(),
             new TextRule(),
         ]);
 

src/Tokens/OrderedListToken.php

@@ -6,6 +6,7 @@
 use Tempest\Markdown\Rules\BoldAndItalicRule;
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
 use Tempest\Markdown\Rules\LinkRule;
@@ -35,6 +36,7 @@ public function parse(Parser $parser): string
             new SocialHandleRule(),
             new ImageRule(),
             new CodeRule(),
+            new EscapeRule(),
             new TextRule(),
         ]);
 

src/Tokens/ParagraphToken.php

@@ -7,6 +7,7 @@
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
 use Tempest\Markdown\Rules\DivRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
 use Tempest\Markdown\Rules\LinkRule;
@@ -36,6 +37,7 @@ public function parse(Parser $parser): string
             new PreRule(),
             new CodeRule(),
             new DivRule(),
+            new EscapeRule(),
             new TextRule(),
         ]);
 

src/Tokens/QuoteToken.php

@@ -6,6 +6,7 @@
 use Tempest\Markdown\Rules\BoldAndItalicRule;
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
 use Tempest\Markdown\Rules\LinkRule;
@@ -34,6 +35,7 @@ public function parse(Parser $parser): string
                 new LinkRule(),
                 new SocialHandleRule(),
                 new ImageRule(),
+                new EscapeRule(),
                 new TextRule(),
             ])
             ->parse($this->content);

src/Tokens/StrikethroughToken.php

@@ -6,6 +6,7 @@
 use Tempest\Markdown\Rules\BoldAndItalicRule;
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
 use Tempest\Markdown\Rules\LinkRule;
@@ -30,6 +31,7 @@ public function parse(Parser $parser): string
                 new LinkRule(),
                 new SocialHandleRule(),
                 new ImageRule(),
+                new EscapeRule(),
                 new TextRule(),
             ])
             ->parse($this->content);

src/Tokens/TableToken.php

@@ -6,6 +6,7 @@
 use Tempest\Markdown\Rules\BoldAndItalicRule;
 use Tempest\Markdown\Rules\BoldRule;
 use Tempest\Markdown\Rules\CodeRule;
+use Tempest\Markdown\Rules\EscapeRule;
 use Tempest\Markdown\Rules\ImageRule;
 use Tempest\Markdown\Rules\ItalicRule;
 use Tempest\Markdown\Rules\LinkRule;
@@ -32,6 +33,7 @@ public function parse(Parser $parser): string
             new SocialHandleRule(),
             new CodeRule(),
             new ImageRule(),
+            new EscapeRule(),
             new TextRule(),
         ]);
 

tests/Rules/EscapeRuleTest.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace Tempest\Markdown\Tests\Rules;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use Tempest\Markdown\Markdown;
+use Tempest\Markdown\Tests\ParserTestCase;
+
+final class EscapeRuleTest extends ParserTestCase
+{
+    #[Test]
+    #[DataProvider('provideEscapes')]
+    public function escaped_punctuation_is_literal(
+        string $markdown,
+        string $expected,
+    ): void {
+        $this->assertSame(
+            $expected,
+            new Markdown(highlighter: null)->parse($markdown)->html,
+        );
+    }
+
+    public static function provideEscapes(): iterable
+    {
+        yield 'asterisks' => [
+            'Hôtels 3\*\*\* et 4\*\*\*\*',
+            '<p>Hôtels 3*** et 4****</p>',
+        ];
+        yield 'emphasis delimiters' => [
+            '\*not emphasis\*',
+            '<p>*not emphasis*</p>',
+        ];
+        yield 'underscores' => ['\_x\_', '<p>_x_</p>'];
+        yield 'link brackets' => ['\[x\](/y)', '<p>[x](/y)</p>'];
+        yield 'ordered list marker' => ['1\. Step', '<p>1. Step</p>'];
+        yield 'heading marker' => ['\# Title', '<p># Title</p>'];
+        yield 'backslash' => ['a\\\\b', '<p>a\b</p>'];
+        yield 'markup' => ['a\<b', '<p>a&lt;b</p>'];
+        yield 'in a list item' => ['- \* star', '<ul><li>* star</li></ul>'];
+        yield 'in a table cell' => [
+            "| a |\n| - |\n| 3\*\* |",
+            '<table><thead><tr><th>a</th></tr></thead>'
+                . '<tbody><tr><td>3**</td></tr></tbody></table>',
+        ];
+
+        // Only ASCII punctuation can be escaped, and code spans keep their
+        // backslashes.
+        yield 'before a letter' => ['a\qb', '<p>a\qb</p>'];
+        yield 'inside code' => ['`a\*b`', '<p><code>a\*b</code></p>'];
+
+        // A backslash before a line ending is a hard line break, an escaped
+        // one is not.
+        yield 'hard line break' => ["a\\\nb", "<p>a<br />\nb</p>"];
+        yield 'escaped backslash before a line ending' => [
+            "a\\\\\nb",
+            "<p>a&#92;\nb</p>",
+        ];
+    }
+}