「成功しているのに『スキップ』と表示される」を最短で突き止める

シート/管理画面のボタン一覧 → コマンド関数をディスパッチする型のツール (Google Apps Script のコマンドキュー、社内管理UI、CLI のサブコマンド表など) で 必ず一度は踏むバグとその潰し方。エラーは一切出ないので、放置すると 「この機能は壊れている」と現場に誤解されたまま何日も動き続ける。

症状

• 実行は成功していて成果物も出来ている。なのに画面の状態列だけが 「スキップされました」「未実行」等になる
• ログにもエラーが無い。例外も飛んでいない
• 特定の1機能だけで起きる（他の機能は正常に「完了」と出る）

原因（最初にここを見る）

ディスパッチャが戻り値を真偽値のフラグとして読んでいるのに、 そのコマンドだけ**同じキー名で配列(明細)**を返している。

// 呼び出し元（全コマンド共通の表示ロジック）
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 判定に頼らない。

if (ret && ret.skipped === true) { ... }

2. フラグと明細でキー名を共有しない。skipped(bool) と skippedItems(array) に分ける。 名前を共有した瞬間に壊れる、が本質。

3. 既定の表示文を上書きできる口を用意する。共通の固定文 （「完了（詳細は別シート参照）」等）は、成果物の置き場が違う機能では 別の意味で誤誘導になる。コマンドが panelResult のような1行サマリを返せるようにし、 あればそれを表示する。

} else if (ret && ret.panelResult) {
  cell.setValue(String(ret.panelResult).slice(0, 200));
} else {
  cell.setValue('完了');
}

4. 明細の件数は人の言葉に畳んで返す。読む人は配列を読めない。 保存 2件 / 既に取込済み 1件 / エラー 0件 → 保存先フォルダ のように、 「何件どうなって、どこに置いたか」を1行で。

再発防止（ここまでやらないと必ず再発する）

表示文言そのものをテストする。 この種のバグは例外を出さないので、 戻り値のテストでは捕まらない。安いのはソース原文の検査:

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 して確認する。 「たぶん直った」で閉じると、表示バグは誰も気付かないまま残る