Merge pull request #5776 from plotly/plot-schema-script

Sort plot-schema and add test to track plot-schema changes

Author: archmoj

.circleci/config.yml

@@ -204,6 +204,9 @@ jobs:
             echo https://$CIRCLE_BUILD_NUM-$PROJECT_NUM-gh.circle-artifacts.com/0/dist/plotly.js
             echo https://$CIRCLE_BUILD_NUM-$PROJECT_NUM-gh.circle-artifacts.com/0/dist/plotly.min.js
             echo https://$CIRCLE_BUILD_NUM-$PROJECT_NUM-gh.circle-artifacts.com/0/dist/plot-schema.json
+      - run:
+          name: Test plot-schema.json diff - If failed, after (npm start) you could run (npm run schema && git add test/plot-schema.json && git commit -m "update plot-schema diff")
+          command: diff --unified --color dist/plot-schema.json test/plot-schema.json
       - run:
           name: Test plotly.min.js import using requirejs
           command: npm run test-requirejs

CONTRIBUTING.md

@@ -138,14 +138,19 @@ Three additional helpers exist that are refreshed every second:
 There is also a search bar in the top right of the dashboard. This fuzzy-searches
 image mocks based on their file name and trace type.
 
-#### Alternative to test dashboard
+#### Step 5: Regenerate plot-schema in "test" folder then review & commit potential changes
 
-Use the [`plotly-mock-viewer`](https://github.com/rreusser/plotly-mock-viewer)
-which has live-reloading and a bunch of other cool features.
-An online version of `plotly-mock-viewer` is available at <https://rreusser.github.io/plotly-mock-viewer/>
-which uses <https://cdn.plot.ly/plotly-latest.min.js>
+```bash
+npm run schema
+```
+
+#### Step 6: Review & commit potential changes made to test/plot-schema.json
+
+> If you are editing attribute descriptions or implementing a new feature this file located in the test folder records the proposed changes to the API. Note that there is another plot-schema.json file located in the dist folder, which should only be updated by the maintainers at release time.
+
+**IMPORTANT:** please do not change and commit any files in the "dist" folder
 
-#### Other npm scripts
+#### Other npm scripts that may be of interest in development
 
 - `npm run preprocess`: pre-processes the css and svg source file in js. This
   script must be run manually when updating the css and svg source files.

draftlogs/5776_change.md

@@ -0,0 +1 @@
+ - Sort plot-schema and add test to track plot-schema changes [[#5776](https://github.com/plotly/plotly.js/pull/5776)]

package.json

@@ -24,13 +24,14 @@
     "custom-bundle": "node tasks/custom_bundle.js",
     "bundle": "node tasks/bundle.js",
     "extra-bundles": "node tasks/extra_bundles.js",
+    "schema": "node tasks/schema.js",
     "stats": "node tasks/stats.js",
     "find-strings": "node tasks/find_locale_strings.js",
     "preprocess": "node tasks/preprocess.js",
     "use-draftlogs": "node tasks/use_draftlogs.js",
     "empty-draftlogs": "node tasks/empty_draftlogs.js",
     "empty-dist": "node tasks/empty_dist.js",
-    "build": "npm run empty-dist && npm run preprocess && npm run find-strings && npm run bundle && npm run extra-bundles && npm run stats",
+    "build": "npm run empty-dist && npm run preprocess && npm run find-strings && npm run bundle && npm run extra-bundles && npm run schema dist && npm run stats",
     "cibuild": "npm run empty-dist && npm run preprocess && node tasks/cibundle.js",
     "watch": "node tasks/watch.js",
     "lint": "eslint --version && eslint .",

tasks/bundle.js

@@ -6,13 +6,11 @@ var prependFile = require('prepend-file');
 var constants = require('./util/constants');
 var common = require('./util/common');
 var _bundle = require('./util/browserify_wrapper');
-var makeSchema = require('./util/make_schema');
 var wrapLocale = require('./util/wrap_locale');
 
 var header = constants.licenseDist + '\n';
 var pathToLib = constants.pathToLib;
 var pathToDist = constants.pathToDist;
-var pathToSchema = constants.pathToSchema;
 var pathToPlotlyDist = constants.pathToPlotlyDist;
 var pathToPlotlyIndex = constants.pathToPlotlyIndex;
 var pathToPlotlyDistMin = constants.pathToPlotlyDistMin;
@@ -67,15 +65,14 @@ tasks.push(function(done) {
     });
 });
 
-// Browserify plotly.js with meta and output plot-schema JSON
+// Browserify plotly.js with meta
 tasks.push(function(done) {
     _bundle(pathToPlotlyIndex, pathToPlotlyDistWithMeta, {
         standalone: 'Plotly',
         noCompress: true
     }, function() {
         prependFile(pathToPlotlyDistWithMeta, header, common.throwOnError);
 
-        makeSchema(pathToPlotlyDistWithMeta, pathToSchema);
         done();
     });
 });

tasks/schema.js

@@ -0,0 +1,85 @@
+var fs = require('fs');
+var path = require('path');
+
+var constants = require('./util/constants');
+var plotlyNode = require('./util/plotly_node');
+
+function caseInsensitive(a, b) {
+    return a.toLowerCase().localeCompare(b.toLowerCase());
+}
+
+function isArray(v) {
+    return Array.isArray(v);
+}
+
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !(isArray(v));
+}
+
+function isArrayOfObjects(v) {
+    return isArray(v) && isObject(v[0]);
+}
+
+function typeHandle(v) {
+    return (
+        isArrayOfObjects(v) ? sortArrayOfObjects(v) :
+        isObject(v) ? sortObject(v) :
+        v
+    );
+}
+
+function sortArrayOfObjects(list) {
+    var newList = [];
+    for(var i = 0; i < list.length; i++) {
+        newList[i] = typeHandle(list[i]);
+    }
+
+    return newList;
+}
+
+function sortObject(obj) {
+    var allKeys = Object.keys(obj);
+    allKeys.sort(caseInsensitive);
+
+    var newObj = {};
+    for(var i = 0; i < allKeys.length; i++) {
+        var key = allKeys[i];
+        newObj[key] = typeHandle(obj[key]);
+    }
+
+    return newObj;
+}
+
+function makeSchema(plotlyPath, schemaPath) {
+    var Plotly = plotlyNode(plotlyPath);
+
+    var obj = Plotly.PlotSchema.get();
+    var sortedObj = sortObject(obj);
+    var plotSchemaRaw = JSON.stringify(obj, null, 1);
+    var plotSchemaStr = JSON.stringify(sortedObj, null, 1);
+
+    fs.writeFileSync(schemaPath, plotSchemaStr);
+
+    var lenBeforeSort = plotSchemaRaw.length;
+    var lenAfterSort = plotSchemaStr.length;
+    var linesBeforeSort = plotSchemaRaw.split('\n').length;
+    var linesAfterSort = plotSchemaStr.split('\n').length;
+    if(linesAfterSort !== linesBeforeSort || lenAfterSort !== lenBeforeSort) {
+        throw 'plot schema should have the same length & number of lines before and after sort';
+    } else {
+        console.log('ok ' + path.basename(schemaPath));
+    }
+}
+
+var isDist = process.argv.indexOf('dist') !== -1;
+
+var pathToSchema = isDist ?
+    constants.pathToSchemaDist :
+    constants.pathToSchemaDiff;
+
+var pathToPlotly = isDist ?
+    constants.pathToPlotlyDistWithMeta :
+    constants.pathToPlotlyBuild;
+
+// output plot-schema JSON
+makeSchema(pathToPlotly, pathToSchema);

