adapt-authoring-content 3.0.6 → 3.2.0

package/errors/errors.json

@@ -21,5 +21,12 @@
     },
     "description": "Resource is currently being used in courses",
     "statusCode": 400
+  },
+  "EMPTY_CONTAINERS": {
+    "data": {
+      "items": "The childless content items blocking the build"
+    },
+    "description": "Course cannot be built: one or more pages, articles or blocks have no content",
+    "statusCode": 400
   }
 }

package/lib/ContentModule.js

@@ -2,7 +2,7 @@ import { AbstractApiModule } from 'adapt-authoring-api'
 import { Hook, stringifyValues } from 'adapt-authoring-core'
 import { createObjectId, parseObjectId } from 'adapt-authoring-mongodb'
 import { ObjectId } from 'mongodb'
-import { ContentTree, computeSortOrderOps, contentTypeToSchemaName, extractAssetIds, formatFriendlyId, parseMaxSeq } from './utils.js'
+import { ContentTree, buildAssetUsagePipeline, computeSortOrderOps, contentTypeToSchemaName, extractAssetIds, formatFriendlyId, parseMaxSeq } from './utils.js'
 /**
  * Module which handles course content
  * @memberof content
@@ -59,6 +59,12 @@ class ContentModule extends AbstractApiModule {
 
     assets.preDeleteHook.tap(this.enforceAssetNotInUse.bind(this))
 
+    // block builds when the course structure has empty containers. adaptframework depends on
+    // content (not vice-versa), so tap its hook once available rather than awaiting it here.
+    this.app.waitForModule('adaptframework').then(framework => {
+      framework.preBuildHook.tap(this.enforceNoEmptyContainers.bind(this))
+    })
+
     await mongodb.setIndex(this.collectionName, { _courseId: 1, _parentId: 1, _type: 1 })
     await mongodb.setIndex(this.collectionName, { _parentId: 1 })
     await mongodb.setIndex(this.collectionName, { _type: 1, _courseId: 1 })
@@ -104,6 +110,45 @@ class ContentModule extends AbstractApiModule {
     throw this.app.errors.RESOURCE_IN_USE.setData({ type: 'asset', courses })
   }
 
+  /**
+   * preBuildHook observer: refuses a build when any non-component content item has no children
+   * (an empty page, article or block). Components are leaf nodes and config is exempt.
+   * @param {AdaptFrameworkBuild} build The build being run
+   * @return {Promise}
+   */
+  async enforceNoEmptyContainers (build) {
+    const _courseId = parseObjectId(build.courseId)
+    const items = await this.find(
+      { $or: [{ _id: _courseId }, { _courseId }] },
+      { validate: false },
+      { projection: { _type: 1, _parentId: 1, title: 1, displayTitle: 1 } }
+    )
+    const empty = new ContentTree(items).getEmptyContainers()
+    if (!empty.length) return
+    throw this.app.errors.EMPTY_CONTAINERS.setData({
+      items: empty.map(i => ({ _id: i._id.toString(), _type: i._type, title: i.displayTitle || i.title }))
+    })
+  }
+
+  /**
+   * Returns a map of asset _id to the number of distinct courses each asset is referenced by.
+   * Reads the indexed `_assetIds` field. Accepts an optional `assetIds` array in the request body to
+   * scope the counts (e.g. the page of assets shown in the UI); assets with no usage are omitted.
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {function} next
+   * @return {Promise}
+   */
+  async handleAssetUsage (req, res, next) {
+    try {
+      const assetIds = Array.isArray(req.body?.assetIds) ? req.body.assetIds.map(id => parseObjectId(id)) : undefined
+      const results = await this.mongodb.getCollection(this.collectionName).aggregate(buildAssetUsagePipeline(assetIds)).toArray()
+      res.json(Object.fromEntries(results.map(r => [r._id.toString(), r.courseCount])))
+    } catch (e) {
+      next(e)
+    }
+  }
+
   /** @override */
   async getSchemaName (data) {
     const { contentplugin } = this

package/lib/ContentTree.js

@@ -114,6 +114,20 @@ class ContentTree {
     return this.getChildren(item._parentId).filter(c => c._id.toString() !== id)
   }
 
+  /**
+   * Finds container items that have no children. Components are leaf nodes and
+   * config is a childless root — both are exempt; every other type (course, menu,
+   * page, article, block) is expected to contain at least one child.
+   * @returns {Array<Object>} Childless container items
+   */
+  getEmptyContainers () {
+    return this.items.filter(i =>
+      i._type !== 'component' &&
+      i._type !== 'config' &&
+      this.getChildren(i._id).length === 0
+    )
+  }
+
   /**
    * O(1) — unique component names across the course
    * @returns {Array<string>}

package/lib/utils/buildAssetUsagePipeline.js

@@ -0,0 +1,29 @@
+/**
+ * Builds the aggregation pipeline that counts, per asset, how many distinct courses reference it.
+ *
+ * Operates on the content collection's indexed `_assetIds` field (maintained on every content
+ * insert/update). The leading `$match` lets the query use the `_assetIds` index when scoped; the
+ * post-`$unwind` `$match` discards the other asset ids carried by matched documents so only the
+ * requested assets remain. Counting distinct `_courseId` via `$addToSet` (rather than documents)
+ * means an asset referenced by many content items within one course still counts as one course.
+ *
+ * Pure helper extracted from {@link ContentModule#handleAssetUsage} so it can be unit-tested without
+ * booting the app. Asset ids must already be coerced to ObjectId — `getCollection().aggregate()` is
+ * the raw driver and does not normalise ObjectId strings the way the module query layer does.
+ *
+ * @param {Array} [assetIds] Asset ObjectIds to scope the counts to. Omit/empty to count all assets.
+ * @returns {Array<Object>} Aggregation pipeline producing `{ _id: <assetId>, courseCount }` rows
+ * @memberof content
+ */
+export default function buildAssetUsagePipeline (assetIds) {
+  const match = Array.isArray(assetIds) && assetIds.length > 0
+    ? { $match: { _assetIds: { $in: assetIds } } }
+    : null
+  return [
+    ...(match ? [match] : []),
+    { $unwind: '$_assetIds' },
+    ...(match ? [match] : []),
+    { $group: { _id: '$_assetIds', courses: { $addToSet: '$_courseId' } } },
+    { $project: { courseCount: { $size: '$courses' } } }
+  ]
+}

package/lib/utils.js

@@ -1,4 +1,5 @@
 export { default as ContentTree } from './ContentTree.js'
+export { default as buildAssetUsagePipeline } from './utils/buildAssetUsagePipeline.js'
 export { default as computeSortOrderOps } from './utils/computeSortOrderOps.js'
 export { extractAssetIds } from './utils/extractAssetIds.js'
 export { default as contentTypeToSchemaName } from './utils/contentTypeToSchemaName.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-content",
-  "version": "3.0.6",
+  "version": "3.2.0",
   "description": "Module for managing Adapt content",
   "homepage": "https://github.com/adapt-security/adapt-authoring-content",
   "license": "GPL-3.0",

package/routes.json

@@ -110,6 +110,29 @@
           }
         }
       }
