Merge PR #195: Add MDS047 rule for detecting ambiguous emphasis sequences

Author: merge-queue-bot

PLAN.md

@@ -27,7 +27,7 @@ footer: |
 | 108 | 🔲     | sonnet | [Horizontal rule style rule](plan/108_horizontal-rule-style.md)                                      |
 | 109 | 🔲     | sonnet | [List marker style rule](plan/109_list-marker-style.md)                                              |
 | 110 | ✅     | sonnet | [Ordered list numbering rule](plan/110_ordered-list-numbering.md)                                    |
-| 111 | 🔲     | sonnet | [Ambiguous emphasis rule](plan/111_ambiguous-emphasis.md)                                            |
+| 111 | ✅     | sonnet | [Ambiguous emphasis rule](plan/111_ambiguous-emphasis.md)                                            |
 | 112 | ✅     | opus   | [Markdown convention bundles for MDS034](plan/112_flavor-profiles.md)                                |
 | 113 | 🔲     | sonnet | [User-defined Markdown conventions](plan/113_user-defined-profiles.md)                               |
 | 114 | ✅     | sonnet | [MDS034 message clarity and flavor-vs-rule docs](plan/114_mds034-message-and-flavor-vs-rule-docs.md) |

cmd/mdsmith/main.go

@@ -24,6 +24,7 @@ import (
 	ruledocs "github.com/jeduden/mdsmith/internal/rules"
 
 	// Import all rule packages so their init() functions register rules.
+	_ "github.com/jeduden/mdsmith/internal/rules/ambiguousemphasis"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundfencedcode"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundheadings"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundlists"

internal/config/config_test.go

@@ -11,6 +11,7 @@ import (
 	"gopkg.in/yaml.v3"
 
 	// Import all rule packages so their init() functions register rules.
+	_ "github.com/jeduden/mdsmith/internal/rules/ambiguousemphasis"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundfencedcode"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundheadings"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundlists"

internal/engine/categories_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	// Import all rule packages so their init() functions register rules.
+	_ "github.com/jeduden/mdsmith/internal/rules/ambiguousemphasis"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundfencedcode"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundheadings"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundlists"

internal/integration/rules_test.go

@@ -16,6 +16,7 @@ import (
 	"github.com/yuin/goldmark/text"
 	"go.abhg.dev/goldmark/frontmatter"
 
+	_ "github.com/jeduden/mdsmith/internal/rules/ambiguousemphasis"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundfencedcode"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundheadings"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundlists"

internal/rules/MDS047-ambiguous-emphasis/README.md

@@ -0,0 +1,213 @@
+---
+id: MDS047
+name: ambiguous-emphasis
+status: ready
+description: Forbid emphasis sequences whose meaning a human cannot predict at a glance.
+---
+# MDS047: ambiguous-emphasis
+
+Forbid emphasis sequences whose meaning a human cannot predict at a glance.
+
+CommonMark pairs `*` and `_` runs by counting flanking delimiters. The
+output is well-defined; the source is not. This rule names three shapes
+that read poorly and refuses them.
+
+The shapes are:
+
+- long runs of the same delimiter character
+- backslash escapes glued to a run
+- the same delimiter repeated three times across word boundaries
+
+The check runs on raw source bytes. It skips ranges covered by inline
+code spans, fenced code blocks, and indented code blocks.
+
+## Settings
+
+| Setting                      | Type | Default | Description                                                                  |
+|------------------------------|------|---------|------------------------------------------------------------------------------|
+| `max-run`                    | int  | 0       | Maximum allowed length of a contiguous `*` or `_` run; 0 disables the check  |
+| `forbid-escaped-in-run`      | bool | false   | Flag `*\*` or `_\_` where a backslash-escaped delimiter butts against a run  |
+| `forbid-adjacent-same-delim` | bool | false   | Flag three same-delimiter runs glued by non-whitespace (`*a*b*`, `__a__b__`) |
+
+The defaults make the rule a no-op even when enabled, so it ships safe.
+Profile activation in plan 112 (`portable`, `plain`) sets `max-run: 2`
+and both bool flags to `true`. User overrides on top still win via
+deep-merge.
+
+## Config
+
+Enable with the active profile values:
+
+```yaml
+rules:
+  ambiguous-emphasis:
+    max-run: 2
+    forbid-escaped-in-run: true
+    forbid-adjacent-same-delim: true
+```
+
+Disable:
+
+```yaml
+rules:
+  ambiguous-emphasis: false
+```
+
+Long-run only (skip the other two detectors):
+
+```yaml
+rules:
+  ambiguous-emphasis:
+    max-run: 2
+```
+
+## Examples
+
+### Bad -- long delimiter run
+
+<?include
+file: bad/long-run.md
+wrap: markdown
+?>
+
+```markdown
+# Title
+
+***bold-italic*** at the start of a paragraph.
+```
+
+<?/include?>
+
+### Bad -- escaped delimiter inside a run
+
+<?include
+file: bad/escaped-in-run.md
+wrap: markdown
+?>
+
+```markdown
+# Title
+
+*****\*a* in the rant string.
+```
+
+<?/include?>
+
+### Bad -- adjacent same-delimiter runs
+
+<?include
+file: bad/adjacent-same-delim.md
+wrap: markdown
+?>
+
+```markdown
+# Title
+
+__a__b__ ambiguous between bold(a) literal-b and literal-a bold(b).
+```
+
+<?/include?>
+
+### Bad -- the rant's Peter Piper example
+
+<?include
+file: bad/peter-piper.md
+wrap: markdown
+?>
+
+```markdown
+# Title
+
+***Peter* Piper** is the rant's other Exhibit-A example.
+```
+
+<?/include?>
+
+### Good
+
+<?include
+file: good/default.md
+wrap: markdown
+?>
+
+```markdown
+# Title
+
+This sentence has **bold** and *italic* and even `*****\*literal*` in a
+code span without flagging.
+
+Multiple separate emphases like *one* and *two* and *three* read
+naturally because spaces split the runs.
+```
+
+<?/include?>
+
+### Good -- patterns inside code spans
+
+<?include
+file: good/in-code-span.md
+wrap: markdown
+?>
+
+```markdown
+# In code span
+
+The string `*****\*a*` inside an inline code span must not flag, and
+neither must `__a__b__` nor `***Peter* Piper**` when wrapped this way.
+```
+
+<?/include?>
+
+### Good -- patterns inside fenced code blocks
+
+<?include
+file: good/in-fenced-block.md
+wrap: markdown
+?>
+
+````markdown
+# In fenced block
+
+The patterns below sit inside a fenced code block and must not flag.
+
+```text
+*****\*a*
+***bold-italic***
+__a__b__
+***Peter* Piper**
+```
+````
+
+<?/include?>
+
+## Diagnostics
+
+- `emphasis run of {n} delimiters; max is {max-run}`
+- `escaped delimiter inside emphasis run`
+- `adjacent same-delimiter emphasis is ambiguous`
+
+## Edge Cases
+
+- **No auto-fix.** The right rewrite depends on author intent: add a
+  space, swap to an HTML entity, or split the run. The rule reports
+  and lets the author choose.
+- **Symmetric openers and closers collapse.** `***x***` has two
+  three-star runs but emits a single long-run diagnostic, anchored at
+  the first occurrence on the line.
+- **Whitespace clears the gap.** `*a* *b* *c*` does not flag adjacent
+  same-delimiter because each gap contains a space; CommonMark resolves
+  the runs unambiguously.
+- **Interaction with MDS042.** MDS042 (emphasis-style) pins which
+  delimiter is used. MDS047 catches the ambiguous combinations that
+  survive a delimiter pin. Both can fire on the same line.
+
+## Meta-Information
+
+- **ID**: MDS047
+- **Name**: `ambiguous-emphasis`
+- **Status**: ready
+- **Default**: disabled
+- **Fixable**: no
+- **Implementation**:
+  [source](./)
+- **Category**: meta

internal/rules/MDS047-ambiguous-emphasis/bad/adjacent-same-delim.md

@@ -0,0 +1,13 @@
+---
+settings:
+  max-run: 2
+  forbid-escaped-in-run: true
+  forbid-adjacent-same-delim: true
+diagnostics:
+  - line: 3
+    column: 1
+    message: "adjacent same-delimiter emphasis is ambiguous"
+---
+# Title
+
+__a__b__ ambiguous between bold(a) literal-b and literal-a bold(b).

internal/rules/MDS047-ambiguous-emphasis/bad/escaped-in-run.md

@@ -0,0 +1,16 @@
+---
+settings:
+  max-run: 2
+  forbid-escaped-in-run: true
+  forbid-adjacent-same-delim: true
+diagnostics:
+  - line: 3
+    column: 1
+    message: "emphasis run of 5 delimiters; max is 2"
+  - line: 3
+    column: 6
+    message: "escaped delimiter inside emphasis run"
+---
+# Title
+
+*****\*a* in the rant string.

internal/rules/MDS047-ambiguous-emphasis/bad/long-run.md

@@ -0,0 +1,13 @@
+---
+settings:
+  max-run: 2
+  forbid-escaped-in-run: true
+  forbid-adjacent-same-delim: true
+diagnostics:
+  - line: 3
+    column: 1
+    message: "emphasis run of 3 delimiters; max is 2"
+---
+# Title
+
+***bold-italic*** at the start of a paragraph.

internal/rules/MDS047-ambiguous-emphasis/bad/peter-piper.md

@@ -0,0 +1,13 @@
+---
+settings:
+  max-run: 2
+  forbid-escaped-in-run: true
+  forbid-adjacent-same-delim: true
+diagnostics:
+  - line: 3
+    column: 1
+    message: "emphasis run of 3 delimiters; max is 2"
+---
+# Title
+
+***Peter* Piper** is the rant's other Exhibit-A example.