Summary
mint broken-links produces dramatically different output between Windows and macOS on the same repo, same git ref, same CLI version (4.2.549). On Windows the run also breaks two ancillary behaviors — output redirection and terminal encoding — that together make the result hard to use.
Environment
|
Windows (broken) |
macOS (works) |
| Mint CLI |
4.2.549 (npx fresh install) |
4.2.549 (npx fresh install) |
| Node |
(current LTS) |
22.x |
| Repo |
same commit |
same commit |
| Working tree |
clean (git status matches) |
clean |
Symptoms
1. Wildly different broken-link counts on the same repo
On the same commit and clean tree, the macOS run reports a small, well-understood set of broken links (a handful tied to known reference-page gaps). The Windows run reports hundreds of broken links across PT/ES navigation pages — pt\reference\midaz\..., pt\platform\helm\..., etc. — most of which point to pages that exist on disk and resolve correctly when the docs are built.
A revealing detail: the Windows output uses backslashes in the source-file paths it prints (pt\reference\flowker\...), whereas the macOS output uses forward slashes. This strongly suggests the Windows path resolver is constructing internal lookup paths with \ and then failing to match against POSIX-style targets declared in docs.json and link references inside .mdx files. The user-visible result is a flood of false positives.
2. Output redirection captures only the spinner, not the result
Running mint broken-links > broken.txt 2>&1 on Windows produces a file containing only the loading-spinner braille characters (⠋ ⠙ ⠹ …) repeated, with no actual broken-link results ever written. The CLI appears to detect the non-TTY destination and either skips the final write or exits without flushing the report.
This makes the bug self-reinforcing on Windows — the Windows terminal scroll buffer is too small to scroll back to the found N broken links header line, and redirecting to a file is the natural workaround, but redirection silently strips the actual content.
3. Mojibake when piped to a file
Even the spinner output that does land in the file is garbled — the braille spinner characters are encoded in a Windows codepage (CP850 / CP437), producing bytes like Ô, á, É instead of ⠋ ⠙ ⠹. The CLI is not forcing UTF-8 on its stdout writer, so when stdout is redirected the encoding falls through to the legacy console codepage.
Reproduction
- Clone any docs repo (we hit this on a Mintlify-formatted documentation repo with
docs.json, mdx files in en/, pt/, es/).
- From Windows PowerShell:
npx mint broken-links — note the visible count.
npx mint broken-links > broken.txt 2>&1 — open broken.txt, observe only spinner characters, mojibaked.- Run the same command on macOS or Linux on the same git ref. The count is dramatically lower (often by 1+ orders of magnitude).
Suggested fixes
- Path normalization: internally normalize all paths to forward-slash form before comparing link targets to the file-tree index. Do this at the platform boundary so the rest of the resolver is OS-independent.
- Honor non-TTY stdout: when
process.stdout.isTTY === false, replace the spinner with a no-op (or a [checking…] line written once), and make sure the final report is written to stdout regardless.
- Force UTF-8 stdout encoding: set
process.stdout.setEncoding('utf8') (or equivalent) at startup so output to redirected files preserves the spinner glyphs and any non-ASCII path components.
Of the three, the first one (path normalization) is the most impactful — it's the difference between the report being usable on Windows or being dominated by false positives.
Why this matters
Translation/localization work on multi-language docs almost always happens on Windows in our team. The current state means we cannot trust broken-links as a CI gate or even as a manual check on Windows machines, and engineers on macOS reviewing the same PRs see a different, much smaller set of issues. We end up with a quality control tool that reports different things to different reviewers on the same content.
Happy to provide additional environment detail, full output samples (mac vs Windows), or a minimal reproduction repo if useful.
Summary
mint broken-linksproduces dramatically different output between Windows and macOS on the same repo, same git ref, same CLI version (4.2.549). On Windows the run also breaks two ancillary behaviors — output redirection and terminal encoding — that together make the result hard to use.Environment
4.2.549(npx fresh install)4.2.549(npx fresh install)22.xgit statusmatches)Symptoms
1. Wildly different broken-link counts on the same repo
On the same commit and clean tree, the macOS run reports a small, well-understood set of broken links (a handful tied to known reference-page gaps). The Windows run reports hundreds of broken links across PT/ES navigation pages —
pt\reference\midaz\...,pt\platform\helm\..., etc. — most of which point to pages that exist on disk and resolve correctly when the docs are built.A revealing detail: the Windows output uses backslashes in the source-file paths it prints (
pt\reference\flowker\...), whereas the macOS output uses forward slashes. This strongly suggests the Windows path resolver is constructing internal lookup paths with\and then failing to match against POSIX-style targets declared indocs.jsonand link references inside.mdxfiles. The user-visible result is a flood of false positives.2. Output redirection captures only the spinner, not the result
Running
mint broken-links > broken.txt 2>&1on Windows produces a file containing only the loading-spinner braille characters (⠋ ⠙ ⠹ …) repeated, with no actual broken-link results ever written. The CLI appears to detect the non-TTY destination and either skips the final write or exits without flushing the report.This makes the bug self-reinforcing on Windows — the Windows terminal scroll buffer is too small to scroll back to the
found N broken linksheader line, and redirecting to a file is the natural workaround, but redirection silently strips the actual content.3. Mojibake when piped to a file
Even the spinner output that does land in the file is garbled — the braille spinner characters are encoded in a Windows codepage (CP850 / CP437), producing bytes like
Ô,á,Éinstead of⠋ ⠙ ⠹. The CLI is not forcing UTF-8 on its stdout writer, so when stdout is redirected the encoding falls through to the legacy console codepage.Reproduction
docs.json, mdx files inen/,pt/,es/).npx mint broken-links— note the visible count.npx mint broken-links > broken.txt 2>&1— openbroken.txt, observe only spinner characters, mojibaked.Suggested fixes
process.stdout.isTTY === false, replace the spinner with a no-op (or a[checking…]line written once), and make sure the final report is written to stdout regardless.process.stdout.setEncoding('utf8')(or equivalent) at startup so output to redirected files preserves the spinner glyphs and any non-ASCII path components.Of the three, the first one (path normalization) is the most impactful — it's the difference between the report being usable on Windows or being dominated by false positives.
Why this matters
Translation/localization work on multi-language docs almost always happens on Windows in our team. The current state means we cannot trust
broken-linksas a CI gate or even as a manual check on Windows machines, and engineers on macOS reviewing the same PRs see a different, much smaller set of issues. We end up with a quality control tool that reports different things to different reviewers on the same content.Happy to provide additional environment detail, full output samples (mac vs Windows), or a minimal reproduction repo if useful.