Conf schema upgrade and upgrade assistant (#128)

BREAKING CHANGE: Option `linking` has become `linking.paths`. Option `baseUrl` has become `linking.baseUrl`. An upgrade assistant will help with the migration. From this version on configuration files must refer to a schema by means of a versioned path. This helps the upgrade assistant in future releases to find out what changes need to be applied to upgrade from an old schema. * test: Upgrade test configurations to v5 schema. * test: New baseline.
about-code · Dec 6, 2020 · 1eb152f · 1eb152f
1 parent 0310e93
commit 1eb152f
Show file tree

Hide file tree

Showing 89 changed files with 2,789 additions and 1,474 deletions.
diff --git a/bin/index.js b/bin/index.js
@@ -5,10 +5,10 @@ const fs = require("fs-extra");
 const path = require("path");
 const proc = require("process");
 const program = require("../lib/main");
-const confSchema = require("../conf.schema.json").properties;
-const {NO_BASEDIR, NO_OUTDIR, OUTDIR_IS_BASEDIR, OUTDIR_NOT_DELETED, OUTDIR_IS_BASEDIR_WITH_DROP} = require("../lib/cli/messages");
+const upgrade = require("../lib/cli/upgrade");
+const confSchema = require("../conf/v5/schema.json").properties;
+const {NO_BASEDIR, NO_OUTDIR, OUTDIR_IS_BASEDIR, OUTDIR_IS_BASEDIR_WITH_DROP} = require("../lib/cli/messages");
 const {version} = require("../package.json");
-
 const CWD = proc.cwd();
 const banner =
 `┌──────────────────────────┐
@@ -64,12 +64,16 @@ if (argv.help || proc.argv.length === 2) {
 // --config
 let confDir = "";
 let confPath = argv.config || "";
-let optsFile = {};
+let confData = {};
+let optsPromise = Promise.resolve({});
 if (confPath) {
     try {
         confPath = path.resolve(CWD, confPath);
         confDir = path.dirname(confPath);
-        optsFile = JSON.parse(fs.readFileSync(confPath));
+        confData = JSON.parse(fs.readFileSync(confPath));
+        if (!argv.noupgrade) {
+            optsPromise = upgrade(confData, confPath);
+        }
     } catch (e) {
         console.error(`Failed to read config '${confPath}'.\nReason:\n  ${e.message}\n`);
         proc.exit(1);
@@ -78,65 +82,55 @@ if (confPath) {
     confDir = CWD;
 }
 
-const optsDefault = Object
-    .keys(confSchema)
-    .reduce((obj, key) => {
-        obj[key] = confSchema[key].default;
-        return obj;
-    }, {});
-
-let opts = optsFile;
+optsPromise.then((opts) => {
 
-// --deep
-if (argv.deep) {
-    try {
-        opts = merge(opts, JSON.parse(argv.deep.replace(/'/g, "\"")));
-    } catch (e) {
-        console.error(`Failed to parse value for --deep.\nReason:\n  ${e.message}\n`);
-        proc.exit(1);
-    }
-}
-// --shallow
-if (argv.shallow) {
-    try {
-        opts = Object.assign(opts, JSON.parse(argv.shallow.replace(/'/g, "\"")));
-    } catch (e) {
-        console.error(`Failed to parse value for --shallow.\nReason:\n  ${e.message}\n`);
-        proc.exit(1);
+    // --deep custum opts
+    if (argv.deep) {
+        try {
+            opts = merge(opts, JSON.parse(argv.deep.replace(/'/g, "\"")));
+        } catch (e) {
+            console.error(`Failed to parse value for --deep.\nReason:\n  ${e.message}\n`);
+            proc.exit(1);
+        }
     }
-}
-opts = merge(optsDefault, opts, {
-    clone: false
-    , arrayMerge: (_default, curOpts) => {
-        return curOpts && curOpts.length > 0 ? curOpts : _default;
+    // --shallow custom opts
+    if (argv.shallow) {
+        try {
+            opts = Object.assign(opts, JSON.parse(argv.shallow.replace(/'/g, "\"")));
+        } catch (e) {
+            console.error(`Failed to parse value for --shallow.\nReason:\n  ${e.message}\n`);
+            proc.exit(1);
+        }
     }
-});
-
-// --init
-if (argv.init) {
-    console.log(JSON.stringify(opts, null, 2));
-    proc.exit(0);
-}
-
-// Resolve 2nd arg paths relative to 1st arg paths...
-opts.baseDir = path.resolve(confDir, opts.baseDir);
-opts.outDir  = path.resolve(opts.baseDir, opts.outDir);
-
-validateOpts(opts);
+    // Merge custom opts with default opts
+    const optsDefault = Object.keys(confSchema).reduce((obj, key) => {
+        obj[key] = confSchema[key].default;
+        return obj;
+    }, {});
+    opts = merge(optsDefault, opts, {
+        clone: false
+        , arrayMerge: (_default, curOpts) => {
+            return curOpts && curOpts.length > 0 ? curOpts : _default;
+        }
+    });
 
-// _/ Drop old stuff \__________________________________________________________
-if (opts.outDirDropOld) {
-    try {
-        fs.removeSync(opts.outDir);
-    } catch (err) {
-        console.log(OUTDIR_NOT_DELETED,` Reason: ${err.code}
-    `);
+    // --init
+    if (argv.init) {
+        console.log(JSON.stringify(opts, null, 2));
+        proc.exit(0);
     }
-}
 
+    // Resolve baseDir relative to confDir and outDir relative to baseDir
+    opts.baseDir = path.resolve(confDir, opts.baseDir);
+    opts.outDir  = path.resolve(opts.baseDir, opts.outDir);
+    validateOpts(opts);
 
-// _/ Run \_____________________________________________________________________
-program.run(opts);
+    // _/ Run \_____________________________________________________________________
+    program.run(opts);
+}).catch(error => {
+    console.error(error);
+    proc.exit(1);
+});
 
 // _/ Helpers \_________________________________________________________________
 function validateOpts(conf) {

diff --git a/conf.schema.json b/conf.schema.json
@@ -1,23 +1,17 @@
 {
     "$schema": "http://json-schema.org/draft-07/schema",
-    "$id": "https://raw.githubusercontent.com/about-code/glossarify-md/v5.0.0/conf.schema.json",
+    "$id": "https://raw.githubusercontent.com/about-code/glossarify-md/v5.0.0/conf/v5/schema.json",
     "type": "object",
     "properties": {
         "$schema": {
             "type": "string",
-            "default": "./node_modules/glossarify-md/conf.schema.json"
+            "default": "./node_modules/glossarify-md/conf/v5/schema.json"
         },
         "baseDir": {
             "description": "Path to directory where to search for the glossary file and markdown files. All paths in a config file will be relative to *baseDir*. *baseDir* itself is relative to the location of the config file or the current working directory when provided via command line.",
             "type": "string",
             "default": "./docs"
         },
-        "baseUrl": {
-            "description": "The base url to use when creating absolute links to glossary.",
-            "type": "string",
-            "format": "url",
-            "default": ""
-        },
         "excludeFiles": {
             "description": "An array of files or file name patterns that should not be included in any processing.",
             "type": "array",
@@ -85,13 +79,12 @@
         },
         "linking": {
             "description": "Whether to use relative or absolute links. Choosing 'absolute' requires a 'baseUrl'.",
-            "oneOf": [{
-                "$ref": "#/$defs/LinkingOpts"
-            },{
-                "description": "Deprecated. Use linking: { \"paths\": \"...\" } with values \"relative\" or \"absolute\" instead.",
-                "$ref": "#/$defs/LinkPaths"
-            }],
-            "default": "relative"
+            "$ref": "#/$defs/LinkingOpts",
+            "default": {
+                "baseUrl": "",
+                "paths": "relative",
+                "terms": "all"
+            }
         },
         "outDir": {
             "description": "Path to directory where to write processed files to.",
@@ -228,17 +221,21 @@
         "LinkingOpts": {
             "type": "object",
             "properties": {
-                "paths": { "$ref": "#/$defs/LinkPaths" },
+                "baseUrl": {
+                    "description": "The base url to use when creating absolute links to glossary.",
+                    "type": "string",
+                    "format": "url"
+                },
+                "paths": {
+                    "type": "string",
+                    "enum": ["relative", "absolute"]
+                },
                 "terms": {
                     "type": "string",
                     "enum": ["all", "first-in-paragraph"]
                 }
             }
         },
-        "LinkPaths": {
-            "type": "string",
-            "enum": ["relative", "absolute"]
-        },
         "DevOpts": {
             "type": "object",
             "properties": {