docs: update README and VI guide for orphan cleanup and test count

- Add quick-reference card at top of README (short-form cheat sheet) - Document clean_orphans.py in ToC, Individual Scripts, folder structure - Update GUI Tools view table: note Clean Orphans tab - Fix Running Tests: 96 → 142, remove stale '1 failing test' note, list all 15 groups - Add clean_orphans.py to folder structure tree - Add cleaner.py to arma_modlist_tools/ listing - VI guide: add summary table for Tools tabs, document Clean Orphans tab in full - VI guide: add 'Mod thừa / Orphan' to glossary
2026-04-08 20:11:41 +07:00
parent 5c824280c6
commit e0c2dfb32a
2 changed files with 110 additions and 18 deletions
--- a/README.md
+++ b/README.md
@@ -4,6 +4,31 @@ Python toolchain for managing Arma 3 mod presets: parse launcher exports, compar

 ---

+## Quick Reference
+
+```bash
+# First time setup
+cp config.template.json config.json   # fill in server URL + credentials + arma_dir
+python check_deps.py                  # verify dependencies
+
+# Day-to-day: full pipeline
+python run.py                         # parse → compare → download → link
+
+# GUI (recommended)
+python gui.py
+
+# Maintenance
+python clean_orphans.py --dry-run     # find stale mod folders from old presets
+python update_mods.py                 # re-download changed files (size-check)
+python sync_missing.py                # retry mods that were absent from server
+python check_names.py --fix           # fix folder name mismatches
+
+# Testing
+python test_suite.py                  # 142 tests (network tests auto-skip if offline)
+```
+
+---
+
 ## Table of Contents

 1. [Prerequisites](#prerequisites)
@@ -20,6 +45,7 @@ Python toolchain for managing Arma 3 mod presets: parse launcher exports, compar
   - [sync_missing.py](#sync_missingpy)
   - [update_mods.py](#update_modspy)
   - [check_names.py](#check_namespy)
+   - [clean_orphans.py](#clean_orphanspy)
   - [run.py](#runpy)
   - [gui.py](#guipy)
 6. [Migrating Existing Mods](#migrating-existing-mods)
@@ -468,6 +494,36 @@ python check_names.py --fix --fix-ids

 ---

+### clean_orphans.py
+
+Find and optionally delete orphaned mod folders — `downloads/{group}/@ModName` folders that are no longer referenced in `comparison.json`. These accumulate when you switch presets and re-run the pipeline without cleaning up old downloads.
+
+```bash
+python clean_orphans.py               # list orphans, prompt for confirmation
+python clean_orphans.py --dry-run     # list orphans, do not delete
+python clean_orphans.py --yes         # list and delete without prompting
+```
+
+```
+  Group                         Folder                            Size
+  ----------------------------  --------------------------------  ----------
+  shared                        @OldMod                           124.5 MB
+  150th_WW2_2026_V1.0           @SomeMod                          88.2 MB
+
+  2 orphan(s) found — 212.7 MB total
+
+  Delete all orphans? [y/N]
+```
+
+- Matches by normalized name (same logic as the fetcher), so spacing/capitalization differences are handled correctly
+- Junction-safe: uses `os.rmdir()` on junctions rather than `shutil.rmtree` to avoid deleting target files
+
+**Requires:** `modlist_json/comparison.json` (run `run.py --skip-fetch --skip-link` first).
+
+The same functionality is available as the **Clean Orphans** tab in the GUI.
+
+---
+
 ### run.py

 Orchestrator that chains all four pipeline steps. Described in [Quick Start](#quick-start--full-pipeline) above.
@@ -488,10 +544,12 @@ Opens a CustomTkinter desktop window with a sidebar navigation and the following
 |------|---------|
 | Dashboard | Overview: status, quick stats, recent activity |
 | Mods | Browse and manage downloaded mods by group |
-| Tools | Link/unlink, rename, sync missing, check server |
+| Tools | Link/unlink, rename, sync missing, check server, **clean orphans** |
 | Logs | Real-time log output from pipeline operations |
 | Settings | Edit `config.json` (server URL, paths, credentials) |

+The **Tools** view has five tabs: Check Names, Update Mods, Link Mods, Sync Missing / Report Missing, and **Clean Orphans** (find and delete stale mod folders from old presets).
+
 On first launch (no `config.json`), a setup wizard walks you through creating one.

 **Requires:** `customtkinter` (`pip install customtkinter`).
@@ -543,6 +601,7 @@ arma-modlist-tools/
 |   |- fetcher.py             # Caddy server downloader
 |   |- linker.py              # Junction/symlink manager
 |   |- reporter.py            # Missing-mod report builder
+|   |- cleaner.py             # Orphan folder detection
 |   |- config.py              # config.json loader
 |   |- compat.py              # OS detection + encoding fix
 |
@@ -591,8 +650,9 @@ arma-modlist-tools/
 |- sync_missing.py            # Sync newly available missing mods
 |- update_mods.py             # Re-download updated mod files
 |- check_names.py             # Diagnose and fix folder name / steam_id issues
+|- clean_orphans.py           # Find and delete orphaned mod folders
 |- check_deps.py              # Dependency checker
-|- test_suite.py              # Test suite
+|- test_suite.py              # Test suite (142 tests)
 ```

 ---
@@ -631,7 +691,7 @@ arma-modlist-tools/

 ## Running Tests

-The test suite covers all modules with 96 tests. No network connection required.
+The test suite covers all modules with 142 tests. Network tests (section 15) auto-skip when the server is unreachable.

 ```bash
 python test_suite.py
@@ -639,19 +699,21 @@ python test_suite.py

 ```
 ------------------------------------------------------------
-  compat            6 tests
-  config            5 tests
-  parser            9 tests
-  compare           8 tests
-  fetcher          19 tests   (pure functions, no network)
-  reporter          8 tests
-  linker           12 tests   (uses temp dirs)
-  __init__          2 tests
-  check_names      16 tests
-  integration       2 tests
-  gui._io          11 tests   (QueueWriter, no GUI required)
+  compat              11 tests
+  config               5 tests
+  parser               9 tests
+  compare              8 tests
+  fetcher             24 tests   (pure functions + mock)
+  reporter             8 tests
+  linker              12 tests   (uses temp dirs)
+  __init__             2 tests
+  check_names         16 tests
+  integration          2 tests
+  gui._io             11 tests   (QueueWriter, no GUI required)
+  cleaner              8 tests
+  e2e — clean_orphans  6 tests   (subprocess CLI)
+  coverage gaps       23 tests   (mocked platform branches)
+  live server          9 tests   (skipped if server unreachable)
 ------------------------------------------------------------
-  Results: 95 passed, 1 failed, 0 skipped  (96 total)
+  Results: 142 passed, 0 failed, 0 skipped  (142 total)
 ```
-
-> The 1 failing test is a pre-existing comparison snapshot mismatch unrelated to the GUI changes.
--- a/docs/huong-dan-su-dung.md
+++ b/docs/huong-dan-su-dung.md
@@ -13,6 +13,11 @@ Tài liệu này dành cho người dùng **chưa biết gì** về dự án. B
 5. [Tổng quan (Dashboard) — Quy trình cơ bản](#5-tổng-quan-dashboard--quy-trình-cơ-bản)
 6. [Danh sách Mod](#6-danh-sách-mod)
 7. [Công cụ nâng cao](#7-công-cụ-nâng-cao)
+   - [Check Names](#tab-check-names--kiểm-tra-tên-thư-mục)
+   - [Update Mods](#tab-update-mods--cập-nhật-mod)
+   - [Link Mods](#tab-link-mods--quản-lý-liên-kết)
+   - [Sync / Report Missing](#tab-sync-missing--đồng-bộ-mod-thiếu)
+   - [Clean Orphans](#tab-clean-orphans--dọn-dẹp-mod-thừa)
 8. [Nhật ký (Logs)](#8-nhật-ký-logs)
 9. [Cài đặt](#9-cài-đặt)
 10. [Đổi sang giao diện tiếng Việt](#10-đổi-sang-giao-diện-tiếng-việt)
@@ -212,6 +217,14 @@ Gõ vào ô **Tìm kiếm:** để lọc mod theo tên trong tab đang xem.

 Trang **Công cụ** có 5 tab phụ cho các tác vụ bảo trì. Mỗi tab đều có nút chạy ở góc phải phía dưới, output hiển thị trong **Nhật ký**.

+| Tab | Chức năng tóm tắt |
+|-----|-------------------|
+| Check Names | Kiểm tra và sửa tên thư mục mod |
+| Update Mods | Tải lại tệp mod đã thay đổi trên máy chủ |
+| Link Mods | Tạo / xóa junction tới Arma 3 Server |
+| Sync / Report Missing | Đồng bộ và báo cáo mod còn thiếu |
+| **Clean Orphans** | Xóa thư mục mod thừa từ preset cũ |
+
 ### Tab "Check Names" — Kiểm tra tên thư mục

 Quét thư mục mod trên máy tính và so sánh với máy chủ. Báo cáo các vấn đề:
@@ -254,6 +267,22 @@ Thử tải lại các mod bị thiếu từ lần chạy pipeline trước. H

 Kiểm tra mod nào trong `comparison.json` chưa có trên máy chủ và lưu báo cáo vào `missing_report.json`. Dùng để theo dõi mod cần yêu cầu admin bổ sung.

+### Tab "Clean Orphans" — Dọn dẹp mod thừa
+
+Khi bạn đổi preset và chạy lại pipeline, các mod của preset cũ vẫn còn trong thư mục `downloads/` nhưng không được dùng nữa — gọi là **mod thừa** (orphan). Tab này giúp tìm và xóa chúng để giải phóng dung lượng ổ đĩa.
+
+**Cách dùng:**
+
+1. Nhấn **Quét mod thừa** — ứng dụng sẽ so sánh thư mục `downloads/` với `comparison.json` hiện tại
+2. Danh sách mod thừa hiện ra kèm tên nhóm và dung lượng
+3. Dùng **Chọn tất cả** hoặc tick thủ công từng mục
+4. Nhấn **Xóa đã chọn** — xuất hiện hộp thoại xác nhận
+5. Nhấn **Xác nhận xóa** để thực hiện; danh sách sẽ tự động quét lại sau khi xóa
+
+> **Lưu ý an toàn:** Ứng dụng chỉ xóa thư mục `@ModName` trong `downloads/`, không đụng tới thư mục Arma 3 Server. Junction (liên kết) sẽ bị xóa đúng cách mà không làm mất tệp gốc.
+
+**Yêu cầu:** Cần có `comparison.json` (chạy pipeline ít nhất một lần trước).
+
 ---

 ## 8. Nhật ký (Logs)
@@ -372,8 +401,9 @@ Hiển thị các đường dẫn đang dùng: URL máy chủ, thư mục Arma,
 | **comparison.json** | Tệp kết quả so sánh preset, lưu danh sách mod theo nhóm |
 | **missing_report.json** | Báo cáo mod có trong preset nhưng chưa có trên máy chủ |
 | **downloads/** | Thư mục chứa tệp mod đã tải về |
+| **Mod thừa (Orphan)** | Thư mục mod còn trong `downloads/` nhưng không còn trong preset nào đang dùng |
 | **config.json** | Tệp cấu hình lưu thông tin máy chủ và đường dẫn |

 ---

-*Phiên bản tài liệu: 2026-04. Nếu có vấn đề, liên hệ người quản trị máy chủ.*
+*Phiên bản tài liệu: 2026-04 (cập nhật: thêm Clean Orphans). Nếu có vấn đề, liên hệ người quản trị máy chủ.*