aberlaas 2.1.0 → 2.3.0

package/README.md

@@ -161,24 +161,6 @@ what most free CI tier offer). If you have access to higher end machines, you
 can update this value by passing the `--cpu-count=X` flag to your `aberlaas ci`
 call.
 
-### Auto-Releasing
-
-As an optional feature, you can have aberlaas automatically release a new
-version of your module from the CI environment when relevant.
-
-The CI will then check all the commits since the last release. If any commit is
-a `feat()` it will release a new minor version; it any commit is a `fix()` it
-will release a new patch version. For major release, you'll have to do it
-manually.
-
-This option is not enabled by default. If you need it, you need to follow those
-steps:
-
-- Run `aberlaas setup --auto-release`. It will setup the required `ENV` variables
-  and ssh keys
-- Update your `aberlaas ci` script to `aberlaas ci --auto-release`
-- Uncomment the `add_ssh_keys` in your `.circleci.yml` file
-
 ## File structure
 
 `./lib/configs` contain the default configuration for all the tools. They are
@@ -188,10 +170,133 @@ exported by the package and thus can be `require`d in userland.
 extends the configuration exported in the previous files. Copying files to
 userland allows user to change the files if they want to change the behavior.
 
-`.eslintrc.js`, `.stylelintrc.js` and `jest.config.js` are local
+`.eslintrc.js`, `stylelint.config.js` and `vite.config.js` are local
 configuration files for `aberlaas` itself. They eat their own dog food by
 referencing the same configs as above.
 
