Add comments and Refactor lib/extensions.js

Co-authored-by: Hanna Laakso <hanna.laakso@digital.cabinet-office.gov.uk>

Author: Alistair Laing

lib/extensions/extensions.js

@@ -1,17 +1,72 @@
-// // Imports
+/**
+ * Extensions.js (Use with caution)
+ *
+ *  Experimental feature which is likely to change.
+ *  This file returns helper methods to enable services to include
+ *  their own departmental frontend(Styles, Scripts, nunjucks etc)
+ *
+ * Module.exports
+ *    getPublicUrls:
+ *      Params: (type | string ) eg. 'scripts', 'stylesheets'
+ *      Description:
+ *        returns array of urls for a type (script, stylesheet, nunjucks etc). do we need to expose this?
+ *    getFileSystemPaths:
+ *      Params: (type | string ) eg. 'scripts', 'stylesheets'
+ *      Description:
+ *        returns array paths to the file in the filesystem for a type (script, stylesheet, nunjucks etc) do we need to expose this?
+ *    getPublicUrlAndFileSystemPaths:
+ *      Params: (type | string ) eg. 'scripts', 'stylesheets'
+ *      Description:
+ *        returns Array of objects, each object is an extension and each obj has the filesystem & public url for the given type
+ *    getAppConfig:
+ *      Params: (type | string ) eg. 'scripts', 'stylesheets'
+ *      Description:
+ *        to do
+ *    getAppViews:
+ *      Params: (type | string ) eg. 'scripts', 'stylesheets'
+ *      Description:
+ *        To do
+ *    setExtensionsByType
+ *      Params: N/A
+ *      Description: only used for test purposes to reset mocked extensions items to ensure they are up-to-date when the tests run
+ *
+ * *
+ */
+
+// Core dependencies
 const fs = require('fs')
 const path = require('path')
+
+// Local dependencies
 const appConfig = require('../../app/config')
 
-// Utils
-const pathFromRoot = (...all) => path.join.apply(null, [__dirname, '..', '..'].concat(all))
-const pathToHookFile = packageName => pathFromRoot('node_modules', packageName, 'govuk-prototype-kit.config.json')
+// Generic utilities
+const removeDuplicates = arr => [...new Set(arr)]
+const filterOutParentAndEmpty = part => part && part !== '..'
 const objectMap = (object, mapFn) => Object.keys(object).reduce((result, key) => {
   result[key] = mapFn(object[key], key)
   return result
 }, {})
