feat: regenerate expected heredocs via CANON_REGENERATE_EXPECTED: https://github.com/lutaml/canon/issues/146

[opoudjis]

Closes #146.

Summary

Adds opt-in mode CANON_REGENERATE_EXPECTED=true that rewrites the source heredoc backing a failing be_*_equivalent_to assertion with the prettyprinted received value. Default OFF; passing assertions are never touched; negated matchers (.not_to) are never rewritten.

Workflow:

CANON_REGENERATE_EXPECTED=true bundle exec rspec
git diff
git commit -am "rebaseline fixtures after upstream X change"

What's new

v1 supports:

• <<~XML / <<-XML / <<XML heredoc assigned to a local variable in the same it block.
• Multiple sequential assignments to the same variable (most-recent-before-expect-line semantics) — covers the common metanorma pattern of reassigning output between format-specific expects.
• Inline heredoc passed directly to the matcher.
• Substitution chains on the actual side (expect(strip_guid(actual).gsub(...))).

v1 skips with [canon:rebaseline] skipped_<reason> warning:

• Heredoc with #{} interpolation (v2 plans token-preserving merge).
• Expected from a method-call result (load_fixture(...)).
• Expected from let / shared_context in a different file.
• Inline string literal expected.

Line-shift handling. Multiple rewrites within one process correctly handle line numbering shifts between the in-memory source (which Ruby's caller_locations reports against) and the on-disk file (which the rebaseliner has changed). A per-file cumulative shift tracker translates each subsequent caller line into its current file position. Tested via the multi-assignment fixture.

Implementation

New module Canon::Rebaseliner under lib/canon/rebaseliner/:

• AtomicWriter — tempfile + rename, cross-device safe.
• Logger — single-line stderr writes with [canon:rebaseline] prefix.
• HeredocSpec — struct describing a heredoc's byte range and style.
• HeredocRewriter — re-indents <<~ bodies, writes verbatim for <<- / <<.
• HeredocLocator — Prism-based AST walk; "most-recent assignment" semantics for local-var references.
• CallSiteResolver — Prism parse, finds the matcher call and its enclosing it block.
• Rebaseliner (orchestrator) — enabled?, rewrite!, line-shift tracker.

Matcher hook in lib/canon/rspec_matchers.rb. Env-var schema registered in lib/canon/config/env_schema.rb for --env-help discoverability. caller_locations is only captured when the env var is set, so passing assertions pay no overhead.

prism added as a runtime dependency (stdlib in Ruby 3.3+; thin gem on 2.7-3.2).

Tests

10 new fixture cases under spec/fixtures/rebaseliner/:

• Squiggly heredoc rewrite + idempotent re-run.
• Multi-assignment-in-same-it-block rewrite.
• Inline heredoc rewrite.
• Interpolation skip (file unchanged).
• Inline-string skip (file unchanged).
• Negated matcher no-op (file unchanged).

Plus unit tests on Rebaseliner.enabled? env-var truthiness.

Full canon suite: 2222 examples, 0 failures, 1 pending (no regressions).

Internal documentation

docs/features/regenerate-expected.adoc covers architecture, supported forms, line-shift handling, limitations, and v2 roadmap. README updated to link.

v2 (separate PR)

Per discussion on #146:

• Interpolation support via token preservation (re-anchor #{var} fragments in the prettyprinted actual).
• JSON / YAML format prettyprinter wiring.
• canon regenerate SPEC_GLOB Thor subcommand.
• File-locking for parallel_rspec safety.
• Optional rubocop -A post-rewrite formatter.

Test plan

• Canon's own suite passes (2222/0/1 pending).
• All 10 rebaseliner fixture cases pass.
• End-to-end against metanorma-iso pinned to this branch (left as a downstream test by the requester — canon-internal coverage is comprehensive).

🤖 Generated with Claude Code