Codebase-wide change: codemods and ratchets

A box office is moving from reserveSeat(seatId, minutes) to holdSeat({ seatId, minutes }); @box/seats exports both. A Betterer 5.4.0 test counts the old calls.

.betterer.js:

const { regexp } = require('@betterer/regexp');
module.exports = { 'no new reserveSeat calls': () => regexp(/reserveSeat\(/g).include('./apps/**/*.ts') };

The team runs jscodeshift 17.4.0 over apps/ with the transform codemods/hold-seat.cjs, shown below the question.

apps/checkout/src/basket.ts:

import { reserveSeat } from '@box/seats';

export const holdPair = (a: string, b: string) => [reserveSeat(a, 10), reserveSeat(b, 10)];

apps/checkout/src/express.ts:

import { reserveSeat } from '@box/seats';

export const quick = (seatId: string) => reserveSeat(seatId);
export const timed = (seatId: string) => reserveSeat(seatId, 5);

apps/kiosk/src/walkup.ts:

import { reserveSeat } from '@box/seats';

export const fromPick = (pick: [string, number]) => reserveSeat(...pick);
export const walkUp = (seatId: string) => reserveSeat(seatId, 15);

apps/kiosk/src/lobby.ts:

import { reserveSeat } from '@box/seats';

export const lobby = (seats: string[]) => seats.map((s) => reserveSeat(s));
export const vip = (seatId: string) => reserveSeat(seatId);

apps/refunds/src/rebook.ts:

import { reserveSeat } from '@box/seats';

export const rebook = (oldSeat: string) => reserveSeat(oldSeat, 30);

Every file the run changes is merged, and then npx betterer updates .betterer.results.

module.exports = function transform(file, { jscodeshift: j }) {  const root = j(file.source);  const specs = root.find(j.ImportDeclaration, { source: { value: '@box/seats' } })    .find(j.ImportSpecifier, { imported: { name: 'reserveSeat' } });  if (specs.size() === 0) return undefined;  const calls = root.find(j.CallExpression, { callee: { name: 'reserveSeat' } })    .filter((call) => call.node.arguments.length === 2 && call.node.arguments.every((a) => a.type !== 'SpreadElement'));  calls.forEach((call) => {    const [seatId, minutes] = call.node.arguments;    call.node.callee = j.identifier('holdSeat');    call.node.arguments = [j.objectExpression([j.property('init', j.identifier('seatId'), seatId), j.property('init', j.identifier('minutes'), minutes)])];  });  if (calls.size() === 0) return undefined;  const left = root.find(j.CallExpression, { callee: { name: 'reserveSeat' } }).size();  if (left === 0) specs.replaceWith(j.importSpecifier(j.identifier('holdSeat')));  else specs.insertAfter(j.importSpecifier(j.identifier('holdSeat')));  return root.toSource();};module.exports.parser = 'ts';

The box office's monorepo maps @box/seats to packages/seats/src/index.ts, which the platform team owns. Three app teams own apps/checkout, apps/kiosk and apps/refunds.

packages/seats/src/index.ts:

export function reserveSeat(seatId: string, minutes: number): string {
  return `${seatId}:${minutes}`;
}

The platform team's new function:

export function holdSeat(hold: { seatId: string; minutes: number }): string {
  return `${hold.seatId}:${hold.minutes}`;
}

apps/checkout/src/pay.ts:

import { reserveSeat } from '@box/seats';

export const pay = (seatId: string) => reserveSeat(seatId, 10);

apps/kiosk/src/walkup.ts:

import { reserveSeat } from '@box/seats';

export const walkUp = (seatId: string) => reserveSeat(seatId, 15);

apps/refunds/src/rebook.ts:

import { reserveSeat } from '@box/seats';

export const rebook = (seatId: string) => reserveSeat(seatId, 30);

For each app, the codemod rewrites the calls as holdSeat({ seatId, minutes }) and the import with them. Three plans:

Ana's plan. The platform team's merge request adds holdSeat and keeps reserveSeat. Once it has merged, the codemod writes one merge request per app from main. Once all three have merged, a last platform merge request deletes reserveSeat.

Ben's plan. The same day, from today's main, the platform team opens a merge request adding holdSeat and the codemod writes one merge request per app. The four merge as their reviews finish. Once all have merged, a last platform merge request deletes reserveSeat.

Cai's plan. As Ana's, except that the codemod writes two merge requests per app, to keep each review small: one converting the calls, one changing the import.

CI type-checks main with TypeScript 6.0.3 after every merge, and each team merges when its review finishes, in no set order.

The box office's Betterer test is the one from P1, and its committed .betterer.results lists five issues: three in apps/checkout/src/basket.ts and two in apps/refunds/src/rebook.ts. No other file under apps/ calls reserveSeat; apps/kiosk/src/walkup.ts exists and calls only holdSeat. A pre-commit hook runs npx betterer precommit, and a commit goes in only if it exits 0; a refused commit is dropped, and the next starts from the last commit that went in. Four commits are tried in this order:

1  checkout  converts two of basket.ts's three reserveSeat calls to holdSeat
2  kiosk     adds one reserveSeat call to walkup.ts
3  refunds   converts both reserveSeat calls in rebook.ts, and adds apps/kiosk/src/upsell.ts with one reserveSeat call
4  checkout  adds one reserveSeat call to basket.ts

On the box office's main, .betterer.results is committed and matches the code. Lena converts four reserveSeat calls in apps/kiosk, runs npx betterer (it exits 0), then runs git commit apps/kiosk and pushes; her machine has no pre-commit hook. CI runs npx betterer ci.

The interviewer says: "Write the ratchet yourself. checkRatchet(counts, baselinePath): counts maps each file to today's number of old calls in it, and baselinePath is a JSON file of the same shape. If any file has more calls than its recorded count (a file the baseline does not list counts as 0), return { ok: false, grew, written: false } with the files that grew, sorted, and write nothing. Otherwise write today's non-zero counts if they differ from the file or there is no file yet, and return { ok: true, grew: [], written }." You have 15 minutes, a blank ratchet.mjs and node:fs.

A payments-ledger team is replacing toCents(amount) with toMinorUnits(amount); @ledger/money exports both. On Monday its transform ran over apps/ from main, and one merge request per app was opened: ledger with apps/ledger/src/post.ts, payouts with apps/payouts/src/batch.ts, and reports with apps/reports/src/monthly.ts and apps/reports/src/annual.ts. By Wednesday the ledger and payouts merge requests have merged. Two other merge requests also reached main on Tuesday: one added apps/payouts/src/fees.ts, which imports toCents from @ledger/money and calls it once, and one edited a line of apps/reports/src/monthly.ts that the reports merge request also changed, so that merge request now conflicts. On Wednesday the author closes the reports merge request and reruns the same transform over apps/ from main: codemods/minor-units.cjs, shown below the question.

module.exports = function transform(file, { jscodeshift: j }) {  const root = j(file.source);  const specs = root.find(j.ImportDeclaration, { source: { value: '@ledger/money' } })    .find(j.ImportSpecifier, { imported: { name: 'toCents' } });  if (specs.size() === 0) return undefined;  specs.replaceWith(j.importSpecifier(j.identifier('toMinorUnits')));  root.find(j.CallExpression, { callee: { name: 'toCents' } })    .forEach((call) => { call.node.callee = j.identifier('toMinorUnits'); });  return root.toSource();};module.exports.parser = 'ts';

A chat app is moving off useTypingStatus(). Its Betterer test counts useTypingStatus( under apps/, its committed .betterer.results matches the code with six issues, a pre-commit hook runs npx betterer precommit (a commit goes in only if it exits 0), and CI runs npx betterer ci. Omar's commit adds two useTypingStatus calls to apps/web/src/Composer.tsx, and the hook refuses it. He runs npx betterer --update, commits again with every changed file, and pushes.