Improve emitter documentation for handling version mutators in multi-version specs
- Dominant language
- TypeScript
- Stars
- 27
- Forks
- 90
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 164
Description
### Describe the bug
The target tsp is from MongoCluster: https://github.com/Azure/azure-rest-api-specs/blob/main/specification/mongocluster/DocumentDB.MongoCluster.Management/main.tsp#L23
When we try to access the properties from metadata of @typespec/http, we cannot find the property `groupId` added in v4, while this mongoCluster is using commonTypes.v5.
The lost property is`groupId` here: https://github.com/Azure/typespec-azure/blob/79f047c60e9e614d2217d0e519e10cbf6541f865/packages/typespec-azure-resource-manager/lib/common-types/private-links.tsp#L61-L62
### Reproduction
Our emitter is `typespec-aaz` here: https://github.com/Azure/aaz-dev-tools/tree/dev/src/typespec-aaz
Please clone the emitter above, link it to local npm env and then provide the tspconfig.yaml as following:

And then, run `tsp compile ${your_workspaceFolder}/specification/mongocluster/DocumentDB.MongoCluster.Management/main.tsp -- config yourconfig.yaml` and check the output file `./tsp-output/@azure-tools/typespec-aaz/resources_operations.json` .
we can check `properties` of `privateEndpointConnections` and you'll find `privateEndpoint`, `privateLinkServiceConnectionState` and other stuff, except `groupIds`.
Emitter code line for parsing properties of common types `PrivateEndpointConnectionProperties` is here: https://github.com/Azure/aaz-dev-tools/blob/dev/src/typespec-aaz/src/convertor.ts#L655. We use metadata from `@typespec/http` and check all its properties for our aaz model generation.
### Checklist
- [x] Follow our [Code of Conduct](https://github.com/azure/typespec-azure/blob/main/CODE_OF_CONDUCT.md)
- [x] Check that this issue is about the Azure libraries for typespec. For bug in the typespec language or core libraries file it in the [TypeSpec repo](https://github.com/Microsoft/TypeSpec/issues/new/choose)
- [x] Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
- [x] The provided reproduction is a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) of the bug.
Contributor guide
Research direction
Reproduce the issue with the MongoCluster main.tsp and the provided tspconfig.yaml, then inspect src/typespec-aaz/src/convertor.ts around line 655. Compare the metadata for PrivateEndpointConnectionProperties with private-links.tsp around lines 61-62 and the generated resources_operations.json. Done means the documentation clearly explains version mutators and the expected handling of groupIds in multi-version specs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- tooling
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100