cht-conf 6.5.2 → 6.6.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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)
 
 

package/package.json

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

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
+};