跳轉到

D-20260815-02｜註解品質本機前移與多語 PR 流程

背景與驅動力

主 repo 的 strict 註解 gate 只在 CI 執行時，尚未提交的工作樹仍曾累積大量缺口；舊 regex checker 也漏掉 exported class member 等語法。Pinning、Signaling、TURN 已有語言中立工具， 但僅供人工執行，無法在編輯、staged commit 或本機 issue 交付時提早回饋。

考慮過的選項

  • 只靠 CI：權威單純，但回饋發生在 push／PR 後，否決。
  • 只靠 Git hooks：回饋早，但 clone 不會自動啟用且可用 --no-verify 略過，否決。
  • 同一規則分層供 editor、本機 issue、opt-in hooks 與官方上游 CI 使用（採納）。

決定

  • TypeScript 覆蓋改用 AST，辨識直接與同檔間接 export、class expression、decorator、accessor、 #private、protected member 與 overload group；所有納管 class 的 private declaration 都需自足 TSDoc。主 repo exported class 只對 public／protected method 強制，不因 public data field 或 accessor 限縮合法資料模型。
  • @param／@returns 只在單位、範圍、null、所有權、副作用、callback 或安全邊界不明顯時要求； 不建立逐參數形式閘，也不得以名稱重述 filler、baseline 或豁免清單清零。
  • 三個 TypeScript repo 以同一 analyzer 供 CLI 與 ESLint 即時診斷。TURN 保持標準函式庫 Python scanner，不為不存在的服務 API 創造 docstring 規則。
  • 每個產品 repo 提供 opt-in .githooks。setup 只寫該 repo 的 local core.hooksPath 與 open4wd.commentProfile，不得覆寫未知 hook 或全域設定。pre-commit 只讀 Git index blob； pre-push 跑全庫。缺 profile、Git／parse／blob 錯誤一律 fail closed。
  • maintainer 與 contributor 都硬擋結構品質；只有主 repo maintainer 硬擋繁中，contributor 只收到語言報告。Pinning、Signaling、TURN 兩種 profile 均接受英文或繁中。
  • workflow issue 由 處理中 進入 已處理 前，依 affected_repos 先完成全部本機品質命令； 任一步失敗時 issue、時間線、owner 與 claim 不得先寫入。
  • 三個公開 Template 的官方上游另有獨立、語言中立 required job；job 不被 build、test、image publish 或 deploy needs，fork 也不會因 clone 自動啟用 hook。此決定延伸而不取代 D-20260813-01。
  • 外語 PR 可以開啟、討論與 review，但主 repo 合併前要完成繁中技術複核。預設由維護者提出 suggested changes 讓作者套用；直接修改 fork branch 只在作者允許且先確認 workflow secret 風險後使用。自動翻譯不得取代技術語意 review。

後果與影響

缺註解會依序在 editor、staged commit、本機 issue 交付與官方 CI 被發現，CI 仍是最終權威。 代價是每個 repo 都要保留可離線執行的 analyzer、fixture 與 hook runner；跨 repo 一致性由共同 fixture 語意與 workflow 測試維持，不建立 private repo 或套件 registry runtime 相依。