@fhiron/sdk 0.1.0

package/src/_linter/rules.js

@@ -0,0 +1,1196 @@
+// Fhiron linter — reglas locales contra CL Core v1.9.4.
+//
+// Diseño: módulo plano en CommonJS, sin dependencias. Corre en tres lugares:
+//   - Web Worker del dashboard (import nativo vía ES module interop de turbopack)
+//   - MCP connector (require directo)
+//   - Servidor (/api/validate enriquece la respuesta HAPI con estas reglas)
+//
+// División de trabajo con HAPI:
+//   - Local: "ortografía" — formato de RUN, presencia de campos obligatorios,
+//     system de identifier correcto, puntos en RUT, etc. Barato, instantáneo.
+//   - HAPI:  "gramática profunda" — slicing, discriminators, binding a
+//     ValueSets, expresiones FHIRPath. Caro, una ronda al servidor.
+//
+// Cada regla devuelve { code, severity, path, message, quickFix? }. Los
+// códigos siguen el patrón cl-<recurso>-NN para que la IA los reconozca sin
+// tener que parsear prosa en español.
+
+"use strict";
+
+const { isKnownResourceType } = require("./resources.js");
+const { lookupCode, listCodes } = require("./catalog.js");
+
+// ── Enriquecimiento pedagógico ───────────────────────────────────────────────
+//
+// Cada issue emitido por las reglas internas trae al menos {code, severity,
+// path, message}. enrichIssue() consulta el catálogo y agrega los campos
+// pedagógicos opcionales: why, profileUrl, docsUrl, suggestion, example.
+//
+// Si el código no está catalogado, devuelve el issue intacto — esto preserva
+// la retrocompatibilidad para integraciones que añaden códigos custom.
+
+function enrichIssue(issue) {
+  if (!issue || !issue.code) return issue;
+  const meta = lookupCode(issue.code);
+  if (!meta) return issue;
+  // No sobreescribir campos ya presentes (las reglas pueden customizar).
+  if (meta.why && !issue.why) issue.why = meta.why;
+  if (meta.profileUrl && !issue.profileUrl) issue.profileUrl = meta.profileUrl;
+  if (meta.docsUrl && !issue.docsUrl) issue.docsUrl = meta.docsUrl;
+  if (meta.suggestion && !issue.suggestion) issue.suggestion = meta.suggestion;
+  if (meta.example !== undefined && issue.example === undefined) issue.example = meta.example;
+  return issue;
+}
+
+// ── Validación de RUN (módulo 11) ────────────────────────────────────────────
+//
+// Cómo se identifica el slot RUN en un Patient.identifier según CL Core 1.9.4:
+//
+//   1. identifier.system = "http://www.registrocivil.cl/run"
+//      (NamingSystem oficial del Registro Civil — uso primario en CL Core)
+//   2. identifier.type.coding[].system = CSTipoIdentificador
+//      identifier.type.coding[].code = "01" (RUN)
+//      (Tipificación canónica del IG)
+//   3. URLs legacy aún en uso por algunas integraciones:
+//      - "https://hl7chile.cl/identificador/run" (CL Core <1.7)
+//      - "https://hl7chile.cl/fhir/ig/clcore/CodeSystem/CSIdentificadores"
+//        (URL inventada por Fhiron en sesión 3-May-2026, ya purgada — se
+//        deja en el detector solo como fallback para clientes que aún la
+//        emiten antes de actualizarse)
+//
+// Cualquiera de estas tres formas cuenta como "este identifier es un RUN".
+
+const RUN_SYSTEM_REGCIVIL = "http://www.registrocivil.cl/run";
+const RUN_SYSTEM_CL_CORE_TIPO = "https://hl7chile.cl/fhir/ig/clcore/CodeSystem/CSTipoIdentificador";
+const RUN_SYSTEM_LEGACY_PRE17 = "https://hl7chile.cl/identificador/run";
+const RUN_SYSTEM_LEGACY_FHIRON_INVENT = "https://hl7chile.cl/fhir/ig/clcore/CodeSystem/CSIdentificadores";
+const RUN_SYSTEMS = [
+  RUN_SYSTEM_REGCIVIL,
+  RUN_SYSTEM_LEGACY_PRE17,
+  RUN_SYSTEM_LEGACY_FHIRON_INVENT,
+];
+const RUN_TYPE_CODE = "01"; // CSTipoIdentificador#01
+
+function stripRunDots(value) {
+  return typeof value === "string" ? value.replace(/\./g, "") : value;
+}
+
+/** Reconoce el system del identifier directamente. */
+function isRunSystem(system) {
+  if (!system) return false;
+  return RUN_SYSTEMS.some((s) => system === s || system === s.replace("https:", "http:") || system === s.replace("http:", "https:"));
+}
+
+/**
+ * Reconoce un identifier como RUN considerando cualquiera de las formas
+ * canónicas: system del identifier, type.coding con CSTipoIdentificador#01,
+ * o URLs legacy aún en uso.
+ */
+function isRunIdentifier(id) {
+  if (!id || typeof id !== "object") return false;
+  if (isRunSystem(id.system)) return true;
+  // type.coding con CSTipoIdentificador + code "01"
+  const codings = (id.type && Array.isArray(id.type.coding)) ? id.type.coding : [];
+  for (const c of codings) {
+    if (!c) continue;
+    const sys = c.system || "";
+    const code = c.code;
+    if (sys === RUN_SYSTEM_CL_CORE_TIPO && (code === RUN_TYPE_CODE || code === "RUN")) return true;
+    // legacy: code === "RUN" sin system específico
+    if (code === "RUN") return true;
+  }
+  return false;
+}
+
+function hasRunDots(value) {
+  return typeof value === "string" && value.includes(".");
+}
+
+// ── Mensajes de error de JSON en español ─────────────────────────────────────
+
+const V8_ERROR_TRANSLATIONS = [
+  [/Expected property name or '}' in JSON at position (\d+)/i,
+    (m) => `Se esperaba un nombre de propiedad o '}' en la posición ${m[1]}`],
+  [/Unexpected token '(.+)', "(.+)" is not valid JSON/i,
+    (m) => `Token inesperado '${m[1]}' — el texto "${m[2]}" no es JSON válido`],
+  [/Unexpected end of JSON input/i,
+    () => "El JSON está incompleto (fin inesperado)"],
+  [/Unexpected token (\S+) in JSON at position (\d+)/i,
+    (m) => `Token inesperado ${m[1]} en la posición ${m[2]}`],
+  [/Expected ',' or '\}' after property value in JSON at position (\d+)/i,
+    (m) => `Se esperaba ',' o '}' tras el valor de la propiedad en la posición ${m[1]}`],
+  [/circular structure/i,
+    () => "El objeto tiene referencias circulares y no puede serializarse como JSON"],
+];
+
+function translateJsonParseError(err) {
+  const msg = err && err.message ? err.message : "no se pudo parsear";
+  for (const [pattern, builder] of V8_ERROR_TRANSLATIONS) {
+    const m = msg.match(pattern);
+    if (m) return builder(m);
+  }
+  return msg;
+}
+
+// ── Clasificación de formato de RUN ─────────────────────────────────────────
+// Devuelve { valid, message, cleaned } antes del cálculo del DV.
+// Permite emitir mensajes específicos según la causa del formato inválido.
+
+function classifyRunFormat(raw) {
+  if (typeof raw !== "string" || !raw.trim()) {
+    return { valid: false, message: "El RUN está vacío.", cleaned: null };
+  }
+  const noSpaces = raw.replace(/\s/g, "").toUpperCase();
+  const noDots = noSpaces.replace(/\./g, "");
+
+  if (!noDots.includes("-")) {
+    return {
+      valid: false,
+      message: "Falta el guión entre el cuerpo y el dígito verificador. Formato esperado: 12345678-5.",
+      cleaned: null,
+    };
+  }
+
+  const dashIdx = noDots.lastIndexOf("-");
+  const body = noDots.slice(0, dashIdx);
+  const dv = noDots.slice(dashIdx + 1);
+
+  if (!/^\d+$/.test(body)) {
+    return {
+      valid: false,
+      message: "El cuerpo del RUN solo admite dígitos 0-9. Formato esperado: 12345678-5.",
+      cleaned: null,
+    };
+  }
+  if (body.length > 8) {
+    return {
+      valid: false,
+      message: `El cuerpo del RUN excede los 8 dígitos permitidos por CL Core CorePacienteCl (recibido: ${body.length} dígitos).`,
+      cleaned: null,
+    };
+  }
+  if (!/^[\dK]$/.test(dv)) {
+    return {
+      valid: false,
+      message: "El dígito verificador debe ser un número del 0-9 o la letra K. CL Core CorePacienteCl.",
+      cleaned: null,
+    };
+  }
+
+  return { valid: true, message: null, cleaned: `${body}-${dv}` };
+}
+
+function validateRunDv(raw) {
+  const fmt = classifyRunFormat(raw);
+  if (!fmt.valid) return { valid: false, message: fmt.message };
+
+  const [body, dv] = fmt.cleaned.split("-");
+  let sum = 0;
+  let mul = 2;
+  for (let i = body.length - 1; i >= 0; i--) {
+    sum += parseInt(body[i], 10) * mul;
+    mul = mul === 7 ? 2 : mul + 1;
+  }
+  const rest = 11 - (sum % 11);
+  const expected = rest === 11 ? "0" : rest === 10 ? "K" : String(rest);
+
+  if (expected !== dv) {
+    return { valid: false, expected, given: dv, cleaned: fmt.cleaned };
+  }
+  return { valid: true, expected, given: dv, normalized: fmt.cleaned };
+}
+
+// ── Rule runner ──────────────────────────────────────────────────────────────
+
+/**
+ * Inspecciona el recurso FHIR y retorna un arreglo de issues.
+ * El input puede ser un objeto ya parseado o un string JSON — si es string
+ * que no parsea, devolvemos un único issue cl-json-01.
+ *
+ * @param {object|string} input
+ * @param {{enrich?:boolean}} [options] — si enrich:false, se omiten los campos
+ *   pedagógicos (why, profileUrl, docsUrl, suggestion, example). Default true.
+ * @returns {Array<{code:string, severity:'error'|'warning'|'info', path:string, message:string, quickFix?:{title:string, jsonPointer:string, replacement:any}, why?:string, profileUrl?:string, docsUrl?:string, suggestion?:string, example?:any}>}
+ */
+function lintResource(input, options) {
+  const enrich = !options || options.enrich !== false;
+  const issues = [];
+
+  let resource = input;
+  if (typeof input === "string") {
+    try {
+      resource = JSON.parse(input);
+    } catch (err) {
+      issues.push({
+        code: "cl-json-01",
+        severity: "error",
+        path: "",
+        message: `JSON inválido: ${translateJsonParseError(err)}.`,
+      });
+      return enrich ? issues.map(enrichIssue) : issues;
+    }
+  }
+  if (!resource || typeof resource !== "object" || Array.isArray(resource)) {
+    issues.push({
+      code: "cl-json-02",
+      severity: "error",
+      path: "",
+      message: "El cuerpo debe ser un objeto FHIR con la propiedad resourceType.",
+    });
+    return enrich ? issues.map(enrichIssue) : issues;
+  }
+
+  const resourceType = resource.resourceType;
+  if (!resourceType || typeof resourceType !== "string") {
+    issues.push({
+      code: "cl-json-03",
+      severity: "error",
+      path: "resourceType",
+      message: "Falta resourceType — todo recurso FHIR debe declararlo (por ejemplo Patient).",
+    });
+    return enrich ? issues.map(enrichIssue) : issues;
+  }
+
+  // cl-json-04: resourceType no reconocido en FHIR R4.
+  if (!isKnownResourceType(resourceType)) {
+    issues.push({
+      code: "cl-json-04",
+      severity: "warning",
+      path: "resourceType",
+      message: `resourceType '${resourceType}' no es un tipo oficial de FHIR R4. El servidor lo rechazará.`,
+    });
+  }
+
+  // ── Identifier: RUN chileno — reglas cl-run-NN ────────────────────────────
+  const identifiers = Array.isArray(resource.identifier) ? resource.identifier : [];
+  identifiers.forEach((id, i) => {
+    const systemTop = id && id.system;
+    const pointsToRun = isRunIdentifier(id);
+    if (!pointsToRun) return;
+
+    const valuePath = `${resourceType}.identifier[${i}].value`;
+
+    if (!id.value || typeof id.value !== "string") {
+      issues.push({
+        code: "cl-run-02",
+        severity: "error",
+        path: valuePath,
+        message: "El identifier referencia el sistema RUN pero no trae value. CL Core CorePacienteCl v1.9.4.",
+      });
+      return;
+    }
+
+    if (hasRunDots(id.value)) {
+      issues.push({
+        code: "cl-run-01",
+        severity: "error",
+        path: valuePath,
+        message: "El RUN no debe incluir puntos. Formato esperado: 12345678-5 (CL Core CorePacienteCl · v1.9.4).",
+        quickFix: {
+          title: "Quitar puntos automáticamente",
+          jsonPointer: `/identifier/${i}/value`,
+          replacement: stripRunDots(id.value),
+        },
+      });
+    }
+
+    const dv = validateRunDv(id.value);
+    if (!dv.valid) {
+      issues.push({
+        code: "cl-run-03",
+        severity: "error",
+        path: valuePath,
+        message: dv.expected
+          ? `Dígito verificador incorrecto: esperado ${dv.expected}, recibido ${dv.given}. CL Core CorePacienteCl.`
+          : dv.message || "Formato de RUN inválido — usa 12345678-5. CL Core CorePacienteCl v1.9.4.",
+      });
+    }
+
+    // Preferir formato canónico: identifier.system = http://www.registrocivil.cl/run
+    // + identifier.type.coding[0] = CSTipoIdentificador#01
+    if (systemTop === RUN_SYSTEM_LEGACY_PRE17) {
+      issues.push({
+        code: "cl-run-04",
+        severity: "warning",
+        path: `${resourceType}.identifier[${i}].system`,
+        message:
+          "El system legacy https://hl7chile.cl/identificador/run está obsoleto en CL Core 1.7+. Usa identifier.system='http://www.registrocivil.cl/run' + type.coding[0] CSTipoIdentificador con code='01' (RUN).",
+        quickFix: {
+          title: "Actualizar al system canónico del Registro Civil",
+          jsonPointer: `/identifier/${i}/system`,
+          replacement: RUN_SYSTEM_REGCIVIL,
+        },
+      });
+    }
+    if (systemTop === RUN_SYSTEM_LEGACY_FHIRON_INVENT) {
+      issues.push({
+        code: "cl-run-04",
+        severity: "warning",
+        path: `${resourceType}.identifier[${i}].system`,
+        message:
+          "El system 'CSIdentificadores' fue una invención de Fhiron y NO existe en CL Core 1.9.4 oficial. Usa identifier.system='http://www.registrocivil.cl/run' + type.coding[0] CSTipoIdentificador con code='01' (RUN).",
+        quickFix: {
+          title: "Actualizar al system canónico del Registro Civil",
+          jsonPointer: `/identifier/${i}/system`,
+          replacement: RUN_SYSTEM_REGCIVIL,
+        },
+      });
+    }
+  });
+
+  // ── Dispatch por resourceType ────────────────────────────────────────────
+  const LINTERS = {
+    Patient:              lintPatient,
+    Practitioner:         lintPractitioner,
+    Observation:          lintObservation,
+    Medication:           lintMedication,
+    MedicationRequest:    lintMedicationRequest,
+    Encounter:            lintEncounter,
+    Condition:            lintCondition,
+    AllergyIntolerance:   lintAllergyIntolerance,
+    Procedure:            lintProcedure,
+    Coverage:             lintCoverage,
+    Organization:         lintOrganization,
+    Immunization:         lintImmunization,
+    DiagnosticReport:     lintDiagnosticReport,
+    Bundle:               lintBundle,
+  };
+
+  const lintFn = LINTERS[resourceType];
+  if (lintFn) lintFn(resource, issues);
+
+  // Linter genérico FHIR — corre en TODOS los recursos. Reglas que no
+  // dependen del resourceType: meta.profile bien formado, fechas ISO,
+  // references válidas. Esto da valor incluso cuando el motor server-side
+  // está caído.
+  lintGeneric(resource, resourceType, issues);
+
+  // Linter EIS — reconoce uso de terminología MINSAL y valida formato.
+  // Aditivo: no rompe ni modifica nada que ya validaba CL Core.
+  lintEisTerminology(resource, resourceType, issues);
+
+  return enrich ? issues.map(enrichIssue) : issues;
+}
+
+// ── MINSAL EIS — reconocimiento de terminología paralela a CL Core ───────────
+//
+// EIS (https://interoperabilidad.minsal.cl/fhir/ig/eis/) es un IG paralelo
+// que publica 49 CodeSystems oficiales del MINSAL bajo un namespace distinto
+// al de CL Core. Sin esta tabla, el linter marcaría como "system desconocido"
+// algo que en realidad es estándar oficial publicado.
+const EIS_CS_PREFIX = "https://interoperabilidad.minsal.cl/fhir/ig/eis/CodeSystem/";
+const EIS_KNOWN_CODESYSTEMS = new Set([
+  "CSAnamnesis", "CSAreaUrbanoCensal", "CSComunas", "CSCondiciondelaActividad",
+  "CSConsultaMedExclu", "CSConsultaMedIncluyente", "CSConsultaMedRendida",
+  "CSDiagnostico", "CSEspecialidadBioquimica", "CSEspecialidadFarma",
+  "CSEspecialidadMedica", "CSEspecialidadOdontologica", "CSEstadoCivil",
+  "CSIdentidadGenero", "CSInstitucionEmiteEspecialidad", "CSInstitucionEmiteTitulo",
+  "CSLeyPrevisionales", "CSModalidadAtencionFonasa", "CSNivelAtencion",
+  "CSNivelComplejidad", "CSNivelInstruccion", "CSOcupaciones",
+  "CSOcupacionesDetalladas", "CSOtroTipoEstabAsistenciales", "CSPaises",
+  "CSPrevision", "CSProvincia", "CSPueblosOriginarios", "CSRegion",
+  "CSReligion",
+  // Hay 49 totales — los menos comunes se aceptan via heurística de prefix.
+]);
+
+function lintEisTerminology(r, resourceType, issues) {
+  if (!r || typeof r !== "object") return;
+  walkForCodings(r, "", (coding, path) => {
+    const sys = coding && coding.system;
+    if (typeof sys !== "string" || !sys.startsWith(EIS_CS_PREFIX)) return;
+
+    const csName = sys.slice(EIS_CS_PREFIX.length);
+
+    // cl-eis-system-01 — system bajo namespace EIS pero el CodeSystem no está
+    // en el catálogo conocido. Heurística simple: nombre debe ser PascalCase
+    // tipo "CSXxxxxx". Marca warning para typos sin alarmar a quien usa los
+    // 19 CodeSystems menos comunes.
+    const looksLikeCS = /^CS[A-Z][A-Za-z0-9]+$/.test(csName);
+    if (!EIS_KNOWN_CODESYSTEMS.has(csName) && !looksLikeCS) {
+      issues.push({
+        code: "cl-eis-system-01",
+        severity: "warning",
+        path,
+        message: `El system '${sys}' parece de MINSAL EIS pero el CodeSystem '${csName}' no es uno de los 49 publicados oficialmente. Verifica el nombre.`,
+      });
+      return;
+    }
+
+    // Reglas pedagógicas por CodeSystem específico (info-level).
+    if (csName === "CSComunas") {
+      issues.push({
+        code: "cl-eis-comuna-01",
+        severity: "information",
+        path,
+        message:
+          "Usando CSComunas oficial MINSAL (347 comunas DEIS). Equivalente válido al CSCodComunasCL de CL Core.",
+      });
+    } else if (csName === "CSPrevision") {
+      issues.push({
+        code: "cl-eis-prevision-01",
+        severity: "information",
+        path,
+        message:
+          "Usando CSPrevision oficial MINSAL — única fuente FHIR para Fonasa/ISAPRE/PRAIS publicada en Chile. Sin equivalente en CL Core.",
+      });
+    }
+  });
+}
+
+// Recorre el recurso buscando coding[] anidados (ej. code.coding,
+// vaccineCode.coding, address.city.coding) y llama cb(coding, fullPath).
+function walkForCodings(node, path, cb) {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) walkForCodings(node[i], `${path}[${i}]`, cb);
+    return;
+  }
+  if (Array.isArray(node.coding)) {
+    for (let i = 0; i < node.coding.length; i++) {
+      cb(node.coding[i], `${path}.coding[${i}]`);
+    }
+  }
+  for (const key of Object.keys(node)) {
+    if (key === "coding") continue;
+    const child = node[key];
+    if (child && typeof child === "object") {
+      walkForCodings(child, path ? `${path}.${key}` : key, cb);
+    }
+  }
+}
+
+/**
+ * Reglas FHIR generales que aplican a todos los recursos.
+ */
+function lintGeneric(r, resourceType, issues) {
+  // meta.profile: array de URIs canónicos
+  if (r.meta && Array.isArray(r.meta.profile)) {
+    r.meta.profile.forEach((url, i) => {
+      if (typeof url !== "string" || !/^https?:\/\//.test(url)) {
+        issues.push({
+          code: "cl-meta-01",
+          severity: "error",
+          path: `${resourceType}.meta.profile[${i}]`,
+          message: `meta.profile[${i}] debería ser una URL canónica HTTPS de un StructureDefinition (ej: https://hl7chile.cl/fhir/ig/clcore/StructureDefinition/CorePacienteCl). Valor recibido: '${url}'.`,
+        });
+      }
+    });
+  }
+
+  // ── text.div narrativa ────────────────────────────────────────────────────
+  // FHIR R4 dom-6 recomienda incluir text.div en cada DomainResource. HAPI
+  // emite la advertencia "A resource should have narrative for robust
+  // management" cuando falta. El linter local replica la regla con
+  // cl-narrative-02 + quickFix (inserta text.status='generated' + div mínimo).
+  // Excluye Bundle (no es DomainResource — su narrativa va en cada entry).
+  const TEXT_EXCLUDED_TYPES = new Set([
+    "Bundle", "Parameters", "Binary", "OperationOutcome",
+  ]);
+  if (!TEXT_EXCLUDED_TYPES.has(resourceType)) {
+    const hasNarrative = r.text && typeof r.text === "object" && r.text.status && typeof r.text.div === "string" && r.text.div.length > 0;
+    if (!hasNarrative) {
+      issues.push({
+        code: "cl-narrative-02",
+        severity: "warning",
+        path: `${resourceType}.text`,
+        message: `${resourceType}.text.div recomendado por FHIR R4 (dom-6): incluye una narrativa HTML legible del recurso. Mejora la lectura humana cuando un sistema no entiende el JSON estructurado.`,
+        quickFix: {
+          title: "Agregar narrativa text.div mínima",
+          jsonPointer: `/text`,
+          replacement: {
+            status: "generated",
+            div: `<div xmlns="http://www.w3.org/1999/xhtml">Recurso ${resourceType} generado por Fhiron.</div>`,
+          },
+        },
+      });
+    }
+  }
+
+  // text.div — si está, debería tener un status válido
+  if (r.text && typeof r.text === "object") {
+    const VALID_NARRATIVE = ["generated", "extensions", "additional", "empty"];
+    if (r.text.status && !VALID_NARRATIVE.includes(r.text.status)) {
+      issues.push({
+        code: "cl-narrative-01",
+        severity: "error",
+        path: `${resourceType}.text.status`,
+        message: `${resourceType}.text.status='${r.text.status}' no es válido. Valores permitidos: ${VALID_NARRATIVE.join(", ")}. FHIR R4 NarrativeStatus.`,
+        quickFix: {
+          title: "Reemplazar por 'generated' (status canónico)",
+          jsonPointer: `/text/status`,
+          replacement: "generated",
+        },
+      });
+    }
+  }
+
+  // Identifier system — los identifier deberían tener system URI absoluto
+  if (Array.isArray(r.identifier)) {
+    r.identifier.forEach((id, i) => {
+      if (id && id.system && typeof id.system === "string") {
+        if (!/^https?:\/\/|^urn:/.test(id.system)) {
+          issues.push({
+            code: "cl-system-02",
+            severity: "warning",
+            path: `${resourceType}.identifier[${i}].system`,
+            message: `identifier.system debería ser una URI absoluta (HTTPS o urn:). Valor recibido: '${id.system}'. FHIR R4 Identifier.`,
+          });
+        }
+      }
+    });
+  }
+}
+
+// ── Linters por recurso ──────────────────────────────────────────────────────
+
+function lintPatient(r, issues) {
+  if (!Array.isArray(r.identifier) || r.identifier.length === 0) {
+    issues.push({
+      code: "cl-patient-01",
+      severity: "error",
+      path: "Patient.identifier",
+      message:
+        "Patient debe incluir al menos un identifier (usualmente el RUN con system http://www.registrocivil.cl/run + type.coding CSTipoIdentificador#01). CL Core CorePacienteCl.",
+    });
+  }
+  if (!Array.isArray(r.name) || r.name.length === 0) {
+    issues.push({
+      code: "cl-patient-02",
+      severity: "error",
+      path: "Patient.name",
+      message:
+        "Patient.name es obligatorio (mínimo family + given). CL Core CorePacienteCl.",
+    });
+  } else {
+    r.name.forEach((n, i) => {
+      if (!n || (!n.family && !(Array.isArray(n.given) && n.given.length))) {
+        issues.push({
+          code: "cl-patient-03",
+          severity: "error",
+          path: `Patient.name[${i}]`,
+          message: "Cada name debe tener family y/o given — CL Core CorePacienteCl.",
+        });
+      }
+    });
+  }
+  if (!r.gender) {
+    issues.push({
+      code: "cl-patient-04",
+      severity: "warning",
+      path: "Patient.gender",
+      message:
+        "Patient.gender es recomendado por CL Core CorePacienteCl (male · female · other · unknown).",
+      quickFix: {
+        title: "Agregar gender='unknown' (valor neutro)",
+        jsonPointer: "/gender",
+        replacement: "unknown",
+      },
+    });
+  }
+}
+
+function lintPractitioner(r, issues) {
+  if (!Array.isArray(r.identifier) || r.identifier.length === 0) {
+    issues.push({
+      code: "cl-practitioner-01",
+      severity: "error",
+      path: "Practitioner.identifier",
+      message:
+        "Practitioner debe incluir un identifier — usualmente RUN o código DEIS. CL Core CorePrestadorCl.",
+    });
+  }
+  if (!Array.isArray(r.name) || r.name.length === 0) {
+    issues.push({
+      code: "cl-practitioner-02",
+      severity: "error",
+      path: "Practitioner.name",
+      message: "Practitioner.name es obligatorio. CL Core CorePrestadorCl.",
+    });
+  }
+}
+
+function lintObservation(r, issues) {
+  if (!r.status) {
+    issues.push({
+      code: "cl-obs-01",
+      severity: "error",
+      path: "Observation.status",
+      message:
+        "Observation.status es obligatorio (registered · preliminary · final · amended · corrected · cancelled · entered-in-error · unknown).",
+    });
+  }
+  if (!r.code) {
+    issues.push({
+      code: "cl-obs-02",
+      severity: "error",
+      path: "Observation.code",
+      message: "Observation.code es obligatorio (LOINC o similar).",
+    });
+  }
+  if (!r.subject) {
+    issues.push({
+      code: "cl-obs-03",
+      severity: "error",
+      path: "Observation.subject",
+      message: "Observation.subject es obligatorio (referencia al Patient).",
+    });
+  }
+}
+
+function lintMedication(r, issues) {
+  if (!r.code) {
+    issues.push({
+      code: "cl-med-01",
+      severity: "error",
+      path: "Medication.code",
+      message:
+        "Medication.code es obligatorio. Usa ATC (http://www.whocc.no/atc), SNOMED CT o RxNorm. CL Core CoreMedicamentoCl.",
+    });
+  } else {
+    const codings = Array.isArray(r.code.coding) ? r.code.coding : [];
+    const KNOWN_MED_SYSTEMS = [
+      "http://www.whocc.no/atc",
+      "http://snomed.info/sct",
+      "http://www.nlm.nih.gov/research/umls/rxnorm",
+    ];
+    const hasKnownSystem = codings.some(
+      (c) => c && KNOWN_MED_SYSTEMS.includes(c.system),
+    );
+    if (codings.length > 0 && !hasKnownSystem) {
+      issues.push({
+        code: "cl-med-02",
+        severity: "warning",
+        path: "Medication.code.coding",
+        message:
+          "Se recomienda usar ATC (http://www.whocc.no/atc), SNOMED CT o RxNorm para Medication.code.coding. CL Core CoreMedicamentoCl.",
+      });
+    }
+  }
+}
+
+function lintMedicationRequest(r, issues) {
+  if (!r.status) {
+    issues.push({
+      code: "cl-medreq-01",
+      severity: "error",
+      path: "MedicationRequest.status",
+      message:
+        "MedicationRequest.status es obligatorio (active · on-hold · cancelled · completed · entered-in-error · stopped · draft · unknown). CL Core.",
+    });
+  }
+  if (!r.intent) {
+    issues.push({
+      code: "cl-medreq-02",
+      severity: "error",
+      path: "MedicationRequest.intent",
+      message:
+        "MedicationRequest.intent es obligatorio (proposal · plan · order · original-order · reflex-order · filler-order · instance-order · option). CL Core.",
+    });
+  }
+  if (!r.subject) {
+    issues.push({
+      code: "cl-medreq-03",
+      severity: "error",
+      path: "MedicationRequest.subject",
+      message:
+        "MedicationRequest.subject es obligatorio (referencia al Patient). CL Core.",
+    });
+  }
+  const hasMed =
+    r.medicationCodeableConcept ||
+    r.medicationReference;
+  if (!hasMed) {
+    issues.push({
+      code: "cl-medreq-04",
+      severity: "error",
+      path: "MedicationRequest.medication[x]",
+      message:
+        "MedicationRequest debe incluir medicationCodeableConcept o medicationReference. CL Core CoreMedicamentoCl.",
+    });
+  }
+}
+
+function lintEncounter(r, issues) {
+  // status — campo obligatorio + value-set cerrado
+  const ENC_STATUS = [
+    "planned", "arrived", "triaged", "in-progress", "onleave",
+    "finished", "cancelled", "entered-in-error", "unknown",
+  ];
+  if (!r.status) {
+    issues.push({
+      code: "cl-enc-01",
+      severity: "error",
+      path: "Encounter.status",
+      message:
+        "Encounter.status es obligatorio. Valores permitidos: planned, arrived, triaged, in-progress, onleave, finished, cancelled, entered-in-error, unknown. CL Core EncounterCL.",
+    });
+  } else if (!ENC_STATUS.includes(r.status)) {
+    issues.push({
+      code: "cl-enc-04",
+      severity: "error",
+      path: "Encounter.status",
+      message: `Encounter.status='${r.status}' no es válido. Valor debe ser uno de: ${ENC_STATUS.join(", ")}. Especificación FHIR R4 EncounterStatus.`,
+    });
+  }
+
+  // class — CodeableConcept con system canónico v3-ActCode
+  if (!r.class) {
+    issues.push({
+      code: "cl-enc-02",
+      severity: "error",
+      path: "Encounter.class",
+      message:
+        "Encounter.class es obligatorio. Usa v3-ActCode (AMB · IMP · EMER, etc.) según el tipo de atención. CL Core EncounterCL.",
+    });
+  } else {
+    const cls = r.class;
+    if (typeof cls === "object" && cls !== null) {
+      if (cls.system && cls.system !== "http://terminology.hl7.org/CodeSystem/v3-ActCode") {
+        issues.push({
+          code: "cl-enc-05",
+          severity: "warning",
+          path: "Encounter.class.system",
+          message: `Encounter.class.system debería ser 'http://terminology.hl7.org/CodeSystem/v3-ActCode' (canónico). Valor recibido: '${cls.system}'.`,
+          quickFix: {
+            title: "Reemplazar por v3-ActCode canónico",
+            jsonPointer: "/class/system",
+            replacement: "http://terminology.hl7.org/CodeSystem/v3-ActCode",
+          },
+        });
+      }
+      const VALID_CLASS_CODES = ["AMB", "IMP", "EMER", "HH", "FLD", "VR", "ACUTE", "NONAC", "OBSENC", "PRENC", "SS"];
+      if (cls.code && !VALID_CLASS_CODES.includes(cls.code)) {
+        issues.push({
+          code: "cl-enc-06",
+          severity: "warning",
+          path: "Encounter.class.code",
+          message: `Encounter.class.code='${cls.code}' no es un valor común de v3-ActCode. Lista típica: ${VALID_CLASS_CODES.slice(0, 6).join(", ")}.`,
+        });
+      }
+    }
+  }
+
+  // subject — referencia obligatoria al Patient
+  if (!r.subject) {
+    issues.push({
+      code: "cl-enc-03",
+      severity: "error",
+      path: "Encounter.subject",
+      message:
+        "Encounter.subject es obligatorio (referencia al Patient). CL Core EncounterCL.",
+    });
+  } else if (typeof r.subject === "object" && r.subject.reference) {
+    if (!REFERENCE_RE.test(r.subject.reference)) {
+      issues.push({
+        code: "cl-ref-01",
+        severity: "error",
+        path: "Encounter.subject.reference",
+        message: `La referencia '${r.subject.reference}' no tiene formato FHIR válido. Esperado: '<ResourceType>/<id>' (ej: 'Patient/123'). FHIR R4.`,
+      });
+    } else if (!r.subject.reference.startsWith("Patient/")) {
+      issues.push({
+        code: "cl-enc-07",
+        severity: "warning",
+        path: "Encounter.subject.reference",
+        message: `Encounter.subject debería referenciar un Patient, no '${r.subject.reference.split("/")[0]}'. CL Core EncounterCL.`,
+      });
+    }
+  }
+
+  // period — si presente, validar fechas
+  if (r.period && typeof r.period === "object") {
+    if (r.period.start && !ISO_DATETIME_RE.test(r.period.start)) {
+      issues.push({
+        code: "cl-date-01",
+        severity: "error",
+        path: "Encounter.period.start",
+        message: `Encounter.period.start='${r.period.start}' no es una fecha/hora ISO-8601 válida. Formato esperado: YYYY-MM-DDTHH:MM:SS+TZ. FHIR R4 dateTime.`,
+      });
+    }
+    if (r.period.end && !ISO_DATETIME_RE.test(r.period.end)) {
+      issues.push({
+        code: "cl-date-01",
+        severity: "error",
+        path: "Encounter.period.end",
+        message: `Encounter.period.end='${r.period.end}' no es una fecha/hora ISO-8601 válida. Formato esperado: YYYY-MM-DDTHH:MM:SS+TZ. FHIR R4 dateTime.`,
+      });
+    }
+  }
+
+  // participant — si hay, cada uno debe tener individual con reference válida
+  if (Array.isArray(r.participant)) {
+    r.participant.forEach((p, i) => {
+      if (p && p.individual && p.individual.reference && !REFERENCE_RE.test(p.individual.reference)) {
+        issues.push({
+          code: "cl-ref-01",
+          severity: "error",
+          path: `Encounter.participant[${i}].individual.reference`,
+          message: `La referencia '${p.individual.reference}' no tiene formato FHIR válido. Esperado: '<ResourceType>/<id>'.`,
+        });
+      }
+    });
+  }
+}
+
+// Regex compartidos para reglas FHIR generales
+const REFERENCE_RE = /^[A-Z][A-Za-z]+\/[A-Za-z0-9\-.]{1,64}(\|[^\s]+)?$/;
+const ISO_DATE_RE = /^\d{4}(-\d{2}(-\d{2})?)?$/;
+const ISO_DATETIME_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?)?$/;
+
+function lintCondition(r, issues) {
+  if (!r.subject) {
+    issues.push({
+      code: "cl-cond-01",
+      severity: "error",
+      path: "Condition.subject",
+      message:
+        "Condition.subject es obligatorio (referencia al Patient). CL Core CoreDiagnosticoCl.",
+    });
+  }
+  if (!r.code) {
+    issues.push({
+      code: "cl-cond-02",
+      severity: "error",
+      path: "Condition.code",
+      message:
+        "Condition.code es obligatorio. Usa codificación CIE-10 (system http://hl7.org/fhir/sid/icd-10) o SNOMED CT. CL Core CoreDiagnosticoCl.",
+    });
+  }
+}
+
+function lintAllergyIntolerance(r, issues) {
+  // cl-allergy-04 — warning si falta clinicalStatus
+  if (!r.clinicalStatus) {
+    issues.push({
+      code: "cl-allergy-04",
+      severity: "warning",
+      path: "AllergyIntolerance.clinicalStatus",
+      message:
+        "Recomendado: declarar clinicalStatus (active · inactive · resolved). Sin él la alergia queda ambigua para el clínico que la lee.",
+    });
+  }
+  if (!r.patient) {
+    issues.push({
+      code: "cl-allergy-01",
+      severity: "error",
+      path: "AllergyIntolerance.patient",
+      message:
+        "AllergyIntolerance.patient es obligatorio (referencia al Patient). CL Core CoreAlergiaIntCl.",
+    });
+  }
+  if (!r.code) {
+    issues.push({
+      code: "cl-allergy-02",
+      severity: "error",
+      path: "AllergyIntolerance.code",
+      message:
+        "AllergyIntolerance.code es obligatorio. Usa SNOMED CT o el catálogo de alergias DEIS. CL Core CoreAlergiaIntCl.",
+    });
+  }
+}
+
+function lintProcedure(r, issues) {
+  if (!r.status) {
+    issues.push({
+      code: "cl-proc-01",
+      severity: "error",
+      path: "Procedure.status",
+      message:
+        "Procedure.status es obligatorio (preparation · in-progress · not-done · on-hold · stopped · completed · entered-in-error · unknown). CL Core.",
+    });
+  }
+  if (!r.subject) {
+    issues.push({
+      code: "cl-proc-02",
+      severity: "error",
+      path: "Procedure.subject",
+      message:
+        "Procedure.subject es obligatorio (referencia al Patient). CL Core.",
+    });
+  }
+  if (!r.code) {
+    issues.push({
+      code: "cl-proc-03",
+      severity: "error",
+      path: "Procedure.code",
+      message:
+        "Procedure.code es obligatorio. Usa SNOMED CT o la codificación de prestaciones FONASA/DEIS. CL Core.",
+    });
+  }
+  // cl-proc-04 — warning si falta fecha del procedimiento
+  if (!r.performedDateTime && !r.performedPeriod && !r.performedString) {
+    issues.push({
+      code: "cl-proc-04",
+      severity: "warning",
+      path: "Procedure.performed[x]",
+      message:
+        "Recomendado: declarar cuándo ocurrió el procedimiento (performedDateTime o performedPeriod). Sin fecha el procedimiento no es analizable epidemiológicamente.",
+    });
+  }
+}
+
+function lintCoverage(r, issues) {
+  if (!r.status) {
+    issues.push({
+      code: "cl-cov-01",
+      severity: "error",
+      path: "Coverage.status",
+      message:
+        "Coverage.status es obligatorio (active · cancelled · draft · entered-in-error). CL Core CoreCoberturaCl.",
+    });
+  }
+  if (!r.beneficiary) {
+    issues.push({
+      code: "cl-cov-02",
+      severity: "error",
+      path: "Coverage.beneficiary",
+      message:
+        "Coverage.beneficiary es obligatorio (referencia al Patient asegurado). CL Core CoreCoberturaCl.",
+    });
+  }
+  if (!Array.isArray(r.payor) || r.payor.length === 0) {
+    issues.push({
+      code: "cl-cov-03",
+      severity: "error",
+      path: "Coverage.payor",
+      message:
+        "Coverage.payor es obligatorio (Isapre, FONASA u otra entidad pagadora). CL Core CoreCoberturaCl.",
+    });
+  }
+  // cl-cov-04 — warning: subscriberId requerido para liquidación Fonasa/ISAPRE
+  if (!r.subscriberId && !r.subscriber) {
+    issues.push({
+      code: "cl-cov-04",
+      severity: "warning",
+      path: "Coverage.subscriberId",
+      message:
+        "Recomendado: incluir subscriberId (RUN del cotizante en Fonasa, número de contrato en ISAPRE) para que el dispensador pueda liquidar.",
+    });
+  }
+}
+
+function lintOrganization(r, issues) {
+  const hasIdentifier = Array.isArray(r.identifier) && r.identifier.length > 0;
+  const hasName = typeof r.name === "string" && r.name.trim().length > 0;
+  if (!hasIdentifier && !hasName) {
+    issues.push({
+      code: "cl-org-01",
+      severity: "error",
+      path: "Organization",
+      message:
+        "Organization debe incluir al menos un identifier (código DEIS) o un name. CL Core CoreOrganizacionCl.",
+    });
+  }
+  // cl-org-02: MINSAL aún no publica un CodeSystem oficial para
+  // establecimientos DEIS. Mientras no exista URI canónica publicada,
+  // este chequeo queda como no-op para no exigir un system inventado.
+  // Cuando MINSAL publique el CodeSystem oficial, restaurar la advertencia
+  // contra esa URI.
+}
+
+function lintImmunization(r, issues) {
+  if (!r.status) {
+    issues.push({
+      code: "cl-imm-01",
+      severity: "error",
+      path: "Immunization.status",
+      message:
+        "Immunization.status es obligatorio (completed · entered-in-error · not-done). CL Core ImmunizationCL.",
+    });
+  }
+  if (!r.vaccineCode) {
+    issues.push({
+      code: "cl-imm-02",
+      severity: "error",
+      path: "Immunization.vaccineCode",
+      message:
+        "Immunization.vaccineCode es obligatorio. Usa CVX (http://hl7.org/fhir/sid/cvx). El catálogo PNI chileno (CSNombreCampana) está pendiente. CL Core ImmunizationCL.",
+    });
+  }
+  if (!r.patient) {
+    issues.push({
+      code: "cl-imm-03",
+      severity: "error",
+      path: "Immunization.patient",
+      message:
+        "Immunization.patient es obligatorio (referencia al Patient). CL Core ImmunizationCL.",
+    });
+  }
+  const hasOccurrence = r.occurrenceDateTime || r.occurrenceString;
+  if (!hasOccurrence) {
+    issues.push({
+      code: "cl-imm-04",
+      severity: "error",
+      path: "Immunization.occurrence[x]",
+      message:
+        "Immunization.occurrenceDateTime u occurrenceString es obligatorio (fecha/hora de la vacunación). CL Core ImmunizationCL.",
+    });
+  }
+  // cl-imm-05 — warning: lotNumber recomendado para trazabilidad PNI
+  if (!r.lotNumber) {
+    issues.push({
+      code: "cl-imm-05",
+      severity: "warning",
+      path: "Immunization.lotNumber",
+      message:
+        "Recomendado: incluir lotNumber para trazabilidad PNI. Sin lote la dosis no es auditable ante eventos adversos.",
+    });
+  }
+}
+
+function lintDiagnosticReport(r, issues) {
+  if (!r.status) {
+    issues.push({
+      code: "cl-dr-01",
+      severity: "error",
+      path: "DiagnosticReport.status",
+      message:
+        "DiagnosticReport.status es obligatorio (registered · partial · preliminary · final · amended · corrected · appended · cancelled · entered-in-error · unknown). CL Core.",
+    });
+  }
+  if (!r.code) {
+    issues.push({
+      code: "cl-dr-02",
+      severity: "error",
+      path: "DiagnosticReport.code",
+      message:
+        "DiagnosticReport.code es obligatorio. Usa LOINC (system http://loinc.org) para el tipo de informe. CL Core.",
+    });
+  }
+  if (!r.subject) {
+    issues.push({
+      code: "cl-dr-03",
+      severity: "error",
+      path: "DiagnosticReport.subject",
+      message:
+        "DiagnosticReport.subject es obligatorio (referencia al Patient). CL Core.",
+    });
+  }
+  // cl-dr-04 — warning si falta effectiveDateTime
+  if (!r.effectiveDateTime && !r.effectivePeriod) {
+    issues.push({
+      code: "cl-dr-04",
+      severity: "warning",
+      path: "DiagnosticReport.effective[x]",
+      message:
+        "Recomendado: declarar effectiveDateTime (fecha/hora del estudio o toma de muestra). Útil para trazabilidad clínica.",
+    });
+  }
+}
+
+function lintBundle(r, issues) {
+  if (!r.type) {
+    issues.push({
+      code: "cl-bundle-01",
+      severity: "error",
+      path: "Bundle.type",
+      message:
+        "Bundle.type es obligatorio (document · message · transaction · transaction-response · batch · batch-response · history · searchset · collection).",
+    });
+  }
+
+  const entries = Array.isArray(r.entry) ? r.entry : [];
+  entries.forEach((entry, i) => {
+    const res = entry && entry.resource;
+    if (!res) return;
+    // Recursión shallow: lintResource sobre el recurso interno.
+    // Pasamos enrich:false porque el outer call enriquece al final — evita doble pasada.
+    const innerIssues = lintResource(res, { enrich: false });
+    innerIssues.forEach((issue) => {
+      const wrapped = {
+        ...issue,
+        entryIndex: i,
+        path: `Bundle.entry[${i}].resource${issue.path ? `.${issue.path}` : ""}`,
+      };
+      // Re-anchorar quickFix.jsonPointer para que sea aplicable al Bundle completo:
+      // /identifier/0/value (relativo al recurso interno) → /entry/0/resource/identifier/0/value
+      if (issue.quickFix && typeof issue.quickFix.jsonPointer === "string") {
+        wrapped.quickFix = {
+          ...issue.quickFix,
+          jsonPointer: `/entry/${i}/resource${issue.quickFix.jsonPointer}`,
+        };
+      }
+      issues.push(wrapped);
+    });
+  });
+}
+
+// ── Quick-fix applier ────────────────────────────────────────────────────────
+
+/**
+ * Aplica un quick-fix sobre el recurso (o string JSON). Retorna el resultado
+ * serializado con el mismo indent que se infirió del input. El jsonPointer
+ * sigue RFC 6901 (ej: /identifier/0/value).
+ */
+// FHI-72 H6: prototype pollution guard. Un atacante puede plantar un
+// jsonPointer `/__proto__/x` o `/constructor/prototype/y` para mutar
+// Object.prototype durante toda la sesión MCP. Bloqueamos *después* de
+// decodePointerSegment porque `~2` no es una codificación válida pero
+// `~01` decodifica a `~1` y un atacante creativo podría intentar variantes.
+const FORBIDDEN_POINTER_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+
+function applyQuickFix(input, fix) {
+  if (!fix || !fix.jsonPointer) return typeof input === "string" ? input : JSON.stringify(input, null, 2);
+  let resource = input;
+  let indent = 2;
+  if (typeof input === "string") {
+    const m = input.match(/\n(\s+)"/);
+    if (m) indent = m[1].length;
+    try {
+      resource = JSON.parse(input);
+    } catch {
+      return input;
+    }
+  }
+  const parts = fix.jsonPointer.split("/").filter(Boolean).map(decodePointerSegment);
+  // FHI-72 H6: rechazar cualquier segmento peligroso → no-op.
+  if (parts.some((p) => FORBIDDEN_POINTER_SEGMENTS.has(p))) {
+    return typeof input === "string" ? input : JSON.stringify(resource, null, indent);
+  }
+  let node = resource;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    if (node == null) return typeof input === "string" ? input : JSON.stringify(resource, null, indent);
+    node = node[key];
+  }
+  if (node && parts.length) {
+    const lastKey = parts[parts.length - 1];
+    node[lastKey] = fix.replacement;
+  }
+  return JSON.stringify(resource, null, indent);
+}
+
+function decodePointerSegment(seg) {
+  return seg.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+// Re-exports — para que consumidores hagan un único require("@fhiron/linter")
+// y obtengan todo el surface (rules + catalog + examples + terminology + i18n).
+const examples = require("./examples.js");
+const terminology = require("./terminology.js");
+const i18n = require("./i18n.js");
+
+module.exports = {
+  lintResource,
+  applyQuickFix,
+  stripRunDots,
+  validateRunDv,
+  classifyRunFormat,
+  translateJsonParseError,
+  enrichIssue,
+  lookupCode,
+  listCodes,
+  RUN_SYSTEMS,
+  // examples
+  getExample: examples.getExample,
+  listExamples: examples.listExamples,
+  EXAMPLES: examples.EXAMPLES,
+  // terminology
+  searchTerminology: terminology.search,
+  listTerminologySystems: terminology.listSystems,
+  TERMINOLOGY_SYSTEMS: terminology.SYSTEMS,
+  // i18n
+  t: i18n.t,
+  normalizeLang: i18n.normalizeLang,
+  SUPPORTED_LANGS: i18n.SUPPORTED_LANGS,
+};