@the-cascade-protocol/cli 0.2.0

package/src/lib/fhir-converter/converters-demographics.ts

@@ -0,0 +1,270 @@
+/**
+ * FHIR -> Cascade converters for demographics and administrative types.
+ *
+ * Converts:
+ *   - Patient -> cascade:PatientProfile
+ *   - Immunization -> health:ImmunizationRecord
+ *   - Coverage -> coverage:InsurancePlan
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { Quad } from 'n3';
+
+import {
+  type ConversionResult,
+  NS,
+  extractCodings,
+  codeableConceptText,
+  tripleStr,
+  tripleInt,
+  tripleType,
+  tripleDateTime,
+  tripleDate,
+  commonTriples,
+  quadsToJsonLd,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Patient converter
+// ---------------------------------------------------------------------------
+
+export function convertPatient(resource: any): ConversionResult & { _quads: Quad[] } {
+  const warnings: string[] = [];
+  const subjectUri = `urn:uuid:${randomUUID()}`;
+  const quads: Quad[] = [];
+
+  quads.push(tripleType(subjectUri, NS.cascade + 'PatientProfile'));
+  quads.push(...commonTriples(subjectUri));
+
+  if (resource.birthDate) {
+    quads.push(tripleDate(subjectUri, NS.cascade + 'dateOfBirth', resource.birthDate));
+    const dob = new Date(resource.birthDate);
+    const now = new Date();
+    let age = now.getFullYear() - dob.getFullYear();
+    const monthDiff = now.getMonth() - dob.getMonth();
+    if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
+      age--;
+    }
+    quads.push(tripleInt(subjectUri, NS.cascade + 'computedAge', age));
+    let ageGroup: string;
+    if (age < 18) ageGroup = 'pediatric';
+    else if (age < 40) ageGroup = 'young_adult';
+    else if (age < 65) ageGroup = 'adult';
+    else ageGroup = 'senior';
+    quads.push(tripleStr(subjectUri, NS.cascade + 'ageGroup', ageGroup));
+  } else {
+    warnings.push('No birthDate found in Patient resource');
+  }
+
+  if (resource.gender) {
+    const genderMap: Record<string, string> = {
+      male: 'male', female: 'female', other: 'intersex', unknown: 'intersex',
+    };
+    quads.push(tripleStr(subjectUri, NS.cascade + 'biologicalSex', genderMap[resource.gender] ?? resource.gender));
+  }
+
+  if (Array.isArray(resource.address) && resource.address.length > 0) {
+    const addr = resource.address[0];
+    if (addr.city) quads.push(tripleStr(subjectUri, NS.cascade + 'addressCity', addr.city));
+    if (addr.state) quads.push(tripleStr(subjectUri, NS.cascade + 'addressState', addr.state));
+    if (addr.postalCode) quads.push(tripleStr(subjectUri, NS.cascade + 'addressPostalCode', addr.postalCode));
+    if (addr.country) quads.push(tripleStr(subjectUri, NS.cascade + 'addressCountry', addr.country));
+    if (Array.isArray(addr.line)) {
+      for (const line of addr.line) {
+        quads.push(tripleStr(subjectUri, NS.cascade + 'addressLine', line));
+      }
+    }
+    warnings.push('Patient address flattened onto profile (blank node structure simplified)');
+  }
+
+  if (resource.maritalStatus) {
+    const maritalText = codeableConceptText(resource.maritalStatus);
+    if (maritalText) {
+      const maritalMap: Record<string, string> = {
+        S: 'single', M: 'married', D: 'divorced', W: 'widowed',
+        A: 'separated', T: 'domestic_partnership', UNK: 'prefer_not_to_say',
+        'Never Married': 'single', 'Married': 'married', 'Divorced': 'divorced',
+        'Widowed': 'widowed', 'Separated': 'separated',
+      };
+      const code = resource.maritalStatus.coding?.[0]?.code;
+      const mapped = maritalMap[code] ?? maritalMap[maritalText] ?? maritalText.toLowerCase();
+      quads.push(tripleStr(subjectUri, NS.cascade + 'maritalStatus', mapped));
+    }
+  }
+
+  if (resource.id) {
+    quads.push(tripleStr(subjectUri, NS.cascade + 'profileId', resource.id));
+  }
+
+  return {
+    turtle: '',
+    jsonld: quadsToJsonLd(quads, 'cascade:PatientProfile'),
+    warnings,
+    resourceType: 'Patient',
+    cascadeType: 'cascade:PatientProfile',
+    _quads: quads,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Immunization converter
+// ---------------------------------------------------------------------------
+
+export function convertImmunization(resource: any): ConversionResult & { _quads: Quad[] } {
+  const warnings: string[] = [];
+  const subjectUri = `urn:uuid:${randomUUID()}`;
+  const quads: Quad[] = [];
+
+  quads.push(tripleType(subjectUri, NS.health + 'ImmunizationRecord'));
+  quads.push(...commonTriples(subjectUri));
+
+  const vaccineName = codeableConceptText(resource.vaccineCode) ?? 'Unknown Vaccine';
+  quads.push(tripleStr(subjectUri, NS.health + 'vaccineName', vaccineName));
+
+  if (resource.occurrenceDateTime) {
+    quads.push(tripleDateTime(subjectUri, NS.health + 'administrationDate', resource.occurrenceDateTime));
+  } else if (resource.occurrenceString) {
+    warnings.push(`Immunization date is a string: ${resource.occurrenceString}`);
+  }
+
+  quads.push(tripleStr(subjectUri, NS.health + 'status', resource.status ?? 'completed'));
+
+  const codings = extractCodings(resource.vaccineCode);
+  for (const c of codings) {
+    if (c.system === 'http://hl7.org/fhir/sid/cvx' || c.system === 'urn:oid:2.16.840.1.113883.12.292') {
+      quads.push(tripleStr(subjectUri, NS.health + 'vaccineCode', `CVX-${c.code}`));
+      break;
+    }
+  }
+
+  if (resource.manufacturer?.display) {
+    quads.push(tripleStr(subjectUri, NS.health + 'manufacturer', resource.manufacturer.display));
+  }
+
+  if (resource.lotNumber) {
+    quads.push(tripleStr(subjectUri, NS.health + 'lotNumber', resource.lotNumber));
+  }
+
+  if (resource.doseQuantity) {
+    const qty = `${resource.doseQuantity.value} ${resource.doseQuantity.unit ?? ''}`.trim();
+    quads.push(tripleStr(subjectUri, NS.health + 'doseQuantity', qty));
+  }
+
+  if (resource.route) {
+    const routeText = codeableConceptText(resource.route);
+    if (routeText) quads.push(tripleStr(subjectUri, NS.health + 'route', routeText));
+  }
+
+  if (resource.site) {
+    const siteText = codeableConceptText(resource.site);
+    if (siteText) quads.push(tripleStr(subjectUri, NS.health + 'site', siteText));
+  }
+
+  if (Array.isArray(resource.performer) && resource.performer.length > 0) {
+    const performer = resource.performer[0]?.actor?.display;
+    if (performer) quads.push(tripleStr(subjectUri, NS.health + 'administeringProvider', performer));
+  }
+
+  if (resource.location?.display) {
+    quads.push(tripleStr(subjectUri, NS.health + 'administeringLocation', resource.location.display));
+  }
+
+  if (resource.note && Array.isArray(resource.note)) {
+    const noteText = resource.note.map((n: any) => n.text).filter(Boolean).join('; ');
+    if (noteText) quads.push(tripleStr(subjectUri, NS.health + 'notes', noteText));
+  }
+
+  if (resource.id) {
+    quads.push(tripleStr(subjectUri, NS.health + 'sourceRecordId', resource.id));
+  }
+
+  return {
+    turtle: '',
+    jsonld: quadsToJsonLd(quads, 'health:ImmunizationRecord'),
+    warnings,
+    resourceType: 'Immunization',
+    cascadeType: 'health:ImmunizationRecord',
+    _quads: quads,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Coverage converter
+// ---------------------------------------------------------------------------
+
+export function convertCoverage(resource: any): ConversionResult & { _quads: Quad[] } {
+  const warnings: string[] = [];
+  const subjectUri = `urn:uuid:${randomUUID()}`;
+  const quads: Quad[] = [];
+
+  quads.push(tripleType(subjectUri, NS.coverage + 'InsurancePlan'));
+  quads.push(...commonTriples(subjectUri));
+
+  if (Array.isArray(resource.payor) && resource.payor.length > 0) {
+    const payorName = resource.payor[0]?.display ?? 'Unknown Insurance';
+    quads.push(tripleStr(subjectUri, NS.coverage + 'providerName', payorName));
+  } else {
+    quads.push(tripleStr(subjectUri, NS.coverage + 'providerName', 'Unknown Insurance'));
+    warnings.push('No payor information found in Coverage resource');
+  }
+
+  if (resource.subscriberId) {
+    quads.push(tripleStr(subjectUri, NS.coverage + 'memberId', resource.subscriberId));
+    quads.push(tripleStr(subjectUri, NS.coverage + 'subscriberId', resource.subscriberId));
+  } else if (resource.identifier && Array.isArray(resource.identifier) && resource.identifier.length > 0) {
+    const memberId = resource.identifier[0]?.value ?? '';
+    quads.push(tripleStr(subjectUri, NS.coverage + 'memberId', memberId));
+  } else {
+    warnings.push('No member/subscriber ID found in Coverage resource');
+  }
+
+  if (resource.type) {
+    const typeText = resource.type.coding?.[0]?.code ?? codeableConceptText(resource.type) ?? 'primary';
+    quads.push(tripleStr(subjectUri, NS.coverage + 'coverageType', typeText));
+  } else {
+    quads.push(tripleStr(subjectUri, NS.coverage + 'coverageType', 'primary'));
+  }
+
+  if (Array.isArray(resource.class)) {
+    for (const cls of resource.class) {
+      const clsType = cls.type?.coding?.[0]?.code ?? '';
+      if (clsType === 'group' && cls.value) {
+        quads.push(tripleStr(subjectUri, NS.coverage + 'groupNumber', cls.value));
+        if (cls.name) quads.push(tripleStr(subjectUri, NS.coverage + 'planName', cls.name));
+      } else if (clsType === 'plan' && cls.value) {
+        quads.push(tripleStr(subjectUri, NS.coverage + 'planName', cls.name ?? cls.value));
+      } else if (clsType === 'rxbin' && cls.value) {
+        quads.push(tripleStr(subjectUri, NS.coverage + 'rxBin', cls.value));
+      } else if (clsType === 'rxpcn' && cls.value) {
+        quads.push(tripleStr(subjectUri, NS.coverage + 'rxPcn', cls.value));
+      } else if (clsType === 'rxgroup' && cls.value) {
+        quads.push(tripleStr(subjectUri, NS.coverage + 'rxGroup', cls.value));
+      }
+    }
+  }
+
+  if (resource.relationship) {
+    const relCode = resource.relationship.coding?.[0]?.code ?? 'self';
+    quads.push(tripleStr(subjectUri, NS.coverage + 'subscriberRelationship', relCode));
+  }
+
+  if (resource.period?.start) {
+    quads.push(tripleDate(subjectUri, NS.coverage + 'effectiveStart', resource.period.start.substring(0, 10)));
+  }
+  if (resource.period?.end) {
+    quads.push(tripleDate(subjectUri, NS.coverage + 'effectiveEnd', resource.period.end.substring(0, 10)));
+  }
+
+  if (resource.id) {
+    quads.push(tripleStr(subjectUri, NS.health + 'sourceRecordId', resource.id));
+  }
+
+  return {
+    turtle: '',
+    jsonld: quadsToJsonLd(quads, 'coverage:InsurancePlan'),
+    warnings,
+    resourceType: 'Coverage',
+    cascadeType: 'coverage:InsurancePlan',
+    _quads: quads,
+  };
+}

package/src/lib/fhir-converter/fhir-to-cascade.ts

@@ -0,0 +1,82 @@
+/**
+ * FHIR -> Cascade dispatcher and public API.
+ *
+ * Routes FHIR resources to the appropriate per-type converter and
+ * provides the main public conversion functions.
+ *
+ * Individual converters are in:
+ *   - converters-clinical.ts     Medications, conditions, allergies, observations
+ *   - converters-demographics.ts Patient, immunization, coverage
+ */
+
+import type { Quad } from 'n3';
+
+import { type ConversionResult, quadsToTurtle } from './types.js';
+
+import {
+  convertMedicationStatement,
+  convertCondition,
+  convertAllergyIntolerance,
+  isVitalSignObservation,
+  convertObservationLab,
+  convertObservationVital,
+} from './converters-clinical.js';
+
+import {
+  convertPatient,
+  convertImmunization,
+  convertCoverage,
+} from './converters-demographics.js';
+
+// ---------------------------------------------------------------------------
+// Main dispatcher: single FHIR resource -> Cascade
+// ---------------------------------------------------------------------------
+
+export function convertFhirResourceToQuads(fhirResource: any): (ConversionResult & { _quads: Quad[] }) | null {
+  const resourceType = fhirResource?.resourceType as string | undefined;
+  if (!resourceType) return null;
+
+  switch (resourceType) {
+    case 'MedicationStatement':
+    case 'MedicationRequest':
+      return convertMedicationStatement(fhirResource);
+    case 'Condition':
+      return convertCondition(fhirResource);
+    case 'AllergyIntolerance':
+      return convertAllergyIntolerance(fhirResource);
+    case 'Observation':
+      if (isVitalSignObservation(fhirResource)) {
+        return convertObservationVital(fhirResource);
+      }
+      return convertObservationLab(fhirResource);
+    case 'Patient':
+      return convertPatient(fhirResource);
+    case 'Immunization':
+      return convertImmunization(fhirResource);
+    case 'Coverage':
+      return convertCoverage(fhirResource);
+    default:
+      return null;
+  }
+}
+
+export async function convertFhirToCascade(fhirResource: any): Promise<ConversionResult> {
+  const result = convertFhirResourceToQuads(fhirResource);
+  if (!result) {
+    return {
+      turtle: '',
+      warnings: [`Unsupported FHIR resource type: ${fhirResource?.resourceType ?? 'unknown'}`],
+      resourceType: fhirResource?.resourceType ?? 'unknown',
+      cascadeType: 'unknown',
+    };
+  }
+
+  const turtle = await quadsToTurtle(result._quads);
+  return {
+    turtle,
+    jsonld: result.jsonld,
+    warnings: result.warnings,
+    resourceType: result.resourceType,
+    cascadeType: result.cascadeType,
+  };
+}

