cht-conf 4.1.3 → 4.3.0

package/src/lib/hierarchy-operations/lineage-constraints.js

@@ -0,0 +1,170 @@
+const log = require('../log');
+const { HIERARCHY_ROOT } = require('./hierarchy-data-source');
+const { trace } = log;
+
+const lineageManipulation = require('./lineage-manipulation');
+
+module.exports = async (db, options) => {
+  const mapTypeToAllowedParents = await fetchAllowedParents(db);
+
+  return {
+    assertNoPrimaryContactViolations: async (sourceDoc, destinationDoc, descendantDocs) => {
+      const invalidPrimaryContactDoc = await getPrimaryContactViolations(db, sourceDoc, destinationDoc, descendantDocs);
+      if (invalidPrimaryContactDoc) {
+        throw Error(`Cannot remove contact '${invalidPrimaryContactDoc?.name}' (${invalidPrimaryContactDoc?._id}) from the hierarchy for which they are a primary contact.`);
+      }
+    },
+    assertNoHierarchyErrors: (sourceDocs, destinationDoc) => {
+
+      sourceDocs.forEach(sourceDoc => {
+        const commonViolations = getCommonViolations(sourceDoc, destinationDoc);
+        const specificViolation = options.merge ?
+          getMergeViolations(sourceDoc, destinationDoc)
+          : getMovingViolations(mapTypeToAllowedParents, sourceDoc, destinationDoc);
+
+        const hierarchyError = commonViolations || specificViolation;
+        if (hierarchyError) {
+          throw Error(`Hierarchy Constraints: ${hierarchyError}`);
+        }
+      });
+  
+      /*
+      It is nice that the tool can move lists of contacts as one operation, but strange things happen when two contactIds are in the same lineage.
+      For example, moving a district_hospital and moving a contact under that district_hospital to a new clinic causes multiple colliding writes to the same json file.
+      */
+      const contactIds = sourceDocs.map(doc => doc._id);
+      sourceDocs
+        .forEach(doc => {
+          const parentIdsOfDoc = lineageManipulation.pluckIdsFromLineage(doc.parent);
+          const violatingParentId = parentIdsOfDoc.find(parentId => contactIds.includes(parentId));
+          if (violatingParentId) {
+            throw Error(`Unable to move two documents from the same lineage: '${doc._id}' and '${violatingParentId}'`);
+          }
+        });
+    }    
+  };
+};
+
+/*
+Enforce the list of allowed parents for each contact type
+Ensure we are not creating a circular hierarchy
+*/
+const getMovingViolations = (mapTypeToAllowedParents, sourceDoc, destinationDoc) => {
+  const contactTypeError = getMovingContactTypeError(mapTypeToAllowedParents, sourceDoc, destinationDoc);
+  const circularHierarchyError = findCircularHierarchyErrors(sourceDoc, destinationDoc);
+  return contactTypeError || circularHierarchyError;
+};
+
+function getMovingContactTypeError(mapTypeToAllowedParents, sourceDoc, destinationDoc) {
+  const sourceContactType = getContactType(sourceDoc);
+  const destinationType = getContactType(destinationDoc);
+  const rulesForContact = mapTypeToAllowedParents[sourceContactType];
+  if (!rulesForContact) {
+    return `cannot move contact with unknown type '${sourceContactType}'`;
+  }
+
+  const isPermittedMoveToRoot = !destinationDoc && rulesForContact.length === 0;
+  if (!isPermittedMoveToRoot && !rulesForContact.includes(destinationType)) {
+    return `contacts of type '${sourceContactType}' cannot have parent of type '${destinationType}'`;
+  }
+}
+
+function findCircularHierarchyErrors(sourceDoc, destinationDoc) {
+  if (!destinationDoc) {
+    return;
+  }
+
+  const parentAncestry = lineageManipulation.pluckIdsFromLineage(destinationDoc);
+  if (parentAncestry.includes(sourceDoc._id)) {
+    return `Circular hierarchy: Cannot set parent of contact '${sourceDoc._id}' as it would create a circular hierarchy.`;
+  }
+}
+
+const getCommonViolations = (sourceDoc, destinationDoc) => {
+  if (!sourceDoc) {
+    return `source doc cannot be found`;
+  }
+
+  const sourceContactType = getContactType(sourceDoc);
+  const destinationContactType = getContactType(destinationDoc);
+  if (!sourceContactType) {
+    return `source contact "${sourceDoc._id}" required attribute "type" is undefined`;
+  }
+
+  if (destinationDoc && !destinationContactType) {
+    return `destination contact "${destinationDoc._id}" required attribute "type" is undefined`;
+  }
+
+  if (sourceDoc._id === destinationDoc?._id) {
+    return `cannot move or merge contact that is itself`;
+  }
+};
+
+const getMergeViolations = (sourceDoc, destinationDoc) => {
+  if (!destinationDoc) {
+    return `destination doc cannot be found`;
+  }
+
+  if ([sourceDoc._id, destinationDoc._id].includes(HIERARCHY_ROOT)) {
+    return `cannot merge using id: "${HIERARCHY_ROOT}"`;
+  }
+
+  const sourceContactType = getContactType(sourceDoc);
+  const destinationContactType = getContactType(destinationDoc);
+  if (sourceContactType !== destinationContactType) {
+    return `source and destinations must have the same type. Source is "${sourceContactType}" while destination is "${destinationContactType}".`;
+  }
+};
+
+/*
+A place's primary contact must be a descendant of that place.
+
+1. Check to see which part of the contact's lineage will be removed
+2. For each removed part of the contact's lineage, confirm that place's primary contact isn't being removed.
+*/
+const getPrimaryContactViolations = async (db, contactDoc, destinationDoc, descendantDocs) => {
+  const contactsLineageIds = lineageManipulation.pluckIdsFromLineage(contactDoc?.parent);
+  const parentsLineageIds = lineageManipulation.pluckIdsFromLineage(destinationDoc);
+
+  const docIdsRemovedFromContactLineage = contactsLineageIds.filter(value => !parentsLineageIds.includes(value));
+  const docsRemovedFromContactLineage = await db.allDocs({
+    keys: docIdsRemovedFromContactLineage,
+    include_docs: true,
+  });
+
+  const primaryContactIds = docsRemovedFromContactLineage.rows
+    .map(row => row?.doc?.contact?._id)
+    .filter(Boolean);
+  
+  return descendantDocs.find(descendant => primaryContactIds.some(primaryId => descendant._id === primaryId));
+};
+
+const getContactType = doc => doc && (doc.type === 'contact' ? doc.contact_type : doc.type);
+
+async function fetchAllowedParents(db) {
+  try {
+    const { settings: { contact_types } } = await db.get('settings');
+
+    if (Array.isArray(contact_types)) {
+      trace('Found app_settings.contact_types. Configurable hierarchy constraints will be enforced.');
+      const parentDict = {};
+      contact_types
+        .filter(Boolean)
+        .forEach(({ id, parents }) => parentDict[id] = parents);
+      return parentDict;
+    }
+  } catch (err) {
+    if (err.status !== 404) {
+      throw err;
+    }
+  }
+
+  trace('Default hierarchy constraints will be enforced.');
+  return {
+    district_hospital: [],
+    health_center: ['district_hospital'],
+    clinic: ['health_center'],
+    person: ['district_hospital', 'health_center', 'clinic'],
+  };
+}
+

