From 1a47cca54c7884b86bd57ece702da3ec71eb2657 Mon Sep 17 00:00:00 2001
From: Ismo Vuorinen <ismo.vuorinen@vincit.fi>
Date: Tue, 31 Oct 2023 11:22:11 +0200
Subject: [PATCH] chore(docs): better readme

---
 packages/config-checker/README.md             | 101 ++++++++++++++++--
 .../helpers/generate-md-table.js              |   4 +-
 packages/config-checker/package.json          |   2 +-
 3 files changed, 95 insertions(+), 12 deletions(-)

diff --git a/packages/config-checker/README.md b/packages/config-checker/README.md
index f66f77e..4f1cfb7 100644
--- a/packages/config-checker/README.md
+++ b/packages/config-checker/README.md
@@ -6,7 +6,7 @@ Check for existence of common configuration files in usually used locations.
 
 ## Installation
 
-Install `this package` as a _`dependencies`_:
+Install `this package` as a _`dependency`_:
 
 ```sh
 # npm
@@ -18,20 +18,100 @@ yarn add @ivuorinen/config-checker
 
 ## Usage
 
+This package is intended to be used in lifecycle events of other packages.
+
+Configuration packages located in this repository use this tool to check for existence of configuration files, and if they exist, they will not create new ones.
+
+### Real world example
+
+For commitlint-config you can find the usage in the [commitlint-config postinstall.js][commitlint-postinstall-link] file.
+
+Here's a snippet from the file:
+
 ```js
-const configChecker = require('@ivuorinen/config-checker')
+const process = require('process')
+const checkConfig = require('@ivuorinen/config-checker')
+const foundConfig = checkConfig('commitlint')
 
-// Check for existance of configuration files.
-// Module name for Eslint would be 'eslint' for example.
-const configFiles = configChecker('module-name')
-
-if (configFiles.length > 0) {
-  console.log('Found configuration files', configFiles)
-} else {
-  console.log('No configuration files found')
+if (foundConfig.length > 0) {
+  console.log('commitlint-config: Found existing commitlint config file, skipping creation.')
+  console.log('commitlint-config: If you want to create a new config file, please remove the existing one.')
+  console.log(`commitlint-config: Found config files at: ${foundConfig.join(', ')}`)
+  process.exit(0)
 }
 ```
 
+### Locations scanned
+
+| Searched configuration files        |
+| ----------------------------------- |
+| `[module name]`                     |
+| `[module name]`rc                   |
+| `[module name]`rc.json              |
+| `[module name]`rc.yaml              |
+| `[module name]`rc.yml               |
+| `[module name]`rc.js                |
+| `[module name]`rc.ts                |
+| `[module name]`rc.mjs               |
+| `[module name]`rc.cjs               |
+| `[module name]`.jsonc               |
+| `[module name]`.yaml                |
+| `[module name]`.json                |
+| `[module name]`.config.js           |
+| `[module name]`.config.ts           |
+| `[module name]`.config.mjs          |
+| `[module name]`.config.cjs          |
+| .`[module name]`                    |
+| .`[module name]`rc                  |
+| .`[module name]`rc.json             |
+| .`[module name]`rc.yaml             |
+| .`[module name]`rc.yml              |
+| .`[module name]`rc.js               |
+| .`[module name]`rc.ts               |
+| .`[module name]`rc.mjs              |
+| .`[module name]`rc.cjs              |
+| .`[module name]`.jsonc              |
+| .`[module name]`.yaml               |
+| .`[module name]`.json               |
+| .`[module name]`.config.js          |
+| .`[module name]`.config.ts          |
+| .`[module name]`.config.mjs         |
+| .`[module name]`.config.cjs         |
+| .config/`[module name]`             |
+| .config/`[module name]`rc           |
+| .config/`[module name]`rc.json      |
+| .config/`[module name]`rc.yaml      |
+| .config/`[module name]`rc.yml       |
+| .config/`[module name]`rc.js        |
+| .config/`[module name]`rc.ts        |
+| .config/`[module name]`rc.mjs       |
+| .config/`[module name]`rc.cjs       |
+| .config/`[module name]`.jsonc       |
+| .config/`[module name]`.yaml        |
+| .config/`[module name]`.json        |
+| .config/`[module name]`.config.js   |
+| .config/`[module name]`.config.ts   |
+| .config/`[module name]`.config.mjs  |
+| .config/`[module name]`.config.cjs  |
+| .config/.`[module name]`            |
+| .config/.`[module name]`rc          |
+| .config/.`[module name]`rc.json     |
+| .config/.`[module name]`rc.yaml     |
+| .config/.`[module name]`rc.yml      |
+| .config/.`[module name]`rc.js       |
+| .config/.`[module name]`rc.ts       |
+| .config/.`[module name]`rc.mjs      |
+| .config/.`[module name]`rc.cjs      |
+| .config/.`[module name]`.jsonc      |
+| .config/.`[module name]`.yaml       |
+| .config/.`[module name]`.json       |
+| .config/.`[module name]`.config.js  |
+| .config/.`[module name]`.config.ts  |
+| .config/.`[module name]`.config.mjs |
+| .config/.`[module name]`.config.cjs |
+
+This list has been generated using `npm run generate-table`.
+
 ## Contributing
 
 If you are interested in helping contribute, please take a look at our [contribution guidelines][contributing-link] and open an [issue][issue-link] or [pull request][pull-request-link].
@@ -54,3 +134,4 @@ This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md
 [pull-request-link]: https://github.com/ivuorinen/base-configs/pulls
 [style-badge]: https://img.shields.io/badge/code_style-ivuorinen%E2%80%99s-663399.svg?labelColor=292a44&style=flat-square
 [style-link]: https://github.com/ivuorinen/base-configs
+[commitlint-postinstall-link]: https://github.com/ivuorinen/base-configs/blob/main/packages/commitlint-config/scripts/postinstall.js
diff --git a/packages/config-checker/helpers/generate-md-table.js b/packages/config-checker/helpers/generate-md-table.js
index a912453..8f7a15f 100644
--- a/packages/config-checker/helpers/generate-md-table.js
+++ b/packages/config-checker/helpers/generate-md-table.js
@@ -2,7 +2,7 @@
 
 const configurationPaths = require('../lib/configuration-paths')
 
-const configItems = configurationPaths('[module name]')
+const configItems = configurationPaths('`[module name]`')
 const longestLine = configItems.reduce((a, b) => (a.length > b.length ? a : b)).length
 
 const mdTable = configItems.map(file => {
@@ -10,6 +10,8 @@ const mdTable = configItems.map(file => {
   return `| ${file}${' '.repeat(diff)} |`
 })
 
+console.log('# Configuration files\n')
+
 const header = 'Searched configuration files'
 console.log('| ' + header + ' '.repeat(longestLine - header.length) + ' |')
 console.log('| ' + '-'.repeat(longestLine) + ' |')
diff --git a/packages/config-checker/package.json b/packages/config-checker/package.json
index 2d20190..bc8ac87 100644
--- a/packages/config-checker/package.json
+++ b/packages/config-checker/package.json
@@ -34,7 +34,7 @@
   },
   "scripts": {
     "test": "node ./__tests__/config-checker.test.js",
-    "files": "node ./helpers/files.js"
+    "generate-table": "node ./helpers/generate-md-table.js"
   },
   "bugs": {
     "url": "https://github.com/ivuorinen/base-configs/issues"