docs(calculate-version): 補齊 function JSDoc 與指令檔逐行註解並重建 README

app/index.js

@@ -19,6 +19,10 @@ const { writeOutput } = require('./output');
  * @param {Function} [deps.writeOutput] - 寫出 output 的函式。
  * @param {{section:Function, info:Function, error:Function}} [deps.log] - log 記錄器。
  * @returns {Promise<string>} 計算出的版本號。
+ * @throws {Error} 當任一注入相依（loadConfig／fetchReleases／calculateVersion／writeOutput）拋出例外時，
+ *   原樣向外傳播，由呼叫端決定如何結束。
+ * @remarks 由模組底部的 require.main 守衛在被直接執行時呼叫；失敗時頂層以模組層級 logger.error 輸出
+ *   並 exit(1)。單元測試可透過 deps 注入替身以覆蓋成功與各失敗路徑。
  */
 async function main(deps = {}) {
     const {

app/output.js

@@ -10,6 +10,8 @@ const fs = require('node:fs');
  * @param {string} [file=process.env.GITHUB_OUTPUT] - 輸出檔路徑，預設取自環境變數 `GITHUB_OUTPUT`。
  * @throws {Error} 當輸出檔路徑為 falsy（例如 `GITHUB_OUTPUT` 未設定）時拋出，無法寫入輸出。
  * @returns {void}
+ * @remarks 由 main 於計算出版本號後呼叫，將 `version` 寫入 Action output 供後續 step 取用；
+ *   以 append 方式寫入、不覆蓋既有內容，且 value 僅支援單行字串（未處理換行或 `=`）。
  */
 function writeOutput(name, value, file = process.env.GITHUB_OUTPUT) {
     if (!file) {

app/version.js

@@ -8,6 +8,8 @@ const SEGMENT_LIMIT = 10;
  * @param {number[]} a - 第一個版本號區段陣列，例如 [1, 2, 3]。
  * @param {number[]} b - 第二個版本號區段陣列，例如 [1, 2, 0]。
  * @returns {number} 大於 0 表示 a 大於 b；小於 0 表示 a 小於 b；0 表示兩者相等。
+ *   相異區段回傳的是該段差值（非固定 ±1）。
+ * @throws {TypeError} 當 a 或 b 非陣列（無 length 屬性）時拋出。
  */
 function compareVersionArrays(a, b) {
     const length = Math.max(a.length, b.length);
@@ -70,6 +72,8 @@ function latestStableVersion(releases) {
  * 依最新穩定版字串計算下一個發行版本號：patch 加 1，patch 達 10 進位至 minor，minor 達 10 進位至 major。
  * @param {string} latest - 最新穩定版版本號字串，例如 "1.2.9"。
  * @returns {string} 下一個發行版本號字串，格式為 "major.minor.patch"，例如 "1.3.0"。
+ * @remarks 「逢 10 進位」為本專案自訂約定（非標準 SemVer）；輸入會先 String() 轉字串，
+ *   缺段或非數字段一律補 0（如 null/undefined → "0.0.1"），major 無進位上限。
  */
 function nextReleaseVersion(latest) {
     const parts = String(latest).split('.').map((part) => Number(part) || 0);