package/src/lib/hierarchy-operations/lineage-manipulation.js

@@ -0,0 +1,63 @@
+const { replaceContactLineage, replaceParentLineage } = require('./replace-lineage');
+
+/*
+Function borrowed from shared-lib/lineage
+*/
+const minifyLineagesInDoc = doc => {
+  const minifyLineage = lineage => {
+    if (!lineage?._id) {
+      return;
+    }
+
+    return {
+      _id: lineage._id,
+      parent: minifyLineage(lineage.parent),
+    };
+  };
+
+  if (!doc) {
+    return;
+  }
+  
+  if ('parent' in doc) {
+    doc.parent = minifyLineage(doc.parent);
+  }
+  
+  if ('contact' in doc) {
+    doc.contact = minifyLineage(doc.contact);
+  }
+
+  if (doc.type === 'data_record') {
+    delete doc.patient;
+  }
+};
+
+const createLineageFromDoc = doc => {
+  if (!doc) {
+    return undefined;
+  }
+
+  return {
+    _id: doc._id,
+    parent: doc.parent || undefined,
+  };
+};
+
+/*
+Given a lineage, return the ids therein
+*/
+const pluckIdsFromLineage = (lineage, results = []) => {
+  if (!lineage) {
+    return results;
+  }
+
+  return pluckIdsFromLineage(lineage.parent, [...results, lineage._id]);
+};
+
+module.exports = {
+  createLineageFromDoc,
+  minifyLineagesInDoc,
+  pluckIdsFromLineage,
+  replaceParentLineage,
+  replaceContactLineage,
+};

