adapt-authoring-content 3.5.0 → 3.5.1

package/docs/content-model.md

@@ -75,8 +75,13 @@ Key methods:
 | `getAncestors(itemId)` | parent chain upward, O(depth) |
 | `getSiblings(itemId)` | siblings excluding self |
 | `getEmptyContainers()` | childless non-`component`/non-`config` items |
+| `isReachable(itemId)` | whether the `_parentId` chain ends at the course root |
+| `getUnreachableItems()` | orphans — items whose chain never reaches the course |
 | `getComponentNames()` | unique `_component` values in the course |
 
+`getUnreachableItems` returns `[]` when the tree has no `course` node (reachability
+is undecidable without a root).
+
 The module builds a `ContentTree` internally for delete, clone, sort-order and
 plugin-list maintenance — anywhere it needs the whole course in memory.
 
@@ -114,11 +119,16 @@ doesn't leak existence; supers are exempt.
 ## CRUD, scaffold, clone, reorder
 
 ### insert
-On insert (`insert`): a `_friendlyId` is generated if absent, `_assetIds` is
-computed if absent, then `super.insert` runs. A new `course` gets its `_courseId`
+On insert (`insert`): `validateParent` runs first — a `_parentId` that doesn't
+resolve to an existing item in the same course throws `INVALID_PARENT` (400),
+which stops orphans being created by a delete/insert race or a stale client
+reference. Then a `_friendlyId` is generated if absent, `_assetIds` is
+computed if absent, and `super.insert` runs. A new `course` gets its `_courseId`
 written back. Otherwise `updateSortOrder` and `updateEnabledPlugins` run unless
 disabled via the `updateSortOrder: false` / `updateEnabledPlugins: false`
 options. A duplicate-key error is rethrown as `DUPL_FRIENDLY_ID` (409).
+`update` applies the same `validateParent` check when a write reparents an item
+(`_parentId` present in the update data).
 
 ### insertRecursive
 `POST /api/content/insertrecursive` (`handleInsertRecursive` → `insertRecursive`)
@@ -220,9 +230,20 @@ schemas of enabled plugins; built schemas are cached per
 
 When `adaptframework` is available, the module taps its `preBuildHook` with
 `enforceNoEmptyContainers` (`init`). This builds a `ContentTree` for the course
-and calls `getEmptyContainers()`; if any non-`component`, non-`config` item has
-no children (an empty page/article/block, or empty menu/course) it throws
-`EMPTY_CONTAINERS` (400) listing the offending items, blocking the build.
+(via the same flat `_courseId` query the build itself uses) and:
+
+1. **Prunes orphans.** `getUnreachableItems()` returns items whose `_parentId`
+   chain never reaches the course root — left behind by an interrupted delete,
+   invisible in the editor (which only renders the reachable tree) yet still
+   carried into the build, where they break it. These are deleted and the count
+   is recorded on `build.prunedOrphans` so the caller can surface it; a `warn`
+   is logged with the pruned `_id`s.
+2. **Blocks on genuine gaps.** Among the remaining reachable items, any
+   non-`component`, non-`config` container with no children (an empty
+   page/article/block, or empty menu/course) throws `EMPTY_CONTAINERS` (400).
+   The error data lists each offending item's `_id`, `_type`, `title` and
+   `_parentId`.
+
 `content` depends on `adaptframework`'s hook (not vice-versa), so the tap is
 deferred via `waitForModule(...).then(...)` rather than awaited in `init`.
 

package/errors/errors.json

@@ -24,7 +24,7 @@
   },
   "EMPTY_CONTAINERS": {
     "data": {
-      "items": "The childless content items blocking the build"
+      "items": "The childless content items blocking the build (each with _id, _type, title and _parentId)"
     },
     "description": "Course cannot be built: one or more pages, articles or blocks have no content",
     "statusCode": 400

package/lib/ContentModule.js

@@ -112,8 +112,11 @@ class ContentModule extends AbstractApiModule {
   }
 
   /**
-   * 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.
+   * preBuildHook observer: prunes orphaned items (unreachable from the course root, left by an
+   * interrupted delete — invisible in the editor but build-breaking), then refuses the build when
+   * any reachable non-component container has no children (an empty page, article or block).
+   * Components are leaf nodes and config is exempt. Records the pruned count on `build` so the
+   * caller can surface it.
    * @param {AdaptFrameworkBuild} build The build being run
    * @return {Promise}
    */
@@ -124,10 +127,18 @@ class ContentModule extends AbstractApiModule {
       { validate: false },
       { projection: { _type: 1, _parentId: 1, title: 1, displayTitle: 1 } }
     )
-    const empty = new ContentTree(items).getEmptyContainers()
+    const tree = new ContentTree(items)
+    const orphans = tree.getUnreachableItems()
+    if (orphans.length) {
+      await this.mongodb.deleteMany(this.collectionName, { _id: { $in: orphans.map(o => o._id) } })
+      this.log('warn', `pruned ${orphans.length} orphaned content item(s) from course ${_courseId}: ${orphans.map(o => o._id).join(', ')}`)
+      build.prunedOrphans = (build.prunedOrphans ?? 0) + orphans.length
+    }
+    const orphanIds = new Set(orphans.map(o => o._id.toString()))
+    const empty = tree.getEmptyContainers().filter(i => !orphanIds.has(i._id.toString()))
     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 }))
