cht-conf 3.10.2 → 3.12.0

package/src/lib/upload-forms.js

@@ -13,21 +13,41 @@ const {
   readTitleFrom,
   readIdFrom
 } = require('./forms-utils');
-const validateForms = require('./validate-forms');
 
 const SUPPORTED_PROPERTIES = ['context', 'icon', 'title', 'xml2sms', 'subject_key', 'hidden_fields'];
+const FORM_EXTENSTION = '.xml';
+const FORM_PROPERTIES_EXTENSION = '.properties.json';
+const FORM_MEDIA_MATCHER = /(.+)-media$/;
+const SUPPORTED_EXTENSIONS = [FORM_EXTENSTION, FORM_PROPERTIES_EXTENSION];
+
+const formFileMatcher = (fileName) => {
+  if (fileName.endsWith(FORM_EXTENSTION)) {
+    return fileName.slice(0, fileName.length - FORM_EXTENSTION.length);
+  }
+  if (fileName.endsWith(FORM_PROPERTIES_EXTENSION)) {
+    return fileName.slice(0, fileName.length - FORM_PROPERTIES_EXTENSION.length);
+  }
+  return null;
+};
+
+const formMediaMatcher = (formMediaDir) => {
+  const matchResult = formMediaDir.match(FORM_MEDIA_MATCHER);
+  if (matchResult) {
+    return matchResult[1]; // return the captured form name
+  }
+  return null;
+};
 
