Extract references from related work section (Part 1)

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

@@ -0,0 +1,18 @@
+package org.jabref.logic.relatedwork;
+
+import java.util.Optional;
+
+import org.jabref.model.FieldChange;
+
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+public record RelatedWorkInsertionResult(
+        RelatedWorkMatchResult matchResult,
+        RelatedWorkInsertionStatus status,
+        Optional<FieldChange> fieldChange
+) {
+    public boolean success() {
+        return status == RelatedWorkInsertionStatus.INSERTED || status == RelatedWorkInsertionStatus.UNCHANGED;
+    }
+}

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

@@ -0,0 +1,10 @@
+package org.jabref.logic.relatedwork;
+
+/// INSERTED: Insert successfully
+/// UNCHANGED: [citation-key]: xxxxx already exists, do not insert
+/// SKIPPED: Cannot find a matched related work
+public enum RelatedWorkInsertionStatus {
+    INSERTED,
+    UNCHANGED,
+    SKIPPED,
+}

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

@@ -0,0 +1,21 @@
+package org.jabref.logic.relatedwork;
+
+import java.util.Optional;
+
+import org.jabref.model.entry.BibEntry;
+
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+/// parsedReference: parsed bib entry in Reference section
+/// matchedLibraryBibEntry: matched bib entry in the library
+public record RelatedWorkMatchResult(
+        String contextText,
+        String citationKey,
+        BibEntry parsedReference,
+        Optional<BibEntry> matchedLibraryBibEntry
+) {
+    public boolean hasMatchedLibraryEntry() {
+        return matchedLibraryBibEntry.isPresent();
+    }
+}

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

@@ -0,0 +1,72 @@
+package org.jabref.logic.relatedwork;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import org.jabref.logic.FilePreferences;
+import org.jabref.logic.importer.ParserResult;
+import org.jabref.logic.importer.fileformat.pdf.RuleBasedBibliographyPdfImporter;
+import org.jabref.model.database.BibDatabaseContext;
+import org.jabref.model.entry.BibEntry;
+import org.jabref.model.entry.LinkedFile;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+public class RelatedWorkReferenceResolver {
+
+    private final RuleBasedBibliographyPdfImporter bibliographyPdfImporter;
+
+    public RelatedWorkReferenceResolver() {
+        this.bibliographyPdfImporter = new RuleBasedBibliographyPdfImporter();
+    }
+
+    /// 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 {
+        Path pdfPath = resolvePdfPath(linkedFile, databaseContext, filePreferences);
+        List<BibEntry> parsedEntries = parseReferenceEntries(pdfPath);
+
+        Map<String, BibEntry> entriesByMarker = new HashMap<>();
+        for (BibEntry parsedEntry : parsedEntries) {
+            Optional<String> citationKey = parsedEntry.getCitationKey();
+            if (citationKey.isPresent()) {
+                String citationMarker = "[" + citationKey.get() + "]";
+                entriesByMarker.putIfAbsent(citationMarker, parsedEntry);
+            }
+        }
+
+        return entriesByMarker;
+    }
+
+    /// Get absolute path of PDF file
+    private Path resolvePdfPath(LinkedFile linkedFile,
+                                BibDatabaseContext databaseContext,
+                                FilePreferences filePreferences) {
+        Optional<Path> resolvedPath = linkedFile.findIn(databaseContext, filePreferences);
+
+        return resolvedPath.get();
+    }
+
+    /// Locate Reference section and parse references
+    ///
+    /// @param pdfPath Absolute path of PDF file
+    /// @return List of reference entries
+    public List<BibEntry> parseReferenceEntries(Path pdfPath) throws IOException {
+        try (PDDocument document = Loader.loadPDF(pdfPath.toFile())) {
+            ParserResult parserResult = bibliographyPdfImporter.importDatabase(pdfPath, document);
+
+            return List.copyOf(parserResult.getDatabase().getEntries());
+        }
+    }
+}

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

