adapt-project 1.0.0

package/lib/Framework.js

@@ -0,0 +1,295 @@
+import path from 'path'
+import JSONFile from './JSONFile.js'
+import Data from './Data.js'
+import Translate from './Translate.js'
+import Plugins from './Plugins.js'
+import Schemas from './Schemas.js'
+
+/**
+ * @typedef {import('./JSONFileItem')} JSONFileItem
+ */
+
+/**
+ * The class represents an Adapt Framework root directory. It provides APIs for
+ * plugins, schemas, data and translations.
+ */
+class Framework {
+  /**
+   * @param {Object} options
+   * @param {string} options.rootPath
+   * @param {string} options.outputPath
+   * @param {string} options.sourcePath
+   * @param {function} options.includedFilter
+   * @param {string} options.jsonext
+   * @param {string} options.trackingIdType,
+   * @param {boolean} options.useOutputData
+   * @param {function} options.log
+   * @param {function} options.warn
+   */
+  constructor ({
+    rootPath = process.cwd(),
+    outputPath = path.join(rootPath, '/build/'),
+    sourcePath = path.join(rootPath, '/src/'),
+    courseDir = 'course',
+    includedFilter = function () { return true },
+    jsonext = 'json',
+    trackingIdType = 'block',
+    useOutputData = false,
+    log = console.log,
+    warn = console.warn
+  } = {}) {
+    /** @type {string} */
+    this.rootPath = rootPath.replace(/\\/g, '/')
+    /** @type {string} */
+    this.outputPath = path.resolve(this.rootPath, outputPath).replace(/\\/g, '/').replace(/\/?$/, '/')
+    /** @type {string} */
+    this.sourcePath = path.resolve(this.rootPath, sourcePath).replace(/\\/g, '/').replace(/\/?$/, '/')
+    /** @type {string} */
+    this.courseDir = courseDir
+    /** @type {function} */
+    this.includedFilter = includedFilter
+    /** @type {string} */
+    this.jsonext = jsonext
+    /** @type {string} */
+    this.trackingIdType = trackingIdType
+    /** @type {boolean} */
+    this.useOutputData = useOutputData
+    /** @type {function} */
+    this.log = log
+    /** @type {function} */
+    this.warn = warn
+    /** @type {JSONFile} */
+    this.packageJSONFile = null
+  }
+
+  /** @returns {Framework} */
+  load () {
+    this.packageJSONFile = new JSONFile({
+      framework: this,
+      path: path.join(this.rootPath, 'package.json').replace(/\\/g, '/')
+    })
+    this.packageJSONFile.load()
+    return this
+  }
+
+  /** @returns {JSONFileItem} */
+  getPackageJSONFileItem () {
+    return this.packageJSONFile.firstFileItem
+  }
+
+  /** @returns {string} */
+  get version () {
+    return this.getPackageJSONFileItem().item.version
+  }
+
+  /**
+   * Returns a Data instance for either the src/course or build/course folder
+   * depending on the specification of the useOutputData property on either the
+   * function or the Framework instance.
+   * @returns {Data}
+   */
+  getData ({
+    useOutputData = this.useOutputData,
+    performLoad = true
+  } = {}) {
+    const data = new Data({
+      framework: this,
+      sourcePath: useOutputData ? this.outputPath : this.sourcePath,
+      courseDir: this.courseDir,
+      jsonext: this.jsonext,
+      trackingIdType: this.trackingIdType,
+      log: this.log
+    })
+    if (performLoad) data.load()
+    return data
+  }
+
+  /** @returns {Plugins} */
+  getPlugins ({
+    includedFilter = this.includedFilter
+  } = {}) {
+    const plugins = new Plugins({
+      framework: this.framework,
+      includedFilter,
+      sourcePath: this.sourcePath,
+      log: this.log,
+      warn: this.warn
+    })
+    plugins.load()
+    return plugins
+  }
+
+  /** @returns {Schemas} */
+  getSchemas ({
+    includedFilter = this.includedFilter
+  } = {}) {
+    const schemas = new Schemas({
+      framework: this,
+      includedFilter,
+      sourcePath: this.sourcePath,
+      log: this.log
+    })
+    schemas.load()
+    return schemas
+  }
+
+  /** @returns {Translate} */
+  getTranslate ({
+    includedFilter = this.includedFilter,
+    masterLang = 'en',
+    targetLang = null,
+    format = 'csv',
+    csvDelimiter = ',',
+    shouldReplaceExisting = false,
+    languagePath = '',
+    isTest = false
+  } = {}) {
+    const translate = new Translate({
+      framework: this,
+      includedFilter,
+      masterLang,
+      targetLang,
+      format,
+      csvDelimiter,
+      shouldReplaceExisting,
+      jsonext: this.jsonext,
+      sourcePath: this.sourcePath,
+      languagePath,
+      outputPath: this.outputPath,
+      courseDir: this.courseDir,
+      useOutputData: this.useOutputData,
+      isTest,
+      log: this.log,
+      warn: this.warn
+    })
+    translate.load()
+    return translate
+  }
+
+  /** @returns {Framework} */
+  applyGlobalsDefaults ({
+    includedFilter = this.includedFilter,
+    useOutputData = this.useOutputData,
+    schemas = this.getSchemas({
+      includedFilter
+    }),
+    data = this.getData(useOutputData)
+  } = {}) {
+    const courseSchema = schemas.getCourseSchema()
+    data.languages.forEach(language => {
+      const { file, item: course } = language.getCourseFileItem()
+      course._globals = courseSchema.applyDefaults(course._globals, '_globals')
+      file.changed()
+    })
+    data.save()
+    return this
+  }
+
+  /** @returns {Framework} */
+  applyScreenSizeDefaults ({
+    includedFilter = this.includedFilter,
+    useOutputData = this.useOutputData,
+    schemas = this.getSchemas({
+      includedFilter
+    }),
+    data = this.getData(useOutputData)
+  } = {}) {
+    const configSchema = schemas.getConfigSchema()
+    const { file, item: config } = data.getConfigFileItem()
+    config.screenSize = configSchema.applyDefaults(config.screenSize, 'screenSize')
+    file.changed()
+    data.save()
+    return this
+  }
+
+  /**
+   * Creates an includedFilter function based on config.build.includes and
+   * config.build.excludes from the course config.json. Automatically resolves
+   * plugin dependencies found in plugin bower.json / package.json files.
+   * @returns {function} A filter function: (sourcePath: string) => boolean
+   */
+  makeIncludeFilter () {
+    const data = this.getData()
+    const configFileItem = data.getConfigFileItem()
+    const buildConfig = (configFileItem && configFileItem.item && configFileItem.item.build) || {}
+    const buildIncludes = buildConfig.includes && buildConfig.includes.length ? buildConfig.includes : null
+    const buildExcludes = buildConfig.excludes && buildConfig.excludes.length ? buildConfig.excludes : null
+
+    if (!buildIncludes && !buildExcludes) {
+      return function () { return true }
+    }
+
+    // Resolve plugin dependencies for includes
+    let resolvedIncludes = null
+    if (buildIncludes) {
+      const allPlugins = this.getPlugins({ includedFilter: () => true })
+      const dependencies = []
+
+      allPlugins.plugins.forEach(plugin => {
+        if (!buildIncludes.includes(plugin.name)) return
+        const packageData = plugin.packageJSONFile.firstFileItem.item
+        const deps = packageData.dependencies
+        if (!deps || typeof deps !== 'object') return
+        Object.keys(deps).forEach(depName => {
+          if (!buildIncludes.includes(depName) && !dependencies.includes(depName)) {
+            dependencies.push(depName)
+          }
+        })
+      })
+
+      resolvedIncludes = [].concat(buildIncludes, dependencies)
+    }
+
+    // Build regex patterns
+    const pluginTypes = ['components', 'extensions', 'menu', 'theme']
+    const sourcedir = 'src/'
+
+    let includedRegExp = null
+    let nestedIncludedRegExp = null
+    if (resolvedIncludes) {
+      const includePatterns = resolvedIncludes.map(plugin => {
+        return pluginTypes.map(type => sourcedir + type + '/' + plugin + '/').join('|')
+      }).join('|')
+      const corePattern = sourcedir + 'core/'
+      includedRegExp = new RegExp(corePattern + '|' + includePatterns, 'i')
+
+      const nestedPatterns = resolvedIncludes.map(plugin => {
+        return sourcedir + '([^/]*)/([^/]*)/' + 'less/plugins' + '/' + plugin + '/'
+      }).join('|')
+      nestedIncludedRegExp = new RegExp(nestedPatterns, 'i')
+    }
+
+    let excludedRegExp = null
+    if (buildExcludes) {
+      const excludePatterns = buildExcludes.map(plugin => {
+        return pluginTypes.map(type => sourcedir + type + '/' + plugin + '/').join('|')
+      }).join('|')
+      excludedRegExp = new RegExp(excludePatterns, 'i')
+    }
+
+    // Return the filter closure
+    return function includedFilter (pluginPath) {
+      pluginPath = pluginPath.replace(/\\/g, '/')
+
+      const isIncluded = resolvedIncludes ? pluginPath.search(includedRegExp) !== -1 : undefined
+      const isExcluded = buildExcludes ? pluginPath.search(excludedRegExp) !== -1 : false
+
+      if (isExcluded || isIncluded === false) {
+        return false
+      }
+
+      const nestedPluginsPath = !!pluginPath.match(/(?:.)+(?:\/less\/plugins)/g)
+      if (!nestedPluginsPath) {
+        return true
+      }
+
+      if (resolvedIncludes) {
+        return !!pluginPath.match(nestedIncludedRegExp)
+      }
+
+      return true
+    }
+  }
+}
+
+export default Framework