tasks/util/constants.js

@@ -5,7 +5,8 @@ var pkg = require('../../package.json');
 var pathToRoot = path.join(__dirname, '../../');
 var pathToSrc = path.join(pathToRoot, 'src/');
 var pathToLib = path.join(pathToRoot, 'lib/');
-var pathToImageTest = path.join(pathToRoot, 'test/image');
+var pathToTest = path.join(pathToRoot, 'test/');
+var pathToImageTest = path.join(pathToTest, 'image/');
 var pathToStrictD3Module = path.join(pathToRoot, 'test/strict-d3.js');
 var pathToDraftlogs = path.join(pathToRoot, 'draftlogs/');
 var pathToDist = path.join(pathToRoot, 'dist/');
@@ -186,7 +187,8 @@ module.exports = {
     pathToPlotlyDistMin: path.join(pathToDist, 'plotly.min.js'),
     pathToPlotlyDistWithMeta: path.join(pathToDist, 'plotly-with-meta.js'),
 
-    pathToSchema: path.join(pathToDist, 'plot-schema.json'),
+    pathToSchemaDiff: path.join(pathToTest, 'plot-schema.json'),
+    pathToSchemaDist: path.join(pathToDist, 'plot-schema.json'),
     pathToTranslationKeys: path.join(pathToDist, 'translation-keys.txt'),
 
     partialBundleNames: partialBundleNames,

tasks/util/make_schema.js

@@ -21,6 +21,7 @@ module.exports = function makeWatchifiedBundle(onFirstBundleCallback) {
     var b = browserify(constants.pathToPlotlyIndex, {
         debug: true,
         standalone: 'Plotly',
+        ignoreTransform: './tasks/compress_attributes.js',
         transform: [],
         cache: {},
         packageCache: {},