-const removeDuplicates = arr => [...new Set(arr)]
-const filterOutParentAndEmpty = part => part && part !== '..'
+
+// File utilities
+const getPathFromProjectRoot = (...all) => {
+  return path.join.apply(null, [__dirname, '..', '..'].concat(all))
+}
+const pathToPackageConfigFile = packageName => getPathFromProjectRoot('node_modules', packageName, 'govuk-prototype-kit.config.json')
+
+const readJsonFile = (filePath) => {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+}
+const getPackageConfig = packageName => {
+  if (fs.existsSync(pathToPackageConfigFile(packageName))) {
+    return readJsonFile(pathToPackageConfigFile(packageName))
+  } else {
+    return {}
+  }
+}
+
+// Handle errors to do with extension paths
+// Example of `subject`: { packageName: 'govuk-frontend', item: '/all.js' }
 const throwIfBadFilepath = subject => {
   if (('' + subject.item).indexOf('\\') > -1) {
     throw new Error(`Can't use backslashes in extension paths - "${subject.packageName}" used "${subject.item}".`)
@@ -21,23 +76,14 @@ const throwIfBadFilepath = subject => {
   }
 }
 
-function readJsonFile (filePath) {
-  return JSON.parse(fs.readFileSync(filePath, 'utf8'))
-}
-
-// Reused Functions
+// Check for `baseExtensions` in config.js. If it's not there, default to `govuk-frontend`
 const getBaseExtensions = () => appConfig.baseExtensions || ['govuk-frontend']
 
-const lookupConfigForPackage = packageName => {
-  if (fs.existsSync(pathToHookFile(packageName))) {
-    return readJsonFile(pathToHookFile(packageName))
-  } else {
-    return {}
-  }
-}
-
+// Get all npm dependencies
+// Get baseExtensions in the order defined in `baseExtensions` in config.js
+// Then place baseExtensions before npm dependencies (and remove duplicates)
 const getPackageNamesInOrder = () => {
-  const dependencies = readJsonFile(pathFromRoot('package.json')).dependencies || {}
+  const dependencies = readJsonFile(getPathFromProjectRoot('package.json')).dependencies || {}
   const allNpmDependenciesInAlphabeticalOrder = Object.keys(dependencies).sort()
   const installedBaseExtensions = getBaseExtensions()
     .filter(packageName => allNpmDependenciesInAlphabeticalOrder.includes(packageName))
@@ -47,32 +93,59 @@ const getPackageNamesInOrder = () => {
 
 // Extensions provide items such as sass scripts, asset paths etc.
 // This function groups them by type in a format which can used by getList
+// Example of return
+//    {
+//     nunjucksPaths: [
+//      { packageName: 'govuk-frontend', item: '/' },
+//      { packageName: 'govuk-frontend', item: '/components'}
+//    ],
+//    scripts: [
+//      { packageName: 'govuk-frontend', item: '/all.js' }
+//    ]
+//    assets: [
+//      { packageName: 'govuk-frontend', item: '/assets' }
+//    ],
+//    sass: [
+//      { packageName: 'govuk-frontend', item: '/all.scss' }
+//    ]}
 const getExtensionsByType = () => {
   return getPackageNamesInOrder()
     .reduce((accum, packageName) => Object.assign({}, accum, objectMap(
-      lookupConfigForPackage(packageName),
+      getPackageConfig(packageName),
       (listOfItemsForType, type) => (accum[type] || [])
-        .concat([].concat(listOfItemsForType).map(item => ({ packageName, item })))
+        .concat([].concat(listOfItemsForType).map(item => ({
+          packageName,
+          item
+        })))
     )), {})
 }
 
 let extensionsByType
 
-const recache = () => {
+const setExtensionsByType = () => {
   extensionsByType = getExtensionsByType()
 }
 
-recache()
+setExtensionsByType()
 
 // The hard-coded reference to govuk-frontend allows us to soft launch without a breaking change.  After a hard launch
 // govuk-frontend assets will be served on /extension-assets/govuk-frontend
-const getPublicUrl = config => (config.item === '/assets' && config.packageName === 'govuk-frontend') ? '/assets' : ['', 'extension-assets', config.packageName]
-  .concat(config.item.split('/').filter(filterOutParentAndEmpty))
-  .map(encodeURIComponent)
-  .join('/')
+const getPublicUrl = config => {
+  if (config.item === '/assets' && config.packageName === 'govuk-frontend') {
+    return '/assets'
+  } else {
+    return ['', 'extension-assets', config.packageName]
+      .concat(config.item.split('/').filter(filterOutParentAndEmpty))
+      .map(encodeURIComponent)
+      .join('/')
+  }
+}
 
-const getFileSystemPath = config => throwIfBadFilepath(config) || pathFromRoot('node_modules', config.packageName,
-  config.item.split('/').filter(filterOutParentAndEmpty).join(path.sep))
+const getFileSystemPath = config => {
+  return throwIfBadFilepath(config) || getPathFromProjectRoot('node_modules',
+    config.packageName,
+    config.item.split('/').filter(filterOutParentAndEmpty).join(path.sep))
+}
 
 const getPublicUrlAndFileSystemPath = config => ({
   fileSystemPath: getFileSystemPath(config),
@@ -86,7 +159,6 @@ const self = module.exports = {
   getPublicUrls: type => getList(type).map(getPublicUrl),
   getFileSystemPaths: type => getList(type).map(getFileSystemPath),
   getPublicUrlAndFileSystemPaths: type => getList(type).map(getPublicUrlAndFileSystemPath),
-
   getAppConfig: _ => ({
     scripts: self.getPublicUrls('scripts'),
     stylesheets: self.getPublicUrls('stylesheets')
@@ -96,5 +168,5 @@ const self = module.exports = {
     .reverse()
     .concat(additionalViews || []),
 
-  recache
+  setExtensionsByType // exposed only for testing purposes
 }

lib/extensions/extensions.test.js

@@ -27,7 +27,7 @@ describe('extensions', () => {
       }
     }
     setupFakeFilesystem()
-    extensions.recache()
+    extensions.setExtensionsByType()
   })
   afterEach(() => {
     jest.clearAllMocks()
@@ -444,7 +444,7 @@ describe('extensions', () => {
     const existingPackageJson = JSON.parse(testScope.fileSystem['/package.json'])
     existingPackageJson.dependencies[packageName] = version
     testScope.fileSystem['/package.json'] = JSON.stringify(existingPackageJson)
-    extensions.recache()
+    extensions.setExtensionsByType()
   }
 
   const mockUninstallExtension = (packageName) => {
@@ -454,7 +454,7 @@ describe('extensions', () => {
     }
     delete existingPackageJson.dependencies[packageName]
     testScope.fileSystem['/package.json'] = JSON.stringify(existingPackageJson)
-    extensions.recache()
+    extensions.setExtensionsByType()
   }
 
   const mockExtensionConfig = (packageName, config = {}, version) => {