refactor(footnotes): unify blockquote-marker stripping into one canonical helper

[lodyai]

Background

Blockquote-marker stripping — repeatedly peeling leading > characters and the
whitespace between them — is currently reimplemented in at least three places
with subtly different code:

• src/footnotes/renumber.rs:71-74 (is_fence_line) —
  while let Some(rest) = trimmed.strip_prefix('>') { trimmed = rest.trim_start(); }
• src/footnotes/lists.rs:62-65 (has_existing_footnote_block) — the same loop
  over a differently named binding.
• src/footnotes/renumber.rs:42-54 (matches_definition_prefix) — the same idea
  expressed as a loop with explicit trim_start_matches(char::is_whitespace) and
  an emptiness check.

Problem

Three hand-rolled variants of one concept invite drift: a fix to nested-marker
handling (> > ) or whitespace rules in one site silently leaves the others
behind, and each copy adds cognitive load to the footnotes pipeline. This is a
tactical DRY defect; the broader semantic rework of blockquotes is tracked
separately in #347, but the duplication should be removed regardless.

Objective

Converge on a single canonical implementation and route every call site
through it.

• Add fn strip_blockquote_markers(s: &str) -> &str at the footnotes module
  root (src/footnotes/mod.rs), returning the input with all leading
  blockquote markers and their surrounding whitespace removed.
• Rewrite is_fence_line and has_existing_footnote_block to call it.
• Rewrite matches_definition_prefix as
  strip_blockquote_markers(prefix).is_empty().

Required approach

This refactor must converge on one canonical helper and be verified, per the
project's DRY and testing conventions:

1. One canonical function. Exactly one strip_blockquote_markers
   definition; remove all duplicate loops and route every caller through it.
2. Document it. Add an entry to docs/developers-guide.md (Internal API
   reference) naming strip_blockquote_markers, stating its contract (idempotent;
   strips arbitrary-depth > markers and interleaved whitespace) and the rule
   that new blockquote-prefix code must reuse it rather than re-deriving the loop.
3. Property tests. Add proptest coverage (existing dev-dependency)
   asserting invariants such as: idempotence
   (strip(strip(s)) == strip(s)); the result never starts with >; for an
   input built from n markers plus a known suffix, the suffix is returned
   unchanged.
4. Model checking (if applicable). The input domain is unbounded UTF-8
   strings, so bounded model checking adds little over property tests; record
   this rationale in the PR rather than adding a Kani harness.
5. Snapshot assertions. Add insta snapshot tests (existing dev-dependency)
   pinning end-to-end footnote renumbering/list-detection output for
   representative single- and nested-blockquote inputs.

All existing tests must pass; run the full make commit gate before merging.

References

• Related semantic rework: Treat block quotes semantically rather than via ad-hoc regexp special-casing #347
• Requested by @leynos

[coderabbitai]

🔗 Related PRs

#273 - Refactor attach_orphan_specifiers; add attach_to_next_fence helper [merged]
#275 - Preserve nested fenced blocks (#262) [merged]
#280 - Keep GFM footnote references atomic (#277) [merged]
#301 - Keep GFM footnote references with preceding code and link spans (#299) [merged]
#343 - Preserve fenced code block contents during wrapping (#329) [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

• Introduce a single strip_blockquote_markers helper in src/footnotes/mod.rs with pub(crate) visibility.
• Refactor all three existing call sites (is_fence_line, matches_definition_prefix, has_existing_footnote_block) to delegate to the helper, eliminating duplicated logic.
• Add proptest property tests for idempotence, no-leading-marker, and suffix-preservation invariants.
• Add insta snapshot tests pinning end-to-end behaviour for single- and nested-blockquote footnote processing.

Implementation Steps

Phase 1: Canonical Helper and Call-Site Refactor

Introduce the single source of truth for blockquote-marker stripping and route every existing call site through it, then document the contract in the developers' guide.

Task 1: Create `strip_blockquote_markers` Helper

Implement the canonical function and expose it to sibling submodules.

• Add pub(crate) fn strip_blockquote_markers(s: &str) -> &str to src/footnotes/mod.rs
• Use an iterative loop: trim leading whitespace, attempt strip_prefix('>'), repeat until neither applies
• Return the remainder slice (a no-copy borrow of the input)
• Mark visibility as pub(crate) so renumber.rs and lists.rs can import it directly

Task 2: Refactor `renumber.rs` Call Sites

Replace the two inline loops with calls to the new helper.

