adapt-authoring-core 2.5.0 → 3.0.1

package/lib/Lang.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs'
+import { globSync } from 'glob'
+import path from 'node:path'
+
+/**
+ * Handles loading and translation of language strings.
+ * @memberof core
+ */
+class Lang {
+  /**
+   * @param {Object} options
+   * @param {Object} options.dependencies Key/value map of dependency configs (each with a rootDir)
+   * @param {String} options.defaultLang The default language for translations
+   * @param {String} options.rootDir The application root directory
+   * @param {Function} [options.log] Optional logging function (level, id, ...args)
+   */
+  constructor ({ dependencies, defaultLang, rootDir, log } = {}) {
+    /**
+     * The loaded language phrases
+     * @type {Object}
+     */
+    this.phrases = {}
+    /**
+     * The default language for translations
+     * @type {String}
+     */
+    this.defaultLang = defaultLang
+    /**
+     * Optional logging function (level, id, ...args)
+     * @type {Function}
+     */
+    this.log = log
+    this.loadPhrases(dependencies, rootDir, log)
+  }
+
+  /**
+   * Returns the languages supported by the application
+   * @type {Array<String>}
+   */
+  get supportedLanguages () {
+    return Object.keys(this.phrases)
+  }
+
+  /**
+   * Loads and merges all language phrases from dependencies
+   * @param {Object} dependencies Key/value map of dependency configs (each with a rootDir)
+   * @param {String} appRootDir The application root directory
+   * @param {Function} [log] Optional logging function (level, id, ...args)
+   */
+  loadPhrases (dependencies = {}, appRootDir, log) {
+    const dirs = [
+      ...(appRootDir ? [appRootDir] : []),
+      ...Object.values(dependencies).map(d => d.rootDir)
+    ]
+    for (const dir of dirs) {
+      const files = globSync('lang/**/*.json', { cwd: dir, absolute: true })
+      for (const f of files) {
+        try {
+          const relative = path.relative(path.join(dir, 'lang'), f)
+          const parts = relative.replace(/\.json$/, '').split(path.sep)
+          const lang = parts[0]
+          const prefix = parts.length > 1 ? parts.slice(1).join('.') + '.' : ''
+          if (!this.phrases[lang]) this.phrases[lang] = {}
+          const contents = JSON.parse(fs.readFileSync(f, 'utf8'))
+          Object.entries(contents).forEach(([k, v]) => { this.phrases[lang][`${prefix}${k}`] = v })
+        } catch (e) {
+          log?.('error', 'lang', e.message, f)
+        }
+      }
+    }
+  }
+
+  /**
+   * Returns translated language string. If key is an Error, translates using
+   * the error code as the key and error data for substitution. Non-Error,
+   * non-string values are returned unchanged.
+   * @param {String} lang The target language (falls back to defaultLang)
+   * @param {String|Error} key The unique string key, or an Error to translate
+   * @param {Object} data Dynamic data to be inserted into translated string
+   * @return {String}
+   */
+  translate (lang, key, data) {
+    if (typeof lang !== 'string') {
+      lang = this.defaultLang
+    }
+    if (key instanceof Error) {
+      if (!key.code) return key.message || String(key)
+      return this.translate(lang, `error.${key.code}`, key.data ?? key)
+    }
+    if (typeof key !== 'string') {
+      return key
+    }
+    const s = this.phrases[lang]?.[key]
+    if (!s) {
+      this.log?.('warn', 'lang', `missing key '${lang}.${key}'`)
+      return key
+    }
+    if (!data) {
+      return s
+    }
+    return this.substituteData(s, lang, data)
+  }
+
+  /**
+   * Replaces placeholders in a translated string with data values.
+   * Supports ${key} for simple substitution, and $map{key:attrs:delim}
+   * for mapping over array values.
+   * @param {String} s The translated string
+   * @param {String} lang The target language
+   * @param {Object} data Key/value pairs to substitute
+   * @return {String}
+   */
+  substituteData (s, lang, data) {
+    for (const [k, v] of Object.entries(data)) {
+      const items = [v].flat().map(item => item instanceof Error ? this.translate(lang, item) : item)
+      s = s.replaceAll(`\${${k}}`, items)
+      for (const [match, expr] of s.matchAll(new RegExp(String.raw`\$map{${k}:(.+)}`, 'g'))) {
+        const [attrs, delim] = expr.split(':')
+        s = s.replace(match, items.map(val => attrs.split(',').map(a => val?.[a] ?? a).join(delim)))
+      }
+    }
+    return s
+  }
+}
+
+export default Lang

