Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@@ -1,1 +9,4 @@
+# 指定基底映像為 Alpine Linux 最新版；Alpine 體積小，可縮小最終映像大小並加快拉取速度。
+# 需人工確認：使用 latest tag 會在不同時間建置出不同基底版本，可能影響可重現性，
+#             建議釘選明確版本（例如 alpine:3.20）以確保建置一致。
 FROM alpine:latest

@@ -1,2 +10,4 @@
+# 需人工確認：使用 latest tag 會在不同時間建置出不同基底版本，可能影響可重現性，
+#             建議釘選明確版本（例如 alpine:3.20）以確保建置一致。
 FROM alpine:latest
 

@@ -3,1 +14,4 @@
 # 安裝必要的工具
+# 安裝執行 code review 所需的工具：bash（執行 entrypoint 腳本）、git（前置遠端驗證／取得 diff）、
+# nodejs 與 npm（執行 app 內的 Node.js 程式）。
+# --no-cache：不保留 apk 套件索引快取，避免殘留在映像層中以減少映像大小。

@@ -4,2 +18,4 @@
+# 需人工確認：--no-check-certificate 會略過套件來源的憑證驗證，存在中間人攻擊風險，
+#             僅在內網或憑證受限環境下使用；正式環境建議移除以維持安全性。
 RUN apk add --no-cache --no-check-certificate bash git nodejs npm
 

@@ -11,0 +13,4 @@
+ *
+ * @param {{ level?: string, role?: string, location?: string, suggestion?: string }} f
+ *   單筆審查問題物件。`level` 若不在 critical/warning/info 之內，emoji 留空、標籤回退為原始 level 值；
+ *   `role`、`location`、`suggestion` 直接內嵌字串（未定義時會輸出 undefined 字樣）。傳入 null/undefined 會拋 TypeError（需人工確認是否需防呆）。

@@ -56,17 +103,48 @@ function reviewCommentBody(f) {
   ].join('\n');

@@ -15,0 +17,4 @@
+ * 供連接使用自簽或無效憑證的 OpenCode 服務時使用。
+ *
+ * @remarks 每次呼叫都會回傳全新的 Agent 實例（不快取），建議呼叫端重用以共用連線池。
+ *          停用憑證驗證有中間人攻擊風險，僅限受信任的內部環境使用。

@@ -54,0 +70,4 @@
+ *
+ * @param {string} fullPath - 目標檔案路徑；上層目錄須事先存在（本函式不建立目錄）。
+ * @param {Array<object>} exclusions - 欲寫入的排除條目陣列。
+ * @returns {void}

@@ -18,5 +18,5 @@
 
 /**
  * 透過 LLM 修正 JSON 陣列內容。
  * @param {string} fullPath 檔案路徑，供提示詞與除錯使用。
  * @param {string} label 檔案標籤。

@@ -49,0 +96,4 @@
+ *
+ * @param {string} systemPrompt - 系統提示詞。
+ * @param {string} userContent - 使用者輸入內容。
+ * @returns {Promise<string>} 模型回應的純文字內容。

@@ -59,5 +59,5 @@
   step('Step5', '角色分析產生 findings');
   const { provider, apiKeys, baseURL, model } = getLLMConfig();
   if (!provider) {
     result(false, '未設定任何 LLM API Key，請檢查 action inputs');
     process.exit(1);

@@ -125,2 +139,4 @@
 }
 
+/**
+ * 將一段仍成立（open）對話對應的 bot finding 加入結轉清單，標記 is_new=false 表示為延續的舊問題。

@@ -11,0 +12,4 @@
+ * 將單一 finding 格式化為 Markdown 表格的一列（等級｜審查員｜位置｜建議）。
+ *
+ * @param {{ level?: string, role?: string, location?: string, suggestion?: string }} f
+ *   單筆審查問題物件。`level` 若不在 critical/warning/info 之內，emoji 留空、標籤回退為原始 level 值；

@@ -21,0 +48,4 @@
+ * @param {{ level?: string, location?: string }} b 比較項 B。
+ * @returns {number} 負值代表 a 排在 b 之前，正值代表之後，0 代表相等（供 Array.prototype.sort 使用）。
+ * @remarks 不在 LEVEL_ORDER 內的等級一律視為最低優先（排在最後）；location 未定義時以空字串參與比較，因此排序穩定不會丟例外。
+ */

@@ -15,0 +18,4 @@
+ *
+ * @remarks 每次呼叫都會回傳全新的 Agent 實例（不快取），建議呼叫端重用以共用連線池。
+ *          停用憑證驗證有中間人攻擊風險，僅限受信任的內部環境使用。
+ * @returns {import('https').Agent} 已關閉憑證驗證的 HTTPS Agent 實例。

