app/index.js

@@ -3,7 +3,7 @@
 const logger = require('./logger');
 const { loadConfig } = require('./config');
 const { fetchReleases } = require('./releases');
-const { calculateVersion } = require('./version');
+const { latestStableVersion, nextVersion } = require('./version');
 const { writeOutput } = require('./output');
 
 /**
@@ -12,15 +12,18 @@ const { writeOutput } = require('./output');
  * 失敗時（loadConfig 或 fetchReleases 拋錯）直接向外拋出例外，由呼叫端決定如何結束，
  * 以利單元測試覆蓋失敗路徑。相依模組可透過 deps 注入，預設使用各兄弟模組的實作。
  *
+ * 流程分為三個階段：1. 參數檢查 2. 取得舊版本 3. 計算版本號。
+ *
  * @param {Object} [deps={}] - 可注入的相依，供測試替換。
  * @param {Function} [deps.loadConfig] - 載入設定的函式。
  * @param {Function} [deps.fetchReleases] - 取得 release 的函式。
- * @param {Function} [deps.calculateVersion] - 計算版本號的函式。
+ * @param {Function} [deps.latestStableVersion] - 從 release 清單取得最新穩定版（舊版本）的函式。
+ * @param {Function} [deps.nextVersion] - 依舊版本計算本次版本號的函式。
  * @param {Function} [deps.writeOutput] - 寫出 output 的函式。
  * @param {{section:Function, info:Function, error:Function}} [deps.log] - log 記錄器。
  * @returns {Promise<string>} 計算出的版本號。
- * @throws {Error} 當任一注入相依（loadConfig／fetchReleases／calculateVersion／writeOutput）拋出例外時，
- *   原樣向外傳播，由呼叫端決定如何結束。
+ * @throws {Error} 當任一注入相依（loadConfig／fetchReleases／latestStableVersion／nextVersion／writeOutput）
+ *   拋出例外時，原樣向外傳播，由呼叫端決定如何結束。
  * @remarks 由模組底部的 require.main 守衛在被直接執行時呼叫；失敗時頂層以模組層級 logger.error 輸出
  *   並 exit(1)。單元測試可透過 deps 注入替身以覆蓋成功與各失敗路徑。
  */
@@ -28,11 +31,13 @@ async function main(deps = {}) {
     const {
         loadConfig: loadConfigFn = loadConfig,
         fetchReleases: fetchReleasesFn = fetchReleases,
-        calculateVersion: calculateVersionFn = calculateVersion,
+        latestStableVersion: latestStableVersionFn = latestStableVersion,
+        nextVersion: nextVersionFn = nextVersion,
         writeOutput: writeOutputFn = writeOutput,
         log = logger,
     } = deps;
 
+    // 1. 參數檢查：載入並驗證環境變數設定
     log.section('參數檢查');
 
     const config = loadConfigFn();
@@ -41,17 +46,20 @@ async function main(deps = {}) {
     log.info(config.token ? 'GITEA_TOKEN=***' : 'GITEA_TOKEN=未提供');
     log.info(`IS_BETA=${config.isBeta}`);
 
-    log.section('取得版本資料');
+    // 2. 取得舊版本：抓取 release 清單並解析出最新穩定版
+    log.section('取得舊版本');
 
     const releaseUrl = `${config.serverUrl}/api/v1/repos/${config.repository}/releases`;
     log.info(`RELEASE_URL=${releaseUrl}`);
 
     const releases = await fetchReleasesFn(releaseUrl, { token: config.token, logger: log });
-
-    const { latest, version } = calculateVersionFn(releases, config.isBeta);
+    const latest = latestStableVersionFn(releases);
     log.info(`LATEST_VERSION=${latest}`);
 
+    // 3. 計算版本號：依舊版本算出本次版本號並寫出 output
     log.section('計算版本號');
+
+    const version = nextVersionFn(latest, releases, config.isBeta);
     log.info(`NEW_VERSION=${version}`);
     writeOutputFn('version', version);
 

app/version.js

@@ -115,6 +115,26 @@ function nextBetaNumber(releases, version) {
     return max + 1;
 }
 
+/**
+ * 依「已知的最新穩定版」計算本次要使用的版本號；isBeta 為 true 時產生 beta 版本號。
+ *
+ * 此函式不負責「取得舊版本」（latest 由呼叫端傳入），僅負責「計算版本號」這一步，
+ * 讓取得舊版本與計算新版本兩個階段可各自獨立。
+ *
+ * @param {string} latest - 已知的最新穩定版版本號字串（如 "1.2.3"；查無時為 "0.0.0"）。
+ * @param {Array<{tag_name?: string}>} releases - release 物件清單；beta 流水號需據此比對。
+ * @param {boolean} isBeta - 是否產生 beta 版本號；true 時回傳形如 "<next>-beta.<n>"。
+ * @returns {string} 本次要使用的版本號字串；非 beta 為下一個發行版（如 "1.3.0"），
+ *   beta 為 "<next>-beta.<n>"（如 "1.3.0-beta.1"）。
+ */
+function nextVersion(latest, releases, isBeta) {
+    const next = nextReleaseVersion(latest);
+
+    return isBeta
+        ? `${next}-beta.${nextBetaNumber(releases, next)}`
+        : next;
+}
+
 /**
  * 計算最新穩定版與下一個版本號；isBeta 為 true 時產生 beta 版本號。
  * @param {Array<{tag_name?: string}>} releases - release 物件清單。
@@ -125,13 +145,8 @@ function nextBetaNumber(releases, version) {
  */
 function calculateVersion(releases, isBeta) {
     const latest = latestStableVersion(releases);
-    const next = nextReleaseVersion(latest);
 
-    const version = isBeta
-        ? `${next}-beta.${nextBetaNumber(releases, next)}`
-        : next;
-
-    return { latest, version };
+    return { latest, version: nextVersion(latest, releases, isBeta) };
 }
 
 module.exports = {
@@ -140,5 +155,6 @@ module.exports = {
     latestStableVersion,
     nextReleaseVersion,
     nextBetaNumber,
+    nextVersion,
     calculateVersion,
 };