@@ -1,10 +1,8 @@
# calculate-version
> 更新時間：2026/06/30 12:32:40
計算版本號的 Gitea Action：依儲存庫現有的 release，推算下一個穩定版或 beta 版本號，並寫出為 Action output 供後續步驟取用。以 Docker 容器執行，容器內由 Node.js 主程式實作。
計算版本號的 Gitea Action。依現有 release 推算下一個穩定版或 beta 版本號，並將結果寫入 Action output `version` 。核心邏輯以 Node.js 實作，置於 `app/` ，由 `entrypoint.sh` 作為容器進入點啟動；容器映像採多階段建置（build 階段 `node:latest` 、runtime 階段 `node:slim` ）。
版本進位規則：`patch + 1` ；當 `patch` 達 10 進位至 `minor` ， `minor` 達 10 進位至 `major` 。beta 版本號形如 `<next>-beta.<n>` ，其中 `<n>` 為該版本既有 beta 標籤的最大序號加 1。
> 更新時間：2026/06/30 17:38:51（ ）
## 專案列表
@@ -12,7 +10,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。 |
### 參考專案
@@ -24,196 +22,195 @@
| 專案名稱 | NuGet 套件列表 |
| --- | --- |
| [calculate-version ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app ) | 無（zero-dependency；僅使用 Node.js 內建模組與全域 fetch ）
| [calculate-version ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app ) | 無（本專案為純 Node.js， ）
## 功能列表
### index（ ）
### calculate-version
| 功能名稱 | 功能描述 |
| --- | --- |
| [index.main https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/index .js#L27 ) | [Action 進入點：協調設定載入、release 取得、版本計算與輸出（支援相依注入）。 ]( #indexmain
### logger（ ）
| 功能名稱 | 功能描述 |
| --- | --- |
| [logger.section ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L45 ) | [輸出帶標題的區塊段落至標準輸出，標題前後以分隔線包夾。 ](#loggersection ) |
| [logger.info ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L60 ) | [輸出 INF 層級 log 訊息，格式為 `[INF][時間]: 訊息` 。](#loggerinfo ) |
| [logger.error ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L77 ) | [輸出 ERR 層級訊息至 stderr（格式為 `[ERR][時間]: 訊息` ，僅輸出不終止行程）。](#loggererror ) |
### config（ ）
| 功能名稱 | 功能描述 |
| --- | --- |
| [config.isUnset ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L11 ) | [判斷環境變數值是否視為「未設定」。 ](#configisunset ) |
| [config.isUnset https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config .js#L11 ) | [判斷環境變數值是否視為「未設定」（undefined／ ]( #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#L80 ) | [從環境變數載入並驗證執行所需的設定。 ](#configloadconfig ) |
### version（ ）
| 功能名稱 | 功能描述 |
| --- | --- |
| [version.compareVersionArrays ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L14 ) | [逐區段比較兩個版本號數值陣列，較短者視為較小。 ](#versioncompareversionarrays ) |
| [version.parseStableVersions ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L38 ) | [從 release 清單解析出所有穩定版的版本號數值陣列。 ](#versionparsestableversions ) |
| [version.latestStableVersion ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L57 ) | [取得 release 清單中最新的穩定版版本號字串。 ](#versionlateststableversion ) |
| [version.nextReleaseVersion ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L78 ) | [依最新穩定版計算下一個發行版本號。 ](#versionnextreleaseversion ) |
| [version.nextBetaNumber ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L101 ) | [計算指定版本號的下一個 beta 流水號。 ](#versionnextbetanumber ) |
| [version.calculateVersion ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L126 ) | [計算最新穩定版與下一個版本號（支援 beta）。 ](#versioncalculateversion ) |
### releases（ ）
| 功能名稱 | 功能描述 |
| --- | --- |
| [releases.fetchReleases ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/releases.js#L24 ) | [以分頁方式取得指定 Gitea repo 的所有 release。 ](#releasesfetchreleases ) |
### output（ ）
| 功能名稱 | 功能描述 |
| --- | --- |
| [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 ) |
| [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 ) |
| [version.parseStableVersions ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L39 ) | [從 release 清單解析出所有穩定版的版本號數值陣列。 ](#versionparsestableversions ) |
| [version.latestStableVersion ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L58 ) | [取得最新（最大）的穩定版版本號字串。 ](#versionlateststableversion ) |
| [version.nextReleaseVersion ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L79 ) | [依最新穩定版計算下一個發行版本號（逢 10 進位）。 ](#versionnextreleaseversion ) |
| [version.nextBetaNumber ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L102 ) | [計算指定版本號的下一個 beta 流水號。 ](#versionnextbetanumber ) |
| [version.nextVersion ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L131 ) | [依已知的最新穩定版計算本次要使用的版本號（含 beta）。 ](#versionnextversion ) |
| [version.calculateVersion ](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L147 ) | [計算最新穩定版與下一個版本號。 ](#versioncalculateversion ) |
## 使用範例
<a id="indexmain"></a>
### 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'
```
<a id="loggersection"></a>
### logger.section
輸出帶標題的區塊段落至標準輸出：先一個換行，接著 50 個 `=` 的主分隔線、標題文字，最後 50 個 `-` 的次分隔線，用於在 log 中建立可視段落區隔。此為結構性段落標題，不套用 `[等級][時間]` 前綴。
``` js
const logger = require ( './logger' ) ;
logger . section ( '參數檢查' ) ;
// 輸出：
//
// ==================================================
// 參數檢查
// --------------------------------------------------
```
<a id="loggerinfo"></a>
### logger.info
輸出一般資訊（INF）層級訊息至標準輸出，格式統一為 `[INF][{時間}]: {訊息}` ，時間使用台灣時區（Asia/Taipei）、格式 `yyyy/MM/dd HH:mm:ss` ，並於結尾換行；不會結束行程。
``` js
const logger = require ( './logger' ) ;
logger . info ( 'IS_BETA=false' ) ;
// 輸出：[INF][2026/06/30 12:00:00]: IS_BETA=false
```
<a id="loggererror"></a>
### logger.error
輸出錯誤（ERR）層級訊息至標準錯誤輸出（stderr），格式統一為 `[ERR][{時間}]: {訊息}` （時間為台灣時區）。僅負責輸出，**不終止行程**；是否結束由呼叫端（進入點）決定，以利測試與錯誤復原。
``` js
const logger = require ( './logger' ) ;
logger . error ( 'GITEA_SERVER_URL 未設定' ) ;
// 對 stderr 輸出：[ERR][2026/06/30 12:00:00]: GITEA_SERVER_URL 未設定
```
<a id="configisunset"></a>
### config.isUnset
判斷環境變數值是否視為「未設定」。`undefined` 、`null` 、空字串、字面字串 `"null"` 皆視為未 設定。
判斷單一 環境變數值是否應 視為「未設定」。下列任一情況回傳 `true` ： `undefined` 、`null` 、空字串、字面字串 `"null"` ；其餘回傳 `false` 。常用於 `loadConfig` 內判斷必填與選填 設定。
``` js
const { isUnset } = require ( './config' ) ;
const { isUnset } = require ( './app/ config' ) ;
isUnset ( undefined ) ; // true
isUnset ( 'null' ) ; // true
isUnset ( 'false ' ) ; // fals e
isUnset ( '' ) ; // tru e
isUnset ( 'abc' ) ; // false
```
<a id="configrequireenv"></a>
### config.requireEnv
驗證必填環境變數；未設定時拋出 `Error` （訊息為 `${name} 未設定` ），已設定時 原樣回傳值。
驗證必填環境變數；值被視為 未設定時拋出 `Error` （訊息為 `${name} 未設定` ），否則 原樣回傳該 值。
``` js
const { requireEnv } = require ( './config' ) ;
const { requireEnv } = require ( './app/ config' ) ;
const url = requireEnv ( 'GITEA_SERVER_URL' , process . env . GITEA _SERVER _URL ) ;
// 未設定時拋出： Error: GITEA_SERVER_URL 未設定
// 未設定時 → throw Error(' GITEA_SERVER_URL 未設定')
```
<a id="confignormalizebetaflag"></a>
### config.normalizeBetaFlag
將 beta 旗標正規化為布林值。未設定時預設為 `false` ；僅當值嚴格等於字面字串 `"true"` 時回傳 `true` 。
將 beta 旗標環境變數 正規化為布林值。未設定時預設為 `false` ；僅當值嚴格等於字面字串 `"true"` 時回傳 `true` 。
``` js
const { normalizeBetaFlag } = require ( './config' ) ;
const { normalizeBetaFlag } = require ( './app/ config' ) ;
normalizeBetaFlag ( 'true' ) ; // true
normalizeBetaFlag ( 'TRUE ' ) ; // false（嚴格比較，不做大小寫轉換）
normalizeBetaFlag ( 'true' ) ; // true
normalizeBetaFlag ( 'false ' ) ; // false
normalizeBetaFlag ( undefined ) ; // false
```
<a id="configloadconfig"></a>
### config.loadConfig
從環境變數載入並驗證執行所需的 設定。`GITEA_SERVER_URL` 與 `GITEA_REPOSITORY` 為必填（未設定即拋錯），且 `GITEA_SERVER_URL` 須為合法的 http/https URL ； `GITEA_TOKEN` 非必 填（未設定為 `null` ）；`IS_BETA` 會 正規化為布林值。
從環境變數載入並驗證執行所需設定。`GITEA_SERVER_URL` （須為合法 http/https URL） 與 `GITEA_REPOSITORY` （須為 `owner/repo` 形式、排除路徑穿越）為必填 ； `GITEA_TOKEN` 選 填（未設定為 `null` ）；`IS_BETA` 正規化為布林值。驗證失敗會拋出 `Error` 。
``` js
const { loadConfig } = require ( './config' ) ;
const { loadConfig } = require ( './app/ config' ) ;
const config = loadConfig ( {
GITEA _SERVER _URL : 'https://gitea.example.com' ,
GITEA _REPOSITORY : 'owner/repo' ,
IS _BETA : 'true' ,
const config = loadConfig ( process . env ) ;
// → { serverUrl, repository, token, isBeta }
```
<a id="indexmain"></a>
### index.main
Action 進入點，依序執行三個階段：1. 參數檢查（`loadConfig` ）、2. 取得舊版本（`fetchReleases` + `latestStableVersion` ）、3. 計算版本號（`nextVersion` ）並以 `writeOutput` 寫出。相依模組可透過 `deps` 注入以利測試；失敗時向外拋出例外。
``` js
const { main } = require ( './app/index' ) ;
// 以預設相依（讀環境變數、實際打 API）執行
await main ( ) ;
// 測試時注入替身
await main ( {
loadConfig : ( ) => ( { serverUrl : 'https://gitea.example.com' , repository : 'owner/repo' , token : null , isBeta : false } ) ,
fetchReleases : async ( ) => [ { tag _name : 'v1.2.3' } ] ,
writeOutput : ( ) => { } ,
} ) ;
// => { serverUrl: 'https://gitea.example.com', repository: 'owner/repo', token: null, isBeta: true }
// → 回傳 '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` ），結尾換行。
``` 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
```
<a id="loggererror"></a>
### logger.error
輸出錯誤（ERR）層級的 log 訊息至標準錯誤輸出（stderr），格式統一為 `[ERR][{台灣時間}]: {訊息}` 。僅負責輸出，不終止行程，是否結束由呼叫端決定。
``` js
const logger = require ( './app/logger' ) ;
logger . error ( 'GITEA_SERVER_URL 未設定' ) ;
// stderr 輸出：[ERR][2026/06/30 17:38:51]: GITEA_SERVER_URL 未設定
```
<a id="outputwriteoutput"></a>
### output.writeOutput
將一行 `name=value` 以 append 方式寫入 GitHub/Gitea Action 的輸出檔（預設取自環境變數 `GITHUB_OUTPUT` ）。輸出檔路徑為 falsy 時拋出 `Error` 。value 僅支援單行字串。
``` js
const { writeOutput } = require ( './app/output' ) ;
writeOutput ( 'version' , '1.2.4' ) ;
// 對 process.env.GITHUB_OUTPUT 指向的檔案附加一行：version=1.2.4
```
<a id="releasesfetchreleases"></a>
### releases.fetchReleases
以分頁方式（每頁 10 筆）透過全域 `fetch` 取得指定 Gitea repo 的所有 release，回傳合併後的陣列。有 token 時以 `Authorization: token <token>` 授權，否則匿名請求；遇空頁或不足一頁即停止。請求失敗、非 2xx、無法解析或非陣列時拋出 `Error` 。
``` js
const { fetchReleases } = require ( './app/releases' ) ;
const logger = require ( './app/logger' ) ;
const releases = await fetchReleases (
'https://gitea.example.com/api/v1/repos/owner/repo/releases' ,
{ token : process . env . GITEA _TOKEN , logger } ,
) ;
```
<a id="versioncompareversionarrays"></a>
### version.compareVersionArrays
逐區段（element-wise）比較兩個版本號數值陣列，較短的陣列視為較小。回傳值 `> 0` 表示 a 大於 b、 `< 0` 表示 a 小於 b、 `0 ` 表示相等；相異區段回傳的是該段差值（非固定 ±1）。
逐區段（element-wise）比較兩個版本號數值陣列，較短的陣列視為較小。回傳大於 0 表示 `a` 大於 `b` 、小於 0 表示 `a` `b ` 、0 表示相等；相異區段回傳的是該段差值（非固定 ±1）。傳入 `null` ／ `undefined` 會在讀取 `.length` 時拋 `TypeError` 。
``` js
const { compareVersionArrays } = require ( './version' ) ;
const { compareVersionArrays } = require ( './app/ version' ) ;
compareVersionArrays ( [ 1 , 10 ] , [ 1 , 2 , 3 ] ) ; // > 0（ ）
compareVersionArrays ( [ 1 , 2 ] , [ 1 , 2 , 0 ] ) ; // < 0（較短者較小）
compareVersionArrays ( [ 1 , 10 , 0 ] , [ 1 , 9 , 0 ] ) ; // > 0
compareVersionArrays ( [ 1 , 2 ] , [ 1 , 2 , 0 ] ) ; // < 0
compareVersionArrays ( [ 1 , 2 , 3 ] , [ 1 , 2 , 3 ] ) ; // 0
```
<a id="versionparsestableversions"></a>
### version.parseStableVersions
從 release 清單解析出所有穩定版（排除 beta、排除 格式不合法者）的版本號數值陣列；會去除 tag 開頭的 `v` 。傳 入非陣列時回傳空陣列。
從 release 清單解析出所有穩定版（排除含 `-beta.` 與 格式不合法者）的版本號數值陣列；會去除 tag 開頭的 `v` 。輸 入非陣列時回傳空陣列。
``` js
const { parseStableVersions } = require ( './version' ) ;
const { parseStableVersions } = require ( './app/ version' ) ;
parseStableVersions ( [
{ tag _name : 'v1.2.3' } ,
{ tag _name : '2.0.0' } ,
{ tag _name : 'v1.0 .0-beta.1' } , // 被排除
{ tag _name : 'v1.3 .0-beta.1' } ,
] ) ;
// => [[1, 2, 3], [2, 0, 0]]
// → [[1, 2, 3], [2, 0, 0]]
```
<a id="versionlateststableversion"></a>
@@ -222,76 +219,63 @@ parseStableVersions([
取得 release 清單中最新（最大）的穩定版版本號字串，固定格式化為三段 `major.minor.patch` ；查無穩定版時回傳 `"0.0.0"` 。
``` js
const { latestStableVersion } = require ( './version' ) ;
const { latestStableVersion } = require ( './app/ version' ) ;
latestStableVersion ( [ { tag _name : 'v1.2.3 ' } , { tag _name : 'v1.9.9 ' } ] ) ; // " 1.9.9"
latestStableVersion ( [ ] ) ; // " 0.0.0"
latestStableVersion ( [ { tag _name : 'v1.9.0 ' } , { tag _name : 'v1.10.0 ' } ] ) ; // ' 1.10.0'
latestStableVersion ( [ ] ) ; // ' 0.0.0'
```
<a id="versionnextreleaseversion"></a>
### version.nextReleaseVersion
依最新穩定版字串計算下一個發行版本號：` patch + 1` ， ` patch` ` minor` ， ` minor` ` major` （「 逢 10 進位」 為本專案自訂約定，非標準 SemVer）。
依最新穩定版字串計算下一個發行版本號：patch 加 1， ， （
``` js
const { nextReleaseVersion } = require ( './version' ) ;
const { nextReleaseVersion } = require ( './app/ version' ) ;
nextReleaseVersion ( '1.2.8 ' ) ; // " 1.2.9"
nextReleaseVersion ( '1.2.9' ) ; // " 1.3.0"
nextReleaseVersion ( '1.9.9' ) ; // " 2.0.0"
nextReleaseVersion ( '1.2.3 ' ) ; // ' 1.2.4'
nextReleaseVersion ( '1.2.9' ) ; // ' 1.3.0'
nextReleaseVersion ( '1.9.9' ) ; // ' 2.0.0'
```
<a id="versionnextbetanumber"></a>
### version.nextBetaNumber
計算指定版本號的下一個 beta 流水號：取現有相符 beta 標籤（ `v<version>-beta.<n>` ） `1` 。 `version` 參數不應含前綴 `v`
計算指定版本號的下一個 beta 流水號：取現有相符 `v<version>-beta.<n>` 標籤 的最大序號加 1，查無時回傳 1 。
``` js
const { nextBetaNumber } = require ( './version' ) ;
const { nextBetaNumber } = require ( './app/ version' ) ;
nextBetaNumber ( [ { tag _name : 'v1.3.0-beta.1' } , { tag _name : 'v1.3.0-beta.3' } ] , '1.3.0' ) ; // 4
nextBetaNumber ( [ ] , '1.3.0' ) ; // 1
nextBetaNumber ( [
{ tag _name : 'v 1.2.4-beta.1' } ,
{ tag _name : 'v1.2.4-beta.3' } ,
] , '1.2.4' ) ; // 4
nextBetaNumber ( [ ] , '1.2.4' ) ; // 1
```
<a id="versionnextversion"></a>
### version.nextVersion
依「已知的最新穩定版」計算本次要使用的版本號（不負責取得舊版本）。`isBeta` 為 `false` 時回傳下一個發行版；為 `true` 時回傳 `<next>-beta.<n>` 。
``` js
const { nextVersion } = require ( './app/version' ) ;
nextVersion ( '1.2.3' , [ ] , false ) ; // '1.2.4'
nextVersion ( '1.2.3' , [ { tag _name : 'v1.2.4-beta.2' } ] , true ) ; // '1.2.4-beta.3'
```
<a id="versioncalculateversion"></a>
### version.calculateVersion
計算最新穩定版與下一個版本號；`isBeta `為 `true` 時產生 beta 版本號 。回傳物件 `{ latest, version }` 。
計算最新穩定版與下一個版本號；組合 `latestStableVersion `與 `nextVersion` 。回傳物件含 `latest` （現有最新穩定版，查無為 `"0.0.0"` ）與 `version` （本次版本號） 。
``` js
const { calculateVersion } = require ( './version' ) ;
const { calculateVersion } = require ( './app/ version' ) ;
calculateVersion ( [ { tag _name : 'v1.2.3' } ] , false ) ;
// => { latest: '1.2.3', version: '1.2.4' }
// → { latest: '1.2.3', version: '1.2.4' }
calculateVersion ( [ { tag _name : 'v1.2.3' } ] , true ) ;
// => { latest: '1.2.3', version: '1.2.4-beta.1 ' }
```
<a id="releasesfetchreleases"></a>
### releases.fetchReleases
以分頁方式取得指定 Gitea repo 的所有 release，並回傳合併後的陣列。使用全域 `fetch` （ `null` 或筆數少於上限時即停止。提供 `options.token` 時以授權方式請求。網路失敗、回應讀取失敗、非 2xx、無法解析或非陣列回應時拋出 `Error` （含頁碼）。
``` js
const { fetchReleases } = require ( './releases' ) ;
const logger = require ( './logger' ) ;
const releases = await fetchReleases (
'https://gitea.example.com/api/v1/repos/owner/repo/releases' ,
{ token : process . env . GITEA _TOKEN , logger } ,
) ;
// => 所有 release 物件合併後的陣列
```
<a id="outputwriteoutput"></a>
### output.writeOutput
將一行 `name=value` 附加寫入 GitHub/Gitea Action 的輸出檔（預設取 `process.env.GITHUB_OUTPUT` ）。以 append 方式寫入、不覆蓋既有內容；輸出檔路徑為 falsy 時拋出 `Error` 。
``` js
const { writeOutput } = require ( './output' ) ;
writeOutput ( 'version' , '1.2.4' ) ;
// 對 $GITHUB_OUTPUT 附加一行：version=1.2.4
calculateVersion ( [ { tag _name : 'v1.2.3' } , { tag _name : 'v1.2.4-beta.2' } ] , true ) ;
// → { latest: '1.2.3', version: '1.2.4-beta.3 ' }
```
Jeffery