# ============================================================================
# 用途：定義 AI Code Review Node action 的名稱、輸入參數與 Node.js 24 進入點，供 Gitea / GitHub workflow 以 uses 引用。
# 更新時間：2026/07/28 13:57:24
# ============================================================================
# Gitea / GitHub node action 的 manifest（action.yml）：
# 定義本 action 的名稱、說明、輸入參數（inputs）與執行方式（runs），
# 供呼叫端 workflow 以 `uses:` 引用；runner 讀取此檔後以 node24 執行 src/index.js。

# action 顯示名稱：呼叫端 workflow log 與 marketplace 列表上看到的名稱。
name: 'AI Code Review'
# action 用途說明：多角色 AI code review 流程（攻擊方找問題、防守方裁決誤報），
# 審查結果會留言到 PR 並保存 findings（.gitea/ai-review/findings/）。
description: 'AI 多角色 code review：攻擊方找問題、防守方裁決誤報，結果留言到 PR 並保存 findings'
# action 作者資訊（僅供辨識，不影響執行）。
author: 'Jeffery'
# 輸入參數區塊：呼叫端 workflow 以 `with:` 傳入，
# runner 會自動注入為 INPUT_* 環境變數（例如 INPUT_TOKEN、INPUT_MODEL、INPUT_CREATE-ISSUE）供主程式讀取。
inputs:
  # Gitea API token：用於對 PR／issue 留言審查結果，以及 push 審查結果檔（findings／exclusions）回 repo。
  token:
    # 參數用途說明：secrets/vars context 在 action 內不可用，故由呼叫端 workflow 以 secrets 傳入。
    # 建議使用 repo 限定、最小權限且可輪替的 token；不得在不受信任 fork PR 暴露可寫入 token。
    description: 'Gitea API token（PR／issue 留言與 push findings 用；請以 repo 限定、最小權限且可輪替的 secrets 傳入）'
    # 必填：缺少 token 無法呼叫 Gitea API，action 無法運作。
    required: true
  # 指定 AI 工具使用的模型名稱。
  model:
    # 參數用途說明：留空表示使用各 AI 工具自身的預設模型。
    description: '指定 AI 工具使用的模型（空值＝各工具預設）'
    # 選填：未指定時採用預設值。
    required: false
    # 預設為空字串，代表不覆寫各工具的預設模型。
    default: ''
  # 建問題模式開關：是否把審查保留的問題另建 issue 追蹤。
  create-issue:
    # 參數用途說明：字串 'true' 時建立 issue（標題＝PR 標題、描述＝PR 描述、AI 挑標籤），
    # 並逐條留言問題明細，findings 檔不進版控、收尾只 commit exclusions.json；
    # 預設 'false' 走原流程（findings 檔與 exclusions.json 一併 commit 回 PR 來源分支）。
    description: '是否將問題建到存取庫的問題追蹤（true 時建立 issue 逐條留言問題明細，最後只 commit exclusions.json；預設 false 走原流程）'
    # 選填：未指定時採用預設值。
    required: false
    # 預設為字串 'false'，代表不啟用建問題模式（主程式只認字串 'true' 才啟用）。
    default: 'false'
# 執行方式區塊：宣告本 action 為 node action 及其進入點。
runs:
  # 以 Node.js 24 runtime 直接在 runner 上執行（非 Docker 容器、非 composite）。
  using: 'node24'
  # 主程式進入點：直接指向 src/index.js（entry point）。
  # 主程式為零外部相依（package.json 無 dependencies，src 僅 require Node 內建模組與本地 lib），
  # runner 不會自動 npm install，零相依時依 node action 慣例 main 直接指向 src/index.js 即正確；
  # 日後若新增外部相依，需改以 @vercel/ncc 打包（package.json 已備有 build script），
  # 並將 main 改指 dist/index.js、把 dist/ commit 進 repo。
  main: 'src/index.js'