From fb760004fdaf99a8f38aaeabbef7db27cfe13223 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 26 Jun 2026 10:52:19 +0800 Subject: [PATCH] =?UTF-8?q?docs(calculate-version):=20=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=20README=20=E5=B0=8D=E9=BD=8A=E9=8C=AF=E8=AA=A4=E8=99=95?= =?UTF-8?q?=E7=90=86=E9=87=8D=E6=A7=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit logger.fail 改為 logger.error、新增 index.main 公開函式說明，並更新對應行號與使用範例。 Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 45 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 21fa9da..4ea412e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # calculate-version -> 更新時間：2026/06/26 10:37:28 +> 更新時間：2026/06/26 10:49:46 計算版本號的 Gitea Action。依現有 release 推算下一個穩定版或 beta 版本號，並將結果寫入 Action output `version`。核心邏輯以 Node.js 實作，置於 `app/`，由 `entrypoint.sh` 作為容器進入點啟動。 @@ -12,7 +12,7 @@ | 專案名稱 | 專案描述 | | --- | --- | -| [calculate-version](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app) | 計算版本號的 Gitea Action：載入環境設定、分頁抓取 Gitea release、計算下一個穩定版或 beta 版本號，並寫出 Action output。 | +| [calculate-version](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app) | 計算版本號的 Gitea Action：載入並驗證環境設定、分頁抓取 Gitea release、計算下一個穩定版或 beta 版本號，並寫出 Action output。 | ### 參考專案 @@ -28,13 +28,19 @@ ## 功能列表 +### index（app/index.js） + +| 功能名稱 | 功能描述 | +| --- | --- | +| [index.main](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/index.js#L23) | [Action 進入點：協調設定載入、release 取得、版本計算與輸出（支援相依注入）。](#indexmain) | + ### logger（app/logger.js） | 功能名稱 | 功能描述 | | --- | --- | | [logger.section](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L16) | [輸出帶標題的區塊段落至標準輸出，標題前後以分隔線包夾。](#loggersection) | | [logger.info](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L26) | [輸出一般資訊層級的 log 訊息，自動加上 `[info]` 前綴。](#loggerinfo) | -| [logger.fail](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L40) | [輸出錯誤訊息至 stderr 並以狀態碼 1 終止行程。](#loggerfail) | +| [logger.error](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L38) | [輸出錯誤訊息至 stderr（僅輸出，不終止行程）。](#loggererror) | ### config（app/config.js） @@ -43,7 +49,7 @@ | [config.isUnset](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L11) | [判斷環境變數值是否視為「未設定」。](#configisunset) | | [config.requireEnv](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L23) | [驗證必填環境變數，未設定時拋出錯誤。](#configrequireenv) | | [config.normalizeBetaFlag](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L38) | [將 beta 旗標正規化為布林值。](#confignormalizebetaflag) | -| [config.loadConfig](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L55) | [從環境變數載入並驗證執行所需的設定。](#configloadconfig) | +| [config.loadConfig](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L68) | [從環境變數載入並驗證執行所需的設定。](#configloadconfig) | ### version（app/version.js） @@ -70,6 +76,24 @@ ## 使用範例 + +### index.main + +Action 進入點：依序協調設定載入、release 取得、版本計算與輸出寫出，回傳計算出的版本號。失敗時向外拋出例外（由進入點頂層攔截並以狀態碼 1 結束）。相依模組可透過 `deps` 注入，便於測試。模組僅在被直接執行（`node app/index.js`）時自動啟動。 + +```js +const { main } = require('./index'); + +// 測試或自訂情境：注入假的相依 +const version = await main({ + loadConfig: () => ({ serverUrl: 'https://gitea.example.com', repository: 'owner/repo', token: null, isBeta: false }), + fetchReleases: async () => ([{ tag_name: 'v1.2.3' }]), + writeOutput: () => {}, + log: { section() {}, info() {}, error() {} }, +}); +// version === '1.2.4' +``` + ### logger.section @@ -98,17 +122,16 @@ logger.info('IS_BETA=false'); // 輸出：[info] IS_BETA=false ``` - -### logger.fail + +### logger.error -輸出錯誤訊息至標準錯誤輸出（stderr），並以狀態碼 1 立即終止整個行程。用於發生無法復原的錯誤時中止執行；呼叫後其下程式碼不會執行。 +輸出錯誤訊息至標準錯誤輸出（stderr），自動加上 `[error]` 前綴與換行。僅負責輸出，**不終止行程**；是否結束由呼叫端（進入點）決定，以利測試與錯誤復原。 ```js const logger = require('./logger'); -logger.fail('GITEA_SERVER_URL 未設定'); +logger.error('GITEA_SERVER_URL 未設定'); // 對 stderr 輸出：[error] GITEA_SERVER_URL 未設定 -// 接著 process.exit(1) 終止行程 ``` @@ -152,7 +175,7 @@ normalizeBetaFlag(undefined); // false ### config.loadConfig -從環境變數載入並驗證執行所需的設定。`GITEA_SERVER_URL` 與 `GITEA_REPOSITORY` 為必填（未設定即拋錯）；`GITEA_TOKEN` 非必填（未設定為 `null`）；`IS_BETA` 會正規化為布林值。 +從環境變數載入並驗證執行所需的設定。`GITEA_SERVER_URL` 與 `GITEA_REPOSITORY` 為必填（未設定即拋錯），且 `GITEA_SERVER_URL` 須為合法的 http/https URL；`GITEA_TOKEN` 非必填（未設定為 `null`）；`IS_BETA` 會正規化為布林值。 ```js const { loadConfig } = require('./config'); @@ -248,7 +271,7 @@ calculateVersion([{ tag_name: 'v1.2.3' }], true); ### releases.fetchReleases -以分頁方式取得指定 Gitea repo 的所有 release，並回傳合併後的陣列。使用全域 `fetch` 逐頁請求（每頁 limit 為 10）；當某頁回傳空資料、`null` 或筆數少於上限時即停止。提供 `options.token` 時以授權方式請求。網路失敗、非 2xx、無法解析或非陣列回應時拋出 `Error`。 +以分頁方式取得指定 Gitea repo 的所有 release，並回傳合併後的陣列。使用全域 `fetch` 逐頁請求（每頁 limit 為 10）；當某頁回傳空資料、`null` 或筆數少於上限時即停止。提供 `options.token` 時以授權方式請求。網路失敗、回應讀取失敗、非 2xx、無法解析或非陣列回應時拋出 `Error`（含頁碼）。 ```js const { fetchReleases } = require('./releases');