+    },
+    {
+      "route": "/assetusage",
+      "handlers": { "post": "handleAssetUsage" },
+      "permissions": { "post": ["read:${scope}"] },
+      "meta": {
+        "post": {
+          "summary": "Count how many distinct courses each asset is used in",
+          "requestBody": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "assetIds": { "type": "array", "items": { "type": "string" }, "description": "Optional list of asset _ids to scope the counts to. Omit to count all assets." }
+                  }
+                }
+              }
+            }
+          },
+          "responses": { "200": { "description": "Object mapping asset _id to the number of distinct courses referencing it; assets with no usage are omitted" } }
+        }
+      }
     }
   ]
 }

package/tests/ContentTree.spec.js

@@ -227,4 +227,53 @@ describe('ContentTree', () => {
       assert.deepEqual(tree.getComponentNames(), [])
     })
   })
+
+  describe('getEmptyContainers', () => {
+    it('should return container items that have no children', () => {
+      // in the shared fixture the menu (id4) and second article (id6) are childless
+      const empty = new ContentTree(items).getEmptyContainers()
+      assert.deepEqual(empty.map(i => i._id.toString()).sort(), ['id4', 'id6'])
+    })
+
+    it('should never flag components (leaf nodes)', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'block', _parentId: makeId(99) },
+        { _id: makeId(2), _type: 'component', _parentId: makeId(1), _component: 'adapt-contrib-text' }
+      ])
+      assert.equal(tree.getEmptyContainers().length, 0)
+    })
+
+    it('should never flag config (childless root)', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'course' },
+        { _id: makeId(2), _type: 'config', _courseId: 'c1' },
+        { _id: makeId(3), _type: 'page', _parentId: makeId(1) },
+        { _id: makeId(4), _type: 'article', _parentId: makeId(3) },
+        { _id: makeId(5), _type: 'block', _parentId: makeId(4) },
+        { _id: makeId(6), _type: 'component', _parentId: makeId(5), _component: 'adapt-contrib-text' }
+      ])
+      assert.deepEqual(tree.getEmptyContainers(), [])
+    })
+
+    it('should flag a block with no components', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'article', _parentId: makeId(99) },
+        { _id: makeId(2), _type: 'block', _parentId: makeId(1) }
+      ])
+      const empty = tree.getEmptyContainers()
+      assert.equal(empty.length, 1)
+      assert.equal(empty[0]._id.toString(), 'id2')
+    })
+
+    it('should flag a course with no children', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'course' }
+      ])
+      assert.deepEqual(tree.getEmptyContainers().map(i => i._type), ['course'])
+    })
+
+    it('should return empty array for an empty tree', () => {
+      assert.deepEqual(new ContentTree([]).getEmptyContainers(), [])
+    })
+  })
 })

