fix(docs): make check:docs work in native PowerShell on Windows by aniruddhaadak80 · Pull Request #91609 · openclaw/openclaw

aniruddhaadak80 · 2026-06-09T04:23:35Z

What Problem This Solves

Currently, the docs formatting check (pnpm check:docs) fails natively on Windows due to CRLF/LF line ending mismatches. When format-docs.mjs compares the repository files with the formatted temporary files, git checkout on Windows may produce CRLF endings while oxfmt writes LF endings. This causes valid files to be incorrectly reported as misformatted. Additionally, the CLAUDE.md file was recently moved to docs/reference/templates/CLAUDE.md but not excluded in markdownlint-cli2.jsonc, causing lint failures.

Why This Change Was Made

To allow Windows users to run docs checks natively without spurious failures, we normalize all line endings to LF before comparing the raw and formatted files in format-docs.mjs. This aligns with the existing practice of normalizing line endings in check-docs-format.mjs. Furthermore, **/CLAUDE.md is added to the markdownlint-cli2.jsonc ignores list so it's not subject to standard Markdown checks that expect different formatting.

User Impact

Allows Windows developers to run native PowerShell docs checks successfully without false-positive failures related to line endings or CLAUDE.md linting.

Evidence

Updated format-docs.mjs to use .replace(/\r\n/g, '\n') when reading both the raw and formatted files.
Added **/CLAUDE.md to config/markdownlint-cli2.jsonc ignores.
Added a new regression test in test/scripts/format-docs.test.ts to verify that CRLF is properly normalized to LF before comparing files in check mode, addressing the missing coverage identified by ClawSweeper.
Ran pnpm test:scripts test/scripts/format-docs.test.ts and verified the new test passes.

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the docs formatting workflow to be more robust during CHECK runs by formatting within a temporary workspace and improving file comparison stability.

Changes:

Chunk oxfmt invocations and allow overriding cwd so formatting can run inside a temp docs copy
Copy .oxfmtrc.jsonc into the temp directory and normalize CRLF/LF when comparing formatted output
Ignore CLAUDE.md files in markdownlint configuration

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
scripts/format-docs.mjs	Runs `oxfmt` in chunks and supports temp-root formatting with normalized comparisons.
config/markdownlint-cli2.jsonc	Adds an ignore rule for `CLAUDE.md`.

+    if (result.status !== 0 || result.error) {
+      console.error("spawnSync result:", result);
+      const stderr = result.stderr?.trim() ?? "";
+      throw new Error(`oxfmt failed${stderr ? `:\n${stderr}` : ""}`);
+    }


