cht-conf 5.2.1 → 5.4.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [5.4.0](https://github.com/medic/cht-conf/compare/v5.3.0...v5.4.0) (2025-09-11)
+
+
+### Features
+
+* **#561:** add form validation for `instance::db-doc-ref` ([#738](https://github.com/medic/cht-conf/issues/738)) ([941a6f5](https://github.com/medic/cht-conf/commit/941a6f5b7504d6ff8c1682845d6e38efd6ea017b)), closes [#561](https://github.com/medic/cht-conf/issues/561)
+
+# [5.3.0](https://github.com/medic/cht-conf/compare/v5.2.1...v5.3.0) (2025-09-04)
+
+
+### Features
+
+* **#512:** add form validation for instance::db-doc ([#737](https://github.com/medic/cht-conf/issues/737)) ([0db687e](https://github.com/medic/cht-conf/commit/0db687eb8f2c5dbb6a2d2e387857af50af81a917)), closes [#512](https://github.com/medic/cht-conf/issues/512)
+
 ## [5.2.1](https://github.com/medic/cht-conf/compare/v5.2.0...v5.2.1) (2025-08-27)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cht-conf",
-  "version": "5.2.1",
+  "version": "5.4.0",
   "description": "Configure CHT deployments",
   "main": "./src/lib/main.js",
   "engines": {
@@ -92,6 +92,6 @@
     "pouchdb-adapter-memory": "^9.0.0",
     "rewire": "^8.0.0",
     "semantic-release": "^24.2.4",
-    "sinon": "^19.0.2"
+    "sinon": "^21.0.0"
   }
 }

package/src/lib/forms-utils.js

@@ -9,6 +9,14 @@ const getNode = (currentNode, path) =>
 const getNodes = (currentNode, path) =>
   xpath.parse(path).select({ node: currentNode, allowAnyNamespaceForNoPrefix: true });
 
+const getFullNodePath = (childNode) => {
+  if (childNode.nodeType !== 1) {
+    return '';
+  }
+  const parentPath = getFullNodePath(childNode.parentNode);
+  return parentPath + '/' + childNode.nodeName;
+};
+
 module.exports = {
   /**
    * Get the full path of the form, or null if the path doesn't exist.
@@ -68,6 +76,15 @@ module.exports = {
    */
   getPrimaryInstanceNode: xmlDoc => getNode(xmlDoc, `${XPATH_MODEL}/instance`),
 
+  /**
+   * Returns the path to the given child node relative to the primary instance node.
+   * This is useful for identifying the node in error/warning messages.
+   * @param childNode the child node
+   * @returns {string}
+   */
+  getPrimaryInstanceNodeChildPath: (childNode) => getFullNodePath(childNode)
+    .replace(`${XPATH_MODEL}/instance`, ''),
+
   /**
    * Check whether the XForm has the <instanceID/> tag.
    * @param {string} xmlDoc the XML document

package/src/lib/validation/form/db-doc-is-valid.js

@@ -0,0 +1,26 @@
+const { getPrimaryInstanceNode, getNodes, getPrimaryInstanceNodeChildPath } = require('../../forms-utils');
+
+module.exports = {
+  requiresInstance: false,
+  execute: async ({ xmlDoc, xformPath }) => {
+    const errors = [];
+    const primaryInstance = getPrimaryInstanceNode(xmlDoc);
+    const dbDocNodes = getNodes(xmlDoc, '//*[@db-doc="true"]', primaryInstance);
+    dbDocNodes.forEach(node => {
+      const childNodes = node.childNodes.filter(n => n.nodeType === 1);
+      if (!childNodes.length) {
+        const nodeName = getPrimaryInstanceNodeChildPath(node);
+        errors.push(`  - ${nodeName}: the db-doc attribute must only be set on groups.`);
+        return;
+      }
+      const hasTypeField = childNodes.some(child => child.nodeName === 'type');
+      if (!hasTypeField) {
+        const nodeName = getPrimaryInstanceNodeChildPath(node);
+        errors.push(`  - ${nodeName}: groups configured with the db-doc attribute must contain a valid type field.`);
+      }
+    });
+
+    const header = `Form at ${xformPath} contains invalid db-doc configuration:`;
+    return { errors: errors.length ? [header, ...errors]: errors };
+  }
+};

package/src/lib/validation/form/db-doc-ref-is-valid.js

@@ -0,0 +1,28 @@
+const { getPrimaryInstanceNode, getNodes, getNode, getPrimaryInstanceNodeChildPath } = require('../../forms-utils');
+
+module.exports = {
+  requiresInstance: false,
+  execute: ({ xmlDoc, xformPath }) => {
+    const errors = [];
+    const primaryInstance = getPrimaryInstanceNode(xmlDoc);
+    const formRootNode = Array
+      .from(primaryInstance.childNodes)
+      .find(n => n.nodeType === 1);
+    const refNodes = getNodes(xmlDoc, '//*[@db-doc-ref]', primaryInstance);
+    refNodes.forEach(node => {
+      const refPath = node
+        .getAttribute('db-doc-ref')
+        .trim()
+        .replace(/^\//, '');
+      const targetNode = getNode(primaryInstance, refPath);
+      if (!targetNode || (targetNode !== formRootNode && targetNode.getAttribute('db-doc') !== 'true')) {
+        const nodeName = getPrimaryInstanceNodeChildPath(node);
+        errors.push(`  - ${nodeName}: the db-doc-ref value [${refPath}] does not reference a valid doc node.`);
+      }
+    });
+
+    const header = `Form at ${xformPath} contains invalid db-doc-ref configuration. A db-doc-ref value should point `
+      + `to either the root node of the form or to a group that is adding a new doc (with db-doc set to "true"):`;
+    return { errors: errors.length ? [header, ...errors]: errors };
+  },
+};