Extract references from related work section (Part 1) by pluto-han · Pull Request #15316 · JabRef/jabref

pluto-han · 2026-03-11T13:50:27Z

Related issues and pull requests

PR Description

This PR adds a new feature that lets JabRef find existing BibEntries referenced in related work text and add the corresponding descriptive text to thecomments-{username} field.

Users can now extract references from related work section in the attached PDF file, and add comment field to corresponding bib entries.

Change overview

Layer	Component	Responsibility
Model	RelatedWorkSnippet	Store parsed related work text and citation marker
	RelatedWorkMatchResult	Store parsed reference and matched bib entry
	RelatedWorkInsertionResult	Store comment insertion result
	RelatedWorkInsertionStatus	Represent insertion status
Logic	RelatedWorkTextParser	Parse related work text into citation mark and citation text
	RelatedWorkReferenceResolver	Resolve reference into a bib entry
	RelatedWorkService	Match bib entry in the library and insert comments
UI	RelatedWorkDialog.fxml	Input dialog layout
	RelatedWorkResultDialog.fxml	Result dialog layout
	RelatedWorkAction	Validate PDF and citation key
	RelatedWorkDialogView	Load PDF and citation key
	RelatedWorkResultDialogView	Load RelatedWorkMatchResult and display matched results
ViewModel	RelatedWorkDialogViewModel	Handle input and parse related work
	RelatedWorkDialogResultViewModel	Handle result preview and comment insertion

Future work in the next pr(s)

Add UI layer
Support more citation format. i.e. [1, 2, 3] / [1-3] / [1-3, 7, 9]
Support citation format (John 2026), (Lee et al. 2020; John 2026), example³

Checklist

I own the copyright of the code submitted and I license it under the MIT license
I manually tested my changes in running JabRef (always required)
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 described the change in CHANGELOG.md in a way that can be understood by the average user (if 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

qodo-free-for-open-source-projects · 2026-03-11T13:50:51Z

Review Summary by Qodo

Add related work extraction and reference matching functionality

✨ Enhancement

Walkthroughs

Description

• Adds related work extraction feature to parse citations from PDF documents
• Implements text parsing to extract citation markers and context from related work sections
• Matches parsed references against library entries using duplicate detection
• Inserts matched references as user-specific comments in target bibliography entries

Diagram

flowchart LR
  A["Related Work Text"] -->|parse| B["RelatedWorkTextParser"]
  B -->|extract snippets| C["RelatedWorkSnippet"]
  D["PDF File"] -->|parse references| E["RelatedWorkReferenceResolver"]
  E -->|extract entries| F["BibEntry References"]
  C -->|match against| F
  F -->|find duplicates| G["DuplicateCheck"]
  G -->|create match results| H["RelatedWorkMatchResult"]
  H -->|insert comments| I["RelatedWorkService"]
  I -->|generate insertion results| J["RelatedWorkInsertionResult"]

File Changes

1. jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkSnippet.java Data structure +7/-0

Record for parsed citation text snippets

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkSnippet.java

2. jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkTextParser.java ✨ Enhancement +64/-0

Parse related work text into citations and context

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkTextParser.java

3. jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkMatchResult.java Data structure +21/-0

Record for matched bibliography entry results

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkMatchResult.java

View more (7)

4. jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkInsertionStatus.java Data structure +10/-0

Enum for field insertion operation status

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkInsertionStatus.java

5. jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkInsertionResult.java Data structure +18/-0

Record for insertion operation results

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkInsertionResult.java

6. jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java ✨ Enhancement +72/-0

Extract and parse references from PDF files

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java

7. jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java ✨ Enhancement +138/-0

Orchestrate matching and insertion of related work

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java

8. jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkTextParserTest.java 🧪 Tests +129/-0

Test citation parsing and text normalization

jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkTextParserTest.java

9. jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolverTest.java 🧪 Tests +90/-0

Test PDF reference extraction and parsing

jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolverTest.java

10. jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkServiceTest.java 🧪 Tests +197/-0

Test matching and insertion workflows

jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkServiceTest.java

qodo-free-for-open-source-projects · 2026-03-11T13:50:52Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX Issues (0)

1. resolvedPath.get() unchecked access ☑ 📘 ≡

Description

resolvePdfPath calls Optional.get() without guarding for absence, which can throw at runtime
when the linked PDF cannot be resolved. This can crash related-work processing instead of handling
missing files gracefully.

Code

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java[R56-59]
+        Optional<Path> resolvedPath = linkedFile.findIn(databaseContext, filePreferences);
+
+        return resolvedPath.get();
+    }

