adapt-authoring-core 2.1.4 → 2.2.1

package/docs/contributing-code.md

@@ -88,51 +88,51 @@ We use [semantic-release](https://semantic-release.gitbook.io/) to automate rele
 | Prefix | Release type | Use for |
 |--------|--------------|---------|
 | `Fix:` | Patch (0.0.x) | Bug fixes |
-| `Update:` | Minor (0.x.0) | New features, backwards-compatible changes |
+| `Update:` | Minor (0.x.0) | Backwards-compatible enhancements to existing features |
+| `New:` | Minor (0.x.0) | New features |
 | `Breaking:` | Major (x.0.0) | Breaking changes |
 | `Docs:` | No release | Documentation only |
-| `Chore:` | No release | Maintenance, refactoring |
+| `Build:` | No release | Build process changes |
+| `Upgrade:` | Varies | Dependency upgrades |
+| `Chore:` | No release | Maintenance, refactoring, tests |
 
 ### Format
 
 ```
-Prefix: Short description
+Prefix: Short description (fixes #1234)
+```
 
-Longer explanation if needed. Wrap at 72 characters.
+Use `(fixes #1234)` when the commit fully resolves an issue, or `(refs #1234)` for partial progress. Keep the first line under 72 characters.
 
-Closes #1234
-```
+Add a longer explanation on subsequent lines if needed:
 
-### Examples
+```
+Prefix: Short description (fixes #1234)
 
+Longer explanation if needed. Wrap at 72 characters.
 ```
-Fix: Prevent crash when uploading empty file
 
-The upload handler now validates file size before processing,
-returning a 400 error for empty files.
+### Examples
 
-Closes #1234
 ```
-
+Fix: Prevent crash when uploading empty file (fixes #1234)
 ```
-Update: Add bulk delete endpoint for assets
 
-Closes #5678
+```
+Update: Add bulk delete endpoint for assets (fixes #5678)
 ```
 
 ```
-Breaking: Remove deprecated /api/v1 endpoints
+Breaking: Remove deprecated /api/v1 endpoints (fixes #9012)
 
 The v1 API has been removed. All clients should migrate to /api.
-
-Closes #9012
 ```
 
 ### Tips
 
 - Use the imperative mood ("Add feature" not "Added feature")
 - Keep the first line under 72 characters
-- Reference the issue number with `Closes #1234` to auto-close it when merged
+- Reference the issue in the first line with `(fixes #N)` or `(refs #N)`
 - For breaking changes, explain what users need to do to migrate
 
 ## Submitting a pull request

package/docs/folder-structure.md

@@ -80,7 +80,7 @@ Command-line tools are found in the `bin` folder. Modules can also provide their
 
 ## `docs`
 
-The `doc` folder contains documentation pages. These are picked up and compiled by the documentation generation tools when running `at-docgen`. See the [Building the docs](building-docs) for details.
+The `docs` folder contains documentation pages. These are picked up and compiled by the documentation generation tools when running `at-docgen`. See the [Building the docs](building-docs) for details.
 
 ## `conf`
 

package/docs/hooks.md

@@ -12,7 +12,7 @@ All hook observers must complete before the operation continues. For example, a
 
 Hooks can be either **mutable** or **immutable**:
 
-- **Immutable**: the _default_ behaviour, observers receive a deep copy of any arguments to ensure that the original data is read-only and prevent unintended modifications. By default, observers are run in parallel (at the same time).
+- **Immutable**: the _default_ behaviour. Observers are run in parallel (at the same time). When running in series, observers receive a deep copy of arguments to prevent unintended modifications.
 - **Mutable**: hooks allow modification of param data, and run observers in series (one after another) to ensure modifications are applied in order.
 
 ## Basic usage
@@ -119,8 +119,8 @@ Below are some commonly used hooks, which you may find useful.
 | AbstractApiModule | `accessCheckHook` | Check document access | `(req, doc)` | No |
 | AdaptFrameworkBuild | `preBuildHook` | Before course build starts | | Yes |
 | AdaptFrameworkBuild | `postBuildHook` | After course build completes | | Yes |
-| AdaptFrameworkImport | `preImportHook` | Before course import starts | | No |
-| AdaptFrameworkImport | `postImportHook` | After course import completes | | No |
+| AdaptFrameworkModule | `preImportHook` | Before course import starts | | Yes |
+| AdaptFrameworkModule | `postImportHook` | After course import completes | | No |
 
 ## Practical examples
 

package/docs/writing-a-module.md

@@ -23,21 +23,19 @@ The below is what we recommend, and is the approach taken by the the core dev te
 | `conf` | Folder | All config files go here (in `.schema.json` format) |
 | `docs` | Folder | Documentation files go here (in `.md` format) |
 | `lib` | Folder | All `.js` code should go here |
-| `test` | Folder | Test scripts go here (in `*.spec.js`) |
+| `tests` | Folder | Test scripts go here (in `*.spec.js`) |
 | `index.js` | File | Contains all of the exports for your module |
 | `adapt-authoring.json` | File | Adapt-specific metadata file used when initialising the app |
 | `package.json` | File | npm configuration file |
+| `routes.json` | File | _(Optional)_ Declarative route definitions for modules that expose HTTP endpoints. See [Handling server requests](server-requests.md) and [Authentication and permissions](auth-permissions.md) for details. |
 
 ##### A note on exports:
-If your module needs to export more than just your main module class, you must make sure your module class uses the key `Module` in order to be loaded by DependencyLoader. For example:
-
-```
-export default {
-  Module: MyModuleClass,
-  utils: MyUtilsClass,
-  // ...other exports
-};
+Your module class must be the **default export** — this is what `DependencyLoader` imports. For additional exports, use named exports:
 
+```javascript
+// index.js
+export { default } from './lib/MyModule.js'
+export { MyUtilsClass } from './lib/utils.js'
 ```
 
 ## 2. Set up your package.json
@@ -81,7 +79,7 @@ If you need to wait for another module to initialise before you can continue, th
 See below for an example:
 
 ```javascript
-const { AbstractModule } = require('adapt-authoring-core');
+import { AbstractModule } from 'adapt-authoring-core'
 
 export default class MyModule extends AbstractModule {
   /** @override */

package/docs/writing-tests.md

@@ -164,7 +164,7 @@ const fixtures = JSON.parse(readFileSync(join(__dirname, 'data', 'fixtures.json'
 
 ```json
 "scripts": {
-  "test": "node --test tests/"
+  "test": "node --test 'tests/*.spec.js'"
 }
 ```
 

package/index.js

@@ -2,4 +2,4 @@ export { default as AbstractModule } from './lib/AbstractModule.js'
 export { default as App } from './lib/App.js'
 export { default as DependencyLoader } from './lib/DependencyLoader.js'
 export { default as Hook } from './lib/Hook.js'
-export { metadataFileName, packageFileName, isObject, getArgs, spawn, readJson, writeJson, toBoolean, ensureDir, escapeRegExp, stringifyValues } from './lib/Utils.js'
+export { metadataFileName, packageFileName, isObject, getArgs, spawn, readJson, writeJson, toBoolean, ensureDir, escapeRegExp, stringifyValues, loadDependencyFiles } from './lib/Utils.js'

package/lib/Utils.js

@@ -8,3 +8,4 @@ export { toBoolean } from './utils/toBoolean.js'
 export { ensureDir } from './utils/ensureDir.js'
 export { escapeRegExp } from './utils/escapeRegExp.js'
 export { stringifyValues } from './utils/stringifyValues.js'
+export { loadDependencyFiles } from './utils/loadDependencyFiles.js'

package/lib/utils/loadDependencyFiles.js

@@ -0,0 +1,25 @@
+import fs from 'fs/promises'
+import { glob } from 'glob'
+import App from '../App.js'
+
+/**
+ * Scans files matching a glob pattern across all module dependency directories.
+ * @param {string} pattern - Glob pattern to match files (e.g. 'errors/*.json')
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.parse=false] - If true, reads and parses each matched file as JSON
+ * @param {Object} [options.dependencies] - Custom dependencies map (defaults to App.instance.dependencies)
+ * @returns {Promise<Object>} Map of module name to array of file paths (or parsed JSON objects if parse is true)
+ */
+export async function loadDependencyFiles (pattern, options = {}) {
+  const { parse = false, dependencies = App.instance.dependencies } = options
+  const results = {}
+  await Promise.all(Object.values(dependencies).map(async dep => {
+    const files = await glob(pattern, { cwd: dep.rootDir, absolute: true })
+    if (!files.length) return
+    results[dep.name] = await Promise.all(files.map(async f => {
+      if (parse) return JSON.parse(await fs.readFile(f, 'utf8'))
+      return f
+    }))
+  }))
+  return results
+}

package/package.json

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

package/tests/utils-loadDependencyFiles.spec.js

@@ -0,0 +1,91 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+
+import { loadDependencyFiles } from '../lib/utils/loadDependencyFiles.js'
+
+async function makeTempDir (suffix) {
+  return fs.mkdtemp(path.join(os.tmpdir(), `loadDepFiles-${suffix}-`))
+}
+
+describe('loadDependencyFiles()', () => {
+  it('should return file paths grouped by module name', async () => {
+    const dir = await makeTempDir('paths')
+    await fs.writeFile(path.join(dir, 'a.json'), '{"x":1}')
+    const deps = { mymod: { name: 'mymod', rootDir: dir } }
+    try {
+      const result = await loadDependencyFiles('*.json', { dependencies: deps })
+      assert.ok(result.mymod, 'should have entry for mymod')
+      assert.equal(result.mymod.length, 1)
+      assert.ok(result.mymod[0].endsWith('a.json'))
+    } finally {
+      await fs.rm(dir, { recursive: true })
+    }
+  })
+
+  it('should parse JSON when parse option is true', async () => {
+    const dir = await makeTempDir('parse')
+    await fs.writeFile(path.join(dir, 'b.json'), '{"key":"value"}')
+    const deps = { mymod: { name: 'mymod', rootDir: dir } }
+    try {
+      const result = await loadDependencyFiles('*.json', { parse: true, dependencies: deps })
+      assert.ok(result.mymod, 'should have entry for mymod')
+      assert.equal(result.mymod.length, 1)
+      assert.deepEqual(result.mymod[0], { key: 'value' })
+    } finally {
+      await fs.rm(dir, { recursive: true })
+    }
+  })
+
+  it('should return empty object when no files match', async () => {
+    const dir = await makeTempDir('nomatch')
+    const deps = { mymod: { name: 'mymod', rootDir: dir } }
+    try {
+      const result = await loadDependencyFiles('errors/*.json', { dependencies: deps })
+      assert.deepEqual(result, {})
+    } finally {
+      await fs.rm(dir, { recursive: true })
+    }
+  })
+
+  it('should group files by module name across multiple deps', async () => {
+    const dir1 = await makeTempDir('multi1')
+    const dir2 = await makeTempDir('multi2')
+    await fs.writeFile(path.join(dir1, 'x.json'), '"a"')
+    await fs.writeFile(path.join(dir2, 'y.json'), '"b"')
+    const deps = {
+      mod1: { name: 'mod1', rootDir: dir1 },
+      mod2: { name: 'mod2', rootDir: dir2 }
+    }
+    try {
+      const result = await loadDependencyFiles('*.json', { dependencies: deps })
+      assert.ok(result.mod1)
+      assert.ok(result.mod2)
+      assert.equal(result.mod1.length, 1)
+      assert.equal(result.mod2.length, 1)
+    } finally {
+      await fs.rm(dir1, { recursive: true })
+      await fs.rm(dir2, { recursive: true })
+    }
+  })
+
+  it('should not include modules with no matching files', async () => {
+    const dir1 = await makeTempDir('partial1')
+    const dir2 = await makeTempDir('partial2')
+    await fs.writeFile(path.join(dir1, 'match.json'), '{}')
+    const deps = {
+      mod1: { name: 'mod1', rootDir: dir1 },
+      mod2: { name: 'mod2', rootDir: dir2 }
+    }
+    try {
+      const result = await loadDependencyFiles('*.json', { dependencies: deps })
+      assert.ok(result.mod1)
+      assert.equal(result.mod2, undefined)
+    } finally {
+      await fs.rm(dir1, { recursive: true })
+      await fs.rm(dir2, { recursive: true })
+    }
+  })
+})