◉ClassyGitshadowzzh

ci.yml

ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  # 內容檢查(content job)用的:文章在 DB 裡不在 repo,PR 改的是程式碼不是內容,
  # 所以那一項不擋 PR,改成每天跑一次 + 需要時手動觸發。
  schedule:
    - cron: '0 19 * * *' # 03:00 Asia/Taipei
  workflow_dispatch:

# 最小權限:所有 job 只需讀 repo(zizmor excessive-permissions)。
permissions:
  contents: read

# 同分支/PR 有新 push 就取消進行中的舊 run,省 runner
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

# action 一律釘 commit SHA:tag 可被移動,上游 repo 被入侵即等於在 CI 執行任意程式碼
# (zizmor unpinned-uses)。版本靠 .github/dependabot.yml 的 github-actions 生態自動更新。
# checkout 一律 persist-credentials: false:預設會把 git 憑證留在工作區(zizmor artipacked)。

jobs:
  frontend:
    name: Frontend · tsc + oxlint + vitest + build
    runs-on: ubuntu-latest
    # 提到 job 層才能在步驟的 `if:` 裡判斷 token 設了沒(step 層的 env 讀不到自己)
    env:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 26
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - name: tsc --noEmit
        run: pnpm exec tsc --noEmit
      - name: mcp-server typecheck
        run: pnpm --filter @koimsurai/mcp-server typecheck
      # server/routes 與 scripts/ 不在根 tsconfig 的 include(只收 src),過去完全沒被檢查。
      # 各自有 tsconfig.json(檔名固定:eslint 的 projectService 只認這個名字)。
      - name: server routes typecheck
        run: pnpm typecheck:server
      - name: scripts typecheck
        run: pnpm typecheck:scripts
      # oxlint 取代 eslint,經 Vite+ 的 `vp lint` 執行(設定在 vite.config.ts 的 lint 區塊,
      # 182 條規則自 eslint --print-config 對映而來;@eslint-react 與 @shadcn/lint 經 jsPlugins 載入,
      # 命名空間保持 @eslint-react 讓既有 eslint-disable 註解續效)。
      # --max-warnings 0:存量已全數清完(379 → 0),從此新增任何警告都直接擋下。
      - name: oxlint (src, type-aware)
        run: pnpm exec vp lint --type-aware --tsconfig=tsconfig.json src --max-warnings 0
      # scripts/server/packages 也是型別感知。這裡不帶 --tsconfig:tsgolint 會替每個檔案找最近的
      # tsconfig(scripts/、server/、packages/*/ 各有一份)。在這之前它們只跑一般 lint,理由是
      # 「型別會全解析成 any」——換到 tsgolint 之後那件事只剩 .mjs 成立,那幾條依賴型別的規則
      # 在 vite.config.ts 對 JS 檔關掉了,TS 檔照常全開(導入時清掉 51 筆,含真 bug)。
      # --max-warnings 0:這三個目錄目前乾淨,直接鎖死,不留讓它從 0 無聲長大的空間。
      - name: oxlint (scripts + server + packages, type-aware)
        run: pnpm exec vp lint --type-aware scripts server packages --max-warnings 0
      # CSS 的格式與 lint(設定見 .config/biome.json)。Biome 在這裡**只管 CSS**——
      # JS/TS 是 oxlint 的地盤,兩個 linter 管同一批檔案只會互相矛盾,而且 Biome
      # 沒有等價的型別感知檢查。
      #
      # ⚠️ 刻意不加 --error-on-warnings:目前是 27 個 noImportantStyles 沒清
      # (noDescendingSpecificity 已經清完)。它們會出現在 CI 輸出裡但不擋——跟 knip
      # 當初的處理一樣,藏起來就沒有人會回來清。這一步擋的是「格式漂移」與 error 類。
      # 那 27 個每一個上面都有註解寫明為什麼留,看到 warning 不要直接拿掉。
      - name: biome(CSS 格式與 lint)
        run: pnpm lint:css
      # 間距 token 的棘輪。biome 沒有「限制某個屬性的合法值」這類規則,而引入
      # stylelint 等於讓兩個 linter 管同一批 CSS,所以走 scripts/check-*.ts 的既有慣例。
      # 擋的是「又開始現編間距值」:原本 87 種值、1594 次、token 覆蓋 0,收斂花了
      # 兩支 PR;沒有這道,CSS 的 git 歷史(寫 51,785 行刪 30,103 行)說明它會長回來。
      - name: 間距 token(不要現編新的間距值)
        run: pnpm check:css-tokens
      # JS/TS 的格式(oxfmt,經 `vp fmt`)。⚠️ oxfmt 不是只認 js/ts——它同時會排 css / json / md,所以
      # vite.config.ts 的 fmt.ignorePatterns 把這三類都明確排除掉,每一條都是實際撞到的:
      #   css  → biome 的地盤,兩邊 quoteStyle 相反(biome 雙引號、oxfmt 單引號),
      #          讓 oxfmt 碰它 lint:css 會一次冒出 32 個 error。
      #   json → 會重排 tests/e2e/computed-style.baseline/ 那 15 個機器產生的基準檔。
      #   md   → 會把中文表格用字元數撐開對齊,CJK 寬度對不上,純粹是雜訊。
      - name: oxfmt(JS/TS 格式)
        run: pnpm check:format
      # 未使用的檔案/匯出/相依。設定見 .config/knip.json。
      #
      # 原本只 gate files + dependencies,因為 exports 類還有 27 個未使用匯出 +
      # 11 個未使用型別沒清。那批已經清完(多數不是「刪掉」而是「拿掉 export」——
      # 它們在自己檔案裡還有用,只是不該對外),所以 --include 拿掉,全類別鎖死。
      - name: knip(未使用的檔案、匯出與相依)
        run: pnpm exec knip --config .config/knip.json --no-progress
      # JUnit 與覆蓋率的產出都由 vitest.config.ts 依 CI 環境決定,不在這裡改寫指令——
      # `pnpm test` 是 CLAUDE.md 裡列的門檻指令,讓它跟本機跑的是同一條。
      - name: vitest
        run: pnpm test
      # 覆蓋率送 Codecov,flag=frontend。跟 backend 分開才看得出各自的趨勢——
      # 混在一起的話後端 82% 會把前端的個位數蓋掉,而那正是需要被看見的數字。
      #
      # ⚠ 這裡量的是**單元測試**的覆蓋率,不含 e2e。e2e 走過的原始碼要另外量
      #   (scripts/e2e-coverage.mjs,靠 V8 coverage + source map 映回 src/),
      #   那份沒有進 Codecov:它需要跑起整個 stack,成本與這條門檻不對等。
      #   兩個數字差很多是正常的,別把它們當成同一件事。
      - name: 覆蓋率上傳(frontend)
        if: ${{ !cancelled() && env.CODECOV_TOKEN != '' }}
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
        with:
          files: coverage/lcov.info
          flags: frontend
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: false
      # 測試結果送 Codecov Test Analytics(不是覆蓋率——那邊看的是每一條測試的
      # 歷史失敗率與 flaky)。!cancelled() 而不是 always():測試紅的時候才最需要
      # 這份資料,只在成功時上傳等於「壞掉時看不到」。
      #
      # ⚠ 用的是 codecov-action 加 `report_type: test_results`,不是 codecov/test-results-action。
      #   後者已棄用,2026-10 起上傳時 TLS 握手直接失敗(SSL alert 40),而且是在讀
      #   fail_ci_if_error 之前就崩潰——於是每一支 PR 的 Frontend / Backend / E2E 都紅,
      #   測試本身卻全過。
      - name: Test Analytics(frontend)
        if: ${{ !cancelled() && env.CODECOV_TOKEN != '' }}
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
        with:
          report_type: test_results
          files: junit-frontend.xml
          flags: frontend
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: false
      # 真正的建置驗證——tsc/lint 過不代表 Nitro/Vite build 不會炸
      - name: build (vite + nitro)
        run: pnpm build

  backend:
    name: Backend · clippy + test + specta drift
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: backend
    # 提到 job 層是為了讓下面的上報步驟能在 `if:` 裡判斷「token 到底設了沒」——
    # step 層的 env 在該 step 自己的 if: 裡讀不到。沒設 token 時整步跳過,
    # 而不是紅一格:Codecov 是儀表板不是守門員,門檻仍在 --fail-under-regions。
    env:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable
        with:
          components: clippy, rustfmt
      # workspaces 必須指向真正的 workspace root。這個 repo 的 Cargo.toml 在根目錄
      # (members = ["backend"]),所以 target/ 也在根目錄——backend/target 根本不存在。
      # 原本寫 backend 導致 rust-cache 找不到 target/,只快取了 ~/.cargo 的 registry。
      #
      # 證據(2026-07-28):GitHub 上的快取 76 MB,而同一份冷編譯在本機是 3.5 GB
      # → 編譯產物一個都沒進去,每次 CI 都在從零重編 453 個依賴。
      # 這也解釋了為什麼還原只要 1–3 秒、每步卻要 100 秒以上,以及為什麼上一次
      # 只換 prefix-key(382s → 350s)幾乎沒用:陳舊的不是內容,是根本沒存。
      #
      # 本機 16 核冷編譯 268 CPU 秒:tikv-jemalloc-sys 27.3s、libwebp-sys 13.7s、
      # libsqlite3-sys 9.0s 都是 C 建置,自有 crate 只佔 7.2%(依賴全熱時 clippy 只要 5.3s)。
      #
      # 判讀:改完的「第一次」run 會慢(要建立並上傳 GB 級快取),第二次才是真實水準。
      # 快取大小若沒從 76 MB 跳到 GB 級,代表這個假設也錯了。
      - uses: Swatinem/rust-cache@258712b0b7b1ddf8bddc9fc3b0faca682b2736c3 # v2
        with:
          workspaces: .
          prefix-key: v1-rust
          # ⚠ 這個 job **不能**跟 e2e / api-fuzz 共用 key。原本三個都寫 `workspace`,
          # 理由是省空間(各存一份是 1265 + 565 + 565 MB),但那個共用是失效的:
          #
          # rust-cache 只在「key 還不存在」時存得進去。e2e 與 api-fuzz 跑得快、先結束、
          # 先把自己的快取存進 workspace——而它們只跑 `cargo build --bin`,裡面沒有
          # clippy 的 .rmeta,也沒有 llvm-cov 的插樁產物。這個 job 最後才結束,key
          # 已存在 → 它的產物**永遠存不進去**。
          #
          # 後果是每一次 CI 都在重編:實測同一個 run 裡
          #   api-fuzz  Checking 2   Compiling 1     ← 全命中
          #   e2e       Checking 2   Compiling 1     ← 全命中
          #   本 job    Checking 297 Compiling 454   ← clippy 353 + llvm-cov 397
          # 也就是 453 個相依編兩次(clippy 一組 flag、llvm-cov 的 -C instrument-coverage
          # 又一組,artifact 本來就不能互用)。1m39 + 2m36 幾乎全是這個。
          #
          # 共用 key 只有在「產物真的一樣」時才成立。e2e 與 api-fuzz 之間成立,
          # 所以它們兩個維持共用;這個 job 拆出來自己一份。
          shared-key: workspace-lint-cov
          # 只有 main 存。GitHub 的快取是**按 ref 隔離**的,PR 分支各存一份,
          # 而 PR 本來就讀得到 base branch 的快取——自己存純粹是浪費額度。
          # 實測:Dependabot 的 4 個 PR 各存了 1.36 GB,加上 main 共 6.8 GB,
          # 把 repo 推到 10.46 / 10 GB → LRU 開始淘汰 → pnpm store 被清掉 →
          # e2e 的 `pnpm install` 從 7s 變 1m41s。省的不是空間,是別人的命中率。
          save-if: ${{ github.ref == 'refs/heads/main' }}
      - uses: taiki-e/install-action@7f4eb899022d8fe70b20c4f3de697aa85c309026 # v2
        with:
          tool: cargo-nextest,cargo-audit,cargo-llvm-cov,cargo-shear,typos-cli
      # 未使用/放錯區段的相依,以及沒被連進模組樹的 .rs 檔。
      # 文字掃描(找 use 路徑),所以只透過巨集展開用到的 crate 可能誤報——
      # 真遇到就進 [package.metadata.cargo-shear] ignored,不要為此關掉整個檢查。
      - name: cargo-shear(未使用的 Rust 相依)
        working-directory: .
        run: cargo shear
      # 錯字:掃程式、5 個語系的 JSON、中文註解(非 ASCII 會被跳過,中文不誤判)。
      # 白名單在 .typos.toml,只放實際被誤報過的字。
      - name: typos
        working-directory: .
        run: typos
      # 格式守門(設定見 backend/rustfmt.toml:max_width 110 + 緊湊啟發式,貼近既有風格)
      - name: cargo fmt --check
        run: cargo fmt --check
      # --locked:CI 必須測「commit 進來的那組版本」,不允許靜默更新 Cargo.lock
      - name: clippy (-D warnings)
        run: cargo clippy --locked --all-targets -- -D warnings
      # 測試 + 覆蓋率一次跑完(llvm-cov 會帶 instrumentation 重編,不另外跑 nextest 免得編兩次)。
      # 用 region 而非 line 當門檻:line coverage 會被「格式化」影響——導入 rustfmt 時
      # 測試一個沒少,line 卻從 17.24% 掉到 14.14%(多行 if/else 被收成單行),
      # 而同一次 region 只從 12.44% 動到 12.45%。region 對應實際分支,不隨排版漂移。
      #
      # 門檻要跟著漲,不然做過的事就沒被鎖住。歷程:
      #   12  最初——當時 0% 的多是外部 API 整合,上游位址寫死在字串裡所以 mock 不了
      #   30  `state::ExternalUrls` 讓上游可注入(wiremock 接得上),
      #       加上 admin/thoughts 的 CRUD 往返測試之後,實際來到 33.46%
      #   37  auth(0→96.8%)、upload(0→96.3%)、oauth(0→95.8%)三個
      #       安全相關的 0% 檔案補完,實際 40.44%
      #   78  watch / books / posts / thoughts / spotify / rss / error 一路補完,實際 82.70%
      #   82  現在——四個「壞了不會有症狀」的區塊補完,實際 87.31%:
      #       polls 25→85(唯一免身分就能寫 DB 的公開端點)、comments 54→95(四道守門
      #       全部沒被走過)、admin 67→84(留言審核整片 + 刪分類 + 改角色)、
      #       gallery 56→90(sync 的掃描/旋轉/增量判斷)
      #
      # 這幾個都用 `cargo mutants` 驗過「弄壞會不會紅」而不是只看百分比:
      # auth / upload / oauth / watch / thirdparty 的可編譯變異全數被抓到。
      # 覆蓋率高不代表測得有效——vitals.rs 曾經覆蓋 98.67% 而變異分數只有 43%,
      # 而 thirdparty.rs 覆蓋到 96% 時 mutants 仍抓出 35 個漏網(SWR 的時間判斷、
      # 錯誤路徑的訊息、GitHub compare 的觸發條件),全部是不會有症狀的那種。
      #
      # 留 5pp 餘裕:加一段還沒測到的新功能不該當場擋下,但「刪掉一批測試」會被抓到。
      # 剩下最大的一塊是 bahamut.rs(24%)——它的主體是 sync worker,要測得先把
      # anigamer client 抽成可注入,那是比寫測試本身更大的改動,不在這一輪。
      #
      # 另一塊刻意不補的是 image_proxy 的成功路徑:它的上游位址要過 net_guard,
      # 而 wiremock 只綁得到 127.0.0.1(正好在 SSRF 黑名單裡)。要測就得在
      # net_guard 開一個「可停用」的開關——為了一個覆蓋率數字,在 SSRF 防護上
      # 加一個旁路開關,這筆帳怎麼算都不划算。被擋掉的那條路徑本身有測(tests/api.rs)。
      # --profile ci 只多做一件事:把 JUnit XML 寫到 target/nextest/ci/junit.xml
      # (設定見 .config/nextest.toml),給下面的 Test Analytics 用。本機不受影響。
      - name: test + coverage (llvm-cov + nextest)
        run: cargo llvm-cov nextest --locked --profile ci --fail-under-regions 82 --lcov --output-path lcov.info
      # ⚠ cargo-llvm-cov 的 lcov 寫的是**絕對路徑**(`SF:/home/runner/work/…/backend/src/x.rs`)。
      #   Codecov 會嘗試用路徑尾端去比對 repo 裡的檔案,比對不上時報告仍然「上傳成功」,
      #   只是每個檔案都掛不到原始碼——網頁上看到的是一份空殼,而且沒有任何錯誤訊息。
      #   在這裡先切成 repo 相對路徑,就不必依賴那層猜測。
      #   `if: always()` 讓覆蓋率沒過門檻時也照樣正規化(那時候最需要看報告)。
      - name: lcov 路徑改成 repo 相對
        if: ${{ !cancelled() }}
        run: sed -i "s|^SF:${GITHUB_WORKSPACE}/|SF:|" lcov.info
      # 上報到 Codecov。這裡只給「看得到趨勢與逐行熱區」,門檻仍然是上面那個
      # --fail-under-regions——外部服務掛掉不該擋住 merge,所以 fail_ci_if_error: false。
      #
      # !cancelled() 而不是 success():覆蓋率掉到門檻以下時上一步會紅,而那正是
      # 最需要看報告的時候;只在成功時上報等於「壞掉時看不到資料」。
      #
      # ⚠ 沒有設 CODECOV_TOKEN 就整步跳過。這個 repo 是公開的,理論上 tokenless
      #   也上傳得了,但 Codecov 對匿名上傳有速率限制、失敗時只回 429,
      #   到時候會變成「有時有報告有時沒有」這種最難查的狀態。
      - name: Codecov(覆蓋率上報)
        if: ${{ !cancelled() && env.CODECOV_TOKEN != '' }}
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
        with:
          files: backend/lcov.info
          # disable_search:不讓它自己去翻整個 repo。前端目前沒有產覆蓋率報告,
          # 開著搜尋只會掃出一堆無關檔案然後靜默地上傳空資料。
          disable_search: true
          flags: backend
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: false
      # 測試結果(跟上面的覆蓋率是兩回事)。target/ 在 workspace root,不是 backend/ 底下。
      - name: Test Analytics(backend)
        if: ${{ !cancelled() && env.CODECOV_TOKEN != '' }}
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
        with:
          report_type: test_results
          files: target/nextest/ci/junit.xml
          flags: backend
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: false
      # 契約守門:Rust struct 改了但沒重跑 export_types → 生成型別與 committed 不一致 → 擋下
      - name: specta types up-to-date
        run: |
          cargo run --locked --bin export_types
          cd ..
          git diff --exit-code packages/api-types/index.ts
      # Rust 依賴漏洞掃描(Cargo.lock 在 workspace 根;豁免清單見 .cargo/audit.toml)
      - name: cargo audit
        working-directory: .
        run: cargo audit

  # 前後端「合起來會不會動」的守門。前面兩個 job 各自都綠,卻擋不到:
  #   - 後端改了回應形狀、前端還照舊讀(這批 specta 化就改過 steam/github/wakatime 的形狀)
  #   - 值沒處理好漏到畫面上(Invalid Date、f/f/1.4、132 mmmm 三個都是手動開瀏覽器才發現的)
  #   - 該掛守衛的端點沒掛
  # 跑的是真的 stack:後端 binary(temp SQLite + seed)+ nitro server + 一層 /api 代理
  # (生產是 nginx 做這件事)。細節見 tests/e2e/stack.mjs。
  e2e:
    name: E2E · 全站煙霧 + API 契約 + a11y (${{ matrix.shard }}/3)
    runs-on: ubuntu-latest
    # 分片:206 條在單機跑要 436s,是整個 CI 的關鍵路徑(其餘 job 都 ≤331s)。
    #
    # ⚠ 為什麼是分片而不是調高 workers:`workers: 2` 是刻意的,playwright.config.ts
    #   有一段 8 輪實測——workers=4 有 3/8 輪 chromium 整個崩掉,而那種崩潰會被 retry
    #   接住變成「綠的 flaky」,蓋掉真實失敗訊號。分片是把 206 條分到三台機器,
    #   每台仍然 workers=2,完全不碰那條線。
    #
    # ⚠ 也不是「只跑有變更的頁面」。那需要用覆蓋率建 spec ↔ 原始檔的對照表,
    #   而它抓不到 CSS、種子資料、設定檔、SSR-only 路徑這些非程式碼相依——
    #   漏掉的方式是安靜的。這個 repo 已經為「某條路徑沒被跑到」付過兩次代價
    #   (#68 只修了兩個呼叫端之一;內容 job 只在 schedule 跑 → PR 綠、main 紅)。
    #   分片跑的還是全部 206 條,沒有這個風險。
    #
    # fail-fast: false —— 一片紅了另外兩片照跑完,才看得到「到底壞了幾條」。
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3]
    env:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 26
          cache: pnpm
      - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable
      # workspace root 在根目錄(見 backend job 那段說明)
      - uses: Swatinem/rust-cache@258712b0b7b1ddf8bddc9fc3b0faca682b2736c3 # v2
        with:
          workspaces: .
          prefix-key: v1-rust
          # 與 api-fuzz 共用:兩個 job 都只跑 `cargo build --bin`,產物一樣,
          # 誰先存都能讓對方全命中(實測兩邊都是 Checking 2 / Compiling 1)。
          # backend job **不在**這把 key 裡——它的 clippy / llvm-cov 產物不同,
          # 硬共用的結果是它永遠存不進去、每次重編兩遍。理由寫在那個 job 底下。
          shared-key: workspace
          # 只有 main 存(理由同 backend job 那段:PR 讀得到 base 的快取,自己存是浪費額度)
          save-if: ${{ github.ref == 'refs/heads/main' }}
      - run: pnpm install --frozen-lockfile
      # ⚠ key 一定要綁 **playwright 的版本**,不能綁整個 lockfile 的雜湊。
      #   原本寫的是 `hashFiles('pnpm-lock.yaml')`,而註解卻寫「綁 playwright 版本」——
      #   兩者差很多:lockfile 每動一次(包含每一個 Dependabot PR、每一次無關的
      #   套件升級)key 就變,chromium 整包重下載。實測代價是這一步從 33s 變成 259s,
      #   而且完全看不出原因——job 仍然是綠的,只是慢了四分鐘。
      #   (抓到它是因為升了 monaco 的版本之後 E2E job 從 375s 跳到 622s。)
      - name: 取 playwright 版本
        id: pw
        run: echo "version=$(node -p "require('@playwright/test/package.json').version")" >> "$GITHUB_OUTPUT"
      # 瀏覽器本體進快取。命中時下面那行仍然會跑,但 playwright 偵測到 binary 已存在
      # 就只做 `--with-deps` 的 apt 那段(系統函式庫沒辦法用 actions/cache 還原,
      # 那是裝進 / 的)。
      - name: playwright 瀏覽器快取
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ steps.pw.outputs.version }}
      # 按頁裁字的字型原檔(宋體、黑體、楷、現代無襯線,約 270 MB,不進 git;Docker 建置時在獨立階段下載)。
      # 少了它 /fonts/serif/… 全是 404,每一頁都在 console 記錯(smoke 的請求失敗、Lighthouse 的
      # errors-in-console)。網址釘在 google/fonts 的某個提交,所以快取鍵綁下載腳本本身就夠。
      - name: 裁字字型原檔快取
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: .cache/fonts
          key: serif-fonts-${{ hashFiles('scripts/fetch-serif-font.mjs') }}
      - name: 下載裁字字型原檔(快取命中時只校驗 sha256)
        run: node scripts/fetch-serif-font.mjs
      # 三件事互相獨立,卻本來排成序列(17s + 19s + 12s = 48s)。
      # chromium 那步是 apt(IO-bound),兩個建置是 CPU-bound,重疊起來剛好互補。
      # 只裝 chromium:三家瀏覽器各裝一次要 3 分鐘,而這裡測的是資料流不是渲染差異。
      - name: 裝 chromium(背景)+ 建置前後端
        run: |
          set -euo pipefail
          # 背景那支的輸出另外收,不要跟 cargo 的交錯在一起;失敗時才印出來
          pnpm exec playwright install --with-deps chromium > /tmp/pw-install.log 2>&1 &
          pw=$!
          cargo build --locked --bin koimsurai-web-backend
          pnpm build
          if ! wait $pw; then
            echo "::error::playwright install 失敗"
            cat /tmp/pw-install.log
            exit 1
          fi
      # 這裡面也包含 computed-style.spec.ts —— 計算後樣式的回歸守門(基準在
      # tests/e2e/computed-style.baseline/,一頁一個檔)。改了樣式而它報紅是正常的,
      # 用 `UPDATE_STYLE_BASELINE=1 pnpm exec playwright test computed-style` 更新,
      # 並在 PR 說明為什麼那些元素該變。理由與陷阱見 CLAUDE.md 的 CSS 段。
      - name: playwright
        # ⚠ 不要寫成 `pnpm e2e -- --shard=…`。pnpm v11 不需要那個分隔符,而帶了之後
        #   參數不會傳到 playwright——實測 `pnpm e2e -- --shard=2/3 --list` 連 `--list`
        #   都失效(webServer 直接起來了),不帶 `--` 才正確吐出 `Total: 78 tests`。
        #   寫錯的話每片都跑全部 206 條:三倍的工,零加速,而且 CI 是綠的。
        run: pnpm e2e --shard=${{ matrix.shard }}/3
        env:
          # 設了才會收 V8 coverage(見 tests/e2e/fixtures.ts)。沒設就完全不做事,
          # 所以本機跑 e2e 不會多付成本。
          E2E_COVERAGE_DIR: .e2e-coverage
      # ⚠ 覆蓋率**不在這裡**算。每片只走過三分之一的測試,各自產報告會得到三份
      # 互不相干的數字;而 lcov 送上 Codecov 之後是「同一個 flag 的多次上傳」,
      # 合併規則跟我們要的(逐行相加)不一定一致。
      # 改成把原始 dump 丟成 artifact,由下面的彙整 job 一次合併——那支用的是
      # `mergeScriptCovs`,跨分片合併本來就是它在做的事(見 e2e-coverage-report.mjs)。
      - name: 覆蓋率 dump 上傳(給彙整用)
        if: ${{ !cancelled() }}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v6
        with:
          name: e2e-coverage-${{ matrix.shard }}
          path: .e2e-coverage
          retention-days: 1
          # ⚠ `.e2e-coverage` 是**隱藏目錄**,而 upload-artifact 從 v4.4 起預設排除隱藏檔。
          #   沒有這一行的結果是「No files were found」——而它只是個 warning,
          #   job 照樣綠,直到下游的彙整 job 才炸。第一次跑就踩到了。
          include-hidden-files: true
          # 不能用 ignore:沒東西上傳一定是出事了(上面那個 bug 就是被 ignore 蓋住的)。
          # 讓它在源頭紅,而不是在三個 job 之後才紅。
          if-no-files-found: error
      # ⚠ 這一個是整組裡最有價值的:e2e 是唯一會 flaky 的那批(瀏覽器在併發下崩潰、
      #   hydration 競賽),而定位它們過去靠的是手動重跑幾十輪。Codecov 會自己累積
      #   每一條測試的失敗率並標出 flaky——playwright 的 retry 讓「失敗後重試成功」
      #   仍然算綠,那種訊號在 CI log 上只是一行 flaky 標記,跑完就沒了。
      - name: Test Analytics(e2e)
        if: ${{ !cancelled() && env.CODECOV_TOKEN != '' }}
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
        with:
          report_type: test_results
          files: junit-e2e.xml
          flags: e2e
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: false
      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v6
        if: failure()
        with:
          # ⚠ 名字要帶分片編號:同名 artifact 在 v4 之後會直接衝突報錯,
          #   而那會發生在「已經有測試失敗」的時候——最不需要多一個錯誤訊息的時機。
          name: playwright-report-${{ matrix.shard }}
          path: |
            playwright-report/
            test-results/
          retention-days: 7

  e2e-coverage:
    name: E2E · 覆蓋率彙整
    needs: e2e
    # 有分片紅掉時照樣算——那時候最需要看「到底走過哪些路徑」。
    if: ${{ !cancelled() }}
    runs-on: ubuntu-latest
    env:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 26
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      # ⚠ 這裡非得重建不可:報告要從 `.output/public` 讀 source map 才映得回原始檔,
      #   而 vite 用 `sourcemap: 'hidden'`(產物沒有 sourceMappingURL,必須手動餵)。
      #   把整個 .output 當 artifact 在 job 之間搬比重建還慢,而且相依已經有快取,
      #   這一步實測只要 ~35s。
      - run: pnpm build
      - name: 取回各分片的 dump
        uses: actions/download-artifact@484a0b528fb4d7bd804637ccb632e47a0e638317 # v6
        with:
          pattern: e2e-coverage-*
          merge-multiple: true
          path: .e2e-coverage
      # e2e 走過多少原始碼 → lcov → Codecov(flag = e2e)。
      #
      # 為什麼這個數字必須存在:單元測試的覆蓋率分母有**八成是 React 元件**
      # (5468/6970 行),而元件的渲染路徑本來就是 e2e 在守。只看單元覆蓋率會得到
      # 41% 這種數字,而 e2e 走過的是 77%。兩個數字並排才看得懂各自在守什麼。
      #
      # ⚠ 合併一定要用 `mergeScriptCovs`(腳本裡已經是)。自己寫的版本曾經把 105664 筆
      #   帶著命中的資料靜靜丟掉,整體被壓低 21.5 個百分點——見那支腳本的檔頭。
      #   分片之後這件事更關鍵:同一個檔在三片裡的 range 形狀必然不同。
      - name: e2e 覆蓋率報告
        run: node scripts/e2e-coverage-report.mjs .e2e-coverage lcov-e2e.info
      - name: 覆蓋率上傳(e2e)
        if: ${{ env.CODECOV_TOKEN != '' }}
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
        with:
          files: lcov-e2e.info
          flags: e2e
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: false

  # Lighthouse:可及性/SEO 的分數、資源預算、以及幾條「一定是 bug」的稽核。
  #
  # ⚠ 它**抓不到**這個站最嚴重的那類問題。實地量到 0.52 的 CLS,Lighthouse 在同一頁
  #   量到的是 0(開了節流也還是 0)——因為它永遠冷啟動、無 history、單頁直接載入,
  #   而那個位移只在「捲在文章深處按 F5」時出現。那條路徑由 tests/e2e/cls.spec.ts 守。
  #   這裡守的是變異小、退步了又真的會痛的東西:a11y/SEO 規則、以及 JS 位元組預算。
  #   門檻與每一條的理由都寫在 .config/lighthouserc.cjs。
  #
  # 拆成獨立 job 而不是併進 e2e:兩者都要 `pnpm build` + `cargo build`(各約 60~90s),
  # 併起來會把 e2e 這條關鍵路徑再拉長三分鐘;分開跑則是平行的,總時間不變。
  lighthouse:
    name: Lighthouse · a11y / SEO / 資源預算
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 26
          cache: pnpm
      - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable
      - uses: Swatinem/rust-cache@258712b0b7b1ddf8bddc9fc3b0faca682b2736c3 # v2
        with:
          workspaces: .
          prefix-key: v1-rust
          # 跟 e2e / api-fuzz 同一把:三個 job 都只跑 `cargo build --bin`,產物一樣
          shared-key: workspace
          save-if: ${{ github.ref == 'refs/heads/main' }}
      # 明確裝一份 Chrome 而不是賭 runner 映像自帶。ubuntu-latest 目前確實有,
      # 但那是映像的實作細節,哪天拿掉就會變成「lighthouse 突然找不到瀏覽器」。
      - uses: browser-actions/setup-chrome@2e1d749697dd1612b833dba4a722266286fbefcd # v2.1.2
        id: chrome
        with:
          chrome-version: stable
      - run: pnpm install --frozen-lockfile
      # 按頁裁字的字型原檔(宋體、黑體、楷、現代無襯線,約 270 MB,不進 git;Docker 建置時在獨立階段下載)。
      # 少了它 /fonts/serif/… 全是 404,每一頁都在 console 記錯(smoke 的請求失敗、Lighthouse 的
      # errors-in-console)。網址釘在 google/fonts 的某個提交,所以快取鍵綁下載腳本本身就夠。
      - name: 裁字字型原檔快取
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: .cache/fonts
          key: serif-fonts-${{ hashFiles('scripts/fetch-serif-font.mjs') }}
      - name: 下載裁字字型原檔(快取命中時只校驗 sha256)
        run: node scripts/fetch-serif-font.mjs
      - name: 建置前後端
        run: |
          set -euo pipefail
          cargo build --locked --bin koimsurai-web-backend
          pnpm build
      # lhci 自己會用 startServerCommand 起 e2e stack(設定見 .config/lighthouserc.cjs)。
      # CHROME_PATH 指向上一步裝的那顆,不讓 chrome-launcher 自己去猜。
      - name: lhci autorun
        env:
          CHROME_PATH: ${{ steps.chrome.outputs.chrome-path }}
        run: pnpm exec lhci autorun --config=.config/lighthouserc.cjs
      # 失敗時把完整的 LHR 收起來。斷言訊息只講「哪一條、差多少」,
      # 要知道是哪個資源變大了得看報告本身。
      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v6
        if: failure()
        with:
          name: lighthouse-report
          path: .lighthouseci/
          retention-days: 7

  # 已發布文章的 MDX 編譯守門。
  #
  # 為什麼需要:MDX 編譯失敗在前台是**靜默退回 markdown**(讀者看到裸標籤),而
  # create/update API 仍回 success。錯誤 UI 其實寫好了卻永遠不會亮——它在 render 期,
  # 而編譯已經在 blogList.ts 那層先失敗了。細節見 scripts/check-mdx.ts 的檔頭。
  #
  # 為什麼不擋 PR:文章存在 DB 裡不在 repo,PR 改的是程式碼不是內容。改成每天跑
  # 一次 + workflow_dispatch,抓的是「有人發了一篇壞掉的文章」。
  content:
    name: 內容 · 已發布文章的 MDX 編譯得過
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 26
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      # 跟 e2e job 共用同一份瀏覽器快取(key 一樣)。沒有這層的話每次都從
      # playwright.download.prss.microsoft.com 下載,那個網域在 runner 上時常解析不到
      # (2026-10-19、10-21 兩次 ENOTFOUND,無障礙巡檢因此紅)。
      - name: 取 playwright 版本
        id: pw
        run: echo "version=$(node -p "require('@playwright/test/package.json').version")" >> "$GITHUB_OUTPUT"
      - name: playwright 瀏覽器快取
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ steps.pw.outputs.version }}
      - name: MDX 編譯 + 未註冊 block 檢查
        run: pnpm check:mdx
      # 安全標頭巡檢。放在這個排程 job 而不是 e2e/PR,理由有兩個:
      #   1. 這些標頭是 nginx 加的,而 nginx 設定不在這個 repo 裡——PR 改不到它,
      #      拿它擋 PR 只會製造無關的紅燈。
      #   2. e2e 起的是 nitro + backend + 一個很小的假代理,裡面沒有 nginx;
      #      在那裡斷言只會驗到假代理,綠了也不代表線上是對的。
      # 所以它直接打正式站,每天一次。缺標頭這種事沒有任何症狀,沒人看就永遠不會發現。
      - name: 正式站安全標頭巡檢
        run: pnpm check:headers
      # 連結會在沒有人動任何程式碼的情況下爛掉(對方改網址、關站、或我們自己把頁面拿掉)。
      # 跟上面兩項一樣放這個排程 job:文章在 DB 裡不在 repo 裡,PR 改不到。
      # 只有**自家**網址壞掉才會讓這步紅——外部網站掛掉不是我們的 bug。
      - name: 已發布文章的連結巡檢
        run: pnpm check:links
      # 無障礙巡檢。tests/e2e 已經有一道 moderate 門檻,但它跑在**沒有第三方金鑰**的
      # e2e stack 上——沒金鑰時 Steam / WakaTime / GitHub 那些區塊整段不 render,
      # 裡面的標題與對比通通不在 DOM 裡,測不到。
      # 實際發生過:/activity 在本機乾淨,部署後對正式站一掃就報 heading-order,
      # 因為 <h2 class="steam-profile-name"> 只有真的抓得到 Steam 資料時才出現。
      # 內容同理:某篇文章的圖沒 alt、表格缺表頭,PR 一次都不會碰到。
      - name: 正式站無障礙巡檢
        run: pnpm exec playwright install --with-deps chromium && pnpm check:a11y

  # 從 OpenAPI spec 自動生成 API 測試。跟 e2e 分開跑,因為它會對同一個 DB 打上千個
  # 請求,要自己的拋棄式 DB;而且它不需要前端,只起後端就好。
  #
  # 為什麼值得:spec 有 123 個 operation,輸入是 schemathesis 生的而不是我們想到的。
  # 第一次跑就撞出 `GET /api/films/recent?limit=abc` → 500(三支 watch 端點都中,
  # 公開免認證)。設定與已知例外見 .config/schemathesis.toml。
  api-fuzz:
    name: API · Schemathesis(從 OpenAPI 自動生成)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      # 這個 job **不裝 pnpm、也不 pnpm install**(省了 36s:action-setup 15s + install 21s)。
      # 它只需要兩件 node 的事,兩件都不用第三方套件:
      #   · tests/e2e/seed.mjs 灌種子 —— 只 import `node:sqlite`(內建,需 node 22+)
      #   · 簽一個 owner JWT     —— HS256 就是 HMAC-SHA256,`node:crypto` 八行搞定
      # setup-node 留著是因為 runner 預設的 node 版本不保證有 `node:sqlite`。
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 26
      - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable
      - uses: Swatinem/rust-cache@258712b0b7b1ddf8bddc9fc3b0faca682b2736c3 # v2
        with:
          workspaces: .
          prefix-key: v1-rust
          # 與 e2e 共用(產物相同,兩邊都只跑 `cargo build --bin`)。
          # backend job 不在這把 key 裡,理由見那個 job 底下的說明。
          shared-key: workspace
          # 只有 main 存(理由同上)
          save-if: ${{ github.ref == 'refs/heads/main' }}
      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v6
      - name: build backend
        run: cargo build --locked --bin koimsurai-web-backend
      # stack.mjs 會等前端的 .output 存在;這裡只要後端,所以直接起 binary
      - name: 起後端(temp SQLite + migrations + seed)
        run: |
          node -e "
            const { spawn } = require('node:child_process');
            const { seed } = require('./tests/e2e/seed.mjs');
            const db = '/tmp/koimsurai-fuzz.db';
            const p = spawn('./target/debug/koimsurai-web-backend', [], {
              env: { ...process.env, DATABASE_URL: 'sqlite://' + db + '?mode=rwc',
                     BIND_ADDR: '127.0.0.1:13999', JWT_SECRET: 'fuzz',
                     ADMIN_USERNAME: 'nope', ADMIN_PASSWORD: 'nope', RUST_LOG: 'warn' },
              detached: true, stdio: 'ignore' });
            p.unref();
            (async () => {
              for (let i = 0; i < 120; i++) {
                try { if ((await fetch('http://127.0.0.1:13999/api/health')).ok) break; } catch {}
                await new Promise(r => setTimeout(r, 500));
              }
              seed(db);
              console.log('後端就緒');
            })();
          "
      # 兩段跑,順序有意義:先在完整種子上掃公開面,最後才帶 token 掃 admin CRUD。
      # admin 的 DELETE 會把種子清掉,所以它必須是最後一步——沒有下一步會讀到殘局。
      - name: schemathesis(公開面,不帶認證)
        run: |
          uvx schemathesis --config-file .config/schemathesis.toml \
            run http://127.0.0.1:13999/api/openapi.json \
            --exclude-path-regex '^/api/admin/' \
            -w 4 --report-junit-path st.xml
      # admin 寫入端點 typed 之後 stateful 階段才推得出 create → update → delete,
      # 而串接需要認證。JWT_SECRET 與上面起後端時給的 'fuzz' 一致。
      - name: schemathesis(admin CRUD,帶 owner token)
        run: |
          TOKEN=$(node --input-type=module -e "
            // HS256 = HMAC-SHA256(base64url(header).base64url(payload))。用內建的
            // node:crypto 而不是 jsonwebtoken,這個 job 才不必 pnpm install(省 36s)。
            import { createHmac } from 'node:crypto';
            const b64 = (o) => Buffer.from(JSON.stringify(o)).toString('base64url');
            const now = Math.floor(Date.now() / 1000);
            const head = b64({ alg: 'HS256', typ: 'JWT' });
            const body = b64({ id: 1, username: 'admin', role: 'OWNER', iat: now, exp: now + 7200 });
            const sig = createHmac('sha256', 'fuzz').update(head + '.' + body).digest('base64url');
            console.log(head + '.' + body + '.' + sig);
          ")
          uvx schemathesis --config-file .config/schemathesis.toml \
            run http://127.0.0.1:13999/api/openapi.json \
            --include-path-regex '^/api/admin/(tags|categories|blacklist|keyword-filters)' \
            -H "Authorization: Bearer $TOKEN" \
            -w 4 --report-junit-path st-admin.xml
      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v6
        if: failure()
        with:
          name: schemathesis-report
          path: |
            st.xml
            st-admin.xml
          retention-days: 7

  # 部署路徑守門:CI 過但 docker build 炸過(js-yaml + 未釘 pnpm 那次),
  # 因為前端 job 只跑 vite build、從不碰 Dockerfile。這個 job 補上那個缺口。
  docker:
    name: Docker · frontend + backend image build
    runs-on: ubuntu-latest
    # 只有這個 job 需要寫 package(把 build cache 推上 GHCR)。
    # 全域仍是 contents: read,不要為了一個 job 把權限提到頂層。
    permissions:
      contents: read
      packages: write
    # 快取從 type=gha 換到 GHCR。要講清楚**不是**為了比較快:
    # type=gha 打的是 Azure Blob 後端的 Actions Cache 服務,GHCR 也是 GitHub/Azure
    # 側的 HTTP endpoint,兩者都走網路,換過去不多一個跳點,傳輸大約是同一個量級。
    # 真正的理由是 Actions Cache 有硬性 10 GB/repo 且會 LRU 淘汰——rust-cache 一撐大
    # 就把 docker layer 擠掉,於是冷建 546s(2026-07 實際發生過)。GHCR 沒有這個上限。
    #
    # package 的可見性繼承來源 repo:這個 repo 是 public,所以兩個 buildcache 建立時
    # 就直接是 public(實測:拿匿名 token 打 ghcr.io 的 manifest 回 200),不必手動去
    # 改設定,也不吃帳號的 Packages 儲存額度。內容只有編譯產物與已經公開的原始碼——
    # .dockerignore 擋掉 .env* 與 .git,不會把祕密烤進快取層。
    # ⚠ 哪天 repo 轉成 private,這個前提就要重新確認。
    env:
      CACHE_FE: ghcr.io/${{ github.repository }}/buildcache-frontend
      CACHE_BE: ghcr.io/${{ github.repository }}/buildcache-backend
    steps:
      # fetch-depth: 2 是給下面那個 diff 用的(要有 HEAD^ 才比得出改了什麼)
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
          fetch-depth: 2
      # 只建「輸入真的變過」的那個 image。
      #
      # 我原本在這裡寫「cache mount 不會被 type=gha 匯出」——講太窄了。實情是
      # **沒有任何** buildx cache backend 會匯出 `--mount=type=cache` 的內容
      # (gha / registry / local / s3 都一樣,見 moby/buildkit#1512,2020-05 開到現在
      # 未解,維護者明確反對)。那不是 gha 的限制,是 cache mount 的設計。
      #
      # 所以 backend/Dockerfile 已改用 cargo-chef:相依的編譯產物落在真正的 image
      # layer 裡,匯得出去也復原得回來。現在 CI 上有三種結果而不是兩種——
      # 整層命中、只重編自己的程式碼(cook 層命中)、或真的冷建。
      # 即使如此,「沒必要就別觸發」仍然是最省的一手,所以這個判斷保留。
      #
      # 判不出來時(schedule / dispatch / 淺 clone)一律兩個都建——寧可多花時間,
      # 不要讓部署路徑的守門靜靜地不跑。
      - name: 判斷要建哪個 image
        id: scope
        run: |
          if ! git rev-parse HEAD^ >/dev/null 2>&1; then
            echo "判不出 diff,兩個都建"
            echo "frontend=true" >> "$GITHUB_OUTPUT"
            echo "backend=true"  >> "$GITHUB_OUTPUT"
            exit 0
          fi
          changed=$(git diff --name-only HEAD^ HEAD)
          echo "$changed"
          # 後端 image 只吃 Cargo.* 與 backend/
          if echo "$changed" | grep -qE '^(Cargo\.(toml|lock)|backend/)'; then
            echo "backend=true" >> "$GITHUB_OUTPUT"
          else
            echo "backend=false" >> "$GITHUB_OUTPUT"
          fi
          # 前端 image 的 context 是整個 repo,但 .dockerignore 擋掉的不算;
          # backend/ 以外的任何改動都可能進 COPY . . → 保守地建
          if echo "$changed" | grep -qvE '^backend/'; then
            echo "frontend=true" >> "$GITHUB_OUTPUT"
          else
            echo "frontend=false" >> "$GITHUB_OUTPUT"
          fi
      # fork 的 PR 拿到的 GITHUB_TOKEN 是唯讀的,登入照樣會成功(只是寫不進去),
      # 所以這步不加條件;真正防護是下面 cache-to 只在 push 時才給值。
      - name: 登入 GHCR
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
      # cache-to 只在 push 到 main 開:PR 不該把未合併的狀態寫進主快取,
      # 而且 fork PR 的 token 本來就寫不進去。
      # image-manifest=true + oci-mediatypes=true 是 GHCR 相容 registry 快取的必要設定。
      #
      # ⚠ 快取還不存在時 log 裡會出現一行紅字:
      #     ERROR: failed to configure registry cache importer: ...:latest: not found
      #   那是 **ERROR 字樣但不致命**——buildx 照樣往下建,job 仍然是綠的(首次啟用時
      #   實測過)。看到它不用緊張,它只代表這次沒東西可還原。
      # load: true 把建好的 image 匯進本機 daemon,trivy 才掃得到(build 完只留在
      # buildx 的快取裡,daemon 看不見)。匯出有成本,所以只在那個 image 真的重建時才做
      # ——上面的 scope 判斷已經幫我們擋掉不必要的那次。
      - name: build frontend image
        if: steps.scope.outputs.frontend == 'true'
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
        with:
          context: .
          file: Dockerfile
          push: false
          load: true
          tags: local/web-frontend:ci
          cache-from: type=registry,ref=${{ env.CACHE_FE }}
          cache-to: ${{ github.event_name == 'push' && format('type=registry,ref={0},mode=max,image-manifest=true,oci-mediatypes=true', env.CACHE_FE) || '' }}
          # 同下面 backend 的說明:runtime 層的 `apt-get upgrade` 不能吃快取。
          no-cache-filters: runtime
      - name: build backend image
        if: steps.scope.outputs.backend == 'true'
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
        with:
          context: .
          file: backend/Dockerfile
          push: false
          load: true
          tags: local/web-backend:ci
          cache-from: type=registry,ref=${{ env.CACHE_BE }}
          cache-to: ${{ github.event_name == 'push' && format('type=registry,ref={0},mode=max,image-manifest=true,oci-mediatypes=true', env.CACHE_BE) || '' }}
          # runtime 那一層做 `apt-get upgrade`,而快取鍵只看 Dockerfile 的字面、不看
          # 「apt 現在有什麼版本」——指令沒改就直接重用舊層,upgrade 等於凍結在建那層
          # 的當天。實際發生過:libssh-4 卡在 0.11.2(0.11.5 早就發了),trivy 一次報
          # 6 個 HIGH,而 Dockerfile 看起來完全沒問題,很難聯想到是快取。
          # 只對這個 stage 關快取:貴的 cargo-chef 層照吃,這層每次重跑約 10 秒。
          no-cache-filters: runtime

      # runtime image 裡 Debian / npm 那些套件的 CVE,在這之前**完全沒有東西在看**
      # ——cargo audit 只管 Cargo.lock,pnpm 那邊只管 package.json,兩者都看不到
      # base image 帶進來的 ffmpeg、libexpat、tar。
      #
      # ⚠ 門檻是 `--ignore-unfixed`,不是「任何 HIGH/CRITICAL」。實測當下:
      #     backend  138 筆 HIGH/CRITICAL,其中**只有 5 筆有修版**
      #              (其餘約 64 筆是 ffmpeg + libav*,Debian 根本還沒出修版)
      #     frontend  27 筆,其中 5 筆有修版
      #   對「沒有修版可用」的東西擋 CI,結果只會是永遠紅、然後大家學會忽略它。
      #   擋「有修版卻沒修」才是可行動的訊號。修完那 10 筆之後現在兩邊都是 0。
      - name: trivy 掃 frontend image
        if: steps.scope.outputs.frontend == 'true'
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: local/web-frontend:ci
          scanners: vuln
          severity: CRITICAL,HIGH
          ignore-unfixed: true
          exit-code: '1'
          format: table
      - name: trivy 掃 backend image
        if: steps.scope.outputs.backend == 'true'
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: local/web-backend:ci
          scanners: vuln
          severity: CRITICAL,HIGH
          ignore-unfixed: true
          exit-code: '1'
          format: table

  # workflow 自身的守門:actionlint 管正確性、zizmor 管安全(template injection、
  # 過寬權限、未釘 action、憑證外洩)。CI 自己也是攻擊面。
  workflows:
    name: Workflows · actionlint + zizmor
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      # actionlint 不在 taiki-e/install-action 的清單裡,用維護中的 wrapper action。
      - uses: raven-actions/actionlint@3d39aea434753780c3b3d4a1a31c854b4dbf49d7 # v2.2.0
      - uses: taiki-e/install-action@7f4eb899022d8fe70b20c4f3de697aa85c309026 # v2
        with:
          tool: zizmor
      - name: zizmor
        run: zizmor .github/workflows/