chore(ai-review 狀態): 清空 findings 並登記排序 top-K 建議為誤報

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.gitea/ai-review/exclusions.json

@@ -134,5 +134,13 @@
     "role": "Bard",
     "original_finding": "統一成同一套語彙，例如把 `section()` 改成 `setLogSection()`，並讓相關變數名稱也跟著一致。",
     "reason": "AI 對話收斂判定為誤報（問題在最新程式碼中不成立或不適用）"
+  },
+  {
+    "location": "src/index.js:363",
+    "role": "Rogue",
+    "original_finding": "改用固定大小的 top-K 選擇策略，例如維持一個大小為 `KEEP_COUNT` 的最小堆，或在 API 已經有新到舊順序時直接取前 `KEEP_COUNT` 筆，避免整體排序。",
+    "reason": "release 數量預期不大，全量排序成本可忽略；後續同時需要「保留的前 K 筆」與「其餘待刪清單」，一次排序是最直接清楚的實作，引入 top-K 堆反而增加複雜度（與既有「分頁結果先完整收集到陣列」的排除理由一致）。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-15"
   }
 ]

.gitea/ai-review/findings.json

@@ -1,98 +1 @@
-[
-  {
-    "level": "critical",
-    "role": "Mage",
-    "problem": "這裡在刪除 tag 的流程中只把失敗記進 `hadFailure`，但流程結束後沒有再檢查或拋錯。最小重現：只要任一個 tag 刪除回傳 404/500，程式仍會以 0 結束，外層 CI 會誤判為清理成功，但實際上遺留的 tag 還在。",
-    "suggestion": "在 `processInBatches(tagJson, ...)` 結束後補上 `if (hadFailure) throw new Error(...)`，讓任何 tag 刪除失敗都會正確回傳非 0 狀態。",
-    "location": "src/index.js:400",
-    "is_new": false
-  },
-  {
-    "level": "warning",
-    "role": "Mage",
-    "problem": "`Promise.all` 只要其中一個刪除任務拋出 reject，整個 batch 會立刻失敗，外層 `main().catch(...)` 也會直接結束。這代表只要某一筆 release 或 tag 遇到網路中斷、DNS 失敗、連線逾時，後續同 batch 的項目就不會再處理，清理流程會在半途中停住。",
-    "suggestion": "把每個 item 的刪除包在個別 `try/catch`，或改用 `Promise.allSettled` 後統一彙總失敗；至少要確保單筆失敗不會中止同批其他清理工作。",
-    "location": "src/index.js:282",
-    "is_new": false
-  },
-  {
-    "level": "warning",
-    "role": "Assassin",
-    "problem": "這個驗證只擋掉非數字，`0` 仍然會通過；若攻擊者能控制 `KEEP_COUNT`，就能把保留數設成 0，後續流程會把所有 release 刪光，還會把所有未被保留的 tag 一併清掉。",
-    "suggestion": "把下限改成至少 `1`，並在進入刪除流程前再做一次保護檢查；如果真的需要全清，應該改成獨立的高風險開關，而不是混在一般輸入參數裡。",
-    "location": "src/index.js:169",
-    "is_new": false
-  },
-  {
-    "level": "warning",
-    "role": "Assassin",
-    "location": "src/index.js:252",
-    "problem": "`GITEA_REPOSITORY` 直接字串串進 release API 路徑，沒有做格式驗證或路徑編碼。只要這個值被污染，攻擊者就能把 `../`、額外斜線或其他路徑片段塞進去，讓帶著授權 token 的請求打到非預期的 API 路徑，擴大刪除面。",
-    "suggestion": "先把 repository 嚴格限制為 `owner/repo` 這種固定格式，再對 owner 與 repo 各自做 `encodeURIComponent` 後組 URL，不要直接把原字串拼進路徑。",
-    "is_new": true
-  },
-  {
-    "level": "warning",
-    "role": "Assassin",
-    "location": "src/index.js:319",
-    "problem": "這裡同樣把未驗證的 `GITEA_REPOSITORY` 直接拼到 tag API 路徑。若輸入被操弄，攻擊者可以藉由路徑注入把刪除請求導向非預期資源，配合授權 token 造成超出原本 repo 範圍的破壞。",
-    "suggestion": "和 release API 一樣，對 repository 做嚴格格式檢查並逐段編碼後再組合路徑，必要時拒絕任何包含額外 `/`、`.` 或保留字元的值。",
-    "is_new": true
-  },
-  {
-    "level": "warning",
-    "role": "Leo",
-    "location": "src/index.js:227",
-    "problem": "`processInBatches()` 用 `Promise.all` 搭配外層共享的 `hadFailure`，失敗語意會變得很難推理：一筆例外會直接中斷整批，但其他並行工作仍可能繼續跑，最後到底刪了哪些、漏了哪些，不看執行細節很難判斷。這種控制流對日後補測試或改錯誤處理都不友善。",
-    "suggestion": "把每筆處理的結果收斂成明確的成功/失敗回傳值，或在批次內逐筆捕捉錯誤後再彙總；若要保留並行，至少讓批次函式回傳可測試的結果集合，而不是依賴外部可變狀態。",
-    "is_new": true
-  },
-  {
-    "level": "warning",
-    "role": "Mage",
-    "location": "src/index.js:345",
-    "problem": "`GITEA_SERVER_URL` 只做非空檢查，沒有先確認它是合法的絕對 URL。只要傳入像 `gitea.local`、`https://` 這類看起來有值但格式不合法的字串，`new URL()` 就會直接丟出未處理例外，錯誤也不會明確指出是參數格式問題。",
-    "suggestion": "在進入主流程前先對 `GITEA_SERVER_URL` 做 `try/catch` 驗證，失敗時回傳明確的參數錯誤並結束；不要把 URL 解析失敗留到中途才爆。",
-    "is_new": true
-  },
-  {
-    "level": "warning",
-    "role": "Mage",
-    "location": "src/index.js:336",
-    "problem": "`KEEP_COUNT` 只驗證是數字字串，沒有保證落在安全整數範圍內。像 `9007199254740993` 這種值會在 `Number()` 轉換時失真，導致 `releaseCount <= keepCount` 與 `slice(keepCount)` 的保留/刪除判斷偏掉，最終清理結果可能和設定不一致。",
-    "suggestion": "除了字串格式外，還要驗證 `Number.isSafeInteger(Number(KEEP_COUNT))`，並加上合理上限；超出範圍時直接報錯，避免用不精確的數值做刪除決策。",
-    "is_new": true
-  },
-  {
-    "level": "warning",
-    "role": "Rogue",
-    "location": "src/index.js:363",
-    "problem": "`releaseJson.sort(...)` 先把所有 release 做完整排序，成本是 O(n log n)，但後面其實只用前 `KEEP_COUNT` 筆。當 release 很多時，這段排序就是多花 CPU 在不必要的全量比較上。",
-    "suggestion": "改用固定大小的 top-K 選擇策略，例如維持一個大小為 `KEEP_COUNT` 的最小堆，或在 API 已經有新到舊順序時直接取前 `KEEP_COUNT` 筆，避免整體排序。",
-    "is_new": true
-  },
-  {
-    "level": "warning",
-    "role": "Rogue",
-    "location": "src/index.js:230",
-    "problem": "這裡對每個 request 都先建立 `chunks` 陣列、收完整個 response body，再 `join` 成字串。刪除 release/tag 時大多只需要狀態碼，還硬把回應內容完整緩衝進記憶體，會在大量刪除時增加不必要的配置與拷貝。",
-    "suggestion": "把 request 包成可選擇是否收集 body；對 DELETE 這類不需要回應內容的呼叫直接丟棄資料串流，只保留 status code。",
-    "is_new": true
-  },
-  {
-    "level": "info",
-    "role": "Assassin",
-    "problem": "分頁迴圈沒有上限，只要對方持續回傳非空頁面，這個 action 就會無限抓取；惡意或故障中的 API 可以把 runner 卡死，消耗時間與配額。",
-    "suggestion": "加入最大頁數、重複頁檢測或總筆數上限，超過就中止並回報異常，避免被外部回應拖成無限迴圈。",
-    "location": "src/index.js:228",
-    "is_new": false
-  },
-  {
-    "level": "info",
-    "role": "Leo",
-    "problem": "在 `catch` 裡先把 `currentStage` 清空再記錄錯誤，會讓最後那筆失敗 log 失去「到底是在哪個階段炸掉」的上下文。等到未來有人要追問題時，只能回頭翻前面的輸出，比對成本會很高。",
-    "suggestion": "保留最後的 `currentStage`，或在進入 `catch` 時把階段一起寫進錯誤訊息；如果擔心汙染後續輸出，可以在輸出完成後再重設，而不是先清空。",
-    "location": "src/index.js:409",
-    "is_new": false
-  }
-]
+[]

