chore: update ai-review findings [skip ci]

.gitea/ai-review/findings.json

@@ -1,23 +1,51 @@
 [
-  {
-    "level": "critical",
-    "role": "Rex",
-    "location": "Dockerfile:4",
-    "suggestion": "原先使用 `--no-check-certificate` 會禁用 SSL/TLS 憑證驗證，使 `apk` 套件管理器容易受到中間人 (MITM) 攻擊。本次變更已正確移除此選項，確保 `apk` 會驗證憑證，有效防範此類攻擊。這是一個重要的安全改進。",
-    "is_new": true
-  },
-  {
-    "level": "critical",
-    "role": "Rex",
-    "location": "entrypoint.sh:130 (舊版), entrypoint.sh:299 (舊版)",
-    "suggestion": "在本次變更之前，`api_request` 及其呼叫者（例如 `fetch_package_versions` 和 `process_candidates`）在建構 API 請求的 URL 路徑時，直接將 `REPO_OWNER`、`name` 和 `version` 等變數插入 URL，而未進行適當的 URL 編碼。這可能導致 URL 路徑遍歷 (Path Traversal) 或注入攻擊，特別是當這些變數包含特殊字元（如 `/` 或 `..`）時。本次變更引入並一致地使用 `url_encode()` 函數對所有路徑組件進行編碼，有效防止了此類 URL 注入和路徑遍歷漏洞，是一個關鍵的安全修復。",
-    "is_new": true
-  },
   {
     "level": "critical",
     "role": "Maya",
     "location": "entrypoint.sh",
     "suggestion": "此 Git Diff 包含了對 `entrypoint.sh` 腳本的大量重構和新功能引入，但完全沒有提供任何測試程式碼。這是一個嚴重的品質問題。對於如此複雜的業務邏輯和多個新引入的工具函數，必須提供單元測試和整合測試，以確保其正確性、穩定性和邊界條件的處理。",
+    "is_new": false
+  },
+  {
+    "level": "critical",
+    "role": "Maya",
+    "location": "entrypoint.sh:13",
+    "suggestion": "新增的 `trim` 函數是許多其他函數的基礎，其正確性至關重要。請為 `trim` 函數編寫單元測試，涵蓋輸入為空字串、僅包含空白字元、前後有空白字元、以及沒有空白字元的字串等情境。",
+    "is_new": true
+  },
+  {
+    "level": "critical",
+    "role": "Maya",
+    "location": "entrypoint.sh:20",
+    "suggestion": "新增的 `url_encode` 函數用於構建 API 路徑，直接影響請求的正確性和安全性。請為 `url_encode` 函數編寫單元測試，涵蓋包含特殊字元、空格、已編碼字元以及一般字元的輸入，確保其符合 RFC 3986 標準。",
+    "is_new": true
+  },
+  {
+    "level": "critical",
+    "role": "Maya",
+    "location": "entrypoint.sh:44",
+    "suggestion": "重構後的 `resolve_package_names` 函數邏輯複雜，涉及字串處理、分割和去重。請為其編寫單元測試，涵蓋以下情境：空輸入、僅空白字元、單一套件名稱、多個套件名稱（逗號分隔、換行符分隔、混合分隔）、帶有前後空白字元的套件名稱、以及重複的套件名稱，確保輸出是唯一且正確的列表。",
+    "is_new": true
+  },
+  {
+    "level": "critical",
+    "role": "Maya",
+    "location": "entrypoint.sh:70",
+    "suggestion": "重構後的 `parse_repo_context` 函數是解析 Gitea 儲存庫資訊的關鍵。請為其編寫單元測試，涵蓋有效格式（例如 `owner/repo`）、空輸入、僅空白字元、缺少 owner 或 repo、以及無效格式（例如 `owner`、`owner/`、`/repo`、`owner/repo/extra`）等情境，確保其能正確解析或報錯。",
+    "is_new": true
+  },
+  {
+    "level": "critical",
+    "role": "Maya",
+    "location": "entrypoint.sh:120",
+    "suggestion": "重構後的 `fetch_package_versions` 函數負責分頁獲取套件版本，邏輯複雜。請為其編寫整合測試，涵蓋單頁、多頁、空結果、套件不存在（404 回應）、以及 API 錯誤等情境。特別要驗證 `url_encode` 在構建 URL 時的正確性。",
+    "is_new": true
+  },
+  {
+    "level": "critical",
+    "role": "Maya",
+    "location": "entrypoint.sh:170",
+    "suggestion": "重構後的 `collect_package_candidates` 函數是決定哪些版本應被刪除的核心邏輯。請為其編寫整合測試，驗證在不同 `keep_count` 值（0、1、等於總版本數、大於總版本數）下，候選版本是否正確選取。同時，確保版本排序邏輯（`created_at` 和 `version`）的正確性。",
     "is_new": true
   },
   {
@@ -25,20 +53,34 @@
     "role": "Zara",
     "location": "entrypoint.sh:125, entrypoint.sh:126, entrypoint.sh:240, entrypoint.sh:241",
     "suggestion": "在 `fetch_package_versions` 函式中，`page_file` 和 `headers_file` 在 `while` 迴圈的每次迭代中都被建立和刪除。同樣地，在 `process_candidates` 函式中，`body_file` 和 `headers_file` 也在迴圈中重複建立和刪除。這會導致頻繁的 `mktemp` 和 `rm -f` 系統呼叫，增加 I/O 和程序啟動的開銷，尤其是在處理大量分頁或多個待刪除版本時。建議在迴圈外部只建立一次這些暫存檔案，並在迴圈內部重複使用它們，最後在函式結束時統一刪除。",
-    "is_new": true
+    "is_new": false
   },
   {
     "level": "warning",
     "role": "Rex",
     "location": "entrypoint.sh:105",
     "suggestion": "`GITEA_SERVER_URL` 變數直接用於建構 API 請求的基礎 URL。如果此變數可被攻擊者控制，可能導致 API 請求被重定向到惡意伺服器。請確保 `GITEA_SERVER_URL` 始終來自受信任、不可變的配置或環境變數。如果它可能來自使用者輸入，則必須實施嚴格的驗證。",
+    "is_new": false
+  },
+  {
+    "level": "warning",
+    "role": "Maya",
+    "location": "entrypoint.sh:30",
+    "suggestion": "重構後的 `resolve_keep_count` 函數需要更全面的邊界條件測試。請新增測試案例，驗證其在 `INPUT_KEEP_COUNT` 為空、僅包含空白字元、非數字、負數、零、以及各種正整數時的行為是否符合預期。",
     "is_new": true
   },
   {
-    "level": "info",
-    "role": "Leo",
-    "location": "entrypoint.sh:7",
-    "suggestion": "目前的 `log` 函式僅將訊息輸出到標準錯誤。對於需要更進階日誌管理（例如日誌級別、時間戳、結構化日誌格式如 JSON，以便於日誌聚合系統解析）的生產環境，可以考慮增強此函式。然而，對於此類型的 shell script 而言，目前的實作是可接受且常見的，並非嚴重的可維護性問題。",
+    "level": "warning",
+    "role": "Maya",
+    "location": "entrypoint.sh:88",
+    "suggestion": "`api_request` 函數是與 Gitea API 互動的核心。由於其涉及外部網路請求，建議使用模擬（mocking）或整合測試來驗證其行為。請測試不同 HTTP 狀態碼（2xx, 4xx, 5xx）、網路錯誤、以及正確解析回應標頭（如 `x-gitea-request-id`）和回應主體的邏輯。",
+    "is_new": true
+  },
+  {
+    "level": "warning",
+    "role": "Maya",
+    "location": "entrypoint.sh:230",
+    "suggestion": "`process_candidates` 函數執行實際的刪除操作。請新增測試案例，模擬 API 刪除請求失敗（例如 4xx 或 5xx 錯誤），以驗證錯誤處理、日誌記錄和錯誤計數是否正確。這對於確保腳本在部分失敗時的健壯性至關重要。",
     "is_new": true
   },
   {
@@ -46,34 +88,41 @@
     "role": "Zara",
     "location": "entrypoint.sh:149",
     "suggestion": "在 `fetch_package_versions` 函式中，每次取得新分頁資料後，都透過 `jq -s '.[0] + .[1]'` 將新資料與已聚合的資料合併。這會導致 `jq` 程序被重複啟動，並且每次合併都需要重新讀取和解析所有已聚合的 JSON 資料，效率會隨著資料量增加而降低。建議考慮更高效的 JSON 聚合策略，例如將所有分頁的 JSON 陣列收集起來，最後一次性地合併，或者使用 `jq` 的 streaming 模式（如果適用）來減少重複處理的開銷。",
-    "is_new": true
+    "is_new": false
   },
   {
     "level": "info",
     "role": "Zara",
     "location": "entrypoint.sh:204, entrypoint.sh:215",
     "suggestion": "在 `collect_package_candidates` 函式中，針對每個套件的版本清單，`jq` 被呼叫兩次進行排序：一次用於日誌輸出，另一次用於選取待刪除的候選版本。雖然 `jq` 排序效率高，但兩次外部程序呼叫仍會產生額外開銷。建議優化為只排序一次，然後將排序後的結果用於後續的日誌記錄和候選版本篩選，以減少重複的計算和程序啟動。",
-    "is_new": true
+    "is_new": false
   },
   {
     "level": "info",
     "role": "Aria",
     "location": "entrypoint.sh:148",
     "suggestion": "在 `fetch_package_versions` 函數中，`limit=100` 是一個硬編碼的數值。考慮將此值定義為一個具名的變數（例如 `PAGE_LIMIT`），以提高可讀性和未來的可配置性。",
-    "is_new": true
+    "is_new": false
   },
   {
     "level": "info",
     "role": "Maya",
     "location": "entrypoint.sh",
     "suggestion": "考慮引入一個專門的 shell 腳本測試框架，例如 `bats-core` 或 `shUnit2`，來組織和執行這些測試。這將大大提高測試的可維護性和可讀性。",
+    "is_new": false
+  },
+  {
+    "level": "info",
+    "role": "Zara",
+    "location": "entrypoint.sh:L30-L35 (url_encode)",
+    "suggestion": "在 `process_candidates` 函數中，`url_encode` 函數在刪除迴圈內被呼叫了三次（針對 `owner`、`package_name` 和 `version`）。雖然 `jq` 執行速度快，但每次呼叫都會產生一個新的子程序。對於 `owner` 參數，由於其值在整個刪除過程中是固定的，可以考慮在迴圈外部只呼叫一次 `url_encode` 並將結果儲存起來，以避免不必要的重複子程序開銷，進一步微調效能。",
     "is_new": true
   },
   {
     "level": "info",
     "role": "Maya",
-    "location": "entrypoint.sh:293",
-    "suggestion": "腳本末尾的 `if [[ \"${BASH_SOURCE[0]}\" == \"$0\" ]]; then main \"$@\"; fi` 結構是一個很好的實踐，它使得腳本中的函數可以被其他測試腳本 `source` 並單獨調用，從而提高了可測試性。現在應該利用這個優勢來編寫實際的測試。",
+    "location": "entrypoint.sh",
+    "suggestion": "除了單元測試和整合測試，建議開發端到端（E2E）測試。這些測試應在一個隔離的測試環境中運行 `main` 函數，並與一個模擬的 Gitea 實例或專用的測試 Gitea 實例互動，以驗證整個工作流程的正確性。",
     "is_new": true
   }
 ]