Motivation
Users may have long-lived or unusual .bib files that no finite fixture suite covers. Given past silent-loss cases, a user should be able to ask whether the installed parser's default public path appears safe for a specific file before trusting it with edits.
This cannot prove that the parser interpreted every construct correctly: parsing and reparsing with the same implementation is not an independent oracle. It can still detect important failure classes and provide a concrete, read-only confidence report.
Proposed API
Add opt-in check_string(...) and check_file(...) APIs returning an immutable, JSON-serializable report. Required checks should include:
- source coverage: ordered raw block spans account for every non-whitespace source token;
- explicit parse success: no retained failed blocks;
- semantic round trip: default write/reparse preserves the protected ordered model inventory;
- canonical stability: a second cycle reaches the same canonical output; and
- source identity: report separately whether default writing would leave the source bytes/text unchanged or merely preserve semantics while normalizing layout.
If explicit parse failures already make the file incompatible, expensive or misleading downstream checks may be marked not run. Diagnostics must use stable codes and avoid embedding bibliography content or paths.
The protected inventory should share the same implementation as semantic round-trip regression tests so the runtime report and suite cannot drift. New model block types must require an explicit contract decision.
CLI
Provide an installed command and python -m bibtexparser entry point:
bibtexparser check FILE [--encoding ...] [--json]
Exit statuses should distinguish compatible (0), incompatible (1), and I/O/usage failure (2). Normal parsing should remain unchanged; the thorough preflight is opt-in.
Issue-report workflow and privacy
On incompatibility, text output may offer a pre-filled GitHub issue-draft URL. The default URL must contain diagnostics and environment metadata only—no file path, source, or snippet—and constructing it must not open a browser, send a request, or create an issue.
The initial report should explicitly mention an opt-in rerun flag that can generate a second source-bearing URL when an exact, bounded failed-block reproduction can be extracted. That path must:
- warn that source will appear in terminal logs, browser history, and the GitHub draft;
- include both blocks for duplicate-key failures;
- refuse arbitrary truncation that could make the reproduction invalid;
- use a Markdown fence that source backticks cannot escape;
- refuse overlong issue URLs; and
- reread and hash the file so source from a changed file cannot be attached to a stale report.
The user still reviews the draft and chooses whether to submit it.
Scope
The preflight is a same-version confidence check, not formal verification, schema validation, or a live provider/LLM feature. It must be deterministic, network-free, read-only, and covered entirely by synthetic tests.
Motivation
Users may have long-lived or unusual
.bibfiles that no finite fixture suite covers. Given past silent-loss cases, a user should be able to ask whether the installed parser's default public path appears safe for a specific file before trusting it with edits.This cannot prove that the parser interpreted every construct correctly: parsing and reparsing with the same implementation is not an independent oracle. It can still detect important failure classes and provide a concrete, read-only confidence report.
Proposed API
Add opt-in
check_string(...)andcheck_file(...)APIs returning an immutable, JSON-serializable report. Required checks should include:If explicit parse failures already make the file incompatible, expensive or misleading downstream checks may be marked
not run. Diagnostics must use stable codes and avoid embedding bibliography content or paths.The protected inventory should share the same implementation as semantic round-trip regression tests so the runtime report and suite cannot drift. New model block types must require an explicit contract decision.
CLI
Provide an installed command and
python -m bibtexparserentry point:Exit statuses should distinguish compatible (
0), incompatible (1), and I/O/usage failure (2). Normal parsing should remain unchanged; the thorough preflight is opt-in.Issue-report workflow and privacy
On incompatibility, text output may offer a pre-filled GitHub issue-draft URL. The default URL must contain diagnostics and environment metadata only—no file path, source, or snippet—and constructing it must not open a browser, send a request, or create an issue.
The initial report should explicitly mention an opt-in rerun flag that can generate a second source-bearing URL when an exact, bounded failed-block reproduction can be extracted. That path must:
The user still reviews the draft and chooses whether to submit it.
Scope
The preflight is a same-version confidence check, not formal verification, schema validation, or a live provider/LLM feature. It must be deterministic, network-free, read-only, and covered entirely by synthetic tests.