[BREAKING] Changed the default behaviour to update the file

Upgraded to TS 5
Updated dependencies
Updated tests to match new default behaviour
Code cleanups

Author: Alessio Michelini

README.md

@@ -17,11 +17,14 @@ $ npm install -g md-index-generator
 $ md-index-generator COMMAND
 running command...
 $ md-index-generator (-v|--version|version)
-md-index-generator/0.10.0 darwin-x64 node-v14.15.3
+1.0.0
 
-// Display the output on the shell
+// Replace the passed markdown file
 $ md-index-generator <MarkDown.md>
 
+// Display the output on the shell
+$ md-index-generator <MarkDown.md> --dry-run
+
 // Store the output in a file
 $ md-index-generator <MARKDOWNFILE.md> --output <Index.md>
 
@@ -30,11 +33,12 @@ $ md-index-generator <MarkDown.md> --depth 3
 
 // Set the title of the index, output will start with "## Docs index"
 $ md-index-generator <MarkDown.md> --title "Docs index"
-
-// Replace the passed markdown file
-$ md-index-generator <MarkDown.md> --replace
 ```
 
+## Breaking Changes
+
+From version `1.x` onward, the logic of the CLI has changed, where by default it replace the index of the source file, while before you had to explicitly use the `--replace` flag to do so. If you want to see the index generated on screen, you must pass the `--dry-run` flag instead.
+
 ### Optional flags
 
 `-o, --output <VALUE>` This takes an output file, where the parsed index will be stored instead of being shown in the shell
@@ -43,7 +47,7 @@ $ md-index-generator <MarkDown.md> --replace
 
 `-t, --title <VALUE>` This set the title for the index list, by default is set to `Index`
 
-`-r, --replace` This flag will set to add the index in the source file
+`-r, --dry-run` This flag will show the output on screen, but it will not update the source file
 
 #### Add the index in the source file
 
@@ -62,4 +66,4 @@ The index will go here!
 Hello
 ```
 
-> If you don't add the index tags, the script will automatically put the index before the first Heading 2 in the document. It is recommended to add the tags to properly control where the index will be added.
+> If you don't add the index tags, the script will automatically put the index before the first Heading 2 in the document. It is recommended to add the tags to properly control where the index will be added.

bin/run

@@ -10,7 +10,7 @@ program
   .option('-o, --output <outputFile>', 'Output will be saved in the defined file')
   .option('-d, --depth <depth>', 'Depth of the headings to parse, 4 means \'till h4\'', 4)
   .option('-t, --title <title>', 'Title to add on top of the index, by default is \'## Index\'')
-  .option('-r, --replace', 'Add the index to the source file', false)
+  .option('-r, --dry-run', 'Show the result on screen, but doesn\'t modify the file', false)
   .action(MarkdownIndexGenerator);
 
 program.parse();

src/constants.ts

@@ -3,6 +3,6 @@ import { Flags } from './interfaces/types';
 export const INDEX_TAG = 'index';
 export const VALID_FORMATS = ['md', 'mdx'];
 export const DEFAULT_VALUES: Flags = {
-  replace: false,
+  dryRun: false,
   depth: 4,
 }

src/index.ts

@@ -26,13 +26,20 @@ const MarkdownIndexGenerator = async(file: string, flags?: Flags) => {
   if (flags?.output) {
     await parser.toFile(flags.output);
     console.log(`File ${flags.output} saved!`);
-  } else if (flags?.replace) {
+    return process.exit(0);
+  }
+
+  if (!flags?.dryRun) {
     await parser.replaceOriginal();
     console.log(`File ${file} updated!`);
-  } else {
+    return process.exit(0);
+  }
+
+  if (flags?.dryRun) {
     console.log('--- Begin MarkDown ---');
     console.log(parser.toView());
     console.log('--- End Markdown ---');
+    return process.exit(0);
   }
 }
 

src/interfaces/types.ts

@@ -1,8 +1,8 @@
 export type HeadingsRange = 2|3|4|5;
 
 export interface Flags {
-  depth: number;
-  replace: boolean;
+  depth?: number;
+  dryRun?: boolean;
   title?: string;
   output?: string;
 }

test/index.test.ts

@@ -10,7 +10,7 @@ describe('MarkdownIndexGenerator', () => {
   });
 
   it('should show the generated menu', async () => {
-    await MarkdownIndexGenerator('./test/__mocks__/test.md');
+    await MarkdownIndexGenerator('./test/__mocks__/test.md', { dryRun: true });
     expect(console.log).toHaveBeenCalledWith('--- Begin MarkDown ---');
     expect(console.log).toHaveBeenCalledWith(expect.stringContaining('Index'));
     expect(console.log).toHaveBeenCalledWith(expect.stringContaining('[Heading 2](#heading-2)'));
@@ -19,15 +19,15 @@ describe('MarkdownIndexGenerator', () => {
   });
 
   it('should show the generated menu, but only at depth 2', async () => {
-    await MarkdownIndexGenerator('./test/__mocks__/test.md', { depth: 2, replace: false});
+    await MarkdownIndexGenerator('./test/__mocks__/test.md', { depth: 2, dryRun: true});
     expect(console.log).toHaveBeenCalledWith('--- Begin MarkDown ---');
     expect(console.log).toHaveBeenCalledWith(expect.stringContaining('[Heading 2](#heading-2)'));
     expect(console.log).toHaveBeenCalledWith(expect.not.stringContaining('- [Sub sub heading 4](#sub-sub-heading-4)'));
     expect(console.log).toHaveBeenCalledWith('--- End Markdown ---');
   });
 
   it('should show the generated menu, and contain a custom title', async () => {
-    await MarkdownIndexGenerator('./test/__mocks__/test.md', { title: 'test', depth: 2, replace: false });
+    await MarkdownIndexGenerator('./test/__mocks__/test.md', { title: 'test', depth: 2, dryRun: true });
     expect(console.log).toHaveBeenCalledWith('--- Begin MarkDown ---');
     expect(console.log).toHaveBeenCalledWith(expect.not.stringContaining('Index'));
     expect(console.log).toHaveBeenCalledWith(expect.stringContaining('[Heading 2](#heading-2)'));