RenameResourceWithAlias and RenameDataSource should support modern upstream docs structure

[guineveresaenger]

The update for pulumi/pulumi-mongodbatlas#536 fails tfgen with the message

error: failed to gather package metadata: problem gathering data sources: 1 error occurred:
	* could not find docs for data source 'mongodbatlas_x509_authentication_database_user' (aliased or renamed). Override the Docs property in the data source mapping. See type tfbridge.DocInfo for details.

But the upstream doc exists, and the renames section in bridge-metadata.json was deprecated. Edited to clarify: this was meant to say the bridge metadata's renames section does not affect docs discovery.

But then I looked at the release notes and noticed upstream migrated to new docs structure.

It turns out that we do not support the new docs formate when finding assigning the docs source for legacy docs.

So what happened with pulumi-mongodbatlas was the following:

1. Upstream renamed docs to end in .md
2. Data source mongodbatlas_x509_authentication_database_user had been renamed on our end (see entry in bridge-metadata.json)
3. Renames only look for docs sources ending in .html.markdown if docs source is nil
4. => Bridge cannot find docs for renamed resources that have docs ending in .md.

The workaround for the upgrade is to explicitly name the docs source. However, this means a manual entry in resources.go and it also means manual intervention in the upgrade itself. The bridge should handle both docs formats.

[t0yv0]

For my 2c, AFAIK "renames" section in bridge-metadata.json has no interaction with documentation processing. Ah I see, looks like this is an unintentional interaction you have found.. Indeed one would not expect that renaming a resource or datasource at Pulumi level should affect how the documentation files are sourced, but looks like it does. Interesting find.

[iwahbe]

Renaming generates a special *_legacy token in the provider, and we use tokens to understand where to find docs. We need to teach the bridge itself (not the upstream provider) about _legacy based renames or teach our docs mechanism to handle stripping _legacy tokens during docs lookup.

[pulumi-bot]

This issue has been addressed in PR #2229 and shipped in release v3.88.0.