fix(markitdown-ocr): sort placeholders by length before substitution to prevent prefix collision

[Azhar (bunnysayzz)]

Root cause

_PLACEHOLDER = "MARKITDOWNOCRBLOCK{}" in packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py.

The substitution loop in DocxConverterWithOCR._convert_local() iterates in ascending index order and calls str.replace(placeholder, ocr_block) for each image. Because "MARKITDOWNOCRBLOCK1" is a prefix of "MARKITDOWNOCRBLOCK10" through "MARKITDOWNOCRBLOCK19", replacing index 1 first corrupts every two-digit placeholder: MARKITDOWNOCRBLOCK10 becomes the OCR content of block 1 followed by a literal "0", dropping the OCR content for image 10 and duplicating the content for image 1.

Reproduction (no OCR service needed):

_PLACEHOLDER = "MARKITDOWNOCRBLOCK{}"
md = " ".join(f"<p>{_PLACEHOLDER.format(i)}</p>" for i in range(11))
for i in range(11):
    md = md.replace(_PLACEHOLDER.format(i), f"[OCR:{i}]")
# Result: ... <p>[OCR:1]</p> ... <p>[OCR:1]0</p>
# OCR block 10 is gone; block 1 appears twice.

Fix

Build the full list of (placeholder, ocr_block) pairs first, then sort by descending placeholder length before iterating. Longer placeholders (MARKITDOWNOCRBLOCK10) are replaced before shorter ones (MARKITDOWNOCRBLOCK1), so no prefix collision can occur.

replacements = [
    (_PLACEHOLDER.format(i), f"*[Image OCR]\n{raw_text}\n[End OCR]*")
    for i, raw_text in enumerate(ocr_texts)
]
replacements.sort(key=lambda pair: len(pair[0]), reverse=True)
for placeholder, ocr_block in replacements:
    md = md.replace(placeholder, ocr_block)

Test evidence

Five regression tests in packages/markitdown-ocr/tests/test_ocr_placeholder_collision.py:

PASSED tests/test_ocr_placeholder_collision.py::test_buggy_code_leaves_corrupted_placeholder_for_11_images
PASSED tests/test_ocr_placeholder_collision.py::test_fixed_code_no_remaining_placeholders_for_11_images
PASSED tests/test_ocr_placeholder_collision.py::test_fixed_code_all_ocr_blocks_present_for_11_images
PASSED tests/test_ocr_placeholder_collision.py::test_fixed_code_no_remaining_placeholders_for_100_images
PASSED tests/test_ocr_placeholder_collision.py::test_no_regression_under_10_images
5 passed in 0.02s

The first test (test_buggy_code_leaves_corrupted_placeholder_for_11_images) documents the bug by asserting the old behavior. The remaining four verify the fix.

Fixes #2383

[Azhar (bunnysayzz)]

@microsoft-github-policy-service agree