debug-info-remapping

デバッグ情報のリマッピング

説明

Lynx では、メインスレッドのスクリプトはバイトコードにエンコードされ、外部のデバッグ情報スキームを使用します。このスキームでは、ランタイムエラーメッセージ内の行番号と列番号は実際の行番号と列番号ではありません。行番号と列番号は、外部の debug-info.json ファイルから解読する必要があります。

debug-info.json の形式は次のとおりです:

{
  "lepusNG_debug_info": {
    "function_info": [
      {
        "function_id": 1,
        "function_name": "App",
        "line_col": [
          { "line": 1, "column": 1 },
          { "line": 2, "column": 1 },
          { "line": 3, "column": 1 }
        ]
      }
    ]
  }
}

適用するタイミング

このスキルは、function_id:pc_index を元のソースコードの位置にリマップしたい場合に役立ちます。

ユーザーが function_id:pc_index を含むランタイムエラーメッセージに遭遇し、そのエラーメッセージに main-thread.js と debug-info.json が含まれている場合、たとえば:

main-thread.js exception: App render failed at main thread backtrace:
    at App (file:///main-thread.js:1356:13)
    at doRender (file:///main-thread.js:1002:12)
    at call (native)
    at render (file:///main-thread.js:466:52)
    at _renderToString (file:///main-thread.js:1001:569)
    at renderToString (file:///main-thread.js:998:191)
    at renderMainThread (file:///main-thread.js:766:45)
    at renderPage (file:///main-thread.js:853:69)

ここで function_id:pc_index は 1356:13 です。

ワークフロー

1. ユーザーに function_id:pc_index を尋ねる

ユーザーはエラーメッセージ内の function_id:pc_index を提供する必要があります。または、完全なバックトレースを提示してください。

それがメインスレッドのバックトレースかどうかを確認する必要があります。バックグラウンドスレッドのバックトレースはリマッピングが不要だからです。

2. debug-info.json 内の対応する位置を見つける

ユーザーに debug-info.json のパスを尋ねてください。たとえば、main エントリを持つ rspeedy プロジェクトでは、次の場所に配置されます:

• main-thread.js: $PROJECT_DIR/dist/.rspeedy/main/main-thread.js
• debug-info.json: $PROJECT_DIR/dist/.rspeedy/main/debug-info.json

ユーザーが rspeedy build を使用していて .rspeedy フォルダーが存在しない場合は、DEBUG='rspeedy,rsbuild' rspeedy build でプロジェクトをビルドするよう促してください。

3. リマッピングスクリプトを実行する

スタックトレース内の各 function_id:pc_index ペアに対して、リマッピングスクリプトを実行します。

node ${CLAUDE_PLUGIN_ROOT}/skills/debug-info-remapping/scripts/index.mjs $PROJECT_DIR/[dist]/.rspeedy/[main]/debug-info.json $function_id $pc_index

4. リマップされた位置を出力する

リマッピングスクリプトは、line:column の形式でリマップされた位置を出力します。

各 function_id:pc_index ペアについて、リマップされた位置を出力する必要があります。

スタックトレース内の function_id:pc_index ペアをリマップされた位置に置き換え、リマップされたスタックトレースを表示してください。

5. リマップされたスタックトレースを表示する

main-thread.js ファイルに到達できる場合は、リマップされた位置のソースコードとともに、リマップされたスタックトレースを表示してください。

最終的な出力は次のようになります:

main-thread.js exception: App render failed at main thread backtrace:
    at App (./dist/.rspeedy/main/main-thread.js:9368:56)
    at doRender (./dist/.rspeedy/main/main-thread.js:7237:44)
    at call (native)
    at render (./dist/.rspeedy/main/main-thread.js:3706:72)
    at _renderToString (./dist/.rspeedy/main/main-thread.js:7177:78)
    at renderToString (./dist/.rspeedy/main/main-thread.js:7067:91)
    at renderMainThread (./dist/.rspeedy/main/main-thread.js:5423:113)
    at renderPage (./dist/.rspeedy/main/main-thread.js:6199:46)

   ╭─[5:55]
 3 │ export function App() {
 4 │   if (__MAIN_THREAD__) {
 5 │     throw new Error('App render failed at main thread');
   ·                                                      ─┬
   ·                                                       ╰── main-thread.js exception: App render failed at main thread backtrace
 6 │   }
 7 │
   ╰────

   ... (the same for other callstacks such as doRender, call, render, _renderToString, renderToString, renderMainThread, renderPage here)

Files used:

  - Debug Info: ./dist/.rspeedy/main/debug-info.json
  - Source File: ./dist/.rspeedy/main/main-thread.js

./dist/.rspeedy/main/main-thread.js:9368:56 は、エディターやターミナルでクリック可能であることを保証します。