adapt-authoring-content 3.4.0 → 3.5.1

package/adapt-authoring.json

@@ -1,5 +1,8 @@
 {
   "documentation": {
-    "enable": true
+    "enable": true,
+    "manualPages": {
+      "content-model.md": "concepts"
+    }
   }
 }

package/docs/content-model.md

@@ -0,0 +1,265 @@
+# Content model
+
+`adapt-authoring-content` stores every piece of authored course content as a flat
+collection of documents (`collectionName = 'content'`). It extends
+`AbstractApiModule`, so it inherits standard REST CRUD plus the access/hook
+machinery, and layers on the tree structure, friendly IDs, asset indexing and
+build-time validation described here.
+
+Source: `lib/ContentModule.js`, `lib/ContentTree.js`, `lib/utils/*`.
+
+## Hierarchy
+
+Content forms a tree whose nodes are distinguished by `_type`:
+
+```
+course
+├── config            (one per course, a childless sibling — not a tree child)
+├── menu              (optional; a menu can nest pages/menus)
+└── page
+    └── article
+        └── block
+            └── component   (leaf node)
+```
+
+The recursive scaffold order is hard-coded in `insertRecursive`
+(`ContentModule.js`):
+
+```js
+['course', 'page', 'article', 'block', 'component']
+```
+
+`menu` is inserted as a special case (when `req.body._type === 'menu'`); `config`
+replaces `course` in the chain when a new course is created.
+
+Every `_type` maps to a JSON schema via `contentTypeToSchemaName`
+(`lib/utils/contentTypeToSchemaName.js`): `page` and `menu` both resolve to
+`contentobject`; all other types map to a schema of the same name. A `component`
+is special — its schema is derived from its plugin's `targetAttribute`
+(see `getSchemaName`), e.g. `adapt-contrib-text` → `text-component`.
+
+## Linking fields
+
+Items are joined by ID references, not nesting:
+
+- `_parentId` — the immediate parent item. `config` has none; `course` has none.
+- `_courseId` — the owning course. Set on every descendant. A `course` document
+  gets its own `_id` written back as `_courseId` after insert (see `insert`),
+  so a single `{ _courseId }` query returns the whole course incl. the course doc.
+
+Indexes built in `init` reflect the common access paths:
+
+```js
+{ _courseId: 1, _parentId: 1, _type: 1 }
+{ _parentId: 1 }
+{ _type: 1, _courseId: 1 }
+{ _assetIds: 1 }
+{ _courseId: 1, _friendlyId: 1 }   // unique, partial (string & non-empty)
+```
+
+## ContentTree
+
+`lib/ContentTree.js` is a pure, DB-free structure over a flat array of items
+(one course's worth). It builds O(1) lookup maps on construction (`byId`,
+`byParent`, `byType`) and exposes `course`/`config` directly. It runs on both
+server and client.
+
+Key methods:
+
+| Method | Returns |
+| --- | --- |
+| `getById(id)` | item, O(1) |
+| `getChildren(parentId)` | direct children, O(1) |
+| `getByType(type)` | all items of a type, O(1) |
+| `getDescendants(rootId)` | all descendants (BFS), O(n) |
+| `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.
+
+## Tree endpoint
+
+`GET /api/content/tree/:_courseId` (`handleTree`, `routes.json`) returns a
+lightweight projection of every item in a course for rendering tree/list views
+without fetching full documents. Permission: `read:content`.
+
+Projected fields (`treeFields` in `handleTree`):
+
+```
+_id, _parentId, _courseId, _type, _sortOrder, title, displayTitle,
+_friendlyId, _component, _layout, _menu, _theme, _enabledPlugins,
+_colorLabel, _language, heroImage, updatedAt
+```
+
+Each returned item also carries a `_children` array of child `_id`s, computed
+from the in-memory tree.
+
+Caching is via a **weak ETag**, not `Last-Modified` (despite the `routes.json`
+OpenAPI `meta` still describing `If-Modified-Since`). `treeEtag`
+(`lib/utils/treeEtag.js`) folds the course `updatedAt` and a hash of the
+projected field list together, so the cache busts both when the course changes
+*and* when the response shape changes — a field added to the projection won't
+stay missing for unedited courses. If `If-None-Match` matches, the handler
+returns `304`.
+
+The course `updatedAt` is bumped on any descendant change via `touchCourse`,
+tapped into `postInsertHook`/`postUpdateHook`/`postDeleteHook` (`init`). The
+handler also enforces course-level access itself (owner / `_isShared` /
+`_shareWithUsers` / shared group), returning `404` rather than `403` so it
+doesn't leak existence; supers are exempt.
+
+## CRUD, scaffold, clone, reorder
+
+### insert
+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`)
+bootstraps a parent plus all required children in one call. With no `rootId` it
+creates a course (+ config + a default page/article/block/text-component);
+with a `rootId` it fills in the missing descendant types below that parent.
+Defaults (titles, the default `adapt-contrib-text` component body) are pulled
+from langpack strings via `req.translate('app.…')`. On any failure all
+just-created items are rolled back. Sort-order/plugin side effects run once for
+the topmost new item.
+
+### clone
+`POST /api/content/clone` (`handleClone` → `clone`) duplicates an item and all
+descendants in a single bulk `insertMany`. It pre-generates new `ObjectId`s
+(old→new map), remaps `_parentId`/`_courseId`, bulk-allocates friendly IDs per
+type, then fires `preInsertHook`/`postInsertHook` per payload and
+`preCloneHook`/`postCloneHook` per item. Cloning a `course` also clones its
+`config`. `clone` accepts `_parentId` for re-homing; an invalid parent throws
+`INVALID_PARENT`.
+
+Clone-specific hooks (created in `init`):
+
+- `preCloneHook` — mutable; invoked per source item before cloning.
+- `postCloneHook` — invoked per item with `(originalItem, newDoc)`.
+
+### delete
+`delete` cascades: it builds the course tree, collects `getDescendants`, bulk-
+deletes them via raw mongodb (avoiding per-item hook storms), deletes the target
+via `super.delete` (to trigger delete middleware), then invokes `postDeleteHook`
+once with the full descendants list. Deleting a `course` also removes its
+`config` and its friendly-ID counters (`deleteCounters`). Sort-order and the
+course plugin list are recalculated afterwards.
+
+### Reordering — `_sortOrder`
+Siblings under one parent are ordered by an integer `_sortOrder` starting at 1.
+`updateSortOrder` re-fetches siblings sorted by `_sortOrder` and delegates to
+`computeSortOrderOps` (`lib/utils/computeSortOrderOps.js`), which splices the
+moved/inserted item to its target index and emits the minimal set of
+`updateOne` ops to renumber. `course` and `config` (and any parentless item)
+are exempt. On `update`, sort recalculation only runs when `_sortOrder` or
+`_parentId` is in the update data.
+
+## `_friendlyId`
+
+A human-readable per-course identifier (`formatFriendlyId`,
+`lib/utils/formatFriendlyId.js`):
+
+- `course` → `course-<n>` (with `-<language>` suffix when `_language` is given)
+- `config` → `config`
+- everything else → `<first-letter-of-type>-<n>`, e.g. `p-3`, `b-12`, `c-40`
+
+IDs are unique per course (enforced by the partial unique index above).
+Sequence numbers come from an atomic counter collection
+(`contentcounters`, keyed `{ _type, _courseId }`). `generateFriendlyIds`
+reserves a range in one `$inc`, seeding the counter from existing content
+(`findMaxSeq` → `parseMaxSeq`, which extracts the numeric part of existing IDs)
+on first use.
+
+## `_assetIds`
+
+Each content document carries `_assetIds`: the unique IDs of assets it
+references. The field is added by extending the `content` schema with
+`contentassets` (`schema/contentassets.schema.json`; `editorOnly`, hidden in
+the UI), wired in `init` via `jsonschema.extendSchema('content', 'contentassets')`.
+
+`computeAssetIds` → `extractAssetIds` (`lib/utils/extractAssetIds.js`) walks the
+item's built schema for `_backboneForms` `Asset`-type fields and collects their
+non-URL values. `_assetIds` is computed on insert and **recomputed on every
+update** from the full merged document (stored as `ObjectId`s to match query
+coercion).
+
+Two consumers:
+
+- `assets.preDeleteHook` → `enforceAssetNotInUse`: refuses to delete an asset
+  still referenced by content, throwing `RESOURCE_IN_USE` with the affected
+  course titles.
+- `POST /api/content/assetusage` (`handleAssetUsage`): returns a map of asset
+  `_id` → distinct-course count, via `buildAssetUsagePipeline`
+  (`lib/utils/buildAssetUsagePipeline.js`). An optional `assetIds` body array
+  scopes the counts; assets with no usage are omitted. Counting distinct
+  `_courseId` (`$addToSet`) means many references within one course count once.
+
+## `_enabledPlugins`
+
+The course `config` document holds `_enabledPlugins` — the list of content
+plugins (components, the menu, the theme, extensions) in use. `updateEnabledPlugins`
+recomputes it from the tree's component names plus `config._menu`/`config._theme`,
+preserving existing extensions. When new plugins are added it re-validates the
+affected content types (`menu`/`page` for `contentobject`-targeted schemas) to
+apply their schema defaults. It runs on insert/clone and on updates that touch
+`_component`, `_menu`, `_theme` or `_enabledPlugins`.
+
+`getSchema` reads `config._enabledPlugins` for the course so it only merges the
+schemas of enabled plugins; built schemas are cached per
+`schemaName + enabledPlugins` key (`_schemaCache`), cleared on
+`jsonschema.registerSchemasHook`.
+
+## Build-time validation
+
+When `adaptframework` is available, the module taps its `preBuildHook` with
+`enforceNoEmptyContainers` (`init`). This builds a `ContentTree` for the course
+(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`.
+
+## Configuration
+
+`conf/config.schema.json` exposes only pagination options (inherited API
+behaviour); there are no content-domain config keys:
+
+```json
+{
+  "defaultPageSize": { "type": "number", "default": 500 },
+  "maxPageSize":     { "type": "number", "default": 500 }
+}
+```
+
+## Errors
+
+`errors/errors.json`: `INVALID_PARENT` (400), `DUPL_FRIENDLY_ID` (409),
+`RESOURCE_IN_USE` (400), `EMPTY_CONTAINERS` (400).

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() }))
     })
   }
 
@@ -150,6 +161,32 @@ class ContentModule extends AbstractApiModule {
     }
   }
 
+  /**
+   * Returns the courses that reference a given asset as `{ _id, title }` rows, for the asset sheet's "used in courses" list.
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {function} next
+   * @return {Promise}
+   */
+  async handleAssetCourses (req, res, next) {
+    try {
+      const usedBy = await this.find(
+        { _assetIds: req.apiData.query._id },
+        { validate: false },
+        { projection: { _courseId: 1 } }
+      )
+      const courseIds = [...new Set(usedBy.map(d => d._courseId?.toString()).filter(Boolean))].map(id => parseObjectId(id))
+      const courses = await this.find(
+        { _type: 'course', _id: { $in: courseIds } },
+        { validate: false },
+        { projection: { title: 1, displayTitle: 1 } }
+      )
+      res.json(courses.map(c => ({ _id: c._id.toString(), title: c.displayTitle || c.title })))
+    } catch (e) {
+      next(e)
+    }
+  }
+
   /**
    * "Unused assets" filter for the asset manager. The UI sends a `?unused`
    * query-string flag (see adapt-authoring-ui Assets page); restrict the assets
@@ -299,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
@@ -330,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.4.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/routes.json

@@ -133,6 +133,18 @@
           "responses": { "200": { "description": "Object mapping asset _id to the number of distinct courses referencing it; assets with no usage are omitted" } }
         }
       }
+    },
+    {
+      "route": "/assetusage/:_id",
+      "handlers": { "get": "handleAssetCourses" },
+      "permissions": { "get": ["read:${scope}"] },
+      "meta": {
+        "get": {
+          "summary": "List the courses that reference an asset",
+          "parameters": [{ "name": "_id", "in": "path", "description": "The asset _id", "required": true }],
+          "responses": { "200": { "description": "Array of { _id, title } for each course referencing the asset" } }
+        }
+      }
     }
   ]
 }

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)