@@ -58,0 +81,4 @@
+/**
+ * 將檔案 mtime（毫秒時間戳）格式化為 ISO 字串，無效值回傳 'unknown'。
+ *
+ * @param {number} mtimeMs - 毫秒時間戳（通常為 fs.Stats.mtimeMs）。

@@ -69,0 +143,4 @@
+ * @param {string} repoDir git 工作目錄路徑。
+ * @param {typeof import('child_process').spawnSync} [_spawnSync=spawnSync]
+ *        測試用依賴注入。
+ * @returns {boolean} HEAD 訊息含機器人標記時為 true；讀取失敗時安全地回傳 false。

@@ -111,0 +191,4 @@
+ * 將 AI 審查產出的 review 檔（findings / exclusions）結轉到 repo，並 commit、
+ * push 回 PR head branch。流程：設定機器人 git 身分 → fetch + hard reset 對齊
+ * 遠端 → 從 workspace 複製存在的 review 檔到 repo 並 add → 若無變更則跳過 →
+ * 以含 `BOT_COMMIT_MARKER` 與結果標籤的訊息 commit → push。

@@ -65,5 +65,5 @@
       const original = readJSONText(fullPath, label);
       const repaired = await repairer(fullPath, label, original);
       fs.writeFileSync(fullPath, repaired.endsWith('\n') ? repaired : `${repaired}\n`, 'utf8');
       JSON.parse(readJSONText(fullPath, label));
       ok(`${label} 已由 AI 修正並通過再次驗證`);

@@ -11,0 +12,4 @@
+ * 將單一 finding 格式化為 Markdown 表格的一列（等級｜審查員｜位置｜建議）。
+ *
+ * @param {{ level?: string, role?: string, location?: string, suggestion?: string }} f
+ *   單筆審查問題物件。`level` 若不在 critical/warning/info 之內，emoji 留空、標籤回退為原始 level 值；

@@ -58,0 +81,4 @@
+/**
+ * 將檔案 mtime（毫秒時間戳）格式化為 ISO 字串，無效值回傳 'unknown'。
+ *
+ * @param {number} mtimeMs - 毫秒時間戳（通常為 fs.Stats.mtimeMs）。

@@ -65,5 +65,5 @@
       const original = readJSONText(fullPath, label);
       const repaired = await repairer(fullPath, label, original);
       fs.writeFileSync(fullPath, repaired.endsWith('\n') ? repaired : `${repaired}\n`, 'utf8');
       JSON.parse(readJSONText(fullPath, label));
       ok(`${label} 已由 AI 修正並通過再次驗證`);

@@ -21,0 +48,4 @@
+ * @param {{ level?: string, location?: string }} b 比較項 B。
+ * @returns {number} 負值代表 a 排在 b 之前，正值代表之後，0 代表相等（供 Array.prototype.sort 使用）。
+ * @remarks 不在 LEVEL_ORDER 內的等級一律視為最低優先（排在最後）；location 未定義時以空字串參與比較，因此排序穩定不會丟例外。
+ */

@@ -15,0 +18,4 @@
+ *
+ * @remarks 每次呼叫都會回傳全新的 Agent 實例（不快取），建議呼叫端重用以共用連線池。
+ *          停用憑證驗證有中間人攻擊風險，僅限受信任的內部環境使用。
+ * @returns {import('https').Agent} 已關閉憑證驗證的 HTTPS Agent 實例。

@@ -69,0 +143,4 @@
+ * @param {string} repoDir git 工作目錄路徑。
+ * @param {typeof import('child_process').spawnSync} [_spawnSync=spawnSync]
+ *        測試用依賴注入。
+ * @returns {boolean} HEAD 訊息含機器人標記時為 true；讀取失敗時安全地回傳 false。

@@ -111,0 +191,4 @@
+ * 將 AI 審查產出的 review 檔（findings / exclusions）結轉到 repo，並 commit、
+ * push 回 PR head branch。流程：設定機器人 git 身分 → fetch + hard reset 對齊
+ * 遠端 → 從 workspace 複製存在的 review 檔到 repo 並 add → 若無變更則跳過 →
+ * 以含 `BOT_COMMIT_MARKER` 與結果標籤的訊息 commit → push。

@@ -0,0 +30,4 @@
+      capturedUserContent = userContent;
+      return '```json\n[{"fixed":true}]\n```';
+    });
+