feat(cli): New parameter --init to generate a config file with all op…

…tions and defaults (#126)

* Bump test suite version
* test: New test case.
* test: New baseline.

bin/index.js

@@ -15,11 +15,16 @@ const banner =
 │   glossarify-md v${version}   │
 └──────────────────────────┘
 `;
-console.log(banner);
 
 // _/ CLI \_____________________________________________________________________
 const cli = {
-    "config": {
+    "init": {
+        alias: "new"
+        ,description: "Generate a complete configuration file with default values."
+        ,type: "boolean"
+        ,default: false
+    }
+    ,"config": {
         alias: "c"
         ,description: "Path to config file, e.g. './glossarify-md.conf.json'."
         ,type: "string"
@@ -46,10 +51,14 @@ const cli = {
 };
 const argv = minimist(proc.argv.slice(2), cli);
 
+if (!argv.init) {
+    // print banner only without --init to prevent writing banner to config.
+    console.log(banner);
+}
 // --help (or no args at all)
 if (argv.help || proc.argv.length === 2) {
     printOpts(cli);
-    process.exit(0);
+    proc.exit(0);
 }
 
 // --config
@@ -103,9 +112,16 @@ opts = merge(optsDefault, opts, {
     }
 });
 
+// --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);
 
 // _/ Drop old stuff \__________________________________________________________

conf.schema.json

@@ -3,26 +3,27 @@
     "$id": "https://raw.githubusercontent.com/about-code/glossarify-md/v5.0.0/conf.schema.json",
     "type": "object",
     "properties": {
+        "$schema": {
+            "type": "string",
+            "default": "./node_modules/glossarify-md/conf.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",
-            "alias": "d",
-            "default": ""
+            "default": "./docs"
         },
         "baseUrl": {
             "description": "The base url to use when creating absolute links to glossary.",
             "type": "string",
             "format": "url",
-            "alias": "b",
-            "default": "http://127.0.0.1"
+            "default": ""
         },
         "excludeFiles": {
             "description": "An array of files or file name patterns that should not be included in any processing.",
             "type": "array",
             "items": {
                 "type": "string"
             },
-            "alias": "e",
             "default": ["node_modules", ".git"]
         },
         "force": {
@@ -43,15 +44,13 @@
             "items": {
                 "$ref": "#/$defs/GlossariesOpts"
             },
-            "alias": "g",
             "default": [
                 { "file": "./glossary.md", "termHint": ""}
             ]
         },
         "ignoreCase": {
             "description": "Find and link every occurrence of a term no matter how it is spelled.",
             "type": "boolean",
-            "alias": "i",
             "default": false
         },
         "includeFiles": {
@@ -60,7 +59,6 @@
             "items": {
                 "type": "string"
             },
-            "alias": "f",
             "default": ["."]
         },
         "indexing": {
@@ -83,7 +81,6 @@
             "items": {
                 "type": "string"
             },
-            "alias": "r",
             "default": []
         },
         "linking": {
@@ -93,25 +90,21 @@
                 "relative",
                 "absolute"
             ],
-            "alias": "l",
             "default": "relative"
         },
         "outDir": {
             "description": "Path to directory where to write processed files to.",
             "type": "string",
-            "alias": "o",
-            "default": ""
+            "default": "./docs-glossarified"
         },
         "outDirDropOld": {
             "description": "If true, remove old 'outDir' before creating a new one. Otherwise just overwrite old files. Default: true",
             "type": "boolean",
-            "alias": "",
             "default": true
         },
         "reportNotMentioned": {
             "description": "Report on terms which exist in a glossary but have neither been mentioned directly nor with any of its aliases.",
             "type": "boolean",
-            "alias": "",
             "default": false
         },
         "dev": {
@@ -148,6 +141,24 @@
                 }
             }
         },
+        "GlossariesOpts": {
+            "type": "object",
+            "properties": {
+                "file": {
+                    "description": "Name of the glossary file. Conventional default is 'glossary.md'",
+                    "type": "string"
+                },
+                "termHint": {
+                    "description": "A symbol to append to a link to denote that the term refers to a glossary term.",
+                    "type": "string"
+                },
+                "sort": {
+                    "description": "If present, sort terms in output glossary. Default: None. See also i18n options.",
+                    "type": "string",
+                    "enum": ["asc", "desc"]
+                }
+            }
+        },
         "IndexFileOpts": {
             "type": "object",
             "properties": {
@@ -213,24 +224,6 @@
                 }
             }
         },
-        "GlossariesOpts": {
-            "type": "object",
-            "properties": {
-                "file": {
-                    "description": "Name of the glossary file. Conventional default is 'glossary.md'",
-                    "type": "string"
-                },
-                "termHint": {
-                    "description": "A symbol to append to a link to denote that the term refers to a glossary term.",
-                    "type": "string"
-                },
-                "sort": {
-                    "description": "If present, sort terms in output glossary. Default: None. See also i18n options.",
-                    "type": "string",
-                    "enum": ["asc", "desc"]
-                }
-            }
-        },
         "DevOpts": {
             "type": "object",
             "properties": {

doc/templates/README.md

@@ -147,47 +147,58 @@ Some syntactic positions of a term are **excluded** from being linked to the glo
 
 Having a configuration file is the recommended way of configuring [glossarify-md]. A minimal configuration may look like:
 
-*glossarify-md.conf.json* (minimal):
+### Minimal Example
+
+> **Since v5.0.0**
+
+*glossarify-md.conf.json*
 
 ```json
 {
   "$schema": "./node_modules/glossarify-md/conf.schema.json",
   "baseDir": "./src",
-  "outDir": "../target",
-  "outDirDropOld": true,
-  "glossaries": [
-     { "file": "./glossary.md" },
-  ],
-  "includeFiles": ["."],
-  "excludeFiles": ["node_modules"],
-  "linking": "relative"
+  "outDir": "../target"
 }
 ```
-**Note:** All paths (except of `$schema`) are interpreted relative to `baseDir`. `baseDir` itself is relative to the location of the config file or current working directory. More options see [Additional Features](#additional-features) or [Options](#options) below.
 
-### Overriding via Command Line
+### Initialize with Default Values
+
+> **Since v5.0.0**
+
+You can generate a config file with all options and default values by running the command:
+~~~
+npx glossarify-md --init > glossarify-md.conf.json
+~~~
+
+> **Note:** All paths (except of `$schema`) are interpreted relative to `baseDir`.
+>
+> `baseDir` itself is relative to the location of the config file or Current Working Directory (CWD). More options see [Additional Features](#additional-features) or [Options](#options) below.
+
+### Configure via Command Line
+
+> **Since v4.0.0**
 
 Use `--shallow` or `--deep`
 
 1. to provide a configuration solely via command line
-2. to merge a configuration with your config file or the implicit default config in `./node_modules/glossarify-md/conf.json.schema`
+2. to merge a configuration with a config file
 
-Use `--shallow` to *replace* simple top-level options:
+*Example: use `--shallow` to *replace* simple top-level options:*
 ~~~
 glossarify-md
   --config ./glossarify-md.conf.json
   --shallow "{ 'baseDir':'./src', 'outDir':'../target' }"
 ~~~
 
-Use `--shallow` to *replace* complex nested options like `glossaries` alltogether:
+*Example: use `--shallow` to *replace* complex nested options like `glossaries` alltogether:*
 
 ~~~
 glossarify-md
   --config ./glossarify-md.conf.json
   --shallow "{ 'glossaries': [{'file':'./replace.md'}] }"
 ~~~
 
-Use `--deep` to *extend* complex nested options, e.g. to *add* another array item to `glossaries` in the config file write:
+*Example: use `--deep` to *extend* complex nested options, e.g. to *add* another array item to `glossaries` in the config file write:*
 
 ~~~
 glossarify-md
@@ -546,34 +557,33 @@ Enable support for markdown footnote syntax as defined at <https://pandoc.org/MA
 - **Range:** `{file: string, [title: string]}`
 - **Since:** v3.0.0
 
-If available, generates an index of glossary terms with links to files in which they have been mentioned. See section [Additional Features](https://github.com/about-code/glossarify-md#index-of-terms-and-where-they-have-been-used) for a configuration example.
+Generates an index of glossary terms with links to files in which they have been mentioned. See section [Additional Features](https://github.com/about-code/glossarify-md#index-of-terms-and-where-they-have-been-used) for a configuration example.
+
+#### `generateFiles.listOf`
+
+- **Range:** `Array<{class: string, file: string, [title: string]}>`
+- **Since:** v3.5.0
 
-> **Important:** The `string` value range is *deprecated*. It will be kept throughout all versions of v3.x but is eventually going to be removed. Please use the object value range as shown in the example.
+If available, generates a list from HTML anchors exposing the configured `class` attribute. See section [Additional Features](https://github.com/about-code/glossarify-md#lists) for an example.
 
 #### `generateFiles.listOfFigures`
 
 - **Range:** `{file: string, [title: string, class: string]}`
 - **Since:** v3.3.0
 
-If available, generates a list of figures with links to sections where the figures have been mentioned. See section [Additional Features](https://github.com/about-code/glossarify-md#list-of-figures) for a configuration example.
+Generates a list of figures with links to sections where the figures have been mentioned. See section [Additional Features](https://github.com/about-code/glossarify-md#list-of-figures) for a configuration example.
 
 #### `generateFiles.listOfTables`
 
 - **Range:** `{file: string, [title: string, class: string]}`
 - **Since:** v3.4.0
 
-If available, generates a list of tables. See section [Additional Features](https://github.com/about-code/glossarify-md#list-of-tables) for an example.
-
-#### `generateFiles.listOf`
-
-- **Range:** `Array<{class: string, file: string, [title: string]}>`
-- **Since:** v3.5.0
-
-If available, generates a list from HTML anchors exposing the configured `class` attribute. See section [Additional Features](https://github.com/about-code/glossarify-md#lists) for an example.
+Generates a list of tables. See section [Additional Features](https://github.com/about-code/glossarify-md#list-of-tables) for an example.
 
 #### `glossaries`
 
 - **Range:** `Array<{file: string, [termHint: string], [sort: string]}>`
+- **Default:** [{ "file": "./glossary.md", "termHint": "" }]
 
 A list of glossary configuations, each with a path to the glossary file. Every
 glossary may have an optional *termHint*. A *termHint* is a symbol character

test/input/config-cli/arg-init/docs/document.md

@@ -0,0 +1,22 @@
+# Test Case
+
+GIVEN
+
+- a directory `docs`
+- a markdown file `./docs/document.md`
+- a markdown file `./docs/glossary.md`
+- a glossary term INIT
+- a command line (multiple lines for readability only)
+
+    ~~~
+    npx glossarify-md --init > glossarify-md.conf.json
+    && npx glossarify-md --config ./glossarify-md.conf.json`
+    ~~~
+
+THEN
+
+- the files MUST be processable without errors
+
+AND
+
+- the term should be replaced with a link to its glossary definition.

test/input/config-cli/arg-init/docs/glossary.md

@@ -0,0 +1,5 @@
+# Glossary
+
+## INIT
+
+Initialize a configuration via `npx glossarify-md --init`.

test/output-expected/config-cli/arg-init/document.md

@@ -0,0 +1,22 @@
+# [Test Case](#test-case)
+
+GIVEN
+
+-   a directory `docs`
+-   a markdown file `./docs/document.md`
+-   a markdown file `./docs/glossary.md`
+-   a glossary term [INIT][1]
+-   a command line (multiple lines for readability only)
+
+        npx glossarify-md --init > glossarify-md.conf.json
+        && npx glossarify-md --config ./glossarify-md.conf.json`
+
+THEN
+
+-   the files MUST be processable without errors
+
+AND
+
+-   the term should be replaced with a link to its glossary definition.
+
+[1]: ./glossary.md#init "Initialize a configuration via npx glossarify-md --init."

test/output-expected/config-cli/arg-init/glossary.md

@@ -0,0 +1,5 @@
+# [Glossary](#glossary)
+
+## [INIT](#init)
+
+Initialize a configuration via `npx glossarify-md --init`.

test/output-expected/config-cli/deep-defaults/glossarify-md-effective.conf.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "../../../../conf.schema.json",
   "baseDir": "{CWD}/output-actual/config-cli/deep-defaults",
   "baseUrl": "file://localhost",
   "excludeFiles": [
@@ -34,6 +35,5 @@
   "reportNotMentioned": false,
   "dev": {
     "effectiveConfFile": "./glossarify-md-effective.conf.json"
-  },
-  "$schema": "../../../../conf.schema.json"
+  }
 }