package/lib/Logger.js

@@ -0,0 +1,149 @@
+import chalk from 'chalk'
+import Hook from './Hook.js'
+
+/**
+ * Provides console logging with configurable levels, colours, and module-specific overrides.
+ * @memberof core
+ */
+class Logger {
+  static levelColours = {
+    error: chalk.red,
+    warn: chalk.yellow,
+    success: chalk.green,
+    info: chalk.cyan,
+    debug: chalk.dim,
+    verbose: chalk.grey.italic
+  }
+
+  /**
+   * Creates a Logger instance from config values
+   * @param {Object} options
+   * @param {Array<String>} options.levels Log level config strings. An empty array mutes all output.
+   * @param {Boolean} options.showTimestamp Whether to show timestamps
+   */
+  constructor ({ levels = Object.keys(Logger.levelColours), showTimestamp = true } = {}) {
+    /**
+     * Hook invoked on each message logged
+     * @type {Hook}
+     */
+    this.logHook = new Hook()
+    /** @ignore */
+    this.config = {
+      levels: Object.entries(Logger.levelColours).reduce((m, [level, colour]) => {
+        m[level] = {
+          enable: Logger.isLevelEnabled(levels, level),
+          moduleOverrides: Logger.getModuleOverrides(levels, level),
+          lineOverrides: Logger.getLineOverrides(levels, level),
+          colour
+        }
+        return m
+      }, {}),
+      idOverrides: Logger.getIdOverrides(levels),
+      timestamp: showTimestamp,
+      mute: levels.length === 0
+    }
+  }
+
+  /**
+   * Logs a message to the console. When `args[0]` is a string it's treated as
+   * a short id for line-level filtering (e.g. `'verbose.server.ADD_ROUTE'`).
+   * @param {String} level Severity of the message
+   * @param {String} id Identifier for the message (typically the module name)
+   * @param {...*} args Arguments to be logged
+   */
+  log (level, id, ...args) {
+    const shortId = typeof args[0] === 'string' ? args[0] : undefined
+    if (this.config.mute || !Logger.isLoggingEnabled(this.config.levels, level, id, shortId, this.config.idOverrides)) {
+      return
+    }
+    const colour = this.config.levels[level]?.colour
+    const logFunc = console[level] ?? console.log
+    const timestamp = this.config.timestamp ? chalk.dim(`${new Date().toISOString()} `) : ''
+    logFunc(`${timestamp}${colour ? colour(level) : level} ${chalk.magenta(id)}`, ...args)
+    this.logHook.invoke(new Date(), level, id, ...args).catch((error) => {
+      console.error('Logger logHook invocation failed:', error)
+    })
+  }
+
+  /**
+   * Determines whether a specific log level is enabled
+   * @param {Array<String>} levelsConfig Array of level configuration strings
+   * @param {String} level The log level to check
+   * @return {Boolean}
+   */
+  static isLevelEnabled (levelsConfig, level) {
+    return !levelsConfig.includes(`!${level}`) && levelsConfig.includes(level)
+  }
+
+  /**
+   * Returns per-level module overrides (e.g. `debug.core` / `!debug.core`).
+   * @param {Array<String>} levelsConfig Array of level configuration strings
+   * @param {String} level The log level to find overrides for
+   * @return {Array<String>}
+   */
+  static getModuleOverrides (levelsConfig, level) {
+    return levelsConfig.filter(l => Logger.matchesLevelPrefix(l, level) && Logger.entrySegmentCount(l) === 2)
+  }
+
+  /**
+   * Returns per-level line overrides (e.g. `debug.core.LOAD` / `!debug.core.LOAD`).
+   * @param {Array<String>} levelsConfig Array of level configuration strings
+   * @param {String} level The log level to find overrides for
+   * @return {Array<String>}
+   */
+  static getLineOverrides (levelsConfig, level) {
+    return levelsConfig.filter(l => Logger.matchesLevelPrefix(l, level) && Logger.entrySegmentCount(l) >= 3)
+  }
+
+  /**
+   * Returns id-wide overrides — entries whose first segment isn't a known level,
+   * meaning they apply to that id at every level (e.g. `core` / `!core`).
+   * @param {Array<String>} levelsConfig Array of level configuration strings
+   * @return {Array<String>}
+   */
+  static getIdOverrides (levelsConfig) {
+    const knownLevels = Object.keys(Logger.levelColours)
+    return levelsConfig.filter(entry => {
+      const body = entry.startsWith('!') ? entry.slice(1) : entry
+      const firstSegment = body.split('.')[0]
+      return body.length > 0 && !knownLevels.includes(firstSegment)
+    })
+  }
+
+  /** @ignore */
+  static matchesLevelPrefix (entry, level) {
+    return entry.startsWith(`${level}.`) || entry.startsWith(`!${level}.`)
+  }
+
+  /** @ignore */
+  static entrySegmentCount (entry) {
+    const body = entry.startsWith('!') ? entry.slice(1) : entry
+    return body.split('.').length
+  }
+
+  /**
+   * Returns whether a message should be logged. Resolution order, most-specific
+   * wins: line-level (`!level.id.shortId`) → per-level module (`!level.id`)
+   * → id-wide (`!id`) → global level.
+   * @param {Object} configLevels The resolved levels config object
+   * @param {String} level Logging level
+   * @param {String} id Id of log caller
+   * @param {String} [shortId] Optional line-level id (typically `args[0]`)
+   * @param {Array<String>} [idOverrides] Id-wide override entries
+   * @returns {Boolean}
+   */
+  static isLoggingEnabled (configLevels, level, id, shortId, idOverrides = []) {
+    const { enable, moduleOverrides = [], lineOverrides = [] } = configLevels?.[level] || {}
+    if (typeof shortId === 'string') {
+      if (lineOverrides.includes(`!${level}.${id}.${shortId}`)) return false
+      if (lineOverrides.includes(`${level}.${id}.${shortId}`)) return true
+    }
+    if (moduleOverrides.includes(`!${level}.${id}`)) return false
+    if (moduleOverrides.includes(`${level}.${id}`)) return true
+    if (idOverrides.includes(`!${id}`)) return false
+    if (idOverrides.includes(id)) return true
+    return Boolean(enable)
+  }
+}
+
+export default Logger

