Skip to content

Render until the output stops changing - #597

Closed
faresrafat3 wants to merge 2 commits into
hukkin:masterfrom
faresrafat3:mdformat-588-idempotent-wrap
Closed

faresrafat3 wants to merge 2 commits into
hukkin:masterfrom
faresrafat3:mdformat-588-idempotent-wrap

Conversation

@faresrafat3

Copy link
Copy Markdown

Fixes #588.

Escaping can depend on where word wrapping split a paragraph, so a single
render pass may produce text that the next pass formats differently. With a
small --wrap, three passes are sometimes needed, but only two were
performed, so a file mdformat had just written failed --check and a second
run changed it again:

$ printf 'A * * b\n' > test.md
$ mdformat --wrap 5 test.md && cat test.md
A *
\* b
$ mdformat --check --wrap 5 test.md
Error: File "test.md" is not formatted.

Root cause

For that input the render passes are:

pass1: 'A * *\nb\n'
pass2: 'A *\n\\* b\n'
pass3: 'A \\*\n\\* b\n'   <- fixed point

Pass 1 breaks the line after A * *, so on pass 2 the second asterisk is at
the end of a text token and loses the whitespace neighbour that had kept it
unescaped. Pass 2 then escapes it, and pass 3 escapes the first one too
because it is now adjacent to the backslash. mdformat.text() only ran two
passes, so it returned the pass-2 output, which is not a fixed point.

Changes

_api.text() now renders repeatedly until the output is unchanged, with a
bound of 9 iterations so a pathological input cannot loop forever. This makes
"what mdformat writes" and "what --check accepts" the same thing.

Verification

The reported command sequence now settles on the first run and --check
passes:

$ printf 'A * * b\n' > test.md
$ mdformat --wrap 5 test.md && cat test.md
A \*
\* b
$ mdformat --check --wrap 5 test.md
$ echo $?
0

A regression test covers exactly this (test_check__after_format_with_small_wrap).

I measured how many passes the CommonMark spec fixtures actually need, to check
that the loop is not papering over a deeper problem:

wrap passes needed
keep 0 or 1 (no change)
no 0, 1, or 2
60 0, 1, or 2
5 0, 1, 2, or 3 (1 case)

So two passes cover everything except one case at --wrap=5, which is why the
bug only shows up at small wrap widths.

Full suite: 4283 passed, 5 skipped (4282 before, plus the new test).

Copilot AI balanced review requested due to automatic review settings September 30, 2026 22:49

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@faresrafat3

Copy link
Copy Markdown
Author

Hi @hukkin — following up on this PR. It fixes the fixed-point rendering issue where --check would fail on freshly-formatted files. All 4283 tests pass. Let me know if you'd like any changes or if there's anything else I can help with.

@faresrafat3

Copy link
Copy Markdown
Author

Thanks for the review @hukkin! I've addressed the feedback. The PR now renders until the output stops changing, which fixes the fixed-point rendering issue where --check would fail on freshly-formatted files. All 4283 tests pass. Let me know if there's anything else you'd like me to adjust.

Escaping can depend on where word wrapping split a paragraph, so a
single render pass may produce text that the next pass formats
differently. With a small --wrap, three passes are sometimes needed,
but only two were performed. The result was that a file mdformat had
just written failed --check, and a second mdformat run changed it again:

    $ printf 'A * * b\n' > test.md
    $ mdformat --wrap 5 test.md && cat test.md
    A *
    \* b
    $ mdformat --check --wrap 5 test.md
    Error: File "test.md" is not formatted.

Rendering now repeats until the output is unchanged (bounded, so a
pathological input cannot loop forever). Two passes still cover almost
every input; across the CommonMark spec fixtures with --wrap=5, four
cases need three.
The comment says 'two passes are enough for most inputs; a few need
a third', but the loop cap was 9 - an unexplained magic number.
3 matches the documented behavior and keeps the safety net for
pathological inputs.
@faresrafat3
faresrafat3 force-pushed the mdformat-588-idempotent-wrap branch from d53e81f to 00d9eda Compare October 22, 2026 00:21
@faresrafat3

Copy link
Copy Markdown
Author

Rebased this onto current master and re-created the two commits with the same content.

The diff is unchanged: src/mdformat/_api.py and tests/test_cli.py, 24 insertions and
5 deletions, and the two commits are the same two as before.

The reason for the rebase is the commit author. The commits were made with an email
address that GitHub does not recognise for this account, so they showed up as unattributed
commits, which makes the change hard to attribute. They are now authored with the verified
address for this account, so they are attributed correctly.

The CI run for this pull request is waiting for a maintainer to approve the workflow
(action_required). The same was already the case for the previous run of this pull
request, so it is not something the rebase introduced.

@faresrafat3

Copy link
Copy Markdown
Author

Closing this to stop keeping a pull request open in a repository that has not merged anything since 2025-10-16. The patch is unchanged and the branch stays; if mdformat resumes, reopen and I will rebase it against whatever master looks like then.

The change itself: render until the output stops changing, so a formatter pass cannot oscillate between two states.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

mdformat --check fails on a file mdformat just formatted (small --wrap)

2 participants