Skip to content

ci(windows): build the docs in the Windows clippy job - #970

Open
yuzi-co wants to merge 3 commits into
AprilNEA:masterfrom
yuzi-co:fix/windows-local-gate
Open

yuzi-co wants to merge 3 commits into
AprilNEA:masterfrom
yuzi-co:fix/windows-local-gate

Conversation

@yuzi-co

@yuzi-co yuzi-co commented Aug 25, 2026 •

Copy link
Copy Markdown
Contributor

Summary

A rustdoc failure that shows up only on Windows can't be caught by CI today. rustdoc (non-GUI crates) runs on ubuntu-latest, so a doc link whose target is cfg-gated off on Windows still resolves everywhere CI checks. That exact bug reached master in openlogi-permissions: the module docs linked to PermissionStatus::Unknown, which isn't declared on Windows, so cargo doc failed there. #1679 has since fixed that link by hand. This PR adds the check that would have caught it.

An earlier version of this PR also fixed the openlogi-permissions link itself, and before that ci.yml line-continuation parsing under CRLF. Master has fixed both independently, so those commits were dropped on rebase.

Changes

  • .github/workflows/ci.yml: after clippy, the clippy (windows) job now runs the same cargo doc command as the rustdoc job. The job already sets up the toolchain and cache, so the cost is one doc build and no extra runner. The step runs under bash so the wrapped command parses.
  • xtask: on a Windows host, cargo xtask ci clippy-windows runs the same docs step after clippy, through one helper shared with the rustdoc job. A test checks that this plan matches the commands ci.yml runs. Other hosts still lint Windows by cross-compiling, as before.
  • .agents/rules/ci.md: the CI job table lists the new docs step.

Testing

Windows 11 Pro, RUSTFLAGS="-D warnings", rebased onto current master:

cargo fmt --all -- --check                                   pass
cargo clippy --workspace --all-targets -- -D warnings        pass
cargo test --workspace                                       pass (1943)
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps \
  --document-private-items --exclude openlogi-ui \
  --exclude openlogi-desktop --exclude openlogi-overlay \
  --exclude openlogi-agent                                   pass
cargo xtask ci clippy-windows                                pass

@yuzi-co
yuzi-co requested a review from AprilNEA as a code owner August 25, 2026 08:47
@greptile-apps

greptile-apps Bot commented Aug 25, 2026 •

Copy link
Copy Markdown

RetriggerConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; the remaining test-coverage finding is non-blocking.

Fix All in CodexFindings

  1. P2 native clippy windows runs what ci runs searches the flattened contents of the entire workflow. Because the Linux rustdoc job contains the same cargo doc command, this test would still pass if that command were removed from the Windows job. The new test therefore does not protect against the Windows CI coverage drifting out of sync. ▶

Summary

Adds Windows documentation checks to CI and the native local gate.

  • Windows clippy now builds the non-GUI workspace docs.

No new findings were accepted.

Reviews (10) · Last reviewed commit: "fix(xtask): build the docs in the native..." · Reviewed by Greptile

@davidbudnick davidbudnick added type: bug Something is broken or behaves incorrectly platform: windows Windows-specific issue labels Aug 25, 2026
@yuzi-co
yuzi-co force-pushed the fix/windows-local-gate branch from c5502e4 to e31d67c Compare August 26, 2026 10:16
@yuzi-co
yuzi-co force-pushed the fix/windows-local-gate branch from a54b02d to bd53f25 Compare September 3, 2026 17:16
@yuzi-co
yuzi-co force-pushed the fix/windows-local-gate branch from bd53f25 to 7acb2ff Compare September 3, 2026 18:05
@yuzi-co
yuzi-co force-pushed the fix/windows-local-gate branch 2 times, most recently from 28fae9d to 324b317 Compare September 23, 2026 07:30
Comment thread .github/workflows/ci.yml
for argv in argvs {
assert!(
commands.contains(&argv),
"ci.yml does not run `{argv}` for ClippyWindows"

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 native_clippy_windows_runs_what_ci_runs searches the flattened contents of the entire workflow. Because the Linux rustdoc job contains the same cargo doc command, this test would still pass if that command were removed from the Windows job. The new test therefore does not protect against the Windows CI coverage drifting out of sync.

Knowledge Base Used: Build and release automation

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Codex Fix in Claude Code

`rustdoc (non-GUI crates)` runs on ubuntu-latest, so a `cfg`-gated doc
target that exists on Linux and macOS but not on Windows leaves an
intra-doc link that resolves everywhere CI looks. The module docs of
`openlogi-permissions` linking `PermissionStatus::Unknown`, which is not
declared on Windows, were exactly that: the crate's docs failed to build
on Windows alone until AprilNEA#1679 escaped the link by hand.

A broken intra-doc link is neither a compile error nor a clippy lint,
so the existing Windows job could not catch it either. Running the
rustdoc job's own command there closes the gap: the toolchain and cache
are already set up, so it costs one doc build and no new runner.
The Windows job's default shell is pwsh, where a trailing backslash is
not a line continuation. It parsed --exclude as a unary operator and the
step failed before cargo ran, which is how the job this PR adds the step
to went red.

bash rather than folding the command onto one line, so it stays
byte-identical to the Linux rustdoc job it exists to mirror.
CI's `clippy (windows)` job now runs the non-GUI `cargo doc` line after
clippy, but `cargo xtask ci clippy-windows` on a Windows host still planned
clippy alone. A Windows contributor could get a green local run while the
Windows-only rustdoc check this branch adds would fail in CI.

The native plan now runs the same `cargo doc` step as the `rustdoc` job,
shared through one helper so the two cannot drift. The cross-lint proxy
used on other hosts is unchanged: it lints a ring-free crate subset for the
GNU target and was never that job. A test pins the native plan to the
commands ci.yml runs, docs step included.
@yuzi-co
yuzi-co force-pushed the fix/windows-local-gate branch from 795cc12 to bb76b7a Compare October 10, 2026 21:40
@yuzi-co yuzi-co changed the title fix(xtask,permissions): make the local gate runnable on Windows ci(windows): build the docs in the Windows clippy job Oct 11, 2026

This branch has not been deployed

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

Labels

platform: windows Windows-specific issue type: bug Something is broken or behaves incorrectly

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants