simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/src/ci/workflow.mjs

@@ -0,0 +1,360 @@
+// The CI gate, as a file a repo owns.
+//
+// `simt-dev check` is the whole gate: projection drift, an unreadable rule, an
+// unrunnable gate, a stale manifest. The pre-commit hook runs it locally, which
+// stops one person committing a broken region and stops nobody else - a hook is a
+// developer's machine, and every review is somebody else's. So the same command
+// ships as a workflow that runs the gate where a pull request is actually merged.
+//
+// Two decisions that are easy to get wrong and are load-bearing:
+//
+//   - The BYTES are copied, not referenced. A GitHub `uses:` line would make this
+//     one file owned by a repository the adopting team cannot read, cannot edit and
+//     cannot diff, changing under them whenever that repo moves. A copied file is
+//     reviewable in the PR that adopts it, which is the only review that happens.
+//
+//   - It is written ONCE and never rewritten. From that point it is the repo's
+//     file: their extra jobs, their triggers, their matrix. Overwriting it would
+//     delete work this tool has no way to know about, which is the same defect as
+//     replacing a hand-written `.mdc` body. A template improvement therefore does
+//     not reach an adopted repo on its own - stated in ADR-023 rather than
+//     discovered later.
+//
+//   - simt-dev's OWN repository is the exception, and the exception has to be the
+//     file's own words. Everywhere else the file is a repo's; here it is a copy of
+//     the thing it is copied from, and a copy that is allowed to rot stops being a
+//     template. A reader who opens this file in this repository and sees a diff has
+//     to be able to tell it apart from a hand edit without reading a decision record,
+//     which is why the header says so in the file rather than in this comment.
+//
+// The own copy also RUNS something different, and that is not a variation for taste.
+// `simt-dev check` is red in this repository by design: AGENTS.md here is written by
+// hand and deliberately never self-adopted (see its own "Why this repository is not
+// self-adopted"), so the check reports it as unmanaged forever. A gate that is red on
+// the day it lands is the one thing worse than no gate - it teaches the reader to
+// ignore it - so the own copy runs what this repository actually declares, which is
+// what `.githooks/pre-push` already runs.
+//
+// The directory decides whether it applies at all: a repo with no
+// `.github/workflows` is not a GitHub Actions repo, and silently creating that
+// directory starts running CI on someone's pull requests they did not ask for. The
+// own repository is exempt from that too, for the same reason it is exempt from
+// write-once: it is the only repo whose Actions directory this tool is entitled to
+// decide the contents of.
+
+import { readFileSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { PACKAGE_ROOT } from '../workspace.mjs';
+import { PACKAGE_NAME, WORKFLOW_FILE_NAME } from '../name.mjs';
+import { renderLocator } from '../locate.mjs';
+import { CLI } from '../name.mjs';
+
+/** Directory whose presence means this repo runs GitHub Actions. */
+export const WORKFLOWS_DIR = '.github/workflows';
+
+/** The one file this module writes. */
+export const WORKFLOW_FILE = `${WORKFLOWS_DIR}/${WORKFLOW_FILE_NAME}`;
+
+/**
+ * Whether this repo is the one this code is running from.
+ *
+ * `resolve` and not `realpath`, deliberately: a repo reached through a symlinked
+ * path fails to match, and that is the safe direction. It would be written once and
+ * never refreshed - the ruling every other repo lives under - where a realpath that
+ * matched a symlink would let an alias of this repo rewrite a file nobody thought of
+ * as managed.
+ *
+ * @param {string} root repo root
+ * @returns {boolean}
+ */
+export function isOwnRepo(root) {
+  return resolve(root) === PACKAGE_ROOT;
+}
+
+/**
+ * The header. The only part of the file that says who owns it, and the place the
+ * exception has to live: a reader of this file who has only this repository has to be
+ * able to tell, from these bytes, that simt-dev rewrites it here and nowhere else.
+ *
+ * @param {boolean} own whether this is simt-dev's own repository
+ * @returns {string}
+ */
+function header(own) {
+  if (own) {
+    return `# Written by simt-dev, and refreshed by it. This repository is simt-dev's
+# own, so this file is a copy of the template rather than a repository's own: a diff
+# here means the GATE changed, not that somebody hand-edited their CI. Anywhere else
+# this file is written once by \`${CLI} init\` and never touched again.
+#
+# To change what the gate does, change \`src/ci/workflow.mjs\` in the same commit and
+# run \`${CLI} ci --yes\`. Editing this file by hand works until the next template
+# change overwrites it.
+#
+# The steps below run what this repository declares - its tests and its registry lint,
+# the same two \`.githooks/pre-push\` runs - and NOT \`${CLI} check\`. That check is
+# red here by design: this AGENTS.md is written by hand and deliberately never
+# self-adopted, so the check reports it as unmanaged on every run. A gate that is red
+# the day it lands is worse than no gate.
+#
+# Every step runs from this checkout: this package has zero dependencies, so there is
+# nothing to install and no binary to resolve. Nothing here can pass by skipping - a
+# step that cannot run fails the job.
+`;
+  }
+  return `# Written by simt-dev when this repo was adopted. Yours from here: ${CLI}
+# creates this file once and never rewrites it, so your own jobs and triggers stay
+# yours.
+#
+# It runs one command, \`${CLI} check\` - the same gate the pre-commit hook runs,
+# in the place a pull request is actually merged. A hook guards one developer's
+# machine; this guards the merge.
+#
+# If ${CLI} cannot be found the job FAILS instead of passing. A green tick from a
+# check that never ran is the one outcome worse than a red one.
+`;
+}
+
+/**
+ * Actions the templates run, pinned to the commit that runs them.
+ *
+ * A tag is a name that moves. `actions/checkout@v4` resolved to whatever that project
+ * published under the name today, so the bytes executing a gate are not the bytes the
+ * adopting repository reviewed, and a change to them arrives as a force-push or a
+ * compromised token rather than as a diff. The pin is the commit; the comment beside it
+ * is the release a reader recognises, and Dependabot's `github-actions` ecosystem
+ * rewrites the pair together - which is why the pin needs no maintenance here.
+ *
+ * The major version is deliberately the one the templates already used rather than the
+ * newest available. `checkout` v7 and `setup-node` v7 both carry breaking changes, and
+ * a gate whose behaviour changes because somebody re-ran an updater is precisely what
+ * pinning exists to prevent. Moving a major is one reviewed line in this table.
+ */
+export const ACTIONS = {
+  checkout: { repo: 'actions/checkout', commit: '11d5960a326750d5838078e36cf38b85af677262', release: 'v4.4.0' },
+  setupNode: { repo: 'actions/setup-node', commit: '49933ea5288caeca8642d1e84afbd3f7d6820020', release: 'v4.4.0' },
+};
+
+/**
+ * One `- uses:` line, pinned.
+ *
+ * @param {keyof typeof ACTIONS} action
+ * @returns {string}
+ */
+function uses(action) {
+  const { repo, commit, release } = ACTIONS[action];
+  return `      - uses: ${repo}@${commit} # ${release}`;
+}
+
+/** The YAML every copy shares, so the two cannot drift on triggers, permissions or
+ *  concurrency. Only `name`, the runner and `steps` vary, and only because they have
+ *  to. The own gate also varies the platforms and the Node versions, because this
+ *  package is the one whose floor and whose ADR-012 claim have to hold on more than
+ *  the minimum. */
+function skeleton(name, steps, { matrix = null } = {}) {
+  const axes = matrix
+    ? Object.entries(matrix)
+        .map(([axis, values]) => `        ${axis}: [${values.map((v) => `'${v}'`).join(', ')}]`)
+        .join('\n')
+    : '';
+  const strategy = axes === '' ? '' : `    strategy:\n      fail-fast: false\n      matrix:\n${axes}\n`;
+  // The runner and the matrix have to be read together: naming the platforms in the
+  // matrix and leaving `runs-on` on one literal is how a job ends up running six times
+  // on the one runner. One of the two is derived from the other rather than written
+  // twice, so a matrix that grows an axis cannot be half-honoured.
+  // `${{ matrix.os }}` is a template-literal hazard - `${` opens an interpolation - so
+  // it is written escaped, the same way the `concurrency` line below spells its own two.
+  const runner = matrix?.os ? '\${{ matrix.os }}' : 'ubuntu-latest';
+  const job = matrix?.node ? '\${{ matrix.os }} node \${{ matrix.node }}' : name;
+  return `name: ${name}
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+# Read-only is enough to check a repo, and a gate job does not need to write to it.
+permissions:
+  contents: read
+
+concurrency:
+  group: simt-dev-\${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: ${job}
+    runs-on: ${runner}
+${strategy}    timeout-minutes: 5
+    steps:
+${steps}`;
+}
+
+/** The minimum Node `engines.node` allows, without the range operator. Both
+ *  templates pin setup-node to it, read from package.json so the two cannot name
+ *  a version the package says it does not run on. */
+export function nodeFloor() {
+  const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+  const range = pkg.engines?.node;
+  const version = typeof range === 'string' ? />=\s*(\d+\.\d+\.\d+)/.exec(range) : null;
+  if (!version) throw new Error(`engines.node must be a >=x.y.z floor, got ${JSON.stringify(range)}`);
+  return version[1];
+}
+
+/** The floor in this package's `engines.node`. A gate that cannot start on the
+ *  version it declares support for is not a gate. The comment ships in the file,
+ *  because the reader deciding whether to bump that version has only the file.
+ *  The own gate passes the matrix expression; every other copy passes the floor. */
+function setupNode(version) {
+  return `${uses('setupNode')}
+        with:
+          # The floor in this package's \`engines.node\`. A gate that cannot start on
+          # the version it declares support for is not a gate.
+          node-version: '${version}'`;
+}
+
+/** Indent a rendered shell block so it sits inside a YAML block scalar. Blank lines
+ *  stay blank: a line of trailing whitespace inside a scalar is a diff nobody meant. */
+function indent(text, spaces) {
+  return text
+    .split('\n')
+    .map((l) => (l === '' ? '' : `${' '.repeat(spaces)}${l}`))
+    .join('\n');
+}
+
+/**
+ * The workflow, as bytes.
+ *
+ * Two renderings, and the argument is which repository this one is for. `own` is the
+ * copy that lives in simt-dev's own repository; it is refreshed rather than left alone,
+ * and it runs this repository's own gate rather than the adopting repository's.
+ *
+ * @param {{own?: boolean}} [options]
+ * @returns {string} YAML, LF-terminated
+ */
+export function renderWorkflow({ own = false } = {}) {
+  if (own) {
+    const floor = nodeFloor();
+    return `${header(true)}${skeleton(
+      'simt-dev own gate',
+      [
+        uses('checkout'),
+        setupNode('${{ matrix.node }}'),
+        // The two checks `.githooks/pre-push` runs, named here rather than discovered,
+        // because a reader of this file has to be able to answer "what stops a merge"
+        // without opening a shell script in another directory.
+        '      - name: tests',
+        '        run: npm test',
+        '      - name: skill registry lint',
+        '        run: node bin/simt-dev.mjs graph lint',
+        '      - name: the gate copy in this repo is current',
+        // The drift this exception exists to prevent, checked where it would be caught.
+        // Without it a template change lands with the copy still describing the old
+        // gate, and the next person to read the diff cannot tell which one is right.
+        //
+        // `--check`, and not the bare command: `ci` previews by default and exits 0,
+        // so this step used to print the drift it exists to catch and pass anyway.
+        '        run: node bin/simt-dev.mjs ci --check',
+      ].join('\n'),
+      // ADR-012 says CI verifies on macOS and Linux. Until this matrix existed that
+      // sentence was false in the one repository that could have made it true, and no
+      // check read it - the package declares `os` for npm to enforce, and nothing here
+      // ever ran a test on a second platform.
+      { matrix: { os: ['ubuntu-latest', 'macos-latest'], node: [floor, '24', '26'] } },
+    )}\n`;
+  }
+
+  const locator = renderLocator('check --root "$ROOT"', {
+    remedy: `REMEDY run: npm i -D ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`,
+  });
+  return `${header(false)}${skeleton(
+    `${CLI} check`,
+    [
+      uses('checkout'),
+      setupNode(nodeFloor()),
+      '      - name: install dependencies',
+      '        # \`npm ci\` needs a lockfile; a repo without one is still gated, not skipped.',
+      '        run: npm ci || npm install',
+      `      - name: ${CLI} check`,
+      '        run: |',
+      indent(`set -eu\nROOT="\${GITHUB_WORKSPACE}"\n${locator}`, 10),
+    ].join('\n'),
+  )}\n`;
+}
+
+/**
+ * What this repo's gate file should be, and what should happen to it.
+ *
+ * The one place that knows about the write-once rule, so `init`, `check` and `ci`
+ * cannot disagree about which repo owns its file.
+ *
+ * @param {string} root repo root
+ * @returns {Promise<{file:string, path:string, action:'create'|'refresh'|'unchanged'|'skip',
+ *                    own:boolean, exists:boolean, bytes:number, current:boolean,
+ *                    workflows:boolean, reason:string|null}>}
+ */
+export async function planWorkflow(root) {
+  const path = join(root, WORKFLOW_FILE);
+  const own = isOwnRepo(root);
+  let text = null;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch {
+    text = null;
+  }
+  const exists = text !== null;
+  const bytes = exists ? Buffer.byteLength(text) : 0;
+
+  // An unreadable path is not an absent one. ENOENT is absence; anything else means
+  // the file is there and this tool cannot see it, and reporting that as "create"
+  // would hand the writer an EACCES at the worst moment.
+  let workflows = false;
+  try {
+    workflows = (await stat(join(root, WORKFLOWS_DIR))).isDirectory();
+  } catch {
+    workflows = false;
+  }
+
+  if (exists) {
+    // Content is only ever compared in simt-dev's own repository. Everywhere else
+    // that comparison is the thing ADR-023 ruled out: a repo's file is the repo's
+    // file, and the only question is whether one is there.
+    const desired = renderWorkflow({ own: true });
+    const current = own ? text === desired : true;
+    return {
+      file: WORKFLOW_FILE,
+      path,
+      action: current ? 'unchanged' : 'refresh',
+      own,
+      exists,
+      bytes,
+      current,
+      // Both sides, so a reader told the file differs can be shown how. Rendering a
+      // second time for a diff would risk a second answer, and the two call sites
+      // must not be able to disagree about what "refresh" means.
+      source: { text, desired },
+      workflows,
+      reason: current ? null : `this repository is simt-dev's own, and the gate template has changed since this copy was written`,
+    };
+  }
+  return {
+    file: WORKFLOW_FILE,
+    path,
+    // The own repository creates the directory. It is the one repo whose Actions
+    // surface this tool is entitled to populate, and the rule that stopped it from
+    // inventing CI on somebody's pull requests does not apply to CI on its own.
+    action: workflows || own ? 'create' : 'skip',
+    own,
+    exists,
+    bytes,
+    current: false,
+    workflows,
+    reason:
+      workflows || own
+        ? null
+        : `no ${WORKFLOWS_DIR} directory, so this repo does not run GitHub Actions yet`,
+  };
+}

simt_dev/vendored/src/commands/ci.mjs

@@ -0,0 +1,285 @@
+// simt-dev ci — the .github files, in the one repository whose copies are refreshed.
+//
+// Why this exists rather than a flag on `init`: the write-once rule is about a
+// repository's own file, and simt-dev's own repository has no file of its own here —
+// its copies are the templates. Something has to be able to write them without
+// adopting the repository, and `init` cannot: adopting this repo would pin its own
+// SHA into its own AGENTS.md, which is precisely why AGENTS.md says it is not
+// self-adopted. A refresh reachable only through `init` would be an exception that
+// never fires, and an exception that never fires is the "permanently red check
+// nothing can fix" failure in another costume.
+//
+// Everywhere else this command refuses rather than creating either file. There, the
+// file belongs to the repository, `init` writes it once, and a second writer would be
+// a second answer to who owns it (ADR-023, ADR-024, ADR-026).
+//
+// Both files are handled here rather than in two commands because they answer the
+// same question with the same answer. A reader who had to learn which of two
+// commands owns which file would be learning about ownership twice to learn nothing
+// new, and the next .github file would arrive with a third command to remember.
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { EXIT, emit, emitJson, isJson, note, writeMode } from '../output/index.mjs';
+import { planWorkflow, renderWorkflow, WORKFLOW_FILE } from '../ci/workflow.mjs';
+import { planDependabot, renderDependabot, DEPENDABOT_FILE } from '../ci/dependabot.mjs';
+import { CLI } from '../name.mjs';
+
+/**
+ * The two plans, with the render and the plan-time data each needs kept attached.
+ *
+ * A table rather than two call sites so that adding a third `.github` file is one
+ * row and not a second copy of the write path — the divergence risk this command
+ * already had once, when the workflow's own rendering lived inline here.
+ */
+function targets() {
+  return [
+    { key: 'workflow', file: WORKFLOW_FILE, plan: planWorkflow, render: () => renderWorkflow({ own: true }) },
+    { key: 'dependabot', file: DEPENDABOT_FILE, plan: planDependabot, render: (plan) => renderDependabot(plan.facts ?? [], { stack: plan.stack ?? [], own: true }) },
+  ];
+}
+
+export async function ciCommand(positional, flags) {
+  const root = flags.root ?? positional[0] ?? process.cwd();
+  const mode = writeMode(flags);
+  const checkOnly = flags.check === true;
+
+  const plans = [];
+  for (const { key, file, plan } of targets()) {
+    plans.push({ key, file, ...(await plan(root)) });
+  }
+
+  // Refuse once, on the first non-own plan, and say which file. One refusal that
+  // names a file is answerable; two refusals is a list the reader has to reconcile
+  // against a rule they cannot see from here.
+  const foreign = plans.find((p) => !p.own);
+  if (foreign) {
+    return failOutside(root, foreign, flags);
+  }
+
+  const todo = plans.filter((p) => p.action !== 'unchanged');
+
+  if (todo.length === 0) {
+    if (isJson(flags)) {
+      emitJson(
+        {
+          ok: true,
+          command: 'ci',
+          root,
+          action: 'unchanged',
+          files: plans.map((p) => ({ file: p.file, bytes: p.bytes })),
+          written: false,
+        },
+        {},
+      );
+    } else {
+      emit(plans.map((p) => `current  ${p.file}  ${p.bytes} bytes`).join('\n'));
+    }
+    return EXIT.OK;
+  }
+
+  // Same shape as every other write in this tool: show it, change it only when told.
+  // The plan is printed from the same call `check` reads, so a reader who is shown
+  // these lines is shown the lines that produced them.
+  const lines = [`repo      ${root}`];
+  for (const p of todo) {
+    lines.push(
+      `file      ${p.file}`,
+      `action    ${p.action}`,
+      `why       ${p.reason ?? (p.action === 'create' ? `this repository is simt-dev's own` : '')}`,
+    );
+    if (p.ecosystems) lines.push(`watching  ${p.ecosystems.join(', ') || '(github actions only)'}`);
+    // A check that names the drift without showing it makes the reader open two files
+    // to answer a question this command already knows the answer to.
+    if (checkOnly && p.source) {
+      const d = unified(p.file, p.source.text, p.source.desired);
+      if (d !== '') lines.push(d);
+    }
+  }
+
+  // `ci --check` is the form the own workflow runs, and the whole point of it is the
+  // exit code. It printed the plan and returned 0, so the step whose own comment says
+  // it exists to catch this drift let through exactly the drift it was written for.
+  if (checkOnly) {
+    if (isJson(flags)) {
+      emitJson(
+        {
+          ok: false,
+          command: 'ci --check',
+          root,
+          files: todo.map(publicPlan),
+          written: false,
+          error: `${todo.length} of ${plans.length} .github file(s) in this repo are stale`,
+          remedy: `run: ${CLI} ci --yes`,
+        },
+        {},
+      );
+    } else {
+      emit(lines.join('\n'));
+    }
+    return EXIT.FAIL;
+  }
+
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'ci', root, files: todo.map(publicPlan), written: false, dryRun: !mode.apply }, {});
+  } else {
+    emit(lines.join('\n'));
+  }
+
+  if (!mode.apply) {
+    note('');
+    note(mode.dryRun ? 'dry-run  nothing written' : `dry-run  nothing written; apply with: ${CLI} ci --yes`);
+    return EXIT.OK;
+  }
+
+  for (const { key, plan, render } of targets()) {
+    const p = plans.find((x) => x.key === key);
+    if (p.action === 'unchanged') continue;
+    await mkdir(dirname(p.path), { recursive: true });
+    // The renderer takes the plan because detection-driven content is a function of
+    // this repo's facts: a dependabot config rendered without them would watch
+    // nothing, which is the same silent-nothing the detection ruling exists to stop.
+    await writeFile(p.path, render(p));
+    note(`wrote    ${p.file} (${p.action}; the template and this copy now agree)`);
+  }
+  if (isJson(flags)) {
+    emitJson(
+      {
+        ok: true,
+        command: 'ci',
+        root,
+        files: plans.map((p) => ({ file: p.file, action: p.action, bytes: p.bytes })),
+        written: true,
+      },
+      {},
+    );
+  }
+  return EXIT.OK;
+}
+
+/**
+ * The refusal, which is a report rather than a wall: a reader who ran this in a
+ * repository that adopted simt-dev has almost certainly just been told to run
+ * something that does not exist, and the useful answer is which command does exist.
+ */
+function failOutside(root, plan, flags) {
+  const remedy = `${CLI} init --yes   (a repository's .github files are written once, by init, and then left alone)`;
+  if (isJson(flags)) {
+    emitJson(
+      {
+        // `ok: true` with a refusal in it was the shape this whole command had: the
+        // document said the request succeeded while the text said it was refused, and
+        // a caller reading `ok` had no way to know which one the writer meant. It is
+        // also `EXIT.UNSUPPORTED` rather than 0 for the same reason — the request
+        // cannot be satisfied in this repository, and that is a fact about the
+        // repository, not a successful no-op.
+        ok: false,
+        command: 'ci',
+        root,
+        file: plan.file,
+        action: plan.action,
+        own: false,
+        error: `simt-dev refreshes its own .github files; ${plan.file} belongs to this repository`,
+        remedy,
+        written: false,
+      },
+      {},
+    );
+  } else {
+    emit(
+      [
+        `file      ${plan.file}`,
+        `state     ${plan.exists ? 'present' : 'absent'}`,
+        `owner     this repository, not simt-dev`,
+        '',
+        'simt-dev refreshes its own .github files and no one else\'s. This command is not',
+        'how a repository that adopted simt-dev gets one; `init` is, and it writes the',
+        'file once.',
+      ].join('\n'),
+    );
+    note('');
+    note(`remedy:   ${remedy}`);
+  }
+  return EXIT.UNSUPPORTED;
+}
+
+/**
+ * A plan without the file bodies. Both sides of the comparison travel on the plan so
+ * the verdict and the diff cannot disagree, and a JSON payload is not the place for
+ * two copies of a workflow file.
+ */
+function publicPlan({ source, ...plan }) {
+  return plan;
+}
+
+/**
+ * A unified diff of the two, or `''` when they are identical.
+ *
+ * Small on purpose: the reader is the author of the template change that made the
+ * copy stale, and the question is "what did I change". Line-level LCS rather than a
+ * character diff, because a workflow's drift is a moved step, not a typo — and a
+ * table over tens of lines is smaller to read and harder to get wrong than a Myers
+ * scan. No dependency, per ADR-012.
+ */
+function unified(file, current, desired) {
+  const a = (current ?? '').split('\n');
+  const b = (desired ?? '').split('\n');
+  const table = Array.from({ length: a.length + 1 }, () => new Uint32Array(b.length + 1));
+  for (let i = a.length - 1; i >= 0; i -= 1) {
+    for (let j = b.length - 1; j >= 0; j -= 1) {
+      table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+    }
+  }
+  const rows = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) {
+      rows.push({ mark: ' ', line: a[i] });
+      i += 1;
+      j += 1;
+    } else if (j < b.length && (i === a.length || table[i][j + 1] >= table[i + 1][j])) {
+      rows.push({ mark: '+', line: b[j] });
+      j += 1;
+    } else {
+      rows.push({ mark: '-', line: a[i] });
+      i += 1;
+    }
+  }
+  // A diff of nothing is not a diff. Returning '' is what lets the caller decide,
+  // rather than printing a header over an empty body.
+  if (rows.every((r) => r.mark === ' ')) return '';
+
+  // Three lines of context, then `...` for whatever was elided. Printing all fifty
+  // lines of a workflow to report one changed step buries the answer in context, and
+  // the answer is the only reason this exists.
+  const CONTEXT = 3;
+  const keep = new Array(rows.length).fill(false);
+  rows.forEach((r, at) => {
+    if (r.mark === ' ') return;
+    for (let k = Math.max(0, at - CONTEXT); k <= Math.min(rows.length - 1, at + CONTEXT); k += 1) {
+      keep[k] = true;
+    }
+  });
+  const out = [];
+  let elided = 0;
+  for (const [at, r] of rows.entries()) {
+    if (!keep[at]) {
+      elided += 1;
+      continue;
+    }
+    if (elided > 0) {
+      out.push(`@@ ${elided} unchanged line(s) elided`);
+      elided = 0;
+    }
+    out.push(`${r.mark}${r.line}`);
+  }
+  const changed = rows.filter((r) => r.mark !== ' ').length;
+  return [
+    `--- a/${file}`,
+    `+++ b/${file}`,
+    `@@ ${changed} changed line(s); apply with: ${CLI} ci --yes @@`,
+    ...out,
+  ].join('\n');
+}