Merge branch 'master' into correct-format-reference

.github/pull_request_template.md

@@ -0,0 +1,5 @@
+**Description:**
+
+**Testing Instructions:**
+
+**Related Issue:**

.tool-versions

@@ -1 +1 @@
-nodejs 18.17.1
+nodejs 18.18.0

BEST-PRACTICES.md

@@ -0,0 +1,58 @@
+# Best Practices
+
+We're glad you're considering contributing to SUSHI! Below are a few best practices that we recommend for all contributions.
+
+## Before Contributing
+
+Before contributing a feature or a bugfix, we recommend creating a GitHub issue if one does not exist. This allows the community to provide feedback on why an issue may be occurring or provide additional insight into a suggested feature. See the [Contribution Policy](CONTRIBUTING.md#issues) to learn more about creating issues. It may also be useful, but is not required, to start a Zulip conversation around the feature or bug. See the [Contribution Policy](CONTRIBUTING.md#zulip) to learn more about Zulip.
+
+If a GitHub issue already exists for what you are planning to contribute, we recommend commenting on the issue to indicate that you are working on an implementation to avoid duplication of work.
+
+## Coding Practices
+
+We recommend the following coding practices for high quality contributions:
+
+- Make all changes in a personal [fork](https://help.github.com/articles/fork-a-repo/) of this repository.
+- Use descriptive commit messages.
+- Prefer self-explanatory code as much as possible, but provide helpful comments for complex expressions and code blocks.
+- Add unit tests for any new or changed functionality, and update any existing tests that are impacted by your changes.
+  - SUSHI uses [Jest](https://jestjs.io/) as a testing framework.
+  - To run the full test suite, run `npm test`.
+  - To review the test coverage report, run `npm run coverage` after running the full test suite.
+  - Ensure all tests are passing. Ensure that code coverage of the new code is complete.
+- Follow the code style and conventions as enforced by the lint configuration and as evidenced by the existing code.
+  - SUSHI uses [ESLint](https://eslint.org/) for code linting.
+  - To run the linter on all code, run `npm run lint`.
+  - To automatically fix as many issues as possible, run `npm run lint:fix`. This uses ESLint's [--fix](https://eslint.org/docs/latest/use/command-line-interface#fix-problems) option.
+  - Ensure there are no issues reported.
+- Follow the code formatting as enforced by the formatter configuration.
+  - SUSHI uses [Prettier](https://prettier.io/) for code formatting.
+  - To run Prettier on all code, run `npm run prettier`.
+  - To automatically rewrite files in order to resolve formatting issues, run `npm run prettier:fix`. This uses Prettier's [--write](https://prettier.io/docs/en/cli.html#--write) option.
+  - Ensure there are no issues reported.
+- Ensure any new dependencies use the latest published version.
+  - If a new dependency is required but the latest published version cannot be used, add the dependency and reason for not updating to [DEPENDENCY-NOTES.md](DEPENDENCY-NOTES.md).
+  - To check the latest published version, check the versions of the package on [npm](https://www.npmjs.com/) or use [npm-outdated](https://docs.npmjs.com/cli/v10/commands/npm-outdated). Run `npm outdated` and check that the new dependency is not listed in the output.
+- Ensure any new dependencies do not contain any known security vulnerabilities
+  - To check for known security vulnerabilities, we recommend using [npm-audit](https://docs.npmjs.com/cli/v10/commands/npm-audit). Run `npm audit` and ensure there are no new issues on your branch.
+- Update documentation to reflect any user-facing changes.
+  - Documentation updates may include, but are not limited to, the project [README](README.md) and [FSH School](https://fshschool.org/).
+  - If changes are required to FSH School, follow the instructions for contributing in the [project repository](https://github.com/FSHSchool/site).
+
+## Making a Pull Request
+
+We recommend the following best practices for creating a high quality pull request:
+
+- Review your own PR before marking it as ready for review by others. Ensure the only code changes included are ones relevant to the feature or bugfix and that they follow the coding practices outlined above.
+- Ensure your branch is up to date with master. There are a few ways you can update your branch:
+  - Use the "Update branch" button available once you make your PR. This is the recommended approach if you are not comfortable with merging or rebasing.
+  - [Merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) master into your branch.
+  - [Rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) your branch on master. We only recommend this approach if you are very comfortable with rebasing.
+- Update the title of the PR to provide a short, descriptive summary of the PR.
+  - Keep the title up to date with any changes made during the review process. The title will be used in the commit message and in the release notes, so it is important that it accurately reflects the current state of the PR.
+- Follow the pull request template to create a detailed PR description.
+  - Include a detailed description of the changes made in the PR.
+  - Include instructions for how to test the PR. You may want to include a link to sample FSH in FSH Online to demonstrate a bug or attach a sample project that highlights new or improved behavior.
+  - [Link the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) that the PR addresses.
+- Follow up on any discussion on your PR. If changes are requested, make any necessary updates and comment indicating your PR is ready for re-review.
+- If your PR is approved, it will be merged to master using the "[squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits)" strategy.

CODE-OF-CONDUCT.md

@@ -0,0 +1,7 @@
+# Contributor Code of Conduct
+
+The FHIR Shorthand team is committed to fostering a welcoming community.
+
+Our Code of Conduct can be found here:
+
+https://www.hl7.org/legal/code-of-conduct.cfm

CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing
+
+We're glad you're thinking about contributing to SUSHI! We welcome all friendly contributions, including:
+
+- bug reports
+- comments and suggestions
+- feature requests
+- bug fixes
+- feature implementations and enhancements
+- documentation updates and additions
+
+To ensure a welcoming environment, we follow the [HL7 Code of Conduct](https://www.hl7.org/legal/code-of-conduct.cfm) and expect contributors to do the same.
+
+Before making a contribution, please familiarize yourself with this document, as well as our [LICENSE](LICENSE) and [README](README.md).
+
+## Issues
+
+We use GitHub issues to track bug reports, comments, suggestions, questions, and feature requests. If you need help with using FHIR Shorthand or its tools, however, you may want to consider posting on Zulip first (see below). Questions posted on Zulip will reach a broader set of FSH users and will likely receive more timely responses. Requests for specific changes, however, should be submitted as GitHub issues so they can be formally tracked.
+
+Before submitting a new issue, please check to make sure a similar issue isn't already open. If one is, contribute to that issue thread with your feedback.
+
+When submitting a bug report, please try to provide as much detail as possible. This may include:
+
+- steps to reproduce the problem
+- screenshots demonstrating the problem
+- the full text of error messages
+- relevant outputs
+- any other information you deem relevant
+
+When creating or contributing to an issue, please include a link to any relevant discussion threads on Zulip (see below).
+
+Please note that the GitHub issue tracker is _public_; any issues you submit are immediately visible to everyone. For this reason, do _not_ submit any information that may be considered sensitive.
+
+## Zulip
+
+In addition to GitHub issues, we also use the FHIR Community Chat @ https://chat.fhir.org to discuss the use of FHIR Shorthand and its associated projects. The [#shorthand stream](https://chat.fhir.org/#narrow/stream/215610-shorthand) is used for all FHIR Shorthand questions and discussion.
+
+Before contributing to the discussion on the #shorthand stream, you will need to register for an account. The instructions to sign up can be found when you visit https://chat.fhir.org.
+
+Before starting a new conversation, please check for earlier discussions on a similar issue or topic. If a previous conversation has been started, contribute to that thread with your feedback.
+
+When starting a new conversation, please use a descriptive topic and include as much detail as possible.
+
+If you are looking for feedback or discussion around an issue, we recommend using Zulip. The FSH community is active on Zulip, and it is the best place to have in-depth discussions and ask questions about the FSH tooling. If the discussion on Zulip determines that a change is required in SUSHI, you should create a GitHub issue to track it. The GitHub issue should include a link to the relevant Zulip discussion thread, and it is best practice to provide a link to the GitHub issue on the Zulip thread. While Zulip is very useful for discussion, GitHub issues are the system of record for changes to SUSHI.
+
+## Code Contributions
+
+If you are planning to work on a reported bug, suggestion, or feature request, please comment on the relevant issue to indicate your intent to work on it.
+If there is no associated issue, please submit a new issue describing the feature you plan to implement or the bug you plan to fix.
+This reduces the likelihood of duplicated effort and also provides the maintainers an opportunity to ask questions, provide hints, or indicate any concerns _before_ you invest your time.
+
+### Coding Practices
+
+Code that is contributed to this project should be done in a personal fork of this repository and follow the coding practices specified in our Best Practices documentation in [BEST-PRACTICES.md](BEST-PRACTICES.md).
+
+### Before Submitting a Pull Request
+
+Before submitting a Pull Request for a code contribution:
+
+- [Merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) master into your branch or [rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) on master if your code is out of sync with master
+  - If you need help with this, submit your Pull Request without merging or rebasing and indicate you need help
+- Build the code (if applicable) and ensure there are no new warnings or errors
+- Run the tests with `npm test` and ensure that all tests pass
+- Run the linter with `npm run lint` and ensure that there are no linter warnings or errors
+- Run the Prettier formatter with `npm run prettier` and ensure that there are no formatting warnings or errors
+
+  _Note: `npm run check` will run the `test`, `lint`, and `prettier` scripts at once_
+
+- Ensure any new dependencies do not contain known security vulnerabilities.
+  - We recommend using `npm audit` to ensure there are no new security vulnerabilities introduced on your branch
+
+For details on how to build, test, lint, and format see the individual project README file.
+
+### Submitting a Pull Request
+
+Pull requests should include a summary of the work, as well as any specific guidance regarding how to test or invoke the code.
+
+When project maintainers review the pull request, they will:
+
+- Verify the contribution is compatible with the project's goals and mission
+- Run the project's unit tests, linters, and formatters to ensure there are no violations
+- Deploy the code locally to ensure it works as expected
+- Review all code changes in detail, looking for:
+  - potential bugs, regressions, security issues, or unintended consequences
+  - edge cases that may not be properly handled
+  - application of generally accepted best practices
+  - adequate unit tests and documentation
+
+### If the Pull Request Passes Review
+
+Congratulations! Your code will be merged by a maintainer into the project's master branch!
+
+### If the Pull Request Does Not Pass Review
+
+If the review process uncovers any issues or concerns, a maintainer will communicate them via a Pull Request comment. In most cases, the maintainer will also suggest changes that can be made to address those concerns and eventually have the Pull Request accepted. If this happens:
+
+- address any noted issues or concerns
+- rebase or merge master (if necessary) and push your code again (may require a force push if you rebased)
+- comment on the Pull Request indicating it is ready for another review
+
+## Apache 2.0
+
+All contributions to this project will be released under the [Apache 2.0 license](http://www.apache.org/licenses/LICENSE-2.0). By submitting a pull request, you are agreeing to comply with this license. As indicated by the license, you are also attesting that you are the copyright owner, or an individual or Legal Entity authorized to submit the contribution on behalf of the copyright owner.

DEPENDENCY-NOTES.md

@@ -1,8 +1,9 @@
-As of 2024 January 25:
+As of 2024 June 17:
 
 The `npm outdated` command reports some dependencies as outdated. They are not being updated at this time for the reasons given below:
 
 - `chalk`: major version 5 causes problems for jest. Keep updated to latest 4.x release.
+- `eslint`: version 8.57.0 is the newest version supported by `@typescript-eslint` packages. Update this package when the `@typescript-eslint` packages' support is updated.
 - `html-minifier-terser`: major version 6 changes the functions we use to become async, which would require changing more or less the entirety of SUSHI's export functions to async.
 - `junk`: major version 4 is an esmodule.
 - `title-case`: major version 4 is an esmodule.

README.md

@@ -5,10 +5,19 @@
 
 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.
+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](https://build.fhir.org/ig/HL7/fhir-shorthand/).
 
+## FHIR Foundation Project Statement
+
+* 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](https://github.com/FHIR/sushi/issues). For discussion of FHIR Shorthand and its associated projects, visit the FHIR Community Chat @ https://chat.fhir.org. The [#shorthand stream](https://chat.fhir.org/#narrow/stream/215610-shorthand) 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](LICENSE).
+* Contribution Policy: The SUSHI Contribution Policy can be found in [CONTRIBUTING.md](CONTRIBUTING.md).
+* Security Information: The SUSHI Security Information can be found in [SECURITY.md](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](test) directory.
+
 # Installation for SUSHI Users
 
 SUSHI requires [Node.js](https://nodejs.org/) 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.

SECURITY.md

@@ -0,0 +1,9 @@
+# Reporting security issues privately
+
+To report a security issue privately, please [create a security advisory](https://github.com/FHIR/sushi/security/advisories) in this repository. This will allow repository administrators to review and address it privately before public disclosure. For more details about this process, see ["Privately reporting a security vulnerability"](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability).
+
+# Project security practices
+
+SUSHI uses NPM for dependency management. Dependencies with security vulnerabilities as reported by NPM's audit tool should be updated to secure versions as soon as possible. A new version of SUSHI that resolves the vulnerabilities should be released as soon as possible afterwards. Pull requests that include new dependencies should not include dependencies that contain known security vulnerabilities.
+
+As part of reviewing pull requests, code changes will be examined for potential security issues. Security issues discovered during pull request review must be resolved before the pull request will be accepted.