Metadata-Version: 2.4
Name: disk-cleanup-audit
Version: 0.1.0
Summary: A modular, high-reliability, 100% read-only Windows disk space and junk file audit tool.
Author: Teamwork Audit Team
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0

# Windows Disk Cleanup & Junk File Audit Tool (`disk-cleanup-audit`)

A modular, enterprise-grade, **100% strictly read-only** Windows disk space and junk file audit tool. Scans multi-dimensional storage consumption across Windows system caches, browser profiles, developer toolchains, and social communication applications. Automatically classifies items into a 3-tier risk taxonomy (Safe / Caution / Warning) and generates actionable console dashboards, structured Markdown reports, and machine-parseable JSON artifacts without ever modifying or deleting user files.

---

## Key Architectural Principles

### 1. Absolute Read-Only Guarantee (Audit & Dry-Run Invariant)
- **Zero Mutating Syscalls**: The tool contains zero destructive primitives (`os.remove`, `os.unlink`, `os.rmdir`, `shutil.rmtree`, `DeleteFileW`, etc.).
- **AST Static Verification**: Enforced at build time via `tests/security/test_readonly_ast.py`.
- **Runtime Interception**: Dynamic monkeypatch interceptors fail tests if any write or delete syscall is invoked.
- **Read-Only File Handles**: All inspections strictly use `mode='r'` or `mode='rb'`.

### 2. 3-Tier Safety & Risk Classification
Every audited directory and file is evaluated against official Microsoft `VolumeCaches` standards and domain rules:
- **SAFE (Green / Zero Data Risk)**: Ephemeral temp files, post-mortem crash dumps (`.dmp`), stale thumbnails (`thumbcache_*.db`), and staged update downloads. Eligible for immediate automated cleanup via official tools.
- **CAUTION (Yellow / Medium Operational Penalty)**: Package caches (`pip`, `npm`, `Maven`, `Gradle`, `Cargo`, Docker images). Non-destructive to delete, but rebuilding them consumes network bandwidth and CPU cycles.
- **WARNING (Red / Irreplaceable Personal Assets)**: Received documents, invoices, chat attachments in WeChat (`Documents\WeChat Files`) and QQ (`Tencent Files`), and user `Downloads`. Strictly prohibited from automated deletion; requires manual user review.

### 3. Fault-Tolerant Windows Filesystem Traversal
- **Reparse Point & Junction Shield**: Inspects NTFS reparse tags (`IO_REPARSE_TAG_MOUNT_POINT = 0xA0000003`) with `follow_symlinks=False`, preventing infinite recursion loops on legacy compatibility junctions (e.g., `Application Data`).
- **Non-Blocking Metadata Sizing**: Queries file attributes via `os.scandir()` without opening exclusive read handles, avoiding `WinError 32 (ERROR_SHARING_VIOLATION)` on active database files (e.g., Edge/Chrome `History`).
- **Extended Path Normalization**: Bypasses the 260-character `MAX_PATH` limit by prefixing deep paths with `\\?\`.
- **Invariant Exit Code 0**: Encounters with `WinError 5 (Access is denied)` or `WinError 32` are recorded as audit telemetry findings rather than execution failures. The process consistently exits with status code `0`.

### 4. CJK East Asian Character Display Width Alignment
Console tables calculate string visual widths using `unicodedata.east_asian_width()` ('W' and 'F' characters occupy 2 terminal columns). Table borders (`│`, `┌`, `└`) remain perfectly aligned regardless of whether paths or category names contain Chinese, Japanese, or Korean characters. Includes `--no-color` plain-text fallback for CI and pipe redirection.

---

## Installation & Requirements

### System Requirements
- Windows 10 / Windows 11 / Windows Server 2016+
- Python 3.10+ (Tested on Python 3.10, 3.11, 3.12, 3.13, 3.14)

### Installation
From the project directory:
```bash
pip install -e .
```
This registers the CLI executable `disk-cleanup-audit`.

Alternatively, run without installation using Python module execution:
```bash
python -m disk_cleanup_audit [OPTIONS]
```

---

## CLI Usage Guide

```text
Usage: disk-cleanup-audit [OPTIONS]

  Windows Disk Cleanup & Junk File Audit Tool.

  Performs a 100% read-only scan of system temporary files, browser caches,
  developer tooling artifacts, and social application files. Evaluates cleanup
  safety risks and produces structured actionable audit reports.

