Wrapped Markdown should satisfy MD013 line length

[lodyai]

Summary

Running make fmt in leynos/episodic leaves Markdown output that fails the project markdownlint gate with MD013 line-length errors. The formatter is invoked with --wrap, so the resulting Markdown should either wrap these lines within the configured width or leave a clearly intentional exception that markdownlint also accepts.

Reproduction context

Repository: leynos/episodic
Branch: feat/audit-mdtablefix-fmt
Command: make fmt
Formatter invocation from the Makefile output:

mdtablefix --wrap --renumber --breaks --ellipsis --fences --in-place

After formatting, make markdownlint reports:

docs/execplans/4-1-2-finalize-rest-surfaces.md:772:81 error MD013/line-length Line length [Expected: 80; Actual: 100]
docs/execplans/4-1-2-finalize-rest-surfaces.md:778:81 error MD013/line-length Line length [Expected: 80; Actual: 84]
docs/execplans/4-1-2-finalize-rest-surfaces.md:783:81 error MD013/line-length Line length [Expected: 80; Actual: 87]
docs/execplans/4-1-2-finalize-rest-surfaces.md:861:81 error MD013/line-length Line length [Expected: 80; Actual: 119]
docs/tei-rapporteur-users-guide.md:166:81 error MD013/line-length Line length [Expected: 80; Actual: 98]

Examples

Long inline signature line

File: docs/execplans/4-1-2-finalize-rest-surfaces.md

Formatter output:

1. Add
   `count_for_series(self, owner_series_profile_id: str, kind: ReferenceDocumentKind | None) -> int`
   to `ReferenceDocumentRepository` ` Protocol at `episodic

The inline signature remains 100 columns wide and fails MD013. Similar failures occur for adjacent wrapped signatures in the same section.

Long union type line

File: docs/tei-rapporteur-users-guide.md

Before formatting, the line was wrapped:

- `Event = DocumentStart | HeaderEvent | ParagraphEvent | UtteranceEvent |
  DivEvent | DocumentEnd`

After formatting, it became a single long line:

- `Event = DocumentStart | HeaderEvent | ParagraphEvent | UtteranceEvent | DivEvent | DocumentEnd`

That line is 98 columns and fails MD013.

Expected behaviour

With --wrap, mdtablefix output should be compatible with an 80-column MD013 gate for ordinary prose/list content. For long inline code spans, acceptable behaviours would include:

• Preserve an existing valid wrapped form when it already satisfies lint.
• Wrap around surrounding prose without increasing line length.
• Leave unwrappable inline code unchanged only when the input was already unwrappable and lint-exempt.
• Optionally report that a line cannot be safely wrapped instead of producing lint-failing output.

Impact

make fmt currently exits non-zero because the formatting pass is followed by markdownlint. This means the formatter can make the repository less valid after being run, and users must manually repair formatter output before the Markdown gate passes.

[coderabbitai]

🔗 Related PRs

#275 - Preserve nested fenced blocks (#262) [merged]
#280 - Keep GFM footnote references atomic (#277) [merged]
#298 - Fix spurious leading spaces in reflowed wrap output (#291) [merged]
#301 - Keep GFM footnote references with preceding code and link spans (#299) [merged]
#308 - Keep hyphenated compounds with inline code spans atomic during wrap (#307) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Store original source lines alongside the joined paragraph buffer to enable fallback
• After wrapping, detect overflow by measuring output line widths
• When output would exceed the target width but input was valid, emit the stored originals instead
• Add regression tests covering preservation, overflow handling, and normal wrapping behaviour

Design Choices

Design Choice 1: Definition of "input validity" for fallback

Options Considered:

1. Preserve if ALL original lines were ≤ 80 columns (strict validity)
2. Preserve if ANY original line was ≤ 80 columns (partial validity)
3. Preserve if average line length was acceptable (statistical approach)

Chosen Option: 1

Rationale: Strict validity—preserve only when every original source line was under the target width. This ensures the fallback output is guaranteed lint-compliant.

Design Choice 2: Handling truly unwrappable content

Options Considered:

1. Emit on own line and accept the overflow (current behaviour)
2. Report a warning to stderr for manual attention
3. Add a markdownlint disable comment automatically

