Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#224 5 commenti 2 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
30/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
javascript, nodejs, typescript
Ambito
api

Direzione di ricerca

Iniziare con la definizione di DebugProtocol.Source e con la regola attuale secondo cui un sourceReference positivo ha la precedenza su path. Chiarire la preferenza, la convalida del checksum e la semantica del fallback, quindi aggiornare la definizione del protocollo e gli esempi in modo che i client possano scegliere in modo coerente tra un percorso modificabile e uno snapshot di sourceReference.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
HTML
Stelle
1.8k
Fork
173
Merge medio
7g 7h
PR unite (30g)
2

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di microsoft/debug-adapter-protocol

Tutte le issue di microsoft/debug-adapter-protocol

Issue simili

Altre issue su Backend & API Design

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.