Convert FSH to FHIR and back using right click context menu in the explorer view

[hvamstel]

Description:
Convert a JSON file to FSH by right click on the file in the explorer view and select the convert option.
Convert a FSH file to JSON by right click on the file in the explorer view and select the convert option.

Testing Instructions:
Right click on a file and convert and then inspect the result.

Related Issue:
Convert FSH to FHIR and back using right click context menu in the explorer view #96

[cmoesel]

@hvamstel - Thank you for the very cool PR. I am reviewing it now and will provide more feedback later. Regarding the broken CI check -- if you run npm run check locally, it will perform the same checks as CI. You'll see that it fails the prettier formatting check. We use prettier to ensure consistent style across the project. It's easy to fix your violations; just run npm run prettier:fix and check in the changes.

[hvamstel]

@cmoesel Thanks for looking into it. I did run
npm run prettier
But that didn't explain what needed to be changed and
npm run prettier --write
didn't seem to do anything.

Your suggestion of npm run prettier:fix works fine.

[cmoesel]

Hi @hvamstel. Thanks again for this contribution. It's a cool idea and I can see its usefulness. In my review of it, I did find a few limitations/questions I'd like to discuss:

1. When doing FSH to FHIR, the FSH file is processed by itself and any other FSH files in the project / IDE are ignored. So if the FSH file refers to something from another FSH file in the project, SUSHI won't find that definition and there will be errors. This means it only works for FSH files that are fully self-contained.
2. Similarly, when doing FHIR to FSH, the JSON file is processed by itself and any other JSON files in the project / IDE are ignored. This isn't as problematic as FSH to FHIR because in this case, it usually just creates aliases for the things it can't find. But it does mean the produced FSH might not be as good as it could be.
3. Setting FHIR version and dependencies at the extension level can be a bit confusing to users because other parts of the extension ignore those settings and pull this info from sushi-config.yaml instead. It might be cool if this worked the same way -- pulling FHIR version and dependencies from sushi-config.yaml or ImplementationGuide-xyz.json if it finds one. If it can't find one, I wonder if it might be better to prompt the user for that info instead? (Although, TBH, I'm not sure how easy that is to do in VS Code). Extension-level config is kind of hidden from the user and also seems a bit more global in nature.
4. You've added sushi and gofsh as dependencies, pinning them to specific versions. This means that if we want to use newer versions, we'll have to publish a new release of the extension just to bump the dependencies. For the already existing SUSHI Build action, we use the user's globally installed SUSHI rather than bundling one. Do you know if it's possible to use the globally installed NPM packages instead (like if you declared them as peerDependencies)? This would allow the user to decide what versions of SUSHI / GoFSH are used. (But I don't know if it is possible).
5. When FSH to FHIR is invoked, the entire JSON result is put on a single line -- it would be nice if we could automatically format the JSON so it's easier to read.
6. When either capability is invoked, it would be nice to give the new tab focus. I had a lot of tabs open and had to search for it.
7. I noticed the the resulting tabs are editors -- showing the results as active changes and prompting me to save them when I close the tab. I expected it to be more like when I preview a markdown document, showing a read-only view. Is that something you considered?

I'm interested in your thoughts about these.

[hvamstel]

Hi Chris,

My main goal was to quickly convert a single file locally. Specifically, I wanted to convert a FHIR resource to FSH to understand how FHIR is represented in FSH and to create a good starting point for our FSH-based resource. Another goal was to convert from FSH to FHIR to demonstrate the equivalence between the two, proving that moving from FHIR to FSH doesn't result in any semantic changes. This ensures that existing FHIR projects can be safely converted to FSH.

1+2) The method(s) that I found in the gofsh and sushi packages allowed only the conversion of a single stand-alone file as far as I could see. If there are other methods, then it would be nice to have the conversion in the context of the sushi project.

3. This approach seems promising. In our GIT repository, we have multiple Sushi projects, each in its own folder. To get the correct sushi-config, the FSH file to be converted should be in a subfolder of the folder containing the sushi-config. Are there any classes or methods in the plugin to find the sushi-config and its dependencies?

4. The packages gofsh and sushi need to be present otherwise the methods are unknown, and the compilation/interpretation will fail to build the extension. I do not believe it is possible to work around this.

5,6,7) Are good ideas and should be in currently :)

[cmoesel]

Hi Hans,

Thanks for the response and the updates! The implementation of 5, 6, and 7 came out very nicely. I really like the way that works now. I hope you do too!

As for 1, the SUSHI API takes in a string that can have any number of FSH definitions in it. So, in theory, you could concatenate all of the FSH files in the project into one big FSH string and send it through. But... you will get an array of all the JSONs back -- and the tricky bit would be figuring out which ones pertain to the original file you invoked "FSH to FHIR" on. Maybe we should update the return object in the API to also include something similar to the fsh-index.json that the SUSHI CLI generates. The other tricky bit would be how you want to handle multiple results -- which is actually a problem that the current implementation already has if the FSH file you select has multiple definitions in it. Should it create multiple preview tabs? Or one preview tab with an array of all the relevant JSON results?

