adapt-authoring-adaptframework 3.1.1 → 3.1.2

package/lib/AdaptFrameworkBuild.js

@@ -3,7 +3,7 @@ import { App, Hook, ensureDir, writeJson } from 'adapt-authoring-core'
 import { parseObjectId } from 'adapt-authoring-mongodb'
 import { createWriteStream } from 'node:fs'
 import AdaptCli from 'adapt-cli'
-import { log, logDir, logMemory, copyFrameworkSource, generateLanguageManifest, applyBuildReplacements } from './utils.js'
+import { log, logDir, logMemory, copyFrameworkSource, generateLanguageManifest, applyBuildReplacements, computeVarsHash } from './utils.js'
 import BuildCache from './BuildCache.js'
 import fs from 'node:fs/promises'
 import path from 'upath'
@@ -200,6 +200,9 @@ class AdaptFrameworkBuild {
 
     await this.loadCourseData()
 
+    // must hash before preBuildHook/applySchemaDefaults mutate course.data
+    const varsHash = this.isPreview ? computeVarsHash(this.courseData.course.data) : null
+
     // Check for cached preview build
     if (this.isPreview && !contentOnly) {
       const cache = new BuildCache(path.join(framework.getConfig('buildDir'), 'prebuilt-cache'))
@@ -207,8 +210,8 @@ class AdaptFrameworkBuild {
       const theme = this.courseData.config.data._theme
       const menu = this.courseData.config.data._menu
 
-      if (await cache.has(pluginHash, theme, menu)) {
-        await cache.restore(pluginHash, theme, menu, this.buildDir)
+      if (await cache.has(pluginHash, theme, menu, varsHash)) {
+        await cache.restore(pluginHash, theme, menu, varsHash, this.buildDir)
         await this.applySchemaDefaults()
         await this.copyAssets()
         await this.preBuildHook.invoke(this)
@@ -278,7 +281,7 @@ class AdaptFrameworkBuild {
       const theme = this.courseData.config.data._theme
       const menu = this.courseData.config.data._menu
       try {
-        await cache.populate(this.buildDir, pluginHash, theme, menu)
+        await cache.populate(this.buildDir, pluginHash, theme, menu, varsHash)
       } catch (e) {
         log('warn', 'CACHE', `failed to populate prebuilt cache: ${e.message}`)
       }

package/lib/BuildCache.js

@@ -6,7 +6,7 @@ import { log } from './utils/log.js'
 const SKIP_ENTRIES = new Set(['course'])
 
 /**
- * Filesystem-level cache of grunt build output, keyed by (pluginHash, theme, menu).
+ * Filesystem-level cache of grunt build output, keyed by (pluginHash, theme, menu, varsHash).
  * One instance per cache root; methods are stateless beyond the root path.
  */
 class BuildCache {
@@ -20,16 +20,16 @@ class BuildCache {
   /**
    * @returns {String} The cache directory path for the given combo
    */
-  getPath (pluginHash, theme, menu) {
-    return path.join(this.cacheRoot, `${pluginHash}_${theme}_${menu}`)
+  getPath (pluginHash, theme, menu, varsHash) {
+    return path.join(this.cacheRoot, `${pluginHash}_${theme}_${menu}_${varsHash}`)
   }
 
   /**
    * @returns {Promise<Boolean>} Whether a cached build exists for the given combo
    */
-  async has (pluginHash, theme, menu) {
+  async has (pluginHash, theme, menu, varsHash) {
     try {
-      await fs.access(this.getPath(pluginHash, theme, menu))
+      await fs.access(this.getPath(pluginHash, theme, menu, varsHash))
       return true
     } catch {
       return false
@@ -41,8 +41,8 @@ class BuildCache {
    * Uses a temp dir + atomic rename for parallel safety.
    * @param {String} buildOutputDir The build output directory
    */
-  async populate (buildOutputDir, pluginHash, theme, menu) {
-    const cacheDir = this.getPath(pluginHash, theme, menu)
+  async populate (buildOutputDir, pluginHash, theme, menu, varsHash) {
+    const cacheDir = this.getPath(pluginHash, theme, menu, varsHash)
     await fs.mkdir(this.cacheRoot, { recursive: true })
 
     const tmpDir = `${cacheDir}_tmp_${Date.now()}`
@@ -54,7 +54,7 @@ class BuildCache {
         await copyEntry(path.join(buildOutputDir, entry), path.join(tmpDir, entry))
       }
       await safeRename(tmpDir, cacheDir)
-      log('info', 'CACHE', `populated cache for ${pluginHash} (theme=${theme}, menu=${menu})`)
+      log('info', 'CACHE', `populated cache for ${pluginHash} (theme=${theme}, menu=${menu}, vars=${varsHash})`)
     } catch (e) {
       await fs.rm(tmpDir, { recursive: true, force: true })
       throw e
@@ -65,10 +65,10 @@ class BuildCache {
    * Copies cached artifacts to a build directory.
    * @param {String} destDir Destination build directory
    */
-  async restore (pluginHash, theme, menu, destDir) {
+  async restore (pluginHash, theme, menu, varsHash, destDir) {
     await fs.mkdir(destDir, { recursive: true })
-    await fs.cp(this.getPath(pluginHash, theme, menu), destDir, { recursive: true })
-    log('info', 'CACHE', `restored from cache for ${pluginHash} (theme=${theme}, menu=${menu})`)
+    await fs.cp(this.getPath(pluginHash, theme, menu, varsHash), destDir, { recursive: true })
+    log('info', 'CACHE', `restored from cache for ${pluginHash} (theme=${theme}, menu=${menu}, vars=${varsHash})`)
   }
 
   /**

package/lib/utils/computeVarsHash.js

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * Serialises a value to JSON with object keys sorted (arrays preserve order, undefined → null)
+ * @param {*} value
+ * @return {String}
+ */
+export function canonicalJson (value) {
+  if (value === undefined || value === null) return 'null'
+  if (typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return '[' + value.map(canonicalJson).join(',') + ']'
+  const keys = Object.keys(value).sort()
+  return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalJson(value[k])).join(',') + '}'
+}
+
+/**
+ * Hashes per-course LESS inputs (themeVariables + customStyle) for the cache key
+ * @param {Object} [data]
+ * @param {Object} [data.themeVariables]
+ * @param {String} [data.customStyle]
+ * @return {String} 12-char hex hash
+ */
+export function computeVarsHash ({ themeVariables, customStyle } = {}) {
+  const input = canonicalJson({
+    themeVariables: themeVariables ?? null,
+    customStyle: customStyle ?? null
+  })
+  return createHash('sha256').update(input).digest('hex').slice(0, 12)
+}

package/lib/utils/prebuildCache.js

@@ -5,8 +5,11 @@ import path from 'upath'
 import { copyFrameworkSource } from './copyFrameworkSource.js'
 import BuildCache from '../BuildCache.js'
 import { computePluginHash } from './computePluginHash.js'
+import { computeVarsHash } from './computeVarsHash.js'
 import { log } from './log.js'
 
+const DEFAULT_VARS_HASH = computeVarsHash()
+
 /**
  * Eagerly populates the prebuilt cache for every (theme, menu) combination
  * of installed plugins. Iterates serially: each iteration runs a full grunt
@@ -54,7 +57,7 @@ export async function prebuildCache ({ buildDir, frameworkDir }) {
 async function prebuildOne ({ buildDir, cache, pluginHash, theme, menu, allPlugins }) {
   const app = App.instance
 
-  if (await cache.has(pluginHash, theme.name, menu.name)) {
+  if (await cache.has(pluginHash, theme.name, menu.name, DEFAULT_VARS_HASH)) {
     log('info', 'CACHE', `skipping cached combo theme=${theme.name} menu=${menu.name}`)
     return
   }
@@ -101,8 +104,8 @@ async function prebuildOne ({ buildDir, cache, pluginHash, theme, menu, allPlugi
       logger: { log: (...args) => app.logger.log('debug', 'adapt-cli', ...args) }
     })
 
-    if (!await cache.has(pluginHash, theme.name, menu.name)) {
-      await cache.populate(outputDir, pluginHash, theme.name, menu.name)
+    if (!await cache.has(pluginHash, theme.name, menu.name, DEFAULT_VARS_HASH)) {
+      await cache.populate(outputDir, pluginHash, theme.name, menu.name, DEFAULT_VARS_HASH)
     }
   } finally {
     await fs.rm(tmpDir, { recursive: true, force: true })

package/lib/utils.js

@@ -16,3 +16,4 @@ export { computePluginHash } from './utils/computePluginHash.js'
 export { prebuildCache } from './utils/prebuildCache.js'
 export { generateLanguageManifest } from './utils/generateLanguageManifest.js'
 export { applyBuildReplacements } from './utils/applyBuildReplacements.js'
+export { computeVarsHash } from './utils/computeVarsHash.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-adaptframework",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "description": "Adapt framework integration for the Adapt authoring tool",
   "homepage": "https://github.com/adapt-security/adapt-authoring-adaptframework",
   "license": "GPL-3.0",

package/tests/BuildCache.spec.js

@@ -34,18 +34,29 @@ describe('BuildCache', () => {
 
   describe('getPath()', () => {
     it('returns one combo-keyed directory path', () => {
-      assert.equal(cache.getPath('abc123', 'vanilla', 'boxMenu'), upath.join(cacheRoot, 'abc123_vanilla_boxMenu'))
+      assert.equal(cache.getPath('abc123', 'vanilla', 'boxMenu', 'vhash'), upath.join(cacheRoot, 'abc123_vanilla_boxMenu_vhash'))
+    })
+
+    it('returns distinct paths for different varsHash', () => {
+      const a = cache.getPath('abc123', 'vanilla', 'boxMenu', 'aaa')
+      const b = cache.getPath('abc123', 'vanilla', 'boxMenu', 'bbb')
+      assert.notEqual(a, b)
     })
   })
 
   describe('has()', () => {
     it('returns false when cache does not exist', async () => {
-      assert.equal(await cache.has('hash1', 'theme', 'menu'), false)
+      assert.equal(await cache.has('hash1', 'theme', 'menu', 'vhash'), false)
     })
 
     it('returns true when the combo dir exists', async () => {
-      await fs.mkdir(cache.getPath('hash1', 'theme', 'menu'), { recursive: true })
-      assert.equal(await cache.has('hash1', 'theme', 'menu'), true)
+      await fs.mkdir(cache.getPath('hash1', 'theme', 'menu', 'vhash'), { recursive: true })
+      assert.equal(await cache.has('hash1', 'theme', 'menu', 'vhash'), true)
+    })
+
+    it('returns false when only a different varsHash exists', async () => {
+      await fs.mkdir(cache.getPath('hash1', 'theme', 'menu', 'vhashA'), { recursive: true })
+      assert.equal(await cache.has('hash1', 'theme', 'menu', 'vhashB'), false)
     })
   })
 
@@ -65,9 +76,9 @@ describe('BuildCache', () => {
       await fs.mkdir(path.join(buildDir, 'course', 'en'), { recursive: true })
       await fs.writeFile(path.join(buildDir, 'course', 'en', 'course.json'), '{}')
 
-      await cache.populate(buildDir, 'hash1', 'theme', 'menu')
+      await cache.populate(buildDir, 'hash1', 'theme', 'menu', 'vhash')
 
-      const cacheDir = cache.getPath('hash1', 'theme', 'menu')
+      const cacheDir = cache.getPath('hash1', 'theme', 'menu', 'vhash')
       assert.equal(await fs.readFile(path.join(cacheDir, 'adapt', 'js', 'adapt.min.js'), 'utf8'), 'js-content')
       assert.equal(await fs.readFile(path.join(cacheDir, 'index.html'), 'utf8'), '<html></html>')
       assert.equal(await fs.readFile(path.join(cacheDir, 'adapt.css'), 'utf8'), 'css-content')
@@ -78,13 +89,13 @@ describe('BuildCache', () => {
 
   describe('restore()', () => {
     it('copies cached artifacts to destination', async () => {
-      const cacheDir = cache.getPath('hash1', 'theme', 'menu')
+      const cacheDir = cache.getPath('hash1', 'theme', 'menu', 'vhash')
       await fs.mkdir(path.join(cacheDir, 'adapt', 'js'), { recursive: true })
       await fs.writeFile(path.join(cacheDir, 'adapt', 'js', 'adapt.min.js'), 'cached-js')
       await fs.writeFile(path.join(cacheDir, 'adapt.css'), 'cached-css')
 
       const destDir = path.join(tmpDir, 'restored')
-      await cache.restore('hash1', 'theme', 'menu', destDir)
+      await cache.restore('hash1', 'theme', 'menu', 'vhash', destDir)
 
       assert.equal(await fs.readFile(path.join(destDir, 'adapt', 'js', 'adapt.min.js'), 'utf8'), 'cached-js')
       assert.equal(await fs.readFile(path.join(destDir, 'adapt.css'), 'utf8'), 'cached-css')

package/tests/utils-computeVarsHash.spec.js

@@ -0,0 +1,70 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { canonicalJson, computeVarsHash } from '../lib/utils/computeVarsHash.js'
+
+describe('canonicalJson()', () => {
+  const cases = [
+    { name: 'primitive string', input: 'abc', expected: '"abc"' },
+    { name: 'primitive number', input: 42, expected: '42' },
+    { name: 'primitive boolean', input: true, expected: 'true' },
+    { name: 'null', input: null, expected: 'null' },
+    { name: 'undefined coerces to null', input: undefined, expected: 'null' },
+    { name: 'empty object', input: {}, expected: '{}' },
+    { name: 'empty array', input: [], expected: '[]' },
+    { name: 'array preserves order', input: [3, 1, 2], expected: '[3,1,2]' },
+    { name: 'sorts top-level keys', input: { b: 1, a: 2 }, expected: '{"a":2,"b":1}' },
+    { name: 'sorts nested keys', input: { x: { d: 1, c: 2 } }, expected: '{"x":{"c":2,"d":1}}' },
+    { name: 'mixed nesting', input: { a: [{ z: 1, y: 2 }] }, expected: '{"a":[{"y":2,"z":1}]}' }
+  ]
+  for (const { name, input, expected } of cases) {
+    it(name, () => assert.equal(canonicalJson(input), expected))
+  }
+
+  it('produces identical output for objects with different key insertion order', () => {
+    const a = { _colors: { primary: 'red', secondary: 'blue' }, _font: { family: 'serif' } }
+    const b = { _font: { family: 'serif' }, _colors: { secondary: 'blue', primary: 'red' } }
+    assert.equal(canonicalJson(a), canonicalJson(b))
+  })
+})
+
+describe('computeVarsHash()', () => {
+  it('returns a 12-character hex string', () => {
+    assert.match(computeVarsHash({ themeVariables: { a: 1 } }), /^[0-9a-f]{12}$/)
+  })
+
+  it('is deterministic for identical inputs', () => {
+    const data = { themeVariables: { _colors: { primary: 'green' } }, customStyle: '.foo { color: red; }' }
+    assert.equal(computeVarsHash(data), computeVarsHash(data))
+  })
+
+  it('treats missing, undefined, null, and empty equivalently', () => {
+    const empty = computeVarsHash()
+    assert.equal(computeVarsHash({}), empty)
+    assert.equal(computeVarsHash({ themeVariables: null, customStyle: null }), empty)
+    assert.equal(computeVarsHash({ themeVariables: undefined, customStyle: undefined }), empty)
+  })
+
+  it('is insensitive to key order within themeVariables', () => {
+    const a = computeVarsHash({ themeVariables: { _colors: { primary: 'red', secondary: 'blue' } } })
+    const b = computeVarsHash({ themeVariables: { _colors: { secondary: 'blue', primary: 'red' } } })
+    assert.equal(a, b)
+  })
+
+  it('differs when themeVariables differ', () => {
+    const a = computeVarsHash({ themeVariables: { _colors: { primary: 'red' } } })
+    const b = computeVarsHash({ themeVariables: { _colors: { primary: 'green' } } })
+    assert.notEqual(a, b)
+  })
+
+  it('differs when customStyle differs', () => {
+    const a = computeVarsHash({ customStyle: '.foo { color: red; }' })
+    const b = computeVarsHash({ customStyle: '.foo { color: green; }' })
+    assert.notEqual(a, b)
+  })
+
+  it('is sensitive to array order (font import precedence)', () => {
+    const a = computeVarsHash({ themeVariables: { _font: { _externalFonts: ['a.css', 'b.css'] } } })
+    const b = computeVarsHash({ themeVariables: { _font: { _externalFonts: ['b.css', 'a.css'] } } })
+    assert.notEqual(a, b)
+  })
+})