+      items: empty.map(i => ({ _id: i._id.toString(), _type: i._type, title: i.displayTitle || i.title, _parentId: i._parentId?.toString() }))
     })
   }
 
@@ -325,8 +336,29 @@ class ContentModule extends AbstractApiModule {
     return extractAssetIds(schema, doc)
   }
 
+  /**
+   * Throws INVALID_PARENT when a write sets a _parentId that does not resolve to an existing item
+   * in the same course. Prevents orphans (items unreachable from the course root) being created by
+   * a delete/insert race or a stale client reference. No-op when no _parentId is set (course/config
+   * roots, or an update that does not reparent).
+   * @param {Object} data The content data being written
+   * @return {Promise}
+   */
+  async validateParent (data) {
+    if (!data._parentId) return
+    const parent = await this.findOne(
+      { _id: data._parentId },
+      { validate: false, throwOnMissing: false },
+      { projection: { _id: 1, _courseId: 1 } }
+    )
+    if (!parent || (data._courseId && parent._courseId && parent._courseId.toString() !== data._courseId.toString())) {
+      throw this.app.errors.INVALID_PARENT.setData({ parentId: data._parentId.toString() })
+    }
+  }
+
   /** @override */
   async insert (data, options = {}, mongoOptions = {}) {
+    await this.validateParent(data)
     if (!data._friendlyId) {
       const [id] = await this.generateFriendlyIds(data._type, data._courseId, 1, data._language)
       data._friendlyId = id
@@ -356,6 +388,7 @@ class ContentModule extends AbstractApiModule {
 
   /** @override */
   async update (query, data, options, mongoOptions) {
+    if ('_parentId' in data && data._parentId) await this.validateParent(data)
     let doc
     try {
       doc = await super.update(query, data, options, mongoOptions)

package/lib/ContentTree.js

@@ -128,6 +128,43 @@ class ContentTree {
     )
   }
 
+  /**
+   * Whether an item's _parentId chain terminates at the course root. Returns false
+   * when a link in the chain points at an item missing from the tree (e.g. a block
+   * whose parent article was deleted) or forms a cycle.
+   * @param {string|Object} itemId
+   * @returns {boolean}
+   */
+  isReachable (itemId) {
+    let current = this.byId.get(itemId.toString())
+    if (!current) return false
+    const seen = new Set()
+    while (current?._parentId) {
+      const id = current._id.toString()
+      if (seen.has(id)) return false
+      seen.add(id)
+      current = this.byId.get(current._parentId.toString())
+      if (!current) return false
+    }
+    return current === this.course
+  }
+
+  /**
+   * Items whose _parentId chain does not reach the course root (orphans), excluding
+   * the course and config (childless roots). Orphans are invisible in the editor yet
+   * still returned by flat _courseId queries, so they break a build. Returns [] when
+   * the tree has no course node, since reachability cannot be determined.
+   * @returns {Array<Object>} Orphaned items
+   */
+  getUnreachableItems () {
+    if (!this.course) return []
+    return this.items.filter(i =>
+      i._type !== 'course' &&
+      i._type !== 'config' &&
+      !this.isReachable(i._id)
+    )
+  }
+
   /**
    * O(1) — unique component names across the course
    * @returns {Array<string>}

package/package.json

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

package/tests/ContentModule.spec.js

@@ -790,6 +790,127 @@ describe('ContentModule', () => {
     })
   })
 
+  describe('validateParent', () => {
+    const PARENT = '507f1f77bcf86cd799439011'
+    const COURSE = '507f1f77bcf86cd799439022'
+    const INVALID = Symbol('INVALID_PARENT')
+
+    function createInst (parentDoc) {
+      return {
+        findOne: mock.fn(async () => parentDoc),
+        app: { errors: { INVALID_PARENT: { setData: mock.fn(data => Object.assign(new Error('INVALID_PARENT'), { symbol: INVALID, data })) } } }
+      }
+    }
+    const run = (inst, data) => ContentModule.prototype.validateParent.call(inst, data)
+
+    it('is a no-op when no _parentId is set', async () => {
+      const inst = createInst(null)
+      await run(inst, { _type: 'course' })
+      assert.equal(inst.findOne.mock.callCount(), 0)
+    })
+
+    it('passes when the parent exists in the same course', async () => {
+      const inst = createInst({ _id: PARENT, _courseId: COURSE })
+      await run(inst, { _parentId: PARENT, _courseId: COURSE })
+      assert.equal(inst.app.errors.INVALID_PARENT.setData.mock.callCount(), 0)
+    })
+
+    it('throws INVALID_PARENT when the parent does not exist', async () => {
+      const inst = createInst(null)
+      await assert.rejects(() => run(inst, { _parentId: 'gone', _courseId: COURSE }),
+        e => e.symbol === INVALID && e.data.parentId === 'gone')
+    })
+
+    it('throws INVALID_PARENT when the parent belongs to another course', async () => {
+      const inst = createInst({ _id: PARENT, _courseId: 'othercourse' })
+      await assert.rejects(() => run(inst, { _parentId: PARENT, _courseId: COURSE }),
+        e => e.symbol === INVALID)
+    })
+
+    it('passes existence-only when data carries no _courseId to cross-check', async () => {
+      const inst = createInst({ _id: PARENT, _courseId: COURSE })
+      await run(inst, { _parentId: PARENT })
+      assert.equal(inst.app.errors.INVALID_PARENT.setData.mock.callCount(), 0)
+    })
+  })
+
+  describe('enforceNoEmptyContainers', () => {
+    const COURSE = '507f1f77bcf86cd799439011'
+    const EMPTY = Symbol('EMPTY_CONTAINERS')
+
+    function createInst (items) {
+      const deleteMany = mock.fn(async () => {})
+      const inst = {
+        collectionName: 'content',
+        find: mock.fn(async () => items),
+        mongodb: { deleteMany },
+        log: mock.fn(),
+        app: { errors: { EMPTY_CONTAINERS: { setData: mock.fn(data => Object.assign(new Error('EMPTY'), { symbol: EMPTY, data })) } } }
+      }
+      return { inst, deleteMany }
+    }
+
+    const run = (inst, build = { courseId: COURSE }) =>
+      ContentModule.prototype.enforceNoEmptyContainers.call(inst, build)
+
+    it('passes silently for a fully connected, populated course', async () => {
+      const { inst, deleteMany } = createInst([
+        { _id: 'c', _type: 'course' },
+        { _id: 'p', _type: 'page', _parentId: 'c' },
+        { _id: 'a', _type: 'article', _parentId: 'p' },
+        { _id: 'b', _type: 'block', _parentId: 'a' },
+        { _id: 'cmp', _type: 'component', _parentId: 'b', _component: 'adapt-contrib-text' }
+      ])
+      await run(inst)
+      assert.equal(deleteMany.mock.callCount(), 0)
+      assert.equal(inst.app.errors.EMPTY_CONTAINERS.setData.mock.callCount(), 0)
+    })
+
+    it('prunes orphans and does not block when no reachable container is empty', async () => {
+      const { inst, deleteMany } = createInst([
+        { _id: 'c', _type: 'course' },
+        { _id: 'p', _type: 'page', _parentId: 'c' },
+        { _id: 'a', _type: 'article', _parentId: 'p' },
+        { _id: 'b', _type: 'block', _parentId: 'a' },
+        { _id: 'cmp', _type: 'component', _parentId: 'b', _component: 'adapt-contrib-text' },
+        { _id: 'orphan', _type: 'block', _parentId: 'gone', title: 'Block title' }
+      ])
+      const build = { courseId: COURSE }
+      await run(inst, build)
+      assert.equal(deleteMany.mock.callCount(), 1)
+      assert.deepEqual(deleteMany.mock.calls[0].arguments, ['content', { _id: { $in: ['orphan'] } }])
+      assert.equal(build.prunedOrphans, 1)
+      assert.equal(inst.app.errors.EMPTY_CONTAINERS.setData.mock.callCount(), 0)
+    })
+
+    it('blocks on a reachable empty container, surfacing _parentId', async () => {
+      const { inst, deleteMany } = createInst([
+        { _id: 'c', _type: 'course' },
+        { _id: 'p', _type: 'page', _parentId: 'c' },
+        { _id: 'a', _type: 'article', _parentId: 'p', title: 'Empty article' }
+      ])
+      await assert.rejects(() => run(inst), e =>
+        e.symbol === EMPTY &&
+        e.data.items.length === 1 &&
+        e.data.items[0]._id === 'a' &&
+        e.data.items[0]._parentId === 'p')
+      assert.equal(deleteMany.mock.callCount(), 0)
+    })
+
+    it('prunes orphans and still blocks on a separate reachable empty', async () => {
+      const { inst, deleteMany } = createInst([
+        { _id: 'c', _type: 'course' },
+        { _id: 'p', _type: 'page', _parentId: 'c' },
+        { _id: 'a', _type: 'article', _parentId: 'p', title: 'Empty article' },
+        { _id: 'orphan', _type: 'block', _parentId: 'gone' }
+      ])
+      await assert.rejects(() => run(inst), e =>
+        e.data.items.length === 1 && e.data.items[0]._id === 'a')
+      assert.equal(deleteMany.mock.callCount(), 1)
+      assert.deepEqual(deleteMany.mock.calls[0].arguments[1], { _id: { $in: ['orphan'] } })
+    })
+  })
+
   describe('delete', () => {
     const COURSE_OID = '507f1f77bcf86cd799439011'
     const TARGET_OID = '507f1f77bcf86cd799439012'

package/tests/ContentTree.spec.js

@@ -201,6 +201,85 @@ describe('ContentTree', () => {
     })
   })
 
+  describe('isReachable', () => {
+    it('should return true for items whose chain reaches the course', () => {
+      const tree = new ContentTree(items)
+      assert.equal(tree.isReachable('id9'), true)
+      assert.equal(tree.isReachable('id5'), true)
+      assert.equal(tree.isReachable('id1'), true)
+    })
+
+    it('should return false when a parent is missing from the tree', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'course' },
+        { _id: makeId(2), _type: 'block', _parentId: makeId(99) }
+      ])
+      assert.equal(tree.isReachable('id2'), false)
+    })
+
+    it('should return false for non-existent ids', () => {
+      const tree = new ContentTree(items)
+      assert.equal(tree.isReachable('missing'), false)
+    })
+
+    it('should return false when there is no course root', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'page', _parentId: makeId(2) },
+        { _id: makeId(2), _type: 'menu' }
+      ])
+      assert.equal(tree.isReachable('id1'), false)
+    })
+
+    it('should not loop forever on a cycle', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'course' },
+        { _id: makeId(2), _type: 'page', _parentId: makeId(3) },
+        { _id: makeId(3), _type: 'article', _parentId: makeId(2) }
+      ])
+      assert.equal(tree.isReachable('id2'), false)
+    })
+  })
+
+  describe('getUnreachableItems', () => {
+    it('should return [] for a fully connected course', () => {
+      assert.deepEqual(new ContentTree(items).getUnreachableItems(), [])
+    })
+
+    it('should return an orphaned block whose parent article was deleted', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'course' },
+        { _id: makeId(2), _type: 'page', _parentId: makeId(1) },
+        { _id: makeId(3), _type: 'block', _parentId: makeId(99) }
+      ])
+      const orphans = tree.getUnreachableItems()
+      assert.deepEqual(orphans.map(i => i._id.toString()), ['id3'])
+    })
+
+    it('should return the whole orphaned subtree, not just childless items', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'course' },
+        { _id: makeId(2), _type: 'article', _parentId: makeId(99) },
+        { _id: makeId(3), _type: 'block', _parentId: makeId(2) }
+      ])
+      assert.deepEqual(tree.getUnreachableItems().map(i => i._id.toString()).sort(), ['id2', 'id3'])
+    })
+
+    it('should never flag course or config', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'course' },
+        { _id: makeId(2), _type: 'config', _courseId: 'c1' }
+      ])
+      assert.deepEqual(tree.getUnreachableItems(), [])
+    })
+
+    it('should return [] when the tree has no course node', () => {
+      const tree = new ContentTree([
+        { _id: makeId(1), _type: 'block', _parentId: makeId(99) }
+      ])
+      assert.deepEqual(tree.getUnreachableItems(), [])
+    })
+  })
+
   describe('getComponentNames', () => {
     it('should return unique component names', () => {
       const tree = new ContentTree(items)