juisy 2.0.0-beta.0

package/README.md

@@ -0,0 +1,211 @@
+<!--
+  ⚠ IMPORTANT
+  This file is generated with **@hperchec/readme-generator**. Don't edit it.
+-->
+
+# 🍊 juisy
+
+<!-- markdownlint-disable line-length -->
+
+![author](https://img.shields.io/static/v1?label=\&message=Author:\&color=black)
+[![herve-perchec](http://herve-perchec.com/badge.svg)](http://herve-perchec.com/)
+
+[![release](https://img.shields.io/gitlab/v/release/hperchec/juisy?include_prereleases\&logo=gitlab\&sort=semver)](https://gitlab.com/hperchec/juisy/-/releases)
+[![pipeline-status](https://gitlab.com/hperchec/juisy/badges/main/pipeline.svg)](https://gitlab.com/hperchec/juisy/commits/main)
+[![package](https://img.shields.io/npm/v/juisy?logo=npm)](https://www.npmjs.com/package/juisy)
+[![downloads](https://img.shields.io/npm/dw/juisy?logo=npm)](https://www.npmjs.com/package/juisy)
+[![issues](https://img.shields.io/gitlab/issues/open/hperchec/juisy?gitlab_url=https%3A%2F%2Fgitlab.com)](https://gitlab.com/hperchec/juisy/issues)
+![license](https://img.shields.io/gitlab/license/hperchec/juisy?gitlab_url=https%3A%2F%2Fgitlab.com)
+
+<!-- markdownlint-enable line-length -->
+
+## Table of contents
+
+* [What is juisy?](#what-is-juisy)
+* [🚀 Get started](#-get-started)
+* [Features](#features)
+  * [Embedded CLI](#embedded-cli)
+  * [Project-level global variables](#project-level-global-variables)
+* [🧱 Dependencies](#-dependencies)
+* [📙 Documentation](#-documentation)
+  * [API](#api)
+  * [Utils](#utils)
+* [✍ Author](#-author)
+* [📄 License](#-license)
+
+## What is juisy?
+
+* 🔧 [Embedded CLI tool](https://gitlab.com/hperchec/juisy/-/blob/main/documentation/api.md#juisycli--yargs) that uses yargs under the ground
+* 📕 Generate your project documentation and README file with [@hperchec/readme-generator](https://www.npmjs.com/package/@hperchec/readme-generator)
+* 🕵️‍♂️ Automatic linting with [lint-staged](https://www.npmjs.com/package/lint-staged) at pre-commit git hook
+* 🦾 Respect [Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) with [commitlint](https://commitlint.js.org/) at commit-msg git hook
+
+## 🚀 Get started
+
+Install package:
+
+```sh
+npm install juisy
+```
+
+Squeeze!
+
+```sh
+npx juisy squeeze
+```
+
+You will get:
+
+```sh
+./
+├─ bin/ # contains CLI
+│  └─ cli/
+│     ├─ cmds/ # commands dir
+│     ├─ lib/ # libraries used by commands
+│     └─ index.js # CLI entry file
+├─ docs/
+│  └─ readme # contains configuration for @hperchec/readme-generator
+└─ ...
+```
+
+...and some new scripts in your `package.json` file:
+
+```js
+"docs", // generate documentation
+"docs:api", // only api
+"docs:readme", // only README file
+"release", // make a release
+"changelog" // generate CHANGELOG file
+"postinstall" // for git hook
+```
+
+Just use `--help` option to show help:
+
+```sh
+node ./bin/cli --help
+```
+
+## Features
+
+### Embedded CLI
+
+PRIVATE AND PUBLIC COMMANDS
+Work in progress...
+
+### Project-level global variables
+
+> > > INSERT MERMAID CHART for file level
+> > > LEVEL 0 : package.json / env ==== hard coded
+> > > LEVEL 1 : globals.config.js
+> > > LEVEL 2 : builder / cli
+> > > LEVEL 4 : Web app ...
+
+Assuming you have a `.env` file in the root of your project:
+
+```sh
+# .env
+MY_ENV_VAR=foo
+```
+
+And the following content in your `globals.config.js` file:
+
+```js
+// globals.config.js
+import { defineGlobals } from '@hperchec/juisy'
+
+export default defineGlobals(
+  {
+    // The environment variables to auto includes in "ENV" property
+    env: { map: [ 'MY_ENV_VAR' ] }
+  },
+  // Access to all environment variables and package.json info
+  ({ env, pkg }) => {
+    return {
+      // Set any variable you want to use globally
+      MY_GLOBAL_VARIABLE: 'bar'
+    }
+  }
+)
+```
+
+Will result to:
+
+```js
+{
+  ENV: {
+    MY_ENV_VAR: 'foo'
+  },
+  PACKAGE: {
+    NAME: '@hperchec/juisy',
+    URL: 'https://www.npmjs.com/package/@hperchec/juisy'
+  },
+  VERSION: '2.0.0',
+  AUTHOR: {
+    EMAIL: 'contact@herve-perchec.com',
+    NAME: 'Hervé Perchec',
+    URL: 'https://gitlab.com/herveperchec'
+  },
+  REPOSITORY: {
+    TYPE: 'git',
+    URL: 'git+https://gitlab.com/hperchec/juisy.git'
+  },
+  ISSUES_URL: 'https://gitlab.com/hperchec/juisy/issues',
+  HOMEPAGE: 'https://gitlab.com/hperchec/juisy#readme',
+  MY_GLOBAL_VARIABLE: 'bar'
+}
+```
+
+You can also print the globals object by running the following command:
+
+```sh
+npx juisy print:globals
+```
+
+## 🧱 Dependencies
+
+It will install the following packages as peer dependencies:
+
+| name                               | version |
+| ---------------------------------- | ------- |
+| @commitlint/cli                    | ^17.7.2 |
+| @commitlint/config-conventional    | ^17.7.0 |
+| @github/markdownlint-github        | ^0.6.0  |
+| @hperchec/readme-generator         | ^3.0.0  |
+| @stylistic/eslint-plugin           | ^2      |
+| @typescript-eslint/eslint-plugin   | ^8      |
+| chalk                              | ^4.1.2  |
+| conventional-changelog-cli         | ^4.1.0  |
+| eslint                             | ^9      |
+| execa                              | ^5.1.1  |
+| lint-staged                        | ^14.0.1 |
+| markdownlint-cli2                  | ^0.12.1 |
+| markdownlint-cli2-formatter-pretty | ^0.0.6  |
+| prompts                            | ^2.4.2  |
+| simple-git-hooks                   | ^2.9.0  |
+| yargs                              | ^17.7.2 |
+
+## 📙 Documentation
+
+### API
+
+> See \[API] documentation]\(https://gitlab.com/hperchec/juisy/-/blob/main/documentation/api.md)
+
+### Utils
+
+> See [utils documentation](https://gitlab.com/hperchec/juisy/-/blob/main/documentation/utils.md)
+
+## ✍ Author
+
+[Hervé Perchec](https://gitlab.com/herveperchec)
+
+## 📄 License
+
+ISC
+
+***
+
+Made with ❤ by [Hervé Perchec](https://gitlab.com/herveperchec)
+
+***
+
+*README.md - this file was auto generated with [juisy](https://www.npmjs.com/package/juisy) README templater. Don't edit it.*

package/bin/cli/cli.js

@@ -0,0 +1,23 @@
+import { CLIFactory } from '#juisy/cli'
+
+import { commands } from './cmds/index.js'
+
+const { $style } = CLI.OutputUtils
+
+function getBanner () {
+  let str = ''
+  const title = '@hperchec/juisy'
+  const length = title.length - 9 // removes characters generated by $style.bold from length
+  str += $style.cyan('-'.repeat(length) + '\n')
+  str += $style.cyan(title + '\n')
+  str += $style.cyan('-'.repeat(length) + '\n')
+  str += $style.italic('Made with') + ' ' + $style.red('❤') + '  ' + $style.italic('by ') + $style.bold('Hervé Perchec <contact@herve-perchec.com>') + '\n'
+  return str
+}
+
+export default CLIFactory(cli => cli
+  .scriptName('juisy')
+  .usage(`${getBanner()}\nUsage: $0 <command> [<options>]`)
+  .command(commands)
+  .demandCommand(1, ('Command is missing. See help to learn more.').red)
+)

package/bin/cli/cmds/changelog.js

@@ -0,0 +1,41 @@
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'changelog',
+  describe: 'Generate CHANGELOG file',
+  builder: function (cli) {
+    return cli.option('i', {
+      alias: 'infile',
+      type: 'string',
+      describe: 'Same as conventional-changelog option',
+      default: 'CHANGELOG.md',
+      requiresArg: true
+    })
+  },
+  async handler (argv) {
+    // Utils
+    const { $style, step, substep, error } = CLI.OutputUtils
+    const { run, wait } = CLI.InterfaceUtils
+    /**
+     * Generate changelog file
+     */
+    step('Generating changelog')
+    await wait('Generating', async () => {
+      try {
+        await run(
+          'npx',
+          [
+            'conventional-changelog',
+            '-p', 'angular',
+            '-i', argv.infile,
+            '-s' // same file to output
+          ],
+          { stdio: 'pipe' }
+        )
+      } catch (e) {
+        error('Unable to generate changelog', e)
+      }
+    })
+    substep($style.green('✔ Success'), { last: true })
+    this.log() // Blank line
+  }
+})

package/bin/cli/cmds/docs/generate-api.js

@@ -0,0 +1,22 @@
+import path from 'node:path'
+import generateApiDoc from '../../lib/docs/generate-api-doc.js'
+
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'generate:api',
+  describe: 'Generate API docs from source code',
+  builder (cli) {
+    cli
+  },
+  async handler (argv) {
+    let options = {}
+    const configPath = path.resolve('./docs/api/docs.config.js')
+
+    options = require(configPath)
+
+    /**
+     * If everything is okay generate doc
+     */
+    await generateApiDoc(options)
+  }
+})

package/bin/cli/cmds/docs/generate-cli.js

@@ -0,0 +1,11 @@
+import { ReadmeTemplater } from '#juisy/templater'
+
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'generate:cli',
+  describe: 'Generate CLI docs',
+  async handler (argv) {
+    const templater = new ReadmeTemplater('./docs/cli/config.js')
+    await templater.generate()
+  }
+})

package/bin/cli/cmds/docs/generate-readme.js

@@ -0,0 +1,11 @@
+import { ReadmeTemplater } from '#juisy/templater'
+
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'generate:readme',
+  describe: 'Generate README.md',
+  async handler (argv) {
+    const templater = new ReadmeTemplater('./docs/readme/config.js')
+    await templater.generate()
+  }
+})

package/bin/cli/cmds/docs/index.js

@@ -0,0 +1,22 @@
+import generateAPI from './generate-api.js'
+import generateCLI from './generate-cli.js'
+import generateReadme from './generate-readme.js'
+
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'docs <command>',
+  describe: 'Manage project documentation',
+  meta: {
+    private: true
+  },
+  builder (cli) {
+    return cli
+      .command([
+        generateAPI,
+        generateCLI,
+        generateReadme
+      ])
+      .demandCommand(1, 'Command is missing. See help to learn more.')
+  },
+  handler (argv) {}
+})

package/bin/cli/cmds/docs/lint.js

@@ -0,0 +1,42 @@
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'lint',
+  describe: 'Lint markdown with markdownlint',
+  builder: function (cli) {
+    cli.option('c', {
+      alias: 'config',
+      type: 'string',
+      describe: 'Path to custom markdownlint config file (relative to root folder)',
+      requiresArg: true
+    })
+    cli.option('f', {
+      alias: 'fix',
+      type: 'boolean',
+      describe: 'Auto fix by passing --fix option to markdownlint-cli2',
+      default: false
+    })
+    return cli
+  },
+  async handler (argv) {
+    const { abort, run } = CLI.InterfaceUtils
+    const configPath = argv.config || './docs/.markdownlint-cli2.cjs' // default relative to root folder
+
+    /**
+     * Call markdownlint command
+     */
+    try {
+      await run(
+        'npx',
+        [
+          'markdownlint-cli2',
+          '--config',
+          configPath,
+          ...(argv.fix ? [ '--fix' ] : [])
+        ],
+        { stdio: 'inherit' }
+      )
+    } catch (error) {
+      abort(error.exitCode)
+    }
+  }
+})

package/bin/cli/cmds/eject.js

@@ -0,0 +1,28 @@
+import { eject } from '#juisy'
+
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'eject <identifier>',
+  describe: 'Eject file from juisy template to project directory',
+  builder (cli) {
+    cli.option('f', {
+      alias: 'force',
+      type: 'boolean',
+      default: false,
+      describe: 'Overwrites existing files'
+    })
+    cli.option('l', {
+      alias: 'log-level',
+      type: 'string',
+      default: 'trace',
+      describe: 'Can be one of: trace, debug, info, warn, error, silent'
+    })
+    return cli
+  },
+  async handler (argv) {
+    await eject(argv.identifier, {
+      force: argv.force,
+      logLevel: argv['log-level']
+    })
+  }
+})

package/bin/cli/cmds/git-hooks/index.js

@@ -0,0 +1,20 @@
+import reset from './reset.js'
+import sync from './sync.js'
+
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'git-hooks <command>',
+  describe: 'Git relative commands',
+  meta: {
+    private: true
+  },
+  builder: function (cli) {
+    return cli
+      .command([
+        reset,
+        sync
+      ])
+      .demandCommand(1, 'Command is missing. See help to learn more.')
+  },
+  handler: async function (argv) {}
+})

package/bin/cli/cmds/git-hooks/reset.js

@@ -0,0 +1,48 @@
+import path from 'path'
+import fs from 'fs-extra'
+
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'reset',
+  describe: 'Reset git hooks',
+  builder (cli) {
+    return cli
+  },
+  async handler (argv) {
+    // Utils
+    const { $style, step, substep } = CLI.OutputUtils
+    const { rootDir, run, abort } = CLI.InterfaceUtils
+    /**
+     * Reset git hooks
+     */
+    step('Reset git hooks')
+
+    // Create temporary empty configuration file
+    const tempConfigFilePath = './__TEMP_SIMPLE_GIT_HOOKS_CONFIG__.json' // relative to project root folder
+    fs.writeFileSync(path.resolve(rootDir, tempConfigFilePath), '{}')
+
+    // Run command with empty configuration
+    let commandError = false
+    try {
+      await run('npx', [
+        'simple-git-hooks',
+        tempConfigFilePath
+      ], { stdio: 'pipe', cwd: rootDir })
+    } catch (e) {
+      commandError = e
+    }
+
+    // Don't forget to always remove temporary file
+    fs.unlinkSync(path.resolve(rootDir, tempConfigFilePath))
+
+    // If error
+    if (commandError) {
+      substep($style.red('❌ Unable to reset git hooks.'), { last: true })
+      abort(1) // Abort with error
+    } else {
+      // Everything is okay
+      substep($style.green('✔ Git hooks successfuly reset'), { last: true })
+      this.log() // blank line
+    }
+  }
+})

package/bin/cli/cmds/git-hooks/sync.js

@@ -0,0 +1,19 @@
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'sync',
+  describe: 'Sync git hooks',
+  builder (cli) {
+    return cli
+  },
+  async handler (argv) {
+    // Utils
+    const { step} = CLI.OutputUtils
+    const { run } = CLI.InterfaceUtils
+    /**
+     * Sync git hooks
+     */
+    step('Sync git hooks')
+
+    await run('npx', [ 'simple-git-hooks' ])
+  }
+})

package/bin/cli/cmds/index.js

@@ -0,0 +1,15 @@
+import docs from './docs/index.js'
+import eject from './eject.js'
+import gitHooks from './git-hooks/index.js'
+import printGlobals from './print-globals.js'
+import squeeze from './squeeze.js'
+import test from './test.js'
+
+export const commands = [
+  docs,
+  eject,
+  gitHooks,
+  printGlobals,
+  squeeze,
+  test
+]

package/bin/cli/cmds/print-globals.js

@@ -0,0 +1,28 @@
+import { getProjectGlobals, DataExporter } from '#juisy'
+
+/** @type {import('#juisy/cli').Command} */
+export default new CLI.Command({
+  command: 'print:globals',
+  describe: 'Print the computed project globals as JSON',
+  meta: {},
+  builder (cli) {
+    cli.option('f', {
+      alias: 'format',
+      describe: 'The export format',
+      default: 'json',
+      choices: [ 'json', 'yaml' ]
+    })
+    cli.option('t', {
+      alias: 'target',
+      type: 'string',
+      describe: 'The target file exporting project globals (fallback to ./globals.config.js)'
+    })
+    return cli
+  },
+  async handler (args) {
+    // Use getProjectGlobals API
+    const projectGlobals = await getProjectGlobals(args.target)
+    // Just console.log the globals as JSON
+    this.log(new DataExporter(args.format).exportSync(projectGlobals, { space: 2 }))
+  }
+})