I'm also realizing now that by adding all the files, the process could take a good bit longer to run - so that's a tradeoff to consider. I wonder if we could extend the SUSHI API to also add a mode where you specify a primary FSH file and have it only compile the things needed to complete that file. That could speed things up -- but... I'm not sure where that would fit in our priorities.

As for 2, the GoFSH API takes an array of JSONs as input -- so you could pass in all the JSONs found in the project. Similar to above, however, the tricky bit would be displaying only the FSH that is relevant to the JSON file originally selected. You might be able to figure it out using the map style option -- but it's still not trivial. We could potentially make it easier by adding another style that returns FSH files in an array matching the original order of the passed in JSONs (although even this might not be perfect since aliases get their own file and if there are contained resources, they might also get their own files... so we'd need to think about that). As I noted originally though, not passing in the full context for "FHIR to FSH" is much less of a problem than it is for "FSH to FHIR".

Regarding 3, here is the code we currently have for finding a sushi-config and grabbing its fhirVersion and dependencies. It just grabs the first one it finds, but you could look at the list of all the ones it finds in the workspace and figure out which one is the closest to the FSH file and use that. Current code starts here (click through to get to all the code):

vscode-fsh/src/FshCompletionProvider.ts

Line 358 in 9f17be9

const configFiles = await workspace.findFiles('sushi-config.{yaml,yml}');

Regarding 4, I was hoping it might work if you made fsh-sushi and gofsh peerDependencies, but I've just experimented with this myself and it looks like it doesn't really make a difference. The dependencies get compiled into the plugin anyway. So perhaps that is not possible.

[hvamstel]

Hi Chris

I noticed indeed that you can have multiple resources in one FSH file. Currently I open multiple previews with Json resource in each. This seems to work quite nicely with the caveat that it can be quite a lot of preview tabs when there are a lot of resources described in one FSH file.

I also rewrote the configuration part and now it will read from the sushi config. It will search for the sushi-config that is part of the same sushi project by matching the directory path. As there can be more than one sushi projects in the workspace as is in our situation. For this I reused some of the code that you mentioned and there are some refactoring opportunities.

Having the conversion in the context of the complete sushi project would be nice. The issue I see there is that concatenating all the resources together and retrieving the needed resources from the result can be complex and therefore error prone. Adopting the API of sushi and gofsh as you mentioned would help here.

Concatenating the FSH files will increase the time of the conversion having some kind of progress of activity indication could help. I was thinking of a panel in the status bar informing the user of a conversion in progress. Happy to know your thoughts and ideas on this.

[cmoesel]

I started to review this but noticed that some of the changes you referred to (regarding opening multiple tabs, extracting information from sushi-config, etc) are not pushed up to this PR. Did you mean to push them up? Or were you waiting for further discussion?

I agree that supporting FSH to FHIR JSON and FHIR to FSH w/ full context would be easiest with the API changes I described -- but I'm not sure if/when we will be able to implement those API changes. Perhaps we should ask the FSH community (on Zulip) if they would support us releasing this feature with the single-file-only limitation for now. What do you think?

[hvamstel]

Hi Chris,

Indeed, I forget to push to origin sorry for that.
I did fix the typos in the README.md and moved the feature description to the appropriate place.

I also managed to implement running the FSH to JSON conversion in the project context and only show the converted resources that where requested.

[cmoesel]

Wow, Hans. This is fantastic! I love it! I think people will really like this new feature!

I've provided some additional comments and suggestions, but they are mostly small and easy to do. Please let me know if you disagree with any of the suggestions I have made.

The one last thing I would like to ask you about is unit tests. As a general rule, we like to include unit tests for any new features that we introduce. This helps to ensure that as the extension evolves, we do not accidentally break anything. I know you have already invested a lot of time in this, but would you have a little more time to create a few basic unit tests to validate the core functionality? If not, then I will check to see if anyone here is able to add unit tests for you.

Thank you again for contributing this excellent feature!

[cmoesel]

@hvamstel This is looking very good! It looks like there are a few merge conflicts that need to be resolved, but we're getting very close! Thank you!

[cmoesel]

Thanks again, @hvamstel. I took this for one more round of testing and made a final request. I felt bad about asking for another change, so I basically implemented it for you (although I'm sure you could have done it just as well, if not better). If you like it, please integrate it and then I'll approve and ask one more team member to review it.

[cmoesel]

@hvamstel - Thank you again for this fantastic contribution! It looks great to me!

@mint-thompson - Could you provide a 2nd review before we merge this?

[mint-thompson]

Thank you for all of your work on this extension! The FSH to FHIR mostly worked fine for me, but I encountered a problem with FSH to FHIR. I've provided details in some additional comments.

[cmoesel]

This still looks good to me!

@mint-thompson - thank you for your review and feedback. I think this is ready for your re-review.

[hvamstel]

Can this pr be merged? I do not have the rights for that :)

[cmoesel]

Yes! I apologize. I meant to do it yesterday and somehow forgot. I will merge it now.

Thank you, @hvamstel, for this excellent PR. It's a really cool feature and I think people will love it!

[cmoesel]

@hvamstel - We've just published a new release of VS Code with your new feature! Thank you again!