adapt-project 1.0.0

package/lib/data/Language.js

@@ -0,0 +1,301 @@
+import path from 'path'
+import fs from 'fs-extra'
+import globs from 'globs'
+import _ from 'lodash'
+import chalk from 'chalk'
+import LanguageFile from './LanguageFile.js'
+
+/**
+ * @typedef {import('../Framework')} Framework
+ * @typedef {import('../JSONFileItem')} JSONFileItem
+ */
+
+/**
+ * Represents all of the json files and file item in a language directory
+ * at course/[lang]/*.[jsonext].
+ * It is filename agnostic, such that there are no hard references to file names.
+ * It has _id and _parentId structure checking and _trackingId management included.
+ */
+class Language {
+  /**
+   * @param {Object} options
+   * @param {Framework} options.framework
+   * @param {string} options.languagePath
+   * @param {string} options.jsonext
+   * @param {string} options.trackingIdType,
+   * @param {function} options.log
+   */
+  constructor ({
+    framework = null,
+    languagePath = '',
+    jsonext = 'json',
+    trackingIdType = 'block',
+    log = console.log
+  } = {}) {
+    /** @type {Framework} */
+    this.framework = framework
+    /** @type {string} */
+    this.jsonext = jsonext
+    /** @type {string} */
+    this.path = path.normalize(languagePath).replace(/\\/g, '/')
+    /** @type {string} */
+    this.name = this.path.split('/').filter(Boolean).pop()
+    /** @type {string} */
+    this.rootPath = this.path.split('/').filter(Boolean).slice(0, -1).join('/')
+    /** @type {string} */
+    this.manifestFileName = 'language_data_manifest.js'
+    /** @type {string} */
+    this.manifestPath = this.path + this.manifestFileName
+    /** @type {string} */
+    this.trackingIdType = trackingIdType
+    /** @type {[LanguageFile]} */
+    this.files = null
+    /** @type {Object.<string, JSONFileItem>} */
+    this._itemIdIndex = null
+    /** @type {[JSONFileItem]} */
+    this.courseFileItem = null
+    /** @type {function} */
+    this.log = log
+  }
+
+  /** @returns {Language} */
+  load () {
+    this.files = []
+    this._itemIdIndex = {}
+    this.courseFileItem = null
+
+    const dataFiles = globs.sync(path.join(this.path, '*.' + this.jsonext)).map((dataFilePath) => {
+      const relativePath = dataFilePath.slice(this.path.length)
+      return relativePath
+    }).filter((dataFilePath) => {
+      const isManifest = (dataFilePath === this.manifestPath)
+      // Skip file if it is the Authoring Tool import/export asset manifest
+      const isAATAssetJSON = (dataFilePath === 'assets.json')
+      return !isManifest && !isAATAssetJSON
+    })
+
+    dataFiles.forEach(jsonFileName => {
+      const jsonFilePath = (this.path + jsonFileName).replace(/\\/g, '/')
+      const file = new LanguageFile({
+        framework: this.framework,
+        language: this,
+        jsonext: this.jsonext,
+        path: jsonFilePath,
+        data: null,
+        hasChanged: false
+      })
+      file.load()
+      this.files.push(file)
+    })
+
+    this._itemIdIndex = this.getAllFileItems().reduce((index, fileItem) => {
+      const { file, item } = fileItem
+      if (item._id && index[item._id]) {
+        const err = new Error(`Duplicate ids ${item._id} in ${index[item._id].file.path} and ${file.path}`)
+        err.number = 10006
+        throw err
+      } else if (item._id) {
+        index[item._id] = fileItem
+      }
+      if (item._type === 'course' && this.courseFileItem) {
+        const err = new Error(`Duplicate course items found, in ${index[item._id].file.path} and ${file.path}`)
+        err.number = 10007
+        throw err
+      } else if (item._type === 'course') {
+        this.courseFileItem = fileItem
+      }
+      return index
+    }, {})
+
+    return this
+  }
+
+  /** @type {boolean} */
+  get isValid () {
+    return Boolean(this.courseFileItem)
+  }
+
+  /** @type {boolean} */
+  get hasChanged () {
+    return this.files.some(file => file.hasChanged)
+  }
+
+  /**
+   * Produces a manifest file for the Framework data layer at course/lang/language_data_manifest.js.
+   * @returns {Language}
+   */
+  saveManifest () {
+    const dataFiles = globs.sync(path.join(this.path, '*.' + this.jsonext)).map((dataFilePath) => {
+      const relativePath = dataFilePath.slice(this.path.length)
+      return relativePath
+    }).filter((dataFilePath) => {
+      const isManifest = (dataFilePath === this.manifestPath)
+      // Skip file if it is the Authoring Tool import/export asset manifest
+      const isAATAssetJSON = (dataFilePath === 'assets.json')
+      return !isManifest && !isAATAssetJSON
+    })
+    const hasNoDataFiles = !dataFiles.length
+    if (hasNoDataFiles) {
+      const err = new Error(`No data files found in ${this.path}`)
+      err.number = 10008
+      throw err
+    }
+    fs.writeJSONSync(this.manifestPath, dataFiles, { spaces: 0 })
+    return this
+  }
+
+  /** @returns {[JSONFileItem]} */
+  getAllFileItems () {
+    return this.files.reduce((memo, file) => {
+      memo.push(...file.fileItems)
+      return memo
+    }, [])
+  }
+
+  /** @returns {JSONFileItem} */
+  getCourseFileItem () {
+    if (!this.courseFileItem) {
+      const err = new Error(`Could not find course item for ${this.path}`)
+      err.number = 10009
+      throw err
+    }
+    return this.courseFileItem
+  }
+
+  /**
+   * @param {string} id
+   * @returns {JSONFileItem}
+   */
+  getFileItemById (id) {
+    const fileItem = this._itemIdIndex[id]
+    if (!fileItem) {
+      const err = new Error(`Could not find item for id ${id} in ${this.path}`)
+      err.number = 10010
+      throw err
+    }
+    return fileItem
+  }
+
+  /** @returns {Language} */
+  checkIds () {
+    const items = this.getAllFileItems().map(({ item }) => item)
+    // Index and group
+    const idIndex = _.keyBy(items, '_id')
+    const idGroups = _.groupBy(items, '_id')
+    const parentIdGroups = _.groupBy(items, '_parentId')
+    // Setup error collection arrays
+    const orphanedIds = {}
+    let emptyIds = {}
+    let duplicateIds = {}
+    const missingIds = {}
+    items.forEach((o) => {
+      const isCourseType = (o._type === 'course')
+      const isComponentType = (o._type === 'component')
+      if (idGroups[o._id].length > 1) {
+        duplicateIds[o._id] = true // Id has more than one item
+      }
+      if (!isComponentType && !parentIdGroups[o._id]) {
+        emptyIds[o._id] = true // Course has no children
+      }
+      if (!isCourseType && (!o._parentId || !idIndex[o._parentId])) {
+        orphanedIds[o._id] = o._type // Item has no defined parent id or the parent id doesn't exist
+      }
+      if (!isCourseType && o._parentId && !idIndex[o._parentId]) {
+        missingIds[o._parentId] = o._type // Referenced parent item does not exist
+      }
+    })
+    const orphanedIdsArray = Object.keys(orphanedIds)
+    const missingIdsArray = Object.keys(missingIds)
+    emptyIds = Object.keys(emptyIds)
+    duplicateIds = Object.keys(duplicateIds)
+    // Output for each type of error
+    const hasErrored = orphanedIdsArray.length || emptyIds.length || duplicateIds.length || missingIdsArray.length
+    if (orphanedIdsArray.length) {
+      const orphanedIdString = orphanedIdsArray.map((id) => `${id} (${orphanedIds[id]})`)
+      this.log(chalk.yellow(`Orphaned _ids: ${orphanedIdString.join(', ')}`))
+    }
+    if (missingIdsArray.length) {
+      const missingIdString = missingIdsArray.map((id) => `${id} (${missingIds[id]})`)
+      this.log(chalk.yellow(`Missing _ids: ${missingIdString.join(', ')}`))
+    }
+    if (emptyIds.length) {
+      this.log(chalk.yellow(`Empty _ids: ${emptyIds}`))
+    }
+    if (duplicateIds.length) {
+      this.log(chalk.yellow(`Duplicate _ids: ${duplicateIds}`))
+    }
+    // If any error has occured, stop processing.
+    if (hasErrored) {
+      const err = new Error('Oops, looks like you have some json errors.')
+      err.number = 10011
+      throw err
+    }
+    this.log(`No issues found in course/${this.name}, your JSON is a-ok!`)
+
+    return this
+  }
+
+  /** @returns {Language} */
+  addTrackingIds () {
+    const { file, item: course } = this.getCourseFileItem()
+    course._latestTrackingId = course._latestTrackingId || -1
+    file.changed()
+
+    let wasAdded = false
+    const trackingIdsSeen = []
+    const fileItems = this.getAllFileItems().filter(fileItem => fileItem.item._type === this.trackingIdType)
+    fileItems.forEach(({ file, item }) => {
+      this.log(`${this.trackingIdType}: ${item._id}: ${item._trackingId !== undefined ? item._trackingId : 'not set'}`)
+      if (item._trackingId === undefined) {
+        item._trackingId = ++course._latestTrackingId
+        file.changed()
+        wasAdded = true
+        this.log(`Adding tracking ID: ${item._trackingId} to ${this.trackingIdType} ${item._id}`)
+      } else {
+        if (trackingIdsSeen.indexOf(item._trackingId) > -1) {
+          item._trackingId = ++course._latestTrackingId
+          file.changed()
+          wasAdded = true
+          this.log(`Warning: ${item._id} has the tracking ID ${item._trackingId} but this is already in use. Changing to ${course._latestTrackingId + 1}.`)
+        } else {
+          trackingIdsSeen.push(item._trackingId)
+        }
+      }
+      if (course._latestTrackingId < item._trackingId) {
+        course._latestTrackingId = item._trackingId
+      }
+    })
+
+    this.save()
+    this.log(`Tracking IDs ${wasAdded ? 'were added to' : 'are ok for'} course/${this.name}. The latest tracking ID is ${course._latestTrackingId}\n`)
+
+    return this
+  }
+
+  /** @returns {Language} */
+  removeTrackingIds () {
+    const { file, item: course } = this.getCourseFileItem()
+    course._latestTrackingId = -1
+    file.changed()
+
+    this.getAllFileItems().forEach(({ file, item }) => {
+      if (item._type !== this.trackingIdType) return
+      delete item._trackingId
+      file.changed()
+    })
+
+    this.save()
+    this.log(`Tracking IDs removed from course/${this.name}.`)
+
+    return this
+  }
+
+  /** @returns {Language} */
+  save () {
+    this.files.forEach(file => file.save())
+    this.load()
+    return this
+  }
+}
+
+export default Language

