• Restructure jabkit CLI with new check parent command grouping consistency and integrity checks
• Accept input files as positional arguments with --input as backward-compatible alias
• Add errorformat output format to consistency check, making it default for both checks
• Support running both checks together via jabkit check <file> without subcommand
• Refactor commands to use shared InputOption mixin and return exit codes consistently

New parent command grouping consistency and integrity checks

jabkit/src/main/java/org/jabref/toolkit/commands/Check.java

Reusable mixin for positional input file argument

jabkit/src/main/java/org/jabref/toolkit/commands/InputOption.java

Refactor to use InputOption mixin and errorformat output

jabkit/src/main/java/org/jabref/toolkit/commands/CheckConsistency.java

Description

IntegrityCheckResultErrorFormatWriter.writeFindings() calls
parserResult.getFieldRange(message.entry(), message.field()) before checking whether
message.field() is null, which can trigger a NullPointerException for entry-level findings. This
violates the requirement to not pass null to methods unless explicitly required.

Code

jablib/src/main/java/org/jabref/logic/integrity/IntegrityCheckResultErrorFormatWriter.java[R26-33]

    for (IntegrityMessage message : messages) {
        ParserResult.Range fieldRange = parserResult.getFieldRange(message.entry(), message.field());
-            writer.append("%s:%d:%d: %s\n".formatted(
+            // Entry-level findings (e.g. on the citation key itself) carry only the citation key;
+            // field-level findings additionally carry the field name.
+            String location = message.entry().getCitationKey().orElse("");
+            Field field = message.field();
+            if (field != null && field != InternalField.KEY_FIELD) {
+                location += ":" + field.getName();

Evidence

PR Compliance ID 15 prohibits passing null as an argument unless explicitly required. The updated
writer checks field != null but still passes message.field() into
parserResult.getFieldRange(...) unconditionally, and ParserResult.getFieldRange(...)
dereferences field (via field.getAlias()), so null will crash at runtime.

AGENTS.md
jablib/src/main/java/org/jabref/logic/integrity/IntegrityCheckResultErrorFormatWriter.java[26-33]
jablib/src/main/java/org/jabref/logic/importer/ParserResult.java[189-205]

Agent prompt

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

## Issue description
`IntegrityCheckResultErrorFormatWriter.writeFindings()` calls `ParserResult.getFieldRange(...)` with `message.field()` even when it can be `null`, which can cause a NullPointerException.
## Issue Context
The code already treats `message.field()` as potentially `null` (see the `field != null` check), but the null-sensitive call happens before that check.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/integrity/IntegrityCheckResultErrorFormatWriter.java[26-40]

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

Description

CheckIntegrity.execute() always returns 0 even when integrity findings exist, so `jabkit check
integrity and jabkit check FILE` cannot signal findings via exit status. This contradicts the
parent check command’s documented exit-code semantics and can let CI pass with integrity problems.

Code

jabkit/src/main/java/org/jabref/toolkit/commands/CheckIntegrity.java[R89-102]

    Writer writer = new OutputStreamWriter(System.out);
    IntegrityCheckResultWriter checkResultWriter;
    switch (outputFormat.toLowerCase(Locale.ROOT)) {
-            case "errorformat" ->
-                    checkResultWriter = new IntegrityCheckResultErrorFormatWriter(writer, messages, parserResult.get(), inputFile);
-            case "txt" ->
-                    checkResultWriter = new IntegrityCheckResultTxtWriter(writer, messages);
-            case "csv" ->
+            // "txt" is kept as an alias for the errorformat output.
+            case Check.FORMAT_ERRORFORMAT,
+                 Check.FORMAT_TXT ->
+                    checkResultWriter = new IntegrityCheckResultErrorFormatWriter(writer, messages, parserResult, inputFile);
+            case Check.FORMAT_CSV ->
                checkResultWriter = new IntegrityCheckResultCsvWriter(writer, messages);
        default -> {
-                System.out.println(Localization.lang("Unknown output format '%0'.", outputFormat));
+                System.err.println(Localization.lang("Unknown output format '%0'.", outputFormat));
            return 3;
        }
    }

Evidence

The integrity check builds a messages list but returns 0 unconditionally after writing results,
while the parent check command expects 1 to represent findings and uses the max of both checks’
exit codes.

jabkit/src/main/java/org/jabref/toolkit/commands/CheckIntegrity.java[83-112]
jabkit/src/main/java/org/jabref/toolkit/commands/Check.java[50-54]

Agent prompt

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

## Issue description
`CheckIntegrity.execute(...)` collects integrity messages, writes them, and then unconditionally returns `0`. This prevents callers (including `jabkit check FILE`) from using exit codes to detect integrity findings.
## Issue Context
The parent `check` command explicitly documents `1 = findings` and combines exit codes using `Math.max(...)`, but `CheckIntegrity.execute(...)` never returns `1`.
## Fix Focus Areas
- jabkit/src/main/java/org/jabref/toolkit/commands/CheckIntegrity.java[83-112]
- jabkit/src/main/java/org/jabref/toolkit/commands/Check.java[50-54]
### Implementation notes
- After writing findings, return `messages.isEmpty() ? 0 : 1`.
- Update the `execute` Javadoc to include `1 = findings` for consistency with `Check` and `CheckConsistency`.

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

Description

IntegrityCheckResultErrorFormatWriter appends a field segment for citation-key findings emitted with
StandardField.KEY, but requirements state citation-key (entry-level) findings must carry only the
citation key. This breaks the documented citationKey[:field] shape and can confuse parsers
consuming the errorformat stream.

Code

jablib/src/main/java/org/jabref/logic/integrity/IntegrityCheckResultErrorFormatWriter.java[R26-40]

    for (IntegrityMessage message : messages) {
        ParserResult.Range fieldRange = parserResult.getFieldRange(message.entry(), message.field());
-            writer.append("%s:%d:%d: %s\n".formatted(
+            // Entry-level findings (e.g. on the citation key itself) carry only the citation key;
+            // field-level findings additionally carry the field name.
+            String location = message.entry().getCitationKey().orElse("");
+            Field field = message.field();
+            if (field != null && field != InternalField.KEY_FIELD) {
+                location += ":" + field.getName();
+            }
+            writer.append("%s:%d:%d:%s: %s\n".formatted(
                inputFile,
                fieldRange.startLine(),
                fieldRange.startColumn(),
+                    location,
                message.message()));

Evidence

The requirements explicitly define that citation-key findings are entry-level and must carry only
the citation key; however, duplicate-key findings use StandardField.KEY and the writer appends the
field name for anything except InternalField.KEY_FIELD.

docs/requirements/cli.md[28-36]
jablib/src/main/java/org/jabref/logic/integrity/CitationKeyDuplicationChecker.java[21-32]
jablib/src/main/java/org/jabref/logic/integrity/IntegrityCheckResultErrorFormatWriter.java[23-41]

Agent prompt

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

## Issue description
`IntegrityCheckResultErrorFormatWriter` only suppresses the field name when `field == InternalField.KEY_FIELD`. Some citation-key findings use `StandardField.KEY`, so the writer appends `:key` even though the requirement says entry-level findings on the citation key must not include a field segment.
## Issue Context
`CitationKeyDuplicationChecker` emits `IntegrityMessage(..., StandardField.KEY)` for duplicate citation keys.
## Fix Focus Areas
- jablib/src/main/java/org/jabref/logic/integrity/IntegrityCheckResultErrorFormatWriter.java[23-41]
- jablib/src/main/java/org/jabref/logic/integrity/CitationKeyDuplicationChecker.java[21-32]
- docs/requirements/cli.md[28-36]
### Implementation notes
- Treat `StandardField.KEY` the same as `InternalField.KEY_FIELD` for formatting (do not append `:field`).
- Optionally, for key-level findings use `parserResult.getCompleteEntryIndicator(entry)` for the range, to avoid depending on field-alias resolution for `StandardField.KEY`.

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

Description

Multiple JBang launchers were changed from //JAVA 25+ to //JAVA 25, which may prevent running
with newer JDKs and conflicts with the repository requirement to use JDK 25+. This can reduce
forward-compatibility of the scripts in CI and developer environments.

Code

.jbang/JabKitLauncher.java[5]

+//JAVA 25

Evidence

PR Compliance ID 1 requires using JDK 25+. The diff shows the PR changed //JAVA 25+ to //JAVA 25
in launcher scripts, which weakens the '25 or later' contract expressed previously.

AGENTS.md
.jbang/JabKitLauncher.java[5-5]

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 JBang scripts now specify `//JAVA 25` instead of `//JAVA 25+`, potentially restricting execution to an exact JDK version rather than allowing JDK 25 or later.
## Issue Context
Repository compliance requires using JDK 25+.
## Fix Focus Areas
- .jbang/JabKitLauncher.java[5-5]
- .jbang/JabLsLauncher.java[5-5]
- .jbang/JabSrvLauncher.java[5-5]
- jablib-examples/jbang/doi_to_bibtex.java[14-14]
- jablib-examples/jbang/ieee_pdf_references_to_bibtex.java[13-13]

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

Description

PdfUpdate prints fatal import/parse errors to stdout while returning non-zero exit codes, mixing
errors into the normal output stream. Other commands in this PR route equivalent failures to stderr,
so PdfUpdate remains inconsistent for scripting and tooling.

Code

jabkit/src/main/java/org/jabref/toolkit/commands/PdfUpdate.java[R75-82]

    if (parserResult.isEmpty()) {
        System.out.println(Localization.lang("Unable to open file '%0'.", inputFile));
-            return;
+            return 2;
    }
    if (parserResult.get().isInvalid()) {
        System.out.println(Localization.lang("Input file '%0' is invalid and could not be parsed.", inputFile));
-            return;
+            return 2;

Evidence

PdfUpdate uses stdout for import errors, while Convert (and other updated commands) uses stderr for
the same failure cases, indicating PdfUpdate was missed and remains inconsistent.

jabkit/src/main/java/org/jabref/toolkit/commands/PdfUpdate.java[69-83]
jabkit/src/main/java/org/jabref/toolkit/commands/Convert.java[59-68]

Agent prompt

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

## Issue description
`PdfUpdate.call()` prints file-open / invalid-input failures using `System.out.println(...)` even though these are fatal errors (exit code 2). This makes it harder to separate normal output from errors in pipelines.
## Issue Context
Several other commands updated in this PR already use `System.err.println(...)` for the same error paths.
## Fix Focus Areas
- jabkit/src/main/java/org/jabref/toolkit/commands/PdfUpdate.java[69-83]
- jabkit/src/main/java/org/jabref/toolkit/commands/Convert.java[59-68]
### Implementation notes
- Replace the two `System.out.println(...)` calls in the error paths with `System.err.println(...)`.
- (Optional) Consider reusing the shared `importBibtexLibrary(...)` helper to standardize message + exit-code handling.

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

Description

The modified consistency- and integrity-check flows use Optional.isEmpty() followed by
Optional.get(), which is discouraged by the Optional-control-flow compliance rule. This pattern is
unnecessarily verbose and increases the risk of unsafe get() usage during future edits or
refactors.

Code

jabkit/src/main/java/org/jabref/toolkit/commands/CheckConsistency.java[R53-60]

   Optional<ParserResult> parserResult = JabKit.importFile(
           inputFile,
           "bibtex",
           jabKit.cliPreferences,
-                sharedOptions.porcelain);
+                porcelain);
   if (parserResult.isEmpty()) {
       System.out.println(Localization.lang("Unable to open file '%0'.", inputFile));
       return 2;

Evidence

PR Compliance ID 29 forbids using isPresent()/isEmpty() checks paired with get() in the same
control flow in new or modified code. In CheckConsistency.execute, the code checks
parserResult.isEmpty() and then calls parserResult.get() multiple times, and in
CheckIntegrity.execute, it similarly checks parserResult.isEmpty() and later calls
parserResult.get(), including when creating the writer, demonstrating the prohibited pattern in
both modified paths.

jabkit/src/main/java/org/jabref/toolkit/commands/CheckConsistency.java[53-84]
jabkit/src/main/java/org/jabref/toolkit/commands/CheckIntegrity.java[64-105]
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
New/modified code uses `Optional.isEmpty()` and then `Optional.get()`, violating the Optional-control-flow compliance rule.
## Issue Context
PR Compliance ID 29 requires idiomatic Optional control flow (e.g., `map`, `ifPresentOrElse`, `orElseThrow`) instead of manual presence checks followed by `get()`, because the latter is verbose and can be accidentally made unsafe during later changes.
## Fix Focus Areas
- jabkit/src/main/java/org/jabref/toolkit/commands/CheckConsistency.java[53-83]
- jabkit/src/main/java/org/jabref/toolkit/commands/CheckIntegrity.java[64-105]

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