feat(jsii): Tag the jsii compiler version in the .jsii assemblies (#420)

By default, the fully qualified version number (including the commit SHA
prefix) is written in the new `jsiiVersion` field of the assembly,
however in order to make this friendlier to tests, there is an option to
turn over to a *short* format by setting the new `jsii.versionFormat`
key in `package.json` to `'short'`.

Also, slightly altered the generation of the fully qualified version
name to distinguish between cases where the commit SHA was provided by
the CodeBuild environment variable, versus parsed using `git rev-parse`,
denoting the later is indicative of an "unreleased" version.

Fixes #412

README.md

@@ -67,7 +67,7 @@ Edit your `package.json`:
 ```js
 {
   // ...
-  
+
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {
@@ -97,14 +97,14 @@ Edit your `package.json`:
 
 So, what's going on here?
 
-* The `jsii` section in your `package.json` is the [jsii configuration](#configuration) for your module. 
+* The `jsii` section in your `package.json` is the [jsii configuration](#configuration) for your module.
   It tells jsii which target languages to package, and includes additional required information for the
   jsii packager.
-* `npm run build` uses `jsii` to compile your code. It invokes the TypeScript compiler (`tsc`) and will compile 
+* `npm run build` uses `jsii` to compile your code. It invokes the TypeScript compiler (`tsc`) and will compile
   your .ts files into .js files.
-* `npm run watch` will invoke `tsc -w` which will monitor your filesystem for changes and recompile 
+* `npm run watch` will invoke `tsc -w` which will monitor your filesystem for changes and recompile
    your .ts files to .js (note that jsii errors will not be reported in this mode)
-* `npm run package` invokes `jsii-pacmak`, which is the __jsii packager__. It will generate _and compile_ your 
+* `npm run package` invokes `jsii-pacmak`, which is the __jsii packager__. It will generate _and compile_ your
    package to all target languages. The output packages will be emitted to `outdir` (in the above case `dist`).
 * Other required `package.json` fields: `license`, `main`, `types`.
 
@@ -198,30 +198,30 @@ Now, if you check out the contents of `dist`, you'll find:
 
 ```
 ├── dotnet
-│   └── Acme.Hello.nupkg
+│   └── Acme.Hello.nupkg
 ├── java
-│   └── com
-│       └── acme
-│           └── hello
-│               └── hello-jsii
-│                   ├── 1.0.0
-│                   │   ├── hello-jsii-1.0.0-javadoc.jar
-│                   │   ├── hello-jsii-1.0.0-javadoc.jar.md5
-│                   │   ├── hello-jsii-1.0.0-javadoc.jar.sha1
-│                   │   ├── hello-jsii-1.0.0-sources.jar
-│                   │   ├── hello-jsii-1.0.0-sources.jar.md5
-│                   │   ├── hello-jsii-1.0.0-sources.jar.sha1
-│                   │   ├── hello-jsii-1.0.0.jar
-│                   │   ├── hello-jsii-1.0.0.jar.md5
-│                   │   ├── hello-jsii-1.0.0.jar.sha1
-│                   │   ├── hello-jsii-1.0.0.pom
-│                   │   ├── hello-jsii-1.0.0.pom.md5
-│                   │   └── hello-jsii-1.0.0.pom.sha1
-│                   ├── maven-metadata.xml
-│                   ├── maven-metadata.xml.md5
-│                   └── maven-metadata.xml.sha1
+│   └── com
+│       └── acme
+│           └── hello
+│               └── hello-jsii
+│                   ├── 1.0.0
+│                   │   ├── hello-jsii-1.0.0-javadoc.jar
+│                   │   ├── hello-jsii-1.0.0-javadoc.jar.md5
+│                   │   ├── hello-jsii-1.0.0-javadoc.jar.sha1
+│                   │   ├── hello-jsii-1.0.0-sources.jar
+│                   │   ├── hello-jsii-1.0.0-sources.jar.md5
+│                   │   ├── hello-jsii-1.0.0-sources.jar.sha1
+│                   │   ├── hello-jsii-1.0.0.jar
+│                   │   ├── hello-jsii-1.0.0.jar.md5
+│                   │   ├── hello-jsii-1.0.0.jar.sha1
+│                   │   ├── hello-jsii-1.0.0.pom
+│                   │   ├── hello-jsii-1.0.0.pom.md5
+│                   │   └── hello-jsii-1.0.0.pom.sha1
+│                   ├── maven-metadata.xml
+│                   ├── maven-metadata.xml.md5
+│                   └── maven-metadata.xml.sha1
 ├── js
-│   └── hello-jsii@1.0.0.jsii.tgz
+│   └── hello-jsii@1.0.0.jsii.tgz
 └── sphinx
     └── hello-jsii.rst
 ```

packages/jsii-calc-base-of-base/package.json

@@ -24,7 +24,8 @@
         "module": "scope.jsii_calc_base_of_base"
       },
       "sphinx": {}
-    }
+    },
+    "versionFormat": "short"
   },
   "scripts": {
     "build": "jsii",

packages/jsii-calc-base-of-base/test/assembly.jsii

@@ -9,6 +9,7 @@
   },
   "description": "An example transitive dependency for jsii-calc.",
   "homepage": "https://github.com/awslabs/jsii.git",
+  "jsiiVersion": "0.8.2",
   "license": "Apache-2.0",
   "name": "@scope/jsii-calc-base-of-base",
   "repository": {
@@ -73,5 +74,5 @@
     }
   },
   "version": "0.8.2",
-  "fingerprint": "oOrmdjK8cve8vAThWcnLUNaTPkvXx/XTFVMnVsR/dZc="
+  "fingerprint": "II5j+yUrBn6dB/gWFSs9fbCeaOJTu2szjv0xtMpkn80="
 }

packages/jsii-calc-base/package.json

@@ -24,7 +24,8 @@
         "module": "scope.jsii_calc_base"
       },
       "sphinx": {}
-    }
+    },
+    "versionFormat": "short"
   },
   "scripts": {
     "build": "jsii",
@@ -50,4 +51,4 @@
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
   }
-}
+}

packages/jsii-calc-base/test/assembly.jsii

@@ -35,6 +35,7 @@
   },
   "description": "An example direct dependency for jsii-calc.",
   "homepage": "https://github.com/awslabs/jsii.git",
+  "jsiiVersion": "0.8.2",
   "license": "Apache-2.0",
   "name": "@scope/jsii-calc-base",
   "repository": {
@@ -111,5 +112,5 @@
     }
   },
   "version": "0.8.2",
-  "fingerprint": "FrfcJZ64DB2APeRFjFb+EjYcfZxYEVji9GDpZ7KW1Ow="
+  "fingerprint": "rxvvJXFGzGZKodg4kjh0+uD9J3GU64sbBwcOkTFU9l8="
 }

packages/jsii-calc-lib/package.json

@@ -24,7 +24,8 @@
         "module": "scope.jsii_calc_lib"
       },
       "sphinx": {}
-    }
+    },
+    "versionFormat": "short"
   },
   "scripts": {
     "build": "jsii",
@@ -50,4 +51,4 @@
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
   }
-}
+}

packages/jsii-calc-lib/test/assembly.jsii

@@ -61,6 +61,7 @@
   },
   "description": "A simple calcuator library built on JSII.",
   "homepage": "https://github.com/awslabs/jsii.git",
+  "jsiiVersion": "0.8.2",
   "license": "Apache-2.0",
   "name": "@scope/jsii-calc-lib",
   "repository": {
@@ -371,5 +372,5 @@
     }
   },
   "version": "0.8.2",
-  "fingerprint": "8L8bV6COHcJBBT5CbQ4Bzwu5ZlT6VBMCXxB1S1TPczw="
+  "fingerprint": "ydArnwt9qdOM1IiBaOFzS2A7t9/+na0q+OibmkwQrEg="
 }

packages/jsii-calc/package.json

@@ -24,7 +24,8 @@
         "module": "jsii_calc"
       },
       "sphinx": {}
-    }
+    },
+    "versionFormat": "short"
   },
   "scripts": {
     "build": "jsii",
@@ -83,4 +84,4 @@
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
   }
-}
+}

packages/jsii-calc/test/assembly.jsii

@@ -187,6 +187,7 @@
   },
   "description": "A simple calcuator built on JSII.",
   "homepage": "https://github.com/awslabs/jsii.git",
+  "jsiiVersion": "0.8.2",
   "license": "Apache-2.0",
   "name": "jsii-calc",
   "readme": {
@@ -4632,5 +4633,5 @@
     }
   },
   "version": "0.8.2",
-  "fingerprint": "CSV1TF9zK+8oZfXWIov5XOKrTmFIpov07DaTV3k1IfA="
+  "fingerprint": "GihU8+thuZ1W9TNwDba1Ux44Rac3+kUHUCrGH73N0tw="
 }

packages/jsii-pacmak/test/expected.jsii-calc-base/dotnet/Amazon.JSII.Tests.CalculatorPackageId.BasePackageId/.jsii

@@ -35,6 +35,7 @@
   },
   "description": "An example direct dependency for jsii-calc.",
   "homepage": "https://github.com/awslabs/jsii.git",
+  "jsiiVersion": "0.8.2",
   "license": "Apache-2.0",
   "name": "@scope/jsii-calc-base",
   "repository": {
@@ -111,5 +112,5 @@
     }
   },
   "version": "0.8.2",
-  "fingerprint": "FrfcJZ64DB2APeRFjFb+EjYcfZxYEVji9GDpZ7KW1Ow="
+  "fingerprint": "rxvvJXFGzGZKodg4kjh0+uD9J3GU64sbBwcOkTFU9l8="
 }

packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/.jsii

@@ -61,6 +61,7 @@
   },
   "description": "A simple calcuator library built on JSII.",
   "homepage": "https://github.com/awslabs/jsii.git",
+  "jsiiVersion": "0.8.2",
   "license": "Apache-2.0",
   "name": "@scope/jsii-calc-lib",
   "repository": {
@@ -371,5 +372,5 @@
     }
   },
   "version": "0.8.2",
-  "fingerprint": "8L8bV6COHcJBBT5CbQ4Bzwu5ZlT6VBMCXxB1S1TPczw="
+  "fingerprint": "ydArnwt9qdOM1IiBaOFzS2A7t9/+na0q+OibmkwQrEg="
 }

packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii

@@ -187,6 +187,7 @@
   },
   "description": "A simple calcuator built on JSII.",
   "homepage": "https://github.com/awslabs/jsii.git",
+  "jsiiVersion": "0.8.2",
   "license": "Apache-2.0",
   "name": "jsii-calc",
   "readme": {
@@ -4632,5 +4633,5 @@
     }
   },
   "version": "0.8.2",
-  "fingerprint": "CSV1TF9zK+8oZfXWIov5XOKrTmFIpov07DaTV3k1IfA="
+  "fingerprint": "GihU8+thuZ1W9TNwDba1Ux44Rac3+kUHUCrGH73N0tw="
 }

packages/jsii-spec/lib/spec.ts

@@ -64,6 +64,12 @@ export interface Assembly extends Documentable {
      */
     version: string;
 
+    /**
+     * The version of the jsii compiler that was used to produce this Assembly.
+     * @minLength 1
+     */
+    jsiiVersion: string;
+
     /**
      * The SPDX name of the license this assembly is distributed on.
      */
@@ -93,7 +99,7 @@ export interface Assembly extends Documentable {
     /**
      * The top-level readme document for this assembly (if any).
      */
-    readme?: { markdown: string };
+    readme?: { markdown: string };
 }
 
 /**

packages/jsii-spec/test/test.name-tree.ts

@@ -21,6 +21,7 @@ export = testCase({
                     url: 'https://github.com/bla/bla'
                 },
                 version: '0.0.1',
+                jsiiVersion: 'TEST',
                 license: 'NONE',
                 fingerprint: '<no-fingerprint>',
                 targets: {},

packages/jsii/generate.sh

@@ -6,12 +6,16 @@ commit=${CODEBUILD_RESOLVED_SOURCE_VERSION:-}
 # use the HEAD commit hash
 if [ -z "${commit}" ]; then
   commit="$(git rev-parse --verify HEAD)"
+  suffix="@dev"
 fi
 
 cat > lib/version.ts <<HERE
 // Generated at $(date -u +"%Y-%m-%dT%H:%M:%SZ") by generate.sh
+// tslint:disable:no-var-requires
 
-/** The qualified version number for this JSII compiler. */
-// tslint:disable-next-line:no-var-requires
-export const VERSION = \`\${require('../package.json').version.replace(/\\+[0-9a-f]+\$/, '')} (build ${commit:0:7})\`;
+/** The short version number for this JSII compiler (e.g: \`X.Y.Z\`) */
+export const SHORT_VERSION = require('../package.json').version.replace(/\\+[0-9a-f]+\$/, '');
+
+/** The qualified version number for this JSII compiler (e.g: \`X.Y.Z (build #######)\`) */
+export const VERSION = \`\${SHORT_VERSION} (build ${commit:0:7}${suffix:-})\`;
 HERE

packages/jsii/lib/assembler.ts

@@ -12,6 +12,7 @@ import literate = require('./literate');
 import { ProjectInfo } from './project-info';
 import utils = require('./utils');
 import { Validator } from './validator';
+import { VERSION, SHORT_VERSION } from './version';
 
 // tslint:disable:no-var-requires Modules without TypeScript definitions
 const sortJson = require('sort-json');
@@ -94,13 +95,15 @@ export class Assembler implements Emitter {
             }
         }
 
+        const jsiiVersion = this.projectInfo.jsiiVersionFormat === 'short' ? SHORT_VERSION : VERSION;
+
         const assembly = {
             schema: spec.SchemaVersion.V1_0,
             name: this.projectInfo.name,
             version: this.projectInfo.version,
             description: this.projectInfo.description || this.projectInfo.name,
             license: this.projectInfo.license,
-            homepage: this.projectInfo.homepage || this.projectInfo.repository.url,
+            homepage: this.projectInfo.homepage || this.projectInfo.repository.url,
             author: this.projectInfo.author,
             contributors: this.projectInfo.contributors && [...this.projectInfo.contributors],
             repository: this.projectInfo.repository,
@@ -109,6 +112,7 @@ export class Assembler implements Emitter {
             types: this._types,
             targets: this.projectInfo.targets,
             readme,
+            jsiiVersion,
             fingerprint: '<TBD>'
         };
 
@@ -615,7 +619,7 @@ export class Assembler implements Emitter {
      *
      * @returns ``documentable``
      */
-    private _visitDocumentation<T extends spec.Documentable>(symbol: ts.Symbol | ts.Signature, documentable: T): T {
+    private _visitDocumentation<T extends spec.Documentable>(symbol: ts.Symbol | ts.Signature, documentable: T): T {
         const comment = ts.displayPartsToString(symbol.getDocumentationComment(this._typeChecker)).trim();
         if (comment) {
             if (LOG.isTraceEnabled()) {

packages/jsii/lib/project-info.ts

@@ -31,6 +31,7 @@ export interface ProjectInfo {
     readonly transitiveDependencies: ReadonlyArray<spec.Assembly>;
     readonly bundleDependencies: { readonly [name: string]: string };
     readonly targets: spec.AssemblyTargets;
+    readonly jsiiVersionFormat: 'short' | 'full';
     readonly description?: string;
     readonly homepage?: string;
     readonly contributors?: ReadonlyArray<spec.Person>;
@@ -87,6 +88,7 @@ export async function loadProjectInfo(projectRoot: string): Promise<ProjectInfo>
             ..._required(pkg.jsii, 'The "package.json" file must specify the "jsii" attribute').targets,
             js: { npm: pkg.name }
         },
+        jsiiVersionFormat: _validateVersionFormat(pkg.jsii.versionFormat || 'full'),
 
         description: pkg.description,
         homepage: pkg.homepage,
@@ -182,3 +184,10 @@ function _validateLicense(id: string): string {
     }
     return id;
 }
+
+function _validateVersionFormat(format: string): 'short' | 'full' {
+    if (format !== 'short' && format !== 'full') {
+        throw new Error(`Invalid jsii.versionFormat "${format}", it must be either "short" or "full" (the default)`);
+    }
+    return format;
+}

packages/jsii/test/test.negatives.ts

@@ -67,6 +67,7 @@ function _makeProjectInfo(types: string): ProjectInfo {
         main: types.replace(/(?:\.d)?\.ts(x?)/, '.js$1'),
         name: 'jsii', // That's what package.json would tell if we look up...
         version: '0.0.1',
+        jsiiVersionFormat: 'short',
         license: 'Apache-2.0',
         author: { name: 'John Doe', roles: ['author'] },
         repository: { type: 'git', url: 'https://github.com/awslabs/jsii.git' },

packages/jsii/test/test.project-info.ts

@@ -5,6 +5,7 @@ import nodeunit = require('nodeunit');
 import os = require('os');
 import path = require('path');
 import { loadProjectInfo } from '../lib/project-info';
+import { VERSION } from '../lib/version';
 
 const BASE_PROJECT = {
     name: 'jsii-test',
@@ -177,7 +178,8 @@ const TEST_DEP_ASSEMBLY: spec.Assembly = {
         'jsii-test-dep-dep': {
             version: '3.2.1'
         }
-    }
+    },
+    jsiiVersion: VERSION,
 };
 
 const TEST_DEP_DEP_ASSEMBLY: spec.Assembly = {
@@ -189,6 +191,7 @@ const TEST_DEP_DEP_ASSEMBLY: spec.Assembly = {
     homepage: 'https://github.com/awslabs/jsii',
     repository: { type: 'git', url: 'git://github.com/awslabs/jsii.git' },
     author: { name: 'Amazon Web Services', url: 'https://aws.amazon.com', organization: true, roles: ['author'] },
+    jsiiVersion: VERSION,
     fingerprint: 'F1NG3RPR1N7'
 };