Summary

• Add immutable, JSON-serializable compatibility reports for files and strings.
• Check raw-source coverage, explicit parse failures, ordered semantic round trips, canonical stability, output encoding, and informational exact byte identity.
• Add bibtexparser check FILE and python -m bibtexparser check FILE with text/JSON output and distinct exit statuses.
• Offer a privacy-safe issue draft by default and a separately warned, opt-in source-bearing draft when an exact bounded reproduction is available.
• Reject source-bearing drafts if the file changed after the compatibility report was produced.

Closes #596.

Scope and commit structure

This additive feature is deliberately split into six commits: core report API, CLI, initial documentation, opt-in reproduction extraction, disclosure documentation, and stale-file protection. Normal parsing and writing behavior is unchanged; the extra parse/write cycles only occur when the preflight is explicitly invoked.

The branch starts directly at upstream main and does not require the other open parser, writer, failed-block-policy, Biber-comment, or round-trip-contract PRs. In particular, malformed brace-delimited input is used for failure fixtures so this PR does not depend on #571.

PR #595 currently has a test-local semantic signature. If both proposals proceed, it should be rebased to use the production inventory introduced here so the runtime checker and regression contract have one implementation; that integration is not hidden in this standalone branch.

Privacy and limits

The default issue URL contains no path or bibliography source and performs no network request. Source inclusion requires --include-source-in-issue-link, prints an explicit warning, refuses truncation and overlong URLs, uses a safe Markdown fence, and verifies the reread file hash before constructing the draft.

A passing report means the named checks passed with this parser version. It is not formal verification or an independent oracle for interpretation correctness.

Validation

• pytest -p no:cacheprovider -W error tests/test_compatibility.py tests/test_cli.py: 19 passed.
• Complete upstream suite: 2,595 passed, 12 skipped, with four existing deprecation warnings in tests/test_entrypoint.py.
• Complete pre-commit hook suite: passed.
• The full suite under -W error reaches only the same four pre-existing warning assertions addressed separately by draft PR Capture expected deprecation warnings in entry-point tests #582.

AI assistance and review note

This pull request was prepared with ChatGPT Codex using GPT-5.6 Sol with high reasoning effort. Codex assisted with contract design, implementation, dependency reduction, privacy review, fixture adaptation, and validation. The work was developed in a concentrated session and has not been field-tested over a long period; automated validation is not a substitute for careful maintainer review.