Skip to content

Write-back to Hayagriva sidecars (directory as library, phase 3) - #739

Open
koppor wants to merge 27 commits into
directory-inbound-syncfrom
directory-write-back
Open

koppor wants to merge 27 commits into
directory-inbound-syncfrom
directory-write-back

Conversation

@koppor

@koppor koppor commented Jul 14, 2026 •

Copy link
Copy Markdown
Member

📚 Directory-as-library stack — bottom → top, each builds on the one below:

  1. Programmatic Hayagriva writer (directory-as-library, phase 0) #736 · Hayagriva YAML writer
  2. Open folder as library (directory as library, phase 1) #737 · Open folder as library
  3. Live inbound sync for directory libraries (phase 2) #738 · Inbound file sync
  4. Write-back to Hayagriva sidecars (directory as library, phase 3) #739 · Write-back to sidecars ← this PR
  5. Groups panel mirrors the directory structure (phase 4, #10930) #740 · Directory-structure groups
  6. Pattern-driven pair renames for directory libraries (phase 5a) #741 · Pattern-driven pair renames
  7. Mirror directory libraries into a .bib with git-sync merge-back #743 · .bib mirror + merge-back
  8. Convert .bib libraries into directory libraries #744 · Convert .bib → directory
  9. Make directory libraries reachable through the REST API #745 · REST API support
  10. Split DirectoryLibrarySynchronizer into collaborators #760 · Split the synchronizer

Related issues and pull requests

Phase 3 of the "directory as library" plan (PLAN.md), stacked on #738 (base branch directory-inbound-sync; the diff also contains the programmatic Hayagriva writer commits of #736, which this phase is the first consumer of). No issue is closed by this PR.

PR Description

🤖 A directory library now saves straight into its Hayagriva sidecar files — Ctrl+S never writes a .bib. The first edit of an entry creates a sidecar beside its PDF or named after its citation key; deleting an entry removes it from its file, leaving the PDF untouched. Hand-written content JabRef does not understand survives every write, and directory tabs no longer prompt on close because nothing is left unsaved.

jabref-contrib-policy:4.2:reviewed​:ok

Analogies

Like honey sealed back into its own comb, every change flows into the cell it came from — the sidecar next to the paper. Like a chocolate mold that shapes only the squares you pour, the read-modify-write merge touches only the fields JabRef owns and leaves the rest of the bar untouched. And like the moon completing its cycle, the round trip is closed: what the importer reads, the writer returns to the very same file.

Steps to test

  1. Open a folder as library, create an entry (toolbar +): a sidecar .yml appears immediately.

  2. Type a title and a citation key: within half a second the file contains them, the YAML key follows the citation key:

    writeback2026:
      type: article
      title: Write-back works end to end
  3. Ctrl+S shows "Library saved" — no .bib file is created anywhere.

  4. Delete the entry: the sidecar disappears, PDFs stay.

New entry in a directory library, persisted to its sidecar

Guarded by seven new DirectoryLibrarySynchronizerTest cases (rewrite preserving unknown YAML, sidecar creation for stubs and new entries, key rename, disposal semantics, multi-entry rewrite, self-echo suppression) plus HayagrivaEntryWriter.mergeIntoDocument.

AI usage

Claude Code (model claude-fable-5).

AI CHECKLIST.md walkthrough

1. Code self-review

  • No == null/!= null beyond nullable JDK/Jackson returns; new members @NullMarked via their classes; Optional consumed idiomatically; no Objects.requireNonNull.
  • Only specific exceptions caught (IOException, JacksonException); none of RuntimeException/IllegalStateException thrown; exceptions last in log calls.
  • Withers for new BibEntrys in tests; records, SequencedMap, List.of(); no new threads (existing per-library executor reused); no commented-out code; Markdown Javadoc.
  • User-facing text: reuses the existing Library saved key; no new strings.
  • [/] Security: no HTML output.
  • Tests: plain JUnit asserts, @TempDir, deterministic (direct handler calls + flush(), injected clock), no sleeps.

2. Verification commands

  • ./gradlew :jablib:check — full suite; only the known environmental Remote*Test port-conflict failures on this machine (a running JabRef occupies the port; green on CI).
  • ./gradlew :jablib:checkstyleMain :jablib:checkstyleTest :jabgui:checkstyleMain.
  • ./gradlew :jablib:modernizer and ./gradlew traceRequirements (new req~directory-library.write-back~1 covered).
  • ./gradlew --no-configuration-cache :rewriteDryRun — no changes.
  • npx markdownlint-cli2 on changed Markdown.
  • [/] IntelliJ-format docker image — not runnable on this machine; CI format job is the backstop.

3. Documentation

  • CHANGELOG.md entry (TODO replaced with this PR's link after creation).
  • Requirement req~directory-library.write-back~1 added with impl markers.
  • [/] ADR — ADR-0072 already specifies this phase's design (write-back section).

4. Pull request

  • Body from the template, all sections filled, HTML comments removed, created from a body file via gh api (stacked cross-repo).
  • CHANGELOG TODO replaced after creation, committed and pushed.

Checklist

  • I own the copyright of the code submitted and I license it under the MIT license
  • If AI tools were used, I disclosed them in the "AI usage" section and reviewed, understood, and take full ownership of all AI-generated code
  • I manually tested my changes in running JabRef (created/edited/renamed/deleted entries in a directory library on the X display and inspected the sidecar files after each step; Ctrl+S produced no .bib)
  • I added JUnit tests for changes (if applicable)
  • I added screenshots in the PR description (if change is visible to the user)
  • [/] I added a screenshot in the PR description showing a library with a single entry with me as author and as title the issue number
  • I added one sentence (max 20 words) to CHANGELOG.md describing the change from the user's point of view (if the change is visible to the user)
  • I checked the user documentation for up to dateness and submitted a pull request to our user documentation repository — deferred until the feature stabilizes; tracked in PLAN.md phase 5

🤖 Generated with Claude Code

koppor and others added 4 commits July 14, 2026 04:39
The outbound half of DirectoryLibrarySynchronizer subscribes to entry
events through a CoarseChangeFilter (mirroring the shared-SQL seam) and
persists user changes read-modify-write into the Hayagriva sidecars,
debounced per file: the first edit of an entry without a sidecar
creates one (next to its PDF, sharing the base name, or named after the
citation key), a citation-key edit renames the YAML map key, and
deleting an entry removes it from its file — the file is trashed or
deleted once its last entry is gone, the paired PDF is never touched.
Own writes are fingerprinted so the inbound watcher ignores them.

Ctrl+S now flushes the pending sidecar writes instead of asking for a
.bib path; "Save as" remains the explicit .bib snapshot. Directory tabs
no longer prompt on close and drop the modification marker, and
generated citation keys are set with a non-local event source so
system-initiated changes never materialize sidecars.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
koppor and others added 3 commits July 17, 2026 01:50
# Conflicts:
#	jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java
New sidecars are now created as Markdown files: the Hayagriva data as
YAML frontmatter, the comment fields as a markdownlint-clean notes body
(# Notes intro, one ## comment-<name> section per per-user comment);
body sections under foreign headings survive rewrites. Plain .yml
sidecars keep being written as pure Hayagriva.

The write debounce is now trailing-edge and re-armed by every change
event, including the keystroke events the CoarseChangeFilter marks as
filtered. Previously only the first keystroke after a field switch
scheduled a write, so the write captured a mid-typing value and the
rest of the burst was never persisted (and Ctrl+S had nothing left to
flush).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5Y5GTihE9rZxKrvPqnHV4
koppor and others added 8 commits September 3, 2026 03:22
Resync layer 4. Conflict: upstream changed SaveDatabaseAction.save() to
return SaveResult instead of boolean — kept the directory-library
flush-instead-of-.bib early return, now returning SaveResult.SUCCESS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDcHNMt9fPWnpYaHheFvry
… write-back

Failed sidecar writes stay pending and are reported on save and close instead of being lost; metadata extraction for a dropped PDF no longer runs under the synchronizer's monitor; deleting an entry keeps its file until the debounced write, so an undo lands it back in the same file; an external edit that arrives before a pending write is merged field-wise instead of overwritten; writes are debounced per file, use AtomicFileOutputStream, and are drained before the final flush on shutdown.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vr3E1Gg5DRU4LQDDVnhPys
# Conflicts:
#	jablib/src/main/java/org/jabref/logic/exporter/HayagrivaEntryWriter.java
Fixes the CI format check.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDcHNMt9fPWnpYaHheFvry
Adapt to upstream: save() gained a mayAutoCommit parameter (directory
early-return unaffected), the change-event filtered flag was renamed to
setFiltered, and the unwritable-sidecar test is disabled on Windows
(setWritable(false) is a no-op there for the owner).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDcHNMt9fPWnpYaHheFvry
Upstream added a 0071 ADR after this stack claimed the number, so the
MADR duplicate-ID check failed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@qodo-free-for-open-source-projects

qodo-free-for-open-source-projects Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (14)

Grey Divider


Action required

1. Save As leaves the snapshot unwritten 🐞 Bug
Description
saveAs(Path, ...) reaches the directory branch of save(BibDatabaseContext, ...), which flushes
sidecars but never writes to the requested target path. When that branch returns success, saveAs
converts the context to a local library and points it at a .bib file that is absent or still
contains old data.
Code

jabgui/src/main/java/org/jabref/gui/exporter/SaveDatabaseAction.java[R273-278]

+        if (bibDatabaseContext.getLocation() == DatabaseLocation.DIRECTORY) {
+            // A directory library persists into its sidecar files; saving means flushing the
+            // debounced writes, never writing a .bib ("Save as" remains the explicit snapshot)
+            // [impl->req~directory-library.write-back~2]
+            List<Path> unwritable = Optional.ofNullable(bibDatabaseContext.getDirectorySynchronizer())
+                                            .map(DirectoryLibrarySynchronizer::flush)
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Directory-library Save As reports success without writing its target `.bib` file.
## Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/exporter/SaveDatabaseAction.java[203-220]
- jabgui/src/main/java/org/jabref/gui/exporter/SaveDatabaseAction.java[272-295]
## Recommended Fix
Distinguish Save As from ordinary directory Save: flush sidecars, write the requested `.bib` snapshot through the path-based writer, and convert the context only after both operations succeed.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


2. Save can finish before the last edit 🐞 Bug
Description
flush() snapshots dirtyFiles without first draining the entry events queued on syncExecutor.
If Save or close follows an edit before its queued handler calls scheduleWrite, the flush returns
success without including that edit; close can then shut down while relying on a later write.
Code

jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[R244-247]

+    public synchronized List<Path> flush() {
+        scheduledWrites.values().forEach(pending -> pending.cancel(false));
+        scheduledWrites.clear();
+        return writeFiles(List.copyOf(dirtyFiles), true);
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A flush can precede already-queued entry event handlers and omit their edits.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[241-247]
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[298-326]
## Recommended Fix
Establish an executor barrier before taking the dirty-file snapshot, without holding the synchronizer monitor while waiting for handlers that need that monitor. Make Save and close wait for that barrier before reporting success.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


3. Citation keys can write outside the folder 🐞 Bug
Description
unusedSidecar() resolves a citation key directly against the library root without checking that
the resulting path stays inside it. A source-less entry with a key such as ../../outside/payload
can create an outside-root sidecar on its first edit, and deleting that entry later passes the same
path to the file disposer; a linked path beneath a symlinked directory offers another escape from
the lexical check.
Code

jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[R367-370]

+    private Path unusedSidecar(String baseName) {
+        Path candidate = root.resolve(baseName + "." + MarkdownSidecar.MARKDOWN_EXTENSION);
+        for (int counter = 1; Files.exists(candidate) || !catalog.entryIdsIn(candidate).isEmpty(); counter++) {
+            candidate = root.resolve(baseName + "-" + counter + "." + MarkdownSidecar.MARKDOWN_EXTENSION);
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Citation keys and symlinked linked-file paths can direct sidecar creation and disposal outside the library root.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[352-372]
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[430-468]
## Recommended Fix
Encode or sanitize citation keys as a single filename component. Validate the resolved parent against the real library root, including symlinks, before registering, writing, or disposing a sidecar; fall back to a safe name when a paired path is outside it.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


4. Failed deletion leaves a sidecar behind 🐞 Bug
Description
disposeFile() catches deletion failures and returns normally, so writeFile() treats disposal as
successful after removing the sidecar from the catalog. If trashing or deletion fails,
writeFiles() clears the dirty path and later Save or close cannot retry or report the sidecar that
still contains the removed entry.
Code

jabgui/src/main/java/org/jabref/gui/importer/actions/OpenDirectoryLibraryAction.java[R122-126]

+                Files.delete(file);
+            }
+        } catch (IOException e) {
+            LOGGER.error("Could not remove sidecar {}", file, e);
+        }
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A failed trash/delete operation is marked complete and omitted from Save and close errors.
## Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/importer/actions/OpenDirectoryLibraryAction.java[115-127]
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[394-440]
## Recommended Fix
Give the disposer a failure-reporting contract and keep the file cataloged and dirty until disposal succeeds. Include disposal failures in the paths returned by flush.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



Remediation recommended

5. Late PDF metadata replaces user edits 🐞 Bug
Description
enrichStub() applies extracted metadata to the same stub that was inserted for immediate editing,
without comparing it to the stub's initial fields. If extraction finishes after a user changes the
title or another extracted field, applyExtractedMetadata() overwrites that value with a SHARED
update, including after the user's sidecar write has been scheduled.
Code

jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[R663-667]

+    private void enrichStub(BibEntry stub, Path pdf) {
+        Optional<BibEntry> extracted = pdfEntryFactory.extractMetadata(pdf, databaseContext);
       modelUpdateMarshaller.accept(() -> {
-            databaseContext.getDatabase().insertEntries(List.of(entry), EntriesEventSource.SHARED);
-            pdfEntryFactory.generateCitationKeyIfMissing(entry, databaseContext);
+            extracted.ifPresent(metadata -> pdfEntryFactory.applyExtractedMetadata(metadata, stub));
+            pdfEntryFactory.generateCitationKeyIfMissing(stub, databaseContext);
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Background PDF enrichment overwrites fields a user edited on the visible stub.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[653-668]
- jablib/src/main/java/org/jabref/logic/directorylibrary/PdfEntryFactory.java[87-100]
## Recommended Fix
Capture the stub's initial values and apply each extracted field only if the corresponding live value is still unchanged, while retaining the existing non-user event source for fields that are applied.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


View medium (8)
6. Slow shutdown can strand the last edit 🐞 Bug
Description
shutdown() ignores the boolean result of its two-second awaitTermination() and flushes even if
queued entry handlers have not run. When the single executor remains busy past that timeout, a
queued handler can mark a file dirty only after the final flush; with the executor shut down,
scheduleWrite() then schedules no replacement write.
Code

jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[R232-238]

       syncExecutor.shutdown();
+        try {
+            syncExecutor.awaitTermination(2, TimeUnit.SECONDS);
+        } catch (InterruptedException _) {
+            Thread.currentThread().interrupt();
+        }
+        return flush();
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Shutdown can flush before its accepted event handlers finish, permanently stranding their edits.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[226-248]
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[375-383]
## Recommended Fix
Make shutdown establish completion of accepted entry-event work before the final flush. If completion cannot be guaranteed, report the incomplete shutdown rather than returning success; avoid waiting while holding the synchronizer monitor.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


7. Code examples can lose their notes 🐞 Bug
Description
parseBody() treats every line beginning ##  as a section delimiter, without excluding fenced
code inside a foreign notes section. If a code example contains a line such as ## comment-alice,
renderBody() reclassifies that text as a JabRef-owned comment section and drops it when the entry
has no corresponding comment field.
Code

jablib/src/main/java/org/jabref/logic/directorylibrary/MarkdownSidecar.java[R171-178]

       for (String line : body.lines().toList()) {
           if (line.startsWith(SECTION_HEADING_PREFIX)) {
-                applySection(entry, currentSection, currentText.toString());
-                currentSection = line.substring(SECTION_HEADING_PREFIX.length()).strip();
+                if (currentHeading.isEmpty()) {
+                    intro = currentText.toString().strip();
+                } else {
+                    sections.add(new Section(currentHeading, currentText.toString().strip()));
+                }
+                currentHeading = line.substring(SECTION_HEADING_PREFIX.length()).strip();
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Heading-like text inside a Markdown code fence can be removed during a sidecar rewrite.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/directorylibrary/MarkdownSidecar.java[165-190]
- jablib/src/main/java/org/jabref/logic/directorylibrary/MarkdownSidecar.java[197-226]
## Recommended Fix
Track fenced code while parsing the notes body and recognize section headings only outside fences. Preserve foreign section text, including its code blocks, when rendering the updated body.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


8. Hand-written YAML comments disappear 🐞 Bug
Description
mergeIntoDocument() reads the existing sidecar into an ObjectNode and serializes a new tree,
which has no representation for YAML # comments. Any write-back of a commented .yml sidecar, or
commented Markdown frontmatter, therefore removes those comments even when the edited bibliographic
field is unrelated.
Code

jablib/src/main/java/org/jabref/logic/exporter/HayagrivaEntryWriter.java[R72-75]

+    public String mergeIntoDocument(String existingDocument, List<KeyedEntry> entries) throws IOException {
+        ObjectNode existingRoot = existingDocument.isBlank() ? MAPPER.createObjectNode() : parseRoot(existingDocument);
+        ObjectNode result = MAPPER.createObjectNode();
+        for (KeyedEntry keyedEntry : entries) {
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new sidecar write-back path discards hand-written YAML comments on every rewrite.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/exporter/HayagrivaEntryWriter.java[64-93]
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[458-468]
## Recommended Fix
Use a comment-preserving YAML edit strategy for existing sidecars, or otherwise preserve and restore comment-bearing source regions rather than replacing the whole document from a Jackson tree.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


9. Saving can overwrite an external edit on disk 🐞 Bug
Description
writeFile calls handleFileChanged for an external edit but, on an immediate flush, serializes
entriesOf(file) before applyChangedFile’s marshalled model update runs; parsing has already
advanced lastSeenFingerprints. When Ctrl+S or close triggers that path, the stale entries
overwrite the sidecar, a later write can treat the external edit as already seen, and the queued
SHARED-source update does not write it back—on close, the edit is lost completely.
Code

jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[R421-428]

+        if (changedExternally) {
+            // The model update is marshalled (asynchronously in the GUI), so the write is retried
+            // one debounce later — unless the caller flushes, where the user's state must win
+            handleFileChanged(file);
+            if (!immediate) {
+                return false;
+            }
+        }
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
An immediate flush can parse an external sidecar edit, then write stale in-memory entries before the queued model update applies. Parsing also advances the acknowledged fingerprint, allowing a later write to treat that edit as already seen.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[416-428]
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[597-615]
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[737-746]
## Recommended Fix
Ensure the external change is applied and merged before an immediate flush writes or acknowledges the file fingerprint. Either apply the parsed field updates synchronously when already on the model thread, or write a synchronous three-way merge of baseline, disk, and memory rather than the live entries; do not rely on the asynchronous marshaller for this path. Update the `writeFiles` comment so it no longer claims the edit has already been applied.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


10. Entry without a citation key is replaced after an outside edit 🐞 Bug
Description
writeFile stores the entry under targetKey, which falls back to entry, the previous key, or a
-N suffixed key, and records that in the catalog. The inbound applyChangedFile still matches
known entries by their live citation key through byCitationKey, so after an outside edit the
parsed entry under the written key no longer matches. This happens for a new entry without a
citation key (written as entry), for a de-duplicated key, and for a key rename made before the
debounced write; the user's entry is then removed (SHARED, so no undo) and a re-parsed copy is
inserted. On the flush path the catalog briefly holds only the not-yet-inserted parsed copy, so
entriesOf comes back empty and the sidecar is disposed.
Code

jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[R448-456]

+            String targetKey = entry.getCitationKey()
+                                    .filter(key -> !key.isBlank())
+                                    .orElse(previousKey.isBlank() ? "entry" : previousKey);
+            String uniqueKey = targetKey;
+            int counter = 1;
+            while (!usedKeys.add(uniqueKey)) {
+                uniqueKey = targetKey + "-" + counter++;
+            }
+            keyedEntries.add(new HayagrivaEntryWriter.KeyedEntry(previousKey, uniqueKey, entry));
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Write-back stores each entry under a Hayagriva key that can differ from its citation key. The inbound diff matches known entries by citation key, so after an external edit the entry is dropped and replaced, and on flush its file can even be disposed.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[577-614]
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[640-644]
## Recommended Fix
In `applyChangedFile`, key `knownEntries` by `catalog.sourceOf(entry).map(EntrySource::hayagrivaKey)` and fall back to the citation key only when that is missing. Use the same key in `takeBaseline`/`copiesByKey` so that baselines, the catalog and the parsed YAML keys stay aligned.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


11. Ctrl+S trashes a sidecar the user is editing 🐞 Bug
Description
If a pending edit's sidecar is saved externally with invalid content, the inbound path stages its
entries for deletion and commits that after RENAME_GRACE, which removes the file from the catalog.
The next flush then gets an empty entriesOf(file) in writeFile and calls fileDisposer on the
file, which exists but is malformed. A file being hand-edited is trashed, or permanently deleted
when trash is off or unsupported, as soon as the user presses Ctrl+S or closes the tab. Until then
the non-immediate path reschedules every 500 ms indefinitely, because lastSeenFingerprints is
never updated for an unparseable file.
Code

jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[R433-440]

+        if (entries.isEmpty()) {
+            catalog.removeFile(file);
+            lastSeenFingerprints.remove(normalized);
+            baselines.remove(file);
+            if (Files.exists(file)) {
+                fileDisposer.accept(file);
+            }
+            return true;
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A dirty sidecar whose entries were removed because an external edit made it unparseable gets disposed on the next flush, and the user's hand-edited file is deleted. The deferred retry also loops every 500 ms forever.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[416-441]
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[692-697]
## Recommended Fix
When `removeEntries` (inbound deletion) drops a file, also remove it from `dirtyFiles`, cancel its scheduled write and clear `lastSeenFingerprints`. In `writeFile`, dispose a file only when its current content equals the last-written or last-seen fingerprint, and never when it changed externally. Limit or drop the retry loop when the external content cannot be parsed.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


12. Background sidecar writes can crash and be dropped 🐞 Bug
Description
entriesOf wraps the iteration in synchronized (allEntries), but getEntries() returns a fresh
FXCollections.unmodifiableObservableList wrapper on each call, not the synchronized list's mutex,
so the lock excludes nothing. When the debounced write on the directory-sync thread iterates while
the FX thread inserts or removes entries, forEach can throw ConcurrentModificationException.
That exception is not caught by writeFiles, so the scheduled write dies silently with the file
still dirty and no retry until the next flush.
Code

jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[R707-711]

+        List<BibEntry> allEntries = databaseContext.getDatabase().getEntries();
+        // The UI thread mutates the (synchronized) list concurrently; field reads need no lock
+        synchronized (allEntries) {
+            allEntries.forEach(entry -> byId.put(entry.getId(), entry));
+        }
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`entriesOf` synchronizes on the unmodifiable wrapper that `getEntries()` returns. It is a new object on every call, so the iteration is not protected against concurrent FX-thread mutations.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[701-713]
- jablib/src/main/java/org/jabref/model/database/BibDatabase.java[60-119]
## Recommended Fix
Add a `BibDatabase` method that copies the entries while holding the backing synchronized list's lock, for example `synchronized (entries) { return List.copyOf(entries); }`, and use it in `entriesOf`. Alternatively, have `getEntryById` do the lookups. Also make `writeScheduled` reschedule or log on unexpected runtime exceptions.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


13. Sidecar writes stall behind PDF metadata lookups 🐞 Bug
Description
handlePdfCreated queues enrichStub on syncExecutor, a single-thread
ScheduledThreadPoolExecutor. The task calls extractMetadata, which does CrossRef/DOI lookups
over the network, so every debounced write, staged-deletion commit and inbound event waits behind
each lookup. Dropping several PDFs into the folder delays write-back by the total lookup time, and
shutdown's 2-second awaitTermination can expire while lookups still run against a library that
is closing.
Code

jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[R657-660]

+            // Metadata extraction may hit the network, so it runs without this synchronizer's
+            // monitor: flush and shutdown on the UI thread must never wait for it
+            syncExecutor.execute(() -> enrichStub(stub, pdf));
+        });
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Network-bound PDF metadata extraction runs on the synchronizer's only thread, so write-back and inbound sync are held up behind it.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/directorylibrary/DirectoryLibrarySynchronizer.java[653-669]
## Recommended Fix
Run `enrichStub` on a separate executor, for example the existing background `TaskExecutor`/`PdfEnrichmentTask` mechanism or a dedicated enrichment pool, and keep `syncExecutor` for short sync work. Shut that executor down separately.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



View low (1)
Informational
14. Last-moment write failures on close go unreported 🐞 Bug
Description
convertToLocalDatabase ignores the list of unwritable files that
DirectoryLibrarySynchronizer.shutdown() now returns. requestClose flushes only dirtyFiles;
events still queued on the sync executor, such as the last keystroke or a brand-new entry's sidecar
assignment, are written only by this final drain-and-flush, so a failure there drops the user's
change with only a log line.
Code

jablib/src/main/java/org/jabref/model/database/BibDatabaseContext.java[R351-355]

       if (directorySynchronizer != null) {
+            // Flushes pending sidecar writes and stops the directory watcher
           directorySynchronizer.shutdown();
-            directorySynchronizer = null;
+            this.directorySynchronizer = null;
       }
Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Write failures from the final shutdown flush are discarded, and the close check does not cover events still queued on the sync executor.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/model/database/BibDatabaseContext.java[344-355]
- jabgui/src/main/java/org/jabref/gui/LibraryTab.java[869-878]
## Recommended Fix
Make `flush()` (or a new public method) drain the queued events on the sync executor before writing, so `requestClose` sees every change. At minimum, log or return the result of `shutdown()` in `convertToLocalDatabase` as a warning.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Tip of the day
💡 Did you know, you can reply 'qodo' on any finding to push back, ask questions, or dig deeper

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant