adapt-authoring-docs 1.3.1 → 1.4.0

package/.github/workflows/releases.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Update npm
         run: npm install -g npm@latest
       - name: Install dependencies
-        run: npm ci
+        run: npm install
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/standardjs.yml

@@ -1,4 +1,4 @@
-name: Standard.js formatting check
+name: Lint
 on: push
 jobs:
   default:
@@ -8,6 +8,5 @@ jobs:
       - uses: actions/setup-node@master
         with:
           node-version: 'lts/*'
-          cache: 'npm'
-      - run: npm ci
-      - run: npx standard
+      - run: npm install
+      - run: npx standard

package/.github/workflows/tests.yml

@@ -10,6 +10,5 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 'lts/*'
-          cache: 'npm'
-      - run: npm ci
+      - run: npm install
       - run: npm test

package/bin/docgen.js

@@ -2,7 +2,8 @@
 /**
  * Generates documentation for the installed modules.
  */
-import { App } from 'adapt-authoring-core'
+import { readJson } from 'adapt-authoring-core'
+import { loadDependencies, loadConfigDefaults, loadSchemas, loadErrors, buildRouterTree, buildPermissions } from '../lib/docsData.js'
 import docsify from '../docsify/docsify.js'
 import fs from 'fs/promises'
 import jsdoc3 from '../jsdoc3/jsdoc3.js'
@@ -11,10 +12,13 @@ import swagger from '../swagger/swagger.js'
 
 const DEBUG = process.argv.includes('--verbose')
 
-process.env.NODE_ENV ??= 'production'
-process.env.ADAPT_AUTHORING_LOGGER__mute = !DEBUG
+function getArg (name) {
+  const idx = process.argv.indexOf(name)
+  return idx !== -1 && idx + 1 < process.argv.length ? process.argv[idx + 1] : undefined
+}
+
+const rootDir = path.resolve(getArg('--rootDir') || process.cwd())
 