-module.exports = async (projectDir, subDirectory, options) => {
-  await validateForms(projectDir, subDirectory, options);
+const execute = async (projectDir, subDirectory, options) => {
   const db = pouch();
   if (!options) options = {};
   const formsDir = getFormDir(projectDir, subDirectory);
-  if(!fs.exists(formsDir)) {
+  if (!fs.exists(formsDir)) {
     log.info(`Forms dir not found: ${formsDir}`);
     return;
   }
 
-  const fileNames = argsFormFilter(formsDir, '.xml', options);
+  const fileNames = argsFormFilter(formsDir, FORM_EXTENSTION, options);
   for (const fileName of fileNames) {
     log.info(`Preparing form for upload: ${fileName}…`);
 
@@ -35,7 +55,7 @@ module.exports = async (projectDir, subDirectory, options) => {
     const baseDocId = (options.id_prefix || '') + baseFileName.replace(/-/g, ':');
 
     const mediaDirExists = fs.exists(mediaDir);
-    if(!mediaDirExists) {
+    if (!mediaDirExists) {
       log.info(`No media directory found at ${mediaDir} for form ${xformPath}`);
     }
 
@@ -48,7 +68,7 @@ module.exports = async (projectDir, subDirectory, options) => {
     };
 
     const internalId = readIdFrom(xml);
-    if(internalId !== baseDocId) log.warn('DEPRECATED', 'Form:', fileName, 'Bad ID set in XML.  Expected:', baseDocId, 'but saw:', internalId, ' Support for setting these values differently will be dropped.  Please see https://github.com/medic/cht-core/issues/3342.');
+    if (internalId !== baseDocId) log.warn('DEPRECATED', 'Form:', fileName, 'Bad ID set in XML.  Expected:', baseDocId, 'but saw:', internalId, ' Support for setting these values differently will be dropped.  Please see https://github.com/medic/cht-core/issues/3342.');
 
     const docId = `form:${baseDocId}`;
     const doc = {
@@ -60,7 +80,7 @@ module.exports = async (projectDir, subDirectory, options) => {
       context: options.default_context,
     };
 
-    const propertiesPath = `${formsDir}/${baseFileName}.properties.json`;
+    const propertiesPath = `${formsDir}/${baseFileName}${FORM_PROPERTIES_EXTENSION}`;
     updateFromPropertiesFile(doc, propertiesPath);
 
     doc._attachments = mediaDirExists ? attachmentsFromDir(mediaDir) : {};
@@ -80,6 +100,14 @@ module.exports = async (projectDir, subDirectory, options) => {
   }
 };
 
+module.exports = {
+  SUPPORTED_EXTENSIONS,
+  FORM_MEDIA_MATCHER,
+  formFileMatcher,
+  formMediaMatcher,
+  execute
+};
+
 const updateFromPropertiesFile = (doc, path) => {
   if (fs.exists(path)) {
 

package/src/lib/validate-forms.js

@@ -1,64 +1,82 @@
-const api = require('./api');
 const argsFormFilter = require('./args-form-filter');
+const environment = require('./environment');
 const fs = require('./sync-fs');
 const log = require('./log');
 const {
   getFormDir,
-  getFormFilePaths,
-  formHasInstanceId
+  getFormFilePaths
 } = require('./forms-utils');
 
+const VALIDATIONS_PATH = fs.path.resolve(__dirname, './validation/form');
+const validations = fs.readdir(VALIDATIONS_PATH)
+  .filter(name => name.endsWith('.js'))
+  .map(validationName => {
+    const validation = require(fs.path.join(VALIDATIONS_PATH, validationName));
+    validation.name = validationName;
+    if(!Object.hasOwnProperty.call(validation, 'requiresInstance')) {
+      validation.requiresInstance = true;
+    }
+    if(!Object.hasOwnProperty.call(validation, 'skipFurtherValidation')) {
+      validation.skipFurtherValidation = false;
+    }
+
+    return validation;
+  })
+  .sort((a, b) => {
+    if(a.skipFurtherValidation && !b.skipFurtherValidation) {
+      return -1;
+    }
+    if(!a.skipFurtherValidation && b.skipFurtherValidation) {
+      return 1;
+    }
+    return a.name.localeCompare(b.name);
+  });
+
 module.exports = async (projectDir, subDirectory, options={}) => {
 
   const formsDir = getFormDir(projectDir, subDirectory);
   if(!formsDir) {
-    log.info(`Forms dir not found: ${formsDir}`);
+    log.info(`Forms dir not found: ${projectDir}/forms/${subDirectory}`);
     return;
   }
 
-  let idValidationsPassed = true;
-  let validateFormsPassed = true;
+  const instanceProvided = environment.apiUrl;
+  let validationSkipped = false;
 
   const fileNames = argsFormFilter(formsDir, '.xml', options);
-  for (const fileName of fileNames) {
+
+  let errorFound = false;
+  for(const fileName of fileNames) {
     log.info(`Validating form: ${fileName}…`);
 
-    const { xformPath, filePath } = getFormFilePaths(formsDir, fileName);
+    const { xformPath } = getFormFilePaths(formsDir, fileName);
     const xml = fs.read(xformPath);
 
-    if(!formHasInstanceId(xml)) {
-      log.error(`Form at ${xformPath} appears to be missing <meta><instanceID/></meta> node. This form will not work on CHT webapp.`);
-      idValidationsPassed = false;
-      continue;
-    }
-    try {
-      await _formsValidate(xml);
-    } catch (err) {
-      log.error(`Error found while validating "${filePath}". Validation response: ${err.message}`);
-      validateFormsPassed = false;
+    const valParams = { xformPath, xmlStr: xml };
+    for(const validation of validations) {
+      if(validation.requiresInstance && !instanceProvided) {
+        validationSkipped = true;
+        continue;
+      }
+
+      const output = await validation.execute(valParams);
+      if(output.warnings) {
+        output.warnings.forEach(warnMsg => log.warn(warnMsg));
+      }
+      if(output.errors && output.errors.length) {
+        output.errors.forEach(errorMsg => log.error(errorMsg));
+        errorFound = true;
+        if(validation.skipFurtherValidation) {
+          break;
+        }
+      }
     }
   }
-  // Once all the fails were checked raise an exception if there were errors
-  let errors = [];
-  if (!validateFormsPassed) {
-    errors.push('One or more forms appears to have errors found by the API validation endpoint.');
-  }
-  if (!idValidationsPassed) {
-    errors.push('One or more forms appears to be missing <meta><instanceID/></meta> node.');
-  }
-  if (errors.length) {
-    // the blank spaces are a trick to align the errors in the log ;)
-    throw new Error(errors.join('\n             '));
-  }
-};
 
-let validateEndpointNotFoundLogged = false;
-const _formsValidate = async (xml) => {
-  const resp = await api().formsValidate(xml);
-  if (resp.formsValidateEndpointFound === false && !validateEndpointNotFoundLogged) {
-    log.warn('Form validation endpoint not found in your version of CHT Core, ' +
-      'no form will be checked before push');
-    validateEndpointNotFoundLogged = true; // Just log the message once
+  if(validationSkipped) {
+    log.warn('Some validations have been skipped because they require a CHT instance.');
+  }
+  if(errorFound) {
+    throw new Error('One or more forms have failed validation.');
   }
-  return resp;
 };

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

@@ -0,0 +1,32 @@
+# Form validations
+
+Form validations should be added to this directory.
+
+Their module should look something like this:
+
+```js
+module.exports = {
+  requiresInstance: false,
+  skipFurtherValidation: true,
+  execute: async ({ xformPath, xmlStr }) => {
+    ...
+  }
+};
+```
+
+## 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.                                                                                                                                          |
+
+## Result
+
+The result has the following format:
+
+| Field    | Notes                                                                                              |
+|----------|----------------------------------------------------------------------------------------------------|
+| warnings | Array containing the descriptions of any warnings.                                                 |
+| errors   | Array containing the descriptions of any errors. If this is empty, the form has passed validation. |

package/src/lib/validation/form/can-generate-xform.js

@@ -0,0 +1,18 @@
+const api = require('../../api');
+
+module.exports = {
+  execute: async ({ xformPath, xmlStr }) => {
+    const warnings = [];
+    const errors = [];
+    try {
+      const resp = await api().formsValidate(xmlStr);
+      if (resp.formsValidateEndpointFound === false) {
+        warnings.push('Form validation endpoint not found in your version of CHT Core, no form will be checked before push');
+      }
+    } catch (err) {
+      errors.push(`Error found while validating "${xformPath}". Validation response: ${err.message}`);
+    }
+
+    return { errors, warnings };
+  }
+};

package/src/lib/validation/form/has-instance-id.js

@@ -0,0 +1,14 @@
+const { formHasInstanceId } = require('../../forms-utils');
+
+module.exports = {
+  requiresInstance: false,
+  skipFurtherValidation: true,
+  execute: async({ xformPath, xmlStr }) => {
+    const errors = [];
+    if(!formHasInstanceId(xmlStr)) {
+      errors.push(`Form at ${xformPath} appears to be missing <meta><instanceID/></meta> node. This form will not work on CHT webapp.`);
+    }
+
+    return { errors, warnings: [] };
+  }
+};