+## Tools used and their future
+
+### ESLint
+
+ESLint doesn't yet support ESM config files. We'll upgrade to the latest ESLint
+when it does. This should also help fix the issue with Yarn PnP (see below).
+
+### Yarn
+
+**tl;dr; We'll move to Yarn PnP once ESLint has support for Flat Configs, and
+default `yarn run` doesn't add a ~1s delay overhead**
+
+#### PnP
+
+
+Aberlaas is using Yarn Berry (v2+) as its main package management tool.
+
+Yarn Berry comes with a Plug And Play (PnP) feature that replaces the usage of
+`node_modules` in favor of a `.pnp.cjs` file. Instead of having a very large
+`node_modules` folder, a unique copy of each dependency is stored in the user
+home folder and the `.pnp.cjs` file only keeps references to those folder. This
+makes installing dependencies faster as it needs way less I/O.
+
+By ditching the whole `node_modules` principle, it also removes concepts like
+hoisting of dependencies in a monorepo. This, unfortunately, breaks ESLint.
+
+ESLint expect all its plugins to be defined as `peerDependencies` at the root of
+a mono-repo, as it will always try to include them from there. It works more or
+less correctly at the best of times, and `aberlaas` already has some hacks
+(including `resolvePluginsRelativeTo`) to work around that.
+
+But with PnP, there is no way to make it work correctly, so I will need to wait
+for a better compatibility between ESLint and Yarn 2 before using it.
+
+Sources:
+- [#8](https://github.com/yarnpkg/berry/issues/8), the initial case study of Yarn + ESLint
+- [GitHub issue that explicitly explain the problem](https://github.com/yarnpkg/berry/discussions/3909)
+- [`eslint-patch`, an ESLint plugin that hacks around this issue](https://yarnpkg.com/package?name=@rushstack/eslint-patch)
+- [The `resolvePluginsRelativeTo` bandaid from ESLint](https://eslint.org/docs/latest/use/command-line-interface#--resolve-plugins-relative-to)
+- [A nice postmortem of moving to Yarn 2](https://www.dolthub.com/blog/2022-03-18-migrating-to-yarn-2/)
+- [The Flat Config feature in ESLint that should solve the problem](https://eslint.org/docs/latest/use/configure/configuration-files-new)
+
+#### Calling binaries from the host
+
+In yarn v1, if you install `aberlaas` in your project, all of `aberlaas`
+dependencies (including binaries) were hoisted to the root. This was a design
+flaw, as if several dependencies defined binaries by the same name, they would
+fight in a race condition to take the slot in `node_modules/.bin`.
+
+This has been fixed in Yarn Berry, but it also means it's no longer possible to
+call `yarn run eslint` from a repository that includes `aberlaas`, because
+`eslint` is not a direct dependency of the repo.
+
+It might be possible to define proxy binaries inside of `aberlaas`, but those
+will incur performance issues as they will need to spawn one more yarn context
+(see below).
+
+#### Calling binaries from aberlaas
+
+In Yarn V1, I was calling binaries that `aberlaas` depends on (`eslint`, `vitest`,
+etc) by calling `yarn run`. This was adding some overhead but was acceptable.
+Yarn Berry adds even more overhead and it is becoming noticeable.
+
+Now, my prefered way it to use the NodeJS API of the dependencies instead of
+their CLI, to limit the overhead. I managed to move most tools to this new
+approach, but sometimes I still need to use the CLI (`vitest` for example has
+awesome live watching and display reloading that I don't think I can easily
+replicate through code).
+
+I ran some performance tests to see what would be the fastest way to call
+`vitest` from `aberlaas`
+
+```
+hyperfine \
+    "zsh -i -c 'yarn bin vitest && /home/tim/local/www/projects/aberlaas/node_modules/vitest/vitest.mjs --version'" \
+    "zsh -i -c 'yarn run vitest --version'" \
+    "/home/tim/local/www/projects/aberlaas/node_modules/vitest/vitest.mjs --version" \
+    "/home/tim/local/www/projects/aberlaas/node_modules/.bin/vitest --version" 
+Benchmark 1: zsh -i -c 'yarn run vitest --version'
+  Time (mean ± σ):      1.945 s ±  0.051 s    [User: 1.986 s, System: 0.850 s]
+  Range (min … max):    1.859 s …  2.018 s    10 runs
+ 
+Benchmark 2: zsh -i -c 'yarn bin vitest && /home/tim/local/www/projects/aberlaas/node_modules/vitest/vitest.mjs --version'
+  Time (mean ± σ):      2.108 s ±  0.150 s    [User: 2.108 s, System: 0.843 s]
+  Range (min … max):    1.930 s …  2.289 s    10 runs
+ 
+Benchmark 3: /home/tim/local/www/projects/aberlaas/node_modules/vitest/vitest.m
+js --version
+  Time (mean ± σ):     482.5 ms ±  40.9 ms    [User: 448.4 ms, System: 327.2 ms]
+  Range (min … max):   442.1 ms … 553.3 ms    10 runs
+ 
+Benchmark 4: /home/tim/local/www/projects/aberlaas/node_modules/.bin/vitest --version
+  Time (mean ± σ):     491.9 ms ±  29.6 ms    [User: 454.1 ms, System: 331.2 ms]
+  Range (min … max):   453.8 ms … 535.4 ms    10 runs
+```
+
+Finding the binary through `yarn bin` then calling it is the slowest, but `yarn
+run` isn't much faster. Directly calling the binary is the fastest, but it's
+path can't be easily guessed (apart from reading and parsing a `package.json`).
+But using the symlinks in `node_modules/.bin` is consistent, barely slower than
+calling the binary directly and much faster than using yarn.
+
+This is what I'll be using. Of course, this will break when I'll move to PnP as
+the `node_modules` folder won't be there, but hopefully Yarn will be faster by
+then and I can use `yarn run` reliably.
+
+#### Speed
+
+With Yarn 2+, calling `yarn run` seem to add ~1s of overhead each time. This is
+a known issue (due to the fact Yarn 2 needs to spawn yarn 1, node and a few
+other layers). 
+
+1s is not much in itself, but grows quickly when you have nested `yarn run
+aberlaas` calls that call `yarn run eslint`, and even more when you need to deal
+with monorepos and multiple packages that each have their own yarn scope.
+
+There are open issues on the topic, but nothing merged yet:
+
+- [#3732](https://github.com/yarnpkg/berry/issues/3732), where it is discussed to make yarn run aware that it's running yarn run
+  and keep the same state without spawning new yarns
+- [#2575](https://github.com/yarnpkg/berry/issues/2575), which is the main issue about Yarn performance, with benchmarks against
+  npm/npx/yarn v1.
+
 ## Where does the name Aberlaas come from?
 
 Aberlaas is the base camp from which all great expedition start in the _La Horde
@@ -205,4 +310,4 @@ For your convenience, `aberlass` and `aberlas` are added as aliases by default.
 
 ## Documentation
 
-The complete documentation can be found on https://projects.pixelastic.com/aberlaas/
+The complete documentation can be found on https://projects.pixelastic.com/aberlaas/

package/commands/ci/index.js

@@ -1,21 +1,10 @@
-import helper from '../../helper.js';
 import ciInfo from 'ci-info';
-import _ from 'golgoth/lodash.js';
-import pMap from 'golgoth/pMap.js';
-import readJson from 'firost/readJson.js';
 import run from 'firost/run.js';
+import commandTest from '../test/index.js';
+import commandLint from '../lint/index.js';
 import consoleInfo from 'firost/consoleInfo.js';
-import autoRelease from './autoRelease.js';
 
 export default {
-  /**
-   * Return the value of an environment variable
-   * @param {string} key Name of the variable
-   * @returns {*} Key value
-   **/
-  getEnv(key) {
-    return _.get(process, `env.${key}`);
-  },
   /**
    * Checks if currently running on a CI server
    * @returns {boolean} True if on a CI server
@@ -23,111 +12,37 @@ export default {
   isCI() {
     return ciInfo.isCI;
   },
-  /**
-   * Checks if currently running on CircleCI
-   * @returns {boolean} True if on CircleCI
-   **/
-  isCircleCI() {
-    return ciInfo.CIRCLE;
-  },
-  /**
-   * Checks if currently on a PR
-   * @returns {boolean} True if on a PR
-   **/
-  isPR() {
-    return ciInfo.isPR;
-  },
-  /**
-   * Return the name of the originating branch of the PR
-   * @returns {string} Name of the PR branch
-   **/
-  prBranch() {
-    if (!this.isPR()) {
-      return false;
-    }
-    if (this.isCircleCI()) {
-      return this.getEnv('CIRCLE_BRANCH');
-    }
-    return false;
-  },
-  /**
-   * Returns the list of scripts defined in the package.json
-   * @returns {Array} List of scripts defined
-   **/
-  async availableScripts() {
-    // Get scripts in package.json
-    const currentPackage = await readJson(helper.hostPath('package.json'));
-    return _.chain(currentPackage).get('scripts').keys().value();
-  },
-  /**
-   * Returns a list of available scripts to run
-   * @returns {Array} List of scripts to run
-   **/
-  async scriptsToRun() {
-    const availableScripts = await this.availableScripts();
-
-    // Get potential scripts to run
-    const potentialScripts = ['test', 'lint', 'build:prod'];
-
-    return _.intersection(potentialScripts, availableScripts);
-  },
-  /**
-   * Display the current node and yarn versions
-   **/
-  async displayVersion() {
-    const { stdout: nodeVersion } = await this.__run('node --version', {
-      stdout: false,
-    });
-    const { stdout: yarnVersion } = await this.__run('yarn --version', {
-      stdout: false,
-    });
-    this.__consoleInfo(`node ${nodeVersion}, yarn v${yarnVersion}`);
-  },
   /**
    * Run CI scripts and fail the job if any fails
+   * Runs lint and test by default, but can be changed with --no-test and
+   * --no-lint
    * @param {object} cliArgs CLI Argument object, as created by minimist
    * @returns {boolean} True on success, throws on error
    **/
   async run(cliArgs = {}) {
     const args = {
-      'auto-release': false,
-      'cpu-count': 2,
+      test: true,
+      lint: true,
       ...cliArgs,
     };
 
     if (!this.isCI()) {
+      this.__consoleInfo('Current system is not a CI, skipping');
       return true;
     }
 
-    await this.displayVersion();
-
-    const scripts = await this.scriptsToRun();
-    await pMap(
-      scripts,
-      async (scriptName) => {
-        let command = scriptName;
-        if (command === 'test') {
-          command = `test --maxWorkers=${args['cpu-count']}`;
-        }
-
-        await helper.yarnRun(command);
-      },
-      { concurrency: 1 },
-    );
+    if (args.test) {
+      await this.__runTest();
+    }
 
-    // Attempt to release the package if --auto-release is set
-    if (args['auto-release']) {
-      await this.autoRelease();
+    if (args.lint) {
+      await this.__runLint();
     }
 
     return true;
   },
-  /**
-   * Attempt to perform an auto-release
-   **/
-  async autoRelease() {
-    await autoRelease.run();
-  },
+  __runTest: commandTest.run.bind(commandTest),
+  __runLint: commandLint.run.bind(commandLint),
   __run: run,
   __consoleInfo: consoleInfo,
 };

package/commands/compress/dummy.js

@@ -0,0 +1,11 @@
+/**
+ * This is a temporary, dummy file to be able to test the top-level
+ * compress.run() function. I assume I'll add more compression types in addition
+ * to png, so this dummy compress is just to test that all compress are
+ * correctly called, but it doesn't do anything
+ **/
+export default {
+  async run() {
+    return true;
+  },
+};

package/commands/compress/index.js

@@ -2,11 +2,13 @@ import _ from 'golgoth/lodash.js';
 import pMap from 'golgoth/pMap.js';
 import consoleError from 'firost/consoleError.js';
 import firostError from 'firost/error.js';
-import helper from '../../helper.js';
+import compressPng from './png.js';
+import compressDummy from './dummy.js';
 
 export default {
   types: {
-    png: './png.js',
+    png: compressPng,
+    dummy: compressDummy,
   },
   /**
    * Wrapper to compress all supported formats
@@ -22,7 +24,7 @@ export default {
     await pMap(typesToCompress, async (type) => {
       try {
         const userPatterns = _.get(cliArgs, '_');
-        const compresser = require(this.types[type]);
+        const compresser = this.types[type];
 
         await compresser.run(userPatterns);
       } catch (error) {
@@ -37,16 +39,5 @@ export default {
 
     return true;
   },
-  /**
-   * Find all relevant files of the specified extension in the host
-   * Note: Should be used by child classes
-   * @param {Array} safeListExtension List of allowed extensions to keep
-   * @param {Array} userPatterns Patterns to narrow the search down
-   * @returns {Array} Array of files
-   **/
-  async getInputFiles(safeListExtension, userPatterns = []) {
-    const inputPatterns = _.isEmpty(userPatterns) ? '.' : userPatterns;
-    return await helper.findHostFiles(inputPatterns, safeListExtension);
-  },
   __consoleError: consoleError,
 };

package/commands/compress/png.js

@@ -1,4 +1,5 @@
-import lint from './index.js';
+import helper from '../../helper.js';
+import _ from 'golgoth/lodash.js';
 import run from 'firost/run.js';
 import which from 'firost/which.js';
 import firostError from 'firost/error.js';
@@ -10,15 +11,19 @@ export default {
    * @returns {Array} Array of files
    **/
   async getInputFiles(userPatterns) {
-    return await lint.getInputFiles(['.png'], userPatterns);
+    const filePatterns = _.isEmpty(userPatterns)
+      ? ['./**/*.png']
+      : userPatterns;
+    return await helper.findHostFiles(filePatterns, ['.png']);
   },
+
   /**
-   * Check if the binary is available in the $PATH
-   * @returns {boolean} True if available, false otherwise
+   
+   * Returns path to the binary to execute
+   * @returns {string|boolean} Path to the binary, or false if not found
    **/
-  async hasBin() {
-    const binary = await which('pngmin');
-    return !!binary;
+  async getBinaryPath() {
+    return await this.__which('pngmin');
   },
   /**
    * Compress files
@@ -27,16 +32,20 @@ export default {
    **/
   async run(userPatterns) {
     // Stop early if no bin
-    if (!(await this.hasBin())) {
+    const binaryPath = await this.getBinaryPath();
+    if (!binaryPath) {
       return true;
     }
 
     try {
       const files = await this.getInputFiles(userPatterns);
-      const command = `pngmin ${files.join(' ')}`;
+      const command = `${binaryPath} ${files.join(' ')}`;
       await run(command, { stdout: false });
     } catch (error) {
       throw firostError('PngCompressError', error.message);
     }
+
+    return true;
   },
+  __which: which,
 };

package/commands/init/index.js

@@ -45,21 +45,34 @@ export default {
    * default rules and overwrite them as they see fit
    **/
   async addConfigFiles() {
+    // Git
+    await this.copyToHost('./templates/_gitignore', './.gitignore');
+    await this.copyToHost('./templates/_gitattributes', './.gitattributes');
+
+    // Yarn
+    await this.copyToHost('templates/_yarnrc.yml', '.yarnrc.yml');
+
     // ESLint
     await this.copyToHost('templates/_eslintrc.cjs', '.eslintrc.cjs');
     await this.copyToHost('templates/_eslintignore.conf', '.eslintignore');
 
     // Lint-staged
-    await this.copyToHost('templates/_lintstagedrc.cjs', '.lintstagedrc.cjs');
+    await this.copyToHost(
+      'templates/lintstaged.config.js',
+      'lintstaged.config.js',
+    );
 
     // Vite
     await this.copyToHost('templates/vite.config.js', 'vite.config.js');
 
     // Prettier
-    await this.copyToHost('templates/_prettierrc.cjs', '.prettierrc.cjs');
+    await this.copyToHost('templates/prettier.config.js', 'prettier.config.js');
 
     // Stylelint
-    await this.copyToHost('templates/_stylelintrc.cjs', '.stylelintrc.cjs');
+    await this.copyToHost(
+      'templates/stylelint.config.js',
+      'stylelint.config.js',
+    );
 
     // Renovate
     await this.copyToHost(
@@ -106,6 +119,7 @@ export default {
   async addScripts() {
     const defaultScripts = [
       { key: 'ci', value: 'scripts/ci' },
+      { key: 'compress', value: 'scripts/compress' },
       { key: 'lint', value: 'scripts/lint' },
       { key: 'lint:fix', value: 'scripts/lint-fix' },
       { key: 'release', value: 'scripts/release' },
@@ -248,7 +262,9 @@ export default {
     await write(nodeConfig.nodeVersion, nvmrcPath);
 
     // Download latest yarn version
-    await this.__run('yarn set version', { stdout: false });
+    await this.__run(`yarn set version ${nodeConfig.yarnVersion}`, {
+      stdout: false,
+    });
   },
   /**
    * Configure git hooks to use scripts/hooks instead of .git/hooks
@@ -270,6 +286,9 @@ export default {
   async run() {
     const progress = spinner();
 
+    progress.tick('Configuring Git');
+    await this.configureGit();
+
     progress.tick('Pinning node and yarn versions');
     await this.pinNodeAndYarn();
     await this.addEngineNodeVersion();
@@ -280,9 +299,6 @@ export default {
     progress.tick('Adding yarn scripts');
     await this.addScripts();
 
-    progress.tick('Configuring git hooks');
-    await this.configureGitHooks();
-
     progress.tick('Updating LICENSE');
     await this.addLicenseFile();
     await this.addLicenseField();

package/commands/lint/css.js

@@ -1,8 +1,8 @@
 import helper from '../../helper.js';
 import { fix as prettierFix } from './helpers/prettier.js';
+import stylelint from 'stylelint';
 import _ from 'golgoth/lodash.js';
 import firostError from 'firost/error.js';
-import run from 'firost/run.js';
 
 export default {
   /**
@@ -11,37 +11,45 @@ export default {
    * @returns {Array} Array of files
    **/
   async getInputFiles(userPatterns) {
-    return await helper.findHostFiles(userPatterns, ['.css']);
+    const filePatterns = _.isEmpty(userPatterns)
+      ? ['./**/*.css']
+      : userPatterns;
+    return await helper.findHostFiles(filePatterns, ['.css']);
   },
   /**
    * Lint all files and display results.
    * @param {Array} userPatterns Patterns to narrow the search down
    * @param {string} userConfigFile Custom config file to use
+   * @param {object} userOptions Options to pass to ESLint, including fix
    * @returns {boolean} True on success
    **/
-  async run(userPatterns, userConfigFile) {
+  async run(userPatterns, userConfigFile, userOptions = {}) {
+    // Options
+    const options = { fix: false, ...userOptions };
+
+    // Files
     const files = await this.getInputFiles(userPatterns);
     if (_.isEmpty(files)) {
       return true;
     }
 
+    // Config
     const configFile = await helper.configFile(
       userConfigFile,
-      '.stylelintrc.cjs',
-      'configs/stylelint.cjs',
+      'stylelint.config.js',
+      'configs/stylelint.js',
     );
-    const binary = await helper.which('stylelint');
-    const options = [...files, '--color', '--config', configFile];
-    try {
-      await run(`${binary} ${options.join(' ')}`, { stdout: false });
-    } catch (error) {
-      // If it fails because no files passed actually exists, it's not really
-      // a failure
-      const errorMessage = error.stdout;
-      if (_.startsWith(errorMessage, 'Error: No files matching the pattern')) {
-        return true;
-      }
-      throw firostError('ERROR_CSS_LINT', error.stdout);
+    const config = await helper.import(configFile);
+
+    const result = await stylelint.lint({
+      config,
+      files,
+      formatter: 'string',
+      ...options,
+    });
+
+    if (result.errored) {
+      throw firostError('ERROR_CSS_LINT', result.output);
     }
     return true;
   },
@@ -57,11 +65,9 @@ export default {
       return true;
     }
     // Try to pretiffy as much as we can
-    await this.__prettierFix(files);
+    await prettierFix(files);
     // Still run a lint on it so it can fail if not everything is fixed
-    await this.run(userPatterns, userConfigFile);
+    await this.run(userPatterns, userConfigFile, { fix: true });
     return true;
   },
-  __prettierFix: prettierFix,
-  __run: run,
 };

package/commands/lint/helpers/prettier.js

@@ -1,25 +1,53 @@
+import * as prettier from 'prettier';
 import helper from '../../../helper.js';
-import run from 'firost/run.js';
 import firostError from 'firost/error.js';
+import write from 'firost/write.js';
+import read from 'firost/read.js';
+import pMap from 'golgoth/pMap.js';
+import _ from 'golgoth/lodash.js';
 
 /**
  * Fix all files using prettier
- * Note: Will be called by child classes
- * Note: Prettier does not output any information as to why it failed, so
- * we'll manually run the command on each file individually so we can catch
- * the file that errors and display it
  * @param {Array} inputFiles Files to auto-fix
  **/
 export async function fix(inputFiles) {
-  const binary = await helper.which('prettier');
-  const options = ['--write', ...inputFiles];
-  try {
-    const command = `${binary} ${options.join(' ')}`;
-    await run(command, { stdout: false });
-  } catch (err) {
+  // Config file
+  const configFile = await helper.configFile(
+    null,
+    'prettier.config.js',
+    'configs/prettier.js',
+  );
+  const config = await prettier.resolveConfig(configFile);
+
+  const errors = [];
+
+  // Read all files, run them through the formatter and save them back to disk
+  // If any emits error, store the errors and display them all in one output
+  await pMap(
+    inputFiles,
+    async (filepath) => {
+      try {
+        const content = await read(filepath);
+        const options = { ...config, filepath };
+        const result = await prettier.format(content, options);
+        await write(result, filepath);
+      } catch (error) {
+        const message = error.toString();
+        errors.push({ filepath, message });
+      }
+    },
+    { concurrency: 10 },
+  );
+
+  if (!_.isEmpty(errors)) {
+    let formattedErrors = '';
+    _.each(errors, (error) => {
+      formattedErrors = `${formattedErrors}${error.filepath}\n\n${error.message}\n\n`;
+    });
+
     throw firostError(
       'LINT_ERROR_FIX_PRETTIER',
-      'Some files could not be automatically fixed.\nPlease run `yarn run lint` to further debug',
+      `Some files could not be automatically fixed:\n\n${formattedErrors}`,
     );
   }
 }

package/commands/lint/index.js

@@ -21,7 +21,7 @@ export default {
    * @param {object} cliArgs CLI Argument object, as created by minimist
    * @returns {boolean} True on success
    **/
-  async run(cliArgs) {
+  async run(cliArgs = {}) {
     const allTypesKeys = _.keys(this.linters);
     const userTypes = _.intersection(_.keys(cliArgs), allTypesKeys);
     const typesToLint = _.isEmpty(userTypes) ? allTypesKeys : userTypes;