Improve emitter documentation for handling version mutators in multi-version specs

[AllyW]

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 isgroupId here:

typespec-azure/packages/typespec-azure-resource-manager/lib/common-types/private-links.tsp

Lines 61 to 62 in 79f047c

	@added(Versions.v4)
	groupIds?: string[];

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

• Follow our Code of Conduct
• 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
• Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
• The provided reproduction is a minimal reproducible example of the bug.

[allenjzhang]

I tried with OpenAPI3 emitter and it correctly filtered out the groupId. Probably missed some processing logic in your emitter. Adding @chrisradek to take a look your emitter code.

Playground links:

V3
V5

[chrisradek]

I haven't been able to get the emitter to actually emit anything except an empty array following the instructions (I am using wsl if that matters), so can't dig too deeply.

Since the openapi3 emitter is handling this properly, I can point out where projections between the 2 emitters are handled differently.

In the openapi3 emitter, we get the projected service:

const document = await getOpenApiFromVersion(
  projectedServiceNs === projectedProgram.getGlobalNamespaceType()
    ? { type: projectedProgram.getGlobalNamespaceType() }
    : getService(program, projectedServiceNs)!,
  record.version,
);

https://github.com/microsoft/typespec/blob/f76f3182addf6c271e41087ee8fa3f8440af3bcb/packages/openapi3/src/openapi.ts#L505-L510

and then pass that service directly into getHttpService:

const httpService = ignoreDiagnostics(getHttpService(program, service.type));

https://github.com/microsoft/typespec/blob/f76f3182addf6c271e41087ee8fa3f8440af3bcb/packages/openapi3/src/openapi.ts#L632

In your emitter, it looks like you store the original service:

const aazContext: AAZEmitterContext = {
  program: projectedProgram,
  service: service,
  sdkContext: sdkContext,
  apiVersion: apiVersion,
  tracer,
};

https://github.com/Azure/aaz-dev-tools/blob/4de9f1448c931cc691b6edeecfb8ddfdce79c7fb/src/typespec-aaz/src/emit.ts#L115-L121

Though, that service isn't actually used. You do however call getAllHttpServices and grab the 1st one returned:

const services = ignoreDiagnostics(getAllHttpServices(context.program));

https://github.com/Azure/aaz-dev-tools/blob/4de9f1448c931cc691b6edeecfb8ddfdce79c7fb/src/typespec-aaz/src/emit.ts#L138

You are using the projectProgram when making that call, but I wonder if you'd have better results passing in the projected service directly.

Again - I'd give it a try but I can't get your repro steps to emit anything locally :-(

[AllyW]

Yes I was thinking maybe we didn't use the proper function for parsing models from commonTypes or missed the version somewhere. However, for inline model properties from target tsp file, the versioning part can be taken care of by the compiler by default, only commonTypes properties has this kind of versioning lost issue.

As @allenjzhang and @chrisradek mentioned, will try the one from openapi3 later.

[AllyW]

During my development period, there often occurs to me that, is there a dev doc or function specification that emitter developer can use when they try to fetch and parse different parts of different models.

[AllyW]

@chrisradek I tried the projected service and namespace as @typespec/openapi3 did (please check my branch in this draft pr AllyW/aaz-dev-tools#2), but typespec-aaz emitter still cannot fetch the v4 versioned property groupIds from Azure.ResourceManager.CommonTypes.Versions.v5.

However, I found, the problem may come from the different ways of declaration for Azure.ResourceManager.CommonTypes.Versions.v5.

If Azure.ResourceManager.CommonTypes.Versions.v5 is decleared outside api Versions enum, as a global one like mongocluster did now (https://github.com/Azure/azure-rest-api-specs/blob/main/specification/mongocluster/DocumentDB.MongoCluster.Management/main.tsp#L23), then, model from typespec/http cannot get the v4 versioned property groupIds correctly. However, if Azure.ResourceManager.CommonTypes.Versions.v5 is decleared inside each api Versions enum, like all the other resource providers, then, the property parsing can work as expected. (please refer to the example code change I made in this pr: https://github.com/AllyW/azure-rest-api-specs/pull/1/files)

@chrisradek any more suggestions on the model parsing or the tsp api definition pattern?