adapt-authoring-core 3.0.1 → 3.1.0

package/conf/config.schema.json

@@ -40,6 +40,44 @@
       "description": "The default language used by the server",
       "type": "string",
       "default": "en"
+    },
+    "appName": {
+      "description": "Application name displayed in the UI header and browser tab",
+      "type": "string",
+      "default": "Adapt",
+      "_adapt": { "isPublic": true }
+    },
+    "primaryColour": {
+      "description": "Primary palette colour for the UI theme (hex format)",
+      "type": "string",
+      "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+      "default": "#1ec0d9",
+      "_adapt": { "isPublic": true }
+    },
+    "chromeColour": {
+      "description": "Chrome colour (navy): icon rail, app bar, headings (hex format)",
+      "type": "string",
+      "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+      "default": "#263944",
+      "_adapt": { "isPublic": true }
+    },
+    "commitColour": {
+      "description": "Commit colour (mint): the single affirmative action per view, e.g. Save/Create (hex format)",
+      "type": "string",
+      "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+      "default": "#00dd95",
+      "_adapt": { "isPublic": true }
+    },
+    "accentColour": {
+      "description": "Accent colour (expressive) and the default decorative-icon ink; never a button fill (hex format)",
+      "type": "string",
+      "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+      "default": "#ec4899",
+      "_adapt": { "isPublic": true }
+    },
+    "logo": {
+      "description": "Absolute path to a custom logo image (PNG recommended — email-safe) to bake into the UI build (overrides the built-in mark) and reuse in branded emails. Leave unset to use the built-in logo.",
+      "type": "string"
     }
   }
 }

package/docs/writing-a-module.md

@@ -122,4 +122,33 @@ If you don't want to publish your module to npm, you can simply provide the URL
     "adapt-authoring-mymodule": "https://github.com/MY_GITHUB_ACCOUNT/GITHUB_REPO_NAME.git"
   }
 }