src/index.js

@@ -191,14 +191,52 @@ function requireValue(name, value, displayValue = value) {
 }
 
 /**
- * 驗證字串是否為非負整數。
+ * 驗證字串是否為正整數，且落在安全整數範圍內；下限 1 可避免把保留數設成 0 而清空所有 release。
  *
  * @param {string} name 參數名稱。
  * @param {string} value 參數值。
  */
-function requireInteger(name, value) {
-  if (!/^[0-9]+$/.test(value)) {
-    fail(`${name} must be a non-negative integer`);
+function requirePositiveInteger(name, value) {
+  if (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1) {
+    fail(`${name} must be a positive integer within the safe integer range`);
+    process.exit(1);
+  }
+}
+
+/**
+ * 驗證值是否為合法的 HTTPS 絕對 URL，避免 URL 解析失敗留到主流程中途才拋出。
+ *
+ * @param {string} name 參數名稱。
+ * @param {*} value 參數值。
+ */
+function requireHttpsUrl(name, value) {
+  let parsed;
+  try {
+    parsed = new URL(String(value));
+  } catch (error) {
+    fail(`${name} must be a valid absolute URL`);
+    process.exit(1);
+  }
+
+  if (parsed.protocol !== 'https:') {
+    fail(`${name} must use HTTPS`);
+    process.exit(1);
+  }
+}
+
+/**
+ * 驗證 repository 是否為 `owner/repo` 格式且僅含安全字元，拒絕 `.`、`..` 等路徑片段。
+ *
+ * @param {string} name 參數名稱。
+ * @param {*} value 參數值。
+ */
+function requireRepository(name, value) {
+  const segments = String(value).split('/');
+  const isValidSegment = (segment) =>
+    /^[A-Za-z0-9_.-]+$/.test(segment) && segment !== '.' && segment !== '..';
+
+  if (segments.length !== 2 || !segments.every(isValidSegment)) {
+    fail(`${name} must be in owner/repo format`);
     process.exit(1);
   }
 }
@@ -207,10 +245,10 @@ function requireInteger(name, value) {
  * 對指定 URL 發送 request，回傳狀態碼與 body。
  *
  * @param {string} url 完整目標網址。
- * @param {{ method?: string, headers?: Record<string, string> }} [options] request 設定。
+ * @param {{ method?: string, headers?: Record<string, string>, collectBody?: boolean }} [options] request 設定；`collectBody` 為 `false` 時丟棄回應內容、只保留狀態碼。
  * @returns {Promise<{ statusCode: number, body: string }>} 回應狀態碼與內容。
  */
-function request(url, { method = 'GET', headers = {} } = {}) {
+function request(url, { method = 'GET', headers = {}, collectBody = true } = {}) {
   return new Promise((resolve, reject) => {
     const target = new URL(url);
     if (target.protocol !== 'https:') {
@@ -226,6 +264,16 @@ function request(url, { method = 'GET', headers = {} } = {}) {
         agent: keepAliveAgent,
       },
       (res) => {
+        const statusCode = res.statusCode || 0;
+
+        if (!collectBody) {
+          res.resume();
+          res.on('end', () => {
+            resolve({ statusCode, body: '' });
+          });
+          return;
+        }
+
         const chunks = [];
 
         res.setEncoding('utf8');
@@ -234,7 +282,7 @@ function request(url, { method = 'GET', headers = {} } = {}) {
         });
         res.on('end', () => {
           resolve({
-            statusCode: res.statusCode || 0,
+            statusCode,
             body: chunks.join(''),
           });
         });
@@ -300,21 +348,49 @@ async function deleteResource(url, headers) {
   return request(url, {
     method: 'DELETE',
     headers,
+    collectBody: false,
   });
 }
 
 /**
- * 以固定批次大小處理項目，降低逐筆等待造成的延遲。
+ * 以固定批次大小處理項目，降低逐筆等待造成的延遲；單筆例外不會中止同批其他項目。
  *
  * @param {any[]} items 要處理的項目。
  * @param {number} batchSize 每批同時處理的數量。
- * @param {(item: any) => Promise<void>} handler 單筆處理函式。
+ * @param {(item: any) => Promise<boolean>} handler 單筆處理函式，回傳該筆是否成功。
+ * @returns {Promise<PromiseSettledResult<boolean>[]>} 依原始順序排列的處理結果。
  */
 async function processInBatches(items, batchSize, handler) {
+  const results = [];
+
   for (let index = 0; index < items.length; index += batchSize) {
     const batch = items.slice(index, index + batchSize);
-    await Promise.all(batch.map((item) => handler(item)));
+    results.push(...(await Promise.allSettled(batch.map((item) => handler(item)))));
   }
+
+  return results;
+}
+
+/**
+ * 彙總批次結果；記錄被 reject 的例外，並回傳是否有任何一筆失敗。
+ *
+ * @param {PromiseSettledResult<boolean>[]} results 批次處理結果。
+ * @returns {boolean} 只要有任一筆失敗即回傳 `true`。
+ */
+function hasBatchFailure(results) {
+  let failed = false;
+
+  for (const result of results) {
+    if (result.status === 'rejected') {
+      failed = true;
+      const reason = result.reason;
+      fail(`批次處理發生例外: ${reason instanceof Error ? reason.message : String(reason)}`);
+    } else if (result.value === false) {
+      failed = true;
+    }
+  }
+
+  return failed;
 }
 
 /**
@@ -328,9 +404,11 @@ async function main() {
 
   section('參數檢查');
   requireValue('GITEA_SERVER_URL', GITEA_SERVER_URL, maskUrlForLog(GITEA_SERVER_URL));
+  requireHttpsUrl('GITEA_SERVER_URL', GITEA_SERVER_URL);
   requireValue('GITEA_REPOSITORY', GITEA_REPOSITORY);
+  requireRepository('GITEA_REPOSITORY', GITEA_REPOSITORY);
   requireValue('KEEP_COUNT', KEEP_COUNT);
-  requireInteger('KEEP_COUNT', KEEP_COUNT);
+  requirePositiveInteger('KEEP_COUNT', KEEP_COUNT);
 
   const keepCount = Number(KEEP_COUNT);
   const authHeaders = {};
@@ -348,7 +426,8 @@ async function main() {
   serverBase.hash = '';
   const serverBaseUrl = serverBase.toString().replace(/\/+$/, '');
 
-  const releaseApiUrl = `${serverBaseUrl}/api/v1/repos/${GITEA_REPOSITORY}/releases`;
+  const repositoryPath = GITEA_REPOSITORY.split('/').map(encodeURIComponent).join('/');
+  const releaseApiUrl = `${serverBaseUrl}/api/v1/repos/${repositoryPath}/releases`;
 
   section('取得成品資訊');
   info(`GET ${releaseApiUrl}`);
@@ -370,21 +449,19 @@ async function main() {
   info(`RELEASE_COUNT=${releaseCount}`);
   info(`KEEP_COUNT=${KEEP_COUNT}`);
 
-  let hadFailure = false;
-
   if (releaseCount <= keepCount) {
     info('沒有需要清理的舊版本成品');
   } else {
     section('刪除舊版本成品');
 
     const releaseToDelete = releaseJson.slice(keepCount);
-    await processInBatches(releaseToDelete, DELETE_CONCURRENCY, async (releaseItem) => {
+    const releaseResults = await processInBatches(releaseToDelete, DELETE_CONCURRENCY, async (releaseItem) => {
       const releaseId = releaseItem?.id;
       if (!Number.isSafeInteger(releaseId) || releaseId <= 0) {
         warn(
           `略過 id 不是正整數的成品: ${sanitizeLogText(releaseItem?.tag_name || '')} (${sanitizeLogText(releaseItem?.name || '')})`,
         );
-        return;
+        return true;
       }
 
       const releaseTag = sanitizeLogText(releaseItem.tag_name || '');
@@ -395,16 +472,17 @@ async function main() {
       const { statusCode } = await deleteResource(deleteUrl, authHeaders);
       if (statusCode === 204) {
         info(`成功刪除: ${releaseTag} (${releaseName})`);
-      } else {
-        hadFailure = true;
-        fail(`刪除失敗: ${releaseTag} (${releaseName}), HTTP ${statusCode}`);
-      }
-    });
+        return true;
       }
 
-  if (hadFailure) {
+      fail(`刪除失敗: ${releaseTag} (${releaseName}), HTTP ${statusCode}`);
+      return false;
+    });
+
+    if (hasBatchFailure(releaseResults)) {
       throw new Error('至少有一筆 release 刪除失敗');
     }
+  }
 
   section('刪除未指定 release 的 tag');
 
@@ -415,23 +493,23 @@ async function main() {
       .filter((tag) => !isEmptyOrNull(tag)),
   );
 
-  const tagApiUrl = `${serverBaseUrl}/api/v1/repos/${GITEA_REPOSITORY}/tags`;
+  const tagApiUrl = `${serverBaseUrl}/api/v1/repos/${repositoryPath}/tags`;
   info(`GET ${tagApiUrl}`);
 
   const tagJson = await fetchAllPages(tagApiUrl, authHeaders);
   info(`TAG_COUNT=${tagJson.length}`);
 
-  await processInBatches(tagJson, DELETE_CONCURRENCY, async (tagItem) => {
+  const tagResults = await processInBatches(tagJson, DELETE_CONCURRENCY, async (tagItem) => {
     const tagName = tagItem?.name;
     if (isEmptyOrNull(tagName)) {
       warn('略過沒有名稱的 tag');
-      return;
+      return true;
     }
 
     const safeTagName = sanitizeLogText(tagName);
     if (releaseTags.has(tagName)) {
       info(`保留指定 release 的 tag: ${safeTagName}`);
-      return;
+      return true;
     }
 
     const deleteUrl = `${tagApiUrl}/${encodeURIComponent(tagName)}`;
@@ -440,13 +518,14 @@ async function main() {
     const { statusCode } = await deleteResource(deleteUrl, authHeaders);
     if (statusCode === 204) {
       info(`成功刪除未指定 release 的 tag: ${safeTagName}`);
-    } else {
-      hadFailure = true;
-      fail(`刪除 tag 失敗: ${safeTagName}, HTTP ${statusCode}`);
+      return true;
     }
+
+    fail(`刪除 tag 失敗: ${safeTagName}, HTTP ${statusCode}`);
+    return false;
   });
 
-  if (hadFailure) {
+  if (hasBatchFailure(tagResults)) {
     throw new Error('至少有一筆 tag 刪除失敗');
   }
 }