FHIR MapBuilder

FHIR MapBuilder is a Visual Studio Code extension designed to facilitate the edition of FHIR StructureMap resources using FHIR Mapping Language (FML).

• User documentation: what the extension does and how to use it, in the extension's README (the page shown on the marketplaces).
• Install: VS Code Marketplace or Open VSX.
• Developer documentation: this README, CONTRIBUTING.md and the architecture decisions under docs/adr/.

Reporting a vulnerability: SECURITY.md.

📂 Project Structure

This repository contains two interconnected projects:

1. vscode-extension – A Visual Studio Code (VS Code) extension written in TypeScript.
2. fhir-mapbuilder-validation – A Java Spring Boot REST API that provides backend validation.

The VS Code extension relies on the JAR file generated by the Spring Boot application.

fhir-mapbuilder/
│── vscode-extension/           # VS Code extension (TypeScript)
│   ├── src/
│   ├── package.json
│   ├── tsconfig.json
│   ├── ...
│   ├── target/                 # This is where the JAR file should be placed
│── fhir-mapbuilder-validation/ # Spring Boot REST API (Java)
│   ├── src/
│   ├── pom.xml
│   ├── ...
│── README.md

🛠 Setup & Installation

Clone the Repository

git clone https://github.com/aphp/fhir-mapbuilder.git
cd fhir-mapbuilder

Java 21 Requirement

This application requires Java Development Kit (JDK) version 21 to run. Please ensure that Java 21 is installed and correctly added to your system's PATH.

Build & Package the Java Application

cd fhir-mapbuilder-validation
mvn clean package

After running this command, the JAR file fhir-mapbuilder-validation.jar will be generated in the target/ folder.

Move the JAR File to the Extension Project

cd ..
mkdir -p vscode-extension/target
mv fhir-mapbuilder-validation/target/fhir-mapbuilder-validation.jar vscode-extension/target

Install Dependencies & Package the VS Code Extension

cd vscode-extension
npm ci
npx vsce package --baseImagesUrl=https://raw.githubusercontent.com/aphp/fhir-mapbuilder/refs/heads/main/vscode-extension

This command will generate a .vsix file, which can be installed in VS Code.

🚀 Running the Applications

Start the Java Spring Boot Application

cd fhir-mapbuilder-validation
mvn spring-boot:run

Run the VS Code Extension

1. Open vscode-extension in VS Code.
2. Press F5 to start a new Extension Development Host.

⚙️ GitHub Workflows

Five GitHub Actions workflows automate the project. Every workflow declares permissions: {} at the top and each job elevates to the minimum it needs; the design is recorded in docs/adr/.

Workflow	Trigger	What it does	ADR
ci.yml	PR, push to main, manual	Lint, format and type checks; the TypeScript and Java test suites with Codecov coverage (the ts and java components each gate at 90 %); an advisory OSV scan on PRs; a build job that packages the .vsix, smoke-tests the validation jar over GET /health and asserts the jar is bundled into the .vsix; an advisory os-smoke job that runs the same jar smoke test and the extension unit tests on Windows and macOS.	0002
commit-policy.yml	PR opened / edited / synchronized, manual	dco and commitlint check every non-merge commit (a DCO Signed-off-by trailer, a valid Conventional Commit); pr-title validates the PR title, which becomes the merge-commit subject. Also runs on pull_request_target, so PRs from forks are covered.	0001
dependency-review.yml	PR, manual	actions/dependency-review-action blocks a PR that introduces a high or critical vulnerability, or a dependency under a strong copyleft licence. The check is named dependency-review.	0002
audit.yml	Weekly cron, manual	OSV-Scanner run over pom.xml + package-lock.json; uploads the SARIF, so each vulnerability is a Code scanning alert that closes by itself once fixed. No issue is opened. A finding does not fail the job; only a scan that cannot run does.	0002
dependabot-auto-merge.yml	Dependabot PRs	Enables auto-merge for patch updates and for minor updates of direct dev-dependencies.	0002
release.yml	push to main, manual (publish_tag, dry_run)	release-please maintains a release PR from the commit history; merging it cuts the tag + GitHub Release, then build → publish-marketplace / publish-openvsx package and publish the .vsix to both registries, and a post-publish smoke job checks the new version surfaced on Open VSX. workflow_dispatch never publishes without a tag: with no publish_tag it is a package-only rehearsal on HEAD; with an existing publish_tag (vX.Y.Z) it rebuilds at that tag, checks the sources match it, and republishes only with dry_run: false. Every job has a timeout.	0003

📜 License

This project is licensed under the MIT License.