package/lib/JSONFile.js

@@ -0,0 +1,104 @@
+import fs from 'fs-extra'
+import JSONFileItem from './JSONFileItem.js'
+
+/**
+ * @typedef {import('./Framework')} Framework
+ * @typedef {import('./JSONFile')} JSONFile
+ */
+
+/**
+ * An abstraction for centralising the loading of JSON files, keeping track of
+ * sub-item changes and saving changed files.
+ */
+class JSONFile {
+  /**
+   * @param {Object} options
+   * @param {Framework} options.framework
+   * @param {string} options.path
+   * @param {Object|Array} options.data
+   * @param {boolean} options.hasChanged
+   */
+  constructor ({
+    framework = null,
+    path = null,
+    jsonext = null,
+    data = null,
+    hasChanged = false
+  } = {}) {
+    /** @type {Framework} */
+    this.framework = framework
+    /** @type {string} */
+    this.path = path
+    /** @type {string} */
+    this.jsonext = jsonext
+    /** @type {Object|Array} */
+    this.data = data
+    /** @type {boolean} */
+    this.hasChanged = hasChanged
+    /** @type {[JSONFileItem]} */
+    this.fileItems = null
+  }
+
+  /** @returns {JSONFile} */
+  load () {
+    this.fileItems = []
+
+    if (this.path) {
+      this.data = fs.readJSONSync(this.path)
+    }
+
+    const addObject = (item, index = null) => {
+      this.fileItems.push(new JSONFileItem({
+        framework: this.framework,
+        file: this,
+        item,
+        index
+      }))
+    }
+
+    if (this.data instanceof Array) {
+      this.data.forEach((item, index) => addObject(item, index))
+    } else if (this.data instanceof Object) {
+      addObject(this.data, null)
+    } else {
+      const err = new Error(`Cannot load json file ${this.path} as it doesn't contain an Array or Object as its root`)
+      err.number = 10013
+      throw err
+    }
+
+    return this
+  }
+
+  /**
+   * This is useful for files such as config.json or course.json which only have
+   * one item/object per file.
+   * @returns {JSONFileItem}
+   */
+  get firstFileItem () {
+    return this.fileItems && this.fileItems[0]
+  }
+
+  /**
+   * Marks this file as having changed. This should be called after changing
+   * the fileItems contained in this instance.
+   * @returns {JSONFile}
+   */
+  changed () {
+    this.hasChanged = true
+    return this
+  }
+
+  /**
+   * Saves any fileItem changes to disk.
+   * @return {JSONFile}
+   */
+  save () {
+    if (!this.hasChanged) {
+      return this
+    }
+    fs.writeJSONSync(this.path, this.data, { spaces: 2 })
+    return this
+  }
+}
+
+export default JSONFile