Chosen Option: 1

Rationale: Accept the overflow silently. The input was already overlong, so the formatter is not making things worse. Adding warnings or automatic comments is out of scope for this ticket.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Track Original Source Lines and Input Validity

Extend the paragraph and continuation state to store original source lines alongside the joined text buffer, enabling fallback when re-wrapping produces overflow.

Task 1: Add Original Line Storage to ParagraphState

Modify ParagraphState to track original source lines for potential verbatim fallback.

• Add original_lines: Vec<String> field to ParagraphState in src/wrap/paragraph.rs
• Add input_all_valid: bool field to track whether all buffered lines were ≤ target width
• Clear both fields in the existing clear() method

Task 2: Capture Original Lines During Paragraph Accumulation

Modify the paragraph accumulation path to store original lines and measure their widths.

• Update ParagraphState::push() in src/wrap/paragraph.rs to accept the full original line string
• Measure each incoming line's Unicode display width using UnicodeWidthStr::width
• Set input_all_valid = false if any line exceeds the target width
• Store the original line in original_lines
• Update call sites in src/wrap.rs (wrap_text main loop) to pass the full line string to push()

Task 3: Add Original Line Storage to PendingPrefix

Extend PendingPrefix to track original source lines for prefixed content (bullets, blockquotes, footnotes).

• Add original_lines: Vec<String> field to PendingPrefix in src/wrap/paragraph.rs
• Add input_all_valid: bool field
• Populate original_lines with the first line when PendingPrefix is created in handle_prefix_line
• Measure the first line's width and initialise input_all_valid

Task 4: Thread Original Lines Through Continuation Handling

Pass original source lines through the continuation chunk mechanism.

• Modify apply_continuation_chunk signature in src/wrap/continuation.rs to accept the original line string
• Append the original line to pending.original_lines
• Measure the line's width and update pending.input_all_valid
• Update call sites in src/wrap.rs (handle_pending_continuation) to pass the full line string

🤖 Prompt for AI agents

Extend `ParagraphState` and `PendingPrefix` to store original source lines and
track input validity, then thread this data through the continuation mechanism.

- In `src/wrap/paragraph.rs`, add `original_lines: Vec<String>` and
`input_all_valid: bool` fields to `ParagraphState`; clear both in the existing
`clear()` method
- Update `ParagraphState::push()` to accept the full original line string;
measure each line's Unicode display width using `UnicodeWidthStr::width`; set
`input_all_valid = false` if any line exceeds the target width; store the
original line in `original_lines`
- In `src/wrap.rs`, update all call sites in the `wrap_text` main loop to pass
the full `line` string to `push()`
- In `src/wrap/paragraph.rs`, add `original_lines: Vec<String>` and
`input_all_valid: bool` fields to `PendingPrefix`; populate `original_lines`
with the first line when `PendingPrefix` is created in `handle_prefix_line`;
measure the first line's width and initialise `input_all_valid`
- In `src/wrap/continuation.rs`, modify the `apply_continuation_chunk` signature
to accept the original line string; append the original line to
`pending.original_lines`; measure the line's width and update
`pending.input_all_valid`
- In `src/wrap.rs`, update all call sites in `handle_pending_continuation` to
pass the full `line` string to `apply_continuation_chunk`

Phase 2: Implement Overflow Detection and Fallback Emission

Add post-wrap overflow detection and implement fallback to original lines when re-wrapping produces worse output than the input.

Task 1: Add Width Measurement Utility

Create a helper to measure rendered line widths for overflow detection.

• Add fn line_exceeds_width(line: &str, width: usize) -> bool helper in src/wrap/paragraph.rs
• Use UnicodeWidthStr::width for Unicode-correct measurement

Task 2: Implement Fallback in flush_paragraph

Add overflow detection and fallback logic for plain paragraphs.

• In flush_paragraph in src/wrap/paragraph.rs, after wrap_preserving_code returns, check if any output line exceeds self.width
• If overflow detected AND state.input_all_valid is true, emit stored state.original_lines instead of the wrapped output
• Ensure original lines are emitted with correct handling (no additional prefix manipulation)

Task 3: Implement Fallback in Prefixed Line Emission

