「名前でフォルダを探して無ければ作る」処理が自分の重複を掴み続ける問題を潰す

対象: Google Drive / S3 風の階層ストレージに対して「決まった名前のフォルダを探し、無ければ作る」処理を持つ自動化全般（GAS・Node・Python 問わず）。

症状

• 自動化が保存したはずのファイルが、現場が使っているフォルダに入っていない。
• 現場から見ると「同じ名前のフォルダが2つある」「素材が消えた」。
• 再帰の深さを増やしても直らない。数日〜数週間、誰も気付かないまま片方に溜まり続ける。

真因（設計の組み合わせで自己増殖する）

次の2つが同時にあると、必ず自己増殖ループになる。

1. 探索が浅い階層を優先し、ヒットしたら即 return する（幅優先＋早期 return）
2. 見つからなかったときの作成先が探索の起点（ルート）直下

初回に本物（深い階層にある、現場が作ったフォルダ）を取り逃がしてルート直下に空フォルダを作る → 2回目以降はその空フォルダの方が浅いので必ず先にヒット → 本物には二度と到達しない。

「ルートの特定が間違っていたのだろう」と考えてルート解決を厳密化しても直らない。深さでも起点でもなく、ヒットで即 return する順序が原因。

直し方

1. 探索は即 return せず、候補を全部集めてスコアで選ぶ

// NG: 浅い方が勝つ
function find(parentId, re, depth) {
  for (const f of children(parentId)) if (re.test(f.name)) return f;  // ← 即 return
  for (const f of children(parentId)) { const hit = find(f.id, re, depth - 1); if (hit) return hit; }
}

// OK: 全部集めてから選ぶ
const candidates = collect(workRootId, 2).filter(f => NAME_RE.test(f.name)).map(f => ({
  folder: f,
  score: (f.inWorkRoot ? 100 : 0) + (f.depth === 1 ? 20 : 0)
       + (STRICT_RE.test(f.name) ? 10 : 0) + (hasAnyFile(f) ? 5 : 0),
}));
candidates.sort((a, b) => b.score - a.score || createdAt(a) - createdAt(b)); // 同点は作成日時が古い方

同点の tie-break は作成日時が古い方にする。現場が先に作った実体が古く、自動化が作った重複が新しいので、これだけで正解に倒れる。

2. 作成先は「現場の作業フォルダ」配下にする

ルート直下に作ってよいのは、作業フォルダが存在しない旧構造のときだけ。作業フォルダは名前だけで同定しない。命名は揺れるので、子フォルダのマーカー（案件標準サブフォルダ名が複数ある、など）を併用する。

const MARKERS = ['<標準サブフォルダ名1>', '<標準サブフォルダ名2>', '<標準サブフォルダ名3>'];
// 名前の完全一致 +100 / 部分一致 +30 / マーカーを持つ子の数 × 10（上限あり）
// ルート自身がすでにマーカーを2つ以上持つならルートが作業フォルダ

3. 名前マッチを緩くしすぎない

預かり.*素材|素材 のように部分語だけでもマッチする正規表現は、無関係なフォルダ（「素材集」など）を掴む。必須語を1つ決め、緩いパターンは「必須語で1件も出なかったときの最後の手段」に降格する。

4. 同じ解決ロジックを複数ファイルにコピペしない

アップロード・取込・パネル表示・デバッグの4箇所に同じ再帰関数がコピペされていると、直すときに必ず取り残す。1関数に集約して全呼び出し元をそこへ寄せる（既存関数は中身だけ差し替えて戻り値の契約を維持すると、呼び出し元を壊さずに寄せられる）。

5. 既にできた重複は削除せず、ファイルだけ移す

repair(caseKey, dryRun = true)
  → { canonical: {id, name, url}, misplaced: [{id, name, moved: [...], skipped: [...]}], dryRun }

• 正解フォルダに同名がある物は移さず skipped に積む。
• フォルダもファイルも削除しない（共有ストレージの削除は他人の作業を壊す）。空フォルダは残しておけば人が後で消せる。
• dryRun を既定 true にして、計画を読んでから実行する。

検証（2段でやる。片方だけでは足りない）

• Layer 1（ローカル単体テスト）: fake のストレージ API を注入して、①ルート直下の空重複より作業フォルダ配下の実体を選ぶ ②作業フォルダが無い旧構造では従来どおり動く ③新規作成が作業フォルダ配下に落ちる ④必須語を含まない紛らわしい名前を選ばない ⑤修復がフォルダを削除しない（fake の削除 API が呼ばれたら fail させる）。
• Layer 2（本番ストレージ）: 「どの候補を何点で選んだか」を返す読み取り専用のデバッグ経路を用意して実データで叩く。解決先 ID が現場のフォルダ ID と一致することを目視ではなく ID 比較で確認する。移動後は移動したファイルの親 ID を読み直して確認する（実行結果の戻り値を信じない）。

落とし穴

• 深さを 2 → 3 に増やす修正は症状を悪化させる（重複がより確実に先にヒットする）。
• ルート解決（設定セルや DB のフォルダ ID）を厳密化しても直らない。過去に同じ事故を起こして「ルートの特定」を直し、再発した実例がある。
• 候補の中身（ファイル有無）を見るスコアは API 呼び出しが増える。候補が数件のときだけ深掘りする上限を入れないと、全件ループでタイムアウトする。
• 重複フォルダのサブフォルダは移動対象に入れていないなら、その旨を戻り値に出す。黙って残すと「全部片付いた」と誤解される。