Merge branch 'do-20260501-dependency-updates' into do-20260626-dependency-updates

Author: dotasek

.gitignore

@@ -243,4 +243,4 @@ shell-scripts/go-publish-fhir.txt
 
 .run/JUnit Validation.run.xml
 
-.run/
+.run/

README.md

@@ -154,7 +154,7 @@ Setup a launch.json file in the .vscode folder with the following content:
             "cwd": "c:/git/hl7/utg",
             "args": [
                 "-ig", ".",
-                "-tx", "http://tx.fhir.org/r4"
+                "-tx", "https://tx.fhir.org/r4"
             ]
         }
     ]

multi-version-IGs.md

@@ -0,0 +1,128 @@
+# Multi-version IGs
+
+## 1 Introduction
+
+An Implementation Guide is authored against a single primary FHIR version, but the
+IG Publisher can, in a single run, additionally emit **downgraded variant packages**
+for other FHIR versions so that implementers on those versions can consume the IG.
+
+This document describes emitting **R4 (4.0.1)** and **R4B (4.3.0)** consumable packages
+from an IG **authored in R5 (5.0.0)**. Existing R4↔R4B behaviour (see
+[the legacy path](#6-relationship-to-the-legacy-r4r4b-path)) is unchanged.
+
+The variant packages are produced by the semantic `generate-version` conversion path,
+which uses the shared version-conversion machinery (`ProfileVersionAdaptor` and the
+`VersionConvertorFactory_*` factories). No new element-level converters are involved -
+this is about enabling R5 as a source version, per-version wiring, configuration,
+analysis and reporting.
+
+## 2 Selecting the target versions
+
+Add one `generate-version` guidance parameter to the IG for each FHIR version you want
+a variant package for. For an R5 IG that should ship R4 and R4B:
+
+```json
+"parameter" : [
+  { "code" : "generate-version", "value" : "r4" },
+  { "code" : "generate-version", "value" : "r4b" }
+]
+```
+
+Each target produces an extra package `<packageId>.<token>.tgz` (e.g. `<id>.r4.tgz`,
+`<id>.r4b.tgz`) alongside the R5 `package.tgz`.
+
+### Version tokens
+
+Everywhere a FHIR version is named (the `generate-version` value, the per-version
+dependency extension, and the inclusion parameters) the token is matched by **version
+family**, so all of the following are accepted and collate to the same target:
+
+| Family | Accepted tokens                 | Recommended |
+|--------|---------------------------------|-------------|
+| R4     | `r4`, `4.0`, `4.0.1`            | `r4`        |
+| R4B    | `r4b`, `4.3`, `4.3.0`          | `r4b`       |
+| R5     | `r5`, `5.0.0`                  | `r5`        |
+
+Use `r4` / `r4b` as the `generate-version` tokens so the produced file names are
+`<id>.r4.tgz` / `<id>.r4b.tgz`.
+
+## 3 Per-version dependencies
+
+The dependencies a downgraded R4/R4B package needs are usually **not** a mechanical
+rename of the R5 dependencies - they frequently have different package ids and/or
+versions, and some dependencies only make sense for a particular FHIR version.
+
+Per-version dependencies are declared with a single repeating extension on each
+`ImplementationGuide.dependsOn` entry:
+
+`http://hl7.org/fhir/tools/StructureDefinition/ig-dependency-for-version`
+
+with these sub-extensions:
+
+| Part          | Card. | Type   | Meaning                                                    |
+|---------------|-------|--------|------------------------------------------------------------|
+| `fhirVersion` | 1..1  | code   | the target version this occurrence describes               |
+| `packageId`   | 0..1  | id     | override the dependency's package id for that version      |
+| `version`     | 0..1  | string | override the dependency's package version for that version |
+| `use`         | 0..1  | code   | `override` (default) or `remove`                           |
+
+Semantics for a given target version `V` (a `generate-version` target, or the base
+version for the R5 package itself):
+
+* **Override** - the entry has an occurrence for `V`: apply its `packageId`/`version`
+  overrides (a bare occurrence keeps the authored values).
+* **Remove** - the entry has an occurrence for `V` with `use = remove`: the entry is
+  absent from `V`.
+* **Add (version-specific)** - the entry has occurrences for some versions but **not**
+  `V`: the entry is absent from `V`. This is how a dependency that applies only to R4
+  is declared - author a normal `dependsOn` row and add one occurrence for `r4`; it is
+  then present only in the R4 package and absent from the R5 and R4B packages.
+* **Legacy** - the entry has **no** such extension: it applies to every version, and for
+  each variant the historical package-id suffix rename applies (`.r5` &rarr; `.r4`,
+  with R4B forced to `.r4` for wire-compatibility).
+
+The effective per-version dependencies drive each variant package's `dependsOn` and are
+surfaced in the rendered dependency table. A version-scoped entry is never loaded,
+validated, rendered, or packaged for a version it does not apply to.
+
+## 4 Per-version resource membership
+
+By default every resource is written into every generated package. To scope a resource
+to particular version(s), use the inclusion parameters:
+
+* `r4-inclusion` - value is a resource `Type/id` or canonical URL
+* `r4b-inclusion`
+* `r5-inclusion`
+
+These use **tag-membership** semantics:
+
+* A resource listed in **any** inclusion set appears **only** in the listed version(s).
+* A resource listed in **no** inclusion set appears in **all** versions (the default).
+
+`r5-inclusion` also gates the base R5 package, so a resource can be scoped away from R5
+entirely (e.g. an R4-only resource authored in R5). Membership governs *package*
+membership only; the R5 site rendering is unchanged.
+
+> The legacy `r4-exclusion` / `r4b-exclusion` parameters are unrelated to this feature -
+> they continue to drive the legacy R4↔R4B path only and are not consulted for an R5 base.
+
+## 5 Cross-version analysis
+
+For an R5 base with `generate-version`, a `cross-version-analysis` page reports, per
+target version:
+
+* conversion problems (from the `ProfileVersionAdaptor` conversion log for
+  StructureDefinition/SearchParameter, and from conversion success/failure for the other
+  conformance types and examples), and
+* resources intentionally omitted from that target via the inclusion parameters.
+
+A resource that uses an R5-only type that cannot be represented in R4/R4B yields a
+**warning** on this page (not a build failure); use the inclusion parameters to exclude
+it from the target(s) where it does not belong.
+
+## 6 Relationship to the legacy R4/R4B path
+
+An IG whose base version is **R4 or R4B** continues to use the original cross-version
+mechanism (`R4ToR4BAnalyser`), which re-parses the built package with the R4B parser and
+clones it into `.r4.tgz` / `.r4b.tgz`. That path is unchanged and is only entered for an
+R4/R4B base; an R5 base always uses the `generate-version` path described above.

org.hl7.fhir.publisher.cli/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>org.hl7.fhir.publisher</artifactId>
         <groupId>org.hl7.fhir.publisher</groupId>
-        <version>2.2.11-SNAPSHOT</version>
+        <version>2.2.12-SNAPSHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

org.hl7.fhir.publisher.core/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>org.hl7.fhir.publisher</groupId>
         <artifactId>org.hl7.fhir.publisher</artifactId>
-        <version>2.2.11-SNAPSHOT</version>
+        <version>2.2.12-SNAPSHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

org.hl7.fhir.publisher.core/src/main/java/org/hl7/fhir/igtools/publisher/CrossVersionAnalyser.java

@@ -0,0 +1,165 @@
+package org.hl7.fhir.igtools.publisher;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import org.hl7.fhir.convertors.misc.ProfileVersionAdaptor;
+import org.hl7.fhir.r5.context.IWorkerContext;
+import org.hl7.fhir.utilities.Utilities;
+import org.hl7.fhir.utilities.VersionUtilities;
+
+/**
+ * Produces the {@code cross-version-analysis} fragment for an <b>R5 base</b> that emits downgraded
+ * R4/R4B variant packages via {@code generate-version}. It is the R5-capable analogue of
+ * {@link R4ToR4BAnalyser} (which stays untouched for the legacy R4/R4B base): rather than checking
+ * wire-compatibility, it reports the actual per-target conversion outcomes observed while the variant
+ * packages are built - the {@link ProfileVersionAdaptor} {@code ConversionMessage} log for
+ * StructureDefinition/SearchParameter, and {@code convVersion} success/failure for every other type -
+ * plus resources intentionally omitted from a target version via the {@code *-inclusion} params.
+ * <p>
+ * All target versions are keyed by their family ({@code r4}/{@code r4b}/{@code r5} via
+ * {@link PublisherIGLoader#canonicalTarget}) so tokens like {@code 4.0}, {@code 4.0.1} and {@code r4}
+ * collate. Strings are English-only for now; i18n is deferred (the existing
+ * {@code RenderingI18nContext.R44B_*} phrases are R4/R4B-specific and live in org.hl7.fhir.core).
+ */
+public class CrossVersionAnalyser {
+
+  private IWorkerContext context;
+  private List<String> targets = new ArrayList<>();
+  private final Map<String, Map<String, List<String>>> problems = new LinkedHashMap<>();
+  private final Map<String, Set<String>> omissions = new LinkedHashMap<>();
+
+  public CrossVersionAnalyser() {
+    super();
+  }
+
+  public void setContext(IWorkerContext context) {
+    this.context = context;
+  }
+
+  /** The generate-version targets (raw tokens); used for iteration order and the "all clean" summary. */
+  public void setTargets(List<String> targets) {
+    if (targets != null) {
+      this.targets = new ArrayList<>(targets);
+    }
+  }
+
+  /** Record the {@link ProfileVersionAdaptor} conversion log for an SD/SP conversion to a target. */
+  public void record(String targetVer, String resourceKey, List<ProfileVersionAdaptor.ConversionMessage> log) {
+    if (log == null) {
+      return;
+    }
+    for (ProfileVersionAdaptor.ConversionMessage m : log) {
+      if (m.getStatus() != ProfileVersionAdaptor.ConversionMessageStatus.NOTE) {
+        addProblem(targetVer, resourceKey, m.getMessage());
+      }
+    }
+  }
+
+  /** Record a single conversion problem (e.g. a caught {@code convVersion} failure) for a target. */
+  public void recordProblem(String targetVer, String resourceKey, String message) {
+    addProblem(targetVer, resourceKey, message);
+  }
+
+  /** Record that a resource was intentionally omitted from a target version via {@code *-inclusion}. */
+  public void recordOmission(String targetVer, String resourceKey) {
+    omissions.computeIfAbsent(key(targetVer), k -> new LinkedHashSet<>()).add(resourceKey);
+  }
+
+  private void addProblem(String targetVer, String resourceKey, String message) {
+    if (message == null) {
+      return;
+    }
+    problems.computeIfAbsent(key(targetVer), k -> new LinkedHashMap<>())
+            .computeIfAbsent(resourceKey, k -> new ArrayList<>())
+            .add(message);
+  }
+
+  private static String key(String v) {
+    return PublisherIGLoader.canonicalTarget(v);
+  }
+
+  private static String name(String familyKey) {
+    return VersionUtilities.getNameForVersion(familyKey);
+  }
+
+  public boolean hasContent() {
+    return !problems.isEmpty() || !omissions.isEmpty();
+  }
+
+  /**
+   * The analysis fragment. {@code inline} yields a terse single-line variant; otherwise a block of
+   * {@code <p>}/{@code <ul>} per target version. An all-clean set of targets yields the "OK" summary
+   * (non-inline) or "" (inline); no targets at all yields "".
+   */
+  public String generate(String pid, boolean inline) {
+    LinkedHashSet<String> keys = new LinkedHashSet<>();
+    for (String t : targets) {
+      keys.add(key(t));
+    }
+    keys.addAll(problems.keySet());
+    keys.addAll(omissions.keySet());
+    if (keys.isEmpty()) {
+      return "";
+    }
+    StringBuilder b = new StringBuilder();
+    boolean any = false;
+    for (String k : keys) {
+      Map<String, List<String>> probs = problems.get(k);
+      Set<String> oms = omissions.get(k);
+      boolean hasProbs = probs != null && !probs.isEmpty();
+      boolean hasOms = oms != null && !oms.isEmpty();
+      if (!hasProbs && !hasOms) {
+        continue;
+      }
+      any = true;
+      String nm = name(k);
+      if (inline) {
+        List<String> parts = new ArrayList<>();
+        if (hasProbs) {
+          for (Map.Entry<String, List<String>> e : probs.entrySet()) {
+            parts.add(Utilities.escapeXml(e.getKey()) + " (" + Utilities.escapeXml(String.join("; ", e.getValue())) + ")");
+          }
+        }
+        if (hasOms) {
+          for (String o : oms) {
+            parts.add(Utilities.escapeXml(o) + " not included");
+          }
+        }
+        b.append("Conversion to " + nm + ": " + String.join(", ", parts) + ". ");
+      } else {
+        b.append("<p>Conversion to " + nm + ":</p>\r\n<ul>\r\n");
+        if (hasProbs) {
+          for (Map.Entry<String, List<String>> e : probs.entrySet()) {
+            b.append("<li>" + Utilities.escapeXml(e.getKey()) + ": " + Utilities.escapeXml(String.join("; ", e.getValue())) + "</li>\r\n");
+          }
+        }
+        if (hasOms) {
+          for (String o : oms) {
+            b.append("<li>" + Utilities.escapeXml(o) + " - intentionally not included in " + nm + "</li>\r\n");
+          }
+        }
+        b.append("</ul>\r\n");
+      }
+    }
+    if (!any) {
+      return inline ? "" : "<p>All resources convert cleanly to the generated version(s): " + versionList() + ".</p>\r\n";
+    }
+    return b.toString();
+  }
+
+  private String versionList() {
+    List<String> names = new ArrayList<>();
+    for (String t : targets) {
+      String n = name(key(t));
+      if (!names.contains(n)) {
+        names.add(n);
+      }
+    }
+    return String.join(", ", names);
+  }
+}

org.hl7.fhir.publisher.core/src/main/java/org/hl7/fhir/igtools/publisher/DependentIGFinder.java

@@ -17,6 +17,7 @@
 import org.hl7.fhir.utilities.FileUtilities;
 import org.hl7.fhir.utilities.Utilities;
 import org.hl7.fhir.utilities.VersionUtilities;
+import org.hl7.fhir.utilities.http.ManagedWebAccess;
 import org.hl7.fhir.utilities.json.model.JsonObject;
 import org.hl7.fhir.utilities.json.parser.JsonParser;
 import org.hl7.fhir.utilities.npm.FilesystemPackageCacheManager;
@@ -346,8 +347,10 @@ private void checkIGDependencies(JsonObject guide) {
 
     // we only check the latest published version, and the CI build
     try {
-      PackageList pl = PackageList.fromUrl(Utilities.pathURL(guide.asString("canonical"), "package-list.json"));
       String canonical = guide.asString("canonical");
+      final String secureCanonical = ManagedWebAccess.makeSecureRef(canonical);
+      PackageList pl = PackageList.fromUrl(Utilities.pathURL(secureCanonical, "package-list.json"));
+
       DepInfo dep = new DepInfo(pid, Utilities.path(canonical, "history.html"));
       deplist.add(dep);
       for (PackageListEntry e : pl.versions()) {

org.hl7.fhir.publisher.core/src/main/java/org/hl7/fhir/igtools/publisher/GitUtilities.java

@@ -6,6 +6,8 @@
 import java.io.InputStream;
 import java.io.InputStreamReader;
 import java.net.MalformedURLException;
+import java.net.URI;
+import java.net.URISyntaxException;
 import java.net.URL;
 
 public class GitUtilities {
@@ -76,16 +78,16 @@ public static String getGitSource(File gitDir) {
 	 */
 	protected static String getURLWithNoUserInfo(final String url, final String urlSource) {
 		try {
-			URL newUrl = new URL(url);
+			URL newUrl = URI.create(url).toURL();
             if (newUrl.getUserInfo() != null) {
 				System.out.println("Info @ Removing user info from GIT URL. Source: " + urlSource);
-				return new URL(newUrl.getProtocol(), newUrl.getHost(), newUrl.getPort(), newUrl.getFile()).toString();
+				return new URI(newUrl.getProtocol(), null, newUrl.getHost(), newUrl.getPort(), newUrl.getPath(), newUrl.getQuery(), null).toURL().toString();
 			}
 			return url;
-		} catch (MalformedURLException e) {
+		} catch (MalformedURLException | URISyntaxException | IllegalArgumentException e ) {
 			System.out.println("Warning @ Git URL is not a valid URl. Source: " + urlSource);
 			return null;
 		}
-	}
+    }
 
 }