v23.0.0

Beware that this is basically an SI rewrite, which I reviewed from an API perspective.
It should be way more correct than the previous version, at least tests would
say so.

Reason: I wanted to prevent piece-meal SI-PRs to fix individual aspects of the prior
version, which was pretty sub-par in the correctness department.

New Features (BREAKING)

• require parser options and validate round-trip configurations

  Checked public API, rest is mostly rubber-stamped

  Make the originating parser flags mandatory in State::new and every cmark
  helper so escaping and source validation agree with the parser. Remove
  State::default(), default to symbolic superscripts/subscripts, and add
  optional, recommended Options::validate. Support all subsets of twelve modern
  extensions with standard markers: 491,520 finite configurations are accepted
  and 5,799,936 are explicitly rejected.

  Preserve mandatory list and definition boundaries, nested delimiter runs,
  math/table interactions, and raw blocks ending at EOF or by dedentation.
  Validate delimiter choices before emitting them and report unrepresentable
  blocks instead of silently changing events. Preserve list structure that
  relied on invisible definitions by reserving a collision-free label; these
  exceptional lists buffer the remaining input until finish.

  Keep accumulated reference occurrences and labels out of block-rendering
  snapshots. Criterion benchmarks cover shared, distinct, edited, and nested
  references at 1,000–8,000 paragraphs and show proportional scaling.

  Add permanent differential tests with exact merged-event comparisons across
  both rendering paths, 860 retained regressions, 91,446 generated inputs,
  symbolic extension combinations, numeric preferences, and every accepted
  configuration. Run the exhaustive release suite in CI. Document migration,
  validation, coverage counts, and commands that print the results.

• round-trip the full CommonMark 0.31.2 spec

  Rubber-stamp mostly, and nearly 1000 SLOC less seem to speak a clear language.
  I at least validated the public API which seemed sensible.
  The new API is definitely nicer, the tests are cleaned up.

  All 652 CommonMark 0.31.2 examples now round-trip with their parsed
  structure intact under default formatting. This includes paragraph
  boundaries, tight and loose lists, link types, and indented versus fenced
  code blocks. Strict event comparisons cover ordinary and source-range
  serialization, every event boundary, and event-by-event input.

  Markdown decisions often need context that arrives later: a later list
  item can make the entire list loose, and the following block affects how
  the list must end. The serializer now retains one top-level block until
  that context is available. It can therefore keep adjacent lists distinct,
  keep following code outside a list, and choose valid heading, emphasis,
  fence, and reference syntax. Consistent newline and container handling
  also preserves tight HTML lists and loose definitions without introducing
  extra block quotes.

  The new opaque State owns its options and retained input, so borrowed
  event chunks and source strings need not outlive a processing call.
  process and process_with_source_range accept all supplied events on
  success and report consumed events and written UTF-8 bytes through
  Progress. Output uses fmt::Write and may be buffered. finish flushes
  the last block and reference definitions; repeated successful calls write
  nothing. Invalid ranges and unbalanced events are reported as errors,
  and a failed state cannot be reused.

  Source ranges preserve original spelling only when it reparses to the
  supplied events. Edited text uses safe escaping, and edited shortcut
  labels can become explicit references to retain their original targets.

Test

• print CommonMark conformance totals

  Print passed example totals for ordinary/source-range and incremental
  serialization so cargo test --test integrate spec:: -- --nocapture shows
  the number of CommonMark examples covered. Check the expected fixture
  count when running the incremental test on its own as well.

• update CommonMark fixtures to 0.31.2

  Vendor the latest published specification and record its source and
  checksum. Decode the spec's tab markers and retain final newlines when
  extracting examples, matching the official JSON inputs and HTML.

  The corrected 652-example corpus currently passes 622 round trips.
  Add a focused regression for fixture extraction.

Documentation

• explain migration to the owning State API Document replacements for resume functions, owned input and configuration,
  progress counts, block buffering, source spelling, terminal errors, and
  idempotent finishing. Describe the strict CommonMark 0.31.2 coverage and
  formatting changes, update fence-count documentation, and add compiled
  incremental and source-range examples.

Changed

• Breaking: require the originating parser flags in State::new and all
  cmark* helpers. Remove State::default() and default to symbolic superscript
  and subscript output so reparsing retains their event types.
• Add optional, recommended Options::validate and SUPPORTED_PARSER_OPTIONS.
  Support every subset of twelve modern parser extensions and standard Markdown
  markers; reject unsupported flags, invalid markers, overflowing lengths, and
  HTML output conflicting with symbolic scripts. The finite matrix accepts
  491,520 configurations and rejects 5,799,936.
• Preserve required list and definition boundaries, delimiter run nesting,
  extension-sensitive punctuation, and raw blocks ending at EOF. Retain list
  structure created by invisible reference definitions with collision-free labels.
• Validate source blocks using only their own reference definitions, keeping
  document-wide reference history out of trial rendering. Add Criterion scaling
  benchmarks for shared, distinct, edited, and nested reference-link workloads.
• Add strict differential tests for all accepted configurations, every CommonMark
  example across standard formatting choices, retained review regressions, and a
  deterministic generated corpus under six parser profiles. Run the full suite
  in CI and document commands that print coverage and failure totals.
• Breaking: replace cmark_resume* and the public State fields with an
  owning State::new, process, process_with_source_range, and finish API.
  Successful calls return event and UTF-8 byte counts. Finishing is idempotent;
  errors make the state unusable. See the migration guide.
• Preserve merged parser events for all 652 CommonMark 0.31.2 examples, including
  source-range serialization and arbitrary event splits. Correct fixture tab
  notation and final newlines, and replace the partial pass-count allowance
  with strict assertions.
• Buffer blocks to choose list spacing and boundaries, heading and emphasis
  delimiters, code fences, and reference labels. Centralize newline and prefix
  handling, retaining tight HTML lists and loose definition spacing.

Commit Statistics

• 8 commits contributed to the release.
• 1 day passed between releases.
• 5 commits were understood as conventional.
• 0 issues like '(#ID)' were seen in commit messages

Commit Details

view details

• Uncategorized
  • Prepare changelog prior to release (c2772f5)
  • Merge pull request #114 from Byron/more-fixes (b69f3ea)
  • Require parser options and validate round-trip configurations (a077980)
  • Merge pull request #113 from Byron/more-fixes (96eebbd)
  • Print CommonMark conformance totals (c4d4f28)
  • Explain migration to the owning State API (e173adb)
  • Round-trip the full CommonMark 0.31.2 spec (c8d9190)
  • Update CommonMark fixtures to 0.31.2 (f16d71b)