Options:
  -o, --output PATH               Destination file path for exported report
                                  (*.md, *.json).
  -f, --format [console|markdown|json|both]
                                  Output format: console, markdown, json, or
                                  both.  [default: console]
  -c, --categories TEXT           Filter scan targets by category (comma-
                                  separated: system,browser,dev,social,all).
                                  [default: all]
  -m, -s, --min-size TEXT         Minimum file/directory size threshold to
                                  include (e.g. 100KB, 10MB, 1GB).  [default: 0B]
  --threshold TEXT                Category warning threshold size (e.g. 500MB,
                                  1GB, 5GB).  [default: 1GB]
  -n, --top-n INTEGER             Maximum number of top disk-consuming paths
                                  displayed.  [default: 10]
  --no-color                      Disable ANSI color codes and escape sequences.
  --dry-run                       Reaffirm strict read-only audit mode (always
                                  enforced).
  -q, --quiet                     Suppress console dashboard output; only export
                                  reports.
  -v, --verbose                   Enable verbose audit logging showing active
                                  paths and skipped items.
  -V, --version                   Show the version and exit.
  -h, --help                      Show this message and exit.
```

---

## Common Usage Examples

### 1. Default Interactive Console Dashboard
```bash
disk-cleanup-audit
```
Scans all four domains and renders the ANSI colored KPI cards, category breakdown, reclaim potential bar, Top 10 space consumers, and official remediation advice.

### 2. Export Structured Markdown Report
```bash
disk-cleanup-audit --format markdown --output audit_report.md
```
Generates a complete Markdown report with executive summary tables, visual distribution charts, offender lists, and remediation playbooks.

### 3. Display Dashboard AND Save Markdown Artifact
```bash
disk-cleanup-audit --format both --output ./reports/full_audit.md
```

### 4. Filter Specific Categories (e.g. Developer & System Temp)
```bash
disk-cleanup-audit -c dev,system -n 20
```

### 5. Filter by Minimum Size (e.g. Items >= 50MB)
```bash
disk-cleanup-audit --min-size 50MB
```

### 6. Export Machine-Parseable JSON for CI/Automation
```bash
disk-cleanup-audit --format json --output report.json --quiet
```

### 7. Plain-Text Output for Pipes or Legacy Consoles
```bash
disk-cleanup-audit --no-color > audit.txt
```

---

## Audited Categories & Target Paths

| Category | Targets & Locations | Risk Level | Cleanup Consequence |
|---|---|:---:|---|
| **System Core Temp** | `%TEMP%`, `%SystemRoot%\Temp`, `SoftwareDistribution\Download`, `CrashDumps`, `Minidump`, `C:\$Recycle.Bin` | **SAFE** | None. OS will transparently recreate directories on demand. |
| **Browser Caches** | Chrome, Edge, and Firefox cache directories (`Cache_Data`, `cache2`), Explorer `thumbcache_*.db` | **CAUTION / SAFE** | Web assets will re-download on next visit; thumbnails regenerate when folders are opened. |
| **Developer Caches** | `pip\cache`, `npm-cache`, `.m2\repository`, `.gradle\caches`, `.cargo\registry\cache`, Docker WSL VHDX, dormant `node_modules` / `.venv` | **CAUTION** | Offline builds may require network re-download of dependencies. |
| **Social & User Files**| `Documents\WeChat Files`, `Tencent Files` (QQNT), user `Downloads` (>100MB, untouched >60d) | **WARNING** | High data loss risk. Contains received work documents, media, and installers. Requires manual verification. |

---

## Official Remediation Playbook (Generated Guidance)

The audit tool provides official, vendor-recommended commands for reclaiming space safely:

### Safe Items (Immediate Automated Remediation)
```powershell
# Windows Disk Cleanup utility
cleanmgr.exe /d C:

# Empty Windows Recycle Bin
Clear-RecycleBin -Force

# Windows Update Component Store Cleanup (Run as Admin)
Dism.exe /online /Cleanup-Image /StartComponentCleanup
```

### Caution Items (Developer Tooling)
```powershell
# Python pip cache
pip cache purge

# Node.js npm cache
npm cache clean --force

# Docker unused images and build caches
docker system prune -a --volumes
```

### Warning Items (Manual Review Required)
- **WeChat Files**: Open WeChat -> `Settings` -> `General` -> `Storage Management` -> manage chats and clear cache safely.
- **Downloads Folder**: Open File Explorer, sort `Downloads` by Size descending, and manually delete unneeded `.iso`, `.exe`, or `.msi` installers.

---

## Security & Verification

Run the complete test suite:
```bash
python -m pytest tests/ -v
```
To verify read-only compliance specifically:
```bash
python -m pytest tests/security/ -v
```
All tests guarantee 100% read-only execution, 0 file alterations, 0 destructive syscalls, and an invariant exit code of 0.
