docs(calculate-version): 重建 README 並補齊指令檔註解與 logger JSDoc #12
@@ -2,7 +2,7 @@
|
||||
|
||||
計算版本號的 Gitea Action：依儲存庫現有的 release，推算下一個穩定版或 beta 版本號，並寫出為 Action output 供後續步驟取用。以 Docker 容器執行，容器內由 Node.js 主程式實作。
|
||||
|
||||
> 更新時間：2026/06/30 17:38:51（Asia/Taipei）
|
||||
> 更新時間：2026/06/30 18:18:13（Asia/Taipei）
|
||||
|
||||
## 專案列表
|
||||
|
||||
@@ -35,9 +35,9 @@
|
||||
| [config.normalizeBetaFlag](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L38) | [將 beta 旗標正規化為布林值（僅字面 "true" 為真）。](#confignormalizebetaflag) |
|
||||
| [config.loadConfig](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L101) | [從環境變數載入並驗證執行所需的設定。](#configloadconfig) |
|
||||
| [index.main](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/index.js#L30) | [Action 進入點：依序執行參數檢查、取得舊版本、計算版本號並寫出 output。](#indexmain) |
|
||||
| [logger.section](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L45) | [輸出帶分隔線的區塊標題，用於在 log 中分隔處理階段。](#loggersection) |
|
||||
| [logger.info](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L60) | [輸出 `[INF][時間]` 格式的資訊訊息至標準輸出。](#loggerinfo) |
|
||||
| [logger.error](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L77) | [輸出 `[ERR][時間]` 格式的錯誤訊息至標準錯誤輸出。](#loggererror) |
|
||||
| [logger.info](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L58) | [輸出 `[階段][INF][時間]` 格式的資訊訊息至標準輸出（階段選填）。](#loggerinfo) |
|
||||
| [logger.error](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L76) | [輸出 `[階段][ERR][時間]` 格式的錯誤訊息至標準錯誤輸出（階段選填）。](#loggererror) |
|
||||
| [logger.forStage](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L89) | [建立綁定特定階段的子記錄器，自動為每則訊息帶入階段前綴。](#loggerforstage) |
|
||||
| [output.writeOutput](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/output.js#L16) | [將一行 `name=value` 附加寫入 Action 的輸出檔。](#outputwriteoutput) |
|
||||
| [releases.fetchReleases](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/releases.js#L24) | [以分頁方式取得指定 Gitea repo 的所有 release。](#releasesfetchreleases) |
|
||||
| [version.compareVersionArrays](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L15) | [逐區段比較兩個版本號數值陣列，較短者視為較小。](#versioncompareversionarrays) |
|
||||
@@ -121,34 +121,25 @@ await main({
|
||||
// → 回傳 '1.2.4'
|
||||
```
|
||||
|
||||
<a id="loggersection"></a>
|
||||
### logger.section
|
||||
|
||||
輸出帶標題的區塊段落至標準輸出，標題前後以分隔線包夾，用於在 log 中分隔各處理階段（例如「參數檢查」「取得舊版本」）。此為結構性段落標題，不套用 `[等級][時間]` 前綴。
|
||||
|
||||
```js
|
||||
const logger = require('./app/logger');
|
||||
|
||||
logger.section('參數檢查');
|
||||
// 輸出：換行 + 50 個 = + 標題 + 50 個 -
|
||||
```
|
||||
|
||||
<a id="loggerinfo"></a>
|
||||
### logger.info
|
||||
|
||||
輸出一般資訊（INF）層級的 log 訊息至標準輸出，格式統一為 `[INF][{台灣時間}]: {訊息}`（時間為 Asia/Taipei，格式 `yyyy/MM/dd HH:mm:ss`），結尾換行。
|
||||
輸出一般資訊（INF）層級的 log 訊息至標準輸出，格式統一為 `[{階段}][INF][{台灣時間}]: {訊息}`（時間為 Asia/Taipei，格式 `yyyy/MM/dd HH:mm:ss`），結尾換行。階段（`stage`）為選填，省略時略過 `[{階段}]` 區塊。
|
||||
|
||||
```js
|
||||
const logger = require('./app/logger');
|
||||
|
||||
logger.info('NEW_VERSION=1.2.4');
|
||||
// 輸出：[INF][2026/06/30 17:38:51]: NEW_VERSION=1.2.4
|
||||
|
||||
logger.info('NEW_VERSION=1.2.4', '計算版本號');
|
||||
// 輸出：[計算版本號][INF][2026/06/30 17:38:51]: NEW_VERSION=1.2.4
|
||||
```
|
||||
|
||||
<a id="loggererror"></a>
|
||||
### logger.error
|
||||
|
||||
輸出錯誤（ERR）層級的 log 訊息至標準錯誤輸出（stderr），格式統一為 `[ERR][{台灣時間}]: {訊息}`。僅負責輸出，不終止行程，是否結束由呼叫端決定。
|
||||
輸出錯誤（ERR）層級的 log 訊息至標準錯誤輸出（stderr），格式統一為 `[{階段}][ERR][{台灣時間}]: {訊息}`。階段為選填。僅負責輸出，不終止行程，是否結束由呼叫端決定。
|
||||
|
||||
```js
|
||||
const logger = require('./app/logger');
|
||||
@@ -157,6 +148,19 @@ logger.error('GITEA_SERVER_URL 未設定');
|
||||
// stderr 輸出：[ERR][2026/06/30 17:38:51]: GITEA_SERVER_URL 未設定
|
||||
```
|
||||
|
||||
<a id="loggerforstage"></a>
|
||||
### logger.forStage
|
||||
|
||||
建立綁定特定階段（stage）的子記錄器，回傳 `{ info, error }`；其方法只需傳入 `message`，即會自動在每則訊息開頭帶入 `[{階段}]` 前綴。進入點以此為每個處理階段建立子記錄器，使該階段（含其呼叫的 `fetchReleases` 等模組）輸出的訊息都帶一致的階段前綴。
|
||||
|
||||
```js
|
||||
const logger = require('./app/logger');
|
||||
|
||||
const stageLog = logger.forStage('取得舊版本');
|
||||
stageLog.info('使用授權 token 取得 release');
|
||||
// 輸出：[取得舊版本][INF][2026/06/30 17:38:51]: 使用授權 token 取得 release
|
||||
```
|
||||
|
||||
<a id="outputwriteoutput"></a>
|
||||
### output.writeOutput
|
||||
|
||||
|
||||
Reference in New Issue
Block a user