-    },
-  );
+function runOxfmt(files, cwd = ROOT) {
+  const chunkSize = 50;


clawsweeper · 2026-06-09T04:26:23Z

Codex review: needs real behavior proof before merge. Reviewed July 5, 2026, 9:20 PM ET / 01:20 UTC.

Summary
The PR normalizes raw/formatted docs text line endings in scripts/format-docs.mjs, broadens markdownlint ignores for CLAUDE.md, and adds a CRLF comparison regression test.

PR surface: Other 0. Total 0 across 2 files.

Reproducibility: yes. source-level: the PR test demonstrates CRLF input being accepted after the formatter writes LF, while current .gitattributes and .oxfmtrc.jsonc require LF. I did not run a live Windows pnpm check:docs lane in this read-only review.

Review metrics: 2 noteworthy metrics.

Windows command budget: 0 changed; remains 24 KiB. The PR targets native PowerShell docs checks, but the cmd.exe-sensitive oxfmt command budget is unchanged in this branch.
Docs linter ignore scope: 1 broad ignore added. The new **/CLAUDE.md ignore broadens future docs lint exclusions even though docs/reference/templates/** is already ignored.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🧂 unranked krab
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Remove the CRLF false-pass behavior and make the regression test expect LF drift to be reported.
[P1] Fix or defer the Windows command-budget path so this PR no longer claims the full native PowerShell docs-check fix.
[P1] Add redacted native Windows PowerShell output or logs showing the final pnpm check:docs path passing.

Proof guidance:

[P1] Needs real behavior proof before merge: The PR body reports a focused test run, but it does not include after-fix native Windows PowerShell output, logs, screenshot, recording, or linked artifact for pnpm check:docs. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

[P1] Merging as-is would let pnpm check:docs pass CRLF-only docs drift even though repo policy and oxfmt configuration require LF.
[P1] The branch title and body still imply the native Windows docs-check path is fixed, but the cmd.exe-sensitive formatter invocation budget is unchanged here and remains tied to ci(windows): add native PowerShell smoke coverage for contributor commands #91610.
[P1] The PR has only test-based validation in the body; it still needs redacted native Windows PowerShell output or logs for the final pnpm check:docs behavior.

Maintainer options:

Repair formatter semantics before merge (recommended)
Preserve LF-drift detection, add or reuse a Windows-safe invocation repair, and require focused tests plus redacted native PowerShell proof.
Split the overlapping Windows work
Leave command-budget and CI-smoke coverage to ci(windows): add native PowerShell smoke coverage for contributor commands #91610 and narrow this PR to behavior that is independently correct and proven.
Accept weaker docs automation
Maintainers could intentionally accept a docs check that hides CRLF drift and lacks Windows proof, but that weakens contributor validation.

Next step before merge

[P1] The PR needs contributor-supplied Windows proof plus maintainer review of the overlap with ci(windows): add native PowerShell smoke coverage for contributor commands #91610, so it is not a safe automated repair lane.

Security
Cleared: No concrete security or supply-chain concern was found; the diff changes local docs-check comparison behavior, markdownlint ignore configuration, and tests only.

Review findings

[P1] Keep the PowerShell fix in the oxfmt invocation path — scripts/format-docs.mjs:228-229
[P2] Keep CRLF drift visible in docs check — scripts/format-docs.mjs:228-229

Review details

Best possible solution:

Keep LF enforcement visible in check mode, handle Windows command-budget or smoke coverage through the focused companion path, and require real native PowerShell pnpm check:docs proof before merge.

Do we have a high-confidence way to reproduce the issue?

Yes, source-level: the PR test demonstrates CRLF input being accepted after the formatter writes LF, while current .gitattributes and .oxfmtrc.jsonc require LF. I did not run a live Windows pnpm check:docs lane in this read-only review.

Is this the best way to solve the issue?

No. Normalizing both sides hides a formatting difference the repo explicitly enforces, and the native Windows command-limit blocker remains in the formatter path before the changed comparison runs.

Full review comments:

[P1] Keep the PowerShell fix in the oxfmt invocation path — scripts/format-docs.mjs:228-229
This was raised in the previous review and still applies: these comparison lines run after runOxfmt, while the native Windows failure occurs before comparison when cmd.exe receives an overlong formatter command. With the budget unchanged at 24 KiB in this branch, the full native PowerShell pnpm check:docs path is still not fixed here.
Confidence: 0.92
[P2] Keep CRLF drift visible in docs check — scripts/format-docs.mjs:228-229
The branch normalizes both repository and formatted temp files before comparing them. Because .gitattributes and .oxfmtrc.jsonc both require LF, a docs file rewritten from CRLF to LF should still be reported as changed; this would let line-ending drift pass pnpm check:docs. Late find: the normalization was visible in an earlier reviewed head, but the new test now makes the false-pass behavior explicit.
Confidence: 0.89
Late finding: first raised on code an earlier review cycle already covered.

Overall correctness: patch is incorrect
Overall confidence: 0.93

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against eda9b9fb1858.

Label changes

Label changes:

remove merge-risk: 🚨 automation: Current PR review selected no merge-risk labels.

Label justifications:

P2: This is a normal-priority contributor-tooling bug with limited runtime blast radius but real Windows docs-check impact.
rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🧂 unranked krab.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body reports a focused test run, but it does not include after-fix native Windows PowerShell output, logs, screenshot, recording, or linked artifact for pnpm check:docs. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

PR surface:

Other 0. Total 0 across 2 files.

View PR surface stats

Area	Files	Added	Removed
Source	0	0	0
Tests	0	0	0
Docs	0	0	0
Config	0	0	0
Generated	0	0	0
Other	2	3	3
Total	2	3	3

What I checked:

Current docs formatter compares raw bytes after oxfmt: Current main runs runOxfmt() before the comparison loop and compares formatted temp files to repository files without CRLF normalization, so line-ending rewrites are currently visible to check mode. (scripts/format-docs.mjs:221, eda9b9fb1858)
PR normalizes away comparison differences: The PR changes the comparison loop to replace CRLF with LF on both sides, which makes a CRLF-only rewrite compare clean. (scripts/format-docs.mjs:228, b20c66cfa53e)
Repo line-ending contract is LF: .gitattributes sets text files to eol=lf, and .oxfmtrc.jsonc sets endOfLine to lf, so docs CRLF drift should remain detectable. (.gitattributes:1, eda9b9fb1858)
New test encodes the false-pass behavior: The added test writes CRLF docs content, simulates oxfmt rewriting it to LF, and expects changed: []. (test/scripts/format-docs.test.ts:149, b20c66cfa53e)
Windows command budget remains unchanged here: Current main and this PR head still use a 24 KiB docs formatter command-line budget; the Windows command-budget work is instead in the open companion PR. (scripts/format-docs.mjs:15, eda9b9fb1858)
History points to the merged PowerShell-safe formatter replacement: The current formatter path was substantially rebuilt by add00d747b6dd367922f29d0b9d42da72e6a3bcb and later touched by Windows cmd shim work in 6c4028e073694e6b7bdae2c61d6c060c623625cf. (scripts/format-docs.mjs, add00d747b6d)

Likely related people:

vincentkoc: Authored and merged the PowerShell-safe docs formatter replacement and later touched the Windows cmd shim path used by scripts/format-docs.mjs. (role: recent docs formatter contributor and merger; confidence: high; commits: add00d747b6d, 6c4028e07369; files: scripts/format-docs.mjs, test/scripts/format-docs.test.ts, scripts/windows-cmd-helpers.mjs)
steipete: History shows the docs formatter package-script direction and markdownlint config move came from this contributor, with the highest sampled activity on the touched formatter/config surface. (role: original script and config introducer; confidence: high; commits: 85fcf16804dc, d0f0fe97a6f0; files: scripts/format-docs.mjs, package.json, config/markdownlint-cli2.jsonc)
yil337: The merged replacement PR credits this contributor's earlier PowerShell-friendly docs format check work and local history contains the earlier helper commit. (role: source contributor for PowerShell-friendly docs checks; confidence: medium; commits: a2c0ce89cecb, add00d747b6d; files: scripts/check-docs-format.mjs, scripts/format-docs.mjs, test/scripts/format-docs.test.ts)
soyames: A closed predecessor PR carried Windows-clean formatter work later credited by the merged replacement, and local history contains that formatter commit. (role: source contributor for Windows-clean formatter direction; confidence: medium; commits: f5972081b881, add00d747b6d; files: scripts/format-docs.mjs, test/scripts/format-docs.test.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (2 earlier review cycles)

reviewed 2026-06-28T13:53:42.142Z sha 46a0cb4 :: needs real behavior proof before merge. :: [P1] Keep the formatter under cmd.exe's command-line limit
reviewed 2026-07-05T15:40:33.594Z sha b20c66c :: needs real behavior proof before merge. :: [P1] Keep Windows oxfmt chunks below cmd.exe's limit | [P2] Do not normalize away CRLF-only formatting changes

aniruddhaadak80 · 2026-06-28T13:41:00Z

Rebased onto main, resolved merge conflict in format-docs.mjs by taking main's refactored structure and preserving the CRLF normalization fix. Ready for re-review.

aniruddhaadak80 · 2026-07-05T12:57:01Z

@clawsweeper re-review

clawsweeper · 2026-07-05T12:57:04Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

vincentkoc · 2026-07-06T21:40:51Z

Closing as superseded by #93512, which landed the PowerShell-safe docs formatter fix in add00d747b6dd367922f29d0b9d42da72e6a3bcb and closed the underlying #44293 path. This branch is now substantially stale, and its remaining CRLF-normalization behavior conflicts with the repository LF policy. Thanks for the investigation and regression-test work here.

Copilot AI review requested due to automatic review settings June 9, 2026 04:23

openclaw-barnacle Bot added scripts Repository scripts size: XS triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 9, 2026

Copilot AI reviewed Jun 9, 2026

View reviewed changes

clawsweeper Bot mentioned this pull request Jun 9, 2026

Make pnpm check:docs work in native PowerShell #44293

Closed

BradGroux mentioned this pull request Jun 9, 2026

WORKING: All Microsoft Issues and PRs (refresh) #74163

Draft

This was referenced Jun 11, 2026

[Feature] Configurable thinking/reasoning block format per channel #8913

Open

Add native PowerShell smoke coverage for contributor commands #44291

Open

clawsweeper Bot mentioned this pull request Jun 19, 2026

ci(windows): add native PowerShell smoke coverage for contributor commands #91610

Open

fix(docs): make check:docs work in native PowerShell on Windows

46a0cb4

aniruddhaadak80 force-pushed the fix/powershell-check-docs branch from e848cdb to 46a0cb4 Compare June 28, 2026 13:40

openclaw-barnacle Bot added the triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. label Jun 28, 2026

test(docs): add CRLF normalization test for format-docs

b20c66c

openclaw-barnacle Bot removed the triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. label Jul 5, 2026

clawsweeper Bot added merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. and removed merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. labels Jul 5, 2026

vincentkoc self-assigned this Jul 6, 2026

vincentkoc closed this Jul 6, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(docs): make check:docs work in native PowerShell on Windows#91609

fix(docs): make check:docs work in native PowerShell on Windows#91609
aniruddhaadak80 wants to merge 2 commits into
openclaw:mainfrom
aniruddhaadak80:fix/powershell-check-docs

aniruddhaadak80 commented Jun 9, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

clawsweeper Bot commented Jun 9, 2026 •

edited

Loading

Uh oh!

aniruddhaadak80 commented Jun 28, 2026

Uh oh!

aniruddhaadak80 commented Jul 5, 2026

Uh oh!

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading

Uh oh!

vincentkoc commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

aniruddhaadak80 commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

clawsweeper Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aniruddhaadak80 commented Jun 28, 2026

Uh oh!

aniruddhaadak80 commented Jul 5, 2026

Uh oh!

clawsweeper Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vincentkoc commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aniruddhaadak80 commented Jun 9, 2026 •

edited

Loading

clawsweeper Bot commented Jun 9, 2026 •

edited

Loading

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading