Betterer

Incremental Improvement

September 2021

September 2021

Hi, I'm Craig!

September 2021

Legacy

September 2021

Local Maxima

Desired state

Current state

September 2021

September 2021

Why don't we rewrite the whole thing?!

Revolution!

September 2021

Revolution...

September 2021

Branching!

September 2021

Branching...

September 2021

// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// eslint-disable-next-line @typescript-eslint/no-explicit-any

Automation

September 2021

Humans

Not obsolete yet!

September 2021

Buttons

September 2021

<button 
  class="button button--green">
  Continue
</button>
<button 
  class="button button--red">
  Cancel
</button>
<button 
  class="button button--success">
  Continue
</button>
<button 
  class="button button--danger">
  Cancel
</button>

September 2021

Inspiration

Evolutionary Architecture

September 2021

Evolutionary Algorithms

September 2021

A genetic representation of the solution domain:

0 0 0 0 0 0 0 0
1 1 1 1 1 1 1 1
1 0 1 0 1 0 1 0
0 1 1 0 0 0 0 1

0

Chromosome

Population

Gene

Genetic Algorithms

September 2021

A genetic representation of the solution domain:

A fitness function to evaluate the solution:

0 0 0 0 0 0 0 0
1 1 1 1 1 1 1 1
1 0 1 0 1 0 1 0
0 1 1 0 0 0 0 1
f(chromosome) => score

Genetic Algorithms

September 2021

Termination

0 0 0 0 0 0 0 0
1 1 1 1 1 1 1 1
1 0 1 0 1 0 1 0
0 1 1 0 0 0 0 1
1 0 1 0 1 0 1 0
0 1 1 0 0 0 0 1

Crossover

1 1 1 1 0 0 0 0
0 0 0 0 1 1 1 1

Offspring

0 0 0 0 1 1 1 0

Mutation

Genetic Algorithms

September 2021

Tetris

September 2021

September 2021

Evolutionary Migration?

A fitness function to evaluate the solution:

f(codebase) => score

September 2021

Code as data

import { BettererOptionsStart } from './config';
import { createGlobals } from './globals';
import { BettererRunner, BettererRunnerΩ } from './runner';
import { BettererSuiteSummary } from './suite';

// Run betterer in single-run mode:
export async function betterer(
  options: BettererOptionsStart = {}
): Promise<BettererSuiteSummary> {
  initDebug();
  const globals = await createGlobals(options);
  const runner = new BettererRunnerΩ(globals);
  return runner.run(globals.config.filePaths);
}

September 2021

Code as data

September 2021

ts(codebase) => nCompilerErrors
eslint(codebase) => nLintErrors
axe(codebase) => nA11yErrors
jest(codebase) => coverage%
f(oldScore, newScore) => better | worse | same

A comparison function to track progress:

Better?

f(codebase) => oldScore
f(codebase) => newScore

Old state of the codebase

New state of the codebase

September 2021

Codebase as database?

It has become common to store extra information about a codebase in the repository:

# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
# yarn lockfile v1

"@babel/code-frame@7.12.11":
  version "7.12.11"
  resolved "https://registry.npmjs.org/@babel/code-frame/-/code-...
  integrity sha512-Zt1yodBx1UcyiePMSkWnU4hPqhwq7hGi2nFL1LeA3EUl+...
  dependencies:
    "@babel/highlight" "^7.10.4"
// Jest Snapshot v1, https://goo.gl/fbAQLP
 
exports[`betterer should not stay worse if an update is forced 1`] = `
"// BETTERER RESULTS V2.
exports[\`tsquery no raw console.log\`] = { 
  ...
}
`

September 2021

Evolutionary Migration

A fitness function to evaluate the solution

A comparison function to track progress

A little file to store the results

September 2021

Betterer

Incremental Improvement

September 2021

September 2021

// package.json
{
  "name": "@craig/my-very-stable-package",
  "version": "20.2.1",
  "author": "Craig Spence <craigspence0@gmail.com>",
  "description": "Gee I wish this package was a little bit better.",
  "scripts": {
    "betterer": "betterer",
    // ...
  },
  // ...
  "devDependencies": {
    "@betterer/cli": "^5.0.0",
    // ...
  }
}

Initialising

September 2021

// .betterer.ts
export default {
  // Add tests here ☀️
};

Initialising

// .betterer.js
module.exports = {
  // Add tests here ☀️
}

TypeScript by default:

JavaScript if you're into that:

September 2021

September 2021

My First Test

// .betterer.ts
import { BettererTest } from '@betterer/betterer';


export default {
  'migrate JS to TS': () => new BettererTest({
    // ...
  })
};

September 2021

My First Test

// .betterer.ts
import { BettererTest } from '@betterer/betterer';
import glob from 'glob';

export default {
  'migrate JS to TS': () => new BettererTest({
    test: () => glob.sync('**/*.js').length,
    // ...
  })
};

September 2021

My First Test

// .betterer.ts
import { BettererTest } from '@betterer/betterer';
import { BettererConstraintResult } from '@betterer/constraints';
import glob from 'glob';

export default {
  'migrate JS to TS': () => new BettererTest({
    test: () => glob.sync('**/*.js').length,
    constraint: (result: number, expected: number) => {
      if (result < expected) {
        return BettererConstraintResult.better;
      }
      if (result === expected) {
        return BettererConstraintResult.same;
      }
      return BettererConstraintResult.worse;
    }
  })
};

September 2021

My First Test

// .betterer.ts
import { BettererTest } from '@betterer/betterer';
import { smaller } from '@betterer/constraints';
import glob from 'glob';

export default {
  'migrate JS to TS': () => new BettererTest({
    test: () => glob.sync('**/*.js').length,
    constraint: smaller
  })
};

September 2021

September 2021

My First Result

// .betterer.results
// // BETTERER RESULTS V2.
exports[`migrate JS to TS`] = {
  value: `9`
};

This is basically the same things as a Jest snapshot file!

September 2021

September 2021

Workflows

Add to CI pipeline

Add to pre-commit hooks for changed files

Take their changes when merging

September 2021

betterer precommit $1 $2 ...
betterer ci
betterer merge
// cool.js
export function ohBoyILoveJavaScript () {
  console.log(`I'll never change!!!`);
  return [1, 2, 3] + [4, 5, 6];
}

September 2021

September 2021

My First  File Test

// .betterer.ts
import { BettererTest } from '@betterer/betterer';
import { smaller } from '@betterer/constraints';
import glob from 'glob';

export default {
  'migrate JS to TS': () => new BettererTest({
    test: () => glob.sync('**/*.js').length,
    constraint: smaller
  })
};

September 2021

My First  File Test

// .betterer.ts
import { BettererFileTest } from '@betterer/betterer';

export default {
  'migrate JS to TS': () =>
    new BettererFileTest(async (filePaths, fileTestResult) => {
      // ...
      // 
    }).include('**/*.js')
};

September 2021

My First  File Test

// .betterer.ts
import { BettererFileTest } from '@betterer/betterer';
import { promises as fs } from 'fs';

export default {
  'migrate JS to TS': () =>
    new BettererFileTest(async (filePaths, fileTestResult) => {
      await Promise.all(
        filePaths.map(async (filePath) => {
          const fileContents = await fs.readFile(filePath, 'utf8');
          const file = fileTestResult.addFile(filePath, fileContents);
          file.addIssue(0, 1, 'Please use TypeScript!');
        })
      );
    }).include('**/**/*.js')
};

September 2021

September 2021

September 2021

// BETTERER RESULTS V2.
exports[`migrate JS to TS`] = {
  value: `{
    "index.js:2978447364": [
      [0, 0, 1, "Please use TypeScript!", "177600"]
    ],
    "cool.js:3542870298": [
      [0, 0, 1, "Please use TypeScript!", "287364"]
    ],
    "amazing.js:8762519887": [
      [0, 0, 1, "Please use TypeScript!", "726351"]
    ],
    //...
    // 9 total issues:
  }`
};

September 2021

September 2021

// BETTERER RESULTS V2.
exports[`migrate JS to TS`] = {
  value: `{
    "index.js:2978447364": [
      [0, 0, 1, "Please use TypeScript!", "177600"]
    ],
    "cool.js:3542870298": [
      [0, 0, 1, "Please use TypeScript!", "287364"]
    ],
    "amazing.js:8762519887": [
      [0, 0, 1, "Please use TypeScript!", "726351"]
    ],
    //...
    // 10 total issues:
  }`
};

September 2021

September 2021

// .betterer.ts
import { BettererFileTest } from '@betterer/betterer';
import { promises as fs } from 'fs';

export default {
  'migrate JS to TS': () =>
    new BettererFileTest(async (filePaths, fileTestResult) => {
      await Promise.all(
        filePaths.map(async (filePath) => {
          const fileContents = await fs.readFile(filePath, 'utf8');
          const file = fileTestResult.addFile(filePath, fileContents);
          file.addIssue(0, 1, 'Please use TypeScript!');
        })
      );
    })
    .include('**/**/*.js')
    .deadline('2021/12/31')
};

My First  Deadline

September 2021

September 2021

// BETTERER RESULTS V2.
exports[`migrate JS to TS`] = {
  value: `{
    "index.js:2978447364": [
      [0, 0, 1, "Please use TypeScript!", "177600"]
    ],
    "boo.js:1827649983": [
      [0, 0, 1, "Please use TypeScript!", "298736"]
    ],
    "gross.js:1872646688": [
      [0, 0, 1, "Please use TypeScript!", "009726"]
    ],
    //...
    // 8 total issues:
  }`
};

