bibsync 0.3.1__tar.gz → 0.3.3__tar.gz

{bibsync-0.3.1 → bibsync-0.3.3}/CITATION.cff

@@ -1,5 +1,7 @@
 cff-version: 1.2.0
 title: "bibsync: A Rust package to automatically resolve, synchronize, and validate LaTeX citations across BibTeX databases"
+version: "0.3.3"
+date-released: "2026-06-02"
 license: "BSD-3-Clause"
 type: software
 authors:

{bibsync-0.3.1 → bibsync-0.3.3}/Cargo.lock

@@ -124,7 +124,7 @@ checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
 [[package]]
 name = "bibsync"
-version = "0.3.1"
+version = "0.3.3"
 dependencies = [
  "assert_cmd",
  "clap",
@@ -170,9 +170,9 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cc"
-version = "1.2.62"
+version = "1.2.63"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a1dce859f0832a7d088c4f1119888ab94ef4b5d6795d1ce05afb7fe159d79f98"
+checksum = "556e016178bb5662a08681bbe0f00f8e17631781a4dfc8c45e466e4b185ec27f"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
@@ -537,9 +537,9 @@ checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
 
 [[package]]
 name = "hyper"
-version = "1.10.0"
+version = "1.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eb92f162bf56536459fc83c79b974bb12837acfed43d6bc370a7916d0ae15ecc"
+checksum = "55281c53a1894c864990125767da440a4e630446785086f52523b20033b74498"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -1270,9 +1270,9 @@ dependencies = [
 
 [[package]]
 name = "rustls-native-certs"
-version = "0.8.3"
+version = "0.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "612460d5f7bea540c490b2b6395d8e34a953e52b491accd6c86c8164c5932a63"
+checksum = "dab5152771c58876a2146916e53e35057e1a4dfa2b9df0f0305b07f611fdea4d"
 dependencies = [
  "openssl-probe",
  "rustls-pki-types",
@@ -1445,9 +1445,9 @@ dependencies = [
 
 [[package]]
 name = "shlex"
-version = "1.3.0"
+version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
 [[package]]
 name = "simd_cesu8"
@@ -2218,18 +2218,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.49"
+version = "0.8.50"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bce33a6288fa3f072a8c2c7d0f2fdbb90e28298f0135c1f99b96c3db2efcc60b"
+checksum = "3b065d4f0e55f82fae73202e189638116a87c55ab6b8e6c2721e13dd9d854ad1"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.49"
+version = "0.8.50"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fd425244944f4ab65ccff928e7323354c5a018c75838362fdce749dfad2ee1e"
+checksum = "0b631b19d36a892ab55420c92dbc83ccd79274f25be714855d3074aa71cab639"
 dependencies = [
  "proc-macro2",
  "quote",

{bibsync-0.3.1 → bibsync-0.3.3}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bibsync"
-version = "0.3.1"
+version = "0.3.3"
 edition = "2024"
 rust-version = "1.85"
 authors = ["Isaac C. F. Wong"]

{bibsync-0.3.1 → bibsync-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bibsync
-Version: 0.3.1
+Version: 0.3.3
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Science/Research
@@ -65,6 +65,11 @@ NASA ADS and/or InspireHEP, rewrites provider BibTeX entries so the citekey stay
 the key used in TeX, and reports whether the output `.bib` file is current. With
 `--fix`, it writes the merged bibliography.
 
+When a citekey cannot be resolved, the command prints the key together with a
+reason and the likely fix. For example, an unsupported citekey is reported as an
+identifier-format problem, while an arXiv ID or DOI that the provider cannot find
+is reported as a provider miss.
+
 ## Installation
 
 Install the Rust CLI from crates.io:
@@ -112,9 +117,9 @@ For convenience, you can also use:
 @software{wong2026bibsync,
   author  = {Wong, Isaac C. F.},
   title   = {bibsync: A Rust package to automatically resolve, synchronize, and validate LaTeX citations across BibTeX databases},
-  version = {v0.3.1},
+  version = {v0.3.3},
   year    = {2026},
-  month   = may,
+  month   = jun,
   doi     = {10.5281/zenodo.20422622},
   url     = {https://doi.org/10.5281/zenodo.20422622}
 }
@@ -193,6 +198,12 @@ To update a bibliography in place, pass a single `.bib` file:
 bibsync --fix references.bib --force-regenerate
 ```
 
+Existing input files are validated before resolution. A missing single `.bib`
+input, `--other` bibliography, or `--ignore-file` is reported as an error with
+the path that could not be read. Existing bibliography files are also parsed
+strictly, so malformed BibTeX reports the file and the approximate failing
+entry instead of being treated as an empty or partial bibliography.
+
 ### Update Behavior
 
 By default `bibsync` leaves published entries untouched. Only entries that look
@@ -244,6 +255,10 @@ bibsync --fix --refresh-cache main.tex -o references.bib
 
 Override the cache location with `--cache-dir DIR`.
 
+If a cache file is corrupt, `bibsync` reports the exact cache path and asks you
+to refresh or remove the bad cache entry. Provider request failures include the
+provider and citekey or batch being resolved.
+
 ## Pre-commit
 
 The repository includes `.pre-commit-hooks.yaml`, so other projects can use
@@ -254,7 +269,7 @@ Use the pre-built binary hook for faster installs:
 ```yaml
 repos:
     - repo: https://github.com/isaac-cf-wong/bibsync
-      rev: v0.3.1
+      rev: v0.3.3
       hooks:
           - id: bibsync-bin
             args: [--cache, --provider, inspire, --output, references.bib]
@@ -269,7 +284,7 @@ installation:
 ```yaml
 repos:
     - repo: https://github.com/isaac-cf-wong/bibsync
-      rev: v0.3.1
+      rev: v0.3.3
       hooks:
           - id: bibsync
             args: [--provider, inspire, --output, references.bib]
@@ -281,7 +296,7 @@ writing changes. To let the hook update files, add `--fix` to the hook args:
 ```yaml
 repos:
     - repo: https://github.com/isaac-cf-wong/bibsync
-      rev: v0.3.1
+      rev: v0.3.3
       hooks:
           - id: bibsync-bin
             args: [--fix, --cache, --provider, inspire, --output, references.bib]
@@ -292,7 +307,7 @@ To skip manually curated entries, add `--ignore-file`:
 ```yaml
 repos:
     - repo: https://github.com/isaac-cf-wong/bibsync
-      rev: v0.3.1
+      rev: v0.3.3
       hooks:
           - id: bibsync-bin
             args:

{bibsync-0.3.1 → bibsync-0.3.3}/README.md

@@ -38,6 +38,11 @@ NASA ADS and/or InspireHEP, rewrites provider BibTeX entries so the citekey stay
 the key used in TeX, and reports whether the output `.bib` file is current. With
 `--fix`, it writes the merged bibliography.
 
+When a citekey cannot be resolved, the command prints the key together with a
+reason and the likely fix. For example, an unsupported citekey is reported as an
+identifier-format problem, while an arXiv ID or DOI that the provider cannot find
+is reported as a provider miss.
+
 ## Installation
 
 Install the Rust CLI from crates.io:
@@ -85,9 +90,9 @@ For convenience, you can also use:
 @software{wong2026bibsync,
   author  = {Wong, Isaac C. F.},
   title   = {bibsync: A Rust package to automatically resolve, synchronize, and validate LaTeX citations across BibTeX databases},
-  version = {v0.3.1},
+  version = {v0.3.3},
   year    = {2026},
-  month   = may,
+  month   = jun,
   doi     = {10.5281/zenodo.20422622},
   url     = {https://doi.org/10.5281/zenodo.20422622}
 }
@@ -166,6 +171,12 @@ To update a bibliography in place, pass a single `.bib` file:
 bibsync --fix references.bib --force-regenerate
 ```
 
+Existing input files are validated before resolution. A missing single `.bib`
+input, `--other` bibliography, or `--ignore-file` is reported as an error with
+the path that could not be read. Existing bibliography files are also parsed
+strictly, so malformed BibTeX reports the file and the approximate failing
+entry instead of being treated as an empty or partial bibliography.
+
 ### Update Behavior
 
 By default `bibsync` leaves published entries untouched. Only entries that look
@@ -217,6 +228,10 @@ bibsync --fix --refresh-cache main.tex -o references.bib
 
 Override the cache location with `--cache-dir DIR`.
 
+If a cache file is corrupt, `bibsync` reports the exact cache path and asks you
+to refresh or remove the bad cache entry. Provider request failures include the
+provider and citekey or batch being resolved.
+
 ## Pre-commit
 
 The repository includes `.pre-commit-hooks.yaml`, so other projects can use
@@ -227,7 +242,7 @@ Use the pre-built binary hook for faster installs:
 ```yaml
 repos:
     - repo: https://github.com/isaac-cf-wong/bibsync
-      rev: v0.3.1
+      rev: v0.3.3
       hooks:
           - id: bibsync-bin
             args: [--cache, --provider, inspire, --output, references.bib]
@@ -242,7 +257,7 @@ installation:
 ```yaml
 repos:
     - repo: https://github.com/isaac-cf-wong/bibsync
-      rev: v0.3.1
+      rev: v0.3.3
       hooks:
           - id: bibsync
             args: [--provider, inspire, --output, references.bib]
@@ -254,7 +269,7 @@ writing changes. To let the hook update files, add `--fix` to the hook args:
 ```yaml
 repos:
     - repo: https://github.com/isaac-cf-wong/bibsync
-      rev: v0.3.1
+      rev: v0.3.3
       hooks:
           - id: bibsync-bin
             args: [--fix, --cache, --provider, inspire, --output, references.bib]
@@ -265,7 +280,7 @@ To skip manually curated entries, add `--ignore-file`:
 ```yaml
 repos:
     - repo: https://github.com/isaac-cf-wong/bibsync
-      rev: v0.3.1
+      rev: v0.3.3
       hooks:
           - id: bibsync-bin
             args:

{bibsync-0.3.1 → bibsync-0.3.3}/docs/api/index.md

@@ -54,11 +54,15 @@ behavior.
 - `output`: explicit output bibliography file.
 - `other_bibliographies`: read-only bibliography sources.
 - `provider`: `auto`, NASA ADS, or InspireHEP.
-- `update_existing`: refresh existing entries when possible.
+- `update_mode`: controls whether existing entries are refreshed.
 - `force_regenerate`: rewrite existing entries from provider output.
 - `merge_other`: copy matching read-only entries into the output file.
 - `backup`: create a `.bak` file before overwriting.
 - `check`: compare only and do not write.
+- `cache`: read and write provider responses from the local cache.
+- `refresh_cache`: bypass cache reads and update cached provider responses.
+- `cache_dir`: override the cache location.
+- `ignore_file`: citekeys to skip during resolution.
 
 `SyncReport` describes the outcome:
 
@@ -67,9 +71,19 @@ behavior.
 - `existing`: citekeys already present.
 - `found_in_other`: citekeys found in read-only bibliographies.
 - `unresolved`: citekeys that could not be resolved.
+- `unresolved_details`: per-citekey diagnostics explaining whether resolution
+  failed because the key is not a supported identifier or because the provider
+  returned no match.
 - `changed`: whether the output would change.
 - `check_mode`: whether the run was check-only.
 
+`sync_files` validates existing input files before resolution. Missing TeX
+inputs, missing single-file `.bib` inputs, missing `other_bibliographies`,
+missing `ignore_file`, malformed existing BibTeX, corrupt cache JSON, and
+provider request failures are returned as `BibsyncError` values with file,
+provider, and key context where available. A missing output bibliography is
+allowed when `output` points to the file that should be created.
+
 ## Providers
 
 The built-in providers are:

{bibsync-0.3.1 → bibsync-0.3.3}/docs/user-guide/pre-commit.md

@@ -115,9 +115,14 @@ bibsync --fix --cache --provider inspire --output references.bib main.tex
 Then review and commit the changed bibliography.
 
 If the hook reports unresolved citekeys, either correct the citekey or choose a
-provider that supports that identifier type. For example, ADS bibcodes require
-NASA ADS:
+provider that supports that identifier type. The hook output includes a reason
+for each unresolved key, such as an unsupported identifier format or a provider
+miss. For example, ADS bibcodes require NASA ADS:
 
 ```shell
 bibsync --fix --cache --provider ads --output references.bib main.tex
 ```
+
+Missing `--ignore-file` or `--other` paths and malformed existing BibTeX are
+reported as input errors with the affected path. Fix those files or hook
+arguments before rerunning the hook.

{bibsync-0.3.1 → bibsync-0.3.3}/docs/user-guide/usage.md

@@ -21,6 +21,13 @@ reports whether `references.bib` is current. It does not write changes unless
 bibsync --fix main.tex -o references.bib
 ```
 
+When a required citekey cannot be resolved, `bibsync` prints a diagnostic for
+each key. Unsupported citekeys are reported as identifier-format problems, and
+identifier-like keys that the selected provider cannot find are reported as
+provider misses. Those messages are meant to be actionable in automation: fix the
+citekey, choose a provider that supports it, add the entry manually, or add the
+key to an ignore file.
+
 ## Citekey Style
 
 The most reliable workflow is to cite by identifier:
@@ -101,6 +108,10 @@ Additional read-only bibliographies can be passed with `--other`:
 bibsync main.tex -o references.bib --other shared.bib software.bib
 ```
 
+Every file passed with `--other` must already exist and contain valid BibTeX.
+If a path is wrong or a file is malformed, `bibsync` stops with an error naming
+that file instead of silently ignoring it.
+
 By default, entries found in those read-only files are not copied into the main
 output file. This is useful when a project deliberately keeps shared references
 or software citations in separate files.
@@ -132,6 +143,9 @@ bibsync --fix main.tex -o references.bib --ignore-file .bibsyncignore
 Ignored citekeys are never sent to any provider and their existing bib entries
 are never modified.
 
+The ignore file must exist when `--ignore-file` is passed. A misspelled ignore
+path is reported as a missing input file.
+
 ## Updating A BibTeX File
 
 Passing a single `.bib` file uses the existing keys in that bibliography as the
@@ -148,6 +162,10 @@ scanning TeX files. Add `--fix` to refresh the file:
 bibsync --fix references.bib
 ```
 
+The `.bib` file must exist in this mode. Existing output bibliographies are also
+parsed before resolution; malformed BibTeX reports the file and approximate
+entry location so the bibliography can be corrected before running again.
+
 Use `--force-regenerate` to rewrite all existing entries from provider output:
 
 ```shell
@@ -167,6 +185,14 @@ The command exits with a non-zero status when the bibliography would change or
 when a required citekey cannot be resolved. This is the mode used by the
 pre-commit hook.
 
+Unresolved citekeys are printed with reasons. For example:
+
+```text
+unresolved:
+  Smith2024: unsupported identifier format; use an arXiv ID, DOI, or ADS bibcode, or add the entry to the bibliography or ignore file
+  2404.14498: provider returned no matching BibTeX entry; check the citekey, choose a provider that supports it, or add the entry manually
+```
+
 Use `--fix` to write the calculated bibliography:
 
 ```shell
@@ -205,6 +231,11 @@ Override the cache location with `--cache-dir`:
 bibsync --cache --cache-dir .bibsync-cache main.tex -o references.bib
 ```
 
+If a cached JSON file is corrupt, `bibsync` reports the exact cache path. Remove
+that file or rerun with `--refresh-cache` to rebuild the provider response.
+Network and provider failures include the provider and citekey or batch being
+resolved.
+
 ## Backups
 
 When `bibsync` writes over an existing bibliography, it creates a `.bak` file by

{bibsync-0.3.1 → bibsync-0.3.3}/python/bibsync/__init__.pyi

@@ -8,6 +8,7 @@ class SyncReport(TypedDict):
     existing: list[str]
     found_in_other: list[str]
     unresolved: list[str]
+    unresolved_details: list[dict[str, str]]
     changed: bool
     check_mode: bool
 

{bibsync-0.3.1 → bibsync-0.3.3}/src/cli.rs

@@ -165,7 +165,10 @@ where
                 );
             }
             if !report.unresolved.is_empty() {
-                println!("unresolved: {}", report.unresolved.join(", "));
+                println!("unresolved:");
+                for detail in &report.unresolved_details {
+                    println!("  {}: {}", detail.key, detail.reason);
+                }
             }
             if report.changed {
                 if report.check_mode {

{bibsync-0.3.1 → bibsync-0.3.3}/src/lib.rs

@@ -36,21 +36,57 @@ pub enum BibsyncError {
         /// The underlying I/O error.
         source: io::Error,
     },
+    /// An expected input file was not found.
+    #[error("{role} not found: {path}")]
+    MissingInput {
+        /// File path associated with the failure.
+        path: PathBuf,
+        /// User-facing description of the missing input.
+        role: &'static str,
+    },
     /// An HTTP request failed.
     #[error("HTTP request failed: {0}")]
     Http(#[from] reqwest::Error),
+    /// A provider request failed while resolving a specific key.
+    #[error("{provider} request failed while resolving {key}: {source}")]
+    ProviderRequest {
+        /// Provider name.
+        provider: &'static str,
+        /// Citekey or identifier being resolved.
+        key: String,
+        /// The underlying request error.
+        source: reqwest::Error,
+    },
     /// NASA ADS was selected without an API token.
     #[error("NASA ADS requires ADS_API_TOKEN")]
     MissingAdsToken,
     /// An HTTP header value could not be built.
     #[error("invalid HTTP header value: {0}")]
     InvalidHeader(#[from] reqwest::header::InvalidHeaderValue),
-    /// JSON cache serialization or parsing failed.
-    #[error("JSON error: {0}")]
-    Json(#[from] serde_json::Error),
+    /// JSON cache parsing failed.
+    #[error("{path}: invalid JSON cache file: {source}")]
+    Json {
+        /// Cache file path associated with the failure.
+        path: PathBuf,
+        /// The underlying JSON error.
+        source: serde_json::Error,
+    },
+    /// JSON cache serialization failed.
+    #[error("could not serialize JSON cache record: {0}")]
+    JsonSerialization(#[from] serde_json::Error),
     /// An input file did not point to any BibTeX output file.
-    #[error("could not identify a bibliography file; pass --output")]
+    #[error(
+        "could not identify a bibliography file; pass --output or add a \\bibliography{{...}} command"
+    )]
     MissingOutput,
+    /// A bibliography file could not be parsed.
+    #[error("{path}: invalid BibTeX: {message}")]
+    InvalidBibtex {
+        /// File path associated with the failure.
+        path: PathBuf,
+        /// User-facing parse diagnostic.
+        message: String,
+    },
     /// A provider returned an invalid BibTeX payload.
     #[error("{provider} did not return a usable BibTeX entry for {key}")]
     InvalidProviderBibtex {
@@ -149,12 +185,59 @@ pub struct SyncReport {
     pub found_in_other: Vec<String>,
     /// Citekeys that could not be resolved.
     pub unresolved: Vec<String>,
+    /// Detailed diagnostics for citekeys that could not be resolved.
+    pub unresolved_details: Vec<UnresolvedCitation>,
     /// Whether the output file content changed.
     pub changed: bool,
     /// Whether changes were only reported because check mode was enabled.
     pub check_mode: bool,
 }
 
+/// Diagnostic for one citekey that could not be resolved.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct UnresolvedCitation {
+    /// Citekey or identifier that could not be resolved.
+    pub key: String,
+    /// Reason the key could not be resolved automatically.
+    pub reason: UnresolvedReason,
+}
+
+/// Reason a citekey could not be resolved.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum UnresolvedReason {
+    /// The key is not an arXiv ID, DOI, or ADS bibcode.
+    UnsupportedIdentifier,
+    /// The selected provider did not return a matching entry.
+    ProviderNoMatch,
+}
+
+impl UnresolvedReason {
+    fn explanation(self) -> &'static str {
+        match self {
+            Self::UnsupportedIdentifier => {
+                "unsupported identifier format; use an arXiv ID, DOI, or ADS bibcode, or add the entry to the bibliography or ignore file"
+            }
+            Self::ProviderNoMatch => {
+                "provider returned no matching BibTeX entry; check the citekey, choose a provider that supports it, or add the entry manually"
+            }
+        }
+    }
+}
+
+impl std::fmt::Display for UnresolvedReason {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(self.explanation())
+    }
+}
+
+impl SyncReport {
+    fn push_unresolved(&mut self, key: String, reason: UnresolvedReason) {
+        self.unresolved.push(key.clone());
+        self.unresolved_details
+            .push(UnresolvedCitation { key, reason });
+    }
+}
+
 /// A resolved BibTeX entry.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct ResolvedEntry {
@@ -241,7 +324,7 @@ pub fn sync_files_with_provider(
     let bib_update_mode = files.len() == 1 && has_extension(&files[0], "bib");
     let (keys, output, discovered_other) = if bib_update_mode {
         let output = files[0].clone();
-        let bib = Bibliography::read_optional(&output)?;
+        let bib = Bibliography::read_existing(&output, "bibliography input")?;
         (bib.keys(), output, Vec::new())
     } else {
         let tex_scan = scan_tex_files(files)?;
@@ -268,10 +351,10 @@ pub fn sync_files_with_provider(
     };
 
     let original = read_to_string_optional(&output)?;
-    let mut bibliography = Bibliography::parse(&original);
+    let mut bibliography = Bibliography::parse_path(&output, &original)?;
     let mut other_bibliography = Bibliography::default();
     for path in &other_paths {
-        other_bibliography.merge(Bibliography::read_optional(path)?);
+        other_bibliography.merge(Bibliography::read_existing(path, "read-only bibliography")?);
     }
 
     let ignore_set = if let Some(ref path) = options.ignore_file {
@@ -326,7 +409,7 @@ pub fn sync_files_with_provider(
             if exists {
                 report.existing.push(key);
             } else {
-                report.unresolved.push(key);
+                report.push_unresolved(key, UnresolvedReason::UnsupportedIdentifier);
             }
             continue;
         }
@@ -358,7 +441,7 @@ pub fn sync_files_with_provider(
             if exists {
                 report.existing.push(key.clone());
             } else {
-                report.unresolved.push(key.clone());
+                report.push_unresolved(key.clone(), UnresolvedReason::ProviderNoMatch);
             }
             continue;
         };
@@ -413,6 +496,9 @@ pub fn sync_files_with_provider(
     report.existing.sort();
     report.found_in_other.sort();
     report.unresolved.sort();
+    report
+        .unresolved_details
+        .sort_by(|left, right| left.key.cmp(&right.key));
     Ok(report)
 }
 
@@ -556,27 +642,38 @@ struct Bibliography {
 }
 
 impl Bibliography {
-    fn read_optional(path: &Path) -> Result<Self> {
-        Ok(Self::parse(&read_to_string_optional(path)?))
+    fn read_existing(path: &Path, role: &'static str) -> Result<Self> {
+        Self::parse_path(path, &read_to_string_existing(path, role)?)
+    }
+
+    fn parse_path(path: &Path, input: &str) -> Result<Self> {
+        Self::try_parse(input).map_err(|message| BibsyncError::InvalidBibtex {
+            path: path.to_owned(),
+            message,
+        })
     }
 
-    fn parse(input: &str) -> Self {
+    fn try_parse(input: &str) -> std::result::Result<Self, String> {
         let mut bibliography = Self::default();
         let mut first_entry_start = None;
-        for segment in split_bib_entries(input) {
+        for segment in split_bib_entries(input)? {
             if first_entry_start.is_none() {
                 first_entry_start = input.find(segment);
             }
-            if let Some(entry) = BibEntry::parse(segment) {
-                bibliography.entries.insert(entry.key.clone(), entry);
-            }
+            let entry = BibEntry::parse(segment).ok_or_else(|| {
+                format!(
+                    "could not parse entry starting near line {}",
+                    line_number(input, input.find(segment).unwrap_or(0))
+                )
+            })?;
+            bibliography.entries.insert(entry.key.clone(), entry);
         }
         if let Some(index) = first_entry_start {
             input[..index].trim().clone_into(&mut bibliography.preamble);
         } else {
             input.trim().clone_into(&mut bibliography.preamble);
         }
-        bibliography
+        Ok(bibliography)
     }
 
     fn contains(&self, key: &str) -> bool {
@@ -617,16 +714,16 @@ impl std::fmt::Display for Bibliography {
     }
 }
 
-fn split_bib_entries(input: &str) -> Vec<&str> {
+fn split_bib_entries(input: &str) -> std::result::Result<Vec<&str>, String> {
     let mut entries = Vec::new();
     let bytes = input.as_bytes();
     let mut index = 0;
     while let Some(relative_at) = input[index..].find('@') {
         let start = index + relative_at;
-        let Some(relative_open) = input[start..].find(['{', '(']) else {
-            break;
+        let Some(open) = bib_entry_open(input, start) else {
+            index = start + 1;
+            continue;
         };
-        let open = start + relative_open;
         let close = if bytes.get(open) == Some(&b'{') {
             b'}'
         } else {
@@ -649,11 +746,42 @@ fn split_bib_entries(input: &str) -> Vec<&str> {
         if let Some(end) = end {
             entries.push(&input[start..end]);
             index = end;
+        } else {
+            return Err(format!(
+                "entry starting near line {} is missing a closing '{}'",
+                line_number(input, start),
+                close as char
+            ));
+        }
+    }
+    Ok(entries)
+}
+
+fn bib_entry_open(input: &str, at_index: usize) -> Option<usize> {
+    let rest = input.get(at_index + 1..)?;
+    let mut type_end = 0;
+    for (offset, ch) in rest.char_indices() {
+        if ch.is_ascii_alphabetic() {
+            type_end = offset + ch.len_utf8();
         } else {
             break;
         }
     }
-    entries
+    if type_end == 0 {
+        return None;
+    }
+    let after_type = &rest[type_end..];
+    let whitespace = after_type.len() - after_type.trim_start().len();
+    let open = at_index + 1 + type_end + whitespace;
+    matches!(input.as_bytes().get(open), Some(b'{' | b'(')).then_some(open)
+}
+
+fn line_number(input: &str, byte_index: usize) -> usize {
+    input[..byte_index.min(input.len())]
+        .bytes()
+        .filter(|byte| *byte == b'\n')
+        .count()
+        + 1
 }
 
 fn indent_body(body: &str) -> String {
@@ -699,12 +827,28 @@ fn read_to_string_optional(path: &Path) -> Result<String> {
     }
 }
 
+fn read_to_string_existing(path: &Path, role: &'static str) -> Result<String> {
+    match fs::read_to_string(path) {
+        Ok(content) => Ok(content),
+        Err(source) if source.kind() == io::ErrorKind::NotFound => {
+            Err(BibsyncError::MissingInput {
+                path: path.to_owned(),
+                role,
+            })
+        }
+        Err(source) => Err(BibsyncError::Io {
+            path: path.to_owned(),
+            source,
+        }),
+    }
+}
+
 fn is_supported_identifier(key: &str) -> bool {
     is_arxiv_id(key) || is_doi(key) || is_ads_bibcode(key)
 }
 
 fn load_ignore_set(path: &Path) -> Result<BTreeSet<String>> {
-    let content = read_to_string_optional(path)?;
+    let content = read_to_string_existing(path, "ignore file")?;
     Ok(content
         .lines()
         .map(str::trim)
@@ -962,7 +1106,14 @@ fn cache_store(root: &Path, key: &str, entry: &ResolvedEntry) -> Result<()> {
 
 fn read_json_optional<T: for<'de> Deserialize<'de>>(path: &Path) -> Result<Option<T>> {
     match fs::read_to_string(path) {
-        Ok(content) => Ok(Some(serde_json::from_str(&content)?)),
+        Ok(content) => {
+            serde_json::from_str(&content)
+                .map(Some)
+                .map_err(|source| BibsyncError::Json {
+                    path: path.to_owned(),
+                    source,
+                })
+        }
         Err(source) if source.kind() == io::ErrorKind::NotFound => Ok(None),
         Err(source) => Err(BibsyncError::Io {
             path: path.to_owned(),
@@ -1038,6 +1189,18 @@ fn provider_name_from_slug(slug: &str) -> &'static str {
     }
 }
 
+fn provider_request<T>(
+    provider: &'static str,
+    key: impl Into<String>,
+    result: std::result::Result<T, reqwest::Error>,
+) -> Result<T> {
+    result.map_err(|source| BibsyncError::ProviderRequest {
+        provider,
+        key: key.into(),
+        source,
+    })
+}
+
 fn unix_timestamp() -> u64 {
     std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
@@ -1117,14 +1280,15 @@ impl AdsProvider {
             return Ok(Some(key.to_owned()));
         }
         let query = format!("identifier:\"{key}\"");
-        let response: AdsSearchResponse = self
+        let response = self
             .client
             .get("https://api.adsabs.harvard.edu/v1/search/query")
             .headers(self.headers()?)
             .query(&[("q", query.as_str()), ("fl", "bibcode"), ("rows", "1")])
-            .send()?
-            .error_for_status()?
-            .json()?;
+            .send();
+        let response = provider_request(self.name(), key, response)?;
+        let response = provider_request(self.name(), key, response.error_for_status())?;
+        let response: AdsSearchResponse = provider_request(self.name(), key, response.json())?;
         Ok(response
             .response
             .docs
@@ -1133,18 +1297,25 @@ impl AdsProvider {
     }
 
     fn export_bibtex_many(&self, bibcodes: &[String]) -> Result<BTreeMap<String, String>> {
-        let response: AdsExportResponse = self
+        let key = if bibcodes.is_empty() {
+            "empty ADS export batch".to_owned()
+        } else {
+            bibcodes.join(", ")
+        };
+        let response = self
             .client
             .post("https://api.adsabs.harvard.edu/v1/export/bibtex")
             .headers(self.headers()?)
             .json(&json!({ "bibcode": bibcodes }))
-            .send()?
-            .error_for_status()?
-            .json()?;
+            .send();
+        let response = provider_request(self.name(), key.clone(), response)?;
+        let response = provider_request(self.name(), key.clone(), response.error_for_status())?;
+        let response: AdsExportResponse = provider_request(self.name(), key, response.json())?;
         let Some(export) = nonempty(&response.export) else {
             return Ok(BTreeMap::new());
         };
         Ok(split_bib_entries(&export)
+            .unwrap_or_default()
             .into_iter()
             .filter_map(|entry| {
                 let parsed = BibEntry::parse(entry)?;
@@ -1266,15 +1437,16 @@ impl BibliographyProvider for InspireProvider {
         } else {
             return Ok(None);
         };
-        let bibtex = self
+        let response = self
             .client
             .get("https://inspirehep.net/api/literature")
             .header(USER_AGENT, "bibsync/0.1")
             .header(ACCEPT, "application/x-bibtex")
             .query(&[("q", query.as_str()), ("format", "bibtex"), ("size", "1")])
-            .send()?
-            .error_for_status()?
-            .text()?;
+            .send();
+        let response = provider_request(self.name(), key, response)?;
+        let response = provider_request(self.name(), key, response.error_for_status())?;
+        let bibtex = provider_request(self.name(), key, response.text())?;
         let Some(bibtex) = nonempty(&bibtex) else {
             return Ok(None);
         };
@@ -1305,7 +1477,12 @@ impl BibliographyProvider for InspireProvider {
             return Ok(BTreeMap::new());
         }
 
-        let response: InspireSearchResponse = self
+        let batch_key = if keys.is_empty() {
+            "empty InspireHEP batch".to_owned()
+        } else {
+            keys.join(", ")
+        };
+        let response = self
             .client
             .get("https://inspirehep.net/api/literature")
             .header(USER_AGENT, "bibsync/0.1")
@@ -1313,9 +1490,12 @@ impl BibliographyProvider for InspireProvider {
                 ("q", query_parts.join(" OR ").as_str()),
                 ("size", keys.len().to_string().as_str()),
             ])
-            .send()?
-            .error_for_status()?
-            .json()?;
+            .send();
+        let response = provider_request(self.name(), batch_key.clone(), response)?;
+        let response =
+            provider_request(self.name(), batch_key.clone(), response.error_for_status())?;
+        let response: InspireSearchResponse =
+            provider_request(self.name(), batch_key, response.json())?;
 
         let mut record_by_key = BTreeMap::new();
         for hit in response.hits.hits {
@@ -1334,15 +1514,16 @@ impl BibliographyProvider for InspireProvider {
 
         let mut resolved = BTreeMap::new();
         for (key, record_id) in record_by_key {
-            let bibtex = self
+            let response = self
                 .client
                 .get(format!("https://inspirehep.net/api/literature/{record_id}"))
                 .header(USER_AGENT, "bibsync/0.1")
                 .header(ACCEPT, "application/x-bibtex")
                 .query(&[("format", "bibtex")])
-                .send()?
-                .error_for_status()?
-                .text()?;
+                .send();
+            let response = provider_request(self.name(), key.clone(), response)?;
+            let response = provider_request(self.name(), key.clone(), response.error_for_status())?;
+            let bibtex = provider_request(self.name(), key.clone(), response.text())?;
             let Some(bibtex) = nonempty(&bibtex) else {
                 continue;
             };
@@ -1437,8 +1618,8 @@ pub fn pre_commit_hook_manifest(ignore_file: Option<&Path>) -> String {
 #[cfg(test)]
 mod tests {
     use super::{
-        BibliographyProvider, ProviderChoice, ResolvedEntry, SyncOptions, citation_keys,
-        sync_files_with_provider,
+        BibliographyProvider, ProviderChoice, ResolvedEntry, SyncOptions, UnresolvedCitation,
+        citation_keys, sync_files_with_provider,
     };
     use std::cell::Cell;
     use std::collections::BTreeMap;
@@ -1623,4 +1804,192 @@ mod tests {
         assert_eq!(second.len(), 1);
         assert_eq!(calls.get(), 1);
     }
+
+    #[test]
+    fn single_bib_update_requires_existing_input() {
+        let dir = tempdir().expect("tempdir");
+        let missing = dir.path().join("missing.bib");
+        let provider = FakeProvider {
+            entries: BTreeMap::new(),
+        };
+
+        let error = sync_files_with_provider(
+            std::slice::from_ref(&missing),
+            &SyncOptions::default(),
+            &provider,
+        )
+        .expect_err("missing single bibliography should fail");
+
+        assert!(error.to_string().contains("bibliography input not found"));
+        assert!(error.to_string().contains(&missing.display().to_string()));
+    }
+
+    #[test]
+    fn other_bibliography_requires_existing_input() {
+        let dir = tempdir().expect("tempdir");
+        let tex = dir.path().join("main.tex");
+        let bib = dir.path().join("refs.bib");
+        let other = dir.path().join("shared.bib");
+        std::fs::write(&tex, "\\cite{2404.14498}").expect("write tex");
+        let provider = FakeProvider {
+            entries: BTreeMap::new(),
+        };
+
+        let error = sync_files_with_provider(
+            &[tex],
+            &SyncOptions {
+                output: Some(bib),
+                other_bibliographies: vec![other.clone()],
+                ..SyncOptions::default()
+            },
+            &provider,
+        )
+        .expect_err("missing other bibliography should fail");
+
+        assert!(
+            error
+                .to_string()
+                .contains("read-only bibliography not found")
+        );
+        assert!(error.to_string().contains(&other.display().to_string()));
+    }
+
+    #[test]
+    fn ignore_file_requires_existing_input() {
+        let dir = tempdir().expect("tempdir");
+        let tex = dir.path().join("main.tex");
+        let bib = dir.path().join("refs.bib");
+        let ignore = dir.path().join(".bibsyncignore");
+        std::fs::write(&tex, "\\cite{NotAnIdentifier}").expect("write tex");
+        let provider = FakeProvider {
+            entries: BTreeMap::new(),
+        };
+
+        let error = sync_files_with_provider(
+            &[tex],
+            &SyncOptions {
+                output: Some(bib),
+                ignore_file: Some(ignore.clone()),
+                ..SyncOptions::default()
+            },
+            &provider,
+        )
+        .expect_err("missing ignore file should fail");
+
+        assert!(error.to_string().contains("ignore file not found"));
+        assert!(error.to_string().contains(&ignore.display().to_string()));
+    }
+
+    #[test]
+    fn malformed_bibtex_reports_file_and_parse_error() {
+        let dir = tempdir().expect("tempdir");
+        let bib = dir.path().join("refs.bib");
+        std::fs::write(&bib, "@article{broken,\n  title = {Missing close}\n")
+            .expect("write malformed bib");
+        let provider = FakeProvider {
+            entries: BTreeMap::new(),
+        };
+
+        let error = sync_files_with_provider(
+            std::slice::from_ref(&bib),
+            &SyncOptions::default(),
+            &provider,
+        )
+        .expect_err("malformed BibTeX should fail");
+
+        assert!(error.to_string().contains("invalid BibTeX"));
+        assert!(error.to_string().contains("missing a closing"));
+        assert!(error.to_string().contains(&bib.display().to_string()));
+    }
+
+    #[test]
+    fn malformed_output_bibtex_reports_file_and_parse_error() {
+        let dir = tempdir().expect("tempdir");
+        let tex = dir.path().join("main.tex");
+        let bib = dir.path().join("refs.bib");
+        std::fs::write(&tex, "\\cite{NotAnIdentifier}").expect("write tex");
+        std::fs::write(&bib, "@article{broken,\n  title = {Missing close}\n")
+            .expect("write malformed bib");
+        let provider = FakeProvider {
+            entries: BTreeMap::new(),
+        };
+
+        let error = sync_files_with_provider(
+            &[tex],
+            &SyncOptions {
+                output: Some(bib.clone()),
+                ..SyncOptions::default()
+            },
+            &provider,
+        )
+        .expect_err("malformed output BibTeX should fail");
+
+        assert!(error.to_string().contains("invalid BibTeX"));
+        assert!(error.to_string().contains("missing a closing"));
+        assert!(error.to_string().contains(&bib.display().to_string()));
+    }
+
+    #[test]
+    fn unresolved_details_distinguish_unsupported_and_provider_miss() {
+        let dir = tempdir().expect("tempdir");
+        let tex = dir.path().join("main.tex");
+        let bib = dir.path().join("refs.bib");
+        std::fs::write(&tex, "\\cite{NotAnIdentifier,2404.14498}").expect("write tex");
+        let provider = FakeProvider {
+            entries: BTreeMap::new(),
+        };
+
+        let report = sync_files_with_provider(
+            &[tex],
+            &SyncOptions {
+                output: Some(bib),
+                ..SyncOptions::default()
+            },
+            &provider,
+        )
+        .expect("sync");
+
+        assert_eq!(report.unresolved, vec!["2404.14498", "NotAnIdentifier"]);
+        assert_eq!(
+            report.unresolved_details,
+            vec![
+                UnresolvedCitation {
+                    key: "2404.14498".to_owned(),
+                    reason: super::UnresolvedReason::ProviderNoMatch,
+                },
+                UnresolvedCitation {
+                    key: "NotAnIdentifier".to_owned(),
+                    reason: super::UnresolvedReason::UnsupportedIdentifier,
+                },
+            ]
+        );
+    }
+
+    #[test]
+    fn corrupt_cache_json_reports_cache_path() {
+        let dir = tempdir().expect("tempdir");
+        let mapping = super::mapping_path(dir.path(), "inspire", "arxiv", "2404.14498");
+        std::fs::create_dir_all(mapping.parent().expect("mapping parent"))
+            .expect("create cache dir");
+        std::fs::write(&mapping, "{").expect("write corrupt cache");
+        let provider = CountingProvider {
+            calls: Rc::new(Cell::new(0)),
+            entries: BTreeMap::new(),
+        };
+        let cached = super::CachedProvider {
+            inner: Box::new(provider),
+            config: super::CacheConfig {
+                enabled: true,
+                refresh: false,
+                root: dir.path().to_owned(),
+            },
+        };
+
+        let error = cached
+            .resolve_many(&["2404.14498".to_owned()])
+            .expect_err("corrupt cache should fail");
+
+        assert!(error.to_string().contains("invalid JSON cache file"));
+        assert!(error.to_string().contains(&mapping.display().to_string()));
+    }
 }

{bibsync-0.3.1 → bibsync-0.3.3}/src/python.rs

@@ -94,6 +94,17 @@ fn sync_files_py<'py>(
     dict.set_item("existing", report.existing)?;
     dict.set_item("found_in_other", report.found_in_other)?;
     dict.set_item("unresolved", report.unresolved)?;
+    let unresolved_details = report
+        .unresolved_details
+        .into_iter()
+        .map(|detail| {
+            let item = PyDict::new(py);
+            item.set_item("key", detail.key)?;
+            item.set_item("reason", detail.reason.to_string())?;
+            Ok(item)
+        })
+        .collect::<PyResult<Vec<_>>>()?;
+    dict.set_item("unresolved_details", unresolved_details)?;
     dict.set_item("changed", report.changed)?;
     dict.set_item("check_mode", report.check_mode)?;
     Ok(dict)

{bibsync-0.3.1 → bibsync-0.3.3}/tests/cli.rs

@@ -43,7 +43,47 @@ fn cli_defaults_to_check_mode() {
         .arg(&tex)
         .assert()
         .failure()
-        .stdout(predicate::str::contains("unresolved: NotAnIdentifier"));
+        .stdout(predicate::str::contains("unresolved:"))
+        .stdout(predicate::str::contains(
+            "NotAnIdentifier: unsupported identifier format",
+        ));
+}
+
+#[test]
+fn cli_reports_missing_ignore_file() {
+    let dir = tempdir().expect("tempdir");
+    let tex = dir.path().join("main.tex");
+    let bib = dir.path().join("refs.bib");
+    let ignore = dir.path().join(".bibsyncignore");
+    std::fs::write(&tex, "\\cite{NotAnIdentifier}").expect("write tex");
+
+    let mut command = Command::cargo_bin("bibsync").expect("binary exists");
+    command
+        .arg("--output")
+        .arg(&bib)
+        .arg("--ignore-file")
+        .arg(&ignore)
+        .arg(&tex)
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("ignore file not found"))
+        .stderr(predicate::str::contains(ignore.display().to_string()));
+}
+
+#[test]
+fn cli_reports_malformed_bibtex() {
+    let dir = tempdir().expect("tempdir");
+    let bib = dir.path().join("refs.bib");
+    std::fs::write(&bib, "@article{broken,\n  title = {Missing close}\n")
+        .expect("write malformed bib");
+
+    let mut command = Command::cargo_bin("bibsync").expect("binary exists");
+    command
+        .arg(&bib)
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("invalid BibTeX"))
+        .stderr(predicate::str::contains("missing a closing"));
 }
 
 #[test]

{bibsync-0.3.1 → bibsync-0.3.3}/tests/python/test_bindings.py

@@ -27,6 +27,7 @@ def test_sync_files_reports_existing_complete_bib_entry(tmp_path: Path) -> None:
         "existing": ["smith2024"],
         "found_in_other": [],
         "unresolved": [],
+        "unresolved_details": [],
         "changed": False,
         "check_mode": True,
     }