package/src/lib/hierarchy-operations/replace-lineage.js

@@ -0,0 +1,76 @@
+function replaceLineage(doc, lineageAttributeName, params) {
+  // Replace the full lineage
+  if (!params.startingFromId) {
+    return replaceEntireLineage(doc, lineageAttributeName, params.replaceWith);
+  }
+
+  const selectedFunction = params.merge ? replaceLineageForMerge : replaceLineageForMove;
+  return selectedFunction(doc, lineageAttributeName, params);
+}
+
+function replaceLineageForMove(doc, lineageAttributeName, params) {
+  let currentElement = doc[lineageAttributeName];
+  while (currentElement) {
+    if (currentElement?._id === params.startingFromId) {
+      return replaceEntireLineage(currentElement, 'parent', params.replaceWith);
+    }
+
+    currentElement = currentElement.parent;
+  }
+
+  return false;
+}
+
+function replaceLineageForMerge(doc, lineageAttributeName, params) {
+  let currentElement = doc;
+  let currentAttributeName = lineageAttributeName;
+  while (currentElement) {
+    if (currentElement[currentAttributeName]?._id === params.startingFromId) {
+      return replaceEntireLineage(currentElement, currentAttributeName, params.replaceWith);
+    }
+
+    currentElement = currentElement[currentAttributeName];
+    currentAttributeName = 'parent';
+  }
+
+  return false;
+}
+
+function replaceEntireLineage(replaceInDoc, lineageAttributeName, replaceWith) {
+  if (!replaceWith) {
+    const lineageWasDeleted = !!replaceInDoc[lineageAttributeName];
+    replaceInDoc[lineageAttributeName] = undefined;
+    return lineageWasDeleted;
+  }
+
+  replaceInDoc[lineageAttributeName] = replaceWith;
+  return true;
+}
+
+module.exports = {
+/**
+ * Given a doc, replace the parent's lineage
+ * 
+ * @param {Object} doc A CouchDB document containing a parent lineage (eg. parent.parent._id) 
+ * @param {Object} params 
+ * @param {Object} params.replaceWith The new hierarchy { parent: { _id: 'parent', parent: { _id: 'grandparent' } }
+ * @param {string} params.startingFromId Only the part of the lineage "after" this id will be replaced
+ * @param {boolean} params.merge When true, startingFromId is replaced and when false, startingFromId's parent is replaced 
+ */
+  replaceParentLineage: (doc, params) => {
+    return replaceLineage(doc, 'parent', params);
+  },
+
+/**
+ * Given a doc, replace the contact's lineage
+ * 
+ * @param {Object} doc A CouchDB document containing a contact lineage (eg. contact.parent._id)
+ * @param {Object} params 
+ * @param {Object} params.replaceWith The new hierarchy { parent: { _id: 'parent', parent: { _id: 'grandparent' } }
+ * @param {string} params.startingFromId Only the part of the lineage "after" this id will be replaced
+ * @param {boolean} params.merge When true, startingFromId is replaced and when false, startingFromId's parent is replaced 
+ */
+  replaceContactLineage: (doc, params) => {
+    return replaceLineage(doc, 'contact', params);
+  },
+};