package/lib/JSONFileItem.js

@@ -0,0 +1,27 @@
+/**
+ * @typedef {import('./Framework')} Framework
+ * @typedef {import('./JSONFile')} JSONFile
+ */
+
+/**
+ * An abstraction for carrying JSON sub-items with their file origins and locations.
+ */
+class JSONFileItem {
+  constructor ({
+    framework = null,
+    file = null,
+    item = null,
+    index = null
+  } = {}) {
+    /** @type {Framework} */
+    this.framework = framework
+    /** @type {JSONFile} */
+    this.file = file
+    /** @type {Object} */
+    this.item = item
+    /** @type {number} */
+    this.index = index
+  }
+}
+
+export default JSONFileItem

package/lib/Plugins.js

@@ -0,0 +1,82 @@
+import globs from 'globs'
+import Plugin from './plugins/Plugin.js'
+
+/**
+ * @typedef {import('./Framework')} Framework
+ * @typedef {import('./JSONFileItem')} JSONFileItem
+ */
+
+/**
+ * Represents all of the plugins in the src/ folder.
+ */
+class Plugins {
+  /**
+   * @param {Object} options
+   * @param {Framework} options.framework
+   * @param {function} options.includedFilter
+   * @param {string} options.sourcePath
+   * @param {function} options.log
+   * @param {function} options.warn
+   */
+  constructor ({
+    framework = null,
+    includedFilter = function () { return true },
+    sourcePath = process.cwd() + '/src/',
+    courseDir = 'course',
+    log = console.log,
+    warn = console.warn
+  } = {}) {
+    /** @type {Framework} */
+    this.framework = framework
+    /** @type {function} */
+    this.includedFilter = includedFilter
+    /** @type {string} */
+    this.sourcePath = sourcePath
+    /** @type {string} */
+    this.courseDir = courseDir
+    /** @type {function} */
+    this.log = log
+    /** @type {function} */
+    this.warn = warn
+    /** @type {[Plugin]} */
+    this.plugins = []
+  }
+
+  /**
+   * Returns the locations of all plugins in the src/ folder.
+   * @returns {[string]}
+   */
+  get pluginLocations () {
+    return [
+      `${this.sourcePath}core/`,
+      `${this.sourcePath}!(core|${this.courseDir})/*/`
+    ]
+  }
+
+  /** @returns {Plugins} */
+  load () {
+    this.plugins = globs.sync(this.pluginLocations)
+      .filter(sourcePath => this.includedFilter(sourcePath))
+      .map(sourcePath => {
+        const plugin = new Plugin({
+          framework: this.framework,
+          sourcePath,
+          log: this.log,
+          warn: this.warn
+        })
+        plugin.load()
+        return plugin
+      })
+    return this
+  }
+
+  /** @returns {JSONFileItem} */
+  getAllPackageJSONFileItems () {
+    return this.plugins.reduce((items, plugin) => {
+      items.push(...plugin.packageJSONFile.fileItems)
+      return items
+    }, [])
+  }
+}
+
+export default Plugins

