api-diff tool: pick an omicron PR, see diff for generated API

[david-crespo]

YES

$ ./tools/deno/api-diff.ts -h
Display changes to API client caused by a given Omicron PR. Works by downloading
the OpenAPI spec before and after, generating clients in temp dirs, and diffing.

Requirements:
  - Deno (which you have if you're seeing this message)
  - GitHub CLI (gh)

Usage:
  ./tools/deno/api-diff.ts [-f] [PR number]
  ./tools/deno/api-diff.ts -h

Flags:
  -f, --force          Download spec and regen client even if dir already exists
  -h, --help           Show this help message

Parameters:
  PR number <int>: If left out, interactive picker is shown

Could add:

• do this for a single commit on main
• take a PR number as an arg and skip the picker UI (would allow us to see diff for closed PRs)
• take two arbitrary commits as base and head

2023-11-25-api-diff-2.mp4

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
console	✅ Ready (Inspect)	Visit Preview	Nov 30, 2023 10:01pm

[github-actions]

license-eye has totally checked 453 files.

Valid	Invalid	Ignored	Fixed
402	1	50	0

Click to see the invalid file list

• tools/deno/api-diff.ts

[david-crespo]

I realized it would be shorter in bash because we're not really doing anything but calling a bunch of commands, so I tried it in bash. Then anything in bash would be better in nushell (see, for example, how trivial it was to add the prNum positional arg), so I tried it in nushell. I do like nu scripts a lot: they're the best of both worlds in terms of a natural API for calling shell commands and working with the output plus modern constructs for looping and conditionals and whatever else. See, for example:

let pr = (gh api graphql -f $query | from json | get data.repository.pullRequest)

Since it would be very few of us using these scripts and all they require is having nu on your path, I am wondering if it might be worth it to actually use nu for these things. Recall I did the same exercise a little while ago for the bump-omicron script and it came out nice too: #1487

[just-be-dev]

Since it would be very few of us using these scripts and all they require is having nu on your path, I am wondering if it might be worth it to actually use nu for these things.

As interesting as our excursions with nushell were and as terse as the output can be, I'm not sure it's really worth it to introduce it as another dependency in the toolchain just to save a few lines.

A few points:

• Nushell is a bit cavalier about their updates and I ran into frequent breaking updates between versions. Until they hit 1.0 and we have a higher guarantee of safety I'd be a little hesitant to build tools on it that we anticipate the broader team using.
• While it's simpler on the face of it, it's still another thing to learn. It would be nice to reduce the overall surface area of tooling.

My preference would be to roll with the deno or bash scripts just given that they're a known quantity.

[david-crespo]

Cool, I'll stick with deno then.