/**
 * 輸出最上層的「區塊／章節」分隔標題（前綴空行 + `=== 標題 ===`）。
 * 用於切分整個執行流程中彼此獨立的大段落（例如「環境檢查」「執行審查」「發布結果」），
 * 讓 CI log 在視覺上分群；屬於最高層級的分隔，內部再以 step / line 等細分。
 *
 * @param {string} title - 區塊標題文字。
 * @returns {void} 無回傳值，僅將標題寫入 stdout。
 */
export function section(title) {
  console.log(`\n=== ${title} ===`);
}

/**
 * 輸出某個「步驟」的標題（前綴空行 + `[步驟代號] 標題`）。
 * 適合在一個 section 之下標示流程中的各個有序步驟（如 `[1] 載入設定`、`[2] 呼叫模型`），
 * 之後再用 input / output / line 等細項函式描述該步驟的細節。
 *
 * @param {string} stepName - 步驟代號或編號，會以中括號包覆顯示。
 * @param {string} title - 步驟標題文字。
 * @returns {void} 無回傳值，僅將步驟標題寫入 stdout。
 */
export function step(stepName, title) {
  console.log(`\n[${stepName}] ${title}`);
}

/**
 * 輸出一筆縮排的一般明細列（`  - 訊息`）。
 * 用於在某個 step 之下列出不帶語意成敗的中性資訊（例如逐項說明、設定值、進度敘述）；
 * 若要表達輸入／輸出或成敗，請改用 input / output / result / ok 等更具語意的函式。
 *
 * @param {string} message - 要顯示的明細訊息。
 * @returns {void} 無回傳值，僅將明細寫入 stdout。
 */
export function line(message) {
  console.log(`  - ${message}`);
}

/**
 * 輸出「階段輸入」描述（`  ← 輸入：訊息`），標示目前步驟吃進了什麼資料。
 * 在一個步驟開始處理前，用來明確記錄其輸入來源或內容，方便日後對照輸出（output）追蹤資料流。
 *
 * @param {string} message - 描述輸入內容的訊息。
 * @returns {void} 無回傳值，僅將輸入描述寫入 stdout。
 */
export function input(message) {
  console.log(`  ← 輸入：${message}`);
}

/**
 * 輸出「階段輸出」描述（`  → 輸出：訊息`），標示目前步驟產出了什麼結果。
 * 在一個步驟處理完成後，用來記錄其產出，與 input 搭配可在 log 中清楚呈現該步驟的資料流向。
 *
 * @param {string} message - 描述輸出內容的訊息。
 * @returns {void} 無回傳值，僅將輸出描述寫入 stdout。
 */
export function output(message) {
  console.log(`  → 輸出：${message}`);
}

/**
 * 輸出一筆檢查／把關結果列，依結果以 `✅ 成功` 或 `❌ 失敗` 為前綴（`  ✅ 成功：訊息`）。
 * 用於明確標示某個驗證、條件判斷或 gate 的通過與否；
 * 需要由布林值決定成敗、且希望成功與失敗使用一致格式時最適合（注意：失敗仍寫入 stdout，非 stderr）。
 *
 * @param {boolean} passed - 結果是否通過；`true` 顯示成功、`false` 顯示失敗。
 * @param {string} message - 描述該結果的訊息。
 * @returns {void} 無回傳值，僅將結果寫入 stdout。
 */
export function result(passed, message) {
  console.log(`  ${passed ? '✅ 成功' : '❌ 失敗'}：${message}`);
}

/**
 * 輸出一筆成功／完成訊息（`  ✓ 訊息`）。
 * 用於確認某項動作已順利完成的正向回饋；當只需表達成功、無需處理失敗分支時使用，
 * 若需依條件同時涵蓋成功與失敗請改用 result，需要警告或錯誤請改用 warn / error。
 *
 * @param {string} message - 描述成功內容的訊息。
 * @returns {void} 無回傳值，僅將成功訊息寫入 stdout。
 */
export function ok(message) {
  console.log(`  ✓ ${message}`);
}

/**
 * 輸出一筆警告訊息（`  ! 訊息`），透過 `console.warn` 寫入 stderr。
 * 用於流程仍可繼續、但需要提醒使用者注意的非致命狀況（例如使用了預設值、跳過某項可選步驟）；
 * 比 line/ok 更醒目，但比 error 輕，真正導致失敗的狀況請改用 error。
 *
 * @param {string} message - 要顯示的警告訊息。
 * @returns {void} 無回傳值，僅將警告訊息寫入 stderr。
 */
export function warn(message) {
  console.warn(`  ! ${message}`);
}

/**
 * 輸出一筆錯誤訊息（`  x 訊息`），透過 `console.error` 寫入 stderr。
 * 用於明確的失敗或例外狀況，是日誌中最高的嚴重層級；
 * 適合在捕捉到錯誤或前置條件不滿足而無法繼續時使用，僅需提醒注意的非致命狀況請改用 warn。
 *
 * @param {string} message - 要顯示的錯誤訊息。
 * @returns {void} 無回傳值，僅將錯誤訊息寫入 stderr。
 */
export function error(message) {
  console.error(`  x ${message}`);
}