Python CodeGen should provide clear message for self-service trouble shooting

[lirenhe]

Clear and concise description of the problem

We need to empower our customers both internal and external to easily trouble shooting and fix spec issues that would block the CodeGen.
If certain TypeSpec features or patterns are not supported by CodeGen, we should clearly point it out and suggest them to update the spec with the features we supported for CodeGen.

Today, Python CodeGen just returned a big call-stack like below which could not help for self-service resolving the problem.

I suggest we improve the following areas:

1. Leverage TypeSpec diagnostics APIs to report the errors and provide more context so that users could easily identify the TypeSpec source that cause the error.
2. Provide a clear message for the unsupported scenarios and ideally provide some suggestions on how to fix the spec.

The error reported today (copied from Azure/autorest.python#2975 (comment)):

ExternalError: Emitter "@azure-tools/typespec-python" crashed! This is a bug.
Please file an issue at https://github.com/Azure/autorest.python/issues

Error: Command failed: /home/swathip/repos/azure-sdk-tools/packages/python-packages/apiview-stub-generator/TempTypeSpecFiles/apiview-treestyle-parser-schema/node_modules/@typespec/http-client-python/venv/bin/python /home/swathip/repos/azure-sdk-tools/packages/python-packages/apiview-stub-generator/TempTypeSpecFiles/apiview-treestyle-parser-schema/node_modules/@typespec/http-client-python/eng/scripts/setup/run_tsp.py --output-folder=/home/swathip/repos/azure-sdk-tools/packages/python-packages/apiview-stub-generator --cadl-file=/tmp/cadl-codegen/python-yaml-path3e7a3279-3ef7-4a45-9b82-59d8fad79e04.yaml --package-version=0.3.13 --generate-packaging-files=false --flavor=azure --package-dir=apiview-stub-generator --package-name=treestyle-parser --generate-test=false --generate-sample=false --models-mode=dpg --emit-cross-language-definition-file=true --from-typespec=true
Traceback (most recent call last):
  File "/home/swathip/repos/azure-sdk-tools/packages/python-packages/apiview-stub-generator/TempTypeSpecFiles/apiview-treestyle-parser-schema/node_modules/@typespec/http-client-python/eng/scripts/setup/run_tsp.py", line 41, in <module>
    codegen.CodeGenerator(output_folder=args.output_folder, cadl_file=args.cadl_file, **unknown_args).process()
  File "/home/swathip/repos/azure-sdk-tools/packages/python-packages/apiview-stub-generator/TempTypeSpecFiles/apiview-treestyle-parser-schema/node_modules/@typespec/http-client-python/generator/pygen/codegen/__init__.py", line 336, in process
    self.sort_exceptions(yaml_data)
  File "/home/swathip/repos/azure-sdk-tools/packages/python-packages/apiview-stub-generator/TempTypeSpecFiles/apiview-treestyle-parser-schema/node_modules/@typespec/http-client-python/generator/pygen/codegen/__init__.py", line 247, in sort_exceptions
    for group in client["operationGroups"]:
KeyError: 'operationGroups'

    at genericNodeError (node:internal/errors:983:15)
    at wrappedFn (node:internal/errors:537:14)
    at checkExecSyncError (node:child_process:882:11)
    at execSync (node:child_process:954:15)
    at $onEmit (file:///home/swathip/repos/azure-sdk-tools/packages/python-packages/apiview-stub-generator/TempTypeSpecFiles/apiview-treestyle-parser-schema/node_modules/@typespec/http-client-python/dist/emitter/emitter.js:110:9)
    at async Object.$onEmit [as emitFunction] (file:///home/swathip/repos/azure-sdk-tools/packages/python-packages/apiview-stub-generator/TempTypeSpecFiles/apiview-treestyle-parser-schema/node_modules/@azure-tools/typespec-python/dist/src/emitter.js:3:5)
    at async runEmitter (file:///home/swathip/repos/azure-sdk-tools/packages/python-packages/apiview-stub-generator/TempTypeSpecFiles/apiview-treestyle-parser-schema/node_modules/@typespec/compiler/dist/src/core/program.js:366:13)
    at async compile (file:///home/swathip/repos/azure-sdk-tools/packages/python-packages/apiview-stub-generator/TempTypeSpecFiles/apiview-treestyle-parser-schema/node_modules/@typespec/compiler/dist/src/core/program.js:123:9)
    at async compileTsp (file:///home/swathip/.nvm/versions/node/v23.5.0/lib/node_modules/@azure-tools/typespec-client-generator-cli/dist/typespec.js:97:21)
    at async generateCommand (file:///home/swathip/.nvm/versions/node/v23.5.0/lib/node_modules/@azure-tools/typespec-client-generator-cli/dist/commands.js:248:35)

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[lmazuel]

Emitter should never ever show a stacktrace to customers, it just gives the feeling to customers that we don't control our code. At the same time, it's impossible to be perfect, and unexpected exceptions will happen.

Therefore, all emitters should have a "catch all" exceptions at the very beginning of the code, acknoledging that exceptions will happen, and in that case show a message like :

The emitter was unable to generate client code from this TypeSpec, please run this command again with --debug to get diagnostic information, and open an issue on https://github.com/Microsoft/typespec

The --debug in that case would show the debugging information, like the full stack trace, package version, NodeJS version, OS version, or anything we think could be useful for debugging. Ideally, there is a method in TCGC to gather all those common information, and emitters can specialize them as needed (for instance Java, could put the version of Java and MVN in the information)