package/lib/data/LanguageFile.js

@@ -0,0 +1,35 @@
+import JSONFile from '../JSONFile.js'
+
+/**
+ * @typedef {import('../Framework')} Framework
+ * @typedef {import('./Language')} Language
+ */
+
+/**
+ * Represents any of the files at course/[lang]/*.[jsonext].
+ */
+class LanguageFile extends JSONFile {
+  /**
+   * @param {Object} options
+   * @param {Framework} options.framework
+   * @param {Language} options.language
+   * @param {string} options.path
+   * @param {string} options.jsonext
+   * @param {Object} options.data
+   * @param {boolean} options.hasChanged
+   */
+  constructor ({
+    framework = null,
+    language = null,
+    path = null,
+    jsonext = null,
+    data = null,
+    hasChanged = false
+  } = {}) {
+    super({ framework, path, jsonext, data, hasChanged })
+    /** @type {Language} */
+    this.language = language
+  }
+}
+
+export default LanguageFile

package/lib/plugins/Plugin.js

@@ -0,0 +1,143 @@
+import semver from 'semver'
+import globs from 'globs'
+import JSONFile from '../JSONFile.js'
+
+/**
+ * Represents a single plugin location, bower.json, version, name and schema
+ * locations.
+   * @todo Should be able to define multiple schemas for all plugins in the AAT
+   * and in the Framework
+   * @todo Switch to package.json with the move to npm
+   * @todo Plugin type is inferred from the JSON.
+   * @todo Component _globals target attribute is inferred from the _component
+ */
+class Plugin {
+  /**
+   * @param {Object} options
+   * @param {Framework} options.framework
+   * @param {string} options.sourcePath
+   * @param {string} options.jsonext
+   * @param {function} options.log
+   */
+  constructor ({
+    framework = null,
+    sourcePath = '',
+    log = console.log,
+    warn = console.warn
+  } = {}) {
+    /** @type {Framework} */
+    this.framework = framework
+    /** @type {string} */
+    this.sourcePath = sourcePath.replace(/\\/g, '/')
+    /** @type {function} */
+    this.log = log
+    /** @type {function} */
+    this.warn = warn
+    /** @type {JSONFile} */
+    this.packageJSONFile = null
+  }
+
+  /** @returns {Plugin} */
+  load () {
+    const pathDerivedName = this.sourcePath.split('/').filter(Boolean).pop()
+    const files = globs.sync(this.packageJSONLocations)
+    const firstFile = files[0]
+    if (firstFile) {
+      // use the first package definition found (this will be bower.json / package.json)
+      this.packageJSONFile = new JSONFile({
+        path: firstFile
+      })
+    } else {
+      // no json found, make some up (this will usually be the core)
+      this.packageJSONFile = new JSONFile({
+        path: null,
+        data: {
+          name: pathDerivedName
+        }
+      })
+    }
+    this.packageJSONFile.load()
+    const packageName = (this.packageJSONFile.firstFileItem.item.name)
+    if (packageName !== pathDerivedName) {
+      // assume path name is also plugin name, this shouldn't be necessary
+      this.warn(`Plugin folder name ${pathDerivedName} does not match package name ${packageName}.`)
+    }
+    if (this.requiredFramework && !this.isFrameworkCompatible) {
+      this.warn(`Required framework version (${this.requiredFramework}) for plugin ${packageName} not satisfied by current framework version (${this.framework.version}).`)
+    }
+    return this
+  }
+
+  /**
+   * Informs the Schemas API from where to fetch the schemas defined in this
+   * plugin.
+   * @returns {[string]}
+   */
+  get schemaLocations () {
+    return [
+      `${this.sourcePath}properties.schema`,
+      `${this.sourcePath}schema/*.schema`
+    ]
+  }
+
+  /**
+   * @returns {[string]}
+   */
+  get packageJSONLocations () {
+    return [
+      `${this.sourcePath}bower.json`
+    ]
+  }
+
+  /** @returns {string} */
+  get name () {
+    return this.packageJSONFile.firstFileItem.item.name
+  }
+
+  /** @returns {string} */
+  get version () {
+    return this.packageJSONFile.firstFileItem.item.version
+  }
+
+  /** @returns {string} */
+  get requiredFramework () {
+    return this.packageJSONFile.firstFileItem.item.framework
+  }
+
+  /** @returns {boolean} */
+  get isFrameworkCompatible () {
+    if (!this.framework || !this.framework.version) return true
+
+    return semver.satisfies(this.framework.version, this.requiredFramework)
+  }
+
+  /**
+   * Returns the plugin type name.
+   * @returns {string}
+   */
+  get type () {
+    if (this.name === 'core') {
+      return 'component'
+    }
+    const config = this.packageJSONFile.firstFileItem.item
+    const configKeys = Object.keys(config)
+    const typeKeyName = ['component', 'extension', 'menu', 'theme']
+    const foundType = configKeys.find(key => typeKeyName.includes(key))
+    if (!foundType) {
+      throw new Error(`Unknown plugin type for ${this.name}`)
+    }
+    return foundType
+  }
+
+  /**
+   * @returns {string}
+   */
+  get targetAttribute () {
+    if (this.type === 'component') {
+      return this.packageJSONFile.firstFileItem.item.component
+    }
+    return this.packageJSONFile.firstFileItem.item.targetAttribute
+  }
+}
+
+export default Plugin

package/lib/schema/ExtensionSchema.js

@@ -0,0 +1,26 @@
+import GlobalsSchema from './GlobalsSchema.js'
+
+/**
+ * Represents a model extension schema. Currently these schemas are only able to
+ * extend config, course, contentobject, article, block and component models.
+ *
+ * @todo pluginLocations is not a good way of listing model extensions or detecting
+ * extension schemas. There should be a schema type (model/extension) and
+ * the extensions should be declared at the root of the schema.
+ * @todo pluginLocations[modelName] should extend any model (article, block,
+ * accordion, narrative)
+ */
+class ExtensionSchema extends GlobalsSchema {
+  /**
+   * Returns the defined model extension sub-schemas listed at pluginLocations.
+   * @returns {Object|undefined}
+   */
+  getModelExtensionParts () {
+    if (!this.json.properties.pluginLocations || !this.json.properties.pluginLocations.properties) {
+      return
+    }
+    return this.json.properties.pluginLocations && this.json.properties.pluginLocations.properties
+  }
+}
+
+export default ExtensionSchema

package/lib/schema/GlobalsSchema.js

@@ -0,0 +1,65 @@
+import Schema from './Schema.js'
+
+/**
+ * @typedef {import('./Framework')} Framework
+ * @typedef {import('../plugins/Plugin')} Plugin
+ */
+
+/**
+ * Represents the globals properties listed in a model or extension schema.
+ * @todo _globals doesn't need to differentiate by plugin type, plugin name should suffice
+ * @todo We should drop all pluralisations, they're unnecessary and complicated.
+ */
+class GlobalsSchema extends Schema {
+  /**
+   * @param {Object} options
+   * @param {Framework} options.framework
+   * @param {string} options.name
+   * @param {Plugin} options.plugin
+   * @param {Object} options.json
+   * @param {string} options.filePath
+   * @param {string} options.globalsType
+   * @param {string} options.targetAttribute Attribute where this sub-schema will be injected into the course.json:_globals._[pluginType] object
+   */
+  constructor ({
+    framework = null,
+    name = '',
+    plugin = null,
+    json = {},
+    filePath = '',
+    globalsType = '',
+    targetAttribute = ''
+  } = {}) {
+    super({ framework, name, plugin, json, filePath, globalsType })
+    // Add an underscore to the front of the targetAttribute if necessary
+    this.targetAttribute = (targetAttribute && targetAttribute[0] !== '_' ? '_' : '') + targetAttribute
+  }
+
+  /**
+   * Returns the sub-schema for the course.json:_globals object.
+   * @returns {Object|undefined}
+   */
+  getCourseGlobalsPart () {
+    if (!this.json.globals) {
+      return
+    }
+    /**
+     * pluralise location name if necessary (components, extensions) etc
+     */
+    const shouldPluralise = ['component', 'extension'].includes(this.globalsType)
+    const globalsType = shouldPluralise ? this.globalsType + 's' : this.globalsType
+    return {
+      [`_${globalsType}`]: {
+        type: 'object',
+        properties: {
+          [this.targetAttribute]: {
+            type: 'object',
+            properties: this.json.globals
+          }
+        }
+      }
+    }
+  }
+}
+
+export default GlobalsSchema