@@ -0,0 +1,138 @@
+package org.jabref.logic.relatedwork;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Optional;
+
+import org.jabref.logic.FilePreferences;
+import org.jabref.logic.database.DuplicateCheck;
+import org.jabref.logic.os.OS;
+import org.jabref.model.FieldChange;
+import org.jabref.model.database.BibDatabaseContext;
+import org.jabref.model.entry.BibEntry;
+import org.jabref.model.entry.LinkedFile;
+import org.jabref.model.entry.field.UserSpecificCommentField;
+
+public class RelatedWorkService {
+
+    private final RelatedWorkTextParser relatedWorkTextParser;
+    private final RelatedWorkReferenceResolver relatedWorkReferenceResolver;
+    private final DuplicateCheck duplicateCheck;
+
+    public RelatedWorkService(RelatedWorkTextParser relatedWorkTextParser, RelatedWorkReferenceResolver relatedWorkReferenceResolver, DuplicateCheck duplicateCheck) {
+        this.relatedWorkTextParser = relatedWorkTextParser;
+        this.relatedWorkReferenceResolver = relatedWorkReferenceResolver;
+        this.duplicateCheck = duplicateCheck;
+    }
+
+    /// Try to find a matched bib entry in library
+    ///
+    /// @param sourceEntry selected bib entry in library
+    /// @return List of matched result
+    public List<RelatedWorkMatchResult> matchRelatedWork(BibEntry sourceEntry,
+                                                         String relatedWorkText,
+                                                         LinkedFile linkedFile,
+                                                         BibDatabaseContext databaseContext,
+                                                         FilePreferences filePreferences) throws IOException {
+        List<RelatedWorkSnippet> relatedWorkSnippets = relatedWorkTextParser.parseRelatedWork(relatedWorkText);
+        if (relatedWorkSnippets.isEmpty()) {
+            return List.of();
+        }
+
+        Map<String, BibEntry> parsedReferencesByMarker = relatedWorkReferenceResolver.parseReferences(linkedFile, databaseContext, filePreferences);
+
+        return createMatchResults(sourceEntry, relatedWorkSnippets, parsedReferencesByMarker, databaseContext);
+    }
+
+    /// Insert {comment-username} to bib entry
+    ///
+    /// @return List of insertion result
+    public List<RelatedWorkInsertionResult> insertMatchedRelatedWork(BibEntry sourceEntry,
+                                                                     List<RelatedWorkMatchResult> matchResults,
+                                                                     String userName) {
+        String sourceCitationKey = sourceEntry.getCitationKey().get();
+
+        UserSpecificCommentField userSpecificCommentField = new UserSpecificCommentField(normalizeOwner(userName));
+        List<RelatedWorkInsertionResult> insertionResults = new ArrayList<>(matchResults.size());
+
+        for (RelatedWorkMatchResult matchResult : matchResults) {
+            if (matchResult.matchedLibraryBibEntry().isEmpty()) {
+                insertionResults.add(new RelatedWorkInsertionResult(
+                        matchResult,
+                        RelatedWorkInsertionStatus.SKIPPED,
+                        Optional.empty()
+                ));
+                continue;
+            }
+
+            Optional<FieldChange> fieldChange = appendRelatedWorkComment(
+                    sourceCitationKey,
+                    matchResult.contextText(),
+                    matchResult.matchedLibraryBibEntry().get(),
+                    userSpecificCommentField
+            );
+            insertionResults.add(new RelatedWorkInsertionResult(
+                    matchResult,
+                    fieldChange.isPresent() ? RelatedWorkInsertionStatus.INSERTED : RelatedWorkInsertionStatus.UNCHANGED,
+                    fieldChange
+            ));
+        }
+
+        return insertionResults;
+    }
+
+    private List<RelatedWorkMatchResult> createMatchResults(BibEntry sourceEntry,
+                                                            List<RelatedWorkSnippet> relatedWorkSnippets,
+                                                            Map<String, BibEntry> referencesByMarker,
+                                                            BibDatabaseContext databaseContext) {
+        List<RelatedWorkMatchResult> matchResults = new ArrayList<>(relatedWorkSnippets.size());
+
+        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
+            ));
+        }
+
+        return matchResults;
+    }
+
+    /// Find duplicate entry in library by parsedReference
+    private Optional<BibEntry> findDuplicateBibEntry(BibEntry sourceEntry,
+                                                     BibEntry parsedReference,
+                                                     BibDatabaseContext databaseContext) {
+        return duplicateCheck.containsDuplicate(databaseContext.getDatabase(), parsedReference, databaseContext.getMode())
+                             .filter(duplicateEntry -> !duplicateEntry.getId().equals(sourceEntry.getId()));
+    }
+
+    /// Insert comment-{username} to target bib entry
+    /// If comment-{username} not exist, then create a new field; Otherwise append it and separate by an empty line.
+    ///
+    /// @param userSpecificCommentField comment-{username}
+    /// @return FieldChange represents if the field is changed
+    private Optional<FieldChange> appendRelatedWorkComment(String sourceCitationKey,
+                                                           String contextText,
+                                                           BibEntry matchedLibraryEntry,
+                                                           UserSpecificCommentField userSpecificCommentField) {
+        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);
+    }
+
+    /// John Doe -> john-doe
+    /// Test -> test
+    private String normalizeOwner(String userName) {
+        return userName.toLowerCase(Locale.ROOT).replaceAll("[^a-z0-9]", "-");
+    }
+}

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

