SUSHI (aka "SUSHI Unshortens Short Hand Inputs") is a reference implementation command-line interpreter/compiler for FHIR Shorthand (FSH).
FHIR Shorthand (FSH) is a specially-designed language for defining the content of FHIR Implementation Guides (IG). It is simple and compact, with tools to produce Fast Healthcare Interoperability Resources (FHIR) profiles, extensions and implementation guides (IG). Because it is a language, written in text statements, FHIR Shorthand encourages distributed, team-based development using conventional source code control tools such as GitHub.
For more information about the evolving FSH syntax see the FHIR Shorthand Reference Manual.
- Maintainers: This project is maintained by The MITRE Corporation.
- Issues / Discussion: For SUSHI issues, such as bug reports, comments, suggestions, questions, and feature requests, visit SUSHI GitHub Issues. For discussion of FHIR Shorthand and its associated projects, visit the FHIR Community Chat @ https://chat.fhir.org. The #shorthand stream is used for all FHIR Shorthand questions and discussion.
- License: All contributions to this project will be released under the Apache 2.0 License, and a copy of this license can be found in LICENSE.
- Contribution Policy: The SUSHI Contribution Policy can be found in CONTRIBUTING.md.
- Security Information: The SUSHI Security Information can be found in SECURITY.md.
- Compliance Information: SUSHI supports creating Implementation Guides for FHIR R4, FHIR R4B, and FHIR R5. While SUSHI performs basic validation to help users author FSH that will produce valid FHIR artifacts, it is not intended to be a full-featured validator. For example, SUSHI does validate paths and cardinalities, but does not validate author-provided FHIRPath expressions, terminological compliance, or slice membership. Authors are encouraged to use a full-featured validator, such as the one found in the IG Publisher, to test their final FHIR outputs. The SUSHI source code includes a comprehensive suite of unit tests to test SUSHI's own behavior and compliance with FHIR, which can be found in the test directory.
SUSHI requires Node.js to be installed on the user's system. Users should install Node.js 18. Although previous versions of Node.js may work, they are not officially supported.
Once Node.js is installed, run the following command to install or update SUSHI:
$ npm install -g fsh-sushiAfter installation, the sushi commandline will be available on your path:
$ sushi help
Usage: sushi [options] [command]
Options:
-v, --version print SUSHI version
-h, --help display help for command
Commands:
build [options] [path-to-fsh-project] build a SUSHI project
init [options] [name] initialize a SUSHI project
update-dependencies [options] [path-to-fsh-project] update FHIR packages in project configuration
help [command] display help for command
To build a SUSHI project, use the build command:
$ sushi build --help
Usage: sushi build [options] [path-to-fsh-project]
build a SUSHI project
Arguments:
path-to-fsh-project path to your FSH project (default: ".")
Options:
-l, --log-level <level> specify the level of log messages (default: "info") (choices: "error", "warn", "info", "debug")
-o, --out <out> the path to the output folder (default: "fsh-generated")
-p, --preprocessed output FSH produced by preprocessing steps
-r, --require-latest exit with error if this is not the latest version of SUSHI (default: false)
-s, --snapshot generate snapshot in Structure Definition output (default: false)
-c, --config <config> override elements in sushi-config.yaml (supported: 'version', 'status', 'releaselabel') (eg: --config status:draft)
-h, --help display help for command
See the SUSHI documentation for detailed information on using SUSHI.
SUSHI supports publishing implementation guides via the new template-based IG Publisher. The template-based publisher is still being developed by the FHIR community. See the Guidance for HL7 IG Creation for more details.
Based on the inputs in FSH files, sushi-config.yaml, and the IG project directory, SUSHI populates the output directory. See the documentation on IG Project with SUSHI for more information on using SUSHI to generate IGs.
SUSHI is a TypeScript project. At a minimum, SUSHI requires Node.js to build, test, and run the CLI. Developers should install Node.js 18.
Once Node.js is installed, run the following command from this project's root folder:
$ npm installThe following NPM tasks are useful in development:
| Task | Description |
|---|---|
| build | compiles src/**/*.ts files to dist/**/*.js files using the TypeScript compiler (tsc) |
| build:watch | similar to build but automatically builds when changes are detected in src files |
| build:grammar | builds the ANTLR grammar from 'antlr/src/main/antlr' to 'src/import/generated' |
| test | runs all unit tests using Jest |
| test:watch | similar to test, but automatically runs affected tests when changes are detected in src files |
| lint | checks all src files to ensure they follow project code styles and rules |
| lint:fix | fixes lint errors when automatic fixes are available for them |
| prettier | checks all src files to ensure they follow project formatting conventions |
| prettier:fix | fixes prettier errors by rewriting files using project formatting conventions |
| check | runs all the checks performed as part of ci (test, lint, prettier) |
| regression | runs regression against repositories found by FSHFinder |
| regression:last-year | runs regression against repositories found by FSHFinder updated in the last 365 days |
To run any of these tasks, use npm run. For example:
$ npm run checkThe regression/cli.ts script can be used to run regression on a set of repos. It's default command, run supports the following options:
Options:
-a, --a <version> Baseline version of SUSHI. Can be an NPM version number or tag, "gh:branch" to use a GitHub branch, or "local" to use the local code with
ts-node. (default: "gh:master")
-b, --b <version> Version of SUSHI under test. Can be an NPM version number or tag, "gh:branch" to use a GitHub branch, or "local" to use the local code with
ts-node. (default: "local")
-l, --lookback <days> The number of days to lookback in FSHFinder repositories (based on last updated date).
-c, --count <number> The maximum number of FSHFinder repositories to test (most recent first).
-r, --repo <repos...> One or more repos to test, each specified as a Github {org}/{repo}#{branch} (e.g., HL7/fhir-mCODE-ig#master). This option is not
compatible with the lookback, count, or file options.
-f, --file <file> A text file for which each line is a GitHub {org}/{repo}#{branch} to test (e.g., HL7/fhir-mCODE-ig#master). This is mostly used for legacy
purposes and is not compatible with the lookback, count, or repo arguments.
-o, --output <folder> The folder to write regression data to (default: "regression/output")
-h, --help display help for command
You can run it via ts-node:
$ ts-node regression/cli.ts run -a 3.0.0 -b local -c 50You can also run it via npm by adding -- followed by the arguments you wish to pass:
$ npm run regression -- -l 30 -c 50Another example specifying just two specific repositories to run regression on:
$ npm run regression -- --repo HL7/fhir-mCODE-ig#master HL7/davinci-crd#masterThe regression script first installs the -a and -b SUSHIs to temporary folders (except for local, in which case it runs npm install on the local SUSHI). Then for each of the relevant repositories, it does the following:
- Downloads the repo source from GitHub, creating two copies (for the base version of SUSHI and the version under test)
- Runs the base version of SUSHI against one copy of the repo
- Runs the version of SUSHI under test against the other copy of the repo
- Compares the results and generates a report of the differences
When the script is complete, it will generate and launch a top-level index file with links to the reports and logs for each repo.
For the best experience, developers should use Visual Studio Code with the following plugins:
- ESLint
- Prettier - Code formatter
- Consider configuring the formatOnSave feature in VS Code settings:
"[typescript]": { "editor.formatOnSave": true }
- Consider configuring the formatOnSave feature in VS Code settings:
- vscode-language-fsh
Copyright 2019-2022 Health Level Seven International
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.