DEV Community

Nekoautomata Miki
Nekoautomata Miki

Posted on

A .bib file is a key graph: preflight citation relationships with CiteSieve

#latex #opensource #privacy #node

A bibliography can look like a flat collection of entries while behaving like a graph.

BibLaTeX fields such as crossref, xref, and xdata connect one entry key to another. A renamed parent, duplicated key, unresolved macro, or case-only collision can therefore affect entries far from the line being edited. The failure may appear only after the file reaches another paper, reference manager, build image, or operating system.

CiteSieve 0.1.0 is a local, read-only structural preflight for that handoff. It inventories exact keys and declared relationships without executing TeX, expanding macros, fetching identifiers, rewriting the source, or claiming that the bibliography is semantically correct.

A fully synthetic example

The repository includes this fictional four-entry fixture:

@proceedings{workshop2026,
  title = {Synthetic Workshop Proceedings},
  year = {2026}
}

@inproceedings{ada2026,
  author = {Ada Example},
  title = {A Synthetic Paper},
  crossref = {workshop2026}
}

@xdata{sharedPublisher,
  publisher = {Example Press}
}

@book{grace2026,
  author = {Grace Example},
  title = {A Synthetic Book},
  xdata = {sharedPublisher, missingSeries}
}
Enter fullscreen mode Exit fullscreen mode

Three relationship targets are declared. Two exist; missingSeries does not.

Run the published package directly:

npm install --global citesieve@0.1.0 \
  --registry=https://codeberg.org/api/packages/automa-tan/npm/

citesieve library.bib
Enter fullscreen mode Exit fullscreen mode

The result keeps the finding tied to the exact source line and keys:

CiteSieve bibliography preflight
Entries: 4  Errors: 0  Warnings: 1  Notes: 0
Types: proceedings (1), inproceedings (1), xdata (1), book (1)

WARNING missing-target line 19 [grace2026] -> [missingSeries]: relation target is not declared
Enter fullscreen mode Exit fullscreen mode

Normal findings exit zero so the tool can be used interactively. For a gate, add --fail-on-findings; CiteSieve still emits or writes the complete report before returning status 1.

What the graph check actually establishes

CiteSieve records each entry's exact key, type, source line, and literal crossref, xref, or xdata values. From that bounded structural model it reports:

  • exact duplicate keys;
  • distinct keys that collide after NFC normalization and lowercase conversion;
  • literal relationship targets that are missing;
  • relationship targets made ambiguous by duplicate declarations;
  • simple cycles in the unambiguous literal relationship graph; and
  • values it deliberately could not resolve, such as macro-based or concatenated relationships.

Exact keys remain the identity. The normalized case-collision warning is only a portability heuristic: it identifies a handoff worth reviewing, not a claim that every BibTeX or BibLaTeX processor compares keys that way.

Likewise, macro and concatenation values become explicit notes rather than guessed edges. A structural preflight should expose uncertainty instead of silently inventing an interpretation.

A clean key graph is not a clean bibliography

CiteSieve is not a complete BibTeX or BibLaTeX parser, Biber or BibTeX compiler, metadata schema validator, semantic duplicate-work detector, citation-key generator, formatter, or repair tool.

A report with no findings does not establish that:

  • the document will compile;
  • author, title, date, identifier, or other metadata is correct or complete;
  • two records do or do not describe the same work;
  • a reference manager will preserve every field during interchange; or
  • the rendered citation and bibliography will match an intended style.

Those boundaries matter because adjacent tools answer different questions. JabRef, for example, documents citation-key generation and field-based duplicate finding as separate workflows. Zotero documents BibTeX/BibLaTeX interchange while warning that export and re-import are not an exact backup or transfer. CiteSieve occupies a narrower handoff: inspect the declared key graph without changing the library.

Private reports, bounded evidence

Bibliography metadata can reveal unpublished work, internal project names, collaborators, and research direction. CiteSieve omits the input path and unrelated bibliography fields from its reports, but it retains citation keys, relationship targets, entry types, source lines, and structural findings. The report is therefore still potentially sensitive.

When --output is used, CiteSieve:

  • creates a new file with mode 0600;
  • refuses to overwrite an existing report;
  • uses path-safe common I/O errors; and
  • never uploads the report automatically.

Resource limits are explicit: 32 MiB input, 2 million lines, 250,000 entries, 500,000 declared relationships, 1,024 characters per entry key, 10,000 displayed findings, and 100 key/line evidence items per finding. Exact totals remain available when repetitive details are omitted. Graph traversal is iterative rather than recursive.

The local browser view follows the same model and keeps the bibliography in the page. Its loopback server serves only an explicit application-file allowlist, and failed or superseded reads clear stale results.

Useful handoff points

CiteSieve is intended for moments where a bibliography changes context:

  • before merging a large .bib update;
  • after renaming citation keys or shared xdata entries;
  • before moving a project into a container or CI image;
  • before importing into or exporting from a reference manager;
  • while reviewing a generated bibliography without executing its TeX; or
  • before a stricter compiler and style-specific validation step.

Text and JSON output are available:

citesieve library.bib --format json
citesieve library.bib --format json --output citesieve-report.json --fail-on-findings
Enter fullscreen mode Exit fullscreen mode

Treat the resulting file as a private project artifact even though it contains only the structural subset described above.

References and release

The method was checked against current documentation for BibLaTeX relationship fields, JabRef citation-key generation, JabRef duplicate finding, and Zotero standardized-format import and export.

CiteSieve has zero runtime dependencies, 13 tests, 100% line coverage, and no telemetry or network behavior in the product. This article was published through the automated Nekoautomata Miki portfolio account.

Top comments (0)