素材を移動しても原稿の参照が古い場所を向いたままなら、ファイル整理は完了していません。テキストエディタ 階層の変更では、移動先の存在、原稿内パスの書き換え、旧パス0件を一組で確認します。STUDIO-357の標本は画像とテキストリンクを一つずつ移動し、保存後のMarkdownを再読込できる形で残しています。
二つの参照を移動前に採番する
開始時の原稿chapters/chapter.mdには、画像../assets/figure.pngとリンク../assets/note.txtが一件ずつありました。最初にrefs usageで各参照元を調べ、原稿のどの行が素材を使うかを記録します。画像と通常リンクは記法が違うため、同じ「参照一件」でまとめません。
素材ファイルのSHA、原稿の開始時SHA、相対パスを台帳へ書きます。先に素材だけを動かすと原稿が一時的にリンク切れになるため、その状態も失敗ではなく移動途中として識別します。作業を中断するときは、どこまで済んだかが分かる印を残します。
画像を移して一件だけ書き換える
figure.pngをmoved/renamed-figure.pngへ移動しました。続いてrefs planを実行すると、chapter.mdの一件が書換対象として返りました。計画が画像行だけを指すことを確認してからrefs rewriteを適用し、rewrittenFiles=1、occurrenceCount=1を取得しました。
保存後の原稿では画像行が../moved/renamed-figure.pngになっています。表示上の画像を見ただけでは、キャッシュが旧ファイルを見せることがあります。文字列の再読込と新しい実体ファイルの存在を別々に確認するのが要点です。
テキストリンクは次の試行として動かす
次にnote.txtをmoved/renamed-note.txtへ移動します。画像の結果を使い回さず、リンク用のrefs planを取り直し、一件だけがchapter.mdにあることを確認します。適用後は通常リンクが../moved/renamed-note.txtを指しました。
画像とリンクを分けることで、一方の書換規則だけが動いた失敗を検出できます。二つを同時に移動し、結果を「2件」とだけ記録すると、画像2件を変えてリンクを残したような誤りを見落とします。
保存後83文字・4行を再読込する
最終原稿のSHA-256は8a0974544a66517c231a351427b346484ff24dd74cf50de252065000fcf61863です。UTF-8、LFで再読込し、characterCount=83、lineCount=4を得ました。内容は見出し、画像行、リンク行の順で、二つの新しい相対パスを含みます。
旧接頭辞../assets/を検索した結果は0件でした。さらに二つの新しい参照先が実在することを確認し、new_targets_exist=trueになりました。旧パス0件だけでは、空文字へ消した失敗も通るため、新パスと実体の両方が必要です。
片方だけ切れた失敗を保全する
想定失敗は、画像のファイル移動には成功したが原稿の参照を書き換えていない状態です。この失敗版では旧パスが一件残り、新実体は存在します。もう一つは、原稿だけ新パスへ変えたが素材移動が失敗した状態で、新参照先が存在しません。
復旧は失敗版を上書きせず、新しい原稿複製で行います。refs usageから対象行を取り直し、計画が一件であることを確認し、書換後に保存します。素材の移動先を存在検査し、旧パス0件、新パス二件、実体二件になるまで完了にしません。
フォルダをもう一段深くするときの注意
移動先がmoved/archive/のように深くなると、原稿から見た../の数も変わります。OS上の絶対パスをMarkdownへ貼らず、原稿ファイルの位置を起点に相対パスを計算します。原稿自体も同時に移動する場合は、素材移動と原稿移動を別試行にし、各段階で参照を再解決します。
名前に空白や非ASCII文字を含む素材では、Markdown記法やURLエンコードの扱いも確認します。今回の英数字標本から、それらの表示互換性まで保証しません。新しい文字種を含むときは別標本を作り、同じ存在検査と再読込を行います。
画像表示とリンク遷移は別の受入になる
保持証拠はパス書換、ディスク保存、旧語検索、新実体の存在を確認しています。特定のプレビューで画像が描画されたか、リンクをクリックしてテキストが開いたかまでは記録していません。構造上の参照合格と画面操作は分けます。
画面試験を追加するなら、アプリ版、開いた原稿SHA、画像の表示領域、リンク先の到達ファイルを記録します。キャッシュを避けるため原稿を閉じて再度開きます。その結果は今回のCLI受入票に上書きせず、同じSHAに紐づく別行として追加します。
二つの新パスを再現できれば引き渡せる
最終票には移動元、移動先、参照計画一件、書換結果一件を画像とリンクで二行ずつ持たせます。保存後原稿の83文字・4行・SHA、旧接頭辞0件、新実体の存在も付けます。
次の担当者は原稿を再読込し、../moved/renamed-figure.pngと../moved/renamed-note.txtを確認できます。素材二つのSHAを照合し、旧場所に頼らず参照を解決できたら構造試験は合格です。プレビュー描画やクリックは、必要な配布環境で別途判定します。