cht-conf 6.5.1 → 6.6.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [6.6.0](https://github.com/medic/cht-conf/compare/v6.5.2...v6.6.0) (2026-08-21)
+
+
+### Features
+
+* **#804:** support linting form field paths during validation ([#805](https://github.com/medic/cht-conf/issues/805)) ([30853a7](https://github.com/medic/cht-conf/commit/30853a795658e626a533871d67023be91ada7801)), closes [#804](https://github.com/medic/cht-conf/issues/804)
+
+## [6.5.2](https://github.com/medic/cht-conf/compare/v6.5.1...v6.5.2) (2026-08-10)
+
+
+### Bug Fixes
+
+* **#832:** fix contact form xml parsing when init has sub-group ([#835](https://github.com/medic/cht-conf/issues/835)) ([e4a11ce](https://github.com/medic/cht-conf/commit/e4a11ced5a48019718299600a122fcd70067b38a))
+
 ## [6.5.1](https://github.com/medic/cht-conf/compare/v6.5.0...v6.5.1) (2026-07-15)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cht-conf",
-  "version": "6.5.1",
+  "version": "6.6.0",
   "description": "Configure CHT deployments",
   "main": "./src/lib/main.js",
   "engines": {

package/src/fn/convert-contact-forms.js

@@ -2,6 +2,23 @@ const convertForms = require('../lib/convert-forms').execute;
 const environment = require('../lib/environment');
 const fs = require('../lib/sync-fs');
 const { CONTACT_FORMS_PATH } = require('../lib/project-paths');
+const { getNode, XPATH_BODY } = require('../lib/forms-utils');
+
+const getBodyGroup = (xmlDoc, ref) => getNode(xmlDoc, `${XPATH_BODY}//group[@ref="${ref}"]`);
+
+/**
+ * Renders the contact fields on the init page instead of on a page of their own, by making the
+ * <contact> body group the last child of the <init> group. Only the body group is moved: the
+ * contact data must stay at /data/contact for the webapp to save the doc correctly.
+ */
+const moveContactGroupIntoInit = (xmlDoc) => {
+  const initGroup = getBodyGroup(xmlDoc, '/data/init');
+  const contactGroup = getBodyGroup(xmlDoc, '/data/contact');
+
+  if (initGroup && contactGroup) {
+    initGroup.appendChild(contactGroup);
+  }
+};
 
 const convertContactForm = (forms) => {
   const dir = `${environment.pathToProject}/${CONTACT_FORMS_PATH}`;
@@ -20,6 +37,7 @@ const convertContactForm = (forms) => {
   return convertForms(environment.pathToProject, 'contact', {
     enketo: true,
     forms: forms,
+    domTransformer: moveContactGroupIntoInit,
     transformer: (xml, path) => {
       const type = path.replace(/.*\/(.*?)(-(create|edit))?\.xml.swp$/, '$1');
 
@@ -60,27 +78,6 @@ const convertContactForm = (forms) => {
         }
       }
 
-      if (xml.includes('ref="/data/contact"')) {
-        const groupRegex = name => new RegExp(`(\\s*)<group(\\s.*)?\\sref="${name}"(\\s.*)?>[^]*?</group>`);
-        let matchedBlock;
-
-        if (xml.match(groupRegex('/data/init'))) {
-          xml = xml.replace(groupRegex('/data/contact'), match => {
-            matchedBlock = match;
-            return '';
-          });
-
-          if (matchedBlock) {
-            const stripTrailingGroup = s => s.replace(/[\r\n\s]*<\/group>$/, '');
-            xml = xml.replace(groupRegex('/data/init'), match => {
-              return stripTrailingGroup(match) +
-                stripTrailingGroup(matchedBlock).replace(/\n/g, '\n  ') +
-                '\n        </group>\n      </group>';
-            });
-          }
-        }
-      }
-
       return xml;
     },
   });

package/src/lib/convert-forms/index.js

@@ -53,7 +53,7 @@ const execute = async (projectDir, subDirectory, options = {}) => {
     try {
       await xls2xform(escapeWhitespacesInPath(sourcePath), escapeWhitespacesInPath(xmlSwpPath), xls);
       const hiddenFields = await getHiddenFields(`${fs.withoutExtension(sourcePath)}.properties.json`);
-      fixXml(xmlSwpPath, hiddenFields, options.transformer, options.enketo);
+      fixXml(xmlSwpPath, hiddenFields, options);
     } catch (e) {
       nodeFs.rmSync(xmlSwpPath, { force: true });
       throw e;
@@ -123,7 +123,7 @@ const xls2xform = async (sourcePath, targetPath, xlsxFileName) => {
 
 // here we fix the form content in arcane ways.  Seeing as we have out own fork
 // of pyxform, we should probably be doing this fixing there.
-const fixXml = (path, hiddenFields, transformer, enketo) => {
+const fixXml = (path, hiddenFields, { transformer, domTransformer, enketo } = {}) => {
   // This is not how you should modify XML, but we have reasonable control over
   // the input and so far this works OK.  Keep an eye on the tests, and any
   // future changes to the output of xls2xform.
@@ -159,6 +159,10 @@ const fixXml = (path, hiddenFields, transformer, enketo) => {
   addRepeatCount(xmlDoc);
   handleDbDocRefs(xmlDoc);
 
+  if (domTransformer) {
+    domTransformer(xmlDoc, path);
+  }
+
   const xmlString = serializer.serializeToString(xmlDoc);
   xml = xmlFormat(xmlString, {
     collapseContent: true,

package/src/lib/forms-utils.js

@@ -81,9 +81,11 @@ module.exports = {
   /**
    * Returns the `bind` nodes for the given form XML.
    * @param {Document} xmlDoc the form XML document
+   * @param {string} filter the form XML bind nodes (optional). 
+   *  Example: [not(@nodeset = "/data/inputs/user/contact_id")]
    * @returns {Element}
    */
-  getBindNodes: xmlDoc => getNodes(xmlDoc, `${XPATH_MODEL}/bind`),
+  getBindNodes: (xmlDoc, filter = '') => getNodes(xmlDoc, `${XPATH_MODEL}/bind${filter}`),
 
   /**
    * Returns the `instance` node with the given ID for the given form XML.

package/src/lib/validate-forms.js

@@ -35,6 +35,14 @@ const validations = fs.readdir(VALIDATIONS_PATH)
     return a.name.localeCompare(b.name);
   });
 
+const getPropsData = (propsJson) => {
+  if(!fs.exists(propsJson) || !fs.statSync(propsJson).isFile()){
+    return {};
+  }
+
+  return fs.readJson(propsJson) || {};
+};
+
 module.exports = async (projectDir, subDirectory, options={}) => {
 
   const formsDir = getFormDir(projectDir, subDirectory);
@@ -53,13 +61,15 @@ module.exports = async (projectDir, subDirectory, options={}) => {
   for(const fileName of fileNames) {
     log.info(`Validating form: ${fileName}…`);
 
-    const { xformPath } = getFormFilePaths(formsDir, fileName);
+    const { xformPath, baseFileName } = getFormFilePaths(formsDir, fileName);
     const xml = fs.read(xformPath);
+    const propsData = getPropsData(`${formsDir}/${baseFileName}.properties.json`);
 
     const valParams = {
       xformPath,
       xmlStr: xml,
       xmlDoc: domParser.parseFromString(xml),
+      propsData,
       apiVersion,
     };
     for(const validation of validations) {

package/src/lib/validation/form/README.md

@@ -20,7 +20,7 @@ module.exports = {
 |-------------------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `requiresInstance`      | Optional, defaults to `true`   | The validation needs the user to have provided a instance location, e.g. via `--local` or `--instance`                                                                                                                                                                                                                            |
 | `skipFurtherValidation` | Optional, defaults to `false`  | When `true`, additional validations will not be performed on a form that fails the current validation. The goal is to avoid unnecessary noise in the validation log for forms that are grossly invalid (e.g. XML files that are not actually xForms at all).                                                                      |
-| `execute(opts)`         | Required                       | The function that is run when the validation is executed. The available ops are:<br>* `xformPath` - the file path to the form<br>* `xmlStr` - string value of the form XML<br>* `xmlDoc` - Document value of the form XML<br>* `apiVersion` - the version of the CHT instance (if connection information was provided) or `null`  |
+| `execute(opts)`         | Required                       | The function that is run when the validation is executed. The available ops are:<br>* `xformPath` - the file path to the form<br>* `xmlStr` - string value of the form XML<br>* `xmlDoc` - Document value of the form XML<br>* `propsData` - JSON contents of the form XML's properties file<br>* `apiVersion` - the version of the CHT instance (if connection information was provided) or `null`  |
 
 ## Result
 

package/src/lib/validation/form/validate-field-paths.js

@@ -0,0 +1,148 @@
+const { getBindNodes } = require('../../forms-utils');
+const joi = require('joi');
+
+const XML_ATT_NODESET = 'nodeset';
+
+const schema = joi.object({
+  warn_length: joi.number().integer().min(0).when('error_length', {
+    is: joi.number().required().greater(0),
+    then: joi.number().less(joi.ref('error_length')),
+  }).optional(),
+  error_length: joi.number().integer().min(0).optional(),
+  ignore_list: joi.array().items(joi.string().pattern(/[`'"]/, { invert: true })).optional().default([]),
+  reserved_list: joi.array().items(joi.string().pattern(/[`'"]/, { invert: true })).optional().default([]),
+});
+
+function formatFeedbackMsg(title, items, footer) {
+  return `${title}\n${items.join('\n')}\n${footer}`;
+}
+
+function checkListOverlap(ignoreList, reservedList) {
+  if (!ignoreList.length || !reservedList.length) {
+    return;
+  }
+
+  const reservedSet = new Set(reservedList);
+  const overlap = ignoreList.filter(x => reservedSet.has(x));
+
+  if (overlap.length > 0) {
+    throw new Error(formatFeedbackMsg(
+      'Overlap between reserved and ignore lists:',
+      overlap,
+      'Please remove where appropriate.'
+    ));
+  }
+}
+
+function validatePropDataOrThrow(props) {
+  const { error, value } = schema.validate(props, { abortEarly: false });
+  if (error) {
+    throw new Error(error.details.map(d => d.message).join('; '));
+  }
+  return value;
+}
+
+function buildPath(entry) {
+  return `/data/${entry.replace(/^\/?(data\/)?/, '')}`;
+}
+
+function unpackProps(props) {
+  const warnLength = props['warn_length'];
+  const errorLength = props['error_length'];
+  const ignoreList = props['ignore_list'].map(buildPath);
+  const reservedList = props['reserved_list'].map(buildPath);
+
+  return { warnLength, errorLength, ignoreList, reservedList };
+}
+
+function buildExclusionPath(list) {
+  if (!list.length) {
+    return '';
+  }
+  const conditions = list.map(v => `@${XML_ATT_NODESET} = "${v}"`).join(' or ');
+  return `[not(${conditions})]`;
+}
+
+function getFilteredBindNodes(xmlDoc, ignoreList) {
+  return getBindNodes(xmlDoc, buildExclusionPath(ignoreList));
+}
+
+function getPathsWithLength(bindNodePaths, targetLength) {
+  if (!targetLength) {
+    return [];
+  }
+
+  return bindNodePaths.filter(path => path.length >= targetLength);
+}
+
+function validateReservedNodes(bindNodePaths, reserved) {
+  const reservedNodes = bindNodePaths.filter(path => reserved.includes(path));
+  if (reservedNodes.length > 0) {
+    throw new Error(formatFeedbackMsg(
+      'The following reserved entries were found in the form:',
+      reservedNodes,
+      'Please remove or rename as appropriate.'
+    ));
+  }
+}
+
+function validateWarnLength(bindNodePaths, warnLength) {
+  const warnLengthPaths = getPathsWithLength(bindNodePaths, warnLength);
+  if (warnLengthPaths.length > 0) {
+    return formatFeedbackMsg(
+      `The following vars are longer than the acceptable var length (${warnLength}):`,
+      warnLengthPaths,
+      'Please consider simplifying nesting or removing verbosity.'
+    );
+  }
+}
+
+function validateErrorLength(bindNodePaths, errorLength) {
+  const errorLengthPaths = getPathsWithLength(bindNodePaths, errorLength);
+  if (errorLengthPaths.length > 0) {
+    throw new Error(formatFeedbackMsg(
+      `The following vars are longer than the acceptable var length (${errorLength}):`,
+      errorLengthPaths,
+      'Please simplify nesting or remove verbosity.'
+    ));
+  }
+}
+
+function validateFieldPaths(xmlDoc, props) {
+  const validatedProps = validatePropDataOrThrow(props);
+
+  const { warnLength, errorLength, ignoreList, reservedList } = unpackProps(validatedProps);
+
+  checkListOverlap(ignoreList, reservedList);
+  const bindNodes = getFilteredBindNodes(xmlDoc, ignoreList);
+  const bindNodePaths = bindNodes.map(node => node.getAttribute(XML_ATT_NODESET));
+  validateReservedNodes(bindNodePaths, reservedList);
+  validateErrorLength(bindNodePaths, errorLength);
+  const warning = validateWarnLength(bindNodePaths, warnLength);
+
+  return warning ? [ warning ] : [];
+}
+
+async function execute({ xmlDoc, propsData }) {
+  const warnings = [];
+  const errors = [];
+  try {
+    const fieldPathLinting = propsData.field_path_linting;
+    if (!fieldPathLinting || Object.keys(fieldPathLinting).length === 0) {
+      return { warnings, errors };
+    }
+
+    warnings.push(...validateFieldPaths(xmlDoc, fieldPathLinting));
+  }
+  catch (e) {
+    errors.push(e.message);
+  }
+
+  return { warnings, errors };
+}
+
+module.exports = {
+  requiresInstance: false,
+  skipFurtherValidation: false,
+  execute
+};