Fix/date fallback file finder

[jadegold55]

Related issues and pull requests

Closes #8152

PR Description

1. Added a check in findAssociatedFiles that detects if [DATE] is contained in regex. If it is use strict matching first and fallback to more broad cases after.
2. If an exact date match (YYYY-MM-DD) is found the search stops there. If not, it tries year-month (YYYY-MM), then year-only (YYYY) before returning empty.
3. If there is no [DATE] field, it will fall back to constructing separate YEAR, MONTH, DAY fields.

Note: This addresses solution 2 outlined in #8152 and does not fix [YEAR], instead addresses it using [DATE] strict matching.

Bibtex after:

bibtext-year-month.mp4

Biblatex after:

biblatex-allcases.mp4

Steps to test

1. Open JabRef, create a new library in either BibTeX or BibLaTeX
2. Create multiple pdf files named with dates in a test folder
3. Go to File -> Preferences -> Linked Files in Jabref
4. Set the file regex search pattern to **/.*[DATE].*\\.[extension]
5. Set main directory to your test folder
6. Add an entry and set the date/year/ month field to a date that will match the file name in any kind of strictness (for BibTeX there is an option field with month)
7. Click on entry
8. Press F7, files are linked

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]

Review Summary by Qodo

Add date fallback search for file finder patterns

✨ Enhancement 🧪 Tests

Walkthroughs

Description

• Implement fallback search for [DATE] patterns in file finder
  - Tries exact date (YYYY-MM-DD) first, then year-month (YYYY-MM), then year-only (YYYY)
  - Constructs date from year, month, day fields if date field absent
  - Handles BibTeX month strings and date ranges
• Add comprehensive parameterized tests for date fallback behavior
• Refactor test code for improved readability and maintainability

Diagram

flowchart LR
  A["[DATE] pattern detected"] --> B["Get date candidates"]
  B --> C["Extract from date field"]
  B --> D["Construct from year/month/day"]
  C --> E["Build candidates list"]
  D --> E
  E --> F["Try exact match YYYY-MM-DD"]
  F --> G{Match found?}
  G -->|Yes| H["Return results"]
  G -->|No| I["Try YYYY-MM"]
  I --> J{Match found?}
  J -->|Yes| H
  J -->|No| K["Try YYYY"]
  K --> L{Match found?}
  L -->|Yes| H
  L -->|No| M["Return empty"]

Loading

File Changes

1. jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java ✨ Enhancement +73/-11

Implement date fallback search logic

• Added DATE_MARKER_PATTERN to detect [DATE] patterns (case-insensitive)
• Implemented getDateFallbackCandidates() method to generate date candidates in decreasing
 specificity
• Modified findAssociatedFiles() to use fallback logic when [DATE] pattern is detected
• Handles date field directly, or constructs from year/month/day fields with BibTeX month string
 normalization
• Supports date ranges by extracting start date before slash
• Added imports for Arrays, Optional, Month, and StandardField

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java

---

2. jablib/src/test/java/org/jabref/logic/util/io/RegExpBasedFileFinderTest.java 🧪 Tests +71/-14

Add comprehensive date fallback tests

• Added parameterized test dateFallbackBehavior() covering 7 scenarios for date fallback matching
• Added parameterized test dateFallbackFromYearMonthFieldsWhenNoDateField() for year/month field
 handling
• Added test nonDatePatternUnaffectedByFallbackLogic() to verify non-DATE patterns unchanged
• Refactored test code formatting for improved readability
• Added imports for ParameterizedTest and CsvSource

jablib/src/test/java/org/jabref/logic/util/io/RegExpBasedFileFinderTest.java

---

3. CHANGELOG.md 📝 Documentation +1/-0

Document date fallback feature

• Added entry documenting the new date fallback search feature for [DATE] patterns
• References issue #8152
• Describes progressive fallback from exact date to year-only matching

CHANGELOG.md

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (4) 📘 Rule violations (3) 📎 Requirement gaps (0) 📐 Spec deviations (0)

1. setField used on new BibEntry 📘 Rule violation ⚙ Maintainability ⭐ New

Description

