Story: Go to Definition "source map" support for Container Registry modules

[johnnyreilly]

Is your feature request related to a problem? Please describe.

We've recently moved to using an internal container registry for our Bicep modules. It's really great. However, when you command+click / hit "Go to Definition" you are presented with ARM templates, rather than Bicep code.

ARM templates are less readable than Bicep. The code you see when you hit "Go to Definition", whilst being the built output of the module being consumed, it is not the beautifully readable Bicep.

Describe the solution you'd like

When a user hits "Go to Definition" they should see the original Bicep. A similar problem exists on the web, where people write in a language such as TypeScript. When debugging, you can still see the original code through use of a tool known as source maps that maps the compiled JavaScript back to the original source code:

https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map

I mention this as prior art which may be useful.

[alex-frankel]

Notes:

• Can potentially bundle bicep code with the JSON in the registry
• May not always want to include the bicep code -- i.e. may not want to include comments, etc.

[BernieWhite]

@alex-frankel It would be good if this was manifested as metadata (similar as resource descriptions) in the generated template as an extent or a separate map file.

For example:

{
    "type": "Microsoft.ContainerRegistry/registries",
    "apiVersion": "2021-06-01-preview",
    "name": "[parameters('registryName')]",
    "location": "[parameters('location')]",
    "sku": {
      "name": "Premium"
    },
    "identity": {
      "type": "SystemAssigned"
    },
    "properties": {
      "adminUserEnabled": false,
      "policies": {
        "quarantinePolicy": {
          "status": "enabled"
        },
        "trustPolicy": {
          "status": "enabled",
          "type": "Notary"
        },
        "retentionPolicy": {
          "status": "enabled",
          "days": 30
        }
      }
    },
    "metadata": {
      "description": "An example",
      "source": {
        "file": "./examples-acr.bicep",
        "startLine": 14,
        "endLine": 39
      }
    }
  }

[ucheNkadiCode]

Hey @johnnyreilly, I am having trouble understanding your use case on this. Where are you when you do the CMD Click (I assume this is the same as right click)-> Go to resource? Are you in VS code? Are you in the Resource group extension? Do you have a screenshot or gif that could tie this experience together of where you are and what is happening?

[johnnyreilly]

I'm in VS code yes. I don't have an image to hand right now, but the story goes something like this:

• in VS code, in a bicep file consuming a module from our private registry
• I want to look at the module contents, so I cmd+click on the module
• if it was a local module I'd be taken directly to the file.
• with our registry module, we don't see Bicep, we see the generated ARM template instead. The original Bicep would be easier to understand. At present, we're having to go and manually look up the source code that creates the private module to find out what the Bicep was. Would love to see the bicep just at the cmd+click

[StephenWeatherford]

Implementation

• Publish source: Add --with-source to publish command #12113
• Add parameter to publish source to az and az ps #11435
• BicepRegistryCacheRequestHandler?
• Publish source: Finish UI experience for viewing a single bicep source file from an external module #12131
• Publish source: Finish publishing of multiple source files #12132
• Remove mentions of experimental flag for module source publishing in Pwsh and Az #12811

[StephenWeatherford]

@johnnyreilly @BernieWhite In this scenario, where do you guys keep the source code? Is it in a location accessible to all end users so that if they press F12, will we be able to grab the source code from a location they have access to? Or do we need to store the sources directly in the ACR registry along with the module so all users with access to the ACR repository will be able to see the source code without further access issues? Thanks!

cc @puicchan @AbhitejJohn

[johnnyreilly]

I think storing the sources directly in the ACR registry is very much the more dependable option. In our case we presently have a shared Azure DevOps private repo where people (if they know how / have permission) can go and locate the source code. But given that it's a monorepo and the various quirks around publishing, I feel very strongly that storing the source code alongside the module is the safer bet.

You might find our organisation setup interesting in terms of feeding into how you design this. For instance we have modules that depend on shared modules etc.

I'd be happy to jump on a call and demo / talk through what we're doing to provide hopefully helpful input if you'd like

cc @rick-roche

[StephenWeatherford]

Experimental first implementation merged via #11896, under experimental feature flag "publishSource".

To publish a module with source, include this in a bicepconfig.json in the folder containing the module being published or in a parent folder:

  "experimentalFeaturesEnabled": {
    "publishSources": true
  },

Pressing F12 on a module reference to this published module should then display the (top-level-only) Bicep source file.