Skip to content

pc-clean: add Windows support to the hidden-home scanner - #1

Open
bardoq wants to merge 1 commit into
elxecutor:mainfrom
bardoq:pc-clean-windows
Open

bardoq wants to merge 1 commit into
elxecutor:mainfrom
bardoq:pc-clean-windows

Conversation

@bardoq

@bardoq bardoq commented Nov 17, 2026

Copy link
Copy Markdown

What

Makes the pc-clean scanner run on Windows as well as Linux and macOS, without changing what it reports and without making it any less read-only. A single implementation (scripts/scan.py) branches on the current platform; scan.ps1 and scan.sh only locate Python and forward arguments.

Why

The scanner assumed a POSIX home:

  • hidden entries were detected only by a leading dot, so Windows missed AppData — normally the largest per-user storage area;
  • the per-folder deadline used SIGALRM, which does not exist on Windows;
  • allocation read st_blocks, which Windows does not report;
  • file attribution shelled out to pacman -Qqo.

The result on Windows was either a crash or a misleadingly empty report.

Changes

  • Hidden detection: dot-prefixed names, plus — on Windows only — the hidden file attribute and the shell-hidden folders Explorer suppresses (AppData, Application Data, Local Settings, Cookies, …). Non-Windows behaviour stays dot-prefix only.
  • Links: junctions and cloud reparse points are handled like symlinks: listed, never followed. This also stops the scanner recursing through the legacy Application Data → AppData aliases.
  • Attribution: POSIX keeps exact pacman -Qqo ownership. Windows matches a file against registry uninstall entries that publish an InstallLocation and labels it as an install-location match. When neither applies, the report says no per-file owner is available instead of guessing.
  • Timeout: SIGALRM is replaced by a time.monotonic() deadline checked between entries, so --timeout works on every platform.
  • Sizes: allocation falls back to logical size only when the OS omits st_blocks, so sparse-file accounting on Linux is unchanged.
  • New scripts/scan.ps1; scan.sh is untouched.
  • Tests: made path-separator and platform aware; 14 tests, standard library only. New coverage for the allocation fallback, hidden detection, registry owner lookup, and the visible-folder error.
  • --folder <visible-name> now reports "exists but is not a hidden entry" instead of "not found".

Safety

Still report-only: no writes, no deletions, no state changes, no elevation. The scanner refuses protected home directories and reports ACL-denied folders as [partial] rather than as clean or zero-sized.

Testing

  • python -B tests/test_scan.py → 14 passed (Windows 11, Python 3.13).
  • Real scans of a user home: ~, --dotfiles-only, --folder .config, --folder AppData (~7.9k directories, 4 ACL-denied folders correctly partial), the .ps1 wrapper, and all argument/error paths.
  • Linux/macOS: the POSIX paths are unchanged apart from the timeout implementation; verified by simulation and diff review, but not executed on a real Linux host. I am happy to add a CI matrix if reviewers want hard proof.

Known limitations (documented in SKILL.md)

  • Windows publishes no per-file package ownership, so attribution is an install-location match.
  • Windows does not expose per-file allocation to Python, so sizes there are logical rather than allocated.
  • The deadline is checked between directory entries, so a hung network mount can overshoot --timeout.

- Detect Windows-hidden entries: dotfiles, the hidden file attribute, and
  the shell-hidden folders Explorer suppresses (AppData and legacy junctions).
- Skip junctions/cloud reparse points instead of following them, and report
  them as not followed.
- Attribute large files by registry install location on Windows while keeping
  exact pacman ownership on Arch.
- Replace SIGALRM with a portable deadline so per-folder timeouts work on
  Windows; sparse-file accounting is unchanged on POSIX.
- Fall back to logical size when the OS does not report st_blocks.
- Add scripts/scan.ps1; scan.sh and the POSIX paths are unchanged.
- Update the test suite for both platforms (14 tests) and make --folder report
  a visible entry as not hidden instead of "not found".
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.

1 participant