September 2021

More tests!

September 2021

September 2021

// axe.ts
export function axe () {
  
}

Axe Test

September 2021

// axe.ts
import { BettererTest } from "@betterer/betterer";

export function axe () {
  return new BettererTest({
    // ...
  });
}

Axe Test

September 2021

// axe.ts
import { BettererTest } from "@betterer/betterer";
import { AxePuppeteer } from "axe-puppeteer";
import puppeteer from "puppeteer";

export function axe (uri: string) {
  return new BettererTest({
    async test() {
      // ...
    },
  });  
}

Axe Test

September 2021

// axe.ts
import { BettererTest } from "@betterer/betterer";
import { AxePuppeteer } from "axe-puppeteer";
import puppeteer from "puppeteer";

export function axe (uri: string) {
  return new BettererTest({
    async test() {
      const browser = await puppeteer.launch();
      const [page] = await browser.pages();

      await page.goto(uri);
      const results = await new AxePuppeteer(page).analyze();

      await page.close();
      await browser.close();

      return results.violations.length;
    },
  });  
}

Axe Test

September 2021

// axe.ts
import { BettererTest } from "@betterer/betterer";
import { smaller } from "@betterer/constraints";
import { AxePuppeteer } from "axe-puppeteer";
import puppeteer from "puppeteer";

export function axe (uri: string) {
  return new BettererTest({
    async test() {
      // ...

      return results.violations.length;
    },
    constraint: smaller,
  });  
}

Axe Test

September 2021

// .betterer.ts
import { axe } from './axe';

export default {
  'documentation homepage a11y': () => 
    axe('https://phenomnomnominal.github.io/betterer'),
  'documentation api a11y': () => 
    axe('https://phenomnomnominal.github.io/betterer/docs/api')
};

Axe Test

September 2021

Axe Test

// BETTERER RESULTS V2.
exports[`documentation homepage a11y`] = {
  value: `7`
};

exports[`documentation api a11y`] = {
  value: `12`
};

September 2021

Axe Test

// axe.ts
import { BettererTest } from "@betterer/betterer";
import { AxePuppeteer } from "axe-puppeteer";
import puppeteer from "puppeteer";

export function axe (uri: string) {
  return new BettererTest<BettererAxeResult>({
    async test() {
      // ...

      return new BettererAxeResult(results.violations);
    }
  });  
}

September 2021

Axe Test

// axe-result.ts
type BettererAxeSelectors = Array<string>;
type BettererAxeViolations = Record<string, Array<string>>;

export class BettererAxeResult {
  public violations: BettererAxeViolations;
  
  constructor (violations) {
    this.violations = this._process(violations);
  }
  
  private _process (): BettererAxeViolations {
    // ...
  }
}

September 2021

Axe Test

// axe.ts
import { BettererConstraintResult } from '@betterer/constraints';

function constraint(
  expected: BettererAxeResult,
  result: BettererAxeResult
): BettererConstraintResult {
  const diff = differ(expected, result);

  if (diff.new.length) {
    return BettererConstraintResult.worse;
  }

  if (diff.fixed.length) {
    return BettererConstraintResult.better;
  }

  return BettererConstraintResult.same;
}

September 2021

Axe Test

// axe.ts
import { BettererTest } from "@betterer/betterer";
import { AxePuppeteer } from "axe-puppeteer";
import puppeteer from "puppeteer";

export function axe (uri: string) {
  return new BettererTest<BettererAxeResult>({
    async test() {
      // ...

      return new BettererAxeResult(results.violations);
    },
    constraint,
    serialiser: {
      deserialise,
      serialise
    }
  });  
}

September 2021

Axe Test

function serialise (deserialised: BettererAxeResult): BettererAxeViolations {
  return deserialised.violations;
}

function deserialised (serialised: BettererAxeViolations): BettererAxeResult {
  return BettererAxeResult.from(serialised);
}

September 2021

Axe Test

// BETTERER RESULTS V2.
exports[`documentation homepage a11y`] = {
  value: {
    "All page content must be contained by landmarks": [
      "#__docusaurus > div:nth-child(2)",
      ".hero"
    ],
    // ... More results
  }
};

Built in tests!

// .betterer.ts
import { eslint } from '@betterer/eslint';

import { regexp } from '@betterer/regexp';

import { stylelint } from '@betterer/stylelint';

import { tsquery } from '@betterer/tsquery';

import { typescript } from '@betterer/typescript';

September 2021

Betterer

Help?!

September 2021

Questions?

September 2021