Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

Allow hinting `DebugProtocol.Source` to prefer `path` over `sourceReference`

オープン
  • 何か問題がありますか？
#224 コメント 5 件 リアクション 2 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
30/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
停滞
技術スタック
javascript, nodejs, typescript
領域
api

調査の方向性

DebugProtocol.Source の定義と、正の sourceReference が path より優先される現在のルールから始めてください。優先順位、チェックサム検証、フォールバックのセマンティクスを明確にし、そのうえでプロトコル定義と例を更新して、クライアントが編集可能なパスと sourceReference スナップショットのどちらかを一貫して選択できるようにしてください。

索引モデルが issue の本文から書いたものです。

説明

clarification feature-request

It'd be nice if a new field (e.g. preference) gets added to DebugProtocol.Source to tell clients (IDEs) that if the Source can be mapped to a file, it should open that file instead of using sourceReference. Perhaps it's even worth making this the default, especially when combined with my item of checknotes below.

Details

  • It's not uncommon to end up debugging a program for which the input source has changed.
    • As in, the debugger still knows the original input source that the program is currently running.
    • A good example is NodeJS with JavaScript, and even TypeScript if the (loaded) source maps also contain the source.
  • Currently the protocol states that a sourceReference bigger than 0 means that should be used, regardless of path.
    • This would either be a "breaking" change (although it won't break anything, IDEs just wouldn't show "modern" behavior).
    • We can specify to only prefer path if checksums is present to validate whether it results in the correct file (contents).
  • It is more user friendly in IDEs if a Source can be mapped to the actual source file, instead of a snapshot in the debugger.
    • The user might already have the file open, and focusing it instead of opening a cached file is preferred.
    • The user can now also directly edit the file, without having to first look for the correct file based on the read-only snapshot.
  • The IDE might find the right file, but maybe its contents have changed:
    • We can use checksums to validate whether it is (the correct version of) the correct file. If not, revert to sourceReference.
  • We have the sources field but this isn't (meant as) a 1-on-1 mapping of the source itself.
  • Having the debug adapter only provide path is not enough:
    • If the file isn't found, the IDE has nothing to show.
    • If the file changed (and checksums isn't present), the IDE might display an outdated (or completely wrong) file.
    • If checksums is present, the IDE can validate whether the file (content) is correct, but not fallback to anything if it isn't.

This is mostly a big quality-of-life improvement towards IDE users, as these would now prefer the actual source files over cached versions provided by the debug adapter, assuming they're the same (using checksums). While the file content will be the exact same, mapping to an editable source file or mapping to a read-only "debug content file" is quite a large difference.

Hotreload example

Since this would still allow different Sources with the same path but a different sourceReference/checksums (and the IDE automatically picking between showing the path file or the read-only sourceReference viewer), we can also easily allow debug adapters to differentiate different versions of the same (path-specified) file, e.g. because of hotreloading:

  • Program loads a.js with AAA as checksum.
  • Debugger attaches, adapter tells the IDE about { path: 'a.js', sourceReference: 1, checksum: ['AAA'] }.
    • IDE finds the properly mapped a.js, validates the checksum and opens it.
  • User edits file and saves it, causing the program/debugger to hotreload it one way or another.
    • Let's say the new content results in BBB as checksum.
  • Debug adapter tells the IDE about { path: 'a.js', sourceReference: 2, checksum: ['BBB'] }.
    • IDE finds the file again (which might still be open), sees the checksum matches the (new) content, so opens it.
  • Debug adapter might tell IDE again about the previous file (ref 1, checksum AAA).
    • IDE finds the file but notices the different checksum. Falls back to using the sourceReference with value 1.
  • Debug adapter might tell IDE again about the current file (ref 2, checksum BBB) after it was saved, but before the hotreload.
    • IDE finds the file but notices the different checksum. Falls back to using the sourceReference with value 2.

Of course, this hotreload example is an advanced use case this change would allow. Just the QoL improvement to open the true (editable) source file instead of a snapshot if possible is already a very nice use case this allows.

主要言語
HTML
スター
1.8k
フォーク
173
平均マージ
7日 7時間
マージ済み PR（30日）
2

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

microsoft/debug-adapter-protocol のほかの issue

microsoft/debug-adapter-protocol の issue をすべて見る

似ている issue

Backend & API Design の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。