Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#224 5 comentarios 2 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
30/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
javascript, nodejs, typescript
Área
api

Línea de trabajo

Comience con la definición de DebugProtocol.Source y la regla actual de que un sourceReference positivo tiene precedencia sobre path. Resuelva la preferencia, la validación de la suma de comprobación y la semántica de fallback; después, actualice la definición del protocolo y los ejemplos para que los clientes puedan elegir de forma coherente entre una ruta editable y un snapshot de sourceReference.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
HTML
Estrellas
1.8k
Forks
173
Merge medio
7 d 7 h
PR fusionados (30 d)
2

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de microsoft/debug-adapter-protocol

Todos los issues de microsoft/debug-adapter-protocol

Issues similares

Más issues de Backend & API Design

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.