package/src/lib/user-prompt.js

@@ -1,5 +1,6 @@
 const environment = require('./environment');
 const readline = require('readline-sync');
+const { warn } = require('./log');
 
 
 /**
@@ -33,8 +34,16 @@ function keyInSelect(items, question, options = {}) {
   return readline.keyInSelect(items, question, options);
 }
 
+function warnPromptAbort(warningMessage) {
+  warn(warningMessage);
+  if (!keyInYN()) {
+    throw new Error('User aborted execution.');
+  }
+}
+
 module.exports = {
   keyInYN,
   question,
-  keyInSelect
+  keyInSelect,
+  warnPromptAbort,
 };

package/src/lib/lineage-constraints.js

@@ -1,94 +0,0 @@
-const log = require('./log');
-const { trace } = log;
-
-const { pluckIdsFromLineage } = require('./lineage-manipulation');
-
-const lineageConstraints = async (repository, parentDoc) => {
-  let mapTypeToAllowedParents;
-  try {
-    const { settings } = await repository.get('settings');
-    const { contact_types } = settings;
-
-    if (Array.isArray(contact_types)) {
-      trace('Found app_settings.contact_types. Configurable hierarchy constraints will be enforced.');
-      mapTypeToAllowedParents = contact_types
-        .filter(rule => rule)
-        .reduce((agg, curr) => Object.assign(agg, { [curr.id]: curr.parents }), {});
-    }
-  } catch (err) {
-    if (err.name !== 'not_found') {
-      throw err;
-    }
-  }
-
-  if (!mapTypeToAllowedParents) {
-    trace('Default hierarchy constraints will be enforced.');
-    mapTypeToAllowedParents = {
-      district_hospital: [],
-      health_center: ['district_hospital'],
-      clinic: ['health_center'],
-      person: ['district_hospital', 'health_center', 'clinic'],
-    };
-  }
-
-  return {
-    getHierarchyErrors: contactDoc => getHierarchyViolations(mapTypeToAllowedParents, contactDoc, parentDoc),
-    getPrimaryContactViolations: (contactDoc, descendantDocs) => getPrimaryContactViolations(repository, contactDoc, parentDoc, descendantDocs),
-  };
-};
-
-/*
-Enforce the list of allowed parents for each contact type
-Ensure we are not creating a circular hierarchy
-*/
-const getHierarchyViolations = (mapTypeToAllowedParents, contactDoc, parentDoc) => {
-  const getContactType = doc => doc && (doc.type === 'contact' ? doc.contact_type : doc.type);
-  const contactType = getContactType(contactDoc);
-  const parentType = getContactType(parentDoc);
-  if (!contactType) return 'contact required attribute "type" is undefined';
-  if (parentDoc && !parentType) return `parent contact "${parentDoc._id}" required attribute "type" is undefined`;
-  if (!mapTypeToAllowedParents) return 'hierarchy constraints are undefined';
-
-  const rulesForContact = mapTypeToAllowedParents[contactType];
-  if (!rulesForContact) return `cannot move contact with unknown type '${contactType}'`;
-
-  const isPermittedMoveToRoot = !parentDoc && rulesForContact.length === 0;
-  if (!isPermittedMoveToRoot && !rulesForContact.includes(parentType)) return `contacts of type '${contactType}' cannot have parent of type '${parentType}'`;
-
-  if (parentDoc && contactDoc._id) {
-    const parentAncestry = [parentDoc._id, ...pluckIdsFromLineage(parentDoc.parent)];
-    if (parentAncestry.includes(contactDoc._id)) {
-      return `Circular hierarchy: Cannot set parent of contact '${contactDoc._id}' as it would create a circular hierarchy.`;
-    }
-  }
-};
-
-/*
-A place's primary contact must be a descendant of that place.
-
-1. Check to see which part of the contact's lineage will be removed
-2. For each removed part of the contact's lineage, confirm that place's primary contact isn't being removed.
-*/
-const getPrimaryContactViolations = async (repository, contactDoc, parentDoc, descendantDocs) => {
-  const safeGetLineageFromDoc = doc => doc ? pluckIdsFromLineage(doc.parent) : [];
-  const contactsLineageIds = safeGetLineageFromDoc(contactDoc);
-  const parentsLineageIds = safeGetLineageFromDoc(parentDoc);
-
-  if (parentDoc) {
-    parentsLineageIds.push(parentDoc._id);
-  }
-
-  const docIdsRemovedFromContactLineage = contactsLineageIds.filter(value => !parentsLineageIds.includes(value));
-  const docsRemovedFromContactLineage = await repository.allDocs({
-    keys: docIdsRemovedFromContactLineage,
-    include_docs: true,
-  });
-
-  const primaryContactIds = docsRemovedFromContactLineage.rows
-    .map(row => row.doc && row.doc.contact && row.doc.contact._id)
-    .filter(id => id);
-  
-  return descendantDocs.find(descendant => primaryContactIds.some(primaryId => descendant._id === primaryId));
-};
-
-module.exports = lineageConstraints;

