Programmatic Hayagriva writer (directory-as-library, phase 0)

[koppor]

📚 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 ← this PR
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
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 0 of the "directory as library" plan — see PLAN.md on the directory-as-library branch. Groundwork for the sidecar write-back (phase 3) and, transitively, for JabRef#10930. No issue is closed by this PR.

Implements the idea of #121 in another way.

PR Description

🤖 JabRef's Hayagriva YAML export is rewritten so that exporting an entry and importing it back returns the same data, including structured titles, author details, and any hand-written keys JabRef does not recognise. Only the fields that actually changed are rewritten, so the rest of a file is left untouched. This is the persistence groundwork the directory-as-library feature needs to update sidecar files without losing manual edits.

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

Analogies

Like honey, the shared HayagrivaMapping is slow-poured but keeps importer and exporter sweetly in sync long after this branch is forgotten. Like chocolate, the read-modify-write merge is layered: bite into a sidecar file and the structure underneath stays intact. And like the moon, the exporter shows the user the same familiar face while quietly pulling the tide for the directory-as-library feature behind it.

Steps to test

1. Import a Hayagriva file (e.g. jablib/src/test/resources/org/jabref/logic/importer/fileformat/basic.yml) via File > Import into new library.
2. Export it with File > Export > Hayagriva YAML and re-import the result: all entries come back identical.
3. Round-trip guarantees are covered by the new HayagrivaRoundTripTest (field-exact round trips for writer-authored entries plus a stability check over the upstream Hayagriva test fixture) and HayagrivaEntryWriterTest (read-modify-write preservation).

No visible UI change, hence no screenshot.

AI usage

Claude Code (model claude-fable-5).

AI CHECKLIST.md walkthrough

1. Code self-review

Nullability and control flow

• No == null / != null checks — JSpecify annotations used instead. (Exception: JsonNode.get(...) returns nullable nodes by API design; those checks match the existing, merged importer code.)
• No Objects.requireNonNull(...).
• New classes annotated with @NullMarked.
• Optional consumed with ifPresent / ifPresentOrElse / map — no isPresent() + get() blocks.
• [/] StringUtil.isBlank(...) — no null-or-blank checks needed.

Exceptions

• No catch (Exception e) — only JacksonException is caught.
• No throw new RuntimeException(...) / IllegalStateException(...) — JacksonException is wrapped into IOException.
• [/] Logged exceptions — no logging added.

Style and idioms

• New BibEntry objects built with withers in tests.
• Modern Java: List.of(), Map.ofEntries(), SequencedMap, text blocks in tests.
• Regexes use precompiled Pattern constants (TYPE_LINE_PATTERN, unchanged).
• [/] Background work — none.
• No commented-out code, no trivial comments, no AI-disclosure comments.
• Markdown Javadoc (///) with Markdown syntax.

User-facing text

• [/] No new user-facing strings (exporter display name follows the existing unlocalized exporter-name convention).
• [/] Sentence case — no new labels.
• [/] Placeholders — no new localized strings.

Security

• [/] No HTML output.

Tests

• Behavior changes in org.jabref.logic covered: HayagrivaExporterTest (golden output), HayagrivaEntryWriterTest (read-modify-write), HayagrivaRoundTripTest (symmetry), HayagrivaImporterTest kept green (now round-tripping through the programmatic exporter).
• Tests assert object contents with plain JUnit asserts, no @DisplayName, exceptions propagate, @TempDir used.

2. Verification commands

• ./gradlew :jablib:check
• ./gradlew :jablib:checkstyleMain :jablib:checkstyleTest :jablib:checkstyleJmh
• ./gradlew :jablib:modernizer
• ./gradlew --no-configuration-cache :rewriteDryRun reports no changes.
• ./gradlew :jablib:javadoc
• npx markdownlint-cli2 on the changed Markdown (CHANGELOG.md).
• [/] IntelliJ-format docker image — not runnable on this machine (no docker group membership); rewriteRun + checkstyle are clean, CI format job is the backstop.

3. Documentation

• CHANGELOG.md entry added (TODO placeholder replaced with this PR's link after creation).
• Searched jabref and jabref-koppor issues for related issues — none matched confidently; nothing closed.
• [/] Requirements doc — internal exporter reimplementation, no new user-facing feature.
• [/] Developer docs — no architecture change.

4. Pull request

• PR body built from .github/PULL_REQUEST_TEMPLATE.md, every section filled.
• All checklist items kept and marked.
• All HTML comments removed.
• PR created from a body file (via gh api, because a same-owner cross-repo head requires the head_repo parameter that gh pr create does not expose).
• CHANGELOG.md TODO placeholder replaced with the real PR link 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 (via jabkit convert --output-format hayagrivayaml, which exercises the same ExporterFactory registration as the GUI export dialog)
• 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

🤖 Generated with Claude Code