The new fallback logic creates a new BibEntry and mutates it using setField, which violates the
project convention to use withField when constructing/updating newly created BibEntry objects.
This increases inconsistency and makes it easier to accidentally mix mutable and wither-based
styles.

Code

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[R87-94]

+            List<String> candidates = getDateFallbackCandidates(entry);
+            for (String candidate : candidates) {
+                BibEntry entryWithCandidate = new BibEntry(entry);
+                entryWithCandidate.setField(StandardField.DATE, candidate);
+                List<Path> results = new ArrayList<>();
+                for (Path directory : directories) {
+                    results.addAll(findFile(entryWithCandidate, directory, this.regExp, extensionRegExp));
+                }

Evidence

PR Compliance ID 32 requires using withField instead of setField when creating new BibEntry
objects. The added code creates entryWithCandidate via new BibEntry(entry) and then calls
entryWithCandidate.setField(StandardField.DATE, candidate).

AGENTS.md
jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[87-94]

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 constructs a new `BibEntry` and uses `setField` to set `StandardField.DATE`, but project conventions require using `withField` when creating/updating newly created `BibEntry` objects.

## Issue Context
This occurs in the new `[DATE]` fallback logic while iterating over date candidates.

## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[87-94]

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

---

2. Optional converted to empty string 📘 Rule violation ✓ Correctness ⭐ New

Description

getDateFallbackCandidates uses orElseGet to fabricate an empty-string sentinel and then relies
on isEmpty() checks and isPresent()/get() branching. This is non-idiomatic Optional usage and
can obscure the absence/presence contract for date construction.

Code

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[R114-139]

+        Optional<String> year = entry.getField(StandardField.YEAR);
+        Optional<String> month = entry.getField(StandardField.MONTH);
+        Optional<String> day = entry.getField(StandardField.DAY);
+
+        String date = entry.getField(StandardField.DATE).orElseGet(() -> {
+            if (year.isEmpty()) {
+                return "";
+            }
+            if (month.isPresent() && day.isPresent()) {
+                return year.get() + "-" + month.get() + "-" + day.get();
+            }
+            if (month.isPresent()) {
+                String monthNum = Month.parse(month.get()).map(Month::getTwoDigitNumber).orElse(month.get());
+                return year.get() + "-" + monthNum;
+            }
+            return year.get();
+        });
+
+        // Handle date ranges (e.g. "2021-01-01/2021-12-31") — use only the start date
+        if (date.contains("/")) {
+            date = date.substring(0, date.indexOf('/'));
+        }
+
+        if (date.isEmpty()) {
+            return new ArrayList<>();
+        }

Evidence

PR Compliance ID 12 forbids converting Optional values into sentinel empty strings (e.g., via
orElse("")) and prefers idiomatic Optional handling patterns. The added code uses
entry.getField(StandardField.DATE).orElseGet(() -> { ... return ""; }) and then checks
date.isEmpty() to represent missing values.

AGENTS.md
jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[114-139]

Agent prompt

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

## Issue description
`getDateFallbackCandidates` converts an Optional into an empty-string sentinel and then branches on `date.isEmpty()`, which violates the project's Optional usage conventions.

## Issue Context
The method builds fallback candidates for `[DATE]` matching. It should keep absence/presence encoded as `Optional` (or use `ifPresentOrElse`) rather than using `""` as a missing-value marker.

## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[114-139]

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

---

3. CHANGELOG has #TODO link ☑ 📘 Rule violation ⚙ Maintainability

Description

The new CHANGELOG entry includes a placeholder issue reference/link ([#TODO](.../TODO)), which is
not a valid or professional user-facing reference. This can break release-note traceability and
violates documentation formatting expectations.

Code

CHANGELOG.md[14]

+- We added fallback search for `[DATE]` patterns in the file finder, so that if an exact date match is not found, progressively less specific dates (year-month, then year) are tried. [#TODO](https://github.com/JabRef/jabref/issues/TODO)

Evidence

The checklist requires user-facing release notes to be professionally written and to use valid,
consistently formatted issue references; the added line uses a TODO placeholder instead of a real
issue number/link.

AGENTS.md
CHANGELOG.md[14-14]
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
A new CHANGELOG entry contains a placeholder issue link `[#TODO](https://github.com/JabRef/jabref/issues/TODO)`, which is invalid and not acceptable in release notes.
## Issue Context
Release notes should reference the actual issue/PR number (e.g., `[#8152](https://github.com/JabRef/jabref/issues/8152)`) to keep documentation professional and traceable.
## Fix Focus Areas
- CHANGELOG.md[14-14]

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

---

View more (3)

4. Case-sensitive [DATE] detection 🐞 Bug ✓ Correctness

Description

findAssociatedFiles only enables the new fallback when the pattern literally contains "[DATE]", so
patterns like "[date]" skip fallback entirely. Because field-name parsing is case-insensitive
elsewhere, this makes fallback inconsistent and leaves the bug unfixed for common lowercase
patterns.

Code

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[R85-88]

+        if (this.regExp.contains("[DATE]")) {
+            List<String> candidates = getDateFallbackCandidates(entry);
+            for (String candidate : candidates) {
+                String patternWithCandidate = this.regExp.replace("[DATE]", candidate);

Evidence

The fallback gate is a case-sensitive substring check ("[DATE]"). However, field name resolution is
case-insensitive (StandardField.fromName lowercases input), and existing file-finder patterns in
tests commonly use lowercase markers (e.g., [year], [citationkey]). Therefore, a user pattern
containing [date] will expand normally but will not benefit from the new fallback behavior.

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[83-100]
jablib/src/main/java/org/jabref/model/entry/field/StandardField.java[158-176]
jablib/src/test/java/org/jabref/logic/util/io/RegExpBasedFileFinderTest.java[52-75]

Agent prompt

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

## Issue description
`RegExpBasedFileFinder.findAssociatedFiles` only triggers date fallback when the regex contains the exact substring `[DATE]`. Patterns using other casing (e.g. `[date]`) will not use the new fallback logic.
### Issue Context
Field names are parsed case-insensitively elsewhere (e.g. `StandardField.fromName` lowercases input), and existing patterns in tests already use lowercase markers like `[year]`.
### Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[83-100]
- jablib/src/main/java/org/jabref/model/entry/field/StandardField.java[158-176]
### Suggested fix
Use a case-insensitive marker check (e.g. `Pattern.compile("\\[(?i:date)\\]")`) and ensure replacement (if still used) also replaces any casing variant. Add/extend a unit test proving `[date]` triggers the fallback behavior.

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

---

5. Date range breaks path 🐞 Bug ✓ Correctness

Description

The fallback replaces the [DATE] marker in the raw pattern string before the path is split on "/";
if the date contains "/" (valid for date ranges), it is incorrectly treated as a directory
separator. This can make the search traverse the wrong path segments and fail to find matching
files.

Code

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[R88-92]

+                String patternWithCandidate = this.regExp.replace("[DATE]", candidate);
+                List<Path> results = new ArrayList<>();
+                for (Path directory : directories) {
+                    results.addAll(findFile(entry, directory, patternWithCandidate, extensionRegExp));
+                }

Evidence

The new logic does regExp.replace("[DATE]", candidate) and passes it into findFile, which splits
the *raw* pattern on / into directory parts before any bracket expansion. JabRef’s Date.parse
explicitly supports date ranges "two dates separated by '/'", so a legitimate DATE value can contain
'/', which would be safe under normal bracket-expansion (since expansion happens after splitting)
but becomes unsafe when injected into the raw pattern string first.

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[85-99]
jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[176-205]
jablib/src/main/java/org/jabref/model/entry/Date.java[72-79]
jablib/src/main/java/org/jabref/model/entry/Date.java[134-150]

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 fallback currently injects the date candidate directly into the raw file-finder pattern string. If the candidate contains `/` (supported by JabRef for date ranges), it will be interpreted as a path separator by `findFile` (which splits on `/` before bracket expansion), causing incorrect traversal and missed matches.
### Issue Context
`Date.parse` supports date ranges with two dates separated by `/`, so `/` can appear in a valid `date` field value.
### Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[83-99]
- jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[176-205]
- jablib/src/main/java/org/jabref/model/entry/Date.java[72-79]
- jablib/src/main/java/org/jabref/model/entry/Date.java[134-150]
### Suggested fix
Do not replace `[DATE]` inside the raw pattern. Instead, keep the original `regExp` and run the existing bracket-expansion pipeline with a per-candidate entry value. A simple approach:
- For each candidate, create `BibEntry entryWithCandidate = new BibEntry(entry)` and set `StandardField.DATE` to the candidate.
- Call the existing `findFile(entryWithCandidate, directory, this.regExp, extensionRegExp)` (or `findFile(entryWithCandidate, directories, extensionRegExp)`) so expansion happens after path splitting.
Also add a unit test with a DATE value containing `/` to prevent regressions.

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

---

6. Month/day not normalized 🐞 Bug ✓ Correctness

Description

getDateFallbackCandidates normalizes MONTH to two digits only for the year-month case, but not for
the year-month-day case. This can generate candidates like "2021-#jul#-7" that will never match
common ISO-style filenames like "2021-07-07".

Code

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[R121-129]

+            if (month.isPresent() && day.isPresent()) {
+                return year.get() + "-" + month.get() + "-" + day.get();
+            }
+            if (month.isPresent()) {
+                String monthNum = Month.parse(month.get())
+                                       .map(Month::getTwoDigitNumber)
+                                       .orElse(month.get());
+                return year.get() + "-" + monthNum;
+            }

Evidence

Month.parse supports both numeric and BibTeX month-string formats (including #jul#) and can
produce a two-digit month number. The code uses this normalization only when day is absent,
leaving the month && day branch to emit raw values that won’t match ISO-like filenames.

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[117-131]
jablib/src/main/java/org/jabref/model/entry/Month.java[64-98]
jablib/src/main/java/org/jabref/model/entry/Month.java[184-189]

Agent prompt

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

## Issue description
When building a fallback date from YEAR+MONTH+DAY, the code concatenates the raw month/day values without normalization. This breaks strict matching for BibTeX month strings (e.g., `#jul#`) and for single-digit values.
### Issue Context
`Month.parse` already handles `#jul#`, `7`, and `07` and can output a two-digit month (`getTwoDigitNumber`). Day likely needs similar normalization when it’s numeric.
### Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[117-131]
- jablib/src/main/java/org/jabref/model/entry/Month.java[64-98]
### Suggested fix
In the `month.isPresent() && day.isPresent()` branch:
- Normalize `month` using `Month.parse(...).map(Month::getTwoDigitNumber).orElse(originalMonth)`.
- Normalize `day` when it’s numeric (e.g., parse int and format `%02d`), otherwise leave as-is.
Add a test case covering YEAR+MONTH+DAY with `month=#jul#` and/or `day=7` expecting to find `YYYY-07-07.pdf`.

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

---

7. Escaped [DATE] breaks search 🐞 Bug ✓ Correctness ⭐ New

Description

findAssociatedFiles enters the [DATE] fallback branch whenever the raw pattern contains "[DATE]"
(even if it is escaped as a literal), and if no date candidates exist it returns an empty list
without executing the normal file search. This can cause patterns intending a literal "[DATE]"
(escaped via "\[") to stop matching files entirely when the entry has no date information.

Code

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[R85-100]

+        Matcher dateMatcher = DATE_MARKER_PATTERN.matcher(this.regExp);
+        if (dateMatcher.find()) {
+            List<String> candidates = getDateFallbackCandidates(entry);
+            for (String candidate : candidates) {
+                BibEntry entryWithCandidate = new BibEntry(entry);
+                entryWithCandidate.setField(StandardField.DATE, candidate);
+                List<Path> results = new ArrayList<>();
+                for (Path directory : directories) {
+                    results.addAll(findFile(entryWithCandidate, directory, this.regExp, extensionRegExp));
+                }
+                if (!results.isEmpty()) {
+                    return results;
+                }
+            }
+            return new ArrayList<>();
+        }

Evidence

RegExpBasedFileFinder switches to the fallback path solely based on DATE_MARKER_PATTERN.find() and
returns empty when no candidates are produced, skipping the normal findFile flow. BracketedPattern
explicitly supports escaping brackets with a backslash, meaning a user can intend a literal "[DATE]"
without placeholder expansion; the current detection does not exclude escaped markers.

jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[32-33]
jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[83-102]
jablib/src/main/java/org/jabref/logic/citationkeypattern/BracketedPattern.java[196-216]

Agent prompt

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

### Issue description
`findAssociatedFiles` detects `[DATE]` via a simple substring-regex and switches to fallback even when `[DATE]` is escaped/literal. If no date candidates are available, it returns `[]` without running the normal search.

### Issue Context
`BracketedPattern.expandBrackets` treats `\[` as an escape sequence (literal `[`), so patterns can intentionally contain a literal `[DATE]` without placeholder expansion. The fallback trigger should therefore exclude escaped occurrences, and ideally should not bypass the normal search when there are no candidates.

### Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[32-33]
- jablib/src/main/java/org/jabref/logic/util/io/RegExpBasedFileFinder.java[83-102]

### Implementation notes
- Update `DATE_MARKER_PATTERN` to ignore escaped markers, e.g. use a negative lookbehind for backslash: `(?<!\\)\[(?i:date)\]`.
- If `getDateFallbackCandidates(entry)` is empty, fall back to the existing behavior (`return findFile(entry, directories, extensionRegExp);`) instead of returning an empty list.

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

---

8. Unrelated test reformatting 📘 Rule violation ⚙ Maintainability

Description

Existing test code was reformatted into single-line statements (e.g., FILE_NAMES and a multi-line
BibEntry builder chain) without functional changes. This introduces unrelated reformatting noise
and reduces reviewability.

Code

jablib/src/test/java/org/jabref/logic/util/io/RegExpBasedFileFinderTest.java[23]

+    private static final List<String> FILE_NAMES = List.of("ACM_IEEE-CS.pdf", "pdfInDatabase.pdf", "Regexp from [A-Z].pdf", "directory/subdirectory/2003_Hippel_209.pdf", "directory/subdirectory/2017_Gražulis_726.pdf", "directory/subdirectory/pdfInSubdirectory.pdf", "directory/subdirectory/GUO ea - INORG CHEM COMMUN 2010 - Ferroelectric Metal Organic Framework (MOF).pdf");

Evidence

The compliance checklist requires avoiding unrelated reformatting; the PR changes previously
multi-line declarations into one-liners in parts not required for the new date-fallback tests/logic.

AGENTS.md
jablib/src/test/java/org/jabref/logic/util/io/RegExpBasedFileFinderTest.java[23-23]
jablib/src/test/java/org/jabref/logic/util/io/RegExpBasedFileFinderTest.java[106-106]

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 PR includes formatting-only changes (collapsing multi-line lists/builder chains into one line) that are unrelated to the functional change, increasing diff noise.
## Issue Context
Please keep formatting changes limited to the code directly impacted by the feature/fix, to preserve reviewability.
## Fix Focus Areas
- jablib/src/test/java/org/jabref/logic/util/io/RegExpBasedFileFinderTest.java[23-23]
- jablib/src/test/java/org/jabref/logic/util/io/RegExpBasedFileFinderTest.java[106-106]

ⓘ 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

[jadegold55]

While working through this issue and local testing I encountered the same bug from #8902 . When testing date range, it would truncate to starting date in the entry field on biblatex.

Update:

Can confirm this is still the case walking through steps to test the bug.

This is affecting the behavior of linking files given range of dates. If you try to link files using date regex with date range 2021-01-01/2021-12-31. It wont find any files if there are no files with 2021-01-01 in its name, which is obviously a consequence of whatever is going on with that bug, (e.g it truncates to 2021-01-01 and I'm assuming is saved as the truncated date) I might try to look at #8902 and see if I can fix it so that linking files using date regex isn't also broken as a consequence.

[Siedlerchr]

PLease keep the existing formatting; it makes it easier to understand the expression

[Siedlerchr]

pleas keep the existing formatting, this is hard to read

[jadegold55]

Will fix this and any other formatting issue today when I have time

[Siedlerchr]

same here, keep the existing formatting

[jadegold55]

addressed all occurences

[testlens-app]

✅ All tests passed ✅

🏷️ Commit: efba242
▶️ Tests: 10224 executed
⚪️ Checks: 53/53 completed

---

Learn more about TestLens at testlens.app.

[calixtus]

LGTM and tests are green. Lets move forward.