Design and implement an effective error message sub-system for our code generation tool

[ArthurMa1978]

We are moving fast, but our tools lack well-designed error messages. Unlike any formal compiler, which provides clear error codes and messages to help developers identify and resolve issues efficiently, we only throw exceptions with lengthy call stack information, which is very user-unfriendly.
Designing an effective error message sub-system is crucial for enhancing user experience and minimizing frustration.
The error message from our tool should be:

1. Clear and Unambiguous Messages: Ensure that error messages are simple, easy to understand, and contextually relevant. Avoid technical jargon that might confuse users.
2. Strategic Placement: Position error messages near the relevant field to make it easier for users to identify and correct the issue.
3. Provide Solutions: Good error messages not only highlight the problem but also offer solutions.
4. Avoid Blaming the User: Frame error messages in a way that doesn't place blame on the user. For example, instead of saying "You did not specify the format of the property XXX," use "Please specify the form of the property XXX".

Features

Preview Give feedback

1. Remove generic warn and generic error and replace with specific cases microsoft/typespec#3347
   emitter:client:csharp +1
2. [http-client-java] Java CodeGen should address the errors and warnings from TCGC microsoft/typespec#5575
   emitter:client:java +1
3. [http-client-python]: Python CodeGen should address the errors and warnings from TCGC microsoft/typespec#5576
   emitter:client:python +1
4. [http-client-csharp]: .NET CodeGen should address the errors and warnings from TCGC microsoft/typespec#5578
   emitter:client:csharp +1
5. Go CodeGen should address the errors and warnings from TCGC autorest.go#1485
   +0
6. TypeScript CodeGen should address the errors and warnings from TCGC autorest.typescript#2991
   HRLC P1 +2
   
7. System.InvalidOperationException: Can't find Baseline contract assembly autorest.csharp#5176
   v3 +1
   

Related tasks

Preview Give feedback

1. build(common): Update generator version in Azure SDK repo not stop when error happens autorest.csharp#2913
   v3 +1
2. [@azure-tools/typespec-csharp] Improve error message if generated property names conflict autorest.csharp#5190
   Mgmt v3 +2
   
3. Add document for all auto conversion in generator autorest.csharp#5192
   CodeGen +1
4. Enable Package validation - Part II azure-sdk-for-net#37826
   Mgmt +1
   
5. AutoRest Generation throws error autorest.csharp#4691
   Mgmt question +2
6. System.InvalidOperationException: Can't find Baseline contract assembly autorest.csharp#5176
   v3 +1
   
7. csharp CodeGen should provide clear message for self-service trouble shooting microsoft/typespec#5508
   emitter:client:csharp +1
   
8. Python CodeGen should provide clear message for self-service trouble shooting microsoft/typespec#5509
   emitter:client:python +1
9. Java CodeGen should provide clear message for self-service trouble shooting microsoft/typespec#5511
   emitter:client:java +1
   
10. TypeScript CodeGen should provide clear message for self-service trouble shooting autorest.typescript#2979
    P1 non-azure +2
    
11. Go CodeGen should provide clear message for self-service trouble shooting autorest.go#1484
    +0
    
12. Compiler/Emitter behavior consistency and improvement microsoft/typespec#5660
    design:needed needs-area +2
    

    

[jsquire]

@ArthurMa1978: Why is this here and not in the TypeSpec repo? Has this gone through the triage process and been discussed with the generator leads?

[ArthurMa1978]

@ArthurMa1978: Why is this here and not in the TypeSpec repo? Has this gone through the triage process and been discussed with the generator leads?

This initiative encompasses general code generation, including both TypeSpec and Swagger.
Designing a good error message sub-system is a significant undertaking that requires huge effort. This project is not limited to C# but extends to all the languages we support. Therefore, we will draft a design and conduct reviews and discussions across all languages.