Add markdown golden-snapshot test harness for engine migration

[jaredwray]

Why

We're preparing to migrate writr's markdown engine from JS (unified/remark/rehype) to native Rust. That migration is only safe if we can prove the new engine produces the same HTML as today's engine across a large, diverse body of real markdown. The repo previously had ~25 ad-hoc fixtures and no snapshot testing — not enough to catch regressions across the 12 markdown features writr supports.

This PR adds a golden-snapshot harness: the current JS engine's output is the source of truth. We fetch a diverse corpus, render every example with today's engine, and commit the HTML as goldens. A future Rust engine plugs in behind the same adapter interface and must reproduce the goldens (with a reviewed allowlist for intentional diffs).

What's included

• Corpus fetcher (test/harness/fetch/) — reproducible, pinned public sources: CommonMark spec, GFM spec, markdown-it fixtures, every public github.com/jaredwray/* repo (they all consume writr), and permissively-licensed docs. Raw payloads are cached and committed for offline replay. 1000 unique documents (incl. 339 from all jaredwray repos), each with provenance (source, license, attribution, sha256) in corpus/manifest.json.
• Render profiles (profiles.ts) — default, commonmark, gfm-only, no-highlight, no-math, rawhtml, mdx. Failures isolate to a feature, and no-highlight/no-math let the Rust engine pass core contracts before achieving highlight.js/KaTeX parity. CommonMark/GFM examples also render under rawhtml so raw-HTML inputs (correctly stripped to empty under the default rawHtml:false) still get a non-empty golden pinning the passthrough.
• Per-feature diagnostic suites (diagnostics/) — hand-authored tiny examples for every plugin (gfm tables/alerts/tasklists/strikethrough/autolinks, emoji, toc, slug, highlight, math, mdx, raw html, frontmatter, commonmark core) so a failure pinpoints the exact feature.
• Pluggable RenderAdapter — current engine is WritrJsAdapter; a future WritrRustAdapter is selected via HARNESS_ENGINE and checked against the same JS-generated goldens. allowlist.json (engine-keyed) records reviewed intentional divergences.
• Golden generator — forces caching:false, asserts renderSync == render, surfaces genuine engine errors via Writr's emitted error event (a legitimately-empty render is a valid golden), and records resolved plugin versions in versions.json for drift auditing.
• Vitest runner — reports first-divergence index/line/col with context instead of a giant diff.

Results

• 2041 goldens generated, 2041 harness tests pass, zero render errors across the full corpus.
• golden:check is clean (no drift); pnpm build and pnpm test are unaffected (100% coverage) — the harness is excluded from the default run via vitest.harness.config.ts + a vitest.config.ts exclude, mirroring the existing integration-test pattern.

New scripts

pnpm corpus:fetch          # fetch/refresh the corpus (online; caches raw payloads)
pnpm corpus:fetch:offline  # rebuild from committed cache only (no network)
pnpm golden:generate       # render corpus + diagnostics, write goldens + versions.json
pnpm golden:check          # CI gate: verify goldens still match the current engine
pnpm test:harness          # run the Vitest runner against committed goldens

Notes

• The corpus is exactly 1000 unique documents (the cap). The stratified round-robin prioritises the jaredwray consumer markdown; CommonMark/GFM/markdown-it are overlapping spec suites, so global dedupe collapses byte-identical examples rather than padding with near-duplicates.
• No credentials are committed: cached API payloads are public repo metadata and the manifest stores only raw CDN URLs (verified). The ghp_ strings present in the corpus are ghp_yourtoken placeholders inside jaredwray's own token documentation.
• See test/harness/README.md for the full workflow and how to wire the Rust adapter (HARNESS_ENGINE=writr-rust).

https://claude.ai/code/session_01Rj1dsi6MW36qudnPKE2Zx9

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (b159168) to head (91d440d).

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #467   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            5         5           
  Lines          518       518           
  Branches       144       144           
=========================================
  Hits           518       518           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive Markdown Golden-Snapshot Harness designed to ensure HTML output consistency across different markdown engines (specifically for an upcoming JS to Rust migration). It adds new package scripts, a detailed README, allowlist management, corpus loading utilities, and a large set of CommonMark spec markdown files to serve as the regression test corpus. There are no review comments to address, so no feedback is provided.

[aikido-pr-checks]

Exposed secret in test/harness/corpus/inputs/jaredwray/0148.md - low severity
Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

_{Reply @AikidoSec ignore: [REASON] to ignore this issue.
More Info}

[jaredwray]

@AikidoSec ignore: False positive. This is a test corpus fixture — markdown faithfully fetched from a public jaredwray repo for the golden-snapshot harness. Line 126 is a documentation placeholder inside a fenced code block (GOOGLE_CLOUD_TASK_API_TOKEN=12345678987654321), not a real credential.

---

Generated by Claude Code

[aikido-pr-checks]

✅ Based on your feedback, we ignored this issue because of the following reason:

False positive. This is a test corpus fixture — markdown faithfully fetched from a public jaredwray repo for the golden-snapshot harness. Line 126 is a documentation placeholder inside a fenced code block (GOOGLE_CLOUD_TASK_API_TOKEN=12345678987654321), not a real credential.

---

Generated by Claude Code