microsoft / microsoft/TypeScript

Feature request: machine-readable (JSONL) diagnostics output

Ouverte
#63,632 6 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Awaiting More Feedback Suggestion
Langage dominant
Go
Étoiles
111k
Forks
14.3k
Merge moyen
2 j 4 h
PR mergées (30 j)
132

Description

## Background

Type-checking integrations that run alongside a dev server - e.g., `vite-plugin-checker`, or a NestJS-style backend that auto-restarts once a change type-checks cleanly - need to know, after every file change, whether the project currently has type errors. There are a few ways to get that from `tsc` today, but they have downsides:

1. Re-run `tsc --noEmit` on each change. Simple to consume (process exit code), but every run is a cold check - no incremental reuse - so it's slow on a real codebase and adds latency to every save, especially on a large codebase or many changes back to back.
2. Run `tsc --watch --noEmit` once and parse its stdout. This is the fast path: the watcher reuses program state and only rechecks what changed. But the output is built for humans, not machines. This causes code like [this](https://gist.github.com/Alex-Bond/b94a5155ec06c73b9eebe7a97b3e523c). While this is faster, it's not ideal, as any changes to the response structure or copy will cause the script to break.

As a side QOL improvement, it will allow for easier logging of the errors in CI/CD - instead of trying to figure out multiline errors, it can now be easily streamed into monitoring systems.

## Proposal

A single flag that switches the entire console output stream to JSONL. This is deliberately all-or-nothing: when enabled, nothing is written as free text, so a consumer can readline → JSON.parse every line without a parser mode-switch. This also composes with --watch and --noEmit, which reuse the same reporters.

Examples of proposed output:
```jsonl
{"type":"diagnostic","category":"error","code":2304,"file":"src/a.ts","start":{"line":3,"character":9},"end":{"line":3,"character":12},"message":"Cannot find name 'foo'.","relatedInformation":[]}
{"type":"summary","errors":1,"warnings":0}
```

```jsonl
{"type":"status","code":6032,"message":"File change detected. Starting incremental compilation..."}
{"type":"diagnostic","category":"error","code":2304,"file":"src/a.ts","start":{"line":3,"character":9},"end":{"line":3,"character":12},"message":"Cannot find name 'foo'.","relatedInformation":[]}
{"type":"summary","errors":0,"warnings":0}
```

### Flag

Off the top of my head, there are a couple of ways to name the flag:

1. `--json` - while this repeats the same approach as `--pretty`, it can be confused with other configurations like `resolveJsonModule`.
2. `--pretty json` - convert `--pretty` from a simple boolean to an advanced combo of boolean and enum. The side problem is that currently, the tsconfig.json field `pretty` is a boolean, and at first glance, there are no union types in the JSON parser and validator.
3. `--diagnosticsFormat json` - the most distinct option, but can confuse when the user tries to use `--pretty` and json.

To my personal taste, it looks like microsoft/typescript-go#2 is the best option. I'm not a maintainer of this codebase, so I will leave it to core contributors to decide.

### stdout vs stderr

It might make sense to split into 2 streams for easier logging.

## Implementation

With my limited knowledge of the codebase, I can see that it is possible to implement it by creating a new flag + adding an additional formatter in diagnostics.go.

I can work on a PR for this, but I need to know the decision about the flag before I try to implement it.

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par lire diagnostics.go et la gestion existante de --pretty et --noEmit. Déterminez avec les maintainers le nom du flag et le comportement de stdout/stderr avant d’implémenter le formatter supplémentaire. C’est terminé lorsque le mode sélectionné émet de manière cohérente du JSONL lisible par machine, y compris les diagnostics, les résumés et les messages d’état de watch.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
go, typescript
Domaine
cli, tooling
Type d'issue
Fonctionnalité
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
Calme
Clarté
Plutôt claire
Accessibilité débutants
45/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.