refactor(converter): replace regex-based markdown→storage with htmlparser2 walker

[devlimits]

Background

Companion PR to #137 in the opposite direction. This work was paused as the refactor is fairly large in scope and I wanted to align on the architectural direction. After #137 landed and confirmed the choice (htmlparser2 + DOM walker), this PR resumes that effort, applying the same approach to the reverse path.

Description

The mirror of #137 in the opposite direction. Replaces the 173-line
regex pipeline in htmlToConfluenceStorage (and through it,
markdownToStorage / markdownToNativeStorage) with an htmlparser2
DOM walker.

The previous regex pipeline had the same structural fragility #137
documented for storageToMarkdown:

• Nested <blockquote>(.*?)</blockquote> could not track depth across
  nested macros, so > > **INFO** lost its outer closing tag.
• CDATA literals containing <blockquote> confused the blockquote
  regex from inside code blocks.
• The [!info] admonition rewrite had to anchor itself defensively
  because it ran on raw markdown text (fix: scope [!info] admonition rewrite to block context #134).
• Marker detection was tightly coupled to markdown-it's exact
  paragraph serialization shape.

Recent fix commits in this area (#132, #134, #136) were all workarounds
for that structural fragility.

Type of Change

• Code refactoring
• Performance improvement (single parse pass replaces 10+ regex
  passes over the same string)

What changed

File	Change
lib/html-to-storage.js (new)	DOM walker with handlers for headings, paragraphs, inline formatting, lists (with <p>-wrap quirk on tight items), code blocks (CDATA + language + ]]> split) and inline code, links (smart/plain/wiki + anchor #id branch), tables, blockquote with INFO/WARNING/NOTE marker detection, TOC/ANCHOR/EXPAND paragraph markers, and void tags. Parser uses decodeEntities: false so text and attribute entities round-trip byte-identical. Recursion is capped at 256 levels via a typed HtmlDepthExceededError.
lib/macro-converter.js	htmlToConfluenceStorage shrinks 173 → 2 lines, delegating to htmlToStorage. markdownToStorage and markdownToNativeStorage route through it, so all three methods share the walker backend.
tests/html-to-storage.test.js (new)	55 unit tests covering each handler in isolation, including depth-guard guarantees (1000-deep throws, 50-deep succeeds).
tests/macro-converter.test.js	+5 nested-blockquote regression tests (the original > > **INFO** unbalance bug plus three-level nesting and sibling blockquotes), +4 integration smoke tests (CDATA-adjacent-marker, public htmlToConfluenceStorage path, task-list literal-text behavior, table-cell <p> wrap).

Testing

• 548/548 tests pass locally; lint clean.
• Existing macro-converter tests act as the public-API regression net,
  mirroring refactor(converter): replace regex-based storageToMarkdown with htmlparser2 walker #137's testing approach.
• New walker unit tests cover handler-level behavior independently of
  markdown-it's serialization shape, including the depth guard.

Test Suites: 13 passed, 13 total
Tests:       548 passed, 548 total

Local validation during development

Beyond the committed test suite, walker development used a 19-case
golden fixture A/B diff harness (16 markdown + 3 HTML, covering all
handler categories — headings, blockquote markers and nesting,
admonitions, CDATA-with-HTML, TOC / ANCHOR / EXPAND, tables, link
styles ×3, task lists, deeply nested lists, mixed content, inline
edges) and reached byte parity 0/19 between the V1 entry point and a
direct walker call.

The fixture infrastructure was removed from this PR following #137's
"existing tests act as regression net" approach; the four new
integration smoke tests in tests/macro-converter.test.js cover the
corners not transitively covered by existing tests.

What is intentionally not changed

The markdown-it preprocessor that rewrites the [!info] shorthand into
the canonical > **INFO** blockquote form (added in #134) stays in
place. It operates on markdown source where line-break information is
needed to support both the [!info]\nbody newline form and the
single-line [!info] body form. Migrating it to the tree level would
lose the single-line form's body delimiter and silently break
backwards compatibility.

Behavioral Notes

For raw-HTML input via --input-format html, the walker's <p>-wrap
behavior on <li> / <th> / <td> differs from the previous regex
pipeline in a few edge cases. The walker decides via inline-tag
membership + newline absence rather than the previous "single-line
regex match" rule:

• Improvement (most cases): A single-line <li><p>existing</p></li>
  (loose-list canonical form, common in Confluence storage round-trips)
  no longer gets double-wrapped to <li><p><p>existing</p></p></li>.
  The previous regex captured the existing <p> and re-wrapped it; the
  walker recognizes <p> as a block child and skips wrap.
• Silent divergence (rare): An <li> containing only HTML5 phrasing
  elements not covered by the walker's INLINE_TAGS set (e.g.
  <meter>, <output>) won't get the <p> wrap the regex would have
  applied. markdown-it doesn't emit these so the markdown→storage path
  is unaffected; only hand-authored raw HTML triggers it.

HTML comments (<!-- ... -->) in raw HTML input are dropped during
conversion rather than preserved in the output payload. This diverges
from the previous regex pipeline (which left them untouched), but
Confluence's storage layer strips HTML comments server-side regardless,
so the rendered page is unchanged.

Extra <a> attributes (title, class, etc.) on raw-HTML input are
dropped in wiki linkStyle output (only href is preserved via
<ri:url ri:value>). The previous regex pipeline matched only the
exact <a href="..."> shape and passed any decorated <a> through
unchanged. Affects only Server/DC users explicitly choosing wiki —
Cloud's storage format does not render the wiki form at all (shown as
"unsupported macro" in the editor), so Cloud defaults to smart.

The dominant markdown-it path is byte-identical to the previous regex
pipeline. The CLI --input-format html and --format html paths
continue to work, now backed by the same walker. The [!info]
shorthand path is unchanged from the user's perspective.

Checklist

• My code follows the style guidelines of this project (lint clean)
• I have performed a self-review of my own code
• My changes generate no new warnings

[pchuri]

Thanks for putting this together — LGTM 🚀

As the mirror of #137, this applies the same htmlparser2-based walker approach consistently to the storage direction. Beyond the refactor, it also fixes some real V1 bugs along the way (nested-blockquote unbalance, malformed XML on multi-attribute links, etc.).

What I particularly liked:

• 55 isolated handler-level unit tests + 9 integration regression tests, with all 548 tests green
• HtmlDepthExceededError guards against stack overflow on pathological input
• The trust boundary in escapeAttrValue is clearly documented in comments
• Intentional V1-parity decisions (e.g. non-normalized <br>/<img>, EXPAND non-greedy pairing) have their reasoning written down inline, which makes future spelunking much easier

A few small follow-ups (non-blocking):

1. <ul> / <ol> are missing renderAttrs, so attributes like class are dropped. For consistency with the <table> family, a one-line addition would be worth considering.
2. HTML comments are silently dropped in raw-HTML input. If intentional, a line in the PR's "Behavioral Notes" section would be helpful.
3. On wiki linkStyle conversion, extra <a> attributes (title, etc.) are lost. Confluence wouldn't accept them anyway, but explicit documentation would still be nice.

Happy to handle these in a follow-up PR or separate issue. Great work — appreciate the careful approach!

[github-actions]

🎉 This PR is included in version 2.1.9 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[devlimits]

Thanks for the careful review!

Items 2 & 3: Verified the actual behavior on Confluence and added Behavioral Notes accordingly.
Item 1: Fixing in a follow-up PR.