package/src/lib/fhir-converter/index.ts

@@ -0,0 +1,215 @@
+/**
+ * FHIR conversion utilities.
+ *
+ * Converts between FHIR R4 JSON and Cascade Protocol RDF (Turtle/JSON-LD).
+ *
+ * Supported FHIR R4 resource types:
+ *   - MedicationStatement / MedicationRequest -> health:MedicationRecord
+ *   - Condition -> health:ConditionRecord
+ *   - AllergyIntolerance -> health:AllergyRecord
+ *   - Observation (lab) -> health:LabResultRecord
+ *   - Observation (vital) -> clinical:VitalSign
+ *   - Patient -> cascade:PatientProfile
+ *   - Immunization -> health:ImmunizationRecord
+ *   - Coverage -> coverage:InsurancePlan
+ *
+ * Zero network calls. All conversion is local.
+ *
+ * This module re-exports all public API for backward compatibility.
+ * Internal implementation is split across:
+ *   - types.ts         Shared types, namespaces, and quad helpers
+ *   - fhir-to-cascade.ts  FHIR -> Cascade converters
+ *   - cascade-to-fhir.ts  Cascade -> FHIR converters
+ */
+
+import type { Quad } from 'n3';
+
+import {
+  type InputFormat,
+  type OutputFormat,
+  type ConversionResult,
+  type BatchConversionResult,
+  SUPPORTED_TYPES,
+  quadsToTurtle,
+  quadsToJsonLd,
+} from './types.js';
+
+import { convertFhirResourceToQuads } from './fhir-to-cascade.js';
+import { convertCascadeToFhir } from './cascade-to-fhir.js';
+
+// Re-export public types
+export type { InputFormat, OutputFormat, ConversionResult, BatchConversionResult };
+
+// Re-export public functions from sub-modules
+export { convertFhirResourceToQuads, convertFhirToCascade } from './fhir-to-cascade.js';
+export { convertCascadeToFhir } from './cascade-to-fhir.js';
+
+// ---------------------------------------------------------------------------
+// Batch conversion (FHIR Bundle support)
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert an entire FHIR input (single resource or Bundle) to Cascade format.
+ */
+export async function convert(
+  input: string,
+  from: InputFormat,
+  to: OutputFormat,
+  outputSerialization: 'turtle' | 'jsonld' = 'turtle',
+): Promise<BatchConversionResult> {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+  const results: ConversionResult[] = [];
+
+  if (from === 'fhir' && (to === 'cascade' || to === 'turtle' || to === 'jsonld')) {
+    // FHIR -> Cascade
+    let parsed: any;
+    try {
+      parsed = JSON.parse(input);
+    } catch {
+      return {
+        success: false, output: '', format: to, resourceCount: 0,
+        warnings: [], errors: ['Invalid JSON input'], results: [],
+      };
+    }
+
+    // Collect resources from Bundle or single resource
+    const fhirResources: any[] = [];
+    if (parsed.resourceType === 'Bundle' && Array.isArray(parsed.entry)) {
+      for (const entry of parsed.entry) {
+        if (entry.resource) fhirResources.push(entry.resource);
+      }
+    } else if (parsed.resourceType) {
+      fhirResources.push(parsed);
+    } else {
+      return {
+        success: false, output: '', format: to, resourceCount: 0,
+        warnings: [], errors: ['Input does not appear to be a FHIR resource or Bundle'], results: [],
+      };
+    }
+
+    const allQuads: Quad[] = [];
+    for (const res of fhirResources) {
+      if (!SUPPORTED_TYPES.has(res.resourceType)) {
+        warnings.push(`Skipping unsupported FHIR resource type: ${res.resourceType}`);
+        continue;
+      }
+      const result = convertFhirResourceToQuads(res);
+      if (result) {
+        allQuads.push(...result._quads);
+        results.push({
+          turtle: '', // will be filled with combined output
+          jsonld: result.jsonld,
+          warnings: result.warnings,
+          resourceType: result.resourceType,
+          cascadeType: result.cascadeType,
+        });
+        warnings.push(...result.warnings);
+      }
+    }
+
+    if (allQuads.length === 0) {
+      return {
+        success: false, output: '', format: to, resourceCount: 0,
+        warnings, errors: ['No convertible FHIR resources found'], results: [],
+      };
+    }
+
+    // Determine output format
+    let output: string;
+    if (outputSerialization === 'jsonld' || to === 'jsonld') {
+      const jsonLd = quadsToJsonLd(allQuads, results[0]?.cascadeType ?? '');
+      output = JSON.stringify(jsonLd, null, 2);
+    } else {
+      output = await quadsToTurtle(allQuads);
+    }
+
+    return {
+      success: true,
+      output,
+      format: to === 'cascade' ? (outputSerialization === 'jsonld' ? 'jsonld' : 'turtle') : to,
+      resourceCount: results.length,
+      warnings,
+      errors,
+      results,
+    };
+  } else if (from === 'cascade' && to === 'fhir') {
+    // Cascade -> FHIR
+    const { resources, warnings: convWarnings } = await convertCascadeToFhir(input);
+    warnings.push(...convWarnings);
+
+    if (resources.length === 0) {
+      return {
+        success: false, output: '', format: 'fhir', resourceCount: 0,
+        warnings, errors: ['No resources converted from Cascade Turtle'], results: [],
+      };
+    }
+
+    const output = resources.length === 1
+      ? JSON.stringify(resources[0], null, 2)
+      : JSON.stringify({ resourceType: 'Bundle', type: 'collection', entry: resources.map(r => ({ resource: r })) }, null, 2);
+
+    return {
+      success: true,
+      output,
+      format: 'fhir',
+      resourceCount: resources.length,
+      warnings,
+      errors,
+      results: resources.map(r => ({
+        turtle: '',
+        warnings: [],
+        resourceType: r.resourceType,
+        cascadeType: 'fhir',
+      })),
+    };
+  } else if (from === 'c-cda') {
+    return {
+      success: false, output: '', format: to, resourceCount: 0,
+      warnings: [], errors: ['C-CDA conversion is not yet supported'], results: [],
+    };
+  } else {
+    return {
+      success: false, output: '', format: to, resourceCount: 0,
+      warnings: [], errors: [`Unsupported conversion: ${from} -> ${to}`], results: [],
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Format detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect the format of input data by inspecting its content.
+ */
+export function detectFormat(input: string): InputFormat | null {
+  const trimmed = input.trim();
+
+  // Check for FHIR JSON (has "resourceType")
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed.resourceType) return 'fhir';
+      if (parsed['@context'] || parsed['@type']) return 'cascade'; // JSON-LD
+    } catch {
+      // Not valid JSON
+    }
+  }
+
+  // Check for Turtle (has @prefix declarations or common Cascade namespace URIs)
+  if (
+    trimmed.includes('@prefix') ||
+    trimmed.includes('ns.cascadeprotocol.org') ||
+    /^<[^>]+>\s+a\s+/.test(trimmed)
+  ) {
+    return 'cascade';
+  }
+
+  // Check for C-CDA (XML with ClinicalDocument root)
+  if (trimmed.startsWith('<?xml') || trimmed.includes('<ClinicalDocument')) {
+    return 'c-cda';
+  }
+
+  return null;
+}