feat: add .version field and assertVersion helper to plugin api (#…

…3861)

partially addresses #2336 (GeneratorAPI TBD)

docs/dev-guide/plugin-api.md

@@ -1,5 +1,24 @@
 # Plugin API
 
+## version
+
+Type: `string`
+
+The version string for the `@vue/cli-service` version that is loading the plugin.
+
+
+## assertVersion(range)
+
+- **Arguments**
+  - `{integer | string} range` - a semver range that `@vue/cli-service` needs to satisfy
+
+- **Usage**
+
+  While api.version can be useful in general, it's sometimes nice to just declare your version.
+  This API exposes a simple way to do that.
+
+  Nothing happens if the provided version is satified. Otherwise, an error will be thrown.
+
 ## getCwd
 
 - **Usage**:

packages/@vue/cli-service/__tests__/Service.spec.js

@@ -170,6 +170,21 @@ test('load project options from vue.config.js', () => {
   expect(service.projectOptions.lintOnSave).toBe(false)
 })
 
+test('api: assertVersion', () => {
+  const plugin = {
+    id: 'test-assertVersion',
+    apply: api => {
+      expect(() => api.assertVersion(3)).not.toThrow()
+      expect(() => api.assertVersion('3')).not.toThrow()
+      expect(() => api.assertVersion('>= 3')).not.toThrow()
+
+      expect(() => api.assertVersion(3.1)).toThrow('Expected string or integer value')
+      expect(() => api.assertVersion('^100')).toThrow('Require @vue/cli-service "^100"')
+    }
+  }
+  createMockService([plugin], true /* init */)
+})
+
 test('api: registerCommand', () => {
   let args
   const service = createMockService([{

packages/@vue/cli-service/lib/PluginAPI.js

@@ -1,5 +1,6 @@
 const path = require('path')
 const hash = require('hash-sum')
+const semver = require('semver')
 const { matchesPluginId } = require('@vue/cli-shared-utils')
 
 // Note: if a plugin-registered command needs to run in a specific default mode,
@@ -17,6 +18,29 @@ class PluginAPI {
     this.service = service
   }
 
+  get version () {
+    return require('../package.json').version
+  }
+
+  assertVersion (range) {
+    if (typeof range === 'number') {
+      console.log(range, Number.isInteger(range))
+      if (!Number.isInteger(range)) {
+        throw new Error('Expected string or integer value.')
+      }
+      range = `^${range}.0.0-0`
+    }
+    if (typeof range !== 'string') {
+      throw new Error('Expected string or integer value.')
+    }
+
+    if (semver.satisfies(this.version, range)) return
+
+    throw new Error(
+      `Require @vue/cli-service "${range}", but was loaded with "${this.version}".`
+    )
+  }
+
   /**
    * Current working directory.
    */