package/src/lib/lineage-manipulation.js

@@ -1,107 +0,0 @@
-
-/*
-Given a doc, replace the lineage information therein with "replaceWith"
-
-startingFromIdInLineage (optional) - Will result in a partial replacement of the lineage. Only the part of the lineage "after" the parent
-with _id=startingFromIdInLineage will be replaced by "replaceWith"
-*/
-const replaceLineage = (doc, lineageAttributeName, replaceWith, startingFromIdInLineage) => {
-  const handleReplacement = (replaceInDoc, docAttr, replaceWith) => {
-    if (!replaceWith) {
-      const lineageWasDeleted = !!replaceInDoc[docAttr];
-      replaceInDoc[docAttr] = undefined;
-      return lineageWasDeleted;
-    } else if (replaceInDoc[docAttr]) {
-      replaceInDoc[docAttr]._id = replaceWith._id;
-      replaceInDoc[docAttr].parent = replaceWith.parent;
-    } else {
-      replaceInDoc[docAttr] = replaceWith;
-    }
-
-    return true;
-  };
-
-  // Replace the full lineage
-  if (!startingFromIdInLineage) {
-    return handleReplacement(doc, lineageAttributeName, replaceWith);
-  }
-
-  // Replace part of a lineage
-  let currentParent = doc[lineageAttributeName];
-  while (currentParent) {
-    if (currentParent._id === startingFromIdInLineage) {
-      return handleReplacement(currentParent, 'parent', replaceWith);
-    }
-    currentParent = currentParent.parent;
-  }
-
-  return false;
-};
-
-/*
-Function borrowed from shared-lib/lineage
-*/
-const minifyLineagesInDoc = doc => {
-  const minifyLineage = lineage => {
-    if (!lineage || !lineage._id) {
-      return undefined;
-    }
-
-    const result = {
-      _id: lineage._id,
-      parent: minifyLineage(lineage.parent),
-    };
-
-    return result;
-  };
-
-  if (!doc) {
-    return undefined;
-  }
-  
-  if ('parent' in doc) {
-    doc.parent = minifyLineage(doc.parent);
-  }
-  
-  if ('contact' in doc) {
-    doc.contact = minifyLineage(doc.contact);
-    if (doc.contact && !doc.contact.parent) delete doc.contact.parent; // for unit test clarity
-  }
-
-  if (doc.type === 'data_record') {
-    delete doc.patient;
-  }
-};
-
-const createLineageFromDoc = doc => {
-  if (!doc) {
-    return undefined;
-  }
-
-  return {
-    _id: doc._id,
-    parent: doc.parent || undefined,
-  };
-};
-
-/*
-Given a lineage, return the ids therein
-*/
-const pluckIdsFromLineage = lineage => {
-  const result = [];
-
-  let current = lineage;
-  while (current) {
-    result.push(current._id);
-    current = current.parent;
-  }
-
-  return result;
-};
-
-module.exports = {
-  createLineageFromDoc,
-  minifyLineagesInDoc,
-  pluckIdsFromLineage,
-  replaceLineage,
-};