package/lib/utils/getArgs.js

@@ -1,12 +1,10 @@
-import minimist from 'minimist'
+import { parseArgs } from 'node:util'
 
 /**
- * Returns the passed arguments, parsed by minimist for easy access
+ * Returns the passed arguments, parsed for easy access
  * @return {Object} The parsed arguments
- * @see {@link https://github.com/substack/minimist#readme}
  */
 export function getArgs () {
-  const args = minimist(process.argv)
-  args.params = args._.slice(2)
-  return args
+  const { values, positionals } = parseArgs({ strict: false, args: process.argv.slice(2) })
+  return { ...values, params: positionals }
 }

package/migrations/3.0.0-conf-migrate-lang-config.js

@@ -0,0 +1,7 @@
+export default function (migration) {
+  migration.describe('Move adapt-authoring-lang config keys to adapt-authoring-core')
+
+  migration
+    .where('adapt-authoring-lang')
+    .replace('defaultLang', 'adapt-authoring-core')
+}

package/migrations/3.0.0-conf-migrate-logger-config.js

@@ -0,0 +1,9 @@
+export default function (migration) {
+  migration.describe('Move adapt-authoring-logger config keys to adapt-authoring-core')
+
+  migration
+    .where('adapt-authoring-logger')
+    .replace('levels', 'adapt-authoring-core', 'logLevels')
+    .replace('showTimestamp', 'adapt-authoring-core', 'showLogTimestamp')
+    .remove('mute', 'dateFormat')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-core",
-  "version": "2.5.0",
+  "version": "3.0.1",
   "description": "A bundle of reusable 'core' functionality",
   "homepage": "https://github.com/adapt-security/adapt-authoring-core",
   "license": "GPL-3.0",
@@ -11,34 +11,17 @@
   },
   "repository": "github:adapt-security/adapt-authoring-core",
   "dependencies": {
-    "fs-extra": "11.3.3",
-    "glob": "^13.0.0",
-    "lodash": "^4.17.21",
-    "minimist": "^1.2.8"
+    "adapt-authoring-migrations": "^2.0.0",
+    "adapt-schemas": "^3.1.0",
+    "chalk": "^5.4.1",
+    "glob": "^13.0.0"
   },
   "devDependencies": {
-    "@semantic-release/git": "^10.0.1",
-    "conventional-changelog-eslint": "^6.0.0",
-    "semantic-release": "^25.0.2",
+    "@adaptlearning/semantic-release-config": "^1.0.0",
+    "fs-extra": "^11.3.4",
     "standard": "^17.1.0"
   },
   "release": {
-    "plugins": [
-      [
-        "@semantic-release/commit-analyzer",
-        {
-          "preset": "eslint"
-        }
-      ],
-      [
-        "@semantic-release/release-notes-generator",
-        {
-          "preset": "eslint"
-        }
-      ],
-      "@semantic-release/npm",
-      "@semantic-release/github",
-      "@semantic-release/git"
-    ]
+    "extends": "@adaptlearning/semantic-release-config"
   }
 }

