# 「成功しているのに『スキップ』と表示される」を最短で突き止める シート/管理画面の**ボタン一覧 → コマンド関数をディスパッチ**する型のツール (Google Apps Script のコマンドキュー、社内管理UI、CLI のサブコマンド表など) で 必ず一度は踏むバグとその潰し方。エラーは一切出ないので、放置すると 「この機能は壊れている」と現場に誤解されたまま何日も動き続ける。 ## 症状 - 実行は成功していて成果物も出来ている。なのに画面の状態列だけが 「スキップされました」「未実行」等になる - ログにもエラーが無い。例外も飛んでいない - 特定の1機能だけで起きる（他の機能は正常に「完了」と出る） ## 原因（最初にここを見る） ディスパッチャが戻り値を**真偽値のフラグ**として読んでいるのに、 そのコマンドだけ**同じキー名で配列(明細)**を返している。 ```js // 呼び出し元（全コマンド共通の表示ロジック） const ret = commands[name].apply(null, args); if (ret && ret.skipped) { // ← 真偽値のつもり status = 'スキップ'; message = ret.reason || 'スキップされました'; } // あるコマンドの実装 return { ok: true, saved: [...], skipped: [], errors: [] }; // ← 明細の配列 ``` JavaScript では **空配列 `[]` も truthy** なので `if (ret.skipped)` は常に成立する。 `reason` は無いので既定文が出る。**型が無い言語（GAS/素のJS/Python の dict）では コマンドを1つ足した時点で、既存の全機能の表示規約を黙って壊せる**。 同じ形の別バリエーション: - `errors: []` を `if (ret.errors)` で読んで常にエラー表示 - `warnings: {}` を truthy 判定（空オブジェクトも truthy） - Python なら逆に `[]` が falsy なので「明細があるのに成功扱い」に化ける ## 修正 1. **分岐を厳格化**する。truthy 判定に頼らない。 ```js if (ret && ret.skipped === true) { ... } ``` 2. **フラグと明細でキー名を共有しない**。`skipped`(bool) と `skippedItems`(array) に分ける。 名前を共有した瞬間に壊れる、が本質。 3. **既定の表示文を上書きできる口**を用意する。共通の固定文 （「完了（詳細は別シート参照）」等）は、成果物の置き場が違う機能では 別の意味で誤誘導になる。コマンドが `panelResult` のような1行サマリを返せるようにし、 あればそれを表示する。 ```js } else if (ret && ret.panelResult) { cell.setValue(String(ret.panelResult).slice(0, 200)); } else { cell.setValue('完了'); } ``` 4. 明細の件数は**人の言葉に畳んで**返す。読む人は配列を読めない。 `保存 2件 / 既に取込済み 1件 / エラー 0件 → 保存先フォルダ` のように、 「何件どうなって、どこに置いたか」を1行で。 ## 再発防止（ここまでやらないと必ず再発する） **表示文言そのものをテストする。** この種のバグは例外を出さないので、 戻り値のテストでは捕まらない。安いのはソース原文の検査: ```js import { readFileSync } from 'node:fs'; const src = (f) => readFileSync(new URL('../src/' + f, import.meta.url), 'utf8'); test('ディスパッチャの判定が === true で書かれている', () => { for (const f of ['Dispatcher.js', 'Queue.js']) { assert.match(src(f), /if \(ret && ret\.skipped === true\) \{/); assert.doesNotMatch(src(f), /if \(ret && ret\.skipped\) \{/); // 退行検知 } }); test('配列を返すコマンドの戻り値をスキップと誤判定しない', () => { const isSkip = (ret) => Boolean(ret && ret.skipped === true); assert.equal(isSkip({ ok: true, saved: [{}], skipped: [], errors: [] }), false); assert.equal(isSkip({ skipped: true, reason: '対象が無いので実行しません' }), true); }); ``` 規約が真偽値なのか明細なのかを、**コマンド一覧の隣にコメントで1行**書いておく。 コマンドを足す人はディスパッチャを読まない。 ## 調査のコツ（順序を守ると数分で終わる） 1. 表示文言を**原文のまま**コードベース全文検索する（`スキップされました` 等）。 要約・言い換えをすると当たらない 2. ヒットした分岐の**判定式だけ**を見る。ここで `if (ret && ret.xxx)` の形なら ほぼ確定。ログや外部APIを疑うのは後回し 3. その機能の実装の `return` 文を見て、同名キーの**型**を確かめる 4. 直したら**本番の1件で実際に実行**し、表示セル/画面を read-back して確認する。 「たぶん直った」で閉じると、表示バグは誰も気付かないまま残る ---