Add overflow detection and fallback for bullet/blockquote/footnote content.

• In append_wrapped_with_prefix_width in src/wrap/paragraph.rs, after wrapping, check output line widths
• Add a fallback path that emits pending.original_lines when overflow is detected and input was valid
• Handle the case where PendingPrefix contains the originals (pass validity state through)

Task 4: Implement Fallback in emit_pending_prefix_segment

Add overflow detection for mid-continuation flushes in src/wrap/continuation.rs.

• After append_wrapped_with_prefix_width is called, check for overflow
• Extend the fallback mechanism to cover partial flushes during ClosedAndReopened handling
• Ensure original_lines are sliced correctly when only part of the pending content is flushed

🤖 Prompt for AI agents

Add a width measurement utility and implement overflow detection with fallback
emission across plain paragraphs, prefixed lines, and mid-continuation flushes.

- In `src/wrap/paragraph.rs`, add `fn line_exceeds_width(line: &str, width:
usize) -> bool` using `UnicodeWidthStr::width` for Unicode-correct measurement
- In `flush_paragraph` in `src/wrap/paragraph.rs`, after `wrap_preserving_code`
returns, use `line_exceeds_width` to check if any output line exceeds
`self.width`; if overflow is detected AND `state.input_all_valid` is true, emit
`state.original_lines` verbatim instead of the wrapped output, with no
additional prefix manipulation
- In `append_wrapped_with_prefix_width` in `src/wrap/paragraph.rs`, after
wrapping, check output line widths; add a fallback path that emits
`pending.original_lines` when overflow is detected and `pending.input_all_valid`
is true
- In `src/wrap/continuation.rs`, in `emit_pending_prefix_segment`, after calling
`append_wrapped_with_prefix_width`, check for overflow; extend the fallback
mechanism to cover partial flushes during `ClosedAndReopened` handling; ensure
`original_lines` are sliced correctly when only part of the pending content is
flushed

Phase 3: Add Regression Tests

Add tests verifying the new preservation behaviour and ensuring existing wrapping logic remains correct.

Task 1: Add Test for Valid-Wrapped Union Type Preservation

Verify that previously-valid wrapped content is preserved when re-wrapping would overflow.

• Add test in tests/wrap/lists.rs with a bullet item containing a union type code span wrapped across two lines
• Assert that the output matches the input (lines preserved, not re-joined)
• Use the example from the ticket: Event = DocumentStart | HeaderEvent | ...

Task 2: Add Test for Unwrappable Long Code Span

Verify that genuinely unwrappable content is handled gracefully.

• Add test in tests/wrap/lists.rs with a bullet item containing a 100+ character inline code span
• Assert that the code span is emitted on its own line (not split)
• Assert that the test does not panic or corrupt the output (overflow is accepted)

Task 3: Add Test for Normal Wrapping Unaffected

Verify that standard paragraph wrapping still functions correctly.

• Add test in tests/wrap/paragraphs.rs with a long plain paragraph (no code spans)
• Assert that output lines are all ≤ 80 columns
• Assert that content is wrapped correctly, not preserved verbatim

Task 4: Add Snapshot Test for Union Type Preservation

Add an insta snapshot test for visual regression coverage.

• Create fixture file in tests/data/ with the union type example from the ticket
• Add snapshot test in tests/wrap/ using insta::assert_snapshot!
• Verify the snapshot shows preserved original line breaks

🤖 Prompt for AI agents

Add regression tests covering preservation behaviour, overflow handling, and
normal wrapping to ensure correctness.

- In `tests/wrap/lists.rs`, add a test with a bullet item containing a union
type code span (e.g., `Event = DocumentStart | HeaderEvent | ...`) wrapped
across two lines; assert that the output matches the input exactly (lines
preserved, not re-joined)
- In `tests/wrap/lists.rs`, add a test with a bullet item containing a 100+
character inline code span; assert that the code span is emitted on its own line
and that the test does not panic or corrupt the output (overflow is accepted
silently)
- In `tests/wrap/paragraphs.rs`, add a test with a long plain paragraph
containing no code spans; assert that all output lines are ≤ 80 columns and that
content is wrapped correctly, not preserved verbatim
- Create a fixture file in `tests/data/` with the union type example from the
ticket; add a snapshot test in `tests/wrap/` using `insta::assert_snapshot!`;
verify the snapshot shows preserved original line breaks

