Add read-only compatibility preflight#597
Draft
claell wants to merge 6 commits into
Draft
Conversation
* Check raw-source coverage, explicit failures, semantic round trips, canonical stability, and output encoding. * Distinguish permitted formatting changes from exact source byte identity. * Keep the checker independent of other open changes.
* Add text and JSON reports with distinct compatible, incompatible, and I/O exit statuses. * Offer privacy-safe, reviewable issue drafts without submitting or exposing bibliography content. * Report exact source bytes separately from semantic compatibility.
* Explain the named checks, exit statuses, and exact-byte distinction. * Describe the privacy-safe issue draft and the limits of same-parser validation.
* Extract bounded exact failed blocks without arbitrary truncation. * Keep source-bearing drafts separate from the privacy-safe default link. * Warn that source URLs may persist in logs, browser history, and GitHub drafts.
* Explain the explicit disclosure option and its privacy risks. * Describe bounded failed-block and duplicate-key reproductions without truncation.
* Verify reread bytes against the checked source hash before embedding a failed block. * Refuse source-bearing drafts when the file changes or cannot be reread.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
bibtexparser check FILEandpython -m bibtexparser check FILEwith text/JSON output and distinct exit statuses.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
mainand 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.tests/test_entrypoint.py.-W errorreaches 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.