package/lib/schema/ModelSchema.js

@@ -0,0 +1,45 @@
+import GlobalsSchema from './GlobalsSchema.js'
+
+/**
+ * Represents an article, block, accordion or other type of model schema
+ */
+class ModelSchema extends GlobalsSchema {
+  /**
+   * Create array of translatable attribute paths
+   * @returns {[string]}
+   */
+  getTranslatablePaths () {
+    const paths = {}
+    this.traverse('', ({ description, next }, attributePath) => {
+      switch (description.type) {
+        case 'object':
+          next(attributePath + description.name + '/')
+          break
+        case 'array':
+          if (!Object.prototype.hasOwnProperty.call(description, 'items')) {
+            // handles 'inputType': 'List' edge-case
+            break
+          }
+          if (description.items.type === 'object') {
+            next(attributePath + description.name + '/')
+          } else {
+            next(attributePath)
+          }
+          break
+        case 'string': {
+          // check if attribute should be picked
+          const value = Boolean(description.translatable)
+          if (value === false) {
+            break
+          }
+          // add value to store
+          paths[attributePath + description.name + '/'] = value
+          break
+        }
+      }
+    }, '/')
+    return Object.keys(paths)
+  }
+}
+
+export default ModelSchema

package/lib/schema/ModelSchemas.js

@@ -0,0 +1,41 @@
+import _ from 'lodash'
+
+/**
+ * @typedef {import('./Framework')} Framework
+ * @typedef {import('./ModelSchema')} ModelSchema
+ * @typedef {import('./Schema')} Schema
+ */
+
+/**
+ * Encapsulates a collection of ModelSchema
+ * @todo Validation, maybe, if this set of files is used in the AAT
+ */
+class ModelSchemas {
+  /**
+   * @param {Object} options
+   * @param {Framework} options.framework
+   * @param {[ModelSchema]} options.schemas
+   */
+  constructor ({
+    framework = null,
+    schemas = []
+  } = {}) {
+    /** @type {Framework} */
+    this.framework = framework
+    /** @type {[ModelSchema]} */
+    this.schemas = schemas
+  }
+
+  /**
+   * Returns an array of translatable attribute paths derived from the schemas.
+   * @returns {[string]}
+   */
+  getTranslatablePaths () {
+    return _.uniq(this.schemas.reduce((paths, modelSchema) => {
+      paths.push(...modelSchema.getTranslatablePaths())
+      return paths
+    }, []))
+  }
+}
+
+export default ModelSchemas