package/tests/utils-buildAssetUsagePipeline.spec.js

@@ -0,0 +1,48 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import buildAssetUsagePipeline from '../lib/utils/buildAssetUsagePipeline.js'
+
+const GROUP = { $group: { _id: '$_assetIds', courses: { $addToSet: '$_courseId' } } }
+const PROJECT = { $project: { courseCount: { $size: '$courses' } } }
+
+describe('buildAssetUsagePipeline', () => {
+  for (const [name, input] of [
+    ['no argument', undefined],
+    ['null', null],
+    ['empty array', []]
+  ]) {
+    it(`counts all assets when given ${name} (no $match, single $unwind)`, () => {
+      const pipeline = buildAssetUsagePipeline(input)
+      assert.deepEqual(pipeline, [
+        { $unwind: '$_assetIds' },
+        GROUP,
+        PROJECT
+      ])
+      assert.equal(pipeline.filter(s => s.$match).length, 0)
+    })
+  }
+
+  it('scopes with a $match before and after $unwind when asset ids are given', () => {
+    const ids = ['id-a', 'id-b']
+    const pipeline = buildAssetUsagePipeline(ids)
+    const expectedMatch = { $match: { _assetIds: { $in: ids } } }
+    assert.deepEqual(pipeline, [
+      expectedMatch,
+      { $unwind: '$_assetIds' },
+      expectedMatch,
+      GROUP,
+      PROJECT
+    ])
+  })
+
+  it('places the pre-$unwind $match first so the _assetIds index can be used', () => {
+    const pipeline = buildAssetUsagePipeline(['id-a'])
+    assert.ok(pipeline[0].$match, 'first stage should be a $match')
+    assert.equal(pipeline[1].$unwind, '$_assetIds')
+  })
+
+  it('counts distinct courses (uses $addToSet on _courseId, not a document count)', () => {
+    const group = buildAssetUsagePipeline().find(s => s.$group)
+    assert.deepEqual(group.$group.courses, { $addToSet: '$_courseId' })
+  })
+})