package/lib/Schemas.js

@@ -0,0 +1,208 @@
+import _ from 'lodash'
+import path from 'path'
+import fs from 'fs-extra'
+import globs from 'globs'
+import ExtensionSchema from './schema/ExtensionSchema.js'
+import ModelSchema from './schema/ModelSchema.js'
+import ModelSchemas from './schema/ModelSchemas.js'
+import Plugins from './Plugins.js'
+
+/**
+ * @typedef {import('./Framework')} Framework
+ * @typedef {import('./Plugins')} Plugins
+ * @typedef {import('./plugins/Plugin')} Plugin
+ */
+
+/**
+ * Represents all of the schemas in a course.
+ * @todo Work out how to do schema inheritance properly (i.e. component+accordion)
+ * @todo Stop deriving schema types (model/extension) from bower and/or folder paths
+ * @todo Stop deriving schema names from bower.json or filenames
+ * @todo Combining and applying multiple schemas for validation or defaults needs consideration
+ */
+class Schemas {
+  /**
+   * @param {Object} options
+   * @param {Framework} options.framework
+   * @param {function} options.includedFilter
+   * @param {Plugins} options.plugins
+   * @param {string} options.sourcePath
+   * @param {function} options.log
+   * @param {function} options.warn
+   */
+  constructor ({
+    framework = null,
+    includedFilter = function () { return true },
+    plugins = null,
+    sourcePath = '',
+    log = console.log,
+    warn = console.warn
+  } = {}) {
+    /** @type {Framework} */
+    this.framework = framework
+    /** @type {function} */
+    this.includedFilter = includedFilter
+    /** @type {string} */
+    this.sourcePath = sourcePath.replace(/\\/g, '/')
+    /** @type {Plugins} */
+    this.plugins = plugins
+    /** @type {[Schema]]} */
+    this.schemas = null
+    /** @type {function} */
+    this.log = log
+    /** @type {function} */
+    this.warn = warn
+  }
+
+  /** @returns {Schemas} */
+  load () {
+    /**
+     * @param {Plugin} plugin
+     * @param {string} filePath
+     */
+    const createSchema = (plugin, filePath) => {
+      const json = fs.readJSONSync(filePath)
+      const isExtensionSchema = Boolean(json.properties.pluginLocations)
+      const InferredSchemaClass = (isExtensionSchema ? ExtensionSchema : ModelSchema)
+      const inferredSchemaName = (plugin.name === 'core')
+        ? path.parse(filePath).name.split('.')[0] // if core, get schema name from file name
+        : isExtensionSchema
+          ? plugin.name // assume schema name is plugin name
+          : plugin.targetAttribute // assume schema name is plugin._[type] value
+      return new InferredSchemaClass({
+        name: inferredSchemaName,
+        plugin,
+        framework: this.framework,
+        filePath,
+        globalsType: plugin.type,
+        targetAttribute: plugin.targetAttribute
+      })
+    }
+
+    this.plugins = new Plugins({
+      framework: this.framework,
+      includedFilter: this.includedFilter,
+      sourcePath: this.sourcePath,
+      log: this.log,
+      warn: this.warn
+    })
+    this.plugins.load()
+
+    this.schemas = []
+    this.plugins.plugins.forEach(plugin => globs.sync(plugin.schemaLocations).forEach(filePath => {
+      const schema = createSchema(plugin, filePath)
+      schema.load()
+      this.schemas.push(schema)
+    }))
+
+    this.generateCourseGlobals()
+    this.generateModelExtensions()
+
+    return this
+  }
+
+  /**
+   * Copy globals schema extensions from model/extension plugins to the course._globals
+   * schema.
+   * @returns {Schemas}
+   * @example
+   * courseModelSchema.properties._globals.properties._components.properties._accordion
+   */
+  generateCourseGlobals () {
+    const courseSchema = this.getCourseSchema()
+    this.schemas.forEach(schema => {
+      const globalsPart = schema.getCourseGlobalsPart()
+      if (!globalsPart) {
+        return
+      }
+      _.merge(courseSchema.json.properties._globals.properties, globalsPart)
+    })
+    return this
+  }
+
+  /**
+   * Copy pluginLocations schema extensions from the extension plugins to the appropriate model schemas
+   * @returns {Schemas}
+   * @example
+   * courseModelSchema.properties._assessment
+   * articleModelSchema.properties._trickle
+   * blockModelSchema.properties._trickle
+   */
+  generateModelExtensions () {
+    const extensionSchemas = this.schemas.filter(schema => schema instanceof ExtensionSchema)
+    extensionSchemas.forEach(schema => {
+      const extensionParts = schema.getModelExtensionParts()
+      if (!extensionParts) {
+        return
+      }
+      for (const modelName in extensionParts) {
+        const extensionPart = extensionParts[modelName]
+        /**
+         * Check if the sub-schema part has any defined properties.
+         * A lot of extension schemas have empty objects with no properties.
+         */
+        if (!extensionPart.properties) {
+          continue
+        }
+        const modelSchema = this.getModelSchemaByName(modelName)
+        if (!modelSchema) {
+          const err = new Error(`Cannot add extensions to model which doesn't exits ${modelName}`)
+          err.number = 10012
+          throw err
+        }
+        /**
+         * Notice that the targetAttribute is not used here, we allow the extension schema
+         * to define its own _[targetAttribute] to extend any core model.
+         */
+        modelSchema.json.properties = _.merge({}, modelSchema.json.properties, extensionPart.properties)
+      }
+    })
+    return this
+  }
+
+  /**
+   * @param {string} schemaName
+   * @returns {ModelSchema}
+   */
+  getModelSchemaByName (schemaName) {
+    const modelSchemas = this.schemas.filter(schema => schema instanceof ModelSchema)
+    return modelSchemas.find(({ name }) => name === schemaName)
+  }
+
+  /** @returns {ModelSchema} */
+  getCourseSchema () {
+    return this.getModelSchemaByName('course')
+  }
+
+  /** @returns {ModelSchema} */
+  getConfigSchema () {
+    return this.getModelSchemaByName('config')
+  }
+
+  /**
+   * Uses a model JSON to derive the appropriate schemas for the model.
+   * @param {Object} json
+   * @returns {ModelSchemas}
+   */
+  getSchemasForModelJSON (json) {
+    const schemas = []
+    if (json._type) {
+      if (json._type === 'menu' || json._type === 'page') {
+        schemas.push(this.getModelSchemaByName('contentobject'))
+      }
+      schemas.push(this.getModelSchemaByName(json._type))
+    }
+    if (json._component) {
+      schemas.push(this.getModelSchemaByName(json._component))
+    }
+    if (json._model) {
+      schemas.push(this.getModelSchemaByName(json._model))
+    }
+    return new ModelSchemas({
+      framework: this.framework,
+      schemas: schemas.filter(Boolean)
+    })
+  }
+}
+
+export default Schemas