-const app = App.instance
 let outputdir
 
 const defaultPages = { // populated in cacheConfigs
@@ -27,10 +31,10 @@ const defaultPages = { // populated in cacheConfigs
 * Documentation for a module can be enabled in:
 * package.json > adapt_authoring.documentation.enable
 */
-function cacheConfigs () {
+function cacheConfigs (appData) {
   const cache = []
-  const excludes = app.pkg.documentation.excludes ?? []
-  Object.values(app.dependencies).forEach(dep => {
+  const excludes = appData.pkg.documentation.excludes ?? []
+  Object.values(appData.dependencies).forEach(dep => {
     const c = dep.documentation
 
     let omitMsg
@@ -49,16 +53,16 @@ function cacheConfigs () {
       ...c,
       name: dep.name,
       version: dep.version,
-      module: !!app.dependencyloader.instances[dep.name],
+      module: dep.module !== false,
       rootDir: dep.rootDir,
       includes: c.includes || {}
     })
   })
   cache.push({
-    ...app.pkg.documentation,
+    ...appData.pkg.documentation,
     enable: true,
     name: 'adapt-authoring',
-    rootDir: app.rootDir,
+    rootDir: appData.rootDir,
     includes: {}
   })
   return cache
@@ -71,19 +75,31 @@ async function copyRootFiles () {
 }
 
 async function docs () {
-  console.log(`Generating documentation for ${app.pkg.name}@${app.pkg.version} ${DEBUG ? ' :: DEBUG' : ''}`)
+  const dependencies = await loadDependencies(rootDir)
+  const pkg = { ...await readJson(path.join(rootDir, 'package.json')), ...await readJson(path.join(rootDir, 'adapt-authoring.json')) }
+  const config = await loadConfigDefaults(dependencies)
+  const schemas = await loadSchemas(dependencies)
+  const errors = await loadErrors(dependencies)
+  const routerTree = await buildRouterTree(dependencies)
+  const permissions = buildPermissions(routerTree)
 
-  try {
-    await app.onReady()
-  } catch (e) {
-    console.log(`App failed to start, cannot continue.\n${e}`)
-    process.exit(1)
+  const appData = {
+    rootDir,
+    pkg,
+    dependencies,
+    config,
+    errors,
+    schemas,
+    routerTree,
+    permissions
   }
-  const config = await app.waitForModule('config')
+
+  console.log(`Generating documentation for ${appData.pkg.name}@${appData.pkg.version} ${DEBUG ? ' :: DEBUG' : ''}`)
+
   const { name } = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url)))
-  outputdir = path.resolve(process.cwd(), config.get(`${name}.outputDir`))
+  outputdir = path.resolve(process.cwd(), getArg('--outputDir') || appData.config.get(`${name}.outputDir`))
 
-  const cachedConfigs = cacheConfigs()
+  const cachedConfigs = cacheConfigs(appData)
 
   console.log('\nThis might take a minute or two...\n')
 
@@ -91,9 +107,9 @@ async function docs () {
     await fs.rm(outputdir, { recursive: true, force: true })
     await fs.mkdir(outputdir)
     await copyRootFiles()
-    await jsdoc3(app, cachedConfigs, outputdir, defaultPages)
-    await docsify(app, cachedConfigs, outputdir, defaultPages)
-    await swagger(app, cachedConfigs, outputdir)
+    await jsdoc3(appData, cachedConfigs, outputdir, defaultPages)
+    await docsify(appData, cachedConfigs, outputdir, defaultPages)
+    await swagger(appData, cachedConfigs, outputdir)
   } catch (e) {
     console.log(e)
     process.exit(1)

package/bin/docserve.js

@@ -1,51 +1,39 @@
 #!/usr/bin/env node
 /**
- * Generates an HTTP server for viewing the local copy of the documentation (note these must be build first with `at-docgen`)
+ * Generates an HTTP server for viewing the local copy of the documentation (note these must be built first with `at-docgen`)
  */
-import { App } from 'adapt-authoring-core'
 import { spawn } from 'child_process'
 import http from 'http-server'
 import path from 'path'
-/*
-function getMime (filePath) {
-  const ext = path.parse(filePath).ext
-  return {
-    '.ico': 'image/x-icon',
-    '.html': 'text/html',
-    '.js': 'text/javascript',
-    '.json': 'application/json',
-    '.css': 'text/css',
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.svg': 'image/svg+xml',
-    '.pdf': 'application/pdf',
-    '.doc': 'application/msword'
-  }[ext] || 'text/plain'
+
+function getArg (name) {
+  const idx = process.argv.indexOf(name)
+  return idx !== -1 && idx + 1 < process.argv.length ? process.argv[idx + 1] : undefined
 }
-*/
-process.env.NODE_ENV ??= 'production'
-process.env.ADAPT_AUTHORING_LOGGER__mute = true
 
-console.log('Starting app, please wait\n')
-// TODO remove need to start app
-App.instance.onReady().then(async app => {
-  console.log('App started\n');
-  (await app.waitForModule('server')).close() // close connections so we can still run the app separately
+async function getOutputDir () {
+  const arg = getArg('--outputDir')
+  if (arg) return path.resolve(arg)
+  const { loadDependencies, loadConfigDefaults } = await import('../lib/docsData.js')
+  const rootDir = path.resolve(getArg('--rootDir') || process.cwd())
+  const dependencies = await loadDependencies(rootDir)
+  const config = await loadConfigDefaults(dependencies)
+  return path.resolve(config.get('adapt-authoring-docs.outputDir'))
+}
 
-  const ROOT = path.resolve(app.config.get('adapt-authoring-docs.outputDir'))
-  const PORT = 9000
-  const OPEN = process.argv.some(a => a === '--open')
+const ROOT = await getOutputDir()
+const PORT = Number(getArg('--port')) || 9000
+const OPEN = process.argv.some(a => a === '--open')
 
-  const server = http.createServer({ root: ROOT, cache: -1 })
+const server = http.createServer({ root: ROOT, cache: -1 })
 
-  server.listen(PORT, () => {
-    const url = `http://localhost:${PORT}`
-    console.log(`Docs hosted at ${url}`)
+server.listen(PORT, () => {
+  const url = `http://localhost:${PORT}`
+  console.log(`Docs hosted at ${url}`)
 
-    if (OPEN) {
-      const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'
-      spawn(`${command} ${url}`, { shell: true })
-        .on('error', e => console.log('spawn error', e))
-    }
-  })
+  if (OPEN) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'
+    spawn(`${command} ${url}`, { shell: true })
+      .on('error', e => console.log('spawn error', e))
+  }
 })

package/docsify/docsify.js

@@ -20,9 +20,9 @@ function generateSectionTitle (sectionName) {
 /**
  * Copies all doc files ready for the generator
  */
-export default async function docsify (app, configs, outputdir, defaultPages) {
+export default async function docsify (appData, configs, outputdir, defaultPages) {
   const dir = path.resolve(outputdir, 'manual')
-  const sectionsConf = app.config.get('adapt-authoring-docs.manualSections')
+  const sectionsConf = appData.config.get('adapt-authoring-docs.manualSections')
   const defaultSection = Object.entries(sectionsConf).find(([, data]) => data.default)?.[0]
   /**
    * init docsify folder
@@ -39,7 +39,7 @@ export default async function docsify (app, configs, outputdir, defaultPages) {
         try {
           const wrapper = await new DocsifyPluginWrapper({
             ...c,
-            app,
+            app: appData,
             docsRootDir: outputdir,
             pluginEntry: path.resolve(c.rootDir, p),
             outputDir: dir

package/jsdoc3/jsdoc3.js

@@ -14,7 +14,7 @@ function resolvePath (relativePath) {
   return fileURLToPath(new URL(relativePath, import.meta.url))
 }
 
-async function writeConfig (app, outputdir, indexFile) {
+async function writeConfig (appData, outputdir, indexFile) {
   return fs.writeFile(configPath, JSON.stringify({
     source: {
       include: getSourceIncludes(indexFile)
@@ -25,7 +25,7 @@ async function writeConfig (app, outputdir, indexFile) {
       search: true,
       static: true,
       menu: {
-        [`<img class="logo" src="assets/logo-outline-colour.png" />Adapt authoring tool back-end API documentation<br><span class="version">v${app.pkg.version}</span>`]: {
+        [`<img class="logo" src="assets/logo-outline-colour.png" />Adapt authoring tool back-end API documentation<br><span class="version">v${appData.pkg.version}</span>`]: {
           class: 'menu-title'
         },
         'Documentation home': {
@@ -60,7 +60,7 @@ async function writeConfig (app, outputdir, indexFile) {
       meta: {
         title: 'Adapt authoring tool UI documentation',
         description: 'Adapt authoring tool UI documentation',
-        keyword: `v${app.pkg.version}`
+        keyword: `v${appData.pkg.version}`
       },
       scripts: [
         'styles/adapt.css',
@@ -88,10 +88,10 @@ function getSourceIncludes (indexFile) {
   return includes
 }
 
-export default async function jsdoc3 (app, configs, outputdir, defaultPages) {
+export default async function jsdoc3 (appData, configs, outputdir, defaultPages) {
   cachedConfigs = configs
   const dir = `${outputdir}/backend`
-  await writeConfig(app, dir, defaultPages.sourceIndex)
+  await writeConfig(appData, dir, defaultPages.sourceIndex)
   try {
     await execPromise(`npx jsdoc -c ${configPath}`)
   } catch (e) {

package/lib/docsData.js

@@ -0,0 +1,298 @@
+import { loadDependencyFiles, readJson } from 'adapt-authoring-core'
+import { glob } from 'glob'
+import os from 'os'
+import path from 'path'
+import { pathToRegexp } from 'path-to-regexp'
+
+/**
+ * Globs node_modules for adapt-authoring.json files, merges each with its
+ * package.json and returns a { [name]: config } map.
+ * @param {string} rootDir Absolute path to the app root
+ * @returns {Promise<Object>}
+ */
+export async function loadDependencies (rootDir) {
+  const files = await glob('node_modules/**/adapt-authoring.json', {
+    cwd: rootDir,
+    absolute: true
+  })
+  const seen = new Set()
+  const deps = {}
+  const sorted = files.sort((a, b) => a.length - b.length)
+  for (const file of sorted) {
+    const dir = path.dirname(file)
+    try {
+      const pkg = await readJson(path.join(dir, 'package.json'))
+      if (seen.has(pkg.name)) continue
+      seen.add(pkg.name)
+      const meta = await readJson(file)
+      deps[pkg.name] = { ...pkg, ...meta, rootDir: dir }
+    } catch {
+      // skip modules with unreadable config
+    }
+  }
+  return deps
+}
+
+/**
+ * Reads conf/config.schema.json from each dependency, extracts default values,
+ * and returns a { get(key) } object. Resolves $TEMP to os.tmpdir().
+ * @param {Object} dependencies Dependencies map from loadDependencies
+ * @returns {Promise<Object>}
+ */
+export async function loadConfigDefaults (dependencies) {
+  const allConfigs = await loadDependencyFiles('conf/config.schema.json', {
+    parse: true,
+    dependencies
+  })
+  const defaults = {}
+  for (const [depName, [schema]] of Object.entries(allConfigs)) {
+    const props = schema.properties || {}
+    const modDefaults = {}
+    for (const [key, prop] of Object.entries(props)) {
+      if (prop.default !== undefined) modDefaults[key] = prop.default
+    }
+    if (Object.keys(modDefaults).length) defaults[depName] = modDefaults
+  }
+  return {
+    get: (key) => {
+      const dotIdx = key.indexOf('.')
+      if (dotIdx === -1) return defaults[key]
+      const modName = key.slice(0, dotIdx)
+      const propKey = key.slice(dotIdx + 1)
+      const val = defaults[modName]?.[propKey]
+      if (typeof val === 'string') return val.replace('$TEMP', os.tmpdir())
+      return val
+    }
+  }
+}
+
+/**
+ * Loads and merges all schema/*.schema.json files across dependencies.
+ * @param {Object} dependencies Dependencies map from loadDependencies
+ * @returns {Promise<Object>} { schemas, raw, getSchema }
+ */
+export async function loadSchemas (dependencies) {
+  const allSchemas = await loadDependencyFiles('schema/*.schema.json', {
+    parse: true,
+    dependencies
+  })
+  const schemaMap = {}
+  const rawMap = {}
+  for (const [, arr] of Object.entries(allSchemas)) {
+    for (const schema of arr) {
+      const name = schema.$anchor || schema.$id || 'unknown'
+      schemaMap[name] = true
+      rawMap[name] = schema
+    }
+  }
+  return {
+    schemas: schemaMap,
+    raw: rawMap,
+    getSchema: async (name) => ({ built: rawMap[name] || {} })
+  }
+}
+
+/**
+ * Loads and merges all errors/*.json files across dependencies.
+ * @param {Object} dependencies Dependencies map from loadDependencies
+ * @returns {Promise<Object>} Merged error map
+ */
+export async function loadErrors (dependencies) {
+  const allErrors = await loadDependencyFiles('errors/*.json', {
+    parse: true,
+    dependencies
+  })
+  const merged = {}
+  for (const arr of Object.values(allErrors)) {
+    for (const obj of arr) Object.assign(merged, obj)
+  }
+  // Match the AdaptError shape that plugins expect:
+  // { code, statusCode, meta: { description, data } }
+  return Object.entries(merged)
+    .sort()
+    .reduce((m, [code, { description, statusCode, data }]) => {
+      const meta = { description }
+      if (data) meta.data = data
+      m[code] = { code, statusCode, meta }
+      return m
+    }, {})
+}
+
+/**
+ * Reads routes.json files from dependencies and assembles an Express-like
+ * { path, routes, childRouters } tree rooted at /api.
+ * @param {Object} dependencies Dependencies map from loadDependencies
+ * @returns {Promise<Object>} Router tree
+ */
+export async function buildRouterTree (dependencies) {
+  const apiRouter = { path: '/api', routes: [], childRouters: [] }
+  let authRouter = null
+  let apiDefaultRoutes = null
+  let authDefaultRoutes = null
+
+  const authDep = dependencies['adapt-authoring-auth']
+  const apiDep = dependencies['adapt-authoring-api']
+
+  if (apiDep) {
+    try {
+      apiDefaultRoutes = await readJson(path.join(apiDep.rootDir, 'lib', 'default-routes.json'))
+    } catch { /* no defaults */ }
+  }
+  if (authDep) {
+    try {
+      authDefaultRoutes = await readJson(path.join(authDep.rootDir, 'lib', 'default-routes.json'))
+    } catch { /* no defaults */ }
+    try {
+      const coreAuthConfig = await readJson(path.join(authDep.rootDir, 'lib', 'routes.json'))
+      authRouter = {
+        path: '/api/auth',
+        routes: (coreAuthConfig.routes || []).map(r => staticRouteEntry(r)),
+        childRouters: []
+      }
+      apiRouter.childRouters.push(authRouter)
+    } catch { /* no auth routes */ }
+  }
+
+  const allRoutes = await loadDependencyFiles('routes.json', {
+    parse: true,
+    dependencies
+  })
+  for (const [depName, [config]] of Object.entries(allRoutes)) {
+    if (dependencies[depName].module === false) continue
+    if (config.type !== undefined) {
+      addAuthTypeRouter(config, authRouter, authDefaultRoutes)
+    } else if (config.root) {
+      addApiRouter(config, apiRouter, apiDefaultRoutes)
+    }
+  }
+  return apiRouter
+}
+
+/**
+ * Walks the router tree and builds a permission store with
+ * { get: [], post: [], ... } arrays of [regexp, scopes] tuples.
+ * @param {Object} routerTree Router tree from buildRouterTree
+ * @returns {Object} Permission store
+ */
+export function buildPermissions (routerTree) {
+  const store = { get: [], post: [], put: [], patch: [], delete: [] }
+  walkRouterPermissions(routerTree, store)
+  return store
+}
+
+// ------- internal helpers -------
+
+function addApiRouter (config, parentRouter, defaultRoutes) {
+  const root = config.root
+  const scope = config.permissionsScope || root
+  const schemaName = config.schemaName ?? root
+  const collectionName = config.collectionName ?? root
+
+  let routes = config.routes || []
+
+  if (config.useDefaultRoutes !== false && defaultRoutes) {
+    routes = mergeWithDefaults(routes, defaultRoutes.routes || [])
+  }
+
+  /* eslint-disable no-template-curly-in-string */
+  const replacements = {
+    '${scope}': scope,
+    '${schemaName}': schemaName,
+    '${collectionName}': collectionName
+  }
+  /* eslint-enable no-template-curly-in-string */
+
+  const childRouter = {
+    path: `/api/${root}`,
+    routes: routes.map(r => staticRouteEntry(replacePlaceholders(r, replacements))),
+    childRouters: []
+  }
+  parentRouter.childRouters.push(childRouter)
+}
+
+function addAuthTypeRouter (config, authRouter, defaultRoutes) {
+  if (!authRouter) return
+  const type = config.type
+  let routes = config.routes || []
+
+  if (defaultRoutes) {
+    routes = mergeWithDefaults(routes, defaultRoutes.routes || [])
+  }
+
+  const childRouter = {
+    path: `/api/auth/${type}`,
+    routes: routes.map(r => staticRouteEntry(r)),
+    childRouters: []
+  }
+  authRouter.childRouters.push(childRouter)
+}
+
+function mergeWithDefaults (customRoutes, defaultRoutes) {
+  const overrides = new Map(
+    customRoutes.filter(r => r.override).map(r => [r.route, r])
+  )
+  const matched = new Set()
+  const mergedDefaults = defaultRoutes.map(d => {
+    const o = overrides.get(d.route)
+    if (!o) return d
+    matched.add(d.route)
+    const { override, ...rest } = o
+    return { ...d, ...rest, handlers: { ...d.handlers, ...rest.handlers } }
+  })
+  const remaining = customRoutes.filter(r => !r.override || !matched.has(r.route))
+  return [...mergedDefaults, ...remaining]
+}
+
+function staticRouteEntry (routeDef) {
+  const handlers = {}
+  if (routeDef.handlers) {
+    for (const method of Object.keys(routeDef.handlers)) {
+      handlers[method] = () => {}
+    }
+  }
+  return {
+    route: routeDef.route,
+    handlers,
+    meta: routeDef.meta || {},
+    internal: routeDef.internal || false,
+    permissions: routeDef.permissions || {}
+  }
+}
+
+function walkRouterPermissions (router, store) {
+  for (const routeDef of router.routes) {
+    const fullRoute = `${router.path}${routeDef.route !== '/' ? routeDef.route : ''}`
+    for (const [method, scopes] of Object.entries(routeDef.permissions || {})) {
+      if (scopes === null) continue
+      const m = method.toLowerCase()
+      if (!store[m]) continue
+      try {
+        const { regexp } = pathToRegexp(fullRoute)
+        store[m].push([regexp, scopes])
+      } catch {
+        // skip routes that can't be compiled (unusual patterns)
+      }
+    }
+  }
+  for (const child of router.childRouters) {
+    walkRouterPermissions(child, store)
+  }
+}
+
+function replacePlaceholders (obj, replacements) {
+  if (typeof obj === 'string') {
+    return Object.entries(replacements).reduce(
+      (s, [k, v]) => v != null ? s.replaceAll(k, v) : s,
+      obj
+    )
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(item => replacePlaceholders(item, replacements))
+  }
+  if (obj && typeof obj === 'object' && obj.constructor === Object) {
+    return Object.fromEntries(
+      Object.entries(obj).map(([k, v]) => [k, replacePlaceholders(v, replacements)])
+    )
+  }
+  return obj
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-docs",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Tools for auto-generating documentation for the Adapt authoring tool",
   "homepage": "https://github.com/adapt-security/adapt-authoring-docs",
   "license": "GPL-3.0",
@@ -14,6 +14,7 @@
     "test": "node --test 'tests/**/*.spec.js'"
   },
   "dependencies": {
+    "adapt-authoring-core": "^2.0.0",
     "comment-parser": "^1.4.1",
     "docdash": "^2.0.2",
     "docsify-cli": "^4.4.4",
@@ -21,16 +22,9 @@
     "glob": "^13.0.0",
     "http-server": "^14.1.1",
     "jsdoc": "^4.0.3",
+    "path-to-regexp": "^8.0.0",
     "swagger-ui": "^5.17.14"
   },
-  "peerDependencies": {
-    "adapt-authoring-core": "^1.7.0"
-  },
-  "peerDependenciesMeta": {
-    "adapt-authoring-core": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@semantic-release/git": "^10.0.1",
     "conventional-changelog-eslint": "^6.0.0",

package/swagger/swagger.js

@@ -8,14 +8,12 @@ function resolvePath (relativePath) {
 /**
  *
  */
-export default async function swagger (app, configs, outputdir) {
-  const server = await app.waitForModule('server')
-  await app.onReady()
+export default async function swagger (appData, configs, outputdir) {
   const spec = {
     openapi: '3.0.3',
-    info: { version: app.pkg.version },
-    components: { schemas: await generateSchemaSpec(app) },
-    paths: generatePathSpec(app, server.api)
+    info: { version: appData.pkg.version },
+    components: { schemas: await generateSchemaSpec(appData.schemas) },
+    paths: generatePathSpec(appData.permissions, appData.routerTree)
   }
   // generate UI
   const dir = path.resolve(outputdir, 'rest')
@@ -38,8 +36,7 @@ export default async function swagger (app, configs, outputdir) {
   ])
 }
 
-async function generateSchemaSpec (app) {
-  const jsonschema = await app.waitForModule('jsonschema')
+async function generateSchemaSpec (jsonschema) {
   const schemas = {}
   await Promise.all(Object.keys(jsonschema.schemas).map(async s => {
     schemas[s] = sanitiseSchema((await jsonschema.getSchema(s)).built)
@@ -57,8 +54,7 @@ function sanitiseSchema (schema) {
   return schema
 }
 
-function generatePathSpec (app, router, paths = {}) {
-  const perms = app.dependencyloader.instances['adapt-authoring-auth'].permissions.routes
+function generatePathSpec (permissions, router, paths = {}) {
   router.routes.forEach(r => {
     const parameters = r.route.split('/').filter(r => r.startsWith(':')).map(r => {
       return {
@@ -70,7 +66,7 @@ function generatePathSpec (app, router, paths = {}) {
     const route = `${router.path}${r.route !== '/' ? r.route : ''}`
     paths[route] = Object.keys(r.handlers).reduce((memo, method) => {
       const meta = r.meta?.[method] || {}
-      const scopes = perms[method].find(p => route.match(p[0]))?.[1] || []
+      const scopes = permissions[method].find(p => route.match(p[0]))?.[1] || []
       let description = r.internal ? 'ROUTE IS ONLY ACCESSIBLE FROM LOCALHOST.<br/><br/>' : ''
       description += scopes.length
         ? `Required scopes: ${scopes.map(s => `<span>${s}</span>`).join(' ')}`
@@ -90,7 +86,7 @@ function generatePathSpec (app, router, paths = {}) {
     }, {})
   })
   if (router.childRouters.length) {
-    router.childRouters.forEach(childRouter => generatePathSpec(app, childRouter, paths))
+    router.childRouters.forEach(childRouter => generatePathSpec(permissions, childRouter, paths))
   }
   return Object.keys(paths).sort().reduce((m, k) => Object.assign(m, { [k]: paths[k] }), {})
 }

package/tests/docsData.spec.js

@@ -0,0 +1,462 @@
+import assert from 'node:assert/strict'
+import { describe, it, before, after } from 'node:test'
+import fs from 'fs/promises'
+import os from 'os'
+import path from 'path'
+
+/* eslint-disable no-template-curly-in-string */
+/**
+ * Creates a temporary fixture directory that simulates a minimal
+ * adapt-authoring app so docsData functions can be tested in isolation.
+ */
+async function createFixture () {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'docs-data-'))
+
+  // root package.json + adapt-authoring.json
+  await fs.writeFile(path.join(root, 'package.json'), JSON.stringify({
+    name: 'adapt-authoring',
+    version: '1.0.0'
+  }))
+  await fs.writeFile(path.join(root, 'adapt-authoring.json'), JSON.stringify({
+    module: false,
+    documentation: { enable: true },
+    essentialApis: []
+  }))
+
+  // --- fake api module (library, not a loaded module) ---
+  const apiDir = path.join(root, 'node_modules', 'adapt-authoring-api')
+  await fs.mkdir(path.join(apiDir, 'lib'), { recursive: true })
+  await fs.writeFile(path.join(apiDir, 'package.json'), JSON.stringify({
+    name: 'adapt-authoring-api',
+    version: '1.0.0'
+  }))
+  await fs.writeFile(path.join(apiDir, 'adapt-authoring.json'), JSON.stringify({
+    module: false,
+    documentation: { enable: true }
+  }))
+  await fs.writeFile(path.join(apiDir, 'lib', 'default-routes.json'), JSON.stringify({
+    routes: [
+      {
+        route: '/',
+        handlers: { post: 'requestHandler', get: 'queryHandler' },
+        permissions: { post: ['write:${scope}'], get: ['read:${scope}'] }
+      },
+      {
+        route: '/:_id',
+        handlers: { get: 'requestHandler', delete: 'requestHandler' },
+        permissions: { get: ['read:${scope}'], delete: ['write:${scope}'] }
+      }
+    ]
+  }))
+
+  // --- fake auth module ---
+  const authDir = path.join(root, 'node_modules', 'adapt-authoring-auth')
+  await fs.mkdir(path.join(authDir, 'lib'), { recursive: true })
+  await fs.writeFile(path.join(authDir, 'package.json'), JSON.stringify({
+    name: 'adapt-authoring-auth',
+    version: '1.0.0'
+  }))
+  await fs.writeFile(path.join(authDir, 'adapt-authoring.json'), JSON.stringify({
+    documentation: { enable: true }
+  }))
+  await fs.writeFile(path.join(authDir, 'lib', 'routes.json'), JSON.stringify({
+    routes: [
+      {
+        route: '/check',
+        handlers: { get: 'checkHandler' },
+        permissions: { get: null }
+      }
+    ]
+  }))
+  await fs.writeFile(path.join(authDir, 'lib', 'default-routes.json'), JSON.stringify({
+    routes: [
+      {
+        route: '/',
+        handlers: { post: 'authenticateHandler' },
+        permissions: { post: null }
+      },
+      {
+        route: '/register',
+        handlers: { post: 'registerHandler' },
+        permissions: { post: ['register:users'] }
+      }
+    ]
+  }))
+
+  // --- fake auth-local module (auth type) ---
+  const authLocalDir = path.join(root, 'node_modules', 'adapt-authoring-auth-local')
+  await fs.mkdir(authLocalDir, { recursive: true })
+  await fs.writeFile(path.join(authLocalDir, 'package.json'), JSON.stringify({
+    name: 'adapt-authoring-auth-local',
+    version: '1.0.0'
+  }))
+  await fs.writeFile(path.join(authLocalDir, 'adapt-authoring.json'), JSON.stringify({
+    documentation: { enable: true }
+  }))
+  await fs.writeFile(path.join(authLocalDir, 'routes.json'), JSON.stringify({
+    type: 'local',
+    routes: [
+      {
+        route: '/',
+        override: true,
+        handlers: { post: 'authenticateHandler' },
+        meta: { post: { summary: 'Local auth' } }
+      },
+      {
+        route: '/changepass',
+        handlers: { post: 'changePasswordHandler' },
+        permissions: { post: null }
+      }
+    ]
+  }))
+
+  // --- fake content module (API module) ---
+  const contentDir = path.join(root, 'node_modules', 'adapt-authoring-content')
+  await fs.mkdir(path.join(contentDir, 'schema'), { recursive: true })
+  await fs.mkdir(path.join(contentDir, 'errors'), { recursive: true })
+  await fs.mkdir(path.join(contentDir, 'conf'), { recursive: true })
+  await fs.writeFile(path.join(contentDir, 'package.json'), JSON.stringify({
+    name: 'adapt-authoring-content',
+    version: '1.0.0'
+  }))
+  await fs.writeFile(path.join(contentDir, 'adapt-authoring.json'), JSON.stringify({
+    documentation: { enable: true }
+  }))
+  await fs.writeFile(path.join(contentDir, 'routes.json'), JSON.stringify({
+    root: 'content',
+    routes: [
+      {
+        route: '/clone',
+        handlers: { post: 'handleClone' },
+        permissions: { post: ['write:${scope}'] }
+      }
+    ]
+  }))
+  await fs.writeFile(path.join(contentDir, 'schema', 'content.schema.json'), JSON.stringify({
+    $anchor: 'content',
+    type: 'object',
+    properties: {
+      title: { type: 'string' },
+      body: { type: 'string' }
+    }
+  }))
+  await fs.writeFile(path.join(contentDir, 'errors', 'errors.json'), JSON.stringify({
+    CONTENT_NOT_FOUND: { statusCode: 404, description: 'Content not found' }
+  }))
+  await fs.writeFile(path.join(contentDir, 'conf', 'config.schema.json'), JSON.stringify({
+    type: 'object',
+    properties: {
+      cacheDir: { type: 'string', default: '$TEMP/content-cache' }
+    }
+  }))
+
+  // --- fake docs module with config ---
+  const docsDir = path.join(root, 'node_modules', 'adapt-authoring-docs')
+  await fs.mkdir(path.join(docsDir, 'conf'), { recursive: true })
+  await fs.writeFile(path.join(docsDir, 'package.json'), JSON.stringify({
+    name: 'adapt-authoring-docs',
+    version: '1.0.0'
+  }))
+  await fs.writeFile(path.join(docsDir, 'adapt-authoring.json'), JSON.stringify({
+    module: false,
+    documentation: { enable: true }
+  }))
+  await fs.writeFile(path.join(docsDir, 'conf', 'config.schema.json'), JSON.stringify({
+    type: 'object',
+    properties: {
+      outputDir: { type: 'string', default: '$TEMP/docs-build' },
+      manualSections: {
+        type: 'object',
+        default: { 'getting-started': {}, 'other-guides': { default: true } }
+      }
+    }
+  }))
+
+  // --- module with useDefaultRoutes: false ---
+  const courseassetDir = path.join(root, 'node_modules', 'adapt-authoring-courseassets')
+  await fs.mkdir(courseassetDir, { recursive: true })
+  await fs.writeFile(path.join(courseassetDir, 'package.json'), JSON.stringify({
+    name: 'adapt-authoring-courseassets',
+    version: '1.0.0'
+  }))
+  await fs.writeFile(path.join(courseassetDir, 'adapt-authoring.json'), JSON.stringify({
+    documentation: { enable: true }
+  }))
+  await fs.writeFile(path.join(courseassetDir, 'routes.json'), JSON.stringify({
+    root: 'courseassets',
+    useDefaultRoutes: false,
+    routes: [
+      {
+        route: '/query',
+        handlers: { post: 'queryHandler' },
+        permissions: { post: ['read:${scope}'] }
+      }
+    ]
+  }))
+
+  // --- module with custom permissionsScope ---
+  const themeDir = path.join(root, 'node_modules', 'adapt-authoring-coursetheme')
+  await fs.mkdir(themeDir, { recursive: true })
+  await fs.writeFile(path.join(themeDir, 'package.json'), JSON.stringify({
+    name: 'adapt-authoring-coursetheme',
+    version: '1.0.0'
+  }))
+  await fs.writeFile(path.join(themeDir, 'adapt-authoring.json'), JSON.stringify({
+    documentation: { enable: true }
+  }))
+  await fs.writeFile(path.join(themeDir, 'routes.json'), JSON.stringify({
+    root: 'coursethemepresets',
+    permissionsScope: 'content',
+    routes: [
+      {
+        route: '/:_id/apply',
+        handlers: { post: 'applyHandler' },
+        permissions: { post: ['write:${scope}'] }
+      }
+    ]
+  }))
+
+  return root
+}
+
+describe('docsData', () => {
+  let fixtureDir
+  let dependencies
+
+  before(async () => {
+    fixtureDir = await createFixture()
+    const { loadDependencies } = await import('../lib/docsData.js')
+    dependencies = await loadDependencies(fixtureDir)
+  })
+
+  after(async () => {
+    if (fixtureDir) await fs.rm(fixtureDir, { recursive: true, force: true }).catch(() => {})
+  })
+
+  describe('loadDependencies', () => {
+    it('should discover all modules with adapt-authoring.json', () => {
+      assert.ok(dependencies['adapt-authoring-content'])
+      assert.ok(dependencies['adapt-authoring-auth'])
+      assert.ok(dependencies['adapt-authoring-auth-local'])
+      assert.ok(dependencies['adapt-authoring-docs'])
+      assert.ok(dependencies['adapt-authoring-api'])
+    })
+
+    it('should merge package.json and adapt-authoring.json for each dep', () => {
+      const content = dependencies['adapt-authoring-content']
+      assert.equal(content.name, 'adapt-authoring-content')
+      assert.equal(content.version, '1.0.0')
+      assert.ok(content.documentation)
+      assert.ok(content.rootDir)
+    })
+
+    it('should set rootDir on each dependency', () => {
+      for (const dep of Object.values(dependencies)) {
+        assert.ok(dep.rootDir, `${dep.name} should have rootDir`)
+        assert.ok(dep.rootDir.includes('node_modules'), `${dep.name} rootDir should be in node_modules`)
+      }
+    })
+  })
+
+  describe('loadConfigDefaults', () => {
+    it('should resolve $TEMP to os.tmpdir()', async () => {
+      const { loadConfigDefaults } = await import('../lib/docsData.js')
+      const config = await loadConfigDefaults(dependencies)
+      const outputDir = config.get('adapt-authoring-docs.outputDir')
+      assert.ok(outputDir.startsWith(os.tmpdir()), `expected ${outputDir} to start with ${os.tmpdir()}`)
+      assert.ok(outputDir.endsWith('/docs-build'))
+    })
+
+    it('should return object defaults', async () => {
+      const { loadConfigDefaults } = await import('../lib/docsData.js')
+      const config = await loadConfigDefaults(dependencies)
+      const sections = config.get('adapt-authoring-docs.manualSections')
+      assert.ok(sections)
+      assert.ok(sections['getting-started'] !== undefined)
+      assert.ok(sections['other-guides']?.default === true)
+    })
+
+    it('should return undefined for unknown config keys', async () => {
+      const { loadConfigDefaults } = await import('../lib/docsData.js')
+      const config = await loadConfigDefaults(dependencies)
+      assert.equal(config.get('nonexistent.key'), undefined)
+    })
+
+    it('should resolve $TEMP in non-docs modules', async () => {
+      const { loadConfigDefaults } = await import('../lib/docsData.js')
+      const config = await loadConfigDefaults(dependencies)
+      const cacheDir = config.get('adapt-authoring-content.cacheDir')
+      assert.ok(cacheDir.startsWith(os.tmpdir()))
+      assert.ok(cacheDir.endsWith('/content-cache'))
+    })
+  })
+
+  describe('buildRouterTree', () => {
+    it('should return api root router', async () => {
+      const { buildRouterTree } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      assert.equal(routerTree.path, '/api')
+    })
+
+    it('should create child routers for API modules', async () => {
+      const { buildRouterTree } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const paths = routerTree.childRouters.map(r => r.path)
+      assert.ok(paths.includes('/api/content'))
+    })
+
+    it('should merge default routes for API modules', async () => {
+      const { buildRouterTree } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const contentRouter = routerTree.childRouters.find(r => r.path === '/api/content')
+      assert.ok(contentRouter)
+      const routePaths = contentRouter.routes.map(r => r.route)
+      // default routes: / and /:_id, plus custom: /clone
+      assert.ok(routePaths.includes('/'), 'should have default root route')
+      assert.ok(routePaths.includes('/:_id'), 'should have default :_id route')
+      assert.ok(routePaths.includes('/clone'), 'should have custom clone route')
+    })
+
+    it('should skip default routes when useDefaultRoutes is false', async () => {
+      const { buildRouterTree } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const router = routerTree.childRouters.find(r => r.path === '/api/courseassets')
+      assert.ok(router)
+      assert.equal(router.routes.length, 1)
+      assert.equal(router.routes[0].route, '/query')
+    })
+
+    it('should replace placeholders in route config', async () => {
+      const { buildRouterTree } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const contentRouter = routerTree.childRouters.find(r => r.path === '/api/content')
+      const rootRoute = contentRouter.routes.find(r => r.route === '/')
+      assert.deepEqual(rootRoute.permissions.post, ['write:content'])
+      assert.deepEqual(rootRoute.permissions.get, ['read:content'])
+    })
+
+    it('should use permissionsScope for placeholder when defined', async () => {
+      const { buildRouterTree } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const themeRouter = routerTree.childRouters.find(r => r.path === '/api/coursethemepresets')
+      assert.ok(themeRouter)
+      const applyRoute = themeRouter.routes.find(r => r.route === '/:_id/apply')
+      assert.deepEqual(applyRoute.permissions.post, ['write:content'])
+    })
+
+    it('should create auth router at /api/auth', async () => {
+      const { buildRouterTree } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const authRouter = routerTree.childRouters.find(r => r.path === '/api/auth')
+      assert.ok(authRouter)
+      assert.ok(authRouter.routes.some(r => r.route === '/check'))
+    })
+
+    it('should create auth type child routers', async () => {
+      const { buildRouterTree } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const authRouter = routerTree.childRouters.find(r => r.path === '/api/auth')
+      const localRouter = authRouter.childRouters.find(r => r.path === '/api/auth/local')
+      assert.ok(localRouter)
+    })
+
+    it('should merge auth type routes with auth defaults', async () => {
+      const { buildRouterTree } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const authRouter = routerTree.childRouters.find(r => r.path === '/api/auth')
+      const localRouter = authRouter.childRouters.find(r => r.path === '/api/auth/local')
+      const routePaths = localRouter.routes.map(r => r.route)
+      // override route: /, default: /register, custom: /changepass
+      assert.ok(routePaths.includes('/'), 'should have root (overridden) route')
+      assert.ok(routePaths.includes('/register'), 'should have default register route')
+      assert.ok(routePaths.includes('/changepass'), 'should have custom changepass route')
+    })
+
+    it('should apply override merging from auth type routes', async () => {
+      const { buildRouterTree } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const authRouter = routerTree.childRouters.find(r => r.path === '/api/auth')
+      const localRouter = authRouter.childRouters.find(r => r.path === '/api/auth/local')
+      const rootRoute = localRouter.routes.find(r => r.route === '/')
+      // override merged meta from auth-local onto default
+      assert.ok(rootRoute.meta?.post?.summary === 'Local auth')
+    })
+  })
+
+  describe('loadSchemas', () => {
+    it('should load schemas from schema/*.schema.json', async () => {
+      const { loadSchemas } = await import('../lib/docsData.js')
+      const schemas = await loadSchemas(dependencies)
+      assert.ok(schemas.schemas.content)
+    })
+
+    it('should provide getSchema returning built schema', async () => {
+      const { loadSchemas } = await import('../lib/docsData.js')
+      const schemas = await loadSchemas(dependencies)
+      const result = await schemas.getSchema('content')
+      assert.ok(result.built)
+      assert.equal(result.built.type, 'object')
+      assert.ok(result.built.properties.title)
+    })
+
+    it('should return empty object for unknown schemas', async () => {
+      const { loadSchemas } = await import('../lib/docsData.js')
+      const schemas = await loadSchemas(dependencies)
+      const result = await schemas.getSchema('nonexistent')
+      assert.deepEqual(result.built, {})
+    })
+  })
+
+  describe('loadErrors', () => {
+    it('should load and merge errors from errors/*.json', async () => {
+      const { loadErrors } = await import('../lib/docsData.js')
+      const errors = await loadErrors(dependencies)
+      assert.ok(errors.CONTENT_NOT_FOUND)
+      assert.equal(errors.CONTENT_NOT_FOUND.statusCode, 404)
+      assert.equal(errors.CONTENT_NOT_FOUND.code, 'CONTENT_NOT_FOUND')
+      assert.equal(errors.CONTENT_NOT_FOUND.meta.description, 'Content not found')
+    })
+  })
+
+  describe('buildPermissions', () => {
+    it('should build permission store with HTTP methods', async () => {
+      const { buildRouterTree, buildPermissions } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const perms = buildPermissions(routerTree)
+      assert.ok(Array.isArray(perms.get))
+      assert.ok(Array.isArray(perms.post))
+      assert.ok(Array.isArray(perms.put))
+      assert.ok(Array.isArray(perms.patch))
+      assert.ok(Array.isArray(perms.delete))
+    })
+
+    it('should contain permission entries for secured routes', async () => {
+      const { buildRouterTree, buildPermissions } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const perms = buildPermissions(routerTree)
+      assert.ok(perms.post.length > 0, 'should have POST permission entries')
+      assert.ok(perms.get.length > 0, 'should have GET permission entries')
+    })
+
+    it('should skip routes with null permissions (unsecured)', async () => {
+      const { buildRouterTree, buildPermissions } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const perms = buildPermissions(routerTree)
+      // /api/auth/check has permissions: { get: null } — should not appear
+      const checkMatch = perms.get.find(([re]) => re.test('/api/auth/check'))
+      assert.equal(checkMatch, undefined, '/api/auth/check should not be in secured routes')
+    })
+
+    it('should store scopes as arrays in permission entries', async () => {
+      const { buildRouterTree, buildPermissions } = await import('../lib/docsData.js')
+      const routerTree = await buildRouterTree(dependencies)
+      const perms = buildPermissions(routerTree)
+      for (const entries of Object.values(perms)) {
+        for (const [re, scopes] of entries) {
+          assert.ok(re instanceof RegExp, 'first element should be RegExp')
+          assert.ok(Array.isArray(scopes), 'second element should be array')
+        }
+      }
+    })
+  })
+})

package/tests/swagger.spec.js

@@ -331,39 +331,21 @@ function createMockApp (options = {}) {
 
   return {
     pkg: { version: '1.0.0' },
-    dependencyloader: {
-      instances: {
-        'adapt-authoring-auth': {
-          permissions: {
-            routes: {
-              get: [],
-              post: [],
-              put: [],
-              patch: [],
-              delete: []
-            }
-          }
-        }
-      }
+    schemas: {
+      schemas: mockSchemas,
+      getSchema: mock.fn(async (s) => schemas[s])
     },
-    waitForModule: mock.fn(async (name) => {
-      if (name === 'jsonschema') {
-        return {
-          schemas: mockSchemas,
-          getSchema: mock.fn(async (s) => schemas[s])
-        }
-      }
-      if (name === 'server') {
-        return {
-          api: {
-            path: routerPath,
-            routes,
-            childRouters
-          }
-        }
-      }
-      return {}
-    }),
-    onReady: mock.fn(async () => {})
+    routerTree: {
+      path: routerPath,
+      routes,
+      childRouters
+    },
+    permissions: {
+      get: [],
+      post: [],
+      put: [],
+      patch: [],
+      delete: []
+    }
   }
 }