cht-conf 3.14.0 → 3.15.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [3.15.0](https://github.com/medic/cht-conf/compare/v3.14.0...v3.15.0) (2022-08-19)
+
+
+### Features
+
+* **#500:** Validate deprecated appearances in forms ([#501](https://github.com/medic/cht-conf/issues/501)) ([1e52c0c](https://github.com/medic/cht-conf/commit/1e52c0c769fbd27ee6a764358ef2a0463ae3023f)), closes [#500](https://github.com/medic/cht-conf/issues/500)
+
 # [3.14.0](https://github.com/medic/cht-conf/compare/v3.13.0...v3.14.0) (2022-08-18)
 
 

package/package.json

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

package/src/fn/upload-custom-translations.js

@@ -2,7 +2,7 @@ const semver = require('semver');
 
 const environment = require('../lib/environment');
 const pouch = require('../lib/db');
-const getApiVersion = require('../lib/get-api-version');
+const { getValidApiVersion } = require('../lib/get-api-version');
 const iso639 = require('iso-639-1');
 const log = require('../lib/log');
 const properties = require('properties');
@@ -168,9 +168,9 @@ function idFor(fileName) {
 }
 
 async function genericTranslationsStructure(db) {
-  const version = await getApiVersion();
+  const version = await getValidApiVersion();
 
-  if (semver.valid(version)) {
+  if (version) {
     return semver.gte(version, '3.4.0');
   }
 

package/src/lib/get-api-version.js

@@ -1,3 +1,5 @@
+const semver = require('semver');
+
 const api = require('./api');
 const db = require('./db');
 
@@ -15,4 +17,8 @@ const getApiVersion = async () => {
   return version;
 };
 
-module.exports = getApiVersion;
+const getValidApiVersion = async () => {
+  return semver.valid(await getApiVersion());
+};
+
+module.exports = { getValidApiVersion };

package/src/lib/validate-forms.js

@@ -1,5 +1,6 @@
 const { DOMParser } = require('@xmldom/xmldom');
 const argsFormFilter = require('./args-form-filter');
+const { getValidApiVersion } = require('./get-api-version');
 const environment = require('./environment');
 const fs = require('./sync-fs');
 const log = require('./log');
@@ -43,6 +44,7 @@ module.exports = async (projectDir, subDirectory, options={}) => {
   }
 
   const instanceProvided = environment.apiUrl;
+  const apiVersion = instanceProvided ? await getValidApiVersion() : null;
   let validationSkipped = false;
 
   const fileNames = argsFormFilter(formsDir, '.xml', options);
@@ -54,7 +56,12 @@ module.exports = async (projectDir, subDirectory, options={}) => {
     const { xformPath } = getFormFilePaths(formsDir, fileName);
     const xml = fs.read(xformPath);
 
-    const valParams = { xformPath, xmlStr: xml, xmlDoc: domParser.parseFromString(xml) };
+    const valParams = {
+      xformPath,
+      xmlStr: xml,
+      xmlDoc: domParser.parseFromString(xml),
+      apiVersion,
+    };
     for(const validation of validations) {
       if(validation.requiresInstance && !instanceProvided) {
         validationSkipped = true;

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

@@ -8,7 +8,7 @@ Their module should look something like this:
 module.exports = {
   requiresInstance: false,
   skipFurtherValidation: true,
-  execute: async ({ xformPath, xmlStr }) => {
+  execute: async ({ xformPath, xmlStr, xmlDoc, apiVersion }) => {
     ...
   }
 };
@@ -16,11 +16,11 @@ module.exports = {
 
 ## Module Exports
 
-| Field                   | Required                       | Notes                                                                                                                                                                                                                                                        |
-|-------------------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `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`               | Required                       | The function that is run when the validation is executed. The provided input argument contains the form XML string.                                                                                                                                          |
+| Field                   | Required                       | Notes                                                                                                                                                                                                                                                                                                                             |
+|-------------------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `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`  |
 
 ## Result
 

package/src/lib/validation/form/deprecated-appearance.js

@@ -0,0 +1,87 @@
+const semver = require('semver');
+const { getNodes } = require('../../forms-utils');
+
+// Based on https://forum.getodk.org/t/spec-proposal-harmonize-compact-compact-n-horizontal-horizontal-compact-appearances/15565/32
+// Note the order of evaluation is important
+const getDeprecatedAppearances = (apiVersion) => [
+  {
+    match: appearance => appearance.match(/(?:^|\s)horizontal-compact(?:$|\s)/),
+    getReplacement: () => 'columns-pack',
+    versionDeprecated: '4.0.0'
+  },
+  {
+    match: appearance => appearance.match(/(?:^|\s)horizontal(?:$|\s)/),
+    getReplacement: () => 'columns',
+    versionDeprecated: '4.0.0'
+  },
+  {
+    match: appearance => appearance.match(/(?:^|\s)compact-(\d{1,2})(?:$|\s)/),
+    getReplacement: (match) => `columns-${match[1].trim()} no-buttons`,
+    versionDeprecated: '4.0.0'
+  },
+  {
+    match: appearance => appearance.match(/(?:^|\s)compact(?:$|\s)/),
+    getReplacement: () => 'columns-pack no-buttons',
+    versionDeprecated: '4.0.0'
+  },
+].filter(deprecatedAppearance => semver.gte(apiVersion, deprecatedAppearance.versionDeprecated));
+
+const getElementsWithAppearance = (xmlDoc) => getNodes(xmlDoc, '/h:html/h:body//*[@appearance]');
+
+const unpackDeprecationAttributes = element => ({
+  ref: element.getAttribute('ref'),
+  appearance: element.getAttribute('appearance'),
+});
+
+const hasAppearance = ({ appearance }) => appearance;
+
+const populateDeprecatedAppearance = deprecatedAppearances => ({ ref, appearance }) => ({
+  ref,
+  appearance,
+  // Only warning for the first deprecated appearance found for an element. This seems acceptable.
+  deprecatedAppearance: deprecatedAppearances.find(depAppearance => depAppearance.match(appearance))
+});
+
+const hasDeprecatedAppearance = ({ deprecatedAppearance }) => deprecatedAppearance;
+
+const createWarning = ({ ref, appearance, deprecatedAppearance }) => {
+  const match = deprecatedAppearance.match(appearance);
+  const originalAppearance = match[0].trim();
+  const newAppearance = deprecatedAppearance.getReplacement(match);
+  return `  - ${ref}: replace [${originalAppearance}] with [${newAppearance}]`;
+};
+
+const populateWarningHeader = (xformPath, warnings) => {
+  if (warnings.length) {
+    warnings.unshift(`Form at ${xformPath} contains fields with the deprecated \`horizontal\`/\`compact\` appearance. ` +
+      'These have been deprecated in favor of the `columns` appearance. Please update the following fields:');
+  }
+};
+
+const validateDeprecatedAppearances = async({ xformPath, xmlDoc, apiVersion }) => {
+  if (!apiVersion) {
+    return { warnings: [], errors: [], };
+  }
+
+  const deprecatedAppearances = getDeprecatedAppearances(apiVersion);
+  if (!deprecatedAppearances.length) {
+    return { warnings: [], errors: [], };
+  }
+
+  const warnings = getElementsWithAppearance(xmlDoc)
+    .map(unpackDeprecationAttributes)
+    .filter(hasAppearance)
+    .map(populateDeprecatedAppearance(deprecatedAppearances))
+    .filter(hasDeprecatedAppearance)
+    .map(createWarning);
+
+  populateWarningHeader(xformPath, warnings);
+
+  return { errors: [], warnings };
+};
+
+module.exports = {
+  requiresInstance: true,
+  skipFurtherValidation: false,
+  execute: validateDeprecatedAppearances
+};