• In src/footnotes/renumber.rs, import super::strip_blockquote_markers
• Rewrite is_fence_line: call strip_blockquote_markers(line) then check for ``` or ~~~ prefix
• Rewrite matches_definition_prefix: replace the entire function body with strip_blockquote_markers(prefix).is_empty()

Task 3: Refactor `lists.rs` Call Site

Replace the inline loop in has_existing_footnote_block.

• In src/footnotes/lists.rs, import super::strip_blockquote_markers
• Within has_existing_footnote_block, replace the manual while let stripping loop with a single call to strip_blockquote_markers(l)

Task 4: Document Helper in Internal API Reference

Add the required documentation entry.

• In docs/developers-guide.md, under ## Internal API reference, add a new file-path heading for src/footnotes/mod.rs
• Add a bullet describing strip_blockquote_markers(s: &str) -> &str: state that it is idempotent, strips arbitrary-depth > markers and interleaved whitespace, and mandate that new blockquote-prefix code must reuse it rather than re-derive the loop

🤖 Prompt for AI agents

Introduce the `strip_blockquote_markers` helper in `src/footnotes/mod.rs` and
refactor all three call sites to use it, then document the helper in
`docs/developers-guide.md`.

**`src/footnotes/mod.rs`**
- Add `pub(crate) fn strip_blockquote_markers(s: &str) -> &str`
- Implement an iterative loop: trim leading whitespace, attempt
`strip_prefix('>')`, repeat until neither operation applies
- Return the remainder slice as a no-copy borrow of the input

**`src/footnotes/renumber.rs`**
- Import `super::strip_blockquote_markers`
- Rewrite `is_fence_line`: call `strip_blockquote_markers(line)`, then check the
result for a ` ``` ` or `~~~` prefix
- Rewrite `matches_definition_prefix`: replace the entire function body with
`strip_blockquote_markers(prefix).is_empty()`

**`src/footnotes/lists.rs`**
- Import `super::strip_blockquote_markers`
- In `has_existing_footnote_block`, replace the manual `while let` stripping
loop with a single call to `strip_blockquote_markers(l)`

**`docs/developers-guide.md`**
- Under `## Internal API reference`, add a new file-path heading for
`src/footnotes/mod.rs`
- Add a bullet entry for `strip_blockquote_markers(s: &str) -> &str` stating it
is idempotent, strips arbitrary-depth `>` markers and interleaved whitespace,
and that new blockquote-prefix code must reuse it rather than re-derive the loop

Phase 2: Test Coverage

Add property tests and snapshot tests to lock in behaviour and guard against regressions.

Task 1: Add Proptest Coverage

Create property tests asserting the helper's invariants.

• Create tests/footnote_properties.rs following the project's proptest! block pattern
• Define a strategy helper blockquote_prefix_strategy() generating strings of > characters and varied whitespace
• Define a strategy helper arbitrary_suffix_strategy() generating arbitrary non-> text
• Add property: idempotence — strip(strip(s)) == strip(s) for any input
• Add property: no leading marker — result never starts with >
• Add property: suffix preservation — for an input built as prefix + suffix where prefix is pure markers/whitespace, the result equals suffix
• Register the new test file in the workspace test harness (Cargo auto-discovers it)

Task 2: Add Insta Snapshot Tests

Pin end-to-end footnote renumbering and list-detection output for blockquote inputs.

• Extend tests/footnotes.rs (or create tests/footnotes_snapshots.rs if separation aids clarity)
• Define assert_footnotes_snapshot helper using insta::with_settings! with snapshot_path => "../snapshots" and prepend_module_to_snapshot => false
• Add snapshot cases covering:
  • Single-level blockquote containing footnote definitions (> [^1]: ...)
  • Nested blockquote (> > [^1]: ...)
  • Mixed blockquote depths in the same document
  • Blockquoted fenced code block containing footnote-like text (should remain unchanged)
• Commit generated .snap files under tests/snapshots/

🤖 Prompt for AI agents

Add property tests and insta snapshot tests to lock in the behaviour of
`strip_blockquote_markers` and guard against regressions in end-to-end footnote
processing.

**`tests/footnote_properties.rs`** (new file)
- Follow the project's `proptest!` block pattern
- Define a strategy helper `blockquote_prefix_strategy()` that generates strings
of `>` characters and varied whitespace
- Define a strategy helper `arbitrary_suffix_strategy()` that generates
arbitrary non-`>` text
- Add three property tests:
  - **Idempotence**: `strip(strip(s)) == strip(s)` for any input
  - **No leading marker**: the result never starts with `>`