package/tests/AbstractModule.spec.js

@@ -448,13 +448,8 @@ describe('AbstractModule', () => {
       assert.equal(result, 'testValue')
     })
 
-    it('should return undefined if config.get throws', async () => {
+    it('should return undefined when config is not available', async () => {
       const mockApp = {
-        config: {
-          get: () => {
-            throw new Error('config error')
-          }
-        },
         dependencyloader: {
           moduleLoadedHook: {
             tap: () => {},
@@ -615,57 +610,12 @@ describe('AbstractModule', () => {
       assert.deepEqual(loggedArgs, ['arg1', 'arg2', 'arg3'])
     })
 
-    it('should queue log and deliver when logger module loads', async () => {
-      let loggedLevel
-      let tapCallback
-      const mockApp = {
-        dependencyloader: {
-          moduleLoadedHook: {
-            tap: (fn) => { tapCallback = fn },
-            untap: () => {}
-          }
-        }
-      }
+    it('should silently skip when logger is not available', async () => {
+      const mockApp = {}
       const module = new AbstractModule(mockApp, { name: 'test-mod' })
       await module.onReady()
 
-      module.log('warn', 'deferred message')
-      assert.ok(tapCallback)
-
-      mockApp.logger = {
-        name: 'adapt-authoring-logger',
-        log: (level) => {
-          loggedLevel = level
-        }
-      }
-
-      tapCallback(null, { name: 'adapt-authoring-logger' })
-      assert.equal(loggedLevel, 'warn')
-    })
-
-    it('should not log when loaded module is not the logger', async () => {
-      const logCalled = false
-      let tapCallback
-      const mockApp = {
-        dependencyloader: {
-          moduleLoadedHook: {
-            tap: (fn) => { tapCallback = fn },
-            untap: () => {}
-          }
-        }
-      }
-      const module = new AbstractModule(mockApp, { name: 'test-mod' })
-      await module.onReady()
-
-      // No logger set yet, so log queues the callback
-      module.log('info', 'some message')
-      assert.ok(tapCallback)
-
-      // Now simulate a non-logger module loading - _log checks !this.app.logger
-      // which is true (no logger), so it returns false
-      const result = tapCallback(null, { name: 'adapt-authoring-other' })
-      assert.equal(result, false)
-      assert.equal(logCalled, false)
+      assert.doesNotThrow(() => module.log('warn', 'no logger'))
     })
   })
 

package/tests/AdaptError.spec.js

@@ -0,0 +1,62 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import AdaptError from '../lib/AdaptError.js'
+
+describe('AdaptError', () => {
+  describe('constructor', () => {
+    it('should set code and default statusCode', () => {
+      const error = new AdaptError('TEST_ERROR')
+      assert.equal(error.code, 'TEST_ERROR')
+      assert.equal(error.statusCode, 500)
+      assert.equal(error.isFatal, false)
+    })
+
+    it('should set custom statusCode', () => {
+      const error = new AdaptError('NOT_FOUND', 404)
+      assert.equal(error.statusCode, 404)
+    })
+
+    it('should set isFatal from metadata', () => {
+      const error = new AdaptError('FATAL_ERROR', 500, { isFatal: true })
+      assert.equal(error.isFatal, true)
+    })
+
+    it('should default isFatal to false when not in metadata', () => {
+      const error = new AdaptError('ERROR', 500, { description: 'test' })
+      assert.equal(error.isFatal, false)
+    })
+
+    it('should store metadata', () => {
+      const meta = { description: 'test error', data: { id: 'test' } }
+      const error = new AdaptError('ERROR', 500, meta)
+      assert.deepEqual(error.meta, meta)
+    })
+
+    it('should extend Error', () => {
+      const error = new AdaptError('TEST')
+      assert.ok(error instanceof Error)
+    })
+  })
+
+  describe('#setData()', () => {
+    it('should set data and return self for chaining', () => {
+      const error = new AdaptError('TEST')
+      const result = error.setData({ id: '123' })
+      assert.equal(result, error)
+      assert.deepEqual(error.data, { id: '123' })
+    })
+  })
+
+  describe('#toString()', () => {
+    it('should include code without data', () => {
+      const error = new AdaptError('TEST')
+      assert.ok(error.toString().includes('TEST'))
+    })
+
+    it('should include stringified data when set', () => {
+      const error = new AdaptError('TEST')
+      error.setData({ id: '123' })
+      assert.ok(error.toString().includes('123'))
+    })
+  })
+})

package/tests/Config.spec.js

@@ -0,0 +1,122 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import Config from '../lib/Config.js'
+import path from 'path'
+
+describe('Config', () => {
+  describe('constructor', () => {
+    it('should initialise with empty config', () => {
+      const config = new Config()
+      assert.deepEqual(config.publicAttributes, [])
+    })
+  })
+
+  describe('#has()', () => {
+    it('should return true for existing keys', () => {
+      const config = new Config()
+      config._config['test.key'] = 'value'
+      assert.equal(config.has('test.key'), true)
+    })
+
+    it('should return false for missing keys', () => {
+      const config = new Config()
+      assert.equal(config.has('missing.key'), false)
+    })
+  })
+
+  describe('#get()', () => {
+    it('should return value for existing key', () => {
+      const config = new Config()
+      config._config['test.key'] = 'value'
+      assert.equal(config.get('test.key'), 'value')
+    })
+
+    it('should return undefined for missing key', () => {
+      const config = new Config()
+      assert.equal(config.get('missing'), undefined)
+    })
+  })
+
+  describe('#getPublicConfig()', () => {
+    it('should return only public attributes', () => {
+      const config = new Config()
+      config._config['mod.public'] = 'yes'
+      config._config['mod.private'] = 'no'
+      config.publicAttributes = ['mod.public']
+      const result = config.getPublicConfig()
+      assert.deepEqual(result, { 'mod.public': 'yes' })
+    })
+  })
+
+  describe('.envVarToConfigKey()', () => {
+    it('should convert ADAPT_AUTHORING_ prefixed vars', () => {
+      const result = Config.envVarToConfigKey('ADAPT_AUTHORING_CORE__dataDir')
+      assert.equal(result, 'adapt-authoring-core.dataDir')
+    })
+
+    it('should prefix non-adapt vars with env.', () => {
+      const result = Config.envVarToConfigKey('NODE_ENV')
+      assert.equal(result, 'env.NODE_ENV')
+    })
+  })
+
+  describe('#storeEnvSettings()', () => {
+    it('should store env vars in config', () => {
+      const config = new Config()
+      process.env.TEST_CONFIG_VAR = 'test_value'
+      config.storeEnvSettings()
+      assert.equal(config.get('env.TEST_CONFIG_VAR'), 'test_value')
+      delete process.env.TEST_CONFIG_VAR
+    })
+
+    it('should parse JSON env values', () => {
+      const config = new Config()
+      process.env.TEST_JSON_VAR = '42'
+      config.storeEnvSettings()
+      assert.equal(config.get('env.TEST_JSON_VAR'), 42)
+      delete process.env.TEST_JSON_VAR
+    })
+  })
+
+  describe('#resolveDirectory()', () => {
+    it('should resolve $ROOT', () => {
+      const config = new Config()
+      config.rootDir = '/app'
+      assert.equal(config.resolveDirectory('$ROOT/APP_DATA/data'), path.resolve('/app', 'APP_DATA/data'))
+    })
+
+    it('should resolve $DATA', () => {
+      const config = new Config()
+      config.rootDir = '/app'
+      config._config['adapt-authoring-core.dataDir'] = '/app/APP_DATA/data'
+      assert.equal(config.resolveDirectory('$DATA/uploads'), path.resolve('/app/APP_DATA/data', 'uploads'))
+    })
+
+    it('should resolve $TEMP', () => {
+      const config = new Config()
+      config.rootDir = '/app'
+      config._config['adapt-authoring-core.tempDir'] = '/app/APP_DATA/temp'
+      assert.equal(config.resolveDirectory('$TEMP/cache'), path.resolve('/app/APP_DATA/temp', 'cache'))
+    })
+
+    it('should not resolve unresolved variables', () => {
+      const config = new Config()
+      config.rootDir = '/app'
+      assert.equal(config.resolveDirectory('$DATA/uploads'), '$DATA/uploads')
+    })
+
+    it('should return non-variable paths unchanged', () => {
+      const config = new Config()
+      config.rootDir = '/app'
+      assert.equal(config.resolveDirectory('/absolute/path'), '/absolute/path')
+    })
+  })
+
+  describe('#storeUserSettings()', () => {
+    it('should handle missing config file gracefully', async () => {
+      const config = new Config()
+      config.configFilePath = '/nonexistent/path/config.js'
+      await assert.doesNotReject(() => config.storeUserSettings())
+    })
+  })
+})