Research

The wrap system in src/wrap/ processes Markdown paragraphs by buffering source lines, joining them with spaces, and re-wrapping via wrap_preserving_code. Inline code spans are treated as atomic units that cannot be split. For prefixed lines (bullets, blockquotes, footnotes), PendingPrefix handles cross-line code spans by accumulating continuation text. The architecture currently discards original source-line boundaries before wrapping, making it impossible to fall back to valid originals when re-wrapping produces overflow.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Extend `ParagraphState` and `PendingPrefix` to store original source lines and
track input validity, then thread this data through the continuation mechanism.

- In `src/wrap/paragraph.rs`, add `original_lines: Vec<String>` and
`input_all_valid: bool` fields to `ParagraphState`; clear both in the existing
`clear()` method
- Update `ParagraphState::push()` to accept the full original line string;
measure each line's Unicode display width using `UnicodeWidthStr::width`; set
`input_all_valid = false` if any line exceeds the target width; store the
original line in `original_lines`
- In `src/wrap.rs`, update all call sites in the `wrap_text` main loop to pass
the full `line` string to `push()`
- In `src/wrap/paragraph.rs`, add `original_lines: Vec<String>` and
`input_all_valid: bool` fields to `PendingPrefix`; populate `original_lines`
with the first line when `PendingPrefix` is created in `handle_prefix_line`;
measure the first line's width and initialise `input_all_valid`
- In `src/wrap/continuation.rs`, modify the `apply_continuation_chunk` signature
to accept the original line string; append the original line to
`pending.original_lines`; measure the line's width and update
`pending.input_all_valid`
- In `src/wrap.rs`, update all call sites in `handle_pending_continuation` to
pass the full `line` string to `apply_continuation_chunk`
===============================================================================

Task: 2

Add a width measurement utility and implement overflow detection with fallback
emission across plain paragraphs, prefixed lines, and mid-continuation flushes.

- In `src/wrap/paragraph.rs`, add `fn line_exceeds_width(line: &str, width:
usize) -> bool` using `UnicodeWidthStr::width` for Unicode-correct measurement
- In `flush_paragraph` in `src/wrap/paragraph.rs`, after `wrap_preserving_code`
returns, use `line_exceeds_width` to check if any output line exceeds
`self.width`; if overflow is detected AND `state.input_all_valid` is true, emit
`state.original_lines` verbatim instead of the wrapped output, with no
additional prefix manipulation
- In `append_wrapped_with_prefix_width` in `src/wrap/paragraph.rs`, after
wrapping, check output line widths; add a fallback path that emits
`pending.original_lines` when overflow is detected and `pending.input_all_valid`
is true
- In `src/wrap/continuation.rs`, in `emit_pending_prefix_segment`, after calling
`append_wrapped_with_prefix_width`, check for overflow; extend the fallback
mechanism to cover partial flushes during `ClosedAndReopened` handling; ensure
`original_lines` are sliced correctly when only part of the pending content is
flushed
===============================================================================

Task: 3

Add regression tests covering preservation behaviour, overflow handling, and
normal wrapping to ensure correctness.

- In `tests/wrap/lists.rs`, add a test with a bullet item containing a union
type code span (e.g., `Event = DocumentStart | HeaderEvent | ...`) wrapped
across two lines; assert that the output matches the input exactly (lines
preserved, not re-joined)
- In `tests/wrap/lists.rs`, add a test with a bullet item containing a 100+
character inline code span; assert that the code span is emitted on its own line
and that the test does not panic or corrupt the output (overflow is accepted
silently)
- In `tests/wrap/paragraphs.rs`, add a test with a long plain paragraph
containing no code spans; assert that all output lines are ≤ 80 columns and that
content is wrapped correctly, not preserved verbatim
- Create a fixture file in `tests/data/` with the union type example from the
ticket; add a snapshot test in `tests/wrap/` using `insta::assert_snapshot!`;
verify the snapshot shows preserved original line breaks

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!