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 {