New: Add hard-limit for framework major version (fixes #142) (#169)

Author: Copilot

adapt-authoring.json

@@ -1,5 +1,8 @@
 {
   "documentation": {
     "enable": true
+  },
+  "framework": {
+    "targetVersion": 5
   }
 }

errors/errors.json

@@ -126,5 +126,14 @@
     },
     "description": "Plugin is missing a dependency",
     "statusCode": 500
+  },
+  "FW_VERSION_NOT_ALLOWED": {
+    "data": {
+      "version": "The version that is not allowed",
+      "targetMajorVersion": "The allowed major version number",
+      "allowedRange": "The allowed semver range"
+    },
+    "description": "Framework version is outside the allowed major version",
+    "statusCode": 400
   }
 }

lib/AdaptFrameworkModule.js

@@ -70,6 +70,13 @@ class AdaptFrameworkModule extends AbstractModule {
      */
     this.contentMigrations = []
 
+    const meta = await readJson(path.resolve(this.rootDir, 'adapt-authoring.json'))
+    /**
+     * The major version of the Adapt framework this module is designed to work with
+     * @type {Number}
+     */
+    this._targetFrameworkVersion = meta.framework?.targetVersion
+
     this.app.waitForModule('content').then(content => {
       content.accessCheckHook.tap(this.checkContentAccess.bind(this))
     })
@@ -103,6 +110,36 @@ class AdaptFrameworkModule extends AbstractModule {
     return this._version
   }
 
+  /**
+   * The major version of the Adapt framework this module is designed to work with
+   * @type {Number|undefined}
+   */
+  get targetFrameworkVersion () {
+    return this._targetFrameworkVersion
+  }
+
+  /**
+   * Returns a semver range string constrained to the target major version, or undefined if no target is set
+   * @type {String|undefined}
+   */
+  get targetVersionRange () {
+    if (this._targetFrameworkVersion === undefined) return undefined
+    return `>=${this._targetFrameworkVersion}.0.0 <${this._targetFrameworkVersion + 1}.0.0`
+  }
+
+  /**
+   * Checks whether the given version is compatible with the configured target major version
+   * @param {string} version Semver version string to check
+   * @throws If the version's major does not match the target major version
+   */
+  checkVersionCompatibility (version) {
+    if (this._targetFrameworkVersion === undefined) return
+    const major = semver.major(version)
+    if (major !== this._targetFrameworkVersion) {
+      throw this.app.errors.FW_VERSION_NOT_ALLOWED.setData({ version, targetMajorVersion: this._targetFrameworkVersion, allowedRange: this.targetVersionRange })
+    }
+  }
+
   /**
    * Installs a local copy of the Adapt framework
    * @return {Promise}
@@ -121,10 +158,13 @@ class AdaptFrameworkModule extends AbstractModule {
       } catch (e) {
         // package is missing, an install is required
       }
-      await this.runCliCommand('installFramework', { version })
+      if (version) {
+        this.checkVersionCompatibility(version)
+      }
+      await this.runCliCommand('installFramework', { version: version ?? this.targetVersionRange })
     } catch (e) {
       this.log('error', `failed to install framework, ${e.message}`)
-      throw this.app.errors.FW_INSTALL_FAILED.setData({ reason: e.message })
+      throw e.statusCode ? e : this.app.errors.FW_INSTALL_FAILED.setData({ reason: e.message })
     }
     this.log('verbose', 'INSTALL hook invoke')
     await this.postInstallHook.invoke()
@@ -136,7 +176,7 @@ class AdaptFrameworkModule extends AbstractModule {
    */
   async getLatestVersion () {
     try {
-      return semver.clean(await this.runCliCommand('getLatestFrameworkVersion'))
+      return semver.clean(await this.runCliCommand('getLatestFrameworkVersion', { version: this.targetVersionRange }))
     } catch (e) {
       this.log('error', `failed to retrieve framework update data, ${e.message}`)
       throw this.app.errors.FW_LATEST_VERSION_FAILED.setData({ reason: e.message })
@@ -167,11 +207,14 @@ class AdaptFrameworkModule extends AbstractModule {
    */
   async updateFramework (version) {
     try {
-      await this.runCliCommand('updateFramework', { version })
+      if (version) {
+        this.checkVersionCompatibility(version)
+      }
+      await this.runCliCommand('updateFramework', { version: version ?? this.targetVersionRange })
       this._version = await this.runCliCommand('getCurrentFrameworkVersion')
     } catch (e) {
       this.log('error', `failed to update framework, ${e.message}`)
-      throw this.app.errors.FW_UPDATE_FAILED.setData({ reason: e.message })
+      throw e.statusCode ? e : this.app.errors.FW_UPDATE_FAILED.setData({ reason: e.message })
     }
     this.postUpdateHook.invoke()
   }
@@ -181,7 +224,7 @@ class AdaptFrameworkModule extends AbstractModule {
    */
   async logStatus () {
     const current = this.version
-    const latest = await this.runCliCommand('getLatestFrameworkVersion')
+    const latest = await this.getLatestVersion()
 
     this.log('info', `local adapt_framework v${current} installed`)
     if (semver.lt(current, latest)) {