adapt-authoring-core 2.2.0 → 2.2.2

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/plugins/licensing.js

@@ -40,6 +40,10 @@ export default class Licensing {
 
   async storeLicenseData (pkg) {
     if (!pkg.license) {
+      const l = 'Undefined'
+      if (!this.licenses[l]) this.licenses[l] = { count: 0, packages: [] }
+      this.licenses[l].count++
+      this.licenses[l].packages.push(pkg.name)
       return
     }
     if (typeof pkg.license === 'object') {
@@ -49,14 +53,17 @@ export default class Licensing {
     for (let l of licenses) {
       l = this.licenseNameMap(l)
       if (this.licenses[l]) {
-        return this.licenses[l].count++
+        this.licenses[l].count++
+        this.licenses[l].packages.push(pkg.name)
+        return
       }
-      this.licenses[l] = { count: 1 }
+      this.licenses[l] = { count: 1, packages: [pkg.name] }
       try {
         const { GITHUB_USER, GITHUB_TOKEN } = process.env
         const res = await fetch(`https://api.github.com/licenses/${l.toLowerCase()}`, { headers: { Authorization: `Basic ${Buffer.from(`${GITHUB_USER}:${GITHUB_TOKEN}`).toString('base64')}` } })
-        if (res.status === 200) Object.assign(this.licenses[l], await res.json())
-        if (res.status > 299) console.error(`Failed to fetch '${l}' license: (${res.status}) ${(await res.json()).message}`)
+        const body = await res.json()
+        if (res.ok) Object.assign(this.licenses[l], body)
+        else console.log(`Could not fetch '${l}' license from GitHub API (${res.status}), will list as unknown`)
       } catch (e) {
         console.error(e)
       }
@@ -92,10 +99,10 @@ export default class Licensing {
 
   async generateLicenseDetailsMd () {
     let md = ''
-    Object.entries(this.licenses).forEach(([key, { name, spdxId, description, body, permissions }]) => {
+    Object.entries(this.licenses).forEach(([key, { name, spdx_id: spdxId, description, body, permissions }]) => {
       if (!name) return
       md += '<details>\n'
-      md += `<summary>${name} (${spdxId})</summary>\n`
+      md += `<summary>${name}${spdxId ? ` (${spdxId})` : ''}</summary>\n`
       md += `<p>${description}</p>\n`
       md += `<p>This license allows the following:\n<ul>${permissions.map(p => `<li>${this.permissionsMap(p)}</li>`).join('\n')}</ul></p>\n`
       md += '<p>The original license text is as follows:</p>\n'
@@ -106,11 +113,13 @@ export default class Licensing {
   }
 
   generateUnknownLicenseMd () {
-    const unknowns = []
-    Object.entries(this.licenses).forEach(([key, { name }]) => !name && unknowns.push(key))
-    if (unknowns.length) {
-      return `No information is held on the following licenses, please do your own research to dermine their suitability.\n\n${unknowns.map(u => `- ${u}`).join('\n')}\n`
-    }
+    const unknowns = Object.entries(this.licenses).filter(([, { name }]) => !name)
+    if (!unknowns.length) return ''
+    let md = 'No information is held on the following licenses, please do your own research to determine their suitability.\n\n'
+    unknowns.forEach(([key, { packages }]) => {
+      md += `- **${key}**: ${packages.join(', ')}\n`
+    })
+    return md
   }
 
   async generateMd () {

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/package.json

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