# 自分が管理していない上流ファイルを「差し込み」で維持する型 — 死んだパッチを検知して retired に移す ## これは何のための指示書か あなたの手元には、**他の誰か（上流）が更新し続けるスクリプト**があり、そこに自分専用の修正を当て続けたい。 典型例: - 共有リポを `git pull` で受け取り、自分の機体だけに必要な修正を足している - 社内共通ツールの配布物に、1台だけの回避策を当てている - OSS を fork せずに、手元で数行だけ書き換えて使っている 素朴にやると必ずこうなる: 1. 上流を取り直すと自分の修正が消える 2. 消えたことに気付かない 3. 気付かないまま「直したはず」の機能が死に、**その機能が支えていた検査も一緒に死ぬ** この指示書は、それを「**当て直しを自動化し、当たらなくなった差し込みを警報に変える**」形で解く。 実測ベース: この型で維持している差し込みは29本、うち4本が上流の変更で死亡し、警報経由で発見・処理された。 ## 全体像 正本（あなたが管理するリポ）に **差し込み定義の配列** を1つ置く。 それを当てるスクリプトを毎日1回走らせる。当たらなくなったら**警報を出して落ちる**。 正本リポ patches.mjs … 差し込み定義（PATCHES 配列）＋ 適用エンジン test/patches.test.mjs … 差し込みが「上流の実物」に当たることのテスト 上流のファイル（live） .mjs … 毎日の同期で上書きされる。ここを直接直しても翌日消える ## 差し込み1本の形 ```js { file: '.mjs', // marker: 「もう当たっている」ことを見分ける文字列。当てた後のコードにだけ現れる語を選ぶ。 marker: 'const launchStarted = Date.now();', // find: 上流の「いまの実物」と完全一致する文字列（前後の空白も1文字も違えてはいけない） find: [ 'async function launchCodex(args) {', ' let result;', ].join('\n'), // replace: 置き換え後。find の全行を保持し、足す行だけ増やす。 replace: [ 'async function launchCodex(args) {', ' const launchStarted = Date.now();', ' let result;', ].join('\n'), } ``` 適用エンジンはこれだけ: ```js export function applyPatch(text, patch) { if (patch.retired) return { text, changed: false, reason: 'retired' }; if (text.includes(patch.marker)) return { text, changed: false, reason: 'already' }; if (!text.includes(patch.find)) return { text, changed: false, reason: 'anchor-missing' }; return { text: text.replace(patch.find, patch.replace), changed: true, reason: 'patched' }; } ``` 返る4状態がこの型の全てである。**`already` と `anchor-missing` を区別することが核心**。 `anchor-missing` を「もう当たってるんだろう」で黙らせた瞬間、この仕組みは無意味になる。 ## 🔴 落とし穴1: marker を replace 後のコードに無い文字列にしてしまう `marker` は**当てた後のテキストに必ず含まれている**こと。含まれないと毎回 `find` を探しにいき、 2回目以降は `anchor-missing` になって偽の警報が出る。逆に marker が**当てる前にも**含まれていると、 一度も当たっていないのに `already` と報告する（**最悪の故障モード。黙って何もしない**）。 marker は `replace` から選び、`find` に含まれていない語にする。 ## 🔴 落とし穴2: find を構文の途中で切る `find` は必ず**構文単位**（文の先頭から終端まで、対応する括弧・引用符ごと）で切る。 引数リストの途中や、開き括弧だけを含む形で切ると、置換後に構文エラーになる。 # 適用後に必ず走らせる。これが唯一の検出器。 node --check この1行を省くと、壊れたファイルを配って初めて気付く。 ## 🔴 落とし穴3: 差し込みは「連鎖」する 後の差し込みが、前の差し込みが置いた行を狙うことがある。これは避けるのではなく**設計として認める**。 差し込みA: 上流の素の2行 → Aの形 差し込みB: Aの形 → Bの形（find が A の replace そのもの） こうすると、**まっさらな上流**（A→B の順に当たる）でも、**すでに A が当たっている手元**（B だけ当たる）でも、 同じ最終形に着地する。片方しか成立しない設計にすると、機体ごとに状態が分かれる。 ただし連鎖させたら、**テストでもその順に当てて検証する**こと（後述）。 ## 🔴 落とし穴4: 既存の差し込みの replace を書き換えても届かない すでに `already` になっている差し込みの `replace` をあとから直しても、**live には永遠に届かない** （marker が見つかるので置換が走らない）。挙動を変えたい時は: - **新しい差し込みを1本足す**（find = 現在 live にある壊れた形、marker = 直した後の形にだけ在る語） これを知らずに replace を直して「直した」と報告する事故が起きやすい。 ## 🔴 落とし穴5: 死んだ差し込みを消すと、上流が戻った時に気付けない 上流が変わって `find` が二度と当たらなくなった差し込みは、**消さずに `retired` へ移し、理由を書く**。 ```js { file: '.mjs', retired: '上流の関数シグネチャが (…, provider, attempts = 1) へ変わり、この find は二度と当たらない。' + '目的は marker const abortLedger の差し込みへ移した', marker: '…', find: '…', replace: '…', // 元の内容はそのまま残す } ``` `retired` は「当てにいかないし、警報も出さない」状態。消してしまうと、 上流が元に戻った時や、別の機体で古い上流が残っていた時に、履歴が何も語らない。 ## 毎日の実行と警報 # 書かずに検める（毎日1回・cron / スケジューラ） node patches.mjs --check # 当てる node patches.mjs `--check` の出力と終了コードをこう設計する: | 状態 | 出力 | exit | |---|---|---| | 全部 already / retired | `未適用 0 件` | 0 | | 未適用がある | `未適用 N 件` | 1 | | **anchor-missing がある** | `🚨 差し込みが二度と当たらない: []` | **3** | | ファイルが無い | `見つからない: …` | 2 | **`anchor-missing` に専用の終了コードを与える**のが要点。「未適用」と同じ扱いにすると、 「まだ当てていないだけ」と「上流が変わって安全網が死んだ」が混ざって埋もれる。 警報文には必ず「どうすればよいか」を書く: 🚨 N 件の差し込みが anchor-missing。上流が変わってこの安全網は死んでいる。 上流の現物に合わせて貼り直すか、retired にして理由を書くこと（放置すると巻き戻りに気付けない）。 ## テストの書き方（ここで一番事故る） ### 期待件数を手書きの数値で固定しない ```js // ✗ 差し込みを1本足した翌日に偽 fail する assert.equal(result.stale.length, 2); // ○ PATCHES から導出する。数ではなく「どのファイルか」で見る const active = PATCHES.filter((p) => !p.retired && p.file === '.mjs').length; assert.ok(active >= 2); assert.equal(result.stale.length, active); ``` ### fixture は「上流の実物」から作り、patch.find を fixture に使わない `applyPatch(patch.find, patch)` は**必ず通る**（find で find を探すのだから）。 これは何も検証していない。fixture は上流の実物を写したものを別に持ち、そこに当てる。 ```js const LIVE_SOURCE = [ /* 上流ファイルから実際に写した行 */ ].join('\n'); const applied = applyPatch(LIVE_SOURCE, getPatch(MARKER)); assert.equal(applied.reason, 'patched'); // 当たること assert.deepEqual(applyPatch(applied.text, getPatch(MARKER)), { text: applied.text, changed: false, reason: 'already', }); // 冪等であること ``` ### 連鎖する差し込みは、連鎖の順に当てた結果を検証する ```js const afterA = applyPatch(LIVE_SOURCE, getPatch(MARKER_A)); const afterB = applyPatch(afterA.text, getPatch(MARKER_B)); assert.equal(afterB.reason, 'patched'); ``` fixture を手写しで「B が当たった後の形」として持つと、上流が動いた時に嘘の緑になる。**必ず導出する。** ### 🔴 最大の落とし穴: テストが足りない値を注入していると、壊れたコードが緑になる 実害の記録。ある差し込みが、別の関数で宣言された変数を参照するコードを置いてしまった （スコープ外参照 → 実行すれば `ReferenceError`）。ところがテストは、置いたコードを サンドボックスで走らせる際に**その変数をコンテキストに注入していた**ため、ずっと緑だった。 結果、この差し込みが守るはずだった記録は**1件も書かれないまま数日が過ぎた**。 対策は「注入をやめる」ではなく「**注入していないことを assert する**」: ```js const context = makeContext(); // 足りない変数は入れない assert.equal(Object.hasOwn(context, 'someVar'), false, '注入せずに走ること'); vm.runInNewContext(`${patchedSource}\nglobalThis.__run = () => target();`, context); await assert.rejects(context.__run, (e) => e === context.expectedExit); ``` さらに、コメント行を除いた**実コードに参照が残っていないこと**も見る （説明コメントに変数名を書くと、素朴な文字列検索は当たってしまう）: ```js const code = source.split('\n').filter((l) => !l.trim().startsWith('//')).join('\n'); assert.equal(code.includes('someVar'), false); ``` ### retired であること自体をテストで固定する ```js function getRetiredPatch(marker) { const [p] = PATCHES.filter((x) => x.marker === marker); assert.ok(p.retired, `retired patch: ${marker}`); return p; } test('死んだ差し込みは retired で、上流の実物にも当たらない', () => { const p = getRetiredPatch(MARKER); assert.equal(LIVE_SOURCE.includes(p.find), false); // 本当に当たらない assert.deepEqual(applyPatch(LIVE_SOURCE, p), { text: LIVE_SOURCE, changed: false, reason: 'retired', }); assert.ok(String(p.retired).length > 10, 'retired には理由を書くこと'); }); ``` これを入れておくと、誰かが「もう要らないだろう」と retired を消した時に落ちる。 ## 上流の関数シグネチャが変わった時の判断 一番厄介なのは、**呼び出し先の引数の意味が変わる**ケース。 実例: 上流の記録関数が `f(a, b, c, provider = 'x', extra = {})` から `f(a, b, c, provider = 'x', attempts = 1)` に変わった。第5引数は「追加フィールドのオブジェクト」から 「数値の試行回数」になった。呼び出し側は**エラーも警告も出さずに**、オブジェクトを `attempts` としてそのまま記録し続けた。記録は増えるが、狙ったキーは一生生まれない。 このとき「引数の渡し方を直す」は解にならない。**その関数を通す道が存在しない**。 判断: 上流の関数を経由せず、自分の差し込みの中で目的を完結させる。 上の例では、記録関数を呼ぶのをやめ、差し込みの中で1行だけ直接書き出す形にした。 上流が何をしようと壊れない。**上流のAPIに依存する量を減らすのが、差し込みの寿命を伸ばす唯一の方法。** ## 完了判定のチェックリスト 差し込みを足した／直した時、次の全部が揃って初めて「直した」と言える: 1. `node --check ` が通る（構文単位で切れている） 2. `--check` の `🚨 anchor-missing` が 0 件 3. テストスイートの **pass 数が減っていない**（「fail 0」だけ見ると、テストが消えても緑になる） 4. **実際に当該経路を1回走らせ、期待する副作用（ログ1行・ファイル1件）が 「修正より後の時刻で」増えている** 4 が一番飛ばされる。終了コードが 0 でも、成果物が無ければ何も起きていない。 逆に終了コードが 0 以外でも、成果物があれば成功していることがある。**判定は常に成果物で行う。** ## 上流への還元 手元の差し込みが3本を超えたら、上流に PR を出すことを検討する。 差し込みは「上流が受け取るまでの橋」であって、住む場所ではない。 retired が増え続けるなら、それは上流と設計が食い違っている信号である。 ---