code-quest-review

Code Quest 專案特定 Code Review

除通用 /code-review skill 的審查維度外，本專案額外檢查以下項目。

Import

• import 放在檔案最頂部，不要 inline import（函式中間寫 import）
• Node.js built-in import（node:path, node:fs）放最上方

isolatedDeclarations

summoner package 開啟了 isolatedDeclarations: true，影響：

• exported 變數必須有顯式型別標注 — 不可依賴推導，這不是冗餘
• schema 檔（schemas.ts、launch-options.ts）的縮寫型別別名（Opt、Str、Num、Bool、Unk、Loose）是為了簡化這些必要標注，屬合理設計，不應移除
• 審查時看到 schema export 帶顯式型別，不要標為「冗餘型別標注」

Zod

• .passthrough() / .loose() → 改 z.looseObject()（Zod v4 deprecated）
• shared schema 只有一個 package 使用 → 搬到該 package
• payload as { ... } inline type assertion → 改用 zod schema parse：
  1. 先查 shared schemas 有沒有現有 schema 可用
  2. 沒有才新建，放 shared 讓前後端共用
  3. 不要 inline z.looseObject({...}).parse(payload) — 那只是換一種 inline，應該抽成 named schema

跨 Package 對齊（shared / summoner / server / client）

• server emitter.on('event', ...) 的 event name 跟 shared socket-events.ts 定義是否一致
• server ch.sendRequest('event', ...) 的 event name 跟 adapter REQUEST_MAPPINGS 是否一致
• adapter transformControlRequest 產出的 event name 跟 server handler 訂閱的是否一致
• client handler on map 的 event name 跟 server emit 給 client 的是否對齊
• shared ClientToServerEvents / ServerToClientEvents 定義跟實際 emit/on 是否同步

summoner（CLI adapter）

• REQUEST_MAPPINGS 是否涵蓋所有 ch.sendRequest 呼叫的 event name
• adapter transform 每個 case 是否都有 named function（不用 inline arrow）
• isRecord() 等 util 是否集中在 utils.ts，不重複定義
• ProcessRunner 終止方法只有 kill()（底層呼叫 handle 的 abort()）— 不要再加 abort() wrapper
• console.debug / console.log → 改用 logger（pino），注意 pino API 第一個參數是 object：logger.debug({ err }, 'message')

server handler

• middleware 是否正確：
  • 需要 channel 且有 callback → withError(withChannel(handler))
  • 需要 channel 無 callback → withChannel(handler)
  • 需要 socket → withSocket(handler)
  • 不需要 channel → 直接註冊
• handler 使用 ch.sendRequest('event', payload) 不直接用 protocol subtype
• handler 使用 named function（不用 arrow）
• handler 內 respondToRequest 只在 auto-respond 或 CLI-initiated event 使用