fix: consult base-font metrics for character decoding when the font dict carries a /Name label

[wittjeff]

Fixes #317.

A base-14 font dictionary that carries the obsolete /Name entry (<< /BaseFont /Symbol /Name /F5 >>, as ReportLab emits) reports the label as its font name. get_correct_character() matched only that name against the base-14 metrics, so Symbol/ZapfDingbats text missed the built-in encoding tables (Symbol.afm, ZapfDingbats.afm) and fell back to StandardEncoding: Symbol's arrowright (0256) decoded as the fi ligature, ZapfDingbats' a35 star (0110) as H. The bogus fi then merged into the neighbouring Helvetica line under the sanitator's cross-font ligature exemption, which is why the issue presented as a merging bug.

The fix mirrors the font_name-or-base_font fallback that every width/bbox lookup in page_font.h already uses.

• src/parse/pdf_resources/page_font.h: one hunk in get_correct_character()
• tests/test_font_name_resolution.py: parse-side regression tests (Symbol arrow, ZapfDingbats star, labelled and unlabelled) alongside the existing render-side /Name-shadowing test

Full test suite: 221 passed, 1 skipped, 3 failed — the three failures are a single groundtruth mismatch surfaced in test_parse/test_threaded_parse/test_threaded_render: annots_01.pdf groundtruth expects l where the fix now yields ●. That document's /F3 is << /BaseFont /ZapfDingbats /Name /F3 >> with no /Encoding — the same bug pattern — so the groundtruth l is itself the misdecode (ZapfDingbats code 108, a71, is the black-circle bullet). The groundtruth dataset needs a revision bump for that file, as with the ActualText fix (#300).

🤖 Generated with Claude Code

[github-actions]

✅ DCO Check Passed

Thanks @wittjeff, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[PeterStaar-IBM]

please run the pre-commit

[wittjeff]

Done — renamed to tests/test_unit_font_name_resolution.py and ran pre-commit (Ruff format/lint, MyPy, uv-lock all pass) in 11283dc.

[PeterStaar-IBM]

can you merge with main (such that we have the latest regression tests) and resolve the merge conflicts?

[wittjeff]

Done — merged main (post-#325) into the branch. The merge resolved cleanly: git's rename detection handled the test_font_name_resolution.py → test_unit_font_name_resolution.py rename (which I had already made per review, matching #325's convention), so relative to main the branch still carries only the one hunk in get_correct_character() plus the regression test file.

Full suite locally after the merge: 227 passed, 1 skipped, 3 failed — the three failures are the known annots_01.pdf groundtruth mismatch described in the PR body: that document's /F3 is << /BaseFont /ZapfDingbats /Name /F3 >> with no /Encoding, i.e. exactly the bug pattern this PR fixes, so the stored groundtruth records the misdecode (l where ZapfDingbats code 108, a71, is the black-circle bullet ●).

I've opened a companion PR on the regression dataset with the four regenerated annots_01 parser artifacts: https://huggingface.co/datasets/docling-project/regression-dataset-for-docling-parse/discussions/3 — the diff there is exactly the four l → ● cells (the .json.gz also re-encodes one embedded page bitmap; verified pixel-identical, just non-deterministic PNG compression on rewrite). With those artifacts in place, the three tests pass locally (59 passed across test_regression_parse / test_regression_threaded_parse / test_regression_threaded_render).

Once the dataset PR is merged I'll bump HF_DATASET_REVISION in tests/constants.py here — which also plays nicely with the corpus cache keying introduced in #329. Until then, CI on this PR will show those three known failures.

[PeterStaar-IBM]

@wittjeff Seems we caught something in the regression testing,

=========================== short test summary info ============================
FAILED tests/test_regression_parse.py::test_reference_documents_from_filenames - AssertionError: 3 page(s) failed: annots_01.pdf@1[char], annots_01.pdf@1[word], annots_01.pdf@1[line]
assert 3 == 0
FAILED tests/test_regression_threaded_parse.py::test_threaded_reference_documents_from_filenames - AssertionError: true_cell.text == pred_cell.text => l == ● for /home/runner/work/docling-parse/docling-parse/tests/data/groundtruth/parser/annots_01.pdf.page_no_1.py.json
assert 'l' == '●'
  
  - ●
  + l
FAILED tests/test_regression_threaded_render.py::test_render_reference_documents_from_filenames - AssertionError: true_cell.text == pred_cell.text => l == ● for /home/runner/work/docling-parse/docling-parse/tests/data/groundtruth/parser/annots_01.pdf.page_no_1.py.json
assert 'l' == '●'
  
  - ●
  + l
============ 3 failed, 68 passed, 12 skipped in 2928.31s (0:48:48) =============

[wittjeff]

@PeterStaar-IBM

I've opened a companion PR on the regression dataset with the four regenerated annots_01 parser artifacts:

Please see https://huggingface.co/datasets/docling-project/regression-dataset-for-docling-parse/discussions/3

Are you intending for the GT dataset to include these issues? My interpretation was that if you incorporate the dataset PR following the HF link above, to fix the dataset first, then re-run the CI here, this docling-parse fix PR should clear.

If I'm actually nulling out an intended error test case in the GT dataset, I'll back out the dataset PR and start over.