- **Suffix preservation**: for an input constructed as `prefix + suffix` where
`prefix` is pure markers/whitespace, the result equals `suffix`
- Cargo auto-discovers the file; no manual registration is required

**`tests/footnotes.rs`** (extend) or **`tests/footnotes_snapshots.rs`** (new, if
separation aids clarity)
- Define an `assert_footnotes_snapshot` helper using `insta::with_settings!`
with `snapshot_path => "../snapshots"` and `prepend_module_to_snapshot => false`
- Add snapshot cases covering:
  - Single-level blockquote with footnote definitions (`> [^1]: ...`)
  - Nested blockquote (`> > [^1]: ...`)
  - Mixed blockquote depths in the same document
- Blockquoted fenced code block containing footnote-like text (must remain
unchanged)
- Commit the generated `.snap` files under `tests/snapshots/`

Research

The footnotes module (src/footnotes/) has a private submodule structure with mod.rs as the sole public entry point. Three files contain near-identical loops stripping > prefixes and interleaved whitespace: renumber.rs (two sites: is_fence_line and matches_definition_prefix) and lists.rs (one site: has_existing_footnote_block). Testing conventions use proptest! blocks with free-function strategy helpers in tests/ and insta snapshots under tests/snapshots/ with a standardised with_settings! helper pattern. Documentation of internal helpers lives in the ## Internal API reference section of docs/developers-guide.md, formatted as bullet lists under backtick-quoted file paths.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Introduce the `strip_blockquote_markers` helper in `src/footnotes/mod.rs` and
refactor all three call sites to use it, then document the helper in
`docs/developers-guide.md`.

**`src/footnotes/mod.rs`**
- Add `pub(crate) fn strip_blockquote_markers(s: &str) -> &str`
- Implement an iterative loop: trim leading whitespace, attempt
`strip_prefix('>')`, repeat until neither operation applies
- Return the remainder slice as a no-copy borrow of the input

**`src/footnotes/renumber.rs`**
- Import `super::strip_blockquote_markers`
- Rewrite `is_fence_line`: call `strip_blockquote_markers(line)`, then check the
result for a ` ``` ` or `~~~` prefix
- Rewrite `matches_definition_prefix`: replace the entire function body with
`strip_blockquote_markers(prefix).is_empty()`

**`src/footnotes/lists.rs`**
- Import `super::strip_blockquote_markers`
- In `has_existing_footnote_block`, replace the manual `while let` stripping
loop with a single call to `strip_blockquote_markers(l)`

**`docs/developers-guide.md`**
- Under `## Internal API reference`, add a new file-path heading for
`src/footnotes/mod.rs`
- Add a bullet entry for `strip_blockquote_markers(s: &str) -> &str` stating it
is idempotent, strips arbitrary-depth `>` markers and interleaved whitespace,
and that new blockquote-prefix code must reuse it rather than re-derive the loop
===============================================================================

Task: 2

Add property tests and insta snapshot tests to lock in the behaviour of
`strip_blockquote_markers` and guard against regressions in end-to-end footnote
processing.

**`tests/footnote_properties.rs`** (new file)
- Follow the project's `proptest!` block pattern
- Define a strategy helper `blockquote_prefix_strategy()` that generates strings
of `>` characters and varied whitespace
- Define a strategy helper `arbitrary_suffix_strategy()` that generates
arbitrary non-`>` text
- Add three property tests:
  - **Idempotence**: `strip(strip(s)) == strip(s)` for any input
  - **No leading marker**: the result never starts with `>`
- **Suffix preservation**: for an input constructed as `prefix + suffix` where
`prefix` is pure markers/whitespace, the result equals `suffix`
- Cargo auto-discovers the file; no manual registration is required

**`tests/footnotes.rs`** (extend) or **`tests/footnotes_snapshots.rs`** (new, if
separation aids clarity)
- Define an `assert_footnotes_snapshot` helper using `insta::with_settings!`
with `snapshot_path => "../snapshots"` and `prepend_module_to_snapshot => false`
- Add snapshot cases covering:
  - Single-level blockquote with footnote definitions (`> [^1]: ...`)
  - Nested blockquote (`> > [^1]: ...`)
  - Mixed blockquote depths in the same document
- Blockquoted fenced code block containing footnote-like text (must remain
unchanged)
- Commit the generated `.snap` files under `tests/snapshots/`

💡 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!