Completely refactor build system (#205)

The goals of this refactoring are the following:

- Improve code quality of the build system
- Prepare code base for adding code coverage
- Prepare code base for exposing the build system as a package export,
  so platforms can build their `cordova.js` during their build (or
  creation) process. This would make the JS build using coho obsolete.
- Prepare code base to remove dependency on Grunt

The build process now lives under `build-tools` (was `tasks`). It does
not depend on Grunt anymore but is written in plain Node.js.

The original Grunt interface for building (as used by coho) was
preserved and is implemented in `Gruntfile.js` using the new build
system. The `platformName` option and support for getting platform paths
from the `cordova-platforms` key in `package.json` have been removed
from the Grunt interface, but neither of those are used in coho.

The logic that is specific to the test build has been extracted from
the rest of the build. It now lives in `test/build.js` and is run
automatically during `npm test`.

The following dependencies have been added:

- execa
- fs-extra
- globby

I have taken extra care to preserve the exact format of the built file.
This means that the correctness of the refactoring can be verified by
simply diffing the build artifacts in `pkg` created with and without
this change.

Author: raphinesse

Gruntfile.js

@@ -16,6 +16,10 @@
  * specific language governing permissions and limitations
  * under the License.
 */
+
+const path = require('path');
+const { build, collectModules } = require('./build-tools');
+
 module.exports = function (grunt) {
 
     grunt.initConfig({
@@ -24,20 +28,46 @@ module.exports = function (grunt) {
             'android': {},
             'ios': {},
             'osx': {},
-            'test': {},
             'windows': { useWindowsLineEndings: true },
             'browser': {},
             'electron': {}
         },
         clean: ['pkg']
     });
 
+    // custom tasks
+    grunt.registerMultiTask('compile', 'Packages cordova.js', function () {
+        const done = this.async();
+
+        const platformPath = path.resolve(`../cordova-${this.target}`);
+        const platformPkgPath = path.join(platformPath, 'package');
+        const platformModulesPath = path.join(platformPath, 'cordova-js-src');
+
+        build({
+            platformName: this.target,
+            platformVersion: grunt.option('platformVersion') ||
+                             require(platformPkgPath).version,
+            extraModules: collectModules(platformModulesPath)
+        })
+            .then(cordovaJs => {
+                // if we are using windows line endings, we will also add the BOM
+                if (this.data.useWindowsLineEndings) {
+                    cordovaJs = '\ufeff' + cordovaJs.split(/\r?\n/).join('\r\n');
+                }
+
+                // Write out the bundle
+                const baseName = `cordova.${this.target}.js`;
+                const fileName = path.join('pkg', baseName);
+                grunt.file.write(fileName, cordovaJs);
+
+                console.log(`Generated ${fileName}`);
+            })
+            .then(done, done);
+    });
+
     // external tasks
     grunt.loadNpmTasks('grunt-contrib-clean');
 
-    // custom tasks
-    grunt.loadTasks('tasks');
-
     // defaults
     grunt.registerTask('default', ['compile']);
 };

build-tools/build.js

@@ -0,0 +1,42 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+const execa = require('execa');
+const bundle = require('./bundle');
+const scripts = require('./scripts');
+const modules = require('./modules');
+const { pkgRoot } = require('./common');
+
+module.exports = function build (userConfig) {
+    const config = Object.assign({ preprocess: x => x }, userConfig);
+
+    return Promise.all([
+        scripts(config),
+        modules(config),
+        getCommitId()
+    ])
+        .then(([ scripts, modules, commitId ]) => {
+            Object.assign(config, { commitId });
+            return bundle(scripts, modules, config);
+        });
+};
+
+function getCommitId () {
+    return execa.stdout('git', ['rev-parse', 'HEAD'], { cwd: pkgRoot });
+}

build-tools/bundle.js

@@ -0,0 +1,63 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+module.exports = function bundle (scripts, modules, config) {
+    const context = Object.assign({
+        modules: modules.map(m => m.contents).join('\n'),
+        includeScript: name => scripts[name].contents
+    }, config);
+
+    return bundleTemplate(context);
+};
+
+const bundleTemplate = ({
+    commitId,
+    platformName,
+    platformVersion,
+    includeScript,
+    modules
+}) => `
+// Platform: ${platformName}
+// ${commitId}
+/*
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+\x20
+     http://www.apache.org/licenses/LICENSE-2.0
+\x20
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+*/
+;(function() {
+var PLATFORM_VERSION_BUILD_LABEL = '${platformVersion}';
+${includeScript('require')}
+${modules}
+window.cordova = require('cordova');
+${includeScript('bootstrap')}
+})();
+`.trim();

build-tools/common.js

@@ -0,0 +1,62 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const globby = require('globby');
+
+const pkgRoot = path.join(__dirname, '..');
+
+module.exports = {
+    pkgRoot,
+
+    values (obj) {
+        return Object.keys(obj).map(key => obj[key]);
+    },
+
+    readContents (f) {
+        return fs.readFile(f.path, 'utf8')
+            .then(contents => Object.assign({}, f, { contents }));
+    },
+
+    // Strips the license header.
+    // Basically only the first multi-line comment up to to the closing */
+    stripLicenseHeader (f) {
+        const LICENSE_REGEX = /^\s*\/\*[\s\S]+?\*\/\s*/;
+        const withoutLicense = f.contents.replace(LICENSE_REGEX, '');
+        return Object.assign({}, f, { contents: withoutLicense });
+    },
+
+    // TODO format path relative to pkg.json
+    prependFileComment (f) {
+        const comment = `// file: ${f.path}`;
+        const contents = [comment, f.contents].join('\n');
+        return Object.assign({}, f, { contents });
+    },
+
+    collectModules (dir) {
+        return globby.sync(['**/*.js'], { cwd: dir })
+            .map(fileName => ({
+                path: path.relative(pkgRoot, path.join(dir, fileName)),
+                moduleId: fileName.slice(0, -3)
+            }))
+            .map(file => ({ [file.moduleId]: file }))
+            .reduce((result, fragment) => Object.assign(result, fragment), {});
+    }
+};

build-tools/index.js

@@ -0,0 +1,23 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+module.exports = {
+    build: require('./build'),
+    collectModules: require('./common').collectModules
+};

build-tools/modules.js

@@ -0,0 +1,80 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+const path = require('path');
+
+const {
+    readContents,
+    stripLicenseHeader,
+    prependFileComment,
+    values,
+    pkgRoot,
+    collectModules
+} = require('./common');
+
+module.exports = function modules (config) {
+    for (const m of values(config.extraModules)) {
+        if (m.path.startsWith('../')) {
+            m.path = path.resolve(m.path);
+        }
+    }
+
+    const commonModules = collectCommonModules();
+    const modules = values(Object.assign(commonModules, config.extraModules));
+    modules.sort((a, b) => a.moduleId.localeCompare(b.moduleId));
+    return Promise.all(modules.map(modulePipeline(config)));
+};
+
+function collectCommonModules () {
+    const modules = collectModules(path.join(pkgRoot, 'src/common'));
+    modules[''] = {
+        moduleId: '',
+        path: path.relative(pkgRoot, path.join(pkgRoot, 'src/cordova.js'))
+    };
+    return modules;
+}
+
+function modulePipeline (config) {
+    return f => Promise.resolve(f)
+        .then(readContents)
+        .then(config.preprocess)
+        .then(stripLicenseHeader)
+        .then(addModuleNamespace('cordova'))
+        .then(wrapInModuleContext)
+        .then(prependFileComment);
+}
+
+function addModuleNamespace (ns) {
+    return m => {
+        const moduleId = path.posix.join(ns, m.moduleId);
+        return Object.assign({}, m, { moduleId });
+    };
+}
+
+function wrapInModuleContext (f) {
+    const contents = moduleTemplate({ id: f.moduleId, body: f.contents });
+    return Object.assign({}, f, { contents });
+}
+
+const moduleTemplate = ({ id, body }) => `
+define("${id}", function(require, exports, module) {
+
+${body}
+});
+`.trimLeft();

build-tools/scripts.js

@@ -0,0 +1,61 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+const path = require('path');
+const {
+    readContents,
+    stripLicenseHeader,
+    prependFileComment,
+    values,
+    pkgRoot,
+    collectModules
+} = require('./common');
+
+module.exports = function scripts (config) {
+    const scripts = values(collectScripts());
+    return Promise.all(scripts.map(scriptPipeline(config)))
+        .then(indexByModuleId);
+};
+
+function collectScripts () {
+    const scripts = collectModules(path.join(pkgRoot, 'src/scripts'));
+    for (const script of ['require', 'bootstrap']) {
+        if (script in scripts) continue;
+        throw new Error(`Could not find required script '${script}.js'`);
+    }
+    return scripts;
+}
+
+function scriptPipeline (config) {
+    return f => Promise.resolve(f)
+        .then(readContents)
+        .then(config.preprocess)
+        .then(stripLicenseHeader)
+        .then(prependEmptyLine)
+        .then(prependFileComment);
+}
+
+function prependEmptyLine (f) {
+    return Object.assign({}, f, { contents: '\n' + f.contents });
+}
+
+function indexByModuleId (files) {
+    return files
+        .reduce((acc, f) => Object.assign(acc, { [f.moduleId]: f }), {});
+}