-```
+```
+
+## Conventions
+
+Beyond structure and code, modules follow a few project-wide conventions.
+
+### Linting
+
+All code must pass [Standard.js](https://standardjs.com/) — no config file is needed. Run `npx standard` in the module root; it must pass before opening a PR.
+
+### Testing
+
+Write tests with `node:test` and `node:assert/strict` (see [Writing tests](writing-tests)). The project's testable-code conventions:
+
+- Extract discrete logic (transformations, mappers, predicates, validators) into one function per file under `lib/utils/<fn>.js`, re-exported via a `lib/utils.js` barrel.
+- Keep logic in the class only when it needs instance state, orchestrates side effects, or is a trivial one-liner delegating to a utility.
+- Each utility gets a matching `tests/utils-<name>.spec.js`, importing the file directly.
+- Use `mock.module()` (before the dynamic `import()`) when the function imports app modules; use table-driven tests for mappers and lookups.
+- Run unit tests with `node --experimental-test-module-mocks --test 'tests/**/*.spec.js'`.
+
+### Workflow and releases
+
+- Start from a clean `master` (`git checkout master && git pull`), then branch.
+- Commit with `Tag: description (fixes #N)` — the tag determines the release type (see [Contributing code](contributing-code)).
+- Merging to `master` triggers an **immediate** semantic-release publish; there is no staging step between merge and publish (see [Developer workflow](developer-workflow)).
+
+### Documentation
+
+- Document non-obvious behaviour in `docs/*.md` guides (built into the documentation site), not just inline comments. Cover what the module does, the APIs/seams it exposes, and any gotchas.
+- Keep the guides current: when a change alters documented behaviour, update the relevant `docs/*.md` in the **same PR**. Treat stale docs as a bug.

package/lib/DependencyLoader.js

@@ -68,8 +68,9 @@ class DependencyLoader {
     const deps = files
       .map(d => d.replace(`${metadataFileName}`, ''))
       .sort((a, b) => {
-        if (a.endsWith(corePathSegment)) return -1
-        if (b.endsWith(corePathSegment)) return 1
+        const aIsCore = a.endsWith(corePathSegment)
+        const bIsCore = b.endsWith(corePathSegment)
+        if (aIsCore !== bIsCore) return aIsCore ? -1 : 1
         return a.length - b.length
       })
     for (const d of deps) {
@@ -133,11 +134,14 @@ class DependencyLoader {
     if (typeof instance.onReady !== 'function') {
       throw this.app.errors.DEP_NO_ONREADY.setData({ module: modName })
     }
+    let timer
     try {
       const timeout = this.app.getConfig('moduleLoadTimeout') ?? 10000
       await Promise.race([
         instance.onReady(),
-        new Promise((resolve, reject) => setTimeout(() => reject(this.app.errors.DEP_TIMEOUT.setData({ module: modName, timeout })), timeout))
+        new Promise((resolve, reject) => {
+          timer = setTimeout(() => reject(this.app.errors.DEP_TIMEOUT.setData({ module: modName, timeout })), timeout)
+        })
       ])
       this.instances[modName] = instance
       await this.moduleLoadedHook.invoke(null, instance)
@@ -145,6 +149,8 @@ class DependencyLoader {
     } catch (e) {
       await this.moduleLoadedHook.invoke(e, { name: modName })
       throw e
+    } finally {
+      clearTimeout(timer)
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-core",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "A bundle of reusable 'core' functionality",
   "homepage": "https://github.com/adapt-security/adapt-authoring-core",
   "license": "GPL-3.0",

package/tests/DependencyLoader.spec.js

@@ -4,7 +4,8 @@ import AdaptError from '../lib/AdaptError.js'
 import DependencyLoader from '../lib/DependencyLoader.js'
 import fs from 'fs-extra'
 import path from 'path'
-import { fileURLToPath } from 'url'
+import { fileURLToPath, pathToFileURL } from 'url'
+import { setTimeout as wait } from 'timers/promises'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
@@ -132,6 +133,39 @@ describe('DependencyLoader', () => {
     })
   })
 
+  describe('#loadConfigs() with nested duplicate', () => {
+    let testRootDir
+
+    before(async () => {
+      testRootDir = path.join(__dirname, 'data', 'loadconfigs-nested-root')
+      const topCoreDir = path.join(testRootDir, 'node_modules', 'adapt-authoring-core')
+      const otherDir = path.join(testRootDir, 'node_modules', 'adapt-authoring-other')
+      const nestedCoreDir = path.join(otherDir, 'node_modules', 'adapt-authoring-core')
+      await fs.ensureDir(topCoreDir)
+      await fs.ensureDir(nestedCoreDir)
+      await fs.writeJson(path.join(topCoreDir, 'package.json'), { name: 'adapt-authoring-core', version: '3.0.0' })
+      await fs.writeJson(path.join(topCoreDir, 'adapt-authoring.json'), { module: false })
+      await fs.writeJson(path.join(otherDir, 'package.json'), { name: 'adapt-authoring-other' })
+      await fs.writeJson(path.join(otherDir, 'adapt-authoring.json'), { module: true })
+      await fs.writeJson(path.join(nestedCoreDir, 'package.json'), { name: 'adapt-authoring-core', version: '1.9.2' })
+      await fs.writeJson(path.join(nestedCoreDir, 'adapt-authoring.json'), { module: false })
+    })
+
+    after(async () => {
+      await fs.remove(testRootDir)
+    })
+
+    it('should prefer the top-level core over a nested duplicate', async () => {
+      const mockApp = { rootDir: testRootDir, name: 'adapt-authoring-core' }
+      const loader = new DependencyLoader(mockApp)
+      await loader.loadConfigs()
+      const winningPath = loader.configs['adapt-authoring-core'].rootDir
+      const expected = path.join(testRootDir, 'node_modules', 'adapt-authoring-core') + path.sep
+      assert.equal(winningPath, expected)
+      assert.equal(loader.configs['adapt-authoring-core'].version, '3.0.0')
+    })
+  })
+
   describe('#loadModuleConfig()', () => {
     let testModuleDir
 
@@ -346,6 +380,26 @@ describe('DependencyLoader', () => {
 
       assert.equal(loader.instances['non-module'], undefined)
     })
+
+    it('should clear the load-timeout timer once onReady resolves', async () => {
+      let timeoutAccessed = false
+      const mockApp = {
+        rootDir: '/test',
+        getConfig: () => 25,
+        errors: {
+          get DEP_TIMEOUT () { timeoutAccessed = true; return new AdaptError('DEP_TIMEOUT') }
+        }
+      }
+      const loader = new DependencyLoader(mockApp)
+      const packageName = pathToFileURL(path.join(__dirname, 'data', 'fast-module.js')).href
+      loader.configs = { 'fast-module': { name: 'fast-module', module: true, packageName } }
+
+      await loader.loadModule('fast-module')
+      await wait(75)
+
+      assert.equal(timeoutAccessed, false, 'DEP_TIMEOUT should never be accessed after a successful load')
+      assert.ok(loader.instances['fast-module'])
+    })
   })
 
   describe('#waitForModule()', () => {

package/tests/data/fast-module.js

@@ -0,0 +1,13 @@
+export default class FastModule {
+  constructor (app, config) {
+    this.app = app
+    this.config = config
+    this.name = config.name
+    this._isReady = false
+  }
+
+  async onReady () {
+    this._isReady = true
+    return this
+  }
+}