fhir-openapi-translator 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-09-17
+
+Search parameters gain derived metadata and a way to emit fewer of them.
+
+No API or CLI breakage — every 0.1.1 invocation behaves as before. Generated
+output does change, though, so **a committed spec will show drift**: on an R4
+`Observation`, schemas and paths are byte-identical, 6 of 38 search parameters
+gain `x-fhir-search-values`/`x-fhir-search-prefixes` and a fuller description,
+and 4 more have trailing whitespace trimmed from HL7's description text.
+Regenerate committed specs, or `fhir-oas check` will fail in CI.
+
+### Added
+
+- `--search-params` limits which resource-specific search parameters are
+  emitted: a preset (`all`, `minimal`, `none`), an explicit code list
+  (`code,date,subject`), or per-resource (`Patient:name,birthdate`). Unknown
+  codes are an error rather than being silently dropped. Combines with
+  `--capability` by intersection. The common result parameters (`_id`,
+  `_count`, ...) are always emitted. `minimal` is tiered — common parameter
+  names first, then parameters addressing a top-level element directly, then
+  everything — so no resource that defines a search parameter is left with
+  none, while a median resource keeps 4. Presets can be tuned with `+code` and
+  `-code` (`minimal,+based-on`, `all,-note`), because no fixed rule can know
+  that `Observation.based-on`, `CarePlan.goal` or
+  `MedicationStatement.adherence` matter for their resource.
+- `fhir-oas --version` (and `-V`) prints the installed version. It is read from
+  `package.json` at runtime rather than inlined at build time, so the CLI
+  cannot report a version the package does not have.
+- `./package.json` is now a subpath export. Reaching for it previously raised
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`, which some bundlers and
+  version-introspection scripts trip over.
+- `x-fhir-search-values` on token search parameters bound to a required
+  ValueSet, and `x-fhir-search-prefixes` on `number`/`date`/`quantity`
+  parameters, listing the comparison prefixes (`eq`, `ne`, `gt`, `lt`, `ge`,
+  `le`, `sa`, `eb`, `ap`) their values may carry. Both are metadata rather than
+  schema constraints: an `enum` would reject the comma-OR, `system|code` and
+  `:modifier` forms that FHIR search permits.
+
+### Changed
+
+- Search parameter descriptions are now derived from the definitions rather
+  than passed through from HL7's prose, which is not uniform — `Encounter-status`
+  spelled its codes out while `Observation-status` did not, though both are
+  token parameters over a required binding. Every parameter of a given kind now
+  reads the same way, and reports the codes its own FHIR version defines.
+- Search parameters shared across resources carry a union expression
+  (`Patient.gender | Person.gender | ...`); the branch matching the resource
+  being generated is now resolved, so `MedicationRequest.status` and
+  `MedicationDispense.status` each report their own code list. Previously such
+  parameters were left unenumerated entirely.
+
 ## [0.1.1] - 2026-09-13
 
 Three correctness fixes. Specs generated with 0.1.0 should be regenerated:

package/README.md

@@ -50,6 +50,9 @@ fhir-oas generate Patient -f r4 --operations
 # Apply an Implementation Guide profile (e.g. US Core)
 fhir-oas generate Patient -f r4 --ig hl7.fhir.us.core@5.0.1 --profile us-core-patient
 
+# Emit only the search parameters your deployment indexes (38 -> 9 here)
+fhir-oas generate Observation -f r4 --search-params minimal,+based-on
+
 # Match one server's declared surface (reads its /metadata)
 fhir-oas generate -f r4 --capability https://server.example.org/fhir
 
@@ -76,16 +79,17 @@ const doc = generateOpenApi({ resources: ["Patient"], fhirVersion: "r4" });
 - **Custom operations** from the official OperationDefinitions.
 - **Profiles / IGs** — apply US Core-style constraints from any IG package.
 - **CapabilityStatement-driven** — generate exactly what a server supports.
+- **Search parameters, documented and tunable** — accepted codes and comparison prefixes per FHIR version; emit only the ones your deployment indexes.
 - **Merge mode & drift guard** — coexist with hand-written specs, catch drift in CI.
 
 ## Where it fits
 
-|  | fhir-openapi-translator | HAPI / Firely |
-|---|:---:|:---:|
-| Output | OpenAPI (→ any language) | Java / .NET models |
-| Runtime needed | none (offline CLI) | a running server / SDK |
-| US Core / IG profiles | ✅ | ✅ |
-| Per-resource, codegen-tuned specs | ✅ | — |
+|                                   | fhir-openapi-translator  |     HAPI / Firely      |
+| --------------------------------- | :----------------------: | :--------------------: |
+| Output                            | OpenAPI (→ any language) |   Java / .NET models   |
+| Runtime needed                    |    none (offline CLI)    | a running server / SDK |
+| US Core / IG profiles             |            ✅            |           ✅           |
+| Per-resource, codegen-tuned specs |            ✅            |           —            |
 
 **Complements a FHIR SDK, doesn't replace it.** Keep HAPI or Firely for server-side models and conformance — this produces the OpenAPI contract around them: for consumers in any language, and for the tooling you already run (gateways, mock servers, contract tests).
 

package/dist/{chunk-RR46JDST.js → chunk-RRAIF3A2.js}

@@ -496,6 +496,148 @@ function applyProfile(context, requested, registry) {
   return { schemaName, resourceType: profile.type, url: profile.url };
 }
 
+// src/searchParams.ts
+var SEARCH_PREFIXES = ["eq", "ne", "gt", "lt", "ge", "le", "sa", "eb", "ap"];
+var PREFIXABLE_TYPES = /* @__PURE__ */ new Set(["number", "date", "quantity"]);
+function prefixesFor(searchParamType) {
+  return PREFIXABLE_TYPES.has(searchParamType) ? SEARCH_PREFIXES : void 0;
+}
+function requiredBindingCodes(fhirVersion) {
+  const index = /* @__PURE__ */ new Map();
+  for (const sd of loadStructureDefinitions(fhirVersion)) {
+    for (const el of sd.elements) {
+      if (el.binding?.strength === "required" && el.binding.codes?.length) {
+        index.set(el.path, el.binding.codes);
+      }
+    }
+  }
+  return index;
+}
+var bindingCache = /* @__PURE__ */ new Map();
+function searchParamCodes(fhirVersion, resource, type, expression) {
+  if (type !== "token" || !expression) return void 0;
+  const branch = expression.split("|").map((part) => part.trim()).find((part) => part.startsWith(`${resource}.`) || !expression.includes("|"));
+  if (!branch || !/^[A-Za-z]+(?:\.[A-Za-z]+)+$/.test(branch)) return void 0;
+  if (branch.split(".")[0] !== resource) return void 0;
+  let index = bindingCache.get(fhirVersion);
+  if (!index) {
+    index = requiredBindingCodes(fhirVersion);
+    bindingCache.set(fhirVersion, index);
+  }
+  return index.get(branch);
+}
+var COMMON_CODES = /* @__PURE__ */ new Set([
+  "identifier",
+  "status",
+  "patient",
+  "subject",
+  "encounter",
+  "code",
+  "category",
+  "date",
+  "type",
+  "url",
+  "name"
+]);
+function directElementBranch(resource, expression) {
+  if (!expression) return void 0;
+  const branch = expression.split("|").map((part) => part.trim()).find((part) => part.startsWith(`${resource}.`));
+  return branch && /^[A-Za-z]+\.[A-Za-z]+$/.test(branch) ? branch : void 0;
+}
+function minimalCodes(resource, available) {
+  const common = available.filter((sp) => COMMON_CODES.has(sp.code));
+  if (common.length > 0) return new Set(common.map((sp) => sp.code));
+  const direct = available.filter((sp) => directElementBranch(resource, sp.expression));
+  if (direct.length > 0) return new Set(direct.map((sp) => sp.code));
+  return new Set(available.map((sp) => sp.code));
+}
+var PRESETS = /* @__PURE__ */ new Set(["all", "minimal", "none"]);
+function parseOne(value) {
+  const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
+  if (parts.length === 0) throw new Error(`--search-params: empty selection in "${value}"`);
+  const add = /* @__PURE__ */ new Set();
+  const remove = /* @__PURE__ */ new Set();
+  const literal = /* @__PURE__ */ new Set();
+  let preset;
+  for (const [index, part] of parts.entries()) {
+    if (part.startsWith("+") || part.startsWith("-")) {
+      const code = part.slice(1);
+      if (!code) throw new Error(`--search-params: "${part}" names no parameter`);
+      (part.startsWith("+") ? add : remove).add(code);
+      continue;
+    }
+    const lower = part.toLowerCase();
+    if (PRESETS.has(lower)) {
+      if (index !== 0) {
+        throw new Error(
+          `--search-params: preset "${part}" must come first in "${value}" (e.g. "minimal,+${parts[0]}").`
+        );
+      }
+      preset = lower;
+      continue;
+    }
+    literal.add(part);
+  }
+  if (preset && literal.size > 0) {
+    throw new Error(
+      `--search-params: "${value}" mixes the preset "${preset}" with bare codes ${[...literal].map((c) => `"${c}"`).join(", ")}. Prefix them with + to add to the preset, or drop the preset to list codes exactly.`
+    );
+  }
+  const rule = { base: preset ?? literal };
+  if (add.size > 0) rule.add = add;
+  if (remove.size > 0) rule.remove = remove;
+  return rule;
+}
+function parseSearchParamSpec(specs) {
+  const selection = {};
+  const byResource = /* @__PURE__ */ new Map();
+  for (const spec of specs) {
+    const colon = spec.indexOf(":");
+    if (colon > 0 && /^[A-Z][A-Za-z]*$/.test(spec.slice(0, colon))) {
+      const resource = spec.slice(0, colon);
+      if (byResource.has(resource)) {
+        throw new Error(`--search-params: ${resource} given more than once`);
+      }
+      byResource.set(resource, parseOne(spec.slice(colon + 1)));
+      continue;
+    }
+    if (selection.default !== void 0) {
+      throw new Error(
+        `--search-params: more than one unscoped selection ("${spec}"). Scope them per resource (Patient:name,birthdate) or pass a single list.`
+      );
+    }
+    selection.default = parseOne(spec);
+  }
+  if (byResource.size > 0) selection.byResource = byResource;
+  return selection;
+}
+function resolveSearchParamCodes(selection, fhirVersion, resource) {
+  const rule = selection?.byResource?.get(resource) ?? selection?.default;
+  if (rule === void 0) return void 0;
+  if (rule.base === "all" && !rule.add && !rule.remove) return void 0;
+  const available = loadSearchParameters(fhirVersion).filter((sp) => sp.base.includes(resource));
+  const codes = new Set(available.map((sp) => sp.code));
+  const named = [
+    ...typeof rule.base === "string" ? [] : rule.base,
+    ...rule.add ?? [],
+    ...rule.remove ?? []
+  ];
+  const unknown = named.filter((code) => !codes.has(code));
+  if (unknown.length > 0) {
+    throw new Error(
+      `--search-params: ${resource} has no search parameter ${unknown.map((c) => `"${c}"`).join(", ")} in ${fhirVersion.toUpperCase()}. Run "fhir-oas generate ${resource} -f ${fhirVersion}" to see the available codes.`
+    );
+  }
+  let selected;
+  if (rule.base === "all") selected = new Set(codes);
+  else if (rule.base === "none") selected = /* @__PURE__ */ new Set();
+  else if (rule.base === "minimal") selected = minimalCodes(resource, available);
+  else selected = new Set(rule.base);
+  for (const code of rule.add ?? []) selected.add(code);
+  for (const code of rule.remove ?? []) selected.delete(code);
+  return selected;
+}
+
 // src/backends/schemaJson.ts
 function buildRegistryFromSchemaJson(fhirVersion) {
   const schema = loadFhirSchema(fhirVersion);
@@ -920,16 +1062,41 @@ function commonSearchParameterComponents() {
   }
   return out;
 }
+function isCodeListDescription(description) {
+  return description.includes("|") && /^[A-Za-z0-9\-.\s|+]+$/.test(description);
+}
+function describeSearchParameter(description, codes, prefixes) {
+  let base = description.trim();
+  if (codes?.length && isCodeListDescription(base)) base = "";
+  const notes = [];
+  if (codes?.length) notes.push(`Accepted values: ${codes.join(" | ")}.`);
+  if (prefixes?.length) {
+    notes.push(`Values may carry a comparison prefix (${prefixes.join(", ")}), e.g. ge2021-01-01.`);
+  }
+  if (notes.length === 0) return base;
+  if (base.length === 0) return notes.join(" ");
+  const separator = base.includes("\n") ? "\n\n" : /[.?!]$/.test(base) ? " " : ". ";
+  return `${base}${separator}${notes.join(" ")}`;
+}
 function resourceSearchParameters(fhirVersion, resource, only) {
-  return loadSearchParameters(fhirVersion).filter((sp) => sp.base.includes(resource) && (!only || only.has(sp.code))).sort((a, b) => a.code.localeCompare(b.code)).map((sp) => ({
-    name: sp.code,
-    in: "query",
-    required: false,
-    description: sp.description,
-    // FHIR search values carry prefixes and modifiers, so all are strings.
-    schema: { type: "string" },
-    "x-fhir-search-type": sp.type
-  }));
+  return loadSearchParameters(fhirVersion).filter((sp) => sp.base.includes(resource) && (!only || only.has(sp.code))).sort((a, b) => a.code.localeCompare(b.code)).map((sp) => {
+    const codes = searchParamCodes(fhirVersion, resource, sp.type, sp.expression);
+    const prefixes = prefixesFor(sp.type);
+    return {
+      name: sp.code,
+      in: "query",
+      required: false,
+      description: describeSearchParameter(sp.description ?? "", codes, prefixes),
+      // FHIR search values carry prefixes and modifiers, so all are strings.
+      // The accepted values are advertised via x-fhir-search-values rather
+      // than `enum`, which would reject the comma-OR (`status=final,amended`),
+      // system|code and `:modifier` forms that FHIR search permits.
+      schema: { type: "string" },
+      "x-fhir-search-type": sp.type,
+      ...codes?.length ? { "x-fhir-search-values": codes } : {},
+      ...prefixes?.length ? { "x-fhir-search-prefixes": prefixes } : {}
+    };
+  });
 }
 var historyParameters = () => [
   { $ref: `${PARAMETERS}_count` },
@@ -1215,11 +1382,13 @@ function generateOpenApi(options) {
   const paths = {};
   for (const resource of resources) {
     const cap = capabilityByResource.get(resource);
+    const selected = resolveSearchParamCodes(options.searchParams, options.fhirVersion, resource);
+    const searchParamCodes2 = cap?.searchParamCodes && selected ? new Set([...selected].filter((code) => cap.searchParamCodes.has(code))) : selected ?? cap?.searchParamCodes;
     Object.assign(
       paths,
       buildResourcePaths(options.fhirVersion, resource, schemaFor(resource), {
         interactions: cap?.interactions,
-        searchParamCodes: cap?.searchParamCodes
+        searchParamCodes: searchParamCodes2
       })
     );
   }
@@ -1467,6 +1636,7 @@ export {
   loadIg,
   loadIgSync,
   buildCoreValueSetFallback,
+  parseSearchParamSpec,
   listResources,
   generateOpenApi,
   loadCapabilityStatement,
@@ -1476,4 +1646,4 @@ export {
   diffAgainstYaml,
   stringifyDocument
 };
-//# sourceMappingURL=chunk-RR46JDST.js.map
+//# sourceMappingURL=chunk-RRAIF3A2.js.map