Merge pull request 'docs(calculate-version): 重建 README 並補齊指令檔註解與 logger JSDoc' (#12) from develop into master

Reviewed-on: docker-actions/calculate-version#12
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>

README.md

@@ -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#L58) | [輸出 `[階段][INF][時間]` 格式的資訊訊息至標準輸出（階段選填）。](#loggerinfo) |
-| [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#L76) | [輸出 `[階段][ERR][時間]` 格式的錯誤訊息至標準錯誤輸出（階段選填）。](#loggererror) |
-| [logger.error](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L77) | [輸出 `[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
 

app/index.js

@@ -20,7 +20,7 @@ const { writeOutput } = require('./output');
  * @param {Function} [deps.latestStableVersion] - 從 release 清單取得最新穩定版（舊版本）的函式。
  * @param {Function} [deps.nextVersion] - 依舊版本計算本次版本號的函式。
  * @param {Function} [deps.writeOutput] - 寫出 output 的函式。
- * @param {{section:Function, info:Function, error:Function}} [deps.log] - log 記錄器。
+ * @param {{forStage:Function, info:Function, error:Function}} [deps.log] - log 記錄器；以 forStage(階段) 取得綁定階段的子記錄器後輸出。
  * @returns {Promise<string>} 計算出的版本號。
  * @throws {Error} 當任一注入相依（loadConfig／fetchReleases／latestStableVersion／nextVersion／writeOutput）
  *   拋出例外時，原樣向外傳播，由呼叫端決定如何結束。
@@ -38,29 +38,29 @@ async function main(deps = {}) {
     } = deps;
 
     // 1. 參數檢查：載入並驗證環境變數設定
-    log.section('參數檢查');
+    const checkLog = log.forStage('參數檢查');
 
     const config = loadConfigFn();
-    log.info(`GITEA_SERVER_URL=${config.serverUrl}`);
+    checkLog.info(`GITEA_SERVER_URL=${config.serverUrl}`);
-    log.info(`GITEA_REPOSITORY=${config.repository}`);
+    checkLog.info(`GITEA_REPOSITORY=${config.repository}`);
-    log.info(config.token ? 'GITEA_TOKEN=***' : 'GITEA_TOKEN=未提供');
+    checkLog.info(config.token ? 'GITEA_TOKEN=***' : 'GITEA_TOKEN=未提供');
-    log.info(`IS_BETA=${config.isBeta}`);
+    checkLog.info(`IS_BETA=${config.isBeta}`);
 
     // 2. 取得舊版本：抓取 release 清單並解析出最新穩定版
-    log.section('取得舊版本');
+    const fetchLog = log.forStage('取得舊版本');
 
     const releaseUrl = `${config.serverUrl}/api/v1/repos/${config.repository}/releases`;
-    log.info(`RELEASE_URL=${releaseUrl}`);
+    fetchLog.info(`RELEASE_URL=${releaseUrl}`);
 
-    const releases = await fetchReleasesFn(releaseUrl, { token: config.token, logger: log });
+    const releases = await fetchReleasesFn(releaseUrl, { token: config.token, logger: fetchLog });
     const latest = latestStableVersionFn(releases);
-    log.info(`LATEST_VERSION=${latest}`);
+    fetchLog.info(`LATEST_VERSION=${latest}`);
 
     // 3. 計算版本號：依舊版本算出本次版本號並寫出 output
-    log.section('計算版本號');
+    const calcLog = log.forStage('計算版本號');
 
     const version = nextVersionFn(latest, releases, config.isBeta);
-    log.info(`NEW_VERSION=${version}`);
+    calcLog.info(`NEW_VERSION=${version}`);
     writeOutputFn('version', version);
 
     return version;

app/logger.js

@@ -1,13 +1,9 @@
 'use strict';
 
-// 主分隔線與次分隔線寬度（沿用原 entrypoint.sh 的視覺樣式）
-const LINE = '='.repeat(50);
-const SUBLINE = '-'.repeat(50);
-
 /**
  * 產生台灣時區（Asia/Taipei）的時間戳，格式固定為 `yyyy/MM/dd HH:mm:ss`。
  *
- * 供 log 訊息統一格式 `[{等級}][{時間}]: {訊息}` 的時間欄位使用。
+ * 供 log 訊息統一格式 `[{階段}][{等級}][{時間}]: {訊息}` 的時間欄位使用。
  *
  * @returns {string} 台灣時區當下時間字串，例如 `2026/06/30 12:13:04`。
  */
@@ -31,51 +27,70 @@ function taipeiTimestamp() {
 }
 
 /**
- * 輸出帶標題的區塊段落至標準輸出，標題前後以分隔線包夾，
+ * 將單一 log 訊息寫入指定輸出串流，格式統一為 `[{階段}][{等級}][{時間}]: {訊息}` 並於結尾換行。
- * 用於在 log 中建立可視的段落區隔。
  *
- * 輸出格式為：換行 + 主分隔線（50 個 `=`）+ 標題 + 次分隔線（50 個 `-`）。
+ * 階段（stage）為選填；省略或空字串時略過開頭的 `[{階段}]` 區塊，輸出退化為 `[{等級}][{時間}]: {訊息}`。
- * 此為結構性段落標題（非 INF/WRN/ERR 等級訊息），故不套用 `[{等級}][{時間}]` 前綴。
+ * 一次呼叫只輸出一則訊息（一行一則）。
  *
- * @param {string} title - 區塊標題文字；會原樣輸出於兩條分隔線之間。
+ * @param {NodeJS.WriteStream} stream - 目標輸出串流（process.stdout 或 process.stderr）。
+ * @param {string} level - 訊息等級，限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`。
+ * @param {string} message - 要輸出的訊息內容。
+ * @param {string} [stage] - 階段名稱（選填）。
  * @returns {void}
- * @remarks 通常在進入一個處理階段前呼叫（例如「參數檢查」「取得舊版本」），
- *   用以在 CI/容器 log 中分隔各階段輸出，便於閱讀與定位。
  */
-function section(title) {
+function write(stream, level, message, stage) {
-    process.stdout.write(`\n${LINE}\n${title}\n${SUBLINE}\n`);
+    const stagePrefix = stage ? `[${stage}]` : '';
+    stream.write(`${stagePrefix}[${level}][${taipeiTimestamp()}]: ${message}\n`);
 }
 
 /**
  * 輸出一般資訊（INF）層級的 log 訊息至標準輸出。
  *
- * 訊息格式統一為 `[INF][{台灣時間}]: {訊息}`，時間使用台灣時區（Asia/Taipei），
+ * 訊息格式統一為 `[{階段}][INF][{台灣時間}]: {訊息}`，時間使用台灣時區（Asia/Taipei），
- * 格式為 `yyyy/MM/dd HH:mm:ss`，並於結尾換行。
+ * 格式為 `yyyy/MM/dd HH:mm:ss`，並於結尾換行；未提供 stage 時略過 `[{階段}]` 區塊。
  *
  * @param {string} message - 要輸出的資訊內容。
+ * @param {string} [stage] - 階段名稱（選填），用於在訊息開頭標示所屬處理階段。
  * @returns {void}
- * @remarks 用於回報正常流程進度（如設定值、URL、各頁取得筆數）；此調整僅變更輸出前綴格式，
+ * @remarks 用於回報正常流程進度（如設定值、URL、各頁取得筆數）；可直接呼叫，或經 forStage()
- *   不改變訊息所反映的實際行為與內容。
+ *   取得綁定階段的子記錄器後以單一 message 參數呼叫。
  */
-function info(message) {
+function info(message, stage) {
-    process.stdout.write(`[INF][${taipeiTimestamp()}]: ${message}\n`);
+    write(process.stdout, 'INF', message, stage);
 }
 
 /**
  * 輸出錯誤（ERR）層級的 log 訊息至標準錯誤輸出（stderr）。
  *
- * 訊息格式統一為 `[ERR][{台灣時間}]: {訊息}`，時間使用台灣時區（Asia/Taipei），
+ * 訊息格式統一為 `[{階段}][ERR][{台灣時間}]: {訊息}`，時間使用台灣時區（Asia/Taipei），
- * 格式為 `yyyy/MM/dd HH:mm:ss`，並於結尾換行。
+ * 格式為 `yyyy/MM/dd HH:mm:ss`，並於結尾換行；未提供 stage 時略過 `[{階段}]` 區塊。
  *
  * 僅負責輸出，不終止行程；是否結束由呼叫端（進入點）決定，以利測試與錯誤復原。
  *
  * @param {string} message - 要輸出的錯誤描述內容。
+ * @param {string} [stage] - 階段名稱（選填），用於在訊息開頭標示所屬處理階段。
  * @returns {void}
- * @remarks 由進入點在頂層捕捉到例外時呼叫，輸出至 stderr 後再由呼叫端決定 exit code；
+ * @remarks 由進入點在頂層捕捉到例外時呼叫（此情境無對應階段，省略 stage），輸出至 stderr 後
- *   此調整僅變更輸出前綴格式，不改變訊息所反映的實際行為與內容。
+ *   再由呼叫端決定 exit code。
  */
-function error(message) {
+function error(message, stage) {
-    process.stderr.write(`[ERR][${taipeiTimestamp()}]: ${message}\n`);
+    write(process.stderr, 'ERR', message, stage);
 }
 
-module.exports = { section, info, error };
+/**
+ * 建立綁定特定階段（stage）的子記錄器；其 info／error 會自動帶入該階段名稱，
+ * 呼叫端僅需傳入 message 即可輸出 `[{階段}][{等級}][{時間}]: {訊息}`。
+ *
+ * @param {string} stage - 階段名稱，例如「參數檢查」「取得舊版本」「計算版本號」。
+ * @returns {{ info: (message: string) => void, error: (message: string) => void }} 綁定該階段的記錄器。
+ * @remarks 由進入點為每個處理階段建立一個子記錄器，使該階段（含其呼叫的 fetchReleases 等模組）
+ *   輸出的每一則訊息都帶有一致的階段前綴，取代過往以分隔線區塊標示階段的做法。
+ */
+function forStage(stage) {
+    return {
+        info: (message) => info(message, stage),
+        error: (message) => error(message, stage),
+    };
+}
+
+module.exports = { info, error, forStage };

app/test/index.test.js

@@ -5,8 +5,12 @@ const assert = require('node:assert/strict');
 
 const { main } = require('../index');
 
-// 安靜的 log 記錄器，避免測試輸出雜訊
+// 安靜的 log 記錄器，避免測試輸出雜訊；forStage 回傳同樣安靜的子記錄器
-const silentLog = { section() {}, info() {}, error() {} };
+const silentLog = {
+    info() {},
+    error() {},
+    forStage() { return { info() {}, error() {} }; },
+};
 
 const okConfig = {
     serverUrl: 'https://gitea.example.com',

app/test/logger.test.js

@@ -29,24 +29,39 @@ function capture(run) {
 
 const TIME = /\[\d{4}\/\d{2}\/\d{2} \d{2}:\d{2}:\d{2}\]/;
 
-test('section 於 stdout 輸出標題與 50 寬分隔線區塊', () => {
+test('info 未帶 stage 時以 [INF][時間]: 格式輸出至 stdout', () => {
-    const { out, err } = capture(() => logger.section('參數檢查'));
-    assert.equal(out, `\n${'='.repeat(50)}\n參數檢查\n${'-'.repeat(50)}\n`);
-    assert.equal(err, '');
-});
-
-test('info 以 [INF][時間]: 格式輸出至 stdout', () => {
     const { out, err } = capture(() => logger.info('IS_BETA=false'));
     assert.match(out, new RegExp(`^\\[INF\\]${TIME.source}: IS_BETA=false\\n$`));
     assert.equal(err, '');
 });
 
-test('error 以 [ERR][時間]: 格式輸出至 stderr，且不寫入 stdout', () => {
+test('info 帶 stage 時以 [階段][INF][時間]: 格式輸出至 stdout', () => {
+    const { out, err } = capture(() => logger.info('IS_BETA=false', '參數檢查'));
+    assert.match(out, new RegExp(`^\\[參數檢查\\]\\[INF\\]${TIME.source}: IS_BETA=false\\n$`));
+    assert.equal(err, '');
+});
+
+test('error 未帶 stage 時以 [ERR][時間]: 格式輸出至 stderr，且不寫入 stdout', () => {
     const { out, err } = capture(() => logger.error('GITEA_SERVER_URL 未設定'));
     assert.match(err, new RegExp(`^\\[ERR\\]${TIME.source}: GITEA_SERVER_URL 未設定\\n$`));
     assert.equal(out, '');
 });
 
+test('error 帶 stage 時以 [階段][ERR][時間]: 格式輸出至 stderr', () => {
+    const { err } = capture(() => logger.error('讀取失敗', '取得舊版本'));
+    assert.match(err, new RegExp(`^\\[取得舊版本\\]\\[ERR\\]${TIME.source}: 讀取失敗\\n$`));
+});
+
+test('forStage 回傳的子記錄器自動帶入階段名稱', () => {
+    const staged = logger.forStage('計算版本號');
+    const { out, err } = capture(() => {
+        staged.info('NEW_VERSION=0.0.6');
+        staged.error('計算錯誤');
+    });
+    assert.match(out, new RegExp(`^\\[計算版本號\\]\\[INF\\]${TIME.source}: NEW_VERSION=0.0.6\\n$`));
+    assert.match(err, new RegExp(`^\\[計算版本號\\]\\[ERR\\]${TIME.source}: 計算錯誤\\n$`));
+});
+
 test('info/error 的時間戳為 yyyy/MM/dd HH:mm:ss 格式', () => {
     const { out } = capture(() => logger.info('x'));
     assert.match(out, TIME);