chore(mzml): annotate StaxMzMLParser BOM/prolog errors (Q8)

[ypriverol]

Summary

The Stax XML parser raises terse ParseError in XML prolog exceptions when an mzML file carries a UTF-8 BOM or a malformed encoding declaration. This is a recurring onboarding failure mode (see thomasp85/MSGFplus#8) — users see the error but not the fix.

This PR wraps the two Stax parse entry points in StaxMzMLParser.java (buildIndex and preloadAllSpectra) with a helper annotate(XMLStreamException, phase) that:

• preserves the original exception as the cause (so existing log-matching tooling keeps working)
• prepends the full mzML file path and the parse phase (index / preload)
• when the underlying message looks like a BOM / prolog / encoding failure, points the user at ThermoRawFileParser / MSConvert and docs/Troubleshooting.md, including a concrete shell recipe to detect a BOM (head -c 3 file.mzML | xxd).

No behaviour change for well-formed mzML — annotate is only reached on an exception.

Test plan

• mvn -B verify — 159 tests pass (was 141 on dev; +2 new Q8 cases — total depends on merge order with PR chore(reliability): actionable centroiding error + missedCleavages test #17/feat: -minSpectraPerThread flag, MSGFLogger, and run-manifest sidecar (Q9/Q11/Q4) #18).
• TestStaxMzMLParserErrorContext (2 cases) — BOM-prefixed mzML and garbage-prolog mzML both trigger the annotated message path.
• Original XMLStreamException kept as .getCause() and its message text is preserved verbatim in the wrapped message under "Underlying parser error: ...".

Not in this PR

Follow-ups from the landscape review queue:

• Q6 (Pr(G|P) / Pr(G|O) columns) — own PR; touches scoring output.
• Q7 (DirectPinWriter + -outputFormat pin) — own PR, 3–5 days.
• Q10 (-Xmx pre-flight warning) — own PR on top of PR feat: -minSpectraPerThread flag, MSGFLogger, and run-manifest sidecar (Q9/Q11/Q4) #18's MSGFLogger.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e92c68f3-5780-41fd-a8bc-bbb3d8edd627

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/stax-error-context

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}