docx-repro: shrink DOCX conversion bug reports while preserving the exact symptom

[Justine Basibas (capt1nedev)]

I maintain docx-repro, a small MIT-licensed Python tool for the part of a DOCX bug report that often takes repeated manual work: removing unrelated content without losing the problem.

Give it a DOCX and a checker for your exact symptom. It deletes whole body blocks, reruns the checker, and confirms the final result before saving it. The source file is preserved. Python 3.10+ is supported, with no core runtime dependencies.

A two-command demo

In a fresh virtual environment:

python -m pip install "docx-repro[demo]==0.1.2"
docx-repro-demo demo

The installed demo generates original synthetic content and reduces 201 body blocks to the one paragraph that still loses a specified phrase in Mammoth 1.13.0. The checker requires the phrase to remain in the source, so deleting the phrase cannot count as reproducing the bug.

The demo pins Mammoth 1.13.0. MarkItDown 0.1.8 uses Mammoth 1.11.x, so keep this demo in a separate environment. To investigate your own MarkItDown case, install the core package in the environment containing your intended converter version and use a symptom-specific checker.

What it helped investigate

For MarkItDown #2323, a case-specific checker reduced the public nested-list example from eight paragraphs to two. The intermediate Mammoth HTML already contained a flat numbered list before Markdown conversion. Case study and checker.

A second case supplies an original synthetic fixture for a reported missing-image crash whose original document is private. It exercises an exact exception checker, including controls for deleted triggers and unrelated errors.

These are verified reproductions and investigations. No upstream fix or maintainer adoption is claimed.

Using your own checker

The checker runs as an explicit command without a shell. Its exit codes have a specific meaning:

• 0: the target symptom still occurs.
• 1: the target symptom is absent.
• Anything else: inconclusive; stop without committing a reduction.

A checker should preserve the source conditions needed by the bug and distinguish the intended exception from an unrelated converter failure. Checker contract and limits.

The alpha removes whole top-level body blocks. Supporting parts and metadata remain. Reduction is not anonymization, so review any output before sharing it. The core reducer does not fetch external document relationships or use a remote conversion service.

If you have a difficult DOCX conversion report, feedback on whether the tool preserves your symptom and which structures block a useful reduction would help. Share a reduction case or limitation; versions and the symptom are useful even without a file attachment.

PyPI · Source and documentation

Disclosure: initial implementation and this post were developed with Codex assistance. Validation includes installed-package tests on Windows/Linux, fresh PyPI installs and converter-specific reproductions. I maintain the project; it is independent of Microsoft and Mammoth.