adapt-authoring-content 3.0.5 → 3.1.0

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
@@ -104,6 +104,25 @@ class ContentModule extends AbstractApiModule {
     throw this.app.errors.RESOURCE_IN_USE.setData({ type: 'asset', courses })
   }
 
+  /**
+   * 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
@@ -460,19 +479,6 @@ class ContentModule extends AbstractApiModule {
       friendlyIds.set(_type, { ids: await this.generateFriendlyIds(_type, newCourseId, count), next: 0 })
     }))
 
-    // Pre-allocate sequential _trackingId for cloned blocks. Bulk insertMany
-    // defeats SpoorTrackingModule's preInsertHook (which reads the current max
-    // from the DB per-block), so without this every cloned block would get the
-    // same id.
-    const blockCount = typeCounts.get('block') ?? 0
-    let nextTrackingId
-    if (blockCount > 0) {
-      const [{ _trackingId: maxTrackingId = 0 } = {}] = await this.find(
-        { _courseId: newCourseId }, {}, { limit: 1, sort: [['_trackingId', -1]] }
-      )
-      nextTrackingId = maxTrackingId + 1
-    }
-
     // Build all insert payloads with pre-mapped IDs and parent references
     const rootId = _id.toString()
     const payloads = allItems.map(item => {
@@ -497,7 +503,6 @@ class ContentModule extends AbstractApiModule {
       return stringifyValues({
         ...item,
         _id: newId,
-        _trackingId: item._type === 'block' ? nextTrackingId++ : undefined,
         _friendlyId: friendlyId,
         _courseId: isCourse ? newId.toString() : newCourseId,
         _parentId: newParentId,

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.5",
+  "version": "3.1.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/ContentModule.spec.js

@@ -517,15 +517,14 @@ describe('ContentModule', () => {
       assert.ok(inst.postInsertHook.invoke.mock.callCount() > 0)
     })
 
-    it('should assign distinct sequential _trackingId values to cloned blocks', async () => {
-      // Regression: bulk insertMany defeats SpoorTrackingModule's preInsertHook
-      // which assumes each new block is persisted before the next hook runs.
-      // The clone path must pre-allocate _trackingId so cloned blocks don't collide.
+    it('should delegate _trackingId assignment to preInsertHook (clone no longer allocates them)', async () => {
+      // Tracking IDs are owned by the spoortracking module, which taps preInsertHook. clone must
+      // fire that hook once per payload (so each cloned block can be assigned an id) and must not
+      // assign _trackingId itself. With no observer attached here, payloads pass through untouched.
       const BLOCK2_OID = '507f1f77bcf86cd79943a001'
       const BLOCK3_OID = '507f1f77bcf86cd79943a002'
 
       const { inst, mongodb } = createCloneInstance()
-      inst.find = mock.fn(async () => [{ _trackingId: 7 }]) // existing max in course
 
       const items = [
         { _id: COURSE_OID, _type: 'course', _courseId: COURSE_OID },
@@ -539,18 +538,16 @@ describe('ContentModule', () => {
       const parent = { _id: COURSE_OID, _type: 'course', _courseId: COURSE_OID }
       await ContentModule.prototype.clone.call(inst, USER_OID, PAGE_OID, COURSE_OID, {}, { tree, parent })
 
+      // preInsertHook fired once per cloned payload — the seam the spoortracking observer uses.
+      // Cloning the page clones page + article + 3 blocks (5 items); the course is the source.
+      assert.equal(inst.preInsertHook.invoke.mock.callCount(), 5)
+      // every payload passed to the hook is a block/page/etc, and a block payload is present
+      const hookedTypes = inst.preInsertHook.invoke.mock.calls.map(c => c.arguments[0]._type)
+      assert.ok(hookedTypes.includes('block'))
+      // clone itself assigned nothing — block payloads still carry the (now irrelevant) source ids
       const inserted = mongodb.collection.insertMany.mock.calls[0].arguments[0]
       const blockTrackingIds = inserted.filter(d => d._type === 'block').map(d => d._trackingId)
-      assert.equal(blockTrackingIds.length, 3)
-      for (const id of blockTrackingIds) {
-        assert.equal(typeof id, 'number', `block cloned without numeric _trackingId (got ${id})`)
-      }
-      // all distinct
-      assert.equal(new Set(blockTrackingIds).size, blockTrackingIds.length, 'duplicate _trackingId among cloned blocks')
-      // and continuing past the existing max
-      for (const id of blockTrackingIds) {
-        assert.ok(id > 7, `expected _trackingId > existing max (7), got ${id}`)
-      }
+      assert.deepEqual(blockTrackingIds.sort(), [5, 6, 7])
     })
   })
 

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' })
+  })
+})