Evidence
PR Compliance ID 46 forbids unsafe access patterns like Optional.get() when the value may be
absent. The new method returns resolvedPath.get() without any check or fallback.
jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java[56-59]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`resolvePdfPath` uses `Optional.get()` without checking presence, which can throw when the linked file cannot be resolved.
## Issue Context
This is in the new related-work logic and will be exercised for entries whose linked PDF cannot be found.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java[52-59]

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

2. sourceEntry citationKey Optional.get ☑ 📘 ≡

Description

insertMatchedRelatedWork unconditionally calls sourceEntry.getCitationKey().get(), which throws
if the source entry has no citation key. This introduces a crash path instead of a controlled result
(e.g., skipped/error).

Code

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java[R53-57]

+    public List<RelatedWorkInsertionResult> insertMatchedRelatedWork(BibEntry sourceEntry,
+                                                                     List<RelatedWorkMatchResult> matchResults,
+                                                                     String userName) {
+        String sourceCitationKey = sourceEntry.getCitationKey().get();
+

Evidence
PR Compliance ID 46 requires guarding against missing optional values and explicitly calls out
Optional.get() without guaranteed presence as a failure case. The new code uses get() with no
validation or fallback.
jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java[53-57]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`insertMatchedRelatedWork` uses `sourceEntry.getCitationKey().get()` without ensuring a citation key exists.
## Issue Context
The feature should not crash when the selected entry lacks a citation key; it should handle the missing value safely.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java[53-57]

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

3. referencesByMarker.get may return null ☑ 📘 ≡

Description

createMatchResults uses Map.get without a missing-key guard and then passes the possibly-null
parsedReference into logic and into a @NullMarked record. This can cause NullPointerExceptions
or violate the intended non-null contract when a citation marker exists in text but is not parsed
from the PDF references.

Code

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java[R93-101]

+        for (RelatedWorkSnippet relatedWorkSnippet : relatedWorkSnippets) {
+            BibEntry parsedReference = referencesByMarker.get(relatedWorkSnippet.citationMarker());
+            Optional<BibEntry> matchedLibraryEntry = findDuplicateBibEntry(sourceEntry, parsedReference, databaseContext);
+            matchResults.add(new RelatedWorkMatchResult(
+                    relatedWorkSnippet.contextText(),
+                    relatedWorkSnippet.citationMarker(),
+                    parsedReference,
+                    matchedLibraryEntry
+            ));

Evidence

PR Compliance ID 46 requires guarding against missing values instead of unsafe dereferencing; PR
Compliance ID 9 also forbids passing null as an argument in new APIs unless explicitly
intended/annotated. The new code assigns from Map.get(...) (which can be null) and then uses it
without validation.

AGENTS.md
jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java[93-101]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`referencesByMarker.get(...)` may return `null`, but the result is used immediately and passed into a `@NullMarked` record and duplicate detection.
## Issue Context
The related-work text may contain markers that are not present in the parsed references map (PDF parsing limitations, incomplete references, format differences).
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java[93-101]
- jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkMatchResult.java[12-17]

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

4. isPresent plus get usage ☑ 📘 ≡

Description

parseReferences uses isPresent() branching and then calls get() on the same Optional, which is
discouraged by the project's Optional-idiom rule. This is less idiomatic and more error-prone than
using ifPresent(...)/map(...) constructs.

Code

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java[R41-46]

+        for (BibEntry parsedEntry : parsedEntries) {
+            Optional<String> citationKey = parsedEntry.getCitationKey();
+            if (citationKey.isPresent()) {
+                String citationMarker = "[" + citationKey.get() + "]";
+                entriesByMarker.putIfAbsent(citationMarker, parsedEntry);
+            }

Evidence
PR Compliance ID 11 asks to use Optional APIs idiomatically and avoid isPresent() branching when
clearer alternatives apply. The new code uses isPresent() followed by get() rather than
ifPresent(...).
AGENTS.md
jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java[41-46]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Optional is handled via `isPresent()` branching followed by `get()`.
## Issue Context
Project guidelines prefer `ifPresent`/`ifPresentOrElse` and discourage `isPresent()` branching when a direct Optional API expresses intent more clearly.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java[41-46]

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

5. setField used in service ☑ 📘 ≡

Description

The new related-work insertion path updates a BibEntry using setField, which conflicts with the
guideline to use BibEntry withers (withField) when creating/updating entries. This reduces
consistency with the preferred immutable-style update patterns in the codebase.

Code

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java[R124-131]

+        String formattedComment = "[%s]: %s".formatted(sourceCitationKey, contextText);
+        String updatedComment = matchedLibraryEntry.getField(userSpecificCommentField)
+                                                   .filter(existingComment -> !existingComment.isBlank())
+                                                   .map(existingComment -> existingComment.stripTrailing() + OS.NEWLINE + OS.NEWLINE + formattedComment)
+                                                   .orElse(formattedComment);
+
+        return matchedLibraryEntry.setField(userSpecificCommentField, updatedComment);
+    }

Evidence
PR Compliance ID 37 states to use withField instead of setField when creating/updating
BibEntry. The new method appendRelatedWorkComment calls matchedLibraryEntry.setField(...).
AGENTS.md
jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java[124-131]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`appendRelatedWorkComment` updates `BibEntry` using `setField`, but project conventions prefer `withField` for BibEntry updates.
## Issue Context
This is new logic in `org.jabref.logic` and should align with JabRef&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;#x27;s BibEntry update conventions.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java[124-131]

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

6. ~~Nonstandard /// Java comments~~ ☑ 📘 ≡

Description

Multiple new Java files use ///-style comments for documentation, which is not typical Java/JabRef
style (Javadoc uses /** ... */). This harms consistency and may not integrate with tooling that
expects Javadoc.

Code

jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java[R30-36]

+    /// Parse references from the given PDF file
+    ///
+    /// @param linkedFile The attached PDF file of the selected bib entry
+    /// @return Map from citation key to the corresponding reference entries
+    public Map<String, BibEntry> parseReferences(LinkedFile linkedFile,
+                                                 BibDatabaseContext databaseContext,
+                                                 FilePreferences filePreferences) throws IOException {

Evidence
PR Compliance ID 6 requires following JabRef code style rules and established best practices. The
new files introduce nonstandard /// documentation comments instead of JabRef's typical Javadoc
conventions.
AGENTS.md
jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java[30-36]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
New code uses `///` comments for documentation instead of standard Javadoc style.
## Issue Context
JabRef code style and tooling typically expect Javadoc formatting for API documentation.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java[30-36]
- jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java[31-55]
- jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkTextParser.java[20-23]

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

View more (2)

7. ~~Uppercase InsertionResult variable~~ ☑ 📘 ≡

Description

A new local variable in tests is named InsertionResult starting with an uppercase letter,
deviating from Java naming conventions. This reduces consistency and readability in the test suite.

Code

jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkServiceTest.java[R108-114]

+        List<RelatedWorkInsertionResult> insertionResults = service.insertMatchedRelatedWork(sourceEntry, List.of(matchResult), "koppor");
+        RelatedWorkInsertionResult InsertionResult = insertionResults.getFirst();
+
+        assertEquals(1, insertionResults.size());
+        assertEquals(RelatedWorkInsertionStatus.INSERTED, InsertionResult.status());
+        assertFalse(InsertionResult.fieldChange().isEmpty());
+        assertEquals("[LunaOstos_2024]: Colombia is a middle-income country with a population of approximately 50 million.",

Evidence
PR Compliance ID 4 requires preserving existing naming conventions. The new test introduces a local
variable InsertionResult that does not follow lowerCamelCase.
AGENTS.md
jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkServiceTest.java[108-114]

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 local test variable is named with an uppercase first letter (`InsertionResult`), which deviates from Java naming conventions used in the codebase.
## Issue Context
Consistency in tests matters for readability and maintenance.
## Fix Focus Areas
- jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkServiceTest.java[108-114]

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

8. WIP trivial test comments ☑ 📘 ≡

Description

New tests include ///  WIP comments that do not explain rationale and add noise. This violates the
guideline that comments should explain “why” rather than act as trivial status notes.

Code

jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkTextParserTest.java[R114-123]

+    ///  WIP
+    @Test
+    void parseCommaSeparatedCitations() {
+        List<RelatedWorkSnippet> snippets = parser.parseRelatedWork("A study on the Colombian context [1,2].");
+
+        assertTrue(snippets.isEmpty());
+    }
+
+    ///  WIP
+    @Test

Evidence
PR Compliance ID 13 requires comments to explain intent/rationale (“why”) and avoid trivial
comments. The added ///  WIP comments are status markers and do not provide rationale.
AGENTS.md
jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkTextParserTest.java[114-123]

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 tests contain trivial `WIP` comments that do not explain rationale.
## Issue Context
Comments should explain why a test exists or why a limitation is currently expected, not just state status.
## Fix Focus Areas
- jablib/src/test/java/org/jabref/logic/relatedwork/RelatedWorkTextParserTest.java[114-129]

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

ⓘ The new review experience is currently in Beta. Learn more

koppor

first round of comments

Co-authored-by: Oliver Kopp <kopp.dev@gmail.com>

…r-issue-14085

pluto-han · 2026-03-12T16:03:49Z

By the way, is it better to continue the work in this pr or create a new one, because I have some ideas about UI and supporting more citation formats

calixtus

everything looks really good now. just a few small suggestions / nitpicks

…r-issue-14085

calixtus · 2026-04-10T19:35:04Z

Is this all cleared? If so, please check the check boxes. #15316 (review)

pluto-han · 2026-04-10T20:26:07Z

If so, please check the check boxes. #15316 (review)

Dumb question: It seems I cannot check the check boxes in #15316 (review). Maybe I have to "copy markdown" and do it myself?

pluto-han · 2026-04-10T20:27:42Z

When opening the dialog, the field "Related work text" should be focused.

The clipboard content should be in there
All the text should be marked (to enable easy replacement)
If possible create a requirement on this - and link your implemnentation and "Interpret Citations" to it. (Reason: We will have more dialogs like this and I don't want to re-iterate on the requirements) -- can be a follow-up.

Does not work for Add manual tests #15351

Open main-paper/main.pdf
Start tool
Paste

Garcia et al. presented a deep learning framework capable of
predicting regional temperature anomalies with 95% accuracy
from satellite imagery [2].
Click "Parse"
See "No matching references were found."

Expected: "[2]" is found.

CHANGELOG.md missing

Doesn't JabRef hihglight non-editabel fileds differently? Disabled maybe?

I miss LOGGER.debug and LOGGER.trace statements. How should users report issues "properly" so that a developer can follow?

pluto-han · 2026-04-10T20:31:43Z

If possible create a requirement on this - and link your implemnentation and "Interpret Citations" to it. (Reason: We will have more dialogs like this and I don't want to re-iterate on the requirements) -- can be a follow-up.

I will do this ~~after this PR is merged~~ NOW.

Edit: Requirement added.

Does not work for #15351

I did not check it because we still need more tests to check edge cases. (texts contain "et al.", "dr.", etc.)

I will work on generating more manual tests for #15351.

calixtus · 2026-04-10T20:49:52Z

Dumb question: It seems I cannot check the check boxes in #15316

Not dumb, my fault., I forgot that this wasn't your comment and one cannot just alter someone else comments. 😆
Just comment on it, making clear that the questions and issues risen are addressed.

subhramit · 2026-04-10T20:53:06Z

If possible create a requirement on this - and link your implemnentation and "Interpret Citations" to it. (Reason: We will have more dialogs like this and I don't want to re-iterate on the requirements) -- can be a follow-up.

Leaving this link here for future reference.

Edit - okay apparently you are coupling it with this PR itself. Good.

Addressed in scope.

ThiloteE · 2026-04-12T18:58:15Z

When I was looking at https://docs.jabref.org/advanced/entryeditor/entrylinks today, I thought wouldn't it makes sense to put some of those references into their an own bibtex field, such as cited or related?

calixtus · 2026-04-12T19:11:18Z

Please create an issue, so we can track that. As a comment, this will be lost.

Extract text about papers from "related work" sections

b4f1af6

qodo-free-for-open-source-projects bot reviewed Mar 11, 2026

View reviewed changes

Comment thread jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkReferenceResolver.java Outdated

Comment thread jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkInserter.java

Comment thread jablib/src/main/java/org/jabref/logic/relatedwork/RelatedWorkService.java Outdated

github-actions bot added the status: no-bot-comments label Mar 11, 2026