fhir-resource-diff 0.2.0

package/dist/cli/index.js

@@ -0,0 +1,615 @@
+#!/usr/bin/env node
+import {
+  buildEnvelope,
+  detectFhirVersion,
+  diff,
+  formatJson,
+  formatMarkdown,
+  formatText,
+  formatValidationJson,
+  formatValidationText,
+  getResourceDocUrl,
+  getResourceInfo,
+  isSupportedFhirVersion,
+  listResourceTypes,
+  normalize,
+  parseJson,
+  resolveFhirVersion,
+  summarizeDiff,
+  validate
+} from "../chunk-2UUKQJDB.js";
+
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/cli/commands/compare.ts
+import pc from "picocolors";
+
+// src/presets/ignore-fields.ts
+var IGNORE_METADATA = {
+  name: "metadata",
+  description: "Ignore id, meta, and text fields \u2014 focus on clinical content",
+  paths: ["id", "meta", "text"]
+};
+var IGNORE_CLINICAL = {
+  name: "clinical",
+  description: "Ignore metadata and extensions \u2014 compare core clinical fields only",
+  paths: ["id", "meta", "text", "extension", "modifierExtension"]
+};
+var IGNORE_STRICT = {
+  name: "strict",
+  description: "Ignore nothing \u2014 compare all fields",
+  paths: []
+};
+
+// src/presets/normalization.ts
+var NORMALIZE_CANONICAL = {
+  name: "canonical",
+  description: "Sort keys, trim strings, normalize dates \u2014 maximally comparable form",
+  options: {
+    sortObjectKeys: true,
+    trimStrings: true,
+    normalizeDates: true
+  }
+};
+var NORMALIZE_NONE = {
+  name: "none",
+  description: "No normalization \u2014 compare exact values",
+  options: {}
+};
+
+// src/presets/index.ts
+var IGNORE_PRESETS = {
+  [IGNORE_METADATA.name]: IGNORE_METADATA,
+  [IGNORE_CLINICAL.name]: IGNORE_CLINICAL,
+  [IGNORE_STRICT.name]: IGNORE_STRICT
+};
+var NORMALIZATION_PRESETS = {
+  [NORMALIZE_CANONICAL.name]: NORMALIZE_CANONICAL,
+  [NORMALIZE_NONE.name]: NORMALIZE_NONE
+};
+function getIgnorePreset(name) {
+  return IGNORE_PRESETS[name];
+}
+function getNormalizationPreset(name) {
+  return NORMALIZATION_PRESETS[name];
+}
+function mergeIgnorePresets(...presets) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const preset of presets) {
+    for (const path of preset.paths) {
+      seen.add(path);
+    }
+  }
+  return Array.from(seen);
+}
+
+// src/cli/utils/read-file.ts
+import { readFileSync } from "fs";
+
+// src/cli/utils/read-stdin.ts
+function readStdinSync() {
+  if (process.stdin.isTTY) {
+    return Promise.reject(new Error("No input on stdin (stdin is a TTY)"));
+  }
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    process.stdin.on("error", reject);
+  });
+}
+
+// src/cli/utils/read-file.ts
+async function readFileOrExit(filePath) {
+  if (filePath === "-") {
+    try {
+      return await readStdinSync();
+    } catch {
+      process.stderr.write(
+        "Error: no input on stdin. Pipe data to stdin or provide a file path.\nUsage: cat resource.json | fhir-resource-diff validate -\n"
+      );
+      process.exit(2);
+    }
+  }
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch (e) {
+    process.stderr.write(
+      `Error: Cannot read file "${filePath}": ${e instanceof Error ? e.message : String(e)}
+`
+    );
+    process.exit(2);
+  }
+}
+
+// src/cli/utils/resolve-version.ts
+function parseVersionFlag(value) {
+  if (value === void 0) return void 0;
+  if (isSupportedFhirVersion(value)) return value;
+  process.stderr.write(
+    `Error: Unknown FHIR version "${value}". Supported: R4, R4B, R5
+`
+  );
+  process.exit(2);
+}
+
+// src/cli/commands/compare.ts
+var SECTION_HEADERS = /* @__PURE__ */ new Set(["Changed:", "Added:", "Removed:", "Type-changed:"]);
+function applyColor(text) {
+  const lines = text.split("\n");
+  let currentSection = null;
+  const colored = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (SECTION_HEADERS.has(trimmed)) {
+      currentSection = trimmed;
+      colored.push(pc.yellow(line));
+      continue;
+    }
+    if (trimmed === "") {
+      currentSection = null;
+      colored.push(line);
+      continue;
+    }
+    let processed = line;
+    if (line.includes(" \u2192 ")) {
+      processed = line.replace(
+        " \u2192 ",
+        ` ${pc.dim("\u2192")} `
+      );
+    }
+    if (currentSection === "Added:") {
+      colored.push(pc.green(processed));
+    } else if (currentSection === "Removed:") {
+      colored.push(pc.red(processed));
+    } else {
+      colored.push(processed);
+    }
+  }
+  return colored.join("\n");
+}
+function parseOrExit(filePath, raw) {
+  const result = parseJson(raw);
+  if (!result.success) {
+    process.stderr.write(`Error: "${filePath}" is not valid FHIR JSON: ${result.error}
+`);
+    process.exit(2);
+  }
+  return result.resource;
+}
+function registerCompareCommand(program2) {
+  program2.command("compare <file-a> <file-b>").description("Compare two FHIR JSON resource files and report differences").option(
+    "--format <fmt>",
+    'Output format: text | json | markdown (default: "text")',
+    "text"
+  ).option(
+    "--ignore <paths>",
+    "Comma-separated field paths to exclude from comparison"
+  ).option("--preset <name>", "Named ignore preset (e.g. metadata, clinical, strict)").option("--normalize <name>", "Named normalization preset to apply before diffing").option("--no-color", "Disable color output").option("--exit-on-diff", "Exit with code 1 if differences are found").option("--fhir-version <ver>", "FHIR version: R4 | R4B | R5 (default: auto-detect or R4)").option("--quiet", "Suppress all stdout output. Only exit code indicates result.").option("--envelope", "Wrap JSON output in a metadata envelope (requires --format json)").action(async (fileA, fileB, opts) => {
+    if (fileA === "-" && fileB === "-") {
+      process.stderr.write(
+        "Error: cannot read both resources from stdin. Provide at least one file path.\n"
+      );
+      process.exit(2);
+    }
+    const rawA = await readFileOrExit(fileA);
+    const rawB = await readFileOrExit(fileB);
+    let resourceA = parseOrExit(fileA, rawA);
+    let resourceB = parseOrExit(fileB, rawB);
+    const explicitVersion = parseVersionFlag(opts.fhirVersion);
+    const resolvedVersionA = resolveFhirVersion(explicitVersion, resourceA);
+    void resolveFhirVersion(explicitVersion, resourceB);
+    if (explicitVersion === void 0) {
+      const detectedA = detectFhirVersion(resourceA);
+      const detectedB = detectFhirVersion(resourceB);
+      if (detectedA !== void 0 && detectedB !== void 0 && detectedA !== detectedB) {
+        process.stderr.write(
+          `Warning: resources appear to be from different FHIR versions (${detectedA} vs ${detectedB})
+`
+        );
+      }
+    }
+    const validateVersion = explicitVersion !== void 0 ? resolvedVersionA : void 0;
+    const validA = validate(resourceA, validateVersion);
+    if (!validA.valid) {
+      process.stderr.write(`Warning: "${fileA}" has validation issues
+`);
+    }
+    const validB = validate(resourceB, validateVersion);
+    if (!validB.valid) {
+      process.stderr.write(`Warning: "${fileB}" has validation issues
+`);
+    }
+    if (opts.normalize !== void 0) {
+      const normPreset = getNormalizationPreset(opts.normalize);
+      if (normPreset === void 0) {
+        process.stderr.write(
+          `Error: Unknown normalization preset "${opts.normalize}". Available: canonical, none
+`
+        );
+        process.exit(2);
+      }
+      resourceA = normalize(resourceA, normPreset.options);
+      resourceB = normalize(resourceB, normPreset.options);
+    }
+    let ignorePaths = [];
+    if (opts.preset !== void 0) {
+      const namedPreset = getIgnorePreset(opts.preset);
+      if (namedPreset === void 0) {
+        process.stderr.write(
+          `Error: Unknown ignore preset "${opts.preset}". Available: metadata, clinical, strict
+`
+        );
+        process.exit(2);
+      }
+      ignorePaths = mergeIgnorePresets(namedPreset);
+    }
+    if (opts.ignore !== void 0 && opts.ignore.trim() !== "") {
+      const manualPaths = opts.ignore.split(",").map((p) => p.trim()).filter((p) => p !== "");
+      ignorePaths = Array.from(/* @__PURE__ */ new Set([...ignorePaths, ...manualPaths]));
+    }
+    const diffOptions = ignorePaths.length > 0 ? { ignorePaths } : {};
+    const result = diff(resourceA, resourceB, diffOptions);
+    let useEnvelope = opts.envelope;
+    if (useEnvelope && opts.format !== "json") {
+      process.stderr.write(
+        "Warning: --envelope requires --format json. Ignoring --envelope.\n"
+      );
+      useEnvelope = false;
+    }
+    const colorsEnabled = opts.color && process.env["NO_COLOR"] === void 0;
+    const format = opts.format;
+    let output;
+    if (format === "json") {
+      if (useEnvelope) {
+        const summary = summarizeDiff(result);
+        const documentation = getResourceDocUrl(result.resourceType, resolvedVersionA);
+        const envelopeResult = { ...result, summary, documentation };
+        const envelope = buildEnvelope("compare", resolvedVersionA, envelopeResult);
+        output = JSON.stringify(envelope, null, 2);
+      } else {
+        output = formatJson(result);
+      }
+    } else if (format === "markdown") {
+      output = formatMarkdown(result);
+    } else {
+      const textOutput = formatText(result);
+      output = colorsEnabled ? applyColor(textOutput) : textOutput;
+    }
+    if (!opts.quiet) {
+      process.stdout.write(output + "\n");
+    }
+    if (opts.exitOnDiff && !result.identical) {
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/commands/validate.ts
+function registerValidateCommand(program2) {
+  program2.command("validate <file>").description("Validate a FHIR JSON resource file").option(
+    "--format <fmt>",
+    'Output format: text | json (default: "text")',
+    "text"
+  ).option("--fhir-version <ver>", "FHIR version: R4 | R4B | R5 (default: auto-detect or R4)").option("--quiet", "Suppress all stdout output. Only exit code indicates result.").option("--envelope", "Wrap JSON output in a metadata envelope (requires --format json)").action(async (file, opts) => {
+    const raw = await readFileOrExit(file);
+    const parsed = parseJson(raw);
+    if (!parsed.success) {
+      process.stderr.write(`Error: "${file}" is not valid FHIR JSON: ${parsed.error}
+`);
+      process.exit(2);
+    }
+    const explicitVersion = parseVersionFlag(opts.fhirVersion);
+    const resolvedVersion = resolveFhirVersion(explicitVersion, parsed.resource);
+    const result = validate(parsed.resource, explicitVersion !== void 0 ? resolvedVersion : void 0);
+    let useEnvelope = opts.envelope;
+    if (useEnvelope && opts.format !== "json") {
+      process.stderr.write(
+        "Warning: --envelope requires --format json. Ignoring --envelope.\n"
+      );
+      useEnvelope = false;
+    }
+    const format = opts.format;
+    let output;
+    if (format === "json") {
+      if (useEnvelope) {
+        const documentation = getResourceDocUrl(parsed.resource.resourceType, resolvedVersion);
+        const envelopeResult = { ...result, documentation };
+        const envelope = buildEnvelope("validate", resolvedVersion, envelopeResult);
+        output = JSON.stringify(envelope, null, 2);
+      } else {
+        output = formatValidationJson(result);
+      }
+    } else {
+      output = formatValidationText(result);
+    }
+    if (!opts.quiet) {
+      process.stdout.write(output + "\n");
+    }
+    const hasErrors = result.valid === false && result.errors.some((e) => e.severity === "error");
+    process.exit(hasErrors ? 1 : 0);
+  });
+}
+
+// src/cli/commands/normalize.ts
+import { writeFileSync } from "fs";
+var DEFAULT_PRESET_NAME = "canonical";
+function registerNormalizeCommand(program2) {
+  program2.command("normalize <file>").description("Normalize a FHIR JSON resource file and output the result").option(
+    "--preset <name>",
+    `Named normalization preset (default: "${DEFAULT_PRESET_NAME}")`,
+    DEFAULT_PRESET_NAME
+  ).option("--output <path>", "Write output to a file instead of stdout").option("--fhir-version <ver>", "FHIR version: R4 | R4B | R5 (default: auto-detect or R4)").option("--quiet", "Suppress all stdout output.").action(async (file, opts) => {
+    const raw = await readFileOrExit(file);
+    const parsed = parseJson(raw);
+    if (!parsed.success) {
+      process.stderr.write(`Error: "${file}" is not valid FHIR JSON: ${parsed.error}
+`);
+      process.exit(2);
+    }
+    const explicitVersion = parseVersionFlag(opts.fhirVersion);
+    void resolveFhirVersion(explicitVersion, parsed.resource);
+    const presetName = opts.preset;
+    const preset = getNormalizationPreset(presetName);
+    if (preset === void 0) {
+      process.stderr.write(
+        `Error: Unknown normalization preset "${presetName}". Available: canonical, none
+`
+      );
+      process.exit(2);
+    }
+    const normalized = normalize(parsed.resource, preset.options);
+    const output = JSON.stringify(normalized, null, 2);
+    if (opts.output !== void 0) {
+      try {
+        writeFileSync(opts.output, output + "\n", "utf-8");
+      } catch (e) {
+        process.stderr.write(
+          `Error: Cannot write to "${opts.output}": ${e instanceof Error ? e.message : String(e)}
+`
+        );
+        process.exit(2);
+      }
+    } else if (!opts.quiet) {
+      process.stdout.write(output + "\n");
+    }
+  });
+}
+
+// src/cli/commands/info.ts
+function buildMaturityLabel(maturityLevel) {
+  if (maturityLevel === void 0) return "";
+  if (maturityLevel === "N") return " \u2014 Normative \u2605";
+  return ` \u2014 FMM ${maturityLevel}`;
+}
+function buildTextOutput(resourceType, fhirVersion) {
+  const info = getResourceInfo(resourceType);
+  if (!info) {
+    return [
+      `Unknown resource type: "${resourceType}"`,
+      "",
+      "Run 'fhir-resource-diff list-resources' to see known types.",
+      "Full resource list: https://hl7.org/fhir/resourcelist.html"
+    ].join("\n");
+  }
+  const versionsToShow = fhirVersion ? [fhirVersion] : info.versions;
+  const versionLine = fhirVersion ? `FHIR version: ${fhirVersion}` : `Available in: ${info.versions.join(" \xB7 ")}`;
+  const lines = [];
+  lines.push(`${info.resourceType} (${info.category})${buildMaturityLabel(info.maturityLevel)}`);
+  lines.push(versionLine);
+  lines.push("");
+  lines.push(info.description);
+  if (info.useCases && info.useCases.length > 0) {
+    lines.push("");
+    lines.push("Use cases:");
+    for (const useCase of info.useCases) {
+      lines.push(`  \u2022 ${useCase}`);
+    }
+  }
+  if (info.keyFields && info.keyFields.length > 0) {
+    lines.push("");
+    lines.push("Key fields:");
+    const nameColWidth = Math.max(...info.keyFields.map((f) => f.name.length + (f.required ? 2 : 0)));
+    for (const field of info.keyFields) {
+      const nameWithMarker = field.required ? `${field.name} *` : field.name;
+      const paddedName = nameWithMarker.padEnd(nameColWidth);
+      lines.push(`  ${paddedName}  ${field.note}`);
+    }
+  }
+  if (!fhirVersion && info.versionNotes) {
+    const r4ToR4b = info.versionNotes["R4\u2192R4B"];
+    const r4bToR5 = info.versionNotes["R4B\u2192R5"];
+    if (r4ToR4b !== void 0 || r4bToR5 !== void 0) {
+      lines.push("");
+      lines.push("Version notes:");
+      if (r4ToR4b !== void 0) {
+        lines.push(`  R4 \u2192 R4B  ${r4ToR4b}`);
+      }
+      if (r4bToR5 !== void 0) {
+        lines.push(`  R4B \u2192 R5  ${r4bToR5}`);
+      }
+    }
+  }
+  const docLines = versionsToShow.map((v) => {
+    const label = `${v}:`.padEnd(5);
+    return `  ${label} ${getResourceDocUrl(resourceType, v)}`;
+  });
+  lines.push("");
+  lines.push("Documentation:");
+  lines.push(...docLines);
+  return lines.join("\n");
+}
+function buildJsonOutput(resourceType, fhirVersion) {
+  const info = getResourceInfo(resourceType);
+  if (!info) {
+    return JSON.stringify(
+      {
+        error: "Unknown resource type",
+        resourceType,
+        help: "https://hl7.org/fhir/resourcelist.html"
+      },
+      null,
+      2
+    );
+  }
+  const versionsToShow = fhirVersion ? [fhirVersion] : info.versions;
+  const documentation = {};
+  for (const v of versionsToShow) {
+    documentation[v] = getResourceDocUrl(resourceType, v);
+  }
+  const output = {
+    resourceType: info.resourceType,
+    category: info.category,
+    versions: fhirVersion ? [fhirVersion] : [...info.versions],
+    description: info.description
+  };
+  if (info.maturityLevel !== void 0) {
+    output.maturityLevel = info.maturityLevel;
+  }
+  if (info.useCases !== void 0) {
+    output.useCases = [...info.useCases];
+  }
+  if (info.keyFields !== void 0) {
+    output.keyFields = info.keyFields.map((f) => ({ name: f.name, required: f.required, note: f.note }));
+  }
+  if (!fhirVersion && info.versionNotes !== void 0) {
+    output.versionNotes = { ...info.versionNotes };
+  }
+  output.documentation = documentation;
+  return JSON.stringify(output, null, 2);
+}
+function registerInfoCommand(program2) {
+  program2.command("info <resourceType>").description("Show metadata and HL7 documentation links for a FHIR resource type").option("--fhir-version <ver>", "Show docs link for a specific version only (R4 | R4B | R5)").option("--format <fmt>", "Output format: text | json", "text").action((resourceType, opts) => {
+    const fhirVersion = parseVersionFlag(opts.fhirVersion);
+    const format = opts.format ?? "text";
+    const isKnown = getResourceInfo(resourceType) !== void 0;
+    const exitCode = isKnown ? 0 : 2;
+    let output;
+    if (format === "json") {
+      output = buildJsonOutput(resourceType, fhirVersion);
+    } else {
+      output = buildTextOutput(resourceType, fhirVersion);
+    }
+    process.stdout.write(output + "\n");
+    process.exit(exitCode);
+  });
+}
+
+// src/cli/commands/list-resources.ts
+var VALID_CATEGORIES = [
+  "foundation",
+  "base",
+  "clinical",
+  "financial",
+  "specialized",
+  "conformance"
+];
+var CATEGORY_ORDER = [
+  "foundation",
+  "base",
+  "clinical",
+  "financial",
+  "specialized",
+  "conformance"
+];
+var HL7_RESOURCE_LIST_URL = "https://hl7.org/fhir/resourcelist.html";
+var RESOURCE_TYPE_COL_WIDTH = 24;
+function buildTitle(fhirVersion, category, total) {
+  const parts = [];
+  if (category) parts.push(category);
+  if (fhirVersion) parts.push(fhirVersion);
+  const qualifier = parts.length > 0 ? ` \u2014 ${parts.join(", ")}` : "";
+  return `FHIR Resource Types${qualifier} (${total} total)`;
+}
+function buildTextOutput2(resources, fhirVersion, category) {
+  if (resources.length === 0) {
+    return "No resource types match the given filters.";
+  }
+  const lines = [buildTitle(fhirVersion, category, resources.length), ""];
+  if (category) {
+    for (const r of resources) {
+      lines.push(`  ${r.resourceType.padEnd(RESOURCE_TYPE_COL_WIDTH)}${r.description}`);
+    }
+  } else {
+    for (const cat of CATEGORY_ORDER) {
+      const group = resources.filter((r) => r.category === cat);
+      if (group.length === 0) continue;
+      lines.push(cat);
+      for (const r of group) {
+        lines.push(`  ${r.resourceType.padEnd(RESOURCE_TYPE_COL_WIDTH)}${r.description}`);
+      }
+      lines.push("");
+    }
+  }
+  lines.push(`Full resource list: ${HL7_RESOURCE_LIST_URL}`);
+  return lines.join("\n");
+}
+function buildJsonOutput2(resources, fhirVersion, category) {
+  const filters = {};
+  if (fhirVersion) filters.fhirVersion = fhirVersion;
+  if (category) filters.category = category;
+  return JSON.stringify(
+    {
+      total: resources.length,
+      filters,
+      resources: resources.map((r) => ({
+        resourceType: r.resourceType,
+        category: r.category,
+        versions: [...r.versions],
+        description: r.description
+      }))
+    },
+    null,
+    2
+  );
+}
+function registerListResourcesCommand(program2) {
+  program2.command("list-resources").description(
+    "List known FHIR resource types, optionally filtered by version and category"
+  ).option(
+    "--fhir-version <ver>",
+    "Filter to resource types available in a specific version (R4 | R4B | R5)"
+  ).option(
+    "--category <cat>",
+    "Filter by category (foundation | base | clinical | financial | specialized | conformance)"
+  ).option("--format <fmt>", "Output format: text | json", "text").action(
+    (opts) => {
+      const fhirVersion = parseVersionFlag(opts.fhirVersion);
+      const format = opts.format ?? "text";
+      let category;
+      if (opts.category !== void 0) {
+        if (!VALID_CATEGORIES.includes(opts.category)) {
+          process.stderr.write(
+            `Error: Unknown category "${opts.category}". Available: ${VALID_CATEGORIES.join(", ")}
+`
+          );
+          process.exit(2);
+        }
+        category = opts.category;
+      }
+      const resources = listResourceTypes({
+        ...fhirVersion !== void 0 && { version: fhirVersion },
+        ...category !== void 0 && { category }
+      });
+      let output;
+      if (format === "json") {
+        output = buildJsonOutput2(resources, fhirVersion, category);
+      } else {
+        output = buildTextOutput2(resources, fhirVersion, category);
+      }
+      process.stdout.write(output + "\n");
+    }
+  );
+}
+
+// src/cli/index.ts
+var program = new Command();
+program.name("fhir-resource-diff").description("CLI for diffing and validating FHIR JSON resources").version("0.1.0");
+registerCompareCommand(program);
+registerValidateCommand(program);
+registerNormalizeCommand(program);
+registerInfoCommand(program);
+registerListResourcesCommand(program);
+program.parse();
+//# sourceMappingURL=index.js.map