Betterer

Incremental Improvement

@phenomnominal

September 2021

@phenomnominal

September 2021

@phenomnominal

Hi, I'm Craig!

September 2021

twitter.com/phenomnominal

linkedin.com/in/craig-spence

github.com/phenomnomnominal

@phenomnominal

Legacy

September 2021

@phenomnominal

Local Maxima

Desired state

Current state

September 2021

@phenomnominal

September 2021

Why don't we rewrite the whole thing?!

@phenomnominal

Revolution!

September 2021

@phenomnominal

Revolution...

September 2021

@phenomnominal

Branching!

September 2021

@phenomnominal

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

@phenomnominal

Automation

September 2021

@phenomnominal

Humans

Not obsolete yet!

September 2021

@phenomnominal

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>

@phenomnominal

September 2021

Inspiration

@phenomnominal

Evolutionary Architecture

September 2021

@phenomnominal

Evolutionary Algorithms

September 2021

@phenomnominal

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

Chromosome

Population

Gene

Genetic Algorithms

September 2021

@phenomnominal

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

@phenomnominal

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

@phenomnominal

Tetris

September 2021

@phenomnominal

September 2021

@phenomnominal

Evolutionary Migration?

A fitness function to evaluate the solution:

f(codebase) => score

September 2021

@phenomnominal

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

@phenomnominal

Code as data

September 2021

ts(codebase) => nCompilerErrors

eslint(codebase) => nLintErrors

axe(codebase) => nA11yErrors

jest(codebase) => coverage%

@phenomnominal

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

@phenomnominal

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

@phenomnominal

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

@phenomnominal

September 2021

@phenomnominal

September 2021

phenomnomnominal.github.io/betterer

@phenomnominal

// 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

@phenomnominal

// .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

@phenomnominal

September 2021

@phenomnominal

My First Test

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


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

September 2021

@phenomnominal

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

@phenomnominal

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

@phenomnominal

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

@phenomnominal

September 2021

@phenomnominal

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

@phenomnominal

September 2021

@phenomnominal

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

@phenomnominal

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

September 2021

@phenomnominal

September 2021

@phenomnominal

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

@phenomnominal

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

@phenomnominal

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

@phenomnominal

September 2021

@phenomnominal

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:
  }`
};

@phenomnominal

Betterer VS Code Extension

September 2021

@phenomnominal

September 2021

@phenomnominal

// 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

@phenomnominal

September 2021

@phenomnominal

// .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

@phenomnominal

September 2021

@phenomnominal

// 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

@phenomnominal

More tests!

September 2021

@phenomnominal

September 2021

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

Axe Test

@phenomnominal

September 2021

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

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

Axe Test

@phenomnominal

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

@phenomnominal

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

@phenomnominal

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

@phenomnominal

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

@phenomnominal

September 2021

Axe Test

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

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

@phenomnominal

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);
    }
  });  
}

@phenomnominal

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 {
    // ...
  }
}

@phenomnominal

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;
}

@phenomnominal

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
    }
  });  
}

@phenomnominal

September 2021

Axe Test

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

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

@phenomnominal

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
  }
};

@phenomnominal

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?!

@phenomnominal

September 2021

Questions?

@phenomnominal

September 2021

twitter.com/phenomnominal