@@ -0,0 +1,7 @@
+package org.jabref.logic.relatedwork;
+
+public record RelatedWorkSnippet(
+        String contextText,
+        String citationMarker
+) {
+}

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

@@ -0,0 +1,64 @@
+package org.jabref.logic.relatedwork;
+
+import java.util.List;
+import java.util.regex.MatchResult;
+import java.util.regex.Pattern;
+
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+public class RelatedWorkTextParser {
+    private static final Pattern SINGLE_CITE_PATTERN = Pattern.compile("\\[(\\d{1,3})\\]");
+    private static final Pattern SEGMENT_SPLIT_PATTERN = Pattern.compile("(?<=[.!?])\\s+");
+    private static final Pattern HYPHENATED_LINE_BREAK_PATTERN = Pattern.compile("-\\R");
+    private static final Pattern NEWLINE_WITHOUT_SENTENCE_END_PATTERN = Pattern.compile("(?<![.:])\\R");
+    private static final Pattern WHITESPACE_PATTERN = Pattern.compile("\\s+");
+    private static final Pattern SPACE_BEFORE_PUNCTUATION_PATTERN = Pattern.compile("\\s+([,.;:!?])");
+    private static final Pattern TRAILING_CONJUNCTION_WITH_PUNCTUATION_PATTERN = Pattern.compile("\\s+(?:and|or)([.?!])$", Pattern.CASE_INSENSITIVE);
+    private static final Pattern TRAILING_CONJUNCTION_PATTERN = Pattern.compile("\\s+(?:and|or)$", Pattern.CASE_INSENSITIVE);
+
+    /// This method first cuts long texts into separate sentence segments, and then parse these sentences.
+    public List<RelatedWorkSnippet> parseRelatedWork(String text) {
+        String normalizedText = getNormalText(text);
+
+        return SEGMENT_SPLIT_PATTERN.splitAsStream(normalizedText)
+                                    .filter(segment -> !segment.isBlank())
+                                    .map(this::parseTextSegment)
+                                    .flatMap(List::stream)
+                                    .toList();
+    }
+
+    /// Parse a sentence into citationKeys and text.
+    public List<RelatedWorkSnippet> parseTextSegment(String text) {
+        List<String> citationMarkers = SINGLE_CITE_PATTERN.matcher(text)
+                                                          .results()
+                                                          .map(MatchResult::group)
+                                                          .toList();
+
+        if (citationMarkers.isEmpty()) {
+            return List.of();
+        }
+
+        String contextText = extractContextText(text);
+
+        return citationMarkers.stream()
+                              .map(citationMarker -> new RelatedWorkSnippet(contextText, citationMarker))
+                              .toList();
+    }
+
+    /// Remove citationKeys
+    private String extractContextText(String text) {
+        text = SINGLE_CITE_PATTERN.matcher(text).replaceAll(" ");
+        text = WHITESPACE_PATTERN.matcher(text.trim()).replaceAll(" ");
+        text = SPACE_BEFORE_PUNCTUATION_PATTERN.matcher(text).replaceAll("$1");
+        text = TRAILING_CONJUNCTION_WITH_PUNCTUATION_PATTERN.matcher(text).replaceAll("$1");
+        return TRAILING_CONJUNCTION_PATTERN.matcher(text).replaceAll("").trim();
+    }
+
+    /// Some long words may contain a hyphen and a newline symbol. This method transforms these words into normal ones.
+    public String getNormalText(String text) {
+        text = HYPHENATED_LINE_BREAK_PATTERN.matcher(text).replaceAll("");
+        text = NEWLINE_WITHOUT_SENTENCE_END_PATTERN.matcher(text).replaceAll(" ");
+        return WHITESPACE_PATTERN.matcher(text.trim()).replaceAll(" ");
+    }
+}